superdoc 2.3.0 → 2.4.0-next.2

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

@@ -35,7 +35,7 @@ export type PatchPageWork = {
     fragmentsReused: number;
 };
 /**
- * Painter plan §4.6 (dark observability): work performed by the page-window
+ * Painter plan §4.6 (dark observability): work performed by the persistent-page
  * paint path, accumulated across paints until consumed. Fields the path
  * cannot attribute yet are reported as 0/null, never invented:
  * `domNodesCreated` stays null until node counting is instrumented. Since P5,
@@ -49,35 +49,26 @@ export type PatchPageWork = {
  * arrays would grow per paint on the product path.
  */
 export type PaintWorkSummary = {
-    /** Pages newly created (no prior element for the slot). */
-    pagesMounted: number;
-    /** Pages removed because they left the window. */
-    pagesUnmounted: number;
-    /** Pages whose slot survived but whose content was patched or re-rendered. */
-    pagesRebuilt: number;
-    /** Pages left completely untouched (version key match, positions unchanged). */
-    pagesUntouched: number;
-    /**
-     * Retained pages whose header/footer DOM was refreshed after provider
-     * identity changed, without mounting or rebuilding the body page. May
-     * overlap position-remapped pages; never overlaps untouched pages.
-     */
-    pagesDecorationsRefreshed: number;
-    /**
-     * Pages whose content was untouched but whose pm positions were uniformly
-     * shifted in place (painter plan P5): the resolve stamps matched while the
-     * packet-fresh fragment positions drifted — attribute remap, not rebuild.
-     */
-    pagesPositionRemapped: number;
-    /**
-     * Rebuilt pages whose resolve stamps MATCHED but whose position drift could
-     * not be proven a uniform shift (`planPmReuse` demote — e.g. a page mixing
-     * body and notes pm planes under a body edit). A demote is sound painter
-     * behavior, not a reuse regression; the repaint oracle allows exactly these
-     * rebuilds on relevance-UNCHANGED pages (P5x review fix). Always a subset
-     * of the rebuilt counters/arrays.
-     */
-    pagesPmDemoted: number;
+    /** Persistent page roots newly created for a committed scaffold. */
+    persistentPagesCreated: number;
+    /** Persistent page roots reused by index whose exact geometry changed. */
+    persistentPagesUpdated: number;
+    /** Persistent page roots removed by a generation commit (never by scroll). */
+    persistentPagesRemoved: number;
+    /** Pages whose content hydrated into an existing persistent root. */
+    contentHydrated: number;
+    /** Pages whose painter-owned content descendants were removed, root kept. */
+    contentDehydrated: number;
+    /** Hydrated pages reconciled through the fragment-keyed patch. */
+    contentPatched: number;
+    /** Hydrated pages left completely untouched. */
+    contentUntouched: number;
+    /** Hydrated pages whose pm positions were uniformly shifted in place. */
+    contentRemapped: number;
+    /** Hydrated pages whose header/footer DOM refreshed without body rebuild. */
+    contentDecorationsRefreshed: number;
+    /** Hydrated pages demoted from reuse because position drift was not uniform. */
+    contentPmDemoted: number;
     fragmentsRendered: number;
     fragmentsReused: number;
     domNodesCreated: number | null;
@@ -87,17 +78,19 @@ export type PaintWorkSummary = {
      * `remapped ⊆ full-changed ∩ window`) need to know WHICH pages, not how
      * many. Accumulated like the counters, drained on consume.
      */
-    mountedPageIndices: number[];
-    unmountedPageIndices: number[];
-    rebuiltPageIndices: number[];
-    untouchedPageIndices: number[];
-    decorationRefreshedPageIndices: number[];
-    remappedPageIndices: number[];
-    pmDemotedPageIndices: number[];
+    createdPersistentPageIndices: number[];
+    removedPersistentPageIndices: number[];
+    patchedContentPageIndices: number[];
+    untouchedContentPageIndices: number[];
+    decorationRefreshedContentPageIndices: number[];
+    remappedContentPageIndices: number[];
+    pmDemotedContentPageIndices: number[];
+    hydratedContentPageIndices: number[];
+    dehydratedContentPageIndices: number[];
 };
 export declare function createEmptyPaintWorkSummary(): PaintWorkSummary;
 /**
- * Painter plan P3a: reuse key for one exact page slot on the page-window
+ * Painter plan P3a: reuse key for one exact page slot on the persistent-page
  * path. Joins everything the painted page DOM depends on for a fixed page
  * index: the resolve-stage version stamp per item (the product paint-reuse
  * mechanism), fragment identity + geometry (stamps do not cover geometry),
@@ -123,7 +116,7 @@ export declare function createEmptyPaintWorkSummary(): PaintWorkSummary;
  * attribute-for-attribute — that exactness is the proof, never normalize it
  * away at the pass level (only the §7.7 unit tests use the normalized form).
  */
-export declare function pageWindowVersionKey(page: ResolvedPage, totalPages: number, sectionPageCount: number): string | null;
+export declare function persistentPageVersionKey(page: ResolvedPage, totalPages: number, sectionPageCount: number): string | null;
 /**
  * The class state `renderPage`/`patchPage` consume, made explicit. The
  * DomPainter builds one per call (values like `totalPages`, `layoutEpoch`,
@@ -148,7 +141,49 @@ export interface PageContentContext {
     updatePositionAttributes(fragmentEl: HTMLElement, mapping: PositionMapping): void;
     updateFragmentElement(el: HTMLElement, fragment: Fragment, section?: 'body' | 'header' | 'footer', resolvedItem?: ResolvedPaintItem): void;
 }
+/**
+ * The subset of `PageContentContext` needed to build a canonical page shell —
+ * the `.superdoc-page` element with exact geometry, chrome, epoch, and layout
+ * boundary stamps, but no content. Persistent scaffold reconciliation builds
+ * shells through this context and hydrates content independently.
+ */
+export type PageShellContext = Pick<PageContentContext, 'doc' | 'layoutEpoch' | 'getEffectivePageStyles' | 'applySemanticPageOverrides'>;
+/**
+ * The exact page box a shell derives from. `ResolvedPage` satisfies it, and
+ * so does a numbers-only scaffold band — the persistent page surface builds
+ * shells without materializing resolved packets.
+ */
+export type PageShellGeometry = {
+    width: number;
+    height: number;
+};
+/** Refresh geometry and document-level presentation without replacing a page. */
+export declare function refreshPageShell(ctx: PageShellContext, el: HTMLElement, page: PageShellGeometry): void;
+/**
+ * Canonical `.superdoc-page` shell: the one place a paginated page element is
+ * created. The persistent scaffold mounts it bare and bounded content
+ * reconciliation hydrates the same element in place.
+ */
+export declare function renderPageShell(ctx: PageShellContext, page: PageShellGeometry): HTMLElement;
+/**
+ * Content half of page painting: resolved fragments, decorations (headers,
+ * footers, behind-doc sections), and column separators, appended to an
+ * existing page shell. Persistent hydration goes through exactly this
+ * function, so a hydrated page is byte-equivalent to one painted
+ * by the content path from scratch — same element, same append order.
+ */
+export declare function hydratePageContent(ctx: PageContentContext, el: HTMLElement, page: ResolvedPage, pageIndex: number): FragmentDomState[];
 export declare function renderPage(ctx: PageContentContext, page: ResolvedPage, pageIndex: number): PageDomState;
+/**
+ * Inverse of {@link hydratePageContent} (default persistent page geometry
+ * plan, Unit 1): remove the painter-owned content descendants from an
+ * existing page root, leaving root identity, root attributes, page order,
+ * exact geometry, and the document scroll extent untouched. The tracked
+ * fragment list is removed first (authoritative retained state), then any
+ * painter-owned straggler matched by class/attribute — a fragment orphaned
+ * from the retained list must not survive dehydration.
+ */
+export declare function dehydratePageContent(el: HTMLElement, state: PageDomState): void;
 export declare function patchPage(ctx: PageContentContext, state: PageDomState, page: ResolvedPage, pageIndex: number): PatchPageWork;
 export declare function pageContextSignature(context: FragmentRenderContext): string;
 export declare function hasPageContextTokenInBlock(block: FlowBlock | undefined): boolean;
@@ -207,3 +242,36 @@ export declare function resolvedPaintCacheSignature(resolvedItem: ResolvedPaintI
 export declare const fragmentKey: (fragment: Fragment) => string;
 export declare const hasFragmentGeometryChanged: (previous: Fragment, next: Fragment) => boolean;
 export declare const isNonBodyStoryBlockId: (blockId: string | undefined) => boolean;
+/** Order-insensitive equality over two SDT label key sets. */
+export declare function sdtLabelSetsEqual(a: ReadonlySet<string>, b: ReadonlySet<string>): boolean;
+export type WindowPositionRemapEntry = {
+    fragmentState: FragmentDomState;
+    freshItem: ResolvedPaintItem & {
+        fragment: Fragment;
+    };
+    /** Fresh minus retained fragment pmStart — the exact uniform shift. */
+    deltaPm: number;
+};
+export type WindowPositionRemapPlan = {
+    kind: 'none' | 'remap' | 'demote';
+    drifted: WindowPositionRemapEntry[];
+};
+/**
+ * Painter plan P5: decide whether a version-key-matched page is reusable
+ * untouched (`none`), needs an in-place uniform position remap (`remap` —
+ * resolve stamps are pm-insensitive, so unchanged content legitimately
+ * drifts), or must be demoted to the fragment-keyed patch (`demote`, where
+ * `pmReuseUnsound` forces a REAL rebuild of the offending fragment).
+ *
+ * Fail-closed: one-sided pm, a span-LENGTH change, an interior-pm signature
+ * mismatch (a PM node inserted/moved inside the block emits no run, so
+ * stamps stay equal while interior offsets move), a missing interior key, or
+ * pm-bearing DOM under a fragment with no fragment-level pm all demote —
+ * only a PROVABLY uniform drift is shifted in place.
+ *
+ * Pairing is lockstep by index (review fix): this only runs under versionKey
+ * EQUALITY, and the key is an order-sensitive join of every fragment's
+ * key+geometry+stamp, so equal keys imply identical ordered fragment
+ * sequences — no per-paint key strings or Maps on the steady-state path.
+ */
+export declare function planWindowPositionRemap(state: PageDomState, resolvedPage: ResolvedPage): WindowPositionRemapPlan;

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

@@ -0,0 +1,144 @@
+import { DocumentBackground, ResolvedPage } from '../../../contracts/src/index.js';
+import { PageContentContext, PageDomState, PaintWorkSummary } from './page-content.js';
+/**
+ * One exact page band of the committed scaffold (numbers-only,
+ * serializable). Structurally compatible with the host pipeline's
+ * `PageScaffoldPage` so a host scaffold's `pages` array — including a lazy
+ * incremental one — is passed through zero-copy.
+ */
+export type DomPainterPersistentScaffoldPage = {
+    index: number;
+    /** Prefix-sum offset of the page's top edge from the document top. */
+    topPx: number;
+    heightPx: number;
+    widthPx: number;
+    /**
+     * Physical page number for the shell's `data-page-number` stamp (page
+     * numbering can restart per section, so it is data, never `index + 1`).
+     * Optional: absent bands leave the stamp to content hydration — the
+     * painter reports, it never invents.
+     */
+    pageNumber?: number;
+};
+/**
+ * The immutable generation-scoped page scaffold. Reference identity IS the
+ * commit identity: the host builds one scaffold object per committed layout
+ * generation and passes the same object to every same-generation content
+ * paint, so the painter's same-generation skip is O(1).
+ */
+export type DomPainterPersistentScaffold = {
+    /** Layout generation that produced this scaffold (the torn-generation fence). */
+    generation: number;
+    pageCount: number;
+    /**
+     * Uniform inter-page gap in px. The persistent surface owns the vertical
+     * rhythm through the mount's flex `gap`, never through spacer nodes, so
+     * `topPx` must equal the prefix sum of heights plus `gapPx` per boundary.
+     */
+    gapPx: number;
+    /** `last.topPx + last.heightPx`; `0` for an empty document. No trailing gap. */
+    totalHeightPx: number;
+    /** Ascending by `index`; `index` must equal the array position. */
+    pages: readonly DomPainterPersistentScaffoldPage[];
+};
+/**
+ * Read-only exact-packet lookup. A `ReadonlyMap<number, ResolvedPage>`
+ * satisfies it; so does a thin facade over a lazily-resolved page array —
+ * the painter reads only the desired content pages, so untouched document
+ * tails are never materialized by a paint.
+ */
+export interface DomPainterPersistentPacketSource {
+    get(pageIndex: number): ResolvedPage | undefined;
+}
+/**
+ * The one paginated reconcile input (plan §Target Architecture). Shells
+ * always cover the whole scaffold; only the desired content set is bounded.
+ */
+export type DomPainterPersistentPageInput = {
+    scaffold: DomPainterPersistentScaffold;
+    /** Pages whose content must be hydrated (visible window + overscan). */
+    desiredContentPageIndices: readonly number[];
+    /** Interaction pins that must stay hydrated regardless of the window. */
+    pinnedContentPageIndices?: readonly number[];
+    /**
+     * Exact resolved packets by page index, consumed only for desired content
+     * pages. A packet stamped with a different layout epoch than
+     * `scaffold.generation` is a torn generation and fails before DOM
+     * mutation; so does packet page geometry that disagrees with the band.
+     */
+    packetsByPageIndex: DomPainterPersistentPacketSource;
+    sectionPageCounts?: Readonly<Record<string, number>>;
+    documentBackground?: DocumentBackground | null;
+    captureSnapshot?: boolean;
+};
+/** Shell registry entry: the persistent page root and its geometry/style reuse key. */
+export type PersistentShellEntry = {
+    element: HTMLElement;
+    shellKey: string;
+};
+/** Bounded content state for one hydrated page. */
+export type PersistentContentEntry = {
+    state: PageDomState;
+    versionKey: string | null;
+    sdtLabels: ReadonlySet<string>;
+};
+type PersistentSurfaceIntegrity = {
+    dirty: boolean;
+    observer: MutationObserver | null;
+    onInvalidated: () => void;
+};
+/** The retained persistent-surface state the painter snapshots and restores. */
+export type PersistentPageSurfaceState = {
+    mount: HTMLElement;
+    /** The committed scaffold; reference identity gates the O(1) skip. */
+    scaffold: DomPainterPersistentScaffold;
+    shells: Map<number, PersistentShellEntry>;
+    content: Map<number, PersistentContentEntry>;
+    integrity: PersistentSurfaceIntegrity;
+};
+/**
+ * The narrow renderer capabilities this module consumes. The deep
+ * fragment/decoration render call graph stays on the painter class and is
+ * reached through the `PageContentContext` it builds.
+ */
+export interface PersistentSurfaceRenderContext {
+    contentContext: PageContentContext;
+    work: PaintWorkSummary;
+    recordPageWork(kind: PersistentPageWorkKind, pageIndex: number): void;
+    /** Read-and-consume the provider-change decorations-dirty flag. */
+    consumeDecorationsDirty(): boolean;
+    /**
+     * Signature of every non-geometry input to the shell's visual styles
+     * (document background, page-style overrides). Folded into the shell reuse
+     * key so a rare document-presentation change refreshes retained roots
+     * while steady generations skip all shell attribute writes.
+     */
+    shellStyleSignature: string;
+    /** Wake the host's canonical planner when foreign DOM work corrupts page roots. */
+    onIntegrityInvalidated: () => void;
+}
+export type PersistentPageWorkKind = 'createdPersistentPageIndices' | 'removedPersistentPageIndices' | 'patchedContentPageIndices' | 'untouchedContentPageIndices' | 'decorationRefreshedContentPageIndices' | 'remappedContentPageIndices' | 'pmDemotedContentPageIndices' | 'hydratedContentPageIndices' | 'dehydratedContentPageIndices';
+/**
+ * Fail-closed scaffold validation: a scaffold is exact geometry or it is
+ * nothing. The prefix-sum pin also proves the flex-gap layout reproduces the
+ * scaffold offsets exactly, which is what lets the surface drop spacers.
+ */
+export declare function validatePersistentScaffold(scaffold: DomPainterPersistentScaffold): void;
+/** Resolve the validated, deduplicated, ascending desired content set. */
+export declare function resolveDesiredContentPageIndices(input: DomPainterPersistentPageInput): number[];
+/**
+ * Read the live shell-plane integrity without mutating page content. The host
+ * uses this before its zero-work skip so external child-list corruption can
+ * never strand the camera over a missing page until some unrelated repaint.
+ */
+export declare function isPersistentPageSurfaceIntact(state: PersistentPageSurfaceState | null): boolean;
+export declare function disposePersistentPageSurfaceState(state: PersistentPageSurfaceState | null): void;
+/**
+ * The one persistent paginated reconcile. Same-scaffold calls skip shell
+ * work in O(1) (reference identity); scaffold identity changes rebuild the
+ * 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. */
+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

@@ -16,7 +16,7 @@ export type RunCoordinateRequirement = 'legacy-pm-required' | 'story-identity-re
 /** Console verbosity. `off` is production and the performance `--quiet` mode. */
 export type PositionValidationConsolePolicy = 'off' | 'summary' | 'verbose';
 /** Which painter produced the observation (kept isolated per painter instance). */
-export type PaintKind = 'surface-window' | 'dense-reference';
+export type PaintKind = 'persistent-page' | 'persistent-page-oracle' | 'semantic';
 /** Execution realm, for cross-realm report comparison. */
 export type PaintRealm = 'node-headless' | 'browser-inline' | 'browser-worker' | 'product';
 export type PositionValidationSection = 'body' | 'header' | 'footer';

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

@@ -1,5 +1,6 @@
-import { FlowMode, Fragment, PageMargins, PageNumberChapterSeparator, PageNumberFormat, SourceAnchor, DocumentBackground, ResolvedLayout, ResolvedPage, ResolvedPaintItem, LayoutSourceIdentity, LayoutStoryLocator } from '../../../contracts/src/index.js';
+import { FlowMode, Fragment, PageMargins, PageNumberChapterSeparator, PageNumberFormat, SourceAnchor, ResolvedLayout, ResolvedPage, ResolvedPaintItem, LayoutSourceIdentity, LayoutStoryLocator } from '../../../contracts/src/index.js';
 import { PaintWorkSummary } from './page-content.js';
+import { DomPainterPersistentPageInput } from './persistent-page-surface.js';
 import { PageStyles } from './styles.js';
 import { PaintSnapshotStructuredContentBlockEntity, PaintSnapshotStructuredContentInlineEntity } from './sdt/snapshot.js';
 import { PositionValidationOptions, PositionValidationSummary } from './pm-position-validation.js';
@@ -40,56 +41,6 @@ export type RenderedLineInfo = {
 export type DomPainterInput = {
     resolvedLayout: ResolvedLayout;
 };
-export type DomPainterPageWindowExactness = 'exact' | 'estimated' | 'loading' | 'pending-source' | 'pending-layout' | 'degraded-unsupported' | 'failed' | 'stale';
-export type DomPainterPageWindowExtent = {
-    pageIndex: number;
-    topPx: number;
-    heightPx: number;
-    widthPx: number;
-};
-export type DomPainterPageWindowPacket = {
-    pageIndex: number;
-    exactness: DomPainterPageWindowExactness;
-    resolvedPage?: ResolvedPage | null;
-    diagnostic?: string | null;
-};
-export type DomPainterPageWindowInput = {
-    pageExtents: readonly DomPainterPageWindowExtent[];
-    documentExtent?: {
-        pageCount: number;
-        scrollHeightPx: number;
-    };
-    visibleRange: {
-        startPageIndex: number;
-        endPageIndexExclusive: number;
-    };
-    packets: readonly DomPainterPageWindowPacket[];
-    /** Exact document-level section totals; never derive these from the mounted window. */
-    sectionPageCounts?: Readonly<Record<string, number>>;
-    overscan?: number;
-    pinnedPageIndices?: readonly number[];
-    captureSnapshot?: boolean;
-    /**
-     * Document-level page background (OOXML `w:background`), normally read off
-     * `ResolvedLayout.documentBackground` by the caller. Page-window paints own
-     * no `ResolvedLayout`, so without this scalar every windowed page silently
-     * loses the document background dense paint applies (page-window rendering
-     * preflight plan, failure mode 5). Omitted/null = no document background.
-     */
-    documentBackground?: DocumentBackground | null;
-    /**
-     * Layout generation the extents were derived from (painter plan P5x). When
-     * provided, the torn-window guard is ARMED: every exact packet whose page
-     * carries a `layoutEpoch` must match it — a mismatch means the caller mixed
-     * packets from one layout pass with extents from another (torn window),
-     * which paints stale geometry that no per-page version key can catch. Fail
-     * loud instead. When omitted the guard stays dark and mixed stamps are
-     * tolerated — the pre-integration render surface serves
-     * stale-while-revalidate packets beside fresh ones by design; P6a arms the
-     * guard when it wires the windowed path (plan P6a item 6).
-     */
-    layoutEpoch?: number;
-};
 export type PageDecorationPayload = {
     fragments: Fragment[];
     /** Resolved items aligned 1:1 with `fragments`. Same length, same order. */
@@ -278,15 +229,14 @@ export type PaintSnapshot = {
     pages: PaintSnapshotPage[];
     entities: PaintSnapshotEntities;
 };
-type PageWindowPainterTransaction = {
+type PersistentPagePainterTransaction = {
     commit(): void;
     rollback(): void;
 };
 /**
  * DOM-based document painter that renders layout fragments to HTML elements.
- * One paint entry per mode (painter plan P7): `paintPageWindow` owns
- * paginated flow (windowed, page-keyed reuse; a dense paint is a full-range
- * window), `paint()` owns semantic flow (continuous surface).
+ * One paint entry per mode (painter plan P7): the persistent shell/content
+ * reconcile owns paginated flow, while `paint()` owns semantic flow.
  *
  * @class DomPainter
  *
@@ -304,7 +254,6 @@ export declare class DomPainter {
     private doc;
     private pageStates;
     private currentLayout;
-    private denseProofNextPageIndex;
     private changedBlocks;
     private readonly isSemanticFlow;
     private headerProvider?;
@@ -326,22 +275,28 @@ export declare class DomPainter {
     private processedLayoutVersion;
     /** Current transaction mapping for position updates (null if no mapping or complex transaction) */
     private currentMapping;
-    private windowPageStates;
-    private windowMount;
+    /**
+     * Persistent paginated page surface (default persistent page geometry
+     * plan, Unit 1): the generation-owned shell registry plus the bounded
+     * content plane, retained across paints. Snapshot/restored by the private
+     * persistent-page transaction like every other retained plane.
+     */
+    private persistentSurface;
+    private persistentSurfaceInvalidationHandler;
     /**
      * Provider identity may advance every render generation even when the body
-     * page remains reusable. Refresh header/footer DOM on the next window paint
+     * page remains reusable. Refresh header/footer DOM on the next content reconcile
      * without discarding the retained page element or its body fragments.
      */
-    private windowDecorationsDirty;
+    private persistentDecorationsDirty;
     /**
      * Page-window analog of `currentLayout.documentBackground`: the window path
      * deliberately runs with `currentLayout = null`, so the document background
-     * scalar from `DomPainterPageWindowInput` is retained here for
+     * scalar from `DomPainterPersistentPageInput` is retained here for
      * `getEffectivePageStyles()`. Reset by dense `paint()`/`resetState()`/
      * `dispose()` so a stale window value can never leak across modes/mounts.
      */
-    private windowDocumentBackground;
+    private persistentDocumentBackground;
     private paintWork;
     /**
      * P5 §4.6 (review fix): per-page attribution arrays are opt-in. Counters
@@ -352,7 +307,7 @@ export declare class DomPainter {
     private readonly paintWorkAttribution;
     /**
      * Story-aware position-coverage collector, owned per painter instance so the
-     * product surface window and the dense-reference oracle never mix counts.
+     * 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;
@@ -360,12 +315,12 @@ export declare class DomPainter {
     private lastPaintSnapshot;
     private onPaintSnapshotCallback;
     /**
-     * Private page-window transaction state. The package handle exposes this
+     * Private persistent-page transaction state. The package handle exposes this
      * only through a non-enumerable Symbol.for seam; it is deliberately absent
      * from the public DomPainterHandle contract.
      */
-    private activePageWindowTransaction;
-    private mountedPageIndices;
+    private activePersistentPageTransaction;
+    private persistentPageIndices;
     /** Resolved layout for the next-gen paint pipeline. */
     private resolvedLayout;
     private showFormattingMarks;
@@ -376,11 +331,9 @@ export declare class DomPainter {
     private applyFormattingMarksClass;
     private invalidateRenderedContent;
     /**
-     * Forget the page-window surface so the next `paintPageWindow` rebuilds
-     * every page from scratch (fresh-mount branch: clear + `innerHTML = ''`).
-     * Used by invalidations whose inputs are not covered by
-     * `pageWindowVersionKey` and require rebuilding body content (for example,
-     * render-setting changes). Provider swaps use a decoration-only refresh.
+     * Forget the persistent surface so its next reconcile rebuilds content
+     * under the current render settings. Provider swaps use a
+     * decoration-only refresh.
      */
     private invalidateWindowSurface;
     /** Returns the resolved page for a given index, or null if resolved data is unavailable. */
@@ -390,15 +343,12 @@ export declare class DomPainter {
      */
     getPaintSnapshot(): PaintSnapshot | null;
     /**
-     * Returns the page indices that are currently mounted in the DOM.
-     *
-     * Reflects the painter's current mounted set (page-window mounts/unmounts
-     * included) without waiting for a full paint cycle.
+     * Returns the stable page-root indices owned by the current surface.
      */
-    getMountedPageIndices(): number[];
+    getPersistentPageIndices(): number[];
     /**
      * Begin a rollbackable transaction around a content paint. Named for the
-     * paginated page-window path it was minted for; the captured snapshot is
+     * paginated persistent-page path it was minted for; the captured snapshot is
      * the painter's COMPLETE retained/index state, so the same journal serves
      * the semantic flow's dense `paint()` entry (the v2 host's canonical
      * atomic visible commit wraps both paint kinds in one transaction).
@@ -409,41 +359,39 @@ export declare class DomPainter {
      * every painter-owned retained/index plane to references for those restored
      * last-good nodes.
      */
-    beginPageWindowTransaction(): PageWindowPainterTransaction;
-    private capturePageWindowPainterState;
-    private restorePageWindowPainterState;
+    beginPersistentPageTransaction(): PersistentPagePainterTransaction;
+    private capturePersistentPagePainterState;
+    private restorePersistentPagePainterState;
     private createAllPageIndices;
-    private setMountedPageIndices;
+    private setPersistentPageIndices;
     private emitPaintSnapshot;
     private beginPaintSnapshot;
     private finalizePaintSnapshotFromBuilder;
     private capturePaintSnapshotLine;
     private collectPaintSnapshotFromDomRoot;
-    /**
-     * Dense continuous paint. Mode ownership (painter plan P7): semantic flow's
-     * ONLY paint entry, and — for paginated flow — the package-internal dense
-     * REFERENCE implementation kept as the executable spec the equivalence
-     * oracles and kernel tests compare `paintPageWindow` against. Consumers
-     * reach the paginated form exclusively through `createDenseReferencePainter`;
-     * the ordinary `createDomPainter` handle rejects paginated `paint()` calls.
-     */
+    /** Semantic continuous paint. Paginated flow has only `paintPersistentPages()`. */
     paint(input: DomPainterInput, mount: HTMLElement, mapping?: PositionMapping): void;
     /**
-     * Proof-only dense traversal. It preserves the dense painter's document
-     * context and cross-page state while retaining DOM for only one bounded
-     * page interval at a time.
+     * The persistent paginated reconcile (default persistent page geometry
+     * plan, Unit 1): one generation-scoped scaffold owns every page root for
+     * the whole layout generation, and only content descendants are
+     * virtualized. Same-scaffold calls skip shell work in O(1); a new scaffold
+     * identity reconciles page roots by index. There is no viewport-owned shell
+     * set and no spacer node — the scroll extent derives
+     * from the persistent shells plus the container gap alone.
      */
-    paintDensePageBatch(input: DomPainterInput, mount: HTMLElement, startPageIndex: number, endPageIndexExclusive: number): void;
+    paintPersistentPages(input: DomPainterPersistentPageInput, mount: HTMLElement): void;
+    /** True only while the retained document-wide page-shell plane matches the live DOM. */
+    isPersistentPageSurfaceIntact(): boolean;
+    /** Register the host wake-up used when foreign DOM work removes/replaces page shells. */
+    setPersistentSurfaceInvalidationHandler(handler?: () => void): void;
     /**
-     * Page-window runtime API. It accepts document-owned page extents and page
-     * packets for the currently visible range, so callers can mount a lower-page
-     * viewport without handing the painter a complete `ResolvedLayout.pages`
-     * array. Non-exact pages are explicit pending/degraded sheets, never blank
-     * workspace.
+     * Hydrated content page indices of the persistent surface, ascending.
+     * Page roots cover the whole scaffold; this is the bounded content set.
      */
-    paintPageWindow(input: DomPainterPageWindowInput, mount: HTMLElement): void;
+    getHydratedContentPageIndices(): number[];
     /**
-     * Painter plan §4.6 (dark observability): page-window paint work since the
+     * Painter plan §4.6 (dark observability): persistent-page paint work since the
      * last consume. Never invents values — fields the path cannot attribute yet
      * stay 0/null.
      */
@@ -462,10 +410,6 @@ export declare class DomPainter {
      * ever consumes the summary. Counters stay always-on and O(1).
      */
     private recordPageWork;
-    private configureSpacerElement;
-    private createPageWindowSpacer;
-    private createPendingPageWindowElement;
-    private ensurePageWindowPendingSkeletonStyles;
     private renderColumnSeparators;
     private getColumnSeparatorPositions;
     private renderDecorationsForPage;
@@ -592,8 +536,8 @@ export declare class DomPainter {
      * @param textAlign - Horizontal text alignment
      * @param textVerticalAlign - Vertical text alignment (top, center, bottom)
      * @param textInsets - Text insets in pixels (top, right, bottom, left)
-     * @param groupScaleX - Scale factor applied by parent group (for counter-scaling)
-     * @param groupScaleY - Scale factor applied by parent group (for counter-scaling)
+     * @param _groupScaleX - Reserved parent-group scale factor
+     * @param _groupScaleY - Reserved parent-group scale factor
      */
     private createFallbackTextElement;
     private tryCreatePresetSvg;

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

@@ -3,7 +3,7 @@ import { SdtBoundaryOptions } from './container.js';
 /**
  * The container-label keys a `computeSdtBoundaries` walk over `resolvedItems`
  * WOULD add to `sdtLabelsRendered`, without mutating it. This is the pure
- * "which labels does this page display" function the page-window reuse path
+ * "which labels does this page display" function the persistent-page reuse path
  * compares against recorded per-page label state: label placement is
  * cross-page prefix state that resolve stamps do not cover, so an untouched
  * reuse is only safe when the recorded labels equal this expectation.

package/dist/public/ui-react.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_rolldown_runtime = require("../chunks/rolldown-runtime-_dR15c8t.cjs");
-const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-CXCqHc2m.cjs");
+const require_rolldown_runtime = require("../chunks/rolldown-runtime-1Y-nnZJ3.cjs");
+const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-DXdWuTzm.cjs");
 let react = require("react");
 var SuperDocUIContext = (0, react.createContext)(null);
 function disposeOwnedUi(ref) {

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

@@ -1,4 +1,4 @@
-import { t as createSuperDocUI } from "../chunks/create-super-doc-ui-fxF2Q8Ib.es.js";
+import { t as createSuperDocUI } from "../chunks/create-super-doc-ui-D4kk9AjM.es.js";
 import { createContext, createElement, useCallback, useContext, useEffect, useRef, useState } from "react";
 var SuperDocUIContext = createContext(null);
 function disposeOwnedUi(ref) {

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-CXCqHc2m.cjs");
+const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-DXdWuTzm.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 { n as shallowEqual, r as BUILT_IN_COMMAND_IDS, t as createSuperDocUI } from "../chunks/create-super-doc-ui-fxF2Q8Ib.es.js";
+import { n as shallowEqual, r as BUILT_IN_COMMAND_IDS, t as createSuperDocUI } from "../chunks/create-super-doc-ui-D4kk9AjM.es.js";
 export { BUILT_IN_COMMAND_IDS, createSuperDocUI, shallowEqual };