superdoc 2.4.0-next.9 → 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';
@@ -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;
 /**
@@ -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.
@@ -655,12 +691,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 +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
@@ -696,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;
@@ -828,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';
@@ -923,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. */
@@ -953,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. */
@@ -960,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;
@@ -975,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;
@@ -1040,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.
@@ -1061,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;
@@ -1078,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;
@@ -1168,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;
@@ -1266,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;
@@ -1285,6 +1573,7 @@ export type ImageAnchor = {
  */
 export declare function isPageRelativeAnchor(input: {
     anchor?: {
+        simplePos?: unknown;
         vRelativeFrom?: unknown;
     } | null;
 } | null | undefined): boolean;
@@ -1372,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 = {
@@ -1645,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;
@@ -1761,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>;
@@ -1813,6 +2111,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 +2163,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 +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;
@@ -1951,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) */
@@ -2081,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).
@@ -2314,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;
@@ -2345,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;
@@ -2455,5 +2808,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;