@superdoc-dev/cli 0.3.0-next.55 → 0.3.0-next.56

package/dist/index.js

@@ -1433,8 +1433,8 @@ var init_operation_definitions = __esm(() => {
     },
     insert: {
       memberPath: "insert",
-      description: "Insert content into the document. Two input shapes: " + "legacy string-based (value + type) inserts inline content at a text position within an existing block; " + "structural SDFragment (content) inserts one or more blocks as siblings relative to a BlockNodeAddress target. " + "When target is omitted, content appends at the end of the document. " + "Legacy mode supports text (default), markdown, and html content types via the `type` field. " + "Structural mode uses `placement` (before/after/insideStart/insideEnd) to position relative to the target block.",
-      expectedResult: "Returns an SDMutationReceipt with applied status; resolution reports a TextAddress for legacy text insertion or a BlockNodeAddress for structural insertion. Receipt reports NO_OP if the insertion point is invalid or content is empty.",
+      description: "Insert content into the document. Two input shapes: " + "text-based (value + type) inserts inline content at a SelectionTarget or ref position within an existing block; " + "structural SDFragment (content) inserts one or more blocks as siblings relative to a BlockNodeAddress target. " + "When target/ref is omitted, content appends at the end of the document. " + "Text mode supports text (default), markdown, and html content types via the `type` field. " + "Structural mode uses `placement` (before/after/insideStart/insideEnd) to position relative to the target block.",
+      expectedResult: "Returns an SDMutationReceipt with applied status; resolution reports the inserted TextAddress for text insertion or a BlockNodeAddress for structural insertion. Receipt reports NO_OP if the insertion point is invalid or content is empty.",
       requiresDocumentContext: true,
       metadata: mutationOperation({
         idempotency: "non-idempotent",
@@ -7329,6 +7329,27 @@ function targetLocatorWithPayload(payloadProperties, payloadRequired = []) {
     ]
   };
 }
+function optionalTargetLocatorWithPayload(payloadProperties, payloadRequired = []) {
+  return {
+    oneOf: [
+      objectSchema({
+        target: {
+          ...ref("SelectionTarget"),
+          description: "Selection target: {kind:'selection', start:{kind:'text', blockId, offset}, end:{kind:'text', blockId, offset}}."
+        },
+        ...payloadProperties
+      }, ["target", ...payloadRequired]),
+      objectSchema({
+        ref: {
+          type: "string",
+          description: "Handle ref string returned by a prior search/query result."
+        },
+        ...payloadProperties
+      }, ["ref", ...payloadRequired]),
+      objectSchema({ ...payloadProperties }, [...payloadRequired])
+    ]
+  };
+}
 function imagesMutationSchemaSet(inputSchema) {
   return {
     input: inputSchema,
@@ -8693,12 +8714,8 @@ var init_schemas = __esm(() => {
   };
   insertInputSchema = {
     oneOf: [
-      objectSchema({
+      optionalTargetLocatorWithPayload({
         in: storyLocatorSchema,
-        target: {
-          ...textAddressSchema,
-          description: "Insertion point: {kind:'text', blockId:'...', range:{start, end}}."
-        },
         value: { type: "string", description: "Text content to insert." },
         type: {
           type: "string",
@@ -13082,8 +13099,8 @@ function validateTargetLocator(input, operation) {
       value: input.target
     });
   }
-  if (hasRef && typeof input.ref !== "string") {
-    throw new DocumentApiValidationError("INVALID_TARGET", "ref must be a string.", {
+  if (hasRef && (typeof input.ref !== "string" || input.ref === "")) {
+    throw new DocumentApiValidationError("INVALID_TARGET", "ref must be a non-empty string.", {
       field: "ref",
       value: input.ref
     });
@@ -13103,13 +13120,8 @@ function validateStyleApplyInput(input) {
 }
 function executeStyleApply(adapter, input, options) {
   validateStyleApplyInput(input);
-  return adapter.execute({
-    kind: "format",
-    target: input.target,
-    ref: input.ref,
-    inline: input.inline,
-    in: input.in
-  }, normalizeMutationOptions(options));
+  const request = input.target ? { kind: "format", target: input.target, inline: input.inline, in: input.in } : { kind: "format", ref: input.ref, inline: input.inline, in: input.in };
+  return adapter.execute(request, normalizeMutationOptions(options));
 }
 function acceptsImplicitTrue(key) {
   return INLINE_PROPERTY_BY_KEY[key].type === "boolean" || key === "underline";
@@ -13134,13 +13146,8 @@ function executeInlineAlias(adapter, key, input, options) {
   const value = normalizeInlineAliasValue(key, input.value);
   const inline = { [key]: value };
   validateInlineRunPatch(inline);
-  return adapter.execute({
-    kind: "format",
-    target: input.target,
-    ref: input.ref,
-    inline,
-    in: input.in
-  }, normalizeMutationOptions(options));
+  const request = input.target ? { kind: "format", target: input.target, inline, in: input.in } : { kind: "format", ref: input.ref, inline, in: input.in };
+  return adapter.execute(request, normalizeMutationOptions(options));
 }
 var STYLE_APPLY_INPUT_ALLOWED_KEYS, INLINE_ALIAS_INPUT_ALLOWED_KEYS;
 var init_format = __esm(() => {
@@ -13215,8 +13222,8 @@ function validateDeleteInput(input) {
       value: target
     });
   }
-  if (hasRef && typeof ref2 !== "string") {
-    throw new DocumentApiValidationError("INVALID_TARGET", "ref must be a string.", {
+  if (hasRef && (typeof ref2 !== "string" || ref2 === "")) {
+    throw new DocumentApiValidationError("INVALID_TARGET", "ref must be a non-empty string.", {
       field: "ref",
       value: ref2
     });
@@ -13227,13 +13234,8 @@ function validateDeleteInput(input) {
 }
 function executeDelete(adapter, input, options) {
   validateDeleteInput(input);
-  return adapter.execute({
-    kind: "delete",
-    target: input.target,
-    ref: input.ref,
-    behavior: input.behavior ?? "selection",
-    in: input.in
-  }, normalizeMutationOptions(options));
+  const request = input.target ? { kind: "delete", target: input.target, behavior: input.behavior ?? "selection", in: input.in } : { kind: "delete", ref: input.ref, behavior: input.behavior ?? "selection", in: input.in };
+  return adapter.execute(request, normalizeMutationOptions(options));
 }
 var DELETE_INPUT_ALLOWED_KEYS, VALID_BEHAVIORS;
 var init_delete = __esm(() => {
@@ -13811,33 +13813,42 @@ function validateInsertInput(input) {
   const hasValue = "value" in input && input.value !== undefined;
   const hasContent = "content" in input && input.content !== undefined;
   if (hasValue && hasContent) {
-    throw new DocumentApiValidationError("INVALID_INPUT", 'Insert input must provide either "value" (legacy) or "content" (structural), not both.', { fields: ["value", "content"] });
+    throw new DocumentApiValidationError("INVALID_INPUT", 'Insert input must provide either "value" (text) or "content" (structural), not both.', { fields: ["value", "content"] });
   }
   if (!hasValue && !hasContent) {
-    throw new DocumentApiValidationError("INVALID_INPUT", 'Insert input must provide either "value" (legacy string) or "content" (SDFragment).', { fields: ["value", "content"] });
+    throw new DocumentApiValidationError("INVALID_INPUT", 'Insert input must provide either "value" (text string) or "content" (SDFragment).', { fields: ["value", "content"] });
   }
   validateStoryLocator(input.in, "in");
   if (hasContent) {
     validateStructuralInsertInput(input);
   } else {
-    validateLegacyInsertInput(input);
+    validateTextInsertInput(input);
   }
 }
-function validateLegacyInsertInput(input) {
+function validateTextInsertInput(input) {
   if ("placement" in input && input.placement !== undefined) {
     throw new DocumentApiValidationError("INVALID_INPUT", '"placement" is only valid with structural content input, not with "value".', { field: "placement" });
   }
   if ("nestingPolicy" in input && input.nestingPolicy !== undefined) {
     throw new DocumentApiValidationError("INVALID_INPUT", '"nestingPolicy" is only valid with structural content input, not with "value".', { field: "nestingPolicy" });
   }
-  assertNoUnknownFields(input, LEGACY_INSERT_ALLOWED_KEYS, "insert");
-  const { target, value, type } = input;
-  if (target !== undefined && !isTextAddress(target)) {
-    throw new DocumentApiValidationError("INVALID_TARGET", "target must be a text address object.", {
+  assertNoUnknownFields(input, TEXT_INSERT_ALLOWED_KEYS, "insert");
+  const { target, ref: ref2, value, type } = input;
+  if (target !== undefined && ref2 !== undefined) {
+    throw new DocumentApiValidationError("INVALID_INPUT", 'Insert input must provide either "target" or "ref", not both.', { fields: ["target", "ref"] });
+  }
+  if (target !== undefined && !isSelectionTarget(target)) {
+    throw new DocumentApiValidationError("INVALID_TARGET", "target must be a SelectionTarget object.", {
       field: "target",
       value: target
     });
   }
+  if (ref2 !== undefined && (typeof ref2 !== "string" || ref2 === "")) {
+    throw new DocumentApiValidationError("INVALID_TARGET", "ref must be a non-empty string.", {
+      field: "ref",
+      value: ref2
+    });
+  }
   if (typeof value !== "string") {
     throw new DocumentApiValidationError("INVALID_TARGET", `value must be a string, got ${typeof value}.`, {
       field: "value",
@@ -13866,29 +13877,35 @@ function validateStructuralInsertInput(input) {
   validateNestingPolicyValue(nestingPolicy);
   validateDocumentFragment(content);
 }
-function executeInsert(adapter, input, options) {
+function executeInsert(selectionAdapter, writeAdapter, input, options) {
   validateInsertInput(input);
   if (isStructuralInsertInput(input)) {
-    return adapter.insertStructured(input, normalizeMutationOptions(options));
+    return writeAdapter.insertStructured(input, normalizeMutationOptions(options));
   }
-  const { target, value } = input;
+  const { target, ref: ref2, value } = input;
   const contentType = input.type ?? "text";
   if (contentType !== "text") {
-    return adapter.insertStructured(input, normalizeMutationOptions(options));
+    return writeAdapter.insertStructured(input, normalizeMutationOptions(options));
   }
   const storyIn = input.in;
-  const request = target ? { kind: "insert", target, text: value, ...storyIn ? { in: storyIn } : undefined } : { kind: "insert", text: value, ...storyIn ? { in: storyIn } : undefined };
-  const textReceipt = executeWrite(adapter, request, options);
+  if (target || ref2) {
+    const request2 = target ? { kind: "insert", target, text: value, ...storyIn ? { in: storyIn } : {} } : { kind: "insert", ref: ref2, text: value, ...storyIn ? { in: storyIn } : {} };
+    const textReceipt2 = selectionAdapter.execute(request2, normalizeMutationOptions(options));
+    return textReceiptToSDReceipt(textReceipt2);
+  }
+  const request = { kind: "insert", text: value, ...storyIn ? { in: storyIn } : {} };
+  const textReceipt = executeWrite(writeAdapter, request, options);
   return textReceiptToSDReceipt(textReceipt);
 }
-var LEGACY_INSERT_ALLOWED_KEYS, STRUCTURAL_INSERT_ALLOWED_KEYS, VALID_INSERT_TYPES;
+var TEXT_INSERT_ALLOWED_KEYS, STRUCTURAL_INSERT_ALLOWED_KEYS, VALID_INSERT_TYPES;
 var init_insert = __esm(() => {
   init_placement();
   init_errors2();
   init_validation_primitives();
+  init_selection_target_validator();
   init_fragment_validator();
   init_story_validator();
-  LEGACY_INSERT_ALLOWED_KEYS = new Set(["value", "type", "target", "in"]);
+  TEXT_INSERT_ALLOWED_KEYS = new Set(["value", "type", "target", "ref", "in"]);
   STRUCTURAL_INSERT_ALLOWED_KEYS = new Set(["content", "target", "placement", "nestingPolicy", "in"]);
   VALID_INSERT_TYPES = new Set(["text", "markdown", "html"]);
 });
@@ -14065,8 +14082,8 @@ function validateTargetLocator2(input, operation) {
       value: input.target
     });
   }
-  if (hasRef && typeof input.ref !== "string") {
-    throw new DocumentApiValidationError("INVALID_TARGET", "ref must be a string.", {
+  if (hasRef && (typeof input.ref !== "string" || input.ref === "")) {
+    throw new DocumentApiValidationError("INVALID_TARGET", "ref must be a non-empty string.", {
       field: "ref",
       value: input.ref
     });
@@ -14140,13 +14157,8 @@ function executeReplace(selectionAdapter, writeAdapter, input, options) {
     return writeAdapter.replaceStructured(input, normalizeMutationOptions(options));
   }
   const textInput = input;
-  const textReceipt = selectionAdapter.execute({
-    kind: "replace",
-    target: textInput.target,
-    ref: textInput.ref,
-    text: textInput.text,
-    in: textInput.in
-  }, normalizeMutationOptions(options));
+  const request = textInput.target ? { kind: "replace", target: textInput.target, text: textInput.text, in: textInput.in } : { kind: "replace", ref: textInput.ref, text: textInput.text, in: textInput.in };
+  const textReceipt = selectionAdapter.execute(request, normalizeMutationOptions(options));
   return textReceiptToSDReceipt(textReceipt);
 }
 var TEXT_REPLACE_ALLOWED_KEYS, STRUCTURAL_REPLACE_ALLOWED_KEYS;
@@ -16664,7 +16676,7 @@ function createDocumentApi(adapters) {
       }
     },
     insert(input, options) {
-      return executeInsert(adapters.write, input, options);
+      return executeInsert(adapters.selectionMutation, adapters.write, input, options);
     },
     replace(input, options) {
       return executeReplace(adapters.selectionMutation, adapters.write, input, options);
@@ -40060,7 +40072,7 @@ var init_remark_gfm_z_sDF4ss_es = __esm(() => {
   emptyOptions2 = {};
 });
 
-// ../../packages/superdoc/dist/chunks/SuperConverter-Cukh7tk8.es.js
+// ../../packages/superdoc/dist/chunks/SuperConverter-C65zRR3r.es.js
 function getExtensionConfigField(extension$1, field, context = { name: "" }) {
   const fieldValue = extension$1.config[field];
   if (typeof fieldValue === "function")
@@ -41859,6 +41871,25 @@ function targetLocatorWithPayload2(payloadProperties, payloadRequired = []) {
     ...payloadProperties
   }, ["ref", ...payloadRequired])] };
 }
+function optionalTargetLocatorWithPayload2(payloadProperties, payloadRequired = []) {
+  return { oneOf: [
+    objectSchema2({
+      target: {
+        ...ref2("SelectionTarget"),
+        description: "Selection target: {kind:'selection', start:{kind:'text', blockId, offset}, end:{kind:'text', blockId, offset}}."
+      },
+      ...payloadProperties
+    }, ["target", ...payloadRequired]),
+    objectSchema2({
+      ref: {
+        type: "string",
+        description: "Handle ref string returned by a prior search/query result."
+      },
+      ...payloadProperties
+    }, ["ref", ...payloadRequired]),
+    objectSchema2({ ...payloadProperties }, [...payloadRequired])
+  ] };
+}
 function imagesMutationSchemaSet2(inputSchema) {
   return {
     input: inputSchema,
@@ -42810,8 +42841,8 @@ function validateTargetLocator$1(input, operation) {
       field: "target",
       value: input.target
     });
-  if (hasRef && typeof input.ref !== "string")
-    throw new DocumentApiValidationError2("INVALID_TARGET", "ref must be a string.", {
+  if (hasRef && (typeof input.ref !== "string" || input.ref === ""))
+    throw new DocumentApiValidationError2("INVALID_TARGET", "ref must be a non-empty string.", {
       field: "ref",
       value: input.ref
     });
@@ -42828,13 +42859,18 @@ function validateStyleApplyInput2(input) {
 }
 function executeStyleApply2(adapter, input, options) {
   validateStyleApplyInput2(input);
-  return adapter.execute({
+  const request = input.target ? {
     kind: "format",
     target: input.target,
+    inline: input.inline,
+    in: input.in
+  } : {
+    kind: "format",
     ref: input.ref,
     inline: input.inline,
     in: input.in
-  }, normalizeMutationOptions2(options));
+  };
+  return adapter.execute(request, normalizeMutationOptions2(options));
 }
 function acceptsImplicitTrue2(key) {
   return INLINE_PROPERTY_BY_KEY2[key].type === "boolean" || key === "underline";
@@ -42858,13 +42894,18 @@ function executeInlineAlias2(adapter, key, input, options) {
   const value = normalizeInlineAliasValue2(key, input.value);
   const inline = { [key]: value };
   validateInlineRunPatch2(inline);
-  return adapter.execute({
+  const request = input.target ? {
     kind: "format",
     target: input.target,
+    inline,
+    in: input.in
+  } : {
+    kind: "format",
     ref: input.ref,
     inline,
     in: input.in
-  }, normalizeMutationOptions2(options));
+  };
+  return adapter.execute(request, normalizeMutationOptions2(options));
 }
 function executeGetNode2(adapter, address2) {
   return adapter.getNode(address2);
@@ -42907,8 +42948,8 @@ function validateDeleteInput2(input) {
       field: "target",
       value: target
     });
-  if (hasRef && typeof ref$1 !== "string")
-    throw new DocumentApiValidationError2("INVALID_TARGET", "ref must be a string.", {
+  if (hasRef && (typeof ref$1 !== "string" || ref$1 === ""))
+    throw new DocumentApiValidationError2("INVALID_TARGET", "ref must be a non-empty string.", {
       field: "ref",
       value: ref$1
     });
@@ -42920,13 +42961,18 @@ function validateDeleteInput2(input) {
 }
 function executeDelete$1(adapter, input, options) {
   validateDeleteInput2(input);
-  return adapter.execute({
+  const request = input.target ? {
     kind: "delete",
     target: input.target,
+    behavior: input.behavior ?? "selection",
+    in: input.in
+  } : {
+    kind: "delete",
     ref: input.ref,
     behavior: input.behavior ?? "selection",
     in: input.in
-  }, normalizeMutationOptions2(options));
+  };
+  return adapter.execute(request, normalizeMutationOptions2(options));
 }
 function validateSDFragment2(fragment2) {
   const nodes = normalizeToNodeArray2(fragment2, "INVALID_PAYLOAD");
@@ -43405,27 +43451,34 @@ function validateInsertInput2(input) {
   const hasValue = "value" in input && input.value !== undefined;
   const hasContent = "content" in input && input.content !== undefined;
   if (hasValue && hasContent)
-    throw new DocumentApiValidationError2("INVALID_INPUT", 'Insert input must provide either "value" (legacy) or "content" (structural), not both.', { fields: ["value", "content"] });
+    throw new DocumentApiValidationError2("INVALID_INPUT", 'Insert input must provide either "value" (text) or "content" (structural), not both.', { fields: ["value", "content"] });
   if (!hasValue && !hasContent)
-    throw new DocumentApiValidationError2("INVALID_INPUT", 'Insert input must provide either "value" (legacy string) or "content" (SDFragment).', { fields: ["value", "content"] });
+    throw new DocumentApiValidationError2("INVALID_INPUT", 'Insert input must provide either "value" (text string) or "content" (SDFragment).', { fields: ["value", "content"] });
   validateStoryLocator2(input.in, "in");
   if (hasContent)
     validateStructuralInsertInput2(input);
   else
-    validateLegacyInsertInput2(input);
+    validateTextInsertInput2(input);
 }
-function validateLegacyInsertInput2(input) {
+function validateTextInsertInput2(input) {
   if ("placement" in input && input.placement !== undefined)
     throw new DocumentApiValidationError2("INVALID_INPUT", '"placement" is only valid with structural content input, not with "value".', { field: "placement" });
   if ("nestingPolicy" in input && input.nestingPolicy !== undefined)
     throw new DocumentApiValidationError2("INVALID_INPUT", '"nestingPolicy" is only valid with structural content input, not with "value".', { field: "nestingPolicy" });
-  assertNoUnknownFields3(input, LEGACY_INSERT_ALLOWED_KEYS2, "insert");
-  const { target, value, type } = input;
-  if (target !== undefined && !isTextAddress2(target))
-    throw new DocumentApiValidationError2("INVALID_TARGET", "target must be a text address object.", {
+  assertNoUnknownFields3(input, TEXT_INSERT_ALLOWED_KEYS2, "insert");
+  const { target, ref: ref$1, value, type } = input;
+  if (target !== undefined && ref$1 !== undefined)
+    throw new DocumentApiValidationError2("INVALID_INPUT", 'Insert input must provide either "target" or "ref", not both.', { fields: ["target", "ref"] });
+  if (target !== undefined && !isSelectionTarget2(target))
+    throw new DocumentApiValidationError2("INVALID_TARGET", "target must be a SelectionTarget object.", {
       field: "target",
       value: target
     });
+  if (ref$1 !== undefined && (typeof ref$1 !== "string" || ref$1 === ""))
+    throw new DocumentApiValidationError2("INVALID_TARGET", "ref must be a non-empty string.", {
+      field: "ref",
+      value: ref$1
+    });
   if (typeof value !== "string")
     throw new DocumentApiValidationError2("INVALID_TARGET", `value must be a string, got ${typeof value}.`, {
       field: "value",
@@ -43455,23 +43508,32 @@ function validateStructuralInsertInput2(input) {
   validateNestingPolicyValue2(nestingPolicy);
   validateDocumentFragment2(content$2);
 }
-function executeInsert2(adapter, input, options) {
+function executeInsert2(selectionAdapter, writeAdapter, input, options) {
   validateInsertInput2(input);
   if (isStructuralInsertInput2(input))
-    return adapter.insertStructured(input, normalizeMutationOptions2(options));
-  const { target, value } = input;
+    return writeAdapter.insertStructured(input, normalizeMutationOptions2(options));
+  const { target, ref: ref$1, value } = input;
   if ((input.type ?? "text") !== "text")
-    return adapter.insertStructured(input, normalizeMutationOptions2(options));
+    return writeAdapter.insertStructured(input, normalizeMutationOptions2(options));
   const storyIn = input.in;
-  return textReceiptToSDReceipt2(executeWrite2(adapter, target ? {
-    kind: "insert",
-    target,
-    text: value,
-    ...storyIn ? { in: storyIn } : undefined
-  } : {
+  if (target || ref$1) {
+    const request = target ? {
+      kind: "insert",
+      target,
+      text: value,
+      ...storyIn ? { in: storyIn } : {}
+    } : {
+      kind: "insert",
+      ref: ref$1,
+      text: value,
+      ...storyIn ? { in: storyIn } : {}
+    };
+    return textReceiptToSDReceipt2(selectionAdapter.execute(request, normalizeMutationOptions2(options)));
+  }
+  return textReceiptToSDReceipt2(executeWrite2(writeAdapter, {
     kind: "insert",
     text: value,
-    ...storyIn ? { in: storyIn } : undefined
+    ...storyIn ? { in: storyIn } : {}
   }, options));
 }
 function validateListTarget2(input, operationName) {
@@ -43634,8 +43696,8 @@ function validateTargetLocator3(input, operation) {
       field: "target",
       value: input.target
     });
-  if (hasRef && typeof input.ref !== "string")
-    throw new DocumentApiValidationError2("INVALID_TARGET", "ref must be a string.", {
+  if (hasRef && (typeof input.ref !== "string" || input.ref === ""))
+    throw new DocumentApiValidationError2("INVALID_TARGET", "ref must be a non-empty string.", {
       field: "ref",
       value: input.ref
     });
@@ -43693,13 +43755,18 @@ function executeReplace2(selectionAdapter, writeAdapter, input, options) {
   if (isStructuralReplaceInput2(input))
     return writeAdapter.replaceStructured(input, normalizeMutationOptions2(options));
   const textInput = input;
-  return textReceiptToSDReceipt2(selectionAdapter.execute({
+  const request = textInput.target ? {
     kind: "replace",
     target: textInput.target,
+    text: textInput.text,
+    in: textInput.in
+  } : {
+    kind: "replace",
     ref: textInput.ref,
     text: textInput.text,
     in: textInput.in
-  }, normalizeMutationOptions2(options)));
+  };
+  return textReceiptToSDReceipt2(selectionAdapter.execute(request, normalizeMutationOptions2(options)));
 }
 function validateTargetOnlyCreateLocation2(at, operationName) {
   if (at.kind !== "before" && at.kind !== "after")
@@ -45832,7 +45899,7 @@ function createDocumentApi2(adapters) {
       }
     },
     insert(input, options) {
-      return executeInsert2(adapters.write, input, options);
+      return executeInsert2(adapters.selectionMutation, adapters.write, input, options);
     },
     replace(input, options) {
       return executeReplace2(adapters.selectionMutation, adapters.write, input, options);
@@ -68715,11 +68782,17 @@ function stableHash(input) {
   }
   return (hash >>> 0).toString(16).padStart(8, "0");
 }
-function toTableLikeBlockNodeType(nodeType) {
+function toFallbackEligibleBlockNodeType(nodeType) {
   if (nodeType === "table")
     return "table";
   if (nodeType === "tableCell")
     return "tableCell";
+  if (nodeType === "paragraph")
+    return "paragraph";
+  if (nodeType === "heading")
+    return "heading";
+  if (nodeType === "listItem")
+    return "listItem";
 }
 function serializeTraversalPath(path2, pos) {
   if (Array.isArray(path2) && path2.length > 0)
@@ -68729,11 +68802,11 @@ function serializeTraversalPath(path2, pos) {
 function isVolatileRuntimeBlockId(id) {
   return typeof id === "string" && UUID_LIKE_PATTERN.test(id);
 }
-function buildFallbackTableNodeId(nodeType, pos, path2) {
-  const tableLikeType = toTableLikeBlockNodeType(nodeType);
-  if (!tableLikeType)
+function buildFallbackBlockNodeId(nodeType, pos, path2) {
+  const eligibleType = toFallbackEligibleBlockNodeType(nodeType);
+  if (!eligibleType)
     return;
-  return `${TABLE_LIKE_PREFIX[tableLikeType]}-${stableHash(`${tableLikeType}:${serializeTraversalPath(path2, pos)}`)}`;
+  return `${FALLBACK_PREFIX[eligibleType]}-${stableHash(`${eligibleType}:${serializeTraversalPath(path2, pos)}`)}`;
 }
 function isListItem(attrs) {
   const numbering = attrs?.paragraphProperties?.numberingProperties;
@@ -68787,16 +68860,19 @@ function mapBlockNodeType(node3) {
 function resolveLegacyTableIdentity(attrs) {
   return toId(attrs.paraId) ?? toId(attrs.blockId) ?? toId(attrs.id) ?? toId(attrs.uuid);
 }
-function resolveRuntimeTableIdentity(nodeType, attrs, pos, path2) {
+function resolveTableRuntimeIdentity(nodeType, attrs, pos, path2) {
   const sdBlockId = toId(attrs.sdBlockId);
   if (sdBlockId && !isVolatileRuntimeBlockId(sdBlockId))
     return sdBlockId;
-  return buildFallbackTableNodeId(nodeType, pos, path2);
+  return buildFallbackBlockNodeId(nodeType, pos, path2);
+}
+function resolveParagraphRuntimeIdentity(nodeType, attrs, pos, path2) {
+  return toId(attrs.sdBlockId) ?? buildFallbackBlockNodeId(nodeType, pos, path2);
 }
 function resolveBlockNodeId(node3, pos, nodeType, path2) {
   if (node3.type.name === "paragraph") {
     const attrs$1 = node3.attrs;
-    return toId(attrs$1?.paraId) ?? toId(attrs$1?.sdBlockId);
+    return toId(attrs$1?.paraId) ?? resolveParagraphRuntimeIdentity(nodeType, attrs$1 ?? {}, pos, path2);
   }
   if (nodeType === "tableOfContents")
     return resolvePublicTocNodeId(node3, pos);
@@ -68805,7 +68881,7 @@ function resolveBlockNodeId(node3, pos, nodeType, path2) {
   if (typeName === "tableRow")
     return toId(attrs.paraId) ?? toId(attrs.sdBlockId) ?? toId(attrs.blockId) ?? toId(attrs.id) ?? toId(attrs.uuid);
   if (typeName === "table" || typeName === "tableCell" || typeName === "tableHeader")
-    return resolveLegacyTableIdentity(attrs) ?? resolveRuntimeTableIdentity(nodeType, attrs, pos, path2);
+    return resolveLegacyTableIdentity(attrs) ?? resolveTableRuntimeIdentity(nodeType, attrs, pos, path2);
   return toId(attrs.blockId) ?? toId(attrs.id) ?? toId(attrs.paraId) ?? toId(attrs.uuid) ?? toId(attrs.sdBlockId);
 }
 function toBlockAddress(candidate) {
@@ -68879,23 +68955,15 @@ function findBlockByIdStrict(index2, address2) {
     throw new DocumentApiAdapterError("TARGET_NOT_FOUND", `Block "${key}" was not found.`, { target: address2 });
   return candidate;
 }
-function findBlockByNodeIdOnly(index2, nodeId) {
-  const matches$1 = index2.candidates.filter((candidate) => candidate.nodeId === nodeId);
-  if (matches$1.length === 1)
-    return matches$1[0];
-  if (matches$1.length > 1)
-    throw new DocumentApiAdapterError("AMBIGUOUS_TARGET", `Multiple blocks share nodeId "${nodeId}".`, {
-      nodeId,
-      count: matches$1.length
-    });
+function resolveBlockAlias(index2, nodeId) {
+  if (!index2.byId)
+    return;
   const aliasMatches = /* @__PURE__ */ new Map;
   for (const [key, candidate] of index2.byId) {
     if (!key.endsWith(`:${nodeId}`))
       continue;
     aliasMatches.set(`${candidate.nodeType}:${candidate.nodeId}`, candidate);
   }
-  if (aliasMatches.size === 1)
-    return Array.from(aliasMatches.values())[0];
   if (aliasMatches.size > 1)
     throw new DocumentApiAdapterError("AMBIGUOUS_TARGET", `Multiple blocks share nodeId "${nodeId}" via aliases.`, {
       nodeId,
@@ -68905,6 +68973,20 @@ function findBlockByNodeIdOnly(index2, nodeId) {
         nodeId: candidate.nodeId
       }))
     });
+  return aliasMatches.size === 1 ? Array.from(aliasMatches.values())[0] : undefined;
+}
+function findBlockByNodeIdOnly(index2, nodeId) {
+  const matches$1 = index2.candidates.filter((candidate) => candidate.nodeId === nodeId);
+  if (matches$1.length === 1)
+    return matches$1[0];
+  if (matches$1.length > 1)
+    throw new DocumentApiAdapterError("AMBIGUOUS_TARGET", `Multiple blocks share nodeId "${nodeId}".`, {
+      nodeId,
+      count: matches$1.length
+    });
+  const alias = resolveBlockAlias(index2, nodeId);
+  if (alias)
+    return alias;
   throw new DocumentApiAdapterError("TARGET_NOT_FOUND", `Block with nodeId "${nodeId}" was not found.`, { nodeId });
 }
 function isTextBlockCandidate(candidate) {
@@ -69170,66 +69252,46 @@ function insertParagraphAtEnd(editor, pos, text$2, applyMeta) {
   editor.dispatch(tr);
 }
 function resolveWriteTarget(editor, request) {
-  const requestedTarget = request.target;
-  if (request.kind === "insert" && !request.target) {
-    const fallback = resolveDefaultInsertTarget(editor);
-    if (!fallback)
-      return null;
-    if (fallback.kind === "structural-end") {
-      const pos = fallback.insertPos;
-      const syntheticRange = {
-        from: pos,
-        to: pos
-      };
-      const syntheticTarget = {
-        kind: "text",
-        blockId: "",
-        range: {
-          start: 0,
-          end: 0
-        }
-      };
-      return {
-        requestedTarget,
-        effectiveTarget: syntheticTarget,
-        range: syntheticRange,
-        resolution: buildTextMutationResolution({
-          requestedTarget,
-          target: syntheticTarget,
-          range: syntheticRange,
-          text: ""
-        }),
-        structuralEnd: true
-      };
-    }
-    const text$2 = readTextAtResolvedRange(editor, fallback.range);
+  const fallback = resolveDefaultInsertTarget(editor);
+  if (!fallback)
+    return null;
+  if (fallback.kind === "structural-end") {
+    const pos = fallback.insertPos;
+    const syntheticRange = {
+      from: pos,
+      to: pos
+    };
+    const syntheticTarget = {
+      kind: "text",
+      blockId: "",
+      range: {
+        start: 0,
+        end: 0
+      }
+    };
     return {
-      requestedTarget,
-      effectiveTarget: fallback.target,
-      range: fallback.range,
+      requestedTarget: undefined,
+      effectiveTarget: syntheticTarget,
+      range: syntheticRange,
       resolution: buildTextMutationResolution({
-        requestedTarget,
-        target: fallback.target,
-        range: fallback.range,
-        text: text$2
-      })
+        requestedTarget: undefined,
+        target: syntheticTarget,
+        range: syntheticRange,
+        text: ""
+      }),
+      structuralEnd: true
     };
   }
-  const target = request.target;
-  if (!target)
-    return null;
-  const range = resolveTextTarget(editor, target);
-  if (!range)
-    return null;
+  const text$2 = readTextAtResolvedRange(editor, fallback.range);
   return {
-    requestedTarget,
-    effectiveTarget: target,
-    range,
+    requestedTarget: undefined,
+    effectiveTarget: fallback.target,
+    range: fallback.range,
     resolution: buildTextMutationResolution({
-      requestedTarget,
-      target,
-      range,
-      text: readTextAtResolvedRange(editor, range)
+      requestedTarget: undefined,
+      target: fallback.target,
+      range: fallback.range,
+      text: text$2
     })
   };
 }
@@ -75030,7 +75092,7 @@ var isRegExp = (value) => {
   tracked: false,
   carrier: runAttributeCarrier2(runPropertyKey ?? key),
   schema
-}), INLINE_PROPERTY_REGISTRY2, INLINE_PROPERTY_KEY_SET2, INLINE_PROPERTY_BY_KEY2, UNDERLINE_OBJECT_ALLOWED_KEYS2, SHADING_ALLOWED_KEYS2, BORDER_ALLOWED_KEYS2, FIT_TEXT_ALLOWED_KEYS2, LANG_ALLOWED_KEYS2, RFONTS_ALLOWED_KEYS2, EAST_ASIAN_LAYOUT_ALLOWED_KEYS2, STYLISTIC_SET_ALLOWED_KEYS2, VERT_ALIGN_VALUES2, PROPERTY_VALIDATOR_MAP2, NONE_FAILURES2, NONE_THROWS2, T_NOT_FOUND2, T_NOT_FOUND_CAPABLE2, T_PLAN_ENGINE2, T_NOT_FOUND_COMMAND2, T_IMAGE_COMMAND2, T_CC_READ2, T_CC_MUTATION2, T_CC_TYPED2, T_CC_TYPED_READ2, T_CC_RAW2, T_QUERY_MATCH2, T_SECTION_CREATE2, T_SECTION_READ2, T_PARAGRAPH_MUTATION2, T_SECTION_MUTATION2, T_SECTION_SETTINGS_MUTATION2, T_HEADER_FOOTER_MUTATION2, T_STORY2, T_REF_READ_LIST2, T_REF_MUTATION2, T_REF_MUTATION_REMOVE2, T_REF_INSERT2, FORMAT_INLINE_ALIAS_OPERATION_DEFINITIONS2, OPERATION_DEFINITIONS2, OPERATION_IDS2, COMMAND_CATALOG3, PARAGRAPH_ALIGNMENTS2, TAB_STOP_ALIGNMENTS2, TAB_STOP_LEADERS2, BORDER_SIDES2, CLEAR_BORDER_SIDES2, LINE_RULES2, PARAGRAPH_DIRECTIONS2, ALIGNMENT_POLICIES2, PARAGRAPH_BLOCK_TYPES2, SET_STYLE_KEYS2, CLEAR_STYLE_KEYS2, RESET_DIRECT_FORMATTING_KEYS2, SET_ALIGNMENT_KEYS2, CLEAR_ALIGNMENT_KEYS2, SET_INDENTATION_KEYS2, CLEAR_INDENTATION_KEYS2, SET_SPACING_KEYS2, CLEAR_SPACING_KEYS2, SET_KEEP_OPTIONS_KEYS2, SET_OUTLINE_LEVEL_KEYS2, SET_FLOW_OPTIONS_KEYS2, SET_TAB_STOP_KEYS2, CLEAR_TAB_STOP_KEYS2, CLEAR_ALL_TAB_STOPS_KEYS2, SET_BORDER_KEYS2, CLEAR_BORDER_KEYS2, SET_SHADING_KEYS2, CLEAR_SHADING_KEYS2, SET_DIRECTION_KEYS2, CLEAR_DIRECTION_KEYS2, ST_ON_OFF_ON_VALUES2, ST_ON_OFF_OFF_VALUES2, ST_UNDERLINE_VALUES2, ST_UNDERLINE_VALUE_SET2, ST_VERTICAL_ALIGN_RUN2, ST_EM2, ST_TEXT_ALIGNMENT2, ST_TEXT_DIRECTION2, ST_TEXTBOX_TIGHT_WRAP2, ST_TEXT_TRANSFORM2, ST_JUSTIFICATION2, FONT_FAMILY_SCHEMA2, COLOR_SCHEMA2, SPACING_SCHEMA2, INDENT_SCHEMA2, UNDERLINE_SCHEMA2, BORDER_PROPERTIES_SCHEMA2, SHADING_SCHEMA2, LANG_SCHEMA2, EAST_ASIAN_LAYOUT_SCHEMA2, FIT_TEXT_SCHEMA2, NUMBERING_PROPERTIES_SCHEMA2, FRAME_PR_SCHEMA2, PARAGRAPH_BORDERS_SCHEMA2, TAB_STOP_SCHEMA2, PROPERTY_REGISTRY2, ALLOWED_KEYS_BY_CHANNEL2, PROPERTY_INDEX2, EXCLUDED_KEYS2, INPUT_ALLOWED_KEYS2, TARGET_ALLOWED_KEYS2, OPTIONS_ALLOWED_KEYS2, VALID_CHANNELS2, Z_ORDER_RELATIVE_HEIGHT_MAX2 = 4294967295, nodeTypeValues2, blockNodeTypeValues2, deletableBlockNodeTypeValues2, inlineNodeTypeValues2, rangeSchema2, textAddressSchema2, textTargetSchema2, blockNodeAddressSchema2, deletableBlockNodeAddressSchema2, tableAddressSchema2, tableRowAddressSchema2, tableCellAddressSchema2, tableOrCellAddressSchema2, paragraphAddressSchema2, headingAddressSchema2, listItemAddressSchema2, paragraphTargetSchema2, sectionAddressSchema2, nodeAddressSchema2, commentAddressSchema2, trackedChangeAddressSchema2, entityAddressSchema2, selectionTargetSchema2, deleteBehaviorSchema2, resolvedHandleSchema2, pageInfoSchema2, receiptSuccessSchema2, textMutationRangeSchema2, textMutationResolutionSchema2, textMutationSuccessSchema2, matchBlockSchema2, storyLocatorSchema2, trackChangeRefSchema2, createParagraphSuccessSchema2, createHeadingSuccessSchema2, headingLevelSchema2, listsInsertSuccessSchema2, listsMutateItemSuccessSchema2, textSelectorSchema2, nodeSelectorSchema2, sdMutationResolutionSchema2, sdMutationSuccessSchema2, documentInfoCountsSchema2, documentInfoOutlineItemSchema2, documentInfoCapabilitiesSchema2, listKindSchema2, listInsertPositionSchema2, sectionBreakTypeSchema2, sectionOrientationSchema2, sectionVerticalAlignSchema2, sectionDirectionSchema2, sectionHeaderFooterKindSchema2, sectionHeaderFooterVariantSchema2, sectionLineNumberRestartSchema2, sectionPageNumberFormatSchema2, sectionRangeDomainSchema2, sectionPageMarginsSchema2, sectionHeaderFooterMarginsSchema2, sectionPageSetupSchema2, sectionColumnsSchema2, sectionLineNumberingSchema2, sectionPageNumberingSchema2, sectionHeaderFooterRefsSchema2, sectionBorderSpecSchema2, sectionPageBordersSchema2, sectionMutationSuccessSchema2, documentMutationSuccessSchema2, paragraphMutationTargetSchema2, paragraphMutationSuccessSchema2, createSectionBreakSuccessSchema2, capabilityReasonsSchema2, capabilityFlagSchema2, operationRuntimeCapabilitySchema2, operationCapabilitiesSchema2, inlinePropertyCapabilitySchema2, formatCapabilitiesSchema2, planEngineCapabilitiesSchema2, nullableTableBorderSpecSchema2, sdFragmentSchema2, placementSchema2, nestingPolicySchema2, tableCreateLocationSchema2, formatInlineAliasOperationSchemas2, tocMutationFailureSchema2, tocMutationSuccessSchema2, tocEntryMutationFailureSchema2, tocEntryMutationSuccessSchema2, hyperlinkTargetSchema2, hyperlinkReadPropertiesSchema2, hyperlinkSpecSchema2, hyperlinkPatchSchema2, hyperlinkDomainSchema2, hyperlinkMutationSuccessSchema2, hyperlinkMutationFailureSchema2, contentControlTargetSchema2, contentControlMutationSuccessSchema2, contentControlMutationFailureSchema2, ccListResultSchema2, ccInfoSchema2, refFailureSchema2, bookmarkAddressSchema2, bookmarkMutation2, footnoteAddressSchema2, footnoteConfigScopeSchema2, footnoteNumberingSchema2, footnoteMutation2, footnoteConfig2, crossRefAddressSchema2, crossRefTargetSchema2, crossRefDisplaySchema2, crossRefMutation2, indexAddressSchema2, indexEntryAddressSchema2, indexConfigSchema2, indexEntryDataSchema2, indexEntryPatchSchema2, indexMutation2, indexEntryMutation2, captionAddressSchema2, captionMutation2, captionConfig2, fieldAddressSchema2, fieldMutation2, citationAddressSchema2, citationSourceAddressSchema2, bibliographyAddressSchema2, citationMutation2, citationSourceMutation2, bibliographyMutation2, citationPersonSchema2, citationSourceFieldsSchema2, tocCreateLocationSchema2, authoritiesAddressSchema2, authorityEntryAddressSchema2, authoritiesConfigSchema2, authorityEntryDataSchema2, authorityEntryPatchSchema2, authoritiesMutation2, authorityEntryMutation2, diffCoverageSchema2, diffSummarySchema2, diffSnapshotSchema2, diffPayloadSchema2, GROUP_METADATA2, STEP_OP_CATALOG_UNFROZEN2, PUBLIC_STEP_OP_CATALOG_UNFROZEN2, PUBLIC_MUTATION_STEP_OP_IDS2, PUBLIC_MUTATION_STEP_OP_SET2, CAPABILITY_REASON_CODES, VALID_EDGE_VALUES2, VALID_EDGE_NODE_TYPES2, VALID_DOCUMENT_EDGES2, VALID_REF_BOUNDARIES2, VALID_ANCHOR_KINDS2, RESOLVE_RANGE_ALLOWED_KEYS2, CREATE_COMMENT_ALLOWED_KEYS2, PATCH_COMMENT_ALLOWED_KEYS2, STYLE_APPLY_INPUT_ALLOWED_KEYS2, INLINE_ALIAS_INPUT_ALLOWED_KEYS2, DELETE_INPUT_ALLOWED_KEYS2, VALID_BEHAVIORS2, CONTENT_KIND_SET2, INLINE_KIND_SET2, LEGACY_TOP_LEVEL_TYPES2, LEGACY_INSERT_ALLOWED_KEYS2, STRUCTURAL_INSERT_ALLOWED_KEYS2, VALID_INSERT_TYPES2, TEXT_REPLACE_ALLOWED_KEYS2, STRUCTURAL_REPLACE_ALLOWED_KEYS2, SECTION_BREAK_TYPES$1, SUPPORTED_DELETE_NODE_TYPES2, REJECTED_DELETE_NODE_TYPES2, VALID_BLOCK_NODE_TYPES2, SNAPSHOT_VERSION2 = "sd-diff-snapshot/v1", PAYLOAD_VERSION2 = "sd-diff-payload/v1", VALID_STYLE_OPTION_FLAGS2, TABLE_BORDER_COLOR_PATTERN2, VALID_APPLY_TO_VALUES2, VALID_BORDER_EDGE_KEYS2, HEADER_FOOTER_KINDS$1, HEADER_FOOTER_VARIANTS$1, DEFAULT_SECTIONS_LIST_LIMIT2 = 250, SECTION_BREAK_TYPES3, SECTION_ORIENTATIONS2, SECTION_VERTICAL_ALIGNS2, SECTION_DIRECTIONS2, HEADER_FOOTER_KINDS3, HEADER_FOOTER_VARIANTS3, LINE_NUMBER_RESTARTS2, PAGE_NUMBER_FORMATS2, PAGE_BORDER_DISPLAYS2, PAGE_BORDER_OFFSET_FROM_VALUES2, PAGE_BORDER_Z_ORDER_VALUES2, VALID_WRAP_TYPES2, VALID_WRAP_SIDES2, VALID_IMAGE_SIZE_UNITS2, PATCH_FIELDS2, ADAPTER_GATED_PREFIXES2, _buffers, _defaultCollectionId = null, _nextCollectionId = 1, generateV2HandlerEntity = (handlerName, translator$216) => ({
+}), INLINE_PROPERTY_REGISTRY2, INLINE_PROPERTY_KEY_SET2, INLINE_PROPERTY_BY_KEY2, UNDERLINE_OBJECT_ALLOWED_KEYS2, SHADING_ALLOWED_KEYS2, BORDER_ALLOWED_KEYS2, FIT_TEXT_ALLOWED_KEYS2, LANG_ALLOWED_KEYS2, RFONTS_ALLOWED_KEYS2, EAST_ASIAN_LAYOUT_ALLOWED_KEYS2, STYLISTIC_SET_ALLOWED_KEYS2, VERT_ALIGN_VALUES2, PROPERTY_VALIDATOR_MAP2, NONE_FAILURES2, NONE_THROWS2, T_NOT_FOUND2, T_NOT_FOUND_CAPABLE2, T_PLAN_ENGINE2, T_NOT_FOUND_COMMAND2, T_IMAGE_COMMAND2, T_CC_READ2, T_CC_MUTATION2, T_CC_TYPED2, T_CC_TYPED_READ2, T_CC_RAW2, T_QUERY_MATCH2, T_SECTION_CREATE2, T_SECTION_READ2, T_PARAGRAPH_MUTATION2, T_SECTION_MUTATION2, T_SECTION_SETTINGS_MUTATION2, T_HEADER_FOOTER_MUTATION2, T_STORY2, T_REF_READ_LIST2, T_REF_MUTATION2, T_REF_MUTATION_REMOVE2, T_REF_INSERT2, FORMAT_INLINE_ALIAS_OPERATION_DEFINITIONS2, OPERATION_DEFINITIONS2, OPERATION_IDS2, COMMAND_CATALOG3, PARAGRAPH_ALIGNMENTS2, TAB_STOP_ALIGNMENTS2, TAB_STOP_LEADERS2, BORDER_SIDES2, CLEAR_BORDER_SIDES2, LINE_RULES2, PARAGRAPH_DIRECTIONS2, ALIGNMENT_POLICIES2, PARAGRAPH_BLOCK_TYPES2, SET_STYLE_KEYS2, CLEAR_STYLE_KEYS2, RESET_DIRECT_FORMATTING_KEYS2, SET_ALIGNMENT_KEYS2, CLEAR_ALIGNMENT_KEYS2, SET_INDENTATION_KEYS2, CLEAR_INDENTATION_KEYS2, SET_SPACING_KEYS2, CLEAR_SPACING_KEYS2, SET_KEEP_OPTIONS_KEYS2, SET_OUTLINE_LEVEL_KEYS2, SET_FLOW_OPTIONS_KEYS2, SET_TAB_STOP_KEYS2, CLEAR_TAB_STOP_KEYS2, CLEAR_ALL_TAB_STOPS_KEYS2, SET_BORDER_KEYS2, CLEAR_BORDER_KEYS2, SET_SHADING_KEYS2, CLEAR_SHADING_KEYS2, SET_DIRECTION_KEYS2, CLEAR_DIRECTION_KEYS2, ST_ON_OFF_ON_VALUES2, ST_ON_OFF_OFF_VALUES2, ST_UNDERLINE_VALUES2, ST_UNDERLINE_VALUE_SET2, ST_VERTICAL_ALIGN_RUN2, ST_EM2, ST_TEXT_ALIGNMENT2, ST_TEXT_DIRECTION2, ST_TEXTBOX_TIGHT_WRAP2, ST_TEXT_TRANSFORM2, ST_JUSTIFICATION2, FONT_FAMILY_SCHEMA2, COLOR_SCHEMA2, SPACING_SCHEMA2, INDENT_SCHEMA2, UNDERLINE_SCHEMA2, BORDER_PROPERTIES_SCHEMA2, SHADING_SCHEMA2, LANG_SCHEMA2, EAST_ASIAN_LAYOUT_SCHEMA2, FIT_TEXT_SCHEMA2, NUMBERING_PROPERTIES_SCHEMA2, FRAME_PR_SCHEMA2, PARAGRAPH_BORDERS_SCHEMA2, TAB_STOP_SCHEMA2, PROPERTY_REGISTRY2, ALLOWED_KEYS_BY_CHANNEL2, PROPERTY_INDEX2, EXCLUDED_KEYS2, INPUT_ALLOWED_KEYS2, TARGET_ALLOWED_KEYS2, OPTIONS_ALLOWED_KEYS2, VALID_CHANNELS2, Z_ORDER_RELATIVE_HEIGHT_MAX2 = 4294967295, nodeTypeValues2, blockNodeTypeValues2, deletableBlockNodeTypeValues2, inlineNodeTypeValues2, rangeSchema2, textAddressSchema2, textTargetSchema2, blockNodeAddressSchema2, deletableBlockNodeAddressSchema2, tableAddressSchema2, tableRowAddressSchema2, tableCellAddressSchema2, tableOrCellAddressSchema2, paragraphAddressSchema2, headingAddressSchema2, listItemAddressSchema2, paragraphTargetSchema2, sectionAddressSchema2, nodeAddressSchema2, commentAddressSchema2, trackedChangeAddressSchema2, entityAddressSchema2, selectionTargetSchema2, deleteBehaviorSchema2, resolvedHandleSchema2, pageInfoSchema2, receiptSuccessSchema2, textMutationRangeSchema2, textMutationResolutionSchema2, textMutationSuccessSchema2, matchBlockSchema2, storyLocatorSchema2, trackChangeRefSchema2, createParagraphSuccessSchema2, createHeadingSuccessSchema2, headingLevelSchema2, listsInsertSuccessSchema2, listsMutateItemSuccessSchema2, textSelectorSchema2, nodeSelectorSchema2, sdMutationResolutionSchema2, sdMutationSuccessSchema2, documentInfoCountsSchema2, documentInfoOutlineItemSchema2, documentInfoCapabilitiesSchema2, listKindSchema2, listInsertPositionSchema2, sectionBreakTypeSchema2, sectionOrientationSchema2, sectionVerticalAlignSchema2, sectionDirectionSchema2, sectionHeaderFooterKindSchema2, sectionHeaderFooterVariantSchema2, sectionLineNumberRestartSchema2, sectionPageNumberFormatSchema2, sectionRangeDomainSchema2, sectionPageMarginsSchema2, sectionHeaderFooterMarginsSchema2, sectionPageSetupSchema2, sectionColumnsSchema2, sectionLineNumberingSchema2, sectionPageNumberingSchema2, sectionHeaderFooterRefsSchema2, sectionBorderSpecSchema2, sectionPageBordersSchema2, sectionMutationSuccessSchema2, documentMutationSuccessSchema2, paragraphMutationTargetSchema2, paragraphMutationSuccessSchema2, createSectionBreakSuccessSchema2, capabilityReasonsSchema2, capabilityFlagSchema2, operationRuntimeCapabilitySchema2, operationCapabilitiesSchema2, inlinePropertyCapabilitySchema2, formatCapabilitiesSchema2, planEngineCapabilitiesSchema2, nullableTableBorderSpecSchema2, sdFragmentSchema2, placementSchema2, nestingPolicySchema2, tableCreateLocationSchema2, formatInlineAliasOperationSchemas2, tocMutationFailureSchema2, tocMutationSuccessSchema2, tocEntryMutationFailureSchema2, tocEntryMutationSuccessSchema2, hyperlinkTargetSchema2, hyperlinkReadPropertiesSchema2, hyperlinkSpecSchema2, hyperlinkPatchSchema2, hyperlinkDomainSchema2, hyperlinkMutationSuccessSchema2, hyperlinkMutationFailureSchema2, contentControlTargetSchema2, contentControlMutationSuccessSchema2, contentControlMutationFailureSchema2, ccListResultSchema2, ccInfoSchema2, refFailureSchema2, bookmarkAddressSchema2, bookmarkMutation2, footnoteAddressSchema2, footnoteConfigScopeSchema2, footnoteNumberingSchema2, footnoteMutation2, footnoteConfig2, crossRefAddressSchema2, crossRefTargetSchema2, crossRefDisplaySchema2, crossRefMutation2, indexAddressSchema2, indexEntryAddressSchema2, indexConfigSchema2, indexEntryDataSchema2, indexEntryPatchSchema2, indexMutation2, indexEntryMutation2, captionAddressSchema2, captionMutation2, captionConfig2, fieldAddressSchema2, fieldMutation2, citationAddressSchema2, citationSourceAddressSchema2, bibliographyAddressSchema2, citationMutation2, citationSourceMutation2, bibliographyMutation2, citationPersonSchema2, citationSourceFieldsSchema2, tocCreateLocationSchema2, authoritiesAddressSchema2, authorityEntryAddressSchema2, authoritiesConfigSchema2, authorityEntryDataSchema2, authorityEntryPatchSchema2, authoritiesMutation2, authorityEntryMutation2, diffCoverageSchema2, diffSummarySchema2, diffSnapshotSchema2, diffPayloadSchema2, GROUP_METADATA2, STEP_OP_CATALOG_UNFROZEN2, PUBLIC_STEP_OP_CATALOG_UNFROZEN2, PUBLIC_MUTATION_STEP_OP_IDS2, PUBLIC_MUTATION_STEP_OP_SET2, CAPABILITY_REASON_CODES, VALID_EDGE_VALUES2, VALID_EDGE_NODE_TYPES2, VALID_DOCUMENT_EDGES2, VALID_REF_BOUNDARIES2, VALID_ANCHOR_KINDS2, RESOLVE_RANGE_ALLOWED_KEYS2, CREATE_COMMENT_ALLOWED_KEYS2, PATCH_COMMENT_ALLOWED_KEYS2, STYLE_APPLY_INPUT_ALLOWED_KEYS2, INLINE_ALIAS_INPUT_ALLOWED_KEYS2, DELETE_INPUT_ALLOWED_KEYS2, VALID_BEHAVIORS2, CONTENT_KIND_SET2, INLINE_KIND_SET2, LEGACY_TOP_LEVEL_TYPES2, TEXT_INSERT_ALLOWED_KEYS2, STRUCTURAL_INSERT_ALLOWED_KEYS2, VALID_INSERT_TYPES2, TEXT_REPLACE_ALLOWED_KEYS2, STRUCTURAL_REPLACE_ALLOWED_KEYS2, SECTION_BREAK_TYPES$1, SUPPORTED_DELETE_NODE_TYPES2, REJECTED_DELETE_NODE_TYPES2, VALID_BLOCK_NODE_TYPES2, SNAPSHOT_VERSION2 = "sd-diff-snapshot/v1", PAYLOAD_VERSION2 = "sd-diff-payload/v1", VALID_STYLE_OPTION_FLAGS2, TABLE_BORDER_COLOR_PATTERN2, VALID_APPLY_TO_VALUES2, VALID_BORDER_EDGE_KEYS2, HEADER_FOOTER_KINDS$1, HEADER_FOOTER_VARIANTS$1, DEFAULT_SECTIONS_LIST_LIMIT2 = 250, SECTION_BREAK_TYPES3, SECTION_ORIENTATIONS2, SECTION_VERTICAL_ALIGNS2, SECTION_DIRECTIONS2, HEADER_FOOTER_KINDS3, HEADER_FOOTER_VARIANTS3, LINE_NUMBER_RESTARTS2, PAGE_NUMBER_FORMATS2, PAGE_BORDER_DISPLAYS2, PAGE_BORDER_OFFSET_FROM_VALUES2, PAGE_BORDER_Z_ORDER_VALUES2, VALID_WRAP_TYPES2, VALID_WRAP_SIDES2, VALID_IMAGE_SIZE_UNITS2, PATCH_FIELDS2, ADAPTER_GATED_PREFIXES2, _buffers, _defaultCollectionId = null, _nextCollectionId = 1, generateV2HandlerEntity = (handlerName, translator$216) => ({
   handlerName,
   handler: (params) => {
     const { nodes } = params;
@@ -89102,7 +89164,7 @@ var isRegExp = (value) => {
       candidate = candidate.prev;
     }
   }
-}, DocumentApiAdapterError, SectionType, DEFAULT_PARAGRAPH_SECTION_TYPE, DEFAULT_BODY_SECTION_TYPE, TWIPS_PER_INCH = 1440, PX_PER_INCH = 96, DEFAULT_COLUMN_GAP_INCHES = 0.5, DEFAULT_HEADER_FOOTER_MARGIN_PX = 0, CommentMarkName = "commentMark", LINK_MARK_NAME = "link", COMMENT_MARK_NAME, SUPPORTED_INLINE_TYPES, TABLE_LIKE_PREFIX, UUID_LIKE_PATTERN, ALIAS_ELIGIBLE_TYPES, cacheByEditor, OBJECT_REPLACEMENT_CHAR = "", LINE_NUMBER_RESTART_VALUES, PAGE_NUMBER_FORMAT_VALUES, SECTION_ORIENTATION_VALUES, SECTION_VERTICAL_ALIGN_VALUES, readSectPrHeaderFooterRefs, PIXELS_PER_INCH = 96, DOCUMENT_RELS_PATH = "word/_rels/document.xml.rels", RELS_XMLNS = "http://schemas.openxmlformats.org/package/2006/relationships", HEADER_RELATIONSHIP_TYPE2 = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/header", FOOTER_RELATIONSHIP_TYPE2 = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/footer", WORDPROCESSINGML_XMLNS = "http://schemas.openxmlformats.org/wordprocessingml/2006/main", OFFICE_DOCUMENT_RELS_XMLNS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships", RELATIONSHIP_ID_PATTERN, HEADER_FILE_PATTERN, FOOTER_FILE_PATTERN, SOURCE_HEADER_FOOTER_LOCAL = "header-footer-sync:local", HEADER_PATTERN, FOOTER_PATTERN, DEFAULT_HDR_FTR_ATTRS, HEADER_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/header", FOOTER_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/footer", VALID_VARIANTS, FOOTNOTES_PART_ID = "word/footnotes.xml", ENDNOTES_PART_ID = "word/endnotes.xml", FOOTNOTES_CONFIG, ENDNOTES_CONFIG, NOTES_XMLNS, footnotesPartDescriptor, endnotesPartDescriptor, storeByEditor, cacheByHost, hostStoreSyncedKeys, BODY_LOCATOR, findMarkPosition = (doc$2, pos, markName) => {
+}, DocumentApiAdapterError, SectionType, DEFAULT_PARAGRAPH_SECTION_TYPE, DEFAULT_BODY_SECTION_TYPE, TWIPS_PER_INCH = 1440, PX_PER_INCH = 96, DEFAULT_COLUMN_GAP_INCHES = 0.5, DEFAULT_HEADER_FOOTER_MARGIN_PX = 0, CommentMarkName = "commentMark", LINK_MARK_NAME = "link", COMMENT_MARK_NAME, SUPPORTED_INLINE_TYPES, FALLBACK_PREFIX, UUID_LIKE_PATTERN, ALIAS_ELIGIBLE_TYPES, cacheByEditor, OBJECT_REPLACEMENT_CHAR = "", LINE_NUMBER_RESTART_VALUES, PAGE_NUMBER_FORMAT_VALUES, SECTION_ORIENTATION_VALUES, SECTION_VERTICAL_ALIGN_VALUES, readSectPrHeaderFooterRefs, PIXELS_PER_INCH = 96, DOCUMENT_RELS_PATH = "word/_rels/document.xml.rels", RELS_XMLNS = "http://schemas.openxmlformats.org/package/2006/relationships", HEADER_RELATIONSHIP_TYPE2 = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/header", FOOTER_RELATIONSHIP_TYPE2 = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/footer", WORDPROCESSINGML_XMLNS = "http://schemas.openxmlformats.org/wordprocessingml/2006/main", OFFICE_DOCUMENT_RELS_XMLNS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships", RELATIONSHIP_ID_PATTERN, HEADER_FILE_PATTERN, FOOTER_FILE_PATTERN, SOURCE_HEADER_FOOTER_LOCAL = "header-footer-sync:local", HEADER_PATTERN, FOOTER_PATTERN, DEFAULT_HDR_FTR_ATTRS, HEADER_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/header", FOOTER_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/footer", VALID_VARIANTS, FOOTNOTES_PART_ID = "word/footnotes.xml", ENDNOTES_PART_ID = "word/endnotes.xml", FOOTNOTES_CONFIG, ENDNOTES_CONFIG, NOTES_XMLNS, footnotesPartDescriptor, endnotesPartDescriptor, storeByEditor, cacheByHost, hostStoreSyncedKeys, BODY_LOCATOR, findMarkPosition = (doc$2, pos, markName) => {
   const $pos = doc$2.resolve(pos);
   const parent = $pos.parent;
   const start = parent.childAfter($pos.parentOffset);
@@ -89204,7 +89266,7 @@ var isRegExp = (value) => {
       state.kern = kernNode.attributes["w:val"];
   }
 }, SuperConverter;
-var init_SuperConverter_Cukh7tk8_es = __esm(() => {
+var init_SuperConverter_C65zRR3r_es = __esm(() => {
   init_rolldown_runtime_B2q5OVn9_es();
   init_jszip_ChlR43oI_es();
   init_xml_js_BtmJ6bNs_es();
@@ -92352,8 +92414,8 @@ var init_SuperConverter_Cukh7tk8_es = __esm(() => {
     },
     insert: {
       memberPath: "insert",
-      description: "Insert content into the document. Two input shapes: legacy string-based (value + type) inserts inline content at a text position within an existing block; structural SDFragment (content) inserts one or more blocks as siblings relative to a BlockNodeAddress target. When target is omitted, content appends at the end of the document. Legacy mode supports text (default), markdown, and html content types via the `type` field. Structural mode uses `placement` (before/after/insideStart/insideEnd) to position relative to the target block.",
-      expectedResult: "Returns an SDMutationReceipt with applied status; resolution reports a TextAddress for legacy text insertion or a BlockNodeAddress for structural insertion. Receipt reports NO_OP if the insertion point is invalid or content is empty.",
+      description: "Insert content into the document. Two input shapes: text-based (value + type) inserts inline content at a SelectionTarget or ref position within an existing block; structural SDFragment (content) inserts one or more blocks as siblings relative to a BlockNodeAddress target. When target/ref is omitted, content appends at the end of the document. Text mode supports text (default), markdown, and html content types via the `type` field. Structural mode uses `placement` (before/after/insideStart/insideEnd) to position relative to the target block.",
+      expectedResult: "Returns an SDMutationReceipt with applied status; resolution reports the inserted TextAddress for text insertion or a BlockNodeAddress for structural insertion. Receipt reports NO_OP if the insertion point is invalid or content is empty.",
       requiresDocumentContext: true,
       metadata: mutationOperation2({
         idempotency: "non-idempotent",
@@ -99293,12 +99355,8 @@ var init_SuperConverter_Cukh7tk8_es = __esm(() => {
     ...objectSchema2({ tables: { enum: ["forbid", "allow"] } }),
     description: "Controls nesting behavior. tables: 'allow' permits inserting tables inside other tables."
   };
-  objectSchema2({
+  optionalTargetLocatorWithPayload2({
     in: storyLocatorSchema2,
-    target: {
-      ...textAddressSchema2,
-      description: "Insertion point: {kind:'text', blockId:'...', range:{start, end}}."
-    },
     value: {
       type: "string",
       description: "Text content to insert."
@@ -103298,10 +103356,11 @@ var init_SuperConverter_Cukh7tk8_es = __esm(() => {
     "tableOfContents",
     "sdt"
   ]);
-  LEGACY_INSERT_ALLOWED_KEYS2 = new Set([
+  TEXT_INSERT_ALLOWED_KEYS2 = new Set([
     "value",
     "type",
     "target",
+    "ref",
     "in"
   ]);
   STRUCTURAL_INSERT_ALLOWED_KEYS2 = new Set([
@@ -124540,9 +124599,12 @@ var init_SuperConverter_Cukh7tk8_es = __esm(() => {
     "tab",
     "lineBreak"
   ]);
-  TABLE_LIKE_PREFIX = {
+  FALLBACK_PREFIX = {
     table: "table-auto",
-    tableCell: "cell-auto"
+    tableCell: "cell-auto",
+    paragraph: "para-auto",
+    heading: "heading-auto",
+    listItem: "list-auto"
   };
   UUID_LIKE_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
   ALIAS_ELIGIBLE_TYPES = new Set([
@@ -152177,7 +152239,7 @@ var init_remark_gfm_CjV8kaUy_es = __esm(() => {
   init_remark_gfm_z_sDF4ss_es();
 });
 
-// ../../packages/superdoc/dist/chunks/src-D389XrYP.es.js
+// ../../packages/superdoc/dist/chunks/src-BrT7SmAZ.es.js
 function deleteProps(obj, propOrProps) {
   const props = typeof propOrProps === "string" ? [propOrProps] : propOrProps;
   const removeNested = (target, pathParts, index2 = 0) => {
@@ -175893,7 +175955,16 @@ function findTextBlockByNodeId(index2, nodeId) {
       blockId: nodeId,
       matchCount: matches2.length
     });
-  return matches2[0];
+  if (matches2.length === 1)
+    return matches2[0];
+  try {
+    const resolved = findBlockByNodeIdOnly(index2, nodeId);
+    if (isTextBlockCandidate(resolved))
+      return resolved;
+  } catch (e) {
+    if (e instanceof DocumentApiAdapterError && e.code === "AMBIGUOUS_TARGET")
+      throw e;
+  }
 }
 function findBlockByTypeAndId(index2, nodeType, nodeId) {
   const key$1 = `${nodeType}:${nodeId}`;
@@ -175902,7 +175973,15 @@ function findBlockByTypeAndId(index2, nodeType, nodeId) {
       nodeType,
       nodeId
     });
-  return index2.byId.get(key$1);
+  const exact = index2.byId.get(key$1);
+  if (exact)
+    return exact;
+  try {
+    return findBlockByNodeIdOnly(index2, nodeId);
+  } catch (e) {
+    if (e instanceof DocumentApiAdapterError && e.code === "AMBIGUOUS_TARGET")
+      throw e;
+  }
 }
 function expandDeleteSelection(editor, absFrom, absTo, start$1, end$1) {
   if (absFrom === absTo)
@@ -176342,7 +176421,13 @@ function resolveTextRef(editor, index2, step3, ref$1) {
   return resolveV3TextRef(editor, index2, step3, decoded);
 }
 function resolveBlockRef(editor, index2, step3, ref$1) {
-  const candidate = index2.candidates.find((c) => c.nodeId === ref$1);
+  const primaryMatches = index2.candidates.filter((c) => c.nodeId === ref$1);
+  if (primaryMatches.length > 1)
+    throw planError("AMBIGUOUS_TARGET", `Multiple blocks share nodeId "${ref$1}".`, step3.id, {
+      ref: ref$1,
+      count: primaryMatches.length
+    });
+  const candidate = primaryMatches[0] ?? resolveBlockAlias(index2, ref$1);
   if (!candidate)
     return [];
   const blockText = getBlockText(editor, candidate);
@@ -178751,6 +178836,18 @@ function resolveMutationStory(context) {
   const effectiveTargetStory = context.target?.story ?? storyFromRef;
   return resolveStoryFromInput({ in: context.in }, effectiveTargetStory ? { story: effectiveTargetStory } : undefined);
 }
+function nodeEdgeAfterOffset(editor, nodeType, nodeId) {
+  const index2 = getBlockIndex(editor);
+  const key$1 = `${nodeType}:${nodeId}`;
+  const block = index2.byId.get(key$1);
+  if (!block || !block.node.isTextblock)
+    return 0;
+  const contentStart = block.pos + 1;
+  const contentEnd = block.end - 1;
+  if (contentEnd <= contentStart)
+    return 0;
+  return editor.state.doc.textBetween(contentStart, contentEnd, "", "").length;
+}
 function editorHasDom(editor) {
   const opts = editor.options;
   return !!(opts?.document ?? opts?.mockDocument ?? (typeof document !== "undefined" ? document : null));
@@ -178821,31 +178918,6 @@ function toTextAddress$1(target) {
     }
   };
 }
-function normalizeWriteLocator(request) {
-  const hasBlockId = request.blockId !== undefined;
-  const hasOffset = request.offset !== undefined;
-  if (hasOffset && request.target)
-    throw new DocumentApiAdapterError("INVALID_TARGET", "Cannot combine target with offset on insert request.", { fields: ["target", "offset"] });
-  if (hasOffset && !hasBlockId)
-    throw new DocumentApiAdapterError("INVALID_TARGET", "offset requires blockId on insert request.", { fields: ["offset", "blockId"] });
-  if (!hasBlockId)
-    return request;
-  if (request.target)
-    throw new DocumentApiAdapterError("INVALID_TARGET", "Cannot combine target with blockId on insert request.", { fields: ["target", "blockId"] });
-  const effectiveOffset = request.offset ?? 0;
-  return {
-    kind: "insert",
-    target: {
-      kind: "text",
-      blockId: request.blockId,
-      range: {
-        start: effectiveOffset,
-        end: effectiveOffset
-      }
-    },
-    text: request.text
-  };
-}
 function mapPlanReceiptToTextReceipt(_receipt, resolution) {
   return {
     success: true,
@@ -178902,11 +178974,10 @@ function writeWrapper(editor, request, options) {
   const runtime = resolveWriteStoryRuntime(editor, request.in);
   try {
     const storyEditor = runtime.editor;
-    const normalizedRequest = normalizeWriteLocator(request);
-    const resolved = resolveWriteTarget(storyEditor, normalizedRequest);
+    const resolved = resolveWriteTarget(storyEditor, request);
     if (!resolved)
-      throw new DocumentApiAdapterError("TARGET_NOT_FOUND", "Mutation target could not be resolved.", { target: normalizedRequest.target });
-    const validationFailure = validateWriteRequest(normalizedRequest, resolved);
+      throw new DocumentApiAdapterError("TARGET_NOT_FOUND", "Mutation target could not be resolved.", {});
+    const validationFailure = validateWriteRequest(request, resolved);
     if (validationFailure)
       return {
         success: false,
@@ -178923,7 +178994,7 @@ function writeWrapper(editor, request, options) {
       };
     if (resolved.structuralEnd) {
       const insertPos = resolved.range.from;
-      const text5 = normalizedRequest.text ?? "";
+      const text5 = request.text ?? "";
       const receipt$1 = executeDomainCommand(storyEditor, () => {
         insertParagraphAtEnd(storyEditor, insertPos, text5, mode === "tracked" ? applyTrackedMutationMeta : applyDirectMutationMeta);
         return true;
@@ -178941,7 +179012,7 @@ function writeWrapper(editor, request, options) {
           where: STUB_WHERE,
           args: {
             position: "before",
-            content: { text: normalizedRequest.text ?? "" }
+            content: { text: request.text ?? "" }
           }
         },
         targets: [toCompiledTarget(stepId, "text.insert", resolved)]
@@ -179003,6 +179074,16 @@ function buildSelectionStepDef(stepId, request, where) {
           style: { inline: { mode: "preserve" } }
         }
       };
+    case "insert":
+      return {
+        id: stepId,
+        op: "text.insert",
+        where,
+        args: {
+          position: "before",
+          content: { text: request.text }
+        }
+      };
     case "format":
       return {
         id: stepId,
@@ -179027,12 +179108,52 @@ function selectionMutationWrapper(editor, request, options) {
     }
     const stepId = v4_default();
     const compiled = compilePlan(storyEditor, [buildSelectionStepDef(stepId, request, buildSelectionWhere(request))]);
+    if (request.kind === "insert" && request.target) {
+      if (request.target.start.kind === "nodeEdge" || request.target.end.kind === "nodeEdge")
+        throw new DocumentApiAdapterError("INVALID_TARGET", "Text inserts do not support nodeEdge targets. Use a text-offset target inside a textblock.");
+    }
+    if (request.kind === "insert") {
+      const target = compiled.mutationSteps.find((s2) => s2.step.id === stepId)?.targets[0];
+      if (target) {
+        if (target.kind === "span")
+          return {
+            success: false,
+            resolution: buildSelectionResolutionFromCompiled(compiled, stepId),
+            failure: {
+              code: "INVALID_TARGET",
+              message: "Insert operations require a single-block target, not a multi-segment span."
+            }
+          };
+        if (target.kind === "range") {
+          if (!storyEditor.state.doc.resolve(target.absFrom).parent.isTextblock)
+            return {
+              success: false,
+              resolution: buildSelectionResolutionFromCompiled(compiled, stepId),
+              failure: {
+                code: "INVALID_TARGET",
+                message: "Text insert target must be inside a textblock."
+              }
+            };
+        }
+      }
+    }
     checkRevision(storyEditor, options?.expectedRevision);
-    if (options?.dryRun)
+    if (options?.dryRun) {
+      const resolution$1 = buildSelectionResolutionFromCompiled(compiled, stepId);
+      if (request.kind === "insert" && !request.text)
+        return {
+          success: false,
+          resolution: resolution$1,
+          failure: {
+            code: "NO_OP",
+            message: "Insert text is empty."
+          }
+        };
       return {
         success: true,
-        resolution: buildSelectionResolutionFromCompiled(compiled, stepId)
+        resolution: resolution$1
       };
+    }
     const stepOutcome = executeCompiledPlan(storyEditor, compiled, {
       changeMode: mode,
       expectedRevision: options?.expectedRevision
@@ -179173,17 +179294,68 @@ function insertStructuredInner(editor, input2, options) {
   if (isStructuralInsertInput2(input2))
     return executeStructuralInsertWrapper(editor, input2, options);
   const contentType = input2.type ?? "text";
-  const { value, target } = input2;
+  const { value, target, ref: ref$1 } = input2;
   if ((options?.changeMode ?? "direct") === "tracked")
     throw new DocumentApiAdapterError("CAPABILITY_UNAVAILABLE", `Tracked mode is not supported for type: '${contentType}' insert operations.`);
   let resolvedRange;
   let effectiveTarget;
+  if (ref$1 !== undefined && ref$1 === "")
+    throw new DocumentApiAdapterError("INVALID_TARGET", "ref must be a non-empty string.", { ref: ref$1 });
   if (target) {
-    const range = resolveTextTarget(editor, target);
-    if (!range)
-      throw new DocumentApiAdapterError("TARGET_NOT_FOUND", "Structured insert target could not be resolved.", { target });
-    resolvedRange = range;
-    effectiveTarget = target;
+    const resolved = resolveSelectionTarget(editor, target);
+    resolvedRange = {
+      from: resolved.absFrom,
+      to: resolved.absTo
+    };
+    const startPoint = target.start;
+    const blockId = startPoint.kind === "text" ? startPoint.blockId : startPoint.node.nodeId;
+    let offset$1;
+    if (startPoint.kind === "text")
+      offset$1 = startPoint.offset;
+    else if (startPoint.edge === "after")
+      offset$1 = nodeEdgeAfterOffset(editor, startPoint.node.nodeType, startPoint.node.nodeId);
+    else
+      offset$1 = 0;
+    effectiveTarget = {
+      kind: "text",
+      blockId,
+      range: {
+        start: offset$1,
+        end: offset$1
+      }
+    };
+  } else if (ref$1) {
+    const dummyStepId = v4_default();
+    const compiled = compilePlan(editor, [{
+      id: dummyStepId,
+      op: "text.insert",
+      where: {
+        by: "ref",
+        ref: ref$1
+      },
+      args: {
+        position: "before",
+        content: { text: "" }
+      }
+    }]);
+    const compiledTarget = compiled.mutationSteps.find((s2) => s2.step.id === dummyStepId)?.targets[0];
+    if (!compiledTarget)
+      throw new DocumentApiAdapterError("TARGET_NOT_FOUND", "Structured insert ref could not be resolved.", { ref: ref$1 });
+    if (compiledTarget.kind === "span")
+      throw new DocumentApiAdapterError("INVALID_TARGET", "Insert operations require a single-block ref. Multi-segment refs are not supported.", { ref: ref$1 });
+    resolvedRange = {
+      from: compiledTarget.absFrom,
+      to: compiledTarget.absFrom
+    };
+    const refTarget = buildSelectionResolutionFromCompiled(compiled, dummyStepId).target;
+    effectiveTarget = {
+      kind: "text",
+      blockId: refTarget.blockId,
+      range: {
+        start: refTarget.range.start,
+        end: refTarget.range.start
+      }
+    };
   } else {
     const fallback = resolveDefaultInsertTarget(editor);
     if (!fallback)
@@ -179208,13 +179380,13 @@ function insertStructuredInner(editor, input2, options) {
     }
   }
   const resolution = buildTextMutationResolution({
-    requestedTarget: target,
+    requestedTarget: effectiveTarget,
     target: effectiveTarget,
     range: resolvedRange,
     text: readTextAtResolvedRange(editor, resolvedRange)
   });
   const { from: from$1, to } = resolvedRange;
-  if (from$1 !== to)
+  if (target && from$1 !== to)
     return {
       success: false,
       resolution,
@@ -231390,9 +231562,9 @@ var Node$13 = class Node$14 {
     return;
   console.log(...args$1);
 }, HEADER_FOOTER_INIT_BUDGET_MS = 200, MAX_ZOOM_WARNING_THRESHOLD = 10, MAX_SELECTION_RECTS_PER_USER = 100, SEMANTIC_RESIZE_DEBOUNCE_MS = 120, MIN_SEMANTIC_CONTENT_WIDTH_PX = 1, GLOBAL_PERFORMANCE, PresentationEditor, ICONS, TEXTS, tableActionsOptions;
-var init_src_D389XrYP_es = __esm(() => {
+var init_src_BrT7SmAZ_es = __esm(() => {
   init_rolldown_runtime_B2q5OVn9_es();
-  init_SuperConverter_Cukh7tk8_es();
+  init_SuperConverter_C65zRR3r_es();
   init_jszip_ChlR43oI_es();
   init_uuid_qzgm05fK_es();
   init_constants_ep1_Gwqi_es();
@@ -264697,8 +264869,8 @@ var init_zipper_DqXT7uTa_es = __esm(() => {
 
 // ../../packages/superdoc/dist/super-editor.es.js
 var init_super_editor_es = __esm(() => {
-  init_src_D389XrYP_es();
-  init_SuperConverter_Cukh7tk8_es();
+  init_src_BrT7SmAZ_es();
+  init_SuperConverter_C65zRR3r_es();
   init_jszip_ChlR43oI_es();
   init_xml_js_BtmJ6bNs_es();
   init_constants_ep1_Gwqi_es();
@@ -320035,10 +320207,11 @@ function normalizeFlatTargetFlags(operationId, apiInput) {
   if (SELECTION_TARGET_OPERATIONS.has(operationId)) {
     const blockId = apiInput.blockId;
     if (typeof blockId === "string") {
-      const start3 = typeof apiInput.start === "number" ? apiInput.start : 0;
-      const end2 = typeof apiInput.end === "number" ? apiInput.end : 0;
+      const hasOffset = typeof apiInput.offset === "number";
+      const start3 = typeof apiInput.start === "number" ? apiInput.start : hasOffset ? apiInput.offset : 0;
+      const end2 = typeof apiInput.end === "number" ? apiInput.end : hasOffset ? apiInput.offset : 0;
       assertLegacySelectionTargetSupported(operationId, { range: { start: start3, end: end2 } });
-      const { blockId: _2, start: _s, end: _e, ...rest } = apiInput;
+      const { blockId: _2, start: _s, end: _e, offset: _o, ...rest } = apiInput;
       return {
         ...rest,
         target: textAddressToSelectionTarget({ blockId, range: { start: start3, end: end2 } })
@@ -320059,18 +320232,6 @@ function normalizeFlatTargetFlags(operationId, apiInput) {
     }
     return apiInput;
   }
-  if (operationId === INSERT_OPERATION) {
-    const blockId = apiInput.blockId;
-    if (typeof blockId === "string") {
-      const offset3 = typeof apiInput.offset === "number" ? apiInput.offset : 0;
-      const { blockId: _2, offset: _o, ...rest } = apiInput;
-      return {
-        ...rest,
-        target: { kind: "text", blockId, range: { start: offset3, end: offset3 } }
-      };
-    }
-    return apiInput;
-  }
   if (operationId === "blocks.delete") {
     const nodeType2 = apiInput.nodeType;
     const nodeId = apiInput.nodeId;
@@ -320112,7 +320273,7 @@ function extractInvokeInput(operationId, cliInput) {
   }
   return normalizeFlatTargetFlags(operationId, apiInput);
 }
-var WRAPPED_INPUT_KEY, PARAM_RENAMES, CLI_LEVEL_KEYS, CHANGEMODE_IN_INPUT, FORMAT_TARGET_OPERATIONS, SELECTION_TARGET_OPERATIONS, TEXT_ADDRESS_TARGET_OPERATIONS, INSERT_OPERATION = "insert", LIST_TARGET_OPERATIONS;
+var WRAPPED_INPUT_KEY, PARAM_RENAMES, CLI_LEVEL_KEYS, CHANGEMODE_IN_INPUT, FORMAT_TARGET_OPERATIONS, SELECTION_TARGET_OPERATIONS, TEXT_ADDRESS_TARGET_OPERATIONS, LIST_TARGET_OPERATIONS;
 var init_invoke_input = __esm(() => {
   init_errors();
   init_operation_set();
@@ -320159,7 +320320,12 @@ var init_invoke_input = __esm(() => {
   CLI_LEVEL_KEYS = new Set(["doc", "sessionId", "out", "dryRun", "force", "expectedRevision", "changeMode"]);
   CHANGEMODE_IN_INPUT = new Set(["mutations.apply", "mutations.preview"]);
   FORMAT_TARGET_OPERATIONS = CLI_DOC_OPERATIONS.filter((operationId) => operationId.startsWith("format."));
-  SELECTION_TARGET_OPERATIONS = new Set(["replace", "delete", ...FORMAT_TARGET_OPERATIONS]);
+  SELECTION_TARGET_OPERATIONS = new Set([
+    "insert",
+    "replace",
+    "delete",
+    ...FORMAT_TARGET_OPERATIONS
+  ]);
   TEXT_ADDRESS_TARGET_OPERATIONS = new Set(["comments.create", "comments.patch"]);
   LIST_TARGET_OPERATIONS = new Set([
     "lists.insert",
@@ -321388,7 +321554,7 @@ function deriveOptionSpecs(operationId, params4) {
   }
   return specs;
 }
-var DOC_PARAM, SESSION_PARAM, OUT_PARAM, FORCE_PARAM, DRY_RUN_PARAM, CHANGE_MODE_PARAM, EXPECTED_REVISION_PARAM, USER_NAME_PARAM, USER_EMAIL_PARAM, AGENT_HIDDEN_PARAM_NAMES, OPERATION_CONSTRAINTS, PARAM_FLAG_OVERRIDES, PARAM_SCHEMA_OVERRIDES, PARAM_EXCLUSIONS, TEXT_TARGET_FLAT_PARAMS, INSERT_FLAT_PARAMS, LIST_TARGET_FLAT_PARAMS, FORMAT_OPERATION_IDS, EXTRA_CLI_PARAMS, CLI_ONLY_METADATA, CLI_OPERATION_METADATA, OPTION_FLAG_ALIASES, CLI_OPERATION_OPTION_SPECS;
+var DOC_PARAM, SESSION_PARAM, OUT_PARAM, FORCE_PARAM, DRY_RUN_PARAM, CHANGE_MODE_PARAM, EXPECTED_REVISION_PARAM, USER_NAME_PARAM, USER_EMAIL_PARAM, AGENT_HIDDEN_PARAM_NAMES, OPERATION_CONSTRAINTS, PARAM_FLAG_OVERRIDES, PARAM_SCHEMA_OVERRIDES, PARAM_EXCLUSIONS, TEXT_TARGET_FLAT_PARAMS, LIST_TARGET_FLAT_PARAMS, FORMAT_OPERATION_IDS, EXTRA_CLI_PARAMS, CLI_ONLY_METADATA, CLI_OPERATION_METADATA, OPTION_FLAG_ALIASES, CLI_OPERATION_OPTION_SPECS;
 var init_operation_params = __esm(() => {
   init_src();
   init_commands();
@@ -321493,10 +321659,6 @@ var init_operation_params = __esm(() => {
     { name: "start", kind: "flag", type: "number", description: "Start offset within the block (character index)." },
     { name: "end", kind: "flag", type: "number", description: "End offset within the block (character index)." }
   ];
-  INSERT_FLAT_PARAMS = [
-    { name: "blockId", kind: "flag", flag: "block-id", type: "string", description: "Block ID of the target paragraph." },
-    { name: "offset", kind: "flag", type: "number", description: "Character offset within the block for insertion." }
-  ];
   LIST_TARGET_FLAT_PARAMS = [
     { name: "nodeId", kind: "flag", flag: "node-id", type: "string", description: "Node ID of the target list item." }
   ];
@@ -321545,7 +321707,15 @@ var init_operation_params = __esm(() => {
         description: "Node address to retrieve (block or inline address object)."
       }
     ],
-    "doc.insert": [...INSERT_FLAT_PARAMS],
+    "doc.insert": [
+      ...TEXT_TARGET_FLAT_PARAMS,
+      {
+        name: "offset",
+        kind: "flag",
+        type: "number",
+        description: "Character offset for insertion (alias for --start/--end with same value)."
+      }
+    ],
     "doc.replace": [...TEXT_TARGET_FLAT_PARAMS],
     "doc.delete": [...TEXT_TARGET_FLAT_PARAMS],
     "doc.styles.apply": [
@@ -322564,7 +322734,7 @@ function acceptsLegacyTextAddressTarget(operationId, param, value2) {
   if (param.name !== "target" || !isTextAddressLike2(value2))
     return false;
   const docApiId = toDocApiId(operationId);
-  return docApiId === "replace" || docApiId === "delete" || docApiId?.startsWith("format.") === true;
+  return docApiId === "insert" || docApiId === "replace" || docApiId === "delete" || docApiId?.startsWith("format.") === true;
 }
 function extractConstValues(variants) {
   const values2 = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdoc-dev/cli",
-  "version": "0.3.0-next.55",
+  "version": "0.3.0-next.56",
   "type": "module",
   "bin": {
     "superdoc": "./dist/index.js"
@@ -20,21 +20,21 @@
     "@types/bun": "^1.3.8",
     "@types/node": "22.19.2",
     "typescript": "^5.9.2",
-    "@superdoc/document-api": "0.0.1",
-    "@superdoc/super-editor": "0.0.1",
+    "@superdoc/pm-adapter": "0.0.0",
     "superdoc": "1.20.0",
-    "@superdoc/pm-adapter": "0.0.0"
+    "@superdoc/super-editor": "0.0.1",
+    "@superdoc/document-api": "0.0.1"
   },
   "module": "src/index.ts",
   "publishConfig": {
     "access": "public"
   },
   "optionalDependencies": {
-    "@superdoc-dev/cli-darwin-arm64": "0.3.0-next.55",
-    "@superdoc-dev/cli-darwin-x64": "0.3.0-next.55",
-    "@superdoc-dev/cli-linux-x64": "0.3.0-next.55",
-    "@superdoc-dev/cli-linux-arm64": "0.3.0-next.55",
-    "@superdoc-dev/cli-windows-x64": "0.3.0-next.55"
+    "@superdoc-dev/cli-darwin-arm64": "0.3.0-next.56",
+    "@superdoc-dev/cli-darwin-x64": "0.3.0-next.56",
+    "@superdoc-dev/cli-linux-x64": "0.3.0-next.56",
+    "@superdoc-dev/cli-linux-arm64": "0.3.0-next.56",
+    "@superdoc-dev/cli-windows-x64": "0.3.0-next.56"
   },
   "scripts": {
     "predev": "node scripts/ensure-superdoc-build.js",