superdoc 2.28.0 → 2.29.0-next.13

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

@@ -1,9 +1,9 @@
 import { DocumentApiSurface } from '../index.js';
-import { PlainTextInsertInput } from '../insert/insert.js';
-import { TextReplaceInput } from '../replace/replace.js';
+import { InsertInput } from '../insert/insert.js';
+import { ReplaceInput, TrackedReplaceMutationOptions } from '../replace/replace.js';
 import { BodyStoryLocator } from '../types/story.types.js';
 import { OperationCancellation } from '../write/operation-cancellation.js';
-import { TrackedTextMutationOptions } from '../write/write.js';
+import { TrackedRichContentMutationOptions } from '../write/write.js';
 import { OPERATION_DEFINITIONS } from './operation-definitions.js';
 import { OperationId } from './types.js';
 type ResolveMemberPath<T, Path extends string> = Path extends `${infer Head}.${infer Tail}` ? Head extends keyof T ? ResolveMemberPath<T[Head], Tail> : never : Path extends keyof T ? T[Path] : never;
@@ -32,19 +32,20 @@ type MethodInvokeRequest<T extends OperationId> = OperationRegistry[T]['options'
     input: OperationRegistry[T]['input'];
     options?: OperationRegistry[T]['options'];
 };
-type AttributedTextInvokeRequest<T extends OperationId> = T extends 'insert' ? {
+type AttributedInvokeRequest<T extends OperationId> = T extends 'insert' ? {
     operationId: T;
-    input: PlainTextInsertInput;
-    options: TrackedTextMutationOptions & OperationCancellation;
+    input: InsertInput;
+    options: TrackedRichContentMutationOptions & OperationCancellation;
 } : T extends 'replace' ? {
     operationId: T;
-    input: Exclude<TextReplaceInput, {
+    input: Exclude<ReplaceInput, {
         target: BodyStoryLocator;
+        text: string;
     }>;
-    options: TrackedTextMutationOptions;
+    options: TrackedReplaceMutationOptions;
 } : never;
 /** Typed invoke request narrowed by `operationId` and supported content shape. */
-export type InvokeRequest<T extends OperationId> = MethodInvokeRequest<T> | AttributedTextInvokeRequest<T>;
+export type InvokeRequest<T extends OperationId> = MethodInvokeRequest<T> | AttributedInvokeRequest<T>;
 /** Typed invoke result narrowed by `operationId`. */
 export type InvokeResult<T extends OperationId> = T extends 'mutations.preview' | 'mutations.apply' ? Promise<OperationRegistry[T]['output']> : T extends 'plan.execute' ? OperationRegistry[T]['output'] | Promise<OperationRegistry[T]['output']> : OperationRegistry[T]['output'];
 export type OperationCall<T extends OperationId> = InvokeRequest<T> extends infer Request ? (Request extends unknown ? Omit<Request, 'operationId'> : never) : never;

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

@@ -26,12 +26,12 @@ 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, ReplaceMutationOptions } from './replace/replace.js';
+import { ReplaceInput, ReplaceMutationOptions, TrackedReplaceMutationOptions } 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';
 import { TrackChangesAdapter, TrackChangesApi } from './track-changes/track-changes.js';
-import { MutationOptions, RichContentMutationOptions, TrackedTextMutationOptions, TextMutationOptions, WriteAdapter } from './write/write.js';
+import { MutationOptions, RichContentMutationOptions, TrackedRichContentMutationOptions, TextMutationOptions, WriteAdapter } from './write/write.js';
 import { OperationCancellation } from './write/operation-cancellation.js';
 import { SelectionMutationAdapter } from './selection-mutation.js';
 import { CapabilitiesAdapter, DocumentApiCapabilities, OperationCapabilityResolveInput, OperationCapabilityResolveResult } from './capabilities/capabilities.js';
@@ -109,7 +109,7 @@ export type { GetMarkdownAdapter, GetMarkdownInput } from './get-markdown/get-ma
 export type { GetHtmlAdapter, GetHtmlInput } from './get-html/get-html.js';
 export type { InfoAdapter, InfoInput } from './info/info.js';
 export type { ExtractAdapter, ExtractInput } from './extract/extract.js';
-export type { WriteAdapter, WriteRequest, RichContentMutationOptions, TrackedTextMutationOptions, TextMutationOptions, } from './write/write.js';
+export type { WriteAdapter, WriteRequest, RichContentMutationOptions, TrackedAttribution, TrackedRichContentMutationOptions, TrackedTextMutationOptions, TextMutationOptions, } from './write/write.js';
 export type { OperationCancellation, OperationCancellationCode } from './write/operation-cancellation.js';
 export { OperationCancellationError, assertOperationCanStart, indeterminateOperation, splitOperationCancellation, } from './write/operation-cancellation.js';
 export type { FormatInlineAliasApi, FormatInlineAliasInput, FormatBoldInput, FormatItalicInput, FormatRangeInput, FormatUnderlineInput, FormatStrikethroughInput, StyleApplyInput, StyleApplyOptions, } from './format/format.js';
@@ -185,7 +185,7 @@ export type { MutationReceiptBridgeContext, StructuralReceiptParams } from './re
 export { isBlockNodeAddress } from './validation-primitives.js';
 export type { InsertInput, InsertContentType, TextInsertInput, PlainTextInsertInput, RichContentInsertInput, NativeOoxmlInsertInput, LegacyInsertInput, } from './insert/insert.js';
 export { isStructuralInsertInput } from './insert/insert.js';
-export type { ReplaceInput, TextReplaceInput, TextReplacementGranularity, RichContentReplaceInput, ReplaceMutationOptions, NativeOoxmlReplaceInput, SnapshotReplaceInput, ParagraphTextReplaceInput, } from './replace/replace.js';
+export type { ReplaceInput, TextReplaceInput, TextReplacementGranularity, RichContentReplaceInput, ReplaceMutationOptions, TrackedReplaceMutationOptions, NativeOoxmlReplaceInput, SnapshotReplaceInput, ParagraphTextReplaceInput, } from './replace/replace.js';
 export { executeReplace, isStructuralReplaceInput, isRichContentReplaceInput, TEXT_REPLACEMENT_GRANULARITIES, isTextReplacementGranularity, isSingleParagraphVisibleTextSelection, } from './replace/replace.js';
 export { executeFind } from './find/find.js';
 export { validateDocumentFragment, validateSDFragment } from './validation/fragment-validator.js';
@@ -362,14 +362,15 @@ export interface DocumentApiSurface {
      * Insert content at a target location.
      * If target is omitted, inserts at the end of the document.
      */
-    insert(input: import('./insert/insert.js').PlainTextInsertInput, options: TrackedTextMutationOptions & OperationCancellation): SDMutationReceipt;
+    insert(input: InsertInput, options: TrackedRichContentMutationOptions & OperationCancellation): SDMutationReceipt;
     insert(input: InsertInput, options?: RichContentMutationOptions & OperationCancellation): SDMutationReceipt;
     /**
      * Replace text at a target range.
      */
-    replace(input: Exclude<import('./replace/replace.js').TextReplaceInput, {
+    replace(input: Exclude<ReplaceInput, {
         target: import('./types/story.types.js').BodyStoryLocator;
-    }>, options: TrackedTextMutationOptions): SDMutationReceipt;
+        text: string;
+    }>, options: TrackedReplaceMutationOptions): SDMutationReceipt;
     replace(input: ReplaceInput, options?: ReplaceMutationOptions): SDMutationReceipt;
     /**
      * Delete text at a target range.

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

@@ -1,5 +1,5 @@
 import { OoxmlContentSource } from '../selection/selection.types.js';
-import { RichContentMutationOptions, TextMutationOptions, WriteAdapter } from '../write/write.js';
+import { RichContentMutationOptions, TextMutationOptions, TrackedRichContentMutationOptions, WriteAdapter } from '../write/write.js';
 import { SelectionTarget, TargetLocator, SDMutationReceipt } from '../types/index.js';
 import { SDInsertInput } from '../types/structural-input.js';
 import { StoryLocator } from '../types/story.types.js';
@@ -80,5 +80,5 @@ export declare function validateInsertInput(input: unknown): asserts input is In
  * @param options - Optional mutation options (changeMode, dryRun, expectedRevision).
  * @returns Receipt indicating success/failure and mutation metadata.
  */
-export declare function executeInsert(selectionAdapter: SelectionMutationAdapter, writeAdapter: WriteAdapter, input: InsertInput, options?: (RichContentMutationOptions | TextMutationOptions) & OperationCancellation): SDMutationReceipt;
+export declare function executeInsert(selectionAdapter: SelectionMutationAdapter, writeAdapter: WriteAdapter, input: InsertInput, options?: (RichContentMutationOptions | TrackedRichContentMutationOptions | TextMutationOptions) & OperationCancellation): SDMutationReceipt;
 export {};

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

@@ -1,100 +1,100 @@
-import { MutationOptions } from '../write/write.js';
+import { TextMutationOptions } from '../write/write.js';
 import { ListInsertInput, ListsGetInput, ListsInsertResult, ListsListQuery, ListsListResult, ListsMutateItemResult, ListTargetInput, ListItemInfo, ListsCreateInput, ListsCreateResult, ListsAttachInput, ListsDetachInput, ListsDetachResult, ListsDeleteInput, ListsDeleteResult, ListsJoinInput, ListsJoinResult, ListsCanJoinInput, ListsCanJoinResult, ListsSeparateInput, ListsSeparateResult, ListsMergeInput, ListsMergeResult, ListsSplitInput, ListsSplitResult, ListsSetLevelInput, ListsSetValueInput, ListsContinuePreviousInput, ListsCanContinuePreviousInput, ListsCanContinuePreviousResult, ListsSetLevelRestartInput, ListsConvertToTextInput, ListsConvertToTextResult, ListsApplyTemplateInput, ListsApplyPresetInput, ListsCaptureTemplateInput, ListsCaptureTemplateResult, ListsSetLevelNumberingInput, ListsSetLevelBulletInput, ListsSetLevelPictureBulletInput, ListsSetLevelAlignmentInput, ListsSetLevelIndentsInput, ListsSetLevelTrailingCharacterInput, ListsSetLevelMarkerFontInput, ListsClearLevelOverridesInput, ListsSetTypeInput, ListsGetStyleInput, ListsGetStyleResult, ListsApplyStyleInput, ListsRestartAtInput, ListsSetLevelNumberStyleInput, ListsSetLevelTextInput, ListsSetLevelStartInput, ListsSetLevelLayoutInput, ListsGetStateInput, ListsGetStateResult, ListsApplyInput, ListsContinueV2Input, ListsRestartV2Input, ListsRemoveV2Input } from './lists.types.js';
 export type { ListInsertInput, ListsGetInput, ListsInsertResult, ListsListQuery, ListsListResult, ListsMutateItemResult, ListTargetInput, ListItemInfo, ListsCreateInput, ListsCreateResult, ListsAttachInput, ListsDetachInput, ListsDetachResult, ListsDeleteInput, ListsDeleteResult, ListsJoinInput, ListsJoinResult, ListsCanJoinInput, ListsCanJoinResult, ListsSeparateInput, ListsSeparateResult, ListsMergeInput, ListsMergeResult, ListsSplitInput, ListsSplitResult, ListsSetLevelInput, ListsSetValueInput, ListsContinuePreviousInput, ListsCanContinuePreviousInput, ListsCanContinuePreviousResult, ListsSetLevelRestartInput, ListsConvertToTextInput, ListsConvertToTextResult, ListsApplyTemplateInput, ListsApplyPresetInput, ListsCaptureTemplateInput, ListsCaptureTemplateResult, ListsSetLevelNumberingInput, ListsSetLevelBulletInput, ListsSetLevelPictureBulletInput, ListsSetLevelAlignmentInput, ListsSetLevelIndentsInput, ListsSetLevelTrailingCharacterInput, ListsSetLevelMarkerFontInput, ListsClearLevelOverridesInput, ListsSetTypeInput, ListsGetStyleInput, ListsGetStyleResult, ListsApplyStyleInput, ListsRestartAtInput, ListsSetLevelNumberStyleInput, ListsSetLevelTextInput, ListsSetLevelStartInput, ListsSetLevelLayoutInput, ListsBlockTarget, ListsGetStateInput, ListsGetStateResult, ListsApplyInput, ListsContinueV2Input, ListsRestartV2Input, ListsRemoveV2Input, } from './lists.types.js';
 export interface ListsAdapter {
     list(query?: ListsListQuery): ListsListResult;
     get(input: ListsGetInput): ListItemInfo;
-    insert(input: ListInsertInput, options?: MutationOptions): ListsInsertResult;
-    indent(input: ListTargetInput, options?: MutationOptions): ListsMutateItemResult;
-    outdent(input: ListTargetInput, options?: MutationOptions): ListsMutateItemResult;
-    create(input: ListsCreateInput, options?: MutationOptions): ListsCreateResult;
-    attach(input: ListsAttachInput, options?: MutationOptions): ListsMutateItemResult;
-    detach(input: ListsDetachInput, options?: MutationOptions): ListsDetachResult;
-    delete(input: ListsDeleteInput, options?: MutationOptions): ListsDeleteResult;
-    join(input: ListsJoinInput, options?: MutationOptions): ListsJoinResult;
+    insert(input: ListInsertInput, options?: TextMutationOptions): ListsInsertResult;
+    indent(input: ListTargetInput, options?: TextMutationOptions): ListsMutateItemResult;
+    outdent(input: ListTargetInput, options?: TextMutationOptions): ListsMutateItemResult;
+    create(input: ListsCreateInput, options?: TextMutationOptions): ListsCreateResult;
+    attach(input: ListsAttachInput, options?: TextMutationOptions): ListsMutateItemResult;
+    detach(input: ListsDetachInput, options?: TextMutationOptions): ListsDetachResult;
+    delete(input: ListsDeleteInput, options?: TextMutationOptions): ListsDeleteResult;
+    join(input: ListsJoinInput, options?: TextMutationOptions): ListsJoinResult;
     canJoin(input: ListsCanJoinInput): ListsCanJoinResult;
-    separate(input: ListsSeparateInput, options?: MutationOptions): ListsSeparateResult;
-    merge(input: ListsMergeInput, options?: MutationOptions): ListsMergeResult;
-    split(input: ListsSplitInput, options?: MutationOptions): ListsSplitResult;
-    setLevel(input: ListsSetLevelInput, options?: MutationOptions): ListsMutateItemResult;
-    setValue(input: ListsSetValueInput, options?: MutationOptions): ListsMutateItemResult;
-    continuePrevious(input: ListsContinuePreviousInput, options?: MutationOptions): ListsMutateItemResult;
+    separate(input: ListsSeparateInput, options?: TextMutationOptions): ListsSeparateResult;
+    merge(input: ListsMergeInput, options?: TextMutationOptions): ListsMergeResult;
+    split(input: ListsSplitInput, options?: TextMutationOptions): ListsSplitResult;
+    setLevel(input: ListsSetLevelInput, options?: TextMutationOptions): ListsMutateItemResult;
+    setValue(input: ListsSetValueInput, options?: TextMutationOptions): ListsMutateItemResult;
+    continuePrevious(input: ListsContinuePreviousInput, options?: TextMutationOptions): ListsMutateItemResult;
     canContinuePrevious(input: ListsCanContinuePreviousInput): ListsCanContinuePreviousResult;
-    setLevelRestart(input: ListsSetLevelRestartInput, options?: MutationOptions): ListsMutateItemResult;
-    convertToText(input: ListsConvertToTextInput, options?: MutationOptions): ListsConvertToTextResult;
-    applyTemplate(input: ListsApplyTemplateInput, options?: MutationOptions): ListsMutateItemResult;
-    applyPreset(input: ListsApplyPresetInput, options?: MutationOptions): ListsMutateItemResult;
+    setLevelRestart(input: ListsSetLevelRestartInput, options?: TextMutationOptions): ListsMutateItemResult;
+    convertToText(input: ListsConvertToTextInput, options?: TextMutationOptions): ListsConvertToTextResult;
+    applyTemplate(input: ListsApplyTemplateInput, options?: TextMutationOptions): ListsMutateItemResult;
+    applyPreset(input: ListsApplyPresetInput, options?: TextMutationOptions): ListsMutateItemResult;
     captureTemplate(input: ListsCaptureTemplateInput): ListsCaptureTemplateResult;
-    setLevelNumbering(input: ListsSetLevelNumberingInput, options?: MutationOptions): ListsMutateItemResult;
-    setLevelBullet(input: ListsSetLevelBulletInput, options?: MutationOptions): ListsMutateItemResult;
-    setLevelPictureBullet(input: ListsSetLevelPictureBulletInput, options?: MutationOptions): ListsMutateItemResult;
-    setLevelAlignment(input: ListsSetLevelAlignmentInput, options?: MutationOptions): ListsMutateItemResult;
-    setLevelIndents(input: ListsSetLevelIndentsInput, options?: MutationOptions): ListsMutateItemResult;
-    setLevelTrailingCharacter(input: ListsSetLevelTrailingCharacterInput, options?: MutationOptions): ListsMutateItemResult;
-    setLevelMarkerFont(input: ListsSetLevelMarkerFontInput, options?: MutationOptions): ListsMutateItemResult;
-    clearLevelOverrides(input: ListsClearLevelOverridesInput, options?: MutationOptions): ListsMutateItemResult;
-    setType(input: ListsSetTypeInput, options?: MutationOptions): ListsMutateItemResult;
+    setLevelNumbering(input: ListsSetLevelNumberingInput, options?: TextMutationOptions): ListsMutateItemResult;
+    setLevelBullet(input: ListsSetLevelBulletInput, options?: TextMutationOptions): ListsMutateItemResult;
+    setLevelPictureBullet(input: ListsSetLevelPictureBulletInput, options?: TextMutationOptions): ListsMutateItemResult;
+    setLevelAlignment(input: ListsSetLevelAlignmentInput, options?: TextMutationOptions): ListsMutateItemResult;
+    setLevelIndents(input: ListsSetLevelIndentsInput, options?: TextMutationOptions): ListsMutateItemResult;
+    setLevelTrailingCharacter(input: ListsSetLevelTrailingCharacterInput, options?: TextMutationOptions): ListsMutateItemResult;
+    setLevelMarkerFont(input: ListsSetLevelMarkerFontInput, options?: TextMutationOptions): ListsMutateItemResult;
+    clearLevelOverrides(input: ListsClearLevelOverridesInput, options?: TextMutationOptions): ListsMutateItemResult;
+    setType(input: ListsSetTypeInput, options?: TextMutationOptions): ListsMutateItemResult;
     getStyle(input: ListsGetStyleInput): ListsGetStyleResult;
-    applyStyle(input: ListsApplyStyleInput, options?: MutationOptions): ListsMutateItemResult;
-    restartAt(input: ListsRestartAtInput, options?: MutationOptions): ListsMutateItemResult;
-    setLevelNumberStyle(input: ListsSetLevelNumberStyleInput, options?: MutationOptions): ListsMutateItemResult;
-    setLevelText(input: ListsSetLevelTextInput, options?: MutationOptions): ListsMutateItemResult;
-    setLevelStart(input: ListsSetLevelStartInput, options?: MutationOptions): ListsMutateItemResult;
-    setLevelLayout(input: ListsSetLevelLayoutInput, options?: MutationOptions): ListsMutateItemResult;
+    applyStyle(input: ListsApplyStyleInput, options?: TextMutationOptions): ListsMutateItemResult;
+    restartAt(input: ListsRestartAtInput, options?: TextMutationOptions): ListsMutateItemResult;
+    setLevelNumberStyle(input: ListsSetLevelNumberStyleInput, options?: TextMutationOptions): ListsMutateItemResult;
+    setLevelText(input: ListsSetLevelTextInput, options?: TextMutationOptions): ListsMutateItemResult;
+    setLevelStart(input: ListsSetLevelStartInput, options?: TextMutationOptions): ListsMutateItemResult;
+    setLevelLayout(input: ListsSetLevelLayoutInput, options?: TextMutationOptions): ListsMutateItemResult;
     getState?(input: ListsGetStateInput): ListsGetStateResult;
-    apply?(input: ListsApplyInput, options?: MutationOptions): ListsMutateItemResult;
-    continue?(input: ListsContinueV2Input, options?: MutationOptions): ListsMutateItemResult;
-    restart?(input: ListsRestartV2Input, options?: MutationOptions): ListsMutateItemResult;
-    remove?(input: ListsRemoveV2Input, options?: MutationOptions): ListsMutateItemResult;
+    apply?(input: ListsApplyInput, options?: TextMutationOptions): ListsMutateItemResult;
+    continue?(input: ListsContinueV2Input, options?: TextMutationOptions): ListsMutateItemResult;
+    restart?(input: ListsRestartV2Input, options?: TextMutationOptions): ListsMutateItemResult;
+    remove?(input: ListsRemoveV2Input, options?: TextMutationOptions): ListsMutateItemResult;
 }
 export interface ListsApi extends ListsAdapter {
     getState(input: ListsGetStateInput): ListsGetStateResult;
-    apply(input: ListsApplyInput, options?: MutationOptions): ListsMutateItemResult;
-    continue(input: ListsContinueV2Input, options?: MutationOptions): ListsMutateItemResult;
-    restart(input: ListsRestartV2Input, options?: MutationOptions): ListsMutateItemResult;
-    remove(input: ListsRemoveV2Input, options?: MutationOptions): ListsMutateItemResult;
+    apply(input: ListsApplyInput, options?: TextMutationOptions): ListsMutateItemResult;
+    continue(input: ListsContinueV2Input, options?: TextMutationOptions): ListsMutateItemResult;
+    restart(input: ListsRestartV2Input, options?: TextMutationOptions): ListsMutateItemResult;
+    remove(input: ListsRemoveV2Input, options?: TextMutationOptions): ListsMutateItemResult;
 }
 export declare function executeListsList(adapter: ListsAdapter, query?: ListsListQuery): ListsListResult;
 export declare function executeListsGet(adapter: ListsAdapter, input: ListsGetInput): ListItemInfo;
-export declare function executeListsInsert(adapter: ListsAdapter, input: ListInsertInput, options?: MutationOptions): ListsInsertResult;
-export declare function executeListsIndent(adapter: ListsAdapter, input: ListTargetInput, options?: MutationOptions): ListsMutateItemResult;
-export declare function executeListsOutdent(adapter: ListsAdapter, input: ListTargetInput, options?: MutationOptions): ListsMutateItemResult;
-export declare function executeListsCreate(adapter: ListsAdapter, input: ListsCreateInput, options?: MutationOptions): ListsCreateResult;
-export declare function executeListsAttach(adapter: ListsAdapter, input: ListsAttachInput, options?: MutationOptions): ListsMutateItemResult;
-export declare function executeListsDetach(adapter: ListsAdapter, input: ListsDetachInput, options?: MutationOptions): ListsDetachResult;
-export declare function executeListsDelete(adapter: ListsAdapter, input: ListsDeleteInput, options?: MutationOptions): ListsDeleteResult;
-export declare function executeListsJoin(adapter: ListsAdapter, input: ListsJoinInput, options?: MutationOptions): ListsJoinResult;
+export declare function executeListsInsert(adapter: ListsAdapter, input: ListInsertInput, options?: TextMutationOptions): ListsInsertResult;
+export declare function executeListsIndent(adapter: ListsAdapter, input: ListTargetInput, options?: TextMutationOptions): ListsMutateItemResult;
+export declare function executeListsOutdent(adapter: ListsAdapter, input: ListTargetInput, options?: TextMutationOptions): ListsMutateItemResult;
+export declare function executeListsCreate(adapter: ListsAdapter, input: ListsCreateInput, options?: TextMutationOptions): ListsCreateResult;
+export declare function executeListsAttach(adapter: ListsAdapter, input: ListsAttachInput, options?: TextMutationOptions): ListsMutateItemResult;
+export declare function executeListsDetach(adapter: ListsAdapter, input: ListsDetachInput, options?: TextMutationOptions): ListsDetachResult;
+export declare function executeListsDelete(adapter: ListsAdapter, input: ListsDeleteInput, options?: TextMutationOptions): ListsDeleteResult;
+export declare function executeListsJoin(adapter: ListsAdapter, input: ListsJoinInput, options?: TextMutationOptions): ListsJoinResult;
 export declare function executeListsCanJoin(adapter: ListsAdapter, input: ListsCanJoinInput): ListsCanJoinResult;
-export declare function executeListsSeparate(adapter: ListsAdapter, input: ListsSeparateInput, options?: MutationOptions): ListsSeparateResult;
-export declare function executeListsMerge(adapter: ListsAdapter, input: ListsMergeInput, options?: MutationOptions): ListsMergeResult;
-export declare function executeListsSplit(adapter: ListsAdapter, input: ListsSplitInput, options?: MutationOptions): ListsSplitResult;
-export declare function executeListsSetLevel(adapter: ListsAdapter, input: ListsSetLevelInput, options?: MutationOptions): ListsMutateItemResult;
-export declare function executeListsSetValue(adapter: ListsAdapter, input: ListsSetValueInput, options?: MutationOptions): ListsMutateItemResult;
-export declare function executeListsContinuePrevious(adapter: ListsAdapter, input: ListsContinuePreviousInput, options?: MutationOptions): ListsMutateItemResult;
+export declare function executeListsSeparate(adapter: ListsAdapter, input: ListsSeparateInput, options?: TextMutationOptions): ListsSeparateResult;
+export declare function executeListsMerge(adapter: ListsAdapter, input: ListsMergeInput, options?: TextMutationOptions): ListsMergeResult;
+export declare function executeListsSplit(adapter: ListsAdapter, input: ListsSplitInput, options?: TextMutationOptions): ListsSplitResult;
+export declare function executeListsSetLevel(adapter: ListsAdapter, input: ListsSetLevelInput, options?: TextMutationOptions): ListsMutateItemResult;
+export declare function executeListsSetValue(adapter: ListsAdapter, input: ListsSetValueInput, options?: TextMutationOptions): ListsMutateItemResult;
+export declare function executeListsContinuePrevious(adapter: ListsAdapter, input: ListsContinuePreviousInput, options?: TextMutationOptions): ListsMutateItemResult;
 export declare function executeListsCanContinuePrevious(adapter: ListsAdapter, input: ListsCanContinuePreviousInput): ListsCanContinuePreviousResult;
-export declare function executeListsSetLevelRestart(adapter: ListsAdapter, input: ListsSetLevelRestartInput, options?: MutationOptions): ListsMutateItemResult;
-export declare function executeListsConvertToText(adapter: ListsAdapter, input: ListsConvertToTextInput, options?: MutationOptions): ListsConvertToTextResult;
-export declare function executeListsApplyTemplate(adapter: ListsAdapter, input: ListsApplyTemplateInput, options?: MutationOptions): ListsMutateItemResult;
-export declare function executeListsApplyPreset(adapter: ListsAdapter, input: ListsApplyPresetInput, options?: MutationOptions): ListsMutateItemResult;
+export declare function executeListsSetLevelRestart(adapter: ListsAdapter, input: ListsSetLevelRestartInput, options?: TextMutationOptions): ListsMutateItemResult;
+export declare function executeListsConvertToText(adapter: ListsAdapter, input: ListsConvertToTextInput, options?: TextMutationOptions): ListsConvertToTextResult;
+export declare function executeListsApplyTemplate(adapter: ListsAdapter, input: ListsApplyTemplateInput, options?: TextMutationOptions): ListsMutateItemResult;
+export declare function executeListsApplyPreset(adapter: ListsAdapter, input: ListsApplyPresetInput, options?: TextMutationOptions): ListsMutateItemResult;
 export declare function executeListsCaptureTemplate(adapter: ListsAdapter, input: ListsCaptureTemplateInput): ListsCaptureTemplateResult;
-export declare function executeListsSetLevelNumbering(adapter: ListsAdapter, input: ListsSetLevelNumberingInput, options?: MutationOptions): ListsMutateItemResult;
-export declare function executeListsSetLevelBullet(adapter: ListsAdapter, input: ListsSetLevelBulletInput, options?: MutationOptions): ListsMutateItemResult;
-export declare function executeListsSetLevelPictureBullet(adapter: ListsAdapter, input: ListsSetLevelPictureBulletInput, options?: MutationOptions): ListsMutateItemResult;
-export declare function executeListsSetLevelAlignment(adapter: ListsAdapter, input: ListsSetLevelAlignmentInput, options?: MutationOptions): ListsMutateItemResult;
-export declare function executeListsSetLevelIndents(adapter: ListsAdapter, input: ListsSetLevelIndentsInput, options?: MutationOptions): ListsMutateItemResult;
-export declare function executeListsSetLevelTrailingCharacter(adapter: ListsAdapter, input: ListsSetLevelTrailingCharacterInput, options?: MutationOptions): ListsMutateItemResult;
-export declare function executeListsSetLevelMarkerFont(adapter: ListsAdapter, input: ListsSetLevelMarkerFontInput, options?: MutationOptions): ListsMutateItemResult;
-export declare function executeListsClearLevelOverrides(adapter: ListsAdapter, input: ListsClearLevelOverridesInput, options?: MutationOptions): ListsMutateItemResult;
-export declare function executeListsSetType(adapter: ListsAdapter, input: ListsSetTypeInput, options?: MutationOptions): ListsMutateItemResult;
+export declare function executeListsSetLevelNumbering(adapter: ListsAdapter, input: ListsSetLevelNumberingInput, options?: TextMutationOptions): ListsMutateItemResult;
+export declare function executeListsSetLevelBullet(adapter: ListsAdapter, input: ListsSetLevelBulletInput, options?: TextMutationOptions): ListsMutateItemResult;
+export declare function executeListsSetLevelPictureBullet(adapter: ListsAdapter, input: ListsSetLevelPictureBulletInput, options?: TextMutationOptions): ListsMutateItemResult;
+export declare function executeListsSetLevelAlignment(adapter: ListsAdapter, input: ListsSetLevelAlignmentInput, options?: TextMutationOptions): ListsMutateItemResult;
+export declare function executeListsSetLevelIndents(adapter: ListsAdapter, input: ListsSetLevelIndentsInput, options?: TextMutationOptions): ListsMutateItemResult;
+export declare function executeListsSetLevelTrailingCharacter(adapter: ListsAdapter, input: ListsSetLevelTrailingCharacterInput, options?: TextMutationOptions): ListsMutateItemResult;
+export declare function executeListsSetLevelMarkerFont(adapter: ListsAdapter, input: ListsSetLevelMarkerFontInput, options?: TextMutationOptions): ListsMutateItemResult;
+export declare function executeListsClearLevelOverrides(adapter: ListsAdapter, input: ListsClearLevelOverridesInput, options?: TextMutationOptions): ListsMutateItemResult;
+export declare function executeListsSetType(adapter: ListsAdapter, input: ListsSetTypeInput, options?: TextMutationOptions): ListsMutateItemResult;
 export declare function executeListsGetStyle(adapter: ListsAdapter, input: ListsGetStyleInput): ListsGetStyleResult;
-export declare function executeListsApplyStyle(adapter: ListsAdapter, input: ListsApplyStyleInput, options?: MutationOptions): ListsMutateItemResult;
-export declare function executeListsRestartAt(adapter: ListsAdapter, input: ListsRestartAtInput, options?: MutationOptions): ListsMutateItemResult;
-export declare function executeListsSetLevelNumberStyle(adapter: ListsAdapter, input: ListsSetLevelNumberStyleInput, options?: MutationOptions): ListsMutateItemResult;
-export declare function executeListsSetLevelText(adapter: ListsAdapter, input: ListsSetLevelTextInput, options?: MutationOptions): ListsMutateItemResult;
-export declare function executeListsSetLevelStart(adapter: ListsAdapter, input: ListsSetLevelStartInput, options?: MutationOptions): ListsMutateItemResult;
-export declare function executeListsSetLevelLayout(adapter: ListsAdapter, input: ListsSetLevelLayoutInput, options?: MutationOptions): ListsMutateItemResult;
+export declare function executeListsApplyStyle(adapter: ListsAdapter, input: ListsApplyStyleInput, options?: TextMutationOptions): ListsMutateItemResult;
+export declare function executeListsRestartAt(adapter: ListsAdapter, input: ListsRestartAtInput, options?: TextMutationOptions): ListsMutateItemResult;
+export declare function executeListsSetLevelNumberStyle(adapter: ListsAdapter, input: ListsSetLevelNumberStyleInput, options?: TextMutationOptions): ListsMutateItemResult;
+export declare function executeListsSetLevelText(adapter: ListsAdapter, input: ListsSetLevelTextInput, options?: TextMutationOptions): ListsMutateItemResult;
+export declare function executeListsSetLevelStart(adapter: ListsAdapter, input: ListsSetLevelStartInput, options?: TextMutationOptions): ListsMutateItemResult;
+export declare function executeListsSetLevelLayout(adapter: ListsAdapter, input: ListsSetLevelLayoutInput, options?: TextMutationOptions): ListsMutateItemResult;
 export declare function executeListsGetState(adapter: ListsAdapter, input: ListsGetStateInput): ListsGetStateResult;
-export declare function executeListsApply(adapter: ListsAdapter, input: ListsApplyInput, options?: MutationOptions): ListsMutateItemResult;
-export declare function executeListsContinueV2(adapter: ListsAdapter, input: ListsContinueV2Input, options?: MutationOptions): ListsMutateItemResult;
-export declare function executeListsRestartV2(adapter: ListsAdapter, input: ListsRestartV2Input, options?: MutationOptions): ListsMutateItemResult;
-export declare function executeListsRemoveV2(adapter: ListsAdapter, input: ListsRemoveV2Input, options?: MutationOptions): ListsMutateItemResult;
+export declare function executeListsApply(adapter: ListsAdapter, input: ListsApplyInput, options?: TextMutationOptions): ListsMutateItemResult;
+export declare function executeListsContinueV2(adapter: ListsAdapter, input: ListsContinueV2Input, options?: TextMutationOptions): ListsMutateItemResult;
+export declare function executeListsRestartV2(adapter: ListsAdapter, input: ListsRestartV2Input, options?: TextMutationOptions): ListsMutateItemResult;
+export declare function executeListsRemoveV2(adapter: ListsAdapter, input: ListsRemoveV2Input, options?: TextMutationOptions): ListsMutateItemResult;

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

@@ -1,5 +1,5 @@
 import { OoxmlContentSource } from '../selection/selection.types.js';
-import { RichContentMutationOptions, TextMutationOptions, WriteAdapter } from '../write/write.js';
+import { RichContentMutationOptions, TextMutationOptions, TrackedRichContentMutationOptions, WriteAdapter } from '../write/write.js';
 import { SelectionTarget } from '../types/address.js';
 import { SDMutationReceipt } from '../types/sd-contract.js';
 import { SDReplaceInput } from '../types/structural-input.js';
@@ -81,7 +81,8 @@ export interface ReplaceMutationOptions extends RichContentMutationOptions {
     /** Compare the addressed paragraph with an unchanged retained snapshot before committing. */
     expectedSnapshotId?: string;
 }
-type ReplaceExecutionOptions = ReplaceMutationOptions | (TextMutationOptions & {
+export type TrackedReplaceMutationOptions = TrackedRichContentMutationOptions & Pick<ReplaceMutationOptions, 'replaceMode' | 'expectedSnapshotId'>;
+type ReplaceExecutionOptions = ReplaceMutationOptions | TrackedReplaceMutationOptions | (TextMutationOptions & {
     replaceMode?: never;
     expectedSnapshotId?: never;
 });

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

@@ -1,5 +1,5 @@
 import { MutationOptions } from '../write/write.js';
-import { TablesApplyStyleInput, TablesSetBordersInput, TablesSetCellPaddingInput, TablesSetLayoutInput, TablesSetTableOptionsInput } from '../types/table-operations.types.js';
+import { TablesApplyStyleInput, TablesSetBordersInput, TablesSetCellPaddingInput, TablesSetLayoutInput, TablesSetTableOptionsInput, TablesSortInput } from '../types/table-operations.types.js';
 type RowLocatorInput = {
     target?: unknown;
     nodeId?: unknown;
@@ -52,6 +52,7 @@ export declare function executeTableLocatorOp<TInput extends {
     nodeId?: unknown;
 }, TResult>(operationName: string, adapter: (input: TInput, options?: MutationOptions) => TResult, input: TInput, options?: MutationOptions): TResult;
 export declare function executeTablesSetLayoutOp<TResult>(adapter: (input: TablesSetLayoutInput, options?: MutationOptions) => TResult, input: TablesSetLayoutInput, options?: MutationOptions): TResult;
+export declare function executeTablesSortOp<TResult>(adapter: (input: TablesSortInput, options?: MutationOptions) => TResult, input: TablesSortInput, options?: MutationOptions): TResult;
 export declare function executeRowLocatorOp<TInput extends RowLocatorInput, TResult>(operationName: string, adapter: (input: TInput, options?: MutationOptions) => TResult, input: TInput, options?: MutationOptions, rowLocatorOptions?: RowLocatorOptions): TResult;
 export declare function executeCellOrTableScopedCellLocatorOp<TInput extends CellOrTableScopedCellLocatorInput, TResult>(operationName: string, adapter: (input: TInput, options?: MutationOptions) => TResult, input: TInput, options?: MutationOptions): TResult;
 /**

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

@@ -17,6 +17,7 @@ export type Range = {
 export type TextCoordinateSpace = 'visible' | 'tracked';
 export type TextAddress = {
     kind: 'text';
+    captureState?: string;
     blockId: string;
     range: Range;
     /** Story containing this text. Omit for body (backward compatible). */
@@ -47,6 +48,7 @@ export type TextSegment = {
  */
 export type TextTarget = {
     kind: 'text';
+    captureState?: string;
     segments: [TextSegment, ...TextSegment[]];
     /** Story containing this text target. Omit for body (backward compatible). */
     story?: StoryLocator;
@@ -93,6 +95,7 @@ export type SelectionPoint = {
  */
 export type SelectionTarget = {
     kind: 'selection';
+    captureState?: string;
     start: SelectionPoint;
     end: SelectionPoint;
     /** Story containing this selection. Omit for body (backward compatible). */

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

@@ -364,6 +364,7 @@ export interface TablesSortKey {
 }
 export interface TablesSortInput extends TableLocator {
     keys: [TablesSortKey, ...TablesSortKey[]];
+    skipHeaderRows?: number;
 }
 export interface TablesSetAltTextInput extends TableLocator {
     title?: string;

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

@@ -1,7 +1,7 @@
 import { DocumentApiSurface } from '../index.js';
 import { ReceiptEntity, ReceiptFailureResult, ReceiptSuccess } from './receipt.js';
 import { PlainTextInsertInput } from '../insert/insert.js';
-import { ParagraphTextReplaceInput, ReplaceMutationOptions, TextReplaceInput } from '../replace/replace.js';
+import { ParagraphTextReplaceInput, ReplaceMutationOptions, TextReplaceInput, TrackedReplaceMutationOptions } from '../replace/replace.js';
 import { MutationOptions, TrackedTextMutationOptions } from '../write/write.js';
 import { BodyStoryLocator } from './story.types.js';
 type TemporaryCall<Name extends string, Method extends (...args: never[]) => unknown> = {
@@ -37,6 +37,10 @@ export type TemporaryMutationOperation = {
     operation: 'replace';
     input: ParagraphTextReplaceInput;
     options?: ReplaceMutationOptions;
+} | {
+    operation: 'replace';
+    input: ParagraphTextReplaceInput;
+    options: TrackedReplaceMutationOptions;
 } | TemporaryCall<'delete', DocumentApiSurface['delete']> | TemporaryCall<'blocks.delete', DocumentApiSurface['blocks']['delete']> | TemporaryCall<'trackChanges.decide', DocumentApiSurface['trackChanges']['decide']> | {
     operation: 'comments.create';
     input: TemporaryCommentInput;

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

@@ -1,6 +1,6 @@
 import { TextMutationReceipt, SDMutationReceipt } from '../types/index.js';
 import { InsertInput } from '../insert/insert.js';
-import { ReplaceMutationOptions, ReplaceInput } from '../replace/replace.js';
+import { ReplaceMutationOptions, ReplaceInput, TrackedReplaceMutationOptions } from '../replace/replace.js';
 import { StoryLocator } from '../types/story.types.js';
 import { SDHtmlMarkdownCheckGuard } from '../capabilities/html-markdown-support.js';
 export type ChangeMode = 'direct' | 'tracked';
@@ -42,23 +42,30 @@ export interface MutationOptions extends RevisionGuardOptions {
      */
     dryRun?: boolean;
 }
+/** Display-only attribution for one tracked mutation. */
+export interface TrackedAttribution {
+    author?: {
+        name: string;
+    };
+    /** ISO 8601 UTC revision timestamp. Omitted values use the transaction time. */
+    date?: string;
+}
 export interface RichContentMutationOptions extends MutationOptions {
     author?: never;
     date?: never;
     /** Guard returned by `doc.capabilities.check` for an exact rich write. */
     supportCheck?: SDHtmlMarkdownCheckGuard;
 }
-/** Display-only attribution for one tracked plain-text or inline-format mutation. */
-export interface TrackedTextMutationOptions extends MutationOptions {
+export interface TrackedTextMutationOptions extends MutationOptions, TrackedAttribution {
     changeMode: 'tracked';
-    author?: {
-        name: string;
-    };
-    /** ISO 8601 UTC revision timestamp. Omitted values use the transaction time. */
-    date?: string;
 }
-export type TextMutationOptions = MutationOptions | TrackedTextMutationOptions;
+export type TrackedRichContentMutationOptions = TrackedTextMutationOptions & Pick<RichContentMutationOptions, 'supportCheck'>;
+export type TextMutationOptions = (MutationOptions & {
+    author?: never;
+    date?: never;
+}) | TrackedTextMutationOptions;
 export declare function normalizeTextMutationOptions(options?: RichContentMutationOptions | TextMutationOptions): RichContentMutationOptions | TrackedTextMutationOptions;
+export declare function normalizeRichMutationOptions(options: (MutationOptions & TrackedAttribution & Pick<RichContentMutationOptions, 'supportCheck'>) | undefined, supportCheckOperation?: 'insert' | 'replace'): RichContentMutationOptions | TrackedRichContentMutationOptions;
 /**
  * Text insertion request: target-less insert at document end.
  *
@@ -86,9 +93,9 @@ export interface WriteAdapter {
     readonly supportsNativeOoxml?: boolean;
     write(request: InsertWriteRequest, options?: TextMutationOptions): TextMutationReceipt;
     /** Structured insert for SDFragment or markdown/html content. Returns SDMutationReceipt. */
-    insertStructured(input: InsertInput, options?: RichContentMutationOptions): SDMutationReceipt;
+    insertStructured(input: InsertInput, options?: RichContentMutationOptions | TrackedRichContentMutationOptions): SDMutationReceipt;
     /** Structured replace for SDFragment or markdown/html content. Returns SDMutationReceipt. */
-    replaceStructured(input: ReplaceInput, options?: ReplaceMutationOptions): SDMutationReceipt;
+    replaceStructured(input: ReplaceInput, options?: ReplaceMutationOptions | TrackedReplaceMutationOptions): SDMutationReceipt;
 }
 export declare function normalizeMutationOptions(options?: MutationOptions | RichContentMutationOptions, supportCheckOperation?: 'insert' | 'replace'): RichContentMutationOptions;
 export declare function executeWrite(adapter: WriteAdapter, request: InsertWriteRequest, options?: TextMutationOptions): TextMutationReceipt;

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

@@ -2976,7 +2976,7 @@ export declare const extractHeaderFooterSpace: (margins?: PageMargins | null) =>
 export type { ResolvedLayout, ResolvedPage, ResolvedPaintItem, ResolvedGroupItem, ResolvedFragmentItem, ResolvedParagraphContent, ResolvedTextLineItem, ResolvedDropCapItem, ResolvedListMarkerItem, ResolvedTableItem, ResolvedImageItem, ResolvedDrawingItem, ResolvedHeaderFooterPage, ResolvedHeaderFooterLayout, } from './resolved-layout.js';
 export { isResolvedTableItem, isResolvedImageItem, isResolvedDrawingItem } from './resolved-layout.js';
 export { PAGE_BREAK_DELETION_ANCHOR_ATTR, DELETED_PAGE_BREAK_LABEL, isPageBreakDeletionAnchorRun, expandRunsForInlineNewlines, isBodyNoteReferenceRun, isZeroWidthMarkerRun, isGeneratedFieldResultRun, hasZeroWidthMarkerSpan, isNoteLabelRun, isNumberedNoteMarkerRun, isEmptyInlineSdtPlaceholderRun, isEmptySdtPlaceholderRun, NOTE_LABEL_MARKER_ATTR, NOTE_REFERENCE_MARKER_ATTR, sliceRunsForLine, usesPositionedTextGeometry, } from './run-helpers.js';
-export { INLINE_OBJECT_REPLACEMENT_CHARACTER, flattenParagraphVisibleText, mapVisibleRangeToRunSlices, type ParagraphVisibleRunSlice, } from './paragraph-visible-text.js';
+export { runVisibleLength, splitsSurrogatePair, INLINE_OBJECT_REPLACEMENT_CHARACTER, flattenParagraphVisibleText, mapVisibleRangeToRunSlices, type ParagraphVisibleRunSlice, } from './paragraph-visible-text.js';
 export { inlineBoxStyleSignature, isFiniteNonNegativeInteger, normalizeInlineBoxLogicalSides, type InlineBoxLogicalSides, type ResolvedInlineBoxLogicalSides, } from './inline-box.js';
 export { INCREMENTAL_DEPENDENCY_CERTIFICATE_CLASSES, PAGE_CHECKPOINT_DEPENDENCY_CLASSES, areValidPageCheckpointDependencyClasses, isValidIncrementalDependencyOwnerVersion, isValidNonFlowingPageRelativeAnchorDependencyProof, isValidPageCheckpointDependencyCertificate, type IncrementalDependencyCertificateClass, type IncrementalDependencyOwnerVersion, type NonFlowingPageRelativeAnchorDependencyProof, type PageCheckpointDependencyCertificate, type PageCheckpointDependencyClass, } from './incremental-dependency.js';
 export * as Engines from './engines/index.js';

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

@@ -1,10 +1,12 @@
-import { ParagraphBlock } from './index.js';
+import { ParagraphBlock, Run } from './index.js';
 export declare const INLINE_OBJECT_REPLACEMENT_CHARACTER = "\uFFFC";
 export type ParagraphVisibleRunSlice = {
     runIndex: number;
     fromChar: number;
     toChar: number;
 };
+export declare const runVisibleLength: (run: Run) => number;
+export declare const splitsSurrogatePair: (text: string, offset: number) => boolean;
 /**
  * Flattens a paragraph into Document API visible-text coordinates.
  *

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

@@ -5,7 +5,7 @@ import { BetweenBorderInfo } from './paragraph/borders/index.js';
 import { PageStyles } from './styles.js';
 import { TableFragmentPatchResult } from './table/renderTableFragment.js';
 import { DerivedRunTextPlane } from './derived-run-text-plane.js';
-export declare function refreshPageBreakReviewPlacements(state: PageDomState, page: ResolvedPage, recordChangedRoot?: (root: HTMLElement) => void): void;
+export declare function refreshPageBreakReviewPlacements(state: PageDomState, page: ResolvedPage, recordChangedRoot?: (root: HTMLElement) => void, beforePlacementChange?: () => void): void;
 export type FragmentDomState = {
     key: string;
     signature: string;

package/dist/layout-engine/painters/dom/src/persistent-page-surface.d.ts

@@ -72,6 +72,8 @@ export type DomPainterPersistentPageInput = {
     documentBackground?: DocumentBackground | null;
     derivedRunTextPlane?: DerivedRunTextPlane | null;
     captureSnapshot?: boolean;
+    beforePageContentChange?: (pageIndex: number) => void;
+    onPageContentRetained?: (pageIndex: number) => void;
 };
 /** Shell registry entry: the persistent page root and its geometry/style reuse key. */
 export type PersistentShellEntry = {

package/dist/public/ui-react.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-BfgYblyI.cjs");
+const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-_SbygYQ4.cjs");
 const require_slice_source = require("../chunks/slice-source-CFaqq0Vo.cjs");
 let react = require("react");
 let use_sync_external_store_shim = require("use-sync-external-store/shim");

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

@@ -1,4 +1,4 @@
-import { t as createSuperDocUI } from "../chunks/create-super-doc-ui-BbjHD1ul.es.js";
+import { t as createSuperDocUI } from "../chunks/create-super-doc-ui-DdT4b29f.es.js";
 import { t as toSliceSource } from "../chunks/slice-source-gfOhG2MW.es.js";
 import { createContext, createElement, useCallback, useContext, useEffect, useRef, useState } from "react";
 import { useSyncExternalStore } from "use-sync-external-store/shim";

package/dist/public/ui-vue.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-BfgYblyI.cjs");
+const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-_SbygYQ4.cjs");
 const require_slice_source = require("../chunks/slice-source-CFaqq0Vo.cjs");
 let superdoc_entry_vue = require("vue");
 //#region src/public/ui/vue.ts

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

@@ -1,4 +1,4 @@
-import { t as createSuperDocUI } from "../chunks/create-super-doc-ui-BbjHD1ul.es.js";
+import { t as createSuperDocUI } from "../chunks/create-super-doc-ui-DdT4b29f.es.js";
 import { t as toSliceSource } from "../chunks/slice-source-gfOhG2MW.es.js";
 import { computed, inject, onScopeDispose, provide, shallowRef, toRaw, toValue, watch } from "vue";
 //#region src/public/ui/vue.ts

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-BfgYblyI.cjs");
+const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-_SbygYQ4.cjs");
 //#region ../document-api/src/types/receipt.ts
 /** Read a known failure.details.reason without assuming every failure has one. */
 function getDocumentApiRejectionReason(details) {

package/dist/public/ui.es.js

@@ -1,4 +1,4 @@
-import { m as shallowEqual, s as BUILT_IN_COMMAND_IDS, t as createSuperDocUI } from "../chunks/create-super-doc-ui-BbjHD1ul.es.js";
+import { m as shallowEqual, s as BUILT_IN_COMMAND_IDS, t as createSuperDocUI } from "../chunks/create-super-doc-ui-DdT4b29f.es.js";
 //#region ../document-api/src/types/receipt.ts
 /** Read a known failure.details.reason without assuming every failure has one. */
 function getDocumentApiRejectionReason(details) {