superdoc 2.0.0-next.27 → 2.0.0-next.29

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.0.0-next.27",
+	superdocVersion: "2.0.0-next.29",
 	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.0.0-next.27",
+	superdocVersion: "2.0.0-next.29",
 	roomSchemaVersion: Object.freeze({ ...PRIVATE_ENGINE_INFO.roomSchemaVersion }),
 	supportedBundleVersions: SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS,
 	supportedV1ReaderContractVersions: SUPPORTED_V1_READER_CONTRACT_VERSIONS

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

@@ -976,7 +976,7 @@ export declare const OPERATION_DEFINITIONS: {
     };
     readonly 'trackChanges.decide': {
         readonly memberPath: "trackChanges.decide";
-        readonly description: "Accept or reject tracked changes by logical id, by selected text range, by logical anchor range ({ anchor, relativeStart, relativeEnd }), or every active change in the document. Range targets may include overlap / side selectors and may partially resolve a change, splitting surviving content into new fragments with stable ids. Legacy `{ id, range: { kind: \"partial\", ... } }` targets are promoted only when the active adapter supports `decide()`; legacy fallback adapters fail closed with `INVALID_INPUT`. `input.expectedRevision` is accepted as a compatibility alias for mutation options.";
+        readonly description: "Accept or reject tracked changes by logical id, by several logical ids atomically, by selected text range, by logical anchor range ({ anchor, relativeStart, relativeEnd }), or every active change in the document. Range targets may include overlap / side selectors and may partially resolve a change, splitting surviving content into new fragments with stable ids. Legacy `{ id, range: { kind: \"partial\", ... } }` targets are promoted only when the active adapter supports `decide()`; legacy fallback adapters fail closed with `INVALID_INPUT`. `input.expectedRevision` is accepted as a compatibility alias for mutation options.";
         readonly expectedResult: "Returns a Receipt. `removed` lists retired tracked-change ids; `inserted` lists successor fragment ids produced by partial range splits; `invalidatedRefs` lists every retired tracked-change ref plus cascade-deleted comment ids; `remappedRefs` carries surviving comment anchors moved by the decision; `affectedStories` lists touched stories; `textRangeShifts` reports per-story visible-text deltas; `txId` correlates with history. Failures: SPAN_FRAGMENTED when a range crosses an indivisible boundary, CAPABILITY_UNAVAILABLE for formatting / structural / move targets (not yet supported), TARGET_NOT_FOUND for retired ids or zero overlap, STALE_REVISION for stale expectedRevision, REVISION_MISMATCH for stale range coverage, NO_OP when { kind: 'all' } resolves an empty target set.";
         readonly requiresDocumentContext: true;
         readonly metadata: CommandStaticMetadata;

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

@@ -72,6 +72,10 @@ export type ReviewDecideTarget = {
     story?: StoryLocator;
     side?: ReviewDecideIdTargetSide;
     moveRole?: ReviewDecideTargetMoveRole;
+} | {
+    /** Resolve several whole logical changes in one atomic history unit. */
+    kind: 'ids';
+    ids: string[];
 } | ReviewDecideTextRangeTarget | ReviewDecideLogicalRangeTarget | {
     kind: 'all';
     story?: StoryLocator | 'all';
@@ -153,7 +157,7 @@ export declare function executeTrackChangesGet(adapter: TrackChangesAdapter, inp
  * {@link RevisionGuardOptions} rather than `MutationOptions`.
  *
  * Validates the canonical discriminated target shape
- * (`{ kind: 'id' | 'range' | 'all' }`) and transparently promotes the
+ * (`{ kind: 'id' | 'ids' | 'range' | 'all' }`) and transparently promotes the
  * legacy `{ id, story? }` / `{ scope: 'all' }` shapes. Adapters that
  * implement the new {@link TrackChangesAdapter.decide} entrypoint receive
  * the normalized canonical input; older adapters that only expose
@@ -163,7 +167,7 @@ export declare function executeTrackChangesGet(adapter: TrackChangesAdapter, inp
 export declare function executeTrackChangesDecide(adapter: TrackChangesAdapter, rawInput: ReviewDecideInput, options?: RevisionGuardOptions): Receipt;
 /**
  * Validate and normalize a `trackChanges.decide` input into the canonical
- * `{ kind: 'id' | 'range' | 'all' }` target shape. Exposed for adapters /
+ * `{ kind: 'id' | 'ids' | 'range' | 'all' }` target shape. Exposed for adapters /
  * tests that need to share the same validation surface.
  */
 export declare function validateReviewDecideInput(rawInput: ReviewDecideInput): ReviewDecideRangeInput;

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

@@ -75,10 +75,14 @@ export interface SDPasteParagraphBlock {
      * Portable list membership intent. Without `numbering`, the kernel always
      * materializes a fresh definition. With `numbering`, the existing identity
      * is retained when the destination defines the same list kind; otherwise
-     * this intent is the cross-document fallback. Single-level.
+     * this intent is the cross-document fallback. `level` is zero-based and
+     * bounded to OOXML's nine list levels; omitted means level 0.
      */
     listIntent?: {
         kind: 'bullet' | 'ordered';
+        level?: number;
+        /** True on the first block of a distinct adjacent portable list. */
+        startsNewList?: boolean;
     };
     /**
      * Pre-validated direct `<w:pPr>` properties. Same-document copy carries the

package/dist/document-api/src/types/table-operations.types.d.ts

@@ -109,15 +109,17 @@ export type TableAnchorLocation = {
  */
 export type TableCreateLocation = TableAnchorLocation
 /**
- * Split the target paragraph at a visible-text offset and insert the table
- * as a standalone block between the head/tail halves (Word semantics: a
- * table cannot splice into a paragraph's runs). Body paragraphs only for
- * now; `changeMode: 'tracked'` is not supported for this location kind.
+ * Split the target paragraph at an offset and insert the table as a
+ * standalone block between the head/tail halves (Word semantics: a table
+ * cannot splice into a paragraph's runs). Offsets are visible-text by
+ * default; use `coordinateSpace: 'tracked'` for a deletion-inclusive caret
+ * coordinate. Body paragraphs only for now.
  */
  | {
     kind: 'inParagraph';
     target: BlockNodeAddress;
     offset: number;
+    coordinateSpace?: 'visible' | 'tracked';
 };
 /**
  * Generic success result for table mutation operations.

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

@@ -448,6 +448,17 @@ export interface TrackChangeImagePreview {
     /** Accessible label for clients that render the preview. */
     alt?: string;
 }
+/**
+ * Authoritative block address for review navigation. Consumers use this
+ * instead of interpreting the shape-specific {@link TrackChangeTarget}
+ * union. `role` records which semantic carrier supplied the address.
+ */
+export interface TrackChangeNavigationTarget {
+    kind: 'block';
+    story: StoryLocator;
+    blockId: string;
+    role: 'primary' | 'move-source' | 'move-destination' | 'formatting-carrier' | 'structural-carrier';
+}
 export interface TrackChangeInfo {
     address: TrackedChangeAddress;
     /** Stable SuperDoc logical tracked-change id (spec §3 / §4). */
@@ -459,6 +470,8 @@ export interface TrackChangeInfo {
     state?: TrackChangeState;
     /** Logical target description. */
     target?: TrackChangeTarget;
+    /** Stable story/block address for focus and virtualized materialization. */
+    navigationTarget?: TrackChangeNavigationTarget;
     /** Semantic before-state needed to reject the change. */
     before?: TrackChangeSnapshot;
     /** Semantic after-state needed to accept the change. */
@@ -598,6 +611,8 @@ export interface TrackChangeDomain {
     state?: TrackChangeState;
     /** Logical target summary for list consumers when the compact projection can provide it safely. */
     target?: TrackChangeTarget;
+    /** Stable story/block address for focus and virtualized materialization. */
+    navigationTarget?: TrackChangeNavigationTarget;
     /** Move side metadata for paired tracked moves. */
     move?: TrackChangeMoveSides;
     /** Direction of a paired move in document order, when source/destination order is known. */

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

@@ -0,0 +1,10 @@
+/**
+ * Stable dependency classes that an incremental page checkpoint may fence.
+ *
+ * This list is proof metadata, never a feature switch. Producers must name
+ * 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 declare function areValidPageCheckpointDependencyClasses(value: unknown): value is readonly PageCheckpointDependencyClass[];

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

@@ -1749,6 +1749,11 @@ export type ListBlock = {
     sourceAnchor?: SourceAnchor;
 };
 export type FlowBlock = ParagraphBlock | ImageBlock | DrawingBlock | ListBlock | TableBlock | SectionBreakBlock | PageBreakBlock | ColumnBreakBlock;
+export declare const isReviewableSectionBoundaryMarkerBlock: (block: FlowBlock | null | undefined) => boolean;
+/** Shared eligibility for paragraphs the layout loop deliberately omits. */
+export declare const shouldSkipParagraphDuringLayout: (blocks: FlowBlock[], index: number) => boolean;
+/** True only for block kinds that produce an addressable layout fragment. */
+export declare const doesFlowBlockProduceLayoutFragment: (blocks: FlowBlock[], index: number) => boolean;
 export type ColumnLayout = {
     count: number;
     gap: number;
@@ -2355,6 +2360,36 @@ export type HeaderFooterLayout = {
     renderHeight?: number;
     pages: HeaderFooterPage[];
 };
+/**
+ * Engine-owned paginator state immediately before a top-level paragraph.
+ * Incremental layout may resume from this state only after independently
+ * proving that every preceding fragment on the page is stable.
+ */
+export type LayoutBlockResumeCheckpoint = {
+    blockId: BlockId;
+    pageIndex: number;
+    prefixFragmentCount: number;
+    cursorY: number;
+    maxCursorY: number;
+    columnIndex: number;
+    trailingSpacing: number;
+    lastParagraphStyleId?: string;
+    lastParagraphContextualSpacing: boolean;
+    lastParagraphBorderHash?: string;
+    constraintBoundaries: readonly {
+        y: number;
+        columns: ColumnLayout;
+    }[];
+    activeConstraintIndex: number;
+    footnoteDemandThisPage: number;
+    footnoteRefsThisPage: number;
+    footnoteAnchorsThisPage: readonly {
+        pmPos: number;
+        refId: string;
+        fullHeight: number;
+        firstLineHeight: number;
+    }[];
+};
 /** Final layout output ready for painting. */
 export type Layout = {
     pageSize: {
@@ -2380,6 +2415,8 @@ export type Layout = {
      * from DOM-derived positions back to the current ProseMirror document state.
      */
     layoutEpoch?: number;
+    /** Exact paragraph-boundary resume sidecar; never inferred from painted geometry. */
+    blockResumeCheckpoints?: ReadonlyMap<BlockId, LayoutBlockResumeCheckpoint>;
 };
 export type WrapTextMode = 'bothSides' | 'left' | 'right' | 'largest';
 export type WrapExclusion = {
@@ -2402,4 +2439,5 @@ 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 * as Engines from './engines/index.js';

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

@@ -1,4 +1,4 @@
-import { FlowBlock, Layout, Measure, HeaderFooterLayout, ParagraphBlock, ParagraphMeasure } from '../../contracts/src/index.js';
+import { PageCheckpointDependencyClass, FlowBlock, Layout, Measure, HeaderFooterLayout, ParagraphBlock, ParagraphMeasure, 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 { computeDirtyRegions } from './diff.js';
@@ -33,10 +33,22 @@ export type HeaderFooterLayoutResult = {
  */
 export type FootnoteReserveSeed = {
     reserves: number[];
+    /** Sparse page indexes that held a reserve, ledger, or injected note slice. */
+    notePageIndexes?: number[];
     separatorSpacingBefore: number | undefined;
     fontSignature: string;
     measurementWidth: number;
     measurementHeight: number;
+    /** Exact note measurement width retained with unchanged section geometry. */
+    footnoteMeasurementWidth?: number;
+    /** Section-column inputs used to derive the retained note measurement width. */
+    sectionColumnsByIndex?: Map<number, ColumnLayout>;
+    /** Exact note block objects retained by the host's authoritative note-bundle proof. */
+    noteBlocksByBlockId?: Map<string, FlowBlock>;
+    /** Measures paired with `noteBlocksByBlockId`; object identity is revalidated before reuse. */
+    noteMeasuresByBlockId?: Map<string, Measure>;
+    noteBodyHeightById?: Map<string, number>;
+    noteFirstLineHeightById?: Map<string, number>;
 };
 export type IncrementalLayoutResult = {
     layout: Layout;
@@ -165,6 +177,12 @@ type IncrementalPaginationProofBase = {
     blockIdsUnchanged: true;
     blockIdsUnique: true;
     renderInputsUnchanged: true;
+    /** The retained dependency scan proved that no body or furniture PAGE_REF token exists. */
+    pageReferencesAbsent: boolean;
+    pageReferenceDependencyClosure?: {
+        referenceBlockIds: readonly string[];
+        targetBookmarkIds: readonly string[];
+    };
 };
 export type IncrementalPaginationProof = IncrementalPaginationProofBase & ({
     profile: 'single-section-local-text';
@@ -181,6 +199,12 @@ export type IncrementalPaginationProof = IncrementalPaginationProofBase & ({
     profile: 'page-checkpoint-local-text';
     globalDependenciesAbsent: false;
     globalDependenciesFencedByPageCheckpoint: true;
+    admittedDependencyClasses: readonly PageCheckpointDependencyClass[];
+    localKeepDependencyClosure?: {
+        checkpointPageIndex: number;
+        checkpointBlockId: string | null;
+        predecessorBlockId: string | null;
+    };
     /**
      * SD-3772 D1: the host proved (via the shared
      * `hasGenuinelyUnequalExplicitColumnWidths` predicate) that no
@@ -226,6 +250,14 @@ export type IncrementalLayoutReuseOptions = {
     }> | null;
     /** Retained key index used for O(1) convergence candidate lookup. */
     previousPageStartKeyIndex?: ReadonlyMap<string, readonly number[]> | null;
+    /**
+     * Host-proved note-only refresh. Body ids are unchanged reference anchors;
+     * only the named note projections may differ from the retained note plane.
+     */
+    provedNoteOnlyRefresh?: {
+        noteIds: readonly string[];
+        bodyReferenceBlockIds: readonly string[];
+    };
 };
 export declare const measureCache: MeasureCache<Measure>;
 /**
@@ -269,6 +301,13 @@ export declare function incrementalLayout(previousBlocks: FlowBlock[], _previous
     previousFontSignature?: string;
 }, warmStart?: {
     footnoteReserveSeed?: FootnoteReserveSeed | null;
+    /** Host proved the authoritative note projection bundle was retained exactly. */
+    noteMeasurePlaneRetainedExact?: true;
+    /** Extra note/decorative planes paired with the retained note bundle. */
+    retainedFootnoteExtras?: {
+        blocks: FlowBlock[];
+        measures: Measure[];
+    };
 }, layoutReuse?: IncrementalLayoutReuseOptions, measureReuseProof?: IncrementalMeasureReuseProof, execution?: IncrementalLayoutExecutionControl): Promise<IncrementalLayoutResult>;
 /**
  * Normalizes a margin value, using a fallback for undefined or non-finite values.

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

@@ -1,4 +1,5 @@
 import { ColumnLayout, FlowBlock, HeaderFooterLayout, Layout, Measure, Page, ParagraphBlock, ParagraphMeasure, SectionMetadata, FlowMode, DocumentBackground } from '../../contracts/src/index.js';
+import { PageState, ConstraintBoundary } from './paginator.js';
 type PageSize = {
     w: number;
     h: number;
@@ -197,6 +198,22 @@ export type LayoutOptions = {
         };
         /** Resolved active column layout at the resumed boundary. */
         activeColumns?: ColumnLayout;
+        /** Engine-authored exact state for a paragraph boundary inside the first emitted page. */
+        initialPageState?: {
+            prefixFragments: readonly Page['fragments'][number][];
+            cursorY: number;
+            maxCursorY: number;
+            columnIndex: number;
+            trailingSpacing: number;
+            lastParagraphStyleId?: string;
+            lastParagraphContextualSpacing: boolean;
+            lastParagraphBorderHash?: string;
+            constraintBoundaries: readonly ConstraintBoundary[];
+            activeConstraintIndex: number;
+            footnoteDemandThisPage: number;
+            footnoteRefsThisPage: number;
+            footnoteAnchorsThisPage: readonly PageState['footnoteAnchorsThisPage'][number][];
+        };
     };
     /**
      * Optional page-boundary stop callback. Called after a page has completed

package/dist/layout-engine/layout-engine/src/paginator.d.ts

@@ -73,6 +73,22 @@ export type PaginatorOptions = {
         h: number;
     };
     getActiveColumns(): ColumnLayout;
+    /** Exact first-page state from an engine-authored paragraph checkpoint. */
+    initialPageState?: {
+        prefixFragments: readonly Page['fragments'][number][];
+        cursorY: number;
+        maxCursorY: number;
+        columnIndex: number;
+        trailingSpacing: number;
+        lastParagraphStyleId?: string;
+        lastParagraphContextualSpacing: boolean;
+        lastParagraphBorderHash?: string;
+        constraintBoundaries: readonly ConstraintBoundary[];
+        activeConstraintIndex: number;
+        footnoteDemandThisPage: number;
+        footnoteRefsThisPage: number;
+        footnoteAnchorsThisPage: readonly PageState['footnoteAnchorsThisPage'][number][];
+    };
     pageNumberOffset?: number;
     createPage(number: number, pageMargins: PageMargins, pageSizeOverride?: {
         w: number;

package/dist/layout-engine/layout-engine/src/paragraph-layout-eligibility.d.ts

@@ -1,4 +1 @@
-import { FlowBlock } from '../../contracts/src/index.js';
-export declare const isReviewableSectionBoundaryMarkerBlock: (block: FlowBlock | null | undefined) => boolean;
-/** Paragraphs omitted by the main layout loop must not receive anchored objects. */
-export declare const shouldSkipParagraphDuringLayout: (blocks: FlowBlock[], index: number) => boolean;
+export { isReviewableSectionBoundaryMarkerBlock, shouldSkipParagraphDuringLayout } from '../../contracts/src/index.js';

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-pYMthdDn.cjs");
+const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-BXehf3i3.cjs");
 let react = require("react");
 var SuperDocUIContext = (0, react.createContext)(null);
 function SuperDocUIProvider(props) {

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

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

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