superdoc 2.29.0-next.3 → 2.29.0-next.9

package/dist/chunks/{create-super-doc-ui-BFt8agAI.es.js → create-super-doc-ui-Bm5kmx0W.es.js}

@@ -1079,6 +1079,11 @@ var decodeLayoutStoryDataset = (raw) => {
 `${DOM_CLASS_NAMES.BLOCK_SDT}${DATA_ATTRS.SDT_ID}`;
 `${DATA_ATTRS.DRAGGABLE}`;
 //#endregion
+//#region src/helpers/object-guards.ts
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
 //#region src/helpers/tracked-change-comment-lane.ts
 var TRACKED_CHANGE_COMMENT_LANE_ID_PREFIX = "tc-comment:";
 function isSyntheticTrackedChangeCommentLaneItem(item) {
@@ -1088,16 +1093,7 @@ function isSyntheticTrackedChangeCommentLaneItem(item) {
 	return typeof itemId === "string" && itemId.startsWith(TRACKED_CHANGE_COMMENT_LANE_ID_PREFIX);
 }
 //#endregion
-//#region src/helpers/object-guards.js
-/**
-* @param {unknown} value
-* @returns {value is Record<string, unknown>}
-*/
-function isPlainObject(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-//#endregion
-//#region src/core/collaboration/permissions.js
+//#region src/core/collaboration/permissions.ts
 var PERMISSIONS = Object.freeze({
 	RESOLVE_OWN: "RESOLVE_OWN",
 	RESOLVE_OTHER: "RESOLVE_OTHER",
@@ -1160,15 +1156,16 @@ var PERMISSION_MATRIX = Object.freeze({
 var pickResolver = (context = {}) => {
 	if (typeof context.permissionResolver === "function") return context.permissionResolver;
 	if (typeof context.superdoc?.config?.permissionResolver === "function") return context.superdoc.config.permissionResolver;
-	const deprecatedResolver = context.superdoc?.config?.modules?.comments?.permissionResolver;
+	const comments = context.superdoc?.config?.modules?.comments;
+	const deprecatedResolver = comments ? comments.permissionResolver : void 0;
 	if (typeof deprecatedResolver === "function") return deprecatedResolver;
 	return null;
 };
 var BUILT_IN_PERMISSION_METHOD = Symbol.for("superdoc.internal.permission-method.builtin");
 var BUILT_IN_PERMISSION_RESOLVER = Symbol.for("superdoc.internal.permission-resolver.builtin");
-/** Create the shell's internal, live tracked-change permission shim. */
+var hasBuiltInPermissionMethodBrand = (method) => (typeof method === "object" && method !== null || typeof method === "function") && Reflect.get(method, BUILT_IN_PERMISSION_METHOD) === true;
 var createTrackedChangePermissionResolver = (superdoc) => {
-	const isBuiltInPolicy = () => superdoc.canPerformPermission?.[BUILT_IN_PERMISSION_METHOD] === true && pickResolver({ superdoc }) === null;
+	const isBuiltInPolicy = () => hasBuiltInPermissionMethodBrand(superdoc.canPerformPermission) && pickResolver({ superdoc }) === null;
 	const resolver = (payload = {}) => isBuiltInPolicy() ? defaultDecisionFor(payload.permission, superdoc.config.role, superdoc.config.isInternal) : superdoc.canPerformPermission({
 		...payload,
 		role: superdoc.config.role,
@@ -1178,6 +1175,7 @@ var createTrackedChangePermissionResolver = (superdoc) => {
 	return resolver;
 };
 var defaultDecisionFor = (permission, role, isInternal) => {
+	if (permission === void 0 || typeof role !== "string") return false;
 	const internalExternal = isInternal ? "internal" : "external";
 	return PERMISSION_MATRIX[permission]?.[internalExternal]?.includes(role) ?? false;
 };
@@ -1222,21 +1220,6 @@ var readBuiltInTrackedChangePermissionDecision = (superdoc, canPerform, permissi
 		return null;
 	}
 };
-/**
-* Resolve a client-side permission through the built-in matrix and optional
-* resolver.
-*
-* @param {string} permission The permission to check
-* @param {string | undefined} role The role to check
-* @param {boolean | undefined} isInternal The internal/external flag
-* @param {object} [context] Context passed to the permission resolver
-* @param {object | null} [context.comment] The comment/tracked change being evaluated
-* @param {object | null} [context.superdoc] The SuperDoc instance
-* @param {object | null} [context.currentUser] The active user object performing the action
-* @param {Function} [context.permissionResolver] Explicit resolver override
-* @param {object | null} [context.trackedChange] Tracked change metadata (for tracked-change permissions)
-* @returns {boolean} Whether the permission is allowed
-*/
 var isAllowed = (permission, role, isInternal, context = {}) => {
 	const defaultDecision = defaultDecisionFor(permission, role, isInternal);
 	const resolver = pickResolver(context);
@@ -15876,4 +15859,4 @@ function commandIsActive(descriptor, selection) {
 	return descriptor.activeMark ? selection.activeMarks.includes(descriptor.activeMark) : false;
 }
 //#endregion
-export { getWorkflowRecording as C, createInteractionHistory as S, recordInteraction as T, isAllowed as _, registerFirstPartyCommandMutation as a, DOM_CLASS_NAMES as b, getCommandDescriptor as c, mutationCommittedEventChangedDocument as d, createImageFilePicker as f, createTrackedChangePermissionResolver as g, PERMISSIONS as h, readFirstPartyPageNumbers as i, applyV2CommentInvalidationFromMutation as l, shallowEqual as m, executeFirstPartyCommandAsync as n, isRecord as o, resolveImageSrc as p, executeFirstPartyShortcutAsync as r, BUILT_IN_COMMAND_IDS as s, createSuperDocUI as t, getV2TrackedChangeMutationImpact as u, isPlainObject as v, isWorkflowRecordingEnabled as w, closeInteractionHistory as x, isSyntheticTrackedChangeCommentLaneItem as y };
+export { createInteractionHistory as C, recordInteraction as E, closeInteractionHistory as S, isWorkflowRecordingEnabled as T, createTrackedChangePermissionResolver as _, registerFirstPartyCommandMutation as a, isPlainObject as b, getCommandDescriptor as c, mutationCommittedEventChangedDocument as d, createImageFilePicker as f, PERMISSIONS as g, BUILT_IN_PERMISSION_METHOD as h, readFirstPartyPageNumbers as i, applyV2CommentInvalidationFromMutation as l, shallowEqual as m, executeFirstPartyCommandAsync as n, isRecord as o, resolveImageSrc as p, executeFirstPartyShortcutAsync as r, BUILT_IN_COMMAND_IDS as s, createSuperDocUI as t, getV2TrackedChangeMutationImpact as u, isAllowed as v, getWorkflowRecording as w, DOM_CLASS_NAMES as x, isSyntheticTrackedChangeCommentLaneItem as y };

package/dist/chunks/{create-super-doc-ui-BAGOnYGM.cjs → create-super-doc-ui-DN70aatf.cjs}

@@ -1079,6 +1079,11 @@ var decodeLayoutStoryDataset = (raw) => {
 `${DOM_CLASS_NAMES.BLOCK_SDT}${DATA_ATTRS.SDT_ID}`;
 `${DATA_ATTRS.DRAGGABLE}`;
 //#endregion
+//#region src/helpers/object-guards.ts
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
 //#region src/helpers/tracked-change-comment-lane.ts
 var TRACKED_CHANGE_COMMENT_LANE_ID_PREFIX = "tc-comment:";
 function isSyntheticTrackedChangeCommentLaneItem(item) {
@@ -1088,16 +1093,7 @@ function isSyntheticTrackedChangeCommentLaneItem(item) {
 	return typeof itemId === "string" && itemId.startsWith(TRACKED_CHANGE_COMMENT_LANE_ID_PREFIX);
 }
 //#endregion
-//#region src/helpers/object-guards.js
-/**
-* @param {unknown} value
-* @returns {value is Record<string, unknown>}
-*/
-function isPlainObject(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-//#endregion
-//#region src/core/collaboration/permissions.js
+//#region src/core/collaboration/permissions.ts
 var PERMISSIONS = Object.freeze({
 	RESOLVE_OWN: "RESOLVE_OWN",
 	RESOLVE_OTHER: "RESOLVE_OTHER",
@@ -1160,15 +1156,16 @@ var PERMISSION_MATRIX = Object.freeze({
 var pickResolver = (context = {}) => {
 	if (typeof context.permissionResolver === "function") return context.permissionResolver;
 	if (typeof context.superdoc?.config?.permissionResolver === "function") return context.superdoc.config.permissionResolver;
-	const deprecatedResolver = context.superdoc?.config?.modules?.comments?.permissionResolver;
+	const comments = context.superdoc?.config?.modules?.comments;
+	const deprecatedResolver = comments ? comments.permissionResolver : void 0;
 	if (typeof deprecatedResolver === "function") return deprecatedResolver;
 	return null;
 };
 var BUILT_IN_PERMISSION_METHOD = Symbol.for("superdoc.internal.permission-method.builtin");
 var BUILT_IN_PERMISSION_RESOLVER = Symbol.for("superdoc.internal.permission-resolver.builtin");
-/** Create the shell's internal, live tracked-change permission shim. */
+var hasBuiltInPermissionMethodBrand = (method) => (typeof method === "object" && method !== null || typeof method === "function") && Reflect.get(method, BUILT_IN_PERMISSION_METHOD) === true;
 var createTrackedChangePermissionResolver = (superdoc) => {
-	const isBuiltInPolicy = () => superdoc.canPerformPermission?.[BUILT_IN_PERMISSION_METHOD] === true && pickResolver({ superdoc }) === null;
+	const isBuiltInPolicy = () => hasBuiltInPermissionMethodBrand(superdoc.canPerformPermission) && pickResolver({ superdoc }) === null;
 	const resolver = (payload = {}) => isBuiltInPolicy() ? defaultDecisionFor(payload.permission, superdoc.config.role, superdoc.config.isInternal) : superdoc.canPerformPermission({
 		...payload,
 		role: superdoc.config.role,
@@ -1178,6 +1175,7 @@ var createTrackedChangePermissionResolver = (superdoc) => {
 	return resolver;
 };
 var defaultDecisionFor = (permission, role, isInternal) => {
+	if (permission === void 0 || typeof role !== "string") return false;
 	const internalExternal = isInternal ? "internal" : "external";
 	return PERMISSION_MATRIX[permission]?.[internalExternal]?.includes(role) ?? false;
 };
@@ -1222,21 +1220,6 @@ var readBuiltInTrackedChangePermissionDecision = (superdoc, canPerform, permissi
 		return null;
 	}
 };
-/**
-* Resolve a client-side permission through the built-in matrix and optional
-* resolver.
-*
-* @param {string} permission The permission to check
-* @param {string | undefined} role The role to check
-* @param {boolean | undefined} isInternal The internal/external flag
-* @param {object} [context] Context passed to the permission resolver
-* @param {object | null} [context.comment] The comment/tracked change being evaluated
-* @param {object | null} [context.superdoc] The SuperDoc instance
-* @param {object | null} [context.currentUser] The active user object performing the action
-* @param {Function} [context.permissionResolver] Explicit resolver override
-* @param {object | null} [context.trackedChange] Tracked change metadata (for tracked-change permissions)
-* @returns {boolean} Whether the permission is allowed
-*/
 var isAllowed = (permission, role, isInternal, context = {}) => {
 	const defaultDecision = defaultDecisionFor(permission, role, isInternal);
 	const resolver = pickResolver(context);
@@ -15883,6 +15866,12 @@ Object.defineProperty(exports, "BUILT_IN_COMMAND_IDS", {
 		return BUILT_IN_COMMAND_IDS;
 	}
 });
+Object.defineProperty(exports, "BUILT_IN_PERMISSION_METHOD", {
+	enumerable: true,
+	get: function() {
+		return BUILT_IN_PERMISSION_METHOD;
+	}
+});
 Object.defineProperty(exports, "DOM_CLASS_NAMES", {
 	enumerable: true,
 	get: function() {

package/dist/collaboration-upgrade-engine.cjs

@@ -19,7 +19,7 @@ var COLLABORATION_UPGRADE_ENGINE_MINIMUM_NODE_MAJOR = 20;
 var PRIVATE_ENGINE_INFO = (0, _superdoc_docx_engine_collaboration_upgrade_engine.getCollaborationUpgradeEngineInfo)();
 var ENGINE_INFO = Object.freeze({
 	...PRIVATE_ENGINE_INFO,
-	superdocVersion: "2.29.0-next.3",
+	superdocVersion: "2.29.0-next.9",
 	roomSchemaVersion: Object.freeze({ ...PRIVATE_ENGINE_INFO.roomSchemaVersion }),
 	supportedBundleVersions: SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS,
 	supportedV1ReaderContractVersions: SUPPORTED_V1_READER_CONTRACT_VERSIONS

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

@@ -18,7 +18,7 @@ var COLLABORATION_UPGRADE_ENGINE_MINIMUM_NODE_MAJOR = 20;
 var PRIVATE_ENGINE_INFO = getCollaborationUpgradeEngineInfo$1();
 var ENGINE_INFO = Object.freeze({
 	...PRIVATE_ENGINE_INFO,
-	superdocVersion: "2.29.0-next.3",
+	superdocVersion: "2.29.0-next.9",
 	roomSchemaVersion: Object.freeze({ ...PRIVATE_ENGINE_INFO.roomSchemaVersion }),
 	supportedBundleVersions: SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS,
 	supportedV1ReaderContractVersions: SUPPORTED_V1_READER_CONTRACT_VERSIONS

package/dist/document-api/src/capabilities/html-markdown-support.d.ts

@@ -1,6 +1,6 @@
 import { RichContentInsertInput } from '../insert/insert.js';
-import { RichContentReplaceInput, ReplaceMutationOptions } from '../replace/replace.js';
-import { ChangeMode, TrackedAttribution } from '../write/write.js';
+import { RichContentReplaceInput, ReplaceMutationOptions, TrackedReplaceMutationOptions } from '../replace/replace.js';
+import { ChangeMode, RichContentMutationOptions, TrackedRichContentMutationOptions } from '../write/write.js';
 import { ProjectHtmlInput, ProjectMarkdownInput, SDContentProjectionResult, SDProjectionReviewMode, SDResolvedProjectionScope } from '../types/content-projection.js';
 import { SDFragment } from '../types/fragment.js';
 import { SDError, SDHtmlMarkdownOutcome, SDMutationConversionReport, SDMutationReceipt } from '../types/sd-contract.js';
@@ -15,13 +15,11 @@ export interface SDHtmlMarkdownCheckGuard {
 export type SDHtmlMarkdownSupportCheckInput = {
     operation: 'insert';
     input: RichContentInsertInput;
-    options?: {
-        changeMode?: ChangeMode;
-    } & TrackedAttribution;
+    options?: Pick<RichContentMutationOptions, 'changeMode' | 'author' | 'date'> | Pick<TrackedRichContentMutationOptions, 'changeMode' | 'author' | 'date'>;
 } | {
     operation: 'replace';
     input: RichContentReplaceInput;
-    options?: Pick<ReplaceMutationOptions, 'changeMode' | 'replaceMode' | 'expectedSnapshotId'> & TrackedAttribution;
+    options?: Pick<ReplaceMutationOptions, 'changeMode' | 'replaceMode' | 'expectedSnapshotId' | 'author' | 'date'> | Pick<TrackedReplaceMutationOptions, 'changeMode' | 'replaceMode' | 'expectedSnapshotId' | 'author' | 'date'>;
 } | {
     operation: 'projectHtml';
     input?: ProjectHtmlInput;

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

@@ -25,6 +25,7 @@ export interface AddCommentInput extends CommentCreateAttributionInput {
     target?: CommentTarget;
     /** The comment body text. */
     text: string;
+    expectedText?: string;
 }
 export interface EditCommentInput {
     commentId: string;
@@ -114,6 +115,7 @@ export interface CommentsCreateInput extends CommentCreateAttributionInput {
      * both when they contain the same value.
      */
     parentId?: string;
+    expectedText?: string;
 }
 /**
  * Input for `comments.patch`: field-level patch on an existing comment.

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

@@ -933,8 +933,8 @@ export declare const OPERATION_DEFINITIONS: {
     };
     readonly 'comments.create': {
         readonly memberPath: "comments.create";
-        readonly description: "Create a new comment thread (or reply when parentCommentId is given). Accepts TextAddress / TextTarget anchors, or a TrackedChangeCommentTarget that names a logical tracked-change id. The tracked-change target accepts both the explicit kind form and the Labs-compatible trackedChangeId-only form; the adapter normalizes it to a Word-compatible content anchor on the requested revision side. Callers may supply a durable externalId, or use the v1-compatible caller-supplied commentId alias, plus author fields and arbitrary JSON metadata for integration correlation. The caller-owned id remains distinct from the generated Word-compatible commentId.";
-        readonly expectedResult: "Returns a Receipt with the new commentId in `id` and `inserted` on success; rejects whitespace-only bodies, unsupported anchor contexts, and cross-story targets. Tracked-change comment targets support insertion, deletion, replacement, and paired-move revisions; they fail with `TARGET_NOT_FOUND` for stale ids, `CAPABILITY_UNAVAILABLE` for formatting / structural revisions and unpaired move sides, and `INVALID_TARGET` for incompatible side requests or ambiguous replacement targets that omit a required `side`.";
+        readonly description: "Create a new comment thread (or reply when parentCommentId is given). Accepts TextAddress / TextTarget anchors, or a TrackedChangeCommentTarget that names a logical tracked-change id. The tracked-change target accepts both the explicit kind form and the Labs-compatible trackedChangeId-only form; the adapter normalizes it to a Word-compatible content anchor on the requested revision side. Callers may supply a durable externalId, or use the v1-compatible caller-supplied commentId alias, plus author fields and arbitrary JSON metadata for integration correlation. The caller-owned id remains distinct from the generated Word-compatible commentId. Pass expectedText with a single-paragraph text target to refuse the comment when the text at that target has changed since it was selected.";
+        readonly expectedResult: "Returns a Receipt with the new commentId in `id` and `inserted` on success; rejects whitespace-only bodies, unsupported anchor contexts, and cross-story targets. When expectedText is given and the target text differs, fails with `PRECONDITION_FAILED` before any change. Tracked-change comment targets support insertion, deletion, replacement, and paired-move revisions; they fail with `TARGET_NOT_FOUND` for stale ids, `CAPABILITY_UNAVAILABLE` for formatting / structural revisions and unpaired move sides, and `INVALID_TARGET` for incompatible side requests or ambiguous replacement targets that omit a required `side`.";
         readonly requiresDocumentContext: true;
         readonly metadata: CommandStaticMetadata;
         readonly referenceDocPath: "comments/create.mdx";

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, TrackedAttribution, 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/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/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/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';
@@ -50,16 +50,22 @@ export interface TrackedAttribution {
     /** ISO 8601 UTC revision timestamp. Omitted values use the transaction time. */
     date?: string;
 }
-export interface RichContentMutationOptions extends MutationOptions, TrackedAttribution {
+export interface RichContentMutationOptions extends MutationOptions {
+    author?: never;
+    date?: never;
     /** Guard returned by `doc.capabilities.check` for an exact rich write. */
     supportCheck?: SDHtmlMarkdownCheckGuard;
 }
 export interface TrackedTextMutationOptions extends MutationOptions, TrackedAttribution {
     changeMode: 'tracked';
 }
-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 & Partial<RichContentMutationOptions>) | undefined, supportCheckOperation?: 'insert' | 'replace'): RichContentMutationOptions;
+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.
  *
@@ -87,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/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-BAGOnYGM.cjs");
+const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-DN70aatf.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-BFt8agAI.es.js";
+import { t as createSuperDocUI } from "../chunks/create-super-doc-ui-Bm5kmx0W.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-BAGOnYGM.cjs");
+const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-DN70aatf.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-BFt8agAI.es.js";
+import { t as createSuperDocUI } from "../chunks/create-super-doc-ui-Bm5kmx0W.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-BAGOnYGM.cjs");
+const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-DN70aatf.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-BFt8agAI.es.js";
+import { m as shallowEqual, s as BUILT_IN_COMMAND_IDS, t as createSuperDocUI } from "../chunks/create-super-doc-ui-Bm5kmx0W.es.js";
 //#region ../document-api/src/types/receipt.ts
 /** Read a known failure.details.reason without assuming every failure has one. */
 function getDocumentApiRejectionReason(details) {