> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/sinelaw/fresh/llms.txt
> Use this file to discover all available pages before exploring further.

# Plugin System Overview

> Extend Fresh with TypeScript plugins running in a sandboxed QuickJS environment

Fresh's functionality can be extended with a powerful plugin system. Plugins are written in **TypeScript** and run in a sandboxed **QuickJS environment** (transpiled via oxc\_transformer), providing full access to the editor's API while maintaining security and performance.

## What are Plugins?

Plugins are TypeScript files that extend the editor's functionality by:

* Registering custom commands and keybindings
* Creating interactive panels and virtual buffers
* Running external processes and tools
* Integrating with LSP servers
* Adding visual decorations and overlays
* Responding to editor events

## Plugin Architecture

<CardGroup cols={2}>
  <Card title="TypeScript Runtime" icon="code">
    Plugins are written in TypeScript and automatically transpiled to JavaScript using the blazing-fast **oxc\_transformer**.
  </Card>

  <Card title="Sandboxed QuickJS" icon="shield">
    All plugins run in an isolated **QuickJS** environment, providing security and preventing plugins from interfering with each other.
  </Card>

  <Card title="Editor API" icon="plug">
    Access a comprehensive TypeScript API through the global `editor` object for all editor operations.
  </Card>

  <Card title="Async/Await Support" icon="bolt">
    Native support for async/await allows plugins to spawn processes, make LSP requests, and perform I/O without blocking.
  </Card>
</CardGroup>

## Available Plugins

Fresh ships with a rich collection of production-ready plugins:

### Core Plugins

| Plugin                 | Description                                |
| ---------------------- | ------------------------------------------ |
| `welcome.ts`           | Displays welcome message on startup        |
| `manual_help.ts`       | Manual page and keyboard shortcuts display |
| `diagnostics_panel.ts` | LSP diagnostics panel with navigation      |
| `search_replace.ts`    | Search and replace functionality           |
| `path_complete.ts`     | Path completion in prompts                 |

### Git Integration

Powerful Git workflow integration:

| Plugin             | Description                                  |
| ------------------ | -------------------------------------------- |
| `git_grep.ts`      | Interactive search through git-tracked files |
| `git_find_file.ts` | Fuzzy file finder for git repositories       |
| `git_blame.ts`     | Git blame view with commit navigation        |
| `git_log.ts`       | Git log viewer with history browsing         |
| `git_gutter.ts`    | Show git diff markers in the gutter          |

### Code Enhancement

| Plugin                 | Description                                         |
| ---------------------- | --------------------------------------------------- |
| `todo_highlighter.ts`  | Highlights TODO/FIXME/HACK keywords in comments     |
| `color_highlighter.ts` | Highlights color codes with their actual colors     |
| `find_references.ts`   | Find references across the codebase                 |
| `clangd_support.ts`    | Clangd-specific LSP features (switch header/source) |

### Language Support

Built-in LSP integration for multiple languages:

<CardGroup cols={3}>
  <Card title="TypeScript/JavaScript" icon="js">
    `typescript-lsp.ts`
  </Card>

  <Card title="Rust" icon="rust">
    `rust-lsp.ts`
  </Card>

  <Card title="Python" icon="python">
    `python-lsp.ts`
  </Card>

  <Card title="Go" icon="golang">
    `go-lsp.ts`
  </Card>

  <Card title="C/C++" icon="c">
    `clangd-lsp.ts`
  </Card>

  <Card title="Java" icon="java">
    `java-lsp.ts`
  </Card>
</CardGroup>

And many more: `css-lsp.ts`, `html-lsp.ts`, `json-lsp.ts`, `latex-lsp.ts`, `marksman-lsp.ts`, `zig-lsp.ts`, `odin-lsp.ts`, `templ-lsp.ts`

### Editing Modes

| Plugin                | Description                                    |
| --------------------- | ---------------------------------------------- |
| `markdown_compose.ts` | Semi-WYSIWYG markdown editing with soft breaks |
| `merge_conflict.ts`   | 3-way merge conflict resolution                |
| `vi_mode.ts`          | Full Vim emulation with modal editing          |

### Advanced Features

| Plugin            | Description                                     |
| ----------------- | ----------------------------------------------- |
| `theme_editor.ts` | Interactive theme customization                 |
| `pkg.ts`          | Built-in package manager for plugins and themes |
| `audit_mode.ts`   | Code review and audit workflow                  |
| `code-tour.ts`    | Guided code tours and walkthroughs              |

## Plugin Lifecycle

Plugins are loaded automatically when Fresh starts:

<Steps>
  <Step title="Discovery">
    All `.ts` files in the `plugins/` directory are discovered at startup.
  </Step>

  <Step title="Transpilation">
    Each plugin is transpiled from TypeScript to JavaScript using **oxc\_transformer**.
  </Step>

  <Step title="Execution">
    The transpiled JavaScript runs in a sandboxed **QuickJS** runtime with access to the `editor` API.
  </Step>

  <Step title="Registration">
    Plugins register commands, event handlers, and modes during initialization.
  </Step>
</Steps>

<Note>
  There is no explicit activation step. All plugins in the `plugins/` directory are loaded automatically.
</Note>

## Core Concepts

### The `editor` Object

The global `editor` object is the main entry point for the Fresh plugin API:

```typescript theme={null}
/// <reference path="../types/fresh.d.ts" />

// Access the editor API
editor.setStatus("Hello from my plugin!");
```

The `editor` object provides methods for:

* **Commands**: Register custom actions in the command palette
* **Buffers**: Read and modify text content
* **Overlays**: Add visual decorations without changing content
* **Processes**: Spawn external commands and tools
* **Events**: Subscribe to editor state changes
* **LSP**: Communicate with language servers
* **File System**: Read/write files and directories

### Commands

Commands are actions that appear in the command palette and can be bound to keys:

```typescript theme={null}
globalThis.my_action = function(): void {
  editor.setStatus("Command executed!");
};

editor.registerCommand(
  "My Custom Command",        // Name in command palette
  "Does something useful",    // Description
  "my_action",                // Global function to call
  "normal"                    // Context: normal, insert, prompt, etc.
);
```

### Virtual Buffers

Create special buffers for displaying structured data like search results or diagnostics:

```typescript theme={null}
await editor.createVirtualBufferInSplit({
  name: "*Search Results*",
  mode: "search-results",
  readOnly: true,
  entries: [
    {
      text: "src/main.rs:42: match found\n",
      properties: { file: "src/main.rs", line: 42 }
    }
  ],
  ratio: 0.3  // Takes 30% of screen height
});
```

### Event Handlers

Subscribe to editor events to react to user actions:

```typescript theme={null}
globalThis.onSave = function(data: { buffer_id: number, path: string }): void {
  editor.debug(`Saved: ${data.path}`);
};

editor.on("buffer_save", "onSave");
```

**Available Events:**

* `buffer_save` - After a buffer is saved
* `buffer_closed` - When a buffer is closed
* `cursor_moved` - When cursor position changes
* `render_start` - Before screen renders
* `lines_changed` - When visible lines change

## Package Types

Fresh supports multiple package types:

<CardGroup cols={3}>
  <Card title="Plugins" icon="puzzle-piece">
    TypeScript code that extends editor functionality
  </Card>

  <Card title="Themes" icon="palette">
    Color schemes for syntax highlighting and UI
  </Card>

  <Card title="Language Packs" icon="language">
    Syntax highlighting, language config, and LSP support
  </Card>
</CardGroup>

### Bundles

Bundles combine multiple languages and plugins into a single package. Useful for language ecosystems with multiple file types:

```json theme={null}
{
  "name": "elixir-bundle",
  "type": "bundle",
  "fresh": {
    "languages": [
      {
        "id": "elixir",
        "grammar": { "file": "grammars/elixir.sublime-syntax" },
        "lsp": { "command": "elixir-ls" }
      },
      {
        "id": "heex",
        "grammar": { "file": "grammars/heex.sublime-syntax" }
      }
    ],
    "plugins": [
      { "id": "elixir-tools", "entry": "plugins/tools.ts" }
    ]
  }
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Getting Started" icon="rocket" href="/plugins/getting-started">
    Learn how to install and use plugins
  </Card>

  <Card title="Plugin Development" icon="code" href="/plugins/development">
    Create your own plugins with TypeScript
  </Card>

  <Card title="Plugin Examples" icon="lightbulb" href="/plugins/examples">
    Explore real plugin examples with code
  </Card>

  <Card title="API Reference" icon="book" href="/api">
    Complete API documentation
  </Card>
</CardGroup>