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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -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-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/renderer.d.ts

@@ -520,6 +520,14 @@ export declare class DomPainter {
      * Apply fill and stroke styles to a fallback shape container
      */
     private applyFallbackShapeStyle;
+    /**
+     * Shape stroke widths reach the painter in physical CSS pixels. Preset SVGs
+     * use a normalized 100 × 100 viewBox while VML custom geometry often uses a
+     * coordsize in the thousands. In both cases allowing the viewBox transform to
+     * scale the stroke changes the authored line weight, sometimes by orders of
+     * magnitude. Keep geometry scalable and paint the resolved width verbatim.
+     */
+    private applyPhysicalStrokeSemantics;
     private hasShapeTextContent;
     private createShapeTextElement;
     private createTextboxContentElement;
@@ -540,6 +548,7 @@ export declare class DomPainter {
      * @param _groupScaleY - Reserved parent-group scale factor
      */
     private createFallbackTextElement;
+    private applyShapeTextFlow;
     private tryCreatePresetSvg;
     /**
      * Creates an SVG string from custom geometry path data (a:custGeom).
@@ -566,6 +575,9 @@ export declare class DomPainter {
      */
     private createChartElement;
     private resolveTableRenderData;
+    private createTableCellLineRenderer;
+    /** Render drawing content nested in any canonical table, including a textbox-owned table. */
+    private renderDrawingContentForTable;
     private renderTableFragment;
     private renderLine;
     private createRunRenderContext;
@@ -600,6 +612,12 @@ export declare class DomPainter {
      * Uses resolved data for spatial properties and delegates PM attributes to the legacy path.
      */
     private isAnchoredMediaFragment;
+    /**
+     * Marks fragments whose paint coordinates are independent from body flow.
+     * DOM consumers such as header/footer hit-testing must not infer page margins
+     * from floating objects that happen to paint above the first flow block.
+     */
+    private applyFragmentFlowClass;
     private shouldRenderBehindPageContent;
     private isHeaderWordArtWatermark;
     private isVmlTextWatermarkImage;

package/dist/layout-engine/painters/dom/src/runs/inline-box.d.ts

@@ -0,0 +1,8 @@
+import { Line, LineInlineBox, ParagraphBlock, Run, TextRun } from '../../../../contracts/src/index.js';
+export declare const markInlineBoxRun: (run: TextRun, lineFrom: number, lineTo: number) => TextRun;
+/** Splits text runs at the segment boundaries emitted for inline-box edges. */
+export declare const splitInlineBoxRuns: (block: ParagraphBlock, line: Line) => Run[] | null;
+/** Returns the resolved inline advance preceding an explicitly positioned text segment. */
+export declare const inlineBoxAdvanceBeforeOffset: (boxes: readonly LineInlineBox[] | undefined, offset: number) => number;
+/** Paints measured LTR inline-box slices on the canonical text leaves. */
+export declare const paintInlineBoxes: (boxes: readonly LineInlineBox[] | undefined, lineElement: HTMLElement, isRtl: boolean) => void;

package/dist/layout-engine/painters/dom/src/runs/text-run.d.ts

@@ -15,6 +15,11 @@ import { RunRenderContext, TrackedChangesRenderConfig } from './types.js';
  * makes the tab border and the text underline rasterize to the same line weight.
  */
 export declare const underlineThicknessPx: (fontSize: number) => number;
+type ResolvePhysicalFont = (cssFontFamily: string, face: {
+    weight: '400' | '700';
+    style: 'normal' | 'italic';
+}) => string;
+export declare const applyRunTypographyStyles: (element: HTMLElement, run: TextRun, resolvePhysical?: ResolvePhysicalFont) => void;
 /**
  * Applies run styling properties to a DOM element.
  *
@@ -25,10 +30,7 @@ export declare const underlineThicknessPx: (fontSize: number) => number;
  *                  inline colors are now applied to all runs (including links) to
  *                  ensure OOXML hyperlink character styles appear correctly.
  */
-export declare const applyRunStyles: (element: HTMLElement, run: Run, _isLink?: boolean, resolvePhysical?: (cssFontFamily: string, face: {
-    weight: "400" | "700";
-    style: "normal" | "italic";
-}) => string) => void;
+export declare const applyRunStyles: (element: HTMLElement, run: Run, _isLink?: boolean, resolvePhysical?: ResolvePhysicalFont) => void;
 export declare const resolveRunText: (run: Run, context: FragmentRenderContext) => string;
 export declare const extractLinkData: (run: Run) => import('./types.js').LinkRenderData | null;
 export declare const renderTextRun: (run: TextRun, context: FragmentRenderContext, renderContext: RunRenderContext, trackedConfig?: TrackedChangesRenderConfig) => HTMLElement | null;

package/dist/layout-engine/painters/dom/src/table/border-utils.d.ts

@@ -1,5 +1,20 @@
 import { BorderSpec, CellBorders, TableBorderValue, TableBorders, TableFragment } from '../../../../contracts/src/index.js';
 import { TableCellGridPosition } from './grid-geometry.js';
+type BorderSide = 'Top' | 'Right' | 'Bottom' | 'Left';
+type ThinDoubleBorderOverlayGeometry = {
+    left: string;
+    top: string;
+    width: string;
+    height: string;
+};
+/**
+ * Paints thin double borders in an unclipped sibling SVG. CSS gradients are
+ * clipped at cell seams and cannot form Word's continuous rectangular rings.
+ * The SVG preserves authored geometry once it is large enough, while the V2
+ * wrapper's inverse-zoom variable keeps sub-pixel components at Word's
+ * one-screen-pixel minimum across editor zoom levels.
+ */
+export declare const createThinDoubleBorderOverlay: (doc: Document, source: HTMLElement, geometry: ThinDoubleBorderOverlayGeometry) => SVGSVGElement | null;
 /**
  * Applies a border specification to one side of an HTML element.
  *
@@ -18,7 +33,7 @@ import { TableCellGridPosition } from './grid-geometry.js';
  * // Sets cell.style.borderTop = '2px solid #FF0000'
  * ```
  */
-export declare const applyBorder: (element: HTMLElement, side: "Top" | "Right" | "Bottom" | "Left", border?: BorderSpec) => void;
+export declare const applyBorder: (element: HTMLElement, side: BorderSide, border?: BorderSpec) => void;
 /**
  * Applies border specifications to all four sides of a table cell element.
  *
@@ -79,32 +94,9 @@ export declare const borderValueToSpec: (value?: TableBorderValue | null) => Bor
  * ```
  */
 export declare const resolveTableBorderValue: (explicit: TableBorderValue | undefined | null, fallback?: TableBorderValue | undefined | null) => BorderSpec | undefined;
-export declare const isPresentBorder: (b?: BorderSpec) => b is BorderSpec;
-/**
- * True when a border is EXPLICITLY set to none/nil (`w:val="nil"`/`"none"`), as opposed to
- * simply unset/absent. The distinction matters for shared interior edges (§17.4.66): an
- * explicit none on BOTH adjacent cells suppresses the divider, while an unset side inherits
- * the table's insideH/insideV. Accepts either a CellBorders BorderSpec (`{style:'none'}`) or
- * a TableBorderValue (`{none:true}`).
- */
-export declare const isExplicitNoneBorder: (b?: unknown) => boolean;
-/**
- * OOXML cell-border conflict resolution (ECMA-376 §17.4.66).
- *
- * With zero cell spacing, two cells sharing an edge each specify a border; the spec
- * collapses them to a SINGLE displayed border:
- *  1. If either side is nil/none/absent, the opposing (present) border is displayed.
- *  2. Otherwise the border with greater weight wins, where
- *     weight = (#lines in the style) × (style number).
- *  3. Equal weight → the style higher on the precedence list (single first) wins.
- *  4. Identical style → the color with the smaller brightness (R+B+2G, then B+2G, then
- *     G) wins; finally the first border (reading order) wins.
- *
- * @param a - One side's border (the owning cell's, e.g. the lower/right cell)
- * @param b - The opposing side's border (e.g. the upper/left neighbor)
- * @returns The single BorderSpec to display, or undefined if neither is present.
- */
-export declare const resolveBorderConflict: (a?: BorderSpec, b?: BorderSpec) => BorderSpec | undefined;
+export declare const isPresentBorder: (border?: BorderSpec) => border is BorderSpec;
+export declare const isExplicitNoneBorder: (border?: unknown) => boolean;
+export declare const resolveBorderConflict: (first?: BorderSpec, second?: BorderSpec) => BorderSpec | undefined;
 /**
  * Creates a border overlay element for a table fragment.
  *
@@ -183,3 +175,4 @@ export declare const swapTableBordersLR: (borders: TableBorders | undefined) =>
  * Swap left↔right on cell borders for RTL tables (ECMA-376 Part 4 §14.3.1, §14.3.5).
  */
 export declare const swapCellBordersLR: (borders: CellBorders | undefined) => CellBorders | undefined;
+export {};

package/dist/layout-engine/painters/dom/src/table/renderTableFragment.d.ts

@@ -39,7 +39,7 @@ export type TableRenderDependencies = {
     /** Built-in SDT chrome rendering mode. */
     chrome?: 'default' | 'none';
     /** Function to render a line of paragraph content */
-    renderLine: (block: ParagraphBlock, line: Line, context: FragmentRenderContext, lineIndex: number, isLastLine: boolean) => HTMLElement;
+    renderLine: (block: ParagraphBlock, line: Line, context: FragmentRenderContext, lineIndex: number, isLastLine: boolean, resolvedListTextStartPx?: number) => HTMLElement;
     /** Optional callback invoked after a table line's final styles/markers are applied. */
     captureLineSnapshot?: (lineEl: HTMLElement, context: FragmentRenderContext, options?: {
         inTableParagraph?: boolean;

package/dist/layout-engine/style-engine/src/ooxml/word-style-model/parse-theme.d.ts

@@ -11,11 +11,17 @@ export interface WordThemeFontFamily {
     readonly ea?: string;
     readonly cs?: string;
 }
+/** Authored DrawingML fill definitions, indexed by `a:fillRef/@idx`. */
+export interface WordThemeFormatScheme {
+    readonly fillStyles: readonly string[];
+    readonly backgroundFillStyles: readonly string[];
+}
 export declare const DEFAULT_WORD_THEME_PALETTE: WordThemeColorPalette;
 export declare const DEFAULT_WORD_THEME_FONT_SCHEME: WordThemeFontScheme;
 export interface ThemeParseResult {
     palette?: WordThemeColorPalette;
     fontScheme?: WordThemeFontScheme;
+    formatScheme?: WordThemeFormatScheme;
 }
 /**
  * Parse the theme root (`a:theme`) into colors + font scheme. Returns an