superdoc 2.4.0-next.6 → 2.4.0-next.60

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

@@ -1,6 +1,7 @@
 import { TabStop } from './engines/tabs.js';
 import { PageNumberChapterSeparator, PageNumberFieldFormat, PageNumberFormat } from './page-number-formatting.js';
 import { TrackedChangeSemanticColorKey } from './semantic-colors.js';
+import { AnchorAlignH, AnchorAlignV, AnchorHRelative, AnchorVRelative } from './graphic-placement.js';
 import { ParagraphDirectionContext, RunBidiContext, RunScriptContext, TableDirectionContext } from './direction-context.js';
 import { LayoutSourceIdentity } from './layout-identity.js';
 export { computeTabStops, layoutWithTabs, calculateTabWidth } from './engines/tabs.js';
@@ -17,7 +18,7 @@ export { shouldApplyJustify, calculateJustifySpacing, getFirstLineIndentOffset,
 export { parseInsetClipPathForScale, formatInsetClipPathTransform, type InsetClipPathScale, } from './clip-path-inset.js';
 export { SUBSCRIPT_SUPERSCRIPT_SCALE, normalizeBaselineShift, hasExplicitBaselineShift, isSuperscriptOrSubscript, usesDefaultScriptLayout, scaleFontSizeForVerticalText, resolveBaseFontSizeForVerticalText, type VerticalTextAlign, } from './vertical-text.js';
 export { computeFragmentPmRange, computeLinePmRange, type LinePmRange } from './pm-range.js';
-export { resolveAnchoredGraphicY, resolveAnchoredGraphicX, resolveFooterPageFrameOriginY, isPositionedParagraphFrame, isPagePositionedParagraphFrame, type ColumnLayoutForAnchor, type ResolveAnchoredGraphicYInput, } from './graphic-placement.js';
+export { resolveAnchoredGraphicY, resolveAnchoredGraphicX, resolveFooterPageFrameOriginY, isPositionedParagraphFrame, isPagePositionedParagraphFrame, isAnchorHRelative, isAnchorVRelative, isAnchorAlignH, isAnchorAlignV, ANCHOR_H_RELATIVE_VALUES, ANCHOR_V_RELATIVE_VALUES, ANCHOR_H_ALIGN_VALUES, ANCHOR_V_ALIGN_VALUES, type ColumnLayoutForAnchor, type ResolveAnchoredGraphicYInput, type ResolveAnchoredGraphicXContext, type AnchorHRelative, type AnchorVRelative, type AnchorAlignH, type AnchorAlignV, } from './graphic-placement.js';
 export { LAYOUT_BOUNDARY_SCHEMA, bodyStoryLocator, namedStoryLocator, computeLayoutFragmentId, buildLayoutSourceIdentity, buildLayoutSourceIdentityForFragment, } from './layout-identity.js';
 export type { LayoutBlockRef, LayoutFragmentId, LayoutPartialRowIdentity, LayoutSourceIdentity, LayoutStoryKind, LayoutStoryLocator, } from './layout-identity.js';
 export { LAYOUT_SEGMENT_GEOMETRY_SCHEMA } from './segment-geometry.js';
@@ -120,7 +121,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 +656,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 +718,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 +749,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 +991,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 +1023,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,10 +1060,18 @@ export type VectorShapeStyle = {
     fillColor?: FillColor;
     strokeColor?: StrokeColor;
     strokeWidth?: number;
+    /** Physical CSS-pixel dash/gap lengths resolved from the source stroke. */
+    strokeDashArray?: number[];
+    strokeLineJoin?: 'round' | 'bevel' | 'miter';
+    strokeLineCap?: 'round' | 'square' | 'butt';
+    /** Optional per-edge frame used by render-only table cells inside legacy shape groups. */
+    borders?: CellBorders;
     lineEnds?: LineEnds;
     textContent?: ShapeTextContent;
     textAlign?: string;
     textVerticalAlign?: 'top' | 'center' | 'bottom';
+    /** Legacy VML textbox text-flow semantics. */
+    textFlow?: 'horizontal' | 'vertical' | 'vertical-ideographic' | 'horizontal-ideographic' | 'bottom-to-top';
     textInsets?: {
         top: number;
         right: number;
@@ -1063,11 +1152,15 @@ export type VectorShapeDrawing = DrawingBlockBase & {
     fillColor?: FillColor;
     strokeColor?: StrokeColor;
     strokeWidth?: number;
+    strokeDashArray?: number[];
+    strokeLineJoin?: 'round' | 'bevel' | 'miter';
+    strokeLineCap?: 'round' | 'square' | 'butt';
     lineEnds?: LineEnds;
     effectExtent?: EffectExtent;
     textContent?: ShapeTextContent;
     textAlign?: string;
     textVerticalAlign?: 'top' | 'center' | 'bottom';
+    textFlow?: 'horizontal' | 'vertical' | 'vertical-ideographic' | 'horizontal-ideographic' | 'bottom-to-top';
     textInsets?: {
         top: number;
         right: number;
@@ -1078,26 +1171,42 @@ 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;
     strokeColor?: StrokeColor;
     strokeWidth?: number;
+    strokeDashArray?: number[];
+    strokeLineJoin?: 'round' | 'bevel' | 'miter';
+    strokeLineCap?: 'round' | 'square' | 'butt';
     lineEnds?: LineEnds;
     effectExtent?: EffectExtent;
     textContent?: ShapeTextContent;
     textAlign?: string;
     textVerticalAlign?: 'top' | 'center' | 'bottom';
+    textFlow?: 'horizontal' | 'vertical' | 'vertical-ideographic' | 'horizontal-ideographic' | 'bottom-to-top';
     textInsets?: {
         top: number;
         right: number;
         bottom: number;
         left: number;
     };
-    contentBlocks: ParagraphBlock[];
-    /** Paragraph layout results for table-cell textboxes; populated by the layout bridge, read by the painter. */
-    contentMeasures?: ParagraphMeasure[];
+    /**
+     * Canonical block content owned by the textbox story.
+     *
+     * ECMA-376 permits general block-level WordprocessingML in `w:txbxContent`.
+     * V2 currently supports paragraphs and tables explicitly; keeping this as a
+     * named subset makes later block-family additions additive instead of
+     * flattening rich content into drawing primitives.
+     */
+    contentBlocks: TextboxContentBlock[];
+    /** Canonical layout results for textbox content; populated by measurement or the layout bridge. */
+    contentMeasures?: TextboxContentMeasure[];
 };
+export type TextboxContentBlock = ParagraphBlock | TableBlock;
+export type TextboxContentMeasure = ParagraphMeasure | TableMeasure;
 export type ShapeGroupDrawing = DrawingBlockBase & {
     drawingKind: 'shapeGroup';
     geometry: DrawingGeometry;
@@ -1169,6 +1278,13 @@ export type SectionBreakBlock = {
     kind: 'sectionBreak';
     id: BlockId;
     type?: 'continuous' | 'nextPage' | 'evenPage' | 'oddPage';
+    /**
+     * Physical page parity required for a `nextPage` break. Word derives this
+     * when distinct odd/even headers are enabled and the new section explicitly
+     * restarts page numbering; authored `evenPage`/`oddPage` breaks express the
+     * same constraint through `type` instead.
+     */
+    requiredPageParity?: 'even' | 'odd';
     pageSize?: {
         w: number;
         h: number;
@@ -1266,10 +1382,21 @@ export type ColumnBreakBlock = {
 /** Positioning for anchored images (offsets in CSS px). */
 export type ImageAnchor = {
     isAnchored?: boolean;
-    hRelativeFrom?: 'column' | 'page' | 'margin';
-    vRelativeFrom?: 'paragraph' | 'page' | 'margin';
-    alignH?: 'left' | 'center' | 'right';
-    alignV?: 'top' | 'center' | 'bottom';
+    /**
+     * Page-space coordinates from `wp:simplePos` in CSS px.
+     * ECMA-376 Part 1 §20.4.2.13: when present because `wp:anchor/@simplePos`
+     * is true, these coordinates override positionH/positionV.
+     */
+    simplePos?: {
+        x: number;
+        y: number;
+    };
+    /** Keep the anchored object inside its table cell and resize the cell as needed. */
+    layoutInCell?: boolean;
+    hRelativeFrom?: AnchorHRelative;
+    vRelativeFrom?: AnchorVRelative;
+    alignH?: AnchorAlignH;
+    alignV?: AnchorAlignV;
     offsetH?: number;
     offsetV?: number;
     behindDoc?: boolean;
@@ -1285,6 +1412,7 @@ export type ImageAnchor = {
  */
 export declare function isPageRelativeAnchor(input: {
     anchor?: {
+        simplePos?: unknown;
         vRelativeFrom?: unknown;
     } | null;
 } | null | undefined): boolean;
@@ -1372,7 +1500,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 +1773,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 +1891,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 +1950,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 +2002,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 +2012,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;
@@ -1951,8 +2124,8 @@ export type DrawingMeasure = {
     naturalHeight: number;
     geometry: DrawingGeometry;
     groupTransform?: ShapeGroupTransform;
-    /** Canonical paragraph measurements for textbox content, when the drawing owns text. */
-    contentMeasures?: ParagraphMeasure[];
+    /** Canonical block measurements for textbox content, when the drawing owns a textbox story. */
+    contentMeasures?: TextboxContentMeasure[];
 };
 export type TableCellMeasure = {
     /** Multi-block cell measurements (new feature) */
@@ -2081,6 +2254,13 @@ export type FootnotePageLedger = {
 export type Page = {
     number: number;
     fragments: Fragment[];
+    /**
+     * Suppress header/footer stories on a physically inserted parity page.
+     * Word emits these pages to satisfy odd/even section starts, but leaves the
+     * page itself completely blank and does not treat it as page one of the new
+     * section.
+     */
+    suppressHeaderFooter?: boolean;
     margins?: PageMargins;
     /**
      * Extra bottom space reserved on this page for footnotes (in px).
@@ -2314,7 +2494,7 @@ export type DrawingFragment = {
     drawingContentId?: string;
     /** V2 textbox story id for DrawingML textbox content painted inside this drawing. */
     textboxId?: string;
-    contentMeasures?: ParagraphMeasure[];
+    contentMeasures?: TextboxContentMeasure[];
     pmStart?: number;
     pmEnd?: number;
     sourceAnchor?: SourceAnchor;
@@ -2345,6 +2525,18 @@ export type HeaderFooterType = 'default' | 'first' | 'even' | 'odd';
 export type HeaderFooterPage = {
     number: number;
     fragments: Fragment[];
+    /**
+     * Measurement height for this page's resolved story content. PAGE/NUMPAGES
+     * fields can wrap differently across physical pages, so paint alignment must
+     * not substitute the layout-wide maximum for this value.
+     */
+    measurementHeight?: number;
+    /** Per-page minimum rendered y, including out-of-band decorations. */
+    minY?: number;
+    /** Per-page maximum rendered y + fragment height. */
+    maxY?: number;
+    /** Per-page visual extent (`maxY - minY`). */
+    renderHeight?: number;
     numberText?: string;
     /** Section-aware numeric page value before formatting. */
     displayNumber?: number;
@@ -2455,5 +2647,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/contracts/src/resolved-layout.d.ts

@@ -476,6 +476,11 @@ export declare function isResolvedDrawingItem(item: ResolvedPaintItem): item is
 /** A resolved header/footer page — mirrors HeaderFooterPage but with resolved items. */
 export type ResolvedHeaderFooterPage = {
     number: number;
+    /** Page-local measurement height; see `HeaderFooterPage.measurementHeight`. */
+    measurementHeight?: number;
+    minY?: number;
+    maxY?: number;
+    renderHeight?: number;
     numberText?: string;
     /** Section-aware numeric page value before formatting. */
     displayNumber?: number;

package/dist/layout-engine/dom-contract/src/class-names.d.ts

@@ -12,6 +12,8 @@ export declare const DOM_CLASS_NAMES: {
     readonly PAGE: "superdoc-page";
     /** Fragment container (paragraph, table, image block, etc.). */
     readonly FRAGMENT: "superdoc-fragment";
+    /** Non-flowing fragment whose visual position must not define body flow geometry. */
+    readonly FLOATING_FRAGMENT: "superdoc-floating-fragment";
     /** Line container within a fragment. */
     readonly LINE: "superdoc-line";
     /**

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[];
@@ -68,9 +70,11 @@ export type IncrementalLayoutResult = {
      * out no footnotes) — the next run then starts cold.
      */
     footnoteReserveSeed?: FootnoteReserveSeed | null;
+    /** Canonical pre-layout furniture heights that can affect body margins. */
+    headerFooterGeometryFingerprint: string;
     layoutReuse?: IncrementalLayoutReuseSummary;
     measureReuse?: {
-        mode: 'full-scan' | 'proved-dirty-only';
+        mode: 'full-scan' | 'proved-dirty-only' | 'body-stable';
         blocksMeasured: number;
         measuresAdopted: number;
         reason: string;
@@ -117,6 +121,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 +182,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 +196,9 @@ export type IncrementalLayoutTailAdoption = {
     sourcePageEndIndexExclusive: number;
     pageIndexDelta: number;
     sectionPageNumberTransform: IncrementalSectionPageNumberTransform | null;
+    displayPageNumberTransform?: IncrementalDisplayPageNumberTransform | null;
+    /** Exact proof that PAGEREF page/numbering locations are unchanged in the adopted tail. */
+    pageReferenceLocationsStable: boolean;
     sourceLayoutEpoch: number | null;
     positionTransforms: readonly LayoutPositionTransform[];
     /** Lazy old->current block-id rekeys for an ordinal-changing structural splice. */
@@ -207,6 +231,7 @@ export type IncrementalPaginationProof = IncrementalPaginationProofBase & ({
     globalDependenciesAbsent: false;
     globalDependenciesFencedByPageCheckpoint: true;
     admittedDependencyClasses: readonly PageCheckpointDependencyClass[];
+    nonFlowingPageRelativeAnchorDependency?: NonFlowingPageRelativeAnchorDependencyProof;
     localKeepDependencyClosure?: {
         checkpointPageIndex: number;
         checkpointBlockId: string | null;
@@ -265,6 +290,15 @@ export type IncrementalLayoutReuseOptions = {
         noteIds: readonly string[];
         bodyReferenceBlockIds: readonly string[];
     };
+    /**
+     * Host-proved header/footer-only refresh. The bridge still compares the
+     * current pre-layout height fingerprint before retaining body pagination.
+     */
+    provedHeaderFooterOnlyRefresh?: {
+        bodyProjectionRetainedExact: true;
+        bodyLayoutInputsUnchanged: true;
+        previousGeometryFingerprint: string;
+    };
 };
 export declare const measureCache: MeasureCache<Measure>;
 /**
@@ -276,10 +310,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 +362,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;