superdoc 2.22.0-next.13 → 2.22.0-next.15

package/dist/collaboration-upgrade-engine.cjs

@@ -19,7 +19,7 @@ var COLLABORATION_UPGRADE_ENGINE_MINIMUM_NODE_MAJOR = 20;
 var PRIVATE_ENGINE_INFO = (0, _superdoc_docx_engine_collaboration_upgrade_engine.getCollaborationUpgradeEngineInfo)();
 var ENGINE_INFO = Object.freeze({
 	...PRIVATE_ENGINE_INFO,
-	superdocVersion: "2.22.0-next.13",
+	superdocVersion: "2.22.0-next.15",
 	roomSchemaVersion: Object.freeze({ ...PRIVATE_ENGINE_INFO.roomSchemaVersion }),
 	supportedBundleVersions: SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS,
 	supportedV1ReaderContractVersions: SUPPORTED_V1_READER_CONTRACT_VERSIONS

package/dist/collaboration-upgrade-engine.es.js

@@ -18,7 +18,7 @@ var COLLABORATION_UPGRADE_ENGINE_MINIMUM_NODE_MAJOR = 20;
 var PRIVATE_ENGINE_INFO = getCollaborationUpgradeEngineInfo$1();
 var ENGINE_INFO = Object.freeze({
 	...PRIVATE_ENGINE_INFO,
-	superdocVersion: "2.22.0-next.13",
+	superdocVersion: "2.22.0-next.15",
 	roomSchemaVersion: Object.freeze({ ...PRIVATE_ENGINE_INFO.roomSchemaVersion }),
 	supportedBundleVersions: SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS,
 	supportedV1ReaderContractVersions: SUPPORTED_V1_READER_CONTRACT_VERSIONS

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

@@ -1,6 +1,6 @@
 import { NonFlowingPageRelativeAnchorDependencyProof, PageCheckpointDependencyClass, FlowBlock, Layout, LayoutBlockResumeCheckpoint, Measure, Page, HeaderFooterLayout, ColumnLayout } from '../../contracts/src/index.js';
 import { FontMeasureCapabilities, FontMeasureContext } from '../../../shared/font-system/src/index.js';
-import { LayoutOptions, HeaderFooterConstraints, LayoutExecutionCheckpoint } from '../../layout-engine/src/index.js';
+import { LayoutContinuationResume, LayoutOptions, HeaderFooterConstraints, LayoutExecutionCheckpoint } from '../../layout-engine/src/index.js';
 import { computeDirtyRegions } from './diff.js';
 import { MeasureCache } from './cache.js';
 import { HeaderFooterBatch } from './layoutHeaderFooter.js';
@@ -127,8 +127,28 @@ export type IncrementalLayoutResult = {
      * and `pageTokenTotalMs` includes token remeasure/relayout details.
      */
     bridgeTiming: IncrementalLayoutBridgeTiming;
+    progressive?: {
+        status: 'pending';
+        completedPageRange: {
+            startPageIndex: number;
+            endPageIndexExclusive: number;
+        };
+        completedRanges: readonly {
+            startOrdinal: number;
+            endOrdinalExclusive: number;
+        }[];
+        resume: LayoutContinuationResume;
+        continuation: IncrementalLayoutContinuation;
+        pageCountFieldsExact: false;
+    };
+    progressiveFallbackReason?: string;
+};
+export type IncrementalLayoutContinuation = {
+    advance(execution?: IncrementalLayoutExecutionControl): Promise<IncrementalLayoutResult>;
+    dispose(): void;
 };
 export type IncrementalLayoutBridgeTiming = {
+    paginationPreparationRejection?: string;
     /** Content-free reason a document used the conservative note fallback. */
     footnoteCoupledRejection?: string;
     totalMs: number;
@@ -184,6 +204,7 @@ export type IncrementalLayoutBridgeTiming = {
         pagesPaginated: number | null;
         pagesSplicedByReuse: number;
         paginationPasses: number;
+        paginationPreparationReuses?: number;
         pageTokenRelayouts: number;
         headerFooterPreLayoutReuses: number;
         headerFooterPreLayoutBodyBlocksEnumerated: number;
@@ -513,8 +534,14 @@ export interface IncrementalLayoutExecutionControl {
     yieldEveryBlocks?: number;
     /** Time-aware mounted probe. Null is the allocation-free under-budget path. */
     checkpointIfDue?: (checkpoint?: LayoutExecutionCheckpoint) => Promise<void> | null;
+    progressive?: {
+        firstBatchPageCount?: number;
+        restartBeforeBlockIndex?: number;
+        restartBeforePageIndex?: number;
+    };
 }
-export declare function incrementalLayout(previousBlocks: FlowBlock[], _previousLayout: Layout | null, nextBlocks: FlowBlock[], options: LayoutOptions, measureBlock: (block: FlowBlock, constraints: {
+export declare function incrementalLayout(...args: Parameters<typeof incrementalLayoutComplete>): Promise<IncrementalLayoutResult>;
+declare function incrementalLayoutComplete(previousBlocks: FlowBlock[], _previousLayout: Layout | null, nextBlocks: FlowBlock[], options: LayoutOptions, measureBlock: (block: FlowBlock, constraints: {
     maxWidth: number;
     maxHeight: number;
 }) => Promise<Measure>, headerFooter?: {

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

@@ -4,9 +4,9 @@ export type { HeaderFooterType } from '../../contracts/src/index.js';
 export { selectHeaderFooterVariantForPage, resolveEffectiveHeaderFooterRef, type HeaderFooterKind, type HeaderFooterVariant, type HeaderFooterSectionRefs, type HeaderFooterResolutionSection, type HeaderFooterVariantSelectionInput, type HeaderFooterEffectiveRefInput, type HeaderFooterEffectiveRefResult, } from '../../contracts/src/index.js';
 export { extractIdentifierFromConverter, getHeaderFooterType, defaultHeaderFooterIdentifier, resolveHeaderFooterForPage, buildMultiSectionIdentifier, defaultMultiSectionIdentifier, getHeaderFooterTypeForSection, getHeaderFooterIdForPage, resolveHeaderFooterForPageAndSection, } from './headerFooterUtils.js';
 export type { HeaderFooterIdentifier, MultiSectionHeaderFooterIdentifier, SectionHeaderFooterIds, } from './headerFooterUtils.js';
-export { layoutHeaderFooterWithCache, invalidateHeaderFooterMeasureCache, type HeaderFooterBatchResult, getBucketForPageNumber, getBucketRepresentative, } from './layoutHeaderFooter.js';
+export { layoutHeaderFooterWithCache, createRetainedHeaderFooterPageReader, invalidateHeaderFooterMeasureCache, type HeaderFooterBatchResult, getBucketForPageNumber, getBucketRepresentative, } from './layoutHeaderFooter.js';
 export type { HeaderFooterBatch, DigitBucket } from './layoutHeaderFooter.js';
-export { resolveHeaderFooterTokens, PROVISIONAL_PAGE_COUNT_PLACEHOLDER, type ResolveHeaderFooterTokensOptions, } from './resolveHeaderFooterTokens.js';
+export { resolveHeaderFooterTokens, cloneHeaderFooterBlocks, PROVISIONAL_PAGE_COUNT_PLACEHOLDER, type ResolveHeaderFooterTokensOptions, } from './resolveHeaderFooterTokens.js';
 export { buildPageStyleReferenceResolver, flowBlocksContainCrossReferenceMetadata, type PageStyleReferenceResolver, } from './resolveLiveCrossReferences.js';
 export { findWordBoundaries, findParagraphBoundaries } from './text-boundaries.js';
 export type { BoundaryRange } from './text-boundaries.js';
@@ -14,7 +14,7 @@ export { buildSectionAwareHeaderFooterLayoutKey, buildSectionContentWidth, build
 export type { HeaderFooterSectionKind, HeaderFooterRefs, SectionAwareHeaderFooterMeasurementGroup, } from './sectionAwareHeaderFooter.js';
 export { clearIncrementalModuleState, incrementalLayout, measureCache, normalizeMargin } from './incrementalLayout.js';
 export { hashMeasureContent } from './cache.js';
-export type { HeaderFooterLayoutResult, HeaderFooterGeometrySeed, IncrementalLayoutBridgeTiming, IncrementalLayoutResult, IncrementalLayoutExecutionControl, IncrementalMeasureReuseProof, IncrementalLayoutReuseOptions, IncrementalLayoutReuseSummary, IncrementalSectionPageNumberTransform, IncrementalLayoutTailAdoption, IncrementalLayoutTailDisposition, IncrementalPaginationProof, LayoutPositionTransform, FootnoteReserveSeed, } from './incrementalLayout.js';
+export type { HeaderFooterLayoutResult, HeaderFooterGeometrySeed, IncrementalLayoutBridgeTiming, IncrementalLayoutResult, IncrementalLayoutExecutionControl, IncrementalLayoutContinuation, IncrementalMeasureReuseProof, IncrementalLayoutReuseOptions, IncrementalLayoutReuseSummary, IncrementalSectionPageNumberTransform, IncrementalLayoutTailAdoption, IncrementalLayoutTailDisposition, IncrementalPaginationProof, LayoutPositionTransform, FootnoteReserveSeed, } from './incrementalLayout.js';
 export { collectFootnoteLedgers, getPreferredReserveCandidates, getPreferredReserveTrialTargets, isMandatoryOnlyFootnotePage, scoreFootnoteWindow, summarizeFootnoteWindow, } from './footnote-scorer.js';
 export type { FootnotePreferredReserveCandidate, FootnoteWindowScoreInput, FootnoteWindowScoreReason, FootnoteWindowScoreResult, FootnoteWindowStats, } from './footnote-scorer.js';
 export { computeDisplayPageNumber } from '../../layout-engine/src/index.js';

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

@@ -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/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

@@ -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
@@ -99,6 +99,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 +107,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/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/superdoc.cjs

@@ -316,7 +316,7 @@ var shuffleArray = (array) => {
 var DEFAULT_ENDPOINT = "https://ingest.superdoc.dev/v1/collect";
 function getSuperdocVersion() {
 	try {
-		return "2.22.0-next.13";
+		return "2.22.0-next.15";
 	} catch {
 		return "unknown";
 	}
@@ -46382,7 +46382,7 @@ var SuperDoc = class extends require_eventemitter3.import_eventemitter3.default
 		this.config.colors = shuffleArray(this.config.colors);
 		this.userColorMap = /* @__PURE__ */ new Map();
 		this.colorIndex = 0;
-		this.version = "2.22.0-next.13";
+		this.version = "2.22.0-next.15";
 		this.#log("🦋 [superdoc] Using SuperDoc version:", this.version);
 		this.superdocId = config.superdocId || require_uuid.v4();
 		this.colors = this.config.colors ?? [];

package/dist/superdoc.es.js

@@ -314,7 +314,7 @@ var shuffleArray = (array) => {
 var DEFAULT_ENDPOINT = "https://ingest.superdoc.dev/v1/collect";
 function getSuperdocVersion() {
 	try {
-		return "2.22.0-next.13";
+		return "2.22.0-next.15";
 	} catch {
 		return "unknown";
 	}
@@ -46311,7 +46311,7 @@ var SuperDoc = class extends import_eventemitter3.default {
 		this.config.colors = shuffleArray(this.config.colors);
 		this.userColorMap = /* @__PURE__ */ new Map();
 		this.colorIndex = 0;
-		this.version = "2.22.0-next.13";
+		this.version = "2.22.0-next.15";
 		this.#log("🦋 [superdoc] Using SuperDoc version:", this.version);
 		this.superdocId = config.superdocId || v4();
 		this.colors = this.config.colors ?? [];