@beyondwork/docx-react-component 1.0.128 → 1.0.130

package/dist/{chunk-LCYYR57Q.js → chunk-WZDKNF37.js}

@@ -9,6 +9,7 @@ import {
   enumerateScopes,
   findParagraphByBlockId,
   getAIActionPolicy,
+  getListKind,
   parseCanonicalFragmentFromWordML,
   resolveDirectRunFormattingAtSegment,
   resolveEditableTableStructureTarget,
@@ -17,7 +18,7 @@ import {
   resolveScopeRange,
   scopeSpecificity,
   searchDocument
-} from "./chunk-XRACP43Q.js";
+} from "./chunk-7G5GR3VV.js";
 import {
   BROADCAST_COMMAND_TYPES,
   COMMAND_EVENT_SCHEMA_VERSION,
@@ -28,7 +29,7 @@ import {
   buildPageAnchorElementId,
   createUiApi,
   emitUxResponse
-} from "./chunk-YIYM4ZAP.js";
+} from "./chunk-CI2TD3T4.js";
 import {
   DEFAULT_PX_PER_TWIP,
   DEFAULT_REGISTRY_ENTRIES,
@@ -36,23 +37,24 @@ import {
   LAYCACHE_SCHEMA_VERSION,
   LAYOUT_ENGINE_VERSION,
   createScopeTagRegistry
-} from "./chunk-YHZHPXDB.js";
+} from "./chunk-THVM6EP5.js";
 import {
   chartModelStore,
   createFormattingContext
-} from "./chunk-CXSYRB37.js";
+} from "./chunk-A3GSNB4G.js";
 import {
+  createSelectionSnapshot,
   deriveDocumentStats
 } from "./chunk-OYGMRRR7.js";
 import {
   DocxSession
-} from "./chunk-TQDQU2E3.js";
+} from "./chunk-DGA7M77X.js";
 import {
   WORKFLOW_PAYLOAD_PART_PATH,
   buildEditorStateXml,
   parseEditorStateXml,
   parseWorkflowPayloadEnvelopeFromPackage
-} from "./chunk-V6XVZFFH.js";
+} from "./chunk-VRKK2CSZ.js";
 import {
   EMU_PER_PX,
   GRADIENT_STOP_UNITS,
@@ -61,10 +63,10 @@ import {
   createHeaderFooterStoryKey,
   createNoteStoryKey,
   validateEditableTargetRef
-} from "./chunk-5DGKFNQT.js";
+} from "./chunk-A66ZVUAT.js";
 import {
   readOpcPackage
-} from "./chunk-OL2UEHRP.js";
+} from "./chunk-WUDSNHWF.js";
 
 // src/api/v3/_mocks.ts
 function mockPayload(reason, shape, body) {
@@ -864,6 +866,10 @@ function extractNLHaystack(entry) {
       }
       return out.slice(0, 200).toLowerCase();
     }
+    case "image": {
+      const text = entry.image.type === "image" ? entry.image.altText ?? "" : entry.image.anchor.docPr?.descr ?? entry.image.anchor.docPr?.name ?? "";
+      return text.slice(0, 200).toLowerCase();
+    }
     case "table":
     case "table-row":
     case "table-cell":
@@ -3993,6 +3999,391 @@ function createViewportFamily(runtime) {
   };
 }
 
+// src/api/v3/runtime/lists.ts
+var SUPPORTED_COMMANDS = [
+  "toggle-numbered",
+  "toggle-bulleted",
+  "indent",
+  "outdent",
+  "restart-numbering",
+  "continue-numbering"
+];
+var UNSUPPORTED_COMMANDS = [
+  "create",
+  "attach",
+  "detach",
+  "join",
+  "separate",
+  "split",
+  "set-value",
+  "apply-template",
+  "capture-template",
+  "apply-preset",
+  "set-level-numbering",
+  "set-level-bullet",
+  "set-level-picture-bullet",
+  "set-level-alignment",
+  "set-level-indents",
+  "set-level-trailing-character",
+  "set-level-marker-font",
+  "set-level-text",
+  "set-level-start",
+  "set-level-layout",
+  "convert-to-text",
+  "paste-fragment",
+  "drop-fragment"
+];
+var applyCommandMetadata = {
+  name: "runtime.lists.applyCommand",
+  status: "live-with-adapter",
+  sourceLayer: "runtime-core",
+  liveEvidence: {
+    runnerTest: "test/api/v3/runtime/lists.test.ts",
+    commit: "refactor-07-runtime-lists-namespace"
+  },
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "surface-refresh",
+    expectedDelta: "list structure changes through the L07 list command surface"
+  },
+  agentMetadata: { readOrMutate: "mutate", boundedScope: "scope", auditCategory: "list-command" },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  broadcastsVia: "crdt",
+  rwdReference: "\xA7Runtime API \xA7 runtime.lists.applyCommand. Dispatches only proven L07 list commands through opaque list targets; future commands return owner-routed blockers until command/export/readback support lands."
+};
+function createListsFamily(runtime) {
+  return {
+    list(input = {}) {
+      const document = runtime.getCanonicalDocument();
+      const rows = currentListTargets(document).filter((entry) => input.storyKey === void 0 || entry.target.storyKey === input.storyKey).map((entry) => toReadback(document, entry.target, entry.paragraph));
+      return input.limit === void 0 ? rows : rows.slice(0, Math.max(0, input.limit));
+    },
+    get(input) {
+      const resolved = resolveCurrentListTarget(runtime.getCanonicalDocument(), input);
+      return resolved.kind === "resolved" ? toReadback(runtime.getCanonicalDocument(), resolved.target, resolved.paragraph) : null;
+    },
+    previewCommand(input) {
+      return previewListCommand(runtime.getCanonicalDocument(), input);
+    },
+    applyCommand(input) {
+      const preview = previewListCommand(runtime.getCanonicalDocument(), input);
+      if (!preview.supported || !preview.target) {
+        return {
+          applied: false,
+          command: input.command,
+          before: preview.target,
+          blockers: preview.blockers
+        };
+      }
+      const resolved = resolveCurrentListTarget(runtime.getCanonicalDocument(), {
+        addressKey: preview.target.addressKey
+      });
+      if (resolved.kind !== "resolved") {
+        return {
+          applied: false,
+          command: input.command,
+          before: preview.target,
+          blockers: [resolved.blocker]
+        };
+      }
+      const command = editorCommandForListCommand(
+        input.command,
+        resolved.target,
+        runtime.now(),
+        input.startAt
+      );
+      if (!command) {
+        return {
+          applied: false,
+          command: input.command,
+          before: preview.target,
+          blockers: [
+            unsupportedCommandBlocker(input.command, {
+              targetKey: preview.target.targetKey,
+              addressKey: preview.target.addressKey
+            })
+          ]
+        };
+      }
+      const beforeDocument = runtime.getCanonicalDocument();
+      runtime.dispatch(command);
+      const afterDocument = runtime.getCanonicalDocument();
+      const after = resolveCurrentListTarget(afterDocument, { targetKey: preview.target.targetKey });
+      emitUxResponse(runtime, {
+        apiFn: applyCommandMetadata.name,
+        intent: applyCommandMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live",
+        uiVisible: true,
+        expectedDelta: applyCommandMetadata.uxIntent.expectedDelta
+      });
+      return {
+        applied: beforeDocument !== afterDocument,
+        command: input.command,
+        before: preview.target,
+        ...after.kind === "resolved" ? { after: toReadback(afterDocument, after.target, after.paragraph) } : {},
+        blockers: []
+      };
+    }
+  };
+}
+function previewListCommand(document, input) {
+  const resolved = resolveCurrentListTarget(document, input);
+  if (resolved.kind !== "resolved") {
+    return {
+      command: input.command,
+      supported: false,
+      affectedTargets: [],
+      blockers: [resolved.blocker]
+    };
+  }
+  const target = toReadback(document, resolved.target, resolved.paragraph);
+  const targetRef = { targetKey: target.targetKey, addressKey: target.addressKey };
+  if (!SUPPORTED_COMMANDS.includes(input.command)) {
+    return {
+      command: input.command,
+      supported: false,
+      target,
+      affectedTargets: [target],
+      blockers: [unsupportedCommandBlocker(input.command, targetRef)]
+    };
+  }
+  const canContinuePrevious = canContinuePreviousSequence(document, resolved.paragraphIndex);
+  const canJoin = canJoinPreviousSequence(document, resolved.paragraphIndex);
+  const blockers = [];
+  if (input.command === "continue-numbering" && !canContinuePrevious) {
+    blockers.push({
+      code: "list-continue-target-missing",
+      ownerLayer: "L07",
+      message: "No previous compatible list sequence is available for continue-numbering.",
+      ...targetRef
+    });
+  }
+  return {
+    command: input.command,
+    supported: blockers.length === 0,
+    target,
+    affectedTargets: [target],
+    blockers,
+    canJoin,
+    canContinuePrevious
+  };
+}
+function editorCommandForListCommand(command, editableTarget, timestamp, startAt) {
+  const origin = { source: "api", timestamp };
+  switch (command) {
+    case "toggle-numbered":
+      return { type: "list.toggle", kind: "numbered", editableTargets: [editableTarget], origin };
+    case "toggle-bulleted":
+      return { type: "list.toggle", kind: "bulleted", editableTargets: [editableTarget], origin };
+    case "indent":
+      return { type: "list.indent", editableTargets: [editableTarget], origin };
+    case "outdent":
+      return { type: "list.outdent", editableTargets: [editableTarget], origin };
+    case "restart-numbering":
+      return {
+        type: "list.restart-numbering",
+        editableTarget,
+        ...startAt !== void 0 ? { startAt } : {},
+        origin
+      };
+    case "continue-numbering":
+      return { type: "list.continue-numbering", editableTarget, origin };
+    default:
+      return void 0;
+  }
+}
+function resolveCurrentListTarget(document, input) {
+  if (input.editableTarget) {
+    const shapeIssues = validateEditableTargetRef(input.editableTarget);
+    if (shapeIssues.length > 0) {
+      return {
+        kind: "blocked",
+        blocker: {
+          code: "list-target-malformed",
+          ownerLayer: "L07",
+          message: `List target is malformed: ${shapeIssues[0]?.path ?? "$"}.`,
+          targetKey: input.editableTarget.targetKey,
+          addressKey: input.editableTarget.listAddress?.addressKey
+        }
+      };
+    }
+  }
+  const requestedTargetKey = input.editableTarget?.targetKey ?? input.targetKey;
+  const requestedAddressKey = input.editableTarget?.listAddress?.addressKey ?? input.addressKey;
+  if (!requestedTargetKey && !requestedAddressKey) {
+    return {
+      kind: "blocked",
+      blocker: {
+        code: "list-target-required",
+        ownerLayer: "L07",
+        message: "runtime.lists requires a targetKey, addressKey, or editableTarget."
+      }
+    };
+  }
+  const currentTargets = currentListTargets(document);
+  const resolved = currentTargets.find(
+    ({ target }) => requestedTargetKey !== void 0 && target.targetKey === requestedTargetKey || requestedAddressKey !== void 0 && target.listAddress?.addressKey === requestedAddressKey
+  );
+  if (!resolved) {
+    return {
+      kind: "blocked",
+      blocker: {
+        code: "list-target-not-found",
+        ownerLayer: "L07",
+        message: "List target no longer resolves in the current canonical document.",
+        ...requestedTargetKey !== void 0 ? { targetKey: requestedTargetKey } : {},
+        ...requestedAddressKey !== void 0 ? { addressKey: requestedAddressKey } : {}
+      }
+    };
+  }
+  if (input.editableTarget && !sameTargetStaleHash(input.editableTarget, resolved.target)) {
+    return {
+      kind: "blocked",
+      blocker: {
+        code: "list-target-stale",
+        ownerLayer: "L07",
+        message: "List target resolved by identity but stale discriminators changed.",
+        targetKey: input.editableTarget.targetKey,
+        addressKey: input.editableTarget.listAddress?.addressKey
+      }
+    };
+  }
+  if (resolved.target.editability !== "editable" || resolved.target.posture.blockers.length > 0) {
+    return {
+      kind: "blocked",
+      blocker: {
+        code: "list-target-non-editable",
+        ownerLayer: "L07",
+        message: resolved.target.posture.blockers.length > 0 ? `List target is not editable: ${resolved.target.posture.blockers.join(", ")}.` : "List target is not editable.",
+        targetKey: resolved.target.targetKey,
+        addressKey: resolved.target.listAddress?.addressKey
+      }
+    };
+  }
+  return { kind: "resolved", ...resolved };
+}
+function currentListTargets(document) {
+  const paragraphs = collectParagraphEntries(document.content.children, "main");
+  const targets = collectEditableTargetRefs(document).filter(isListTextTarget);
+  const byBlockPath = /* @__PURE__ */ new Map();
+  for (const target of targets) byBlockPath.set(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);
+    if (!target) continue;
+    out.push({ target, paragraph: entry.paragraph, paragraphIndex });
+  }
+  return out;
+}
+function collectParagraphEntries(blocks, basePath) {
+  const out = [];
+  collectParagraphEntriesInto(blocks, basePath, out);
+  return out;
+}
+function collectParagraphEntriesInto(blocks, 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 });
+        break;
+      case "table":
+        for (let rowIndex = 0; rowIndex < block.rows.length; rowIndex += 1) {
+          const row = block.rows[rowIndex];
+          if (!row) continue;
+          for (let cellIndex = 0; cellIndex < row.cells.length; cellIndex += 1) {
+            const cell = row.cells[cellIndex];
+            if (!cell) continue;
+            collectParagraphEntriesInto(
+              cell.children,
+              `${blockPath}/row[${rowIndex}]/cell[${cellIndex}]`,
+              out
+            );
+          }
+        }
+        break;
+      case "sdt":
+        collectParagraphEntriesInto(block.children, blockPath, out);
+        break;
+      case "custom_xml":
+        break;
+      default:
+        break;
+    }
+  }
+}
+function isListTextTarget(target) {
+  return target.commandFamily === "text-leaf" && target.listAddress?.operationScope === "list-text" && target.listAddress.addressKind === "list-item-text";
+}
+function sameTargetStaleHash(left, right) {
+  return left.targetKey === right.targetKey && left.listAddress?.addressKey === right.listAddress?.addressKey && left.listAddress?.resolver?.staleHash === right.listAddress?.resolver?.staleHash && left.staleCheck.paragraphTextHash === right.staleCheck.paragraphTextHash && left.staleCheck.paragraphTextLength === right.staleCheck.paragraphTextLength && left.staleCheck.inlineCount === right.staleCheck.inlineCount;
+}
+function toReadback(document, target, paragraph) {
+  const numbering = paragraph.numbering;
+  const instance = document.numbering.instances[numbering.numberingInstanceId];
+  const listKind = instance ? getListKind(document.numbering, numbering.numberingInstanceId) : void 0;
+  return {
+    targetKey: target.targetKey,
+    actionHandle: `list-action:${target.listAddress.addressKey}`,
+    kind: target.kind,
+    storyKey: target.storyKey,
+    blockPath: target.blockPath,
+    leafPath: target.leafPath,
+    addressKey: target.listAddress.addressKey,
+    numberingInstanceId: numbering.numberingInstanceId,
+    ...instance?.abstractNumberingId ? { abstractNumberingId: instance.abstractNumberingId } : {},
+    level: numbering.level,
+    ...listKind ? { listKind } : {},
+    editability: target.editability,
+    blockers: target.posture.blockers,
+    supportedCommands: SUPPORTED_COMMANDS,
+    unsupportedCommands: UNSUPPORTED_COMMANDS,
+    staleDiscriminators: {
+      paragraphTextHash: target.staleCheck.paragraphTextHash,
+      paragraphTextLength: target.staleCheck.paragraphTextLength,
+      inlineCount: target.staleCheck.inlineCount,
+      listAddressStaleHash: target.listAddress?.resolver?.staleHash
+    }
+  };
+}
+function canContinuePreviousSequence(document, paragraphIndex) {
+  const paragraphs = collectParagraphEntries(document.content.children, "main");
+  const current = paragraphs[paragraphIndex]?.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;
+    if (!previous?.numbering) continue;
+    const previousKind = getListKind(document.numbering, previous.numbering.numberingInstanceId);
+    return previousKind === currentKind && previous.numbering.numberingInstanceId !== current.numbering.numberingInstanceId;
+  }
+  return false;
+}
+function canJoinPreviousSequence(document, paragraphIndex) {
+  const paragraphs = collectParagraphEntries(document.content.children, "main");
+  const current = paragraphs[paragraphIndex]?.paragraph;
+  const previous = paragraphs[paragraphIndex - 1]?.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 unsupportedCommandBlocker(command, target) {
+  return {
+    code: "list-command-unsupported",
+    ownerLayer: "L07",
+    message: `runtime.lists.${command} is reserved but not implemented by the L07 command surface yet.`,
+    ...target.targetKey !== void 0 ? { targetKey: target.targetKey } : {},
+    ...target.addressKey !== void 0 ? { addressKey: target.addressKey } : {}
+  };
+}
+
 // src/api/v3/ai/_pe2-evidence.ts
 function copyCoverage(coverage) {
   return {
@@ -5720,6 +6111,17 @@ function createTableActionFamily(runtime) {
             operationScope: target.table?.operationScope
           });
         }
+        if (fragmentContent && fragmentContent.blocks.length === 0) {
+          return blockedResult(input, proposalId, {
+            code: `table-action-structured-fragment-empty:${input.operation.kind}`,
+            category: "unsupported-operation",
+            message: "Structured table text actions require a canonical document fragment with at least one block.",
+            nextStep: 'Retry with operation.content.kind="structured" and a CanonicalDocumentFragment whose blocks array contains the paragraph or table content to paste/drop.',
+            actionHandle: input.actionHandle,
+            operation: input.operation.kind,
+            operationScope: target.table?.operationScope
+          });
+        }
         const resolution2 = resolveEditableTextTarget({
           document: runtime.getCanonicalDocument(),
           surface: runtime.getRenderSnapshot().surface?.blocks ?? [],
@@ -5742,6 +6144,7 @@ function createTableActionFamily(runtime) {
           runtime.dispatch({
             type: "fragment.insert",
             fragment: fragmentContent,
+            selection: createSelectionSnapshot(resolution2.range.to, resolution2.range.to),
             editableTarget: target,
             origin: { source: "api", timestamp: nowUtc }
           });
@@ -5754,6 +6157,17 @@ function createTableActionFamily(runtime) {
           });
         }
         const changed2 = runtime.getCanonicalDocument() !== before2;
+        if (!changed2) {
+          return blockedResult(input, proposalId, {
+            code: `table-action-noop:${input.operation.kind}:${input.actionHandle}`,
+            category: "runtime-noop",
+            message: "The runtime accepted the table text target but the operation produced no document change.",
+            nextStep: "Refresh the table action list and verify the target is still editable, the payload is non-empty when required, and structured fragments are dispatched through a command-safe table text action.",
+            actionHandle: input.actionHandle,
+            operation: input.operation.kind,
+            operationScope: target.table?.operationScope
+          });
+        }
         const afterReadback = tableTextReadback(readEditableTargetText(runtime.getCanonicalDocument(), target));
         return {
           proposalId,
@@ -6361,7 +6775,7 @@ var listOperationMetadata = actionMethodMetadata(
   "listOperation",
   "mutate",
   "actions-list-operation",
-  "Apply list toggle, indent, outdent, restart, or continue-numbering commands to paragraph-like scope handles.",
+  "Apply list toggle, indent, outdent, restart, or continue-numbering commands through opaque list action handles or command-safe list scope targets.",
   {
     uiVisible: true,
     expectsUxResponse: "inline-change",
@@ -8096,25 +8510,16 @@ function checkPlanStepCapability(runtime, step, before) {
     return null;
   }
   if (step.kind === "listOperation") {
-    const resolved = resolveScopeExactTarget(runtime, step.target, step.kind);
+    const resolved = resolveListOperationTarget(runtime, step.target);
     if (!resolved.ok) return resolved.blockerDetails[0] ?? null;
-    const scope = resolved.target.scope;
-    if (scope.kind !== "list-item" && scope.kind !== "paragraph" && scope.kind !== "heading") {
-      return blocker(
-        `actions:list-operation:target-kind-unsupported:${scope.kind}`,
-        "unsupported",
-        "List operations require a paragraph-like scope handle.",
-        "Use ai.actions.locateAll or ai.listScopes to select a paragraph, heading, or list-item handle."
-      );
-    }
-    if (paragraphIndexFromHandle(scope.handle) === null) {
-      return blockerWithOwner(
-        `actions:list-operation:paragraph-index-unresolved:${scope.handle.scopeId}`,
-        "blocked",
-        "The list operation target did not resolve to a current paragraph index.",
-        "Refresh the scope handle and retry; route persistent failures to L08 scope resolution.",
-        "L08 semantic scope compiler"
-      );
+    const command = runtimeListCommandForOperation(step.operation);
+    const preview = createListsFamily(runtime).previewCommand({
+      ...resolved.input,
+      command,
+      ...step.operation.kind === "restart-numbering" && step.operation.startAt !== void 0 ? { startAt: step.operation.startAt } : {}
+    });
+    if (preview.blockers.length > 0) {
+      return listBlockerDetails("actions:list-operation:preflight", preview.blockers)[0] ?? null;
     }
     return null;
   }
@@ -8271,70 +8676,253 @@ function applyModeledCommand(runtime, targetInput, kind, commandInput, reference
   };
 }
 function applyListOperation(runtime, input) {
-  const resolvedScope = resolveScopeExactTarget(runtime, input.target, "listOperation");
-  if (!resolvedScope.ok) return blockedApplyFromResolution(resolvedScope);
+  const resolvedTarget = resolveListOperationTarget(runtime, input.target);
+  if (!resolvedTarget.ok) return blockedApplyFromResolution(resolvedTarget);
+  const command = runtimeListCommandForOperation(input.operation);
+  const result = createListsFamily(runtime).applyCommand({
+    ...resolvedTarget.input,
+    command,
+    ...input.operation.kind === "restart-numbering" && input.operation.startAt !== void 0 ? { startAt: input.operation.startAt } : {}
+  });
+  if (!result.applied) {
+    const details = result.blockers.length > 0 ? listBlockerDetails("actions:list-operation", result.blockers) : [
+      blockerWithOwner(
+        `actions:list-operation:runtime-noop:${resolvedTarget.before?.addressKey ?? "unknown"}`,
+        "blocked",
+        "The runtime list command produced no document change for the selected list target.",
+        "Refresh the list action handle and retry; route persistent failures with before/after readback to L07 runtime list commands.",
+        "L07 runtime list commands"
+      )
+    ];
+    return {
+      status: details.some((detail) => detail.category === "unsupported") ? "unsupported" : "blocked",
+      applied: false,
+      changed: false,
+      target: summarizeListTarget(resolvedTarget, result.before ?? resolvedTarget.before),
+      blockers: Object.freeze(details.map((detail) => detail.code)),
+      blockerDetails: Object.freeze(details),
+      listReadback: listOperationReadback(result, resolvedTarget.before)
+    };
+  }
+  const compiledAfter = resolvedTarget.scopeHandle ? createScopeCompilerService(runtime).compileScopeById(resolvedTarget.scopeHandle.scopeId) : null;
+  const target = compiledAfter ? summarizeTarget({ kind: "scope", scope: compiledAfter.scope, handle: compiledAfter.scope.handle }) : summarizeListTarget(resolvedTarget, result.after ?? result.before ?? resolvedTarget.before);
+  return {
+    status: "applied",
+    applied: true,
+    changed: result.applied,
+    target,
+    commandReference: {
+      command: commandReferenceForListCommand(result.command),
+      actorId: input.actorId ?? "v3-ai-api",
+      origin: input.origin ?? "agent",
+      emittedAtUtc: currentAuditTimestamp(runtime)
+    },
+    listReadback: listOperationReadback(result, resolvedTarget.before)
+  };
+}
+function resolveListOperationTarget(runtime, targetInput) {
+  const lists = createListsFamily(runtime);
+  if ("actionHandle" in targetInput) {
+    const addressKey = listAddressKeyFromActionHandle(targetInput.actionHandle);
+    if (!addressKey) {
+      const detail = blockerWithOwner(
+        `actions:list-operation:action-handle-malformed:${targetInput.actionHandle}`,
+        "unsupported",
+        "List operations require an opaque list action handle from runtime.lists or list editable-target evidence.",
+        "Call runtime.lists.list or refresh the scope bundle and retry with a list-action:* or scope-command:text-leaf:* list handle.",
+        "L07 runtime list commands and L08 semantic scopes"
+      );
+      return {
+        ok: false,
+        blockers: Object.freeze([detail.code]),
+        blockerDetails: Object.freeze([detail])
+      };
+    }
+    const before2 = lists.get({ addressKey });
+    if (!before2) {
+      const detail = blockerWithOwner(
+        `actions:list-operation:action-handle-not-found:${targetInput.actionHandle}`,
+        "unresolved-target",
+        "No current list target matches the supplied opaque action handle.",
+        "Refresh runtime.lists.list or the scope bundle, then retry with the current list action handle.",
+        "L07 runtime list commands"
+      );
+      return {
+        ok: false,
+        blockers: Object.freeze([detail.code]),
+        blockerDetails: Object.freeze([detail])
+      };
+    }
+    return { ok: true, input: { addressKey }, before: before2 };
+  }
+  const resolvedScope = resolveScopeExactTarget(runtime, targetInput, "listOperation");
+  if (!resolvedScope.ok) return resolvedScope;
   const scope = resolvedScope.target.scope;
   if (scope.kind !== "list-item" && scope.kind !== "paragraph" && scope.kind !== "heading") {
-    return blockedApply(
+    const detail = blocker(
       `actions:list-operation:target-kind-unsupported:${scope.kind}`,
       "unsupported",
-      "List operations require a paragraph-like scope handle.",
-      "Use ai.actions.locateAll or ai.listScopes to select a paragraph, heading, or list-item handle."
+      "List operations require a list item or command-safe paragraph-like scope target.",
+      "Use ai.actions.locateAll, ai.listScopes, or runtime.lists.list to select a current list item target."
     );
+    return {
+      ok: false,
+      blockers: Object.freeze([detail.code]),
+      blockerDetails: Object.freeze([detail])
+    };
   }
-  const paragraphIndex = paragraphIndexFromHandle(scope.handle);
-  if (paragraphIndex === null) {
-    return blockedApply(
-      `actions:list-operation:paragraph-index-unresolved:${scope.handle.scopeId}`,
+  const bundle = createScopeCompilerService(runtime).compileBundleById(
+    scope.handle.scopeId,
+    currentAuditTimestamp(runtime)
+  );
+  const entries = bundle?.evidence.editableTargets?.entries ?? [];
+  const listEntry = entries.find(
+    (entry) => entry.commandFamily === "text-leaf" && entry.runtimeCommand.status === "supported" && entry.runtimeCommand.intents.includes("list-structure-action") && entry.runtimeCommand.canonicalAddress?.operationScope === "list-text" && entry.runtimeCommand.canonicalAddress.addressKind === "list-item-text"
+  );
+  if (!listEntry) {
+    const detail = blockerWithOwner(
+      `actions:list-operation:list-target-missing:${scope.handle.scopeId}`,
       "blocked",
-      "The list operation target did not resolve to a current paragraph index.",
-      "Refresh the scope handle and retry; route persistent failures to L08 scope resolution.",
-      [
-        blockerWithOwner(
-          `actions:list-operation:paragraph-index-unresolved:${scope.handle.scopeId}`,
-          "blocked",
-          "The list operation target did not resolve to a current paragraph index.",
-          "Refresh the scope handle and retry; route persistent failures to L08 scope resolution.",
-          "L08 semantic scope compiler"
-        )
-      ]
+      "The selected scope does not expose a command-safe list structure target.",
+      "Refresh the scope bundle and route missing list editable-target evidence to L08/L07; do not derive a paragraph index from the scope handle.",
+      "L08 semantic scopes and L07 runtime list commands"
     );
+    return {
+      ok: false,
+      blockers: Object.freeze([detail.code]),
+      blockerDetails: Object.freeze([detail])
+    };
   }
-  const command = listCommandForOperation(input.operation, paragraphIndex, actionOrigin(runtime, input));
-  const before = runtime.getCanonicalDocument();
-  runtime.dispatch(command);
-  const changed = runtime.getCanonicalDocument() !== before;
-  if (!changed) {
-    return blockedApply(
-      `actions:list-operation:runtime-noop:${scope.handle.scopeId}`,
+  const currentTarget = collectEditableTargetRefs(runtime.getCanonicalDocument()).find(
+    (target) => target.targetKey === listEntry.targetKey || target.listAddress?.addressKey === listEntry.runtimeCommand.canonicalAddress?.addressKey
+  );
+  if (!currentTarget) {
+    const detail = blockerWithOwner(
+      `actions:list-operation:list-target-not-current:${scope.handle.scopeId}`,
+      "unresolved-target",
+      "The list editable target evidence is stale in the current document.",
+      "Refresh the scope bundle and retry with the current opaque list target.",
+      "L08 semantic scopes and L07 runtime list commands"
+    );
+    return {
+      ok: false,
+      blockers: Object.freeze([detail.code]),
+      blockerDetails: Object.freeze([detail])
+    };
+  }
+  const before = lists.get({ editableTarget: currentTarget });
+  if (!before) {
+    const detail = blockerWithOwner(
+      `actions:list-operation:list-readback-missing:${scope.handle.scopeId}`,
       "blocked",
-      "The list runtime command produced no document change for the selected scope.",
-      "Select a list-compatible paragraph and retry, or route to L03/L07 list command support with the scope handle.",
-      [
-        blockerWithOwner(
-          `actions:list-operation:runtime-noop:${scope.handle.scopeId}`,
-          "blocked",
-          "The list runtime command produced no document change for the selected scope.",
-          "Select a list-compatible paragraph and retry, or route to L03/L07 list command support with the scope handle.",
-          "L03 numbering/list semantics and L07 runtime list commands"
-        )
-      ]
+      "The list target was present in scope evidence but runtime.lists could not produce readback.",
+      "Route the target with editable-target evidence to L07 runtime list readback.",
+      "L07 runtime list commands"
     );
+    return {
+      ok: false,
+      blockers: Object.freeze([detail.code]),
+      blockerDetails: Object.freeze([detail])
+    };
   }
-  const compiledAfter = createScopeCompilerService(runtime).compileScopeById(scope.handle.scopeId);
   return {
-    status: "applied",
-    applied: true,
-    changed: true,
-    target: compiledAfter ? summarizeTarget({ kind: "scope", scope: compiledAfter.scope, handle: compiledAfter.scope.handle }) : summarizeTarget(resolvedScope.target),
-    commandReference: {
-      command: command.type,
-      actorId: input.actorId ?? "v3-ai-api",
-      origin: input.origin ?? "agent",
-      emittedAtUtc: command.origin?.timestamp ?? currentAuditTimestamp(runtime)
-    }
+    ok: true,
+    input: { editableTarget: currentTarget },
+    before,
+    scopeHandle: scope.handle
   };
 }
+function listAddressKeyFromActionHandle(actionHandle) {
+  const listPrefix = "list-action:";
+  if (actionHandle.startsWith(listPrefix)) return actionHandle.slice(listPrefix.length) || null;
+  const scopeCommandPrefix = "scope-command:text-leaf:";
+  if (actionHandle.startsWith(scopeCommandPrefix)) {
+    return actionHandle.slice(scopeCommandPrefix.length) || null;
+  }
+  return null;
+}
+function runtimeListCommandForOperation(operation) {
+  switch (operation.kind) {
+    case "toggle":
+      return operation.listKind === "numbered" ? "toggle-numbered" : "toggle-bulleted";
+    case "indent":
+      return "indent";
+    case "outdent":
+      return "outdent";
+    case "restart-numbering":
+      return "restart-numbering";
+    case "continue-numbering":
+      return "continue-numbering";
+  }
+}
+function commandReferenceForListCommand(command) {
+  switch (command) {
+    case "toggle-numbered":
+    case "toggle-bulleted":
+      return "list.toggle";
+    case "indent":
+      return "list.indent";
+    case "outdent":
+      return "list.outdent";
+    case "restart-numbering":
+      return "list.restart-numbering";
+    case "continue-numbering":
+      return "list.continue-numbering";
+    default:
+      return "list.toggle";
+  }
+}
+function listOperationReadback(result, fallbackBefore) {
+  const before = sanitizeListReadback(result.before ?? fallbackBefore);
+  const after = sanitizeListReadback(result.after);
+  return {
+    ...before ? { before } : {},
+    ...after ? { after } : {}
+  };
+}
+function sanitizeListReadback(readback) {
+  if (!readback) return void 0;
+  return {
+    actionHandle: readback.actionHandle,
+    kind: readback.kind,
+    storyKey: readback.storyKey,
+    addressKey: readback.addressKey,
+    numberingInstanceId: readback.numberingInstanceId,
+    ...readback.abstractNumberingId ? { abstractNumberingId: readback.abstractNumberingId } : {},
+    level: readback.level,
+    ...readback.listKind ? { listKind: readback.listKind } : {},
+    editability: readback.editability,
+    blockers: readback.blockers,
+    supportedCommands: readback.supportedCommands,
+    unsupportedCommands: readback.unsupportedCommands,
+    staleDiscriminators: readback.staleDiscriminators
+  };
+}
+function summarizeListTarget(target, readback) {
+  const current = readback ?? target.before;
+  return {
+    kind: "list-item",
+    ...target.scopeHandle ? { handle: target.scopeHandle } : {},
+    ...current?.actionHandle ? { actionHandle: current.actionHandle } : {},
+    canRewriteText: current?.editability === "editable" && (current.blockers.length ?? 0) === 0,
+    canInsertAdjacentText: false,
+    canFlag: Boolean(target.scopeHandle),
+    canMark: Boolean(target.scopeHandle)
+  };
+}
+function listBlockerDetails(prefix, blockers) {
+  return Object.freeze(
+    blockers.map(
+      (entry) => blockerWithOwner(
+        `${prefix}:${entry.code}:${entry.addressKey ?? entry.targetKey ?? "unknown"}`,
+        entry.code === "list-command-unsupported" ? "unsupported" : "blocked",
+        entry.message,
+        "Refresh the opaque list target/readback and route persistent blockers to the owning runtime list layer.",
+        entry.ownerLayer === "L07" ? "L07 runtime list commands" : entry.ownerLayer
+      )
+    )
+  );
+}
 function projectTableApplyResult(result) {
   return {
     status: result.applied ? "applied" : "blocked",
@@ -8462,36 +9050,6 @@ function tableSelectionStepHasDescriptor(operation) {
     operation && "selectionDescriptor" in operation && operation.selectionDescriptor
   );
 }
-function listCommandForOperation(operation, paragraphIndex, origin) {
-  switch (operation.kind) {
-    case "toggle":
-      return {
-        type: "list.toggle",
-        kind: operation.listKind,
-        paragraphIndexes: [paragraphIndex],
-        origin
-      };
-    case "indent":
-      return { type: "list.indent", paragraphIndexes: [paragraphIndex], origin };
-    case "outdent":
-      return { type: "list.outdent", paragraphIndexes: [paragraphIndex], origin };
-    case "restart-numbering":
-      return {
-        type: "list.restart-numbering",
-        paragraphIndex,
-        ...operation.startAt !== void 0 ? { startAt: operation.startAt } : {},
-        origin
-      };
-    case "continue-numbering":
-      return { type: "list.continue-numbering", paragraphIndex, origin };
-  }
-}
-function paragraphIndexFromHandle(handle) {
-  const raw = handle.semanticPath[handle.semanticPath.length - 1];
-  if (raw === void 0) return null;
-  const index = Number(raw);
-  return Number.isSafeInteger(index) && index >= 0 ? index : null;
-}
 function actionOrigin(runtime, input) {
   return { source: "api", timestamp: currentAuditTimestamp(runtime) };
 }
@@ -8856,7 +9414,8 @@ function createApiV3(handle, opts) {
     chart: createChartFamily(handle),
     search: createSearchFamily(handle),
     table: createTableFamily(handle),
-    viewport: createViewportFamily(handle)
+    viewport: createViewportFamily(handle),
+    lists: createListsFamily(handle)
   };
   const ui = opts?.ui ? createUiApi(handle, opts.ui) : void 0;
   const api = ui ? { runtime, ai, ui } : { runtime, ai };