Module api 

Plugin API: Safe interface for plugins to interact with the editor

This module provides a safe, controlled API for plugins (Lua, WASM, etc.) to interact with the editor without direct access to internal state.

Type Safety Architecture

Rust structs in this module serve as the single source of truth for the TypeScript plugin API. The type safety system works as follows:

Rust struct                  Generated TypeScript
───────────                  ────────────────────
#[derive(TS, Deserialize)]   type ActionPopupOptions = {
#[serde(deny_unknown_fields)]    id: string;
struct ActionPopupOptions {      title: string;
    id: String,                  message: string;
    title: String,               actions: TsActionPopupAction[];
    ...                      };
}

Key Patterns

1. #[derive(TS)] - Generates TypeScript type definitions via ts-rs
2. #[serde(deny_unknown_fields)] - Rejects typos/unknown fields at runtime
3. impl FromJs - Bridges rquickjs values to typed Rust structs

Validation Layers

Layer	What it catches
TypeScript compile	Wrong field names, missing required fields
Rust runtime (serde)	Typos like popup_id instead of id
Rust compile	Type mismatches in method signatures

Limitations & Tradeoffs

• Manual parsing for complex types: Some methods (e.g., submitViewTransform) still use manual object parsing due to enum serialization complexity
• Two-step deserialization: Complex nested structs may need rquickjs::Value → serde_json::Value → typed struct due to rquickjs_serde limits
• Duplicate attributes: Both #[serde(...)] and #[ts(...)] needed since they control different things (runtime serialization vs compile-time codegen)

Structs

ActionPopupAction

Action button for action popups

ActionPopupOptions

Options for showActionPopup

ActionSpec

Specification for an action to execute, with optional repeat count

BackgroundProcessResult

Result from spawning a background process

BufferInfo

Information about a buffer

BufferSavedDiff

Diff between current buffer content and last saved snapshot

CommandRegistry

Minimal command registry for PluginApi. This is a stub that provides basic command storage for plugin use. The editor’s full CommandRegistry lives in fresh-editor.

CompositeHunk

Diff hunk for composite buffer alignment

CompositeLayoutConfig

Layout configuration for composite buffers

CompositePaneStyle

Style configuration for a composite pane

CompositeSourceConfig

Source pane configuration for composite buffers

CreateCompositeBufferOptions

Options for creating a composite buffer (used by plugin API)

CreateTerminalOptions

Options for createTerminal

CreateVirtualBufferInExistingSplitOptions

Options for createVirtualBufferInExistingSplit

CreateVirtualBufferInSplitOptions

Options for createVirtualBufferInSplit

CreateVirtualBufferOptions

Options for createVirtualBuffer

CursorInfo

Information about a cursor in the editor

DirEntry

Directory entry returned by readDir

EditorStateSnapshot

Snapshot of editor state for plugin queries This is updated by the editor on each loop iteration

FormatterPackConfig

Formatter configuration for language packs

GrammarInfoSnapshot

Grammar info exposed to plugins, mirroring the editor’s grammar provenance tracking.

GrepMatch

A single match from project-wide grep

JsCallbackId

A callback ID for JavaScript promises in the plugin runtime.

JsDiagnostic

Diagnostic from LSP

JsPosition

Position in a document (line and character)

JsRange

Range in a document (start and end positions)

JsTextPropertyEntry

Entry for virtual buffer content with optional text properties (JS API version)

LanguagePackConfig

Language configuration for language packs

LayoutHints

Layout hints supplied by plugins (e.g., Compose mode)

LspServerPackConfig

LSP server configuration for language packs

OverlayOptions

Options for adding an overlay with theme support.

PluginApi

Plugin API context - provides safe access to editor functionality

ProcessLimitsPackConfig

Process resource limits for LSP servers

ReplaceResult

Result from replacing matches in a buffer

ReviewHunk

A high-level hunk directive for the Review Diff tool

SpawnResult

Result from spawning a process with spawnProcess

TerminalResult

Result of creating a terminal

TextPropertiesAtCursor

Result of getTextPropertiesAtCursor - array of property objects

TsCompletionCandidate

A completion candidate produced by a TypeScript plugin provider.

TsCompletionContext

Context sent to a TypeScript plugin’s provideCompletions handler.

TsCompletionProviderRegistration

Registration payload sent by a plugin to register a completion provider.

TsHighlightSpan

Syntax highlight span for a buffer range

ViewTokenStyle

Styling for view tokens (used for injected annotations)

ViewTokenWire

Wire-format view token with optional source mapping and styling

ViewTransformPayload

Transformed view stream payload (plugin-provided)

ViewportInfo

Information about the viewport

VirtualBufferResult

Result of creating a virtual buffer

Enums

HunkStatus

Hunk status for Review Diff

MenuPosition

Position for inserting menu items or menus

OverlayColorSpec

Color specification that can be either RGB values or a theme key.

PluginAsyncMessage

Messages sent from async plugin tasks to the synchronous main loop

PluginCommand

Plugin command - allows plugins to send commands to the editor

PluginResponse

Response from the editor for async plugin operations

ViewTokenWireKind

Wire-format view token kind (serialized for plugin transforms)