superdoc 2.2.1 → 2.3.0

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

@@ -0,0 +1,390 @@
+import { PageCheckpointDependencyClass, FlowBlock, Layout, Measure, HeaderFooterLayout, ParagraphBlock, ParagraphMeasure, ColumnLayout } from '../../contracts/src/index.js';
+import { FontMeasureContext } from '../../../shared/font-system/src/index.js';
+import { LayoutOptions, HeaderFooterConstraints } from '../../layout-engine/src/index.js';
+import { computeDirtyRegions } from './diff.js';
+import { MeasureCache } from './cache.js';
+import { HeaderFooterBatch } from './layoutHeaderFooter.js';
+export type HeaderFooterMeasureFn = (block: FlowBlock, constraints: {
+    maxWidth: number;
+    maxHeight: number;
+}) => Promise<Measure>;
+export type HeaderFooterLayoutResult = {
+    kind: 'header' | 'footer';
+    type: keyof HeaderFooterBatch;
+    layout: HeaderFooterLayout;
+    blocks: FlowBlock[];
+    measures: Measure[];
+    /** Effective layout width when table grid widths exceed section content width (SD-1837). */
+    effectiveWidth?: number;
+};
+/**
+ * SD-3432: the footnote reserve fixed point of a completed layout run, used to
+ * warm-start the next run's convergence loop. The seed is ONLY a starting
+ * vector — every run re-validates it through the full convergence machinery
+ * (pass-1 relayout + plan stability + grow/tighten + widow + trials), so a
+ * stale or wrong seed costs extra passes, never correctness. Captured only
+ * when the run ended on an EXACT fixed point (plan === applied reserves), so
+ * an unchanged document warm-validates in a single relayout.
+ *
+ * Guards carried with the vector (fontSignature / measurement constraints)
+ * exist purely to discard pathological starting vectors after zoom or font
+ * changes; they carry no document identity (no footnote ids, no content
+ * hashes — see the SD-3418 post-mortem for why identity keys are forbidden).
+ */
+export type FootnoteReserveSeed = {
+    reserves: number[];
+    /** Sparse page indexes that held a reserve, ledger, or injected note slice. */
+    notePageIndexes?: number[];
+    separatorSpacingBefore: number | undefined;
+    fontSignature: string;
+    measurementWidth: number;
+    measurementHeight: number;
+    /** Exact note measurement width retained with unchanged section geometry. */
+    footnoteMeasurementWidth?: number;
+    /** Section-column inputs used to derive the retained note measurement width. */
+    sectionColumnsByIndex?: Map<number, ColumnLayout>;
+    /** Exact note block objects retained by the host's authoritative note-bundle proof. */
+    noteBlocksByBlockId?: Map<string, FlowBlock>;
+    /** Measures paired with `noteBlocksByBlockId`; object identity is revalidated before reuse. */
+    noteMeasuresByBlockId?: Map<string, Measure>;
+    noteBodyHeightById?: Map<string, number>;
+    noteFirstLineHeightById?: Map<string, number>;
+};
+export type IncrementalLayoutResult = {
+    layout: Layout;
+    measures: Measure[];
+    dirty: ReturnType<typeof computeDirtyRegions>;
+    headers?: HeaderFooterLayoutResult[];
+    footers?: HeaderFooterLayoutResult[];
+    /**
+     * Extra blocks/measures that should be added to the painter's lookup table.
+     * Used for rendering non-body fragments injected into the layout (e.g., footnotes).
+     */
+    extraBlocks?: FlowBlock[];
+    extraMeasures?: Measure[];
+    /**
+     * SD-3432: next-run warm-start seed for the footnote convergence loop.
+     * Null when this run did not end on an exact footnote fixed point (or laid
+     * out no footnotes) — the next run then starts cold.
+     */
+    footnoteReserveSeed?: FootnoteReserveSeed | null;
+    layoutReuse?: IncrementalLayoutReuseSummary;
+    measureReuse?: {
+        mode: 'full-scan' | 'proved-dirty-only';
+        blocksMeasured: number;
+        measuresAdopted: number;
+        reason: string;
+    };
+    /**
+     * Per-call bridge-owned timing. This is returned with the canonical layout
+     * result so callers do not need to read the process-global metrics collector.
+     * Substage fields are non-overlapping for the top-level reconciliation:
+     * `measureTotalMs` includes cache lookup and actual measurement details,
+     * and `pageTokenTotalMs` includes token remeasure/relayout details.
+     */
+    bridgeTiming: IncrementalLayoutBridgeTiming;
+};
+export type IncrementalLayoutBridgeTiming = {
+    totalMs: number;
+    inputPreparationMs: number;
+    measureTotalMs: number;
+    /** Union wall time spent inside caller-owned measure callbacks across body and furniture. */
+    measureCallbackWallMs: number;
+    measureCacheLookupMs: number;
+    measureActualMs: number;
+    headerFooterPreLayoutMs: number;
+    headerPreLayoutMs: number;
+    footerPreLayoutMs: number;
+    warmStartPreparationMs: number;
+    /** Wall time inside the initial body `layoutDocument` invocation only. */
+    layoutDocumentMs: number;
+    /** Initial body-layout wrapper work outside `layoutDocument` (proof, slice, convergence, splice). */
+    layoutReuseOrchestrationMs: number;
+    paginationMs: number;
+    pageTokenSetupMs: number;
+    pageTokenTotalMs: number;
+    pageTokenRemeasureMs: number;
+    pageTokenRelayoutMs: number;
+    footnoteMs: number;
+    numberingMs: number;
+    finalHeaderFooterMs: number;
+    layoutExposureMs: number;
+    unattributedMs: number;
+    counters: {
+        blocksRead: number;
+        cacheHits: number;
+        cacheMisses: number;
+        measuresAdopted: number;
+        pagesPaginated: number | null;
+        pagesSplicedByReuse: number;
+    };
+};
+/**
+ * Structural discriminator for what happened to the document tail (SD-3772
+ * D5). Consumers branch on THIS, never on the diagnostic `reason` string:
+ * - `none`: no retained tail exists (full recompute).
+ * - `adopted-source-tail`: a convergence page was proved and the source tail
+ *   was adopted; `tailAdoption` is non-null and range-valid.
+ * - `relaid-to-document-end`: the bounded slice reached the exact end of the
+ *   document and every terminal page was freshly paginated; `tailAdoption`
+ *   is null. Every other combination fails closed before publication.
+ */
+export type IncrementalLayoutTailDisposition = 'none' | 'adopted-source-tail' | 'relaid-to-document-end';
+export type IncrementalLayoutReuseSummary = {
+    mode: 'full' | 'prefix-resume' | 'tail-splice';
+    /** Diagnostic label only; never drives product behavior (SD-3772 D5). */
+    reason: string;
+    tailDisposition: IncrementalLayoutTailDisposition;
+    checkpointPageIndex: number | null;
+    /** Last prior page that can be affected by the dirty content/dependencies. */
+    affectedFrontierPageIndex: number | null;
+    /** Last source-generation page covered by the dirty content. */
+    sourceAffectedFrontierPageIndex: number | null;
+    convergencePageIndex: number | null;
+    /** Source-generation page adopted at convergence (may differ after page-count shifts). */
+    sourceConvergencePageIndex: number | null;
+    pagesPaginated: number | null;
+    pagesSplicedByReuse: number;
+    /**
+     * Proof for a retained tail. Pages in this interval remain byte-for-byte
+     * retained; consumers apply the position transforms only when a page enters
+     * the active paint window.
+     */
+    tailAdoption: IncrementalLayoutTailAdoption | null;
+};
+/**
+ * Exact dirty-measure proof that is useful even when pagination reuse is
+ * independently vetoed. Keeping it separate prevents a global layout
+ * dependency from forcing an O(document) measurement-preparation scan.
+ */
+export type IncrementalMeasureReuseProof = Pick<IncrementalLayoutReuseOptions, 'provedDirtyRegion' | 'dependencyProof' | 'previousBlockIndexById' | 'currentBlockIndexById' | 'provedDirtyMeasureConstraints'>;
+export type LayoutPositionTransform = {
+    atChar: number;
+    delta: number;
+};
+export type IncrementalSectionPageNumberTransform = {
+    /** Section whose retained pages need rebasing before its next boundary. */
+    sectionIndex: number;
+    /** Difference between target and source section-relative page positions. */
+    delta: number;
+};
+export type IncrementalLayoutTailAdoption = {
+    startPageIndex: number;
+    endPageIndexExclusive: number;
+    sourcePageStartIndex: number;
+    sourcePageEndIndexExclusive: number;
+    pageIndexDelta: number;
+    sectionPageNumberTransform: IncrementalSectionPageNumberTransform | null;
+    sourceLayoutEpoch: number | null;
+    positionTransforms: readonly LayoutPositionTransform[];
+    /** Lazy old->current block-id rekeys for an ordinal-changing structural splice. */
+    blockIdRewrites?: ReadonlyMap<string, string> | null;
+};
+type IncrementalPaginationProofBase = {
+    blockIdsUnchanged: true;
+    blockIdsUnique: true;
+    renderInputsUnchanged: true;
+    /** The retained dependency scan proved that no body or furniture PAGE_REF token exists. */
+    pageReferencesAbsent: boolean;
+    pageReferenceDependencyClosure?: {
+        referenceBlockIds: readonly string[];
+        targetBookmarkIds: readonly string[];
+    };
+};
+export type IncrementalPaginationProof = IncrementalPaginationProofBase & ({
+    profile: 'single-section-local-text';
+    globalDependenciesAbsent: true;
+    globalDependenciesFencedByDocumentStart?: never;
+} | {
+    /** Stable dependency-rich documents must replay from a page-zero checkpoint. */
+    profile: 'document-start-local-text';
+    globalDependenciesAbsent: false;
+    globalDependenciesFencedByDocumentStart: true;
+    multiColumnSectionsProvedNonBalanceable: true;
+} | {
+    /** Stable dependency-rich documents may replay from an engine-seeded page checkpoint. */
+    profile: 'page-checkpoint-local-text';
+    globalDependenciesAbsent: false;
+    globalDependenciesFencedByPageCheckpoint: true;
+    admittedDependencyClasses: readonly PageCheckpointDependencyClass[];
+    localKeepDependencyClosure?: {
+        checkpointPageIndex: number;
+        checkpointBlockId: string | null;
+        predecessorBlockId: string | null;
+    };
+    /**
+     * SD-3772 D1: the host proved (via the shared
+     * `hasGenuinelyUnequalExplicitColumnWidths` predicate) that no
+     * potentially balanceable multi-column section exists anywhere in the
+     * retained document. Balancing is a post-pagination finalizer that a
+     * mid-section checkpoint cannot seed; a packet without this proof
+     * fails validation and takes the canonical full layout.
+     */
+    multiColumnSectionsProvedNonBalanceable: true;
+});
+export type IncrementalLayoutReuseOptions = {
+    previousLayout: Layout | null;
+    /** Epoch that produced every retained page/index/key in this reuse packet. */
+    retainedMetadataSourceLayoutEpoch?: number | null;
+    previousPageStartKeys: readonly string[] | null;
+    previousBlockPageIndex: Map<string, {
+        firstPage: number;
+        lastPage: number;
+    }> | null;
+    maxRelaidPages?: number;
+    requireDocumentStartCheckpoint?: boolean;
+    allowBlockIdChurn?: boolean;
+    pmShift?: LayoutPositionTransform | null;
+    /** Exact dirty identities from the commit envelope when already available. */
+    dirtyBlockIds?: readonly string[];
+    /** Exact retained block index, required to align a structural ±1 measure plane. */
+    previousBlockIndexById?: ReadonlyMap<string, number> | null;
+    /** Optional retained ordinal index, avoiding a whole-array checkpoint lookup. */
+    currentBlockIndexById?: ReadonlyMap<string, number> | null;
+    /** Inverse identity proof for ordinal-scoped ids shifted by a structural edit. */
+    blockIdRewrites?: {
+        previousToCurrent: ReadonlyMap<string, string>;
+        currentToPrevious: ReadonlyMap<string, string>;
+    } | null;
+    /** Retained dependency proof; avoids rescanning every block on a warm edit. */
+    dependencyProof?: IncrementalPaginationProof | null;
+    /** Exact retained dirty analysis; bypasses computeDirtyRegions on a proved warm edit. */
+    provedDirtyRegion?: ReturnType<typeof computeDirtyRegions> | null;
+    /** Cold-observed exact section constraints for each dirty block. */
+    provedDirtyMeasureConstraints?: ReadonlyMap<string, {
+        maxWidth: number;
+        maxHeight: number;
+    }> | null;
+    /** Retained key index used for O(1) convergence candidate lookup. */
+    previousPageStartKeyIndex?: ReadonlyMap<string, readonly number[]> | null;
+    /**
+     * Host-proved note-only refresh. Body ids are unchanged reference anchors;
+     * only the named note projections may differ from the retained note plane.
+     */
+    provedNoteOnlyRefresh?: {
+        noteIds: readonly string[];
+        bodyReferenceBlockIds: readonly string[];
+    };
+};
+export declare const measureCache: MeasureCache<Measure>;
+/**
+ * Reset every module-global cache this bridge holds (measure cache,
+ * header/footer measure cache, header/footer invalidation state). A clean
+ * cold-recompute oracle must start from exactly the state a fresh worker
+ * would have; clearing only the measure cache leaves warm header/footer
+ * state that can legally shift page geometry.
+ */
+export declare function clearIncrementalModuleState(): void;
+export interface IncrementalLayoutExecutionControl {
+    /** Budget-aware host-task yield; may resolve immediately. */
+    yieldToHost?: () => Promise<void>;
+    /** Checkpoint cadence for the block measurement loop. Defaults to 32. */
+    yieldEveryBlocks?: number;
+}
+export declare function incrementalLayout(previousBlocks: FlowBlock[], _previousLayout: Layout | null, nextBlocks: FlowBlock[], options: LayoutOptions, measureBlock: (block: FlowBlock, constraints: {
+    maxWidth: number;
+    maxHeight: number;
+}) => Promise<Measure>, headerFooter?: {
+    headerBlocks?: HeaderFooterBatch;
+    footerBlocks?: HeaderFooterBatch;
+    headerBlocksByRId?: Map<string, FlowBlock[]>;
+    footerBlocksByRId?: Map<string, FlowBlock[]>;
+    constraints: HeaderFooterConstraints;
+    measure?: HeaderFooterMeasureFn;
+    /**
+     * When `false`, header/footer NUMPAGES/SECTIONPAGES fields keep their
+     * source-cached DOCX text (em dash when absent) instead of resolving to
+     * the current — possibly partial — page total. Defaults to exact.
+     */
+    pageCountFieldsExact?: boolean;
+    /**
+     * @deprecated Compatibility-only. Measurement identity is derived from
+     * content, constraints, font signature, and page-count field mode; render
+     * generation must not invalidate unchanged header/footer measurements.
+     */
+    cacheGeneration?: number;
+}, previousMeasures?: Measure[] | null, fontRuntime?: {
+    fontContext?: FontMeasureContext;
+    previousFontSignature?: string;
+}, warmStart?: {
+    footnoteReserveSeed?: FootnoteReserveSeed | null;
+    /** Host proved the authoritative note projection bundle was retained exactly. */
+    noteMeasurePlaneRetainedExact?: true;
+    /** Extra note/decorative planes paired with the retained note bundle. */
+    retainedFootnoteExtras?: {
+        blocks: FlowBlock[];
+        measures: Measure[];
+    };
+}, layoutReuse?: IncrementalLayoutReuseOptions, measureReuseProof?: IncrementalMeasureReuseProof, execution?: IncrementalLayoutExecutionControl): Promise<IncrementalLayoutResult>;
+/**
+ * Normalizes a margin value, using a fallback for undefined or non-finite values.
+ * Prevents NaN content sizes when margin properties are partially defined.
+ *
+ * @param value - The margin value to normalize (may be undefined)
+ * @param fallback - The default margin value to use if value is invalid
+ * @returns The normalized margin value (guaranteed to be finite)
+ */
+export declare const normalizeMargin: (value: number | undefined, fallback: number) => number;
+/**
+ * Walks table blocks (including nested tables) and computes `contentMeasures` for any
+ * `textboxShape` drawings found in table cells. Stores results directly on the block so
+ * the painter can read them without a `DrawingFragment` (table-cell drawings have none).
+ */
+export declare function hydrateTableTextboxMeasures(blocks: FlowBlock[], remeasure: (block: ParagraphBlock, maxWidth: number) => ParagraphMeasure): void;
+/**
+ * Resolves the maximum measurement constraints (width and height) needed for measuring blocks
+ * across all sections in a document.
+ *
+ * This function scans the entire document (including all section breaks) to determine the
+ * widest column configuration and tallest content area that will be encountered during layout.
+ * The result is used for cache invalidation and backward-compatible comparison (see
+ * `canReusePreviousMeasures`). Actual per-block measurement uses `computePerSectionConstraints`.
+ *
+ * Algorithm:
+ * 1. Start with base content width/height from options.pageSize and options.margins
+ * 2. Calculate base column width from options.columns (if multi-column)
+ * 3. Scan all sectionBreak blocks to find maximum column width and content height
+ * 4. For each section: compute content area, calculate column width, track maximum
+ * 5. Return the widest column width and tallest content height found
+ *
+ * Column width calculation:
+ * - Single column: contentWidth (no gap subtraction)
+ * - Multi-column: (contentWidth - totalGap) / columnCount
+ * - Total gap = gap * (columnCount - 1)
+ *
+ * @param options - Layout options containing default page size, margins, and columns
+ * @param blocks - Optional array of flow blocks to scan for section breaks
+ *   If not provided, only base constraints from options are used
+ * @returns Object containing:
+ *   - measurementWidth: Maximum column width in pixels (guaranteed positive)
+ *   - measurementHeight: Maximum content height in pixels (guaranteed positive)
+ *
+ * @throws Error if resolved constraints are non-positive (indicates invalid configuration)
+ *
+ * @example
+ * ```typescript
+ * // Document with two sections: single column and 2-column
+ * const options = {
+ *   pageSize: { w: 612, h: 792 }, // Letter size
+ *   margins: { top: 72, right: 72, bottom: 72, left: 72 },
+ *   columns: { count: 1, gap: 0 }
+ * };
+ * const blocks = [
+ *   // ... content blocks ...
+ *   {
+ *     kind: 'sectionBreak',
+ *     columns: { count: 2, gap: 48 },
+ *     // ... other section properties ...
+ *   }
+ * ];
+ * const constraints = resolveMeasurementConstraints(options, blocks);
+ * // Returns: { measurementWidth: 468, measurementHeight: 648 }
+ * // 468px = (612 - 72 - 72) width, single column (wider than 2-column: 234px)
+ * // All blocks measured at 468px will fit in both sections
+ * ```
+ */
+export declare function resolveMeasurementConstraints(options: LayoutOptions, blocks?: FlowBlock[]): {
+    measurementWidth: number;
+    measurementHeight: number;
+};
+export {};

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

@@ -0,0 +1,211 @@
+import { FlowBlock, Layout, Measure, Line } from '../../contracts/src/index.js';
+import { Point, FragmentHit, PositionHit } from './position-hit.js';
+export type { HeaderFooterType } from '../../contracts/src/index.js';
+export { selectHeaderFooterVariantForPage, resolveEffectiveHeaderFooterRef, type HeaderFooterKind, type HeaderFooterVariant, type HeaderFooterSectionRefs, type HeaderFooterResolutionSection, type HeaderFooterVariantSelectionInput, type HeaderFooterEffectiveRefInput, type HeaderFooterEffectiveRefResult, } from '../../contracts/src/index.js';
+export { extractIdentifierFromConverter, getHeaderFooterType, defaultHeaderFooterIdentifier, resolveHeaderFooterForPage, buildMultiSectionIdentifier, defaultMultiSectionIdentifier, getHeaderFooterTypeForSection, getHeaderFooterIdForPage, resolveHeaderFooterForPageAndSection, } from './headerFooterUtils.js';
+export type { HeaderFooterIdentifier, MultiSectionHeaderFooterIdentifier, SectionHeaderFooterIds, } from './headerFooterUtils.js';
+export { layoutHeaderFooterWithCache, invalidateHeaderFooterMeasureCache, type HeaderFooterBatchResult, getBucketForPageNumber, getBucketRepresentative, } from './layoutHeaderFooter.js';
+export type { HeaderFooterBatch, DigitBucket } from './layoutHeaderFooter.js';
+export { resolveHeaderFooterTokens, PROVISIONAL_PAGE_COUNT_PLACEHOLDER, type ResolveHeaderFooterTokensOptions, } from './resolveHeaderFooterTokens.js';
+export { findWordBoundaries, findParagraphBoundaries } from './text-boundaries.js';
+export type { BoundaryRange } from './text-boundaries.js';
+export { buildSectionAwareHeaderFooterLayoutKey, buildSectionContentWidth, buildEffectiveHeaderFooterRefsBySection, collectReferencedHeaderFooterRIds, buildSectionAwareHeaderFooterMeasurementGroups, } from './sectionAwareHeaderFooter.js';
+export type { HeaderFooterSectionKind, HeaderFooterRefs, SectionAwareHeaderFooterMeasurementGroup, } from './sectionAwareHeaderFooter.js';
+export { clearIncrementalModuleState, incrementalLayout, measureCache, normalizeMargin, hydrateTableTextboxMeasures, } from './incrementalLayout.js';
+export type { HeaderFooterLayoutResult, IncrementalLayoutBridgeTiming, IncrementalLayoutResult, IncrementalMeasureReuseProof, IncrementalLayoutReuseOptions, IncrementalLayoutReuseSummary, IncrementalSectionPageNumberTransform, IncrementalLayoutTailAdoption, IncrementalLayoutTailDisposition, IncrementalPaginationProof, LayoutPositionTransform, FootnoteReserveSeed, } from './incrementalLayout.js';
+export { collectFootnoteLedgers, getPreferredReserveCandidates, getPreferredReserveTrialTargets, isMandatoryOnlyFootnotePage, scoreFootnoteWindow, summarizeFootnoteWindow, } from './footnote-scorer.js';
+export type { FootnotePreferredReserveCandidate, FootnoteWindowScoreInput, FootnoteWindowScoreReason, FootnoteWindowScoreResult, FootnoteWindowStats, } from './footnote-scorer.js';
+export { computeDisplayPageNumber } from '../../layout-engine/src/index.js';
+export type { DisplayPageInfo, HeaderFooterConstraints } from '../../layout-engine/src/index.js';
+export { clearRemeasureTextCaches, remeasureParagraph } from './remeasure.js';
+export { findCharacterAtX, measureCharacterX } from './text-measurement.js';
+export { sliceRunsForLine } from '../../contracts/src/index.js';
+export { clickToPositionDom, findPageElement } from './dom-mapping.js';
+export { isListItem, getWordLayoutConfig, calculateTextStartIndent, extractParagraphIndent } from './list-indent-utils.js';
+export type { TextIndentCalculationParams } from './list-indent-utils.js';
+export { LayoutVersionLogger } from './instrumentation.js';
+export type { LayoutMetrics } from './instrumentation.js';
+export { hitTestTextboxFragment, resolveTextboxContentHit } from './position-hit.js';
+export type { TextboxHitResult } from './position-hit.js';
+export { FontMetricsCache } from './font-metrics-cache.js';
+export type { FontMetrics, FontMetricsCacheConfig } from './font-metrics-cache.js';
+export { ParagraphLineCache } from './paragraph-line-cache.js';
+export type { LineInfo, ParagraphLines } from './paragraph-line-cache.js';
+export { CursorRenderer } from './cursor-renderer.js';
+export type { CursorRendererOptions, CursorRect } from './cursor-renderer.js';
+export { LocalParagraphLayout } from './local-paragraph-layout.js';
+export type { LocalLayoutResult, TextRun } from './local-paragraph-layout.js';
+export { PmDomFallback } from './pm-dom-fallback.js';
+export type { PageTransform, PmEditorView } from './pm-dom-fallback.js';
+export { PageGeometryHelper } from './page-geometry-helper.js';
+export type { PageGeometryConfig } from './page-geometry-helper.js';
+export { DirtyTracker } from './dirty-tracker.js';
+export type { DirtyRange } from './dirty-tracker.js';
+export { DebouncedPassManager } from './debounced-passes.js';
+export type { DebouncedPass } from './debounced-passes.js';
+export { PmPositionValidator } from './pm-position-validator.js';
+export type { ValidationResult, ValidationError } from './pm-position-validator.js';
+export { ImeHandler } from './ime-handler.js';
+export type { ImeState } from './ime-handler.js';
+export { TableHandler } from './table-handler.js';
+export type { TableLayoutState } from './table-handler.js';
+export { TrackChangesHandler } from './track-changes-handler.js';
+export type { TrackChangeSpan } from './track-changes-handler.js';
+export { CacheWarmer } from './cache-warmer.js';
+export type { WarmingConfig, ParagraphWarmInfo } from './cache-warmer.js';
+export { PerformanceMetricsCollector, perfMetrics } from './performance-metrics.js';
+export type { MetricSample, MetricSummary, TypingPerfMetrics, BudgetViolation } from './performance-metrics.js';
+export { SafetyNet } from './safety-net.js';
+export type { FallbackReason, SafetyConfig } from './safety-net.js';
+export { FocusWatchdog } from './focus-watchdog.js';
+export type { FocusWatchdogConfig } from './focus-watchdog.js';
+export { hashParagraphBorder, hashParagraphBorders, hashParagraphAttrs, hashBorderSpec, hashTableBorderValue, hashTableBorders, hashCellBorders, hasStringProp, hasNumberProp, hasBooleanProp, getRunStringProp, getRunNumberProp, getRunBooleanProp, } from './paragraph-hash-utils.js';
+export type { LayoutHit, LayoutHitDiagnostic, LayoutFragmentOpaqueRange, LayoutFragmentSubrange, LayoutRangeMapping, LayoutRect, PmOpaqueRange, } from './neutral-hit.js';
+export { hitTestNeutral, mapRangeToFragmentsNeutral } from './neutral-hit.js';
+export { collectSegmentGeometry } from './neutral-segment-geometry.js';
+export type { CollectSegmentGeometryOptions } from './neutral-segment-geometry.js';
+export { lineHasComplexBidiContent, logicalAdvanceToContainerX, containerXToLogicalAdvance, } from './rtl-text-geometry.js';
+export type { Point, PageHit, FragmentHit, PositionHit, TableHitResult, GeometryPageHint, ClickToPositionGeometryOptions, } from './position-hit.js';
+export { isAtomicFragment, getAtomicPmRange, isRtlBlock, determineColumn, findLineIndexAtY, mapPointToPm, snapToNearestFragment, hitTestPage, hitTestFragment, hitTestAtomicFragment, hitTestTableFragment, findBlockIndexByFragmentId, calculatePageTopFallback, resolvePositionHitFromDomPosition, clickToPositionGeometry, } from './position-hit.js';
+export type Rect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    pageIndex: number;
+};
+/**
+ * Compatibility wrapper — delegates to resolvePositionHitFromDomPosition and
+ * clickToPositionGeometry from position-hit.ts.
+ *
+ * Production editor-runtime callers should use resolvePointerPositionHit from
+ * their pointer resolver instead. This wrapper exists so that external
+ * consumers and tests that import clickToPosition from @superdoc/layout-bridge
+ * continue to work unchanged.
+ */
+export declare function clickToPosition(layout: Layout, blocks: FlowBlock[], measures: Measure[], containerPoint: Point, domContainer?: HTMLElement, clientX?: number, clientY?: number, geometryHelper?: import('./page-geometry-helper.js').PageGeometryHelper): PositionHit | null;
+/**
+ * Given a PM range [from, to), return selection rectangles for highlighting.
+ *
+ * @param layout - The layout containing page and fragment data
+ * @param blocks - Array of flow blocks
+ * @param measures - Array of measurements corresponding to blocks
+ * @param from - Start PM position
+ * @param to - End PM position
+ * @param geometryHelper - Optional PageGeometryHelper for accurate Y calculations (recommended)
+ * @returns Array of selection rectangles in container space
+ */
+export declare function selectionToRects(layout: Layout, blocks: FlowBlock[], measures: Measure[], from: number, to: number, geometryHelper?: import('./page-geometry-helper.js').PageGeometryHelper): Rect[];
+export declare function getFragmentAtPosition(layout: Layout, blocks: FlowBlock[], measures: Measure[], pos: number): FragmentHit | null;
+export declare function findLinesIntersectingRange(block: FlowBlock, measure: Measure, from: number, to: number): {
+    line: Line;
+    index: number;
+}[];
+/**
+ * Computes the ProseMirror position range for a line within a paragraph block.
+ *
+ * This function calculates the start and end PM positions by iterating through all runs
+ * that contribute to the line, handling partial runs at line boundaries and accounting
+ * for various run types (text, images, breaks, annotations).
+ *
+ * **Empty Run Handling (SD-1108 Fix):**
+ * Unlike `pmPosToCharOffset` which skips empty runs during position-to-character mapping,
+ * this function intentionally PRESERVES empty runs to support cursor positioning in
+ * zero-width content like empty table cells. Empty runs carry PM position metadata that
+ * enables click-to-position mapping even when there's no visible text.
+ *
+ * **Why the difference?**
+ * - `computeLinePmRange`: Used for spatial operations (click mapping, selection highlighting)
+ *   where we need to know the PM range of ALL content, including zero-width positions.
+ * - `pmPosToCharOffset`: Used for text measurement where only visible characters matter.
+ *   Empty runs contribute no pixels and should be skipped during character-based calculations.
+ *
+ * **Algorithm:**
+ * 1. Filter out atomic runs (images, line breaks, field annotations) - they have no text length
+ * 2. For each text run in the line:
+ *    a. If the run is empty (length 0), preserve its PM positions for cursor support
+ *    b. If the run has text, calculate PM positions based on character offsets
+ *    c. Handle partial runs (first/last in line) by adjusting offsets
+ * 3. Return the accumulated PM range
+ *
+ * **Edge Cases Handled:**
+ * - Empty runs (zero text length but valid PM positions) - PRESERVED for SD-1108
+ * - Atomic runs (images, breaks) - skipped, don't contribute to text range
+ * - Runs with missing PM data - skipped with warning logged
+ * - Runs with invalid PM positions (negative, Infinity, NaN) - logged as warnings
+ * - Partial runs at line boundaries - offset calculations applied
+ *
+ * @param block - The flow block to compute PM range for (must be a paragraph block)
+ * @param line - The line specification including run range (fromRun to toRun) and character offsets
+ * @returns Object containing pmStart and pmEnd positions, or empty object if block is not a paragraph
+ *
+ * @example
+ * ```typescript
+ * // Normal text run
+ * const range = computeLinePmRange(paragraphBlock, line);
+ * // { pmStart: 10, pmEnd: 25 }
+ *
+ * // Empty table cell (SD-1108 fix)
+ * const emptyRange = computeLinePmRange(emptyParagraphBlock, line);
+ * // { pmStart: 15, pmEnd: 15 } - zero-width but valid for cursor positioning
+ * ```
+ *
+ * @see pmPosToCharOffset - Related function that skips empty runs during character offset calculation
+ */
+export declare function computeLinePmRange(block: FlowBlock, line: Line): {
+    pmStart?: number;
+    pmEnd?: number;
+};
+/**
+ * Convert a ProseMirror position to a character offset within a line.
+ *
+ * This function performs ratio-based interpolation to handle cases where the PM position
+ * range doesn't match the text length (e.g., when a run has formatting marks or when
+ * there are position gaps between runs due to wrapper nodes).
+ *
+ * Algorithm:
+ * 1. Iterate through runs in the line
+ * 2. For each run, calculate its PM range and character count
+ * 3. If pmPos falls within the run's PM range:
+ *    - Use ratio interpolation: (pmPos - runStart) / runPmRange * runCharCount
+ *    - This handles cases where PM positions don't align 1:1 with characters
+ * 4. Return the accumulated character offset
+ *
+ * Edge Cases:
+ * - Position before line start: Returns 0
+ * - Position after line end: Returns total character count of the line
+ * - Empty runs (images, breaks): Skipped, don't contribute to character count
+ * - Runs with missing PM data: Skipped
+ * - Zero-length PM range: Returns current accumulated offset without adding
+ *
+ * Performance:
+ * - Time complexity: O(n) where n is the number of runs in the line
+ * - Space complexity: O(1)
+ *
+ * @param block - The paragraph block containing the line
+ * @param line - The line containing the position
+ * @param pmPos - The ProseMirror position to convert
+ * @returns Character offset from start of line (0-based), or 0 if position not found
+ *
+ * @example
+ * ```typescript
+ * // Run with PM range [10, 15] containing "Hello" (5 chars)
+ * // pmPos = 12 should map to character offset 2 within the run
+ * const offset = pmPosToCharOffset(block, line, 12);
+ * // offset = 2 (ratio: (12-10)/(15-10) * 5 = 2/5 * 5 = 2)
+ * ```
+ */
+export declare function pmPosToCharOffset(block: FlowBlock, line: Line, pmPos: number): number;
+/**
+ * Convert a ProseMirror position to a rendered character offset within a line.
+ *
+ * Unlike {@link pmPosToCharOffset}, this helper includes visual-only text runs
+ * that do not carry PM positions. That matters for selection highlighting when
+ * a line starts with rendered chrome such as a synthetic footnote number:
+ * the marker consumes horizontal space in the painter, but it is not part of
+ * the editable PM story. Using a PM-only offset would place the highlight too
+ * far left by the marker's width.
+ *
+ * The returned offset is intended for visual X mapping, not for slicing PM text.
+ */
+export declare function pmPosToVisualCharOffset(block: FlowBlock, line: Line, pmPos: number): number;