@superdoc/mcp 1.9.0-next.11 → 1.9.0-next.13

package/dist/index.js

@@ -31620,7 +31620,7 @@ var init_host = __esm(() => {
 });
 
 // ../../packages/sdk/langs/node/src/runtime/sdk-version.generated.ts
-var SDK_VERSION = "2.22.0-next.11";
+var SDK_VERSION = "2.22.0-next.13";
 
 // ../../packages/sdk/langs/node/src/runtime/embedded-platform.ts
 import { accessSync, chmodSync, constants, existsSync, statSync } from "node:fs";
@@ -87423,10 +87423,10 @@ var init_action_descriptors = __esm(() => {
       operations: ["create.heading"]
     },
     replace_text: {
-      hint: "edits[{find,replace}], optional selector to scope replacements to one inspected block, caseSensitive?, changeMode? — for EDITING existing wording only; the replaced span is rewritten as PLAIN text (intra-span bold/italic is dropped), so keep find/replace spans MINIMAL (the words that change, not the whole paragraph) and NEVER use it to append a new sentence/clause/paragraph (use insert_paragraphs)",
+      hint: "edits[{find,replace,occurrence?}], optional selector to scope replacements to one inspected block, caseSensitive?, expectedRevision?, changeMode? — for EDITING existing wording only; keep find/replace spans MINIMAL (the words that change, not the whole paragraph). When the find appears more than once in the selected block and only one should change, set that edit's occurrence (1-based match number within the block; requires selector; this is not selector.occurrence, which picks a block). NEVER use it to append a new sentence/clause/paragraph (use insert_paragraphs)",
       group: "Text/structure actions",
       groupOrder: 2,
-      args: ["edits", "selector", "caseSensitive", "changeMode"],
+      args: ["edits", "selector", "caseSensitive", "expectedRevision", "changeMode"],
       operations: ["replace"]
     },
     delete_text: {
@@ -93107,12 +93107,10 @@ function normalizeTitleLikeRewriteText(targetText, rewrittenText) {
   const displayTitle = toDisplayTitleCase(targetText);
   if (rewrittenText.includes(displayTitle))
     return rewrittenText;
-  const lowerTarget = targetText.toLocaleLowerCase();
-  const lowerRewrite = rewrittenText.toLocaleLowerCase();
-  const index = lowerRewrite.indexOf(lowerTarget);
-  if (index < 0)
+  const match = findRanges(rewrittenText, targetText, false)[0];
+  if (!match)
     return rewrittenText;
-  return `${rewrittenText.slice(0, index)}${displayTitle}${rewrittenText.slice(index + targetText.length)}`;
+  return `${rewrittenText.slice(0, match.start)}${displayTitle}${rewrittenText.slice(match.end)}`;
 }
 async function executeCreateParagraph(doc2, text, placement, changeMode) {
   const fn = maybeMethod2(doc2, ["create", "paragraph"]);
@@ -93417,6 +93415,7 @@ async function runReplaceTextUnchecked(doc2, args) {
   const preIdentity = requiresBlockSnapshot ? null : await readDocumentIdentity(doc2);
   const pre = requiresBlockSnapshot ? await buildMutationSnapshot(doc2, { includeDomains: selectorDomains ?? ["blocks"] }) : snapshotFromIdentity(preIdentity);
   try {
+    assertExpectedReplacementRevision(args.expectedRevision, pre.revision);
     assertReplacementTextPayloads(args.edits);
     if (args.edits.length === 0) {
       return failedReceipt("replace_text", new Error("edits must be non-empty"), pre);
@@ -93425,7 +93424,7 @@ async function runReplaceTextUnchecked(doc2, args) {
     const selectedTargets = [];
     let skippedEdits = [];
     let steps;
-    let applyExpectedRevision;
+    let applyExpectedRevision = args.expectedRevision != null ? pre.revision : undefined;
     if (args.selector) {
       const target = selectorToBlockTarget(args.selector, pre);
       if (!target) {
@@ -95411,18 +95410,25 @@ function findRanges(haystack, needle, caseSensitive) {
   const ranges = [];
   if (needle.length === 0)
     return ranges;
-  const source = caseSensitive ? haystack : haystack.toLocaleLowerCase();
-  const target = caseSensitive ? needle : needle.toLocaleLowerCase();
-  let offset = 0;
-  while (offset < source.length) {
-    const idx = source.indexOf(target, offset);
-    if (idx < 0)
-      break;
-    ranges.push({ start: idx, end: idx + target.length });
-    offset = idx + target.length;
+  if (caseSensitive) {
+    let offset = 0;
+    while (offset < haystack.length) {
+      const idx = haystack.indexOf(needle, offset);
+      if (idx < 0)
+        break;
+      ranges.push({ start: idx, end: idx + needle.length });
+      offset = idx + needle.length;
+    }
+    return ranges;
+  }
+  for (const match of haystack.matchAll(caseInsensitivePattern(needle))) {
+    ranges.push({ start: match.index, end: match.index + match[0].length });
   }
   return ranges;
 }
+function caseInsensitivePattern(needle) {
+  return new RegExp(needle.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "giu");
+}
 async function runApplyLetterSpacing(doc2, args) {
   const pre = await buildMutationSnapshot(doc2, { includeDomains: ["blocks"] });
   try {
@@ -96168,29 +96174,59 @@ function trackedChangeRefIds(result) {
     return entityId ? [entityId] : [];
   }));
 }
-function parseScopedReplaceArgs(args, changeMode) {
-  if (args.action !== "replace_text")
-    return null;
+function parseScopedReplaceArgs(args, edits, changeMode, expectedRevision) {
   if (!isRecord2(args.selector))
     return null;
-  if (!Array.isArray(args.edits) || args.edits.length === 0)
-    return null;
-  const edits = [];
-  for (const entry of args.edits) {
-    if (!isRecord2(entry) || typeof entry.find !== "string" || entry.find.length === 0)
-      return null;
-    edits.push({ find: entry.find, replace: typeof entry.replace === "string" ? entry.replace : "" });
-  }
   return {
     edits,
     selector: args.selector,
     caseSensitive: args.caseSensitive === true,
+    expectedRevision,
     changeMode
   };
 }
+function assertExpectedReplacementRevision(expected, actual) {
+  if (expected != null && expected !== actual) {
+    throw new SuperDocCliError("replace_text: expectedRevision is stale. Inspect this live document again before editing.", {
+      code: "REVISION_CONFLICT"
+    });
+  }
+}
+async function fieldResultRanges(doc2, nodeId, blockText) {
+  const fn = maybeMethod2(doc2, ["fields", "list"]);
+  if (!fn)
+    return null;
+  const results = [];
+  const limit = 500;
+  for (let offset = 0;offset < 1e5; offset += limit) {
+    const page = await fn({ limit, offset });
+    const items = isRecord2(page) && Array.isArray(page.items) ? page.items.filter(isRecord2) : [];
+    for (const item of items) {
+      const address = isRecord2(item.address) ? item.address : null;
+      const inBody = typeof address?.storyId !== "string" || address.storyId.startsWith("main:");
+      if (address?.blockId !== nodeId || !inBody)
+        continue;
+      if (typeof item.resolvedText !== "string" || item.resolvedText.length === 0) {
+        return [{ start: 0, end: blockText.length }];
+      }
+      results.push(item.resolvedText);
+    }
+    const total = isRecord2(page) && typeof page.total === "number" ? page.total : null;
+    if (items.length < limit || total != null && offset + limit >= total)
+      break;
+  }
+  const ranges = [];
+  for (const result of results) {
+    for (let at = blockText.indexOf(result);at >= 0; at = blockText.indexOf(result, at + 1)) {
+      ranges.push({ start: at, end: at + result.length });
+    }
+  }
+  return ranges;
+}
 async function runScopedReplaceUnchecked(doc2, args) {
   assertReplacementTextPayloads(args.edits);
   const pre = await buildMutationSnapshot(doc2, { includeDomains: ["blocks", "tables"] });
+  assertExpectedReplacementRevision(args.expectedRevision, pre.revision);
   const matched = resolveSnapshotSelector(pre, args.selector);
   if (matched.length !== 1) {
     const failure2 = describeSelectorFailure(args.selector, matched, pre, args.edits.map((e) => e.find));
@@ -96210,13 +96246,22 @@ async function runScopedReplaceUnchecked(doc2, args) {
     };
   }
   const caseSensitive = args.caseSensitive === true;
+  const hasExplicitOccurrence = args.edits.some((edit) => edit.occurrence != null);
   const perEdit = [];
   const allSpans = [];
   for (const edit of args.edits) {
-    const spans = findRanges(block.text, edit.find, caseSensitive);
-    perEdit.push({ find: edit.find, occurrences: spans.length });
+    const matches = findRanges(block.text, edit.find, caseSensitive);
+    const spans = edit.occurrence == null ? matches : matches.slice(edit.occurrence - 1, edit.occurrence);
+    if (hasExplicitOccurrence && spans.length === 0) {
+      return failedReceipt("replace_text", new SuperDocCliError(edit.occurrence == null ? `replace_text: ${JSON.stringify(edit.find)} not found in the selected block. Inspect and choose a valid target.` : `replace_text: ${JSON.stringify(edit.find)} occurrence ${edit.occurrence} not found in the selected block (${matches.length} matches). Inspect and choose a valid target.`, { code: "MATCH_NOT_FOUND" }), pre);
+    }
+    perEdit.push({
+      find: edit.find,
+      occurrences: spans.length,
+      ...edit.occurrence != null ? { occurrence: edit.occurrence } : {}
+    });
     for (const span of spans)
-      allSpans.push({ ...span, replace: edit.replace ?? "", find: edit.find });
+      allSpans.push({ ...span, replace: edit.replace, find: edit.find });
   }
   const appliedEdits = perEdit.filter((e) => e.occurrences > 0);
   const skippedEdits = perEdit.filter((e) => e.occurrences === 0);
@@ -96241,6 +96286,9 @@ async function runScopedReplaceUnchecked(doc2, args) {
   let lastEnd = -1;
   for (const span of allSpans) {
     if (span.start < lastEnd) {
+      if (hasExplicitOccurrence) {
+        return failedReceipt("replace_text", new SuperDocCliError("replace_text: explicit occurrence targets overlap. Choose non-overlapping edits in the pre-edit block.", { code: "INVALID_ARGUMENT" }), pre);
+      }
       droppedOverlaps.push(span);
       continue;
     }
@@ -96249,24 +96297,45 @@ async function runScopedReplaceUnchecked(doc2, args) {
   }
   const expected = planned.reduceRight((text, span) => text.slice(0, span.start) + span.replace + text.slice(span.end), block.text);
   const tracked = (args.changeMode ?? "direct") === "tracked";
-  let result = null;
   const uniqueFinds = new Set(planned.map((s) => caseSensitive ? s.find : s.find.toLowerCase()));
-  if (tracked && uniqueFinds.size === planned.length) {
-    const spanSteps = planned.map((span, index) => ({
+  const deletions = tracked ? [] : planned.filter((span) => span.replace.length === 0);
+  const fieldRanges = deletions.length > 0 ? await fieldResultRanges(doc2, nodeId, block.text) : [];
+  const fieldDeletionRisk = fieldRanges == null || deletions.some((span) => fieldRanges.some((range) => span.start < range.end && span.end > range.start));
+  const exactTargets = !fieldDeletionRisk && (hasExplicitOccurrence || tracked && uniqueFinds.size === planned.length);
+  let result = null;
+  let wroteExactTargets = false;
+  if (exactTargets) {
+    const targetedSpans = [...planned].reverse().filter((span) => block.text.slice(span.start, span.end) !== span.replace);
+    const steps = targetedSpans.map((span, index) => ({
       id: `scoped-replace-${index + 1}`,
       op: "text.rewrite",
       where: {
-        by: "select",
-        select: { type: "text", pattern: span.find, mode: "contains", caseSensitive },
-        require: "first",
-        within: { kind: "block", nodeType: block.nodeType, nodeId }
+        by: "target",
+        target: {
+          kind: "selection",
+          start: { kind: "text", blockId: nodeId, offset: span.start },
+          end: { kind: "text", blockId: nodeId, offset: span.end }
+        }
       },
       args: { replacement: { text: span.replace }, style: preserveRewriteStyle() }
     }));
-    try {
-      result = await executeMutations(doc2, spanSteps, args.changeMode, pre.revision);
-    } catch {
-      result = null;
+    if (steps.length === 0) {
+      result = { noop: true };
+    } else {
+      const preview = await previewMutations(doc2, steps, args.changeMode, pre.revision);
+      const previewSteps = Array.isArray(preview.steps) ? preview.steps.filter(isRecord2) : [];
+      const aligned = preview.valid === true && steps.every((step, index) => {
+        const resolutions = previewSteps.find((candidate) => candidate.stepId === step.id)?.resolutions;
+        const resolved = Array.isArray(resolutions) && isRecord2(resolutions[0]) ? resolutions[0].text : undefined;
+        const span = targetedSpans[index];
+        return resolved === block.text.slice(span.start, span.end);
+      });
+      if (aligned) {
+        result = await executeMutations(doc2, steps, args.changeMode, pre.revision);
+        wroteExactTargets = true;
+      } else if (hasExplicitOccurrence) {
+        return failedReceipt("replace_text", new SuperDocCliError("replace_text: the chosen occurrence does not resolve to the same text in the document. Inspect again before editing.", { code: "TARGET_NOT_FOUND" }), pre);
+      }
     }
   }
   if (result == null) {
@@ -96280,9 +96349,20 @@ async function runScopedReplaceUnchecked(doc2, args) {
     ];
     result = await executeMutations(doc2, steps, args.changeMode, pre.revision);
   }
-  const post = await buildMutationSnapshot(doc2, { includeDomains: ["blocks", "tables"] });
-  const postBlock = findTextTarget(post, nodeId);
-  const passed = postBlock != null && (tracked ? planned.every((span) => span.replace.length === 0 || postBlock.text.includes(span.replace)) : postBlock.text === expected);
+  let post = await buildMutationSnapshot(doc2, { includeDomains: ["blocks", "tables"] });
+  let postBlock = findTextTarget(post, nodeId);
+  let rolledBack = false;
+  const appliedRevision = isRecord2(result) && isRecord2(result.revision) ? result.revision.after : undefined;
+  if (wroteExactTargets && postBlock != null && postBlock.text !== expected && postBlock.text !== block.text && typeof appliedRevision === "string" && appliedRevision === post.revision) {
+    const undoFn = maybeMethod2(doc2, ["history", "undo"]);
+    if (undoFn) {
+      await undoFn({});
+      post = await buildMutationSnapshot(doc2, { includeDomains: ["blocks", "tables"] });
+      postBlock = findTextTarget(post, nodeId);
+      rolledBack = postBlock?.text === block.text;
+    }
+  }
+  const passed = postBlock != null && !rolledBack && (tracked && !hasExplicitOccurrence && !wroteExactTargets ? planned.every((span) => span.replace.length === 0 || postBlock.text.includes(span.replace)) : postBlock.text === expected);
   const status = !passed ? "failed" : skippedEdits.length > 0 ? "partial" : "ok";
   return {
     status,
@@ -96291,6 +96371,14 @@ async function runScopedReplaceUnchecked(doc2, args) {
       nextStep: `${skippedEdits.length} of ${perEdit.length} edits were NOT applied — the find text is not in the selected block. ` + `Do not stop: call replace_text again for the remaining edits with a different selector (or no selector for a global replace).`,
       recovery: { kind: "retry" }
     } : {},
+    ...rolledBack ? {
+      errors: [
+        {
+          code: "ACTION_FAILED",
+          message: "replace_text: the engine changed more than the requested text, so the edit was undone. Inspect the block and retry with a larger find or rewrite the whole block."
+        }
+      ]
+    } : {},
     preSnapshot: { revision: pre.revision },
     postSnapshot: { revision: post.revision },
     selectedBlock: { nodeId, nodeType: block.nodeType },
@@ -97622,8 +97710,17 @@ async function dispatchSuperdocPerformAction(doc2, args) {
           code: "INVALID_ARGUMENT"
         });
       }
+      const expectedRevision = args.expectedRevision;
+      if (expectedRevision !== undefined && (typeof expectedRevision !== "string" || expectedRevision.length === 0)) {
+        throw new SuperDocCliError("replace_text: expectedRevision must be a non-empty string from this live document handle", { code: "INVALID_ARGUMENT" });
+      }
+      if (edits.some((edit) => edit.occurrence != null) && !isRecord2(args.selector)) {
+        throw new SuperDocCliError("replace_text: explicit occurrence requires a selector resolving to one block", {
+          code: "INVALID_ARGUMENT"
+        });
+      }
       const changeMode = parseReplaceTextChangeMode(args.changeMode);
-      const scoped = parseScopedReplaceArgs(args, changeMode);
+      const scoped = parseScopedReplaceArgs(args, edits, changeMode, expectedRevision);
       if (scoped) {
         return runScopedReplace(doc2, scoped);
       }
@@ -97636,6 +97733,7 @@ async function dispatchSuperdocPerformAction(doc2, args) {
         edits,
         selector,
         caseSensitive: args.caseSensitive === true,
+        expectedRevision,
         changeMode
       });
     }
@@ -98281,7 +98379,11 @@ function parseEdits2(value) {
     const replace = asString2(entry.replace) ?? "";
     if (!find)
       return;
-    result.push({ find, replace });
+    const occurrence = entry.occurrence;
+    if (occurrence !== undefined && (typeof occurrence !== "number" || !Number.isSafeInteger(occurrence) || occurrence < 1)) {
+      throw new SuperDocCliError("replace_text: occurrence must be a positive safe integer (one-based within the selected block)", { code: "INVALID_ARGUMENT" });
+    }
+    result.push({ find, replace, ...occurrence !== undefined ? { occurrence } : {} });
   }
   return result;
 }
@@ -98743,10 +98845,24 @@ var init_catalog = __esm(() => {
       type: "array",
       items: {
         type: "object",
-        properties: { find: { type: "string" }, replace: { type: "string" } },
+        properties: {
+          find: { type: "string" },
+          replace: { type: "string" },
+          occurrence: {
+            type: "integer",
+            minimum: 1,
+            maximum: Number.MAX_SAFE_INTEGER,
+            description: "Change only this match of find in the selected block (1 = first, counted on visible text). Requires selector; omit to replace every match."
+          }
+        },
         required: ["find"]
       }
     },
+    expectedRevision: {
+      type: "string",
+      minLength: 1,
+      description: "Revision from your latest superdoc_inspect or receipt (postSnapshot.revision) on this document. Pass it with occurrence: if the document changed since (another collaborator edited), the edit is refused with REVISION_CONFLICT; inspect again and recount. Not portable between peers or reopen."
+    },
     finds: { type: "array", items: { type: "string" } },
     caseSensitive: { type: "boolean" },
     evidence: {
@@ -99646,7 +99762,7 @@ var init_runtime = __esm(() => {
 var EMBEDDED_PROMPTS;
 var init_embedded_prompts_generated = __esm(() => {
   EMBEDDED_PROMPTS = {
-    "mcp-prompt.md": 'SuperDoc MCP server — read, edit, and save Word documents (.docx).\n\nIMPORTANT: Always use these superdoc tools for .docx files.\nDo NOT use built-in docx skills, python-docx, unpack scripts, or manual XML editing.\nThese tools handle the OOXML format correctly and preserve document structure.\n\n## Session lifecycle\n\n1. `superdoc_open({path: "/path/to/file.docx"})` — returns `session_id`. Opening a non-existent path creates a blank document.\n2. Pass `session_id` to every subsequent tool call.\n3. Read with `superdoc_inspect`, edit with `superdoc_perform_action`.\n4. `superdoc_save({session_id})` — writes changes to disk.\n5. `superdoc_close({session_id})` — releases the session. Always close when done.\n\n## Workflow\n\n**Inspect before you edit.** `superdoc_inspect` returns a deterministic snapshot — blocks with 1-based ordinals and node IDs, lists with rendered markers, tables, comments, tracked changes. Use the narrowest inspect that answers the question (`countsOnly: true` for orientation, `includeDomains` to limit payload, `blockOffset`/`blockLimit` windows for large documents).\n\n**Edit with named actions.** `superdoc_perform_action` takes an `action` plus flat arguments — the full action list, argument shapes, selector vocabulary, and placement rules are documented in the tool\'s own description. Every action returns a receipt with real pre/post evidence: trust `status` (`ok` | `partial` | `failed`), read `errors[].message` for recovery guidance, and re-inspect after `partial`.\n\n**Tracked changes (redlining).** Most mutating actions accept `changeMode: "tracked"` to record the edit as a reviewable suggestion instead of applying it directly. Review with `accept_tracked_changes` / `reject_tracked_changes` (target one change with `id`, or an exact set with `id:[…]`; or filter by `author` or `changeType`). Do not combine exact IDs with filters. Recover with `undo_changes` / `redo_changes`.\n\n**Failures are safe.** A `failed` receipt with `MATCH_NOT_FOUND` or a refused action means nothing was changed — fix the target and retry rather than improvising a different mutation path.\n',
+    "mcp-prompt.md": 'SuperDoc MCP server — read, edit, and save Word documents (.docx).\n\nIMPORTANT: Always use these superdoc tools for .docx files.\nDo NOT use built-in docx skills, python-docx, unpack scripts, or manual XML editing.\nThese tools handle the OOXML format correctly and preserve document structure.\n\n## Session lifecycle\n\n1. `superdoc_open({path: "/path/to/file.docx"})` — returns `session_id`. Opening a non-existent path creates a blank document.\n2. Pass `session_id` to every subsequent tool call.\n3. Read with `superdoc_inspect`, edit with `superdoc_perform_action`.\n4. `superdoc_save({session_id})` — writes changes to disk.\n5. `superdoc_close({session_id})` — releases the session. Always close when done.\n\n## Workflow\n\n**Inspect before you edit.** `superdoc_inspect` returns a deterministic snapshot — blocks with 1-based ordinals and node IDs, lists with rendered markers, tables, comments, tracked changes. Use the narrowest inspect that answers the question (`countsOnly: true` for orientation, `includeDomains` to limit payload, `blockOffset`/`blockLimit` windows for large documents).\n\n**Edit with named actions.** `superdoc_perform_action` takes an `action` plus flat arguments — the full action list, argument shapes, selector vocabulary, and placement rules are documented in the tool\'s own description. Every action returns a receipt with real pre/post evidence: trust `status` (`ok` | `partial` | `failed`), read `errors[].message` for recovery guidance, and re-inspect after `partial`.\n\n**Target one repeated match.** For `replace_text`, scope to one block with a selector and set `occurrence` on the edit (1 = first match in that block) to change only that match. Also pass `expectedRevision` from your latest inspect or receipt; on `REVISION_CONFLICT`, inspect again and recount.\n\n**Tracked changes (redlining).** Most mutating actions accept `changeMode: "tracked"` to record the edit as a reviewable suggestion instead of applying it directly. Review with `accept_tracked_changes` / `reject_tracked_changes` (target one change with `id`, or an exact set with `id:[…]`; or filter by `author` or `changeType`). Do not combine exact IDs with filters. Recover with `undo_changes` / `redo_changes`.\n\n**Failures are safe.** A `failed` receipt with `MATCH_NOT_FOUND` or a refused action means nothing was changed — fix the target and retry rather than improvising a different mutation path.\n',
     "system-prompt.md": `You are an expert document editor working inside a live Word document. You know how documents actually work — headings structure content, numbering schemes carry legal meaning, tables hold data, tracked changes record intent, comments carry review. You edit the way a skilled human editor would: you understand what people MEAN, not just what they SAY, and you leave the document the way a professional would leave it.
 
 ============================================================
@@ -99697,7 +99813,7 @@ ACTIONS (superdoc_perform_action with flat args)
 - undo_changes: untilMarker (rendered marker from the original state, e.g. "2.1.") or steps (1-25). Deterministic revert — steps history back until the marker reappears; the receipt proves it. NEVER use steps > 1 blindly: prefer untilMarker, and after ANY undo verify (superdoc_inspect) that content you meant to KEEP still exists — if you overshot, redo_changes {steps:N} steps forward again to recover it.
 - redo_changes: steps (1-25, default 1). Steps history FORWARD to re-apply edits a prior undo removed — THE recovery for an undo overshoot. Only reaches the forward branch until a NEW edit is made.
 - attach_numbering: anchorText (text of the block) or nodeId, likeMarker (rendered marker of a sibling clause, e.g. "10."). Makes an EXISTING block a numbered clause at the same scheme/level — "make this the section 11 heading" in a clause-numbered document is exactly this (it will render as the next number).
-- replace_text: edits:[{find,replace}], caseSensitive default false. selector to scope. changeMode:"tracked" if asked. The receipt reports editsApplied and editsSkipped per find — READ IT: a skipped find is not in the selected block; re-target instead of assuming success.
+- replace_text: edits:[{find,replace,occurrence?}], caseSensitive default false. selector to scope. Keep find/replace spans MINIMAL. If the find appears more than once in the selected block and only one should change, give that edit occurrence (1 = first match in the block; needs selector; not selector.occurrence). With occurrence, also pass expectedRevision from your latest inspect or receipt; on REVISION_CONFLICT inspect again and recount. changeMode:"tracked" if asked. The receipt reports editsApplied and editsSkipped per find — READ IT: a skipped find is not in the selected block; re-target instead of assuming success.
 - delete_text: finds:[string]. selector to scope deletions to ONE block — REQUIRED for whitespace-only finds (unscoped whitespace matches document-wide and is refused). changeMode:"tracked" if asked. Deletes TEXT ONLY: the block survives, so a list item keeps its bullet/number and an accepted tracked deletion leaves an empty numbered item behind. To remove the item itself use delete_blocks.
 - delete_blocks: selectors:[…], each resolving to ONE block (list item, paragraph or heading). changeMode:"tracked" if asked. THE way to DELETE a whole LIST ITEM, paragraph or heading — the bullet/number goes with it and the remaining items renumber. "Delete the first item under Article II" / "remove that clause" is exactly this, NOT delete_text. Pass every target in ONE call. Use delete_table for a whole table.
 - rewrite_block: selector, text. Inspect first to gather current text; never ask the user to paste text already in the doc.
@@ -159330,7 +159446,7 @@ function buildCommentsCatalog(state) {
   const extendedBytes = state.packageBytes.get(COMMENTS_EXTENDED_PART_URI);
   let extendedByParaId = extendedBytes ? parseCommentsExtendedXml(TD12.decode(extendedBytes)) : new Map;
   if (entries.length > 1) {
-    extendedByParaId = mergeInferredThreading(extendedByParaId, inferThreadingFromStoryAnchors(state, entries));
+    extendedByParaId = mergeInferredThreading(extendedByParaId, inferThreadingFromStoryAnchors(state, entries, extendedByParaId));
   }
   const idsBytes = state.packageBytes.get(COMMENTS_IDS_PART_URI);
   const durableByParaId = idsBytes ? parseCommentsIdsXml(TD12.decode(idsBytes)) : new Map;
@@ -159630,17 +159746,25 @@ function normalizeNullableCustomAttr(value) {
     return null;
   return decodeAttr(value);
 }
-function inferThreadingFromStoryAnchors(state, entries) {
+function inferThreadingFromStoryAnchors(state, entries, explicit) {
   const entryByWId = new Map;
   for (const entry of entries) {
     if (!entryByWId.has(entry.wId))
       entryByWId.set(entry.wId, entry);
   }
+  const paraIdOwners = new Map;
+  for (const entry of entries) {
+    for (const paraId of new Set(entry.bodyParaIds))
+      paraIdOwners.set(paraId, (paraIdOwners.get(paraId) ?? 0) + 1);
+  }
   const sessionParaIds = state.idReservations.comments.paraIds;
   const importedSourceIds = new Set(entries.filter((entry) => {
     const paraId = entry.bodyParaIds[0];
-    return paraId && !entry.isExplicitRoot && !sessionParaIds.has(paraId);
+    return paraId && paraIdOwners.get(paraId) === 1 && !entry.isExplicitRoot && !sessionParaIds.has(paraId);
   }).map((entry) => entry.wId));
+  const inferenceSourceIds = new Set([...entryByWId.values()].filter((entry) => importedSourceIds.has(entry.wId) && !entry.bodyParaIds.some((paraId) => explicit.has(paraId))).map((entry) => entry.wId));
+  if (inferenceSourceIds.size === 0)
+    return new Map;
   const sourceOrder = new Map;
   for (let i = 0;i < entries.length; i += 1) {
     const entry = entries[i];
@@ -159664,11 +159788,6 @@ function inferThreadingFromStoryAnchors(state, entries) {
       groups.push([anchor]);
   }
   const out = new Map;
-  for (const entry of entries) {
-    const paraId = entry.bodyParaIds[0];
-    if (paraId)
-      out.set(paraId, { parentParaId: null, done: false });
-  }
   for (const group of groups) {
     const uniqueSourceIds = Array.from(new Set(group.map((a) => a.sourceWId)));
     if (uniqueSourceIds.length < 2)
@@ -159680,7 +159799,7 @@ function inferThreadingFromStoryAnchors(state, entries) {
     if (!rootParaId)
       continue;
     for (const sourceWId of uniqueSourceIds) {
-      if (sourceWId === rootSourceId)
+      if (sourceWId === rootSourceId || !inferenceSourceIds.has(sourceWId))
         continue;
       const replyEntry = entryByWId.get(sourceWId);
       const replyParaId = replyEntry?.bodyParaIds[0];
@@ -159688,12 +159807,25 @@ function inferThreadingFromStoryAnchors(state, entries) {
         continue;
       const parentSourceId = chooseContainingParentSourceId(sourceWId, uniqueSourceIds, envelopeBySourceId, sourceOrder) ?? rootSourceId;
       const parentEntry = entryByWId.get(parentSourceId);
-      const parentParaId = parentEntry?.bodyParaIds[0] ?? rootParaId;
+      const parentParaId = parentEntry ? selectThreadingParaId(parentEntry, explicit) : rootParaId;
+      if (wouldCreateThreadCycle(replyParaId, parentParaId, explicit, out))
+        continue;
       out.set(replyParaId, { parentParaId, done: false });
     }
   }
   return out;
 }
+function wouldCreateThreadCycle(childParaId, parentParaId, explicit, inferred) {
+  const seen = new Set([childParaId]);
+  let cursor = parentParaId;
+  while (cursor !== null) {
+    if (seen.has(cursor))
+      return true;
+    seen.add(cursor);
+    cursor = (explicit.get(cursor) ?? inferred.get(cursor))?.parentParaId ?? null;
+  }
+  return false;
+}
 function representativeEnvelopeBySourceId(group) {
   const out = new Map;
   for (const envelope of group) {
@@ -159758,17 +159890,8 @@ function mergeInferredThreading(explicit, inferred) {
     return explicit;
   const out = new Map(explicit);
   for (const [paraId, inferredExt] of inferred) {
-    const existing = out.get(paraId);
-    if (!existing) {
+    if (!out.has(paraId))
       out.set(paraId, inferredExt);
-      continue;
-    }
-    if (existing.parentParaId === null && inferredExt.parentParaId !== null) {
-      out.set(paraId, {
-        parentParaId: inferredExt.parentParaId,
-        done: existing.done
-      });
-    }
   }
   return out;
 }
@@ -159779,25 +159902,38 @@ function collectCommentAnchorEnvelopes(state) {
       continue;
     const xml = TD12.decode(bytes);
     const starts = [];
-    const ends = [];
+    const endsBySourceId = new Map;
     const tokenRe = /<[\w.-]+:(commentRangeStart|commentRangeEnd)\b[^>]*\bw:id="([^"]+)"[^>]*\/?>/g;
     for (let match = tokenRe.exec(xml);match; match = tokenRe.exec(xml)) {
       const item = { sourceWId: match[2] ?? "", pos: match.index };
       if (match[1] === "commentRangeStart")
         starts.push(item);
-      else
-        ends.push(item);
+      else {
+        const ends = endsBySourceId.get(item.sourceWId);
+        if (ends)
+          ends.push(item.pos);
+        else
+          endsBySourceId.set(item.sourceWId, [item.pos]);
+      }
     }
+    const endCursors = new Map;
     for (const start of starts) {
-      const end = ends.find((candidate2) => candidate2.sourceWId === start.sourceWId && candidate2.pos >= start.pos);
-      if (end)
-        out.push({ sourceWId: start.sourceWId, start: start.pos, end: end.pos });
+      const ends = endsBySourceId.get(start.sourceWId);
+      if (!ends)
+        continue;
+      let cursor = endCursors.get(start.sourceWId) ?? 0;
+      while (cursor < ends.length && ends[cursor] < start.pos)
+        cursor++;
+      endCursors.set(start.sourceWId, cursor);
+      const end = ends[cursor];
+      if (end !== undefined)
+        out.push({ partUri, sourceWId: start.sourceWId, start: start.pos, end });
     }
   }
   return out;
 }
 function envelopesOverlap(a, b) {
-  return a.start <= b.end && b.start <= a.end;
+  return a.partUri === b.partUri && a.start <= b.end && b.start <= a.end;
 }
 function isStoryPartUri(partUri) {
   return partUri === "/word/document.xml" || /^\/word\/header\d+\.xml$/.test(partUri) || /^\/word\/footer\d+\.xml$/.test(partUri) || partUri === "/word/footnotes.xml" || partUri === "/word/endnotes.xml";
@@ -159961,27 +160097,42 @@ function shiftedMarker(marker, delta) {
     paragraph: marker.paragraph ? { ...marker.paragraph, range: shift(marker.paragraph.range) } : null
   };
 }
-function getBodyCommentMarkerFacts(state, partUri) {
+function indexMarkersBySourceId(markers) {
+  const index = new Map;
+  for (const marker of markers) {
+    const existing = index.get(marker.id);
+    if (existing)
+      existing.push(marker);
+    else
+      index.set(marker.id, [marker]);
+  }
+  return index;
+}
+function getBodyCommentByteFacts(state, partUri) {
   const bytes = state.packageBytes.get(partUri);
   const revision = state.parts.get(partUri)?.descriptor.revision;
   if (!bytes || !revision)
-    return [];
+    return null;
   const cache = byteFacts(state);
   const prior = cache.get(partUri);
   if (prior?.bytes === bytes && prior.partRevision === revision)
-    return prior.markers;
+    return prior;
   const bom = bytes[0] === 239 && bytes[1] === 187 && bytes[2] === 191 ? 3 : 0;
   const scanned = scanBodyCommentMarkers(TD13.decode(bytes));
   const markers = scanned.markers.map((marker) => shiftedMarker(marker, bom));
-  cache.set(partUri, { bytes, partRevision: revision, markers, complete: scanned.complete });
-  return markers;
+  const facts = { bytes, partRevision: revision, markers, markersBySourceId: indexMarkersBySourceId(markers), complete: scanned.complete };
+  cache.set(partUri, facts);
+  return facts;
+}
+function getBodyCommentMarkerFacts(state, partUri) {
+  return getBodyCommentByteFacts(state, partUri)?.markers ?? [];
+}
+function getBodyCommentMarkersForSourceId(state, partUri, commentId) {
+  return getBodyCommentByteFacts(state, partUri)?.markersBySourceId.get(commentId) ?? [];
 }
 function readCompleteBodyCommentMarkerFacts(state, partUri) {
-  if (!state.packageBytes.has(partUri))
-    return null;
-  const markers = getBodyCommentMarkerFacts(state, partUri);
-  const facts = byteFacts(state).get(partUri);
-  return facts?.complete === true && facts.bytes === state.packageBytes.get(partUri) && facts.partRevision === state.parts.get(partUri)?.descriptor.revision ? markers : null;
+  const facts = getBodyCommentByteFacts(state, partUri);
+  return facts?.complete === true ? facts.markers : null;
 }
 function peekBodyCommentMarkerFacts(state, partUri) {
   const cache = state.partRegistries.get(BYTE_FACTS_KEY);
@@ -160011,22 +160162,22 @@ function refreshBodyCommentMarkerFactsAfterParagraphMutation(input) {
   }
   const scanned = scanBodyCommentMarkers(TD13.decode(bytes.subarray(input.beforeStart, input.afterEnd)), input.namespaceBindings);
   const current = scanned.markers.map((marker) => shiftedMarker(marker, input.beforeStart));
+  const markers = [...unchanged, ...current].sort((a, b) => a.range.byteStart - b.range.byteStart);
   cache.set(input.partUri, {
     bytes,
     partRevision: revision,
     complete: prior.complete && scanned.complete,
-    markers: [...unchanged, ...current].sort((a, b) => a.range.byteStart - b.range.byteStart)
+    markers,
+    markersBySourceId: indexMarkersBySourceId(markers)
   });
 }
 function findRetainedBodyCommentAnchors(state, partUri, commentId, occurrenceIndex) {
-  return anchorsFromMarkers(getBodyCommentMarkerFacts(state, partUri), commentId, occurrenceIndex);
+  return anchorsFromMarkers(getBodyCommentMarkersForSourceId(state, partUri, commentId), commentId, occurrenceIndex);
 }
 function countRetainedBodyCommentAnchorOccurrences(state, partUri, commentId) {
   const counts = { commentRangeStart: 0, commentRangeEnd: 0, commentReference: 0 };
-  for (const marker of getBodyCommentMarkerFacts(state, partUri)) {
-    if (marker.id === commentId)
-      counts[marker.kind] += 1;
-  }
+  for (const marker of getBodyCommentMarkersForSourceId(state, partUri, commentId))
+    counts[marker.kind] += 1;
   return Math.max(counts.commentRangeStart, counts.commentRangeEnd, counts.commentReference);
 }
 function collectBodyCommentMarkers(documentXml, namespaceBindings) {
@@ -185500,7 +185651,8 @@ function createReviewStagingState(state, targetBlockIds) {
       result[key3] = clone2(item);
     return result;
   };
-  Object.assign(staged, Object.fromEntries(Object.entries(staged).filter(([key3]) => !["packageBytes", "paragraphIndexes", "partRegistries"].includes(key3)).map(([key3, value]) => [key3, clone2(value)])));
+  Object.assign(staged, Object.fromEntries(Object.entries(staged).filter(([key3]) => !["packageBytes", "paragraphIndexes", "partRegistries", "history"].includes(key3)).map(([key3, value]) => [key3, clone2(value)])));
+  staged.history = { entries: new Map(state.history.entries), order: [...state.history.order] };
   staged.paragraphIndexes = new Map;
   staged.partRegistries = new Map;
   staged.revisions = new RevisionAllocator("review-preview");
@@ -202035,6 +202187,7 @@ function commitResidentText(input, view) {
     return null;
   const range = { byteStart: paragraph.byteStart, byteEnd: paragraph.byteEnd };
   const collapsed = op.on.startOffset === op.on.endOffset;
+  const leadingBookmarkBoundary = collapsed && op.newText.length > 0 && edit.visibleStart === 0 && edit.before.model.leaves().some((piece) => piece.kind === "marker" && piece.visibleStart === 0 && (piece.markerKind === "bookmarkStart" || piece.markerKind === "bookmarkEnd"));
   const requiresCollaborationSessionSync = op.changeMode === "direct" && op.on.coordinateSpace === "tracked" && edit.visibleStart !== op.on.startOffset;
   return finalizeCommit({
     input,
@@ -202059,7 +202212,8 @@ function commitResidentText(input, view) {
       blockId: op.on.startBlockId,
       startOffset: edit.visibleStart,
       text: op.newText,
-      runPropertiesXml: leaf.runProperties ?? ""
+      runPropertiesXml: leaf.runProperties ?? "",
+      ...leadingBookmarkBoundary ? { afterLeadingMarkers: true } : {}
     } } : {},
     ...edit.insertionRsid && !collapsed ? { trackedTextRefinement: {
       kind: "trackedTextRefinement",
@@ -264694,8 +264848,7 @@ class TxContext {
     const documentBytes = this.state.packageBytes.get(op.on.partUri);
     if (!documentBytes)
       return rejected21(this.txId, "invalid-range");
-    const documentXml = TD78.decode(documentBytes);
-    const anchors = findBodyCommentAnchors(documentXml, markerWId, sourceStoryInfo.localOccurrenceIndex);
+    const anchors = sourceStoryInfo.anchors;
     if (!anchors.rangeStart || !anchors.rangeEnd) {
       return rejected21(this.txId, "comment-anchor-not-found");
     }
@@ -264714,7 +264867,7 @@ class TxContext {
         continue;
       if (threadStory.partUri !== op.on.partUri)
         return rejected21(this.txId, "comment-move-cross-story");
-      const threadAnchors = findBodyCommentAnchors(documentXml, threadMarkerWId, threadStory.localOccurrenceIndex);
+      const threadAnchors = threadStory.anchors;
       if (threadAnchors.rangeStart)
         removeRanges.push(threadAnchors.rangeStart);
       if (threadAnchors.rangeEnd)
@@ -264741,7 +264894,7 @@ class TxContext {
     };
     if (newRange.byteEnd < newRange.byteStart)
       return rejected21(this.txId, "invalid-range");
-    if (!op.allowMarkerCarrierOverlap && rangesOverlap(oldEnvelope, newRange)) {
+    if (!op.allowMarkerCarrierOverlap && rangesOverlap(oldEnvelope, newRange) && !isUnchangedCommentRange(this.state, op.on, markerWId, anchors)) {
       return rejected21(this.txId, "comment-move-overlap");
     }
     const stripped = stripBytes2(documentBytes, mergedRemovals);
@@ -264749,7 +264902,7 @@ class TxContext {
     const newEnd = translateAfterRemovals(newRange.byteEnd, mergedRemovals);
     if (newStart == null || newEnd == null)
       return rejected21(this.txId, "comment-move-overlap");
-    const rewrite = rewriteDocumentXml(TD78.decode(stripped), { ...op.on, startByte: newStart, endByte: newEnd }, markerWId, undefined, {
+    const rewrite = rewriteDocumentXml(TD_KEEP_BOM.decode(stripped), { ...op.on, startByte: newStart, endByte: newEnd }, markerWId, undefined, {
       start: relocatedAnchors.map((anchor) => commentRangeStart(anchor.markerWId)).join(""),
       end: relocatedAnchors.map((anchor) => commentRangeEnd(anchor.markerWId) + commentReferenceRun(anchor.markerWId, anchor.referenceRunXml)).join("")
     });
@@ -264778,28 +264931,31 @@ class TxContext {
       const commentsBytes = this.state.packageBytes.get(COMMENTS_PART_URI3);
       if (!commentsBytes)
         return rejected21(this.txId, "comments-part-missing");
-      const commentsXml = TD78.decode(commentsBytes);
-      let commentsNext = commentsXml;
+      const bom = commentsBytes[0] === 239 && commentsBytes[1] === 187 && commentsBytes[2] === 191 ? 3 : 0;
+      const commentsPatches = [];
       for (const threadEntry of threadEntries) {
-        const rewritten = rewriteCommentTrackedChangeMetadata(commentsNext, threadEntry.sourceWId || threadEntry.wId, threadEntry.sourceWIdOccurrenceIndex, op.trackedChangeMetadata);
+        const startByte = threadEntry.byteStart + bom;
+        const endByte = threadEntry.byteEnd + bom;
+        const fragment3 = TD78.decode(commentsBytes.subarray(startByte, endByte));
+        const rewritten = rewriteCommentTrackedChangeMetadata(fragment3, threadEntry.sourceWId || threadEntry.wId, 0, op.trackedChangeMetadata);
         if (!rewritten.ok)
           return rejected21(this.txId, rewritten.reason);
-        commentsNext = rewritten.xml;
+        if (rewritten.xml !== fragment3)
+          commentsPatches.push({
+            kind: "replaceBytes",
+            order: commentsPatches.length,
+            startByte,
+            endByte,
+            bytes: TE44.encode(rewritten.xml)
+          });
       }
-      if (commentsNext !== commentsXml) {
-        const commentsPatch = {
-          kind: "replaceBytes",
-          order: 0,
-          startByte: 0,
-          endByte: commentsBytes.length,
-          bytes: TE44.encode(commentsNext)
-        };
-        perPart[COMMENTS_PART_URI3] = { kind: "modify", patches: [commentsPatch] };
+      if (commentsPatches.length > 0) {
+        perPart[COMMENTS_PART_URI3] = { kind: "modify", patches: commentsPatches };
         preconditions.push(byteWindowPrecondition10(COMMENTS_PART_URI3, commentsBytes));
         const commentsMap = buildPatchMap({
           partUri: COMMENTS_PART_URI3,
           originalLength: commentsBytes.length,
-          patches: [commentsPatch]
+          patches: commentsPatches
         });
         patchMaps[COMMENTS_PART_URI3] = commentsMap.ok ? commentsMap.value : { partUri: COMMENTS_PART_URI3, ranges: [] };
       }
@@ -265440,6 +265596,34 @@ function locateCommentAnchorStory(state, commentId, occurrenceIndex) {
   }
   return null;
 }
+function isUnchangedCommentRange(state, target, markerWId, anchors) {
+  if (!anchors.rangeStart || !anchors.rangeEnd)
+    return false;
+  const markers = getBodyCommentMarkersForSourceId(state, target.partUri, markerWId);
+  const bytes = state.packageBytes.get(target.partUri);
+  if (!bytes)
+    return false;
+  const models = new Map;
+  const matchesBoundary = (kind, anchor, blockId, offset) => {
+    const marker = markers.find((item) => item.kind === kind && item.range.byteStart === anchor.byteStart);
+    const paragraph = marker?.paragraph;
+    if (!paragraph || anchor.byteStart < paragraph.range.byteStart || anchor.byteEnd > paragraph.range.byteEnd)
+      return false;
+    if (paragraph.blockId !== blockId) {
+      const indexed = getStoryParagraphIndexFromState(state, target.storyId)?.byParaId(blockId);
+      if (!indexed || indexed.partUri !== target.partUri || indexed.partRevision !== target.partRevision || indexed.byteStart !== paragraph.range.byteStart || indexed.byteEnd !== paragraph.range.byteEnd)
+        return false;
+    }
+    let model = models.get(paragraph.range.byteStart);
+    if (!model) {
+      model = parseParagraphInlineMap(TD78.decode(bytes.subarray(paragraph.range.byteStart, paragraph.range.byteEnd)), paragraph.namespaceBindings);
+      models.set(paragraph.range.byteStart, model);
+    }
+    const leaf = model.leaves().find((piece) => piece.kind === "marker" && piece.id === markerWId && piece.markerKind === kind && piece.byteStart + paragraph.range.byteStart === anchor.byteStart);
+    return !!leaf && (target.coordinateSpace === "tracked" ? leaf.trackedStart : leaf.visibleStart) === offset;
+  };
+  return matchesBoundary("commentRangeStart", anchors.rangeStart, target.startBlockId, target.startOffset) && matchesBoundary("commentRangeEnd", anchors.rangeEnd, target.endBlockId, target.endOffset);
+}
 function findCommentAnchorsForStory(state, partUri, storyXml, commentId, occurrenceIndex) {
   const localOccurrenceIndex = localOccurrenceIndexForStory(state, partUri, storyXml, commentId, occurrenceIndex);
   if (localOccurrenceIndex === null) {
@@ -266206,22 +266390,25 @@ function materializeCurrentCommentThreadExtendedRows(input) {
     Object.assign(input.patchMaps, compiled.value.patchMaps);
     return { ok: true };
   }
-  let nextXml = TD78.decode(extendedBytes);
-  let changed = false;
-  for (const item of entries2) {
-    const next = upsertCommentsExtendedThreadRow(nextXml, {
-      paraId: item.paraId,
-      parentParaId: item.parentParaId,
-      done: item.done
-    });
-    if (!next.ok)
-      return next;
-    if (next.value !== nextXml) {
-      nextXml = next.value;
-      changed = true;
-    }
+  const xml = TD_KEEP_BOM.decode(extendedBytes);
+  const remaining = new Map(entries2.map((item) => [item.paraId, item]));
+  let nextXml = xml.replace(/<[\w.-]+:commentEx\b[^>]*>/g, (fragment3) => {
+    const paraId = /\b(?:w14|w15):paraId="([^"]*)"/.exec(fragment3)?.[1];
+    const item = paraId ? remaining.get(paraId) : undefined;
+    if (!item)
+      return fragment3;
+    remaining.delete(item.paraId);
+    const next = upsertCommentsExtendedThreadRow(fragment3, item);
+    return next.ok ? next.value : fragment3;
+  });
+  if (remaining.size > 0) {
+    const fragments = [...remaining.values()].map(commentsExtendedRowXml).join("");
+    const appended = appendToExistingXmlRoot(nextXml, fragments, "commentsEx");
+    if (!appended.ok)
+      return appended;
+    nextXml = appended.value;
   }
-  if (changed)
+  if (nextXml !== xml)
     addWholePartReplace(input, COMMENTS_EXTENDED_PART_URI3, extendedBytes, nextXml);
   return { ok: true };
 }
@@ -266277,11 +266464,13 @@ function threadRootParaId(catalog, entry) {
   }
   return entry.paraId;
 }
-function appendCommentsExtendedXml(xml, input) {
+function commentsExtendedRowXml(input) {
   const parentAttr = input.parentParaId ? ` w15:paraIdParent="${escapeXmlAttribute(input.parentParaId)}"` : "";
   const doneAttr = input.done ? "1" : "0";
-  const fragment3 = `<w15:commentEx w15:paraId="${escapeXmlAttribute(input.paraId)}" w15:done="${doneAttr}"${parentAttr}/>`;
-  return appendToExistingXmlRoot(xml, fragment3, "commentsEx");
+  return `<w15:commentEx w15:paraId="${escapeXmlAttribute(input.paraId)}" w15:done="${doneAttr}"${parentAttr}/>`;
+}
+function appendCommentsExtendedXml(xml, input) {
+  return appendToExistingXmlRoot(xml, commentsExtendedRowXml(input), "commentsEx");
 }
 function appendCommentsIdsXml(xml, input) {
   const fragment3 = `<w16cid:commentId w16cid:paraId="${escapeXmlAttribute(input.paraId)}" w16cid:durableId="${escapeXmlAttribute(input.durableId)}"/>`;
@@ -266448,7 +266637,7 @@ function emptyHeaderFooterSkeleton(kind) {
   const root = kind === "header" ? "w:hdr" : "w:ftr";
   return '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>' + `<${root}` + ' xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"' + ' xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"' + ">" + "<w:p/>" + `</${root}>`;
 }
-var TE44, TD78, nextTx = 0, CONTENT_TYPES_PART_URI12 = "/[Content_Types].xml", DOCUMENT_RELS_PART_URI10 = "/word/_rels/document.xml.rels", COMMENTS_PART_URI3 = "/word/comments.xml", COMMENTS_IDS_PART_URI3 = "/word/commentsIds.xml", COMMENTS_EXTENDED_PART_URI3 = "/word/commentsExtended.xml", SDCOM_COMMENTS_NS_URI = "http://superdoc.dev/2024/comments", COMMENT_ELEMENT_RE, RUN_HAS_TEXT_LEAF_VISIBLE_RE, RUN_HAS_TEXT_LEAF_TRACKED_RE, RUN_CONTROL_LEAF_RE, RUN_TEXT_LEAF_RE_VISIBLE, RUN_TEXT_LEAF_RE_TRACKED;
+var TE44, TD78, TD_KEEP_BOM, nextTx = 0, CONTENT_TYPES_PART_URI12 = "/[Content_Types].xml", DOCUMENT_RELS_PART_URI10 = "/word/_rels/document.xml.rels", COMMENTS_PART_URI3 = "/word/comments.xml", COMMENTS_IDS_PART_URI3 = "/word/commentsIds.xml", COMMENTS_EXTENDED_PART_URI3 = "/word/commentsExtended.xml", SDCOM_COMMENTS_NS_URI = "http://superdoc.dev/2024/comments", COMMENT_ELEMENT_RE, RUN_HAS_TEXT_LEAF_VISIBLE_RE, RUN_HAS_TEXT_LEAF_TRACKED_RE, RUN_CONTROL_LEAF_RE, RUN_TEXT_LEAF_RE_VISIBLE, RUN_TEXT_LEAF_RE_TRACKED;
 var init_tx_context = __esm(() => {
   init_resident_paragraph_ownership();
   init_canonical_xml_analysis_frame();
@@ -266494,6 +266683,7 @@ var init_tx_context = __esm(() => {
   init_compile_image_ops();
   TE44 = new TextEncoder;
   TD78 = new TextDecoder;
+  TD_KEEP_BOM = new TextDecoder("utf-8", { ignoreBOM: true });
   COMMENT_ELEMENT_RE = /<[\w.-]+:comment(?=[\s>/])/;
   RUN_HAS_TEXT_LEAF_VISIBLE_RE = /<[\w.-]+:t\b/;
   RUN_HAS_TEXT_LEAF_TRACKED_RE = /<[\w.-]+:(t|delText)\b/;
@@ -377832,13 +378022,29 @@ function resolveCommentEntryByParaId(catalog, paraId) {
     return null;
   return catalog.commentsByCommentId.get(canonicalCommentId) ?? null;
 }
+function commentAnchorProjectionEntry(entry, catalog, anchorIndex) {
+  let cursor = entry;
+  const seen = new Set;
+  while (cursor.parentParaId !== null) {
+    if (seen.has(cursor.commentId))
+      return entry;
+    seen.add(cursor.commentId);
+    const hits = anchorIndex.hitsBySourceWId.get(cursor.sourceWId) ?? [];
+    if (catalog.commentsBySourceWId.get(cursor.sourceWId)?.length !== 1 || !hits.some((hit) => hit.hasReference) || hits.some((hit) => hit.hasRangeStart || hit.hasRangeEnd))
+      break;
+    const parent = resolveCommentEntryByParaId(catalog, cursor.parentParaId);
+    if (!parent)
+      break;
+    cursor = parent;
+  }
+  return cursor;
+}
 function toCommentInfo(entry, catalog, anchorIndex, headerFooterRels, trackedAssociations) {
   const publicCommentId = publicCommentIdForEntry(entry);
   const parentParaId = entry.parentParaId;
   const parentEntry = parentParaId ? resolveCommentEntryByParaId(catalog, parentParaId) : null;
   const parentCommentId = parentEntry ? publicCommentIdForEntry(parentEntry) : undefined;
   const rootCommentId = parentCommentId ? rootCommentIdForCatalogEntry(entry, catalog) : null;
-  const anchorProjectionEntry = entry;
   const info = {
     address: { kind: "entity", entityType: "comment", entityId: publicCommentId },
     commentId: publicCommentId,
@@ -377860,10 +378066,9 @@ function toCommentInfo(entry, catalog, anchorIndex, headerFooterRels, trackedAss
     info.creatorImage = entry.authorImage;
   if (entry.importedId !== null && entry.importedId !== publicCommentId)
     info.importedId = entry.importedId;
-  let sourceSiblings;
   if (entry.sourceWId) {
     info.rawOoxmlId = entry.sourceWId;
-    sourceSiblings = catalog.commentsBySourceWId.get(entry.sourceWId);
+    const sourceSiblings = catalog.commentsBySourceWId.get(entry.sourceWId);
     if (sourceSiblings && sourceSiblings.length > 1) {
       info.rawOoxmlOccurrenceIndex = entry.sourceWIdOccurrenceIndex;
     }
@@ -377901,11 +378106,12 @@ function toCommentInfo(entry, catalog, anchorIndex, headerFooterRels, trackedAss
   if (!info.trackedChange) {
     attachMetadataOnlyTrackedChangeLink(info, entry, anchorIndex ? null : trackedAssociations, metadataAssociation.status !== "unsafe");
   }
-  if (anchorIndex && anchorProjectionEntry) {
+  if (anchorIndex) {
+    const anchorProjectionEntry = commentAnchorProjectionEntry(entry, catalog, anchorIndex);
     const hits = anchorIndex.hitsBySourceWId.get(anchorProjectionEntry.sourceWId) ?? [];
     const projectable = hits.filter((h) => h.story.kind === "body" || h.story.kind === "header" || h.story.kind === "footer");
     if (projectable.length > 0) {
-      sourceSiblings ?? (sourceSiblings = catalog.commentsBySourceWId.get(anchorProjectionEntry.sourceWId));
+      const sourceSiblings = catalog.commentsBySourceWId.get(anchorProjectionEntry.sourceWId);
       const globalSegmentIndex = sourceSiblings && sourceSiblings.length > 1 ? anchorProjectionEntry.sourceWIdOccurrenceIndex : undefined;
       const projected = projectAnchor(projectable, headerFooterRels, globalSegmentIndex);
       if (projected) {
@@ -385238,6 +385444,7 @@ class V2ListsAdapter {
     if (insertReceipt.status === "rejected") {
       return failure8(mapRejectionReason(insertReceipt.rejectedReason ?? "internal-error"), insertReceipt.rejectedReason ?? "list insert: paragraph insert rejected");
     }
+    this.context.invalidate(insertReceipt);
     recordCommittedTxIdForHistory(this.context, insertReceipt.txId);
     const newParaId = readCreatedParagraphRefId(insertReceipt.createdRefs ?? [], insertReceipt.provisionalToFinal);
     if (!newParaId) {
@@ -385364,6 +385571,7 @@ class V2ListsAdapter {
       if (insertReceipt.status === "rejected") {
         return failure8(mapRejectionReason(insertReceipt.rejectedReason ?? "internal-error"), insertReceipt.rejectedReason ?? "list create: paragraph insert rejected");
       }
+      this.context.invalidate(insertReceipt);
       recordCommittedTxIdForHistory(this.context, insertReceipt.txId);
       const newParaId = readCreatedParagraphRefId(insertReceipt.createdRefs ?? [], insertReceipt.provisionalToFinal);
       if (!newParaId) {
@@ -387095,6 +387303,7 @@ function applyListSeed(adapter, storyId, paraId, kind, expectedRevision, changeM
   if (receipt3.status === "rejected") {
     return failure8(mapRejectionReason(receipt3.rejectedReason ?? "internal-error"), receipt3.rejectedReason ?? "list create rejected");
   }
+  adapter.context.invalidate(receipt3);
   recordCommittedTxIdForHistory(adapter.context, receipt3.txId);
   const summary = readListItemSummaryForSession(adapter.context.session, storyId, paraId);
   return {
@@ -419150,8 +419359,67 @@ async function compilePlan(context, input) {
   }
   detectTargetConflicts(context, steps, failures);
   detectUnsupportedRuntimeDrift(input.steps, failures);
-  detectTargetOffsetDriftRisk(steps, failures);
-  return { evaluatedRevision, steps, failures };
+  const exactProgram = failures.length === 0 ? compileDescendingExactTargets(context, steps) : undefined;
+  if (exactProgram) {
+    if (exactProgram.edits.length > 0) {
+      const preview = new V2SelectionMutationAdapter(context).executeResolvedTextRewrites(exactProgram.edits, { changeMode: changeMode ?? "direct", dryRun: true });
+      if (!preview.success)
+        failures.push({
+          code: preview.failure.code,
+          stepId: exactProgram.edits[0].ownerStepId,
+          phase: "compile",
+          message: preview.failure.message
+        });
+    }
+  } else
+    detectTargetOffsetDriftRisk(steps, failures);
+  return {
+    evaluatedRevision,
+    steps,
+    failures,
+    ...exactProgram ? { atomicTextProgram: exactProgram } : {}
+  };
+}
+function compileDescendingExactTargets(context, steps) {
+  const mutating = steps.filter((step3) => step3.op !== "assert");
+  if (mutating.length < 2)
+    return;
+  const edits = [];
+  let blockId;
+  let previousStart = Infinity;
+  const index2 = getSDDocumentSessionInternalParagraphIndex(context.session);
+  if (!index2)
+    return;
+  for (const step3 of mutating) {
+    const source = step3.source;
+    if (step3.op !== "text.rewrite" && step3.op !== "text.delete" || source.op === "assert" || !("where" in source) || source.where.by !== "target" || !step3.resolution || step3.request?.kind !== "replace")
+      return;
+    const target = source.where.target;
+    if (target.kind !== "selection" || target.start.kind !== "text" || target.end.kind !== "text" || target.coordinateSpace === "tracked" || !isSupportedMutationStoryScope(target.story) || !isSupportedMutationStoryScope(target.start.story) || !isSupportedMutationStoryScope(target.end.story) || target.start.blockId !== target.end.blockId)
+      return;
+    blockId ?? (blockId = target.start.blockId);
+    if (target.start.blockId !== blockId || step3.resolution.range.from >= step3.resolution.range.to || step3.resolution.range.to > previousStart)
+      return;
+    previousStart = step3.resolution.range.from;
+    const on = resolveSelectionTargetToRange({
+      target,
+      index: index2,
+      readPartBytes: (partUri) => getSDDocumentSessionInternalPartBytes(context.session, partUri),
+      readPartRange: (partUri, start, end) => getSDDocumentSessionInternalPartRange(context.session, partUri, start, end),
+      buildOffsetMap: buildOffsetMapForCoordinateSpace4
+    });
+    if ("error" in on)
+      throw new DocumentApiValidationError2(on.error, on.message);
+    if (step3.request.text !== step3.resolution.text)
+      edits.push({
+        on,
+        newText: step3.request.text,
+        resolution: step3.resolution,
+        ownerStepId: step3.stepId,
+        rewriteIntent: step3.op === "text.rewrite"
+      });
+  }
+  return { edits };
 }
 function isOrderedAtomicTextProgram(steps) {
   return steps.length > 1 && steps.every((step3) => (step3.op === "text.rewrite" || step3.op === "text.delete") && step3.where.by === "select" && step3.where.select.type === "text" && step3.where.require === "all");
@@ -420748,6 +421016,7 @@ var init_engine3 = __esm(() => {
   init_sd_document_session_internal();
   init_search();
   init_raw_block_ref();
+  init_selection_target();
   init_story_identity();
   init_story_surface();
   init_v2_search_ref();
@@ -475103,7 +475372,7 @@ function tryMirrorStoryText(prepared, extension2, options, admitted) {
             text: source.newText,
             txId: prepared.txId,
             directInsert: validation.directInsert,
-            preserveZeroLengthAtOffset: validation.inlineControl?.afterParagraphTail,
+            preserveZeroLengthAtOffset: validation.directInsert.afterLeadingMarkers || validation.inlineControl?.afterParagraphTail,
             acceptedTextInsertionSplit: validation.acceptedTextInsertionSplit
           });
         } else {
@@ -475534,7 +475803,7 @@ function validateDirectTextInsert(source, extension2) {
   if (!directInsert) {
     return { ok: false, failureReason: "direct insert requires typed storySurface metadata" };
   }
-  if (directInsert.kind !== "directTextInsert" || directInsert.blockId !== source.on.startBlockId || directInsert.startOffset !== source.on.startOffset || directInsert.text !== source.newText) {
+  if (directInsert.kind !== "directTextInsert" || directInsert.blockId !== source.on.startBlockId || directInsert.startOffset !== source.on.startOffset || directInsert.text !== source.newText || directInsert.afterLeadingMarkers !== undefined && (directInsert.afterLeadingMarkers !== true || directInsert.startOffset !== 0)) {
     return { ok: false, failureReason: "direct insert storySurface metadata does not match source" };
   }
   if (parsePreparedRunAttributes(directInsert.runPropertiesXml) === null) {
@@ -482861,6 +483130,25 @@ async function openV2CollaborativeDocumentSession(options) {
     } else {
       trace.mark("source-complete-deferred");
     }
+    if (ownsPreparedBootstrap) {
+      const current = readRoomManifest(rootConn.ydoc);
+      if (current.snapshot?.meta.bootstrapState === "committed") {
+        const committed = options.runtime.validateLateJoin({
+          compatibility: { supports: COLLAB_V2_ROOM_SCHEMA_VERSION },
+          readiness: READINESS_CLASS.bodyEditable
+        });
+        if (!committed.ok)
+          throwLateJoinValidationFailure(committed, options.runtime.rootId);
+        throw new CollabV2DiagnosticError(COLLAB_V2_DIAGNOSTICS.COLLAB_V2_ROOM_ALREADY_EXISTS, "another creator committed this v2 collaboration room during open; reopen with join", { rootId: options.runtime.rootId });
+      }
+      if (current.snapshot?.meta.bootstrapState !== "pending" || current.diagnostics.length > 0) {
+        throw new CollabV2DiagnosticError(COLLAB_V2_DIAGNOSTICS.COLLAB_V2_ROOM_CORRUPT, "prepared v2 collaboration room is no longer a valid pending room; this open did not publish content", { rootId: options.runtime.rootId });
+      }
+      const leader = readBootstrapClaims(rootConn.ydoc).find((claim) => claim.status !== "aborted");
+      if (leader?.claimerId !== expectedClaimerId || leader?.status !== "pending") {
+        throw new CollabV2DiagnosticError(COLLAB_V2_DIAGNOSTICS.COLLAB_V2_ROOM_INITIALIZING, "another creator is initializing this v2 collaboration room", { rootId: options.runtime.rootId });
+      }
+    }
     const canonical = await buildCanonicalShardGraph({
       runtime: options.runtime,
       rootDoc: rootConn.ydoc,
@@ -483395,14 +483683,17 @@ async function buildCanonicalShardGraph(input) {
   for (const { story, shardId, bytes } of stories) {
     let unit;
     if (maySeedStoryShardsFromLocalSource && bytes) {
-      unit = createCollabUnitHandle({ rootDoc, shardId, shardKind: SHARD_KIND.story });
-      trySeedStoryShard(unit, {
-        shardId,
-        storyId: story.storyId,
-        storyKind: story.storyKind,
-        sourcePartUri: story.partUri,
-        bytes
-      });
+      unit = rootDoc.transact(() => {
+        const created = createCollabUnitHandle({ rootDoc, shardId, shardKind: SHARD_KIND.story });
+        trySeedStoryShard(created, {
+          shardId,
+          storyId: story.storyId,
+          storyKind: story.storyKind,
+          sourcePartUri: story.partUri,
+          bytes
+        });
+        return created;
+      }, "collab-v2:bootstrap:seed-unit");
     } else {
       await waitForStoryShardSeeded(rootDoc, shardId);
       unit = createCollabUnitHandle({ rootDoc, shardId, shardKind: SHARD_KIND.story });
@@ -483475,13 +483766,16 @@ async function buildCanonicalShardGraph(input) {
   let commentsHandle = null;
   const commentsShardId = packageShardId2(input.runtime.rootId, SHARD_KIND.comments, COMMENTS_PART_URI6);
   {
-    const unit = createCollabUnitHandle({ rootDoc, shardId: commentsShardId, shardKind: SHARD_KIND.comments });
-    if (commentsFamily != null) {
-      const commentsCatalog = buildCommentsCatalogFromParts(new Map(commentsFamily.parts.flatMap((part) => part.bytes ? [[part.partUri, part.bytes]] : [])));
-      trySeedCommentsShard(unit, commentsShardId, commentsCatalog, commentsFamily.partKeys, commentsFamily.parts);
-    } else {
-      trySeedEmptyCommentsShard(unit, commentsShardId);
-    }
+    const unit = rootDoc.transact(() => {
+      const created = createCollabUnitHandle({ rootDoc, shardId: commentsShardId, shardKind: SHARD_KIND.comments });
+      if (commentsFamily != null) {
+        const commentsCatalog = buildCommentsCatalogFromParts(new Map(commentsFamily.parts.flatMap((part) => part.bytes ? [[part.partUri, part.bytes]] : [])));
+        trySeedCommentsShard(created, commentsShardId, commentsCatalog, commentsFamily.partKeys, commentsFamily.parts);
+      } else {
+        trySeedEmptyCommentsShard(created, commentsShardId);
+      }
+      return created;
+    }, "collab-v2:bootstrap:seed-unit");
     projectionHandles.set(commentsShardId, {
       shardId: commentsShardId,
       shardKind: SHARD_KIND.comments,
@@ -483609,243 +483903,259 @@ function subtreePackageHandle(rootDoc, unit, shardKind, bootstrap) {
   };
 }
 async function connectRelationshipsShard(rootDoc, shardId, part) {
-  const unit = createCollabUnitHandle({ rootDoc, shardId, shardKind: SHARD_KIND.relationships });
-  if (part.bytes) {
-    const ownerPartUri2 = ownerPartUriForRels3(part.partUri);
-    const xml = TEXT_DECODER12.decode(part.bytes);
-    const parsed = parseRelationshipsXml(xml, {
-      ownerPartUri: ownerPartUri2,
-      relsUri: part.partUri,
-      resolveTarget(target, targetMode) {
-        return resolveTargetUri(ownerPartUri2, target, targetMode);
-      }
-    });
-    try {
-      seedRelationshipsShard({
-        doc: unit,
-        shardId,
-        ownerPartKey: part.partKey,
+  return rootDoc.transact(() => {
+    const unit = createCollabUnitHandle({ rootDoc, shardId, shardKind: SHARD_KIND.relationships });
+    if (part.bytes) {
+      const ownerPartUri2 = ownerPartUriForRels3(part.partUri);
+      const xml = TEXT_DECODER12.decode(part.bytes);
+      const parsed = parseRelationshipsXml(xml, {
         ownerPartUri: ownerPartUri2,
-        relationships: parsed.relationships.map((relationship) => ({
-          rId: relationship.id,
-          type: relationship.type,
-          target: relationship.target,
-          targetMode: relationship.targetMode,
-          external: relationship.targetMode === "External"
-        }))
+        relsUri: part.partUri,
+        resolveTarget(target, targetMode) {
+          return resolveTargetUri(ownerPartUri2, target, targetMode);
+        }
       });
-    } catch (error50) {
-      if (!isAlreadySeededError(error50))
-        throw error50;
+      try {
+        seedRelationshipsShard({
+          doc: unit,
+          shardId,
+          ownerPartKey: part.partKey,
+          ownerPartUri: ownerPartUri2,
+          relationships: parsed.relationships.map((relationship) => ({
+            rId: relationship.id,
+            type: relationship.type,
+            target: relationship.target,
+            targetMode: relationship.targetMode,
+            external: relationship.targetMode === "External"
+          }))
+        });
+      } catch (error50) {
+        if (!isAlreadySeededError(error50))
+          throw error50;
+      }
     }
-  }
-  return subtreePackageHandle(rootDoc, unit, SHARD_KIND.relationships);
+    return subtreePackageHandle(rootDoc, unit, SHARD_KIND.relationships);
+  }, "collab-v2:bootstrap:seed-unit");
 }
 async function connectContentTypesShard(rootDoc, shardId, part) {
-  const unit = createCollabUnitHandle({ rootDoc, shardId, shardKind: SHARD_KIND.contentTypes });
-  if (part.bytes) {
-    const parsed = parseContentTypes(TEXT_DECODER12.decode(part.bytes));
-    try {
-      seedContentTypesShard({
-        doc: unit,
-        shardId,
-        ownerPartKey: part.partKey,
-        ownerPartUri: part.partUri,
-        defaults: Array.from(parsed.defaults.entries()).map(([extension2, contentType]) => ({
-          extension: extension2,
-          contentType
-        })),
-        overrides: Array.from(parsed.overrides.entries()).map(([partKey2, contentType]) => ({
-          partKey: partKey2,
-          contentType
-        }))
-      });
-    } catch (error50) {
-      if (!isAlreadySeededError(error50))
-        throw error50;
+  return rootDoc.transact(() => {
+    const unit = createCollabUnitHandle({ rootDoc, shardId, shardKind: SHARD_KIND.contentTypes });
+    if (part.bytes) {
+      const parsed = parseContentTypes(TEXT_DECODER12.decode(part.bytes));
+      try {
+        seedContentTypesShard({
+          doc: unit,
+          shardId,
+          ownerPartKey: part.partKey,
+          ownerPartUri: part.partUri,
+          defaults: Array.from(parsed.defaults.entries()).map(([extension2, contentType]) => ({
+            extension: extension2,
+            contentType
+          })),
+          overrides: Array.from(parsed.overrides.entries()).map(([partKey2, contentType]) => ({
+            partKey: partKey2,
+            contentType
+          }))
+        });
+      } catch (error50) {
+        if (!isAlreadySeededError(error50))
+          throw error50;
+      }
     }
-  }
-  return subtreePackageHandle(rootDoc, unit, SHARD_KIND.contentTypes);
+    return subtreePackageHandle(rootDoc, unit, SHARD_KIND.contentTypes);
+  }, "collab-v2:bootstrap:seed-unit");
 }
 async function connectStylesShard(rootDoc, shardId, part) {
-  const unit = createCollabUnitHandle({ rootDoc, shardId, shardKind: SHARD_KIND.styles });
-  let bootstrap;
-  if (part.bytes) {
-    const xml = TEXT_DECODER12.decode(part.bytes);
-    const parsed = parseStylesPart3(xml);
-    bootstrap = bootstrapPartProjection(xml);
-    try {
-      seedStylesShard({
-        doc: unit,
-        shardId,
-        ownerPartKey: part.partKey,
-        ownerPartUri: part.partUri,
-        documentDefaults: parsed.documentDefaults,
-        styles: parsed.styles
-      });
-    } catch (error50) {
-      if (!isAlreadySeededError(error50))
-        throw error50;
+  return rootDoc.transact(() => {
+    const unit = createCollabUnitHandle({ rootDoc, shardId, shardKind: SHARD_KIND.styles });
+    let bootstrap;
+    if (part.bytes) {
+      const xml = TEXT_DECODER12.decode(part.bytes);
+      const parsed = parseStylesPart3(xml);
+      bootstrap = bootstrapPartProjection(xml);
+      try {
+        seedStylesShard({
+          doc: unit,
+          shardId,
+          ownerPartKey: part.partKey,
+          ownerPartUri: part.partUri,
+          documentDefaults: parsed.documentDefaults,
+          styles: parsed.styles
+        });
+      } catch (error50) {
+        if (!isAlreadySeededError(error50))
+          throw error50;
+      }
     }
-  }
-  return subtreePackageHandle(rootDoc, unit, SHARD_KIND.styles, bootstrap);
+    return subtreePackageHandle(rootDoc, unit, SHARD_KIND.styles, bootstrap);
+  }, "collab-v2:bootstrap:seed-unit");
 }
 async function connectNumberingShard(rootDoc, shardId, part, numbering) {
-  const unit = createCollabUnitHandle({ rootDoc, shardId, shardKind: SHARD_KIND.numbering });
-  let bootstrap;
-  if (part.bytes) {
-    bootstrap = bootstrapPartProjection(TEXT_DECODER12.decode(part.bytes));
-  }
-  if (part.bytes && numbering.present) {
-    try {
-      seedNumberingShard({
-        doc: unit,
-        shardId,
-        ownerPartKey: part.partKey,
-        ownerPartUri: part.partUri,
-        abstractNums: Array.from(numbering.abstracts.values()).map((entry) => ({
-          abstractNumId: entry.abstractNumId,
-          multiLevelType: entry.multiLevelType,
-          rawXml: entry.rawXml,
-          levels: Array.from(entry.levels.values()).map((level) => ({
-            ilvl: level.ilvl,
-            numFmt: level.numFmt,
-            lvlText: level.lvlText,
-            start: level.start,
-            opaqueXml: null
-          }))
-        })),
-        nums: Array.from(numbering.instances.values()).map((entry) => ({
-          numId: entry.numId,
-          abstractNumId: entry.abstractNumId,
-          rawXml: entry.rawXml,
-          lvlOverrides: Array.from(entry.lvlOverrides.entries()).map(([ilvl, value2]) => ({
-            ilvl,
-            startOverride: value2.startOverride
+  return rootDoc.transact(() => {
+    const unit = createCollabUnitHandle({ rootDoc, shardId, shardKind: SHARD_KIND.numbering });
+    let bootstrap;
+    if (part.bytes) {
+      bootstrap = bootstrapPartProjection(TEXT_DECODER12.decode(part.bytes));
+    }
+    if (part.bytes && numbering.present) {
+      try {
+        seedNumberingShard({
+          doc: unit,
+          shardId,
+          ownerPartKey: part.partKey,
+          ownerPartUri: part.partUri,
+          abstractNums: Array.from(numbering.abstracts.values()).map((entry) => ({
+            abstractNumId: entry.abstractNumId,
+            multiLevelType: entry.multiLevelType,
+            rawXml: entry.rawXml,
+            levels: Array.from(entry.levels.values()).map((level) => ({
+              ilvl: level.ilvl,
+              numFmt: level.numFmt,
+              lvlText: level.lvlText,
+              start: level.start,
+              opaqueXml: null
+            }))
+          })),
+          nums: Array.from(numbering.instances.values()).map((entry) => ({
+            numId: entry.numId,
+            abstractNumId: entry.abstractNumId,
+            rawXml: entry.rawXml,
+            lvlOverrides: Array.from(entry.lvlOverrides.entries()).map(([ilvl, value2]) => ({
+              ilvl,
+              startOverride: value2.startOverride
+            }))
           }))
-        }))
-      });
-    } catch (error50) {
-      if (!isAlreadySeededError(error50))
-        throw error50;
+        });
+      } catch (error50) {
+        if (!isAlreadySeededError(error50))
+          throw error50;
+      }
     }
-  }
-  return subtreePackageHandle(rootDoc, unit, SHARD_KIND.numbering, bootstrap);
+    return subtreePackageHandle(rootDoc, unit, SHARD_KIND.numbering, bootstrap);
+  }, "collab-v2:bootstrap:seed-unit");
 }
 async function connectSettingsShard(rootDoc, shardId, settingsPart, webSettingsPart) {
-  const unit = createCollabUnitHandle({ rootDoc, shardId, shardKind: SHARD_KIND.settings });
-  const settingsBootstrap = settingsPart?.bytes ? bootstrapPartProjection(TEXT_DECODER12.decode(settingsPart.bytes)) : null;
-  const webSettingsBootstrap = webSettingsPart?.bytes ? bootstrapPartProjection(TEXT_DECODER12.decode(webSettingsPart.bytes)) : null;
-  if (settingsPart?.bytes || webSettingsPart?.bytes) {
-    try {
-      seedSettingsShard({
-        doc: unit,
-        shardId,
-        ownerPartKey: settingsPart?.partKey ?? encodeLogicalOwnerKey(SETTINGS_PART_URI7),
-        ownerPartUri: settingsPart?.partUri ?? SETTINGS_PART_URI7,
-        pairedPartKeys: [settingsPart?.partKey, webSettingsPart?.partKey].filter(Boolean),
-        settings: {
-          fields: {},
-          webFields: {},
-          opaqueXml: settingsPart?.bytes ? settingsInnerXmlWithNamespaceScope(TEXT_DECODER12.decode(settingsPart.bytes)) : null,
-          webOpaqueXml: webSettingsPart?.bytes ? settingsInnerXmlWithNamespaceScope(TEXT_DECODER12.decode(webSettingsPart.bytes)) : null
-        }
-      });
-    } catch (error50) {
-      if (!isAlreadySeededError(error50))
-        throw error50;
+  return rootDoc.transact(() => {
+    const unit = createCollabUnitHandle({ rootDoc, shardId, shardKind: SHARD_KIND.settings });
+    const settingsBootstrap = settingsPart?.bytes ? bootstrapPartProjection(TEXT_DECODER12.decode(settingsPart.bytes)) : null;
+    const webSettingsBootstrap = webSettingsPart?.bytes ? bootstrapPartProjection(TEXT_DECODER12.decode(webSettingsPart.bytes)) : null;
+    if (settingsPart?.bytes || webSettingsPart?.bytes) {
+      try {
+        seedSettingsShard({
+          doc: unit,
+          shardId,
+          ownerPartKey: settingsPart?.partKey ?? encodeLogicalOwnerKey(SETTINGS_PART_URI7),
+          ownerPartUri: settingsPart?.partUri ?? SETTINGS_PART_URI7,
+          pairedPartKeys: [settingsPart?.partKey, webSettingsPart?.partKey].filter(Boolean),
+          settings: {
+            fields: {},
+            webFields: {},
+            opaqueXml: settingsPart?.bytes ? settingsInnerXmlWithNamespaceScope(TEXT_DECODER12.decode(settingsPart.bytes)) : null,
+            webOpaqueXml: webSettingsPart?.bytes ? settingsInnerXmlWithNamespaceScope(TEXT_DECODER12.decode(webSettingsPart.bytes)) : null
+          }
+        });
+      } catch (error50) {
+        if (!isAlreadySeededError(error50))
+          throw error50;
+      }
     }
-  }
-  return subtreePackageHandle(rootDoc, unit, SHARD_KIND.settings, {
-    sourceXml: settingsBootstrap?.sourceXml ?? null,
-    rootOpenTagXml: settingsBootstrap?.rootOpenTagXml ?? null,
-    rootCloseTagXml: settingsBootstrap?.rootCloseTagXml ?? null,
-    containerOpenTagXml: webSettingsBootstrap?.rootOpenTagXml ?? null,
-    containerCloseTagXml: webSettingsBootstrap?.rootCloseTagXml ?? null
-  });
+    return subtreePackageHandle(rootDoc, unit, SHARD_KIND.settings, {
+      sourceXml: settingsBootstrap?.sourceXml ?? null,
+      rootOpenTagXml: settingsBootstrap?.rootOpenTagXml ?? null,
+      rootCloseTagXml: settingsBootstrap?.rootCloseTagXml ?? null,
+      containerOpenTagXml: webSettingsBootstrap?.rootOpenTagXml ?? null,
+      containerCloseTagXml: webSettingsBootstrap?.rootCloseTagXml ?? null
+    });
+  }, "collab-v2:bootstrap:seed-unit");
 }
 async function connectMediaManifestShard(rootDoc, shardId, parts, session, binaryMode) {
-  const unit = createCollabUnitHandle({ rootDoc, shardId, shardKind: SHARD_KIND.mediaManifest });
-  const assets = buildMediaAssets(parts, session, binaryMode);
-  if (assets.length > 0) {
-    try {
-      seedMediaManifestShard({
-        doc: unit,
-        shardId,
-        ownerPartKey: encodeLogicalOwnerKey(MEDIA_OWNER_URI2),
-        ownerPartUri: MEDIA_OWNER_URI2,
-        assets
-      });
-    } catch (error50) {
-      if (!isAlreadySeededError(error50))
-        throw error50;
+  return rootDoc.transact(() => {
+    const unit = createCollabUnitHandle({ rootDoc, shardId, shardKind: SHARD_KIND.mediaManifest });
+    const assets = buildMediaAssets(parts, session, binaryMode);
+    if (assets.length > 0) {
+      try {
+        seedMediaManifestShard({
+          doc: unit,
+          shardId,
+          ownerPartKey: encodeLogicalOwnerKey(MEDIA_OWNER_URI2),
+          ownerPartUri: MEDIA_OWNER_URI2,
+          assets
+        });
+      } catch (error50) {
+        if (!isAlreadySeededError(error50))
+          throw error50;
+      }
     }
-  }
-  return subtreePackageHandle(rootDoc, unit, SHARD_KIND.mediaManifest);
+    return subtreePackageHandle(rootDoc, unit, SHARD_KIND.mediaManifest);
+  }, "collab-v2:bootstrap:seed-unit");
 }
 async function connectBinaryShard(rootDoc, shardId, part, assetId, binaryMode, blobStore) {
-  const unit = createCollabUnitHandle({ rootDoc, shardId, shardKind: SHARD_KIND.binary });
-  if (part.bytes) {
-    try {
-      const payload = prepareSingleDocBinaryPayload(part.bytes, binaryMode, blobStore);
-      seedBinaryShard({
-        doc: unit,
-        shardId,
-        ownerPartKey: part.partKey,
-        ownerPartUri: part.partUri,
-        assetId,
-        mode: payload.mode,
-        contentType: part.contentType ?? "",
-        ...payload.mode === BINARY_MODE.blob ? {
-          blobRef: payload.blobRef,
-          sha256: payload.sha256,
-          byteLength: payload.byteLength
-        } : {
-          bytes: payload.bytes,
-          sha256: payload.sha256
-        }
-      });
-    } catch (error50) {
-      if (!isAlreadySeededError(error50))
-        throw error50;
+  return rootDoc.transact(() => {
+    const unit = createCollabUnitHandle({ rootDoc, shardId, shardKind: SHARD_KIND.binary });
+    if (part.bytes) {
+      try {
+        const payload = prepareSingleDocBinaryPayload(part.bytes, binaryMode, blobStore);
+        seedBinaryShard({
+          doc: unit,
+          shardId,
+          ownerPartKey: part.partKey,
+          ownerPartUri: part.partUri,
+          assetId,
+          mode: payload.mode,
+          contentType: part.contentType ?? "",
+          ...payload.mode === BINARY_MODE.blob ? {
+            blobRef: payload.blobRef,
+            sha256: payload.sha256,
+            byteLength: payload.byteLength
+          } : {
+            bytes: payload.bytes,
+            sha256: payload.sha256
+          }
+        });
+      } catch (error50) {
+        if (!isAlreadySeededError(error50))
+          throw error50;
+      }
     }
-  }
-  return subtreePackageHandle(rootDoc, unit, SHARD_KIND.binary);
+    return subtreePackageHandle(rootDoc, unit, SHARD_KIND.binary);
+  }, "collab-v2:bootstrap:seed-unit");
 }
 async function connectOpaqueShard(rootDoc, shardId, part, sourceZipSha256, binaryMode, blobStore) {
-  const unit = createCollabUnitHandle({ rootDoc, shardId, shardKind: SHARD_KIND.opaquePart });
-  if (part.bytes) {
-    try {
-      const payload = prepareSingleDocBinaryPayload(part.bytes, binaryMode, blobStore);
-      seedOpaquePartShard({
-        doc: unit,
-        shardId,
-        ownerPartKey: part.partKey,
-        ownerPartUri: part.partUri,
-        partKey: part.partKey,
-        partUri: part.partUri,
-        contentType: part.contentType,
-        mode: payload.mode,
-        ...payload.mode === BINARY_MODE.blob ? {
-          blobRef: payload.blobRef,
-          sha256: payload.sha256,
-          byteLength: payload.byteLength
-        } : {
-          bytes: payload.bytes,
-          sha256: payload.sha256
-        },
-        sourceProvenance: {
-          sha256Zip: sourceZipSha256,
-          committedAt: null,
-          committerId: null
-        }
-      });
-    } catch (error50) {
-      if (!isAlreadySeededError(error50))
-        throw error50;
+  return rootDoc.transact(() => {
+    const unit = createCollabUnitHandle({ rootDoc, shardId, shardKind: SHARD_KIND.opaquePart });
+    if (part.bytes) {
+      try {
+        const payload = prepareSingleDocBinaryPayload(part.bytes, binaryMode, blobStore);
+        seedOpaquePartShard({
+          doc: unit,
+          shardId,
+          ownerPartKey: part.partKey,
+          ownerPartUri: part.partUri,
+          partKey: part.partKey,
+          partUri: part.partUri,
+          contentType: part.contentType,
+          mode: payload.mode,
+          ...payload.mode === BINARY_MODE.blob ? {
+            blobRef: payload.blobRef,
+            sha256: payload.sha256,
+            byteLength: payload.byteLength
+          } : {
+            bytes: payload.bytes,
+            sha256: payload.sha256
+          },
+          sourceProvenance: {
+            sha256Zip: sourceZipSha256,
+            committedAt: null,
+            committerId: null
+          }
+        });
+      } catch (error50) {
+        if (!isAlreadySeededError(error50))
+          throw error50;
+      }
     }
-  }
-  return subtreePackageHandle(rootDoc, unit, SHARD_KIND.opaquePart);
+    return subtreePackageHandle(rootDoc, unit, SHARD_KIND.opaquePart);
+  }, "collab-v2:bootstrap:seed-unit");
 }
 function storyProjectionHandle(handle) {
   return {
@@ -485263,8 +485573,12 @@ function jsonSchemaPropertyToZod(prop, definitions = {}, resolvingReferences = n
     return describe3(intersection3);
   }
   switch (type) {
-    case "string":
-      return describe3(exports_external.string());
+    case "string": {
+      let schema = exports_external.string();
+      if (typeof prop.minLength === "number")
+        schema = schema.min(prop.minLength);
+      return describe3(schema);
+    }
     case "number": {
       let schema = exports_external.number();
       if (typeof prop.exclusiveMinimum === "number")