superdoc 2.22.0-next.9 → 2.22.1-next.1

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

@@ -85,6 +85,9 @@ export declare function getBucketForPageNumber(pageNumber: number): DigitBucket;
  * ```
  */
 export declare function getBucketRepresentative(bucket: DigitBucket): number;
+type RetainedBucketContext = ReturnType<PageResolver>;
+/** Reads only a measured bucket issued by this canonical layout operation. */
+export declare function createRetainedHeaderFooterPageReader(layout: HeaderFooterLayout, blocks: FlowBlock[], constraints: HeaderFooterConstraints, fontSignature: string): ((context: RetainedBucketContext) => HeaderFooterLayout['pages'][number] | null) | null;
 export declare class HeaderFooterLayoutCache {
     private readonly cache;
     /** Drop every cached header/footer measure (equivalence-oracle cold start). */
@@ -128,3 +131,4 @@ export declare function invalidateHeaderFooterMeasureCache(blockIds: string[]):
  * @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, lineRegions?: readonly (readonly ParagraphLineRegion[])[]) => ParagraphMeasure, options?: ResolveHeaderFooterTokensOptions, execution?: HeaderFooterLayoutExecution): Promise<HeaderFooterBatchResult>;
+export {};

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

@@ -40,19 +40,19 @@ 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 collectPreRegisteredAnchorsSteps(blocks: FlowBlock[], measures: Measure[], checkpointEveryBlocks?: number | null, candidateIndices?: readonly number[]): Generator<LayoutWorkCheckpoint, AnchoredDrawing[], void>;
 export declare function collectPreRegisteredAnchors(blocks: FlowBlock[], measures: Measure[]): AnchoredDrawing[];
 /** Collect page- or margin-relative floating tables before paragraph layout. */
-export declare function collectPreRegisteredTablesSteps(blocks: FlowBlock[], measures: Measure[], checkpointEveryBlocks?: number | null): Generator<LayoutWorkCheckpoint, AnchoredTable[], void>;
+export declare function collectPreRegisteredTablesSteps(blocks: FlowBlock[], measures: Measure[], checkpointEveryBlocks?: number | null, candidateIndices?: readonly number[]): Generator<LayoutWorkCheckpoint, AnchoredTable[], void>;
 /**
  * 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 collectAnchoredDrawingsSteps(blocks: FlowBlock[], measures: Measure[], checkpointEveryBlocks?: number | null, preparedParagraphIndexById?: Map<string, number>, candidateIndices?: readonly number[]): 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 collectAnchoredTablesSteps(blocks: FlowBlock[], measures: Measure[], checkpointEveryBlocks?: number | null, preparedParagraphIndexById?: Map<string, number>, candidateIndices?: readonly number[]): Generator<LayoutWorkCheckpoint, AnchoredTableCollection, void>;
 export declare function collectAnchoredTables(blocks: FlowBlock[], measures: Measure[]): AnchoredTableCollection;

package/dist/layout-engine/layout-engine/src/column-balancing.d.ts

@@ -250,8 +250,8 @@ export interface BalanceSectionOnPageArgs {
  * Guards (skip balancing when):
  *   - Section has <= 1 column (nothing to balance)
  *   - Section contains an explicit column break (author intent wins)
- *   - Section uses GENUINELY-unequal column widths (Word fills these column-by-column;
- *     explicit widths that are all equal still balance — SD-2324)
+ *   - Section uses genuinely unequal widths, which require width-aware reflow
+ *     rather than this redistribution of fixed line measurements
  *   - No fragments on this page belong to the section
  */
 export declare function balanceSectionOnPage(args: BalanceSectionOnPageArgs): {

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

@@ -1,4 +1,4 @@
-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:table-fragment' | 'layout-document:footnote-continuation' | '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 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:paragraph-fragment' | 'layout-document:table-fragment' | 'layout-document:footnote-continuation' | '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;

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

@@ -3,7 +3,7 @@ import { FootnotePageFlow } from './footnote-page-flow.js';
 import { PageState, ConstraintBoundary } from './paginator.js';
 import { LayoutExecutionControl } from './execution.js';
 export type { FootnotePageFlow } from './footnote-page-flow.js';
-export { findLineIndexForRunOrdinal } from './layout-utils.js';
+export { findLineIndexForRunOrdinal, findKeepNextChainStart, isOutOfFlowDrawing } from './layout-utils.js';
 type PageSize = {
     w: number;
     h: number;
@@ -275,6 +275,33 @@ export type HeaderFooterConstraints = {
  */
 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 LayoutContinuationResume = {
+    nextBlockIndex: number;
+    nextPageIndex: number;
+    pageIndex: number;
+    checkpointIdentity: object;
+    paragraphLineIndex?: number;
+    tableRowIndex?: number;
+};
+export type LayoutContinuationBatch = {
+    layout: Layout;
+    pageRange: {
+        startPageIndex: number;
+        endPageIndexExclusive: number;
+    };
+    status: 'pending' | 'complete';
+    resume: LayoutContinuationResume;
+    completeReason?: string;
+};
+export type LayoutDocumentContinuation = {
+    advance(input?: {
+        pageCount?: number;
+        execution?: LayoutExecutionControl;
+    }): Promise<LayoutContinuationBatch>;
+    dispose(): void;
+};
+/** AIDEV-NOTE: The handle owns one live paginator; advancing never replays a stopped prefix. */
+export declare function createLayoutDocumentContinuation(blocks: FlowBlock[], measures: Measure[], options?: LayoutOptions, execution?: LayoutExecutionControl): LayoutDocumentContinuation;
 export type LayoutRangeBoundaryPolicy = 'conservative-context' | 'overscan' | 'degraded-on-incomplete-state';
 export type LayoutRangeExactness = 'exact' | 'pending-layout' | 'degraded-unsupported' | 'stale';
 export type LayoutRangeSourceRange = {

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

@@ -6,4 +6,7 @@ import { FlowBlock, Measure, Page } from '../../contracts/src/index.js';
  * 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;
+export declare function alignInlineZeroHeightDrawingFragments(pages: Page[], blocks: FlowBlock[], measures: Measure[], indices?: {
+    blockById: ReadonlyMap<string, FlowBlock>;
+    measureById: ReadonlyMap<string, Measure | undefined>;
+}): void;

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

@@ -1,7 +1,7 @@
 import { FloatingObjectManager } from './floating-objects.js';
 import { PageState } from './paginator.js';
 import { FootnotePageFlow } from './footnote-page-flow.js';
-import { PageMargins, ParagraphBlock, ParagraphMeasure, ImageBlock, ImageMeasure, DrawingBlock, DrawingMeasure, ParagraphLineRegion, ColumnLayoutForAnchor } from '../../contracts/src/index.js';
+import { PageMargins, ParagraphBlock, ParagraphMeasure, ImageBlock, ImageMeasure, DrawingBlock, DrawingMeasure, TableBlock, TableMeasure, ParagraphLineRegion, ColumnLayoutForAnchor } from '../../contracts/src/index.js';
 import { AnchoredTable } from './anchors.js';
 /**
  * SD-2656: ordered footnote anchor entry. The body slicer reads the candidate
@@ -21,6 +21,7 @@ export type ParagraphLayoutContext = {
     block: ParagraphBlock;
     measure: ParagraphMeasure;
     columnWidth: number;
+    columnWidthForState?: (state: PageState) => number;
     ensurePage: () => PageState;
     advanceColumn: (state: PageState) => PageState;
     columnX: (state: PageState, columnIndex?: number) => number;
@@ -32,6 +33,8 @@ export type ParagraphLayoutContext = {
      * When undefined, uses the value from block.attrs.spacing.after.
      */
     overrideSpacingAfter?: number;
+    /** A keep-next preflight moved this paragraph to a fresh page. */
+    suppressSpacingBefore?: boolean;
     /**
      * SD-3049 / SD-2656: footnote demand under the ordered-cluster rule.
      *
@@ -99,6 +102,7 @@ export type AnchoredDrawingEntry = {
 export type ParagraphAnchorsContext = {
     anchoredDrawings?: AnchoredDrawingEntry[];
     anchoredTables?: AnchoredTable[];
+    resolveCurrentTable?: (id: string, measure: TableMeasure) => TableBlock;
     columnWidth: number;
     pageWidth: number;
     pageMargins: PageMargins;
@@ -106,4 +110,8 @@ export type ParagraphAnchorsContext = {
     columns: ColumnLayoutForAnchor;
     placedAnchoredIds: Set<string>;
 };
+export declare function layoutParagraphBlockSteps(ctx: ParagraphLayoutContext, anchors?: ParagraphAnchorsContext): Generator<{
+    index: number;
+    total: number;
+}, void, void>;
 export declare function layoutParagraphBlock(ctx: ParagraphLayoutContext, anchors?: ParagraphAnchorsContext): void;

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

@@ -1,4 +1,4 @@
-import { Line, ParagraphBlock, ParagraphMeasure, LinePmRange } from '../../contracts/src/index.js';
+import { FlowBlock, Line, ParagraphBlock, ParagraphMeasure, LinePmRange } from '../../contracts/src/index.js';
 /**
  * Tracks which paragraph spacing properties were explicitly set.
  *
@@ -104,3 +104,7 @@ export declare function computeParagraphLayoutStartY(input: {
 export declare const extractBlockPmRange: (block: {
     attrs?: Record<string, unknown>;
 } | null | undefined) => LinePmRange;
+/** Positioned drawings are laid out by their owner, rather than consuming a flow slot. */
+export declare function isOutOfFlowDrawing(block: FlowBlock): boolean;
+/** Find the kept paragraph whose page decision also owns this flow block. */
+export declare function findKeepNextChainStart(blocks: readonly FlowBlock[], index: number): number;

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

@@ -0,0 +1,6 @@
+import { Line, ParagraphBlock } from '../../contracts/src/index.js';
+/** Build a measurement-only suffix while keeping line coordinates in the original paragraph. */
+export declare function paragraphContinuation(block: ParagraphBlock, first: Line): {
+    block: ParagraphBlock;
+    mapLine: (line: Line) => Line;
+};

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

@@ -66,5 +66,5 @@ 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 computeNextSectionPropsAtBreakSteps(blocks: FlowBlock[], checkpointEveryBlocks?: number | null, candidateIndices?: readonly number[]): Generator<SectionPropsScanCheckpoint, Map<number, SectionProps>, void>;
 export declare function computeNextSectionPropsAtBreak(blocks: FlowBlock[]): Map<number, SectionProps>;

package/dist/layout-engine/layout-engine/src/source-preparation.d.ts

@@ -0,0 +1,52 @@
+import { FlowBlock, Measure } from '../../contracts/src/index.js';
+export type CanonicalPaginationSourceSplice = {
+    readonly previous: readonly FlowBlock[];
+    readonly current: readonly FlowBlock[];
+    readonly authoredChangedBlockIds: readonly string[];
+    readonly replacements: readonly {
+        start: number;
+        deleteCount: number;
+        insertCount: number;
+    }[];
+};
+export type PaginationSourceScan = {
+    readonly blocks: FlowBlock[];
+    readonly measures: Measure[];
+    readonly indexById: ReadonlyMap<string, number>;
+    readonly candidateIds: readonly string[];
+    readonly dependencyIds?: readonly string[];
+    readonly offset: number;
+    readonly isCurrent?: () => boolean;
+};
+/**
+ * Trusted internal dependency injection for the canonical host source issuer.
+ * This constructor is intentionally absent from the engine's main exports;
+ * opaque tokens offered by generic bridge callers have no authority here.
+ */
+export declare function createCanonicalPaginationSourceReader(read: (previous: readonly FlowBlock[], current: readonly FlowBlock[]) => CanonicalPaginationSourceSplice | null, owns: (source: readonly FlowBlock[]) => boolean): object;
+export declare function isPaginationPreparationCandidate(block: FlowBlock): boolean;
+/** Only the engine's completed input validation issues a scan plan. */
+export declare function retainPaginationSourceScan(blocks: FlowBlock[], measures: Measure[], indexById: ReadonlyMap<string, number>, candidateIds: readonly string[]): void;
+export declare function readPaginationSourceScan(blocks: FlowBlock[], measures: Measure[], requirePrepared?: boolean): PaginationSourceScan | null;
+/**
+ * The canonical owner certifies the exact immutable source recipe. The bridge
+ * separately proves its current dirty measures and index rewrites before calling.
+ * Foreign/copy tokens and mismatched source or measure vectors lose the shortcut.
+ */
+export declare function prepareCanonicalPaginationSource(input: {
+    reader: object;
+    previousBlocks: FlowBlock[];
+    blocks: FlowBlock[];
+    previousMeasures: Measure[];
+    measures: Measure[];
+    dirtyBlockIds: readonly string[];
+    currentIndexById: ReadonlyMap<string, number>;
+    previousToCurrentBlockId?: ReadonlyMap<string, string> | null;
+    onReject?: (reason: string) => void;
+}): boolean;
+/** Only an owned prepared scan may substitute metadata for a clean table preflight read. */
+export declare function createPreparedPaginationMetadataView(blocks: FlowBlock[], measures: Measure[]): FlowBlock[];
+export declare function createPreparedPaginationSuffix(blocks: FlowBlock[], measures: Measure[], start: number, end: number): {
+    blocks: FlowBlock[];
+    measures: Measure[];
+} | null;

package/dist/layout-engine/painters/dom/src/page-content.d.ts

@@ -276,3 +276,9 @@ export type WindowPositionRemapPlan = {
  * sequences — no per-paint key strings or Maps on the steady-state path.
  */
 export declare function planWindowPositionRemap(state: PageDomState, resolvedPage: ResolvedPage): WindowPositionRemapPlan;
+export declare function planDetachedPageFragments(ctx: PageContentContext, state: PageDomState | undefined, page: ResolvedPage, pageIndex: number): Generator<void, {
+    item: ResolvedPaintItem;
+    context: FragmentRenderContext;
+    sdtBoundary?: SdtBoundaryOptions;
+    betweenInfo?: BetweenBorderInfo;
+}[], void>;

package/dist/layout-engine/painters/dom/src/paragraph/renderParagraphContent.d.ts

@@ -1,3 +1,4 @@
+import { RenderWork } from '../render-work.js';
 import { DropCapDescriptor, Line, ParagraphBlock, ParagraphMeasure, ResolvedParagraphContent, Run, SdtMetadata, SourceAnchor } from '../../../../contracts/src/index.js';
 import { MinimalWordLayout } from '../../../../../../shared/common/list-marker-utils';
 import { ResolvePhysicalFamily } from '../../../../../shared/font-system/src/index.js';
@@ -20,7 +21,7 @@ export type ParagraphRenderLineInput = {
     indentOffsetOverride?: number;
     paragraphMarkLeftOffsetOverride?: number;
 };
-export type ParagraphRenderLine = (input: ParagraphRenderLineInput) => HTMLElement;
+export type ParagraphRenderLine = (input: ParagraphRenderLineInput) => HTMLElement | RenderWork<HTMLElement>;
 export type ParagraphRenderDropCap = (descriptor: DropCapDescriptor, measure?: {
     width: number;
     height: number;
@@ -83,5 +84,6 @@ export type RenderParagraphContentResult = {
     totalHeight: number;
     renderedLines: RenderedParagraphLineInfo[];
 };
+export declare function renderParagraphContentWork(params: RenderParagraphContentParams): RenderWork<RenderParagraphContentResult>;
 export declare const renderParagraphContent: (params: RenderParagraphContentParams) => RenderParagraphContentResult;
 export {};

package/dist/layout-engine/painters/dom/src/paragraph/renderParagraphFragment.d.ts

@@ -1,3 +1,4 @@
+import { RenderWork } from '../render-work.js';
 import { ParaFragment, ResolvedFragmentItem, SdtMetadata } from '../../../../contracts/src/index.js';
 import { ResolvePhysicalFamily } from '../../../../../shared/font-system/src/index.js';
 import { SdtBoundaryOptions } from '../sdt/container.js';
@@ -15,7 +16,7 @@ type RenderParagraphFragmentParams = {
     applyFragmentFrame: (el: HTMLElement, fragment: ParaFragment) => void;
     applySdtDataset: (el: HTMLElement | null, metadata?: SdtMetadata | null) => void;
     applyContainerSdtDataset: (el: HTMLElement | null, metadata?: SdtMetadata | null) => void;
-    renderLine: (input: ParagraphRenderLineInput) => HTMLElement;
+    renderLine: (input: ParagraphRenderLineInput) => HTMLElement | RenderWork<HTMLElement>;
     captureLineSnapshot: (lineEl: HTMLElement, options?: {
         sourceAnchor?: ResolvedFragmentItem['sourceAnchor'];
         wrapperEl?: HTMLElement;
@@ -29,5 +30,6 @@ type RenderParagraphFragmentParams = {
      */
     resolvePhysical?: ResolvePhysicalFamily;
 };
+export declare function renderParagraphFragmentWork(params: RenderParagraphFragmentParams): RenderWork<HTMLElement>;
 export declare const renderParagraphFragment: (params: RenderParagraphFragmentParams) => HTMLElement;
 export {};

package/dist/layout-engine/painters/dom/src/persistent-page-surface.d.ts

@@ -75,8 +75,8 @@ export type DomPainterPersistentPageInput = {
 };
 /** Shell registry entry: the persistent page root and its geometry/style reuse key. */
 export type PersistentShellEntry = {
-    element: HTMLElement;
-    shellKey: string;
+    readonly element: HTMLElement;
+    readonly shellKey: string;
 };
 /** Bounded content state for one hydrated page. */
 export type PersistentContentEntry = {
@@ -94,9 +94,10 @@ export type PersistentPageSurfaceState = {
     mount: HTMLElement;
     /** The committed scaffold; reference identity gates the O(1) skip. */
     scaffold: DomPainterPersistentScaffold;
-    shells: Map<number, PersistentShellEntry>;
+    shells: ReadonlyMap<number, PersistentShellEntry>;
     content: Map<number, PersistentContentEntry>;
     integrity: PersistentSurfaceIntegrity;
+    shellStyleSignature: string;
 };
 /**
  * The narrow renderer capabilities this module consumes. The deep
@@ -141,6 +142,6 @@ export declare function disposePersistentPageSurfaceState(state: PersistentPageS
  * shell registry by page index; the content window reconciles every call.
  */
 export declare function reconcilePersistentPageSurface(ctx: PersistentSurfaceRenderContext, previous: PersistentPageSurfaceState | null, input: DomPainterPersistentPageInput, mount: HTMLElement): PersistentPageSurfaceState;
-/** Deep-clone the retained planes for the painter's rollback snapshot. */
+/** Snapshot mutable content metadata; scaffold reconciliation replaces the shell registry. */
 export declare function clonePersistentPageSurfaceState(state: PersistentPageSurfaceState | null, clonePageState: (pageState: PageDomState) => PageDomState): PersistentPageSurfaceState | null;
 export {};

package/dist/layout-engine/painters/dom/src/pm-position-validation.d.ts

@@ -135,6 +135,7 @@ export declare class PositionValidationCollector {
     private verboseLines;
     private suppressedConsole;
     constructor(options?: PositionValidationOptions);
+    clone(policy?: PositionValidationConsolePolicy): PositionValidationCollector;
     get isEnabled(): boolean;
     record(obs: RunPositionObservation): void;
     /** Verbose-mode: one content-free warning per NEW structural key, capped. */

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

@@ -0,0 +1,3 @@
+export type RenderWork<T> = Generator<void, T, void>;
+export declare function completeRenderWork<T>(work: RenderWork<T>): T;
+export declare function resolveRenderWork<T>(value: T | RenderWork<T>): RenderWork<T>;

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

@@ -236,6 +236,7 @@ type PainterFragmentFailure = {
     readonly code: 'painter-fragment-unavailable';
 };
 type PersistentPagePainterTransaction = {
+    prepareCommit(): void;
     commit(): void;
     rollback(): void;
     readFragmentFailures(): readonly PainterFragmentFailure[];
@@ -254,6 +255,11 @@ export declare class DomPainter {
     private totalPages;
     private sectionPageCounts;
     private linkIdCounter;
+    private retainedPaintRevision;
+    private preparedDecorations;
+    private preparedFragments;
+    private detachedPreparationActive;
+    private detachedFragmentFailures;
     private shapeImageFillCounter;
     private wordArtPathCounter;
     private sdtLabelsRendered;
@@ -306,7 +312,7 @@ export declare class DomPainter {
      * live persistent surface and fresh-state oracle never mix counts.
      * Dark unless enabled via options; when dark, `record()` is a single branch.
      */
-    private readonly positionValidation;
+    private positionValidation;
     private paintSnapshotBuilder;
     private lastPaintSnapshot;
     private onPaintSnapshotCallback;
@@ -316,7 +322,7 @@ export declare class DomPainter {
      * from the public DomPainterHandle contract.
      */
     private activePersistentPageTransaction;
-    private persistentPageIndices;
+    private persistentPageCount;
     /** Resolved layout for the next-gen paint pipeline. */
     private resolvedLayout;
     private showFormattingMarks;
@@ -358,8 +364,7 @@ export declare class DomPainter {
     beginPersistentPageTransaction(): PersistentPagePainterTransaction;
     private capturePersistentPagePainterState;
     private restorePersistentPagePainterState;
-    private createAllPageIndices;
-    private setPersistentPageIndices;
+    private setPersistentPageCount;
     private emitPaintSnapshot;
     private beginPaintSnapshot;
     private finalizePaintSnapshotFromBuilder;
@@ -367,6 +372,19 @@ export declare class DomPainter {
     private collectPaintSnapshotFromDomRoot;
     /** Semantic continuous paint. Paginated flow has only `paintPersistentPages()`. */
     paint(input: DomPainterInput, mount: HTMLElement, mapping?: PositionMapping): void;
+    /** Prepare detached content before the host opens its atomic visible transaction. */
+    preparePersistentPages(input: DomPainterPersistentPageInput, options: {
+        mount: HTMLElement;
+        signal?: AbortSignal;
+        yieldToHost?: (checkpoint: {
+            phase: 'paint:content';
+            index: number;
+            total: number;
+        }) => Promise<void>;
+    }): Promise<{
+        input: DomPainterPersistentPageInput;
+        discard(): void;
+    }>;
     /**
      * The persistent paginated reconcile (default persistent page geometry
      * plan, Unit 1): one generation-scoped scaffold owns every page root for
@@ -414,6 +432,7 @@ export declare class DomPainter {
      */
     private resolveSeparatorColumnGeometry;
     private renderDecorationsForPage;
+    private renderDecorationsForPageWork;
     /**
      * Check if a fragment is vertically anchored to the page.
      * Used to determine special Y positioning for page-relative anchored content
@@ -434,7 +453,7 @@ export declare class DomPainter {
      */
     private getDecorationAnchorPageOriginY;
     private getFooterFragmentAnchorPageOriginY;
-    private renderDecorationSection;
+    private renderDecorationSectionWork;
     private resetState;
     dispose(): void;
     private getSectionPageCount;
@@ -467,6 +486,7 @@ export declare class DomPainter {
     private applySemanticPageOverrides;
     private getEffectivePageStyles;
     private renderFragment;
+    private renderFragmentWork;
     /**
      * Renders a paragraph fragment with defensive error handling.
      * Falls back to error placeholder on rendering errors to prevent full paint failure.
@@ -477,6 +497,7 @@ export declare class DomPainter {
      * @returns HTMLElement containing the rendered fragment or error placeholder
      */
     private renderParagraphFragment;
+    private renderParagraphFragmentWork;
     private createErrorPlaceholder;
     private renderImageFragment;
     /**
@@ -606,7 +627,9 @@ export declare class DomPainter {
     /** Render drawing content nested in any canonical table, including a textbox-owned table. */
     private renderDrawingContentForTable;
     private renderTableFragment;
+    private renderTableFragmentWork;
     private renderLine;
+    private renderLineWork;
     private createRunRenderContext;
     private defaultFragmentRenderContext;
     /**

package/dist/layout-engine/painters/dom/src/runs/render-line.d.ts

@@ -1,2 +1,4 @@
+import { RenderWork } from '../render-work.js';
 import { RenderLineParams } from './types.js';
-export declare const renderLine: ({ block, line, context, availableWidthOverride, lineIndex, skipJustify, preExpandedRuns, resolvedListTextStartPx, indentOffsetOverride, paragraphMarkLeftOffsetOverride, runContext, }: RenderLineParams) => HTMLElement;
+export declare function renderLineWork({ block, line, context, availableWidthOverride, lineIndex, skipJustify, preExpandedRuns, resolvedListTextStartPx, indentOffsetOverride, paragraphMarkLeftOffsetOverride, runContext, }: RenderLineParams): RenderWork<HTMLElement>;
+export declare const renderLine: (params: RenderLineParams) => HTMLElement;

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

@@ -46,7 +46,7 @@ export declare const renderInlineTabRun: (run: Extract<Run, {
 tabWidthFromCache?: number) => HTMLElement;
 export declare const renderPositionedTabRun: (run: Extract<Run, {
     kind: "tab";
-}>, line: Line, doc: Document, layoutEpoch: number, tabStartX: number, indentOffset: number, immediateNextSegment?: LineSegment, styleId?: string, paintUnderline?: boolean) => {
+}>, line: Line, doc: Document, layoutEpoch: number, tabStartX: number, indentOffset: number, immediateNextSegment?: LineSegment, styleId?: string, paintUnderline?: boolean, tabWidthFromCache?: number) => {
     element: HTMLElement;
     tabEndX: number;
     actualTabWidth: number;

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

@@ -1,3 +1,4 @@
+import { RenderWork } from '../render-work.js';
 import { CellBorders, DrawingBlock, DrawingMeasure, ImageBlock, Line, ParagraphBlock, SdtMetadata, TableBlock, TableCell, TableMeasure } from '../../../../contracts/src/index.js';
 import { ResolvePhysicalFamily } from '../../../../../shared/font-system/src/index.js';
 import { FragmentRenderContext } from '../renderer.js';
@@ -57,7 +58,7 @@ type TableCellRenderDependencies = {
     /** Whether to apply default border if no borders specified */
     useDefaultBorder?: boolean;
     /** Function to render a line of paragraph content */
-    renderLine: (block: ParagraphBlock, line: Line, context: FragmentRenderContext, lineIndex: number, isLastLine: boolean, resolvedListTextStartPx?: number) => HTMLElement;
+    renderLine: (block: ParagraphBlock, line: Line, context: FragmentRenderContext, lineIndex: number, isLastLine: boolean, resolvedListTextStartPx?: number) => HTMLElement | RenderWork<HTMLElement>;
     /** Optional callback invoked after a table line's final styles/markers are applied. */
     captureLineSnapshot?: (lineEl: HTMLElement, context: FragmentRenderContext, options?: {
         inTableParagraph?: boolean;
@@ -166,5 +167,6 @@ export type TableCellRenderResult = {
  * container.appendChild(cellElement);
  * ```
  */
+export declare function renderTableCellWork(deps: TableCellRenderDependencies): RenderWork<TableCellRenderResult>;
 export declare const renderTableCell: (deps: TableCellRenderDependencies) => TableCellRenderResult;
 export {};

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

@@ -1,3 +1,4 @@
+import { RenderWork } from '../render-work.js';
 import { DrawingBlock, DrawingMeasure, Fragment, Line, ParagraphBlock, SdtMetadata, TableBlock, TableFragment, TableMeasure } from '../../../../contracts/src/index.js';
 import { ResolvePhysicalFamily } from '../../../../../shared/font-system/src/index.js';
 import { FragmentRenderContext } from '../renderer.js';
@@ -39,7 +40,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, resolvedListTextStartPx?: number) => HTMLElement;
+    renderLine: (block: ParagraphBlock, line: Line, context: FragmentRenderContext, lineIndex: number, isLastLine: boolean, resolvedListTextStartPx?: number) => HTMLElement | RenderWork<HTMLElement>;
     /** Optional callback invoked after a table line's final styles/markers are applied. */
     captureLineSnapshot?: (lineEl: HTMLElement, context: FragmentRenderContext, options?: {
         inTableParagraph?: boolean;
@@ -128,5 +129,6 @@ export type TableRenderDependencies = {
  * container.appendChild(tableElement);
  * ```
  */
+export declare function renderTableFragmentWork(deps: TableRenderDependencies): RenderWork<HTMLElement>;
 export declare const renderTableFragment: (deps: TableRenderDependencies) => HTMLElement;
 export {};

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

@@ -1,3 +1,4 @@
+import { RenderWork } from '../render-work.js';
 import { DrawingBlock, DrawingMeasure, Line, ParagraphBlock, PartialRowInfo, SdtMetadata, TableBlock, TableBorders, TableMeasure } from '../../../../contracts/src/index.js';
 import { ResolvePhysicalFamily } from '../../../../../shared/font-system/src/index.js';
 import { FragmentRenderContext } from '../renderer.js';
@@ -59,7 +60,7 @@ type TableRowRenderDependencies = {
     /** Rendering context */
     context: FragmentRenderContext;
     /** 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) => HTMLElement | RenderWork<HTMLElement>;
     /** Optional callback invoked after a table line's final styles/markers are applied. */
     captureLineSnapshot?: (lineEl: HTMLElement, context: FragmentRenderContext, options?: {
         inTableParagraph?: boolean;
@@ -145,5 +146,6 @@ type TableRowRenderDependencies = {
  * // Appends all cell elements to container
  * ```
  */
+export declare function renderTableRowWork(deps: TableRowRenderDependencies): RenderWork<void>;
 export declare const renderTableRow: (deps: TableRowRenderDependencies) => void;
 export {};

package/dist/public/ui-react.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-DTLJMJIl.cjs");
+const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-MSiU8Kg0.cjs");
 const require_slice_source = require("../chunks/slice-source-CFaqq0Vo.cjs");
 let react = require("react");
 //#region src/public/ui/react.ts

package/dist/public/ui-react.es.js

@@ -1,4 +1,4 @@
-import { t as createSuperDocUI } from "../chunks/create-super-doc-ui-Dos1KQcL.es.js";
+import { t as createSuperDocUI } from "../chunks/create-super-doc-ui-DmGX1w-i.es.js";
 import { t as toSliceSource } from "../chunks/slice-source-gfOhG2MW.es.js";
 import { createContext, createElement, useCallback, useContext, useEffect, useRef, useState } from "react";
 //#region src/public/ui/react.ts

package/dist/public/ui-vue.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-DTLJMJIl.cjs");
+const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-MSiU8Kg0.cjs");
 const require_slice_source = require("../chunks/slice-source-CFaqq0Vo.cjs");
 let superdoc_entry_vue = require("vue");
 //#region src/public/ui/vue.ts

package/dist/public/ui-vue.es.js

@@ -1,4 +1,4 @@
-import { t as createSuperDocUI } from "../chunks/create-super-doc-ui-Dos1KQcL.es.js";
+import { t as createSuperDocUI } from "../chunks/create-super-doc-ui-DmGX1w-i.es.js";
 import { t as toSliceSource } from "../chunks/slice-source-gfOhG2MW.es.js";
 import { computed, inject, onScopeDispose, provide, shallowRef, toRaw, toValue, watch } from "vue";
 //#region src/public/ui/vue.ts

package/dist/public/ui.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-DTLJMJIl.cjs");
+const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-MSiU8Kg0.cjs");
 exports.BUILT_IN_COMMAND_IDS = require_create_super_doc_ui.BUILT_IN_COMMAND_IDS;
 exports.createSuperDocUI = require_create_super_doc_ui.createSuperDocUI;
 exports.shallowEqual = require_create_super_doc_ui.shallowEqual;

package/dist/public/ui.es.js

@@ -1,2 +1,2 @@
-import { a as BUILT_IN_COMMAND_IDS, t as createSuperDocUI, u as shallowEqual } from "../chunks/create-super-doc-ui-Dos1KQcL.es.js";
+import { a as BUILT_IN_COMMAND_IDS, t as createSuperDocUI, u as shallowEqual } from "../chunks/create-super-doc-ui-DmGX1w-i.es.js";
 export { BUILT_IN_COMMAND_IDS, createSuperDocUI, shallowEqual };