@beyondwork/docx-react-component 1.0.126 → 1.0.128

package/dist/index.cjs

@@ -28074,6 +28074,9 @@ function splitParagraph(document2, selection, context) {
   if (scope?.kind !== "top-level") {
     return result;
   }
+  if (context.preserveNumberingOnSplit && scope.paragraph.numbering) {
+    return result;
+  }
   const originalStyleId = scope.paragraph.styleId;
   const nextStyleId = originalStyleId !== void 0 ? resolveNextStyle(originalStyleId, document2.styles) : void 0;
   if (nextStyleId !== void 0) {
@@ -52092,7 +52095,52 @@ function compileReplacement(inputs) {
 
 // src/runtime/scopes/replacement/apply.ts
 function documentHash2(doc) {
-  return JSON.stringify(doc.content);
+  let hash = 2166136261;
+  const mix = (value) => {
+    for (let i = 0; i < value.length; i += 1) {
+      hash ^= value.charCodeAt(i);
+      hash = Math.imul(hash, 16777619);
+    }
+  };
+  const visit = (value) => {
+    if (value === null) {
+      mix("null");
+      return;
+    }
+    switch (typeof value) {
+      case "string":
+      case "number":
+      case "boolean":
+      case "bigint":
+        mix(`${typeof value}:${String(value)}`);
+        return;
+      case "undefined":
+        mix("undefined");
+        return;
+      case "object":
+        if (Array.isArray(value)) {
+          mix(`[${value.length}`);
+          for (const item of value) visit(item);
+          mix("]");
+          return;
+        }
+        {
+          const record = value;
+          const keys = Object.keys(record).sort();
+          mix(`{${keys.length}`);
+          for (const key of keys) {
+            mix(key);
+            visit(record[key]);
+          }
+          mix("}");
+        }
+        return;
+      default:
+        mix(typeof value);
+    }
+  };
+  visit(doc.content);
+  return (hash >>> 0).toString(36).padStart(7, "0");
 }
 function compileScopeById(document2, overlay, scopeId) {
   const paragraphIndexByBlockIndex = buildParagraphIndexMap(document2);
@@ -69250,15 +69298,17 @@ function createDocumentRuntime(options) {
       ...resolution.textTarget ? { textTarget: resolution.textTarget } : {}
     };
   }
-  function prepareFragmentInsertCommandForExecution(command, document2, surface, storyTarget) {
+  function prepareFragmentInsertCommandForExecution(command, document2, surface, storyTarget, selection) {
     if (!command.editableTarget) {
-      return { kind: "accepted", selection: state.selection };
+      return { kind: "accepted", selection };
     }
+    const preserveCallerSelection = command.editableTarget.listAddress?.operationScope === "list-text";
     const resolution = resolveEditableTextTarget({
       document: document2,
       surface,
       target: command.editableTarget,
       activeStoryKey: canonicalEditableTargetStoryKey(storyTarget),
+      ...preserveCallerSelection ? { selection } : {},
       editableTargetCache: editableTargetBlockCache
     });
     if (resolution.kind === "rejected") {
@@ -69276,7 +69326,7 @@ function createDocumentRuntime(options) {
     }
     return {
       kind: "accepted",
-      selection: createSelectionSnapshot(resolution.range.from, resolution.range.to),
+      selection: preserveCallerSelection ? selection : createSelectionSnapshot(resolution.range.from, resolution.range.to),
       ...resolution.textTarget ? { textTarget: resolution.textTarget } : {}
     };
   }
@@ -69448,7 +69498,8 @@ function createDocumentRuntime(options) {
           command,
           state.document,
           cachedRenderSnapshot.surface?.blocks ?? [],
-          activeStory
+          activeStory,
+          commandSelection
         );
         if (prepared.kind === "rejected") {
           return;
@@ -69611,7 +69662,8 @@ function createDocumentRuntime(options) {
             command,
             replayState.document,
             replaySnapshot.surface?.blocks ?? [],
-            replayStory
+            replayStory,
+            replayState.selection
           );
           if (prepared.kind === "rejected") {
             return;
@@ -69754,7 +69806,8 @@ function createDocumentRuntime(options) {
               command,
               stateForCommand.document,
               snapshotForCommand.surface?.blocks ?? [],
-              replayStory
+              replayStory,
+              stateForCommand.selection
             );
             if (prepared.kind === "rejected") {
               continue;
@@ -70318,7 +70371,7 @@ function createDocumentRuntime(options) {
       try {
         const timestamp = clock();
         const selection = target ? createSelectionFromPublicAnchor(target) : state.selection;
-        const editableTarget = editContext?.editableTarget && isTableParagraphEditableTarget(editContext.editableTarget) ? editContext.editableTarget : inferEditableTargetForFragmentInsert(
+        const editableTarget = editContext?.editableTarget && isFragmentInsertEditableTarget(editContext.editableTarget) ? editContext.editableTarget : inferEditableTargetForFragmentInsert(
           cachedRenderSnapshot.surface?.blocks ?? [],
           selection
         );
@@ -72125,7 +72178,8 @@ function createDocumentRuntime(options) {
         blockedReasons: [blockedReason]
       });
     }
-    const textTarget = targetResolution?.kind === "accepted" ? targetResolution.textTarget : legacyTextTarget;
+    const listBoundaryDeleteUsesStoryText = targetResolution?.kind === "accepted" && editableTarget?.listAddress?.operationScope === "list-text" && isTopLevelMainStoryBlockPath(editableTarget.blockPath) && selection.isCollapsed && (commandForDispatch.type === "text.delete-backward" && selection.anchor === targetResolution.range.from || commandForDispatch.type === "text.delete-forward" && selection.anchor === targetResolution.range.to);
+    const textTarget = targetResolution?.kind === "accepted" && !listBoundaryDeleteUsesStoryText ? targetResolution.textTarget : legacyTextTarget;
     const context = {
       timestamp,
       documentMode: textOptions.documentModeOverride ?? workflowCoordinator.getEffectiveDocumentMode(selection),
@@ -72135,6 +72189,7 @@ function createDocumentRuntime(options) {
       editableTargetCache: editableTargetBlockCache,
       activeStorySize: cachedRenderSnapshot.surface?.storySize,
       textTarget,
+      preserveNumberingOnSplit: (commandForDispatch.type === "paragraph.split" || commandForDispatch.type === "fragment.insert") && targetResolution?.kind === "accepted" && editableTarget?.listAddress?.operationScope === "list-text",
       rejectTargetlessTableStructureInsert: true
     };
     const baseState = selection === state.selection ? state : {
@@ -72956,7 +73011,7 @@ function canonicalEditableTargetStoryKey(storyTarget) {
 function inferEditableTargetForFragmentInsert(blocks, selection) {
   const position = Math.min(selection.anchor, selection.head);
   const target = findEditableTargetAtSurfacePosition(blocks, position);
-  return target && isTableParagraphEditableTarget(target) ? target : void 0;
+  return target && isFragmentInsertEditableTarget(target) ? target : void 0;
 }
 function findEditableTargetAtSurfacePosition(blocks, position) {
   for (const block of blocks) {
@@ -72985,8 +73040,14 @@ function findEditableTargetInSurfaceCell(cell, position) {
   }
   return findEditableTargetAtSurfacePosition(cell.content, position);
 }
-function isTableParagraphEditableTarget(target) {
-  return target.editability === "editable" && target.posture.blockers.length === 0 && target.commandFamily === "text-leaf" && (target.kind === "table-cell-paragraph-text" || target.kind === "nested-table-cell-paragraph-text" || target.kind === "sdt-table-cell-paragraph-text");
+function isFragmentInsertEditableTarget(target) {
+  if (target.editability !== "editable" || target.posture.blockers.length > 0 || target.commandFamily !== "text-leaf") {
+    return false;
+  }
+  if (target.listAddress?.operationScope === "list-text") {
+    return true;
+  }
+  return target.kind === "table-cell-paragraph-text" || target.kind === "nested-table-cell-paragraph-text" || target.kind === "sdt-table-cell-paragraph-text";
 }
 function extractSelectionFragment(document2, selection, activeStory) {
   const from = Math.min(selection.anchor, selection.head);
@@ -74983,6 +75044,9 @@ function stripStoryTarget2(selection) {
   const { storyTarget: _storyTarget, ...rest } = selection;
   return rest;
 }
+function isTopLevelMainStoryBlockPath(blockPath) {
+  return typeof blockPath === "string" && /^main\/block\[\d+\]$/u.test(blockPath);
+}
 function toInternalSelectionSnapshot2(selection) {
   return {
     anchor: selection.anchor,
@@ -127907,6 +127971,18 @@ function createTableActionFamily(runtime) {
     }
   };
 }
+function findTableActionDescriptor(runtime, actionHandle) {
+  const document2 = runtime.getCanonicalDocument();
+  const seed = documentSeed(runtime);
+  const surface = runtime.getRenderSnapshot().surface?.blocks ?? [];
+  for (const target of collectEditableTargetRefs(document2)) {
+    if (!target.table || callableOperationsForScope(target.table.operationScope).length === 0 || tableActionHandle(seed, target.targetKey) !== actionHandle || !isResolvableCurrentTableActionTarget(runtime, surface, target)) {
+      continue;
+    }
+    return projectCurrentTableTarget(document2, seed, target);
+  }
+  return null;
+}
 function isSupportedTableActionEvidence(entry) {
   return isSupportedTableStructureEvidence(entry) || isSupportedTableTextEvidence(entry);
 }
@@ -127925,6 +128001,7 @@ function projectTableActionDescriptor(document2, seed, entry) {
   const callableOperations = callableOperationsForScope(scope);
   const supportedOperations = operationsForScope(scope);
   if (callableOperations.length === 0) return [];
+  const selectionRequiredOperations = selectionRequiredOperationsForScope(scope);
   return [
     {
       actionHandle: tableActionHandle(seed, entry.targetKey),
@@ -127933,6 +128010,7 @@ function projectTableActionDescriptor(document2, seed, entry) {
       relation: entry.relation,
       operationScope: scope,
       callableOperations,
+      ...selectionRequiredOperations.length > 0 ? { selectionRequiredOperations } : {},
       supportedOperations,
       ...scope === "text" ? { readback: tableTextReadback(readBlockPathText(document2, entry.blockPath)) } : {},
       reason: entry.runtimeCommand.reason
@@ -127944,6 +128022,7 @@ function projectCurrentTableTarget(document2, seed, target) {
   if (!table) return null;
   const callableOperations = callableOperationsForScope(table.operationScope);
   if (callableOperations.length === 0) return null;
+  const selectionRequiredOperations = selectionRequiredOperationsForScope(table.operationScope);
   return {
     actionHandle: tableActionHandle(seed, target.targetKey),
     family: table.operationScope === "text" ? "table-text" : "table-structure",
@@ -127951,6 +128030,7 @@ function projectCurrentTableTarget(document2, seed, target) {
     relation: "contained-by-scope",
     operationScope: table.operationScope,
     callableOperations,
+    ...selectionRequiredOperations.length > 0 ? { selectionRequiredOperations } : {},
     supportedOperations: operationsForScope(table.operationScope),
     ...table.operationScope === "text" ? { readback: tableTextReadback(readEditableTargetText(document2, target)) } : {},
     reason: table.operationScope === "text" ? "l07:table-text-target-supported" : "l07:table-structure-target-supported"
@@ -128028,11 +128108,14 @@ function callableOperationsForScope(scope) {
     case "text":
       return TEXT_TRANSFER_OPERATIONS;
     case "cell":
-      return [...CELL_STRUCTURE_OPERATIONS, "merge-cells"];
+      return CELL_STRUCTURE_OPERATIONS;
     default:
       return operationsForScope(scope);
   }
 }
+function selectionRequiredOperationsForScope(scope) {
+  return scope === "cell" ? ["merge-cells"] : [];
+}
 function operationsForScope(scope) {
   switch (scope) {
     case "text":
@@ -128390,6 +128473,31 @@ var hyperlinkTextEditMetadata = actionMethodMetadata(
     expectedDelta: "hyperlink display text changes"
   }
 );
+var validateTemplateTargetsMetadata = actionMethodMetadata(
+  "validateTemplateTargets",
+  "read",
+  "actions-template-targets",
+  "Validate template field/clause targets against current document readback, duplicate ranges, and exact action/scope handles before fill.",
+  { uiVisible: false, expectsUxResponse: "none" }
+);
+var templateTargetReadMetadata = actionMethodMetadata(
+  "templateTargetRead",
+  "read",
+  "actions-template-targets",
+  "Read a template field/clause target through its exact scope/action handle when present, or diagnostic placeholder occurrence evidence otherwise.",
+  { uiVisible: false, expectsUxResponse: "none" }
+);
+var templateFieldFillMetadata = actionMethodMetadata(
+  "templateFieldFill",
+  "mutate",
+  "actions-template-targets",
+  "Fill one template field only through an exact scope/action handle after same-target readback validation; raw ranges are diagnostics only.",
+  {
+    uiVisible: true,
+    expectsUxResponse: "inline-change",
+    expectedDelta: "the exact template field target text changes"
+  }
+);
 var listOperationMetadata = actionMethodMetadata(
   "listOperation",
   "mutate",
@@ -128450,6 +128558,9 @@ var ACTION_METHODS = Object.freeze([
   "bookmarkEdit",
   "hyperlinkDestinationEdit",
   "hyperlinkTextEdit",
+  "validateTemplateTargets",
+  "templateTargetRead",
+  "templateFieldFill",
   "listOperation",
   "tableFragment",
   "tableSelection",
@@ -128459,9 +128570,6 @@ var DEFAULT_LOCATE_LIMIT = 20;
 var DEFAULT_REWRITE_ALL_LIMIT = 10;
 var DEFAULT_TABLE_TEXT_SCOPE_LIMIT = 3;
 var DEFAULT_PLAN_STEP_LIMIT = 20;
-function documentContentHash(runtime) {
-  return JSON.stringify(runtime.getCanonicalDocument().content);
-}
 function createActionsFamily(runtime) {
   const category = {
     discover(input) {
@@ -128821,6 +128929,25 @@ function createActionsFamily(runtime) {
         origin: input.origin
       });
     },
+    validateTemplateTargets(input) {
+      return validateTemplateTargets(runtime, input);
+    },
+    templateTargetRead(input) {
+      const item = validateTemplateTarget(runtime, input.target, {
+        duplicateRanges: /* @__PURE__ */ new Set(),
+        allowDuplicateRanges: true
+      });
+      return {
+        status: item.status === "blocked" ? "blocked" : "read",
+        ...item.target ? { target: item.target } : {},
+        ...item.readback ? { readback: item.readback } : {},
+        ...item.blockers ? { blockers: item.blockers } : {},
+        ...item.blockerDetails ? { blockerDetails: item.blockerDetails } : {}
+      };
+    },
+    templateFieldFill(input) {
+      return applyTemplateFieldFill(runtime, input);
+    },
     listOperation(input) {
       return applyListOperation(runtime, input);
     },
@@ -128890,6 +129017,9 @@ function runPlanStep(runtime, mode, step, plan) {
   if (step.kind === "tableAction" || step.kind === "tableFragment" || step.kind === "tableSelection") {
     return runPlanTableActionStep(runtime, mode, step, plan);
   }
+  if (step.kind === "templateFieldFill") {
+    return runPlanTemplateFieldFillStep(runtime, mode, step, plan);
+  }
   const before = step.target ? readPlanTarget(runtime, step.target) : readDocumentPlanTarget(runtime);
   if (!before.ok) {
     return blockedPlanStepFromDetails(step.id, step.kind, before.blockerDetails);
@@ -128934,10 +129064,10 @@ function runPlanStep(runtime, mode, step, plan) {
       ...before.readback ? { beforeReadback: before.readback } : {}
     };
   }
-  const documentHashBeforeApply = documentContentHash(runtime);
+  const documentBeforeApply = runtime.getCanonicalDocument();
   const applied = applyPlanStep(runtime, step, plan);
-  const documentHashAfterApply = documentContentHash(runtime);
-  const projectedApply = !applied.applied && documentHashAfterApply !== documentHashBeforeApply ? withSuspectMutationApplyResult(applied, step.id, applied.target ?? before.target) : applied;
+  const documentAfterApply = runtime.getCanonicalDocument();
+  const projectedApply = !applied.applied && documentAfterApply !== documentBeforeApply ? withSuspectMutationApplyResult(applied, step.id, applied.target ?? before.target) : applied;
   const after = step.kind === "flag" ? before : step.target ? readPlanTarget(runtime, step.target) : before;
   return {
     id: step.id,
@@ -128988,7 +129118,8 @@ function runPlanTableActionStep(runtime, mode, step, plan) {
       tableAction: tableAction2
     });
   }
-  if (!operationKind || !tableAction2.callableOperations.includes(operationKind)) {
+  const isSelectionRequiredOperation = step.kind === "tableSelection" && operationKind !== void 0 && (tableAction2.selectionRequiredOperations ?? []).includes(operationKind) && tableSelectionStepHasDescriptor(step.operation);
+  if (!operationKind || !tableAction2.callableOperations.includes(operationKind) && !isSelectionRequiredOperation) {
     return blockedPlanStepFromDetails(
       step.id,
       step.kind,
@@ -129048,6 +129179,72 @@ function runPlanTableActionStep(runtime, mode, step, plan) {
     ...result.commandReference ? { commandReference: result.commandReference } : {}
   };
 }
+function runPlanTemplateFieldFillStep(runtime, mode, step, plan) {
+  const validation = validateTemplateTarget(runtime, step.field, {
+    duplicateRanges: /* @__PURE__ */ new Set(),
+    allowDuplicateRanges: true
+  });
+  if (validation.status === "blocked" || !validation.canFill) {
+    return blockedPlanStepFromDetails(
+      step.id,
+      step.kind,
+      validation.blockerDetails ?? [
+        blocker(
+          `actions:template-field-fill:not-fillable:${templateTargetDebugId(step.field)}`,
+          "blocked",
+          "The template field target is not backed by an exact fill handle.",
+          "Plant the field through editor APIs and pass the returned scope handle or actionHandle; raw ranges are diagnostics only."
+        )
+      ],
+      {
+        ...validation.target ? { target: validation.target } : {},
+        ...validation.readback ? { beforeReadback: templateReadbackToPlanReadback(validation.readback) } : {}
+      }
+    );
+  }
+  const precondition = checkPlanPreconditions(step, templateReadbackToPlanReadback(validation.readback));
+  if (precondition) {
+    return blockedPlanStepFromDetails(step.id, step.kind, [precondition], {
+      ...validation.target ? { target: validation.target } : {},
+      ...validation.readback ? { beforeReadback: templateReadbackToPlanReadback(validation.readback) } : {}
+    });
+  }
+  if (mode === "preview") {
+    return {
+      id: step.id,
+      kind: step.kind,
+      status: "planned",
+      applied: false,
+      changed: false,
+      ...validation.target ? { target: validation.target } : {},
+      ...validation.readback ? { beforeReadback: templateReadbackToPlanReadback(validation.readback) } : {}
+    };
+  }
+  const applied = applyTemplateFieldFill(runtime, {
+    field: step.field,
+    text: step.text,
+    actorId: step.actorId ?? plan.actorId,
+    origin: step.origin ?? plan.origin,
+    ...step.proposalId ? { proposalId: step.proposalId } : {}
+  });
+  const after = step.field.target ? readPlanTarget(runtime, step.field.target) : null;
+  return {
+    id: step.id,
+    kind: step.kind,
+    status: applied.status === "unsupported" ? "unsupported" : applied.applied ? "applied" : "blocked",
+    applied: applied.applied,
+    changed: applied.changed,
+    ...applied.target ?? validation.target ? { target: applied.target ?? validation.target } : {},
+    ...validation.readback ? { beforeReadback: templateReadbackToPlanReadback(validation.readback) } : {},
+    ...after?.ok && after.readback ? { afterReadback: after.readback } : {},
+    ...applied.proposalId ? { proposalId: applied.proposalId } : {},
+    ...applied.posture ? { posture: applied.posture } : {},
+    ...applied.blockers ? { blockers: applied.blockers } : {},
+    ...applied.blockerDetails ? { blockerDetails: applied.blockerDetails } : {},
+    ...applied.auditReference ? { auditReference: applied.auditReference } : {},
+    ...applied.commandReference ? { commandReference: applied.commandReference } : {}
+  };
+}
 function locateAll(runtime, input) {
   if (!input.query) {
     const detail = blocker(
@@ -129130,6 +129327,310 @@ function locateAll(runtime, input) {
     ...matches.length === 0 ? { blockers: Object.freeze([`actions:locate:not-found:${input.query}`]) } : {}
   };
 }
+function validateTemplateTargets(runtime, input) {
+  if (!Array.isArray(input.targets) || input.targets.length === 0) {
+    const detail = blocker(
+      "actions:template-targets:empty",
+      "input",
+      "Template target validation requires at least one field or clause target.",
+      "Pass the analyzer targets before saving the template."
+    );
+    return {
+      status: "blocked",
+      targets: Object.freeze([]),
+      blockers: Object.freeze([detail.code]),
+      blockerDetails: Object.freeze([detail])
+    };
+  }
+  const duplicateRanges = /* @__PURE__ */ new Set();
+  const items = input.targets.map(
+    (target) => validateTemplateTarget(runtime, target, {
+      duplicateRanges,
+      allowDuplicateRanges: input.allowDuplicateRanges === true
+    })
+  );
+  const blockers = items.flatMap((item) => item.blockers ?? []);
+  const blockerDetails = items.flatMap((item) => item.blockerDetails ?? []);
+  return {
+    status: blockerDetails.length === 0 ? "valid" : items.some((item) => item.status !== "blocked") ? "partial" : "blocked",
+    targets: Object.freeze(items),
+    ...blockers.length > 0 ? { blockers: Object.freeze(blockers) } : {},
+    ...blockerDetails.length > 0 ? { blockerDetails: Object.freeze(blockerDetails) } : {}
+  };
+}
+function validateTemplateTarget(runtime, target, context) {
+  const targetKind = templateTargetKind(target);
+  const details = [];
+  const warnings = [];
+  const expected = templateExpectedText(target);
+  const occurrenceCount = expected ? countOccurrences(documentText(runtime.getCanonicalDocument()), expected) : void 0;
+  const rangeKey = templateLocationKey(target.location);
+  if (target.fieldId && target.clauseId) {
+    details.push(
+      blocker(
+        `actions:template-targets:mixed-field-clause:${templateTargetDebugId(target)}`,
+        "input",
+        "A template target cannot be both a field and a clause.",
+        "Split clause boundaries from fillable fields and save them as separate template targets."
+      )
+    );
+  }
+  if (!expected && !target.target) {
+    details.push(
+      blocker(
+        `actions:template-targets:expected-text-required:${templateTargetDebugId(target)}`,
+        "input",
+        "A template target without an exact handle requires placeholderText or expectedText for validation.",
+        "Store the visible placeholder/current text with the target before saving the template."
+      )
+    );
+  }
+  if (rangeKey && !context.allowDuplicateRanges) {
+    if (context.duplicateRanges.has(rangeKey)) {
+      details.push(
+        blocker(
+          `actions:template-targets:duplicate-range:${rangeKey}`,
+          "ambiguous-target",
+          "More than one template target claims the same document range.",
+          "Create one shared grouped field target, or give each field a distinct occurrence identity."
+        )
+      );
+    } else {
+      context.duplicateRanges.add(rangeKey);
+    }
+  }
+  if (isTableTemplateLocation(target.location) && !hasTableCellIdentity(target.location)) {
+    details.push(
+      blocker(
+        `actions:template-targets:table-cell-identity-required:${templateTargetDebugId(target)}`,
+        "input",
+        "A table template target must carry stable cell identity.",
+        "Include cellSourceRef/cellRefId or row and column identity plus the exact actionHandle returned for the cell text."
+      )
+    );
+  }
+  if (expected && occurrenceCount !== void 0 && occurrenceCount > 1 && !hasOccurrenceIdentity(target) && !target.target) {
+    details.push(
+      blocker(
+        `actions:template-targets:ambiguous-placeholder:${templateTargetDebugId(target)}`,
+        "ambiguous-target",
+        "The placeholder/current text appears more than once and the target has no occurrence identity or exact handle.",
+        "Persist an occurrence refId/index or the exact scope/action handle returned by ai.actions.locateAll."
+      )
+    );
+  }
+  let summary;
+  let readback = occurrenceCount !== void 0 && expected !== void 0 ? { text: expected, excerpt: excerpt(expected), isEmpty: expected.trim().length === 0, occurrenceCount } : void 0;
+  if (target.target) {
+    const read = readPlanTarget(runtime, target.target);
+    if (!read.ok) {
+      details.push(...read.blockerDetails);
+    } else {
+      summary = read.target;
+      readback = {
+        text: read.readback?.text,
+        excerpt: read.readback?.excerpt,
+        isEmpty: read.readback?.isEmpty,
+        ...occurrenceCount !== void 0 ? { occurrenceCount } : {}
+      };
+      const text = read.readback?.text ?? "";
+      if (expected && !text.includes(expected)) {
+        details.push(
+          blocker(
+            `actions:template-targets:stale-readback:${templateTargetDebugId(target)}`,
+            "blocked",
+            "The exact handle readback no longer contains the analyzer's expected text.",
+            "Re-run template analysis against the current document and save fresh targets before filling."
+          )
+        );
+      }
+    }
+  }
+  const canFill = targetKind === "template-field" && target.target !== void 0 && details.length === 0;
+  if (targetKind === "template-field" && !target.target) {
+    details.push(
+      blocker(
+        `actions:template-field-fill:exact-target-required:${templateTargetDebugId(target)}`,
+        "blocked",
+        "Template field fill requires an exact scope handle or opaque actionHandle.",
+        "Plant fields through editor APIs and store the returned handle; raw offsets and YAML ranges are diagnostics only."
+      )
+    );
+  }
+  if (targetKind === "template-clause") {
+    warnings.push("template-clause targets are boundary evidence; fillable placeholders must be separate template-field targets.");
+  }
+  const status = details.length > 0 ? "blocked" : warnings.length > 0 ? "warning" : "valid";
+  return {
+    status,
+    targetKind,
+    ...target.fieldId ? { fieldId: target.fieldId } : {},
+    ...target.clauseId ? { clauseId: target.clauseId } : {},
+    ...target.name ? { name: target.name } : {},
+    ...target.groupId ? { groupId: target.groupId } : {},
+    canFill,
+    ...summary ? { target: summary } : {},
+    ...readback ? { readback } : {},
+    ...details.length > 0 ? { blockers: Object.freeze(details.map((detail) => detail.code)) } : {},
+    ...details.length > 0 ? { blockerDetails: Object.freeze(details) } : {},
+    ...warnings.length > 0 ? { warnings: Object.freeze(warnings) } : {}
+  };
+}
+function applyTemplateFieldFill(runtime, input) {
+  if (input.text === void 0) {
+    return blockedApply(
+      "actions:template-field-fill:text-required",
+      "input",
+      "Template field fill requires a text value.",
+      "Retry with the field fill text."
+    );
+  }
+  if (templateTargetKind(input.field) !== "template-field") {
+    return blockedApply(
+      `actions:template-field-fill:field-target-required:${templateTargetDebugId(input.field)}`,
+      "input",
+      "Template field fill accepts only template-field targets.",
+      "Split clause boundaries from fields and call templateFieldFill only for fillable fields."
+    );
+  }
+  const validation = validateTemplateTarget(runtime, input.field, {
+    duplicateRanges: /* @__PURE__ */ new Set(),
+    allowDuplicateRanges: true
+  });
+  if (validation.status === "blocked" || !validation.canFill || !input.field.target) {
+    return blockedApply(
+      validation.blockerDetails?.[0]?.code ?? `actions:template-field-fill:exact-target-required:${templateTargetDebugId(input.field)}`,
+      validation.blockerDetails?.[0]?.category ?? "blocked",
+      validation.blockerDetails?.[0]?.message ?? "Template field fill requires a validated exact scope handle or opaque actionHandle.",
+      validation.blockerDetails?.[0]?.nextStep ?? "Plant the field through editor APIs and pass the returned handle; raw ranges are diagnostics only.",
+      validation.blockerDetails
+    );
+  }
+  const exactnessBlocker = templateFillExactnessBlocker(input.field, validation);
+  if (exactnessBlocker) {
+    return blockedApply(
+      exactnessBlocker.code,
+      exactnessBlocker.category,
+      exactnessBlocker.message,
+      exactnessBlocker.nextStep,
+      [exactnessBlocker]
+    );
+  }
+  const resolved = resolveTarget(runtime, input.field.target);
+  if (!resolved.ok) return blockedApplyFromResolution(resolved);
+  const result = applyRewrite(runtime, resolved.target, {
+    target: input.field.target,
+    text: input.text,
+    actorId: input.actorId,
+    origin: input.origin,
+    ...input.proposalId ? { proposalId: input.proposalId } : {}
+  });
+  if (!result.applied) return result;
+  const after = readPlanTarget(runtime, input.field.target);
+  if (!after.ok || after.readback?.text !== input.text) {
+    const detail = blockerWithOwner(
+      `actions:template-field-fill:readback-mismatch:${templateTargetDebugId(input.field)}`,
+      "blocked",
+      "The field fill reported applied, but same-target readback did not match the requested text.",
+      "Treat this as failed, inspect export/reopen evidence, and route the target lowering to L08/L07 before retrying.",
+      "L08 semantic scopes and L07 runtime text commands"
+    );
+    return {
+      ...result,
+      status: "blocked",
+      applied: false,
+      changed: result.changed,
+      posture: "suspect-readback",
+      blockers: Object.freeze([...result.blockers ?? [], detail.code]),
+      blockerDetails: Object.freeze([...result.blockerDetails ?? [], detail])
+    };
+  }
+  return result;
+}
+function templateFillExactnessBlocker(target, validation) {
+  const readback = validation.readback?.text ?? "";
+  const expected = templateExpectedText(target);
+  if (!expected) return null;
+  if (readback === expected) return null;
+  return blocker(
+    `actions:template-field-fill:exact-target-not-isolated:${templateTargetDebugId(target)}`,
+    "blocked",
+    "The exact handle readback contains surrounding document text, not just the template field text.",
+    "Plant an isolated template-field scope/action handle for the placeholder; do not fill by broad paragraph, clause, or raw range."
+  );
+}
+function templateReadbackToPlanReadback(readback) {
+  if (!readback) return void 0;
+  return {
+    ...readback.text !== void 0 ? { text: readback.text } : {},
+    ...readback.excerpt !== void 0 ? { excerpt: readback.excerpt } : {},
+    ...readback.isEmpty !== void 0 ? { isEmpty: readback.isEmpty } : {}
+  };
+}
+function templateTargetKind(target) {
+  return target.kind ?? (target.clauseId && !target.fieldId ? "template-clause" : "template-field");
+}
+function templateExpectedText(target) {
+  const text = target.expectedText ?? target.placeholderText;
+  return text && text.length > 0 ? text : void 0;
+}
+function templateTargetDebugId(target) {
+  return target.fieldId ?? target.clauseId ?? target.name ?? target.placeholderText ?? "unknown";
+}
+function templateLocationKey(location) {
+  if (!location?.refId && location?.start === void 0 && location?.end === void 0) return null;
+  return [
+    location.story ?? "main",
+    location.refId ?? "no-ref",
+    location.start ?? "no-start",
+    location.end ?? "no-end"
+  ].join(":");
+}
+function isTableTemplateLocation(location) {
+  return Boolean(
+    location?.blockKind === "table-cell" || location?.tableRefId || location?.rowRefId || location?.cellRefId
+  );
+}
+function hasTableCellIdentity(location) {
+  return Boolean(
+    location?.cellRefId || location?.rowRefId && location.columnIndex !== void 0 || location?.rowIndex !== void 0 && location?.columnIndex !== void 0
+  );
+}
+function hasOccurrenceIdentity(target) {
+  return Boolean(
+    target.occurrence?.refId || target.occurrence?.occurrenceIndexInRef !== void 0 || target.occurrence?.occurrenceIndexGlobal !== void 0 || target.location?.refId || target.location?.cellRefId
+  );
+}
+function countOccurrences(text, query) {
+  if (!query) return 0;
+  let count = 0;
+  let index = 0;
+  while (index <= text.length) {
+    const found = text.indexOf(query, index);
+    if (found === -1) break;
+    count += 1;
+    index = found + Math.max(1, query.length);
+  }
+  return count;
+}
+function documentText(document2) {
+  return document2.content.children.map((block) => blockText(block)).join("\n");
+}
+function blockText(block) {
+  switch (block.type) {
+    case "paragraph":
+      return collectInlineText3(block.children);
+    case "table":
+      return block.rows.map(
+        (row2) => row2.cells.map((cell) => cell.children.map((child) => blockText(child)).join("\n")).join("	")
+      ).join("\n");
+    case "sdt":
+    case "custom_xml":
+      return block.children.map((child) => blockText(child)).join("\n");
+    default:
+      return "";
+  }
+}
 function resolveTarget(runtime, target) {
   if ("actionHandle" in target) {
     const action = findTableAction(runtime, target.actionHandle);
@@ -129252,7 +129753,7 @@ function applyRewrite(runtime, target, input) {
     );
   }
   const beforeText = target.scope.content.text;
-  const documentHashBeforeApply = documentContentHash(runtime);
+  const documentBeforeApply = runtime.getCanonicalDocument();
   const result = createReplacementFamily(runtime).applyReplacementScope({
     targetScopeId: target.handle.scopeId,
     operation: "replace",
@@ -129264,7 +129765,7 @@ function applyRewrite(runtime, target, input) {
     ...input.origin ? { origin: input.origin } : {},
     ...input.proposalId ? { proposalId: input.proposalId } : {}
   });
-  const documentMutated = documentContentHash(runtime) !== documentHashBeforeApply;
+  const documentMutated = runtime.getCanonicalDocument() !== documentBeforeApply;
   if (!result.applied) {
     return documentMutated ? withSuspectMutationApplyResult(
       projectApplyResult(result, target),
@@ -129521,19 +130022,7 @@ function findTableAction(runtime, actionHandle) {
   return action?.family === "table-text" ? action : null;
 }
 function findAnyTableAction(runtime, actionHandle) {
-  const compiler = createScopeCompilerService(runtime);
-  for (const scope of compiler.compileAllScopes()) {
-    if (scope.kind !== "table") continue;
-    const result = createTableActionFamily(runtime).listTableActions({
-      handle: scope.handle,
-      nowUtc: currentAuditTimestamp(runtime)
-    });
-    const action = result.actions.find(
-      (candidate) => candidate.actionHandle === actionHandle
-    );
-    if (action) return action;
-  }
-  return null;
+  return findTableActionDescriptor(runtime, actionHandle);
 }
 function findEditableTextAction(runtime, actionHandle) {
   if (!actionHandle.startsWith("scope-command:text-leaf:")) return null;
@@ -129852,6 +130341,14 @@ function applyPlanStep(runtime, step, plan) {
         actorId: step.actorId ?? plan.actorId,
         origin: step.origin ?? plan.origin
       });
+    case "templateFieldFill":
+      return createActionsFamily(runtime).actions.templateFieldFill({
+        field: step.field,
+        text: step.text,
+        actorId: step.actorId ?? plan.actorId,
+        origin: step.origin ?? plan.origin,
+        ...step.proposalId ? { proposalId: step.proposalId } : {}
+      });
     case "listOperation":
       return createActionsFamily(runtime).actions.listOperation({
         target: step.target,
@@ -130101,6 +130598,11 @@ function tablePlanOperationFamilyBlocker(stepKind, operationKind) {
   }
   return null;
 }
+function tableSelectionStepHasDescriptor(operation) {
+  return Boolean(
+    operation && "selectionDescriptor" in operation && operation.selectionDescriptor
+  );
+}
 function listCommandForOperation(operation, paragraphIndex, origin) {
   switch (operation.kind) {
     case "toggle":
@@ -132875,7 +133377,12 @@ var WordReviewEditor = (0, import_react71.forwardRef)(
             activeRuntime.endAction();
           }
         } else {
-          activeRuntime.insertFragment(meta.fragment);
+          const editableTarget = activeRuntime.getRenderSnapshot().selection.editableTarget;
+          activeRuntime.insertFragment(
+            meta.fragment,
+            void 0,
+            editableTarget ? { editableTarget } : void 0
+          );
         }
       },
       onInsertHardBreak: () => dispatchTextCommand(activeRuntime, { type: "insert-hard-break" }, DISPATCH_CONTEXT),
@@ -132900,7 +133407,12 @@ var WordReviewEditor = (0, import_react71.forwardRef)(
       // insertFragment auto-bracket (R.5.a Phase 2) makes the paste a
       // single-undo action.
       onPasteFragment: (meta) => {
-        activeRuntime.insertFragment(meta.fragment);
+        const editableTarget = activeRuntime.getRenderSnapshot().selection.editableTarget;
+        activeRuntime.insertFragment(
+          meta.fragment,
+          void 0,
+          editableTarget ? { editableTarget } : void 0
+        );
       },
       // v5 close-out: image paste via existing insertImage ref method.
       // Width/height are omitted so the renderer picks sensible defaults