superdoc 2.24.0-next.1 → 2.24.0-next.10

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

@@ -28,7 +28,7 @@ export interface IntentGroupMeta {
      */
     inputExamples?: Record<string, unknown>[];
 }
-export declare const V1_RUNTIME_UNAVAILABLE_OPERATION_IDS: readonly ["blocks.split", "blocks.merge", "blocks.move", "lists.getState", "lists.apply", "lists.continue", "lists.restart", "lists.remove", "format.paragraph.setMarkRunProps", "tables.moveRow", "tables.moveColumn"];
+export declare const V1_RUNTIME_UNAVAILABLE_OPERATION_IDS: readonly ["selection.releaseSnapshot", "blocks.split", "blocks.merge", "blocks.move", "lists.getState", "lists.apply", "lists.continue", "lists.restart", "lists.remove", "format.paragraph.setMarkRunProps", "tables.moveRow", "tables.moveColumn"];
 export declare const INTENT_GROUP_META: Record<string, IntentGroupMeta>;
 export declare const OPERATION_DEFINITIONS: {
     readonly 'styles.apply': {
@@ -1031,9 +1031,19 @@ export declare const OPERATION_DEFINITIONS: {
         readonly referenceDocPath: "selection/current.mdx";
         readonly referenceGroup: "selection";
     };
+    readonly 'selection.releaseSnapshot': {
+        readonly memberPath: "selection.releaseSnapshot";
+        readonly description: string;
+        readonly expectedResult: "Returns released=true when a same-session handle was removed; otherwise false.";
+        readonly requiresDocumentContext: true;
+        readonly metadata: CommandStaticMetadata;
+        readonly referenceDocPath: "selection/release-snapshot.mdx";
+        readonly referenceGroup: "selection";
+        readonly batchable: false;
+    };
     readonly 'selection.extractOoxml': {
         readonly memberPath: "selection.extractOoxml";
-        readonly description: "Capture a nonempty current or addressed selection as OOXML with its structure, context, and package dependencies.";
+        readonly description: "Capture a nonempty current or addressed selection as portable OOXML with native dependencies. Optional retain:true keeps an exact same-session restoration handle for one complete standalone body paragraph; release it when unused. Unsupported retained contexts and collaboration reject.";
         readonly expectedResult: "Returns the selected OOXML, structural placement, source provenance, and required relationships and parts without changing the document.";
         readonly requiresDocumentContext: true;
         readonly metadata: CommandStaticMetadata;
@@ -3580,9 +3590,6 @@ export declare const OPERATION_DEFINITIONS: {
     readonly "format.border": OperationDefinitionEntry & {
         memberPath: "format.border";
     };
-    readonly "format.fitText": OperationDefinitionEntry & {
-        memberPath: "format.fitText";
-    };
     readonly "format.dstrike": OperationDefinitionEntry & {
         memberPath: "format.dstrike";
     };
@@ -3610,6 +3617,9 @@ export declare const OPERATION_DEFINITIONS: {
     readonly "format.kerning": OperationDefinitionEntry & {
         memberPath: "format.kerning";
     };
+    readonly "format.fitText": OperationDefinitionEntry & {
+        memberPath: "format.fitText";
+    };
     readonly "format.rStyle": OperationDefinitionEntry & {
         memberPath: "format.rStyle";
     };

package/dist/document-api/src/cross-refs/cross-refs.types.d.ts

@@ -62,6 +62,7 @@ export interface CrossRefDomain {
 }
 export interface CrossRefMutationSuccess {
     success: true;
+    appliedChangeMode?: 'direct' | 'tracked';
     crossRef: CrossRefAddress;
 }
 export type CrossRefMutationResult = CrossRefMutationSuccess | AdapterMutationFailure;

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

@@ -84,6 +84,7 @@ export interface FieldDomain {
 }
 export interface FieldMutationSuccess {
     success: true;
+    appliedChangeMode?: 'direct' | 'tracked';
     field: FieldAddress;
 }
 export type FieldMutationResult = FieldMutationSuccess | AdapterMutationFailure;

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

@@ -94,11 +94,13 @@ export interface FootnoteDomain {
 }
 export interface FootnoteMutationSuccess {
     success: true;
+    appliedChangeMode?: 'direct' | 'tracked';
     footnote: FootnoteAddress;
 }
 export type FootnoteMutationResult = FootnoteMutationSuccess | AdapterMutationFailure;
 export interface FootnoteConfigSuccess {
     success: true;
+    appliedChangeMode?: 'direct' | 'tracked';
 }
 export type FootnoteConfigResult = FootnoteConfigSuccess | AdapterMutationFailure;
 export type FootnotesListResult = DiscoveryOutput<FootnoteDomain>;

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

@@ -76,6 +76,7 @@ export interface HyperlinkInfo {
 }
 export interface HyperlinkMutationSuccess {
     success: true;
+    appliedChangeMode?: 'direct' | 'tracked';
     hyperlink: HyperlinkTarget;
 }
 export interface HyperlinkMutationFailure {

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

@@ -188,6 +188,7 @@ export interface SetZOrderInput {
 }
 export interface CreateImageSuccessResult {
     success: true;
+    appliedChangeMode?: 'direct' | 'tracked';
     image: ImageAddress;
     trackedChangeRefs?: ReceiptInsert[];
     /** Commit id for the insertion, including its alt text when that was set in the same call. */
@@ -207,6 +208,7 @@ export interface ImagesListResult {
 }
 export interface ImagesMutationSuccessResult {
     success: true;
+    appliedChangeMode?: 'direct' | 'tracked';
     image: ImageAddress;
     trackedChangeRefs?: ReceiptInsert[];
 }

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

@@ -113,11 +113,13 @@ export interface IndexEntryDomain {
 }
 export interface IndexMutationSuccess {
     success: true;
+    appliedChangeMode?: 'direct' | 'tracked';
     index: IndexAddress;
 }
 export type IndexMutationResult = IndexMutationSuccess | AdapterMutationFailure;
 export interface IndexEntryMutationSuccess {
     success: true;
+    appliedChangeMode?: 'direct' | 'tracked';
     entry: IndexEntryAddress;
 }
 export type IndexEntryMutationResult = IndexEntryMutationSuccess | AdapterMutationFailure;

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

@@ -25,7 +25,7 @@ import { InsertInput } from './insert/insert.js';
 import { ResolveRangeInput, ResolveRangeOutput } from './ranges/ranges.types.js';
 import { SelectionApi, SelectionAdapter } from './selection/selection.js';
 import { ListsAdapter, ListsApi } from './lists/lists.js';
-import { ReplaceInput } from './replace/replace.js';
+import { ReplaceInput, ReplaceMutationOptions } from './replace/replace.js';
 import { CreateAdapter, CreateApi } from './create/create.js';
 import { BlocksAdapter, BlocksApi } from './blocks/blocks.js';
 import { TableLocator, TableMutationResult, TablesConvertFromTextInput, TablesMoveInput, TablesSplitInput, TablesConvertToTextInput, TablesSetLayoutInput, TablesInsertRowInput, TablesDeleteRowInput, TablesMoveRowInput, TablesSetRowHeightInput, TablesDistributeRowsInput, TablesSetRowOptionsInput, TablesInsertColumnInput, TablesDeleteColumnInput, TablesMoveColumnInput, TablesSetColumnWidthInput, TablesDistributeColumnsInput, TablesInsertCellInput, TablesDeleteCellInput, TablesMergeCellsInput, TablesUnmergeCellsInput, TablesSplitCellInput, TablesSetCellPropertiesInput, TablesSetCellTextInput, TablesSortInput, TablesSetAltTextInput, TablesSetStyleInput, TablesClearStyleInput, TablesSetStyleOptionInput, TablesSetBorderInput, TablesClearBorderInput, TablesApplyBorderPresetInput, TablesSetShadingInput, TablesClearShadingInput, TablesSetTablePaddingInput, TablesSetCellPaddingInput, TablesSetCellSpacingInput, TablesClearCellSpacingInput, TablesApplyStyleInput, TablesSetBordersInput, TablesSetTableOptionsInput, TablesApplyPresetInput, TablesGetInput, TablesGetOutput, TablesGetCellsInput, TablesGetCellsOutput, TablesGetPropertiesInput, TablesGetPropertiesOutput, TablesGetStylesInput, TablesGetStylesOutput, TablesSetDefaultStyleInput, TablesClearDefaultStyleInput } from './types/table-operations.types.js';
@@ -77,8 +77,8 @@ export * from './export/export.types.js';
 export type { SelectionMutationAdapter, SelectionMutationRequest, SelectionInsertRequest, } from './selection-mutation.js';
 export type { RangeAnchor, DocumentEdgeAnchor, PointAnchor, RefBoundaryAnchor, ResolveRangeInput, ResolveRangeOutput, RangeBlockPreview, RangePreview, RangeResolverAdapter, ScrollIntoViewInput, ScrollIntoViewOutput, } from './ranges/index.js';
 export { executeResolveRange } from './ranges/index.js';
-export type { SelectionApi, SelectionAdapter, SelectionCurrentInput, SelectionExtractOoxmlInput, SelectionExtractOoxmlResult, SelectionOoxmlDependency, SelectionTableCellsTarget, TableSelectionInfo, SelectionInfo, } from './selection/selection.js';
-export { executeSelectionCurrent, executeSelectionExtractOoxml } from './selection/selection.js';
+export type { SelectionApi, SelectionAdapter, SelectionCurrentInput, SelectionExtractOoxmlInput, SelectionExtractOoxmlResult, SelectionOoxmlDependency, OoxmlContentSource, SelectionReleaseSnapshotInput, SelectionReleaseSnapshotResult, SelectionTableCellsTarget, TableSelectionInfo, SelectionInfo, } from './selection/selection.js';
+export { executeSelectionCurrent, executeSelectionExtractOoxml, executeSelectionReleaseSnapshot, } from './selection/selection.js';
 export type { HeaderFootersAdapter, HeaderFootersApi } from './header-footers/header-footers.js';
 export * from './header-footers/header-footers.types.js';
 export type { WatermarksAdapter, WatermarksApi } from './watermarks/watermarks.js';
@@ -175,9 +175,9 @@ export { DocumentApiValidationError } from './errors.js';
 export { textReceiptToSDReceipt, buildStructuralReceipt } from './receipt-bridge.js';
 export type { MutationReceiptBridgeContext, StructuralReceiptParams } from './receipt-bridge.js';
 export { isBlockNodeAddress } from './validation-primitives.js';
-export type { InsertInput, InsertContentType, TextInsertInput, PlainTextInsertInput, RichContentInsertInput, LegacyInsertInput, } from './insert/insert.js';
+export type { InsertInput, InsertContentType, TextInsertInput, PlainTextInsertInput, RichContentInsertInput, NativeOoxmlInsertInput, LegacyInsertInput, } from './insert/insert.js';
 export { isStructuralInsertInput } from './insert/insert.js';
-export type { ReplaceInput, TextReplaceInput, RichContentReplaceInput } from './replace/replace.js';
+export type { ReplaceInput, TextReplaceInput, RichContentReplaceInput, ReplaceMutationOptions, NativeOoxmlReplaceInput, SnapshotReplaceInput, ParagraphTextReplaceInput, } from './replace/replace.js';
 export { executeReplace, isStructuralReplaceInput, isRichContentReplaceInput } from './replace/replace.js';
 export { executeFind } from './find/find.js';
 export { validateDocumentFragment, validateSDFragment } from './validation/fragment-validator.js';
@@ -353,7 +353,7 @@ export interface DocumentApiSurface {
     replace(input: Exclude<import('./replace/replace.js').TextReplaceInput, {
         target: import('./types/story.types.js').BodyStoryLocator;
     }>, options: TrackedTextMutationOptions): SDMutationReceipt;
-    replace(input: ReplaceInput, options?: RichContentMutationOptions): SDMutationReceipt;
+    replace(input: ReplaceInput, options?: ReplaceMutationOptions): SDMutationReceipt;
     /**
      * Delete text at a target range.
      */

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

@@ -1,3 +1,4 @@
+import { OoxmlContentSource } from '../selection/selection.types.js';
 import { RichContentMutationOptions, TextMutationOptions, WriteAdapter } from '../write/write.js';
 import { SelectionTarget, TargetLocator, SDMutationReceipt } from '../types/index.js';
 import { SDInsertInput } from '../types/structural-input.js';
@@ -45,7 +46,12 @@ export type LegacyInsertInput = TextInsertInput;
  * Discrimination: presence of `content` (structural) vs `value` (text string).
  * These are mutually exclusive: providing both is an error.
  */
-export type InsertInput = TextInsertInput | RichContentInsertInput | SDInsertInput;
+export type NativeOoxmlInsertInput = OoxmlContentSource & {
+    target?: SelectionTarget | BlockNodeAddress;
+    placement?: Placement;
+    in?: StoryLocator;
+};
+export type InsertInput = TextInsertInput | RichContentInsertInput | SDInsertInput | NativeOoxmlInsertInput;
 export type PlainTextInsertInput = TextInsertInput & {
     type?: 'text';
 };

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

@@ -358,12 +358,14 @@ export interface ListsCaptureTemplateSuccessResult {
 export type ListsCaptureTemplateResult = ListsCaptureTemplateSuccessResult | ListsFailureResult;
 export interface ListsInsertSuccessResult {
     success: true;
+    appliedChangeMode?: 'direct' | 'tracked';
     item: ListItemAddress;
     insertionPoint: TextAddress;
     trackedChangeRefs?: ReceiptInsert[];
 }
 export interface ListsMutateItemSuccessResult {
     success: true;
+    appliedChangeMode?: 'direct' | 'tracked';
     item: ListItemAddress;
     /** Tracked changes authored by this mutation when `changeMode` is tracked. */
     trackedChangeRefs?: ReceiptInsert[];
@@ -375,32 +377,38 @@ export interface ListsMutateItemSuccessResult {
 }
 export interface ListsCreateSuccessResult {
     success: true;
+    appliedChangeMode?: 'direct' | 'tracked';
     listId: string;
     item: ListItemAddress;
 }
 export interface ListsJoinSuccessResult {
     success: true;
+    appliedChangeMode?: 'direct' | 'tracked';
     listId: string;
 }
 export interface ListsSeparateSuccessResult {
     success: true;
+    appliedChangeMode?: 'direct' | 'tracked';
     listId: string;
     numId: number;
 }
 export interface ListsMergeSuccessResult {
     success: true;
+    appliedChangeMode?: 'direct' | 'tracked';
     listId: string;
     absorbedCount: number;
     removedEmptyBlocks: number;
 }
 export interface ListsSplitSuccessResult {
     success: true;
+    appliedChangeMode?: 'direct' | 'tracked';
     listId: string;
     numId: number;
     restartedAt: number | null;
 }
 export interface ListsDetachSuccessResult {
     success: true;
+    appliedChangeMode?: 'direct' | 'tracked';
     paragraph: {
         kind: 'block';
         nodeType: 'paragraph';
@@ -409,6 +417,7 @@ export interface ListsDetachSuccessResult {
 }
 export interface ListsConvertToTextSuccessResult {
     success: true;
+    appliedChangeMode?: 'direct' | 'tracked';
     paragraph: {
         kind: 'block';
         nodeType: 'paragraph';
@@ -440,6 +449,7 @@ export type ListsDetachResult = ListsDetachSuccessResult | ListsFailureResult;
 export type ListsConvertToTextResult = ListsConvertToTextSuccessResult | ListsFailureResult;
 export interface ListsDeleteSuccessResult {
     success: true;
+    appliedChangeMode?: 'direct' | 'tracked';
     /** Number of list items removed. */
     deletedCount: number;
 }

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

@@ -1,6 +1,7 @@
 import { BlockNodeAddress } from '../types/base.js';
 import { ReceiptFailure, ReceiptInsert } from '../types/receipt.js';
 import { SDRunProps } from '../types/sd-props.js';
+import { ChangeMode } from '../write/write.js';
 export type ParagraphBlockType = 'paragraph' | 'heading' | 'listItem';
 export type ParagraphTarget = BlockNodeAddress & {
     nodeType: ParagraphBlockType;
@@ -12,6 +13,8 @@ export interface ParagraphMutationSuccess {
     success: true;
     target: ParagraphTarget;
     resolution: MutationResolution;
+    /** Mode applied to committed paragraph content; omitted when no content was committed. */
+    appliedChangeMode?: ChangeMode;
     /** Logical tracked-change entities created or revised by this mutation. */
     trackedChangeRefs?: ReceiptInsert[];
 }

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

@@ -7,6 +7,7 @@ export interface MutationReceiptBridgeContext {
     conversion?: SDMutationConversionReport;
 }
 interface CanonicalSuccessMetadata {
+    appliedChangeMode?: ReceiptSuccess['appliedChangeMode'];
     id?: ReceiptSuccess['id'];
     inserted?: ReceiptSuccess['inserted'];
     updated?: ReceiptSuccess['updated'];

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

@@ -1,3 +1,4 @@
+import { OoxmlContentSource } from '../selection/selection.types.js';
 import { RichContentMutationOptions, TextMutationOptions, WriteAdapter } from '../write/write.js';
 import { SelectionTarget } from '../types/address.js';
 import { SDMutationReceipt } from '../types/sd-contract.js';
@@ -47,11 +48,37 @@ export type RichContentReplaceInput = {
 /**
  * Input payload for the `doc.replace` operation.
  *
- * Discrimination: `text` (plain), `value` (HTML/Markdown), or `content` (SDFragment).
+ * Discrimination: `text`, typed `value`, `content`, portable `capture`, or retained `snapshotId`.
  */
-export type ReplaceInput = TextReplaceInput | RichContentReplaceInput | SDReplaceInput;
+export type NativeOoxmlReplaceInput = OoxmlContentSource & {
+    target: SelectionTarget | BlockNodeAddress;
+    in?: StoryLocator;
+    nestingPolicy?: NestingPolicy;
+};
+export type SnapshotReplaceInput = {
+    target: BlockNodeAddress;
+    snapshotId: string;
+    in?: never;
+};
+export type ParagraphTextReplaceInput = {
+    target: BlockNodeAddress;
+    text: string;
+    in?: never;
+};
+export interface ReplaceMutationOptions extends RichContentMutationOptions {
+    /** Replace one paragraph's contents, retaining its identity and exact paragraph properties. */
+    replaceMode?: 'contents';
+    /** Compare the addressed paragraph with an unchanged retained snapshot before committing. */
+    expectedSnapshotId?: string;
+}
+type ReplaceExecutionOptions = ReplaceMutationOptions | (TextMutationOptions & {
+    replaceMode?: never;
+    expectedSnapshotId?: never;
+});
+export type ReplaceInput = TextReplaceInput | RichContentReplaceInput | SDReplaceInput | NativeOoxmlReplaceInput | SnapshotReplaceInput | ParagraphTextReplaceInput;
 /** Returns true when the input uses the structural SDFragment shape. */
 export declare function isStructuralReplaceInput(input: ReplaceInput): input is SDReplaceInput;
 export declare function isRichContentReplaceInput(input: ReplaceInput): input is RichContentReplaceInput;
-export declare function validateReplaceInput(input: unknown): asserts input is ReplaceInput;
-export declare function executeReplace(selectionAdapter: SelectionMutationAdapter, writeAdapter: WriteAdapter, input: ReplaceInput, options?: RichContentMutationOptions | TextMutationOptions): SDMutationReceipt;
+export declare function validateReplaceInput(input: unknown, options?: ReplaceExecutionOptions): asserts input is ReplaceInput;
+export declare function executeReplace(selectionAdapter: SelectionMutationAdapter, writeAdapter: WriteAdapter, input: ReplaceInput, options?: ReplaceExecutionOptions): SDMutationReceipt;
+export {};

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

@@ -1,4 +1,4 @@
-import { BlockNodeAddress, ReceiptFailure } from '../types/index.js';
+import { BlockNodeAddress, ChangeMode, ReceiptFailure } from '../types/index.js';
 import { DiscoveryOutput } from '../types/discovery.js';
 export type SectionAddress = {
     kind: 'section';
@@ -112,6 +112,8 @@ export type SectionsListResult = DiscoveryOutput<SectionDomain>;
 export interface SectionMutationSuccessResult {
     success: true;
     section: SectionAddress;
+    /** Committed review-aware content mode; omitted for dry runs, no-ops and non-reviewable settings. */
+    appliedChangeMode?: ChangeMode;
 }
 export interface SectionMutationFailureResult {
     success: false;
@@ -128,6 +130,7 @@ export interface DocumentMutationSuccessResult {
 export type DocumentMutationResult = DocumentMutationSuccessResult | SectionMutationFailureResult;
 export interface CreateSectionBreakSuccessResult {
     success: true;
+    appliedChangeMode?: 'direct' | 'tracked';
     section: SectionAddress;
     /**
      * Present only when the break is represented as a dedicated paragraph.

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

@@ -1,12 +1,14 @@
-import { SelectionCurrentInput, SelectionExtractOoxmlInput, SelectionExtractOoxmlResult, SelectionInfo } from './selection.types.js';
-export type { SelectionCurrentInput, SelectionExtractOoxmlInput, SelectionExtractOoxmlResult, SelectionOoxmlDependency, SelectionTableCellsTarget, TableSelectionInfo, SelectionInfo, } from './selection.types.js';
+import { SelectionCurrentInput, SelectionExtractOoxmlInput, SelectionExtractOoxmlResult, SelectionInfo, SelectionReleaseSnapshotInput, SelectionReleaseSnapshotResult, OoxmlContentSource } from './selection.types.js';
+export type { SelectionCurrentInput, SelectionExtractOoxmlInput, SelectionExtractOoxmlResult, SelectionOoxmlDependency, SelectionTableCellsTarget, TableSelectionInfo, SelectionInfo, SelectionReleaseSnapshotInput, SelectionReleaseSnapshotResult, OoxmlContentSource, } from './selection.types.js';
 /**
  * Engine-specific adapter for the selection API.
  */
 export interface SelectionAdapter {
+    readonly supportsRetainedOoxml?: boolean;
     /** Read the editor's current selection. */
     current(input: SelectionCurrentInput): SelectionInfo;
     extractOoxml(input: SelectionExtractOoxmlInput): SelectionExtractOoxmlResult;
+    releaseSnapshot?(input: SelectionReleaseSnapshotInput): SelectionReleaseSnapshotResult;
 }
 /**
  * Public selection API exposed on `editor.doc.selection`.
@@ -22,6 +24,11 @@ export interface SelectionApi {
     current(input?: SelectionCurrentInput): SelectionInfo;
     /** Capture the addressed selected OOXML and its package dependencies. */
     extractOoxml(input: SelectionExtractOoxmlInput): SelectionExtractOoxmlResult;
+    /** Release an exact restoration handle without changing document or history. */
+    releaseSnapshot(input: SelectionReleaseSnapshotInput): SelectionReleaseSnapshotResult;
 }
 export declare function executeSelectionExtractOoxml(adapter: SelectionAdapter, input: SelectionExtractOoxmlInput): SelectionExtractOoxmlResult;
 export declare function executeSelectionCurrent(adapter: SelectionAdapter, input?: SelectionCurrentInput): SelectionInfo;
+export declare function executeSelectionReleaseSnapshot(adapter: SelectionAdapter, input: SelectionReleaseSnapshotInput): SelectionReleaseSnapshotResult;
+export declare function isOoxmlContentSource<T>(input: T): input is T & OoxmlContentSource;
+export declare function validateOoxmlContentSource(input: Record<string, unknown>): void;

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

@@ -1,6 +1,8 @@
 import { SelectionTarget, TextTarget } from '../types/address.js';
 export interface SelectionTableCellsTarget {
     kind: 'tableCells';
+    selectionMode?: 'cells';
+    isRectangular?: true;
     tableId: string;
     start: {
         rowIndex: number;
@@ -12,23 +14,43 @@ export interface SelectionTableCellsTarget {
     };
     story?: SelectionTarget['story'];
 }
-/** Table identity for a caret, rectangular cell selection, or whole-grid selection. */
-export interface TableSelectionInfo extends SelectionTableCellsTarget {
-    /** `cell` includes a caret or text range contained in one cell. */
+/** Table/cell context for the selection; bounds alone are not an editing target. */
+export interface TableSelectionInfo {
+    kind: 'tableCells';
+    tableId: string;
+    story?: SelectionTarget['story'];
+    /** Inclusive logical bounds, including each selected owner's span. */
+    start: {
+        rowIndex: number;
+        columnIndex: number;
+    };
+    end: {
+        rowIndex: number;
+        columnIndex: number;
+    };
+    /** Whole-table identity requires whole-cell selection intent. */
     type: 'table' | 'cell' | 'cells';
-    /** Selected cells in row-major order, using opaque Document API node IDs. */
+    /** Text context preserves exact character targets; cells denotes whole-cell intent. */
+    selectionMode: 'text' | 'cells';
+    /** Whether the exact cells fill the bounding rectangle without holes. */
+    isRectangular: boolean;
+    /** Exact logical owners in row-major order; vertical continuations are deduplicated. */
     cells: {
         nodeId: string;
         rowIndex: number;
         columnIndex: number;
+        rowspan: number;
+        colspan: number;
     }[];
 }
 export type SelectionExtractOoxmlInput = {
     at: SelectionTarget | SelectionTableCellsTarget;
     selection?: never;
+    retain?: boolean;
 } | {
     selection: 'current';
     at?: never;
+    retain?: boolean;
 };
 export interface SelectionOoxmlDependency {
     sourcePartUri: string;
@@ -43,6 +65,8 @@ export interface SelectionOoxmlDependency {
 export interface SelectionExtractOoxmlResult {
     /** Version of the serialized selection-capture manifest. */
     formatVersion: 1;
+    /** Same-session exact restoration handle, present only for retain:true. Release when unused. */
+    snapshotId?: string;
     at: SelectionTarget | SelectionTableCellsTarget;
     /** Source revision for provenance, never a read precondition. */
     evaluatedRevision: string;
@@ -68,6 +92,8 @@ export interface SelectionExtractOoxmlResult {
         story: SelectionTarget['story'] | null;
         partUri: string;
         paragraphStyleId: string | null;
+        /** Exact opaque package coordinate for a retained capture, for pairing with committed review UI. */
+        packageRevision?: string;
     };
     /** Source structure outside the selected visible content needed to interpret it. */
     context: {
@@ -123,6 +149,12 @@ export interface SelectionInfo {
      * full selection.
      */
     target: TextTarget | null;
+    /** Deletion-inclusive multi-block text coverage for range review decisions, when resolvable. */
+    trackedTarget?: TextTarget | null;
+    /** Whether this exact text range supports tracked-change decisions; excludes permissions. */
+    trackedChangeRangeDecisionSupported?: boolean;
+    /** Whether the selection covers every tracked-text fragment of each active change. */
+    trackedChangesWhollySelected?: boolean;
     /**
      * Explicit selection envelope for the current live selection, or `null` when
      * the runtime cannot project one truthfully.
@@ -132,10 +164,11 @@ export interface SelectionInfo {
      */
     selectionTarget?: SelectionTarget | null;
     /**
-     * V2 browser table selection with inclusive, zero-based grid coordinates.
-     * Rectangles in unmerged tables clear `target` and `selectionTarget`.
-     * Rectangles in tables containing merged cells return null and empty text.
-     * A single-cell caret/text range preserves its text targets and `empty` value.
+     * V2 browser cell context with inclusive, zero-based logical bounds.
+     * Whole-cell selections clear text targets. Character selections preserve
+     * their targets and include the containing cells, including endpoint cells.
+     * Exact cell IDs and spans describe merged or nonrectangular selections;
+     * only rectangular whole-cell metadata can become a table-cells target.
      */
     tableSelection?: TableSelectionInfo | null;
     /**
@@ -176,3 +209,19 @@ export interface SelectionInfo {
      */
     text?: string;
 }
+/** Native source shared by insert and replace; portable captures copy with fresh identities. */
+export type OoxmlContentSource = {
+    type: 'ooxml';
+    value: string;
+    namespaces: Record<string, string>;
+    dependencies?: SelectionOoxmlDependency[];
+    sourcePartUri?: string;
+} | {
+    capture: SelectionExtractOoxmlResult;
+};
+export interface SelectionReleaseSnapshotInput {
+    snapshotId: string;
+}
+export interface SelectionReleaseSnapshotResult {
+    released: boolean;
+}

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

@@ -116,6 +116,7 @@ export interface TocRemoveInput {
 }
 export interface TocMutationSuccess {
     success: true;
+    appliedChangeMode?: 'direct' | 'tracked';
     toc: TocAddress;
 }
 export interface TocMutationFailure {
@@ -147,6 +148,7 @@ export interface CreateTableOfContentsInput {
 }
 export interface CreateTableOfContentsSuccess {
     success: true;
+    appliedChangeMode?: 'direct' | 'tracked';
     toc: TocAddress;
 }
 export interface CreateTableOfContentsFailure {
@@ -238,6 +240,7 @@ export interface TocEntryDomain {
 export type TocListEntriesResult = DiscoveryOutput<TocEntryDomain>;
 export interface TocEntryMutationSuccess {
     success: true;
+    appliedChangeMode?: 'direct' | 'tracked';
     entry: TocEntryAddress;
 }
 export interface TocEntryMutationFailure {

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

@@ -1,5 +1,5 @@
 import { BlockNodeType, BlockNodeAddress, DeletableBlockNodeAddress } from './base.js';
-import { AffectedRef, AffectedRefRemapping, Receipt, ReceiptFailure, ReceiptInsert, TextRangeShift } from './receipt.js';
+import { AffectedRef, AffectedRefRemapping, Receipt, ReceiptFailure, ReceiptInsert, ReceiptSuccess, TextRangeShift } from './receipt.js';
 import { StoryLocator } from './story.types.js';
 import { ParagraphNumbering } from './paragraph.types.js';
 import { SDProjectionReviewMode } from './content-projection.js';
@@ -117,6 +117,7 @@ export interface BlocksDeleteInput {
 }
 export interface BlocksDeleteResult {
     success: true;
+    appliedChangeMode?: ReceiptSuccess['appliedChangeMode'];
     deleted: DeletableBlockNodeAddress;
     deletedBlock?: DeletedBlockSummary;
     trackedChangeRefs?: ReceiptInsert[];
@@ -145,6 +146,7 @@ export interface BlocksSplitInput {
 }
 export interface BlocksSplitSuccessResult {
     success: true;
+    appliedChangeMode?: ReceiptSuccess['appliedChangeMode'];
     /** Address of the new paragraph created by the split (the tail). */
     inserted: BlockNodeAddress;
     /**
@@ -173,6 +175,7 @@ export interface BlocksMergeInput {
 }
 export interface BlocksMergeSuccessResult {
     success: true;
+    appliedChangeMode?: ReceiptSuccess['appliedChangeMode'];
     /** Address of the paragraph that was removed (the second paragraph). */
     removed: BlockNodeAddress;
     /**
@@ -208,6 +211,7 @@ export interface BlocksMoveInput {
 }
 export interface BlocksMoveSuccessResult {
     success: true;
+    appliedChangeMode?: ReceiptSuccess['appliedChangeMode'];
     /** Same `source` paragraph, now relocated. */
     moved: BlockNodeAddress;
     remappedRefs?: AffectedRefRemapping[];
@@ -229,6 +233,7 @@ export type BlocksMoveResult = BlocksMoveSuccessResult | BlocksMoveFailureResult
 export type { Receipt };
 export interface BlocksDeleteRangeResult {
     success: true;
+    appliedChangeMode?: ReceiptSuccess['appliedChangeMode'];
     deletedCount: number;
     deletedBlocks: DeletedBlockSummary[];
     revision: {

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

@@ -1,7 +1,7 @@
 import { TextAddress } from './address.js';
 import { BlockNodeAddress } from './base.js';
 import { ResolvedHandle } from './discovery.js';
-import { ReceiptFailure, ReceiptInsert } from './receipt.js';
+import { ReceiptFailure, ReceiptInsert, ReceiptSuccess } from './receipt.js';
 import { StoryLocator } from './story.types.js';
 export type ParagraphCreateLocation = {
     kind: 'documentStart';
@@ -29,6 +29,7 @@ export interface CreateParagraphInput {
 }
 export interface CreateParagraphSuccessResult {
     success: true;
+    appliedChangeMode?: ReceiptSuccess['appliedChangeMode'];
     paragraph: BlockNodeAddress;
     insertionPoint: TextAddress;
     trackedChangeRefs?: ReceiptInsert[];
@@ -95,6 +96,7 @@ export interface CreateHeadingInput {
 }
 export interface CreateHeadingSuccessResult {
     success: true;
+    appliedChangeMode?: ReceiptSuccess['appliedChangeMode'];
     heading: BlockNodeAddress;
     insertionPoint: TextAddress;
     trackedChangeRefs?: ReceiptInsert[];

package/dist/document-api/src/types/mutation-plan.types.d.ts

@@ -233,6 +233,8 @@ export type StructuralStepData = {
 export type StepOutcomeData = TextStepData | AssertStepData | DomainStepData | TableStepData | StructuralStepData;
 export type StepOutcome = {
     stepId: string;
+    /** Effective mode when all committed requests in this step used the same mode. */
+    appliedChangeMode?: ChangeMode;
     op: string;
     effect: StepEffect;
     matchCount: number;
@@ -241,6 +243,8 @@ export type StepOutcome = {
 };
 export type PlanReceipt = {
     success: true;
+    /** Effective mode when every committed step used the same mode. */
+    appliedChangeMode?: ChangeMode;
     revision: {
         before: string;
         after: string;

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

@@ -2,6 +2,7 @@ import { BlockNavigationAddress, EntityAddress, SelectionTarget, TextAddress, Tr
 import { BlockNodeAddress } from './base.js';
 import { BookmarkAddress } from '../bookmarks/bookmarks.types.js';
 import { StoryLocator } from './story.types.js';
+import { ChangeMode } from '../write/write.js';
 export type ReceiptInsert = TrackedChangeAddress;
 export type ReceiptEntity = EntityAddress;
 export type AffectedRef = TextAddress | BookmarkAddress | EntityAddress | BlockNavigationAddress;
@@ -109,6 +110,13 @@ export interface ReceiptEffects {
 }
 export type ReceiptSuccess = {
     success: true;
+    /**
+     * Mode in which this call's document content was committed. An edit folded
+     * into the author's existing insertion is tracked; auxiliary style and
+     * numbering definition writes do not change the content mode. Omitted for
+     * dry runs, no-ops, and operations that do not author reviewable content.
+     */
+    appliedChangeMode?: ChangeMode;
     /**
      * Convenience id for operations that create exactly one primary durable entity.
      * Generic consumers should prefer `inserted`; this field exists for simple