@synclineapi/editor 4.0.3 → 4.0.4

package/dist/types/index.d.ts

@@ -1,3 +1,8 @@
+declare interface BracketMatch {
+    open: CursorPosition;
+    close: CursorPosition;
+}
+
 export declare const BUILT_IN_THEMES: ThemeDefinition[];
 
 /**
@@ -124,6 +129,34 @@ export declare interface CursorPosition {
     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.
@@ -213,6 +246,132 @@ export declare interface EditorAPI {
     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.
@@ -466,6 +625,42 @@ export declare interface EditorConfig {
      * 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
@@ -491,14 +686,14 @@ export declare interface EditorConfig {
      * 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.
+     * Pass an empty object `{ } ` to disable all auto-closing.
      *
      * @example
      * ```ts
      * // Only auto-close parentheses and curly braces
      * autoClosePairs: { '(': ')', '{': '}' }
      * ```
-     * Default: `{ '(': ')', '[': ']', '{': '}', '"': '"', "'": "'", '`': '`' }`.
+     * Default: `{ '(': ')', '[': ']', '{': '}', '"': '"', "'": "'", '`': '`' } `.
      */
     autoClosePairs?: Record<string, string>;
     /**
@@ -598,15 +793,15 @@ export declare interface EditorConfig {
      * // Dracula-inspired keywords + string colours on any base theme
      * editor.updateConfig({
      *   tokenColors: {
-     *     keyword:  '#ff79c6',
-     *     string:   '#f1fa8c',
+     *     keyword: '#ff79c6',
+     *     string: '#f1fa8c',
      *     function: '#50fa7b',
-     *     type:     '#8be9fd',
-     *     comment:  '#6272a4',
+     *     type: '#8be9fd',
+     *     comment: '#6272a4',
      *   }
      * });
      * ```
-     * Default: `{}` (no overrides — all colours come from the active theme).
+     * Default: `{ } ` (no overrides — all colours come from the active theme).
      */
     tokenColors?: TokenColors;
     /**
@@ -674,6 +869,98 @@ export declare interface EditorConfig {
     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.
@@ -725,14 +1012,31 @@ export declare interface FindMatch {
 
 /**
  * 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 {
-    /** Document lines at the time of the snapshot. */
-    doc: string[];
-    /** Cursor position at the time of the snapshot. */
-    cur: CursorPosition;
-    /** Selection at the time of the snapshot, or `null` if none. */
-    sel: Selection_2 | null;
+    /** 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[];
 }
 
 /**
@@ -814,6 +1118,13 @@ export declare interface MinimapColors {
     [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
@@ -831,77 +1142,7 @@ declare interface Selection_2 {
 }
 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 readonly _placeholderEl;
-    private readonly _goToLineBar;
-    private readonly _goToLineInput;
-    private readonly _goToLineHint;
-    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;
-    /** Active snippet tab-stop session. Cleared on click, Escape, or structural edit. */
-    private _snippetSession;
-    /** 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);
+export declare class SynclineEditor extends EditorEvents implements EditorAPI {
     getValue(): string;
     setValue(value: string): void;
     getCursor(): CursorPosition;
@@ -918,101 +1159,6 @@ export declare class SynclineEditor implements EditorAPI {
     redo(): void;
     executeCommand(command: string): void;
     destroy(): void;
-    private _buildFindBar;
-    private _buildGoToLineBar;
-    private _openGoToLine;
-    private _closeGoToLine;
-    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 _duplicateLines;
-    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;
@@ -1049,6 +1195,22 @@ export declare interface ThemeDefinition {
     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
@@ -1166,6 +1328,25 @@ export declare interface ThemeTokens {
     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.
@@ -1259,4 +1440,35 @@ export declare interface VisualRow {
     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 { }

package/package.json

@@ -3,7 +3,7 @@
     "publishConfig": {
         "access": "public"
     },
-    "version": "4.0.3",
+    "version": "4.0.4",
     "description": "A zero-dependency, pixel-perfect, fully customisable browser-based code editor",
     "type": "module",
     "main": "./dist/syncline-editor.umd.js",