superdoc 2.4.0 → 2.5.0

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';
@@ -317,6 +318,8 @@ export type RunMarks = {
      * Rendering normalizes a shift of zero to "no explicit shift".
      */
     baselineShift?: number;
+    /** Paint-only Word 2010+ text effects (`w14:textFill`, outline, shadow, reflection). */
+    textEffects?: TextEffects;
 };
 export type PageReferenceRelativePositionText = 'above' | 'below';
 export type FieldResultFormat = 'charformat' | 'mergeformat';
@@ -472,6 +475,31 @@ export type ImageHyperlink = {
  *   baseline next to the surrounding text instead of floating above it.
  */
 export type ImageRunVerticalAlign = 'top' | 'bottom' | 'baseline';
+/**
+ * Paint-only frame authored on a DrawingML picture (`pic:spPr/a:ln`).
+ *
+ * The frame is intentionally separate from the image dimensions: DrawingML
+ * strokes are centered on the picture geometry and must not enlarge the
+ * layout box. Keeping this as a shared contract lets inline and anchored
+ * pictures use the same extraction and paint path.
+ */
+export type ImageOutline = {
+    color: string;
+    /** Physical CSS-pixel width resolved from `a:ln/@w`. */
+    width: number;
+};
+/**
+ * Explicit fail-closed rendering metadata for content that keeps its authored
+ * layout box but cannot be painted faithfully.
+ *
+ * The producer owns the diagnostic identity; painters only expose it on the
+ * visible, accessible placeholder. This keeps support decisions out of the DOM
+ * layer and makes degraded output observable in browser regression proofs.
+ */
+export type RenderPlaceholder = {
+    diagnosticIds: string[];
+    accessibleName: string;
+};
 /**
  * Inline image run for images that flow with text on the same line.
  * Unlike ImageBlock (anchored/floating images), ImageRun is part of the paragraph's run array
@@ -498,14 +526,22 @@ export type ImageRun = {
     width: number;
     /** Image height in pixels. */
     height: number;
+    /** Font family of the owning OOXML run, used to compose an image-only line box. */
+    fontFamily?: string;
+    /** Font size of the owning OOXML run, used to compose an image-only line box. */
+    fontSize?: number;
     /** Alternative text for accessibility. */
     alt?: string;
     /** Image title (tooltip). */
     title?: string;
+    /** Visible fail-closed replacement when the image source cannot be painted. */
+    placeholder?: RenderPlaceholder;
     /** DrawingML docPr/@id of the picture (used to target the Document API for interactive resize). */
     imageId?: string;
     /** Clip-path value for cropped images. */
     clipPath?: string;
+    /** DrawingML picture frame; paint-only and excluded from layout sizing. */
+    outline?: ImageOutline;
     /**
      * Spacing around the image (from DOCX distT/distB/distL/distR attributes).
      * Applied as CSS margins in the DOM painter.
@@ -717,6 +753,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
@@ -742,6 +784,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;
@@ -874,6 +926,10 @@ export type ImageBlock = {
     height?: number;
     alt?: string;
     title?: string;
+    /** DrawingML picture frame; paint-only and excluded from layout sizing. */
+    outline?: ImageOutline;
+    /** Visible fail-closed replacement when the image source cannot be painted. */
+    placeholder?: RenderPlaceholder;
     /** DrawingML docPr/@id of the picture (used to target the Document API for interactive resize). */
     imageId?: string;
     objectFit?: 'contain' | 'cover' | 'fill' | 'scale-down';
@@ -969,11 +1025,73 @@ export type TextFormatting = {
     fontSize?: number;
     fontFamily?: string;
     letterSpacing?: number;
+    /** Paint-only Word 2010+ text effects shared with ordinary text runs. */
+    textEffects?: TextEffects;
+};
+/** Solid color used by a text effect, with optional opacity. */
+export type TextEffectColor = {
+    color: string;
+    alpha?: number;
+};
+/** Word 2010+ text outline (`w14:textOutline`). */
+export type TextOutlineEffect = {
+    /** Outline width converted from EMU to CSS pixels. */
+    width: number;
+    fill: FillColor;
+};
+/** Word 2010+ text glow (`w14:glow`). */
+export type TextGlowEffect = {
+    color: TextEffectColor;
+    /** Glow radius converted from EMU to CSS pixels. */
+    radius: number;
+};
+/** Word 2010+ outer text shadow (`w14:shadow`). */
+export type TextShadowEffect = {
+    color: TextEffectColor;
+    /** Blur radius converted from EMU to CSS pixels. */
+    blurRadius: number;
+    /** Shadow distance converted from EMU to CSS pixels. */
+    distance: number;
+    /** Direction in DrawingML degrees (`0` points right, `90` points down). */
+    direction: number;
+};
+/** Word 2010+ reflected-text mask (`w14:reflection`). */
+export type TextReflectionEffect = {
+    blurRadius: number;
+    distance: number;
+    direction: number;
+    /** Direction of the reflection opacity gradient; defaults to `direction`. */
+    fadeDirection?: number;
+    startAlpha: number;
+    startPosition: number;
+    endAlpha: number;
+    endPosition: number;
+    scaleX: number;
+    scaleY: number;
+};
+/**
+ * Paint-only text effects shared by paragraph runs and flattened shape text.
+ * These effects do not change glyph advances, so layout measurement continues
+ * to use the run's ordinary typography contract.
+ */
+export type TextEffects = {
+    fill?: FillColor;
+    outline?: TextOutlineEffect;
+    glow?: TextGlowEffect;
+    shadow?: TextShadowEffect;
+    reflection?: TextReflectionEffect;
 };
 /** A single text part with optional formatting. */
 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. */
@@ -999,6 +1117,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. */
@@ -1006,6 +1135,34 @@ export type ShapeTextContent = {
     /** Horizontal text alignment within the shape. */
     horizontalAlign?: 'left' | 'center' | 'right';
 };
+/** DrawingML textbox flow/overflow semantics from `a:bodyPr`. */
+export type ShapeTextLayout = {
+    /** `a:bodyPr/@wrap`; `none` keeps authored paragraphs on explicit lines only. */
+    wrap?: 'square' | 'none';
+    /** `a:bodyPr/@horzOverflow`. */
+    horizontalOverflow?: 'overflow' | 'clip';
+    /** `a:bodyPr/@vertOverflow`. */
+    verticalOverflow?: 'overflow' | 'clip' | 'ellipsis';
+};
+/** ECMA-376 Part 1 `ST_TextShapeType` preset text-warp vocabulary. */
+export declare const SHAPE_TEXT_WARP_PRESETS: readonly ["textNoShape", "textPlain", "textStop", "textTriangle", "textTriangleInverted", "textChevron", "textChevronInverted", "textRingInside", "textRingOutside", "textArchUp", "textArchDown", "textCircle", "textButton", "textArchUpPour", "textArchDownPour", "textCirclePour", "textButtonPour", "textCurveUp", "textCurveDown", "textCanUp", "textCanDown", "textWave1", "textWave2", "textDoubleWave1", "textWave4", "textInflate", "textDeflate", "textInflateBottom", "textDeflateBottom", "textInflateTop", "textDeflateTop", "textDeflateInflate", "textDeflateInflateDeflate", "textFadeRight", "textFadeLeft", "textFadeUp", "textFadeDown", "textSlantUp", "textSlantDown", "textCascadeUp", "textCascadeDown"];
+export type ShapeTextWarpPreset = (typeof SHAPE_TEXT_WARP_PRESETS)[number];
+export declare function isShapeTextBaselineWarp(warp: ShapeTextWarp | undefined): boolean;
+export declare function isShapeTextSingleBandEnvelopeWarp(warp: ShapeTextWarp | undefined): boolean;
+/** Preserved `a:prstTxWarp` geometry and guide formulas from `a:bodyPr`. */
+export type ShapeTextWarp = {
+    preset: ShapeTextWarpPreset;
+    adjustments?: Array<{
+        name: string;
+        /** Raw DrawingML guide formula, for example `val 25000`. */
+        formula: string;
+    }>;
+};
+/** Resolve the line-breaking width for DrawingML textbox content. */
+export declare function resolveShapeTextContentMeasureWidth(shapeWidth: number, insets: {
+    left: number;
+    right: number;
+}, layout: ShapeTextLayout | undefined, autoFitBoundaryWidth?: number): number;
 export type LineEnd = {
     type?: string;
     width?: string;
@@ -1021,14 +1178,53 @@ export type EffectExtent = {
     right: number;
     bottom: number;
 };
+/**
+ * DrawingML relative rectangle in the source 1000ths-of-a-percent units.
+ * Values may be negative: ECMA-376 allows an outset as well as an inset.
+ */
+export type ShapeImageFillRect = {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+};
+/** DrawingML `a:tile` parameters, preserved without painter-specific conversion. */
+export type ShapeImageFillTile = {
+    offsetX?: number;
+    offsetY?: number;
+    scaleX?: number;
+    scaleY?: number;
+    flip?: string;
+    alignment?: string;
+};
+/** Resolved bitmap used as the fill paint for vector geometry. */
+export type ShapeImageFill = {
+    src: string;
+    mode: 'stretch' | 'tile';
+    sourceRect?: ShapeImageFillRect;
+    fillRect?: ShapeImageFillRect;
+    tile?: ShapeImageFillTile;
+    dpi?: number;
+    rotateWithShape?: boolean;
+};
 export type VectorShapeStyle = {
     fillColor?: FillColor;
+    imageFill?: ShapeImageFill;
     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;
+    textLayout?: ShapeTextLayout;
     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;
@@ -1086,6 +1282,8 @@ export type DrawingBlockBase = {
     drawingContent?: DrawingContentSnapshot;
     attrs?: Record<string, unknown>;
     sourceAnchor?: SourceAnchor;
+    /** Visible fail-closed replacement metadata owned by the projection layer. */
+    placeholder?: RenderPlaceholder;
 };
 /**
  * Custom geometry path data extracted from a:custGeom/a:pathLst.
@@ -1107,13 +1305,20 @@ export type VectorShapeDrawing = DrawingBlockBase & {
     shapeKind?: string;
     customGeometry?: CustomGeometryData;
     fillColor?: FillColor;
+    imageFill?: ShapeImageFill;
     strokeColor?: StrokeColor;
     strokeWidth?: number;
+    strokeDashArray?: number[];
+    strokeLineJoin?: 'round' | 'bevel' | 'miter';
+    strokeLineCap?: 'round' | 'square' | 'butt';
     lineEnds?: LineEnds;
     effectExtent?: EffectExtent;
     textContent?: ShapeTextContent;
+    textLayout?: ShapeTextLayout;
+    textWarp?: ShapeTextWarp;
     textAlign?: string;
     textVerticalAlign?: 'top' | 'center' | 'bottom';
+    textFlow?: 'horizontal' | 'vertical' | 'vertical-ideographic' | 'horizontal-ideographic' | 'bottom-to-top';
     textInsets?: {
         top: number;
         right: number;
@@ -1124,26 +1329,45 @@ 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;
+    imageFill?: ShapeImageFill;
     strokeColor?: StrokeColor;
     strokeWidth?: number;
+    strokeDashArray?: number[];
+    strokeLineJoin?: 'round' | 'bevel' | 'miter';
+    strokeLineCap?: 'round' | 'square' | 'butt';
     lineEnds?: LineEnds;
     effectExtent?: EffectExtent;
     textContent?: ShapeTextContent;
+    textLayout?: ShapeTextLayout;
+    textWarp?: ShapeTextWarp;
     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;
@@ -1214,7 +1438,14 @@ export type SectionVerticalAlign = 'top' | 'center' | 'bottom' | 'both';
 export type SectionBreakBlock = {
     kind: 'sectionBreak';
     id: BlockId;
-    type?: 'continuous' | 'nextPage' | 'evenPage' | 'oddPage';
+    type?: 'continuous' | 'nextColumn' | '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;
@@ -1312,10 +1543,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;
@@ -1331,6 +1573,7 @@ export type ImageAnchor = {
  */
 export declare function isPageRelativeAnchor(input: {
     anchor?: {
+        simplePos?: unknown;
         vRelativeFrom?: unknown;
     } | null;
 } | null | undefined): boolean;
@@ -1418,7 +1661,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 = {
@@ -1691,6 +1934,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;
@@ -1807,6 +2052,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>;
@@ -1921,6 +2173,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;
@@ -2021,8 +2285,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) */
@@ -2151,6 +2415,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).
@@ -2384,7 +2655,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;
@@ -2415,6 +2686,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;

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 {};