superdoc 2.2.1 → 2.3.0

package/dist/layout-engine/layout-bridge/src/dirty-tracker.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Dirty Tracker
+ *
+ * Tracks which pages and blocks need to be repainted during incremental layout updates.
+ * This enables efficient partial repaints by identifying only the affected regions,
+ * avoiding full document reflows during typing and editing operations.
+ *
+ * Tracking Strategy:
+ * 1. Mark dirty regions when edits occur (pages, blocks, or ranges)
+ * 2. Query dirty state to determine what needs repainting
+ * 3. Clear dirty state after processing
+ * 4. Support viewport-based queries for prioritizing visible content
+ *
+ * @module dirty-tracker
+ */
+/**
+ * Represents a range of dirty content with reason for tracking.
+ */
+export interface DirtyRange {
+    /** Starting page index (inclusive) */
+    startPage: number;
+    /** Ending page index (inclusive) */
+    endPage: number;
+    /** Starting block index (inclusive) */
+    startBlock: number;
+    /** Ending block index (inclusive) */
+    endBlock: number;
+    /** Reason this range became dirty */
+    reason: 'edit' | 'resize' | 'scroll' | 'pagination';
+}
+/**
+ * DirtyTracker manages dirty state for incremental layout updates.
+ *
+ * This class provides fine-grained tracking of which pages and blocks need
+ * repainting, enabling efficient partial updates during typing bursts.
+ */
+export declare class DirtyTracker {
+    private dirtyPages;
+    private dirtyBlocks;
+    private dirtyRanges;
+    private maxPageTracked;
+    /**
+     * Mark a specific page as dirty.
+     *
+     * @param pageIndex - Zero-based page index to mark dirty
+     * @param reason - Reason for marking dirty
+     */
+    markPageDirty(pageIndex: number, reason: DirtyRange['reason']): void;
+    /**
+     * Mark a range of blocks as dirty.
+     *
+     * @param startBlock - Starting block index (inclusive)
+     * @param endBlock - Ending block index (inclusive)
+     * @param reason - Reason for marking dirty
+     */
+    markBlocksDirty(startBlock: number, endBlock: number, reason: DirtyRange['reason']): void;
+    /**
+     * Mark all pages from a starting point as dirty.
+     * Used for pagination changes that affect all subsequent pages.
+     *
+     * @param startPage - Starting page index (inclusive)
+     * @param reason - Reason for marking dirty (typically 'pagination')
+     */
+    markDirtyFrom(startPage: number, reason: DirtyRange['reason']): void;
+    /**
+     * Get dirty pages that intersect with the viewport range.
+     *
+     * @param viewportStart - Starting page index of viewport (inclusive)
+     * @param viewportEnd - Ending page index of viewport (inclusive)
+     * @returns Sorted array of dirty page indices within viewport
+     */
+    getDirtyPagesInViewport(viewportStart: number, viewportEnd: number): number[];
+    /**
+     * Get all dirty ranges.
+     *
+     * @returns Array of dirty ranges (copy to prevent external mutation)
+     */
+    getDirtyRanges(): DirtyRange[];
+    /**
+     * Clear dirty state for the specified pages.
+     *
+     * @param pages - Array of page indices to clear
+     */
+    clearDirty(pages: number[]): void;
+    /**
+     * Check if any dirty content exists.
+     *
+     * @returns True if there are any dirty pages, blocks, or ranges
+     */
+    hasDirty(): boolean;
+    /**
+     * Clear all dirty state.
+     */
+    clearAll(): void;
+    /**
+     * Add a new range or merge with existing compatible ranges.
+     *
+     * @param newRange - Range to add
+     * @private
+     */
+    private addOrMergeRange;
+    /**
+     * Check if two ranges overlap or are adjacent.
+     *
+     * This method is used for range merging optimization. Two ranges are considered
+     * mergeable if they overlap or are directly adjacent (touching). This prevents
+     * fragmentation of the dirty ranges list.
+     *
+     * Algorithm:
+     * - Ranges [a, b] and [c, d] overlap if: a <= d+1 AND c <= b+1
+     * - The +1 accounts for adjacent ranges (e.g., [1,3] and [4,6] are adjacent)
+     *
+     * Examples:
+     * - [1, 3] and [2, 5]: overlap (intersect)
+     * - [1, 3] and [4, 6]: adjacent (touch at boundary)
+     * - [1, 3] and [5, 7]: separate (gap of 1)
+     *
+     * Complexity: O(1)
+     *
+     * @param start1 - Start of first range (inclusive)
+     * @param end1 - End of first range (inclusive)
+     * @param start2 - Start of second range (inclusive)
+     * @param end2 - End of second range (inclusive)
+     * @returns True if ranges overlap or are adjacent, false otherwise
+     * @private
+     */
+    private rangesOverlap;
+}

package/dist/layout-engine/layout-bridge/src/dom-mapping.d.ts

@@ -0,0 +1,80 @@
+/**
+ * ===================================================================
+ * COMPATIBILITY ONLY — DO NOT USE FOR NEW CODE
+ * ===================================================================
+ *
+ * The production implementation of DOM pointer mapping lives with the editor
+ * runtime's DOM observer.
+ *
+ * This file is retained only for backward compatibility with existing
+ * layout-bridge consumers. It will be removed in a later cleanup PR.
+ *
+ * Do NOT import from this file in editor runtime production code.
+ * ===================================================================
+ *
+ * DOM-based click-to-position mapping utilities.
+ *
+ * This module provides pixel-perfect click-to-position mapping by reading actual
+ * DOM elements with data attributes (`data-pm-start`, `data-pm-end`). This approach
+ * is more accurate than pure geometry-based mapping because it uses the browser's
+ * actual rendering and correctly handles ProseMirror position gaps that may occur
+ * after document operations like paragraph joins.
+ *
+ * @module dom-mapping
+ * @deprecated Use the editor runtime's DOM observer mapping instead.
+ */
+/**
+ * Maps a click coordinate to a ProseMirror document position using DOM data attributes.
+ *
+ * This function provides pixel-perfect accuracy by:
+ * 1. Finding the fragment element under the click point using `elementsFromPoint`
+ * 2. Finding the line element at the Y coordinate
+ * 3. Finding the span (text run) at the X coordinate
+ * 4. Using binary search with `document.createRange()` to find the exact character boundary
+ *
+ * The DOM structure must follow this pattern (as produced by the DOM painter):
+ * ```
+ * <div class="superdoc-page" data-page-index="0">
+ *   <div class="superdoc-fragment" data-block-id="...">
+ *     <div class="superdoc-line" data-pm-start="2" data-pm-end="19">
+ *       <span data-pm-start="2" data-pm-end="12">text content</span>
+ *       <span data-pm-start="14" data-pm-end="19">more text</span>
+ *     </div>
+ *   </div>
+ * </div>
+ * ```
+ *
+ * **Important:** This function correctly handles PM position gaps (e.g., 12→14 in the example
+ * above) that can occur after document edits. The geometry-based mapping in `clickToPosition`
+ * may produce incorrect positions in these cases, which is why DOM mapping should be preferred
+ * when available.
+ *
+ * **Inline SDT Filtering:** Inline structured content (SDT) wrapper elements are automatically
+ * excluded from click-to-position mapping. These wrappers (identified by the class
+ * `superdoc-structured-content-inline`) have PM position attributes for selection highlighting,
+ * but their child spans provide more accurate character-level positioning for clicks. This
+ * ensures the caret is placed at the exact clicked character rather than at wrapper boundaries.
+ *
+ * @param domContainer - The DOM container element (typically the viewport or page element)
+ * @param clientX - X coordinate in viewport space (from MouseEvent.clientX)
+ * @param clientY - Y coordinate in viewport space (from MouseEvent.clientY)
+ * @returns ProseMirror document position, or null if mapping fails (no DOM data, invalid structure, etc.)
+ *
+ * @example
+ * ```typescript
+ * const pos = clickToPositionDom(viewportElement, event.clientX, event.clientY);
+ * if (pos !== null) {
+ *   editor.setSelection(pos, pos);
+ * }
+ * ```
+ */
+export declare function clickToPositionDom(domContainer: HTMLElement, clientX: number, clientY: number): number | null;
+/**
+ * Finds the page element containing the click coordinates.
+ *
+ * @param domContainer - The container element to search within
+ * @param clientX - X coordinate in viewport space
+ * @param clientY - Y coordinate in viewport space
+ * @returns The page element, or null if not found
+ */
+export declare function findPageElement(domContainer: HTMLElement, clientX: number, clientY: number): HTMLElement | null;

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

@@ -0,0 +1,95 @@
+/**
+ * Feature Flags Module
+ *
+ * Centralized feature flag configuration for headers/footers page-number parity.
+ * All flags are enabled by default but can be toggled via environment variables.
+ *
+ * Environment variables:
+ * - SD_NUMBERING_SECTION_AWARE: Enable section-aware numbering (restarts, formats)
+ * - SD_BODY_PAGE_TOKENS: Enable body page token resolution (PAGE/NUMPAGES)
+ * - SD_HEADER_FOOTER_PAGE_TOKENS: Enable header/footer page token resolution
+ * - SD_HF_DIGIT_BUCKETING: Enable digit bucketing for large documents
+ * - SD_DEBUG_PAGE_TOKENS: Enable debug logging for page token resolution
+ * - SD_DEBUG_HF_CACHE: Enable debug logging for header/footer cache operations
+ * - SD_DEBUG_LAYOUT_VERSION: Enable debug logging for layout version tracking
+ *
+ * Each flag can be set to:
+ * - "true" or "1": Explicitly enabled
+ * - "false" or "0": Explicitly disabled
+ * - undefined: Use default value (all default to true)
+ */
+/**
+ * Feature flag configuration object.
+ * All flags are checked once at module load time for performance.
+ */
+export declare const FeatureFlags: {
+    /**
+     * Enable section-aware numbering with restarts and format changes.
+     * When disabled, falls back to simple 1-N sequential numbering.
+     */
+    readonly NUMBERING_SECTION_AWARE: boolean;
+    /**
+     * Enable body page token resolution (PAGE/NUMPAGES in document content).
+     * When disabled, tokens remain as placeholders in body content.
+     */
+    readonly BODY_PAGE_TOKENS: boolean;
+    /**
+     * Enable header/footer page token resolution.
+     * When disabled, headers/footers use painter-time token rendering fallback.
+     */
+    readonly HEADER_FOOTER_PAGE_TOKENS: boolean;
+    /**
+     * Enable digit bucketing for header/footer caching in large documents.
+     * When disabled, creates per-page layouts for all documents (no bucketing).
+     * Recommended to keep enabled for documents with 100+ pages.
+     */
+    readonly HF_DIGIT_BUCKETING: boolean;
+    /**
+     * Enable debug logging for page token resolution.
+     * Logs token resolution details, affected blocks, and convergence iteration info.
+     * Should be disabled in production (only enabled for debugging).
+     */
+    readonly DEBUG_PAGE_TOKENS: boolean;
+    /**
+     * Enable debug logging for header/footer cache operations.
+     * Logs cache hits, misses, invalidations, and bucket selection.
+     * Should be disabled in production (only enabled for debugging).
+     */
+    readonly DEBUG_HF_CACHE: boolean;
+    /**
+     * Enable debug logging for layout version tracking.
+     * Logs stale layout reads, geometry fallbacks, PM transactions, and layout completions.
+     * Should be disabled in production (only enabled for debugging).
+     */
+    readonly DEBUG_LAYOUT_VERSION: boolean;
+};
+/**
+ * Type-safe feature flag keys for programmatic access.
+ */
+export type FeatureFlagKey = keyof typeof FeatureFlags;
+/**
+ * Checks if a specific feature flag is enabled.
+ *
+ * @param flag - Feature flag key
+ * @returns True if the flag is enabled
+ *
+ * @example
+ * ```typescript
+ * if (isFeatureEnabled('BODY_PAGE_TOKENS')) {
+ *   // Execute body token resolution
+ * }
+ * ```
+ */
+export declare function isFeatureEnabled(flag: FeatureFlagKey): boolean;
+/**
+ * Gets all feature flag values as an object.
+ * Useful for logging and debugging.
+ *
+ * @returns Object with all feature flag values
+ *
+ * @example
+ * ```typescript
+ * console.log('Feature flags:', getAllFeatureFlags());
+ * ```
+ */
+export declare function getAllFeatureFlags(): Record<FeatureFlagKey, boolean>;

package/dist/layout-engine/layout-bridge/src/field-annotation-key.d.ts

@@ -0,0 +1,2 @@
+import { Run } from '../../contracts/src/index.js';
+export declare const fieldAnnotationKey: (run: Run) => string;

package/dist/layout-engine/layout-bridge/src/focus-watchdog.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Focus Watchdog
+ *
+ * Monitors focus stability of the hidden ProseMirror view.
+ * The typing performance system relies on the PM view maintaining focus
+ * to receive input events. This watchdog detects focus drift and attempts
+ * automatic recovery.
+ *
+ * Features:
+ * - Periodic focus checking
+ * - Drift detection with configurable threshold
+ * - Automatic focus restoration
+ * - Drift count tracking for debugging
+ * - Event callbacks for drift and recovery
+ *
+ * @module focus-watchdog
+ */
+/**
+ * Configuration for focus watchdog.
+ */
+export interface FocusWatchdogConfig {
+    /** Interval between focus checks in ms (default: 1000) */
+    checkInterval: number;
+    /** Trigger recovery after this many drifts (default: 3) */
+    maxDriftCount: number;
+    /** Called when focus drift is detected */
+    onDrift: (target: Element | null) => void;
+    /** Called when focus is successfully restored */
+    onRecovery: () => void;
+}
+/**
+ * Focus watchdog for monitoring hidden PM view focus.
+ *
+ * Periodically checks that focus remains on the expected element (hidden PM view).
+ * Detects drift and attempts automatic restoration.
+ *
+ * @example
+ * ```typescript
+ * const watchdog = new FocusWatchdog({
+ *   checkInterval: 1000,
+ *   maxDriftCount: 3,
+ *   onDrift: (target) => {
+ *     console.warn('Focus drifted to:', target);
+ *   },
+ *   onRecovery: () => {
+ *     console.log('Focus restored');
+ *   },
+ * });
+ *
+ * // Set the expected focus element
+ * watchdog.setExpectedFocus(hiddenPmView.dom);
+ *
+ * // Start monitoring
+ * watchdog.start();
+ *
+ * // Later: stop monitoring
+ * watchdog.stop();
+ * ```
+ */
+export declare class FocusWatchdog {
+    private config;
+    private expectedFocusElement;
+    private driftCount;
+    private intervalId;
+    private running;
+    /**
+     * Creates a new focus watchdog.
+     *
+     * @param config - Watchdog configuration
+     */
+    constructor(config: FocusWatchdogConfig);
+    /**
+     * Sets the expected focus element (hidden PM view).
+     *
+     * This is the element that should maintain focus during typing.
+     *
+     * @param element - The element that should have focus
+     *
+     * @example
+     * ```typescript
+     * watchdog.setExpectedFocus(pmView.dom);
+     * ```
+     */
+    setExpectedFocus(element: HTMLElement): void;
+    /**
+     * Starts monitoring focus.
+     *
+     * Begins periodic checks at the configured interval.
+     *
+     * @example
+     * ```typescript
+     * watchdog.start();
+     * ```
+     */
+    start(): void;
+    /**
+     * Stops monitoring focus.
+     *
+     * Clears the periodic check interval.
+     *
+     * @example
+     * ```typescript
+     * watchdog.stop();
+     * ```
+     */
+    stop(): void;
+    /**
+     * Checks focus immediately.
+     *
+     * Returns true if focus is on the expected element, false otherwise.
+     *
+     * @returns True if focus is correct
+     *
+     * @example
+     * ```typescript
+     * if (!watchdog.check()) {
+     *   console.warn('Focus is not on PM view');
+     * }
+     * ```
+     */
+    check(): boolean;
+    /**
+     * Gets the current drift count.
+     *
+     * @returns Number of times focus has drifted
+     *
+     * @example
+     * ```typescript
+     * const drifts = watchdog.getDriftCount();
+     * console.log(`Focus has drifted ${drifts} times`);
+     * ```
+     */
+    getDriftCount(): number;
+    /**
+     * Resets the drift count.
+     *
+     * Useful after manual intervention or system restart.
+     *
+     * @example
+     * ```typescript
+     * watchdog.resetDriftCount();
+     * ```
+     */
+    resetDriftCount(): void;
+    /**
+     * Attempts to restore focus to the expected element.
+     *
+     * @returns True if restoration successful
+     *
+     * @example
+     * ```typescript
+     * if (watchdog.restoreFocus()) {
+     *   console.log('Focus restored');
+     * }
+     * ```
+     */
+    restoreFocus(): boolean;
+    /**
+     * Handles focus drift detection.
+     *
+     * @param target - Element that currently has focus
+     */
+    private handleDrift;
+    /**
+     * Cleans up resources.
+     *
+     * Call when destroying the watchdog.
+     */
+    destroy(): void;
+}

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

@@ -0,0 +1,164 @@
+/**
+ * Font Metrics Cache
+ *
+ * Pre-measures character widths for common fonts using canvas measureText() API.
+ * Enables fast character width lookups without repeated DOM operations.
+ *
+ * Population Strategy:
+ * 1. On document load, scan all text runs for unique font combinations
+ * 2. For each font, measure full printable ASCII + common Unicode via canvas
+ * 3. Cache is persistent for session, keyed by font signature
+ *
+ * @module font-metrics-cache
+ */
+/**
+ * Metrics for a specific font configuration.
+ */
+export interface FontMetrics {
+    /** Map of character to width in pixels */
+    charWidths: Map<string, number>;
+    /** Width of space character in pixels */
+    spaceWidth: number;
+    /** Line height in pixels */
+    lineHeight: number;
+    /** Baseline offset from top in pixels */
+    baseline: number;
+    /** Average character width (fallback for unmeasured chars) */
+    avgCharWidth: number;
+    /** Timestamp when metrics were measured (for cache invalidation) */
+    measuredAt: number;
+}
+/**
+ * Configuration for font metrics caching.
+ */
+export interface FontMetricsCacheConfig {
+    /** Font key in format "fontFamily|fontSize|fontWeight|fontStyle" */
+    fontKey: string;
+}
+/**
+ * FontMetricsCache provides fast character width lookups by pre-measuring
+ * character widths for font configurations using canvas measureText().
+ *
+ * This cache is essential for performance when calculating cursor positions,
+ * as it avoids repeated DOM measurements.
+ */
+export declare class FontMetricsCache {
+    private cache;
+    private canvas;
+    private ctx;
+    /**
+     * Creates a new FontMetricsCache instance.
+     * Initializes the canvas context for measurements.
+     */
+    constructor();
+    /**
+     * Initializes the canvas and context for font measurements.
+     *
+     * Creates an offscreen 1x1 canvas with 2D rendering context optimized for
+     * text measurement. The canvas is never attached to the DOM and is purely
+     * used for the canvas.measureText() API.
+     *
+     * Performance considerations:
+     * - Canvas is created once and reused for all measurements
+     * - Size is minimal (1x1) as we only need measureText(), not rendering
+     * - willReadFrequently hint optimizes for frequent measureText() calls
+     *
+     * Failure modes:
+     * - Not in browser environment (SSR): Sets ctx to null, cache will be disabled
+     * - Canvas creation fails: Catches error, sets ctx to null, measurements fall back to defaults
+     *
+     * Side effects:
+     * - Creates this.canvas and this.ctx properties
+     * - On failure, cache becomes read-only (getMetrics returns undefined for unmeasured fonts)
+     *
+     * @private
+     */
+    private initializeCanvas;
+    /**
+     * Pre-warms the cache by measuring all characters for the specified fonts.
+     *
+     * @param fonts - Array of font configurations to pre-measure
+     */
+    warmCache(fonts: FontMetricsCacheConfig[]): void;
+    /**
+     * Gets cached metrics for a font key.
+     *
+     * @param fontKey - Font key in format "fontFamily|fontSize|fontWeight|fontStyle"
+     * @returns Font metrics if cached, undefined otherwise
+     */
+    getMetrics(fontKey: string): FontMetrics | undefined;
+    /**
+     * Measures a specific character if not already in cache.
+     * If the font is not cached, measures the entire font first.
+     *
+     * @param fontKey - Font key in format "fontFamily|fontSize|fontWeight|fontStyle"
+     * @param char - Character to measure
+     * @returns Width of the character in pixels
+     */
+    measureChar(fontKey: string, char: string): number;
+    /**
+     * Measures all common characters for a font and caches the results.
+     *
+     * @param fontKey - Font key in format "fontFamily|fontSize|fontWeight|fontStyle"
+     * @returns Measured font metrics
+     * @private
+     */
+    private measureFont;
+    /**
+     * Measures the width of a single character.
+     *
+     * @param fontKey - Font key in format "fontFamily|fontSize|fontWeight|fontStyle"
+     * @param char - Character to measure
+     * @returns Width in pixels
+     * @private
+     */
+    private measureCharWidth;
+    /**
+     * Creates default metrics when canvas is not available.
+     *
+     * @returns Default font metrics
+     * @private
+     */
+    private createDefaultMetrics;
+    /**
+     * Generates a font key from font properties.
+     *
+     * @param family - Font family name
+     * @param size - Font size in pixels
+     * @param weight - Font weight (e.g., 'normal', 'bold', '400', '700')
+     * @param style - Font style (e.g., 'normal', 'italic')
+     * @returns Font key string
+     */
+    static createFontKey(family: string, size: number, weight?: string, style?: string): string;
+    /**
+     * Parses a font key into its components.
+     *
+     * @param fontKey - Font key string
+     * @returns Font properties
+     * @private
+     */
+    private static parseFontKey;
+    /**
+     * Clears all cached metrics.
+     */
+    clear(): void;
+    /**
+     * Gets the number of cached font configurations.
+     */
+    get size(): number;
+    /**
+     * Checks if metrics exist for a font key.
+     *
+     * @param fontKey - Font key to check
+     * @returns True if metrics are cached
+     */
+    has(fontKey: string): boolean;
+    /**
+     * Validates fontKey format.
+     *
+     * @param fontKey - Font key to validate
+     * @returns True if fontKey has valid format "family|size|weight|style"
+     * @private
+     */
+    private isValidFontKey;
+}