@synclineapi/editor 4.0.2 → 4.0.4

package/dist/types/index.d.ts

@@ -0,0 +1,1474 @@
+declare interface BracketMatch {
+    open: CursorPosition;
+    close: CursorPosition;
+}
+
+export declare const BUILT_IN_THEMES: ThemeDefinition[];
+
+/**
+ * Snapshot of token cache performance counters.
+ * Useful for monitoring and diagnosing tokeniser regressions.
+ */
+export declare interface CacheMetrics {
+    /** Number of successful cache lookups (cache hits). */
+    hits: number;
+    /** Number of failed lookups that required re-tokenising a line. */
+    misses: number;
+    /** Number of entries evicted to stay within `maxSize`. */
+    evictions: number;
+    /** Current number of entries in the cache. */
+    size: number;
+}
+
+/**
+ * Context passed to a `provideCompletions` callback.
+ * Describes the current cursor position and document state at the moment
+ * the autocomplete popup is about to open.
+ */
+export declare interface CompletionContext {
+    /** The full text of the line the cursor is on. */
+    line: string;
+    /** Zero-based column index of the cursor within the line. */
+    col: number;
+    /** The word-prefix immediately before the cursor (characters typed so far). */
+    prefix: string;
+    /** The active language identifier (e.g. `'typescript'`, `'css'`). */
+    language: string;
+    /** The full document as an array of lines (read-only view). */
+    doc: readonly string[];
+}
+
+/**
+ * A single entry shown in the autocomplete popup.
+ *
+ * @example
+ * ```ts
+ * const item: CompletionItem = {
+ *   label: 'myFunction',
+ *   kind:  'fn',
+ *   detail: '(x: number) => void',
+ * };
+ * ```
+ */
+export declare interface CompletionItem {
+    /** The text inserted when this item is accepted. Also used for filtering. */
+    label: string;
+    /** Visual category badge shown in the popup. */
+    kind: CompletionKind;
+    /**
+     * Short hint shown on the right side of the popup row (type signature, source, etc.).
+     * Keep this brief — one line or a short type annotation.
+     */
+    detail?: string;
+    /**
+     * Full documentation shown in the VS Code-style description panel on the right side
+     * of the popup when this item is selected. Supports plain text; newlines are rendered
+     * as paragraph breaks. Falls back to `body` preview for `'snip'` items when omitted.
+     *
+     * @example
+     * ```ts
+     * { label: 'fetch', kind: 'fn', detail: 'Promise<Response>',
+     *   description: 'Fetches a resource from the network.\n\nReturns a Promise that resolves to a Response.' }
+     * ```
+     */
+    description?: string;
+    /**
+     * Snippet body template. When present, accepting this item expands the
+     * full body instead of inserting just the label. Use `$1`, `$2`, … as
+     * tab-stop placeholders — the cursor is placed at `$1` after expansion.
+     * Use `\n` for newlines; indentation is inherited from the trigger line.
+     *
+     * Set `kind` to `'snip'` so the badge shows **S** in the popup.
+     *
+     * @example
+     * ```ts
+     * { label: 'forof', kind: 'snip', detail: 'for…of loop',
+     *   body: 'for (const $1 of $2) {\n  $3\n}' }
+     * ```
+     */
+    body?: string;
+    /**
+     * Restrict this item to specific languages. When provided, the item only appears
+     * when the editor's active language matches. Omit to show in all languages.
+     *
+     * @example `language: 'typescript'`  or  `language: ['typescript', 'javascript']`
+     */
+    language?: string | string[];
+}
+
+/**
+ * Category of a completion item, controlling the badge icon shown in the popup.
+ *
+ * - `'kw'`   — keyword (badge: **K**)
+ * - `'fn'`   — function or method (badge: **f**)
+ * - `'typ'`  — type or interface (badge: **T**)
+ * - `'cls'`  — class (badge: **C**)
+ * - `'var'`  — variable, property, or other symbol (badge: **·**)
+ * - `'snip'` — snippet template (badge: **S**); accepting expands a multi-line body
+ * - `'emmet'` — emmet abbreviation (badge: **E**); accepting expands the abbreviation to HTML
+ */
+export declare type CompletionKind = 'kw' | 'fn' | 'typ' | 'cls' | 'var' | 'snip' | 'emmet';
+
+/**
+ * Quick factory function for creating an editor instance.
+ *
+ * @param container The DOM element to mount the editor in.
+ * @param config Optional editor configuration.
+ * @returns The editor API.
+ */
+export declare function createEditor(container: HTMLElement, config?: EditorConfig): EditorAPI;
+
+/**
+ * A single cursor position in document (line/column) space.
+ * Both `row` and `col` are zero-based.
+ */
+export declare interface CursorPosition {
+    /** Zero-based line index within the document. */
+    row: number;
+    /** Zero-based character offset within the line. */
+    col: number;
+}
+
+/**
+ * A single editing operation that can be applied forward (redo) or inverted (undo).
+ *
+ * - `insert`  — `lines` were inserted starting at `row`. Undo removes them; redo re-inserts.
+ * - `delete`  — `count` lines starting at `row` were removed; `removed` holds their content.
+ *               Undo re-inserts; redo removes again.
+ * - `replace` — lines `[row, row + oldLines.length)` were replaced by `newLines`.
+ *               Undo swaps `newLines` back to `oldLines`; redo swaps forward again.
+ *
+ * Only the affected lines are stored — never a full document copy — making this
+ * safe for documents with 1 M+ lines.
+ */
+declare type EditOp = {
+    kind: 'insert';
+    row: number;
+    lines: string[];
+} | {
+    kind: 'delete';
+    row: number;
+    count: number;
+    removed: string[];
+} | {
+    kind: 'replace';
+    row: number;
+    oldLines: string[];
+    newLines: string[];
+};
+
+/**
+ * Public API surface returned by `SynclineEditor.create()`.
+ * All methods are safe to call at any time after construction.
+ */
+export declare interface EditorAPI {
+    /**
+     * Returns the full document content as a single newline-joined string.
+     */
+    getValue(): string;
+    /**
+     * Replaces the entire document content.
+     * Records an undo snapshot before overwriting, so the change can be undone.
+     * Fires `onChange`.
+     */
+    setValue(value: string): void;
+    /**
+     * Returns a copy of the current cursor position.
+     */
+    getCursor(): CursorPosition;
+    /**
+     * Moves the cursor to the given position and scrolls it into view.
+     */
+    setCursor(position: CursorPosition): void;
+    /**
+     * Returns a copy of the current selection, or `null` if nothing is selected.
+     */
+    getSelection(): Selection_2 | null;
+    /**
+     * Sets or clears the selection without moving the cursor.
+     * Pass `null` to deselect.
+     */
+    setSelection(selection: Selection_2 | null): void;
+    /**
+     * Inserts text at the current cursor position, replacing any active selection.
+     * No-op when `readOnly` is `true`.
+     */
+    insertText(text: string): void;
+    /**
+     * Applies a theme by registered ID or by passing a full `ThemeDefinition`.
+     * Rebuilds minimap colours and re-renders immediately.
+     */
+    setTheme(theme: string | ThemeDefinition): void;
+    /**
+     * Updates any subset of config options at runtime.
+     * Visual options (font, cursor, gutter, etc.) take effect immediately.
+     * Structural options (`showMinimap`, `showStatusBar`) add or remove DOM nodes.
+     */
+    updateConfig(patch: Partial<EditorConfig>): void;
+    /**
+     * Focuses the hidden textarea that captures keyboard input.
+     */
+    focus(): void;
+    /**
+     * Returns the IDs of all currently registered themes (built-in + custom).
+     */
+    getThemes(): string[];
+    /**
+     * Registers a custom theme so it can be applied by ID via `setTheme()`.
+     * If a theme with the same `id` already exists it is overwritten.
+     */
+    registerTheme(theme: ThemeDefinition): void;
+    /**
+     * Undoes the last edit operation.
+     * No-op if the undo stack is empty or `readOnly` is `true`.
+     */
+    undo(): void;
+    /**
+     * Redoes the last undone operation.
+     * No-op if the redo stack is empty or `readOnly` is `true`.
+     */
+    redo(): void;
+    /**
+     * Executes a built-in editor command by name.
+     * Mutating commands are no-ops when `readOnly` is `true`.
+     *
+     * Supported command names:
+     * `'undo'`, `'redo'`, `'selectAll'`, `'copy'`, `'cut'`,
+     * `'toggleComment'`, `'duplicateLine'`, `'deleteLine'`,
+     * `'toggleWordWrap'`, `'find'`, `'findReplace'`,
+     * `'indentLine'`, `'outdentLine'`
+     */
+    executeCommand(command: string): void;
+    /**
+     * Removes all editor DOM nodes from the host element and cleans up
+     * internal state. The instance should not be used after calling this.
+     */
+    destroy(): void;
+}
+
+declare abstract class EditorAutocomplete extends EditorFind {
+    protected _acVisible(): boolean;
+    protected _acHide(): void;
+    protected _acTrigger(): void;
+    protected _acTriggerNow(): void;
+    protected _renderAcPopup(): void;
+    protected _posAcPopup(): void;
+    protected _acAccept(): void;
+    protected _allCompletions(): CompletionItem[];
+    protected _emmetCheck(): void;
+    protected _emmetAccept(): boolean;
+    protected _snippetCheck(): void;
+    protected _snippetAccept(): boolean;
+    protected _expandBodyAt(body: string, triggerStart: number): void;
+    protected _ctrlD(): void;
+}
+
+declare abstract class EditorBase {
+    protected readonly _host: HTMLElement;
+    protected readonly _shadow: ShadowRoot;
+    protected readonly _editorEl: HTMLElement;
+    protected readonly _spacerEl: HTMLElement;
+    protected readonly _vpEl: HTMLElement;
+    protected readonly _inputEl: HTMLTextAreaElement;
+    protected readonly _minimapWrap: HTMLElement;
+    protected readonly _mmCanvas: HTMLCanvasElement;
+    protected readonly _mmSlider: HTMLElement;
+    protected readonly _statusBar: HTMLElement;
+    protected readonly _findBar: HTMLElement;
+    protected readonly _findInput: HTMLInputElement;
+    protected readonly _replaceInput: HTMLInputElement;
+    protected readonly _findCount: HTMLElement;
+    protected readonly _replaceRow: HTMLElement;
+    protected readonly _acPopup: HTMLElement;
+    protected readonly _emmetTip: HTMLElement;
+    protected readonly _snippetTip: HTMLElement;
+    protected readonly _hoverTip: HTMLElement;
+    protected readonly _themeOverlay: HTMLElement;
+    protected readonly _themePanel: HTMLElement;
+    protected readonly _placeholderEl: HTMLElement;
+    protected readonly _goToLineBar: HTMLElement;
+    protected readonly _goToLineInput: HTMLInputElement;
+    protected readonly _goToLineHint: HTMLElement;
+    protected _config: Required<EditorConfig>;
+    protected _tab: EditorTab;
+    protected _wm: WrapMap;
+    protected _foldedLines: Map<number, number>;
+    protected _tokenCache: TokenCache;
+    protected _themeManager: ThemeManager;
+    protected _findMatches: FindMatch[];
+    protected _findIdx: number;
+    protected _findCaseSensitive: boolean;
+    protected _findRegex: boolean;
+    protected _wordHighlights: FindMatch[];
+    protected _bracketMatch: BracketMatch | null;
+    protected _acItems: CompletionItem[];
+    protected _acSel: number;
+    protected _acPrefix: string;
+    protected _acStartCol: number;
+    protected _emmetAcStartCol: number;
+    protected _mc: MultiCursorState;
+    protected _extraCursors: ExtraCursor[];
+    protected _isDragging: boolean;
+    protected _dragAnchor: CursorPosition | null;
+    protected _hoverTimer: ReturnType<typeof setTimeout> | null;
+    protected _hoverPinned: boolean;
+    protected _mmDragMode: 'none' | 'slider' | 'jump';
+    protected _mmDragStartY: number;
+    protected _mmDragStartScroll: number;
+    protected _mmSliderOffset: number;
+    protected _mmColors: MinimapColors;
+    protected _lastInputTime: number;
+    protected _linewiseCopy: boolean;
+    protected _dynamicStyleEl: HTMLStyleElement;
+    protected _emmetExpanded: {
+        abbr: string;
+        result: string;
+        start: number;
+    } | null;
+    protected _snippetExpanded: {
+        snippet: CompletionItem;
+        start: number;
+    } | null;
+    protected _snippetSession: {
+        stops: Array<{
+            row: number;
+            col: number;
+        }>;
+        idx: number;
+    } | null;
+    protected _acDebounceTimer: ReturnType<typeof setTimeout> | null;
+    protected _rafId: number | null;
+    /** Number of visual rows currently rendered in the DOM viewport. */
+    protected _renderedRowCount: number;
+    /** Last scrollTop seen in _render(); used to gate wrap-map rebuilds. */
+    protected _lastRenderScroll: number;
+    protected _logicalScroll(domScrollTop: number): number;
+    protected _domScroll(logicalPx: number): number;
+    protected readonly _onWinMouseUp: () => void;
+    protected readonly _onWinResize: () => void;
+    protected readonly _onEditorScroll: () => void;
+    protected readonly _onWinMmMouseMove: (e: MouseEvent) => void;
+    protected readonly _onWinMmMouseUp: () => void;
+    protected _ro: ResizeObserver | null;
+    protected abstract _render(): void;
+    protected abstract _scheduleRender(): void;
+    protected abstract _scrollIntoView(): void;
+    protected abstract _applyDynamicStyles(): void;
+    protected abstract _rebuildWrapMap(): void;
+    protected abstract _bindEditorEvents(): void;
+    protected abstract _bindMinimapEvents(): void;
+    protected abstract _bindFindEvents(): void;
+    protected abstract _toggleWrap(): void;
+    protected abstract _openThemePicker(): void;
+    protected abstract _hideHover(): void;
+    protected abstract _updateMinimap(): void;
+    constructor(container: HTMLElement, config?: EditorConfig);
+    private _buildFindBar;
+    private _buildGoToLineBar;
+    protected _openGoToLine(): void;
+    protected _closeGoToLine(): void;
+    protected _focusInput(): void;
+    private _buildStatusBar;
+    protected _destroyBase(): void;
+}
+
+/** ─── Editor Configuration ──────────────────────────────── */
+/**
+ * Full, deeply-customisable editor configuration.
+ * Every field is optional — sensible defaults are applied for any omitted field.
+ * Pass this object to `SynclineEditor.create()` to configure the editor on
+ * initialisation, or call `updateConfig()` to change options at runtime.
+ */
+export declare interface EditorConfig {
+    /**
+     * Initial document content.
+     * Accepts either a newline-delimited string or a pre-split string array.
+     * Default: `''` (empty document).
+     */
+    value?: string | string[];
+    /**
+     * Language used for syntax highlighting and autocomplete.
+     * Selects the built-in keyword set, type set, and built-in completion items
+     * appropriate for that language.
+     * Default: `'typescript'`.
+     */
+    language?: Language;
+    /**
+     * Active theme.
+     * Pass a registered theme ID string (e.g. `'vr-dark'`) or a full
+     * `ThemeDefinition` object for a custom theme.
+     * Default: `''` (built-in VR Dark theme).
+     */
+    theme?: string | ThemeDefinition;
+    /**
+     * Show the line-number gutter on the left side of the editor.
+     * When `false` the gutter is hidden and its width is removed from all
+     * mouse-position calculations.
+     * Default: `true`.
+     */
+    showGutter?: boolean;
+    /**
+     * Show the minimap panel on the right side of the editor.
+     * Can be toggled at runtime via `updateConfig({ showMinimap: false })`.
+     * Default: `true`.
+     */
+    showMinimap?: boolean;
+    /**
+     * Show the status bar at the bottom of the editor.
+     * Displays cursor position, language, selection count, and undo depth.
+     * Default: `true`.
+     */
+    showStatusBar?: boolean;
+    /**
+     * Wrap long lines at `wrapColumn` characters instead of scrolling horizontally.
+     * Wrapped lines produce multiple visual rows for a single document line.
+     * Toggle at runtime with `updateConfig({ wordWrap: true })` or `Alt+Z`.
+     * Default: `false`.
+     */
+    wordWrap?: boolean;
+    /**
+     * Column at which lines are soft-wrapped when `wordWrap` is `true`.
+     * Has no effect when `wordWrap` is `false`.
+     * Default: `80`.
+     */
+    wrapColumn?: number;
+    /**
+     * CSS font-family string applied to all code text and the gutter.
+     * Example: `"'Fira Code', monospace"`.
+     * Default: `"'JetBrains Mono', monospace"`.
+     */
+    fontFamily?: string;
+    /**
+     * Font size in pixels applied to all code text.
+     * Default: `13`.
+     */
+    fontSize?: number;
+    /**
+     * Line height in pixels. Controls row height, cursor size, and all
+     * scroll/minimap calculations. Must match the rendered font metrics to
+     * avoid misaligned click targets.
+     * Default: `22`.
+     */
+    lineHeight?: number;
+    /**
+     * Number of spaces inserted when the Tab key is pressed (or used as the
+     * indentation unit when `insertSpaces` is `true`).
+     * Default: `2`.
+     */
+    tabSize?: number;
+    /**
+     * When `true`, pressing Tab inserts spaces; when `false`, a literal tab
+     * character (`\t`) is inserted.
+     * Default: `true`.
+     */
+    insertSpaces?: boolean;
+    /**
+     * Maximum number of undo snapshots retained per buffer.
+     * Older snapshots are discarded when the stack exceeds this limit.
+     * Default: `300`.
+     */
+    maxUndoHistory?: number;
+    /**
+     * Render faint vertical lines at each indentation level to aid visual
+     * alignment of nested code blocks.
+     * Default: `true`.
+     */
+    showIndentGuides?: boolean;
+    /**
+     * Highlight matching bracket pairs when the cursor is adjacent to a
+     * bracket character (`(`, `)`, `[`, `]`, `{`, `}`).
+     * Default: `true`.
+     */
+    bracketMatching?: boolean;
+    /**
+     * Enable code folding. When `true`, a fold toggle button appears in the
+     * gutter for foldable blocks (functions, classes, etc.).
+     * Default: `true`.
+     */
+    codeFolding?: boolean;
+    /**
+     * Enable Emmet abbreviation expansion via the Tab key.
+     * A preview tooltip appears when a valid Emmet abbreviation is detected
+     * before the cursor.
+     * Default: `true`.
+     */
+    emmet?: boolean;
+    /**
+     * Enable snippet expansion via the Tab key.
+     * When the word immediately before the cursor matches a snippet trigger,
+     * pressing Tab replaces it with the snippet body and places the cursor
+     * at the first `$1` tab stop.
+     * Built-in snippets are provided for TypeScript/JavaScript, CSS, and HTML.
+     * A preview tooltip appears when a matching trigger is detected.
+     * Default: `true`.
+     */
+    snippetExpansion?: boolean;
+    /**
+     * Show an autocomplete popup with suggestions as the user types.
+     * Suggestions are derived from symbols already present in the document.
+     * Default: `true`.
+     */
+    autocomplete?: boolean;
+    /**
+     * Allow multiple simultaneous cursors.
+     * Multi-cursor is activated via `Alt+Click` (add cursor) and `Ctrl+D`
+     * (select next occurrence). Setting this to `false` disables both.
+     * Default: `true`.
+     */
+    multiCursor?: boolean;
+    /**
+     * Enable the find bar (Ctrl+F / Cmd+F).
+     * When `false`, the find bar cannot be opened via keyboard shortcut or
+     * `executeCommand('find')`, and the Ctrl+F key combination is released
+     * back to the browser.
+     * Default: `true`.
+     */
+    find?: boolean;
+    /**
+     * Enable find-and-replace (Ctrl+H / Cmd+H).
+     * When `false`, the replace row is inaccessible and Ctrl+H is a no-op.
+     * Has no effect when `find` is also `false`.
+     * Default: `true`.
+     */
+    findReplace?: boolean;
+    /**
+     * Enable word selection on double-click.
+     * When `true`, double-clicking a word selects it (standard editor behaviour).
+     * When `false`, double-clicking places the cursor without creating a selection.
+     * Default: `true`.
+     */
+    wordSelection?: boolean;
+    /**
+     * Highlight all occurrences of the word currently under the cursor.
+     * When `true`, every other occurrence of the same whole-word token in the
+     * document gets a subtle background box (`--word-hl-bg` / `--word-hl-border`).
+     * Highlights are cleared automatically when a text selection is active.
+     * When `false`, no word-occurrence highlighting is applied.
+     * Default: `true`.
+     */
+    wordHighlight?: boolean;
+    /**
+     * Highlight the line that currently contains the cursor with a distinct
+     * background colour (`--cur-line-bg`) and a matching gutter background.
+     * Set to `false` to disable the active-line indicator entirely.
+     * Default: `true`.
+     */
+    highlightActiveLine?: boolean;
+    /**
+     * Minimum number of characters the user must type before the autocomplete
+     * popup appears. Increasing this reduces noise on short prefixes; setting it
+     * to `1` triggers suggestions after a single character.
+     * Default: `2`.
+     */
+    autocompletePrefixLength?: number;
+    /**
+     * Prevent all content mutations.
+     * When `true`, typing, paste, cut, undo/redo, and all other edit operations
+     * are silently blocked. Navigation, selection, copy, and find still work.
+     * Default: `false`.
+     */
+    readOnly?: boolean;
+    /**
+     * Additional keywords to include in syntax highlighting beyond the
+     * built-in keyword list for the active language.
+     * Example: `['myDSLKeyword', 'pipeline']`.
+     * Default: `[]`.
+     */
+    extraKeywords?: string[];
+    /**
+     * Additional type names to recognise during syntax highlighting beyond
+     * the built-in type list for the active language.
+     * Example: `['MyCustomType', 'Result']`.
+     * Default: `[]`.
+     */
+    extraTypes?: string[];
+    /**
+     * The **single unified completions array** — the only completion source you need.
+     *
+     * Every item is a `CompletionItem`. Differentiate by `kind`:
+     * - `'kw'`, `'fn'`, `'typ'`, `'cls'`, `'var'` — regular completions merged with built-ins
+     * - `'snip'` — snippet: set `body` and the item expands like a snippet on accept
+     *
+     * All items can carry a `language` filter and a `description` for the docs panel.
+     *
+     * @example
+     * ```ts
+     * completions: [
+     *   // Regular completion with docs
+     *   { label: 'myQuery', kind: 'fn', detail: 'GraphQL helper',
+     *     description: 'Executes a GraphQL query and returns the result.' },
+     *   // Inline snippet
+     *   { label: 'mycomp', kind: 'snip', detail: 'My component',
+     *     body: 'export function $1Component() {\n  return <div>$2</div>;\n}',
+     *     language: ['typescript'] },
+     * ]
+     * ```
+     * Default: `[]`.
+     */
+    completions?: CompletionItem[];
+    /**
+     * When `true`, the items in `completions` **replace** the built-in language
+     * keywords/types/functions entirely instead of being merged on top.
+     * Only the provided items (plus in-file word suggestions) will appear.
+     *
+     * Use alongside `completions`.
+     *
+     * @example
+     * ```ts
+     * // DSL editor — show only your own keywords
+     * replaceBuiltins: true,
+     * completions: [
+     *   { label: 'SELECT', kind: 'kw', detail: 'SQL' },
+     *   { label: 'FROM',   kind: 'kw', detail: 'SQL' },
+     * ]
+     * ```
+     * Default: `false`.
+     */
+    replaceBuiltins?: boolean;
+    /**
+     * Custom syntax tokeniser override.
+     *
+     * When provided, this function is called **instead of** the built-in
+     * regex-free tokeniser for **every line** before it is rendered.
+     * Return an array of `TokenSegment` objects that cover the half-open
+     * character ranges you want coloured.  Ranges you don't cover are
+     * rendered as plain text.
+     *
+     * The result is still cached by the internal LRU token cache (keyed on
+     * the raw line text + language), so the function is only called once per
+     * unique `(text, language)` pair — not on every frame.
+     *
+     * Pass `null` or `undefined` to fall through to the built-in tokeniser.
+     *
+     * **Use this for custom languages, DSLs, or Markdown** where you need
+     * full control over which character ranges receive which token class.
+     *
+     * @example
+     * ```ts
+     * // Minimal Markdown tokeniser
+     * provideTokens: (line, _lang) => {
+     *   const segs: TokenSegment[] = [];
+     *   // ATX headings  →  keyword colour
+     *   if (/^#{1,6}\s/.test(line))
+     *     segs.push({ cls: 'kw', start: 0, end: line.length });
+     *   // **bold**  →  string colour
+     *   for (const m of line.matchAll(/\*\*(.+?)\*\*\/g))
+     * segs.push({ cls: 'str', start: m.index!, end: m.index! + m[0].length });
+     *   return segs;
+     * }
+     * ```
+     *
+     * Default: `undefined` (use built-in tokeniser).
+     */
+    provideTokens?: (line: string, language: string) => TokenSegment[];
+    /**
+     * Dynamic completion provider called each time the autocomplete popup is
+     * about to open. Receives a `CompletionContext` describing the current
+     * cursor position and returns an array of `CompletionItem` to display
+     * instead of the built-in language completions.
+     *
+     * Return `null` or `undefined` to fall through to the built-in defaults.
+     *
+     * @example
+     * ```ts
+     * provideCompletions: (ctx) => {
+     *   if (ctx.prefix.startsWith('$')) {
+     *     return mySymbolTable.map(s => ({ label: s, kind: 'var' }));
+     *   }
+     *   return null; // use defaults
+     * }
+     * ```
+     * Default: `undefined` (use built-in language completions).
+     */
+    provideCompletions?: (context: CompletionContext) => CompletionItem[] | null | undefined;
+    /**
+     * Auto-close bracket and quote pairs.
+     * When the user types the opening character, the closing character is
+     * inserted automatically and the cursor placed between them.
+     *
+     * Pass an empty object `{ } ` to disable all auto-closing.
+     *
+     * @example
+     * ```ts
+     * // Only auto-close parentheses and curly braces
+     * autoClosePairs: { '(': ')', '{': '}' }
+     * ```
+     * Default: `{ '(': ')', '[': ']', '{': '}', '"': '"', "'": "'", '`': '`' } `.
+     */
+    autoClosePairs?: Record<string, string>;
+    /**
+     * Line comment token used by the "toggle comment" command (Ctrl+/).
+     * Set to the prefix string for single-line comments in your language.
+     *
+     * When empty or omitted, the editor auto-selects based on `language`:
+     * - TypeScript / JavaScript / CSS → `'//'`
+     * - Python / Ruby / Bash / YAML → `'#'`
+     * - Markdown / JSON → no comment token (toggle comment is a no-op)
+     *
+     * @example
+     * ```ts
+     * lineCommentToken: '#'   // Python, Ruby, shell scripts
+     * lineCommentToken: '--'  // SQL, Lua
+     * lineCommentToken: '%'   // LaTeX
+     * ```
+     * Default: `''` (auto-detect from language).
+     */
+    lineCommentToken?: string;
+    /**
+     * A string containing every character that should be treated as a word
+     * separator (non-word character) for word-based operations: double-click
+     * word selection, Ctrl+Left/Right navigation, and Ctrl+D (select next
+     * occurrence).
+     *
+     * Characters NOT in this string (and not whitespace) are treated as word
+     * characters. Leave empty to use the default `\w` + `$` word boundary.
+     *
+     * @example
+     * ```ts
+     * // Treat hyphens as word separators (useful for CSS/Markdown)
+     * wordSeparators: '`~!@#%^&*()-=+[{]}\\|;:\'",.<>/?'
+     * ```
+     * Default: `''` (use built-in `\w$` word character definition).
+     */
+    wordSeparators?: string;
+    /**
+     * Milliseconds window for grouping consecutive keystrokes into a single
+     * undo snapshot. Keystrokes within this window are merged and undone
+     * together in one step.
+     *
+     * Set to `0` to record a separate undo snapshot for every keystroke.
+     * Default: `700`.
+     */
+    undoBatchMs?: number;
+    /**
+     * Maximum number of items shown in the autocomplete popup.
+     * Includes both base completions and in-file word suggestions.
+     * Default: `14`.
+     */
+    maxCompletions?: number;
+    /**
+     * Width of the line-number gutter in pixels.
+     * Affects mouse-to-cursor mapping and popup positioning.
+     * Default: `60`.
+     */
+    gutterWidth?: number;
+    /**
+     * Width of the minimap panel in pixels.
+     * Default: `120`.
+     */
+    minimapWidth?: number;
+    /**
+     * Cursor blink period in milliseconds.
+     * The cursor completes one full blink cycle (on → off → on) in this time.
+     * Set to a very large value (e.g. `999999`) to effectively disable blinking.
+     * Default: `1050`.
+     */
+    cursorBlinkRate?: number;
+    /**
+     * Visual style of the text cursor.
+     * - `'line'`      — thin vertical beam (default, VS Code-style)
+     * - `'block'`     — filled rectangle covering the character under the cursor
+     * - `'underline'` — horizontal bar below the character
+     * Default: `'line'`.
+     */
+    cursorStyle?: 'line' | 'block' | 'underline';
+    /**
+     * Controls whether whitespace characters are rendered as visible glyphs.
+     * - `'none'`     — whitespace is invisible (default)
+     * - `'boundary'` — leading and trailing spaces shown as `·`, tabs as `→`
+     * - `'all'`      — every space shown as `·`, every tab as `→`
+     * Default: `'none'`.
+     */
+    renderWhitespace?: 'none' | 'boundary' | 'all';
+    /**
+     * Per-token syntax-highlight colour overrides applied **on top of** the
+     * active theme. Any field set here takes precedence over the corresponding
+     * `ThemeTokens` colour without replacing the entire theme.
+     *
+     * Set a field to `''` (empty string) to restore the theme's default for
+     * that token. Omit a field entirely to leave it unchanged.
+     *
+     * @example
+     * ```ts
+     * // Dracula-inspired keywords + string colours on any base theme
+     * editor.updateConfig({
+     *   tokenColors: {
+     *     keyword: '#ff79c6',
+     *     string: '#f1fa8c',
+     *     function: '#50fa7b',
+     *     type: '#8be9fd',
+     *     comment: '#6272a4',
+     *   }
+     * });
+     * ```
+     * Default: `{ } ` (no overrides — all colours come from the active theme).
+     */
+    tokenColors?: TokenColors;
+    /**
+     * Called whenever the document content changes (after every keystroke,
+     * paste, undo, or programmatic `setValue`).
+     * Receives the full document as a newline-joined string.
+     */
+    onChange?: (value: string) => void;
+    /**
+     * Called whenever the cursor moves to a new position.
+     * Receives a copy of the new `CursorPosition`.
+     */
+    onCursorChange?: (position: CursorPosition) => void;
+    /**
+     * Called whenever the selection changes or is cleared.
+     * Receives a copy of the new `Selection`, or `null` when deselected.
+     */
+    onSelectionChange?: (selection: Selection_2 | null) => void;
+    /**
+     * Called when the editor gains keyboard focus.
+     */
+    onFocus?: () => void;
+    /**
+     * Called when the editor loses keyboard focus.
+     */
+    onBlur?: () => void;
+    /**
+     * Enable hover documentation tooltips.
+     * When `true`, resting the pointer over a recognised identifier for ~500 ms
+     * shows a floating tooltip with its type signature and description.
+     * Covers built-in JS/TS/CSS symbols and any symbols provided via `provideHover`.
+     * Default: `true`.
+     */
+    hover?: boolean;
+    /**
+     * Custom hover documentation provider.
+     * Called when the user hovers over an identifier and no built-in doc is found.
+     * Return a `HoverDoc` object to show a tooltip, or `null`/`undefined` to show nothing.
+     *
+     * @example
+     * ```ts
+     * provideHover: (ctx) => {
+     *   const entry = mySymbolTable[ctx.word];
+     *   if (!entry) return null;
+     *   return {
+     *     title: entry.name,
+     *     type: entry.signature,
+     *     body: entry.description,
+     *   };
+     * }
+     * ```
+     */
+    provideHover?: (context: HoverContext) => HoverDoc | null | undefined;
+    /**
+     * Ghost text shown inside the editor when the document is completely empty.
+     * Only rendered when this string is non-empty.
+     * @default ''
+     */
+    placeholder?: string;
+    /**
+     * Enable the Go to Line bar (Ctrl+G / Cmd+G).
+     * When `false` the shortcut does nothing and the bar is never shown.
+     * @default false
+     */
+    goToLine?: boolean;
+}
+
+declare abstract class EditorEditing extends EditorRenderer {
+    protected _insertStr(text: string, groupable: boolean): void;
+    protected _doBackspace(): void;
+    protected _doEnter(): void;
+    protected _doDelete(): void;
+    protected _selectAll(): void;
+    protected _doCopy(): void;
+    protected _doCut(): void;
+    /**
+     * Cmd+Enter: insert a blank (auto-indented) line below the current line and
+     * move the cursor there — regardless of where the cursor is on the line.
+     * Matches VS Code's "editor.action.insertLineAfter".
+     */
+    protected _doInsertLineBelow(): void;
+    /**
+     * Cmd+Shift+Enter: insert a blank (auto-indented) line above the current line
+     * and move the cursor there.
+     * Matches VS Code's "editor.action.insertLineBefore".
+     */
+    protected _doInsertLineAbove(): void;
+    protected _toggleComment(): void;
+    protected _duplicateLine(): void;
+    protected _deleteLine(): void;
+    protected _indentSel(): void;
+    protected _unindentSel(): void;
+    protected _toggleWrap(): void;
+    protected _getSelRows(): number[];
+    protected _duplicateLines(down: boolean): void;
+    protected _moveLines(up: boolean): void;
+    /** Skip forward past one word boundary (Option/Ctrl+Right, Option/Ctrl+Delete). */
+    protected _wordSkipRight(line: string, col: number): number;
+    /** Skip backward past one word boundary (Option/Ctrl+Left, Option/Ctrl+Backspace). */
+    protected _wordSkipLeft(line: string, col: number): number;
+    /** Cmd+Backspace: delete from cursor back to column 0 on the same line. */
+    protected _deleteToLineStart(): void;
+    /** Option/Ctrl+Backspace: delete one word to the left of cursor. */
+    protected _deleteWordLeft(): void;
+    /** Cmd+Delete: delete from cursor forward to end of line. */
+    protected _deleteToLineEnd(): void;
+    /** Option/Ctrl+Delete: delete one word to the right of cursor. */
+    protected _deleteWordRight(): void;
+    protected _doUndo(): void;
+    protected _doRedo(): void;
+}
+
+declare abstract class EditorEvents extends EditorHoverAndTheme {
+    protected _posFromMouse(e: MouseEvent): CursorPosition;
+    protected _bindEditorEvents(): void;
+    protected _onKeyDown(e: KeyboardEvent): void;
+    protected _handleArrowKeys(e: KeyboardEvent, _ctrl: boolean, shift: boolean): void;
+    protected _isWordChar(ch: string): boolean;
+    private _wordStart;
+    private _wordEnd;
+    protected _onInput(e: InputEvent): void;
+    protected _bindMinimapEvents(): void;
+}
+
+declare abstract class EditorFind extends EditorEditing {
+    protected _openFind(withReplace: boolean): void;
+    protected _closeFind(): void;
+    protected _runFind(q: string): void;
+    protected _navFind(dir: 1 | -1): void;
+    protected _doReplaceOne(): void;
+    protected _doReplaceAll(): void;
+    protected _bindFindEvents(): void;
+}
+
+declare abstract class EditorHoverAndTheme extends EditorAutocomplete {
+    protected _scheduleHover(e: MouseEvent): void;
+    protected _doHover(clientX: number, clientY: number): void;
+    protected _showHoverTip(doc: HoverDoc, clientX: number, clientY: number): void;
+    protected _hideHover(): void;
+    protected _openThemePicker(): void;
+    protected _applyTheme(theme: string | ThemeDefinition): void;
+}
+
+declare abstract class EditorRenderer extends EditorStyles {
+    protected _scheduleRender(): void;
+    protected _render(): void;
+    protected readonly _onFoldBtnClick: (e: MouseEvent) => void;
+    protected _updateStatusBar(): void;
+    protected _updateMinimap(): void;
+    protected _rebuildWrapMap(): void;
+    protected _scrollIntoView(): void;
+}
+
+declare abstract class EditorStyles extends EditorBase {
+    protected _applyDynamicStyles(): void;
+    protected _applyTokenOverrides(): void;
+    protected _refreshMinimapColors(): void;
+}
+
+/**
+ * The full state of an open editor buffer (tab).
+ * Contains the document text, cursor, selection, scroll offset, and history stacks.
+ */
+export declare interface EditorTab {
+    /** Unique numeric identifier for this buffer. */
+    fileId: number;
+    /** Document content as an array of lines (without newline characters). */
+    doc: string[];
+    /** Current cursor position. */
+    cur: CursorPosition;
+    /** Current text selection, or `null` if nothing is selected. */
+    sel: Selection_2 | null;
+    /** `true` if the buffer has unsaved changes. */
+    dirty: boolean;
+    /** Stack of snapshots that can be restored via Undo. */
+    undoStack: HistorySnapshot[];
+    /** Stack of snapshots that can be restored via Redo. */
+    redoStack: HistorySnapshot[];
+    /** Vertical scroll offset of the editor viewport in pixels. */
+    scrollTop: number;
+}
+
+/**
+ * An additional cursor in a multi-cursor editing session.
+ * Each extra cursor tracks its own position and optional selection range.
+ */
+export declare interface ExtraCursor {
+    /** Zero-based line index of this cursor. */
+    row: number;
+    /** Zero-based column of this cursor. */
+    col: number;
+    /** Selection associated with this cursor, or `null` if none. */
+    sel: Selection_2 | null;
+}
+
+/**
+ * A single result from a find (search) operation.
+ * Identifies a contiguous substring within one document line.
+ */
+export declare interface FindMatch {
+    /** Zero-based line index where the match was found. */
+    row: number;
+    /** Zero-based column where the match starts. */
+    col: number;
+    /** Length of the matched text in characters. */
+    len: number;
+}
+
+/**
+ * A point-in-time snapshot of document state stored in the undo/redo stacks.
+ * Stores a delta `EditOp` rather than a full document copy.
+ */
+export declare interface HistorySnapshot {
+    /** The editing operation that was performed to reach the post-edit state. */
+    op: EditOp;
+    /** Cursor position before the operation (restored on undo). */
+    beforeCur: CursorPosition;
+    /** Selection before the operation (restored on undo). */
+    beforeSel: Selection_2 | null;
+    /** Cursor position after the operation (restored on redo). */
+    afterCur: CursorPosition;
+    /** Selection after the operation (restored on redo). */
+    afterSel: Selection_2 | null;
+    /**
+     * Extra cursor positions immediately BEFORE the operation.
+     * Restored when the operation is undone, so multi-cursor state
+     * (including per-cursor selections from Ctrl+D) is preserved
+     * across undo — identical to VS Code behaviour.
+     */
+    beforeExtra: ExtraCursor[];
+    /**
+     * Extra cursor positions immediately AFTER the operation.
+     * Restored when the operation is redone.
+     */
+    afterExtra: ExtraCursor[];
+}
+
+/**
+ * Context passed to a `provideHover` callback.
+ * Describes the word under the pointer and the surrounding document state.
+ */
+export declare interface HoverContext {
+    /** The full identifier under the pointer (may include a dot prefix, e.g. `"console.log"`). */
+    word: string;
+    /** Zero-based document line index where the pointer is. */
+    row: number;
+    /** Zero-based character column where the pointer is. */
+    col: number;
+    /** The full text of the hovered line. */
+    line: string;
+    /** The active language identifier (e.g. `'typescript'`). */
+    language: string;
+    /** The full document as a read-only array of lines. */
+    doc: readonly string[];
+}
+
+/**
+ * Documentation shown in a hover tooltip when the user rests the pointer
+ * over a recognised identifier in the editor.
+ */
+export declare interface HoverDoc {
+    /** Display name of the symbol — shown prominently at the top of the tooltip. */
+    title: string;
+    /**
+     * Type signature or category label (e.g. `"(...data: any[]) => void"`,
+     * `"primitive type"`, `"keyword"`).
+     * Rendered in monospace below the title.
+     */
+    type?: string;
+    /** Human-readable description of what the symbol does. */
+    body: string;
+    /**
+     * Restrict this doc entry to specific languages.
+     * When provided, the tooltip only appears when the editor's active language matches.
+     * Omit to show in all languages.
+     */
+    language?: string | string[];
+}
+
+/**
+ * Supported language identifiers for syntax highlighting and autocomplete.
+ * Pass as the `language` option in `EditorConfig`.
+ */
+export declare type Language = 'typescript' | 'javascript' | 'css' | 'json' | 'markdown' | 'text';
+
+/**
+ * Colour palette used when painting the minimap canvas.
+ * Each value is a CSS colour string resolved from the active theme.
+ * The interface also accepts arbitrary string keys so token class names
+ * (`'kw'`, `'fn'`, etc.) can be used for direct index access.
+ */
+export declare interface MinimapColors {
+    /** Colour for keyword tokens. */
+    kw: string;
+    /** Colour for function-name tokens. */
+    fn: string;
+    /** Colour for class-name tokens. */
+    cls: string;
+    /** Colour for type-name tokens. */
+    typ: string;
+    /** Colour for string-literal tokens. */
+    str: string;
+    /** Colour for numeric-literal tokens. */
+    num: string;
+    /** Colour for comment tokens. */
+    cmt: string;
+    /** Colour for decorator tokens. */
+    dec: string;
+    /** Colour for operator tokens. */
+    op: string;
+    /** Colour for plain (un-tokenised) text. */
+    txt: string;
+    /** Index signature — allows token class names to be used as dynamic keys. */
+    [key: string]: string;
+}
+
+declare interface MultiCursorState {
+    cursors: ExtraCursor[];
+    searchWord: string;
+    lastMatchRow: number;
+    lastMatchCol: number;
+}
+
+/**
+ * A selection range defined by an anchor (where selection started)
+ * and a focus (where the caret currently sits). Either end can be
+ * before the other — use `normaliseSelection` when you need start ≤ end.
+ */
+declare interface Selection_2 {
+    /** Anchor row — the line where the selection was started. */
+    ar: number;
+    /** Anchor column — the character offset where the selection was started. */
+    ac: number;
+    /** Focus row — the line where the caret currently sits. */
+    fr: number;
+    /** Focus column — the character offset where the caret currently sits. */
+    fc: number;
+}
+export { Selection_2 as Selection }
+
+export declare class SynclineEditor extends EditorEvents implements EditorAPI {
+    getValue(): string;
+    setValue(value: string): void;
+    getCursor(): CursorPosition;
+    setCursor(pos: CursorPosition): void;
+    getSelection(): Selection_2 | null;
+    setSelection(sel: Selection_2 | null): void;
+    insertText(text: string): void;
+    setTheme(theme: string | ThemeDefinition): void;
+    updateConfig(patch: Partial<EditorConfig>): void;
+    focus(): void;
+    getThemes(): string[];
+    registerTheme(theme: ThemeDefinition): void;
+    undo(): void;
+    redo(): void;
+    executeCommand(command: string): void;
+    destroy(): void;
+}
+
+export declare const THEME_DRACULA: ThemeDefinition;
+
+export declare const THEME_GITHUB_LIGHT: ThemeDefinition;
+
+export declare const THEME_MDX_DARK: ThemeDefinition;
+
+export declare const THEME_MDX_LIGHT: ThemeDefinition;
+
+export declare const THEME_MONOKAI: ThemeDefinition;
+
+export declare const THEME_SOLARIZED_LIGHT: ThemeDefinition;
+
+export declare const THEME_VR_DARK: ThemeDefinition;
+
+export declare const THEME_VSCODE_DARK: ThemeDefinition;
+
+/**
+ * A named, complete theme definition.
+ * Pass a `ThemeDefinition` to `setTheme()` or `registerTheme()` to apply
+ * a fully custom colour scheme at runtime.
+ */
+export declare interface ThemeDefinition {
+    /** Unique identifier used to reference this theme (e.g. `'my-dark'`). */
+    id: string;
+    /** Human-readable display name shown in the theme picker. */
+    name: string;
+    /** Short description of the theme's appearance or origin. */
+    description: string;
+    /** `true` for light themes, `false` for dark themes. */
+    light: boolean;
+    /** Complete set of colour values for every CSS variable the theme controls. */
+    tokens: ThemeTokens;
+}
+
+declare class ThemeManager {
+    private readonly _registry;
+    private _activeId;
+    private readonly _root;
+    constructor(root: HTMLElement);
+    /** Register a custom or override theme. */
+    register(theme: ThemeDefinition): void;
+    /** Apply a theme by id or by definition. */
+    apply(idOrDef: string | ThemeDefinition): void;
+    get activeId(): string;
+    get activeTheme(): ThemeDefinition | undefined;
+    get allIds(): string[];
+    get all(): ThemeDefinition[];
+    private _applyTokens;
+}
+
+/** ─── Theme ─────────────────────────────────────────────── */
+/**
+ * The complete set of CSS custom-property values that define a theme's
+ * visual appearance. Every key maps 1-to-1 with a `--<name>` CSS variable
+ * injected on the editor host element.
+ */
+export declare interface ThemeTokens {
+    /** Deepest background — editor chrome and overall host fill. */
+    bg0: string;
+    /** Slightly lighter background — used for panels and sidebars. */
+    bg1: string;
+    /** Editor pane background. */
+    bg2: string;
+    /** Popover / floating-panel background (find bar, theme picker). */
+    bg3: string;
+    /** Input and list-item background inside popovers. */
+    bg4: string;
+    /** Subtle border — low-contrast dividers. */
+    border: string;
+    /** Medium-contrast border. */
+    border2: string;
+    /** High-contrast border — used for focused inputs and active elements. */
+    border3: string;
+    /** Primary text colour for code and labels. */
+    text: string;
+    /** Secondary text colour for metadata and de-emphasised labels. */
+    text2: string;
+    /** Muted text colour for placeholders and disabled states. */
+    text3: string;
+    /** Primary accent — cursor, links, and active highlights. */
+    accent: string;
+    /** Darker accent — status bar background. */
+    accent2: string;
+    /** Semantic green (success, string tokens in some themes). */
+    green: string;
+    /** Semantic orange (warnings, function tokens in some themes). */
+    orange: string;
+    /** Semantic purple (numbers, extra cursors). */
+    purple: string;
+    /** Semantic red (errors, decorator tokens). */
+    red: string;
+    /** Semantic yellow (class names in some themes). */
+    yellow: string;
+    /** Cursor beam / block fill colour. */
+    cur: string;
+    /** Glow halo colour rendered around the cursor. */
+    curGlow: string;
+    /** Background tint applied to the current-line row. */
+    curLineBg: string;
+    /** Gutter cell background on the current-line row. */
+    curLineGutter: string;
+    /** Default gutter background. */
+    gutterBg: string;
+    /** Gutter background on row hover. */
+    gutterHover: string;
+    /** Gutter right-border colour. */
+    gutterBorder: string;
+    /** Line-number text colour (inactive lines). */
+    gutterNum: string;
+    /** Line-number text colour on the active (cursor) line. */
+    gutterNumAct: string;
+    /** Background tint for selected text. */
+    selBg: string;
+    /** Background tint for word-occurrence highlights. */
+    wordHlBg: string;
+    /** Border colour for word-occurrence highlights. */
+    wordHlBorder: string;
+    /** Border colour for bracket-match highlights. */
+    bmBorder: string;
+    /** Background tint applied to folded-line rows. */
+    foldBg: string;
+    /** Bottom-border colour on folded-line rows. */
+    foldBorder: string;
+    /** Background tint for non-current find matches. */
+    findBg: string;
+    /** Border colour for non-current find matches. */
+    findBorder: string;
+    /** Background for the currently active find match. */
+    findCurBg: string;
+    /** Border colour for the currently active find match. */
+    findCurBorder: string;
+    /** Text colour inside the currently active find match. */
+    findCurText: string;
+    /** Background for the active file entry in a sidebar. */
+    fileActiveBg: string;
+    /** Text colour for the active file entry in a sidebar. */
+    fileActiveText: string;
+    /** Minimap panel background. */
+    mmBg: string;
+    /** Minimap viewport-slider fill colour. */
+    mmSlider: string;
+    /** Semi-transparent overlay dimming the out-of-view minimap area. */
+    mmDim: string;
+    /** Edge highlight on the minimap slider. */
+    mmEdge: string;
+    /** Colour of vertical indent-guide lines. */
+    indentGuide: string;
+    /** Colour for keyword tokens (`kw`). */
+    tokKw: string;
+    /** Colour for string-literal tokens (`str`). */
+    tokStr: string;
+    /** Colour for comment tokens (`cmt`). */
+    tokCmt: string;
+    /** Colour for function-name tokens (`fn`). */
+    tokFn: string;
+    /** Colour for numeric-literal tokens (`num`). */
+    tokNum: string;
+    /** Colour for class-name tokens (`cls`). */
+    tokCls: string;
+    /** Colour for operator tokens (`op`). */
+    tokOp: string;
+    /** Colour for type-name tokens (`typ`). */
+    tokTyp: string;
+    /** Colour for decorator tokens (`dec`). */
+    tokDec: string;
+}
+
+/** Simple LRU token cache — keyed by `"docLine:segIdx"`. */
+declare class TokenCache {
+    private readonly _cache;
+    private readonly _maxSize;
+    private _hits;
+    private _misses;
+    private _evictions;
+    constructor(maxSize?: number);
+    /** Live snapshot of cache performance. Useful for observability. */
+    get metrics(): CacheMetrics;
+    get(key: string, text: string): TokenSegment[] | null;
+    set(key: string, text: string, segs: TokenSegment[]): void;
+    invalidateLine(docLine: number, segCount: number): void;
+    /** Clear all cached entries and reset performance counters. */
+    clear(): void;
+    /** Reset performance counters without clearing cached entries. */
+    resetMetrics(): void;
+}
+
+/**
+ * Syntax token class identifiers produced by the tokeniser.
+ * Each value maps to a CSS class that controls token colour.
+ *
+ * - `'kw'`  — keyword (e.g. `if`, `const`, `return`)
+ * - `'str'` — string literal
+ * - `'cmt'` — comment
+ * - `'fn'`  — function name
+ * - `'num'` — numeric literal
+ * - `'cls'` — class name
+ * - `'op'`  — operator
+ * - `'typ'` — type name
+ * - `'dec'` — decorator
+ */
+export declare type TokenClass = 'kw' | 'str' | 'cmt' | 'fn' | 'num' | 'cls' | 'op' | 'typ' | 'dec';
+
+/**
+ * Per-token syntax-highlight colour overrides.
+ *
+ * Set any subset of these to override the corresponding CSS variable on top
+ * of the active theme — without needing to register a full `ThemeDefinition`.
+ * Accepts any valid CSS colour string (`'#ff79c6'`, `'hsl(330,100%,74%)'`,
+ * `'rgba(255,121,198,.9)'`, etc.).
+ *
+ * These map 1-to-1 to the `ThemeTokens` syntax fields:
+ * `keyword → tokKw`, `string → tokStr`, `comment → tokCmt`,
+ * `function → tokFn`, `number → tokNum`, `class → tokCls`,
+ * `operator → tokOp`, `type → tokTyp`, `decorator → tokDec`.
+ *
+ * @example
+ * ```ts
+ * editor.updateConfig({
+ *   tokenColors: {
+ *     keyword:  '#ff79c6',  // pink keywords
+ *     string:   '#f1fa8c',  // yellow strings
+ *     type:     '#8be9fd',  // cyan types
+ *     comment:  '#6272a4',  // muted comments
+ *   }
+ * });
+ * ```
+ */
+export declare interface TokenColors {
+    /** Colour for keyword tokens — `if`, `const`, `class`, `interface`, `return`, etc. */
+    keyword?: string;
+    /** Colour for string-literal tokens — single-quoted, double-quoted, and template literals. */
+    string?: string;
+    /** Colour for comment tokens — line comments (//) and block comments. */
+    comment?: string;
+    /** Colour for function-name tokens — `console`, `fetch`, `myFn` when followed by `(`. */
+    function?: string;
+    /** Colour for numeric-literal tokens — `42`, `3.14`, `0xff`, `1n`. */
+    number?: string;
+    /** Colour for class-name tokens — `MyClass`, `EventEmitter`, constructor calls. */
+    class?: string;
+    /** Colour for operator tokens — `+`, `=>`, `===`, `&&`, `?.`, `|`. */
+    operator?: string;
+    /** Colour for type-name tokens — `string`, `number`, `boolean`, `Promise`, `Record`. */
+    type?: string;
+    /** Colour for decorator tokens — `@Component`, `@Injectable`, `@deprecated`. */
+    decorator?: string;
+}
+
+/**
+ * A tokenised segment within a single line.
+ * Covers the half-open character range `[start, end)`.
+ */
+export declare interface TokenSegment {
+    /** Token class that determines the syntax highlight colour. */
+    cls: TokenClass;
+    /** Start character index (inclusive). */
+    start: number;
+    /** End character index (exclusive). */
+    end: number;
+}
+
+/**
+ * One visual (rendered) row on screen.
+ * A single document line may produce multiple `VisualRow` entries when
+ * word-wrap is active.
+ */
+export declare interface VisualRow {
+    /** Zero-based document line that this visual row belongs to. */
+    docLine: number;
+    /**
+     * Wrap-segment index within the document line.
+     * `0` for the first (or only) visual row of a line; `1`, `2`, … for
+     * subsequent wrapped segments.
+     */
+    segIdx: number;
+    /** The text content of this visual row segment. */
+    text: string;
+}
+
+declare interface WrapMap {
+    /** wrapMap[docLine] = array of segment strings (empty array for outside-window lines). */
+    segments: string[][];
+    /**
+     * Compact array of fully-computed visual rows covering only the window
+     * [windowStart, windowEnd].  Index 0 here corresponds to absolute visual
+     * row `windowVisStart`, so callers must offset: `visualRows[v - windowVisStart]`.
+     *
+     * For non-windowed mode `windowVisStart === 0` and the array covers the
+     * whole document — the offset is a no-op (0).
+     */
+    visualRows: VisualRow[];
+    /**
+     * docToVisArr[docLine] = first visual row index for that doc line.
+     * `null` signals the **identity mapping** (visRow === docLine), used by the
+     * large-file fast path when word-wrap is off and there are no folds.
+     * Callers should use `docToVisualPos()` rather than indexing this directly.
+     */
+    docToVisArr: number[] | null;
+    /**
+     * Total estimated visual rows in the document.
+     * Use this for spacer-height calculations instead of `visualRows.length`.
+     */
+    totalVisualRows: number;
+    /**
+     * Absolute visual-row index of `visualRows[0]`.
+     * Always 0 for non-windowed (full) builds.
+     */
+    windowVisStart: number;
+}
+
+export { }