@ai-matrx/context-menu 0.0.0 → 0.1.0

package/dist/engine.d.cts

@@ -0,0 +1,731 @@
+import './host-types-AOiEYwR8.cjs';
+import { ExtraSectionAnchor, MenuContentProps, ResolvedContextMenuContext, ContextMenuExtraSection, ContextMenuEntityRef } from '@ai-matrx/chat/context-menu/types';
+export * from '@ai-matrx/chat/context-menu/types';
+import { C as ContextMenuActions, M as MenuGrouping } from './grouping-CGcWsltu.cjs';
+export { A as AuditRow, B as BuildJsonMenuActionsParams, a as CompareBaseInput, b as ContextAssignmentOptions, c as ContextMenuHost, d as ContextMenuHostBindings, e as ContextMenuQuickActions, D as DEFAULT_CONTEXT_MENU_HOST, f as DiffWindowOptions, g as DocumentAgentReviewProps, F as FindReplaceOptions, G as GroupingDestination, h as GroupingRule, I as InertMenuDiagnostic, J as JsonMenuAction, i as JsonMenuSection, L as LinkRecordSheetOptions, j as ListenSummaryWindowOptions, k as ManualCopyOptions, l as MenuGroupDef, P as ProposedHome, R as REGROUP_ID_PREFIX, m as ReferencePick, n as ReferencePickerOptions, o as RegroupAudit, p as RegroupOptions, q as RegroupResult, r as ResolveScopeArgs, s as ResolvedActionText, S as ShareModalOptions, t as SurfaceAgentBindOptions, u as SurfaceContextWindowOptions, v as SurfaceInspectorOptions, w as actionLabel, x as auditRegroup, y as auditSurfaceScope, z as buildJsonMenuSection, E as configureContextMenuHost, H as currentModel, K as destinationFor, N as detectInertMenu, O as drawnPlaces, Q as getContextMenuHost, T as hasActionableContent, U as jsonSectionLabel, V as matchRule, W as regroupResolved, X as reportMenuDiagnostics, Y as resetContextMenuHost, Z as resolveActionText, _ as resolveApplicationScope, $ as topLevelRowCount, a0 as useContextMenuHostBindings } from './grouping-CGcWsltu.cjs';
+export * from '@ai-matrx/chat/context-menu/utils/build-application-scope';
+export * from '@ai-matrx/chat/context-menu/utils/availability';
+import { SelectionRange } from '@ai-matrx/chat/context-menu/utils/selection-tracking';
+export * from '@ai-matrx/chat/context-menu/utils/selection-tracking';
+export * from '@ai-matrx/chat/context-menu/utils/menu-deadline';
+export * from '@ai-matrx/chat/context-menu/utils/resolveMarkdownContext';
+export * from '@ai-matrx/chat/context-menu/model/requirement-gate';
+import React__default from 'react';
+import { IconComponentType } from '@ai-matrx/icons';
+import { RichDocumentAction, RichDocumentActionContext, ContentSource, ContentSourceAdapter } from '@ai-matrx/rich-content/rich-document/types';
+import { ResolvedItem } from '@ai-matrx/alchemy/declare';
+import { MatrxDataTableRecordControls } from '@ai-matrx/design-system/data-table/types';
+import { MatrxTableMenuPayload, MatrxTableMenuTarget } from '@ai-matrx/design-system/data-table/menu-targets';
+import { ActionCategory, ClickTarget, ResolvedAction, Action, ActionProvider } from '@ai-matrx/alchemy/actions';
+import { WidgetHandle, SelectionWriteBack } from '@ai-matrx/chat/agents/types/widget-handle.types';
+import { ApplicationScope } from '@ai-matrx/chat/agents/types/scope.types';
+import { ItemMenuConfig } from '@ai-matrx/design-system/item';
+import 'lucide-react';
+import '@ai-matrx/chat/surfaces/types';
+import '@ai-matrx/chat/agents/redux/agent-shortcuts/skl-types';
+import '@ai-matrx/kit/confirm-opener';
+import '@ai-matrx/chat/agents/redux/agent-shortcuts/types';
+import '@ai-matrx/chat/agents/redux/agent-shortcut-categories/types';
+import '@ai-matrx/chat/agents/redux/shared/scope';
+import '@ai-matrx/chat/surfaces/services/surface-bound-agents.service';
+import '@ai-matrx/kit/json-format';
+import '@ai-matrx/alchemy/menu';
+
+/**
+ * Opens the canonical context menu from an explicit overflow control.
+ *
+ * Touch surfaces cannot rely on a discoverable right-click. Dispatching the
+ * same bubbling event keeps the overflow button on the exact desktop/mobile
+ * ContextMenuV3 path instead of creating a second action menu.
+ */
+declare function openContextMenuForElement(element: HTMLElement | null): void;
+
+interface MenuNodeBase {
+    id: string;
+}
+interface MenuItemNode extends MenuNodeBase {
+    kind: "item";
+    label: string;
+    icon?: IconComponentType | undefined;
+    /** Tailwind classes for the icon (colour). */
+    iconClassName?: string | undefined;
+    /** Inline style for the icon (data-driven category colours). */
+    iconStyle?: React__default.CSSProperties | undefined;
+    /** Second muted line. */
+    description?: string | undefined;
+    /** Right-aligned muted hint (shortcut, count, …). */
+    hint?: string | undefined;
+    /** Native tooltip. */
+    title?: string | undefined;
+    disabled?: boolean | undefined;
+    destructive?: boolean | undefined;
+    /** Extra classes on the row (admin amber, …). */
+    className?: string | undefined;
+    /** Running it reloads this menu's own rows (Retry): the menu stays open (alchemy `keepsMenuOpen`). */
+    keepsMenuOpen?: boolean | undefined;
+    onSelect: () => void;
+}
+interface MenuSubmenuNode extends MenuNodeBase {
+    kind: "submenu";
+    label: string;
+    icon?: IconComponentType | undefined;
+    iconClassName?: string | undefined;
+    iconStyle?: React__default.CSSProperties | undefined;
+    disabled?: boolean | undefined;
+    /** Spinner in the trigger while the data loads. */
+    loading?: boolean | undefined;
+    /** Rendered centred when `children` has no actionable node. */
+    emptyLabel?: string | undefined;
+    /** Tailwind width class for the panel. Default `w-60`. */
+    width?: string | undefined;
+    /** Layout hint: which placement this submenu is (for re-grouping). */
+    placement?: string | undefined;
+    children: MenuNode[];
+}
+interface MenuCheckboxNode extends MenuNodeBase {
+    kind: "checkbox";
+    label: string;
+    icon?: IconComponentType | undefined;
+    description?: string | undefined;
+    hint?: string | undefined;
+    checked: boolean;
+    disabled?: boolean | undefined;
+    onCheckedChange: (next: boolean) => void;
+}
+interface MenuLinkNode extends MenuNodeBase {
+    kind: "link";
+    label: string;
+    icon?: IconComponentType | undefined;
+    description?: string | undefined;
+    hint?: string | undefined;
+    href: string;
+    target?: string | undefined;
+    disabled?: boolean | undefined;
+}
+interface MenuLabelNode extends MenuNodeBase {
+    kind: "label";
+    label: string;
+}
+interface MenuSeparatorNode extends MenuNodeBase {
+    kind: "separator";
+}
+type MenuNode = MenuItemNode | MenuSubmenuNode | MenuCheckboxNode | MenuLinkNode | MenuLabelNode | MenuSeparatorNode;
+/** Actionable leaf kinds (what a filter can match and run). */
+type MenuLeafNode = MenuItemNode | MenuCheckboxNode | MenuLinkNode;
+/**
+ * Coarse group a section belongs to. Layouts regroup by this, never by id
+ * string-matching, so a surface's `extraSections` ("surface") and the
+ * data-driven placements ("ai") stay distinguishable from the core verbs.
+ */
+type MenuGroup = "clipboard" | "tools" | "history" | "share" | "document" | "surface" | "ai" | "quick" | "editable" | "admin" | "surface-info";
+interface MenuSection {
+    id: string;
+    group: MenuGroup;
+    /** Muted heading rendered above the section (surface sections). */
+    label?: string | undefined;
+    /** Icon for the fold a layout may collapse this section into (any className-drawn icon, like nodes). */
+    icon?: IconComponentType | undefined;
+    /** Classic rendering: no separator between this and the previous section. */
+    joinPrevious?: boolean | undefined;
+    /** The clicked target's section — see `ContextMenuExtraSection.primary`. */
+    primary?: boolean | undefined;
+    nodes: MenuNode[];
+}
+interface MenuHeader {
+    label: "Selected" | "Content";
+    text: string;
+}
+interface MenuModel {
+    header: MenuHeader | null;
+    /** Classic order — exactly the historical top-to-bottom arrangement. */
+    sections: MenuSection[];
+    /** Well-known nodes layouts pull out by role (never by label). */
+    roles: MenuRoles;
+}
+/** The nodes a layout needs to address individually. */
+interface MenuRoles {
+    copy: MenuItemNode;
+    speak: MenuItemNode;
+    /** ONE slot: "Listen" submenu — Summarize without playing / Summarize & listen. */
+    listen: MenuSubmenuNode | null;
+    copyAs: MenuSubmenuNode | null;
+    json: MenuSubmenuNode | null;
+    cut: MenuItemNode;
+    paste: MenuItemNode;
+    selectAll: MenuItemNode;
+    find: MenuItemNode;
+    /** "Insert reference…" (editable) / "Copy reference…" (read-only) — never absent. */
+    insertReference: MenuItemNode;
+    chat: MenuItemNode;
+    undo: MenuItemNode;
+    redo: MenuItemNode;
+    viewHistory: MenuItemNode;
+    compare: MenuSubmenuNode | null;
+    exportMenu: MenuSubmenuNode | null;
+    convert: MenuSubmenuNode | null;
+    attach: MenuItemNode | null;
+    /** "Link a record…" — present on EVERY menu that targets a record (guard: every-record-menu-links-a-record). */
+    linkRecord: MenuItemNode | null;
+    share: MenuItemNode | null;
+    placements: MenuSubmenuNode[];
+    /**
+     * THE ONE REGISTRY TREE (RC-B6): the same tree, in the same order, as the
+     * ⋯ menu, ProTextarea's "…" and the mobile sheet — with the agent-shortcut
+     * libraries folded into its AI submenu. `null` when there is no content.
+     */
+    registry: MenuNode[] | null;
+    quickActions: MenuSubmenuNode | null;
+    save: MenuItemNode | null;
+    del: MenuItemNode | null;
+    admin: MenuSubmenuNode | null;
+    /** The engine-built surface submenu section (location / context / agents / related). */
+    surfaceInfo: MenuSection;
+    /** Surface `extraSections`, by anchor, already converted to model nodes. */
+    extras: Record<ExtraSectionAnchor, MenuSection[]>;
+}
+/** Does the subtree contain anything the user can act on? */
+declare function hasActionable(nodes: MenuNode[]): boolean;
+/**
+ * Classic order, with the clicked target's section lifted to the very top.
+ * Stable: everything else keeps the anchor order it was assembled in.
+ */
+declare function liftPrimarySections(sections: MenuSection[]): MenuSection[];
+/**
+ * The registry tree as model nodes — `buildMenuTree` (the ONE structure every
+ * host renders), with `aiExtras` (the agent-shortcut libraries) folded into
+ * its AI submenu. Ids are the registry ids behind a `rich:` prefix, which is
+ * what the one-tree guard compares against the ⋯ menu.
+ */
+declare function registryTreeNodes(actions: RichDocumentAction[], ctx: ContextMenuActions["richDocCtx"], aiExtras: MenuNode[]): MenuNode[];
+declare function buildMenuModel(m: ContextMenuActions, props: Pick<MenuContentProps, "extraSections" | "isEditable" | "onSave" | "onDelete" | "onUndo" | "onRedo" | "canUndo" | "canRedo" | "undoHint" | "redoHint" | "onViewHistory" | "hasHistory" | "selectedText" | "entity" | "getTextarea"> & Partial<Pick<MenuContentProps, "selectionRange" | "recordActionsOnly">>): MenuModel;
+
+interface TableRowMenuDescriptor {
+    context: ResolvedContextMenuContext;
+    extraSections: ContextMenuExtraSection[];
+}
+declare function createTableRowMenuDescriptor(descriptor: TableRowMenuDescriptor): object;
+/** Exactly the row commands the default menu renders. Nothing else is read. */
+type TableRowEditCommands = Pick<MatrxDataTableRecordControls, "beginEdit" | "saveEdits" | "cancelEdits">;
+/**
+ * The table hands its host the row's controls as `unknown` — it never
+ * interprets what the host builds from them — so they are READ here, one
+ * command at a time. A command the table did not send, or sent as something
+ * that cannot be called, is simply not offered rather than rendered dead.
+ */
+declare function tableRowEditCommands(controls: unknown): TableRowEditCommands;
+/**
+ * The host's generic menu model: complete current row data plus the
+ * table-owned edit commands.
+ *
+ * The table asks this for whichever of its five right-click LEVELS was aimed
+ * at. Only the row has a generic menu here, so every other level answers
+ * `null` and the table leaves that level to the surface that owns it.
+ */
+declare function createDefaultTableRowMenuDescriptor(payload: MatrxTableMenuPayload): object | null;
+/** Reusable base for a domain menu that keeps the shared row edit controls. */
+declare function buildDefaultTableRowMenuDescriptor(row: unknown, controls: TableRowEditCommands): TableRowMenuDescriptor;
+/**
+ * The canonical table registers ONE item source per mounted instance, under its table id. The table
+ * answers which of its right-click LEVELS was aimed at (`MatrxTableMenuTarget`); the source turns
+ * that answer into the declared `table_row` item, with the row's menu as its host data.
+ */
+declare function registerTableRowContextResolver(tableId: string, resolve: (target: MatrxTableMenuTarget) => unknown): () => void;
+/** The clicked row as its declared item (raw-free) and the menu its table built for it. */
+interface TableRowItemHit {
+    item: ResolvedItem;
+    menu: TableRowMenuDescriptor;
+}
+declare function resolveTableRowItem(target: HTMLElement | null): TableRowItemHit | null;
+/** The row's menu, or null when the click was not on a canonical table's row. */
+declare function resolveTableRowMenuDescriptor(target: HTMLElement | null): TableRowMenuDescriptor | null;
+/** The row's record name: the first data cell (not a tick box, star or button cell) with words. */
+declare function rowRecordName(row: HTMLElement | null | undefined): string;
+
+interface InventoryRow {
+    id: string;
+    label: string;
+    category: ActionCategory;
+}
+declare const CONTEXT_MENU_ENGINE_ROWS: readonly InventoryRow[];
+/** Engine rows whose ids are generated per library (one per agent category or placement). */
+declare const CONTEXT_MENU_ENGINE_ID_PREFIXES: readonly string[];
+
+declare const PROPOSED_MENU_GROUPING: MenuGrouping;
+
+/**
+ * A RECORD'S ROWS, IN THE ONE MENU OF THE CONTENT THAT SHOWS IT (R26; ALC-15 round 5).
+ *
+ * A record's toolbar can live apart from the content it belongs to: on /notes the tab strip holds the
+ * note's ⋯ (Save, Duplicate, Move, Delete, Close tab…) while the note's content is drawn in the pane
+ * below. The ⋯ and a right-click on that content target the SAME thing — the note — so they must be
+ * one menu (measured 2026-09-27: 27 rows from the tab's ⋯, 25 from the content, each missing the
+ * other's rows).
+ *
+ *   · The owner of the rows registers them under a key: `registerRecordMenu(key, get)`.
+ *   · The host marks the content's root with `data-record-menu="<key>"`.
+ *   · Every menu opened inside that root carries the registered sections (and the record's entity,
+ *     when the menu has none of its own) — the shell reads them at open (ContextMenuV3).
+ *   · The record's ⋯ calls `openRecordMenu(key, button)`: it opens the content's OWN menu at the
+ *     button. `false` = that content is not on screen; the caller opens its own menu instead.
+ *
+ * Plain data, no React.
+ */
+
+declare const RECORD_MENU_ATTR = "data-record-menu";
+interface RecordMenuRows {
+    entity?: ContextMenuEntityRef | null | undefined;
+    extraSections: ContextMenuExtraSection[];
+    /**
+     * The record's own name for the menu header ("Note · Clinic intake
+     * checklist") — used when the clicked content names nothing itself, so the
+     * header names the record instead of quoting its body. A selection still wins.
+     */
+    heading?: {
+        label: string;
+        text: string;
+    } | null;
+}
+/** The owner of registered rows says they changed (its record was renamed). */
+declare function recordMenuChanged(): void;
+/** For `useSyncExternalStore`: re-render when any registered record changes. */
+declare function subscribeRecordMenus(listener: () => void): () => void;
+declare function recordMenusRevision(): number;
+/** Register the rows a record contributes; returns the unregister. Read at every open, so always current. */
+declare function registerRecordMenu(key: string, get: () => RecordMenuRows): () => void;
+/** The rows of the record whose content holds `target` (nearest marked root), or null. */
+declare function resolveRecordMenu(target: Element | null): RecordMenuRows | null;
+/**
+ * Open the record content's own menu at `anchor` (a ⋯ button). Returns false when no content for
+ * `key` is on screen, so the caller can open its own menu instead.
+ */
+declare function openRecordMenu(key: string, anchor: HTMLElement): boolean;
+
+declare const STRIP_MAX = 6;
+declare const OWN_ROWS_MAX = 4;
+type ClickedKind = "thing" | "editable" | "text";
+declare function clickedKind(target: ClickTarget, resolved: readonly ResolvedAction[]): ClickedKind;
+interface ProposedOptions {
+    /** The clicked thing's name for "More <noun> options" ("table", "quiz", "note"). */
+    noun: string;
+}
+declare function proposedArrangement(target: ClickTarget, resolved: readonly ResolvedAction[], { noun }: ProposedOptions): ResolvedAction[];
+
+interface WhereTheMenuIs {
+    /** The rich-document source type (`note`, `task`, `chat-message`, `raw`, …). */
+    sourceType: string;
+    /** The registry surface the menu belongs to. */
+    surfaceName?: string | null | undefined;
+    /** The menu wraps an editor (EditableContextMenu). */
+    isEditable: boolean;
+}
+declare function actionsAlreadyHere(where: WhereTheMenuIs): string[];
+
+/**
+ * The effective entity for ONE menu open.
+ *
+ *   key absent  → the menu-level prop stands (single-entity surfaces unchanged)
+ *   key present → that row's entity wins
+ *   key `null`  → this target has no entity, so the entity-bound actions hide
+ *                 rather than target the wrong record
+ *
+ * A malformed value (no string `type` + `id`) is treated as absent and SCREAMS
+ * in dev — a half-built entity would render an Attach that writes a broken edge.
+ */
+declare function resolveEffectiveEntity(entityProp: ContextMenuEntityRef | undefined, resolved: ResolvedContextMenuContext | null): ContextMenuEntityRef | undefined;
+/**
+ * The effective `contextData` for one open: static payload + per-target merge,
+ * with the reserved entity key stripped so it never lands in the
+ * `ApplicationScope` as a value.
+ */
+declare function mergeResolvedContextData(contextData: Record<string, unknown> | undefined, resolved: ResolvedContextMenuContext | null): Record<string, unknown>;
+/**
+ * The context for ONE open on a table row: the table's own row descriptor
+ * (table-row-item.ts) JOINED with the surface's `resolveContextOnOpen` answer.
+ *
+ * 🚨 WHY (2026-10-03, CHAIR-REACH). The shell used to read `rowMenu?.context ?? surface(target)`:
+ * once a canonical table registered its default row descriptor — which every MatrxDataTable does,
+ * with `__entity: null` — the surface's resolver was never called on a row. So a list that names
+ * its row's record there (CRM `useCrmRowMenu`, the keyword tables) lost Attach To, Share and
+ * "Link a record…" on every row, and its own row doors with them (they are built from the state
+ * that resolver sets).
+ *
+ *   · The row descriptor still owns the row's VALUES (content, heading, the full row): on a key
+ *     both name, the descriptor stands (the 2026-09-26/27 heading rulings are unchanged).
+ *   · The ENTITY is the surface's to name when the descriptor names none: the table knows a row,
+ *     only the surface knows which record that row is. A descriptor that names its own entity
+ *     keeps it.
+ *   · Anything only the surface says is kept.
+ */
+declare function joinRowAndSurfaceContext(row: ResolvedContextMenuContext | null | undefined, surface: ResolvedContextMenuContext | null | undefined): ResolvedContextMenuContext | null;
+/**
+ * Read the right-clicked row's entity straight off the DOM.
+ *
+ * 🚨 WHY THIS EXISTS (Phase 0, 2026-08-25). `resolveContextOnOpen` is the
+ * precise path and remains it — but it made per-row identity cost a
+ * hand-written resolver on EVERY table. With ~500 surfaces still to wire that
+ * is ~500 bespoke `rowFor(target)` functions, each one a place to return the
+ * wrong row. A row that already knows what it is can now simply SAY so:
+ *
+ *   <tr data-entity-type="seo_keyword" data-entity-id={k.id} data-entity-title={k.phrase}>
+ *
+ * and Attach To / Share target that record with no resolver at all.
+ *
+ * PRECEDENCE — THE SURFACE ALWAYS WINS. This runs ONLY when
+ * `resolveContextOnOpen` did not speak about the entity at all (key absent).
+ * An explicit `null` from the surface means "this target has no entity" and is
+ * honoured; the DOM never overrides a deliberate answer.
+ */
+declare function sniffEntityFromDom(target: HTMLElement | null): ContextMenuEntityRef | null;
+/**
+ * The effective entity for one open, DOM sniff included. Surface answer wins;
+ * the sniff only fills a silence.
+ */
+declare function resolveEffectiveEntityWithDom(entityProp: ContextMenuEntityRef | undefined, resolved: ResolvedContextMenuContext | null, target: HTMLElement | null): ContextMenuEntityRef | undefined;
+
+/**
+ * ONE MENU, SEVERAL SOURCES OF SURFACE ROWS — joined so every row id is unique.
+ *
+ * A menu's surface sections can come from more than one owner for one open: a table row's
+ * descriptor plus the grid's per-target sections, or the content's own sections plus the RECORD
+ * it belongs to (record-menu-registry.ts — a note's tab rows join the menu opened on the note's
+ * content). Each owner keeps its own ids unique, but not across owners, and the menu model
+ * namespaces every surface row as `x:<id>` (menu-model.ts) — so the same id from two owners
+ * reached the one Alchemy registry twice and it refused the second:
+ * `DuplicateActionError: Action "cm:x:save" is yielded twice by provider "context-menu:…"`
+ * (/notes, 2026-09-30: the editor's "Save" and the tab's "Save", both saving the same note).
+ *
+ * Sources are passed in precedence order. Two owners describing one target with the same id
+ * mean the same action on it, so the FIRST source's row stands and a later source's row with
+ * that id is not drawn a second time. A duplicate inside ONE source is that source's own defect
+ * and is left untouched, so the registry still refuses it loudly.
+ */
+
+declare function joinExtraSections(...sources: Array<ContextMenuExtraSection[] | null | undefined>): ContextMenuExtraSection[] | undefined;
+
+/**
+ * THE MENU OPENED IN A FIELD NAMES THE FIELD (page-pass 2026-09-27,
+ * /chat/message-templates/<id>). Right-clicking the Body box headed the menu
+ * "Content: {{reply.body}}" — the field's raw text. The header is now the
+ * field's own name ("Body"), with a short plain preview only when it helps:
+ * merge fields read as their names ("Reply body"), and text that is ONLY merge
+ * fields gets no preview (the name already says it). Pure, so it is tested
+ * without a DOM menu.
+ */
+/** A field's name, the way a person reads it on screen. `null` when it has none. */
+declare function fieldLabelOf(element: Element | null | undefined): string | null;
+/** "reply.body" / "reply_body" → "Reply body". */
+declare function mergeFieldName(token: string): string;
+declare const FIELD_PREVIEW_MAX = 60;
+/**
+ * The preview beside the field's name: plain words with merge fields named,
+ * clipped; `""` when the text holds nothing but merge fields (or nothing).
+ */
+declare function fieldPreview(text: string): string;
+
+interface KeyCombo {
+    alt: boolean;
+    shift: boolean;
+    ctrl: boolean;
+    meta: boolean;
+    /** `KeyboardEvent.code` for letters/digits ("KeyS", "Digit1"), else null. */
+    code: string | null;
+    /** Lowercased `KeyboardEvent.key` for named keys ("enter", "/"), else null. */
+    key: string | null;
+}
+/**
+ * Parse an advertised combo. Null when it cannot be a combo this listener can
+ * honour: no non-Shift modifier (plain typing), or no key.
+ */
+declare function parseKeyCombo(raw: string | null | undefined): KeyCombo | null;
+type KeyEventLike = Pick<KeyboardEvent, "altKey" | "shiftKey" | "ctrlKey" | "metaKey" | "code" | "key">;
+declare function eventMatchesCombo(e: KeyEventLike, combo: KeyCombo): boolean;
+/** First item whose advertised combo this key event presses. */
+declare function findComboMatch<T>(e: KeyEventLike, items: readonly T[], comboOf: (item: T) => string | null | undefined): T | null;
+
+interface BuildEditableWidgetHandleArgs {
+    getTextarea?: (() => HTMLTextAreaElement | null) | undefined;
+    onTextReplace?: ((newText: string) => void) | undefined;
+    onTextInsertBefore?: ((text: string) => void) | undefined;
+    onTextInsertAfter?: ((text: string) => void) | undefined;
+    /** Live scope builder — read for `content` when there is no textarea. */
+    getApplicationScope?: (() => ApplicationScope) | undefined;
+}
+/**
+ * Build the widget handle for an editable surface, or `null` when the surface
+ * exposes no way to write (nothing to register, no tools advertised).
+ */
+declare function buildEditableWidgetHandle(args: BuildEditableWidgetHandleArgs): WidgetHandle | null;
+
+interface BuildSelectionWriteBackArgs {
+    /** The text the agent was launched on (the selection, or the whole field). */
+    originalText: string;
+    /** "selection" when the person selected text; anything else = whole field. */
+    textSource: string;
+    selectionRange: SelectionRange | null | undefined;
+    onTextReplace?: ((fullValue: string) => void) | undefined;
+    onTextInsertAfter?: ((text: string) => void) | undefined;
+    insertAtCaret?: ((text: string) => boolean) | undefined;
+}
+/**
+ * Build the write-back for one launch, or null when the surface cannot be
+ * written (read-only, or nothing captured to write over).
+ */
+declare function buildSelectionWriteBack(args: BuildSelectionWriteBackArgs): SelectionWriteBack | null;
+
+/**
+ * `inline` goes exactly at the caret; `block` (a reference fence, a section)
+ * goes on its own line, never inside a word (G5 review, 2026-10-02: "of" became
+ * "o" + block + "f") — BEFORE the caret's line only from its very start,
+ * AFTER it otherwise (G11B: a right-click at the start of a line goes above;
+ * G15, 2026-10-07: a character "first half" rule surprised wrapped
+ * paragraphs). The one rule is `blockBoundary(…, "nearest")`
+ * (@ai-matrx/rich-editor ≥ 0.3.1).
+ */
+type EditorInsertPlacement = "inline" | "block";
+interface EditorInsertTargets {
+    /** A contentEditable editor addressed by `data-editor-id`. */
+    editorId?: string | undefined;
+    /** The surface's textarea — may return null when no textarea is mounted now. */
+    getTextarea?: (() => HTMLTextAreaElement | null) | undefined;
+    /**
+     * A rich editor's insert-at-the-caret. Returns false when it cannot take it.
+     * A `block` must land on its own line/paragraph, never inside a word.
+     */
+    insertAtCaret?: ((text: string, placement?: EditorInsertPlacement) => boolean) | undefined;
+    /** Full-value write-back for a controlled textarea. */
+    onTextReplace?: ((nextValue: string) => void) | undefined;
+}
+/** The text to insert, shaped per target (a textarea knows its neighbours). */
+interface EditorInsertText {
+    editor: string;
+    textarea: (field: HTMLTextAreaElement) => string;
+    caret: string;
+    /** Default `inline`. */
+    placement?: EditorInsertPlacement | undefined;
+}
+type EditorInsertTarget = "editor" | "textarea" | "caret";
+/** True when the surface advertises any write target at all. */
+declare function hasEditorInsertTarget(targets: EditorInsertTargets): boolean;
+/**
+ * Insert into whichever target is live right now. Returns the target that took
+ * the text, or null when none could (the caller then copies — never silent).
+ */
+declare function insertIntoEditor(targets: EditorInsertTargets, text: string | EditorInsertText): EditorInsertTarget | null;
+/**
+ * A block that must sit on its own paragraph inside a textarea: blank lines
+ * are added only where the neighbours do not already provide them.
+ */
+declare function ownParagraph(block: string, field: HTMLTextAreaElement): string;
+
+type Callbacks = RichDocumentActionContext["callbacks"];
+type Request = NonNullable<NonNullable<Callbacks>["onRequestTextAgentAction"]>;
+declare function editorTextAgentCallbacks(callbacks: Callbacks, source: ContentSource, adapter: Pick<ContentSourceAdapter, "edit">, request: Request | undefined): Callbacks;
+
+declare function tableTextAtTarget(target: Element | null): string | null;
+
+/**
+ * The attributes ContextMenuV3 stamps onto every right-click REGION it wraps
+ * (the chat composer textarea, every sidebar chat row, messages, table rows).
+ *
+ * ONE source: `ContextMenuV3.tsx` spreads this onto its trigger, and the real-
+ * browser layout gate (`features/shell/layout-gate/shipped-css-region-triggers.spec.ts`)
+ * renders its fixtures with the same object — so a stylesheet the app ships
+ * that styles these attributes (the 2026-09-26 `[data-alchemy-trigger] {
+ * width: 2rem }` collapse) is measured against exactly what production emits.
+ *
+ * Plain data, no React: the Playwright spec imports it directly.
+ */
+declare const CONTEXT_REGION_TRIGGER_ATTRS: {
+    readonly "data-alchemy-trigger": "context";
+};
+
+/**
+ * Framework-owned launch defaults for agents listed in the managed "Agents"
+ * context-menu section. Shortcuts do not use this config: their persisted
+ * execution definitions remain authoritative.
+ */
+declare const MANAGED_CONTEXT_MENU_AGENT_CONFIG: {
+    readonly displayMode: "flexible-panel";
+    readonly allowChat: true;
+    readonly showVariablePanel: true;
+};
+
+/**
+ * features/context-menu-v3/item/itemMenuToV3.ts
+ *
+ * ItemMenuConfig → v3 `extraSections` converter — the bridge that lets
+ * `ItemContextMenu` render the ONE universal context menu instead of its own
+ * Radix tree. Command/toggle execution reuses `run-entry.ts` (toast.promise
+ * parity with the kebab dropdown), checkbox/link map to the dedicated v3 item
+ * kinds, and section boundaries/labels carry over. Deliberate deltas from the
+ * old bespoke render (documented in FEATURE.md): no in-menu single-key
+ * shortcut execution (hints still display) and the header renders as a
+ * leading section label instead of a Radix label block.
+ */
+
+declare const toastPromise: (promise: Promise<unknown>, messages: {
+    loading: string;
+    success: string;
+    error: (e: unknown) => string;
+}) => void;
+
+declare function itemMenuConfigToExtraSections(config: ItemMenuConfig): ContextMenuExtraSection[];
+
+interface ContextMenuTargetHost {
+    kind: "context-menu";
+    /** The menu instance (one open menu = one provider registration). */
+    instanceId: string;
+}
+/** Composite host: a right-click target can carry both providers' halves. */
+interface CompositeTargetHost {
+    contextMenu?: ContextMenuTargetHost | undefined;
+    richDocument?: unknown | undefined;
+}
+declare function contextMenuHostOf(target: ClickTarget): ContextMenuTargetHost | null;
+interface ProviderOptions {
+    /**
+     * Resolves with the NEXT model the engine hook builds. A library still
+     * loading (the first agent fetch) waits on it instead of vanishing.
+     */
+    nextModel?: (() => Promise<MenuModel>) | undefined;
+    /**
+     * Whether THIS menu instance edits its surface (`isEditable`). A read-only
+     * wrapper over rich content still gets a writable rich-document target
+     * (actions may write back to the SOURCE), so `target.readOnly` alone cannot
+     * say "the person cannot type here" — this can (live 2026-09-27: a table
+     * row's menu still drew Cut / Paste / Undo / Redo).
+     */
+    editable?: boolean | undefined;
+}
+/**
+ * The model → the actions this menu instance contributes. Rich-document rows
+ * (`rich:` leaves) are skipped: the rich-document provider supplies them.
+ */
+declare function contextMenuActionsFromModel(model: MenuModel, instanceId: string, opts?: ProviderOptions): Action[];
+/**
+ * THE provider one open menu registers (AlchemyMenuContent). Every menu
+ * instance yields the same baseline ids (`cm:copy`, `cm:find`, …) and the
+ * Alchemy registry refuses an id a second provider yields — so an instance
+ * answers ONLY a target it opened. Two menus mounted at once (a message's menu
+ * nested in the page's, PB-06 2026-10-01: 18 `DuplicateActionError`s per
+ * open) each contribute to their own target and nothing to the other's.
+ */
+declare function contextMenuProvider(instanceId: string, actions: () => readonly Action[]): ActionProvider;
+/** A cheap fingerprint of what the menu would draw (re-resolve when it moves). */
+declare function modelRevision(model: MenuModel): string;
+/**
+ * The text the menu's "Content: …" header shows for what the menu acts on —
+ * without storage plumbing: the tutor's trust comment goes through the ONE
+ * strip copies and files use (live 2026-09-26: the header showed
+ * `<!--MATRX_TRUST_V1 …-->` on every tutor answer).
+ */
+declare function menuHeaderContent(actionText: {
+    source: string;
+    text: string;
+}): string | null;
+/** The transcript store slice `chatMessageSubject` reads (RootState["messages"]). */
+interface TranscriptStoreSlice {
+    messages?: {
+        byConversationId?: Record<string, {
+            byId?: Record<string, {
+                role?: unknown;
+                createdAt?: string | null;
+            } | undefined>;
+        } | undefined>;
+    };
+}
+/**
+ * THE MESSAGE A MENU WAS OPENED ON — one answer for every menu over a chat
+ * transcript, so the same message gets the same heading everywhere ("AI answer
+ * · Sep 27, 6:50 PM", "Your message · …").
+ *
+ * Two doors name a message and both land here:
+ *   1. the menu's own content source is that message (`chat-message` — the
+ *      per-answer registry menu);
+ *   2. the menu is the transcript-level one and the right-click resolved the
+ *      message under the pointer (`messageId` in the per-open context —
+ *      `resolveMarkdownContext` reads the `data-message-id` every message root
+ *      carries). Run History's user turns and any answer area outside the
+ *      per-answer menu came through here and were headed "Content: <the whole
+ *      text>" (2026-09-28).
+ */
+declare function chatMessageSubject(args: {
+    state: TranscriptStoreSlice;
+    source: {
+        type: string;
+        conversationId?: string;
+        messageId?: string;
+    } | null | undefined;
+    extensions?: {
+        type?: string;
+        role?: unknown;
+    } | null;
+    contextData?: Record<string, unknown> | null | undefined;
+}): {
+    role: string;
+    createdAt: string | null;
+} | null;
+/**
+ * The header for a menu opened in a FIELD with no selection: the field's name
+ * and, when it helps, a short plain preview (`utils/field-menu-header.ts`).
+ * Anything else keeps `menuHeaderContent`.
+ */
+declare function menuHeader(actionText: {
+    source: string;
+    text: string;
+}, fieldLabel: string | null, 
+/** The chat message the menu opened on, when it did (its role and when it was written). */
+message?: {
+    role: string;
+    createdAt?: string | null;
+} | null): {
+    content: string | null;
+    contentLabel: string | null;
+};
+/**
+ * The header is a one-line PREVIEW, so it shows words, never markdown syntax:
+ * "Content: # Clinic intake…" on /notes/<id> (page-pass 2026-09-27). Block
+ * markers (headings, quotes, list bullets, task boxes, fences) are dropped per
+ * line, inline emphasis goes through THE plain-text helper, and lines join
+ * with a space. Only the header changes — the actions still act on the text
+ * as written.
+ */
+declare function headerPreview(text: string): string;
+/**
+ * A target that NAMES itself (`CONTEXT_MENU_HEADING_KEY`: a list row's record)
+ * heads the menu with that name — "Quiz: Unit 2 review" — instead of the
+ * generic "Content: <agent context>" (page-pass 2026-09-27). A selection still
+ * shows itself.
+ */
+declare function namedHeader(heading: {
+    label: string;
+    text: string;
+} | null | undefined, actionText: {
+    source: string;
+}): {
+    content: string;
+    contentLabel: string;
+} | null;
+/**
+ * The revision the alchemy menu engine re-resolves on. The engine
+ * (`useMenuEngine` in @ai-matrx/alchemy/react/menu) rebuilds its model — header
+ * included — only when its `revision` moves; `content` / `contentLabel` are not
+ * in its dependency list. A menu that stays mounted between opens therefore
+ * kept the FIRST header: "Note: New Note" after the note was renamed
+ * (G6B review, 2026-10-02). The header text is part of what the menu draws, so
+ * it is part of the revision.
+ */
+declare function menuEngineRevision(drawn: string, header: {
+    content: string | null;
+    contentLabel: string | null;
+}): string;
+
+declare const CONTEXT_MENU_SELECTION_HOST_KEY = "contextMenuSelection";
+interface ContextMenuSelectionHost {
+    kind: "context-menu-selection";
+    /** Open this menu instance over the current selection. */
+    open(): void;
+}
+declare const contextMenuSelectionProvider: ActionProvider;
+
+export { type BuildEditableWidgetHandleArgs, type BuildSelectionWriteBackArgs, CONTEXT_MENU_ENGINE_ID_PREFIXES, CONTEXT_MENU_ENGINE_ROWS, CONTEXT_MENU_SELECTION_HOST_KEY, CONTEXT_REGION_TRIGGER_ATTRS, type ClickedKind, type CompositeTargetHost, type ContextMenuSelectionHost, type ContextMenuTargetHost, type EditorInsertPlacement, type EditorInsertTarget, type EditorInsertTargets, type EditorInsertText, FIELD_PREVIEW_MAX, type InventoryRow, type KeyCombo, MANAGED_CONTEXT_MENU_AGENT_CONFIG, type MenuCheckboxNode, type MenuGroup, MenuGrouping, type MenuHeader, type MenuItemNode, type MenuLabelNode, type MenuLeafNode, type MenuLinkNode, type MenuModel, type MenuNode, type MenuRoles, type MenuSection, type MenuSeparatorNode, type MenuSubmenuNode, OWN_ROWS_MAX, PROPOSED_MENU_GROUPING, type ProposedOptions, type ProviderOptions, RECORD_MENU_ATTR, type RecordMenuRows, STRIP_MAX, type TableRowEditCommands, type TableRowItemHit, type TableRowMenuDescriptor, type WhereTheMenuIs, actionsAlreadyHere, buildDefaultTableRowMenuDescriptor, buildEditableWidgetHandle, buildMenuModel, buildSelectionWriteBack, chatMessageSubject, clickedKind, contextMenuActionsFromModel, contextMenuHostOf, contextMenuProvider, contextMenuSelectionProvider, createDefaultTableRowMenuDescriptor, createTableRowMenuDescriptor, editorTextAgentCallbacks, eventMatchesCombo, fieldLabelOf, fieldPreview, findComboMatch, hasActionable, hasEditorInsertTarget, headerPreview, insertIntoEditor, itemMenuConfigToExtraSections, toastPromise as itemToastPromise, joinExtraSections, joinRowAndSurfaceContext, liftPrimarySections, menuEngineRevision, menuHeader, menuHeaderContent, mergeFieldName, mergeResolvedContextData, modelRevision, namedHeader, openContextMenuForElement, openRecordMenu, ownParagraph, parseKeyCombo, proposedArrangement, recordMenuChanged, recordMenusRevision, registerRecordMenu, registerTableRowContextResolver, registryTreeNodes, resolveEffectiveEntity, resolveEffectiveEntityWithDom, resolveRecordMenu, resolveTableRowItem, resolveTableRowMenuDescriptor, rowRecordName, sniffEntityFromDom, subscribeRecordMenus, tableRowEditCommands, tableTextAtTarget };