superdoc 2.2.1 → 2.3.0

package/dist/layout-engine/layout-bridge/src/cache-warmer.d.ts

@@ -0,0 +1,73 @@
+import { FontMetricsCache } from './font-metrics-cache.js';
+import { ParagraphLineCache } from './paragraph-line-cache.js';
+/**
+ * Configuration for cache warming.
+ */
+export interface WarmingConfig {
+    /** Font keys to pre-warm */
+    fonts: string[];
+    /** Page indices currently in viewport */
+    viewportPages: number[];
+    /** Whether to prefetch adjacent pages */
+    prefetchAdjacent: boolean;
+}
+/**
+ * Information about a paragraph for cache warming.
+ */
+export interface ParagraphWarmInfo {
+    /** Paragraph block index */
+    index: number;
+    /** Paragraph text content */
+    text: string;
+    /** Font key for this paragraph */
+    fontKey: string;
+    /** Maximum width for line breaking */
+    maxWidth: number;
+}
+/**
+ * CacheWarmer proactively populates caches to improve performance.
+ */
+export declare class CacheWarmer {
+    private fontMetricsCache;
+    private paragraphLineCache;
+    private warmingProgress;
+    constructor(fontMetricsCache: FontMetricsCache, paragraphLineCache: ParagraphLineCache);
+    /**
+     * Warm caches on document load.
+     *
+     * @param config - Warming configuration
+     */
+    warmOnLoad(config: WarmingConfig): Promise<void>;
+    /**
+     * Warm caches for adjacent pages as user scrolls.
+     *
+     * @param currentPage - Current page index
+     */
+    warmForScroll(_currentPage: number): void;
+    /**
+     * Pre-calculate line breaks for visible paragraphs.
+     *
+     * @param paragraphs - Array of paragraphs to warm
+     */
+    precalculateLines(paragraphs: ParagraphWarmInfo[]): void;
+    /**
+     * Get warming progress for UI feedback.
+     *
+     * @returns Progress statistics
+     */
+    getProgress(): {
+        fontsCached: number;
+        paragraphsCached: number;
+        total: number;
+    };
+    /**
+     * Reset warming progress counters.
+     */
+    resetProgress(): void;
+    /**
+     * Estimate completion percentage.
+     *
+     * @returns Completion percentage (0-100)
+     */
+    getCompletionPercentage(): number;
+}

package/dist/layout-engine/layout-bridge/src/cache.d.ts

@@ -0,0 +1,143 @@
+import { FlowBlock } from '../../contracts/src/index.js';
+/**
+ * Generates a cache key hash from a block's content, incorporating text,
+ * formatting, and embedded block data.
+ *
+ * Text content is preserved verbatim without whitespace normalization. Different
+ * whitespace (multiple spaces, tabs, leading/trailing spaces) produces different
+ * text measurements and must generate distinct cache keys to prevent incorrect
+ * cache hits. See PR #1551 for context on the whitespace normalization bug.
+ *
+ * For image runs, includes the image source (first 50 chars) and dimensions to ensure
+ * cache invalidation when image properties change. This is critical for converted
+ * metafiles (WMF/EMF) where placeholder images may have different dimensions than
+ * the original, preventing stale cached measurements from being served.
+ *
+ * @param block - The flow block to generate a hash for
+ * @returns A string hash representing the block's run content and formatting
+ */
+/**
+ * Content identity used by the measure cache's key (P8.4: also the adoption
+ * key for previous-pass measures when block ids churn). Measures are a pure
+ * function of (content, constraints, font signature); this hash IS the
+ * content component of that key, so adopting a previous measure on hash
+ * equality is exactly as sound as a cache hit.
+ */
+export declare const hashMeasureContent: (block: FlowBlock) => string;
+/**
+ * Cache statistics with LRU eviction tracking
+ */
+export type MeasureCacheStats = {
+    hits: number;
+    misses: number;
+    sets: number;
+    invalidations: number;
+    clears: number;
+    /**
+     * Number of entries evicted due to LRU policy
+     */
+    evictions: number;
+    /**
+     * Current cache size (number of entries)
+     */
+    size: number;
+    /**
+     * Estimated memory usage (bytes)
+     */
+    memorySizeEstimate: number;
+};
+/**
+ * LRU-enhanced MeasureCache
+ *
+ * Key improvements:
+ * 1. Bounded size: max 10,000 entries
+ * 2. LRU eviction: Evicts least recently used when full
+ * 3. O(1) access and eviction using Map insertion order
+ * 4. Memory usage estimation
+ * 5. Eviction statistics
+ *
+ * Performance characteristics:
+ * - get(): O(1) - Map lookup + delete + re-insert for LRU tracking
+ * - set(): O(1) - eviction (delete first key) + insert
+ * - invalidate(): O(n) - where n = number of keys matching blockId prefix
+ * - Memory: Bounded at 10K entries ~= 50-100MB
+ */
+export declare class MeasureCache<T> {
+    private cache;
+    private stats;
+    /**
+     * Retrieve a cached measure for the given block and dimensions.
+     * Returns undefined if the block is null/undefined, lacks an ID, or if no cached value exists.
+     *
+     * @param block - The flow block to look up (may be null/undefined)
+     * @param width - The width dimension for cache key
+     * @param height - The height dimension for cache key
+     * @returns The cached value or undefined
+     */
+    get(block: FlowBlock | null | undefined, width: number, height: number, fontSignature?: string): T | undefined;
+    /**
+     * Store a measure in the cache for the given block and dimensions.
+     * Silently returns if the block is null/undefined or lacks an ID.
+     *
+     * @param block - The flow block to cache (may be null/undefined)
+     * @param width - The width dimension for cache key
+     * @param height - The height dimension for cache key
+     * @param value - The value to cache
+     */
+    set(block: FlowBlock | null | undefined, width: number, height: number, value: T, fontSignature?: string): void;
+    /**
+     * Invalidates cached measurements for specific block IDs.
+     * Removes all cache entries whose keys start with any of the provided block IDs.
+     *
+     * @param blockIds - Array of block IDs to invalidate from the cache
+     *
+     * @example
+     * ```typescript
+     * cache.invalidate(['block-123', 'block-456']);
+     * ```
+     */
+    invalidate(blockIds: string[]): void;
+    /**
+     * Clears all cached measurements and resets statistics.
+     * Use when performing a full document re-layout.
+     */
+    clear(): void;
+    /**
+     * Resets cache statistics (hits, misses, sets) to zero.
+     * Does not clear cached values.
+     */
+    resetStats(): void;
+    /**
+     * Returns current cache performance statistics.
+     * Useful for monitoring cache effectiveness.
+     *
+     * @returns Object containing hits, misses, sets, and hit rate
+     */
+    getStats(): MeasureCacheStats;
+    /**
+     * Get current cache size (number of entries)
+     */
+    getSize(): number;
+    /**
+     * Get maximum cache size
+     */
+    getMaxSize(): number;
+    /**
+     * Check if cache is near capacity
+     */
+    isNearCapacity(threshold?: number): boolean;
+    /**
+     * Update size statistics
+     */
+    private updateSizeStats;
+    /**
+     * Composes a cache key from block properties and dimensions.
+     * Validates and clamps dimensions to prevent memory exhaustion.
+     *
+     * @param block - The flow block to create a key for
+     * @param width - Width dimension (will be clamped to [0, MAX_DIMENSION])
+     * @param height - Height dimension (will be clamped to [0, MAX_DIMENSION])
+     * @returns Cache key string
+     */
+    private composeKey;
+}

package/dist/layout-engine/layout-bridge/src/cacheInvalidation.d.ts

@@ -0,0 +1,117 @@
+import { FlowBlock, SectionMetadata } from '../../contracts/src/index.js';
+import { HeaderFooterConstraints } from '../../layout-engine/src/index.js';
+import { MeasureCache } from './cache.js';
+import { HeaderFooterLayoutCache } from './layoutHeaderFooter.js';
+/**
+ * Computes a hash for header/footer block content.
+ * Used to detect when header/footer content has changed.
+ *
+ * @param blocks - Header/footer blocks
+ * @returns Content hash string
+ */
+export declare function computeHeaderFooterContentHash(blocks: FlowBlock[]): string;
+/**
+ * Computes a hash for section metadata.
+ * Used to detect when section numbering or properties have changed.
+ *
+ * @param sections - Section metadata array
+ * @returns Metadata hash string
+ */
+export declare function computeSectionMetadataHash(sections: SectionMetadata[]): string;
+/**
+ * Computes a hash for header/footer constraints.
+ * Used to detect when layout constraints have changed.
+ *
+ * @param constraints - Header/footer constraints
+ * @returns Constraints hash string
+ */
+export declare function computeConstraintsHash(constraints: HeaderFooterConstraints): string;
+/**
+ * Cache state tracker for header/footer layouts.
+ * Stores hashes of content, constraints, and metadata to detect changes.
+ */
+export declare class HeaderFooterCacheState {
+    private contentHashes;
+    private constraintsHash;
+    private sectionMetadataHash;
+    /**
+     * Checks if header/footer content has changed for a variant.
+     *
+     * @param variantKey - Unique key for the variant (e.g., 'header-default')
+     * @param blocks - Current blocks for the variant
+     * @returns True if content has changed
+     */
+    hasContentChanged(variantKey: string, blocks: FlowBlock[]): boolean;
+    /**
+     * Checks if constraints have changed.
+     *
+     * @param constraints - Current constraints
+     * @returns True if constraints have changed
+     */
+    hasConstraintsChanged(constraints: HeaderFooterConstraints): boolean;
+    /**
+     * Checks if section metadata has changed.
+     *
+     * @param sections - Current section metadata
+     * @returns True if metadata has changed
+     */
+    hasSectionMetadataChanged(sections: SectionMetadata[]): boolean;
+    /**
+     * Resets all cached state.
+     * Called when performing a full cache clear.
+     */
+    reset(): void;
+}
+/**
+ * Invalidates header/footer cache based on change detection.
+ *
+ * This function checks what has changed (content, constraints, metadata) and
+ * invalidates the appropriate cache entries. It uses the cache state tracker
+ * to detect changes between layout runs.
+ *
+ * @param cache - Header/footer layout cache
+ * @param cacheState - Cache state tracker
+ * @param headerBlocks - Current header blocks (optional)
+ * @param footerBlocks - Current footer blocks (optional)
+ * @param constraints - Current constraints
+ * @param sections - Current section metadata
+ *
+ * @example
+ * ```typescript
+ * invalidateHeaderFooterCache(
+ *   cache,
+ *   cacheState,
+ *   headerBlocks,
+ *   footerBlocks,
+ *   constraints,
+ *   sections
+ * );
+ * ```
+ */
+export declare function invalidateHeaderFooterCache(cache: HeaderFooterLayoutCache, cacheState: HeaderFooterCacheState, headerBlocks?: {
+    default?: FlowBlock[];
+    first?: FlowBlock[];
+    even?: FlowBlock[];
+    odd?: FlowBlock[];
+}, footerBlocks?: {
+    default?: FlowBlock[];
+    first?: FlowBlock[];
+    even?: FlowBlock[];
+    odd?: FlowBlock[];
+}, constraints?: HeaderFooterConstraints, sections?: SectionMetadata[]): void;
+/**
+ * Invalidates body measure cache for blocks affected by token resolution.
+ *
+ * This should be called after page token resolution to ensure re-measurement
+ * of blocks with resolved tokens.
+ *
+ * @param cache - Body measure cache
+ * @param affectedBlockIds - Set of block IDs affected by token resolution
+ *
+ * @example
+ * ```typescript
+ * const result = resolvePageNumberTokens(layout, blocks, measures, numberingCtx);
+ * invalidateBodyMeasureCache(measureCache, result.affectedBlockIds);
+ * ```
+ */
+export declare function invalidateBodyMeasureCache<T>(cache: MeasureCache<T>, affectedBlockIds: Set<string>): void;

package/dist/layout-engine/layout-bridge/src/cursor-renderer.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Cursor Renderer
+ *
+ * Renders cursor and selection overlays as positioned div elements.
+ * Provides smooth cursor blinking and instant updates without DOM measurements.
+ *
+ * @module cursor-renderer
+ */
+/**
+ * Cursor position rectangle for rendering.
+ */
+export interface CursorRect {
+    /** Page index where cursor is located */
+    pageIndex: number;
+    /** X position within the page */
+    x: number;
+    /** Y position within the page */
+    y: number;
+    /** Height of the cursor line */
+    height: number;
+    /**
+     * Width of the selection rectangle.
+     *
+     * **Semantics:**
+     * - When undefined: Represents a collapsed cursor (zero-width selection). Rendered as a thin
+     *   vertical line at the cursor position. Typically uses the configured cursorWidth (default 2px).
+     * - When defined: Represents a selection span (from !== to). Width indicates the horizontal
+     *   extent of selected text or content.
+     *
+     * **Use Cases:**
+     * - Cursor rendering: width should be undefined or omitted
+     * - Selection highlighting: width should be the measured pixel width of the selected text/content
+     * - Collapsed selections: Some renderers treat width=0 as equivalent to undefined
+     *
+     * **Rendering Behavior:**
+     * The CursorRenderer uses this field to distinguish between cursor (thin line) and selection
+     * (filled rectangle). When width is undefined, it falls back to cursorWidth for rendering.
+     */
+    width?: number;
+}
+/**
+ * Configuration options for cursor rendering.
+ */
+export interface CursorRendererOptions {
+    /** Container element to render cursor within */
+    container: HTMLElement;
+    /** Width of cursor line in pixels (default: 2) */
+    cursorWidth?: number;
+    /** Color of cursor (default: 'black') */
+    cursorColor?: string;
+    /** Cursor blink rate in milliseconds (default: 530) */
+    blinkRate?: number;
+    /** Selection background color (default: 'rgba(0, 123, 255, 0.3)') */
+    selectionColor?: string;
+}
+/**
+ * CursorRenderer renders cursor and selection overlays using positioned divs.
+ *
+ * This approach avoids browser's native cursor rendering and provides:
+ * - Instant cursor updates without DOM measurements
+ * - Precise positioning using calculated coordinates
+ * - Smooth cursor blinking
+ * - Multi-rect selection rendering
+ *
+ * Usage:
+ * ```typescript
+ * const renderer = new CursorRenderer({
+ *   container: editorElement,
+ *   cursorWidth: 2,
+ *   cursorColor: 'black',
+ *   blinkRate: 530
+ * });
+ *
+ * // Render cursor at calculated position
+ * renderer.render(cursorRect);
+ *
+ * // Render selection
+ * renderer.renderSelection(selectionRects);
+ *
+ * // Clean up
+ * renderer.destroy();
+ * ```
+ */
+export declare class CursorRenderer {
+    private container;
+    private cursorWidth;
+    private cursorColor;
+    private blinkRate;
+    private selectionColor;
+    private cursorElement;
+    private selectionElements;
+    private blinkInterval;
+    private isBlinkVisible;
+    private isCursorVisible;
+    /**
+     * Creates a new CursorRenderer instance.
+     *
+     * @param options - Cursor rendering options
+     */
+    constructor(options: CursorRendererOptions);
+    /**
+     * Initialize the cursor DOM element.
+     * @private
+     */
+    private initializeCursorElement;
+    /**
+     * Render cursor at calculated position.
+     *
+     * @param rect - Cursor rectangle or null to hide cursor
+     */
+    render(rect: CursorRect | null): void;
+    /**
+     * Render selection rectangles.
+     *
+     * Creates or updates div elements for each selection rectangle.
+     *
+     * @param rects - Array of selection rectangles
+     */
+    renderSelection(rects: CursorRect[]): void;
+    /**
+     * Show or hide the cursor.
+     *
+     * @param visible - Whether cursor should be visible
+     */
+    setVisible(visible: boolean): void;
+    /**
+     * Start cursor blink animation.
+     */
+    startBlink(): void;
+    /**
+     * Stop cursor blink animation.
+     */
+    stopBlink(): void;
+    /**
+     * Reset blink animation (show cursor and restart timer).
+     * Call this when cursor moves to provide immediate visual feedback.
+     * @private
+     */
+    private resetBlink;
+    /**
+     * Update cursor visibility based on blink state.
+     * @private
+     */
+    private updateBlinkState;
+    /**
+     * Update cursor color.
+     *
+     * @param color - New cursor color
+     */
+    setCursorColor(color: string): void;
+    /**
+     * Update selection color.
+     *
+     * @param color - New selection color
+     */
+    setSelectionColor(color: string): void;
+    /**
+     * Update cursor width.
+     *
+     * @param width - New cursor width in pixels
+     */
+    setCursorWidth(width: number): void;
+    /**
+     * Update blink rate.
+     *
+     * @param rate - New blink rate in milliseconds
+     */
+    setBlinkRate(rate: number): void;
+    /**
+     * Clean up and remove all cursor and selection elements.
+     */
+    destroy(): void;
+    /**
+     * Check if cursor is currently visible (not hidden by user).
+     *
+     * @returns True if cursor is set to visible
+     */
+    isVisible(): boolean;
+    /**
+     * Check if cursor is currently blinking.
+     *
+     * @returns True if blink animation is running
+     */
+    isBlinking(): boolean;
+    /**
+     * Get current cursor position.
+     *
+     * @returns Current cursor rectangle or null if not rendered
+     */
+    getCurrentPosition(): {
+        x: number;
+        y: number;
+        height: number;
+    } | null;
+    /**
+     * Get count of currently rendered selection rectangles.
+     *
+     * @returns Number of selection rects
+     */
+    getSelectionCount(): number;
+}

package/dist/layout-engine/layout-bridge/src/debounced-passes.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Debounced Pass Manager
+ *
+ * Manages debouncing of expensive update passes during document editing to improve
+ * typing performance. Allows deferring non-critical operations until typing pauses.
+ *
+ * Debouncing Strategy:
+ * 1. Register expensive passes with delays and priorities
+ * 2. Trigger passes during edits (starts/resets debounce timers)
+ * 3. Execute passes only after debounce delay expires
+ * 4. Cancel pending passes when needed
+ *
+ * Common Debounced Passes:
+ * - Header/footer updates (500ms)
+ * - List renumbering (100ms)
+ * - Cross-reference updates (2000ms)
+ * - Page number updates (500ms)
+ * - Footnote layout (200ms)
+ *
+ * @module debounced-passes
+ */
+/**
+ * Configuration for a debounced pass.
+ */
+export interface DebouncedPass {
+    /** Unique identifier for this pass */
+    id: string;
+    /** Debounce delay in milliseconds */
+    delay: number;
+    /** Priority for execution ordering (higher = earlier) */
+    priority: number;
+    /** Function to execute when debounce expires */
+    execute: () => void | Promise<void>;
+}
+/**
+ * DebouncedPassManager coordinates the execution of expensive layout passes
+ * by debouncing them during typing bursts.
+ *
+ * This ensures a responsive typing experience while still updating document
+ * features like headers, footers, and cross-references once editing pauses.
+ */
+export declare class DebouncedPassManager {
+    private passes;
+    private timers;
+    private pendingExecutions;
+    /**
+     * Register a debounced pass.
+     *
+     * @param pass - Pass configuration
+     */
+    register(pass: DebouncedPass): void;
+    /**
+     * Trigger a pass, starting or resetting its debounce timer.
+     *
+     * Example debounce delays:
+     * - Header/footer updates: 500ms
+     * - List renumbering: 100ms
+     * - Cross-reference updates: 2000ms
+     * - Page number updates: 500ms
+     * - Footnote layout: 200ms
+     *
+     * @param passId - ID of the pass to trigger
+     */
+    trigger(passId: string): void;
+    /**
+     * Cancel a pending pass execution.
+     *
+     * @param passId - ID of the pass to cancel
+     */
+    cancel(passId: string): void;
+    /**
+     * Cancel all pending pass executions.
+     */
+    cancelAll(): void;
+    /**
+     * Check if a specific pass is currently pending.
+     *
+     * @param passId - ID of the pass to check
+     * @returns True if the pass is pending execution
+     */
+    isPending(passId: string): boolean;
+    /**
+     * Get the number of pending pass executions.
+     *
+     * @returns Count of passes waiting to execute
+     */
+    getPendingCount(): number;
+    /**
+     * Execute a pass immediately.
+     * Clears the timer and pending state.
+     *
+     * @param passId - ID of the pass to execute
+     * @private
+     */
+    private executePass;
+    /**
+     * Unregister a pass.
+     *
+     * @param passId - ID of the pass to unregister
+     */
+    unregister(passId: string): void;
+    /**
+     * Get all registered pass IDs.
+     *
+     * @returns Array of registered pass IDs
+     */
+    getRegisteredPasses(): string[];
+    /**
+     * Clear all registrations and timers.
+     */
+    clear(): void;
+    /**
+     * Get pass configuration for a specific pass.
+     *
+     * @param passId - ID of the pass
+     * @returns Pass configuration if registered, undefined otherwise
+     */
+    getPass(passId: string): DebouncedPass | undefined;
+    /**
+     * Trigger all pending passes immediately without waiting for debounce.
+     * Useful when forcing a full update (e.g., before saving).
+     */
+    flushAll(): Promise<void>;
+    /**
+     * Trigger a specific pass immediately without waiting for debounce.
+     *
+     * @param passId - ID of the pass to flush
+     */
+    flush(passId: string): Promise<void>;
+}

package/dist/layout-engine/layout-bridge/src/diff.d.ts

@@ -0,0 +1,36 @@
+import { FlowBlock } from '../../contracts/src/index.js';
+export type DirtyRegion = {
+    firstDirtyIndex: number;
+    lastStableIndex: number;
+    insertedBlockIds: string[];
+    deletedBlockIds: string[];
+    /**
+     * Existing blocks whose render-relevant content changed. This is distinct
+     * from insertion/deletion churn and lets pagination establish the complete
+     * affected frontier without guessing from only the first dirty ordinal.
+     */
+    changedBlockIds: string[];
+    stableBlockIds: Set<string>;
+};
+/**
+ * Computes dirty regions between two versions of a document's flow blocks.
+ *
+ * Identifies which blocks have changed, been added, or removed, and determines
+ * the minimal region that needs to be re-laid out. Uses block IDs and tracked
+ * change metadata to detect modifications.
+ *
+ * @param previous - Previous version of flow blocks
+ * @param next - New version of flow blocks
+ * @returns DirtyRegion describing the extent of changes
+ *
+ * @example
+ * ```typescript
+ * const region = computeDirtyRegions(oldBlocks, newBlocks);
+ * if (region.isEntireDocument) {
+ *   relayoutAll();
+ * } else {
+ *   relayoutRange(region.firstDirtyIndex, region.lastDirtyIndex);
+ * }
+ * ```
+ */
+export declare const computeDirtyRegions: (previous: FlowBlock[], next: FlowBlock[]) => DirtyRegion;