@synclineapi/editor 2.0.0

package/dist/types/index.d.ts

@@ -0,0 +1,1183 @@
+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';
+
+/** Convenience type alias for the `createEditor` function signature. */
+export declare type CreateEditor = typeof createEditor;
+
+/**
+ * Create and mount a `SynclineEditor` inside `container`.
+ *
+ * This is the recommended entry point — it returns the narrower `EditorAPI`
+ * type, which hides the internal class members and exposes only the public
+ * interface. Use `new SynclineEditor(...)` directly if you need access to the
+ * concrete class type (e.g., for `instanceof` checks).
+ *
+ * Config values are validated and clamped to sensible bounds automatically —
+ * you never need to guard against negative font sizes or extreme tab widths.
+ *
+ * @param container - The `HTMLElement` that will host the editor.
+ * @param config    - Initial configuration. All properties are optional.
+ * @returns         An `EditorAPI` instance ready to use.
+ *
+ * @example
+ * ```ts
+ * import { createEditor } from 'syncline-editor';
+ *
+ * const editor = createEditor(document.getElementById('app')!, {
+ *   value:    'console.log("Hello, world!")',
+ *   language: 'typescript',
+ *   theme:    'dracula',
+ *   onChange: (value) => console.log('changed:', value.length, 'chars'),
+ * });
+ *
+ * // Later — update config without remounting
+ * editor.updateConfig({ theme: 'github-light', fontSize: 15 });
+ *
+ * // Clean up when done
+ * editor.destroy();
+ * ```
+ */
+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;
+}
+
+/**
+ * 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;
+}
+
+/** ─── 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;
+    /**
+     * 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;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Context passed to a `provideHover` callback.
+ * Describes the word under the pointer and the surrounding document state.
+ */
+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.
+ */
+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;
+}
+
+/**
+ * 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 implements EditorAPI {
+    private readonly _host;
+    private readonly _shadow;
+    private readonly _editorEl;
+    private readonly _spacerEl;
+    private readonly _vpEl;
+    private readonly _inputEl;
+    private readonly _minimapWrap;
+    private readonly _mmCanvas;
+    private readonly _mmSlider;
+    private readonly _statusBar;
+    private readonly _findBar;
+    private readonly _findInput;
+    private readonly _replaceInput;
+    private readonly _findCount;
+    private readonly _replaceRow;
+    private readonly _acPopup;
+    private readonly _emmetTip;
+    private readonly _snippetTip;
+    private readonly _hoverTip;
+    private readonly _themeOverlay;
+    private readonly _themePanel;
+    private _config;
+    private _tab;
+    private _wm;
+    private _foldedLines;
+    private _tokenCache;
+    private _themeManager;
+    private _findMatches;
+    private _findIdx;
+    private _findCaseSensitive;
+    private _findRegex;
+    private _wordHighlights;
+    private _bracketMatch;
+    private _acItems;
+    private _acSel;
+    private _acPrefix;
+    private _acStartCol;
+    private _emmetAcStartCol;
+    private _mc;
+    private _extraCursors;
+    private _isDragging;
+    private _dragAnchor;
+    private _hoverTimer;
+    private _hoverPinned;
+    private _mmDragMode;
+    private _mmDragStartY;
+    private _mmDragStartScroll;
+    private _mmSliderOffset;
+    private _mmColors;
+    private _lastInputTime;
+    private _dynamicStyleEl;
+    private _emmetExpanded;
+    private _snippetExpanded;
+    /** Pending debounce timer ID for autocomplete re-computation. */
+    private _acDebounceTimer;
+    /** Pending requestAnimationFrame ID for coalesced renders. */
+    private _rafId;
+    private readonly _onWinMouseUp;
+    private readonly _onWinResize;
+    private readonly _onEditorScroll;
+    private readonly _onWinMmMouseMove;
+    private readonly _onWinMmMouseUp;
+    private _ro;
+    constructor(container: HTMLElement, config?: EditorConfig);
+    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;
+    private _buildFindBar;
+    private _buildStatusBar;
+    private _applyDynamicStyles;
+    /**
+     * Apply tokenColors overrides as inline styles on the host element.
+     * Must be called AFTER the theme has applied its own inline styles so
+     * our values win (last writer wins for element.style.setProperty).
+     * When a token field is empty/absent, restore the active theme's value.
+     */
+    private _applyTokenOverrides;
+    /**
+     * Schedule a render on the next animation frame.
+     * Multiple calls within a single frame are coalesced into one render —
+     * ideal for scroll and resize handlers which can fire at 60+ Hz.
+     */
+    private _scheduleRender;
+    private _render;
+    private readonly _onFoldBtnClick;
+    private _updateStatusBar;
+    private _updateMinimap;
+    private _rebuildWrapMap;
+    private _scrollIntoView;
+    private _focusInput;
+    private _insertStr;
+    private _doBackspace;
+    private _doEnter;
+    private _doDelete;
+    private _selectAll;
+    private _doCopy;
+    private _doCut;
+    private _toggleComment;
+    private _duplicateLine;
+    private _deleteLine;
+    private _indentSel;
+    private _unindentSel;
+    private _toggleWrap;
+    private _getSelRows;
+    private _posFromMouse;
+    private _openFind;
+    private _closeFind;
+    private _runFind;
+    private _navFind;
+    private _acVisible;
+    private _acHide;
+    /**
+     * Schedule an autocomplete refresh after a brief debounce pause.
+     * Prevents the suggestion engine running on every single keystroke —
+     * only fires when the user pauses for `AC_DEBOUNCE_MS` milliseconds.
+     * Call `_acTriggerNow()` directly when an immediate refresh is required
+     * (e.g., on explicit Ctrl+Space or arrow-key navigation).
+     */
+    private _acTrigger;
+    /** Run an autocomplete refresh immediately (no debounce). */
+    private _acTriggerNow;
+    private _renderAcPopup;
+    private _posAcPopup;
+    private _acAccept;
+    private _emmetCheck;
+    private _emmetAccept;
+    /** Returns built-in snippets for the current language merged with user completions.
+     *  When `replaceBuiltins` is true the language built-ins are suppressed so only
+     *  the caller-supplied completions (e.g. MDX_SNIPPETS) are active. */
+    private _allCompletions;
+    private _snippetCheck;
+    private _snippetAccept;
+    /**
+     * Expand a snippet/emmet body template at the current cursor position.
+     * `triggerStart` is the column where the trigger word begins.
+     * `cur.col` must be at the end of the trigger (emmet) or at `triggerStart`
+     * when the prefix was already stripped (snippet accepted from popup).
+     * Everything between `triggerStart` and `cur.col` is replaced by `body`.
+     */
+    private _expandBodyAt;
+    private _openThemePicker;
+    private _bindEditorEvents;
+    private _onKeyDown;
+    private _handleArrowKeys;
+    private _isWordChar;
+    private _wordSkipRight;
+    private _wordSkipLeft;
+    private _moveLines;
+    private _scheduleHover;
+    private _doHover;
+    private _showHoverTip;
+    private _hideHover;
+    private _onInput;
+    private _ctrlD;
+    private _bindFindEvents;
+    private _doReplaceOne;
+    private _doReplaceAll;
+    private _bindMinimapEvents;
+}
+
+export declare const THEME_DRACULA: ThemeDefinition;
+
+export declare const THEME_GITHUB_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;
+}
+
+/** ─── 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;
+}
+
+/**
+ * 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;
+}
+
+export { }