superdoc 2.22.0-next.14 → 2.22.0-next.16

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.14",
+	superdocVersion: "2.22.0-next.16",
 	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.14",
+	superdocVersion: "2.22.0-next.16",
 	roomSchemaVersion: Object.freeze({ ...PRIVATE_ENGINE_INFO.roomSchemaVersion }),
 	supportedBundleVersions: SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS,
 	supportedV1ReaderContractVersions: SUPPORTED_V1_READER_CONTRACT_VERSIONS

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

@@ -840,6 +840,8 @@ export declare const isExplicitNoneBorder: (border?: unknown) => boolean;
  */
 export declare const resolveBorderConflict: (first?: BorderSpec, second?: BorderSpec) => BorderSpec | undefined;
 export type TableCellAttrs = {
+    /** Resolved ordinary Latin text rotation from w:tcPr/w:textDirection. */
+    textDirection?: 'btLr' | 'tbRl';
     borders?: CellBorders;
     padding?: BoxSpacing;
     verticalAlign?: 'top' | 'middle' | 'center' | 'bottom';
@@ -891,6 +893,8 @@ export type TableCell = {
     attrs?: TableCellAttrs;
     sourceAnchor?: SourceAnchor;
 };
+/** Read the resolved cell axis, with compatibility for older raw carriers. */
+export declare function getTableCellTextDirection(attrs: TableCellAttrs | undefined): 'btLr' | 'tbRl' | undefined;
 export type TableRowProperties = {
     repeatHeader?: boolean;
     cantSplit?: boolean;
@@ -1671,13 +1675,9 @@ export declare function allExplicitColumnWidthsEqual(widths: readonly number[]):
 /**
  * Shared "genuinely unequal explicit column widths" predicate (SD-2324).
  *
- * The layout engine skips end-of-section column balancing exactly when this
- * is true: Word fills genuinely-unequal explicit columns column-by-column
- * rather than rebalancing them. Host retained-layout dependency scanning
- * (SD-3772) consumes the same predicate so checkpoint admission can never
- * drift from the engine's balancing semantics. Explicit widths that are all
- * EQUAL (`equalWidth="0"` with every `<w:col w:w>` equal) still balance like
- * implicit equal columns and are NOT genuinely unequal.
+ * Unequal geometry requires width-aware paragraph reflow during balancing;
+ * equal explicit widths can use the same fixed-line balancing as implicit
+ * equal columns. This predicate describes geometry, not balancing eligibility.
  */
 export declare function hasGenuinelyUnequalExplicitColumnWidths(columns: {
     equalWidth?: boolean | undefined;
@@ -2067,6 +2067,8 @@ export type ParagraphAttrs = {
      * See `@superdoc/contracts/direction-context` for axis semantics.
      */
     directionContext?: ParagraphDirectionContext;
+    /** Authored paragraph writing-mode override; kept distinct from inherited cell rotation. */
+    textDirection?: string;
     isTocEntry?: boolean;
     tocInstruction?: string;
     /** Stable id shared by every paragraph in the same TOC (docPartObj uniqueId or parent sdBlockId). */
@@ -2413,6 +2415,12 @@ export type TableCellMeasure = {
     paragraph?: ParagraphMeasure;
     width: number;
     height: number;
+    /** Resolved whole-cell rotated flow; dimensions exclude physical padding/borders. */
+    verticalText?: {
+        direction: 'btLr' | 'tbRl';
+        inlineSize: number;
+        blockSize: number;
+    };
     /** Starting grid column index (0-based) */
     gridColumnStart?: number;
     /** Number of grid columns this cell spans */

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;
@@ -351,8 +372,7 @@ export type IncrementalPaginationProof = IncrementalPaginationProofBase & ({
         predecessorBlockId: string | null;
     };
     /**
-     * SD-3772 D1: true means the host proved (via the shared
-     * `hasGenuinelyUnequalExplicitColumnWidths` predicate) that no
+     * SD-3772 D1: true means the host proved that no
      * potentially balanceable multi-column section exists anywhere in the
      * retained document. Balancing is a post-pagination finalizer that a
      * mid-section checkpoint cannot seed. False is admissible only
@@ -513,8 +533,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/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;