superdoc 2.24.0-next.1 → 2.24.0-next.11

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': {
@@ -40,6 +40,15 @@ export declare const OPERATION_DEFINITIONS: {
         readonly referenceDocPath: "styles/apply.mdx";
         readonly referenceGroup: "styles";
     };
+    readonly 'styles.create': {
+        readonly memberPath: "styles.create";
+        readonly description: "Define or redefine a named paragraph or character style in the Style Definitions part. Replaces the definition rather than merging into it, and decides conflicts on both styleId and name, because Word keys its Styles gallery on the name. Linked style pairs and table/numbering styles are out of scope.";
+        readonly expectedResult: "Returns a StylesCreateReceipt reporting whether the style was created or redefined, with per-channel before/after state for the paragraph and run properties.";
+        readonly requiresDocumentContext: true;
+        readonly metadata: CommandStaticMetadata;
+        readonly referenceDocPath: "styles/create.mdx";
+        readonly referenceGroup: "styles";
+    };
     readonly 'styles.getCatalog': {
         readonly memberPath: "styles.getCatalog";
         readonly description: "List the available styles as a normalized catalogue with stable IDs, display names, type, visibility, priority, provenance, and source diagnostics. Supports view (quickGallery/recommended/currentDocument/all/inUse), type filtering, hidden/latent inclusion, usage rollups, and UI-safe preview tokens. Distinct from DocumentInfo.styles, which is a usage summary.";
@@ -49,6 +58,15 @@ export declare const OPERATION_DEFINITIONS: {
         readonly referenceDocPath: "styles/get-catalog.mdx";
         readonly referenceGroup: "styles";
     };
+    readonly 'styles.getTheme': {
+        readonly memberPath: "styles.getTheme";
+        readonly description: "Read the document theme: its 12 theme colors, major and minor fonts, and the color mapping from settings.xml. A missing or malformed theme part returns the default Office theme labeled source 'fallback', with part status and diagnostics. Same theme as doc.get().theme, without the rest of the document.";
+        readonly expectedResult: "Returns a StylesGetThemeResult with the theme (always present, labeled document or fallback), the theme and settings part status, and diagnostics.";
+        readonly requiresDocumentContext: true;
+        readonly metadata: CommandStaticMetadata;
+        readonly referenceDocPath: "styles/get-theme.mdx";
+        readonly referenceGroup: "styles";
+    };
     readonly 'templates.apply': {
         readonly memberPath: "templates.apply";
         readonly description: "Apply detected DOCX template/substrate (styles, numbering, settings, theme, font table, web settings, headers/footers, section defaults) from a source package onto the current document, preserving body content. Scopes are auto-detected from source package evidence.";
@@ -1031,9 +1049,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 +3608,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 +3635,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";
     };
@@ -3640,7 +3668,7 @@ export declare const OPERATION_DEFINITIONS: {
     readonly get: {
         readonly memberPath: "get";
         readonly description: "Read the full document as an SDDocument structure.";
-        readonly expectedResult: "Returns an SDDocument with body content projected into SDM/1 canonical shapes.";
+        readonly expectedResult: "Returns an SDDocument with body content projected into SDM/1 canonical shapes, plus the document's authored styles, theme (labeled document or fallback), docDefaults, and diagnostics for missing or unreadable style parts.";
         readonly requiresDocumentContext: true;
         readonly metadata: CommandStaticMetadata;
         readonly referenceDocPath: "get.mdx";

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/get/get.d.ts

@@ -14,6 +14,7 @@ export interface GetAdapter {
  *
  * @param adapter - Engine-specific get adapter.
  * @param input - Canonical get input object.
- * @returns An SDDocument with body content projected into SDM/1 canonical shapes.
+ * @returns An SDDocument with body content projected into SDM/1 canonical shapes,
+ *   plus the document's authored styles, theme, docDefaults and diagnostics.
  */
 export declare function executeGet(adapter: GetAdapter, input: SDGetInput): SDDocument;

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

@@ -4,7 +4,7 @@ import { DeleteInput } from './delete/delete.js';
 import { FindAdapter } from './find/find.js';
 import { SDFindInput, SDFindResult, SDGetInput, SDNodeResult } from './types/sd-envelope.js';
 import { FormatApi, FormatRangeInput } from './format/format.js';
-import { StylesAdapter, StylesApi } from './styles/index.js';
+import { StylesAdapter, StylesApi, StylesCreateAdapter, StylesCreateApi } from './styles/index.js';
 import { TemplatesAdapter, TemplatesApi } from './templates/index.js';
 import { GetNodeAdapter, GetNodeByIdInput } from './get-node/get-node.js';
 import { GetAdapter } from './get/get.js';
@@ -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';
@@ -112,8 +112,10 @@ export type { FormatInlineAliasApi, FormatInlineAliasInput, FormatBoldInput, For
 export type { InlineRunPatch, InlineRunPatchKey, InlinePropertyStorage, InlinePropertyType, InlinePropertyCarrier, InlinePropertyRegistryEntry, UnderlinePatch, ShadingPatch, BorderPatch, FitTextPatch, LangPatch, RFontsPatch, EastAsianLayoutPatch, StylisticSetPatch, } from './format/inline-run-patch.js';
 export { INLINE_PROPERTY_REGISTRY, INLINE_PROPERTY_KEY_SET, INLINE_PROPERTY_BY_KEY, INLINE_PROPERTY_KEYS_BY_STORAGE, validateInlineRunPatch, buildInlineRunPatchSchema, } from './format/inline-run-patch.js';
 export { PROPERTY_REGISTRY, EXCLUDED_KEYS, ALLOWED_KEYS_BY_CHANNEL, getPropertyDefinition, toJsonSchema, buildPatchSchema, buildStateSchema, } from './styles/index.js';
-export type { ValueSchema, MergeStrategy, PropertyDefinition, StylesAdapter, StylesApplyInput, StylesApplyRunInput, StylesApplyParagraphInput, StylesApplyOptions, StylesApplyReceipt, StylesBooleanState, StylesNumberState, StylesEnumState, StylesObjectState, StylesArrayState, StylesStateMap, StylesChannel, StylesRunPatch, StylesParagraphPatch, StylesTargetResolution, StylesApplyReceiptSuccess, StylesApplyReceiptFailure, NormalizedStylesApplyOptions, StyleCatalogView, StyleCatalogItemType, StyleCatalogFilterType, StyleProvenance, StyleCatalogDiagnosticSeverity, StyleSourcePartStatus, StyleCatalogUsageStatus, StyleCatalogPreviewStatus, StyleCatalogViewStatus, StyleCatalogItemVisibility, StyleCatalogItemUsage, StyleCatalogItemPreview, StyleCatalogItem, StyleCatalogDefaults, StyleCatalogDiagnostic, StyleCatalogSourceStatus, StylesGetCatalogInput, StylesGetCatalogResult, StylesGetCatalogAdapter, } from './styles/index.js';
-export { STYLE_CATALOG_VIEWS, STYLE_CATALOG_FILTER_TYPES, executeStylesGetCatalog, validateStylesGetCatalogInput, } from './styles/index.js';
+export type { ValueSchema, MergeStrategy, PropertyDefinition, StylesAdapter, StylesApplyInput, StylesApplyRunInput, StylesApplyParagraphInput, StylesApplyOptions, StylesApplyReceipt, StylesBooleanState, StylesNumberState, StylesEnumState, StylesObjectState, StylesArrayState, StylesStateMap, StylesChannel, StylesRunPatch, StylesParagraphPatch, StylesTargetResolution, StylesApplyReceiptSuccess, StylesApplyReceiptFailure, NormalizedStylesApplyOptions, StyleCatalogView, StyleCatalogItemType, StyleCatalogFilterType, StyleProvenance, StyleCatalogDiagnosticSeverity, StyleSourcePartStatus, StyleCatalogUsageStatus, StyleCatalogPreviewStatus, StyleCatalogViewStatus, StyleCatalogItemVisibility, StyleCatalogItemUsage, StyleCatalogItemPreview, StyleCatalogPreviewFontSource, StyleCatalogPreviewColorSource, StyleCatalogPreviewSources, StyleCatalogItem, StyleCatalogDefaults, StyleCatalogDiagnostic, StyleCatalogSourceStatus, StylesGetCatalogInput, StylesGetCatalogResult, StylesGetCatalogAdapter, StylesGetThemeInput, StylesThemeSourceStatus, StylesGetThemeResult, StylesGetThemeAdapter, } from './styles/index.js';
+export { STYLE_CATALOG_VIEWS, STYLE_CATALOG_FILTER_TYPES, executeStylesGetCatalog, validateStylesGetCatalogInput, executeStylesGetTheme, validateStylesGetThemeInput, } from './styles/index.js';
+export type { StylesScope, StyleRunPatch, StyleConflictPolicy, StyleChannelState, StylesCreateAdapter, StylesCreateApi, StylesCreateInput, StylesCreateParagraphInput, StylesCreateCharacterInput, StylesCreateOptions, NormalizedStylesCreateOptions, StylesCreateResolution, StylesCreateReceipt, StylesCreateReceiptSuccess, StylesCreateReceiptFailure, } from './styles/index.js';
+export { STYLE_EXCLUDED_KEYS, EXCLUDED_KEYS_BY_SCOPE, SCOPE_LABEL, STYLE_XML_PATH, executeStylesCreate, validateStylesCreateInput, validateStylesCreateOptions, validatePatchObject, } from './styles/index.js';
 export type { TemplatesAdapter, TemplatesApi, TemplatesApplyInput, TemplatesApplyOptions, TemplatesApplySource, TemplatesApplySourcePath, TemplatesApplySourceBase64, TemplateBodyPolicy, TemplateScope, NormalizedTemplatesApplyOptions, TemplateScopeReport, TemplateSkipReason, TemplateScopeSkip, TemplateUnsupportedItem, TemplateChangeKind, TemplateChangedPart, TemplateIdMapping, TemplateApplyWarning, TemplatesApplySourceInfo, TemplatesApplyReceiptSuccess, TemplatesApplyFailureCode, TemplatesApplyReceiptFailure, TemplatesApplyReceipt, } from './templates/index.js';
 export { executeTemplatesApply } from './templates/index.js';
 export type { CreateAdapter, CreateApi } from './create/create.js';
@@ -175,9 +177,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';
@@ -280,7 +282,8 @@ export interface DocumentApiSurface {
     /**
      * Read the full document as an SDDocument structure.
      * @param input - Get input with optional read options.
-     * @returns An SDDocument with body content projected into SDM/1 canonical shapes.
+     * @returns An SDDocument with body content projected into SDM/1 canonical shapes,
+     *   plus the document's authored styles, theme, docDefaults and diagnostics.
      */
     get(input: SDGetInput): SDDocument;
     /**
@@ -353,7 +356,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.
      */
@@ -373,7 +376,7 @@ export interface DocumentApiSurface {
     /**
      * Stylesheet operations (docDefaults, style definitions, paragraph style references).
      */
-    styles: StylesApi & {
+    styles: StylesApi & StylesCreateApi & {
         paragraph: ParagraphStylesApi;
     };
     /**
@@ -560,7 +563,7 @@ export interface DocumentApiAdapters {
     comments: CommentsAdapter;
     write: WriteAdapter;
     selectionMutation: SelectionMutationAdapter;
-    styles: StylesAdapter;
+    styles: StylesAdapter & Partial<StylesCreateAdapter>;
     templates: TemplatesAdapter;
     trackChanges: TrackChangesAdapter;
     create: CreateAdapter;

package/dist/document-api/src/inline-semantics/token-sets.d.ts

@@ -32,3 +32,14 @@ export declare const ST_THEME_COLOR_VALUES: readonly ["dark1", "light1", "dark2"
 export type StThemeColorValue = (typeof ST_THEME_COLOR_VALUES)[number];
 /** Runtime set for O(1) ST_ThemeColor validation. */
 export declare const ST_THEME_COLOR_VALUE_SET: ReadonlySet<string>;
+/**
+ * Accepted `w:val` values for `w:highlight`. A closed enumeration, unlike a
+ * colour value: anything outside it produces a document Word offers to repair.
+ *
+ * No `StHighlightValue` alias beside it, unlike the sets above:
+ * {@link SDHighlightColor} in `types/sd-props.ts` is already derived from this
+ * list, and a second name for one union is a second thing to keep in step.
+ */
+export declare const ST_HIGHLIGHT_VALUES: readonly ["black", "blue", "cyan", "green", "magenta", "red", "yellow", "white", "darkBlue", "darkCyan", "darkGreen", "darkMagenta", "darkRed", "darkYellow", "darkGray", "lightGray", "none"];
+/** Runtime set for O(1) ST_HighlightColor validation. */
+export declare const ST_HIGHLIGHT_VALUE_SET: ReadonlySet<string>;

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;
+}