@pre-markdown/layout 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,660 @@
+import { PrepareOptions, PreparedText, PreparedTextWithSegments, LayoutResult as LayoutResult$1, LayoutLinesResult } from '@chenglou/pretext';
+export { PreparedText, PreparedTextWithSegments, LayoutLine as PretextLine } from '@chenglou/pretext';
+
+/**
+ * @pre-markdown/layout — Worker-Based Measurement Backend
+ *
+ * Offloads expensive pretext prepare() calls to a Web Worker,
+ * keeping the main thread free for rendering and user interaction.
+ *
+ * The backend transparently proxies prepare()/prepareWithSegments() to the
+ * worker thread and caches results on the main thread.
+ *
+ * Usage:
+ *   const backend = createWorkerBackend()
+ *   const engine = new LayoutEngine(config, backend)
+ *
+ *   // Bulk prepare paragraphs in background (non-blocking)
+ *   await backend.prepareAsync(texts, font)
+ *
+ *   // After prepareAsync, computeLayout() hits cache — synchronous & instant
+ *   engine.computeLayout(text)
+ *
+ *   // Clean up when done
+ *   backend.terminate()
+ */
+
+interface WorkerMeasurementBackend extends MeasurementBackend {
+    /**
+     * Asynchronously prepare multiple text blocks in the Worker thread.
+     * Results are cached so subsequent synchronous prepare() calls are instant.
+     *
+     * Use this for bulk preparation of large documents:
+     *   await backend.prepareAsync(paragraphs, font)
+     *   // Now all paragraphs are cached, computeLayout() is O(1)
+     */
+    prepareAsync(texts: string[], font: string, options?: PrepareOptions): Promise<PreparedText[]>;
+    /**
+     * Asynchronously prepare with segments (for layoutWithLines).
+     */
+    prepareWithSegmentsAsync(texts: string[], font: string, options?: PrepareOptions): Promise<PreparedTextWithSegments[]>;
+    /**
+     * Check if the worker is alive.
+     */
+    readonly isAlive: boolean;
+    /**
+     * Terminate the worker. After this, async methods will reject.
+     * Synchronous methods fall back to main-thread pretext.
+     */
+    terminate(): void;
+}
+/**
+ * Create a Worker-based measurement backend.
+ *
+ * On the main thread:
+ *  - prepare() / prepareWithSegments() — synchronous, uses main-thread pretext (with cache)
+ *  - prepareAsync() / prepareWithSegmentsAsync() — offloads to Worker
+ *  - layout() / layoutWithLines() — always synchronous (pure arithmetic)
+ *
+ * The typical workflow:
+ *  1. Call prepareAsync() for bulk paragraphs → Worker runs prepare() in background
+ *  2. Results are stored in main-thread cache
+ *  3. Subsequent computeLayout() hits cache → no main-thread blocking
+ *
+ * @param workerUrl - Optional custom URL for the worker script.
+ *                    Defaults to auto-resolving the bundled worker.
+ */
+declare function createWorkerBackend(workerUrl?: URL | string): WorkerMeasurementBackend;
+
+/**
+ * @pre-markdown/layout — Virtual List
+ *
+ * Dynamic-height virtual list powered by pretext precise text measurement.
+ * Unlike typical virtual lists that estimate item heights, this uses
+ * pretext's exact layout computation for pixel-perfect scrolling.
+ *
+ * Key features:
+ *  - Zero estimation error: every item height is precisely computed via pretext
+ *  - Incremental updates: only recompute changed items
+ *  - Binary search viewport: O(log n) item lookup
+ *  - Configurable overscan: smooth scrolling with buffer items
+ *  - Resize-aware: automatic relayout on width changes
+ *  - Callback-driven: onViewportChange fires with visible item range
+ */
+
+interface VirtualListConfig {
+    /** The LayoutEngine instance for text measurement */
+    engine: LayoutEngine;
+    /** Viewport height in pixels */
+    viewportHeight: number;
+    /** Number of extra items to render above/below viewport (default: 5) */
+    overscan?: number;
+    /** Gap between items in pixels (default: 0) */
+    itemGap?: number;
+}
+interface VirtualListItem {
+    /** Index in the data array */
+    index: number;
+    /** Y offset from document top (pixels) */
+    offsetTop: number;
+    /** Item height in pixels (pretext-measured) */
+    height: number;
+    /** The text content */
+    text: string;
+}
+interface ViewportRange {
+    /** First visible item index (inclusive) */
+    startIndex: number;
+    /** Last visible item index (exclusive) */
+    endIndex: number;
+    /** Items to render (including overscan) */
+    items: VirtualListItem[];
+    /** Total scroll height of all items */
+    totalHeight: number;
+    /** Offset to position the visible container */
+    offsetY: number;
+}
+type ViewportChangeCallback = (range: ViewportRange) => void;
+declare class VirtualList {
+    private engine;
+    private viewportHeight;
+    private overscan;
+    private itemGap;
+    /** Item texts */
+    private items;
+    /** Cached item heights (pretext-measured) */
+    private heights;
+    /** Cumulative offsets (heights[0..i-1] + gaps) */
+    private offsets;
+    /** Total height of all items */
+    private totalHeight;
+    /** Current scroll position */
+    private scrollTop;
+    /** Viewport change callback */
+    private onViewportChange;
+    constructor(config: VirtualListConfig);
+    /**
+     * Set the full list of items. Computes all heights.
+     * For incremental updates, use updateItems() instead.
+     */
+    setItems(texts: string[]): void;
+    /**
+     * Incrementally update items. Only recomputes heights for changed items.
+     * Much faster than setItems() for editing scenarios.
+     *
+     * @returns Indices of items that changed height
+     */
+    updateItems(texts: string[]): number[];
+    /**
+     * Get the height of a specific item.
+     */
+    getItemHeight(index: number): number;
+    /**
+     * Get the offset of a specific item from the top.
+     */
+    getItemOffset(index: number): number;
+    /**
+     * Set the scroll position and compute the visible range.
+     * Fires the onViewportChange callback if registered.
+     */
+    setScrollTop(scrollTop: number): ViewportRange;
+    /**
+     * Get the current scroll position.
+     */
+    getScrollTop(): number;
+    /**
+     * Update viewport height (e.g., on window resize).
+     */
+    setViewportHeight(height: number): void;
+    /**
+     * Scroll to make a specific item visible.
+     * @param index - Item index to scroll to
+     * @param align - 'start' | 'center' | 'end' (default: 'start')
+     */
+    scrollToItem(index: number, align?: 'start' | 'center' | 'end'): ViewportRange;
+    /**
+     * Register a callback for viewport changes.
+     */
+    onViewport(callback: ViewportChangeCallback | null): void;
+    /**
+     * Compute the current visible range.
+     */
+    computeViewport(): ViewportRange;
+    /**
+     * Find which item is at a given Y position.
+     * @returns Item index, or -1 if out of bounds
+     */
+    hitTest(y: number): number;
+    /**
+     * Find the item and local Y offset within it.
+     */
+    hitTestDetailed(y: number): {
+        index: number;
+        localY: number;
+    } | null;
+    /**
+     * Recompute all item heights (e.g., after maxWidth change).
+     * Call this after engine.updateConfig({ maxWidth: newWidth }).
+     *
+     * @returns Time taken in milliseconds
+     */
+    relayout(): number;
+    /** Total height of all items */
+    getTotalHeight(): number;
+    /** Number of items */
+    getItemCount(): number;
+    /** Get all item heights (readonly) */
+    getHeights(): readonly number[];
+    /** Get all item offsets (readonly) */
+    getOffsets(): readonly number[];
+    /**
+     * Binary search for the item at a given Y offset.
+     * Returns the index of the item that contains the offset.
+     */
+    private binarySearchOffset;
+}
+
+/**
+ * @pre-markdown/layout — Cursor & Selection Engine
+ *
+ * Provides pixel-perfect cursor positioning and selection highlighting
+ * powered by pretext's zero-DOM-reflow text measurement.
+ *
+ * Key capabilities:
+ *  - offsetToXY: text offset → (x, y) pixel coordinates (via pretext layout)
+ *  - xyToOffset: (x, y) click → text offset (reverse hit-test)
+ *  - getSelectionRects: start/end offset → array of highlight rectangles
+ *  - getLineInfo: get line boundaries, count, and visual line mapping
+ *
+ * All calculations are pure arithmetic after initial prepare() —
+ * zero DOM reads, zero reflow.
+ */
+
+/** A 2D point in pixel coordinates */
+interface Point {
+    x: number;
+    y: number;
+}
+/** A rectangle in pixel coordinates */
+interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Cursor position information */
+interface CursorPosition {
+    /** Text offset in the source string */
+    offset: number;
+    /** Visual line index (0-based, accounts for wrapping) */
+    visualLine: number;
+    /** X coordinate in pixels from left edge */
+    x: number;
+    /** Y coordinate in pixels from top */
+    y: number;
+    /** Line height in pixels */
+    lineHeight: number;
+}
+/** Information about a visual line (may be a wrapped sub-line) */
+interface VisualLineInfo {
+    /** Visual line index (0-based) */
+    index: number;
+    /** Text content of this visual line */
+    text: string;
+    /** Measured width in pixels */
+    width: number;
+    /** Y offset from document top */
+    y: number;
+    /** The source (hard) line index (0-based) */
+    sourceLine: number;
+    /** Start offset in the original text */
+    startOffset: number;
+    /** End offset in the original text (exclusive) */
+    endOffset: number;
+}
+/** Line number mapping for display */
+interface LineNumberInfo {
+    /** Source line number (1-based, for display) */
+    lineNumber: number;
+    /** Y position of this source line's first visual line */
+    y: number;
+    /** Number of visual lines this source line spans */
+    visualLineCount: number;
+    /** Height of all visual lines for this source line */
+    height: number;
+}
+/**
+ * Cursor and selection engine powered by pretext.
+ *
+ * Usage:
+ *   const cursor = new CursorEngine(layoutEngine)
+ *   cursor.setText(editorContent)
+ *
+ *   // Click → offset
+ *   const offset = cursor.xyToOffset(clickX, clickY)
+ *
+ *   // Offset → position
+ *   const pos = cursor.offsetToPosition(offset)
+ *
+ *   // Selection rectangles
+ *   const rects = cursor.getSelectionRects(selStart, selEnd)
+ */
+declare class CursorEngine {
+    private engine;
+    private text;
+    private hardLines;
+    private visualLines;
+    private lineNumbers;
+    private totalHeight;
+    constructor(engine: LayoutEngine);
+    /**
+     * Set the text content and compute all visual line info.
+     * Call this when the editor content changes.
+     */
+    setText(text: string): void;
+    /** Get current text */
+    getText(): string;
+    /**
+     * Force recomputation of layout (e.g., after width change).
+     * Call after engine.updateConfig({ maxWidth: newWidth }).
+     */
+    recompute(): void;
+    /**
+     * Convert a text offset to pixel coordinates.
+     * Returns the cursor position (x, y) for rendering a blinking cursor.
+     */
+    offsetToPosition(offset: number): CursorPosition;
+    /**
+     * Convert pixel coordinates (from a click event) to a text offset.
+     * This is the reverse of offsetToPosition().
+     */
+    xyToOffset(x: number, y: number): number;
+    /**
+     * Compute selection highlight rectangles for a text range.
+     * Returns one rect per visual line that intersects the selection.
+     */
+    getSelectionRects(start: number, end: number): Rect[];
+    /** Get all visual lines */
+    getVisualLines(): readonly VisualLineInfo[];
+    /** Get visual line count (total lines including wrapped) */
+    getVisualLineCount(): number;
+    /** Get source line count (hard lines from \n) */
+    getSourceLineCount(): number;
+    /**
+     * Get line number info for rendering line numbers.
+     * Each entry represents a source line with its Y position
+     * and how many visual lines it spans (for proper alignment).
+     */
+    getLineNumbers(): readonly LineNumberInfo[];
+    /** Get total content height in pixels */
+    getTotalHeight(): number;
+    /**
+     * Get the source line number for a given text offset.
+     * Returns 1-based line number.
+     */
+    getLineNumberAtOffset(offset: number): number;
+    /**
+     * Get the visual line at a given Y coordinate.
+     */
+    getVisualLineAtY(y: number): VisualLineInfo | null;
+    /**
+     * Get all visual lines for a given source line.
+     */
+    getVisualLinesForSourceLine(sourceLine: number): VisualLineInfo[];
+    /**
+     * Find word boundaries at a given offset.
+     * Returns [start, end] offsets of the word.
+     */
+    getWordBoundary(offset: number): [number, number];
+    /**
+     * Find the visual line containing a given text offset.
+     * Uses binary search for O(log n) performance.
+     */
+    private findVisualLineByOffset;
+}
+
+/**
+ * @pre-markdown/layout — Line Renderer
+ *
+ * Provides pretext-based line number rendering and soft-wrap computation.
+ * Replaces naive "one div per line" approach with accurate visual line mapping
+ * that correctly handles soft-wrapped (long) lines.
+ *
+ * Key features:
+ *  - Accurate line number positioning that aligns with soft-wrapped text
+ *  - Incremental updates: only recompute changed lines
+ *  - Active line tracking (current cursor line highlight)
+ *  - Virtual rendering for large documents (only render visible line numbers)
+ *  - Pure pretext computation — zero DOM measurement needed
+ */
+
+/** Configuration for the line renderer */
+interface LineRendererConfig {
+    /** The CursorEngine instance (provides visual line mapping) */
+    cursor: CursorEngine;
+    /** Container element for line numbers */
+    container: HTMLElement;
+    /** Line height in pixels (must match editor) */
+    lineHeight: number;
+    /** Class name for active line highlight */
+    activeClass?: string;
+    /** Whether to use virtual rendering (default: true for > 1000 lines) */
+    virtual?: boolean;
+    /** Extra lines to render above/below viewport in virtual mode */
+    overscan?: number;
+}
+/** A rendered line number entry */
+interface RenderedLineNumber {
+    /** Source line number (1-based) */
+    lineNumber: number;
+    /** Y position in pixels */
+    y: number;
+    /** Height spanning all visual lines of this source line */
+    height: number;
+    /** Whether this is the active (cursor) line */
+    isActive: boolean;
+}
+/**
+ * Renders line numbers with correct alignment for soft-wrapped text.
+ * Uses pretext layout data from CursorEngine for pixel-perfect positioning.
+ */
+declare class LineRenderer {
+    private cursor;
+    private container;
+    private lineHeight;
+    private activeClass;
+    private virtual;
+    private overscan;
+    private activeLine;
+    private lastScrollTop;
+    private lastViewportHeight;
+    private renderedRange;
+    private pool;
+    constructor(config: LineRendererConfig);
+    /**
+     * Set the active (cursor) line. Highlighted in the gutter.
+     * @param lineNumber - 1-based source line number
+     */
+    setActiveLine(lineNumber: number): void;
+    /** Get the current active line number (1-based) */
+    getActiveLine(): number;
+    /**
+     * Full render: rebuild all line numbers.
+     * Use for initial render or after text content changes.
+     */
+    render(): void;
+    /**
+     * Render all line numbers (non-virtual mode).
+     * Uses absolutely-positioned divs for correct alignment with soft-wrapped text.
+     */
+    private renderAll;
+    /**
+     * Virtual rendering: only render line numbers visible in the viewport.
+     * Uses absolute positioning with a spacer for correct scroll height.
+     */
+    renderVirtual(): void;
+    /**
+     * Update scroll position for virtual rendering.
+     * Call from the editor's scroll event handler.
+     */
+    updateScroll(scrollTop: number, viewportHeight: number): void;
+    /**
+     * Update after text changes. Re-renders line numbers.
+     */
+    update(): void;
+    /**
+     * Get the number of visual lines for each source line.
+     * Useful for understanding how text wraps without DOM measurement.
+     *
+     * @returns Array where index = source line (0-based), value = visual line count
+     */
+    getWrapInfo(): number[];
+    /**
+     * Check if a source line is soft-wrapped (spans multiple visual lines).
+     */
+    isLineWrapped(sourceLine: number): boolean;
+    /**
+     * Get total visual line count (including wrapped lines).
+     */
+    getTotalVisualLines(): number;
+    /**
+     * Dispose resources.
+     */
+    dispose(): void;
+    private getPooledDiv;
+}
+
+/**
+ * @pre-markdown/layout
+ *
+ * Pretext-based text layout engine.
+ * Handles text measurement, line breaking, and virtual viewport layout.
+ *
+ * Uses @chenglou/pretext for zero-DOM-reflow text measurement:
+ *   prepare()  → one-time text analysis (cached)
+ *   layout()   → pure-arithmetic line breaking (hot path)
+ */
+
+interface LayoutConfig {
+    /** CSS font string (e.g., '16px Inter'). Must be loaded before use. */
+    font: string;
+    /** Line height in pixels (must match CSS line-height) */
+    lineHeight: number;
+    /** Maximum width for text wrapping (pixels) */
+    maxWidth: number;
+    /** White-space mode: 'normal' (default) or 'pre-wrap' */
+    whiteSpace?: 'normal' | 'pre-wrap';
+    /** Viewport buffer multiplier (default 2 = 2x viewport above & below) */
+    viewportBuffer?: number;
+    /** Font for code blocks / inline code (defaults to main font) */
+    codeFont?: string;
+    /** Line height for code blocks (defaults to main lineHeight) */
+    codeLineHeight?: number;
+}
+interface LayoutLine {
+    /** Line text content */
+    text: string;
+    /** Measured width in pixels */
+    width: number;
+    /** Y position from top */
+    y: number;
+    /** Source line index (in document paragraphs) */
+    sourceIndex: number;
+}
+interface LayoutResult {
+    /** Total height of all lines */
+    height: number;
+    /** Total number of visual lines */
+    lineCount: number;
+    /** Individual line layouts (only populated when requested) */
+    lines?: LayoutLine[];
+}
+interface ViewportLayoutResult {
+    /** Lines visible in the viewport */
+    visibleLines: LayoutLine[];
+    /** Total height of the entire document */
+    totalHeight: number;
+    /** Y offset of the first visible line */
+    startY: number;
+    /** Index of first visible line */
+    startIndex: number;
+    /** Index of last visible line (exclusive) */
+    endIndex: number;
+}
+interface MeasurementBackend {
+    /** One-time text analysis (expensive, cache result) */
+    prepare(text: string, font: string, options?: PrepareOptions): PreparedText;
+    /** One-time text analysis with segment info */
+    prepareWithSegments(text: string, font: string, options?: PrepareOptions): PreparedTextWithSegments;
+    /** Pure-arithmetic layout (cheap, can call per frame) */
+    layout(prepared: PreparedText, maxWidth: number, lineHeight: number): LayoutResult$1;
+    /** Layout with per-line info */
+    layoutWithLines(prepared: PreparedTextWithSegments, maxWidth: number, lineHeight: number): LayoutLinesResult;
+    /** Clear internal caches */
+    clearCache(): void;
+    /** Set locale for text segmentation */
+    setLocale(locale?: string): void;
+}
+/**
+ * Fallback backend for environments without Canvas (e.g. Node.js tests).
+ * Uses character-count heuristic for approximate measurement.
+ */
+declare function createFallbackBackend(avgCharWidth?: number): MeasurementBackend;
+/**
+ * High-performance text layout engine powered by @chenglou/pretext.
+ *
+ * Two-phase pipeline:
+ *   1. prepare() — one-time text analysis (~1-5ms per paragraph, cached via LRU)
+ *   2. layout()  — pure arithmetic (~0.0002ms, safe for animation frames)
+ *
+ * In environments without Canvas (Node.js), set a fallback backend
+ * via the constructor or `setBackend()`.
+ */
+declare class LayoutEngine {
+    private config;
+    private backend;
+    private preparedCache;
+    private preparedSegCache;
+    constructor(config: LayoutConfig, backend?: MeasurementBackend);
+    /** Update layout configuration. Invalidates cache if font changes. */
+    updateConfig(config: Partial<LayoutConfig>): void;
+    /** Get current configuration (readonly). */
+    getConfig(): Readonly<LayoutConfig>;
+    /** Replace the measurement backend (e.g. for testing). */
+    setBackend(backend: MeasurementBackend): void;
+    /** Set locale for text segmentation. */
+    setLocale(locale?: string): void;
+    /**
+     * Compute height and line count for a text block.
+     * Uses pretext prepare() + layout() pipeline.
+     * The PreparedText is cached by (text, font) key.
+     */
+    computeLayout(text: string): LayoutResult;
+    /**
+     * Compute layout for code blocks using code font.
+     * Falls back to main font if codeFont is not configured.
+     */
+    computeCodeLayout(text: string): LayoutResult;
+    /**
+     * Compute layout with individual line information.
+     * Uses prepareWithSegments() + layoutWithLines().
+     */
+    computeLayoutWithLines(text: string): LayoutResult;
+    /**
+     * Compute layout for only the visible viewport.
+     * Key performance optimization: only measure and position visible lines.
+     * Includes configurable buffer (default 2x viewport) for smooth scrolling.
+     */
+    computeViewportLayout(text: string, scrollTop: number, viewportHeight: number): ViewportLayoutResult;
+    /**
+     * Compute layout for an array of text blocks (paragraphs).
+     * Returns cumulative heights for virtual scrolling.
+     */
+    computeDocumentLayout(paragraphs: string[]): {
+        totalHeight: number;
+        paragraphOffsets: number[];
+        paragraphHeights: number[];
+    };
+    /**
+     * Find which paragraph and line is at a given scrollTop position.
+     */
+    hitTest(paragraphs: string[], scrollTop: number): {
+        paragraphIndex: number;
+        lineIndex: number;
+    } | null;
+    private _lastParagraphs;
+    private _lastHeights;
+    private _lastTotalHeight;
+    /**
+     * Incremental document layout — reuses cached heights for unchanged paragraphs.
+     * Only recomputes layout for paragraphs that changed since the last call.
+     * Use this for real-time editing instead of computeDocumentLayout().
+     *
+     * Returns the same structure as computeDocumentLayout().
+     */
+    updateDocumentLayout(paragraphs: string[]): {
+        totalHeight: number;
+        paragraphOffsets: number[];
+        paragraphHeights: number[];
+        changedIndices: number[];
+    };
+    /**
+     * Get the cached total height from the last updateDocumentLayout() call.
+     * O(1) — no recomputation.
+     */
+    getCachedTotalHeight(): number;
+    /** Invalidate cache for a specific text block. */
+    invalidateCache(text?: string): void;
+    /** Clear all caches including pretext internal cache. */
+    clearAllCaches(): void;
+    /** Get current cache statistics. */
+    getCacheStats(): {
+        preparedSize: number;
+        segmentSize: number;
+    };
+    private cacheKey;
+    private getPrepared;
+    private getPreparedWithSegments;
+}
+
+export { CursorEngine, type CursorPosition, type LayoutConfig, LayoutEngine, type LayoutLine, type LayoutResult, type LineNumberInfo, LineRenderer, type LineRendererConfig, type MeasurementBackend, type Point, type Rect, type RenderedLineNumber, type ViewportChangeCallback, type ViewportLayoutResult, type ViewportRange, VirtualList, type VirtualListConfig, type VirtualListItem, type VisualLineInfo, type WorkerMeasurementBackend, createFallbackBackend, createWorkerBackend };