superdoc 2.2.1 → 2.3.0

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

@@ -0,0 +1,249 @@
+/**
+ * Performance Metrics Collector
+ *
+ * Comprehensive metrics collection system for typing performance monitoring.
+ * Tracks latency, duration, and rate metrics with statistical analysis.
+ *
+ * Features:
+ * - Per-metric sample collection with context
+ * - Statistical summaries (min, max, avg, percentiles)
+ * - Budget checking with configurable thresholds
+ * - Sample limit management to prevent memory bloat
+ * - Timer helpers for duration tracking
+ *
+ * Metrics tracked:
+ * - cursorUpdateLatency: Time to update cursor position (target <2ms)
+ * - p0LayoutDuration: P0 layout pass duration (target <5ms)
+ * - p1LayoutDuration: P1 layout pass duration (target <50ms)
+ * - workerRoundTrip: Worker message round-trip time (target <10ms)
+ * - layoutStaleness: Time layout is stale during typing (target <100ms)
+ * - geometryFallbackRate: Frequency of DOM measurement fallbacks
+ * - cacheMissRate: Cache miss frequency
+ * - droppedEvents: Number of dropped input events
+ *
+ * @module performance-metrics
+ */
+/**
+ * Individual metric sample with timestamp and optional context.
+ */
+export interface MetricSample {
+    /** Timestamp when sample was recorded (ms since epoch) */
+    timestamp: number;
+    /** Measured value */
+    value: number;
+    /** Optional contextual information about this sample */
+    context?: Record<string, unknown>;
+}
+/**
+ * Statistical summary of a metric's samples.
+ */
+export interface MetricSummary {
+    /** Number of samples */
+    count: number;
+    /** Minimum value */
+    min: number;
+    /** Maximum value */
+    max: number;
+    /** Average (mean) value */
+    avg: number;
+    /** 50th percentile (median) */
+    p50: number;
+    /** 95th percentile */
+    p95: number;
+    /** 99th percentile */
+    p99: number;
+}
+/**
+ * All typing performance metrics tracked by the system.
+ */
+export interface TypingPerfMetrics {
+    /** Cursor position update latency samples */
+    cursorUpdateLatency: MetricSample[];
+    /** P0 (critical) layout pass duration samples */
+    p0LayoutDuration: MetricSample[];
+    /** P1 (high priority) layout pass duration samples */
+    p1LayoutDuration: MetricSample[];
+    /** Web Worker round-trip time samples */
+    workerRoundTrip: MetricSample[];
+    /** Layout staleness duration samples */
+    layoutStaleness: MetricSample[];
+    /** Geometry fallback rate samples */
+    geometryFallbackRate: MetricSample[];
+    /** Cache miss rate samples */
+    cacheMissRate: MetricSample[];
+    /** Dropped input events samples */
+    droppedEvents: MetricSample[];
+}
+/**
+ * Budget violation report.
+ */
+export interface BudgetViolation {
+    /** Metric that exceeded budget */
+    metric: string;
+    /** Measured value that violated budget */
+    value: number;
+    /** Budget threshold that was exceeded */
+    budget: number;
+}
+/**
+ * Performance metrics collector for typing optimization monitoring.
+ *
+ * Collects samples for various metrics and provides statistical analysis
+ * with budget checking.
+ *
+ * @example
+ * ```typescript
+ * const metrics = new PerformanceMetricsCollector({
+ *   cursorUpdateLatency: 2,
+ *   p0LayoutDuration: 5,
+ * });
+ *
+ * // Record a sample
+ * metrics.record('cursorUpdateLatency', 1.5);
+ *
+ * // Use a timer
+ * const endTimer = metrics.startTimer('p0LayoutDuration');
+ * // ... perform layout ...
+ * endTimer();
+ *
+ * // Get summary
+ * const summary = metrics.getSummary('cursorUpdateLatency');
+ * console.log(`P95: ${summary.p95}ms`);
+ *
+ * // Check budgets
+ * const violations = metrics.checkBudgets();
+ * if (violations.length > 0) {
+ *   console.warn('Budget violations:', violations);
+ * }
+ * ```
+ */
+export declare class PerformanceMetricsCollector {
+    private metrics;
+    private maxSamples;
+    private budgets;
+    /**
+     * Creates a new performance metrics collector.
+     *
+     * @param budgets - Performance budgets for each metric (in ms or rate)
+     * @param maxSamples - Maximum samples to retain per metric (default: 1000)
+     */
+    constructor(budgets?: Partial<Record<keyof TypingPerfMetrics, number>>, maxSamples?: number);
+    /**
+     * Records a metric sample.
+     *
+     * Automatically manages sample buffer size by removing oldest samples
+     * when the limit is reached.
+     *
+     * @param metric - Metric key to record
+     * @param value - Measured value
+     * @param context - Optional contextual information
+     *
+     * @example
+     * ```typescript
+     * collector.record('cursorUpdateLatency', 1.8, {
+     *   position: 42,
+     *   direction: 'forward',
+     * });
+     * ```
+     */
+    record(metric: keyof TypingPerfMetrics, value: number, context?: Record<string, unknown>): void;
+    /**
+     * Starts a timer for duration metrics.
+     *
+     * Returns a function that, when called, records the elapsed time.
+     *
+     * @param metric - Duration metric to time
+     * @returns Function to call when operation completes
+     *
+     * @example
+     * ```typescript
+     * const endTimer = collector.startTimer('p0LayoutDuration');
+     * await performLayout();
+     * endTimer(); // Records elapsed time
+     * ```
+     */
+    startTimer(metric: keyof TypingPerfMetrics): () => void;
+    /**
+     * Gets statistical summary for a specific metric.
+     *
+     * @param metric - Metric key to summarize
+     * @returns Statistical summary including percentiles
+     *
+     * @example
+     * ```typescript
+     * const summary = collector.getSummary('cursorUpdateLatency');
+     * console.log(`P95 latency: ${summary.p95.toFixed(2)}ms`);
+     * ```
+     */
+    getSummary(metric: keyof TypingPerfMetrics): MetricSummary;
+    /**
+     * Gets summaries for all metrics.
+     *
+     * @returns Record of all metric summaries
+     *
+     * @example
+     * ```typescript
+     * const allSummaries = collector.getAllSummaries();
+     * for (const [metric, summary] of Object.entries(allSummaries)) {
+     *   console.log(`${metric}: ${summary.avg.toFixed(2)}ms avg`);
+     * }
+     * ```
+     */
+    getAllSummaries(): Record<keyof TypingPerfMetrics, MetricSummary>;
+    /**
+     * Checks if any metrics exceed their configured budgets.
+     *
+     * Uses P95 values for comparison against budgets.
+     *
+     * @returns Array of budget violations (empty if all within budget)
+     *
+     * @example
+     * ```typescript
+     * const violations = collector.checkBudgets();
+     * if (violations.length > 0) {
+     *   console.warn('Performance budgets exceeded:', violations);
+     *   // Consider triggering fallback
+     * }
+     * ```
+     */
+    checkBudgets(): BudgetViolation[];
+    /**
+     * Exports all raw metric data.
+     *
+     * Useful for debugging and offline analysis.
+     *
+     * @returns Complete metrics data structure
+     *
+     * @example
+     * ```typescript
+     * const data = collector.export();
+     * console.log(JSON.stringify(data, null, 2));
+     * ```
+     */
+    export(): TypingPerfMetrics;
+    /**
+     * Clears all recorded metrics.
+     *
+     * Resets all sample arrays to empty state.
+     *
+     * @example
+     * ```typescript
+     * collector.clear(); // Start fresh measurement period
+     * ```
+     */
+    clear(): void;
+}
+/**
+ * Global singleton performance metrics collector instance.
+ *
+ * Configured with default performance budgets for typing optimization.
+ *
+ * @example
+ * ```typescript
+ * import { perfMetrics } from './performance-metrics.js';
+ *
+ * perfMetrics.record('cursorUpdateLatency', 1.5);
+ * const summary = perfMetrics.getSummary('cursorUpdateLatency');
+ * ```
+ */
+export declare const perfMetrics: PerformanceMetricsCollector;

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

@@ -0,0 +1,188 @@
+/**
+ * ProseMirror DOM Fallback
+ *
+ * Provides cursor positioning using ProseMirror's native DOM coordinate system
+ * when layout data is stale. Transforms PM's coordinates into paginated space.
+ *
+ * This is a fallback mechanism used when:
+ * - Layout is currently being recalculated
+ * - Layout version is behind PM document version
+ * - Need immediate cursor positioning before layout completes
+ *
+ * @module pm-dom-fallback
+ */
+/**
+ * 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 (optional for cursor, required for selections) */
+    width?: number;
+}
+/**
+ * Page transformation information for converting coordinates.
+ */
+export interface PageTransform {
+    /** Index of the page */
+    pageIndex: number;
+    /** X offset of the page in container */
+    x: number;
+    /** Y offset of the page in container */
+    y: number;
+    /** Scale factor applied to the page */
+    scale: number;
+    /**
+     * Height of the page in pixels (before scaling).
+     *
+     * **When Present:**
+     * - The page has a known, measured height (e.g., from layout calculation or DOM measurement)
+     * - Used to calculate page bottom boundary: pageBottom = y + height / scale
+     * - Enables accurate hit testing when determining which page contains a cursor
+     *
+     * **When Absent (undefined):**
+     * - Page height is unknown or not yet calculated
+     * - Falls back to a conservative default (e.g., 1000px) for coordinate transformation
+     * - May occur during initial layout before page heights are measured
+     * - May occur for pages that haven't been rendered yet
+     *
+     * **Impact on Cursor Visibility:**
+     * When height is absent, coordinate mapping uses a fallback value which may be incorrect
+     * for unusually tall or short pages. This can affect:
+     * - Cursor positioning accuracy when layout is stale
+     * - Page boundary detection for multi-page cursors
+     * - Scroll-to-cursor behavior near page boundaries
+     *
+     * **Recommendation:**
+     * Always provide height when available to ensure accurate cursor positioning. The fallback
+     * is safe but may result in minor positioning errors for non-standard page sizes.
+     */
+    height?: number;
+}
+/**
+ * Minimal interface for ProseMirror EditorView.
+ * Only includes the methods we need for fallback positioning.
+ */
+export interface PmEditorView {
+    /**
+     * Get DOM coordinates for a PM position.
+     * Returns null if position is not currently rendered.
+     */
+    coordsAtPos(pos: number): {
+        left: number;
+        top: number;
+        bottom: number;
+    } | null;
+    /**
+     * Get the DOM node for the editor.
+     */
+    dom: HTMLElement;
+}
+/**
+ * PmDomFallback provides cursor positioning using ProseMirror's DOM
+ * coordinate system when layout is stale.
+ *
+ * This class bridges between PM's viewport-relative coordinates and
+ * the paginated layout coordinate system.
+ *
+ * Usage:
+ * ```typescript
+ * const fallback = new PmDomFallback(pmView, getPageTransforms);
+ *
+ * // When layout is stale, use DOM-based positioning
+ * const cursorRect = fallback.getCursorRect(pmPos);
+ * if (cursorRect) {
+ *   renderer.render(cursorRect);
+ * }
+ * ```
+ */
+export declare class PmDomFallback {
+    private pmView;
+    private getPageTransforms;
+    /**
+     * Creates a new PmDomFallback instance.
+     *
+     * @param pmView - ProseMirror editor view
+     * @param getPageTransforms - Function to get current page transformations
+     */
+    constructor(pmView: PmEditorView, getPageTransforms: () => PageTransform[]);
+    /**
+     * Get cursor rect using PM's coordsAtPos, transformed to page space.
+     * Use when layout is stale.
+     *
+     * @param pmPos - ProseMirror position
+     * @returns Cursor rectangle in page space, or null if position not rendered
+     */
+    getCursorRect(pmPos: number): CursorRect | null;
+    /**
+     * Map PM coords to page-local coordinates.
+     *
+     * Takes viewport-relative coordinates from PM and transforms them
+     * into page-local coordinates accounting for:
+     * - Page positioning in the layout
+     * - Zoom/scale transformations
+     * - Multi-page layout
+     *
+     * **Behavioral Change (Selection Polish):**
+     * This function now returns null when the cursor is outside all pages, rather than
+     * falling back to the first page. This change improves cursor positioning accuracy
+     * when layout is stale.
+     *
+     * **Why null is preferred over fallback-to-first-page:**
+     * 1. **Accuracy:** When layout is stale, showing no cursor is better than showing it
+     *    at the wrong position. A missing cursor prompts layout refresh; a misplaced cursor
+     *    causes user confusion and incorrect editing.
+     * 2. **Temporary State:** Layout staleness is temporary - typically resolves within
+     *    100-200ms. Hiding the cursor briefly is less disruptive than showing it incorrectly.
+     * 3. **User Expectations:** Users expect the cursor to appear where they clicked. If we
+     *    can't determine that position accurately, hiding it is more honest than guessing.
+     * 4. **Prevents Drift:** Fallback positioning can cause selection drift where the visual
+     *    cursor and actual PM selection position diverge, leading to incorrect edits.
+     *
+     * **Impact on Cursor Visibility:**
+     * - Cursor may briefly disappear during layout recalculation (typically < 200ms)
+     * - Cursor will not appear when clicking in gaps between pages (expected behavior)
+     * - Cursor will not appear for positions outside the document bounds (expected behavior)
+     * - When layout catches up, cursor will reappear at the correct position
+     *
+     * **Migration Notes:**
+     * Code relying on the old fallback behavior should handle null returns gracefully:
+     * ```typescript
+     * const cursorRect = fallback.getCursorRect(pmPos);
+     * if (cursorRect) {
+     *   renderer.render(cursorRect);
+     * } else {
+     *   renderer.hide(); // Cursor is outside all pages - hide it
+     * }
+     * ```
+     *
+     * @param coords - PM viewport coordinates
+     * @returns Cursor rectangle in page space, or null if outside all pages (including gaps)
+     */
+    mapToPageSpace(coords: {
+        left: number;
+        top: number;
+        bottom: number;
+    }): CursorRect | null;
+    /**
+     * Check if a PM position is currently visible in the viewport.
+     *
+     * @param pmPos - ProseMirror position
+     * @returns True if position is rendered and visible
+     */
+    isPositionVisible(pmPos: number): boolean;
+    /**
+     * Get selection rectangles using PM's DOM for a range.
+     *
+     * @param from - Start PM position
+     * @param to - End PM position
+     * @returns Array of cursor rectangles for the selection
+     */
+    getSelectionRects(from: number, to: number): CursorRect[];
+}

package/dist/layout-engine/layout-bridge/src/pm-position-validator.d.ts

@@ -0,0 +1,100 @@
+import { FlowBlock } from '../../contracts/src/index.js';
+/**
+ * Result of PM position validation.
+ */
+export interface ValidationResult {
+    /** Whether validation passed */
+    valid: boolean;
+    /** Errors found during validation */
+    errors: ValidationError[];
+    /** Fraction of document covered by valid PM positions (0-1) */
+    coverage: number;
+}
+/**
+ * An error in PM position continuity.
+ */
+export interface ValidationError {
+    /** Type of error */
+    type: 'gap' | 'overlap' | 'out_of_order' | 'missing';
+    /** Index of block where error occurred */
+    blockIndex: number;
+    /** Expected position range */
+    expected: {
+        start: number;
+        end: number;
+    };
+    /** Actual position range */
+    actual: {
+        start: number;
+        end: number;
+    };
+}
+/**
+ * PmPositionValidator ensures PM position continuity across document blocks.
+ */
+export declare class PmPositionValidator {
+    /**
+     * Validate pmStart/pmEnd continuity across all blocks.
+     *
+     * @param blocks - Array of flow blocks to validate
+     * @returns Validation result with errors and coverage info
+     */
+    validate(blocks: FlowBlock[]): ValidationResult;
+    /**
+     * Validate a subset of blocks for incremental validation.
+     *
+     * @param blocks - Array of flow blocks
+     * @param startIndex - Starting block index (inclusive)
+     * @param endIndex - Ending block index (exclusive)
+     * @returns Validation result
+     */
+    validateRange(blocks: FlowBlock[], startIndex: number, endIndex: number): ValidationResult;
+    /**
+     * Attempt to repair gaps in pmStart/pmEnd by interpolating missing positions.
+     *
+     * @param blocks - Array of flow blocks
+     * @param errors - Validation errors to repair
+     * @returns Repaired blocks (new array, original unmodified)
+     */
+    repair(blocks: FlowBlock[], errors: ValidationError[]): FlowBlock[];
+    /**
+     * Get coverage report for complex features.
+     *
+     * @param blocks - Array of flow blocks
+     * @returns Coverage statistics for complex features
+     */
+    getFeatureCoverage(blocks: FlowBlock[]): {
+        trackedChanges: {
+            total: number;
+            covered: number;
+        };
+        tables: {
+            total: number;
+            covered: number;
+        };
+        embeds: {
+            total: number;
+            covered: number;
+        };
+        tokens: {
+            total: number;
+            covered: number;
+        };
+    };
+    /**
+     * Extract pmStart from a block.
+     *
+     * @param block - Flow block
+     * @returns PM start position or undefined
+     * @private
+     */
+    private getBlockPmStart;
+    /**
+     * Extract pmEnd from a block.
+     *
+     * @param block - Flow block
+     * @returns PM end position or undefined
+     * @private
+     */
+    private getBlockPmEnd;
+}

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

@@ -0,0 +1,167 @@
+import { FlowBlock, Layout, Page, Measure, Fragment, DrawingFragment, ImageFragment, Line, TableFragment, TableBlock, TableMeasure, ParagraphBlock, ParagraphMeasure, TextboxDrawing } from '../../contracts/src/index.js';
+import { PageGeometryHelper } from './page-geometry-helper.js';
+export type Point = {
+    x: number;
+    y: number;
+};
+export type PageHit = {
+    pageIndex: number;
+    page: Layout['pages'][number];
+};
+export type FragmentHit = {
+    fragment: Fragment;
+    block: FlowBlock;
+    measure: Measure;
+    pageIndex: number;
+    pageY: number;
+};
+export type PositionHit = {
+    pos: number;
+    layoutEpoch: number;
+    blockId: string;
+    pageIndex: number;
+    column: number;
+    lineIndex: number;
+};
+/**
+ * Result of hit-testing a table fragment.
+ * Contains all information needed to identify the cell and paragraph at a click point.
+ */
+export type TableHitResult = {
+    /** The table fragment that was hit */
+    fragment: TableFragment;
+    /** The table block from the document structure */
+    block: TableBlock;
+    /** The table measurement data */
+    measure: TableMeasure;
+    /** Index of the page containing the hit */
+    pageIndex: number;
+    /** Row index of the hit cell (0-based) */
+    cellRowIndex: number;
+    /** Column index of the hit cell (0-based) */
+    cellColIndex: number;
+    /** The paragraph block inside the cell */
+    cellBlock: ParagraphBlock;
+    /** Measurement data for the paragraph inside the cell */
+    cellMeasure: ParagraphMeasure;
+    /** X coordinate relative to the cell content area */
+    localX: number;
+    /** Y coordinate relative to the cell content area */
+    localY: number;
+    /**
+     * Cumulative line count of preceding paragraph blocks in this cell.
+     * Used by callers to compute the hit paragraph's local first-line flag
+     * when the row continues from a prior page: `isFirstLineOfParagraph` is
+     * `lineIndex === 0 && max(0, cellLineStart - blockStartGlobal) === 0`,
+     * matching `renderTableCell.ts`'s `localStartLine` computation.
+     */
+    blockStartGlobal: number;
+};
+export type TextboxHitResult = {
+    /** The textbox drawing fragment that was hit */
+    fragment: DrawingFragment;
+    /** The textbox drawing block from the document structure */
+    block: Extract<FlowBlock, {
+        kind: 'drawing';
+        drawingKind: 'textboxShape';
+    }>;
+    /** The drawing measurement data */
+    measure: Measure;
+    /** Index of the page containing the hit */
+    pageIndex: number;
+    /** The paragraph block inside the textbox */
+    contentBlock: ParagraphBlock;
+    /** Measurement data for the paragraph inside the textbox */
+    contentMeasure: ParagraphMeasure;
+    /** Paragraph index inside block.contentBlocks */
+    paragraphIndex: number;
+    /** X coordinate relative to the textbox content area */
+    localX: number;
+    /** Y coordinate relative to the paragraph content area */
+    localY: number;
+    /** Cumulative line count of preceding textbox paragraphs */
+    blockStartGlobal: number;
+};
+type AtomicFragment = DrawingFragment | ImageFragment;
+export type GeometryPageHint = {
+    pageIndex: number;
+    pageRelativeY?: number;
+};
+export type ClickToPositionGeometryOptions = {
+    geometryHelper?: PageGeometryHelper;
+    pageHint?: GeometryPageHint;
+};
+export declare const isAtomicFragment: (fragment: Fragment) => fragment is AtomicFragment;
+export declare const getAtomicPmRange: (fragment: AtomicFragment, block: FlowBlock) => {
+    pmStart?: number;
+    pmEnd?: number;
+};
+export declare const isRtlBlock: (block: FlowBlock) => boolean;
+export declare const determineColumn: (layout: Layout, fragmentX: number, page?: Page, fragmentY?: number) => number;
+export declare const determineTableColumn: (layout: Layout, fragment: TableFragment, page?: Page) => number;
+/**
+ * Finds the line index at a given Y offset within a set of lines.
+ */
+export declare const findLineIndexAtY: (lines: Line[], offsetY: number, fromLine: number, toLine: number) => number | null;
+/**
+ * Maps an X coordinate within a line to a ProseMirror position.
+ */
+export declare const mapPointToPm: (block: FlowBlock, line: Line, x: number, isRTL: boolean, availableWidthOverride?: number, alignmentOverride?: string) => number | null;
+/**
+ * Finds the nearest paragraph or atomic fragment to a point on a page.
+ */
+export declare function snapToNearestFragment(pageHit: PageHit, blocks: FlowBlock[], measures: Measure[], pageRelativePoint: Point): FragmentHit | null;
+export declare function findBlockIndexByFragmentId(blocks: FlowBlock[], fragmentBlockId: string, targetPmRange?: {
+    from: number;
+    to: number;
+}): number;
+/**
+ * Calculates cumulative Y position for a page (fallback when no geometry helper provided).
+ */
+export declare const calculatePageTopFallback: (layout: Layout, pageIndex: number) => number;
+/**
+ * Find the page hit given layout and a coordinate relative to the layout container.
+ * Accounts for gaps between pages when calculating page boundaries.
+ */
+export declare function hitTestPage(layout: Layout, point: Point, geometryHelper?: PageGeometryHelper): PageHit | null;
+/**
+ * Hit-test fragments within a page for a given point (page-relative coordinates).
+ */
+export declare function hitTestFragment(layout: Layout, pageHit: PageHit, blocks: FlowBlock[], measures: Measure[], point: Point): FragmentHit | null;
+export declare const hitTestAtomicFragment: (pageHit: PageHit, blocks: FlowBlock[], measures: Measure[], point: Point) => FragmentHit | null;
+/**
+ * Hit-test table fragments to find the cell and paragraph at a click point.
+ */
+export declare const hitTestTableFragment: (pageHit: PageHit, blocks: FlowBlock[], measures: Measure[], point: Point) => TableHitResult | null;
+/**
+ * Walk the paragraph content of an already-resolved textbox fragment and return the
+ * paragraph hit at `point`. Callers that already hold a resolved fragment/block should
+ * call this directly instead of {@link hitTestTextboxFragment}, which would otherwise
+ * re-scan every page fragment and could resolve a different textbox for overlapping shapes.
+ */
+export declare const resolveTextboxContentHit: (fragment: DrawingFragment, block: TextboxDrawing, measure: Measure, pageIndex: number, point: Point) => TextboxHitResult | null;
+/**
+ * Hit-test textbox drawing fragments to find the paragraph at a click point.
+ * Scans all page fragments by point — when the fragment and block are already resolved,
+ * call {@link resolveTextboxContentHit} directly to avoid resolving a different textbox
+ * for overlapping shapes.
+ */
+export declare const hitTestTextboxFragment: (pageHit: PageHit, blocks: FlowBlock[], measures: Measure[], point: Point) => TextboxHitResult | null;
+/**
+ * Enriches a DOM-resolved PM position into a full PositionHit by searching layout
+ * metadata. Pure data lookup — no DOM reads.
+ *
+ * Extracted from the DOM-success path of the original `clickToPosition()`.
+ */
+export declare function resolvePositionHitFromDomPosition(layout: Layout, blocks: FlowBlock[], measures: Measure[], domPos: number, layoutEpoch: number): PositionHit;
+/**
+ * Geometry-only hit testing. DOM-free — no `elementsFromPoint`, no `getBoundingClientRect`.
+ *
+ * When `options.pageHint` is provided, uses the hint's page index and optional
+ * page-relative Y instead of recomputing from geometry. This allows callers that
+ * have already done DOM page detection to pass their result through.
+ *
+ * Extracted from the geometry fallback path of the original `clickToPosition()`.
+ */
+export declare function clickToPositionGeometry(layout: Layout, blocks: FlowBlock[], measures: Measure[], containerPoint: Point, options?: ClickToPositionGeometryOptions): PositionHit | null;
+export {};