superdoc 2.3.0 → 2.4.0-next.2

package/dist/chunks/{eventemitter3-B60Fsz-a.es.js → eventemitter3-Bt2s0X0a.es.js}

@@ -1,4 +1,4 @@
-import { o as __toESM, t as __commonJSMin } from "./rolldown-runtime-BJVcqBbz.es.js";
+import { i as __toESM, t as __commonJSMin } from "./rolldown-runtime-D7PMmH3s.es.js";
 var import_eventemitter3 = /* @__PURE__ */ __toESM((/* @__PURE__ */ __commonJSMin(((exports, module) => {
 	var has = Object.prototype.hasOwnProperty, prefix = "~";
 	function Events() {}

package/dist/chunks/{eventemitter3-DCfwFVNn.cjs → eventemitter3-DqY4aSMf.cjs}

@@ -1,4 +1,4 @@
-const require_rolldown_runtime = require("./rolldown-runtime-_dR15c8t.cjs");
+const require_rolldown_runtime = require("./rolldown-runtime-1Y-nnZJ3.cjs");
 var require_eventemitter3 = /* @__PURE__ */ require_rolldown_runtime.__commonJSMin(((exports, module) => {
 	var has = Object.prototype.hasOwnProperty, prefix = "~";
 	function Events() {}

package/dist/chunks/{jszip-DzmwAHr3.es.js → jszip-C8srOKAO.es.js}

@@ -1,4 +1,4 @@
-import { a as __require, n as __esmMin, t as __commonJSMin } from "./rolldown-runtime-BJVcqBbz.es.js";
+import { n as __esmMin, r as __require, t as __commonJSMin } from "./rolldown-runtime-D7PMmH3s.es.js";
 function getLens(b64) {
 	var len$1 = b64.length;
 	if (len$1 % 4 > 0) throw new Error("Invalid string. Length must be a multiple of 4");
@@ -4647,4 +4647,4 @@ while (n$2 === a$2[++i$3] && n$2 === a$2[++i$3] && n$2 === a$2[++i$3] && n$2 ===
 		}, {}, [10])(10);
 	});
 }));
-export { init_dist$1 as a, global as i, init_dist as n, process$1 as r, require_jszip_min as t };
+export { init_dist$1 as a, global as i, init_dist as n, Buffer as o, process$1 as r, init_dist$2 as s, require_jszip_min as t };

package/dist/chunks/{jszip-BdUBlUeG.cjs → jszip-Cs9JBLlJ.cjs}

@@ -1,4 +1,4 @@
-const require_rolldown_runtime = require("./rolldown-runtime-_dR15c8t.cjs");
+const require_rolldown_runtime = require("./rolldown-runtime-1Y-nnZJ3.cjs");
 function getLens(b64) {
 	var len$1 = b64.length;
 	if (len$1 % 4 > 0) throw new Error("Invalid string. Length must be a multiple of 4");
@@ -4647,6 +4647,12 @@ while (n$2 === a$2[++i$3] && n$2 === a$2[++i$3] && n$2 === a$2[++i$3] && n$2 ===
 		}, {}, [10])(10);
 	});
 }));
+Object.defineProperty(exports, "Buffer", {
+	enumerable: true,
+	get: function() {
+		return Buffer;
+	}
+});
 Object.defineProperty(exports, "global", {
 	enumerable: true,
 	get: function() {
@@ -4665,6 +4671,12 @@ Object.defineProperty(exports, "init_dist$1", {
 		return init_dist$1;
 	}
 });
+Object.defineProperty(exports, "init_dist$2", {
+	enumerable: true,
+	get: function() {
+		return init_dist$2;
+	}
+});
 Object.defineProperty(exports, "process$1", {
 	enumerable: true,
 	get: function() {

package/dist/chunks/{rolldown-runtime-_dR15c8t.cjs → rolldown-runtime-1Y-nnZJ3.cjs}

@@ -6,15 +6,6 @@ var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __esmMin = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 var __commonJSMin = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
-var __export = (all, symbols) => {
-	let target = {};
-	for (var name in all) __defProp(target, name, {
-		get: all[name],
-		enumerable: true
-	});
-	if (symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
-	return target;
-};
 var __copyProps = (to, from, except, desc) => {
 	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
 		key = keys[i];
@@ -25,13 +16,6 @@ var __copyProps = (to, from, except, desc) => {
 	}
 	return to;
 };
-var __reExport = (target, mod, secondTarget, symbols) => {
-	if (symbols) {
-		__defProp(target, Symbol.toStringTag, { value: "Module" });
-		secondTarget && __defProp(secondTarget, Symbol.toStringTag, { value: "Module" });
-	}
-	__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default");
-};
 var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
 	value: mod,
 	enumerable: true
@@ -48,18 +32,6 @@ Object.defineProperty(exports, "__esmMin", {
 		return __esmMin;
 	}
 });
-Object.defineProperty(exports, "__export", {
-	enumerable: true,
-	get: function() {
-		return __export;
-	}
-});
-Object.defineProperty(exports, "__reExport", {
-	enumerable: true,
-	get: function() {
-		return __reExport;
-	}
-});
 Object.defineProperty(exports, "__toESM", {
 	enumerable: true,
 	get: function() {

package/dist/chunks/{rolldown-runtime-BJVcqBbz.es.js → rolldown-runtime-D7PMmH3s.es.js}

@@ -6,15 +6,6 @@ var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __esmMin = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 var __commonJSMin = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
-var __export = (all, symbols) => {
-	let target = {};
-	for (var name in all) __defProp(target, name, {
-		get: all[name],
-		enumerable: true
-	});
-	if (symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
-	return target;
-};
 var __copyProps = (to, from, except, desc) => {
 	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
 		key = keys[i];
@@ -25,13 +16,6 @@ var __copyProps = (to, from, except, desc) => {
 	}
 	return to;
 };
-var __reExport = (target, mod, secondTarget, symbols) => {
-	if (symbols) {
-		__defProp(target, Symbol.toStringTag, { value: "Module" });
-		secondTarget && __defProp(secondTarget, Symbol.toStringTag, { value: "Module" });
-	}
-	__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default");
-};
 var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
 	value: mod,
 	enumerable: true
@@ -40,4 +24,4 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
 	if (typeof require !== "undefined") return require.apply(this, arguments);
 	throw Error("Calling `require` for \"" + x + "\" in an environment that doesn't expose the `require` function.");
 });
-export { __require as a, __reExport as i, __esmMin as n, __toESM as o, __export as r, __commonJSMin as t };
+export { __toESM as i, __esmMin as n, __require as r, __commonJSMin as t };

package/dist/collaboration-upgrade-engine.cjs

@@ -7,7 +7,7 @@ const 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.3.0",
+	superdocVersion: "2.4.0-next.2",
 	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

@@ -6,7 +6,7 @@ const COLLABORATION_UPGRADE_ENGINE_MINIMUM_NODE_MAJOR = 20;
 var PRIVATE_ENGINE_INFO = getCollaborationUpgradeEngineInfo$1();
 var ENGINE_INFO = Object.freeze({
 	...PRIVATE_ENGINE_INFO,
-	superdocVersion: "2.3.0",
+	superdocVersion: "2.4.0-next.2",
 	roomSchemaVersion: Object.freeze({ ...PRIVATE_ENGINE_INFO.roomSchemaVersion }),
 	supportedBundleVersions: SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS,
 	supportedV1ReaderContractVersions: SUPPORTED_V1_READER_CONTRACT_VERSIONS

package/dist/document-api/src/comments/comment-create-attribution.d.ts

@@ -0,0 +1,2 @@
+import { CommentCreateAttributionInput } from './comments.types.js';
+export declare function normalizeCommentCreateAttribution(input: CommentCreateAttributionInput): CommentCreateAttributionInput | null;

package/dist/document-api/src/comments/comments.d.ts

@@ -1,7 +1,8 @@
 import { Receipt, ReceiptFailureResult, ReceiptSuccess, StoryLocator } from '../types/index.js';
-import { CommentInfo, CommentTarget, CommentsListQuery, CommentsListResult, TextSearchCommentTarget, TrackedChangeCommentTarget, TrackedChangeCommentTargetSide } from './comments.types.js';
+import { CommentInfo, CommentCreateAttributionInput, CommentTarget, CommentsListQuery, CommentsListResult, TextSearchCommentTarget, TrackedChangeCommentTarget, TrackedChangeCommentTargetSide } from './comments.types.js';
 import { RevisionGuardOptions } from '../write/write.js';
 export type { TextSearchCommentTarget, TrackedChangeCommentTarget, TrackedChangeCommentTargetSide };
+export type { CommentCreateAttributionInput, CommentMetadata, CommentMetadataValue } from './comments.types.js';
 /**
  * Input for adding a comment to a text range.
  *
@@ -10,7 +11,7 @@ export type { TextSearchCommentTarget, TrackedChangeCommentTarget, TrackedChange
  * across contiguous blocks: use it directly from `editor.doc.selection.current().target`
  * without picking a single segment.
  */
-export interface AddCommentInput {
+export interface AddCommentInput extends CommentCreateAttributionInput {
     /**
      * The text range to attach the comment to.
      *
@@ -29,7 +30,7 @@ export interface EditCommentInput {
     commentId: string;
     text: string;
 }
-export interface ReplyToCommentInput {
+export interface ReplyToCommentInput extends CommentCreateAttributionInput {
     parentCommentId: string;
     text: string;
 }
@@ -74,9 +75,17 @@ export interface GetCommentInput {
  * When `parentCommentId` is provided, creates a reply on an existing thread.
  * Otherwise, creates a new root comment anchored to the given text range.
  */
-export interface CommentsCreateInput {
+export interface CommentsCreateInput extends CommentCreateAttributionInput {
     /** The comment body text. */
     text: string;
+    /**
+     * Compatibility alias for {@link CommentCreateAttributionInput.externalId},
+     * matching the caller-supplied `commentId` accepted by the v1 editor.
+     *
+     * V2 still mints a separate Word-compatible id for the document. Pass
+     * either `commentId` or `externalId`; when both are present they must agree.
+     */
+    commentId?: string;
     /**
      * The text range to attach the comment to (root comments only).
      *

package/dist/document-api/src/comments/comments.types.d.ts

@@ -2,6 +2,30 @@ import { CommentAddress, CommentStatus, SelectionTarget, StoryLocator, TextAddre
 import { DiscoveryOutput } from '../types/discovery.js';
 import { TrackChangeType } from '../types/track-changes.types.js';
 export type { CommentStatus } from '../types/index.js';
+export type CommentMetadataValue = string | number | boolean | null | readonly CommentMetadataValue[] | {
+    readonly [key: string]: CommentMetadataValue;
+};
+/** Caller-owned JSON metadata persisted with a comment. */
+export type CommentMetadata = Readonly<Record<string, CommentMetadataValue>>;
+/** Optional caller-owned identity and authorship for a newly-created comment. */
+export interface CommentCreateAttributionInput {
+    /**
+     * Durable document-scoped integration id, distinct from the Word-compatible
+     * `commentId` returned by the operation. Must be unique when provided and no
+     * longer than 1,024 Unicode characters.
+     */
+    externalId?: string;
+    /** Author display name. Defaults to the configured session author. */
+    author?: string;
+    /** Stable actor id, matching the v1 `addComment` option. */
+    authorId?: string;
+    /** Author email, matching the v1 `addComment` option. */
+    authorEmail?: string;
+    /** Author image URL, matching the v1 `addComment` option. */
+    authorImage?: string;
+    /** Caller-owned JSON metadata persisted through DOCX save/reopen. */
+    metadata?: CommentMetadata;
+}
 /**
  * Side of a tracked-change anchor that a comment is currently anchored on.
  * Derived on read; not stored in a persisted custom carrier.
@@ -78,6 +102,13 @@ export interface CommentTrackedChangeLink {
 export interface CommentInfo {
     address: CommentAddress;
     commentId: string;
+    /**
+     * Caller-owned integration id. This is distinct from the Word-compatible
+     * {@link commentId} and survives save/reopen as a durable correlation key.
+     */
+    externalId?: string;
+    /** Caller-owned JSON metadata persisted with the comment. */
+    metadata?: CommentMetadata;
     /**
      * Logical tracked-change id that the comment anchor
      * currently maps wholly to, when the surviving anchor sits inside
@@ -161,7 +192,9 @@ export interface CommentInfo {
      */
     createdTime?: number;
     creatorName?: string;
+    creatorId?: string;
     creatorEmail?: string;
+    creatorImage?: string;
 }
 export interface CommentsListQuery {
     includeResolved?: boolean;
@@ -176,6 +209,10 @@ export interface CommentsListQuery {
  */
 export interface CommentDomain {
     address: CommentAddress;
+    /** See {@link CommentInfo.externalId}. */
+    externalId?: string;
+    /** See {@link CommentInfo.metadata}. */
+    metadata?: CommentMetadata;
     /** See {@link CommentInfo.importedId}. */
     importedId?: string;
     /** See {@link CommentInfo.rawOoxmlId}. */
@@ -219,7 +256,9 @@ export interface CommentDomain {
     anchoredText?: string;
     createdTime?: number;
     creatorName?: string;
+    creatorId?: string;
     creatorEmail?: string;
+    creatorImage?: string;
 }
 /**
  * Standardized discovery output for `comments.list`.

package/dist/document-api/src/content-controls/content-controls.types.d.ts

@@ -148,6 +148,8 @@ export interface ContentControlInfo {
     target: ContentControlTarget;
     selectionTarget?: SelectionTarget | null;
     text?: string;
+    /** Authoritative structural emptiness when the adapter can determine it. */
+    isEmpty?: boolean;
 }
 export interface ContentControlMutationSuccess {
     success: true;

package/dist/document-api/src/contract/metadata-types.d.ts

@@ -12,6 +12,24 @@ export interface CommandStaticMetadata {
     idempotency: OperationIdempotency;
     supportsDryRun: boolean;
     supportsTrackedMode: boolean;
+    /**
+     * Tracked mode is permitted for *some* targets of this operation but cannot
+     * be promised statically, because whether it applies depends on the document
+     * state at the target — not on the operation itself.
+     *
+     * Set this only when `supportsTrackedMode` is `false`. It does not advertise
+     * tracked support: capability reporting still reports `tracked: false`,
+     * because the operation cannot guarantee a reviewable revision. What it does
+     * is stop transports from rejecting a tracked call on static metadata alone,
+     * so the engine adapter gets to resolve the target and make the real
+     * decision — succeeding where the context allows it and otherwise failing
+     * closed with `CAPABILITY_UNAVAILABLE`, exactly as an unsupported operation
+     * would.
+     *
+     * Without this, an adapter-level contextual allowance is unreachable from
+     * any transport that gates on the contract (see `tables.setCellText`).
+     */
+    supportsConditionalTrackedMode?: boolean;
     possibleFailureCodes: readonly ReceiptFailureCode[];
     throws: CommandThrowPolicy;
     deterministicTargetResolution: boolean;

package/dist/document-api/src/contract/operation-definitions.d.ts

@@ -901,7 +901,7 @@ export declare const OPERATION_DEFINITIONS: {
     };
     readonly 'comments.create': {
         readonly memberPath: "comments.create";
-        readonly description: "Create a new comment thread (or reply when parentCommentId is given). Accepts TextAddress / TextTarget anchors, or a TrackedChangeCommentTarget that names a logical tracked-change id. The tracked-change target accepts both the explicit kind form and the Labs-compatible trackedChangeId-only form; the adapter normalizes it to a Word-compatible content anchor on the requested revision side.";
+        readonly description: "Create a new comment thread (or reply when parentCommentId is given). Accepts TextAddress / TextTarget anchors, or a TrackedChangeCommentTarget that names a logical tracked-change id. The tracked-change target accepts both the explicit kind form and the Labs-compatible trackedChangeId-only form; the adapter normalizes it to a Word-compatible content anchor on the requested revision side. Callers may supply a durable externalId, or use the v1-compatible caller-supplied commentId alias, plus author fields and arbitrary JSON metadata for integration correlation. The caller-owned id remains distinct from the generated Word-compatible commentId.";
         readonly expectedResult: "Returns a Receipt with the new commentId in `id` and `inserted` on success; rejects whitespace-only bodies, unsupported anchor contexts, and cross-story targets. Tracked-change comment targets support insertion, deletion, replacement, and paired-move revisions; they fail with `TARGET_NOT_FOUND` for stale ids, `CAPABILITY_UNAVAILABLE` for formatting / structural revisions and unpaired move sides, and `INVALID_TARGET` for incompatible side requests or ambiguous replacement targets that omit a required `side`.";
         readonly requiresDocumentContext: true;
         readonly metadata: CommandStaticMetadata;

package/dist/document-api/src/index.d.ts

@@ -144,9 +144,9 @@ export { PARAGRAPH_ALIGNMENTS, TAB_STOP_ALIGNMENTS, TAB_STOP_LEADERS, BORDER_SID
 export type { BlockAddress, BlockRange, CanContinueReason, CanJoinReason, JoinDirection, ListInsertInput, ListItemAddress, ListItemInfo, ListKind, ListsAttachInput, ListsCanContinuePreviousInput, ListsCanContinuePreviousResult, ListsCanJoinInput, ListsCanJoinResult, ListsConvertToTextInput, ListsConvertToTextResult, ListsContinuePreviousInput, ListsCreateInput, ListsCreateResult, ListsDetachInput, ListsDetachResult, ListsDeleteInput, ListsDeleteResult, ListsFailureCode, ListsGetInput, ListsInsertResult, ListsJoinInput, ListsJoinResult, ListsListQuery, ListsListResult, ListsMutateItemResult, ListsSeparateInput, ListsSeparateResult, ListsMergeInput, ListsMergeResult, ListsSplitInput, ListsSplitResult, ListsSetLevelInput, ListsSetLevelRestartInput, ListsSetValueInput, ListTargetInput, MutationScope, LevelAlignment, TrailingCharacter, ListPresetId, ListPresetMarker, ListLevelTemplate, ListTemplate, ListsApplyTemplateInput, ListsApplyPresetInput, ListsCaptureTemplateInput, ListsCaptureTemplateResult, ListsCaptureTemplateSuccessResult, ListsSetLevelNumberingInput, ListsSetLevelBulletInput, ListsSetLevelPictureBulletInput, ListsSetLevelAlignmentInput, ListsSetLevelIndentsInput, ListsSetLevelTrailingCharacterInput, ListsSetLevelMarkerFontInput, ListsClearLevelOverridesInput, ListsSetTypeInput, ListStyle, ListLevelStyle, ListLevelLayout, ListsGetStyleInput, ListsGetStyleResult, ListsGetStyleSuccessResult, ListsApplyStyleInput, ListsRestartAtInput, ListsSetLevelNumberStyleInput, ListsSetLevelTextInput, ListsSetLevelStartInput, ListsSetLevelLayoutInput, ListsGetStateInput, ListsGetStateResult, ListsApplyInput, ListsContinueV2Input, ListsRestartV2Input, ListsRemoveV2Input, } from './lists/lists.types.js';
 export { LIST_KINDS, LIST_INSERT_POSITIONS, JOIN_DIRECTIONS, MUTATION_SCOPES, LEVEL_ALIGNMENTS, TRAILING_CHARACTERS, LIST_PRESET_IDS, LIST_PRESET_MARKERS, } from './lists/lists.types.js';
 export type { CreateSectionBreakInput, CreateSectionBreakResult, DocumentMutationResult, SectionAddress, SectionBorderSpec, SectionBreakCreateLocation, SectionBreakRepresentation, SectionBreakType, SectionColumns, SectionDirection, SectionDomain, SectionHeaderFooterKind, SectionHeaderFooterMargins, SectionHeaderFooterRefs, SectionHeaderFooterVariant, SectionInfo, SectionLineNumbering, SectionLineNumberRestart, SectionMutationResult, SectionOrientation, SectionPageBorders, SectionPageMargins, SectionPageNumbering, SectionPageNumberingChapterSeparator, SectionPageNumberingFormat, SectionPageSetup, SectionRangeDomain, SectionTargetInput, SectionVerticalAlign, SectionsClearHeaderFooterRefInput, SectionsClearPageBordersInput, SectionsGetInput, SectionsListQuery, SectionsListResult, SectionsSetBreakTypeInput, SectionsSetColumnsInput, SectionsSetHeaderFooterMarginsInput, SectionsSetHeaderFooterRefInput, SectionsSetLineNumberingInput, SectionsSetLinkToPreviousInput, SectionsSetOddEvenHeadersFootersInput, SectionsSetPageBordersInput, SectionsSetPageMarginsInput, SectionsSetPageNumberingInput, SectionsSetPageSetupInput, SectionsSetSectionDirectionInput, SectionsSetTitlePageInput, SectionsSetVerticalAlignInput, } from './sections/sections.types.js';
-export type { CommentsCreateReceipt, CommentsCreateInput, CommentsPatchInput, CommentsDeleteInput, CommentsAdapter, CommentsApi, GetCommentInput, TrackedChangeCommentTarget, TrackedChangeCommentTargetSide, TextSearchCommentTarget, AddCommentInput, EditCommentInput, ReplyToCommentInput, MoveCommentInput, ResolveCommentInput, ReopenCommentInput, RemoveCommentInput, SetCommentInternalInput, GoToCommentInput, SetCommentActiveInput, } from './comments/comments.js';
+export type { CommentsCreateReceipt, CommentsCreateInput, CommentCreateAttributionInput, CommentsPatchInput, CommentsDeleteInput, CommentsAdapter, CommentsApi, GetCommentInput, TrackedChangeCommentTarget, TrackedChangeCommentTargetSide, TextSearchCommentTarget, AddCommentInput, EditCommentInput, ReplyToCommentInput, MoveCommentInput, ResolveCommentInput, ReopenCommentInput, RemoveCommentInput, SetCommentInternalInput, GoToCommentInput, SetCommentActiveInput, } from './comments/comments.js';
 export { executeCommentsCreate, executeCommentsPatch, executeCommentsDelete, executeGetComment, executeListComments, } from './comments/comments.js';
-export type { CommentInfo, CommentDomain, CommentsListQuery, CommentsListResult, CommentTrackedChangeSide, CommentTrackedChangeLink, CommentTarget, } from './comments/comments.types.js';
+export type { CommentInfo, CommentDomain, CommentMetadata, CommentMetadataValue, CommentsListQuery, CommentsListResult, CommentTrackedChangeSide, CommentTrackedChangeLink, CommentTarget, } from './comments/comments.types.js';
 export type { BlocksApi } from './blocks/blocks.js';
 export { executeBlocksList, executeBlocksDelete, executeBlocksDeleteRange, executeBlocksSplit, executeBlocksMerge, executeBlocksMove, } from './blocks/blocks.js';
 export { executeListsIndent, executeListsOutdent, executeListsGetState, executeListsApply, executeListsContinueV2, executeListsRestartV2, executeListsRemoveV2, } from './lists/lists.js';

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

@@ -1,7 +1,8 @@
-import { DomPainterOptions, PaintSnapshot } from './index.js';
+import { DomPainterHandle, DomPainterOptions, PaintSnapshot } from './index.js';
 import { PageDecorationProvider } from './renderer.js';
 import { FlowBlock, Layout, Measure, ResolvedLayout } from '../../../contracts/src/index.js';
 export declare const emptyResolved: ResolvedLayout;
+export declare function paintResolvedLayoutPersistent(painter: DomPainterHandle, resolvedLayout: ResolvedLayout, mount: HTMLElement): void;
 /**
  * Test-only bridge: accepts old-style `{ blocks, measures, ...options }` and
  * returns a painter whose `paint()` automatically builds a `DomPainterInput`.
@@ -14,7 +15,7 @@ export declare function createTestPainter(opts: {
     setData(blocks: FlowBlock[], measures: Measure[], hb?: FlowBlock[], hm?: Measure[], fb?: FlowBlock[], fm?: Measure[]): void;
     setResolvedLayout(rl: ResolvedLayout | null): void;
     setProviders(header?: PageDecorationProvider, footer?: PageDecorationProvider): void;
-    getMountedPageIndices(): number[];
+    getPersistentPageIndices(): number[];
     getPaintSnapshot(): PaintSnapshot | null;
     setShowFormattingMarks(showFormattingMarks: boolean): void;
     dispose(): void;

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

@@ -1,7 +1,8 @@
 import { PaintWorkSummary } from './page-content.js';
 import { PageStyles } from './styles.js';
 import { PositionValidationOptions, PositionValidationSummary } from './pm-position-validation.js';
-import { DomPainterInput, DomPainterPageWindowInput, PageDecorationProvider, PaintSnapshot, PositionMapping, FlowMode } from './renderer.js';
+import { DomPainterInput, PageDecorationProvider, PaintSnapshot, PositionMapping, FlowMode } from './renderer.js';
+import { DomPainterPersistentPageInput } from './persistent-page-surface.js';
 export { DOM_CLASS_NAMES } from './constants.js';
 export type { DomClassName } from './constants.js';
 export { ensureDocumentSurfaceStyles } from './styles.js';
@@ -11,7 +12,7 @@ export { generateRulerDefinition, generateRulerDefinitionFromPx, createRulerElem
 export type { RulerDefinition, RulerConfig, RulerConfigPx, RulerTick, CreateRulerElementOptions, } from './ruler/index.js';
 export type { PaintSnapshot, PaintSnapshotAnnotationEntity, PaintSnapshotStructuredContentBlockEntity, PaintSnapshotStructuredContentInlineEntity, PaintSnapshotImageEntity, PaintSnapshotEntities, } from './renderer.js';
 export type { DomPainterInput, PositionMapping } from './renderer.js';
-export type { DomPainterPageWindowExactness, DomPainterPageWindowExtent, DomPainterPageWindowInput, DomPainterPageWindowPacket, } from './renderer.js';
+export type { DomPainterPersistentPacketSource, DomPainterPersistentPageInput, DomPainterPersistentScaffold, DomPainterPersistentScaffoldPage, } from './persistent-page-surface.js';
 export type { PaintWorkSummary } from './page-content.js';
 export type { RenderedLineInfo } from './runs/index.js';
 export { sanitizeUrl, linkMetrics, applyRunDataAttributes } from './runs/index.js';
@@ -66,18 +67,29 @@ export type DomPainterOptions = {
      * branch with no allocation. The performance harness enables it (with an
      * explicit `off | summary | verbose` console policy — never `NODE_ENV`) and
      * drains it via `consumePositionValidationSummary()`. Each painter instance
-     * owns its collector, so the product surface window and the dense-reference
-     * oracle never mix counts.
+     * owns its collector, so the live persistent surface and the fresh-state
+     * persistent-page oracle never mix counts.
      */
     positionValidation?: PositionValidationOptions;
 };
 export type DomPainterHandle = {
-    /** Semantic flow only (painter plan P7); paginated documents use `paintPageWindow`. */
+    /** Semantic flow only (painter plan P7); paginated documents use the persistent reconcile. */
     paint(input: DomPainterInput, mount: HTMLElement, mapping?: PositionMapping): void;
-    /** Paginated flow only (painter plan P7); a dense paint is a full-range window. */
-    paintPageWindow(input: DomPainterPageWindowInput, mount: HTMLElement): void;
     /**
-     * Painter plan §4.6 (dark observability): page-window paint work since the
+     * The persistent paginated reconcile (default persistent page geometry
+     * plan): a generation-scoped scaffold publishes every page root atomically
+     * and keeps it mounted for the whole layout generation; only content
+     * descendants are virtualized. Paginated flow only.
+     */
+    paintPersistentPages(input: DomPainterPersistentPageInput, mount: HTMLElement): void;
+    /** Live integrity probe used to prevent zero-work skips over a corrupted shell plane. */
+    isPersistentPageSurfaceIntact(): boolean;
+    /** Wake-up callback for foreign page-root DOM corruption. */
+    setPersistentSurfaceInvalidationHandler(handler?: () => void): void;
+    /** Ascending hydrated content page indices of the persistent surface. */
+    getHydratedContentPageIndices(): number[];
+    /**
+     * Painter plan §4.6 (dark observability): persistent-page paint work since the
      * last consume. Fields the path cannot attribute yet are 0/null, never
      * invented (`domNodesCreated` stays null until node counting lands). Since
      * P5, `pagesPositionRemapped` counts uniform in-place pm shifts on reused
@@ -92,14 +104,10 @@ export type DomPainterHandle = {
      */
     consumePositionValidationSummary(): PositionValidationSummary;
     setProviders(header?: PageDecorationProvider, footer?: PageDecorationProvider): void;
-    getMountedPageIndices(): number[];
+    getPersistentPageIndices(): number[];
     setShowFormattingMarks(showFormattingMarks: boolean): void;
     dispose(): void;
 };
-export type DenseReferencePainterHandle = DomPainterHandle & {
-    /** Proof-only sequential batch traversal; product surfaces never receive this handle. */
-    paintDensePageBatch(input: DomPainterInput, mount: HTMLElement, startPageIndex: number, endPageIndexExclusive: number): void;
-};
 /**
  * Thin pass-through factory: instantiates DomPainter with the supplied options
  * and returns a stable handle that exposes only the rendering-stage API.
@@ -108,11 +116,9 @@ export type DenseReferencePainterHandle = DomPainterHandle & {
  * Header/footer decoration providers must supply both `fragments` and `items`
  * on their `PageDecorationPayload`.
  *
- * Mode ownership (painter plan P7): this handle's `paint()` REJECTS paginated
- * flow — paginated documents have exactly one paint entry, `paintPageWindow`
- * (a dense paint is a full-range window). Equivalence oracles and kernel spec
- * tests that need the paginated dense REFERENCE go through
- * {@link createDenseReferencePainter} instead.
+ * Mode ownership: `paint()` serves semantic flow and rejects paginated flow;
+ * paginated documents and fresh-state oracles both use the one persistent
+ * page reconcile.
  *
  * v1 EOL (product decision 2026-07-06, P7 review): the v1 PresentationEditor
  * consumed the deleted surface (paginated `paint()`, `virtualization`/`ruler`
@@ -122,4 +128,3 @@ export type DenseReferencePainterHandle = DomPainterHandle & {
  * `mode-ownership.test.ts` battery pins the surface deleted.
  */
 export declare const createDomPainter: (options: DomPainterOptions) => DomPainterHandle;
-export declare const createDenseReferencePainter: (options: DomPainterOptions) => DenseReferencePainterHandle;