superdoc 2.4.0-next.5 → 2.4.0-next.50

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

@@ -120,7 +120,7 @@ export type DocPartMetadata = {
  * - Doc parts: special objects like tables of contents
  */
 export type SdtMetadata = FieldAnnotationMetadata | StructuredContentMetadata | DocumentSectionMetadata | DocPartMetadata;
-export declare const CONTRACTS_VERSION = "1.1.0";
+export declare const CONTRACTS_VERSION = "1.2.0";
 /** Unique identifier for a block in the document. Format: `${pos}-${type}`. */
 export type BlockId = string;
 /**
@@ -655,12 +655,58 @@ export type MathRun = {
     sdt?: SdtMetadata;
 };
 export type Run = TextRun | TabRun | ImageRun | LineBreakRun | BreakRun | FieldAnnotationRun | MathRun;
+/** Layout-affecting inline-box values, resolved to logical CSS pixel sides. */
+export type ResolvedInlineBoxLayout = {
+    paddingInlineStart: number;
+    paddingInlineEnd: number;
+    paddingBlockStart: number;
+    paddingBlockEnd: number;
+    gapBefore: number;
+    gapAfter: number;
+    borderWidth: number;
+};
+/** Sanitized, paint-only inline-box appearance. */
+export type ResolvedInlineBoxAppearance = {
+    backgroundColor?: string;
+    borderColor?: string;
+    borderStyle?: 'solid' | 'dashed' | 'dotted';
+    borderRadius?: number;
+    color?: string;
+};
+/** Paint-ready inline-box style emitted on measured line slices. */
+export type ResolvedInlineBoxStyle = ResolvedInlineBoxLayout & ResolvedInlineBoxAppearance;
+/**
+ * An internal, layout-aware presentation over a paragraph-visible text range.
+ *
+ * The proof uses leaf styling (D1): measurement creates box-edge segment
+ * boundaries and the painter styles the canonical text leaves. The fallback
+ * sibling layer was not needed. Extension-authored boxes reach this internal
+ * layout contract through the v2 host bridge. RTL input is ignored (D12), and
+ * the synchronous paragraph remeasurer does not consume this field (D14).
+ */
+export type InlineBoxSpan = {
+    id: string;
+    /**
+     * UTF-16 offsets over the paragraph's flattened visible text. Every
+     * non-text run contributes one placeholder character. These offsets never
+     * alter run PM ranges, run indices, source anchors, or document identity.
+     */
+    from: number;
+    to: number;
+    layout: ResolvedInlineBoxLayout;
+    appearance: ResolvedInlineBoxAppearance;
+    className?: string;
+    data?: Record<string, string>;
+    cursor?: 'default' | 'pointer' | 'text' | 'help';
+};
 export type ParagraphBlock = {
     kind: 'paragraph';
     id: BlockId;
     runs: Run[];
     attrs?: ParagraphAttrs;
     sourceAnchor?: SourceAnchor;
+    /** @internal Layout-aware presentation projected from the extension API by the v2 host. */
+    inlineBoxes?: InlineBoxSpan[];
 };
 /** Border style (subset of OOXML ST_Border). */
 export type BorderStyle = 'none' | 'single' | 'double' | 'dashed' | 'dotted' | 'thick' | 'triple' | 'dotDash' | 'dotDotDash' | 'wave' | 'doubleWave';
@@ -671,6 +717,12 @@ export type BorderSpec = {
     color?: string;
     space?: number;
 };
+/**
+ * Returns the complete painted width of an OOXML table border in CSS pixels.
+ * `w:sz` is the width of the complete border, including compound styles such
+ * as double. `thick` retains the existing table-painter minimum used in V2.
+ */
+export declare const getRenderedTableBorderWidthPx: (border: Pick<BorderSpec, "style" | "width"> | undefined, defaultWidth?: number) => number;
 /**
  * Three-state border value for table borders.
  * - `null`: inherit from table style
@@ -696,6 +748,16 @@ export type CellBorders = {
     bottom?: BorderSpec;
     left?: BorderSpec;
 };
+/** True when a normalized border contributes a visible edge. */
+export declare const isPresentBorder: (border?: BorderSpec) => border is BorderSpec;
+/** True when the source explicitly suppresses an edge rather than omitting it. */
+export declare const isExplicitNoneBorder: (border?: unknown) => boolean;
+/**
+ * Resolve the single visible edge shared by two cells according to
+ * ECMA-376 Part 1 §17.4.66. Kept in the editor-neutral contract package so
+ * import and DOM paint use one conflict algorithm.
+ */
+export declare const resolveBorderConflict: (first?: BorderSpec, second?: BorderSpec) => BorderSpec | undefined;
 export type TableCellAttrs = {
     borders?: CellBorders;
     padding?: BoxSpacing;
@@ -928,6 +990,13 @@ export type TextFormatting = {
 export type TextPart = {
     text: string;
     formatting?: TextFormatting;
+    /**
+     * Paragraph properties carried by the first visible part of a shape-text
+     * paragraph. Shape text is intentionally flattened into `parts`, so this
+     * marker preserves the authored block geometry without introducing a second
+     * competing text model.
+     */
+    paragraphProperties?: ShapeTextParagraphProperties;
     /** Optional field token (e.g., PAGE/NUMPAGES/SECTIONPAGES) resolved at render time. */
     fieldType?: 'PAGE' | 'NUMPAGES' | 'SECTIONPAGES';
     /** PAGE/SECTIONPAGES field-local value formatting override. */
@@ -953,6 +1022,17 @@ export type TextPart = {
     height?: number;
     alt?: string;
 };
+/** Paragraph geometry used by flattened DrawingML/VML shape text. */
+export type ShapeTextParagraphProperties = {
+    horizontalAlign?: 'left' | 'center' | 'right' | 'justify';
+    spacingBefore?: number;
+    spacingAfter?: number;
+    line?: number;
+    lineUnit?: 'px' | 'multiplier';
+    leftIndent?: number;
+    rightIndent?: number;
+    firstLineIndent?: number;
+};
 /** Text content configuration for shapes. */
 export type ShapeTextContent = {
     /** Array of text parts with individual formatting. */
@@ -979,6 +1059,8 @@ export type VectorShapeStyle = {
     fillColor?: FillColor;
     strokeColor?: StrokeColor;
     strokeWidth?: number;
+    /** Optional per-edge frame used by render-only table cells inside legacy shape groups. */
+    borders?: CellBorders;
     lineEnds?: LineEnds;
     textContent?: ShapeTextContent;
     textAlign?: string;
@@ -1078,6 +1160,8 @@ export type VectorShapeDrawing = DrawingBlockBase & {
 export type TextboxDrawing = DrawingBlockBase & {
     drawingKind: 'textboxShape';
     geometry: DrawingGeometry;
+    /** `a:spAutoFit`: resize the shape height to its measured text content. */
+    autoFit?: boolean;
     shapeKind?: string;
     customGeometry?: CustomGeometryData;
     fillColor?: FillColor;
@@ -1266,6 +1350,8 @@ export type ColumnBreakBlock = {
 /** Positioning for anchored images (offsets in CSS px). */
 export type ImageAnchor = {
     isAnchored?: boolean;
+    /** Keep the anchored object inside its table cell and resize the cell as needed. */
+    layoutInCell?: boolean;
     hRelativeFrom?: 'column' | 'page' | 'margin';
     vRelativeFrom?: 'paragraph' | 'page' | 'margin';
     alignH?: 'left' | 'center' | 'right';
@@ -1372,7 +1458,7 @@ export type ExclusionZone = {
         left: number;
         right: number;
     };
-    wrapMode: 'left' | 'right' | 'both' | 'none' | 'largest';
+    wrapMode: 'left' | 'right' | 'both' | 'none' | 'largest' | 'topBottom';
     polygon?: number[][];
 };
 export type ParagraphSpacing = {
@@ -1645,6 +1731,8 @@ export type ParagraphAttrs = {
     tabIntervalTwips?: number;
     keepNext?: boolean;
     keepLines?: boolean;
+    /** Prevent a single first or last paragraph line from appearing alone on a page. Defaults to true. */
+    widowControl?: boolean;
     pageBreakBefore?: boolean;
     trackedChangesMode?: TrackedChangesMode;
     trackedChangesEnabled?: boolean;
@@ -1761,6 +1849,13 @@ export declare const isForcedSectPrSectionBreak: (block: FlowBlock | undefined)
  * accepted only when their source/anchor proves they belong to the same filler
  * run.
  */
+export type SectionBoundaryFillerScanCheckpoint = {
+    index: number;
+    total: number;
+};
+export declare function collectSectionBoundaryFillerBlockIdsSteps(blocks: readonly FlowBlock[], options?: {
+    isTinyInlineBoundaryDrawing?: (block: DrawingBlock, index: number) => boolean;
+}, checkpointEveryBlocks?: number | null): Generator<SectionBoundaryFillerScanCheckpoint, ReadonlySet<string>, void>;
 export declare const collectSectionBoundaryFillerBlockIds: (blocks: readonly FlowBlock[], options?: {
     isTinyInlineBoundaryDrawing?: (block: DrawingBlock, index: number) => boolean;
 }) => ReadonlySet<string>;
@@ -1813,6 +1908,28 @@ export type LineInlineImageAlignment = {
     runIndex: number;
     verticalAlign: ImageRunVerticalAlign;
 };
+/**
+ * Paint-ready geometry for one inline-box slice on a measured line.
+ *
+ * Measurement owns the slice geometry and resolved style. The painter consumes
+ * these values directly and never normalizes logical sides or measures the DOM.
+ */
+export type LineInlineBox = {
+    id: string;
+    /** Line-relative UTF-16 offsets covered by this slice. */
+    from: number;
+    to: number;
+    x: number;
+    width: number;
+    top: number;
+    height: number;
+    startsRange: boolean;
+    endsRange: boolean;
+    style: ResolvedInlineBoxStyle;
+    className?: string;
+    data?: Record<string, string>;
+    cursor?: 'default' | 'pointer' | 'text' | 'help';
+};
 export type Line = {
     fromRun: number;
     fromChar: number;
@@ -1843,6 +1960,8 @@ export type Line = {
      * wins over the entry here.
      */
     inlineImageAlignments?: LineInlineImageAlignment[];
+    /** Paint-ready inline-box slices emitted by measurement. */
+    inlineBoxes?: LineInlineBox[];
     /**
      * Measured tab widths keyed by tab run `pmStart`, stored alongside the
      * `ParagraphMeasure` so the painter can read them even after FlowBlock
@@ -1851,6 +1970,18 @@ export type Line = {
      */
     tabWidths?: Record<number, number>;
 };
+/**
+ * One contiguous horizontal region available to a measured paragraph line.
+ *
+ * Coordinates are relative to the paragraph fragment's content origin. A line
+ * can expose multiple regions when text wraps on both sides of a floating
+ * object. Measuring owns the line breaks inside these regions; layout owns
+ * deriving the regions from page/column float geometry.
+ */
+export type ParagraphLineRegion = {
+    offsetX: number;
+    width: number;
+};
 export type LineSegment = {
     runIndex: number;
     fromChar: number;
@@ -2455,5 +2586,7 @@ export declare const extractHeaderFooterSpace: (margins?: PageMargins | null) =>
 export type { ResolvedLayout, ResolvedPage, ResolvedPaintItem, ResolvedGroupItem, ResolvedFragmentItem, ResolvedParagraphContent, ResolvedTextLineItem, ResolvedDropCapItem, ResolvedListMarkerItem, ResolvedTableItem, ResolvedImageItem, ResolvedDrawingItem, ResolvedHeaderFooterPage, ResolvedHeaderFooterLayout, } from './resolved-layout.js';
 export { isResolvedTableItem, isResolvedImageItem, isResolvedDrawingItem } from './resolved-layout.js';
 export { expandRunsForInlineNewlines, isEmptyInlineSdtPlaceholderRun, isEmptySdtPlaceholderRun, sliceRunsForLine, } from './run-helpers.js';
-export { PAGE_CHECKPOINT_DEPENDENCY_CLASSES, areValidPageCheckpointDependencyClasses, type PageCheckpointDependencyClass, } from './incremental-dependency.js';
+export { INLINE_OBJECT_REPLACEMENT_CHARACTER, flattenParagraphVisibleText, mapVisibleRangeToRunSlices, type ParagraphVisibleRunSlice, } from './paragraph-visible-text.js';
+export { inlineBoxStyleSignature, isFiniteNonNegativeInteger, normalizeInlineBoxLogicalSides, type InlineBoxLogicalSides, type ResolvedInlineBoxLogicalSides, } from './inline-box.js';
+export { PAGE_CHECKPOINT_DEPENDENCY_CLASSES, areValidPageCheckpointDependencyClasses, type NonFlowingPageRelativeAnchorDependencyProof, type PageCheckpointDependencyClass, } from './incremental-dependency.js';
 export * as Engines from './engines/index.js';

package/dist/layout-engine/contracts/src/inline-box.d.ts

@@ -0,0 +1,19 @@
+import { ResolvedInlineBoxStyle } from './index.js';
+export type InlineBoxLogicalSides = number | {
+    start: number;
+    end: number;
+};
+export type ResolvedInlineBoxLogicalSides = {
+    start: number;
+    end: number;
+};
+/** True for finite, non-negative integer CSS pixel values. */
+export declare const isFiniteNonNegativeInteger: (value: unknown) => value is number;
+/**
+ * Expands a scalar logical value into explicit start/end values.
+ *
+ * Undefined resolves to zero. Invalid or non-integer input fails closed.
+ */
+export declare const normalizeInlineBoxLogicalSides: (value: InlineBoxLogicalSides | undefined) => ResolvedInlineBoxLogicalSides | null;
+/** Stable signature for every metric and appearance value consumed by paint. */
+export declare const inlineBoxStyleSignature: (style: ResolvedInlineBoxStyle) => string;

package/dist/layout-engine/contracts/src/paragraph-visible-text.d.ts

@@ -0,0 +1,19 @@
+import { ParagraphBlock } from './index.js';
+export declare const INLINE_OBJECT_REPLACEMENT_CHARACTER = "\uFFFC";
+export type ParagraphVisibleRunSlice = {
+    runIndex: number;
+    fromChar: number;
+    toChar: number;
+};
+/**
+ * Flattens a paragraph into Document API visible-text coordinates.
+ *
+ * Text is preserved verbatim in UTF-16. Every non-text run contributes one
+ * U+FFFC object-replacement character, regardless of its rendered label.
+ */
+export declare const flattenParagraphVisibleText: (block: ParagraphBlock) => string;
+/**
+ * Maps a validated visible-text range to slices in the paragraph's run space.
+ * Returns null for non-integer, reversed, negative, or out-of-bounds ranges.
+ */
+export declare const mapVisibleRangeToRunSlices: (block: ParagraphBlock, from: number, to: number) => ParagraphVisibleRunSlice[] | null;

package/dist/layout-engine/layout-bridge/src/footnote-scorer.d.ts

@@ -42,7 +42,7 @@ export type FootnoteWindowScoreResult = {
 };
 export declare const isMandatoryOnlyFootnotePage: (ledger: FootnotePageLedger, preferredDeltaThresholdPx?: number, mandatoryOnlyTolerancePx?: number) => boolean;
 /**
- * SD-2656 (post-Vivienne-feedback): a page whose LAST anchor partially rendered
+ * SD-2656: a page whose LAST anchor partially rendered
  * but spilled to a later page. The user-visible bug is a footnote split across
  * pages even when the preferred reserve would fit the whole anchor on the
  * anchor page (Word does keep it together).

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

@@ -0,0 +1,9 @@
+import { FlowBlock, ParagraphBlock, ParagraphMeasure } from '../../contracts/src/index.js';
+type TextboxRemeasure = (block: ParagraphBlock, maxWidth: number) => ParagraphMeasure;
+/**
+ * Derives table-cell textbox measurements without mutating the projection
+ * plane supplied by the caller. Only the textbox and its table ancestry are
+ * copied; documents without table textboxes retain their original identities.
+ */
+export declare function hydrateTableTextboxMeasures(blocks: FlowBlock[], remeasure: TextboxRemeasure): FlowBlock[];
+export {};

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

@@ -1,6 +1,6 @@
-import { PageCheckpointDependencyClass, FlowBlock, Layout, Measure, HeaderFooterLayout, ParagraphBlock, ParagraphMeasure, ColumnLayout } from '../../contracts/src/index.js';
+import { NonFlowingPageRelativeAnchorDependencyProof, PageCheckpointDependencyClass, FlowBlock, Layout, Measure, HeaderFooterLayout, 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 { LayoutOptions, HeaderFooterConstraints, LayoutExecutionCheckpoint } from '../../layout-engine/src/index.js';
 import { computeDirtyRegions } from './diff.js';
 import { MeasureCache } from './cache.js';
 import { HeaderFooterBatch } from './layoutHeaderFooter.js';
@@ -52,6 +52,8 @@ export type FootnoteReserveSeed = {
 };
 export type IncrementalLayoutResult = {
     layout: Layout;
+    /** Pass-owned block plane after derived layout annotations are attached. */
+    blocks: FlowBlock[];
     measures: Measure[];
     dirty: ReturnType<typeof computeDirtyRegions>;
     headers?: HeaderFooterLayoutResult[];
@@ -117,6 +119,16 @@ export type IncrementalLayoutBridgeTiming = {
         measuresAdopted: number;
         pagesPaginated: number | null;
         pagesSplicedByReuse: number;
+        paginationPasses: number;
+        pageTokenRelayouts: number;
+        footnoteRelayouts: number;
+        footnoteReserveRelayouts: number;
+        footnoteGrowRelayouts: number;
+        footnoteTightenRelayouts: number;
+        footnotePreferredRelayouts: number;
+        footnoteWidowRelayouts: number;
+        footnoteRevertRelayouts: number;
+        footnoteOtherRelayouts: number;
     };
 };
 /**
@@ -168,6 +180,13 @@ export type IncrementalSectionPageNumberTransform = {
     /** Difference between target and source section-relative page positions. */
     delta: number;
 };
+export type IncrementalDisplayPageNumberTransform = {
+    /** First section whose retained display-page values inherit the local page delta. */
+    startSectionIndex: number;
+    /** First later section with an explicit numbering restart. */
+    endSectionIndexExclusive: number;
+    delta: number;
+};
 export type IncrementalLayoutTailAdoption = {
     startPageIndex: number;
     endPageIndexExclusive: number;
@@ -175,6 +194,7 @@ export type IncrementalLayoutTailAdoption = {
     sourcePageEndIndexExclusive: number;
     pageIndexDelta: number;
     sectionPageNumberTransform: IncrementalSectionPageNumberTransform | null;
+    displayPageNumberTransform?: IncrementalDisplayPageNumberTransform | null;
     sourceLayoutEpoch: number | null;
     positionTransforms: readonly LayoutPositionTransform[];
     /** Lazy old->current block-id rekeys for an ordinal-changing structural splice. */
@@ -207,6 +227,7 @@ export type IncrementalPaginationProof = IncrementalPaginationProofBase & ({
     globalDependenciesAbsent: false;
     globalDependenciesFencedByPageCheckpoint: true;
     admittedDependencyClasses: readonly PageCheckpointDependencyClass[];
+    nonFlowingPageRelativeAnchorDependency?: NonFlowingPageRelativeAnchorDependencyProof;
     localKeepDependencyClosure?: {
         checkpointPageIndex: number;
         checkpointBlockId: string | null;
@@ -276,10 +297,13 @@ export declare const measureCache: MeasureCache<Measure>;
  */
 export declare function clearIncrementalModuleState(): void;
 export interface IncrementalLayoutExecutionControl {
+    signal?: AbortSignal;
     /** Budget-aware host-task yield; may resolve immediately. */
-    yieldToHost?: () => Promise<void>;
-    /** Checkpoint cadence for the block measurement loop. Defaults to 32. */
+    yieldToHost?: (checkpoint?: LayoutExecutionCheckpoint) => Promise<void>;
+    /** Measurement checkpoints default to 32 blocks; nested layout checkpoints default to 16. */
     yieldEveryBlocks?: number;
+    /** Time-aware mounted probe. Null is the allocation-free under-budget path. */
+    checkpointIfDue?: (checkpoint?: LayoutExecutionCheckpoint) => Promise<void> | null;
 }
 export declare function incrementalLayout(previousBlocks: FlowBlock[], _previousLayout: Layout | null, nextBlocks: FlowBlock[], options: LayoutOptions, measureBlock: (block: FlowBlock, constraints: {
     maxWidth: number;
@@ -325,12 +349,6 @@ export declare function incrementalLayout(previousBlocks: FlowBlock[], _previous
  * @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.

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

@@ -11,8 +11,10 @@ export { findWordBoundaries, findParagraphBoundaries } from './text-boundaries.j
 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 { clearIncrementalModuleState, incrementalLayout, measureCache, normalizeMargin } from './incrementalLayout.js';
+export { hydrateTableTextboxMeasures } from './hydrateTableTextboxMeasures.js';
+export { hashMeasureContent } from './cache.js';
+export type { HeaderFooterLayoutResult, IncrementalLayoutBridgeTiming, IncrementalLayoutResult, IncrementalLayoutExecutionControl, 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';

package/dist/layout-engine/layout-bridge/src/inline-box-key.d.ts

@@ -0,0 +1,3 @@
+import { InlineBoxSpan } from '../../contracts/src/index.js';
+/** Shared inline-box identity for measure-cache and dirty-region decisions. */
+export declare const inlineBoxKey: (box: InlineBoxSpan) => string;

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

@@ -1,5 +1,5 @@
-import { FlowBlock, HeaderFooterLayout, Measure, PageNumberChapterSeparator, PageNumberFormat, ParagraphBlock, ParagraphMeasure } from '../../contracts/src/index.js';
-import { HeaderFooterConstraints } from '../../layout-engine/src/index.js';
+import { FlowBlock, HeaderFooterLayout, Measure, PageNumberChapterSeparator, PageNumberFormat, ParagraphBlock, ParagraphLineRegion, ParagraphMeasure } from '../../contracts/src/index.js';
+import { HeaderFooterConstraints, LayoutExecutionCheckpoint, LayoutExecutionControl } from '../../layout-engine/src/index.js';
 import { MeasureCache } from './cache.js';
 import { ResolveHeaderFooterTokensOptions } from './resolveHeaderFooterTokens.js';
 export type HeaderFooterBatch = Partial<Record<'default' | 'first' | 'even' | 'odd', FlowBlock[]>>;
@@ -28,6 +28,13 @@ export type PageResolver = (pageNumber: number) => {
     chapterNumberText?: string;
     chapterSeparator?: PageNumberChapterSeparator;
 };
+/** Optional cooperative execution hooks for browser-owned furniture builds. */
+export interface HeaderFooterLayoutExecution extends LayoutExecutionControl {
+    /** Time-aware mounted probe. Null is the allocation-free under-budget path. */
+    checkpointIfDue?: (checkpoint?: LayoutExecutionCheckpoint) => Promise<void> | null;
+    /** Exact physical pages whose PAGE contexts are missing from a retained layout entry. */
+    pageNumbers?: readonly number[];
+}
 /**
  * Digit bucket for page number caching strategy.
  * Different digit lengths require different measurements due to width changes.
@@ -85,7 +92,7 @@ export declare class HeaderFooterLayoutCache {
     measureBlocks(blocks: FlowBlock[], constraints: {
         width: number;
         height: number;
-    }, measureBlock: MeasureResolver, fontSignature?: string): Promise<Measure[]>;
+    }, measureBlock: MeasureResolver, fontSignature?: string, execution?: LayoutExecutionControl): Promise<Measure[]>;
     invalidate(blockIds: string[]): void;
     /**
      * Gets cache statistics for monitoring and debugging.
@@ -120,4 +127,4 @@ export declare function invalidateHeaderFooterMeasureCache(blockIds: string[]):
  * @param pageResolver - Callback to resolve display page info for a physical page number
  * @returns Batch result with layouts, blocks, and measures for each variant
  */
-export declare function layoutHeaderFooterWithCache(sections: HeaderFooterBatch, constraints: HeaderFooterConstraints, measureBlock: MeasureResolver, cache?: HeaderFooterLayoutCache, totalPages?: number, pageResolver?: PageResolver, kind?: 'header' | 'footer', fontSignature?: string, remeasureParagraph?: (block: ParagraphBlock, maxWidth: number, firstLineIndent?: number) => ParagraphMeasure, options?: ResolveHeaderFooterTokensOptions): Promise<HeaderFooterBatchResult>;
+export declare function layoutHeaderFooterWithCache(sections: HeaderFooterBatch, constraints: HeaderFooterConstraints, measureBlock: MeasureResolver, cache?: HeaderFooterLayoutCache, totalPages?: number, pageResolver?: PageResolver, kind?: 'header' | 'footer', fontSignature?: string, remeasureParagraph?: (block: ParagraphBlock, maxWidth: number, firstLineIndent?: number, lineRegions?: readonly (readonly ParagraphLineRegion[])[]) => ParagraphMeasure, options?: ResolveHeaderFooterTokensOptions, execution?: HeaderFooterLayoutExecution): Promise<HeaderFooterBatchResult>;

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

@@ -1,4 +1,4 @@
-import { ParagraphBlock, ParagraphMeasure } from '../../contracts/src/index.js';
+import { ParagraphBlock, ParagraphMeasure, ParagraphLineRegion } from '../../contracts/src/index.js';
 /** Drop cached text widths and the canvas context. Call when registered font faces may have changed. */
 export declare function clearRemeasureTextCaches(): void;
 /**
@@ -72,4 +72,4 @@ export declare function clearRemeasureTextCaches(): void;
  * // First line has only 170px available (200 - 30), subsequent lines have full 200px
  * ```
  */
-export declare function remeasureParagraph(block: ParagraphBlock, maxWidth: number, firstLineIndent?: number): ParagraphMeasure;
+export declare function remeasureParagraph(block: ParagraphBlock, maxWidth: number, firstLineIndent?: number, lineRegions?: readonly (readonly ParagraphLineRegion[])[]): ParagraphMeasure;

package/dist/layout-engine/layout-bridge/src/run-visual-marks.d.ts

@@ -5,6 +5,8 @@ import { Run } from '../../contracts/src/index.js';
  * Include every run property that affects text measurement or painted output but is not
  * covered elsewhere (e.g. tracked-change / comment keys). When adding a new visual
  * property, update this function only — `cache.ts` and `diff.ts` both depend on it.
+ * Paragraph-scoped inline boxes are deliberately keyed by `inline-box-key.ts`,
+ * not by this run-scoped helper.
  *
  * @param run - Flow run (text, tab, image, etc.); unknown fields are ignored safely.
  * @returns Stable string encoding bold/italic/underline/strike/color/font/highlight/link.

package/dist/layout-engine/layout-bridge/src/text-measurement.d.ts

@@ -7,18 +7,6 @@ import { FontMeasureContext } from '../../../shared/font-system/src/index.js';
  * @returns CSS font string (e.g., "italic bold 16px Arial")
  */
 export declare function getRunFontString(run: Run, fontContext?: FontMeasureContext): string;
-/**
- * Measure the X position for a specific character offset within a line.
- * Uses Canvas measureText for pixel-perfect accuracy.
- *
- * @param block - The paragraph block containing the line
- * @param line - The line to measure within
- * @param charOffset - Character offset from the start of the line (0-based)
- * @param availableWidthOverride - Optional override for available width
- * @param alignmentOverride - Optional override for text alignment (e.g., 'left' for list items
- *   which are always rendered left-aligned in the DOM regardless of paragraph alignment)
- * @returns The X coordinate (in pixels) from the start of the line
- */
 export declare function measureCharacterX(block: FlowBlock, line: Line, charOffset: number, availableWidthOverride?: number, alignmentOverride?: string, fontContext?: FontMeasureContext): number;
 /**
  * Convert a character offset within a line back to a ProseMirror position.

package/dist/layout-engine/layout-engine/src/anchors.d.ts

@@ -1,5 +1,6 @@
 import { FlowBlock, ImageBlock, ImageMeasure, Measure, DrawingBlock, DrawingMeasure, TableBlock, TableMeasure, isPageRelativeAnchor } from '../../contracts/src/index.js';
 import { resolveFloatingTableAnchorResolution } from './floating-table-anchor.js';
+import { LayoutWorkCheckpoint } from './execution.js';
 export type { FloatingTableAnchorResolution } from './floating-table-anchor.js';
 export { resolveFloatingTableAnchorResolution };
 export { isPageRelativeAnchor };
@@ -39,14 +40,17 @@ export type AnchoredTableCollection = {
  * @param measures - Corresponding measures for each block
  * @returns Array of anchored drawings that should be pre-registered
  */
+export declare function collectPreRegisteredAnchorsSteps(blocks: FlowBlock[], measures: Measure[], checkpointEveryBlocks?: number | null): Generator<LayoutWorkCheckpoint, AnchoredDrawing[], void>;
 export declare function collectPreRegisteredAnchors(blocks: FlowBlock[], measures: Measure[]): AnchoredDrawing[];
 /**
  * Collect anchored drawings (images/drawings) mapped to their anchor paragraph index.
  * Map of paragraph block index -> anchored images/drawings associated with that paragraph.
  */
+export declare function collectAnchoredDrawingsSteps(blocks: FlowBlock[], measures: Measure[], checkpointEveryBlocks?: number | null): Generator<LayoutWorkCheckpoint, AnchoredDrawingCollection, void>;
 export declare function collectAnchoredDrawings(blocks: FlowBlock[], measures: Measure[]): AnchoredDrawingCollection;
 /**
  * Collect anchored/floating tables mapped to their anchor paragraph index.
  * Also returns anchored tables that have no paragraph to attach to.
  */
+export declare function collectAnchoredTablesSteps(blocks: FlowBlock[], measures: Measure[], checkpointEveryBlocks?: number | null): Generator<LayoutWorkCheckpoint, AnchoredTableCollection, void>;
 export declare function collectAnchoredTables(blocks: FlowBlock[], measures: Measure[]): AnchoredTableCollection;

package/dist/layout-engine/layout-engine/src/execution.d.ts

@@ -0,0 +1,21 @@
+export type LayoutExecutionPhase = 'measure:block' | 'layout-document:prepare' | 'layout-document:preflight-section' | 'layout-document:preflight-footnote' | 'layout-document:preflight-anchor' | 'layout-document:preflight-keep-next' | 'layout-document:block' | 'layout-document:finalize-page' | 'layout-document:finalize-section' | 'page-token:prepare' | 'page-token:page' | 'numbering-context:chapter' | 'numbering-context:page' | 'footnote:phase' | 'header-footer:variant' | 'header-footer:block' | 'header-footer:page';
+export type LayoutExecutionCheckpoint = {
+    phase: LayoutExecutionPhase;
+    index?: number;
+    total?: number;
+};
+/** Phase-agnostic progress emitted by resumable layout helpers. */
+export type LayoutWorkCheckpoint = {
+    index: number;
+    total?: number;
+};
+export interface LayoutExecutionControl {
+    signal?: AbortSignal;
+    /** Host-owned task boundary. It may resolve immediately while the current budget remains. */
+    yieldToHost?: (checkpoint: LayoutExecutionCheckpoint) => Promise<void>;
+    /** Work cadence for document/block loops. Defaults to 16. */
+    checkpointEveryBlocks?: number;
+}
+export declare function layoutExecutionCheckpointEveryBlocks(execution: LayoutExecutionControl | undefined): number;
+export declare function throwIfLayoutExecutionAborted(execution: LayoutExecutionControl | undefined): void;
+export declare function checkpointLayoutExecution(execution: LayoutExecutionControl | undefined, checkpoint: LayoutExecutionCheckpoint): Promise<void>;

package/dist/layout-engine/layout-engine/src/floating-objects.d.ts

@@ -31,6 +31,19 @@ export type FloatingObjectManager = {
         width: number;
         offsetX: number;
     };
+    /**
+     * Compute every contiguous horizontal region available to a line.
+     * Unlike computeAvailableWidth, this preserves both sides of a centered
+     * `wrapText="bothSides"` object instead of collapsing them to one side.
+     */
+    computeAvailableRegions(lineY: number, lineHeight: number, baseWidth: number, columnIndex: number, pageNumber: number): Array<{
+        offsetX: number;
+        width: number;
+    }>;
+    /**
+     * Return the first Y coordinate below every overlapping TopAndBottom float.
+     */
+    computeVerticalClearance(lineY: number, lineHeight: number, columnIndex: number, pageNumber: number): number | null;
     /**
      * Get all floating images for a page (for debugging/painting).
      */

package/dist/layout-engine/layout-engine/src/floating-table-anchor.d.ts

@@ -1,4 +1,5 @@
 import { FlowBlock, Measure, TableBlock, TableMeasure } from '../../contracts/src/index.js';
+import { LayoutWorkCheckpoint } from './execution.js';
 export type FloatingTableAnchorResolution = {
     paragraphIndex: number;
     offsetV: number;
@@ -18,4 +19,5 @@ export declare function isAnchoredTableFullWidth(block: TableBlock, measure: Tab
 /**
  * Resolve anchor paragraph + vertical offset for a block-level floating table.
  */
+export declare function resolveFloatingTableAnchorResolutionSteps(blocks: FlowBlock[], measures: Measure[], len: number, tableIndex: number, tableBlock: TableBlock, paragraphIndexById: Map<string, number>, checkpointEveryBlocks?: number | null): Generator<LayoutWorkCheckpoint, FloatingTableAnchorResolution | null, void>;
 export declare function resolveFloatingTableAnchorResolution(blocks: FlowBlock[], measures: Measure[], len: number, tableIndex: number, tableBlock: TableBlock, paragraphIndexById: Map<string, number>): FloatingTableAnchorResolution | null;

package/dist/layout-engine/layout-engine/src/footnote-anchor-index.d.ts

@@ -0,0 +1,17 @@
+import { FlowBlock } from '../../contracts/src/index.js';
+import { LayoutWorkCheckpoint } from './execution.js';
+import { FootnoteAnchorRef } from './layout-paragraph.js';
+export type FootnoteAnchorIndexInput = {
+    refs?: Array<{
+        id: string;
+        pos: number;
+    }>;
+    bodyHeightById?: Map<string, number>;
+    firstLineHeightById?: Map<string, number>;
+};
+export type FootnoteAnchorIndexDiagnostics = {
+    rangeComparisons: number;
+    lowerBoundComparisons: number;
+    legacyComparisons: number;
+};
+export declare function buildFootnoteAnchorIndexSteps(blocks: FlowBlock[], footnotes: FootnoteAnchorIndexInput | undefined, checkpointEveryBlocks: number | null, diagnostics?: FootnoteAnchorIndexDiagnostics): Generator<LayoutWorkCheckpoint, Map<string, FootnoteAnchorRef[]>, void>;