@ai-matrx/context-menu 0.0.0-stage → 0.1.0

package/dist/menu-content.js

@@ -0,0 +1,3197 @@
+"use client";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+
+// src/engine/utils/compact.ts
+function compact(value) {
+  const out = {};
+  for (const [key, v] of Object.entries(value)) if (v !== void 0) out[key] = v;
+  return out;
+}
+
+// src/engine/components/AlchemyMenuContent.tsx
+import * as React2 from "react";
+import { createClickTarget } from "@ai-matrx/alchemy/actions";
+import { useAlchemyActions as useAlchemyActions2 } from "@ai-matrx/alchemy/react/host";
+import { ContextMenuPanel } from "@ai-matrx/alchemy/react/menu";
+import { ActionSheet } from "@ai-matrx/alchemy/react/sheet";
+import { ActionPalette } from "@ai-matrx/alchemy/react/palette";
+import { SOURCE_WRITE_TARGET, richDocumentTargetHost } from "@ai-matrx/rich-content/rich-document/actions/provider";
+import { useRichDocumentProvider } from "@ai-matrx/rich-content/rich-document/actions/useRichDocumentProvider";
+
+// src/engine/utils/field-menu-header.ts
+function fieldLabelOf(element) {
+  if (!element) return null;
+  const clean = (s) => (s ?? "").replace(/\s+/g, " ").replace(/\s*\*$/, "").trim() || null;
+  const aria = clean(element.getAttribute("aria-label"));
+  if (aria) return aria;
+  const labelledBy = element.getAttribute("aria-labelledby");
+  if (labelledBy) {
+    const text = labelledBy.split(/\s+/).map((id2) => element.ownerDocument?.getElementById(id2)?.textContent ?? "").join(" ");
+    if (clean(text)) return clean(text);
+  }
+  const labels = element.labels;
+  if (labels && labels.length > 0) {
+    const text = clean(labels[0]?.textContent);
+    if (text) return text;
+  }
+  const id = element.getAttribute("id");
+  if (id && element.ownerDocument) {
+    const label = element.ownerDocument.querySelector(`label[for="${CSS.escape(id)}"]`);
+    if (clean(label?.textContent)) return clean(label?.textContent);
+  }
+  return null;
+}
+var MERGE_FIELD = /\{\{\s*([^{}]+?)\s*\}\}/g;
+function mergeFieldName(token) {
+  const words = token.replace(/[._-]+/g, " ").replace(/([a-z])([A-Z])/g, "$1 $2").trim().toLowerCase();
+  return words ? words[0].toUpperCase() + words.slice(1) : token;
+}
+var FIELD_PREVIEW_MAX = 60;
+function fieldPreview(text) {
+  const withoutFields = text.replace(MERGE_FIELD, "").replace(/[\s\p{P}]+/gu, "");
+  if (!withoutFields) return "";
+  const readable = text.replace(MERGE_FIELD, (_, name) => mergeFieldName(name)).replace(/\s+/g, " ").trim();
+  return readable.length > FIELD_PREVIEW_MAX ? `${readable.slice(0, FIELD_PREVIEW_MAX - 1).trimEnd()}\u2026` : readable;
+}
+
+// src/engine/utils/already-here.ts
+var SAVE_INTO_WHERE_YOU_ARE = [
+  { sourceType: "note", surface: "matrx-user/notes", actionId: "save-to-notes" },
+  { sourceType: "task", surface: "matrx-user/tasks", actionId: "save-to-task" }
+];
+var OPEN_WHERE_YOU_ARE = [
+  // The Feedback window's menus offered "Submit feedback" — reopening itself.
+  { surface: "matrx-user/feedback", actionId: "submit-feedback" }
+];
+var EDITOR_DOORS = ["edit", "open-fullscreen-editor"];
+function actionsAlreadyHere(where) {
+  const out = [];
+  for (const rule of SAVE_INTO_WHERE_YOU_ARE) {
+    if (where.sourceType === rule.sourceType || where.surfaceName === rule.surface) out.push(rule.actionId);
+  }
+  for (const rule of OPEN_WHERE_YOU_ARE) {
+    if (where.surfaceName === rule.surface) out.push(rule.actionId);
+  }
+  const ownPage = SAVE_INTO_WHERE_YOU_ARE.some(
+    (rule) => where.sourceType === rule.sourceType || where.surfaceName === rule.surface
+  );
+  if (where.isEditable || ownPage) out.push(...EDITOR_DOORS);
+  return [...new Set(out)];
+}
+
+// src/engine/utils/editor-text-agent.ts
+function editorTextAgentCallbacks(callbacks, source, adapter, request) {
+  if (callbacks?.onRequestTextAgentAction || !request) return callbacks;
+  if (source.type === "raw" || source.readOnly || typeof adapter.edit !== "function") return callbacks;
+  return { ...callbacks ?? {}, onRequestTextAgentAction: request };
+}
+
+// src/engine/hooks/useContextMenuActions.ts
+import { useEffect, useMemo as useMemo2 } from "react";
+import { copyText as kitCopyText, readText as kitReadText } from "@ai-matrx/kit/clipboard";
+import {
+  AppWindow,
+  Braces,
+  Building,
+  ClipboardCopy,
+  FileText,
+  Info,
+  Layers,
+  Plus,
+  Rocket,
+  ShieldCheck,
+  User
+} from "lucide-react";
+
+// src/engine/types.ts
+var types_exports = {};
+__reExport(types_exports, types_star);
+import * as types_star from "@ai-matrx/chat/context-menu/types";
+
+// src/engine/hooks/useContextMenuActions.ts
+import { detectActiveSurface } from "@ai-matrx/chat/surfaces/utils/route-to-surface";
+import { getSurfaceDisplayLabel } from "@ai-matrx/chat/surfaces/utils/surface-display";
+import { getRelatedSurfaces } from "@ai-matrx/chat/surfaces/runtime/fetchRelatedSurfaces";
+import { getIconComponent } from "@ai-matrx/icons";
+import { useAppDispatch as useAppDispatch2, useAppSelector as useAppSelector2, useAppStore } from "@ai-matrx/chat/store/hooks";
+import { selectUserId } from "@ai-matrx/chat/host/identity";
+
+// src/engine/utils/notify.ts
+import { toast as notify } from "@ai-matrx/chat/host/notify";
+function toast(props) {
+  const { title, description, variant, duration } = props;
+  const message = title ?? description ?? "";
+  const options = {
+    ...title !== void 0 && description !== void 0 ? { description } : {},
+    ...duration !== void 0 ? { duration } : {}
+  };
+  if (variant === "destructive") notify.error(message, options);
+  else if (variant === "success") notify.success(message, options);
+  else if (variant === "warning") notify.warning(message, options);
+  else if (variant === "info") notify.info(message, options);
+  else notify.message(message, options);
+}
+
+// src/engine/host/port.ts
+import { confirm as kitConfirm } from "@ai-matrx/kit/confirm-opener";
+function unwired(name) {
+  const announced = slot().announced;
+  if (announced.has(name)) return;
+  announced.add(name);
+  console.warn(`[context-menu] host port "${name}" is not wired \u2014 configureContextMenuHost({ ${name} }).`);
+}
+function unwiredFn(name) {
+  return () => unwired(name);
+}
+var DEFAULT_QUICK_ACTIONS = {
+  openChatWindow: unwiredFn("quickActions.openChatWindow"),
+  openQuickChat: unwiredFn("quickActions.openQuickChat"),
+  openQuickData: unwiredFn("quickActions.openQuickData"),
+  openQuickFiles: unwiredFn("quickActions.openQuickFiles"),
+  openQuickNotes: unwiredFn("quickActions.openQuickNotes"),
+  openQuickTasks: unwiredFn("quickActions.openQuickTasks"),
+  openVoicePad: unwiredFn("quickActions.openVoicePad")
+};
+var DEFAULT_BINDINGS = {
+  isAdminDebugger: false,
+  hasAdminPower: false,
+  isDebugMode: false,
+  isAdminIndicatorOpen: false,
+  hasCompareBase: false,
+  activeScopeIds: null,
+  toggleDebugMode: unwiredFn("useBindings.toggleDebugMode"),
+  toggleAdminIndicator: unwiredFn("useBindings.toggleAdminIndicator"),
+  setCompareBase: unwiredFn("useBindings.setCompareBase"),
+  openCompareWithBase: async () => {
+    unwired("useBindings.openCompareWithBase");
+    return false;
+  },
+  openListenSummaryWindow: unwiredFn("useBindings.openListenSummaryWindow"),
+  openDiffWindow: unwiredFn("useBindings.openDiffWindow"),
+  openFindReplace: unwiredFn("useBindings.openFindReplace"),
+  openReferencePicker: unwiredFn("useBindings.openReferencePicker"),
+  openContextAssignment: unwiredFn("useBindings.openContextAssignment"),
+  openLinkRecordSheet: unwiredFn("useBindings.openLinkRecordSheet"),
+  openShareModalWindow: unwiredFn("useBindings.openShareModalWindow"),
+  openStateViewer: unwiredFn("useBindings.openStateViewer"),
+  openSurfaceInspector: unwiredFn("useBindings.openSurfaceInspector"),
+  openSurfaceContextWindow: unwiredFn("useBindings.openSurfaceContextWindow"),
+  openBindAgent: unwiredFn("useBindings.openBindAgent"),
+  quickActions: DEFAULT_QUICK_ACTIONS
+};
+var EMPTY_RENDER_DEFINITIONS = [];
+var DEFAULT_CONTEXT_MENU_HOST = {
+  useBindings: () => DEFAULT_BINDINGS,
+  getSurfaceManifest: () => void 0,
+  selectRenderDefinitions: () => EMPTY_RENDER_DEFINITIONS,
+  confirm: kitConfirm,
+  showManualCopy: () => unwired("showManualCopy"),
+  listeningHomeSurface: "matrx-user/assistant-message",
+  DocumentAgentReview: null
+};
+var SLOT = /* @__PURE__ */ Symbol.for("ai-matrx.context-menu.host");
+function slot() {
+  const g = globalThis;
+  let s = g[SLOT];
+  if (!s) {
+    s = { host: DEFAULT_CONTEXT_MENU_HOST, announced: /* @__PURE__ */ new Set() };
+    g[SLOT] = s;
+  }
+  return s;
+}
+function getContextMenuHost() {
+  return slot().host;
+}
+function useContextMenuHostBindings() {
+  return getContextMenuHost().useBindings();
+}
+
+// src/engine/hooks/useContextMenuActions.ts
+import { selectOrganizationId } from "@ai-matrx/chat/host/org";
+import { useAgentLauncher } from "@ai-matrx/chat/agents/hooks/useAgentLauncher";
+import { useSpeech } from "@ai-matrx/media/react";
+import { primeAudioOutput } from "@ai-matrx/media/speech";
+import { useSurfaceAgentRoles } from "@ai-matrx/chat/surfaces/hooks/useSurfaceConfig";
+
+// src/engine/utils/editor-text-insertion.ts
+function insertTextAtCursor(editorId, text) {
+  try {
+    const editor = document.querySelector(
+      `[data-editor-id="${editorId}"]`
+    );
+    if (!editor) {
+      console.error("[editor-text-insertion] Editor not found:", editorId);
+      return false;
+    }
+    editor.focus();
+    const selection = window.getSelection();
+    if (!selection) {
+      console.error("[editor-text-insertion] Selection not available");
+      return false;
+    }
+    let range;
+    if (selection.rangeCount > 0) {
+      range = selection.getRangeAt(0);
+    } else {
+      range = document.createRange();
+      const lastNode = editor.lastChild;
+      if (lastNode) {
+        if (lastNode.nodeType === Node.TEXT_NODE) {
+          range.setStart(lastNode, lastNode.textContent?.length ?? 0);
+        } else {
+          range.setStartAfter(lastNode);
+        }
+      } else {
+        range.setStart(editor, 0);
+      }
+      range.collapse(true);
+      selection.removeAllRanges();
+      selection.addRange(range);
+    }
+    if (!range.collapsed) {
+      range.deleteContents();
+    }
+    const textNode = document.createTextNode(text);
+    range.insertNode(textNode);
+    range.setStartAfter(textNode);
+    range.setEndAfter(textNode);
+    selection.removeAllRanges();
+    selection.addRange(range);
+    editor.focus();
+    return true;
+  } catch (error) {
+    console.error("[editor-text-insertion] Error inserting text:", error);
+    return false;
+  }
+}
+
+// src/engine/utils/insert-into-editor.ts
+import { blockBoundary, insertTextAtTextareaCursor } from "@ai-matrx/rich-editor/core/text-insertion";
+function hasEditorInsertTarget(targets) {
+  return Boolean(targets.editorId) || Boolean(targets.getTextarea) || Boolean(targets.insertAtCaret);
+}
+function insertIntoEditor(targets, text) {
+  const shaped = typeof text === "string" ? { editor: text, textarea: () => text, caret: text } : text;
+  const { editorId, getTextarea, insertAtCaret, onTextReplace } = targets;
+  const placement = shaped.placement ?? "inline";
+  if (editorId) {
+    const took = attempt("editor", () => {
+      if (placement === "block") moveEditorCaretToLineEnd(editorId);
+      return insertTextAtCursor(editorId, shaped.editor);
+    });
+    if (took) return "editor";
+  }
+  const field = editorId ? null : getTextarea?.() ?? null;
+  if (field) {
+    const took = attempt("textarea", () => {
+      if (placement === "block" && field.selectionStart === field.selectionEnd) {
+        const at = blockBoundary(field.value, field.selectionStart, field.selectionEnd, "nearest");
+        field.setSelectionRange(at, at);
+      }
+      return insertTextAtTextareaCursor(field, shaped.textarea(field), onTextReplace);
+    });
+    if (took) return "textarea";
+  }
+  if (insertAtCaret && attempt("caret", () => insertAtCaret(shaped.caret, placement))) return "caret";
+  return null;
+}
+function attempt(target, insert) {
+  try {
+    return insert();
+  } catch (error) {
+    console.error(`[ContextMenuV3] ${target} insert failed`, error);
+    return false;
+  }
+}
+function moveEditorCaretToLineEnd(editorId) {
+  const editor = document.querySelector(`[data-editor-id="${editorId}"]`);
+  const selection = window.getSelection();
+  if (!editor || !selection || selection.rangeCount === 0) return;
+  const range = selection.getRangeAt(0);
+  if (!range.collapsed || !editor.contains(range.startContainer)) return;
+  const node = range.startContainer;
+  if (node.nodeType !== Node.TEXT_NODE) return;
+  const text = node.textContent ?? "";
+  const at = blockBoundary(text, range.startOffset, range.startOffset, "nearest");
+  const next = document.createRange();
+  next.setStart(node, at);
+  next.collapse(true);
+  selection.removeAllRanges();
+  selection.addRange(next);
+}
+function ownParagraph(block, field) {
+  const before = field.value.slice(0, field.selectionStart);
+  const after = field.value.slice(field.selectionEnd);
+  const lead = before.length === 0 || before.endsWith("\n\n") ? "" : before.endsWith("\n") ? "\n" : "\n\n";
+  const tail = after.length === 0 || after.startsWith("\n\n") ? "" : after.startsWith("\n") ? "\n" : "\n\n";
+  return `${lead}${block}${tail}`;
+}
+
+// src/engine/hooks/useContextMenuActions.ts
+import { resolveActions } from "@ai-matrx/rich-content/rich-document/actions/provider";
+import { registryMenuActions } from "@ai-matrx/rich-content/rich-document/variants/shared/menuStructure";
+import { getSourceAdapter } from "@ai-matrx/rich-content/rich-document/actions/sources/index";
+import { shortHash } from "@ai-matrx/rich-content/rich-document/actions/sources/raw";
+import {
+  placementGroupKey as placementGroupKey2,
+  PLACEMENT_TYPES,
+  PLACEMENT_TYPE_META
+} from "@ai-matrx/chat/agents/shortcuts/constants";
+
+// src/engine/hooks/useUnifiedAgentContextMenu.ts
+import { useMemo, useState, useCallback } from "react";
+import { useAppDispatch, useAppSelector } from "@ai-matrx/chat/store/hooks";
+import {
+  fetchUnifiedMenu,
+  unifiedMenuLoadedKey
+} from "@ai-matrx/chat/agents/redux/agent-shortcuts/thunks";
+
+// src/engine/utils/menu-deadline.ts
+var menu_deadline_exports = {};
+__reExport(menu_deadline_exports, menu_deadline_star);
+import * as menu_deadline_star from "@ai-matrx/chat/context-menu/utils/menu-deadline";
+
+// src/engine/hooks/useUnifiedAgentContextMenu.ts
+import { selectAllShortcutsArray } from "@ai-matrx/chat/agents/redux/agent-shortcuts/selectors";
+import { selectAllCategoriesArray } from "@ai-matrx/chat/agents/redux/agent-shortcut-categories/selectors";
+import { resolveRowScope } from "@ai-matrx/chat/agents/redux/shared/scope";
+import { placementGroupKey } from "@ai-matrx/chat/agents/shortcuts/constants";
+
+// src/engine/model/requirement-gate.ts
+var requirement_gate_exports = {};
+__reExport(requirement_gate_exports, requirement_gate_star);
+import * as requirement_gate_star from "@ai-matrx/chat/context-menu/model/requirement-gate";
+
+// src/engine/hooks/useUnifiedAgentContextMenu.ts
+var SELECTION_DEPENDENT_KEYS = /* @__PURE__ */ new Set(["selection"]);
+var SCOPE_PRIORITY = {
+  task: 5,
+  project: 4,
+  user: 3,
+  organization: 2,
+  global: 1
+};
+var SPECIFICITY = {
+  surface: 3,
+  domain: 2,
+  global: 1
+};
+function specificityOf(item) {
+  return SPECIFICITY[(0, requirement_gate_exports.readMenuScope)({ id: "", surfaceName: item.surfaceName ?? null }).level];
+}
+function beats(a, b) {
+  const byOwner = SCOPE_PRIORITY[a.scopeLevel] - SCOPE_PRIORITY[b.scopeLevel];
+  if (byOwner !== 0) return byOwner > 0;
+  const bySpecificity = specificityOf(a) - specificityOf(b);
+  if (bySpecificity !== 0) return bySpecificity > 0;
+  return a.id < b.id;
+}
+function dedupeByPrecedence(items, keyFn) {
+  const winners = /* @__PURE__ */ new Map();
+  const passthrough = [];
+  for (const item of items) {
+    const key = keyFn(item);
+    if (!key) {
+      passthrough.push(item);
+      continue;
+    }
+    const existing = winners.get(key);
+    if (!existing || beats(item, existing)) winners.set(key, item);
+  }
+  return [...winners.values(), ...passthrough];
+}
+function buildCategoryGroups(args) {
+  const {
+    placementTypes,
+    surfaceName = null,
+    availableKeys,
+    hasSelection,
+    excludedItemIds,
+    shortcuts,
+    categories,
+    contentBlocks
+  } = args;
+  if (placementTypes.length === 0) return [];
+  const placementSet = new Set(placementTypes);
+  const scopedCategories = categories.filter(
+    (c) => c.isActive !== false && placementSet.has(placementGroupKey(c.placementType))
+  ).map((c) => ({ ...c, scopeLevel: resolveRowScope(c) }));
+  const scopedShortcuts = shortcuts.filter((s) => s.isActive !== false).map((s) => ({
+    ...s,
+    entryType: "agent_shortcut",
+    scopeLevel: resolveRowScope(s)
+  }));
+  const scopedBlocks = contentBlocks.filter((b) => b.isActive !== false).map((b) => ({
+    ...b,
+    entryType: "content_block",
+    scopeLevel: resolveRowScope(b)
+  }));
+  const offerCtx = compact({
+    surfaceName,
+    availableKeys,
+    excludedItemIds
+  });
+  const filteredShortcuts = scopedShortcuts.filter((s) => {
+    if (!(0, requirement_gate_exports.decideOffer)(s, offerCtx).offered) return false;
+    if (hasSelection) return true;
+    return !(0, requirement_gate_exports.requirementsOf)(s).some((key) => SELECTION_DEPENDENT_KEYS.has(key));
+  });
+  const filteredBlocks = scopedBlocks.filter(
+    (b) => !excludedItemIds?.has(b.id)
+  );
+  const dedupedShortcuts = dedupeByPrecedence(filteredShortcuts, (s) => {
+    if (s.keyboardShortcut) return `kbd:${s.keyboardShortcut}`;
+    return `label:${s.categoryId}:${s.label}`;
+  });
+  const dedupedBlocks = dedupeByPrecedence(
+    filteredBlocks,
+    (b) => `block:${b.categoryId ?? "_none"}:${b.blockId}`
+  );
+  const byCategory = /* @__PURE__ */ new Map();
+  for (const s of dedupedShortcuts) {
+    if (!byCategory.has(s.categoryId)) byCategory.set(s.categoryId, []);
+    byCategory.get(s.categoryId).push(s);
+  }
+  for (const b of dedupedBlocks) {
+    const cid = b.categoryId;
+    if (!cid) continue;
+    if (!byCategory.has(cid)) byCategory.set(cid, []);
+    byCategory.get(cid).push(b);
+  }
+  const dedupedCategories = dedupeByPrecedence(
+    scopedCategories,
+    (c) => `${c.placementType}:${c.parentCategoryId ?? "_root"}:${c.label}`
+  );
+  const nodeMap = /* @__PURE__ */ new Map();
+  for (const cat of dedupedCategories) {
+    nodeMap.set(cat.id, {
+      category: cat,
+      items: (byCategory.get(cat.id) ?? []).slice().sort((x, y) => (x.sortOrder ?? 0) - (y.sortOrder ?? 0)),
+      children: []
+    });
+  }
+  const roots = [];
+  for (const cat of dedupedCategories) {
+    const node = nodeMap.get(cat.id);
+    if (cat.parentCategoryId && nodeMap.has(cat.parentCategoryId)) {
+      nodeMap.get(cat.parentCategoryId).children.push(node);
+    } else {
+      roots.push(node);
+    }
+  }
+  const sortNodes = (nodes) => {
+    nodes.sort(
+      (a, b) => (a.category.sortOrder ?? 0) - (b.category.sortOrder ?? 0) || a.category.label.localeCompare(b.category.label)
+    );
+    for (const n of nodes) sortNodes(n.children);
+  };
+  sortNodes(roots);
+  return roots;
+}
+function useUnifiedAgentContextMenu(args) {
+  const {
+    placementTypes,
+    surfaceName = null,
+    availableKeys,
+    hasSelection,
+    excludedItemIds,
+    enabled = true,
+    scope = "global",
+    scopeId = null
+  } = args;
+  const dispatch = useAppDispatch();
+  const shortcuts = useAppSelector(selectAllShortcutsArray);
+  const categories = useAppSelector(selectAllCategoriesArray);
+  const contentBlocks = useAppSelector((state) => getContextMenuHost().selectRenderDefinitions(state));
+  const rowsInHand = useAppSelector(
+    (state) => state.agentShortcut.contextLoaded?.[unifiedMenuLoadedKey({ scope, scopeId })] ?? false
+  );
+  const [error, setError] = useState(null);
+  const refresh = useCallback(async () => {
+    if (!enabled || placementTypes.length === 0) return;
+    try {
+      setError(null);
+      await (0, menu_deadline_exports.withMenuDeadline)(
+        dispatch(fetchUnifiedMenu({ scope, scopeId })).unwrap(),
+        "Loading the menu's AI actions"
+      );
+    } catch (err) {
+      if (err?.name === "ConditionError") return;
+      setError(err instanceof Error ? err.message : "Failed to load menu");
+    }
+  }, [dispatch, enabled, placementTypes.length, scope, scopeId]);
+  const categoryGroups = useMemo(() => {
+    if (!enabled) return [];
+    return buildCategoryGroups({
+      placementTypes,
+      surfaceName,
+      availableKeys,
+      hasSelection,
+      excludedItemIds,
+      shortcuts,
+      categories,
+      contentBlocks: [...contentBlocks]
+    });
+  }, [
+    enabled,
+    placementTypes,
+    categories,
+    shortcuts,
+    contentBlocks,
+    surfaceName,
+    availableKeys,
+    hasSelection,
+    excludedItemIds
+  ]);
+  return {
+    categoryGroups,
+    loading: enabled && placementTypes.length > 0 && !rowsInHand && error === null,
+    // Rows in hand end a failure too: a fetch that landed after the menu's
+    // deadline must not leave a "Couldn't load" row beside the rows it brought.
+    error: rowsInHand ? null : error,
+    refresh
+  };
+}
+
+// src/engine/hooks/useContextMenuActions.ts
+import { BASELINE_VALUE_NAMES as BASELINE_VALUE_NAMES2 } from "@ai-matrx/chat/surfaces/manifests/_baseline.manifest";
+import { useSurfaceConfig } from "@ai-matrx/chat/surfaces/hooks/useSurfaceConfig";
+import { useSurfaceBoundAgents } from "@ai-matrx/chat/surfaces/hooks/useSurfaceBoundAgents";
+
+// src/engine/value-resolution.ts
+import { withBaselineScope } from "@ai-matrx/chat/surfaces/utils/baseline-scope";
+import {
+  BASELINE_VALUE_NAMES
+} from "@ai-matrx/chat/surfaces/manifests/_baseline.manifest";
+import {
+  getSurfaceRuntime,
+  getSurfaceRuntimeForName
+} from "@ai-matrx/chat/surfaces/runtime/SurfaceRuntimeContext";
+var SKIP_MERGE_KEYS = /* @__PURE__ */ new Set([types_exports.CONTEXT_MENU_ENTITY_KEY, types_exports.CONTEXT_MENU_HEADING_KEY]);
+var isDev = process.env.NODE_ENV !== "production";
+function strOf(value) {
+  return typeof value === "string" ? value : "";
+}
+function adoptMountedRuntimeScope(surfaceName) {
+  try {
+    const mounted = surfaceName ? getSurfaceRuntimeForName(surfaceName) : getSurfaceRuntime();
+    if (!mounted) return null;
+    const payload = mounted.getScope();
+    if (payload && typeof payload.then === "function")
+      return null;
+    return payload;
+  } catch (err) {
+    if (isDev)
+      console.error(
+        "[ContextMenuV3] mounted SurfaceRuntime threw in getScope() \u2014 menu scope falls back to the surface's own values",
+        err
+      );
+    return null;
+  }
+}
+function isEmptyValue(value) {
+  if (value === void 0 || value === null) return true;
+  if (typeof value === "string") return value.trim() === "";
+  if (typeof value === "object" && !Array.isArray(value))
+    return Object.keys(value).length === 0;
+  return false;
+}
+function resolveApplicationScope(args) {
+  const base = buildFromMenuContext(args);
+  const surfaceAnswered = new Set(
+    Object.keys(args.contextData ?? {}).filter((k) => !SKIP_MERGE_KEYS.has(k))
+  );
+  if (args.getApplicationScope) {
+    const live = args.getApplicationScope();
+    for (const [k, v] of Object.entries(live)) {
+      if (SKIP_MERGE_KEYS.has(k) || v === void 0) continue;
+      base[k] = v;
+      surfaceAnswered.add(k);
+    }
+  }
+  const runtime = adoptMountedRuntimeScope(args.surfaceName);
+  if (runtime) {
+    for (const [k, v] of Object.entries(runtime)) {
+      if (SKIP_MERGE_KEYS.has(k) || v === void 0) continue;
+      if (surfaceAnswered.has(k)) continue;
+      if (isEmptyValue(base[k])) base[k] = v;
+    }
+  }
+  if (args.ambient && !surfaceAnswered.has("ambient") && isEmptyValue(base.ambient))
+    base.ambient = args.ambient;
+  const hasContent = strOf(base.content).trim().length > 0;
+  if (!args.getApplicationScope && !hasContent && args.fallbackContent && args.fallbackContent.trim()) {
+    base.content = args.fallbackContent;
+  }
+  return withBaselineScope(base);
+}
+function buildFromMenuContext(args) {
+  const { selectedText, selectionRange, contextData: cd } = args;
+  let textBefore = "";
+  let textAfter = "";
+  let fullContent = "";
+  if (selectionRange && selectionRange.type === "editable" && selectionRange.element) {
+    const value = selectionRange.element.value ?? "";
+    fullContent = value;
+    textBefore = value.substring(0, selectionRange.start ?? 0);
+    textAfter = value.substring(selectionRange.end ?? 0);
+  }
+  const scope = {};
+  for (const [k, v] of Object.entries(cd)) {
+    if (SKIP_MERGE_KEYS.has(k) || v === void 0) continue;
+    scope[k] = v;
+  }
+  if (typeof cd.context === "string") {
+    scope.context = { raw: cd.context };
+  } else if (cd.context !== void 0 && typeof cd.context !== "string") {
+    scope.context = cd.context;
+  } else if (scope.context === void 0) {
+    scope.context = {};
+  }
+  scope.selection = selectedText;
+  scope.text_before = textBefore;
+  scope.text_after = textAfter;
+  if (typeof cd.content === "string") {
+    scope.content = cd.content;
+  } else if (fullContent) {
+    scope.content = fullContent;
+  } else if (scope.content === void 0) {
+    scope.content = "";
+  }
+  const activeText = scope.active_text;
+  if (scope.selection === "" && typeof activeText === "string" && activeText.length > 0) {
+    scope.selection = activeText;
+  }
+  return scope;
+}
+function resolveActionText(scope) {
+  const selection = strOf(scope.selection).trim();
+  if (selection) return { text: strOf(scope.selection), source: "selection" };
+  const content = strOf(scope.content).trim();
+  if (content) return { text: strOf(scope.content), source: "content" };
+  return { text: "", source: "none" };
+}
+function detectInertMenu(args) {
+  const reasons = [];
+  const selection = strOf(args.scope.selection).trim();
+  const content = strOf(args.scope.content).trim();
+  const baseline = new Set(
+    BASELINE_VALUE_NAMES
+  );
+  const hasApplicationScope = Object.entries(args.scope).some(
+    ([key, value]) => !baseline.has(key) && !isEmptyValue(value)
+  );
+  if (!selection) reasons.push("no selection");
+  if (!content) reasons.push("no resolvable content (and no DOM-text fallback)");
+  const inert = !args.isEditable && !selection && !content && !hasApplicationScope && !args.hasExtraSections;
+  return { inert, reasons };
+}
+function auditSurfaceScope(surfaceName, scope) {
+  if (!surfaceName) return [];
+  const manifest = getContextMenuHost().getSurfaceManifest(surfaceName);
+  if (!manifest) {
+    return [
+      `surface "${surfaceName}" has no registered manifest \u2014 its declared values cannot be verified`
+    ];
+  }
+  const baseline = new Set(BASELINE_VALUE_NAMES);
+  const warnings = [];
+  for (const value of manifest.values) {
+    if (baseline.has(value.name)) continue;
+    if (!value.alwaysAvailable) continue;
+    const present = scope[value.name];
+    if (!(value.name in scope) || present === void 0 || present === null) {
+      warnings.push(
+        `declared value "${value.name}" is alwaysAvailable but was not emitted into the scope`
+      );
+    }
+  }
+  return warnings;
+}
+function reportMenuDiagnostics(args) {
+  const diag = detectInertMenu(args);
+  if (!isDev) return diag;
+  const label = args.surfaceName ?? "(no surfaceName)";
+  if (diag.inert) {
+    console.error(
+      `%c[ContextMenuV3] INERT MENU on "${label}"%c \u2014 opened with nothing to act on (${diag.reasons.join(
+        ", "
+      )}). This is the "fake menu" defect: the surface must provide a selection, contextData.content, getApplicationScope(), or render selectable content the DOM fallback can read.`,
+      "color:#ef4444;font-weight:bold",
+      "color:inherit",
+      { scopeKeys: Object.keys(args.scope) }
+    );
+  }
+  const valueWarnings = auditSurfaceScope(args.surfaceName, args.scope);
+  if (valueWarnings.length > 0) {
+    console.error(
+      `%c[ContextMenuV3] VALUE MAPPING GAP on "${label}"%c \u2014 ${valueWarnings.join(
+        "; "
+      )}. Shortcuts/agents bound to these values will receive nothing.`,
+      "color:#f59e0b;font-weight:bold",
+      "color:inherit"
+    );
+  }
+  return diag;
+}
+
+// src/engine/utils/selection-tracking.ts
+var selection_tracking_exports = {};
+__reExport(selection_tracking_exports, selection_tracking_star);
+import * as selection_tracking_star from "@ai-matrx/chat/context-menu/utils/selection-tracking";
+
+// src/engine/utils/selection-write-back.ts
+function isField(el) {
+  return typeof HTMLTextAreaElement !== "undefined" && el instanceof HTMLTextAreaElement || typeof HTMLInputElement !== "undefined" && el instanceof HTMLInputElement;
+}
+function buildSelectionWriteBack(args) {
+  const {
+    originalText,
+    textSource,
+    selectionRange,
+    onTextReplace,
+    onTextInsertAfter,
+    insertAtCaret
+  } = args;
+  if (!originalText) return null;
+  const fieldEl = selectionRange?.type === "editable" && isField(selectionRange.element) ? selectionRange.element : null;
+  if (fieldEl) {
+    let anchorText = originalText;
+    let anchorStart = textSource === "selection" ? selectionRange.start : 0;
+    const locate = () => {
+      if (!fieldEl.isConnected) return null;
+      const value = fieldEl.value;
+      if (value.slice(anchorStart, anchorStart + anchorText.length) === anchorText) {
+        return { start: anchorStart, end: anchorStart + anchorText.length };
+      }
+      const first = value.indexOf(anchorText);
+      if (first === -1 || value.indexOf(anchorText, first + 1) !== -1) {
+        return null;
+      }
+      return { start: first, end: first + anchorText.length };
+    };
+    const write = (start, end, insert) => {
+      const value = fieldEl.value;
+      const next = value.slice(0, start) + insert + value.slice(end);
+      if (onTextReplace) onTextReplace(next);
+      else (0, selection_tracking_exports.spliceInputValue)(fieldEl, start, end, insert);
+    };
+    return {
+      originalText,
+      replace: (text) => {
+        const at = locate();
+        if (!at) return false;
+        write(at.start, at.end, text);
+        anchorStart = at.start;
+        anchorText = text;
+        return true;
+      },
+      insertBelow: (text) => {
+        const at = locate();
+        if (!at) return false;
+        const block = "\n\n" + text;
+        write(at.end, at.end, block);
+        anchorStart = at.end + 2;
+        anchorText = text;
+        return true;
+      }
+    };
+  }
+  if (textSource !== "selection") return null;
+  if (!insertAtCaret && !onTextInsertAfter) return null;
+  return {
+    originalText,
+    replace: (text) => insertAtCaret ? insertAtCaret(text) : false,
+    insertBelow: (text) => {
+      if (!onTextInsertAfter) return false;
+      onTextInsertAfter(text);
+      return true;
+    }
+  };
+}
+
+// src/engine/hooks/useContextMenuActions.ts
+import { registerLaunchWidgetHandle } from "@ai-matrx/chat/agents/utils/launch-widget-handles";
+
+// src/engine/utils/json-menu-actions.ts
+import { detectJson } from "@ai-matrx/kit/json-format";
+import { formatJsonText } from "@ai-matrx/kit/json-format";
+function lineCount(text) {
+  let n = text === "" ? 0 : 1;
+  for (let i = 0; i < text.length; i++) if (text[i] === "\n") n++;
+  return n;
+}
+function sizeHint(before, after) {
+  const b = lineCount(before);
+  const a = lineCount(after);
+  if (b !== a) {
+    return `${b} line${b !== 1 ? "s" : ""} -> ${a} line${a !== 1 ? "s" : ""}`;
+  }
+  return `${before.length} -> ${after.length} chars`;
+}
+function shapePreservingStyle(detection) {
+  return detection.payload.includes("\n") ? "pretty" : "minify";
+}
+function buildJsonMenuSection(params) {
+  const { text, canWrite, onReplace, onCopy } = params;
+  if (!text.trim()) return null;
+  const detection = detectJson(text);
+  if (!detection.looksLikeJson) return null;
+  if (!detection.ok) {
+    return {
+      detection,
+      writes: false,
+      actions: [
+        {
+          id: "json-invalid",
+          label: "Invalid JSON",
+          hint: detection.error,
+          disabled: true,
+          run: () => {
+          }
+        }
+      ]
+    };
+  }
+  const apply = (next) => {
+    if (canWrite) onReplace(next);
+    else void onCopy(next);
+  };
+  const verb = canWrite ? "" : "Copy ";
+  const actions = [];
+  const addFormat = (id, label, style, fence = "preserve", sortKeys = false) => {
+    const result = formatJsonText(text, { style, fence, sortKeys });
+    if (!result.ok) return;
+    if (canWrite && !result.changed) return;
+    actions.push({
+      id,
+      label,
+      hint: result.changed ? sizeHint(text, result.text) : void 0,
+      run: () => apply(result.text)
+    });
+  };
+  addFormat("json-condense", `${verb}Condense`, "compact");
+  addFormat("json-minify", `${verb}Minify (one line)`, "minify");
+  addFormat("json-expand", `${verb}Expand`, "pretty");
+  addFormat(
+    "json-sort-keys",
+    `${verb}Sort keys A-Z`,
+    shapePreservingStyle(detection),
+    "preserve",
+    true
+  );
+  if (detection.fence) {
+    addFormat(
+      "json-strip-fence",
+      `${verb}Remove code fence`,
+      shapePreservingStyle(detection),
+      "strip"
+    );
+  } else {
+    addFormat(
+      "json-add-fence",
+      `${verb}Wrap in json code fence`,
+      shapePreservingStyle(detection),
+      "add"
+    );
+  }
+  if (canWrite) {
+    const minified = formatJsonText(text, { style: "minify", fence: "strip" });
+    if (minified.ok) {
+      actions.push({
+        id: "json-copy-minified",
+        label: "Copy minified",
+        hint: sizeHint(text, minified.text),
+        run: () => void onCopy(minified.text)
+      });
+    }
+  }
+  if (actions.length === 0) return null;
+  return { detection, writes: canWrite, actions };
+}
+function jsonSectionLabel(section) {
+  const { detection } = section;
+  if (!detection.ok) return "JSON (invalid)";
+  const n = detection.lineCount;
+  const kind = detection.root === "array" ? "array" : "object";
+  return `JSON ${kind} \xB7 ${n} line${n !== 1 ? "s" : ""}`;
+}
+
+// src/engine/managed-agent-launch.ts
+var MANAGED_CONTEXT_MENU_AGENT_CONFIG = {
+  displayMode: "flexible-panel",
+  allowChat: true,
+  showVariablePanel: true
+};
+
+// src/engine/hooks/useContextMenuActions.ts
+import { AGENT_ICON } from "@ai-matrx/icons/domain";
+var DEFAULT_PLACEMENT_MODE = {
+  "ai-action": "show",
+  "bound-agent": "show",
+  "content-block": "show",
+  "organization-tool": "show",
+  "user-tool": "show",
+  "quick-action": "show"
+};
+var ALL_DB_PLACEMENTS = [
+  "ai-action",
+  "content-block",
+  "organization-tool",
+  "user-tool"
+];
+var PLACEMENT_LABEL_OVERRIDE = {
+  [PLACEMENT_TYPES.USER_TOOL]: "My Items",
+  [PLACEMENT_TYPES.ORGANIZATION_TOOL]: "Org Items"
+};
+var PLACEMENT_COLOR = {
+  [PLACEMENT_TYPES.AI_ACTION]: "#0ea5e9",
+  [PLACEMENT_TYPES.CONTENT_BLOCK]: "#8b5cf6",
+  [PLACEMENT_TYPES.ORGANIZATION_TOOL]: "#f59e0b",
+  [PLACEMENT_TYPES.USER_TOOL]: "#10b981"
+};
+function getPlacementIcon(placementType) {
+  switch (placementType) {
+    case PLACEMENT_TYPES.AI_ACTION:
+      return Rocket;
+    case PLACEMENT_TYPES.CONTENT_BLOCK:
+      return FileText;
+    case PLACEMENT_TYPES.ORGANIZATION_TOOL:
+      return Building;
+    case PLACEMENT_TYPES.USER_TOOL:
+      return User;
+    default:
+      return FileText;
+  }
+}
+function getPlacementLabel(placementType) {
+  return PLACEMENT_LABEL_OVERRIDE[placementType] ?? PLACEMENT_TYPE_META[placementType]?.label ?? placementType;
+}
+function resolveIcon(iconName, fallback = "FileText") {
+  return getIconComponent(iconName ?? fallback, fallback);
+}
+function groupsByPlacement(groups) {
+  const map = {};
+  for (const g of groups) {
+    (map[placementGroupKey2(g.category.placementType)] ??= []).push(g);
+  }
+  return map;
+}
+function resolveRichActionView(action, ctx) {
+  const label = typeof action.label === "function" ? action.label(ctx) : action.label;
+  const disabledResult = action.disabled?.(ctx);
+  const disabled = typeof disabledResult === "object" ? true : Boolean(disabledResult);
+  return { label, disabled };
+}
+function useContextMenuActions(props) {
+  const {
+    sourceFeature,
+    surfaceName,
+    menuVersion,
+    getApplicationScope,
+    contextData,
+    selectedText,
+    selectionRange,
+    fallbackContent,
+    placementMode,
+    scope: shortcutScope,
+    scopeId,
+    extraSections,
+    isEditable,
+    editorId,
+    getTextarea,
+    insertAtCaret,
+    onContentInserted,
+    onTextReplace,
+    onTextInsertAfter,
+    onDelete,
+    onUndo,
+    onRedo,
+    widgetHandleId
+  } = props;
+  const dispatch = useAppDispatch2();
+  const store = useAppStore();
+  const host = useContextMenuHostBindings();
+  const entity = props.entity;
+  const resolvedPlacementMode = {
+    ...DEFAULT_PLACEMENT_MODE,
+    ...placementMode ?? {}
+  };
+  const dbPlacementTypes = ALL_DB_PLACEMENTS.filter(
+    (p) => resolvedPlacementMode[p] !== "hide"
+  );
+  const activeOrganizationId = useAppSelector2(selectOrganizationId);
+  const activeScopeIds = host.activeScopeIds;
+  const scope = resolveApplicationScope({
+    getApplicationScope,
+    contextData,
+    selectedText,
+    selectionRange,
+    fallbackContent,
+    surfaceName,
+    ambient: {
+      active_organization_id: activeOrganizationId ?? null,
+      active_scope_ids: activeScopeIds ?? [],
+      surface_name: surfaceName ?? null
+    }
+  });
+  const scopeKeySignature = Object.keys(scope).sort().join("|");
+  const availableKeys = useMemo2(
+    () => (0, requirement_gate_exports.buildAvailableKeys)(compact({
+      baselineValueNames: BASELINE_VALUE_NAMES2,
+      declaredValueNames: surfaceName ? getContextMenuHost().getSurfaceManifest(surfaceName)?.values.map((v) => v.name) : void 0,
+      // `scope` is rebuilt every render but its KEY SET is stable for an
+      // open, so the signature — not the object — is the dependency.
+      runtimeScopeKeys: scopeKeySignature.split("|").filter(Boolean)
+    })),
+    [surfaceName, scopeKeySignature]
+  );
+  const { getNamespace: getSurfaceNamespace } = useSurfaceConfig(
+    surfaceName ?? "matrx-unregistered/context-menu"
+  );
+  const menuSurfaceConfig = getSurfaceNamespace("menu");
+  const excludedItemIds = useMemo2(
+    () => new Set(menuSurfaceConfig?.excludedItemIds ?? []),
+    [menuSurfaceConfig]
+  );
+  const {
+    categoryGroups,
+    loading,
+    error: librariesError,
+    refresh
+  } = useUnifiedAgentContextMenu({
+    placementTypes: dbPlacementTypes,
+    surfaceName,
+    availableKeys,
+    hasSelection: String(scope.selection ?? "").trim().length > 0,
+    excludedItemIds,
+    enabled: dbPlacementTypes.length > 0,
+    scope: shortcutScope,
+    scopeId
+  });
+  const {
+    sections: boundAgentSections,
+    loading: boundAgentsFetching,
+    settled: boundAgentsSettled,
+    error: boundAgentsError,
+    refresh: refreshBoundAgents
+  } = useSurfaceBoundAgents(surfaceName, { isEditable });
+  const boundAgentsLoading = boundAgentsFetching || !boundAgentsSettled;
+  const { launchShortcut, launchAgent } = useAgentLauncher();
+  const { speak } = useSpeech({ processMarkdown: true, label: "Selected text" });
+  const { roles: surfaceAgentRoles } = useSurfaceAgentRoles(
+    surfaceName ?? "matrx-unregistered/context-menu"
+  );
+  const {
+    openListenSummaryWindow,
+    quickActions,
+    openDiffWindow,
+    openFindReplace,
+    openReferencePicker,
+    openContextAssignment,
+    openLinkRecordSheet,
+    openShareModalWindow,
+    openStateViewer,
+    openSurfaceInspector,
+    hasCompareBase
+  } = host;
+  const currentUserId = useAppSelector2(selectUserId);
+  const isAdmin = host.isAdminDebugger;
+  const hasAdminPower = host.hasAdminPower;
+  const organizationId = useAppSelector2(selectOrganizationId);
+  const isDebugMode = host.isDebugMode;
+  const isAdminIndicatorOpen = host.isAdminIndicatorOpen;
+  useEffect(() => {
+    void refresh();
+    void refreshBoundAgents();
+  }, []);
+  const actionText = resolveActionText(scope);
+  const richDocSource = props.contentSource ?? { type: "raw" };
+  const richDocAdapter = getSourceAdapter(richDocSource.type);
+  const richPrefix = richDocSource.type === "raw" ? `${richDocAdapter.instanceKeyPrefix(richDocSource)}-${shortHash(actionText.text).slice(0, 8)}` : richDocAdapter.instanceKeyPrefix(richDocSource);
+  const richDocCtx = {
+    content: actionText.text,
+    source: richDocSource,
+    metadata: null,
+    dispatch,
+    getState: store.getState,
+    organizationId,
+    isAuthenticated: Boolean(currentUserId),
+    isAdmin: hasAdminPower,
+    isCreator: false,
+    surfaceKey: surfaceName ?? null,
+    onClose: () => {
+    },
+    instanceKey: (prefix) => `${richPrefix}-${prefix}`,
+    sourceAdapter: richDocAdapter,
+    applicationScope: scope,
+    ...props.richDocCtxExtras ?? {}
+  };
+  const textAgentCallbacks = editorTextAgentCallbacks(richDocCtx.callbacks, richDocSource, richDocAdapter, props.requestTextAgentReview);
+  if (textAgentCallbacks) richDocCtx.callbacks = textAgentCallbacks;
+  const excludedRichActionIds = [
+    ...props.excludedRichActions ?? [],
+    ...actionsAlreadyHere({
+      sourceType: richDocSource.type,
+      surfaceName,
+      isEditable: Boolean(isEditable)
+    })
+  ];
+  const richActions = actionText.source !== "none" ? resolveActions(richDocCtx, compact({
+    exclude: excludedRichActionIds,
+    extra: props.extraRichActions
+  })) : [];
+  const registryActions = registryMenuActions(richActions);
+  const copyVariantActions = richActions.filter((a) => a.category === "copy");
+  const exportActions = richActions.filter(
+    (a) => a.category === "export" || a.id === "save-as-file"
+  );
+  const convertActions = richActions.filter(
+    (a) => a.category === "save" && a.id !== "save-as-file"
+  );
+  useEffect(() => {
+    reportMenuDiagnostics({
+      surfaceName,
+      scope,
+      isEditable,
+      hasExtraSections: Boolean(extraSections && extraSections.length > 0)
+    });
+  }, []);
+  const handleCopy = async () => {
+    if (!actionText.text) return;
+    if (!await kitCopyText(actionText.text)) {
+      getContextMenuHost().showManualCopy({ text: actionText.text });
+    }
+  };
+  const handleSpeak = () => {
+    if (actionText.text.trim()) speak(actionText.text);
+  };
+  const { roles: listenHomeRoles } = useSurfaceAgentRoles(
+    getContextMenuHost().listeningHomeSurface
+  );
+  const spokenSummaryRole = surfaceAgentRoles.spoken_summary?.effectiveAgentId ? surfaceAgentRoles.spoken_summary : listenHomeRoles.spoken_summary;
+  const spokenSummaryAgentId = spokenSummaryRole?.effectiveAgentId ?? null;
+  const openSpokenSummary = (autoPlay) => {
+    if (!spokenSummaryAgentId || !actionText.text.trim()) return;
+    primeAudioOutput();
+    openListenSummaryWindow({
+      agentId: spokenSummaryAgentId,
+      agentName: spokenSummaryRole?.role.label ?? null,
+      sourceText: actionText.text,
+      style: "Extremely Concise Summary",
+      autoPlay
+    });
+  };
+  const handleSpokenSummary = () => openSpokenSummary(false);
+  const handleSpokenSummaryLive = () => openSpokenSummary(true);
+  const handleCut = async () => {
+    if (!selectionRange || selectionRange.type !== "editable") return;
+    const element = selectionRange.element;
+    if (!(element instanceof HTMLTextAreaElement) && !(element instanceof HTMLInputElement))
+      return;
+    const { start, end } = selectionRange;
+    const cutText = element.value.substring(start, end);
+    if (!await kitCopyText(cutText)) {
+      getContextMenuHost().showManualCopy({ text: cutText, title: "Copy manually (cut was blocked)" });
+      return;
+    }
+    if (onTextReplace) {
+      onTextReplace(
+        element.value.substring(0, start) + element.value.substring(end)
+      );
+    } else {
+      (0, selection_tracking_exports.spliceInputValue)(element, start, end, "");
+    }
+  };
+  const handlePaste = async () => {
+    if (!isEditable || !selectionRange || selectionRange.type !== "editable")
+      return;
+    const element = selectionRange.element;
+    if (!(element instanceof HTMLTextAreaElement) && !(element instanceof HTMLInputElement))
+      return;
+    const text = await kitReadText();
+    if (text === null) {
+      toast({ title: "Couldn't read the clipboard", variant: "destructive" });
+      return;
+    }
+    const { start, end } = selectionRange;
+    if (onTextReplace) {
+      onTextReplace(
+        element.value.substring(0, start) + text + element.value.substring(end)
+      );
+    } else {
+      (0, selection_tracking_exports.spliceInputValue)(element, start, end, text);
+    }
+  };
+  const editableTarget = isEditable && selectionRange?.type === "editable" ? selectionRange.element : null;
+  const canWriteJson = editableTarget instanceof HTMLTextAreaElement || editableTarget instanceof HTMLInputElement;
+  const jsonSection = buildJsonMenuSection({
+    text: actionText.text,
+    canWrite: canWriteJson,
+    onReplace: (next) => {
+      if (!canWriteJson || !selectionRange || selectionRange.type !== "editable")
+        return;
+      const element = selectionRange.element;
+      if (!(element instanceof HTMLTextAreaElement) && !(element instanceof HTMLInputElement))
+        return;
+      const { start, end } = actionText.source === "selection" ? selectionRange : { start: 0, end: element.value.length };
+      if (onTextReplace) {
+        onTextReplace(
+          element.value.substring(0, start) + next + element.value.substring(end)
+        );
+      } else {
+        (0, selection_tracking_exports.spliceInputValue)(element, start, end, next);
+      }
+    },
+    onCopy: async (next) => {
+      if (await kitCopyText(next)) {
+        toast({ title: "Copied", description: "JSON copied to clipboard." });
+      } else {
+        getContextMenuHost().showManualCopy({ text: next });
+      }
+    }
+  });
+  const handleSelectAll = () => {
+    if (!selectionRange) {
+      const field = getTextarea?.();
+      if (field) {
+        requestAnimationFrame(() => {
+          field.focus();
+          field.select();
+        });
+      }
+      return;
+    }
+    if (selectionRange.type === "editable") {
+      const element = selectionRange.element;
+      if (element instanceof HTMLTextAreaElement || element instanceof HTMLInputElement) {
+        requestAnimationFrame(() => {
+          element.focus();
+          element.select();
+        });
+      }
+    } else {
+      const container = selectionRange.containerElement;
+      if (!container) return;
+      requestAnimationFrame(() => {
+        try {
+          const range = document.createRange();
+          range.selectNodeContents(container);
+          const selection = window.getSelection();
+          if (selection) {
+            selection.removeAllRanges();
+            selection.addRange(range);
+          }
+        } catch {
+        }
+      });
+    }
+  };
+  const editableElement = (() => {
+    const fromRange = selectionRange?.type === "editable" ? selectionRange.element : null;
+    const el = fromRange ?? getTextarea?.() ?? null;
+    return el instanceof HTMLTextAreaElement || el instanceof HTMLInputElement ? el : null;
+  })();
+  const canNativeUndo = Boolean(isEditable && editableElement);
+  const runNativeEdit = (command) => {
+    if (!editableElement) return;
+    editableElement.focus();
+    try {
+      document.execCommand(command);
+    } catch (err) {
+      console.error(`[ContextMenuV3] native ${command} failed`, err);
+    }
+  };
+  const handleUndo = () => onUndo ? onUndo() : runNativeEdit("undo");
+  const handleRedo = () => onRedo ? onRedo() : runNativeEdit("redo");
+  const compareContent = () => actionText.source === "selection" ? { content: actionText.text, label: "Selection" } : { content: actionText.text, label: "Current" };
+  const handleCompareClipboard = async () => {
+    const { content, label } = compareContent();
+    const clip = await kitReadText();
+    if (clip === null) {
+      toast({ title: "Couldn't read the clipboard", variant: "destructive" });
+      return;
+    }
+    if (!clip) {
+      toast({ title: "Clipboard is empty" });
+      return;
+    }
+    openDiffWindow({
+      original: content,
+      modified: clip,
+      originalLabel: label,
+      modifiedLabel: "Clipboard",
+      title: "Compare with clipboard",
+      engine: "light"
+    });
+  };
+  const handleSetCompareBase = () => {
+    const { content, label } = compareContent();
+    host.setCompareBase({ content, label, language: null });
+    toast({
+      title: "Set as compare base",
+      description: "Open another item and choose \u201CCompare with base\u201D."
+    });
+  };
+  const handleCompareWithBase = async () => {
+    const { content, label } = compareContent();
+    const opened = await host.openCompareWithBase({ current: content, currentLabel: label });
+    if (!opened) {
+      toast({
+        title: "No compare base set",
+        description: "Choose \u201CSet as compare base\u201D on another item first."
+      });
+    }
+  };
+  const launchWidgetHandleId = () => registerLaunchWidgetHandle(
+    widgetHandleId,
+    isEditable ? buildSelectionWriteBack({
+      originalText: actionText.text,
+      textSource: actionText.source,
+      selectionRange,
+      onTextReplace,
+      onTextInsertAfter,
+      insertAtCaret
+    }) : null
+  );
+  const handleShortcutExecute = async (entry) => {
+    if (!entry.agentId) {
+      toast({
+        title: "Agent Not Connected",
+        description: `"${entry.label}" has no connected agent. Configure it in the admin panel.`,
+        variant: "destructive"
+      });
+      return;
+    }
+    const resultDisplay = entry.displayMode ?? "modal-full";
+    try {
+      await launchShortcut(entry.id, scope, {
+        surfaceKey: `${sourceFeature}:${entry.id}`,
+        sourceFeature,
+        config: { displayMode: resultDisplay },
+        runtime: compact({
+          originalText: actionText.text,
+          surfaceName,
+          // Editable surfaces: let the agent stream widget_text_* edits
+          // straight into the surface, and give the person Replace / Insert
+          // below on the result (undefined on read-only — no tools).
+          widgetHandleId: launchWidgetHandleId()
+        })
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "An unknown error occurred";
+      toast({
+        title: "Execution Failed",
+        description: `${entry.label}: ${message}`,
+        variant: "destructive"
+      });
+    }
+  };
+  const handleBoundAgentExecute = async (entry) => {
+    try {
+      await launchAgent(entry.agentId, {
+        surfaceKey: `${sourceFeature}:bound-agent:${entry.agentId}`,
+        sourceFeature,
+        // Managed entries share the WindowPanel default. autoRun is deliberately
+        // absent so the safe open-and-wait default remains authoritative.
+        config: MANAGED_CONTEXT_MENU_AGENT_CONFIG,
+        runtime: compact({
+          applicationScope: scope,
+          originalText: actionText.text,
+          surfaceName,
+          widgetHandleId: launchWidgetHandleId()
+        })
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "An unknown error occurred";
+      toast({
+        title: "Execution Failed",
+        description: `${entry.name}: ${message}`,
+        variant: "destructive"
+      });
+    }
+  };
+  const insertTargets = { editorId, getTextarea, insertAtCaret, onTextReplace };
+  const handleContentBlockInsert = (entry) => {
+    const template = entry.template;
+    if (insertIntoEditor(insertTargets, template)) {
+      onContentInserted?.();
+      return;
+    }
+    void kitCopyText(template).then((copied) => {
+      if (copied) {
+        toast({
+          title: "Copied to clipboard",
+          description: `"${entry.label}" can't be inserted here \u2014 this surface isn't editable.`
+        });
+      } else {
+        getContextMenuHost().showManualCopy({ text: template });
+      }
+    });
+  };
+  const handleEntrySelect = (entry) => {
+    if (entry.entryType === "agent_shortcut") void handleShortcutExecute(entry);
+    else handleContentBlockInsert(entry);
+  };
+  const handleDelete = async () => {
+    if (!onDelete) return;
+    const ok = await getContextMenuHost().confirm({
+      title: "Delete this item?",
+      description: "This action cannot be undone.",
+      confirmLabel: "Delete",
+      variant: "destructive"
+    });
+    if (ok) onDelete();
+  };
+  const handleFind = () => {
+    props.suppressSelectionRestore();
+    openFindReplace({
+      getTargetElement: () => selectionRange?.type === "editable" ? selectionRange.element : null,
+      onReplace: onTextReplace
+    });
+  };
+  const canInsertReference = isEditable && hasEditorInsertTarget(insertTargets);
+  const copyReference = (pick) => {
+    void kitCopyText(pick.fence).then((copied) => {
+      if (copied) {
+        toast({
+          title: "Reference copied",
+          description: pick.title ? `Paste it anywhere to link "${pick.title}".` : "Paste it anywhere to render the link."
+        });
+      } else {
+        getContextMenuHost().showManualCopy({ text: pick.fence, title: "Copy the reference" });
+      }
+    });
+  };
+  const insertReference = (pick) => {
+    const inserted = insertIntoEditor(insertTargets, {
+      editor: `
+${pick.fence}
+`,
+      textarea: (field) => ownParagraph(pick.fence, field),
+      caret: pick.fence,
+      placement: "block"
+    });
+    if (inserted) {
+      onContentInserted?.();
+      return;
+    }
+    toast({
+      title: "Copied instead",
+      description: "Couldn't insert here. Paste it where you want it."
+    });
+    copyReference(pick);
+  };
+  const handleInsertReference = () => {
+    props.suppressSelectionRestore();
+    openReferencePicker({
+      mode: canInsertReference ? "insert" : "copy",
+      onPicked: (pick) => {
+        if (pick.delivery === "insert" && canInsertReference) insertReference(pick);
+        else copyReference(pick);
+      }
+    });
+  };
+  const handleAttach = () => {
+    if (!entity) return;
+    openContextAssignment({
+      subject: {
+        entityType: entity.type,
+        entityId: entity.id,
+        title: entity.title
+      }
+    });
+  };
+  const handleLinkRecord = () => {
+    if (!entity) return;
+    openLinkRecordSheet({ target: { token: entity.type, id: entity.id, title: entity.title } });
+  };
+  const handleShare = () => {
+    if (!entity?.resourceType) return;
+    openShareModalWindow({
+      resourceType: entity.resourceType,
+      resourceId: entity.id,
+      resourceName: entity.title
+    });
+  };
+  const { openSurfaceContextWindow, openBindAgent } = host;
+  const resolvedSurfaceName = surfaceName ?? detectActiveSurface();
+  const surfaceLabel = resolvedSurfaceName ? getSurfaceDisplayLabel(resolvedSurfaceName) : "This page";
+  const related = getRelatedSurfaces(resolvedSurfaceName);
+  const copyText = (text) => {
+    void kitCopyText(text).then((copied) => {
+      if (copied) toast({ title: "Copied", description: text });
+      else getContextMenuHost().showManualCopy({ text });
+    });
+  };
+  const surfaceAgentItems = [];
+  boundAgentSections.filter((section) => section.agents.length > 0).forEach((section, idx) => {
+    if (idx > 0)
+      surfaceAgentItems.push({ kind: "separator", id: `sa:${section.key}:sep` });
+    for (const agent of section.agents) {
+      surfaceAgentItems.push({
+        kind: "item",
+        id: `sa:${section.key}:${agent.agentId}`,
+        label: agent.name,
+        description: agent.organizationName ? `${section.label} \xB7 ${agent.organizationName}` : section.label,
+        icon: AGENT_ICON,
+        onSelect: () => void handleBoundAgentExecute(agent)
+      });
+    }
+  });
+  if (surfaceAgentItems.length > 0)
+    surfaceAgentItems.push({ kind: "separator", id: "sa:bind-sep" });
+  surfaceAgentItems.push({
+    kind: "item",
+    id: "sa:bind",
+    label: "Bind an agent to this page\u2026",
+    icon: Plus,
+    disabled: !resolvedSurfaceName,
+    onSelect: () => {
+      if (resolvedSurfaceName) openBindAgent({ surfaceName: resolvedSurfaceName });
+    }
+  });
+  const relatedItems = [
+    ...related.ancestry,
+    ...related.children
+  ].map((ref) => ({
+    kind: "item",
+    id: `sr:${ref.name}`,
+    label: ref.label,
+    description: `${ref.kind === "ancestor" ? "Parent" : "Child"} \xB7 ${ref.name}`,
+    icon: AppWindow,
+    onSelect: () => openSurfaceContextWindow({ surfaceName: ref.name, isEditable: false })
+  }));
+  const surfaceChildren = [
+    // The surface key is an engineer's handle — admin-only (cold walk 20),
+    // like the Agents panel's sub-line. Everyone else sees the label only.
+    ...isAdmin ? [
+      {
+        kind: "item",
+        id: "surface:location",
+        label: resolvedSurfaceName ?? "No surface registered for this page",
+        ...resolvedSurfaceName ? { description: "Surface location \xB7 click to copy" } : {},
+        icon: ClipboardCopy,
+        disabled: !resolvedSurfaceName,
+        onSelect: () => resolvedSurfaceName && copyText(resolvedSurfaceName)
+      },
+      { kind: "separator", id: "surface:sep1" }
+    ] : [],
+    {
+      kind: "item",
+      id: "surface:context",
+      label: "Surface Context",
+      description: "Live page values",
+      icon: Braces,
+      disabled: !resolvedSurfaceName,
+      onSelect: () => {
+        if (!resolvedSurfaceName) return;
+        openSurfaceContextWindow({
+          surfaceName: resolvedSurfaceName,
+          isEditable: Boolean(isEditable)
+        });
+      }
+    },
+    ...hasAdminPower ? [
+      {
+        kind: "item",
+        id: "surface:context-admin",
+        label: "Surface Context Admin",
+        description: "Contract, provenance & settings",
+        icon: ShieldCheck,
+        onSelect: () => openSurfaceInspector({
+          surfaceName: resolvedSurfaceName ?? null,
+          scope,
+          isEditable: Boolean(isEditable),
+          preferRuntime: true
+        })
+      }
+    ] : [],
+    { kind: "separator", id: "surface:sep2" },
+    {
+      kind: "submenu",
+      id: "surface:agents",
+      label: "Agents on this page",
+      icon: AGENT_ICON,
+      children: surfaceAgentItems
+    },
+    ...relatedItems.length > 0 ? [
+      {
+        kind: "submenu",
+        id: "surface:related",
+        label: "Related surfaces",
+        icon: Layers,
+        children: relatedItems
+      }
+    ] : [],
+    ...isAdmin ? [
+      { kind: "separator", id: "surface:sep3" },
+      {
+        kind: "item",
+        id: "surface:version",
+        label: `Menu v3.${types_exports.CANONICAL_MENU_VERSION_V3} \xB7 V${menuVersion}`,
+        description: "Menu revision \xB7 surface wiring version",
+        icon: Info,
+        onSelect: () => copyText(
+          `${resolvedSurfaceName ?? "(no surface)"} \xB7 v3.${types_exports.CANONICAL_MENU_VERSION_V3} \xB7 V${menuVersion}`
+        )
+      }
+    ] : []
+  ];
+  const surfaceSection = {
+    id: "surface-info",
+    items: [
+      {
+        kind: "submenu",
+        id: "surface",
+        label: surfaceLabel,
+        icon: AppWindow,
+        children: surfaceChildren
+      }
+    ]
+  };
+  const handleInspectValues = () => {
+    openSurfaceInspector({
+      surfaceName: surfaceName ?? null,
+      scope,
+      isEditable: Boolean(isEditable)
+    });
+  };
+  const handleInspectState = () => {
+    openStateViewer();
+  };
+  const handleToggleDebugMode = () => {
+    host.toggleDebugMode();
+  };
+  const handleToggleAdminIndicator = () => {
+    host.toggleAdminIndicator();
+  };
+  return {
+    scope,
+    actionText,
+    // A textarea/input, or a contenteditable field (chip / rich editor), names
+    // itself in the header — never "Content: {{reply.body}}".
+    fieldLabel: isEditable && selectionRange ? fieldLabelOf(selectionRange.element) : null,
+    jsonSection,
+    resolvedPlacementMode,
+    categoryGroups,
+    grouped: groupsByPlacement(categoryGroups),
+    loading,
+    librariesError,
+    boundAgentSections,
+    boundAgentsLoading,
+    boundAgentsError,
+    excludedRichActionIds,
+    retryLibraries: () => {
+      void refresh();
+      void refreshBoundAgents();
+    },
+    richDocCtx,
+    registryActions,
+    copyVariantActions,
+    exportActions,
+    convertActions,
+    hasCompareBase,
+    isAdmin,
+    isDebugMode,
+    isAdminIndicatorOpen,
+    canNativeUndo,
+    handleCopy,
+    handleSpeak,
+    handleSpokenSummary,
+    handleSpokenSummaryLive,
+    spokenSummaryAvailable: Boolean(spokenSummaryAgentId),
+    handleCut,
+    handlePaste,
+    handleSelectAll,
+    handleUndo,
+    handleRedo,
+    handleCompareClipboard,
+    handleSetCompareBase,
+    handleCompareWithBase,
+    handleShortcutExecute,
+    handleBoundAgentExecute,
+    handleContentBlockInsert,
+    handleEntrySelect,
+    handleDelete,
+    handleFind,
+    handleInsertReference,
+    handleAttach,
+    handleLinkRecord,
+    handleShare,
+    handleInspectValues,
+    handleInspectState,
+    handleToggleDebugMode,
+    handleToggleAdminIndicator,
+    quickActions,
+    surfaceSection
+  };
+}
+
+// src/engine/model/menu-model.ts
+import { hasEditInPlaceTarget, openEditInPlaceFromLastInteraction } from "@ai-matrx/rich-editor/in-place/EditInPlace";
+
+// src/engine/utils/key-combo.ts
+var MOD_ALIASES = {
+  alt: "alt",
+  option: "alt",
+  opt: "alt",
+  "\u2325": "alt",
+  shift: "shift",
+  "\u21E7": "shift",
+  ctrl: "ctrl",
+  control: "ctrl",
+  "\u2303": "ctrl",
+  cmd: "meta",
+  command: "meta",
+  meta: "meta",
+  "\u2318": "meta",
+  win: "meta",
+  mod: "mod"
+};
+function isApplePlatform() {
+  if (typeof navigator === "undefined") return false;
+  return /mac|iphone|ipad|ipod/i.test(navigator.platform || navigator.userAgent || "");
+}
+function parseKeyCombo(raw) {
+  if (!raw) return null;
+  const parts = raw.split(/\s*\+\s*/).map((p) => p.trim()).filter(Boolean);
+  if (parts.length < 2) return null;
+  const combo = { alt: false, shift: false, ctrl: false, meta: false, code: null, key: null };
+  const last = parts[parts.length - 1];
+  for (const part of parts.slice(0, -1)) {
+    const mod = MOD_ALIASES[part.toLowerCase()];
+    if (!mod) return null;
+    if (mod === "mod") combo[isApplePlatform() ? "meta" : "ctrl"] = true;
+    else combo[mod] = true;
+  }
+  if (/^[a-z]$/i.test(last)) combo.code = `Key${last.toUpperCase()}`;
+  else if (/^[0-9]$/.test(last)) combo.code = `Digit${last}`;
+  else combo.key = last.toLowerCase();
+  if (!combo.alt && !combo.ctrl && !combo.meta) return null;
+  if ((combo.ctrl || combo.meta) && combo.shift && !combo.alt && combo.code === "KeyK") return null;
+  return combo;
+}
+
+// src/engine/model/menu-model.ts
+import {
+  StickyNote,
+  CheckSquare,
+  MessageSquare,
+  Database,
+  FolderOpen,
+  Zap,
+  Scissors,
+  Pencil,
+  Copy,
+  Clipboard,
+  Type,
+  Undo2,
+  Redo2,
+  History,
+  GitCompareArrows,
+  Pin,
+  Shield,
+  Eye,
+  EyeOff,
+  Save,
+  Trash2,
+  Mic,
+  Download,
+  Replace,
+  Search,
+  Share2,
+  Link,
+  Link2,
+  AtSign,
+  Bug,
+  Braces as Braces2,
+  Volume2,
+  Headphones,
+  AudioLines,
+  RotateCcw
+} from "lucide-react";
+import { PLACEMENT_TYPES as PLACEMENT_TYPES2 } from "@ai-matrx/chat/agents/shortcuts/constants";
+import {
+  AI_SUBMENU_LABEL,
+  buildMenuTree,
+  withAiSlot
+} from "@ai-matrx/rich-content/rich-document/variants/shared/menuStructure";
+import { AGENT_ICON as AGENT_ICON2 } from "@ai-matrx/icons/domain";
+function withEditInPlace(sections) {
+  if (!hasEditInPlaceTarget()) return sections;
+  const edit = {
+    kind: "item",
+    id: "edit-in-place",
+    label: "Edit",
+    icon: Pencil,
+    iconClassName: "text-muted-foreground",
+    onSelect: () => void openEditInPlaceFromLastInteraction()
+  };
+  return [{ id: "edit-in-place", group: "editable", nodes: [edit] }, ...sections];
+}
+function compactNodes(nodes) {
+  return nodes.filter((node) => node !== null);
+}
+function fromExtraItem(item) {
+  const id = `x:${item.id}`;
+  switch (item.kind) {
+    case "separator":
+      return { kind: "separator", id };
+    case "submenu":
+      return {
+        kind: "submenu",
+        id,
+        label: item.label,
+        icon: item.icon,
+        disabled: item.disabled,
+        children: item.children.map(fromExtraItem)
+      };
+    case "checkbox":
+      return {
+        kind: "checkbox",
+        id,
+        label: item.label,
+        icon: item.icon,
+        description: item.description,
+        hint: item.hint,
+        checked: item.checked,
+        disabled: item.disabled,
+        onCheckedChange: item.onCheckedChange
+      };
+    case "link":
+      return {
+        kind: "link",
+        id,
+        label: item.label,
+        icon: item.icon,
+        description: item.description,
+        hint: item.hint,
+        href: item.href,
+        target: item.target,
+        disabled: item.disabled
+      };
+    case "item":
+    default:
+      return {
+        kind: "item",
+        id,
+        label: item.label,
+        icon: item.icon,
+        description: item.description,
+        hint: item.hint,
+        disabled: item.disabled,
+        destructive: item.destructive,
+        onSelect: item.onSelect
+      };
+  }
+}
+function extrasByAnchor(extraSections) {
+  const out = {
+    "after-clipboard": [],
+    "after-compare": [],
+    "after-placements": []
+  };
+  for (const s of extraSections ?? []) {
+    const anchor = s.anchor ?? "after-compare";
+    out[anchor].push({
+      id: `extra:${s.id}`,
+      group: "surface",
+      label: s.label,
+      icon: s.icon,
+      primary: s.primary === true ? true : void 0,
+      nodes: s.items.map(fromExtraItem)
+    });
+  }
+  return out;
+}
+function liftPrimarySections(sections) {
+  const primary = sections.filter((s) => s.primary);
+  if (primary.length === 0) return sections;
+  return [...primary, ...sections.filter((s) => !s.primary)];
+}
+function richActionNode(action, ctx) {
+  const { label, disabled } = resolveRichActionView(action, ctx);
+  return {
+    kind: "item",
+    id: `rich:${action.id}`,
+    label,
+    icon: action.icon,
+    iconClassName: action.iconColor ?? void 0,
+    disabled,
+    onSelect: () => void action.run(ctx)
+  };
+}
+function registryTreeNodes(actions, ctx, aiExtras) {
+  const tree = buildMenuTree(actions, { aiSlot: aiExtras.length > 0 });
+  const nodes = tree.topLevel.map((a) => richActionNode(a, ctx));
+  for (const sub of withAiSlot(tree.submenus, aiExtras.length > 0)) {
+    const children = sub.actions.map((a) => richActionNode(a, ctx));
+    const isAi = sub.label === AI_SUBMENU_LABEL;
+    if (isAi && aiExtras.length > 0) {
+      if (children.length > 0) children.push({ kind: "separator", id: "rich-ai:sep" });
+      children.push(...aiExtras);
+    }
+    nodes.push({
+      kind: "submenu",
+      id: `rich-sub:${sub.label.toLowerCase().replace(/[^a-z0-9]+/g, "-")}`,
+      label: sub.label,
+      icon: sub.icon,
+      width: isAi ? "w-64" : void 0,
+      children
+    });
+  }
+  nodes.push(...tree.extras.map((a) => richActionNode(a, ctx)));
+  return nodes;
+}
+function categoryGroupNode(group, m) {
+  const { category, items, children } = group;
+  const children_ = items.map((entry) => {
+    const isDisabled = entry.entryType === "agent_shortcut" && !entry.agentId;
+    const hint = (
+      // Advertised only when the shell's key listener can run it (key-combo.ts).
+      entry.entryType === "agent_shortcut" && entry.keyboardShortcut && parseKeyCombo(entry.keyboardShortcut) ? entry.keyboardShortcut : isDisabled ? "Not configured" : void 0
+    );
+    return {
+      kind: "item",
+      id: `entry:${entry.id}`,
+      label: entry.label,
+      icon: resolveIcon(entry.iconName),
+      // Phase 6.7: there is no "legacy match" row any more. Availability is
+      // derived (requirement-gate.ts) — an item either QUALIFIES here or is
+      // absent. Nothing renders red to advertise a backfill backlog.
+      hint,
+      disabled: isDisabled,
+      onSelect: () => m.handleEntrySelect(entry)
+    };
+  });
+  if (children.length > 0) {
+    if (items.length > 0) children_.push({ kind: "separator", id: `${category.id}:sep` });
+    for (const child of children) children_.push(categoryGroupNode(child, m));
+  }
+  return {
+    kind: "submenu",
+    id: `cat:${category.id}`,
+    label: category.label,
+    icon: resolveIcon(category.iconName),
+    iconStyle: { color: category.color || "currentColor" },
+    disabled: items.length === 0 && children.length === 0,
+    emptyLabel: `No items in ${category.label}`,
+    width: "w-64",
+    children: children_
+  };
+}
+function placementNode(placementType, m) {
+  const mode = m.resolvedPlacementMode[placementType];
+  if (mode === "hide") return null;
+  const groups = m.grouped[placementType] || [];
+  const hasCategories = groups.length > 0;
+  const label = getPlacementLabel(placementType);
+  const color = PLACEMENT_COLOR[placementType];
+  if (!hasCategories && m.librariesError && mode !== "disable") {
+    return failedLibraryNode(`placement:${placementType}`, label, getPlacementIcon(placementType), m, placementType);
+  }
+  return {
+    kind: "submenu",
+    id: `placement:${placementType}`,
+    label,
+    icon: getPlacementIcon(placementType),
+    iconStyle: color ? { color } : void 0,
+    disabled: mode === "disable" || !hasCategories,
+    loading: m.loading && !hasCategories,
+    emptyLabel: `No ${label}`,
+    width: "w-64",
+    placement: placementType,
+    children: groups.map((g) => categoryGroupNode(g, m))
+  };
+}
+function failedLibraryNode(id, label, icon2, m, placement) {
+  return {
+    kind: "submenu",
+    id,
+    label,
+    icon: icon2,
+    width: "w-64",
+    placement,
+    children: [
+      {
+        kind: "item",
+        id: `${id}:retry`,
+        label: "Couldn't load. Retry",
+        icon: RotateCcw,
+        keepsMenuOpen: true,
+        onSelect: m.retryLibraries
+      }
+    ]
+  };
+}
+function boundAgentsNode(m) {
+  const mode = m.resolvedPlacementMode["bound-agent"];
+  if (mode === "hide") return null;
+  const sections = m.boundAgentSections.filter((s) => s.agents.length > 0);
+  const hasAgents = sections.length > 0;
+  if (!hasAgents && m.boundAgentsError && !m.boundAgentsLoading && mode !== "disable") {
+    return failedLibraryNode("placement:bound-agent", "Agents", AGENT_ICON2, m, "bound-agent");
+  }
+  const children = [];
+  sections.forEach((section, idx) => {
+    if (idx > 0) children.push({ kind: "separator", id: `agents:${section.key}:sep` });
+    children.push({
+      kind: "label",
+      id: `agents:${section.key}:label`,
+      label: section.label.toUpperCase()
+    });
+    for (const agent of section.agents) {
+      children.push({
+        kind: "item",
+        id: `agent:${section.key}:${agent.agentId}`,
+        label: agent.name,
+        icon: AGENT_ICON2,
+        iconClassName: "text-indigo-500/80",
+        onSelect: () => void m.handleBoundAgentExecute(agent)
+      });
+    }
+  });
+  return {
+    kind: "submenu",
+    id: "placement:bound-agent",
+    label: "Agents",
+    icon: AGENT_ICON2,
+    iconClassName: "text-indigo-500",
+    disabled: mode === "disable" || !hasAgents && !m.boundAgentsLoading,
+    loading: m.boundAgentsLoading,
+    emptyLabel: m.boundAgentsLoading && !hasAgents ? "Loading\u2026" : "No agents available",
+    width: "w-64",
+    placement: "bound-agent",
+    children
+  };
+}
+function buildMenuModel(m, props) {
+  const {
+    extraSections,
+    isEditable,
+    onSave,
+    onDelete,
+    onUndo,
+    onRedo,
+    canUndo,
+    canRedo,
+    undoHint,
+    redoHint,
+    onViewHistory,
+    hasHistory,
+    selectedText,
+    entity,
+    selectionRange,
+    getTextarea,
+    recordActionsOnly = false
+  } = props;
+  const { actionText, quickActions } = m;
+  const header = actionText.source === "selection" ? { label: "Selected", text: actionText.text } : actionText.source === "content" ? { label: "Content", text: actionText.text } : null;
+  const copy = {
+    kind: "item",
+    id: "copy",
+    label: "Copy",
+    icon: Copy,
+    iconClassName: "text-emerald-500",
+    disabled: actionText.source === "none",
+    onSelect: () => void m.handleCopy()
+  };
+  const speak = {
+    kind: "item",
+    id: "speak",
+    label: "Speak",
+    icon: Volume2,
+    iconClassName: "text-sky-500",
+    disabled: actionText.source === "none",
+    onSelect: m.handleSpeak
+  };
+  const listenDisabled = actionText.source === "none" || !m.spokenSummaryAvailable;
+  const hasRegistry = m.registryActions.length > 0;
+  const spokenSummary = {
+    kind: "item",
+    id: "spoken-summary",
+    label: "Summarize without playing",
+    icon: Headphones,
+    iconClassName: "text-violet-500",
+    disabled: listenDisabled,
+    onSelect: m.handleSpokenSummary
+  };
+  const spokenSummaryLive = {
+    kind: "item",
+    id: "spoken-summary-live",
+    label: "Summarize & listen",
+    icon: AudioLines,
+    iconClassName: "text-violet-500",
+    disabled: listenDisabled,
+    onSelect: m.handleSpokenSummaryLive
+  };
+  const listen = hasRegistry ? null : {
+    kind: "submenu",
+    id: "listen",
+    label: "Listen",
+    icon: Headphones,
+    iconClassName: "text-violet-500",
+    disabled: listenDisabled,
+    children: [spokenSummary, spokenSummaryLive]
+  };
+  const copyAs = !hasRegistry && m.copyVariantActions.length > 0 ? {
+    kind: "submenu",
+    id: "copy-as",
+    label: "Copy as",
+    icon: Copy,
+    iconClassName: "text-emerald-500",
+    children: m.copyVariantActions.map((a) => richActionNode(a, m.richDocCtx))
+  } : null;
+  const json = m.jsonSection ? {
+    kind: "submenu",
+    id: "json",
+    label: jsonSectionLabel(m.jsonSection),
+    icon: Braces2,
+    iconClassName: "text-amber-500",
+    width: "w-72",
+    children: m.jsonSection.actions.map((action) => ({
+      kind: "item",
+      id: `json:${action.id}`,
+      label: action.label,
+      hint: action.hint,
+      disabled: action.disabled,
+      onSelect: () => void action.run()
+    }))
+  } : null;
+  const cut = {
+    kind: "item",
+    id: "cut",
+    label: "Cut",
+    icon: Scissors,
+    iconClassName: "text-emerald-500",
+    disabled: !isEditable || !selectedText,
+    onSelect: () => void m.handleCut()
+  };
+  const paste = {
+    kind: "item",
+    id: "paste",
+    label: "Paste",
+    icon: Clipboard,
+    iconClassName: "text-emerald-500",
+    disabled: !isEditable,
+    onSelect: () => void m.handlePaste()
+  };
+  const selectAll = {
+    kind: "item",
+    id: "select-all",
+    label: "Select All",
+    icon: Type,
+    iconClassName: "text-muted-foreground",
+    // Select All acts on a captured selection's container, or an editable
+    // surface's own field. With neither (right-click on a table row or on
+    // read-only content without selecting) it would do nothing — a dead row,
+    // so it is absent (R1 b), not offered.
+    disabled: !selectionRange && !(isEditable && getTextarea),
+    onSelect: m.handleSelectAll
+  };
+  const find = {
+    kind: "item",
+    id: "find",
+    label: "Find & Replace",
+    icon: Search,
+    iconClassName: "text-muted-foreground",
+    onSelect: m.handleFind
+  };
+  const insertReference = {
+    kind: "item",
+    id: "insert-reference",
+    label: isEditable ? "Insert reference\u2026" : "Copy reference\u2026",
+    icon: AtSign,
+    iconClassName: "text-primary",
+    onSelect: m.handleInsertReference
+  };
+  const chat = {
+    kind: "item",
+    id: "chat",
+    label: "Chat",
+    icon: MessageSquare,
+    iconClassName: "text-primary",
+    onSelect: () => quickActions.openChatWindow()
+  };
+  const undo = {
+    kind: "item",
+    id: "undo",
+    label: "Undo",
+    icon: Undo2,
+    iconClassName: "text-sky-500",
+    hint: undoHint,
+    disabled: onUndo ? !canUndo : !m.canNativeUndo,
+    onSelect: m.handleUndo
+  };
+  const redo = {
+    kind: "item",
+    id: "redo",
+    label: "Redo",
+    icon: Redo2,
+    iconClassName: "text-sky-500",
+    hint: redoHint,
+    disabled: onRedo ? !canRedo : !m.canNativeUndo,
+    onSelect: m.handleRedo
+  };
+  const viewHistory = {
+    kind: "item",
+    id: "view-history",
+    label: "View History",
+    icon: History,
+    iconClassName: "text-violet-500",
+    disabled: !onViewHistory || !hasHistory,
+    onSelect: () => onViewHistory?.()
+  };
+  const compare = hasRegistry ? null : {
+    kind: "submenu",
+    id: "compare",
+    label: "Compare",
+    icon: GitCompareArrows,
+    iconClassName: "text-amber-500",
+    children: [
+      {
+        kind: "item",
+        id: "compare:clipboard",
+        label: "Compare with clipboard",
+        icon: Clipboard,
+        onSelect: () => void m.handleCompareClipboard()
+      },
+      {
+        kind: "item",
+        id: "compare:set-base",
+        label: "Set as compare base",
+        icon: Pin,
+        description: actionText.source === "selection" ? "Use selection" : "Use content",
+        onSelect: m.handleSetCompareBase
+      },
+      {
+        kind: "item",
+        id: "compare:with-base",
+        label: "Compare with base",
+        icon: GitCompareArrows,
+        description: m.hasCompareBase ? void 0 : "No base set yet",
+        disabled: !m.hasCompareBase,
+        onSelect: () => void m.handleCompareWithBase()
+      }
+    ]
+  };
+  const exportMenu = !hasRegistry && m.exportActions.length > 0 ? {
+    kind: "submenu",
+    id: "export",
+    label: "Export",
+    icon: Download,
+    iconClassName: "text-amber-500",
+    children: m.exportActions.map((a) => richActionNode(a, m.richDocCtx))
+  } : null;
+  const convert = !hasRegistry && m.convertActions.length > 0 ? {
+    kind: "submenu",
+    id: "convert",
+    label: "Convert",
+    icon: Replace,
+    iconClassName: "text-violet-500",
+    children: m.convertActions.map((a) => richActionNode(a, m.richDocCtx))
+  } : null;
+  const attach = entity ? {
+    kind: "item",
+    id: "attach",
+    label: "Attach To",
+    icon: Link2,
+    iconClassName: "text-sky-500",
+    onSelect: m.handleAttach
+  } : null;
+  const linkRecord = entity ? {
+    kind: "item",
+    id: "link-record",
+    label: "Link a record\u2026",
+    icon: Link,
+    iconClassName: "text-sky-500",
+    onSelect: m.handleLinkRecord
+  } : null;
+  const share = entity?.resourceType ? {
+    kind: "item",
+    id: "share",
+    label: "Share",
+    icon: Share2,
+    iconClassName: "text-emerald-500",
+    onSelect: m.handleShare
+  } : null;
+  const libraryNodes = [
+    placementNode(PLACEMENT_TYPES2.AI_ACTION, m),
+    boundAgentsNode(m),
+    placementNode(PLACEMENT_TYPES2.CONTENT_BLOCK, m),
+    placementNode(PLACEMENT_TYPES2.USER_TOOL, m),
+    placementNode(PLACEMENT_TYPES2.ORGANIZATION_TOOL, m)
+  ].filter((n) => n !== null);
+  const registry = hasRegistry ? registryTreeNodes(m.registryActions, m.richDocCtx, libraryNodes) : null;
+  const placements = hasRegistry ? [] : libraryNodes;
+  const quickMode = m.resolvedPlacementMode["quick-action"];
+  const quick = quickMode === "hide" ? null : {
+    kind: "submenu",
+    id: "quick-actions",
+    label: "Quick Actions",
+    icon: Zap,
+    iconClassName: "text-pink-500",
+    disabled: quickMode === "disable",
+    width: "w-56",
+    children: [
+      { kind: "item", id: "qa:notes", label: "Notes", icon: StickyNote, onSelect: () => quickActions.openQuickNotes() },
+      { kind: "item", id: "qa:tasks", label: "Tasks", icon: CheckSquare, onSelect: () => quickActions.openQuickTasks() },
+      { kind: "item", id: "qa:chat", label: "Chat", icon: MessageSquare, onSelect: () => quickActions.openQuickChat() },
+      { kind: "item", id: "qa:data", label: "Data", icon: Database, onSelect: () => quickActions.openQuickData() },
+      { kind: "item", id: "qa:files", label: "Files", icon: FolderOpen, onSelect: () => quickActions.openQuickFiles() },
+      { kind: "item", id: "qa:voice", label: "Voice Input", icon: Mic, onSelect: () => quickActions.openVoicePad() }
+    ]
+  };
+  const save = isEditable && onSave ? {
+    kind: "item",
+    id: "save",
+    label: "Save",
+    icon: Save,
+    iconClassName: "text-emerald-500",
+    onSelect: () => onSave()
+  } : null;
+  const del = isEditable && onDelete ? {
+    kind: "item",
+    id: "delete",
+    label: "Delete",
+    icon: Trash2,
+    destructive: true,
+    onSelect: () => void m.handleDelete()
+  } : null;
+  const admin = m.isAdmin ? {
+    kind: "submenu",
+    id: "admin",
+    label: "Admin Tools",
+    icon: Shield,
+    iconClassName: "text-rose-500",
+    width: "w-56",
+    children: [
+      {
+        kind: "item",
+        id: "admin:debug",
+        label: `${m.isDebugMode ? "Disable" : "Enable"} Debug Mode`,
+        icon: m.isDebugMode ? EyeOff : Eye,
+        iconClassName: m.isDebugMode ? "text-amber-600 dark:text-amber-400" : void 0,
+        onSelect: m.handleToggleDebugMode
+      },
+      {
+        kind: "item",
+        id: "admin:values",
+        label: "Context Values",
+        icon: Bug,
+        className: "text-amber-600 dark:text-amber-400",
+        onSelect: m.handleInspectValues
+      },
+      ...m.isDebugMode ? [
+        {
+          kind: "item",
+          id: "admin:state",
+          label: "Redux State",
+          icon: Database,
+          className: "text-amber-600 dark:text-amber-400",
+          onSelect: m.handleInspectState
+        }
+      ] : [],
+      { kind: "separator", id: "admin:sep" },
+      {
+        kind: "item",
+        id: "admin:indicator",
+        label: `${m.isAdminIndicatorOpen ? "Hide" : "Show"} Admin Indicator`,
+        icon: m.isAdminIndicatorOpen ? Eye : EyeOff,
+        iconClassName: m.isAdminIndicatorOpen ? "text-green-600 dark:text-green-400" : void 0,
+        onSelect: m.handleToggleAdminIndicator
+      }
+    ]
+  } : null;
+  const extras = extrasByAnchor(extraSections);
+  const surfaceInfo = {
+    id: "surface-info",
+    group: "surface-info",
+    nodes: m.surfaceSection.items.map(fromExtraItem)
+  };
+  if (recordActionsOnly) {
+    const recordSections = [];
+    const recordHasDocument = hasRegistry && m.richDocCtx?.source?.type !== "raw";
+    const clipboardRecord = compactNodes([recordHasDocument ? copy : null, recordHasDocument ? copyAs : null, recordHasDocument ? json : null]);
+    if (clipboardRecord.length > 0) {
+      recordSections.push({ id: "clipboard", group: "clipboard", nodes: clipboardRecord });
+    }
+    if (registry && recordHasDocument) recordSections.push({ id: "registry", group: "document", nodes: registry });
+    recordSections.push(...extras["after-clipboard"]);
+    if (recordHasDocument && (exportMenu || convert)) {
+      recordSections.push({ id: "document-out", group: "document", nodes: compactNodes([exportMenu, convert]) });
+    }
+    if (attach || linkRecord || share) {
+      recordSections.push({ id: "share", group: "share", nodes: compactNodes([attach, linkRecord, share]) });
+    }
+    recordSections.push(...extras["after-compare"]);
+    recordSections.push(...extras["after-placements"]);
+    if (save || del) recordSections.push({ id: "editable", group: "editable", nodes: compactNodes([save, del]) });
+    if (admin) recordSections.push({ id: "admin", group: "admin", nodes: [admin] });
+    recordSections.push(surfaceInfo);
+    return {
+      header,
+      sections: withEditInPlace(liftPrimarySections(recordSections)),
+      roles: {
+        copy,
+        speak,
+        listen: null,
+        copyAs,
+        json,
+        cut,
+        paste,
+        selectAll,
+        find,
+        insertReference,
+        chat,
+        undo,
+        redo,
+        viewHistory,
+        compare: null,
+        exportMenu,
+        convert,
+        attach,
+        linkRecord,
+        share,
+        placements: [],
+        registry,
+        quickActions: null,
+        save,
+        del,
+        admin,
+        extras,
+        surfaceInfo
+      }
+    };
+  }
+  const sections = [];
+  sections.push({
+    id: "clipboard",
+    group: "clipboard",
+    nodes: compactNodes([
+      copy,
+      speak,
+      listen,
+      copyAs,
+      json,
+      cut,
+      paste,
+      selectAll,
+      find,
+      insertReference
+    ])
+  });
+  if (registry) sections.push({ id: "registry", group: "document", nodes: registry });
+  sections.push(...extras["after-clipboard"]);
+  sections.push({ id: "tools", group: "tools", nodes: [chat] });
+  sections.push({
+    id: "history",
+    group: "history",
+    nodes: compactNodes([undo, redo, viewHistory])
+  });
+  if (compare) sections.push({ id: "compare", group: "tools", nodes: [compare] });
+  if (exportMenu || convert) {
+    sections.push({ id: "document-out", group: "document", nodes: compactNodes([exportMenu, convert]) });
+  }
+  if (attach || linkRecord || share) {
+    sections.push({ id: "share", group: "share", nodes: compactNodes([attach, linkRecord, share]) });
+  }
+  sections.push(...extras["after-compare"]);
+  if (placements.length > 0) sections.push({ id: "placements", group: "ai", nodes: placements });
+  sections.push(...extras["after-placements"]);
+  if (quick) {
+    sections.push({
+      id: "quick",
+      group: "quick",
+      joinPrevious: extras["after-placements"].length === 0,
+      nodes: [quick]
+    });
+  }
+  if (save || del) {
+    sections.push({
+      id: "editable",
+      group: "editable",
+      nodes: compactNodes([save, del])
+    });
+  }
+  if (admin) sections.push({ id: "admin", group: "admin", nodes: [admin] });
+  sections.push(surfaceInfo);
+  return {
+    header,
+    sections: withEditInPlace(liftPrimarySections(sections)),
+    roles: {
+      copy,
+      speak,
+      listen,
+      copyAs,
+      json,
+      cut,
+      paste,
+      selectAll,
+      find,
+      insertReference,
+      chat,
+      undo,
+      redo,
+      viewHistory,
+      compare,
+      exportMenu,
+      convert,
+      attach,
+      linkRecord,
+      share,
+      placements,
+      registry,
+      quickActions: quick,
+      save,
+      del,
+      admin,
+      extras,
+      surfaceInfo
+    }
+  };
+}
+
+// src/engine/alchemy-provider.ts
+import { registerAlchemyIcon } from "@ai-matrx/rich-content/utils/alchemy-icon-keys";
+import { stripTurnTrust } from "@ai-matrx/chat/agents/conversation-export/turn-trust-strip";
+import { markdownToPlainText } from "@ai-matrx/content-ir/source";
+function contextMenuHostOf(target) {
+  const host = target.host;
+  if (!host) return null;
+  if (host.kind === "context-menu" && typeof host.instanceId === "string") {
+    return host;
+  }
+  return host.contextMenu ?? null;
+}
+var VERBS = {
+  copy: { verb: "copy", sentence: "Select text, or right-click content, to copy it." },
+  cut: { verb: "cut", sentence: "Cut works on selected text in an editable field." },
+  paste: { verb: "paste", sentence: "Paste works in an editable field." },
+  undo: { verb: "undo", sentence: "Nothing to undo here." },
+  redo: { verb: "redo", sentence: "Nothing to redo here." },
+  find: { verb: "find", sentence: "Find works where there is text." }
+};
+var EDIT_ONLY_VERBS = /* @__PURE__ */ new Set(["cut", "paste", "undo", "redo"]);
+var CATEGORY_OF = {
+  clipboard: "clipboard",
+  tools: "app",
+  history: "history",
+  share: "share",
+  document: "save",
+  surface: "edit",
+  ai: "ai",
+  quick: "feedback",
+  editable: "edit",
+  admin: "admin",
+  "surface-info": "surface-info"
+};
+var NON_VERB_CLIPBOARD = {
+  "select-all": "edit",
+  "insert-reference": "edit"
+};
+var INSERTS_CONTENT = /* @__PURE__ */ new Set(["placement:content-block"]);
+function findNodeById(nodes, id) {
+  for (const n of nodes) {
+    if (n.id === id) return n;
+    if (n.kind === "submenu") {
+      const hit = findNodeById(n.children, id);
+      if (hit) return hit;
+    }
+  }
+  return null;
+}
+var available = { status: "available" };
+var absent = { status: "absent" };
+function icon(node) {
+  return node.icon ? registerAlchemyIcon(node.icon) : void 0;
+}
+function startGroup(a) {
+  Object.assign(a, { startsGroup: true });
+}
+function toAction(node, place, instanceId, opts = {}) {
+  if (node.kind === "separator" || node.kind === "label") return null;
+  const id = `cm:${node.id}`;
+  const own = (t) => contextMenuHostOf(t)?.instanceId === instanceId;
+  const base = {
+    id,
+    label: node.label,
+    category: place.category,
+    order: place.order,
+    ...place.section ? { section: place.section } : {},
+    .../* @__PURE__ */ ((key) => key ? { icon: key } : {})(icon(node)),
+    ..."iconClassName" in node && node.iconClassName ? { iconTone: node.iconClassName } : {},
+    ..."description" in node && node.description ? { description: node.description } : {},
+    ..."hint" in node && node.hint ? { hint: node.hint } : {}
+  };
+  if (node.kind === "submenu") {
+    const inserts = INSERTS_CONTENT.has(node.id);
+    return {
+      ...base,
+      // Still loading at the source: every layout shows "Loading…" on the row.
+      pending: () => Boolean(node.loading),
+      eligible: (t) => {
+        if (!own(t)) return absent;
+        if (inserts && (t.readOnly || opts.editable === false)) return absent;
+        if (node.loading) return available;
+        return !node.disabled && hasRows(node.children) ? available : absent;
+      },
+      expand: async (t) => {
+        let current = node;
+        for (let i = 0; current.kind === "submenu" && current.loading && opts.nextModel && i < 20; i++) {
+          const next = await opts.nextModel();
+          const found = next.sections.map((s) => findNodeById(s.nodes, node.id)).find(Boolean);
+          if (!found) return [];
+          current = found;
+        }
+        if (current.kind !== "submenu") return [];
+        void t;
+        const rows = [];
+        let startsNext = false;
+        for (const child of current.children) {
+          if (child.kind === "separator") {
+            startsNext = rows.length > 0;
+            continue;
+          }
+          if (unusable(child)) continue;
+          const a = toAction(child, { ...place, section: void 0, order: rows.length }, instanceId, opts);
+          if (!a) continue;
+          if (startsNext) startGroup(a);
+          startsNext = false;
+          rows.push(a);
+        }
+        return rows;
+      },
+      run: () => void 0
+    };
+  }
+  if (node.kind === "link") {
+    return { ...base, href: node.href, eligible: (t) => own(t) && !node.disabled ? available : absent, run: () => void 0 };
+  }
+  if (node.kind === "checkbox") {
+    return {
+      ...base,
+      toggle: true,
+      pressed: () => node.checked,
+      eligible: (t) => own(t) && !node.disabled ? available : absent,
+      run: () => node.onCheckedChange(!node.checked)
+    };
+  }
+  const verb = place.category === "clipboard" ? VERBS[node.id] : void 0;
+  return {
+    ...base,
+    ...verb ? { verb: verb.verb } : {},
+    ...node.destructive ? { destructive: true } : {},
+    ...node.keepsMenuOpen ? { keepsMenuOpen: true } : {},
+    eligible: (t) => {
+      if (!own(t)) return absent;
+      if (!node.disabled) return available;
+      if (verb && (t.readOnly || opts.editable === false) && EDIT_ONLY_VERBS.has(verb.verb)) return absent;
+      if (verb) return { status: "unavailable-verb", verb: verb.verb, sentence: verb.sentence };
+      const reason = "description" in node && typeof node.description === "string" ? node.description.trim() : "";
+      return reason ? { status: "unavailable", sentence: reason } : absent;
+    },
+    run: () => node.onSelect()
+  };
+}
+function unusable(node) {
+  if (node.kind === "separator" || node.kind === "label") return false;
+  if (node.kind === "submenu") return !node.loading && (Boolean(node.disabled) || !hasRows(node.children));
+  if (!("disabled" in node) || !node.disabled) return false;
+  return !("description" in node && typeof node.description === "string" && node.description.trim());
+}
+function hasRows(nodes) {
+  return nodes.some((n) => n.kind === "submenu" ? n.loading || hasRows(n.children) : n.kind !== "separator" && n.kind !== "label");
+}
+function contextMenuActionsFromModel(model, instanceId, opts = {}) {
+  const out = [];
+  model.sections.forEach((section, sectionIndex) => {
+    const base = sectionIndex * 100;
+    if (section.id === "registry") {
+      section.nodes.forEach((node, i) => {
+        if (node.kind !== "submenu" || !node.id.startsWith("rich-sub:")) return;
+        const libraries = node.children.filter((c) => !c.id.startsWith("rich") && c.kind !== "separator");
+        libraries.forEach((lib, j) => {
+          const a = toAction(
+            lib,
+            {
+              category: "ai",
+              order: 5e3 + i * 50 + j
+            },
+            instanceId,
+            opts
+          );
+          if (a) out.push(a);
+        });
+      });
+      return;
+    }
+    const named = section.group === "history" ? { id: "cm-history", label: "History" } : section.label ? {
+      id: `cm-${section.id}`,
+      label: section.label,
+      ...section.primary ? { primary: true } : {},
+      // A surface section's label is the clicked thing's own name.
+      ...section.group === "surface" ? { kind: "target" } : {}
+    } : void 0;
+    let groupStarts = false;
+    section.nodes.forEach((node, i) => {
+      if (node.kind === "separator") {
+        groupStarts = true;
+        return;
+      }
+      const category = section.group === "clipboard" ? NON_VERB_CLIPBOARD[node.id] ?? "clipboard" : CATEGORY_OF[section.group];
+      const isHistoryVerb = section.group === "history" && (node.id === "undo" || node.id === "redo");
+      const a = toAction(
+        node,
+        {
+          category: isHistoryVerb ? "clipboard" : category,
+          ...named && !isHistoryVerb ? { section: named } : {},
+          order: base + i
+        },
+        instanceId,
+        opts
+      );
+      if (a) {
+        if (groupStarts) startGroup(a);
+        groupStarts = false;
+        out.push(a);
+      }
+    });
+  });
+  return out;
+}
+function contextMenuProvider(instanceId, actions) {
+  return {
+    id: `context-menu:${instanceId}`,
+    tier: "T1",
+    actions: (target) => contextMenuHostOf(target)?.instanceId === instanceId ? actions() : []
+  };
+}
+function modelRevision(model) {
+  const walk = (nodes) => nodes.map(
+    (n) => n.kind === "submenu" ? `${n.id}${n.disabled ? "!" : ""}${n.loading ? "~" : ""}[${walk(n.children)}]` : `${n.id}${"disabled" in n && n.disabled ? "!" : ""}${n.kind === "checkbox" && n.checked ? "*" : ""}${"label" in n ? `:${n.label}` : ""}`
+  ).join(",");
+  return model.sections.map((s) => `${s.id}(${walk(s.nodes)})`).join("|");
+}
+function menuHeaderContent(actionText) {
+  if (actionText.source === "none") return null;
+  return headerPreview(stripTurnTrust(actionText.text));
+}
+function chatMessageSubject(args) {
+  const { state, source, extensions, contextData } = args;
+  const read = (conversationId, messageId) => typeof conversationId === "string" && typeof messageId === "string" ? state.messages?.byConversationId?.[conversationId]?.byId?.[messageId] : void 0;
+  if (source?.type === "chat-message") {
+    const record2 = read(source.conversationId, source.messageId);
+    const role = record2?.role ?? (extensions?.type === "chat-message" ? extensions.role : null);
+    return role ? { role: String(role), createdAt: record2?.createdAt ?? null } : null;
+  }
+  const record = read(contextData?.conversationId, contextData?.messageId);
+  return record?.role ? { role: String(record.role), createdAt: record.createdAt ?? null } : null;
+}
+function menuHeader(actionText, fieldLabel, message) {
+  if (message && actionText.source !== "selection" && actionText.source !== "none") {
+    const who = message.role === "user" ? "Your message" : message.role === "assistant" ? "AI answer" : "Message";
+    const at = message.createdAt ? new Date(message.createdAt) : null;
+    const when = at && !Number.isNaN(at.getTime()) ? ` \xB7 ${at.toLocaleString(void 0, { month: "short", day: "numeric", hour: "numeric", minute: "2-digit" })}` : "";
+    return { content: "", contentLabel: `${who}${when}` };
+  }
+  if (fieldLabel && actionText.source !== "selection") {
+    return { content: fieldPreview(headerPreview(stripTurnTrust(actionText.text))), contentLabel: fieldLabel };
+  }
+  return { content: menuHeaderContent(actionText), contentLabel: null };
+}
+function headerPreview(text) {
+  const blocks = text.replace(/^\s{0,3}(?:```|~~~).*$/gm, "").replace(/^\s{0,3}#{1,6}\s+/gm, "").replace(/^\s{0,3}>\s?/gm, "").replace(/^\s{0,3}(?:[-*+]|\d+[.)])\s+(?:\[[ xX]\]\s+)?/gm, "");
+  return markdownToPlainText(blocks).replace(/\s*\n+\s*/g, " ").trim();
+}
+function namedHeader(heading, actionText) {
+  if (!heading || actionText.source === "selection") return null;
+  return { content: heading.text, contentLabel: heading.label };
+}
+function menuEngineRevision(drawn, header) {
+  return `${drawn}\0${header.contentLabel ?? ""}\0${header.content ?? ""}`;
+}
+
+// src/engine/regroup/RegroupContext.tsx
+import * as React from "react";
+import { AlchemyActionsProvider, useAlchemyActions } from "@ai-matrx/alchemy/react/host";
+
+// src/engine/regroup/grouping.ts
+import {
+  buildMenuModel as buildMenuModel2,
+  context as arrangeContext
+} from "@ai-matrx/alchemy/menu";
+var REGROUP_ID_PREFIX = "regroup:";
+function actionLabel(action, target) {
+  try {
+    return typeof action.label === "function" ? action.label(target) : action.label;
+  } catch {
+    return action.id;
+  }
+}
+function isPageOwn(action) {
+  const section = action.section;
+  return Boolean(section && (section.primary || section.kind === "target"));
+}
+function labelOf(action, target) {
+  if (typeof action.label === "string") return action.label;
+  return target ? actionLabel(action, target) : "";
+}
+function ruleMatches(rule, action, target) {
+  const w = rule.when;
+  if (w.pageOwnLabels && isPageOwn(action)) {
+    const label = labelOf(action, target);
+    if (label && w.pageOwnLabels.some((p) => new RegExp(p, "i").test(label))) return true;
+  }
+  if (w.ids?.includes(action.id)) return true;
+  if (w.idPrefixes?.some((p) => action.id.startsWith(p))) return true;
+  if (w.categories?.includes(action.category)) return true;
+  if (w.pageOwn && isPageOwn(action)) return true;
+  return false;
+}
+function matchRule(grouping, action, target) {
+  return grouping.rules.find((r) => ruleMatches(r, action, target)) ?? null;
+}
+function destinationFor(grouping, action, target) {
+  return matchRule(grouping, action, target)?.to ?? grouping.fallback;
+}
+var sameName = (label) => label.toLowerCase().replace(/[….]+$/g, "").replace(/\s+/g, " ").trim();
+function drawnOrder(model) {
+  const order = /* @__PURE__ */ new Map();
+  const walk = (nodes) => {
+    for (const n of nodes) {
+      if (!order.has(n.id)) order.set(n.id, order.size);
+      if (n.kind === "submenu") walk(n.children);
+    }
+  };
+  for (const s of model.sections) walk(s.nodes);
+  return order;
+}
+function currentModel(target, resolved) {
+  return buildMenuModel2(target, resolved, { headingPolicy: "inline" });
+}
+function regroupResolved(target, resolved, grouping, options) {
+  const order = drawnOrder(currentModel(target, resolved));
+  const pos = (r) => order.get(r.action.id) ?? Number.MAX_SAFE_INTEGER;
+  const groupDef = new Map(grouping.groups.map((g) => [g.key, g]));
+  const top = [];
+  const home = /* @__PURE__ */ new Map();
+  const wanted = /* @__PURE__ */ new Map();
+  const present = new Map(resolved.map((r) => [r.action.id, r]));
+  const twinOf = (r) => {
+    const rule = matchRule(grouping, r.action, target);
+    for (const id of rule?.mergeWithIds ?? []) {
+      const twin = present.get(id);
+      if (twin && twin !== r) return twin;
+    }
+    return null;
+  };
+  const mergedInto = /* @__PURE__ */ new Map();
+  const pageVersionOf = /* @__PURE__ */ new Map();
+  for (const r of resolved) {
+    if (r.action.expand) continue;
+    const twin = twinOf(r);
+    if (!twin || pageVersionOf.has(twin.action.id)) continue;
+    mergedInto.set(r.action.id, twin);
+    pageVersionOf.set(twin.action.id, r);
+  }
+  const withPageHandler = (r) => {
+    const page = pageVersionOf.get(r.action.id);
+    if (!page) return r;
+    const { href: _generalHref, ...general } = r.action;
+    void _generalHref;
+    const action = {
+      ...general,
+      run: page.action.run,
+      ...page.action.href !== void 0 ? { href: page.action.href } : {}
+    };
+    return { ...r, action };
+  };
+  for (const original of resolved) {
+    if (mergedInto.has(original.action.id)) continue;
+    const r = withPageHandler(original);
+    const to = destinationFor(grouping, r.action, target);
+    if (to.kind === "group" && groupDef.has(to.key)) {
+      if (r.eligibility.status !== "available") {
+        top.push(r);
+        home.set(r.action.id, { kind: "top", note: "greyed here, so it stays visible with its reason" });
+        continue;
+      }
+      const list = wanted.get(to.key) ?? [];
+      list.push(r);
+      wanted.set(to.key, list);
+      continue;
+    }
+    if (to.kind === "page-first") {
+      const section = r.action.section;
+      top.push(
+        section ? { ...r, action: { ...r.action, section: { ...section, primary: true } } } : r
+      );
+      home.set(r.action.id, { kind: "page-first" });
+      continue;
+    }
+    top.push(r);
+    home.set(r.action.id, { kind: "top" });
+  }
+  const members = /* @__PURE__ */ new Map();
+  const groupActions = [];
+  for (const def of grouping.groups) {
+    const list = (wanted.get(def.key) ?? []).slice().sort((a, b) => pos(a) - pos(b));
+    if (list.length === 0) continue;
+    if (list.length < grouping.minMembers) {
+      for (const r of list) {
+        top.push(r);
+        home.set(r.action.id, { kind: "top", note: `the only row for ${def.label}` });
+      }
+      continue;
+    }
+    const kept = [];
+    const byName = /* @__PURE__ */ new Map();
+    for (const r of list) {
+      const name = sameName(actionLabel(r.action, target));
+      const first = options.mergeSameName ? byName.get(name) : void 0;
+      if (first) {
+        home.set(r.action.id, {
+          kind: "merged",
+          intoId: first.action.id,
+          intoLabel: actionLabel(first.action, target),
+          groupLabel: def.label
+        });
+        continue;
+      }
+      byName.set(name, r);
+      kept.push(r);
+      home.set(r.action.id, { kind: "group", key: def.key, label: def.label });
+    }
+    members.set(def.key, kept);
+    const children = kept.map((r) => r.action);
+    const submenu = {
+      id: `${REGROUP_ID_PREFIX}${def.key}`,
+      label: def.label,
+      category: def.category,
+      order: def.order,
+      ...def.icon ? { icon: def.icon } : {},
+      // Still loading at the source when any member is.
+      pending: (t) => children.some((c) => Boolean(c.expand && c.pending?.(t))),
+      eligible: () => ({ status: "available" }),
+      expand: async () => children,
+      run: () => void 0
+    };
+    groupActions.push({ action: submenu, eligibility: { status: "available" } });
+  }
+  for (const [id, twin] of mergedInto) {
+    const at = home.get(twin.action.id);
+    home.set(id, {
+      kind: "merged",
+      intoId: twin.action.id,
+      intoLabel: actionLabel(twin.action, target),
+      groupLabel: at?.kind === "group" ? at.label : at?.kind === "merged" ? at.groupLabel : "",
+      pageActionKept: true
+    });
+  }
+  return { resolved: [...top, ...groupActions], members, home };
+}
+
+// src/engine/regroup/RegroupContext.tsx
+import { jsx } from "react/jsx-runtime";
+var MenuRegroupContext = React.createContext(null);
+function regroupingRegistry(inner, first) {
+  let inputs = first;
+  const read = () => inputs;
+  return {
+    update(next) {
+      inputs = next;
+    },
+    register: (provider) => inner.register(provider),
+    providers: () => inner.providers(),
+    subscribe: (listener) => inner.subscribe(listener),
+    // By-id lookup (alchemy 0.12): regrouping changes how a menu is arranged, never which Action an id names.
+    get: (id, target) => inner.get(id, target),
+    async resolve(target, restrict) {
+      const list = await inner.resolve(target, restrict);
+      const { value, arrangement, close } = read();
+      if (!value) return list;
+      value.onResolved?.({ target, resolved: list, arrangement }, close);
+      if (value.transform) return value.transform(target, list);
+      if (!value.grouping) return list;
+      return regroupResolved(target, list, value.grouping, { mergeSameName: value.mergeSameName }).resolved;
+    }
+  };
+}
+function RegroupBoundary({
+  arrangement,
+  close,
+  children
+}) {
+  const value = React.useContext(MenuRegroupContext);
+  const { registry, ports } = useAlchemyActions();
+  const [view] = React.useState(
+    () => value ? regroupingRegistry(registry, { value, arrangement, close }) : null
+  );
+  React.useLayoutEffect(() => {
+    view?.update({ value, arrangement, close });
+  });
+  if (!view) return children;
+  return /* @__PURE__ */ jsx(AlchemyActionsProvider, { ports, registry: view, children });
+}
+
+// src/engine/components/AlchemyMenuContent.tsx
+import { jsx as jsx2 } from "react/jsx-runtime";
+var EDITOR_ONLY_RICH_IDS = /* @__PURE__ */ new Set([
+  "compare-with-clipboard",
+  "set-compare-base",
+  "compare-with-base",
+  "conversation-find"
+]);
+function editorOnlyRichActionIds(actions) {
+  return actions.filter((a) => a.category === "listen" || EDITOR_ONLY_RICH_IDS.has(a.id)).map((a) => a.id);
+}
+function AlchemyMenuContent(props) {
+  const { mode, point, open, onOpenChange, ...menuProps } = props;
+  const m = useContextMenuActions(menuProps);
+  const model = buildMenuModel(m, menuProps);
+  const { registry } = useAlchemyActions2();
+  useRichDocumentProvider();
+  const instanceId = React2.useId();
+  const waitersRef = React2.useRef([]);
+  const nextModel = () => new Promise((resolve) => waitersRef.current.push(resolve));
+  const actionsRef = React2.useRef(contextMenuActionsFromModel(model, instanceId, { nextModel, editable: Boolean(menuProps.isEditable) }));
+  const drawnRef = React2.useRef("");
+  const drawn = modelRevision(model);
+  React2.useLayoutEffect(() => {
+    actionsRef.current = contextMenuActionsFromModel(model, instanceId, { nextModel, editable: Boolean(menuProps.isEditable) });
+    if (drawnRef.current !== drawn) {
+      drawnRef.current = drawn;
+      const waiters = waitersRef.current;
+      waitersRef.current = [];
+      for (const wake of waiters) wake(model);
+    }
+  });
+  React2.useEffect(
+    () => registry.register(contextMenuProvider(instanceId, () => actionsRef.current)),
+    [registry, instanceId]
+  );
+  const hasRichDocument = m.registryActions.length > 0 && !(menuProps.recordActionsOnly && m.richDocCtx.source.type === "raw");
+  const sourceWritable = hasRichDocument && !m.richDocCtx.source.readOnly && (Boolean(m.richDocCtx.sourceAdapter.edit) || Boolean(menuProps.isEditable));
+  const makeTarget = (withRich) => createClickTarget({
+    // The declared item under the pointer (a table row), as itemSources resolved it.
+    item: menuProps.item ?? null,
+    readOnly: hasRichDocument ? !sourceWritable : !menuProps.isEditable,
+    writable: sourceWritable ? [SOURCE_WRITE_TARGET] : [],
+    // The strip's Copy IS the registry's one-tap copy here — one row, not two.
+    excludedActionIds: [
+      ...m.excludedRichActionIds,
+      ...hasRichDocument ? ["copy"] : [],
+      ...menuProps.recordActionsOnly ? editorOnlyRichActionIds(m.registryActions) : []
+    ],
+    organizationId: m.richDocCtx.organizationId,
+    auth: {
+      authenticated: m.richDocCtx.isAuthenticated,
+      admin: m.richDocCtx.isAdmin,
+      creator: m.richDocCtx.isCreator
+    },
+    selection: menuProps.selectedText ? {
+      text: menuProps.selectedText,
+      type: menuProps.selectionRange?.type ?? "non-editable",
+      start: menuProps.selectionRange?.start ?? 0,
+      end: menuProps.selectionRange?.end ?? 0,
+      handle: menuProps.selectionRange
+    } : null,
+    payloadKinds: ["markdown"],
+    host: {
+      contextMenu: { kind: "context-menu", instanceId },
+      ...hasRichDocument && withRich ? {
+        richDocument: richDocumentTargetHost(m.richDocCtx, {
+          extra: menuProps.extraRichActions ?? []
+        })
+      } : {}
+    }
+  });
+  const [target] = React2.useState(() => makeTarget(true));
+  const chatMessage = chatMessageSubject({
+    state: m.richDocCtx.getState(),
+    source: m.richDocCtx.source,
+    ...compact({
+      extensions: m.richDocCtx.extensions,
+      contextData: menuProps.contextData
+    })
+  });
+  const { content, contentLabel } = namedHeader(menuProps.heading, m.actionText) ?? menuHeader(m.actionText, m.fieldLabel, chatMessage);
+  const revision = menuEngineRevision(drawn, { content, contentLabel });
+  const engine = { revision, content, contentLabel };
+  const close = () => onOpenChange(false);
+  const regroup = React2.useContext(MenuRegroupContext);
+  const panelLook = { size: regroup?.size ?? "standard", hideHeader: regroup?.hideHeader ?? false };
+  if (mode === "sheet") {
+    return /* @__PURE__ */ jsx2(RegroupBoundary, { arrangement: menuProps.menuLayout, close, children: /* @__PURE__ */ jsx2(ActionSheet, { ...engine, target, open, onOpenChange }) });
+  }
+  if (mode === "palette") {
+    return /* @__PURE__ */ jsx2(RegroupBoundary, { arrangement: menuProps.menuLayout, close, children: /* @__PURE__ */ jsx2(ActionPalette, { ...engine, target, open, onOpenChange }) });
+  }
+  return /* @__PURE__ */ jsx2(RegroupBoundary, { arrangement: menuProps.menuLayout, close, children: /* @__PURE__ */ jsx2(
+    ContextMenuPanel,
+    {
+      ...engine,
+      target,
+      point,
+      open,
+      onOpenChange,
+      arrangement: menuProps.menuLayout,
+      density: menuProps.menuDensity,
+      ...compact({ subjectFold: menuProps.subjectFold }),
+      ...panelLook
+    }
+  ) });
+}
+
+// src/engine/components/ShortcutKeyRunner.tsx
+import { useEffect as useEffect3, useRef as useRef2 } from "react";
+function findShortcut(groups, id) {
+  for (const group of groups) {
+    for (const item of group.items) {
+      if (item.entryType === "agent_shortcut" && item.id === id) return item;
+    }
+    const nested = findShortcut(group.children, id);
+    if (nested) return nested;
+  }
+  return null;
+}
+function ShortcutKeyRunner(props) {
+  const { shortcutId, shortcutLabel, onDone, ...menuProps } = props;
+  const m = useContextMenuActions(menuProps);
+  const ran = useRef2(false);
+  useEffect3(() => {
+    if (ran.current || m.loading) return;
+    ran.current = true;
+    const entry = findShortcut(m.categoryGroups, shortcutId);
+    if (!entry) {
+      toast({
+        title: m.librariesError ? `Couldn't load ${shortcutLabel}` : `${shortcutLabel} isn't available here`,
+        ...m.librariesError ? { variant: "destructive" } : {}
+      });
+      onDone();
+      return;
+    }
+    void m.handleShortcutExecute(entry).finally(onDone);
+  });
+  return null;
+}
+export {
+  AlchemyMenuContent,
+  ShortcutKeyRunner,
+  editorOnlyRichActionIds
+};
+//# sourceMappingURL=menu-content.js.map