superdoc 2.4.0-next.3 → 2.4.0-next.30

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

@@ -1,11 +1,19 @@
+//#region \0rolldown/runtime.js
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 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 __esmMin = (fn, res, err) => () => {
+	if (err) throw err[0];
+	try {
+		return fn && (res = fn(fn = 0)), res;
+	} catch (e) {
+		throw err = [e], e;
+	}
+};
+var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
 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];
@@ -16,12 +24,13 @@ var __copyProps = (to, from, except, desc) => {
 	}
 	return to;
 };
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule || !__hasOwnProp.call(mod, "default") ? __defProp(target, "default", {
 	value: mod,
 	enumerable: true
 }) : target, mod));
 var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, { get: (a, b) => (typeof require !== "undefined" ? require : a)[b] }) : x)(function(x) {
 	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.");
+	throw Error("Calling `require` for \"" + x + "\" in an environment that doesn't expose the `require` function. See https://rolldown.rs/in-depth/bundling-cjs#require-external-modules for more details.");
 });
+//#endregion
 export { __toESM as i, __esmMin as n, __require as r, __commonJSMin as t };

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

@@ -1,11 +1,19 @@
+//#region \0rolldown/runtime.js
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 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 __esmMin = (fn, res, err) => () => {
+	if (err) throw err[0];
+	try {
+		return fn && (res = fn(fn = 0)), res;
+	} catch (e) {
+		throw err = [e], e;
+	}
+};
+var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
 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];
@@ -16,10 +24,11 @@ var __copyProps = (to, from, except, desc) => {
 	}
 	return to;
 };
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule || !__hasOwnProp.call(mod, "default") ? __defProp(target, "default", {
 	value: mod,
 	enumerable: true
 }) : target, mod));
+//#endregion
 Object.defineProperty(exports, "__commonJSMin", {
 	enumerable: true,
 	get: function() {

package/dist/chunks/{uuid-CFp0WGVU.cjs → uuid-BhG0ngwk.cjs}

@@ -1,10 +1,13 @@
+//#region ../../node_modules/.pnpm/uuid@11.1.1/node_modules/uuid/dist/esm-browser/stringify.js
 var byteToHex = [];
 for (let i = 0; i < 256; ++i) byteToHex.push((i + 256).toString(16).slice(1));
 function unsafeStringify(arr, offset = 0) {
 	return (byteToHex[arr[offset + 0]] + byteToHex[arr[offset + 1]] + byteToHex[arr[offset + 2]] + byteToHex[arr[offset + 3]] + "-" + byteToHex[arr[offset + 4]] + byteToHex[arr[offset + 5]] + "-" + byteToHex[arr[offset + 6]] + byteToHex[arr[offset + 7]] + "-" + byteToHex[arr[offset + 8]] + byteToHex[arr[offset + 9]] + "-" + byteToHex[arr[offset + 10]] + byteToHex[arr[offset + 11]] + byteToHex[arr[offset + 12]] + byteToHex[arr[offset + 13]] + byteToHex[arr[offset + 14]] + byteToHex[arr[offset + 15]]).toLowerCase();
 }
+//#endregion
+//#region ../../node_modules/.pnpm/uuid@11.1.1/node_modules/uuid/dist/esm-browser/rng.js
 var getRandomValues;
-var rnds8 = new Uint8Array(16);
+var rnds8 = /* @__PURE__ */ new Uint8Array(16);
 function rng() {
 	if (!getRandomValues) {
 		if (typeof crypto === "undefined" || !crypto.getRandomValues) throw new Error("crypto.getRandomValues() not supported. See https://github.com/uuidjs/uuid#getrandomvalues-not-supported");
@@ -12,8 +15,9 @@ function rng() {
 	}
 	return getRandomValues(rnds8);
 }
-var randomUUID = typeof crypto !== "undefined" && crypto.randomUUID && crypto.randomUUID.bind(crypto);
-var native_default = { randomUUID };
+var native_default = { randomUUID: typeof crypto !== "undefined" && crypto.randomUUID && crypto.randomUUID.bind(crypto) };
+//#endregion
+//#region ../../node_modules/.pnpm/uuid@11.1.1/node_modules/uuid/dist/esm-browser/v4.js
 function v4(options, buf, offset) {
 	if (native_default.randomUUID && !buf && !options) return native_default.randomUUID();
 	options = options || {};
@@ -29,10 +33,10 @@ function v4(options, buf, offset) {
 	}
 	return unsafeStringify(rnds);
 }
-var v4_default = v4;
-Object.defineProperty(exports, "v4_default", {
+//#endregion
+Object.defineProperty(exports, "v4", {
 	enumerable: true,
 	get: function() {
-		return v4_default;
+		return v4;
 	}
 });

package/dist/chunks/{uuid-B2Sqk-3p.es.js → uuid-H0Xcmmhy.es.js}

@@ -1,10 +1,13 @@
+//#region ../../node_modules/.pnpm/uuid@11.1.1/node_modules/uuid/dist/esm-browser/stringify.js
 var byteToHex = [];
 for (let i = 0; i < 256; ++i) byteToHex.push((i + 256).toString(16).slice(1));
 function unsafeStringify(arr, offset = 0) {
 	return (byteToHex[arr[offset + 0]] + byteToHex[arr[offset + 1]] + byteToHex[arr[offset + 2]] + byteToHex[arr[offset + 3]] + "-" + byteToHex[arr[offset + 4]] + byteToHex[arr[offset + 5]] + "-" + byteToHex[arr[offset + 6]] + byteToHex[arr[offset + 7]] + "-" + byteToHex[arr[offset + 8]] + byteToHex[arr[offset + 9]] + "-" + byteToHex[arr[offset + 10]] + byteToHex[arr[offset + 11]] + byteToHex[arr[offset + 12]] + byteToHex[arr[offset + 13]] + byteToHex[arr[offset + 14]] + byteToHex[arr[offset + 15]]).toLowerCase();
 }
+//#endregion
+//#region ../../node_modules/.pnpm/uuid@11.1.1/node_modules/uuid/dist/esm-browser/rng.js
 var getRandomValues;
-var rnds8 = new Uint8Array(16);
+var rnds8 = /* @__PURE__ */ new Uint8Array(16);
 function rng() {
 	if (!getRandomValues) {
 		if (typeof crypto === "undefined" || !crypto.getRandomValues) throw new Error("crypto.getRandomValues() not supported. See https://github.com/uuidjs/uuid#getrandomvalues-not-supported");
@@ -13,6 +16,8 @@ function rng() {
 	return getRandomValues(rnds8);
 }
 var native_default = { randomUUID: typeof crypto !== "undefined" && crypto.randomUUID && crypto.randomUUID.bind(crypto) };
+//#endregion
+//#region ../../node_modules/.pnpm/uuid@11.1.1/node_modules/uuid/dist/esm-browser/v4.js
 function v4(options, buf, offset) {
 	if (native_default.randomUUID && !buf && !options) return native_default.randomUUID();
 	options = options || {};
@@ -28,5 +33,5 @@ function v4(options, buf, offset) {
 	}
 	return unsafeStringify(rnds);
 }
-var v4_default = v4;
-export { v4_default as t };
+//#endregion
+export { v4 as t };

package/dist/collaboration-upgrade-engine.cjs

@@ -1,33 +1,58 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-let __superdoc_docx_engine_collaboration_upgrade_engine = require("@superdoc/docx-engine/collaboration-upgrade-engine");
-const COLLABORATION_UPGRADE_ENGINE_PROTOCOL_VERSION = 1;
-const SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS = Object.freeze([1]);
-const SUPPORTED_V1_READER_CONTRACT_VERSIONS = Object.freeze([1]);
-const COLLABORATION_UPGRADE_ENGINE_MINIMUM_NODE_MAJOR = 20;
-var PRIVATE_ENGINE_INFO = (0, __superdoc_docx_engine_collaboration_upgrade_engine.getCollaborationUpgradeEngineInfo)();
+let _superdoc_docx_engine_collaboration_upgrade_engine = require("@superdoc/docx-engine/collaboration-upgrade-engine");
+//#region src/public/collaboration-upgrade-engine.ts
+/**
+* SuperDoc public facade: `superdoc/collaboration-upgrade-engine`.
+*
+* This is a Node-only bridge used by the public v2 collaboration upgrade package.
+* It deliberately exposes data-only inputs and outputs: no live Y.Doc, editor,
+* provider, browser, UI, or private workspace type crosses this boundary.
+*/
+/** Compatibility protocol between the upgrade package and installed SuperDoc. */
+var COLLABORATION_UPGRADE_ENGINE_PROTOCOL_VERSION = 1;
+/** Recovery-bundle versions accepted by this engine. */
+var SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS = Object.freeze([1]);
+/** Frozen final-v1 reader contracts accepted by this engine. */
+var SUPPORTED_V1_READER_CONTRACT_VERSIONS = Object.freeze([1]);
+/** Minimum supported Node.js major version. */
+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.4.0-next.3",
+	superdocVersion: "2.4.0-next.30",
 	roomSchemaVersion: Object.freeze({ ...PRIVATE_ENGINE_INFO.roomSchemaVersion }),
 	supportedBundleVersions: SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS,
 	supportedV1ReaderContractVersions: SUPPORTED_V1_READER_CONTRACT_VERSIONS
 });
+/** Return immutable metadata used to reject incompatible engines preflight. */
 function getCollaborationUpgradeEngineInfo() {
 	return ENGINE_INFO;
 }
+/**
+* Build and offline-validate one self-contained v2 collaboration update.
+*
+* This function performs no provider I/O and never mutates the v1 source room.
+*/
 async function buildV2CollaborationUpgradeArtifactFromBundle(input) {
 	assertSupportedNodeRuntime();
-	return (0, __superdoc_docx_engine_collaboration_upgrade_engine.buildV2CollaborationUpgradeArtifactFromBundle)(input);
+	return (0, _superdoc_docx_engine_collaboration_upgrade_engine.buildV2CollaborationUpgradeArtifactFromBundle)(input);
 }
+/**
+* Validate target bytes after a provider reads them through a fresh client.
+*
+* Provenance and carrier bytes are derived from the authenticated recovery
+* bundle rather than accepted as independent caller assertions.
+*/
 async function validateV2CollaborationUpgradeTarget(input) {
 	assertSupportedNodeRuntime();
-	return (0, __superdoc_docx_engine_collaboration_upgrade_engine.validateV2CollaborationUpgradeTarget)(input);
+	return (0, _superdoc_docx_engine_collaboration_upgrade_engine.validateV2CollaborationUpgradeTarget)(input);
 }
 function assertSupportedNodeRuntime() {
 	const nodeVersion = globalThis.process?.versions?.node;
 	const nodeMajor = nodeVersion ? Number.parseInt(nodeVersion.split(".")[0] ?? "", 10) : NaN;
 	if (!Number.isInteger(nodeMajor) || nodeMajor < 20) throw new Error(`superdoc/collaboration-upgrade-engine requires Node.js 20 or newer`);
 }
+//#endregion
 exports.COLLABORATION_UPGRADE_ENGINE_MINIMUM_NODE_MAJOR = COLLABORATION_UPGRADE_ENGINE_MINIMUM_NODE_MAJOR;
 exports.COLLABORATION_UPGRADE_ENGINE_PROTOCOL_VERSION = COLLABORATION_UPGRADE_ENGINE_PROTOCOL_VERSION;
 exports.SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS = SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS;

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

@@ -1,23 +1,47 @@
 import { buildV2CollaborationUpgradeArtifactFromBundle as buildV2CollaborationUpgradeArtifactFromBundle$1, getCollaborationUpgradeEngineInfo as getCollaborationUpgradeEngineInfo$1, validateV2CollaborationUpgradeTarget as validateV2CollaborationUpgradeTarget$1 } from "@superdoc/docx-engine/collaboration-upgrade-engine";
-const COLLABORATION_UPGRADE_ENGINE_PROTOCOL_VERSION = 1;
-const SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS = Object.freeze([1]);
-const SUPPORTED_V1_READER_CONTRACT_VERSIONS = Object.freeze([1]);
-const COLLABORATION_UPGRADE_ENGINE_MINIMUM_NODE_MAJOR = 20;
+//#region src/public/collaboration-upgrade-engine.ts
+/**
+* SuperDoc public facade: `superdoc/collaboration-upgrade-engine`.
+*
+* This is a Node-only bridge used by the public v2 collaboration upgrade package.
+* It deliberately exposes data-only inputs and outputs: no live Y.Doc, editor,
+* provider, browser, UI, or private workspace type crosses this boundary.
+*/
+/** Compatibility protocol between the upgrade package and installed SuperDoc. */
+var COLLABORATION_UPGRADE_ENGINE_PROTOCOL_VERSION = 1;
+/** Recovery-bundle versions accepted by this engine. */
+var SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS = Object.freeze([1]);
+/** Frozen final-v1 reader contracts accepted by this engine. */
+var SUPPORTED_V1_READER_CONTRACT_VERSIONS = Object.freeze([1]);
+/** Minimum supported Node.js major version. */
+var COLLABORATION_UPGRADE_ENGINE_MINIMUM_NODE_MAJOR = 20;
 var PRIVATE_ENGINE_INFO = getCollaborationUpgradeEngineInfo$1();
 var ENGINE_INFO = Object.freeze({
 	...PRIVATE_ENGINE_INFO,
-	superdocVersion: "2.4.0-next.3",
+	superdocVersion: "2.4.0-next.30",
 	roomSchemaVersion: Object.freeze({ ...PRIVATE_ENGINE_INFO.roomSchemaVersion }),
 	supportedBundleVersions: SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS,
 	supportedV1ReaderContractVersions: SUPPORTED_V1_READER_CONTRACT_VERSIONS
 });
+/** Return immutable metadata used to reject incompatible engines preflight. */
 function getCollaborationUpgradeEngineInfo() {
 	return ENGINE_INFO;
 }
+/**
+* Build and offline-validate one self-contained v2 collaboration update.
+*
+* This function performs no provider I/O and never mutates the v1 source room.
+*/
 async function buildV2CollaborationUpgradeArtifactFromBundle(input) {
 	assertSupportedNodeRuntime();
 	return buildV2CollaborationUpgradeArtifactFromBundle$1(input);
 }
+/**
+* Validate target bytes after a provider reads them through a fresh client.
+*
+* Provenance and carrier bytes are derived from the authenticated recovery
+* bundle rather than accepted as independent caller assertions.
+*/
 async function validateV2CollaborationUpgradeTarget(input) {
 	assertSupportedNodeRuntime();
 	return validateV2CollaborationUpgradeTarget$1(input);
@@ -27,4 +51,5 @@ function assertSupportedNodeRuntime() {
 	const nodeMajor = nodeVersion ? Number.parseInt(nodeVersion.split(".")[0] ?? "", 10) : NaN;
 	if (!Number.isInteger(nodeMajor) || nodeMajor < 20) throw new Error(`superdoc/collaboration-upgrade-engine requires Node.js 20 or newer`);
 }
+//#endregion
 export { COLLABORATION_UPGRADE_ENGINE_MINIMUM_NODE_MAJOR, COLLABORATION_UPGRADE_ENGINE_PROTOCOL_VERSION, SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS, SUPPORTED_V1_READER_CONTRACT_VERSIONS, buildV2CollaborationUpgradeArtifactFromBundle, getCollaborationUpgradeEngineInfo, validateV2CollaborationUpgradeTarget };

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

@@ -1,5 +1,6 @@
 import { InlineAnchor } from '../types/base.js';
 import { TextTarget } from '../types/address.js';
+import { StoryLocator } from '../types/story.types.js';
 import { AdapterMutationFailure } from '../types/adapter-result.js';
 import { DiscoveryOutput } from '../types/discovery.js';
 import { TocCreateLocation } from '../toc/toc.types.js';
@@ -7,6 +8,14 @@ export interface CitationAddress {
     kind: 'inline';
     nodeType: 'citation';
     anchor: InlineAnchor;
+    /** Story containing this citation. Omit for body (backward compatible). */
+    story?: StoryLocator;
+    /** Session-stable story identity used by the v2 runtime with `fieldId`. */
+    storyId?: string;
+    /** Session-stable identity of the citation's backing OOXML field. */
+    fieldId?: string;
+    /** Field occurrence fallback for collocated citations with identical anchors. */
+    occurrenceIndex?: number;
 }
 export interface CitationSourceAddress {
     kind: 'entity';

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

@@ -200,6 +200,13 @@ export interface CommentsListQuery {
     includeResolved?: boolean;
     limit?: number;
     offset?: number;
+    /**
+     * Optional bounded review-window filter. Each id may be canonical or an
+     * imported/source alias. Only matching visible threads are projected.
+     */
+    visibleCommentIds?: readonly string[];
+    /** Include every reply belonging to a matched visible thread. */
+    includeThreadReplies?: boolean;
 }
 /**
  * Domain fields for a comment discovery item (C2).

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

@@ -42,22 +42,26 @@ export type ReviewWarning = {
  * operation. Callers maintain their own held-ref state by applying these
  * deltas:
  *
- * - Any caller-held text address whose `range.start` is `>= atChar` in the
- *   same `story` gets `range.start += delta` (and similarly `range.end`).
- * - Any caller-held text address whose range straddles `atChar` is
- *   *invalidated* — the kernel already lists those in `invalidatedRefs`.
+ * `atChar` is story-absolute. When `blockId` and `atCharInBlock` are both
+ * present, they identify the same shift in block-local visible coordinates.
+ * Consumers that store block-local ranges must fail closed when that pair is
+ * absent rather than interpreting `atChar` as a block offset.
  *
  * Negative `delta` describes a deletion. Positive `delta` describes an
  * insertion (e.g. when a `<w:del>` is rejected and its content is restored
  * to the visible flow).
  *
- * One entry per story. Cross-story shifts are reported as separate entries.
+ * One entry is emitted per story. Cross-story shifts are reported separately.
  */
 export interface TextRangeShift {
     /** The story whose text was shifted. */
     story: StoryLocator;
     /** Character offset in the story's flattened text where the shift begins. */
     atChar: number;
+    /** Block containing the shift, when the producer can prove one. */
+    blockId?: string;
+    /** Visible character offset within `blockId`, paired with `blockId`. */
+    atCharInBlock?: number;
     /** Net change in characters. Negative for deletions, positive for insertions. */
     delta: number;
 }

package/dist/document-api/src/types/track-changes.types.d.ts

@@ -2,9 +2,7 @@ import { TextTarget, TrackedChangeAddress } from './address.js';
 import { DiscoveryOutput } from './discovery.js';
 import { StoryLocator } from './story.types.js';
 /**
- * Canonical v2 tracked-change broad-type vocabulary defined by
- * `../labs/tests/requirements/specs/tracked-changes-comments/tracked-changes-spec.md`
- * §3 / §5.
+ * Canonical v2 tracked-change broad-type vocabulary.
  *
  * Public adapters MUST emit one of these values. Existing v1 emitters and
  * tests still produce the legacy `insert` / `delete` / `format` strings; both

package/dist/layout-engine/contracts/src/incremental-dependency.d.ts

@@ -5,6 +5,26 @@
  * every retained dependency that required the checkpoint; consumers reject
  * empty, duplicate, or unknown lists instead of trusting a generic boolean.
  */
-export type PageCheckpointDependencyClass = 'multiple-sections' | 'furniture-page-tokens' | 'non-balanceable-multi-column-sections' | 'body-anchored-objects' | 'footnotes' | 'page-references' | 'keep-constraints' | 'tables' | 'furniture-anchored-objects';
-export declare const PAGE_CHECKPOINT_DEPENDENCY_CLASSES: readonly ["multiple-sections", "furniture-page-tokens", "non-balanceable-multi-column-sections", "body-anchored-objects", "footnotes", "page-references", "keep-constraints", "tables", "furniture-anchored-objects"];
+export type PageCheckpointDependencyClass = 'multiple-sections' | 'furniture-page-tokens' | 'non-balanceable-multi-column-sections' | 'body-anchored-objects' | 'non-flowing-page-relative-body-anchors' | 'footnotes' | 'page-references' | 'keep-constraints' | 'tables' | 'furniture-anchored-objects';
+export declare const PAGE_CHECKPOINT_DEPENDENCY_CLASSES: readonly ["multiple-sections", "furniture-page-tokens", "non-balanceable-multi-column-sections", "body-anchored-objects", "non-flowing-page-relative-body-anchors", "footnotes", "page-references", "keep-constraints", "tables", "furniture-anchored-objects"];
+/**
+ * Exact retained-generation proof for page/margin-relative body anchors that
+ * cannot influence paragraph flow (`wrap=None`). The host builds this once
+ * from a canonical layout generation; warm consumers validate the epoch,
+ * inventory, identities, and page ownership before admitting bounded layout.
+ */
+export type NonFlowingPageRelativeAnchorDependencyProof = {
+    version: 1;
+    sourceLayoutEpoch: number;
+    inventoryFingerprint: string;
+    entries: readonly {
+        blockId: string;
+        carrierParagraphId: string;
+        sourcePageIndex: number;
+        sectionIndex: number;
+        geometryFingerprint: string;
+        measureFingerprint: string;
+        pageGeometryFingerprint: string;
+    }[];
+};
 export declare function areValidPageCheckpointDependencyClasses(value: unknown): value is readonly PageCheckpointDependencyClass[];

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

@@ -120,7 +120,7 @@ export type DocPartMetadata = {
  * - Doc parts: special objects like tables of contents
  */
 export type SdtMetadata = FieldAnnotationMetadata | StructuredContentMetadata | DocumentSectionMetadata | DocPartMetadata;
-export declare const CONTRACTS_VERSION = "1.1.0";
+export declare const CONTRACTS_VERSION = "1.2.0";
 /** Unique identifier for a block in the document. Format: `${pos}-${type}`. */
 export type BlockId = string;
 /**
@@ -655,12 +655,58 @@ export type MathRun = {
     sdt?: SdtMetadata;
 };
 export type Run = TextRun | TabRun | ImageRun | LineBreakRun | BreakRun | FieldAnnotationRun | MathRun;
+/** Layout-affecting inline-box values, resolved to logical CSS pixel sides. */
+export type ResolvedInlineBoxLayout = {
+    paddingInlineStart: number;
+    paddingInlineEnd: number;
+    paddingBlockStart: number;
+    paddingBlockEnd: number;
+    gapBefore: number;
+    gapAfter: number;
+    borderWidth: number;
+};
+/** Sanitized, paint-only inline-box appearance. */
+export type ResolvedInlineBoxAppearance = {
+    backgroundColor?: string;
+    borderColor?: string;
+    borderStyle?: 'solid' | 'dashed' | 'dotted';
+    borderRadius?: number;
+    color?: string;
+};
+/** Paint-ready inline-box style emitted on measured line slices. */
+export type ResolvedInlineBoxStyle = ResolvedInlineBoxLayout & ResolvedInlineBoxAppearance;
+/**
+ * An internal, layout-aware presentation over a paragraph-visible text range.
+ *
+ * The proof uses leaf styling (D1): measurement creates box-edge segment
+ * boundaries and the painter styles the canonical text leaves. The fallback
+ * sibling layer was not needed. Extension-authored boxes reach this internal
+ * layout contract through the v2 host bridge. RTL input is ignored (D12), and
+ * the synchronous paragraph remeasurer does not consume this field (D14).
+ */
+export type InlineBoxSpan = {
+    id: string;
+    /**
+     * UTF-16 offsets over the paragraph's flattened visible text. Every
+     * non-text run contributes one placeholder character. These offsets never
+     * alter run PM ranges, run indices, source anchors, or document identity.
+     */
+    from: number;
+    to: number;
+    layout: ResolvedInlineBoxLayout;
+    appearance: ResolvedInlineBoxAppearance;
+    className?: string;
+    data?: Record<string, string>;
+    cursor?: 'default' | 'pointer' | 'text' | 'help';
+};
 export type ParagraphBlock = {
     kind: 'paragraph';
     id: BlockId;
     runs: Run[];
     attrs?: ParagraphAttrs;
     sourceAnchor?: SourceAnchor;
+    /** @internal Layout-aware presentation projected from the extension API by the v2 host. */
+    inlineBoxes?: InlineBoxSpan[];
 };
 /** Border style (subset of OOXML ST_Border). */
 export type BorderStyle = 'none' | 'single' | 'double' | 'dashed' | 'dotted' | 'thick' | 'triple' | 'dotDash' | 'dotDotDash' | 'wave' | 'doubleWave';
@@ -1645,6 +1691,8 @@ export type ParagraphAttrs = {
     tabIntervalTwips?: number;
     keepNext?: boolean;
     keepLines?: boolean;
+    /** Prevent a single first or last paragraph line from appearing alone on a page. Defaults to true. */
+    widowControl?: boolean;
     pageBreakBefore?: boolean;
     trackedChangesMode?: TrackedChangesMode;
     trackedChangesEnabled?: boolean;
@@ -1761,6 +1809,13 @@ export declare const isForcedSectPrSectionBreak: (block: FlowBlock | undefined)
  * accepted only when their source/anchor proves they belong to the same filler
  * run.
  */
+export type SectionBoundaryFillerScanCheckpoint = {
+    index: number;
+    total: number;
+};
+export declare function collectSectionBoundaryFillerBlockIdsSteps(blocks: readonly FlowBlock[], options?: {
+    isTinyInlineBoundaryDrawing?: (block: DrawingBlock, index: number) => boolean;
+}, checkpointEveryBlocks?: number | null): Generator<SectionBoundaryFillerScanCheckpoint, ReadonlySet<string>, void>;
 export declare const collectSectionBoundaryFillerBlockIds: (blocks: readonly FlowBlock[], options?: {
     isTinyInlineBoundaryDrawing?: (block: DrawingBlock, index: number) => boolean;
 }) => ReadonlySet<string>;
@@ -1813,6 +1868,28 @@ export type LineInlineImageAlignment = {
     runIndex: number;
     verticalAlign: ImageRunVerticalAlign;
 };
+/**
+ * Paint-ready geometry for one inline-box slice on a measured line.
+ *
+ * Measurement owns the slice geometry and resolved style. The painter consumes
+ * these values directly and never normalizes logical sides or measures the DOM.
+ */
+export type LineInlineBox = {
+    id: string;
+    /** Line-relative UTF-16 offsets covered by this slice. */
+    from: number;
+    to: number;
+    x: number;
+    width: number;
+    top: number;
+    height: number;
+    startsRange: boolean;
+    endsRange: boolean;
+    style: ResolvedInlineBoxStyle;
+    className?: string;
+    data?: Record<string, string>;
+    cursor?: 'default' | 'pointer' | 'text' | 'help';
+};
 export type Line = {
     fromRun: number;
     fromChar: number;
@@ -1843,6 +1920,8 @@ export type Line = {
      * wins over the entry here.
      */
     inlineImageAlignments?: LineInlineImageAlignment[];
+    /** Paint-ready inline-box slices emitted by measurement. */
+    inlineBoxes?: LineInlineBox[];
     /**
      * Measured tab widths keyed by tab run `pmStart`, stored alongside the
      * `ParagraphMeasure` so the painter can read them even after FlowBlock
@@ -2455,5 +2534,7 @@ export declare const extractHeaderFooterSpace: (margins?: PageMargins | null) =>
 export type { ResolvedLayout, ResolvedPage, ResolvedPaintItem, ResolvedGroupItem, ResolvedFragmentItem, ResolvedParagraphContent, ResolvedTextLineItem, ResolvedDropCapItem, ResolvedListMarkerItem, ResolvedTableItem, ResolvedImageItem, ResolvedDrawingItem, ResolvedHeaderFooterPage, ResolvedHeaderFooterLayout, } from './resolved-layout.js';
 export { isResolvedTableItem, isResolvedImageItem, isResolvedDrawingItem } from './resolved-layout.js';
 export { expandRunsForInlineNewlines, isEmptyInlineSdtPlaceholderRun, isEmptySdtPlaceholderRun, sliceRunsForLine, } from './run-helpers.js';
-export { PAGE_CHECKPOINT_DEPENDENCY_CLASSES, areValidPageCheckpointDependencyClasses, type PageCheckpointDependencyClass, } from './incremental-dependency.js';
+export { INLINE_OBJECT_REPLACEMENT_CHARACTER, flattenParagraphVisibleText, mapVisibleRangeToRunSlices, type ParagraphVisibleRunSlice, } from './paragraph-visible-text.js';
+export { inlineBoxStyleSignature, isFiniteNonNegativeInteger, normalizeInlineBoxLogicalSides, type InlineBoxLogicalSides, type ResolvedInlineBoxLogicalSides, } from './inline-box.js';
+export { PAGE_CHECKPOINT_DEPENDENCY_CLASSES, areValidPageCheckpointDependencyClasses, type NonFlowingPageRelativeAnchorDependencyProof, type PageCheckpointDependencyClass, } from './incremental-dependency.js';
 export * as Engines from './engines/index.js';

package/dist/layout-engine/contracts/src/inline-box.d.ts

@@ -0,0 +1,19 @@
+import { ResolvedInlineBoxStyle } from './index.js';
+export type InlineBoxLogicalSides = number | {
+    start: number;
+    end: number;
+};
+export type ResolvedInlineBoxLogicalSides = {
+    start: number;
+    end: number;
+};
+/** True for finite, non-negative integer CSS pixel values. */
+export declare const isFiniteNonNegativeInteger: (value: unknown) => value is number;
+/**
+ * Expands a scalar logical value into explicit start/end values.
+ *
+ * Undefined resolves to zero. Invalid or non-integer input fails closed.
+ */
+export declare const normalizeInlineBoxLogicalSides: (value: InlineBoxLogicalSides | undefined) => ResolvedInlineBoxLogicalSides | null;
+/** Stable signature for every metric and appearance value consumed by paint. */
+export declare const inlineBoxStyleSignature: (style: ResolvedInlineBoxStyle) => string;

package/dist/layout-engine/contracts/src/paragraph-visible-text.d.ts

@@ -0,0 +1,19 @@
+import { ParagraphBlock } from './index.js';
+export declare const INLINE_OBJECT_REPLACEMENT_CHARACTER = "\uFFFC";
+export type ParagraphVisibleRunSlice = {
+    runIndex: number;
+    fromChar: number;
+    toChar: number;
+};
+/**
+ * Flattens a paragraph into Document API visible-text coordinates.
+ *
+ * Text is preserved verbatim in UTF-16. Every non-text run contributes one
+ * U+FFFC object-replacement character, regardless of its rendered label.
+ */
+export declare const flattenParagraphVisibleText: (block: ParagraphBlock) => string;
+/**
+ * Maps a validated visible-text range to slices in the paragraph's run space.
+ * Returns null for non-integer, reversed, negative, or out-of-bounds ranges.
+ */
+export declare const mapVisibleRangeToRunSlices: (block: ParagraphBlock, from: number, to: number) => ParagraphVisibleRunSlice[] | null;

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

@@ -0,0 +1,9 @@
+import { FlowBlock, ParagraphBlock, ParagraphMeasure } from '../../contracts/src/index.js';
+type TextboxRemeasure = (block: ParagraphBlock, maxWidth: number) => ParagraphMeasure;
+/**
+ * Derives table-cell textbox measurements without mutating the projection
+ * plane supplied by the caller. Only the textbox and its table ancestry are
+ * copied; documents without table textboxes retain their original identities.
+ */
+export declare function hydrateTableTextboxMeasures(blocks: FlowBlock[], remeasure: TextboxRemeasure): FlowBlock[];
+export {};

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

@@ -1,6 +1,6 @@
-import { PageCheckpointDependencyClass, FlowBlock, Layout, Measure, HeaderFooterLayout, ParagraphBlock, ParagraphMeasure, ColumnLayout } from '../../contracts/src/index.js';
+import { NonFlowingPageRelativeAnchorDependencyProof, PageCheckpointDependencyClass, FlowBlock, Layout, Measure, HeaderFooterLayout, ColumnLayout } from '../../contracts/src/index.js';
 import { FontMeasureContext } from '../../../shared/font-system/src/index.js';
-import { LayoutOptions, HeaderFooterConstraints } from '../../layout-engine/src/index.js';
+import { LayoutOptions, HeaderFooterConstraints, LayoutExecutionCheckpoint } from '../../layout-engine/src/index.js';
 import { computeDirtyRegions } from './diff.js';
 import { MeasureCache } from './cache.js';
 import { HeaderFooterBatch } from './layoutHeaderFooter.js';
@@ -52,6 +52,8 @@ export type FootnoteReserveSeed = {
 };
 export type IncrementalLayoutResult = {
     layout: Layout;
+    /** Pass-owned block plane after derived layout annotations are attached. */
+    blocks: FlowBlock[];
     measures: Measure[];
     dirty: ReturnType<typeof computeDirtyRegions>;
     headers?: HeaderFooterLayoutResult[];
@@ -207,6 +209,7 @@ export type IncrementalPaginationProof = IncrementalPaginationProofBase & ({
     globalDependenciesAbsent: false;
     globalDependenciesFencedByPageCheckpoint: true;
     admittedDependencyClasses: readonly PageCheckpointDependencyClass[];
+    nonFlowingPageRelativeAnchorDependency?: NonFlowingPageRelativeAnchorDependencyProof;
     localKeepDependencyClosure?: {
         checkpointPageIndex: number;
         checkpointBlockId: string | null;
@@ -276,10 +279,13 @@ export declare const measureCache: MeasureCache<Measure>;
  */
 export declare function clearIncrementalModuleState(): void;
 export interface IncrementalLayoutExecutionControl {
+    signal?: AbortSignal;
     /** Budget-aware host-task yield; may resolve immediately. */
-    yieldToHost?: () => Promise<void>;
-    /** Checkpoint cadence for the block measurement loop. Defaults to 32. */
+    yieldToHost?: (checkpoint?: LayoutExecutionCheckpoint) => Promise<void>;
+    /** Measurement checkpoints default to 32 blocks; nested layout checkpoints default to 16. */
     yieldEveryBlocks?: number;
+    /** Time-aware mounted probe. Null is the allocation-free under-budget path. */
+    checkpointIfDue?: (checkpoint?: LayoutExecutionCheckpoint) => Promise<void> | null;
 }
 export declare function incrementalLayout(previousBlocks: FlowBlock[], _previousLayout: Layout | null, nextBlocks: FlowBlock[], options: LayoutOptions, measureBlock: (block: FlowBlock, constraints: {
     maxWidth: number;
@@ -325,12 +331,6 @@ export declare function incrementalLayout(previousBlocks: FlowBlock[], _previous
  * @returns The normalized margin value (guaranteed to be finite)
  */
 export declare const normalizeMargin: (value: number | undefined, fallback: number) => number;
-/**
- * Walks table blocks (including nested tables) and computes `contentMeasures` for any
- * `textboxShape` drawings found in table cells. Stores results directly on the block so
- * the painter can read them without a `DrawingFragment` (table-cell drawings have none).
- */
-export declare function hydrateTableTextboxMeasures(blocks: FlowBlock[], remeasure: (block: ParagraphBlock, maxWidth: number) => ParagraphMeasure): void;
 /**
  * Resolves the maximum measurement constraints (width and height) needed for measuring blocks
  * across all sections in a document.