superdoc 2.4.0 → 2.5.0

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

@@ -1,6 +1,6 @@
-import { NonFlowingPageRelativeAnchorDependencyProof, 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. */
@@ -266,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>;
 /**
@@ -277,12 +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?: () => Promise<void> | null;
+    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;
@@ -328,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,9 +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 { clearIncrementalModuleState, incrementalLayout, measureCache, normalizeMargin } from './incrementalLayout.js';
+export { hydrateTableTextboxMeasures } from './hydrateTableTextboxMeasures.js';
 export { hashMeasureContent } from './cache.js';
-export type { HeaderFooterLayoutResult, IncrementalLayoutBridgeTiming, IncrementalLayoutResult, IncrementalMeasureReuseProof, IncrementalLayoutReuseOptions, IncrementalLayoutReuseSummary, IncrementalSectionPageNumberTransform, IncrementalLayoutTailAdoption, IncrementalLayoutTailDisposition, IncrementalPaginationProof, LayoutPositionTransform, FootnoteReserveSeed, } from './incrementalLayout.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/layoutHeaderFooter.d.ts

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

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

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

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

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

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

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

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

@@ -1,4 +1,4 @@
-import { ImageBlock, ImageMeasure, ExclusionZone, DrawingBlock, DrawingMeasure, TableBlock, TableMeasure, ColumnLayoutForAnchor } from '../../contracts/src/index.js';
+import { ImageBlock, ImageMeasure, ExclusionZone, DrawingBlock, DrawingMeasure, TableBlock, TableMeasure, ColumnLayoutForAnchor, ResolveAnchoredGraphicXContext } from '../../contracts/src/index.js';
 type FloatBlock = ImageBlock | DrawingBlock;
 type FloatMeasure = ImageMeasure | DrawingMeasure;
 export type FloatingObjectManager = {
@@ -31,6 +31,19 @@ export type FloatingObjectManager = {
         width: number;
         offsetX: number;
     };
+    /**
+     * Compute every contiguous horizontal region available to a line.
+     * Unlike computeAvailableWidth, this preserves both sides of a centered
+     * `wrapText="bothSides"` object instead of collapsing them to one side.
+     */
+    computeAvailableRegions(lineY: number, lineHeight: number, baseWidth: number, columnIndex: number, pageNumber: number): Array<{
+        offsetX: number;
+        width: number;
+    }>;
+    /**
+     * Return the first Y coordinate below every overlapping TopAndBottom float.
+     */
+    computeVerticalClearance(lineY: number, lineHeight: number, columnIndex: number, pageNumber: number): number | null;
     /**
      * Get all floating images for a page (for debugging/painting).
      */
@@ -56,5 +69,5 @@ export declare function createFloatingObjectManager(columns: ColumnLayout, margi
 export declare function computeAnchorX(anchor: NonNullable<ImageBlock['anchor']>, columnIndex: number, columns: ColumnLayout, imageWidth: number, margins?: {
     left?: number;
     right?: number;
-}, pageWidth?: number): number;
+}, pageWidth?: number, context?: ResolveAnchoredGraphicXContext): number;
 export {};

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

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

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

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

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

@@ -1,5 +1,6 @@
-import { ColumnLayout, FlowBlock, HeaderFooterLayout, Layout, Measure, Page, ParagraphBlock, ParagraphMeasure, SectionMetadata, FlowMode, DocumentBackground } from '../../contracts/src/index.js';
+import { ColumnLayout, FlowBlock, HeaderFooterLayout, Layout, Measure, Page, ParagraphBlock, ParagraphMeasure, SectionMetadata, FlowMode, DocumentBackground, ParagraphLineRegion } from '../../contracts/src/index.js';
 import { PageState, ConstraintBoundary } from './paginator.js';
+import { LayoutExecutionControl } from './execution.js';
 type PageSize = {
     w: number;
     h: number;
@@ -30,7 +31,7 @@ export type LayoutOptions = {
         marginTop?: number;
         marginBottom?: number;
     };
-    remeasureParagraph?: (block: ParagraphBlock, maxWidth: number, firstLineIndent?: number) => ParagraphMeasure;
+    remeasureParagraph?: (block: ParagraphBlock, maxWidth: number, firstLineIndent?: number, lineRegions?: readonly (readonly ParagraphLineRegion[])[]) => ParagraphMeasure;
     /** @internal Positioned paragraph frames that render without advancing the story cursor. */
     nonFlowPositionedParagraphFrameIds?: ReadonlySet<string>;
     sectionMetadata?: SectionMetadata[];
@@ -258,13 +259,12 @@ export type HeaderFooterConstraints = {
     overflowBaseHeight?: number;
 };
 /**
- * Layout FlowBlocks into paginated fragments using measured line data.
- *
- * The function is intentionally deterministic: it walks the provided
- * FlowBlocks in order, consumes their Measure objects (same index),
- * and greedily stacks fragments inside the content box of each page/column.
+ * The synchronous API drains the same resumable state machine without host
+ * turns. Mounted orchestration uses `layoutDocumentCooperatively`; keeping one
+ * algorithm prevents cancellation support from becoming a second paginator.
  */
 export declare function layoutDocument(blocks: FlowBlock[], measures: Measure[], options?: LayoutOptions): Layout;
+export declare function layoutDocumentCooperatively(blocks: FlowBlock[], measures: Measure[], options?: LayoutOptions, execution?: LayoutExecutionControl): Promise<Layout>;
 export type LayoutRangeBoundaryPolicy = 'conservative-context' | 'overscan' | 'degraded-on-incomplete-state';
 export type LayoutRangeExactness = 'exact' | 'pending-layout' | 'degraded-unsupported' | 'stale';
 export type LayoutRangeSourceRange = {
@@ -337,13 +337,16 @@ export declare function layoutDocumentRange(input: LayoutRangeInput): LayoutRang
  * Returns separate measurement bounds (for pagination) and render bounds
  * (for overlay shift). See the Coordinate Contract in the fix plan for details.
  */
-export declare function layoutHeaderFooter(blocks: FlowBlock[], measures: Measure[], constraints: HeaderFooterConstraints, kind?: 'header' | 'footer', remeasureParagraph?: (block: ParagraphBlock, maxWidth: number, firstLineIndent?: number) => ParagraphMeasure): HeaderFooterLayout;
+export declare function layoutHeaderFooter(blocks: FlowBlock[], measures: Measure[], constraints: HeaderFooterConstraints, kind?: 'header' | 'footer', remeasureParagraph?: LayoutOptions['remeasureParagraph']): HeaderFooterLayout;
+export declare function layoutHeaderFooterCooperatively(blocks: FlowBlock[], measures: Measure[], constraints: HeaderFooterConstraints, kind?: 'header' | 'footer', remeasureParagraph?: LayoutOptions['remeasureParagraph'], execution?: LayoutExecutionControl): Promise<HeaderFooterLayout>;
 export { buildAnchorMap, resolvePageRefTokens, getTocBlocksForRemeasurement } from './resolvePageRefs.js';
-export { buildChapterContextByPage, computeDisplayPageNumber, formatPageNumber, formatPageNumberFieldValue, formatSectionPageNumberText, normalizeChapterMarkerText, } from './pageNumbering.js';
+export { buildChapterContextByPage, buildChapterContextByPageCooperatively, computeDisplayPageNumber, computeDisplayPageNumberCooperatively, formatPageNumber, formatPageNumberFieldValue, formatSectionPageNumberText, normalizeChapterMarkerText, } from './pageNumbering.js';
 export type { ChapterPageInfo, DisplayPageInfo, PageNumberFormat } from './pageNumbering.js';
-export { resolvePageNumberTokens } from './resolvePageTokens.js';
+export { resolvePageNumberTokens, resolvePageNumberTokensCooperatively } from './resolvePageTokens.js';
 export type { NumberingContext, ResolvePageTokensResult, ResolvePageTokensOptions } from './resolvePageTokens.js';
 export { getCellLines, getEmbeddedRowLines, resolveTableFrame, resolveRenderedTableWidth } from './layout-table.js';
 export { describeCellRenderBlocks, computeCellSliceContentHeight } from './table-cell-slice.js';
 export { layoutTextboxContent, resolveTextboxContentMeasures } from './layout-textbox.js';
 export { SINGLE_COLUMN_DEFAULT } from './section-breaks.js';
+export { checkpointLayoutExecution, throwIfLayoutExecutionAborted } from './execution.js';
+export type { LayoutExecutionCheckpoint, LayoutExecutionControl, LayoutExecutionPhase } from './execution.js';

package/dist/layout-engine/layout-engine/src/inline-drawing-alignment.d.ts

@@ -0,0 +1,9 @@
+import { FlowBlock, Measure, Page } from '../../contracts/src/index.js';
+/**
+ * Word baseline-aligns an inline zero-height connector with the run that owns
+ * it. Projection keeps vector drawings as sibling blocks, so the connector has
+ * already reserved its authored flow height before the empty carrier paragraph
+ * is laid out. Reposition only its paint fragment once that carrier's measured
+ * baseline is known; later flow remains untouched.
+ */
+export declare function alignInlineZeroHeightDrawingFragments(pages: Page[], blocks: FlowBlock[], measures: Measure[]): void;

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

@@ -1,4 +1,4 @@
-import { DrawingBlock, DrawingMeasure, ParagraphMeasure } from '../../contracts/src/index.js';
+import { DrawingBlock, DrawingMeasure, TextboxContentMeasure } from '../../contracts/src/index.js';
 import { NormalizedColumns } from './layout-image.js';
 import { PageState } from './paginator.js';
 /**
@@ -21,8 +21,8 @@ export type DrawingLayoutContext = {
     advanceColumn: (state: PageState) => PageState;
     /** Computes the X coordinate for a column in the given page state (SD-2629). */
     columnX: (state: PageState, columnIndex?: number) => number;
-    /** Optional textbox paragraph measurements carried alongside textbox drawings. */
-    textboxContentMeasures?: ParagraphMeasure[];
+    /** Optional canonical textbox block measurements carried alongside textbox drawings. */
+    textboxContentMeasures?: TextboxContentMeasure[];
 };
 /**
  * Layout a drawing block (vector shape) within the document flow.

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

@@ -1,6 +1,6 @@
 import { FloatingObjectManager } from './floating-objects.js';
 import { PageState } from './paginator.js';
-import { PageMargins, ParagraphBlock, ParagraphMeasure, ImageBlock, ImageMeasure, DrawingBlock, DrawingMeasure } from '../../contracts/src/index.js';
+import { PageMargins, ParagraphBlock, ParagraphMeasure, ImageBlock, ImageMeasure, DrawingBlock, DrawingMeasure, ParagraphLineRegion } from '../../contracts/src/index.js';
 import { AnchoredTable } from './anchors.js';
 /**
  * SD-2656: ordered footnote anchor entry. The body slicer reads the candidate
@@ -21,7 +21,7 @@ export type ParagraphLayoutContext = {
     advanceColumn: (state: PageState) => PageState;
     columnX: (state: PageState, columnIndex?: number) => number;
     floatManager: FloatingObjectManager;
-    remeasureParagraph?: (block: ParagraphBlock, maxWidth: number, firstLineIndent?: number) => ParagraphMeasure;
+    remeasureParagraph?: (block: ParagraphBlock, maxWidth: number, firstLineIndent?: number, lineRegions?: readonly (readonly ParagraphLineRegion[])[]) => ParagraphMeasure;
     /**
      * Override the paragraph's spacing-after value. Used when contextual spacing
      * should suppress spacing between this paragraph and the next (same-style) paragraph.

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

@@ -1,4 +1,4 @@
-import { DrawingMeasure, ParagraphMeasure, TextboxDrawing } from '../../contracts/src/index.js';
-export declare function layoutTextboxContent(block: TextboxDrawing, remeasureParagraph: (block: TextboxDrawing['contentBlocks'][number], maxWidth: number) => ParagraphMeasure): ParagraphMeasure[];
+import { DrawingMeasure, ParagraphBlock, ParagraphMeasure, TextboxContentMeasure, TextboxDrawing } from '../../contracts/src/index.js';
+export declare function layoutTextboxContent(block: TextboxDrawing, remeasureParagraph: (block: ParagraphBlock, maxWidth: number) => ParagraphMeasure): ParagraphMeasure[] | undefined;
 /** Prefer canonical measurement output, retaining the synchronous bridge as a legacy fallback. */
-export declare function resolveTextboxContentMeasures(block: TextboxDrawing, measure: DrawingMeasure, remeasureParagraph?: (block: TextboxDrawing['contentBlocks'][number], maxWidth: number) => ParagraphMeasure): ParagraphMeasure[] | undefined;
+export declare function resolveTextboxContentMeasures(block: TextboxDrawing, measure: DrawingMeasure, remeasureParagraph?: (block: ParagraphBlock, maxWidth: number) => ParagraphMeasure): TextboxContentMeasure[] | undefined;

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

@@ -1,4 +1,5 @@
 import { formatPageNumber, formatPageNumberFieldValue, formatSectionPageNumberText, FlowBlock, Layout, Page, PageNumberChapterSeparator, PageNumberFormat, SectionMetadata } from '../../contracts/src/index.js';
+import { LayoutExecutionControl } from './execution.js';
 export { formatPageNumber, formatPageNumberFieldValue, formatSectionPageNumberText };
 export type { PageNumberFormat };
 export interface ChapterPageInfo {
@@ -29,45 +30,6 @@ export interface DisplayPageInfo {
 }
 export declare function normalizeChapterMarkerText(markerText: unknown): string | undefined;
 export declare function buildChapterContextByPage(layout: Layout, blocks: FlowBlock[] | ReadonlyMap<string, FlowBlock>, sections: SectionMetadata[]): Map<number, ChapterPageInfo>;
-/**
- * Computes section-aware display page numbers for all pages in a document.
- *
- * This function implements MS Word's section numbering behavior:
- * - Each section can have its own page number format
- * - Sections can restart numbering at a specific value
- * - Continuous sections inherit the previous section's running count unless restart is set
- * - Display numbers are calculated as: pageIndexWithinSection + offset (or restart value)
- * - Display numbers are never less than 1
- *
- * Algorithm:
- * 1. Map each page to its owning section
- * 2. For each section:
- *    - If restart/start is set, begin counting from that value
- *    - Otherwise, continue from previous section's count
- * 3. For each page within a section:
- *    - Calculate displayIndex = pageIndexWithinSection + offset
- *    - Clamp displayNumber = max(1, displayIndex)
- *    - Format displayText using the section's number format
- *
- * @param pages - Array of pages from the layout (with page.number 1-indexed)
- * @param sections - Array of section metadata (aligned by sectionIndex)
- * @returns Array of display page information for each page
- *
- * @example
- * ```typescript
- * const pages = [
- *   { number: 1, ... },
- *   { number: 2, ... },
- *   { number: 3, ... },
- * ];
- * const sections = [
- *   { sectionIndex: 0, numbering: { format: 'lowerRoman', start: 1 } },
- *   { sectionIndex: 1, numbering: { format: 'decimal', start: 1 } },
- * ];
- * const displayInfo = computeDisplayPageNumber(pages, sections);
- * // displayInfo[0]: { physicalPage: 1, displayNumber: 1, displayText: "i", sectionIndex: 0 }
- * // displayInfo[1]: { physicalPage: 2, displayNumber: 2, displayText: "ii", sectionIndex: 0 }
- * // displayInfo[2]: { physicalPage: 3, displayNumber: 1, displayText: "1", sectionIndex: 1 }
- * ```
- */
+export declare function buildChapterContextByPageCooperatively(layout: Layout, blocks: FlowBlock[] | ReadonlyMap<string, FlowBlock>, sections: SectionMetadata[], execution?: LayoutExecutionControl): Promise<Map<number, ChapterPageInfo>>;
 export declare function computeDisplayPageNumber(pages: Page[], sections: SectionMetadata[], chapterInfoByPage?: ReadonlyMap<number, ChapterPageInfo>): DisplayPageInfo[];
+export declare function computeDisplayPageNumberCooperatively(pages: Page[], sections: SectionMetadata[], chapterInfoByPage: ReadonlyMap<number, ChapterPageInfo> | undefined, execution?: LayoutExecutionControl): Promise<DisplayPageInfo[]>;

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

@@ -94,7 +94,9 @@ export type PaginatorOptions = {
         w: number;
         h: number;
     }): Page;
-    onNewPage?: (state: PageState) => void;
+    onNewPage?: (state: PageState | undefined, options?: {
+        applyPendingSection: boolean;
+    }) => void;
     shouldStopBeforeNewPage?: (input: {
         completedPageIndex: number;
         pages: readonly Page[];
@@ -122,7 +124,10 @@ export declare function breakParagraphAdjacency(state: PageState): void;
 export declare function createPaginator(opts: PaginatorOptions): {
     readonly pages: Page[];
     readonly states: PageState[];
-    readonly startNewPage: () => PageState;
+    readonly startNewPage: (options?: {
+        applyPendingSection?: boolean;
+        replaceCurrentPage?: boolean;
+    }) => PageState;
     readonly ensurePage: () => PageState;
     readonly advanceColumn: (state: PageState) => PageState;
     readonly getActiveColumnsForState: (state: PageState) => ColumnLayout;

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

@@ -1,5 +1,6 @@
 import { Layout, FlowBlock, ParagraphBlock, Measure } from '../../contracts/src/index.js';
 import { DisplayPageInfo } from './pageNumbering.js';
+import { LayoutExecutionControl } from './execution.js';
 /**
  * Numbering context for page token resolution.
  * Contains display page information for each physical page in the document.
@@ -59,6 +60,7 @@ export interface ResolvePageTokensOptions {
     pageCountFieldsExact?: boolean;
 }
 export declare function resolvePageNumberTokens(layout: Layout, blocks: FlowBlock[], measures: Measure[], numberingCtx: NumberingContext, options?: ResolvePageTokensOptions): ResolvePageTokensResult;
+export declare function resolvePageNumberTokensCooperatively(layout: Layout, blocks: FlowBlock[], measures: Measure[], numberingCtx: NumberingContext, options?: ResolvePageTokensOptions, execution?: LayoutExecutionControl): Promise<ResolvePageTokensResult>;
 /**
  * Resolves page number tokens in paragraph blocks.
  *

package/dist/layout-engine/layout-engine/src/section-breaks.d.ts

@@ -28,6 +28,7 @@ export type SectionState = {
 };
 export type BreakDecision = {
     forcePageBreak: boolean;
+    forceColumnBreak?: boolean;
     forceMidPageRegion: boolean;
     requiredParity?: 'even' | 'odd';
 };

package/dist/layout-engine/layout-engine/src/section-props.d.ts

@@ -62,4 +62,9 @@ export type SectionProps = {
  * }
  * ```
  */
+export type SectionPropsScanCheckpoint = {
+    index: number;
+    total: number;
+};
+export declare function computeNextSectionPropsAtBreakSteps(blocks: FlowBlock[], checkpointEveryBlocks?: number | null): Generator<SectionPropsScanCheckpoint, Map<number, SectionProps>, void>;
 export declare function computeNextSectionPropsAtBreak(blocks: FlowBlock[]): Map<number, SectionProps>;

package/dist/layout-engine/painters/dom/src/chart-renderer.d.ts

@@ -1,13 +1,13 @@
-import { ChartModel, DrawingGeometry } from '../../../contracts/src/index.js';
+import { ChartModel, DrawingGeometry, RenderPlaceholder } from '../../../contracts/src/index.js';
 /**
  * Create a chart element from a ChartDrawing block.
  * Routes to the correct renderer based on chart type, with placeholder fallback.
  */
-export declare function createChartElement(doc: Document, chartData: ChartModel | undefined, geometry: DrawingGeometry): HTMLElement;
+export declare function createChartElement(doc: Document, chartData: ChartModel | undefined, geometry: DrawingGeometry, placeholder?: RenderPlaceholder): HTMLElement;
 /**
  * Create a placeholder for charts with missing data or unsupported types.
  * Preserves layout dimensions and is print-visible.
  */
-export declare function createChartPlaceholder(doc: Document, container: HTMLElement, label: string): HTMLElement;
+export declare function createChartPlaceholder(doc: Document, container: HTMLElement, label: string, placeholder?: RenderPlaceholder): HTMLElement;
 /** Format a numeric tick value for chart axis labels. */
 export declare function formatTickValue(value: number): string;

package/dist/layout-engine/painters/dom/src/images/image-outline.d.ts

@@ -0,0 +1,7 @@
+import { ImageOutline } from '../../../../contracts/src/index.js';
+/**
+ * Paint a DrawingML picture frame without changing the image's layout box.
+ * `a:ln` is centered on the picture geometry; a negatively offset CSS outline
+ * reproduces that geometry while keeping width/height authoritative.
+ */
+export declare const applyImageOutline: (target: HTMLElement, outline?: ImageOutline) => void;

package/dist/layout-engine/painters/dom/src/images/render-placeholder.d.ts

@@ -0,0 +1,12 @@
+import { RenderPlaceholder } from '../../../../contracts/src/index.js';
+export type CreateRenderPlaceholderOptions = {
+    doc: Document;
+    placeholder: RenderPlaceholder;
+};
+/** Stamp the shared diagnostic and accessibility contract on a placeholder. */
+export declare const applyRenderPlaceholderSemantics: (element: HTMLElement, placeholder: RenderPlaceholder) => void;
+/**
+ * Paint an observable, print-visible replacement for content that the
+ * projection layer deliberately kept fail-closed.
+ */
+export declare const createRenderPlaceholder: ({ doc, placeholder }: CreateRenderPlaceholderOptions) => HTMLSpanElement;