superdoc 2.4.0-next.4 → 2.4.0-next.41

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

@@ -1,6 +1,6 @@
-import { PageCheckpointDependencyClass, FlowBlock, Layout, Measure, HeaderFooterLayout, ParagraphBlock, ParagraphMeasure, ColumnLayout } from '../../contracts/src/index.js';
+import { NonFlowingPageRelativeAnchorDependencyProof, PageCheckpointDependencyClass, FlowBlock, Layout, Measure, HeaderFooterLayout, ColumnLayout } from '../../contracts/src/index.js';
 import { FontMeasureContext } from '../../../shared/font-system/src/index.js';
-import { LayoutOptions, HeaderFooterConstraints } from '../../layout-engine/src/index.js';
+import { LayoutOptions, HeaderFooterConstraints, LayoutExecutionCheckpoint } from '../../layout-engine/src/index.js';
 import { computeDirtyRegions } from './diff.js';
 import { MeasureCache } from './cache.js';
 import { HeaderFooterBatch } from './layoutHeaderFooter.js';
@@ -52,6 +52,8 @@ export type FootnoteReserveSeed = {
 };
 export type IncrementalLayoutResult = {
     layout: Layout;
+    /** Pass-owned block plane after derived layout annotations are attached. */
+    blocks: FlowBlock[];
     measures: Measure[];
     dirty: ReturnType<typeof computeDirtyRegions>;
     headers?: HeaderFooterLayoutResult[];
@@ -117,6 +119,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 +180,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 +194,7 @@ export type IncrementalLayoutTailAdoption = {
     sourcePageEndIndexExclusive: number;
     pageIndexDelta: number;
     sectionPageNumberTransform: IncrementalSectionPageNumberTransform | null;
+    displayPageNumberTransform?: IncrementalDisplayPageNumberTransform | null;
     sourceLayoutEpoch: number | null;
     positionTransforms: readonly LayoutPositionTransform[];
     /** Lazy old->current block-id rekeys for an ordinal-changing structural splice. */
@@ -207,6 +227,7 @@ export type IncrementalPaginationProof = IncrementalPaginationProofBase & ({
     globalDependenciesAbsent: false;
     globalDependenciesFencedByPageCheckpoint: true;
     admittedDependencyClasses: readonly PageCheckpointDependencyClass[];
+    nonFlowingPageRelativeAnchorDependency?: NonFlowingPageRelativeAnchorDependencyProof;
     localKeepDependencyClosure?: {
         checkpointPageIndex: number;
         checkpointBlockId: string | null;
@@ -276,10 +297,13 @@ export declare const measureCache: MeasureCache<Measure>;
  */
 export declare function clearIncrementalModuleState(): void;
 export interface IncrementalLayoutExecutionControl {
+    signal?: AbortSignal;
     /** Budget-aware host-task yield; may resolve immediately. */
-    yieldToHost?: () => Promise<void>;
-    /** Checkpoint cadence for the block measurement loop. Defaults to 32. */
+    yieldToHost?: (checkpoint?: LayoutExecutionCheckpoint) => Promise<void>;
+    /** Measurement checkpoints default to 32 blocks; nested layout checkpoints default to 16. */
     yieldEveryBlocks?: number;
+    /** Time-aware mounted probe. Null is the allocation-free under-budget path. */
+    checkpointIfDue?: (checkpoint?: LayoutExecutionCheckpoint) => Promise<void> | null;
 }
 export declare function incrementalLayout(previousBlocks: FlowBlock[], _previousLayout: Layout | null, nextBlocks: FlowBlock[], options: LayoutOptions, measureBlock: (block: FlowBlock, constraints: {
     maxWidth: number;
@@ -325,12 +349,6 @@ export declare function incrementalLayout(previousBlocks: FlowBlock[], _previous
  * @returns The normalized margin value (guaranteed to be finite)
  */
 export declare const normalizeMargin: (value: number | undefined, fallback: number) => number;
-/**
- * Walks table blocks (including nested tables) and computes `contentMeasures` for any
- * `textboxShape` drawings found in table cells. Stores results directly on the block so
- * the painter can read them without a `DrawingFragment` (table-cell drawings have none).
- */
-export declare function hydrateTableTextboxMeasures(blocks: FlowBlock[], remeasure: (block: ParagraphBlock, maxWidth: number) => ParagraphMeasure): void;
 /**
  * Resolves the maximum measurement constraints (width and height) needed for measuring blocks
  * across all sections in a document.

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

@@ -11,8 +11,10 @@ export { findWordBoundaries, findParagraphBoundaries } from './text-boundaries.j
 export type { BoundaryRange } from './text-boundaries.js';
 export { buildSectionAwareHeaderFooterLayoutKey, buildSectionContentWidth, buildEffectiveHeaderFooterRefsBySection, collectReferencedHeaderFooterRIds, buildSectionAwareHeaderFooterMeasurementGroups, } from './sectionAwareHeaderFooter.js';
 export type { HeaderFooterSectionKind, HeaderFooterRefs, SectionAwareHeaderFooterMeasurementGroup, } from './sectionAwareHeaderFooter.js';
-export { clearIncrementalModuleState, incrementalLayout, measureCache, normalizeMargin, hydrateTableTextboxMeasures, } from './incrementalLayout.js';
-export type { HeaderFooterLayoutResult, IncrementalLayoutBridgeTiming, IncrementalLayoutResult, IncrementalMeasureReuseProof, IncrementalLayoutReuseOptions, IncrementalLayoutReuseSummary, IncrementalSectionPageNumberTransform, IncrementalLayoutTailAdoption, IncrementalLayoutTailDisposition, IncrementalPaginationProof, LayoutPositionTransform, FootnoteReserveSeed, } from './incrementalLayout.js';
+export { clearIncrementalModuleState, incrementalLayout, measureCache, normalizeMargin } from './incrementalLayout.js';
+export { hydrateTableTextboxMeasures } from './hydrateTableTextboxMeasures.js';
+export { hashMeasureContent } from './cache.js';
+export type { HeaderFooterLayoutResult, IncrementalLayoutBridgeTiming, IncrementalLayoutResult, IncrementalLayoutExecutionControl, IncrementalMeasureReuseProof, IncrementalLayoutReuseOptions, IncrementalLayoutReuseSummary, IncrementalSectionPageNumberTransform, IncrementalLayoutTailAdoption, IncrementalLayoutTailDisposition, IncrementalPaginationProof, LayoutPositionTransform, FootnoteReserveSeed, } from './incrementalLayout.js';
 export { collectFootnoteLedgers, getPreferredReserveCandidates, getPreferredReserveTrialTargets, isMandatoryOnlyFootnotePage, scoreFootnoteWindow, summarizeFootnoteWindow, } from './footnote-scorer.js';
 export type { FootnotePreferredReserveCandidate, FootnoteWindowScoreInput, FootnoteWindowScoreReason, FootnoteWindowScoreResult, FootnoteWindowStats, } from './footnote-scorer.js';
 export { computeDisplayPageNumber } from '../../layout-engine/src/index.js';

package/dist/layout-engine/layout-bridge/src/inline-box-key.d.ts

@@ -0,0 +1,3 @@
+import { InlineBoxSpan } from '../../contracts/src/index.js';
+/** Shared inline-box identity for measure-cache and dirty-region decisions. */
+export declare const inlineBoxKey: (box: InlineBoxSpan) => string;

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 { 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) => ParagraphMeasure, options?: ResolveHeaderFooterTokensOptions, execution?: HeaderFooterLayoutExecution): Promise<HeaderFooterBatchResult>;

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-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 { PageState, ConstraintBoundary } from './paginator.js';
+import { LayoutExecutionControl } from './execution.js';
 type PageSize = {
     w: number;
     h: number;
@@ -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 = {
@@ -338,12 +338,15 @@ export declare function layoutDocumentRange(input: LayoutRangeInput): LayoutRang
  * (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 layoutHeaderFooterCooperatively(blocks: FlowBlock[], measures: Measure[], constraints: HeaderFooterConstraints, kind?: 'header' | 'footer', remeasureParagraph?: (block: ParagraphBlock, maxWidth: number, firstLineIndent?: number) => ParagraphMeasure, 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/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/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/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/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

package/dist/public/ui-react.cjs

@@ -1,17 +1,45 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_rolldown_runtime = require("../chunks/rolldown-runtime-1Y-nnZJ3.cjs");
-const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-BHMQEL2y.cjs");
+const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-Dmv8Hjs6.cjs");
 let react = require("react");
+//#region src/public/ui/react.ts
+/**
+* v2-native React bindings for the `superdoc/ui` controller.
+*
+* Provider + hooks over the SuperDoc-owned controller (`superdoc.ui`). For a
+* real `SuperDoc` this layer never creates or destroys a controller; it binds
+* to the one the instance already owns. It falls back to building (and then
+* owning) one only for a structural host that carries no `ui`, since
+* `SuperDocHost` leaves that property optional. Authored with
+* `React.createElement` (no JSX) so the
+* library build needs no JSX transform, and `react` stays an external/optional
+* peer. No v1 editor or private v2 runtime imports.
+*/
 var SuperDocUIContext = (0, react.createContext)(null);
+/**
+* Destroy a controller this provider built itself. Controllers read off
+* `superdoc.ui` are never passed here: the instance owns those.
+*/
 function disposeOwnedUi(ref) {
 	const ui = ref.current;
 	if (!ui) return;
 	ui.destroy();
 	ref.current = null;
 }
+/**
+* Root provider. Call {@link useSetSuperDoc} from your editor-mount
+* component's ready callback to bind a running SuperDoc instance; the hooks
+* below then read that instance's own controller (`superdoc.ui`).
+*
+* The provider is a consumer, not an owner. SuperDoc creates the controller
+* and destroys it in `superdoc.destroy()`, so unmounting or rebinding the
+* provider leaves it running for the built-in toolbar and any other consumer
+* of the same instance. Every React hook therefore observes the same command
+* state the rest of the application sees.
+*/
 function SuperDocUIProvider(props) {
 	const [ui, setUi] = (0, react.useState)(null);
 	const [host, setHost] = (0, react.useState)(null);
+	/** Only ever holds a controller this provider created for a host lacking one. */
 	const ownedUiRef = (0, react.useRef)(null);
 	const setSuperDoc = (0, react.useCallback)((superdoc) => {
 		const hostUi = superdoc.ui;
@@ -37,15 +65,33 @@ function useContextValue() {
 	if (!value) throw new Error("[superdoc/ui/react] hooks must be used within <SuperDocUIProvider>.");
 	return value;
 }
+/**
+* Read the controller, or `null` until a SuperDoc instance is bound.
+*
+* Borrowed: the bound instance owns teardown, so the returned type omits
+* `destroy()`. A provider-built fallback controller is disposed by the provider.
+*/
 function useSuperDocUI() {
 	return useContextValue().ui;
 }
+/** Read the raw bound SuperDoc host, or `null` until one is bound. */
 function useSuperDocHost() {
 	return useContextValue().host;
 }
+/** Get the stable callback used to bind a running SuperDoc instance. */
 function useSetSuperDoc() {
 	return useContextValue().setSuperDoc;
 }
+/**
+* Normalize a `pick` result into a {@link SliceSource}. Domain handles and the
+* command/font hooks already expose the snapshot-shaped contract
+* (`getSnapshot` + `observe`) and pass through unchanged. A raw `ui.select(...)`
+* {@link Subscribable} (`get` + `subscribe`) is adapted: it `subscribe`s FIRST,
+* then emits the current value, so a synchronous recompute triggered by the
+* first listener is not missed (the substrate's `subscribe` does not emit on
+* attach). Exported for unit tests; not re-exported by the `superdoc/ui/react`
+* facade, so it stays off the public surface.
+*/
 function toSliceSource(source) {
 	const candidate = source;
 	if (typeof candidate.getSnapshot === "function" && typeof candidate.observe === "function") return source;
@@ -59,6 +105,13 @@ function toSliceSource(source) {
 		}
 	};
 }
+/**
+* Subscribe to a derived slice of controller state. `pick` selects a value
+* source from the controller: a domain handle / snapshot source
+* ({@link SliceSource}) or a raw `ui.select(...)` {@link Subscribable}, both
+* normalized via {@link toSliceSource}. `initial` is returned until the
+* controller is bound.
+*/
 function useSuperDocSlice(pick, initial) {
 	const ui = useSuperDocUI();
 	const [value, setValue] = (0, react.useState)(() => ui ? toSliceSource(pick(ui)).getSnapshot() : initial);
@@ -83,9 +136,11 @@ var EMPTY_SELECTION = {
 	activeChangeIds: [],
 	quotedText: ""
 };
+/** Subscribe to the selection slice. */
 function useSuperDocSelection() {
 	return useSuperDocSlice((ui) => ui.selection, EMPTY_SELECTION);
 }
+/** Subscribe to the comments slice. */
 function useSuperDocComments() {
 	return useSuperDocSlice((ui) => ui.comments, {
 		status: "pending",
@@ -96,6 +151,7 @@ function useSuperDocComments() {
 		activeId: null
 	});
 }
+/** Subscribe to the content-controls slice. */
 function useSuperDocContentControls() {
 	return useSuperDocSlice((ui) => ui.contentControls, {
 		status: "pending",
@@ -105,6 +161,7 @@ function useSuperDocContentControls() {
 		activeIds: []
 	});
 }
+/** Subscribe to the track-changes slice. */
 function useSuperDocTrackChanges() {
 	return useSuperDocSlice((ui) => ui.trackChanges, {
 		status: "pending",
@@ -114,6 +171,7 @@ function useSuperDocTrackChanges() {
 		authors: []
 	});
 }
+/** Subscribe to the toolbar snapshot slice. */
 function useSuperDocToolbar() {
 	return useSuperDocSlice((ui) => ui.toolbar, {
 		context: null,
@@ -121,6 +179,7 @@ function useSuperDocToolbar() {
 		copyFormatActive: false
 	});
 }
+/** Subscribe to a single command's enable/active state. */
 function useSuperDocCommand(id) {
 	return useSuperDocSlice((ui) => ({
 		getSnapshot: () => ui.commands.get(id).getState(),
@@ -131,6 +190,7 @@ function useSuperDocCommand(id) {
 		supported: false
 	});
 }
+/** Subscribe to the document slice. */
 function useSuperDocDocument() {
 	return useSuperDocSlice((ui) => ui.document, {
 		ready: false,
@@ -138,18 +198,21 @@ function useSuperDocDocument() {
 		dirty: false
 	});
 }
+/** Subscribe to available font-family options. */
 function useSuperDocFontOptions() {
 	return useSuperDocSlice((ui) => ({
 		getSnapshot: () => ui.fonts.getFamilyOptions(),
 		observe: (cb) => ui.fonts.observe((slice) => cb(slice.options))
 	}), []);
 }
+/** Subscribe to available font-size options. */
 function useSuperDocFontSizeOptions() {
 	return useSuperDocSlice((ui) => ({
 		getSnapshot: () => ui.fonts.getSizeOptions(),
 		observe: (cb) => ui.fonts.observe((slice) => cb(slice.sizeOptions))
 	}), []);
 }
+/** Subscribe to the zoom slice. */
 function useSuperDocZoom() {
 	return useSuperDocSlice((ui) => ui.zoom, {
 		mode: null,
@@ -158,6 +221,7 @@ function useSuperDocZoom() {
 		max: 100
 	});
 }
+//#endregion
 exports.SuperDocUIProvider = SuperDocUIProvider;
 exports.useSetSuperDoc = useSetSuperDoc;
 exports.useSuperDocCommand = useSuperDocCommand;