superdoc 2.2.0 → 2.3.0

package/dist/layout-engine/layout-bridge/src/neutral-hit.d.ts

@@ -0,0 +1,142 @@
+import { FlowBlock, Layout, LayoutBlockRef, LayoutFragmentId, LayoutSourceIdentity, LayoutStoryLocator, Measure, SourceAnchor, LAYOUT_BOUNDARY_SCHEMA } from '../../contracts/src/index.js';
+import { ClickToPositionGeometryOptions, PositionHit, Point } from './position-hit.js';
+/** Container-space rectangle (mirrors `Rect` from this package's `index.ts`). */
+export type LayoutRect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    pageIndex: number;
+};
+/**
+ * Layout-side representation of a hit-tested point.
+ *
+ * Carries everything an editor-neutral consumer needs to address the
+ * rendered fragment under a click. Legacy PM fields (`pmPosition`,
+ * `layoutEpoch`, `lineIndex`, `column`) are surfaced under `legacyPm` for
+ * v1 callers that still need them.
+ */
+export type LayoutHit = {
+    /** Schema version for this hit-test result. */
+    schema: typeof LAYOUT_BOUNDARY_SCHEMA;
+    /** Layout revision (today: `layout.layoutEpoch`). */
+    layoutRevision: number;
+    /** Composite editor-neutral identity for the hit fragment. */
+    identity: LayoutSourceIdentity;
+    /** Story locator for the hit fragment. */
+    story: LayoutStoryLocator;
+    /** Source block reference (today: producer's `blockId`). */
+    blockRef: LayoutBlockRef;
+    /** Stable opaque fragment id. */
+    fragmentId: LayoutFragmentId;
+    /** 0-based page index containing the hit. */
+    pageIndex: number;
+    /** Optional cross-reference to the DOCX source anchor. */
+    sourceAnchor?: SourceAnchor;
+    /** Diagnostics for partially supported or rejected hits. */
+    diagnostics?: LayoutHitDiagnostic[];
+    /**
+     * Legacy PM-shaped position hit.
+     *
+     * AIDEV-NOTE: compat-fallback - callers may still consume `pmPosition`.
+     * Retire once providers stop relying on PM positions to map this hit back to
+     * a document ref. Do not gate new editor-neutral behavior on this field.
+     */
+    legacyPm?: PositionHit;
+};
+export type LayoutHitDiagnostic = {
+    code: 'no-page-hit';
+} | {
+    code: 'no-fragment-hit';
+} | {
+    code: 'pm-position-unavailable';
+} | {
+    code: 'unsupported-fragment-kind';
+    fragmentKind: string;
+};
+/**
+ * Subrange of a single fragment, in editor-neutral terms.
+ *
+ * `inlineFromOpaque` / `inlineToOpaque` are placeholders for the offsets a
+ * future neutral text-offset model will carry. They are intentionally
+ * optional because the current producer can only describe character offsets
+ * via PM positions, and PM-required fields are not allowed on this contract.
+ * v1 consumers that need pixel rects should use `selectionToRects` directly;
+ * they should not gate behavior on this neutral surface yet.
+ */
+export type LayoutFragmentSubrange = {
+    identity: LayoutSourceIdentity;
+    story: LayoutStoryLocator;
+    blockRef: LayoutBlockRef;
+    fragmentId: LayoutFragmentId;
+    pageIndex: number;
+    /** Container-space rectangle covered by the fragment slice. */
+    rect: LayoutRect;
+    /** Optional opaque inline-offset start (may be omitted). */
+    inlineFromOpaque?: string;
+    /** Optional opaque inline-offset end (may be omitted). */
+    inlineToOpaque?: string;
+};
+/**
+ * PM-free rendered range for the current neutral subset.
+ *
+ * This maps one or more already-known rendered fragment ids to their full
+ * fragment rectangles. It intentionally does not model text offsets; v1 PM
+ * range slicing remains available through `PmOpaqueRange`.
+ */
+export type LayoutFragmentOpaqueRange = {
+    fragmentIds: readonly LayoutFragmentId[];
+};
+/**
+ * Result of mapping an opaque source range to rendered fragments.
+ *
+ * The opaque range type is intentionally `unknown` here; today the only
+ * concrete instantiation is `{ pmFrom: number; pmTo: number }`, but the
+ * contract names neither, so a future v2 source range can substitute
+ * without reopening the layout boundary.
+ */
+export type LayoutRangeMapping = {
+    schema: typeof LAYOUT_BOUNDARY_SCHEMA;
+    layoutRevision: number;
+    fragments: LayoutFragmentSubrange[];
+    diagnostics?: LayoutHitDiagnostic[];
+};
+/**
+ * Concrete opaque-range instantiation for v1 consumers using PM positions.
+ *
+ * Kept here (and not in `@superdoc/contracts`) because nothing about it is
+ * editor-neutral. v2 consumers should not import this type; they should
+ * define their own opaque-range shape and the same `mapRangeToFragmentsNeutral`
+ * entry point will accept it (via the function overload defined below).
+ */
+export type PmOpaqueRange = {
+    pmFrom: number;
+    pmTo: number;
+};
+/**
+ * Hit-test a container-space coordinate and return an editor-neutral
+ * `LayoutHit`.
+ *
+ * Today the implementation derives the underlying mapping by calling
+ * `clickToPositionGeometry` and projecting the result onto the neutral
+ * shape. The `legacyPm` field is populated so v1 callers continue to work.
+ *
+ * Returns `null` only when no page can be hit at all; partial hits emit
+ * diagnostics rather than failing closed so consumers can distinguish
+ * "outside content" from "fragment unrecognized".
+ */
+export declare function hitTestNeutral(layout: Layout, blocks: FlowBlock[], measures: Measure[], containerPoint: Point, options?: ClickToPositionGeometryOptions): LayoutHit | null;
+/**
+ * Project rendered selection rectangles into editor-neutral fragment
+ * subranges.
+ *
+ * Accepts a `PmOpaqueRange` today; future neutral range shapes can be
+ * accepted via overloads without reopening this contract.
+ *
+ * The `selectionToRects` produces one `Rect` per visual line; this helper
+ * groups them by page and surfaces the underlying fragment identity for
+ * each rect. v1 callers that need raw pixel rects should continue to call
+ * `selectionToRects` directly — this is the editor-neutral adapter.
+ */
+export declare function mapRangeToFragmentsNeutral(layout: Layout, blocks: FlowBlock[], measures: Measure[], range: PmOpaqueRange, selectionToRectsFn: (layout: Layout, blocks: FlowBlock[], measures: Measure[], from: number, to: number) => LayoutRect[]): LayoutRangeMapping;
+export declare function mapRangeToFragmentsNeutral(layout: Layout, blocks: FlowBlock[], measures: Measure[], range: LayoutFragmentOpaqueRange): LayoutRangeMapping;

package/dist/layout-engine/layout-bridge/src/neutral-segment-geometry.d.ts

@@ -0,0 +1,32 @@
+import { FlowBlock, Layout, LayoutStoryLocator, Measure, NeutralSegmentGeometryReadback } from '../../contracts/src/index.js';
+import { PageGeometryHelper } from './page-geometry-helper.js';
+export type CollectSegmentGeometryOptions = {
+    /**
+     * Story locator for the layout being read. Defaults to body. Pass the
+     * header/footer/footnote/endnote locator when collecting geometry for a
+     * non-body story layout so identity stays story-correct.
+     */
+    story?: LayoutStoryLocator;
+    /**
+     * Optional `PageGeometryHelper` for page-top lookups. Strongly recommended so
+     * vertical geometry matches selection rendering exactly. Falls back to
+     * `calculatePageTopFallback` when omitted.
+     */
+    geometryHelper?: PageGeometryHelper;
+    /** Exact page interval/window to read; omitted means every page. */
+    pageIndices?: readonly number[];
+    /** Bounded page-top lookup used with `pageIndices` without building a whole-document helper cache. */
+    pageTopAt?: (pageIndex: number) => number;
+};
+/**
+ * Read editor-neutral measured segment geometry for every paintable fragment in
+ * a layout.
+ *
+ * Body paragraph fragments (including word-layout list paragraphs) resolve to
+ * full per-line / per-segment geometry. Fragment kinds whose text geometry this
+ * version does not model (tables, inline/anchored images and drawings, and
+ * standalone list-item fragments), and lines the substrate cannot place safely
+ * (RTL/bidi), are emitted with identity + bounds and a diagnostic, never with a
+ * guessed rect.
+ */
+export declare function collectSegmentGeometry(layout: Layout, blocks: FlowBlock[], measures: Measure[], options?: CollectSegmentGeometryOptions): NeutralSegmentGeometryReadback;

package/dist/layout-engine/layout-bridge/src/page-geometry-helper.d.ts

@@ -0,0 +1,197 @@
+import { Layout } from '../../contracts/src/index.js';
+/**
+ * Configuration for page geometry calculations.
+ */
+export interface PageGeometryConfig {
+    /** The layout containing page data */
+    layout: Layout;
+    /** Gap between pages in pixels (defaults to layout.pageGap ?? 0) */
+    pageGap?: number;
+}
+/**
+ * PageGeometryHelper provides efficient, cached access to page positions and heights.
+ *
+ * This class:
+ * - Computes cumulative Y positions for each page (accounting for per-page heights and gaps)
+ * - Caches calculations for O(1) lookup performance
+ * - Invalidates cache when layout changes
+ * - Handles mixed page sizes correctly
+ *
+ * **Why This Exists:**
+ * Selection overlays were drifting because geometry calculations used different
+ * assumptions about page spacing than the DOM painter. This helper ensures all
+ * code uses the same page positions by providing a single source of truth.
+ *
+ * **Performance:**
+ * - Initial calculation: O(n) where n = number of pages
+ * - Subsequent lookups: O(1) via cached arrays
+ * - Cache invalidation: O(1) version check
+ *
+ * **Usage:**
+ * ```typescript
+ * const helper = new PageGeometryHelper({ layout, pageGap: 24 });
+ *
+ * // Get cumulative Y position for page 5
+ * const y = helper.getPageTop(5);
+ *
+ * // Get height of page 5
+ * const height = helper.getPageHeight(5);
+ *
+ * // Get gap between pages
+ * const gap = helper.getPageGap();
+ *
+ * // Update when layout changes
+ * helper.updateLayout(newLayout);
+ * ```
+ */
+export declare class PageGeometryHelper {
+    private config;
+    private cache;
+    /**
+     * Creates a new PageGeometryHelper instance.
+     *
+     * @param config - Page geometry configuration
+     */
+    constructor(config: PageGeometryConfig);
+    /**
+     * Updates the layout and invalidates the cache.
+     *
+     * Call this whenever the layout changes (new pages, different heights, etc.)
+     *
+     * @param layout - New layout data
+     * @param pageGap - Optional new page gap (if not provided, uses current gap)
+     */
+    updateLayout(layout: Layout, pageGap?: number): void;
+    /**
+     * Updates the page gap and invalidates the cache.
+     *
+     * @param pageGap - New gap between pages in pixels
+     */
+    updatePageGap(pageGap: number): void;
+    /**
+     * Gets the cumulative Y position (top edge) of a page in container space.
+     *
+     * The returned value is the distance from the top of the container to the
+     * top of the specified page, accounting for all previous pages and gaps.
+     *
+     * @param pageIndex - Zero-based page index
+     * @returns Y position in pixels, or 0 if page index is invalid
+     *
+     * @example
+     * ```typescript
+     * // Get Y position of page 0 (first page)
+     * const y0 = helper.getPageTop(0); // Returns 0
+     *
+     * // Get Y position of page 2 (third page)
+     * // Assumes page 0 height = 1000, page 1 height = 1200, gap = 24
+     * const y2 = helper.getPageTop(2); // Returns 1000 + 24 + 1200 + 24 = 2248
+     * ```
+     */
+    getPageTop(pageIndex: number): number;
+    /**
+     * Gets the height of a specific page.
+     *
+     * Uses per-page height if available (from layout.pages[i].size?.h),
+     * otherwise falls back to layout.pageSize.h.
+     *
+     * @param pageIndex - Zero-based page index
+     * @returns Page height in pixels, or 0 if page index is invalid
+     *
+     * @example
+     * ```typescript
+     * const height = helper.getPageHeight(0); // Returns page-specific height
+     * ```
+     */
+    getPageHeight(pageIndex: number): number;
+    /**
+     * Gets the gap between pages.
+     *
+     * @returns Gap in pixels
+     *
+     * @example
+     * ```typescript
+     * const gap = helper.getPageGap(); // Returns 24
+     * ```
+     */
+    getPageGap(): number;
+    /**
+     * Gets the total height of all pages including gaps.
+     *
+     * Total height = sum of all page heights + (pageCount - 1) * gap
+     *
+     * @returns Total height in pixels
+     *
+     * @example
+     * ```typescript
+     * // 3 pages: heights [1000, 1200, 1000], gap = 24
+     * const total = helper.getTotalHeight();
+     * // Returns 1000 + 24 + 1200 + 24 + 1000 = 3248
+     * ```
+     */
+    getTotalHeight(): number;
+    /**
+     * Gets the number of pages in the layout.
+     *
+     * @returns Page count
+     */
+    getPageCount(): number;
+    /**
+     * Finds the page index containing a given Y coordinate.
+     *
+     * This performs a linear search through cached cumulative positions.
+     * For large documents, consider adding binary search optimization.
+     *
+     * @param containerY - Y coordinate in container space
+     * @returns Page index, or null if Y is outside all pages
+     *
+     * @example
+     * ```typescript
+     * // Find which page contains Y = 1500
+     * const pageIndex = helper.getPageIndexAtY(1500);
+     * // Returns 1 (second page) if first page ends at Y=1024
+     * ```
+     */
+    getPageIndexAtY(containerY: number): number | null;
+    /**
+     * Finds the nearest page index to a given Y coordinate (snap-to-nearest).
+     *
+     * Returns the page containing Y when inside a page; otherwise returns the
+     * closest page based on distance to page center. Useful for dragging through
+     * page gaps where getPageIndexAtY would return null.
+     *
+     * @param containerY - Y coordinate in container space
+     * @returns Nearest page index, or null if there are no pages
+     */
+    getNearestPageIndex(containerY: number): number | null;
+    /**
+     * Ensures the cache is built and up-to-date.
+     * Validates cache state and rebuilds if needed.
+     * @private
+     * @throws Never throws - handles errors gracefully with fallback values
+     */
+    private ensureCache;
+    /**
+     * Builds the geometry cache from current layout data.
+     * Handles errors gracefully by providing fallback values.
+     * @private
+     * @throws Never throws - catches all errors and provides safe defaults
+     */
+    private buildCache;
+    /**
+     * Clears the cache, forcing recalculation on next access.
+     * Useful for testing or manual cache invalidation.
+     */
+    clearCache(): void;
+    /**
+     * Gets debug information about the current cache state.
+     * @internal
+     */
+    getDebugInfo(): {
+        isCached: boolean;
+        pageCount: number;
+        pageGap: number;
+        totalHeight: number;
+        cumulativeY: number[];
+        pageHeights: number[];
+    };
+}

package/dist/layout-engine/layout-bridge/src/paragraph-hash-utils.d.ts

@@ -0,0 +1,126 @@
+import { ParagraphAttrs, ParagraphBorders, ParagraphBorder, Run, TableBorders, TableBorderValue, CellBorders, BorderSpec } from '../../contracts/src/index.js';
+/**
+ * Creates a deterministic hash string for a paragraph border.
+ * Ensures consistent ordering regardless of JS engine property enumeration.
+ *
+ * @param border - The paragraph border to hash
+ * @returns A deterministic hash string
+ */
+export declare const hashParagraphBorder: (border: ParagraphBorder) => string;
+/**
+ * Creates a deterministic hash string for paragraph borders.
+ * Hashes all four sides (top, right, bottom, left) in a consistent order.
+ *
+ * @param borders - The paragraph borders to hash
+ * @returns A deterministic hash string
+ */
+export declare const hashParagraphBorders: (borders: ParagraphBorders) => string;
+/**
+ * Creates a deterministic hash string for a border spec (used in table/cell borders).
+ * Ensures consistent ordering regardless of JS engine property enumeration.
+ *
+ * @param border - The border spec to hash
+ * @returns A deterministic hash string in format "s:style,w:width,c:color,sp:space"
+ */
+export declare const hashBorderSpec: (border: BorderSpec) => string;
+/**
+ * Creates a deterministic hash string for a table border value.
+ * Handles the three-state value: null (inherit), { none: true } (explicit no border), or BorderSpec.
+ *
+ * @param borderValue - The table border value to hash
+ * @returns A deterministic hash string:
+ *   - Empty string for undefined
+ *   - "null" for null (inherit from parent)
+ *   - "none" for { none: true } (explicit no border)
+ *   - Hash string for BorderSpec (e.g., "s:single,w:4,c:000000")
+ * @example
+ * hashTableBorderValue(undefined) // ""
+ * hashTableBorderValue(null) // "null"
+ * hashTableBorderValue({ none: true }) // "none"
+ * hashTableBorderValue({ style: 'single', width: 4, color: '000000' }) // "s:single,w:4,c:000000"
+ */
+export declare const hashTableBorderValue: (borderValue: TableBorderValue | undefined) => string;
+/**
+ * Creates a deterministic hash string for table-level borders.
+ * Hashes all six border positions (top, right, bottom, left, insideH, insideV) in a consistent order.
+ *
+ * @param borders - The table borders to hash
+ * @returns A deterministic hash string with format "t:[top];r:[right];b:[bottom];l:[left];ih:[insideH];iv:[insideV]"
+ *   where each border value is hashed using hashTableBorderValue. Empty string if borders is undefined.
+ * @example
+ * hashTableBorders(undefined) // ""
+ * hashTableBorders({ top: { style: 'single', width: 4 } }) // "t:[s:single,w:4]"
+ */
+export declare const hashTableBorders: (borders: TableBorders | undefined) => string;
+/**
+ * Creates a deterministic hash string for cell-level borders.
+ * Hashes all four sides (top, right, bottom, left) in a consistent order.
+ *
+ * @param borders - The cell borders to hash
+ * @returns A deterministic hash string with format "t:[top];r:[right];b:[bottom];l:[left]"
+ *   where each border is hashed using hashBorderSpec. Empty string if borders is undefined.
+ * @example
+ * hashCellBorders(undefined) // ""
+ * hashCellBorders({ top: { style: 'single', width: 4, color: '000000' } }) // "t:[s:single,w:4,c:000000]"
+ */
+export declare const hashCellBorders: (borders: CellBorders | undefined) => string;
+/**
+ * Creates a deterministic hash string for paragraph-level attributes.
+ * This is used for cache invalidation when paragraph formatting changes
+ * (alignment, spacing, line height, indent, borders, shading, direction).
+ *
+ * The hash is deterministic to ensure consistent cache keys across different
+ * JS engine property enumeration orders.
+ *
+ * @param attrs - The paragraph attributes to hash
+ * @returns A deterministic hash string representing all paragraph attributes
+ */
+export declare const hashParagraphAttrs: (attrs: ParagraphAttrs | undefined) => string;
+/**
+ * Type guard to check if a run has a string property.
+ *
+ * @param run - The run to check
+ * @param prop - The property name to check
+ * @returns True if the run has the property and it's a string
+ */
+export declare const hasStringProp: (run: Run, prop: string) => run is Run & Record<string, string>;
+/**
+ * Type guard to check if a run has a number property.
+ *
+ * @param run - The run to check
+ * @param prop - The property name to check
+ * @returns True if the run has the property and it's a number
+ */
+export declare const hasNumberProp: (run: Run, prop: string) => run is Run & Record<string, number>;
+/**
+ * Type guard to check if a run has a boolean property.
+ *
+ * @param run - The run to check
+ * @param prop - The property name to check
+ * @returns True if the run has the property and it's a boolean
+ */
+export declare const hasBooleanProp: (run: Run, prop: string) => run is Run & Record<string, boolean>;
+/**
+ * Safely gets a string property from a run, with type narrowing.
+ *
+ * @param run - The run to get the property from
+ * @param prop - The property name
+ * @returns The string value or empty string if not present
+ */
+export declare const getRunStringProp: (run: Run, prop: string) => string;
+/**
+ * Safely gets a number property from a run, with type narrowing.
+ *
+ * @param run - The run to get the property from
+ * @param prop - The property name
+ * @returns The number value or 0 if not present
+ */
+export declare const getRunNumberProp: (run: Run, prop: string) => number;
+/**
+ * Safely gets a boolean property from a run, with type narrowing.
+ *
+ * @param run - The run to get the property from
+ * @param prop - The property name
+ * @returns The boolean value or false if not present
+ */
+export declare const getRunBooleanProp: (run: Run, prop: string) => boolean;

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

@@ -0,0 +1,152 @@
+/**
+ * Paragraph Line Cache
+ *
+ * Caches line break information for paragraphs to avoid expensive recalculation.
+ * Tracks dirty state to know when recalculation is needed after edits.
+ *
+ * @module paragraph-line-cache
+ */
+/**
+ * Information about a single line within a paragraph.
+ */
+export interface LineInfo {
+    /** Character offset within paragraph where line starts */
+    localStart: number;
+    /** Character offset within paragraph where line ends (exclusive) */
+    localEnd: number;
+    /** Width of the line in pixels */
+    width: number;
+    /** Height of the line in pixels */
+    height: number;
+}
+/**
+ * Cached line break information for a paragraph.
+ */
+export interface ParagraphLines {
+    /** PM document version when these lines were calculated */
+    version: number;
+    /** Array of lines in this paragraph */
+    lines: LineInfo[];
+    /** Total height of all lines */
+    totalHeight: number;
+    /** Whether this cache entry needs recalculation */
+    dirty: boolean;
+}
+/**
+ * ParagraphLineCache stores line break information for paragraphs.
+ *
+ * This cache is essential for performance when calculating cursor positions
+ * within multi-line paragraphs, as it avoids re-measuring line breaks.
+ */
+export declare class ParagraphLineCache {
+    private cache;
+    /**
+     * Gets cached lines for a paragraph.
+     *
+     * @param paragraphIndex - Index of the paragraph
+     * @returns Cached lines if available, undefined otherwise
+     */
+    getLines(paragraphIndex: number): ParagraphLines | undefined;
+    /**
+     * Sets lines for a paragraph.
+     *
+     * @param paragraphIndex - Index of the paragraph
+     * @param lines - Line information to cache
+     */
+    setLines(paragraphIndex: number, lines: ParagraphLines): void;
+    /**
+     * Marks a paragraph as dirty (needs recalculation).
+     *
+     * @param paragraphIndex - Index of the paragraph to mark dirty
+     */
+    markDirty(paragraphIndex: number): void;
+    /**
+     * Marks all paragraphs starting from a specific index as dirty.
+     *
+     * This is useful when a change affects multiple paragraphs.
+     *
+     * @param startIndex - First paragraph index to mark dirty
+     */
+    markDirtyFrom(startIndex: number): void;
+    /**
+     * Marks all paragraphs in a range as dirty.
+     *
+     * @param startIndex - First paragraph index to mark dirty (inclusive)
+     * @param endIndex - Last paragraph index to mark dirty (exclusive)
+     */
+    markDirtyRange(startIndex: number, endIndex: number): void;
+    /**
+     * Checks if a paragraph needs recalculation.
+     *
+     * @param paragraphIndex - Index of the paragraph to check
+     * @returns True if the paragraph is dirty or not cached
+     */
+    isDirty(paragraphIndex: number): boolean;
+    /**
+     * Finds the line containing a local character offset within a paragraph.
+     *
+     * @param paragraphIndex - Index of the paragraph
+     * @param localOffset - Character offset within the paragraph
+     * @returns Line info if found, null otherwise
+     */
+    findLineContaining(paragraphIndex: number, localOffset: number): LineInfo | null;
+    /**
+     * Gets the line index containing a local character offset.
+     *
+     * @param paragraphIndex - Index of the paragraph
+     * @param localOffset - Character offset within the paragraph
+     * @returns Line index if found, -1 otherwise
+     */
+    findLineIndex(paragraphIndex: number, localOffset: number): number;
+    /**
+     * Removes a paragraph from the cache.
+     *
+     * @param paragraphIndex - Index of the paragraph to remove
+     */
+    remove(paragraphIndex: number): void;
+    /**
+     * Clears the entire cache.
+     */
+    clear(): void;
+    /**
+     * Gets the number of cached paragraphs.
+     */
+    get size(): number;
+    /**
+     * Checks if a paragraph is cached.
+     *
+     * @param paragraphIndex - Index of the paragraph to check
+     * @returns True if the paragraph has cached lines
+     */
+    has(paragraphIndex: number): boolean;
+    /**
+     * Gets all cached paragraph indices.
+     *
+     * @returns Array of paragraph indices that are cached
+     */
+    getCachedIndices(): number[];
+    /**
+     * Gets cache statistics for debugging.
+     *
+     * @returns Statistics about the cache
+     */
+    getStats(): {
+        total: number;
+        dirty: number;
+        clean: number;
+    };
+    /**
+     * Validates cache entries for a specific version.
+     * Marks entries with mismatched versions as dirty.
+     *
+     * @param currentVersion - Current PM document version
+     * @returns Number of entries marked dirty
+     */
+    validateVersion(currentVersion: number): number;
+    /**
+     * Prunes dirty entries from the cache to free memory.
+     *
+     * @returns Number of entries removed
+     */
+    pruneDirty(): number;
+}