@beyondwork/docx-react-component 1.0.135 → 1.0.137

package/dist/{chunk-EPFVMUKF.js → chunk-M3AEVSKU.js}

@@ -18,7 +18,7 @@ import {
   resolveScopeRange,
   scopeSpecificity,
   searchDocument
-} from "./chunk-5CCYF333.js";
+} from "./chunk-NYIMPM3Z.js";
 import {
   BROADCAST_COMMAND_TYPES,
   COMMAND_EVENT_SCHEMA_VERSION,
@@ -41,7 +41,8 @@ import {
 import {
   chartModelStore,
   createEditorSurfaceSnapshot,
-  createFormattingContext
+  createFormattingContext,
+  storyTargetKey
 } from "./chunk-EZFF6GKF.js";
 import {
   createSelectionSnapshot,
@@ -61,6 +62,7 @@ import {
   GRADIENT_STOP_UNITS,
   MAIN_STORY_KEY,
   collectEditableTargetRefs,
+  collectStoryBlockContexts,
   createHeaderFooterStoryKey,
   createNoteStoryKey,
   validateEditableTargetRef
@@ -1329,9 +1331,23 @@ function findSurfaceBlockById(blocks, blockId) {
 }
 function createScopeFromAnchor(runtime, input) {
   const doc = runtime.getCanonicalDocument();
-  const storyTarget = input.anchor.storyTarget ?? { kind: "main" };
+  const normalizedInputAnchor = normalizeCreateScopeAnchor(input.anchor);
+  const storyTarget = normalizedInputAnchor.storyTarget ?? { kind: "main" };
   const storyLength = storyTarget.kind === "main" ? computeMainStoryLength(doc) : Number.MAX_SAFE_INTEGER;
-  const { from, to } = input.anchor;
+  const { from, to } = normalizedInputAnchor;
+  if (!Number.isFinite(from) || !Number.isFinite(to)) {
+    const diagnosticFrom = Number.isFinite(from) ? from : 0;
+    const diagnosticTo = Number.isFinite(to) ? to : diagnosticFrom;
+    return {
+      status: "range-invalid",
+      reason: "non-finite-range",
+      from: diagnosticFrom,
+      to: diagnosticTo,
+      storyLength,
+      message: `createScopeFromAnchor requires finite numeric from/to offsets. Pass selection.activeRange or an object shaped as {from, to}; do not pass a malformed range.`,
+      nextStep: "pass-selection-activeRange-or-finite-from-to"
+    };
+  }
   if (from < 0) {
     return {
       status: "range-invalid",
@@ -1429,6 +1445,29 @@ function createScopeFromAnchor(runtime, input) {
   }
   return { status: "created", scopeId: result.scopeId, anchor: result.anchor };
 }
+function normalizeCreateScopeAnchor(anchor) {
+  const candidate = anchor;
+  const activeRange = candidate.activeRange;
+  if (activeRange?.kind === "range") {
+    return {
+      from: activeRange.from,
+      to: activeRange.to,
+      storyTarget: candidate.storyTarget
+    };
+  }
+  if (candidate.kind === "range") {
+    return {
+      from: candidate.from ?? Number.NaN,
+      to: candidate.to ?? Number.NaN,
+      storyTarget: candidate.storyTarget
+    };
+  }
+  return {
+    from: candidate.from ?? Number.NaN,
+    to: candidate.to ?? Number.NaN,
+    storyTarget: candidate.storyTarget
+  };
+}
 
 // src/api/v3/runtime/workflow.ts
 var createScopeMetadata = {
@@ -1469,6 +1508,29 @@ var createScopeFromAnchorMetadata = {
   broadcastsVia: "crdt",
   rwdReference: "\xA7Runtime API \xA7 runtime.workflow.createScopeFromAnchor. Companion to createScope({blockId}) for sub-block ranges. Consumes from/to once to plant inline scope_marker_start/end; the returned scopeId is the durable reference (KI-P9)."
 };
+var createScopesMetadata = {
+  name: "runtime.workflow.createScopes",
+  status: "live-with-adapter",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/api/v3/workflow-create-scope-live.test.ts",
+    commit: "pending"
+  },
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "scope-created",
+    expectedDelta: "rail shows new scope chips; editor surface refreshes once after the bulk scope batch"
+  },
+  agentMetadata: {
+    readOrMutate: "mutate",
+    boundedScope: "selection",
+    auditCategory: "scope-creation"
+  },
+  stateClass: "A-canonical",
+  persistsTo: "customXml",
+  broadcastsVia: "crdt",
+  rwdReference: "\xA7Runtime API \xA7 runtime.workflow.createScopes. Bulk companion to createScope/createScopeFromAnchor; resolves blockId/range inputs, plants marker-backed scopes via one runtime addScopes batch, and returns per-item results."
+};
 var setScopeGuardPolicyMetadata = {
   name: "runtime.workflow.setScopeGuardPolicy",
   status: "live",
@@ -1564,6 +1626,228 @@ var setMarkupModePolicyMetadata = {
   broadcastsVia: "crdt",
   rwdReference: "\xA7Runtime API \xA7 runtime.workflow.setMarkupModePolicy"
 };
+function isAnchorScopeInput(input) {
+  return "anchor" in input;
+}
+function normalizeCreateScopesAnchor(anchor) {
+  const candidate = anchor;
+  const activeRange = candidate.activeRange;
+  if (activeRange?.kind === "range") {
+    return {
+      from: activeRange.from,
+      to: activeRange.to,
+      storyTarget: candidate.storyTarget
+    };
+  }
+  if (candidate.kind === "range") {
+    return {
+      from: candidate.from ?? Number.NaN,
+      to: candidate.to ?? Number.NaN,
+      storyTarget: candidate.storyTarget
+    };
+  }
+  return {
+    from: candidate.from ?? Number.NaN,
+    to: candidate.to ?? Number.NaN,
+    storyTarget: candidate.storyTarget
+  };
+}
+function stableRefMetadataFields(stableRefHint) {
+  if (stableRefHint === void 0) return void 0;
+  return [{
+    key: "stableRefHint",
+    valueType: "string",
+    value: stableRefHint
+  }];
+}
+function createRangeInvalidResult(inputIndex, reason, from, to, storyLength, detail) {
+  const base = {
+    inputIndex,
+    scopeId: "",
+    status: "range-invalid",
+    reason,
+    from,
+    to,
+    storyLength,
+    ...detail?.blockIndex !== void 0 ? { blockIndex: detail.blockIndex } : {},
+    ...detail?.blockKind !== void 0 ? { blockKind: detail.blockKind } : {}
+  };
+  switch (reason) {
+    case "non-finite-range":
+      return {
+        ...base,
+        message: `createScopes requires finite numeric from/to values (received from=${from}, to=${to}). Pass selection.activeRange or an object shaped as {from, to}.`,
+        nextStep: "pass-selection-activeRange-or-finite-from-to"
+      };
+    case "from-negative":
+      return {
+        ...base,
+        message: `createScopes requires from >= 0 (received from=${from}). Clamp negative values to 0 before calling.`,
+        nextStep: "clamp-from-to-zero"
+      };
+    case "to-less-than-from":
+      return {
+        ...base,
+        message: `createScopes requires to >= from (received from=${from}, to=${to}). Swap the two values before calling.`,
+        nextStep: "swap-from-and-to"
+      };
+    case "range-exceeds-story-length":
+      return {
+        ...base,
+        message: `createScopes requires to <= storyLength (received to=${to}, storyLength=${storyLength}). Re-derive positions from the current document and retry.`,
+        nextStep: "clamp-to-to-storyLength-or-pick-a-different-range"
+      };
+    case "non-paragraph-target":
+      return {
+        ...base,
+        message: `createScopes refused range [${from}, ${to}]: it targets a ${detail?.blockKind ?? "non-paragraph"} block. Pick a paragraph target or use a structural workflow scope.`,
+        nextStep: "pick-a-paragraph-target"
+      };
+    case "empty-document":
+      return {
+        ...base,
+        message: "createScopes refused: the target document has no blocks; initialize a document before creating scopes.",
+        nextStep: "initialize-document-before-creating-scopes"
+      };
+  }
+}
+function plantFailureToCreateScopesResult(pending, result) {
+  const status = result.plantStatus;
+  if (!status || status.planted !== false) {
+    return {
+      inputIndex: pending.inputIndex,
+      status: "created",
+      scopeId: result.scopeId
+    };
+  }
+  if (status.reason === "non-paragraph-target") {
+    return createRangeInvalidResult(
+      pending.inputIndex,
+      "non-paragraph-target",
+      pending.from,
+      pending.to,
+      status.storyLength ?? pending.storyLength,
+      {
+        blockIndex: status.blockIndex ?? -1,
+        blockKind: status.blockKind ?? "unknown"
+      }
+    );
+  }
+  if (status.reason === "range-out-of-bounds") {
+    return createRangeInvalidResult(
+      pending.inputIndex,
+      "range-exceeds-story-length",
+      pending.from,
+      pending.to,
+      status.storyLength ?? pending.storyLength
+    );
+  }
+  return createRangeInvalidResult(
+    pending.inputIndex,
+    "empty-document",
+    pending.from,
+    pending.to,
+    status.storyLength ?? pending.storyLength
+  );
+}
+function createScopesBulk(runtime, input) {
+  const doc = runtime.getCanonicalDocument();
+  const storyLength = runtime.getRenderSnapshot().surface?.storySize ?? 0;
+  const results = [];
+  const pending = [];
+  input.scopes.forEach((item, inputIndex) => {
+    const assoc = item.assoc ?? { start: 1, end: -1 };
+    const scopeMetadataFields = stableRefMetadataFields(item.stableRefHint);
+    if (isAnchorScopeInput(item)) {
+      const normalizedAnchor = normalizeCreateScopesAnchor(item.anchor);
+      const { from, to } = normalizedAnchor;
+      const itemStoryLength = normalizedAnchor.storyTarget?.kind === void 0 || normalizedAnchor.storyTarget.kind === "main" ? storyLength : Number.MAX_SAFE_INTEGER;
+      if (!Number.isFinite(from) || !Number.isFinite(to)) {
+        results.push(createRangeInvalidResult(inputIndex, "non-finite-range", from, to, itemStoryLength));
+        return;
+      }
+      if (from < 0) {
+        results.push(createRangeInvalidResult(inputIndex, "from-negative", from, to, itemStoryLength));
+        return;
+      }
+      if (to < from) {
+        results.push(createRangeInvalidResult(inputIndex, "to-less-than-from", from, to, itemStoryLength));
+        return;
+      }
+      if (to > itemStoryLength) {
+        results.push(createRangeInvalidResult(inputIndex, "range-exceeds-story-length", from, to, itemStoryLength));
+        return;
+      }
+      const anchor2 = {
+        kind: "range",
+        from,
+        to,
+        assoc
+      };
+      pending.push({
+        inputIndex,
+        request: {
+          anchor: anchor2,
+          scopeId: item.scopeId,
+          mode: item.mode,
+          persistence: item.persistence,
+          metadata: item.metadata,
+          label: item.label,
+          storyTarget: normalizedAnchor.storyTarget ?? { kind: "main" },
+          ...item.visibility ? { visibility: item.visibility } : {},
+          ...item.guardPolicy ? { guardPolicy: item.guardPolicy } : {},
+          ...scopeMetadataFields ? { scopeMetadataFields } : {}
+        },
+        from,
+        to,
+        storyLength: itemStoryLength
+      });
+      return;
+    }
+    const anchor = resolveBlockAnchorFromCanonical(doc, item.blockId, assoc);
+    if (!anchor || anchor.kind !== "range") {
+      results.push({
+        inputIndex,
+        scopeId: "",
+        status: "block-not-found"
+      });
+      return;
+    }
+    pending.push({
+      inputIndex,
+      request: {
+        anchor,
+        scopeId: item.scopeId,
+        mode: item.mode,
+        persistence: item.persistence,
+        metadata: item.metadata,
+        label: item.label,
+        ...item.visibility ? { visibility: item.visibility } : {},
+        ...item.guardPolicy ? { guardPolicy: item.guardPolicy } : {},
+        ...scopeMetadataFields ? { scopeMetadataFields } : {}
+      },
+      from: anchor.from,
+      to: anchor.to,
+      storyLength
+    });
+  });
+  const created = runtime.addScopes(pending.map((item) => item.request));
+  created.forEach((result, index) => {
+    const item = pending[index];
+    if (!item) return;
+    results.push(plantFailureToCreateScopesResult(item, result));
+  });
+  const sorted = results.sort((a, b) => a.inputIndex - b.inputIndex);
+  const createdCount = sorted.filter((item) => item.status === "created").length;
+  const blocked = sorted.length - createdCount;
+  return {
+    status: blocked === 0 ? "created" : createdCount > 0 ? "partial" : "blocked",
+    total: input.scopes.length,
+    created: createdCount,
+    blocked,
+    scopes: Object.freeze(sorted)
+  };
+}
 function createWorkflowFamily(runtime) {
   return {
     queryScopes(filter) {
@@ -1578,7 +1862,10 @@ function createWorkflowFamily(runtime) {
     createScope(input) {
       const adapterResult = createScopeFromBlockId(runtime, {
         blockId: input.blockId,
+        scopeId: input.scopeId,
         mode: input.mode,
+        persistence: input.persistence,
+        metadata: input.metadata,
         label: input.label,
         ...input.visibility ? { visibility: input.visibility } : {},
         ...input.guardPolicy ? { guardPolicy: input.guardPolicy } : {},
@@ -1612,6 +1899,25 @@ function createWorkflowFamily(runtime) {
       }
       return { scopeId: adapterResult.scopeId, status: "created" };
     },
+    createScopes(input) {
+      const result = createScopesBulk(runtime, input);
+      emitUxResponse(runtime, {
+        apiFn: createScopesMetadata.name,
+        intent: createScopesMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live",
+        uiVisible: true,
+        expectedDelta: createScopesMetadata.uxIntent.expectedDelta,
+        actualDelta: result.created > 0 ? {
+          kind: "inline-change",
+          payload: {
+            created: result.created,
+            blocked: result.blocked,
+            scopeIds: result.scopes.filter((scope) => scope.status === "created").map((scope) => scope.scopeId)
+          }
+        } : void 0
+      });
+      return result;
+    },
     getScopeGuardPolicy(scopeId) {
       return runtime.getScopeGuardPolicy(scopeId);
     },
@@ -1647,7 +1953,10 @@ function createWorkflowFamily(runtime) {
     createScopeFromAnchor(input) {
       const adapterResult = createScopeFromAnchor(runtime, {
         anchor: input.anchor,
+        scopeId: input.scopeId,
         mode: input.mode,
+        persistence: input.persistence,
+        metadata: input.metadata,
         label: input.label,
         ...input.visibility ? { visibility: input.visibility } : {},
         ...input.guardPolicy ? { guardPolicy: input.guardPolicy } : {},
@@ -3969,7 +4278,8 @@ var SUPPORTED_COMMANDS = [
   "indent",
   "outdent",
   "restart-numbering",
-  "continue-numbering"
+  "continue-numbering",
+  "set-value"
 ];
 var UNSUPPORTED_COMMANDS = [
   "create",
@@ -3978,7 +4288,6 @@ var UNSUPPORTED_COMMANDS = [
   "join",
   "separate",
   "split",
-  "set-value",
   "apply-template",
   "capture-template",
   "apply-preset",
@@ -4026,11 +4335,17 @@ function createListsFamily(runtime) {
       const resolved = resolveCurrentListTarget(runtime.getCanonicalDocument(), input);
       return resolved.kind === "resolved" ? toReadback(runtime.getCanonicalDocument(), resolved.target, resolved.paragraph) : null;
     },
+    canJoin(input) {
+      return sequencePreflight(runtime.getCanonicalDocument(), input, activeStoryKey(runtime));
+    },
+    canContinuePrevious(input) {
+      return sequencePreflight(runtime.getCanonicalDocument(), input, activeStoryKey(runtime));
+    },
     previewCommand(input) {
-      return previewListCommand(runtime.getCanonicalDocument(), input);
+      return previewListCommand(runtime.getCanonicalDocument(), input, activeStoryKey(runtime));
     },
     applyCommand(input) {
-      const preview = previewListCommand(runtime.getCanonicalDocument(), input);
+      const preview = previewListCommand(runtime.getCanonicalDocument(), input, activeStoryKey(runtime));
       if (!preview.supported || !preview.target) {
         return {
           applied: false,
@@ -4090,7 +4405,38 @@ function createListsFamily(runtime) {
     }
   };
 }
-function previewListCommand(document, input) {
+function sequencePreflight(document, input, activeStoryKey2) {
+  const resolved = resolveCurrentListTarget(document, input);
+  if (resolved.kind !== "resolved") {
+    return {
+      canJoin: false,
+      canContinuePrevious: false,
+      blockers: [resolved.blocker]
+    };
+  }
+  const target = toReadback(document, resolved.target, resolved.paragraph);
+  const targetRef = { targetKey: target.targetKey, addressKey: target.addressKey };
+  if (activeStoryKey2 !== void 0 && target.storyKey !== activeStoryKey2) {
+    return {
+      target,
+      canJoin: false,
+      canContinuePrevious: false,
+      blockers: [{
+        code: "list-target-wrong-story",
+        ownerLayer: "L07",
+        message: "List target does not belong to the runtime active story.",
+        ...targetRef
+      }]
+    };
+  }
+  return {
+    target,
+    canJoin: canJoinPreviousSequence(document, resolved.paragraphIndex),
+    canContinuePrevious: canContinuePreviousSequence(document, resolved.paragraphIndex),
+    blockers: []
+  };
+}
+function previewListCommand(document, input, activeStoryKey2) {
   const resolved = resolveCurrentListTarget(document, input);
   if (resolved.kind !== "resolved") {
     return {
@@ -4102,6 +4448,20 @@ function previewListCommand(document, input) {
   }
   const target = toReadback(document, resolved.target, resolved.paragraph);
   const targetRef = { targetKey: target.targetKey, addressKey: target.addressKey };
+  if (activeStoryKey2 !== void 0 && target.storyKey !== activeStoryKey2) {
+    return {
+      command: input.command,
+      supported: false,
+      target,
+      affectedTargets: [target],
+      blockers: [{
+        code: "list-target-wrong-story",
+        ownerLayer: "L07",
+        message: "List target does not belong to the runtime active story.",
+        ...targetRef
+      }]
+    };
+  }
   if (!SUPPORTED_COMMANDS.includes(input.command)) {
     return {
       command: input.command,
@@ -4114,6 +4474,17 @@ function previewListCommand(document, input) {
   const canContinuePrevious = canContinuePreviousSequence(document, resolved.paragraphIndex);
   const canJoin = canJoinPreviousSequence(document, resolved.paragraphIndex);
   const blockers = [];
+  if (input.command === "set-value") {
+    const value = input.startAt;
+    if (!Number.isInteger(value) || value === void 0 || value < 1) {
+      blockers.push({
+        code: "list-command-preflight-blocked",
+        ownerLayer: "L07",
+        message: "runtime.lists.set-value requires a positive integer startAt value.",
+        ...targetRef
+      });
+    }
+  }
   if (input.command === "continue-numbering" && !canContinuePrevious) {
     blockers.push({
       code: "list-continue-target-missing",
@@ -4144,6 +4515,7 @@ function editorCommandForListCommand(command, editableTarget, timestamp, startAt
     case "outdent":
       return { type: "list.outdent", editableTargets: [editableTarget], origin };
     case "restart-numbering":
+    case "set-value":
       return {
         type: "list.restart-numbering",
         editableTarget,
@@ -4227,33 +4599,35 @@ function resolveCurrentListTarget(document, input) {
   return { kind: "resolved", ...resolved };
 }
 function currentListTargets(document) {
-  const paragraphs = collectParagraphEntries(document.content.children, "main");
+  const paragraphs = collectParagraphEntries(document);
   const targets = collectEditableTargetRefs(document).filter(isListTextTarget);
-  const byBlockPath = /* @__PURE__ */ new Map();
-  for (const target of targets) byBlockPath.set(target.blockPath, target);
+  const byStoryBlockPath = /* @__PURE__ */ new Map();
+  for (const target of targets) byStoryBlockPath.set(storyBlockPathKey(target.storyKey, target.blockPath), target);
   const out = [];
   for (let paragraphIndex = 0; paragraphIndex < paragraphs.length; paragraphIndex += 1) {
     const entry = paragraphs[paragraphIndex];
     if (!entry?.paragraph.numbering) continue;
-    const target = byBlockPath.get(entry.blockPath);
+    const target = byStoryBlockPath.get(storyBlockPathKey(entry.storyKey, entry.blockPath));
     if (!target) continue;
-    out.push({ target, paragraph: entry.paragraph, paragraphIndex });
+    out.push({ target, paragraph: entry.paragraph, paragraphIndex, storyKey: entry.storyKey });
   }
   return out;
 }
-function collectParagraphEntries(blocks, basePath) {
+function collectParagraphEntries(document) {
   const out = [];
-  collectParagraphEntriesInto(blocks, basePath, out);
+  for (const context of collectStoryBlockContexts(document)) {
+    collectParagraphEntriesInto(context.blocks, context.storyKey, context.basePath, out);
+  }
   return out;
 }
-function collectParagraphEntriesInto(blocks, basePath, out) {
+function collectParagraphEntriesInto(blocks, storyKey, basePath, out) {
   for (let blockIndex = 0; blockIndex < blocks.length; blockIndex += 1) {
     const block = blocks[blockIndex];
     if (!block) continue;
     const blockPath = `${basePath}/block[${blockIndex}]`;
     switch (block.type) {
       case "paragraph":
-        out.push({ paragraph: block, blockPath });
+        out.push({ paragraph: block, storyKey, blockPath, containerPath: basePath });
         break;
       case "table":
         for (let rowIndex = 0; rowIndex < block.rows.length; rowIndex += 1) {
@@ -4264,6 +4638,7 @@ function collectParagraphEntriesInto(blocks, basePath, out) {
             if (!cell) continue;
             collectParagraphEntriesInto(
               cell.children,
+              storyKey,
               `${blockPath}/row[${rowIndex}]/cell[${cellIndex}]`,
               out
             );
@@ -4271,7 +4646,7 @@ function collectParagraphEntriesInto(blocks, basePath, out) {
         }
         break;
       case "sdt":
-        collectParagraphEntriesInto(block.children, blockPath, out);
+        collectParagraphEntriesInto(block.children, storyKey, blockPath, out);
         break;
       case "custom_xml":
         break;
@@ -4315,13 +4690,17 @@ function toReadback(document, target, paragraph) {
   };
 }
 function canContinuePreviousSequence(document, paragraphIndex) {
-  const paragraphs = collectParagraphEntries(document.content.children, "main");
-  const current = paragraphs[paragraphIndex]?.paragraph;
+  const paragraphs = collectParagraphEntries(document);
+  const currentEntry = paragraphs[paragraphIndex];
+  const current = currentEntry?.paragraph;
   if (!current?.numbering) return false;
   const currentKind = getListKind(document.numbering, current.numbering.numberingInstanceId);
   if (!currentKind) return false;
   for (let index = paragraphIndex - 1; index >= 0; index -= 1) {
-    const previous = paragraphs[index]?.paragraph;
+    const previousEntry = paragraphs[index];
+    if (previousEntry?.storyKey !== currentEntry.storyKey) break;
+    if (previousEntry.containerPath !== currentEntry.containerPath) break;
+    const previous = previousEntry.paragraph;
     if (!previous?.numbering) continue;
     const previousKind = getListKind(document.numbering, previous.numbering.numberingInstanceId);
     return previousKind === currentKind && previous.numbering.numberingInstanceId !== current.numbering.numberingInstanceId;
@@ -4329,14 +4708,26 @@ function canContinuePreviousSequence(document, paragraphIndex) {
   return false;
 }
 function canJoinPreviousSequence(document, paragraphIndex) {
-  const paragraphs = collectParagraphEntries(document.content.children, "main");
-  const current = paragraphs[paragraphIndex]?.paragraph;
-  const previous = paragraphs[paragraphIndex - 1]?.paragraph;
+  const paragraphs = collectParagraphEntries(document);
+  const currentEntry = paragraphs[paragraphIndex];
+  const previousEntry = paragraphs[paragraphIndex - 1];
+  if (previousEntry?.storyKey !== currentEntry?.storyKey) return false;
+  if (previousEntry?.containerPath !== currentEntry?.containerPath) return false;
+  const current = currentEntry?.paragraph;
+  const previous = previousEntry?.paragraph;
   if (!current?.numbering || !previous?.numbering) return false;
   const currentKind = getListKind(document.numbering, current.numbering.numberingInstanceId);
   const previousKind = getListKind(document.numbering, previous.numbering.numberingInstanceId);
   return Boolean(currentKind) && currentKind === previousKind && current.numbering.numberingInstanceId !== previous.numbering.numberingInstanceId;
 }
+function storyBlockPathKey(storyKey, blockPath) {
+  return `${storyKey}
+${blockPath}`;
+}
+function activeStoryKey(runtime) {
+  const activeStory = runtime.getRenderSnapshot()?.activeStory;
+  return activeStory ? storyTargetKey(activeStory) : void 0;
+}
 function unsupportedCommandBlocker(command, target) {
   return {
     code: "list-command-unsupported",
@@ -8631,33 +9022,51 @@ function createPlaceholderScopes(runtime, input) {
       blockerDetails: Object.freeze([detail])
     };
   }
-  const compiler = createScopeCompilerService(runtime);
   const byOriginalIndex = /* @__PURE__ */ new Map();
-  for (const item of orderedHits) {
+  const createdScopeIds = [];
+  const scopeRequests = orderedHits.map((item) => {
     const text = item.text || query;
     const label = input.labelPrefix === void 0 ? text : `${input.labelPrefix} ${item.originalIndex + 1}`;
-    const result = createScopeFromAnchor(runtime, {
-      anchor: { from: item.hit.from, to: item.hit.to },
+    return {
+      anchor: {
+        kind: "range",
+        from: item.hit.from,
+        to: item.hit.to,
+        assoc: input.assoc ?? { start: 1, end: -1 }
+      },
       mode: input.mode ?? "edit",
       label,
       ...input.visibility ? { visibility: input.visibility } : {},
       ...input.guardPolicy ? { guardPolicy: input.guardPolicy } : {},
       ...input.assoc ? { assoc: input.assoc } : {},
-      ...input.stableRefHint ? { stableRefHint: input.stableRefHint } : {}
-    });
-    if (result.status === "created") {
-      const compiled = compiler.compileScopeById(result.scopeId)?.scope;
+      ...input.stableRefHint ? {
+        scopeMetadataFields: [
+          {
+            key: "stableRefHint",
+            valueType: "string",
+            value: input.stableRefHint
+          }
+        ]
+      } : {}
+    };
+  });
+  const scopeResults = runtime.addScopes(scopeRequests);
+  orderedHits.forEach((item, requestIndex) => {
+    const text = item.text || query;
+    const result = scopeResults[requestIndex];
+    if (result && result.scopeId && result.plantStatus?.planted !== false) {
+      createdScopeIds.push(result.scopeId);
       byOriginalIndex.set(item.originalIndex, {
         status: "created",
         text,
         excerpt: excerpt(text),
-        scopeId: result.scopeId,
-        ...compiled?.handle ? { handle: compiled.handle } : {}
+        scopeId: result.scopeId
       });
-      continue;
+      return;
     }
+    const reason = result?.plantStatus?.reason ?? "unknown";
     const detail = blockerWithOwner(
-      `actions:placeholder-scopes:create-refused:${result.reason}`,
+      `actions:placeholder-scopes:create-refused:${reason}`,
       "blocked",
       "The placeholder match could not be converted into a workflow scope.",
       "Refresh the document and retry; if it still refuses, route the target to the workflow/scope writer owner.",
@@ -8670,6 +9079,38 @@ function createPlaceholderScopes(runtime, input) {
       blockers: Object.freeze([detail.code]),
       blockerDetails: Object.freeze([detail])
     });
+  });
+  if (createdScopeIds.length > 0) {
+    const createdScopeIdSet = new Set(createdScopeIds);
+    const handlesByScopeId = new Map(
+      createScopeCompilerService(runtime).compileAllScopes().filter((scope) => createdScopeIdSet.has(scope.handle.scopeId)).map((scope) => [scope.handle.scopeId, scope.handle])
+    );
+    for (const [originalIndex, item] of byOriginalIndex) {
+      if (item.status !== "created" || !item.scopeId) continue;
+      const handle = handlesByScopeId.get(item.scopeId);
+      if (!handle) {
+        const detail = blockerWithOwner(
+          `actions:placeholder-scopes:create-unresolved:${item.scopeId}`,
+          "blocked",
+          "The placeholder scope marker was planted but did not enumerate as a current semantic scope handle.",
+          "Treat this target as unresolved, refresh scope enumeration, and route persistent misses to the semantic-scope compiler owner.",
+          "L08"
+        );
+        byOriginalIndex.set(originalIndex, {
+          status: "blocked",
+          text: item.text,
+          excerpt: item.excerpt,
+          scopeId: item.scopeId,
+          blockers: Object.freeze([detail.code]),
+          blockerDetails: Object.freeze([detail])
+        });
+        continue;
+      }
+      byOriginalIndex.set(originalIndex, {
+        ...item,
+        handle
+      });
+    }
   }
   const scopes = orderedHits.map((item) => byOriginalIndex.get(item.originalIndex)).filter((value) => value !== void 0);
   const created = scopes.filter((scope) => scope.status === "created").length;
@@ -9132,6 +9573,9 @@ function applyRewrite(runtime, target, input) {
   if (target.kind === "editable-text") {
     return applyEditableTextRewrite(runtime, target, input);
   }
+  if (target.handle.provenance === "marker-backed" && (target.scope.kind === "paragraph" || target.scope.kind === "list-item")) {
+    return applyMarkerBackedRangeRewrite(runtime, target, input);
+  }
   if (target.scope.kind === "list-item") {
     const listTextTarget = uniqueListTextActionForScope(runtime, target.handle);
     if (!listTextTarget.ok) return blockedApplyFromResolution(listTextTarget);
@@ -9278,13 +9722,97 @@ function applyEditableTextRewrite(runtime, target, input) {
     afterReadback
   };
 }
+function applyMarkerBackedRangeRewrite(runtime, target, input) {
+  const range = buildScopePositionMap(runtime.getCanonicalDocument()).markerScopes.get(
+    target.handle.scopeId
+  );
+  if (!range) {
+    return blockedApply(
+      `actions:rewrite:marker-range-unresolved:${target.handle.scopeId}`,
+      "unresolved-target",
+      "The marker-backed scope could not be joined to its current marker range.",
+      "Refresh placeholder scopes and retry; route persistent failures to L06 marker scope tracking."
+    );
+  }
+  const beforeReadback = markerScopeReadback(runtime, target.handle.scopeId) ?? {
+    text: target.scope.content.text,
+    isEmpty: target.scope.content.text.length === 0
+  };
+  const before = runtime.getCanonicalDocument();
+  const origin = actionOrigin(runtime, input);
+  runtime.dispatch({
+    type: "selection.set",
+    selection: {
+      anchor: range.from,
+      head: range.to,
+      isCollapsed: range.from === range.to,
+      activeRange: {
+        kind: "range",
+        from: range.from,
+        to: range.to,
+        assoc: { start: -1, end: 1 }
+      }
+    },
+    origin
+  });
+  const ack = runtime.applyActiveStoryTextCommand({
+    type: "text.insert",
+    text: input.text,
+    origin
+  });
+  const changed = runtime.getCanonicalDocument() !== before;
+  const afterReadback = markerScopeReadback(runtime, target.handle.scopeId);
+  const compiledAfter = createScopeCompilerService(runtime).compileScopeById(target.handle.scopeId);
+  if (!changed || afterReadback?.text !== input.text) {
+    return {
+      status: "blocked",
+      applied: false,
+      changed,
+      target: summarizeTarget(
+        compiledAfter ? { ...target, scope: compiledAfter.scope, handle: compiledAfter.scope.handle } : target
+      ),
+      posture: "suspect-readback",
+      blockers: Object.freeze([
+        `actions:rewrite:marker-range-readback-mismatch:${target.handle.scopeId}`
+      ]),
+      blockerDetails: Object.freeze([
+        blocker(
+          `actions:rewrite:marker-range-readback-mismatch:${target.handle.scopeId}`,
+          "blocked",
+          ack.kind === "rejected" ? "The marker-backed rewrite command was rejected or did not produce the requested marker readback." : "The marker-backed rewrite command did not produce the requested marker readback.",
+          "Treat the mutation as suspect. Re-read the target and export before claiming success."
+        )
+      ]),
+      ...afterReadback ? { afterReadback } : {}
+    };
+  }
+  return {
+    status: "applied",
+    applied: true,
+    changed: true,
+    target: summarizeTarget(
+      compiledAfter ? { ...target, scope: compiledAfter.scope, handle: compiledAfter.scope.handle } : target
+    ),
+    commandReference: {
+      command: "text.insert",
+      actorId: input.actorId ?? "v3-ai-api",
+      origin: input.origin ?? "agent",
+      emittedAtUtc: currentAuditTimestamp(runtime)
+    },
+    beforeReadback,
+    afterReadback
+  };
+}
 function applyTableScopedMarkerRewrite(runtime, target, action, input) {
   const workflowScope = runtime.getScope(target.handle.scopeId);
+  const markerRange = buildScopePositionMap(runtime.getCanonicalDocument()).markerScopes.get(
+    target.handle.scopeId
+  );
   const editableTarget = tableEditableTargetForActionHandle(
     runtime,
     action.actionHandle
   );
-  if (!workflowScope || workflowScope.anchor.kind !== "range" || !editableTarget) {
+  if (!workflowScope || !markerRange || !editableTarget) {
     return blockedApply(
       `actions:rewrite:table-marker-target-unresolved:${target.handle.scopeId}`,
       "unresolved-target",
@@ -9292,19 +9820,23 @@ function applyTableScopedMarkerRewrite(runtime, target, action, input) {
       "Refresh placeholder scopes and retry; route persistent failures to L08 table scope target mapping."
     );
   }
+  const beforeReadback = markerScopeReadback(runtime, target.handle.scopeId) ?? {
+    text: target.scope.content.text,
+    isEmpty: target.scope.content.text.length === 0
+  };
   const before = runtime.getCanonicalDocument();
   try {
     runtime.dispatch({
       type: "selection.set",
       selection: {
-        anchor: workflowScope.anchor.from,
-        head: workflowScope.anchor.to,
-        isCollapsed: workflowScope.anchor.from === workflowScope.anchor.to,
+        anchor: markerRange.from,
+        head: markerRange.to,
+        isCollapsed: markerRange.from === markerRange.to,
         activeRange: {
           kind: "range",
-          from: workflowScope.anchor.from,
-          to: workflowScope.anchor.to,
-          assoc: workflowScope.anchor.assoc ?? { start: -1, end: 1 }
+          from: markerRange.from,
+          to: markerRange.to,
+          assoc: { start: -1, end: 1 }
         }
       },
       origin: actionOrigin(runtime, input)
@@ -9339,12 +9871,19 @@ function applyTableScopedMarkerRewrite(runtime, target, action, input) {
   );
   const afterText = paragraph ? collectInlineText3(paragraph.children) : void 0;
   const afterReadback = afterText === void 0 ? void 0 : { text: afterText, isEmpty: afterText.length === 0 };
-  if (!changed || afterReadback?.text !== input.text) {
+  const compiledAfter = createScopeCompilerService(runtime).compileScopeById(target.handle.scopeId);
+  const scopeReadback = markerScopeReadback(runtime, target.handle.scopeId) ?? (compiledAfter ? {
+    text: compiledAfter.scope.content.text,
+    isEmpty: compiledAfter.scope.content.text.length === 0
+  } : void 0);
+  if (!changed || scopeReadback?.text !== input.text) {
     return {
       status: "blocked",
       applied: false,
       changed,
-      target: summarizeTarget({ kind: "table-text", action }),
+      target: summarizeTarget(
+        compiledAfter ? { ...target, scope: compiledAfter.scope, handle: compiledAfter.scope.handle } : target
+      ),
       posture: "suspect-readback",
       blockers: Object.freeze([
         `actions:rewrite:table-marker-readback-mismatch:${target.handle.scopeId}`
@@ -9357,25 +9896,24 @@ function applyTableScopedMarkerRewrite(runtime, target, action, input) {
           "Treat the mutation as suspect. Re-read the target and export before claiming success."
         )
       ]),
-      ...afterReadback ? { afterReadback } : {}
+      ...scopeReadback ? { afterReadback: scopeReadback } : afterReadback ? { afterReadback } : {}
     };
   }
   return {
     status: "applied",
     applied: true,
     changed: true,
-    target: summarizeTarget({
-      kind: "table-text",
-      action: { ...action, readback: afterReadback }
-    }),
+    target: summarizeTarget(
+      compiledAfter ? { ...target, scope: compiledAfter.scope, handle: compiledAfter.scope.handle } : { kind: "table-text", action: { ...action, readback: scopeReadback } }
+    ),
     commandReference: {
       command: "text.insert",
       actorId: input.actorId ?? "v3-ai-api",
       origin: input.origin ?? "agent",
       emittedAtUtc: currentAuditTimestamp(runtime)
     },
-    ...action.readback ? { beforeReadback: action.readback } : {},
-    afterReadback
+    beforeReadback,
+    afterReadback: scopeReadback
   };
 }
 function projectRewriteScopeResult(runtime, result, target, beforeText, proposedText, documentMutated) {
@@ -9469,7 +10007,7 @@ function summarizeTarget(target) {
   if (target.kind === "editable-text") {
     return {
       kind: target.targetKind,
-      handle: target.ownerHandle,
+      handle: publicActionScopeHandle(target.ownerHandle),
       actionHandle: target.actionHandle,
       readback: target.readback,
       canRewriteText: true,
@@ -9480,13 +10018,21 @@ function summarizeTarget(target) {
   }
   return {
     kind: target.scope.kind,
-    handle: target.handle,
+    handle: publicActionScopeHandle(target.handle),
     canRewriteText: canRewriteScopeText(target.scope),
     canInsertAdjacentText: canInsertAdjacentScopeText(target.scope),
     canFlag: true,
     canMark: canMarkScope(target.scope)
   };
 }
+function publicActionScopeHandle(handle) {
+  const parentScopeId = handle.parentScopeId;
+  if (!parentScopeId || !/^(cell|table|row|column|span):/u.test(parentScopeId)) {
+    return handle;
+  }
+  const { parentScopeId: _parentScopeId, ...rest } = handle;
+  return rest;
+}
 function tableTextActionsForScope(runtime, handle) {
   const result = createTableActionFamily(runtime).listTableActions({
     handle,
@@ -9539,6 +10085,13 @@ function tableEditableTargetForActionHandle(runtime, actionHandle) {
   }
   return null;
 }
+function markerScopeReadback(runtime, scopeId) {
+  const document = runtime.getCanonicalDocument();
+  const range = buildScopePositionMap(document).markerScopes.get(scopeId);
+  if (!range) return null;
+  const text = textForCanonicalRange(document, range.from, range.to);
+  return { text, isEmpty: text.length === 0 };
+}
 function editableTextActionsForScope(runtime, handle) {
   const bundle = createScopeCompilerService(runtime).compileBundleById(
     handle.scopeId,
@@ -10891,6 +11444,86 @@ function blockTextLength(block) {
       return 0;
   }
 }
+function textForCanonicalRange(document, from, to) {
+  let cursor = 0;
+  let text = "";
+  const append = (value, start, end) => {
+    const clippedFrom = Math.max(from, start);
+    const clippedTo = Math.min(to, end);
+    if (clippedTo <= clippedFrom) return;
+    const localFrom = clippedFrom - start;
+    const localTo = clippedTo - start;
+    text += Array.from(value).slice(localFrom, localTo).join("");
+  };
+  const walkInline = (inline) => {
+    const start = cursor;
+    switch (inline.type) {
+      case "text": {
+        const length = Array.from(inline.text).length;
+        cursor += length;
+        append(inline.text, start, cursor);
+        return length;
+      }
+      case "tab":
+        cursor += 1;
+        append("	", start, cursor);
+        return 1;
+      case "hard_break":
+        cursor += 1;
+        append("\n", start, cursor);
+        return 1;
+      case "hyperlink":
+      case "field": {
+        const before = cursor;
+        for (const child of inline.children) {
+          walkInline(child);
+        }
+        return cursor - before;
+      }
+      case "bookmark_start":
+      case "bookmark_end":
+      case "scope_marker_start":
+      case "scope_marker_end":
+        return 0;
+      default:
+        cursor += 1;
+        return 1;
+    }
+  };
+  const walkBlock = (block) => {
+    if (!block) return 0;
+    const before = cursor;
+    switch (block.type) {
+      case "paragraph":
+        for (const child of block.children) walkInline(child);
+        break;
+      case "table":
+        for (const row of block.rows) {
+          for (const cell of row.cells) {
+            for (const child of cell.children) walkBlock(child);
+          }
+        }
+        break;
+      case "sdt":
+      case "custom_xml":
+        for (const child of block.children) walkBlock(child);
+        break;
+      default:
+        cursor += 1;
+        break;
+    }
+    return cursor - before;
+  };
+  const blocks = document.content.children;
+  for (let index = 0; index < blocks.length; index += 1) {
+    walkBlock(blocks[index]);
+    if (index < blocks.length - 1 && blocks[index + 1]?.type === "paragraph") {
+      cursor += 1;
+      append("\n", cursor - 1, cursor);
+    }
+  }
+  return text;
+}
 function inlineTextLength(inline) {
   if (!inline) return 0;
   switch (inline.type) {
@@ -11046,6 +11679,109 @@ function summarizePlanResult(mode, steps) {
   };
 }
 
+// src/api/v3/ai/agent.ts
+function createAgentFamily(runtime, pe2Evidence) {
+  const inspect = createInspectFamily(runtime, pe2Evidence);
+  const resolve = createResolveFamily(runtime);
+  const bundle = createBundleFamily(runtime, pe2Evidence);
+  const actions = createActionsFamily(runtime).actions;
+  const table = createTableActionFamily(runtime);
+  const object = createObjectActionFamily(runtime);
+  const policy = createPolicyFamily(runtime);
+  const evaluate = createEvaluateFamily(runtime);
+  const outline = createOutlineFamily(runtime);
+  const stats = createStatsFamily(runtime);
+  const explain = createExplainFamily(runtime);
+  const review = createReviewFamily2(runtime);
+  const exportFamily = createExportFamily(runtime);
+  const read = Object.freeze({
+    inspectDocument: inspect.inspectDocument,
+    listScopes: inspect.listScopes,
+    getScope: bundle.getScope,
+    getScopeBundle: bundle.getScopeBundle,
+    resolveReference: resolve.resolveReference,
+    queryScopeAtPosition: resolve.queryScopeAtPosition,
+    queryScopeInRange: resolve.queryScopeInRange,
+    brief: actions.brief,
+    getDocumentOutline: outline.getDocumentOutline,
+    getDocumentStatistics: stats.getDocumentStatistics,
+    explainFormatting: explain.explainFormatting
+  });
+  const target = Object.freeze({
+    discover: actions.discover,
+    locate: actions.locate,
+    locateAll: actions.locateAll,
+    createPlaceholderScopes: actions.createPlaceholderScopes
+  });
+  const edit = Object.freeze({
+    rewrite: actions.rewrite,
+    runPlan: actions.runPlan,
+    insertText: actions.insertText,
+    mark: actions.mark,
+    flag: actions.flag,
+    flagMany: actions.flagMany,
+    fieldRefresh: actions.fieldRefresh,
+    tocRefresh: actions.tocRefresh,
+    bookmarkEdit: actions.bookmarkEdit,
+    hyperlinkDestinationEdit: actions.hyperlinkDestinationEdit,
+    hyperlinkTextEdit: actions.hyperlinkTextEdit
+  });
+  const template = Object.freeze({
+    validateTargets: actions.validateTemplateTargets,
+    readTarget: actions.templateTargetRead,
+    fillField: actions.templateFieldFill
+  });
+  const tableGroup = Object.freeze({
+    replaceContent: actions.tableContent,
+    applyFragment: actions.tableFragment,
+    applySelection: actions.tableSelection,
+    listActions: table.listTableActions,
+    applyAction: table.applyTableAction
+  });
+  const list = Object.freeze({
+    applyOperation: actions.listOperation
+  });
+  const objectGroup = Object.freeze({
+    listActions: object.listObjectActions,
+    applyAction: object.applyObjectAction
+  });
+  const reviewGroup = Object.freeze({
+    acceptRevision: review.acceptRevision,
+    rejectRevision: review.rejectRevision,
+    resolveCommentThread: review.resolveCommentThread,
+    resolveIssue: review.resolveIssue,
+    reopenIssue: review.reopenIssue
+  });
+  const policyGroup = Object.freeze({
+    getPolicy: policy.getPolicy,
+    listActions: policy.listAIActions,
+    evaluateAction: evaluate.evaluateAction
+  });
+  const exportGroup = Object.freeze({
+    reviewedDocument: exportFamily.exportReviewedDocument
+  });
+  const category = Object.freeze({
+    read,
+    target,
+    edit,
+    template,
+    table: tableGroup,
+    list,
+    object: objectGroup,
+    review: reviewGroup,
+    policy: policyGroup,
+    export: exportGroup
+  });
+  const family = {
+    agent() {
+      return category;
+    }
+  };
+  return {
+    agent: family.agent()
+  };
+}
+
 // src/api/v3/_create.ts
 function createApiV3(handle, opts) {
   const ai = {
@@ -11063,7 +11799,8 @@ function createApiV3(handle, opts) {
     ...createOutlineFamily(handle),
     ...createTableActionFamily(handle),
     ...createObjectActionFamily(handle),
-    ...createActionsFamily(handle)
+    ...createActionsFamily(handle),
+    ...createAgentFamily(handle, opts?.pe2Evidence)
   };
   const runtime = {
     document: createDocumentFamily(handle),