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

package/dist/grouping-CB3zlD1T.d.ts

@@ -0,0 +1,623 @@
+import * as _ai_matrx_icons from '@ai-matrx/icons';
+import * as lucide_react from 'lucide-react';
+import './host-types-AOiEYwR8.js';
+import { PlacementKey, PlacementVisibility, ContextMenuExtraSection, MenuContentProps } from '@ai-matrx/chat/context-menu/types';
+import { ComponentType } from 'react';
+import { ResolvedSurfaceManifest } from '@ai-matrx/chat/surfaces/types';
+import { SklRenderDefinition } from '@ai-matrx/chat/agents/redux/agent-shortcuts/skl-types';
+import { ConfirmOptions } from '@ai-matrx/kit/confirm-opener';
+import { RichDocumentActionContext, RichDocumentAction } from '@ai-matrx/rich-content/rich-document/types';
+import { ApplicationScope } from '@ai-matrx/chat/agents/types/scope.types';
+import { AgentShortcutRecord } from '@ai-matrx/chat/agents/redux/agent-shortcuts/types';
+import { AgentShortcutCategoryRecord } from '@ai-matrx/chat/agents/redux/agent-shortcut-categories/types';
+import { Scope } from '@ai-matrx/chat/agents/redux/shared/scope';
+import { SurfaceBoundAgentSection, SurfaceBoundAgentEntry } from '@ai-matrx/chat/surfaces/services/surface-bound-agents.service';
+import { SelectionRange } from '@ai-matrx/chat/context-menu/utils/selection-tracking';
+import { JsonDetection } from '@ai-matrx/kit/json-format';
+import { ActionCategory, ResolvedAction, Action, ClickTarget } from '@ai-matrx/alchemy/actions';
+import { ContextArrangement, MenuModel } from '@ai-matrx/alchemy/menu';
+
+/**
+ * THE CONTEXT MENU HOST PORT — everything the engine needs that only the app
+ * running it can answer.
+ *
+ * The engine (model, layouts, handlers, data fetch, scope resolution) lives
+ * in this package. What stays with the host is identity-shaped: which overlay
+ * opens for "Find", what the app's diff window is, which of its admin lanes
+ * is open, its surface-manifest registry, its toast/confirm/manual-copy
+ * doors. A host registers them ONCE at boot:
+ *
+ *   configureContextMenuHost({ useBindings, getSurfaceManifest, ... });
+ *
+ * Organization, user id and toasts are NOT here — they come through the chat
+ * package's host (`@ai-matrx/chat/host/*`), which every menu host already
+ * configures because the menu launches agents.
+ *
+ * Every member has a shipped default. A default never pretends: it either
+ * does the honest minimum (kit `confirm`) or announces once, by name, that
+ * the host did not wire it (`[context-menu] host port "<name>" is not wired`).
+ *
+ * The registration lives on `globalThis` under a `Symbol.for` key so the ESM
+ * and CJS builds (and a host that loads both) share one host.
+ */
+
+interface ListenSummaryWindowOptions {
+    agentId: string;
+    agentName: string | null;
+    sourceText: string;
+    style: string;
+    autoPlay: boolean;
+}
+interface DiffWindowOptions {
+    original: string;
+    modified: string;
+    originalLabel: string;
+    modifiedLabel: string;
+    title: string;
+    engine: "light";
+}
+interface FindReplaceOptions {
+    getTargetElement: () => HTMLElement | null;
+    onReplace: ((nextText: string) => void) | undefined;
+}
+/** What the reference picker hands back. */
+interface ReferencePick {
+    /** The canonical ```matrx fence carrying the minified one-line shell. */
+    fence: string;
+    /** The bare minified shell (what the fence wraps). */
+    shell: string;
+    /** Grammar class the fence carries. */
+    directiveClass: string;
+    /** Reference type token on the wire (`conversation`, `note`, `file`, `url`, …). */
+    type: string;
+    /** Display title of the picked record, when known. */
+    title: string | null;
+    delivery: "insert" | "copy";
+}
+interface ReferencePickerOptions {
+    mode: "insert" | "copy";
+    onPicked: (pick: ReferencePick) => void;
+}
+interface ContextAssignmentOptions {
+    subject: {
+        entityType: string;
+        entityId: string;
+        title: string | undefined;
+    };
+}
+interface LinkRecordSheetOptions {
+    target: {
+        token: string;
+        id: string;
+        title: string | undefined;
+    };
+}
+interface ShareModalOptions {
+    resourceType: string;
+    resourceId: string;
+    resourceName: string | undefined;
+}
+interface SurfaceContextWindowOptions {
+    surfaceName: string;
+    isEditable: boolean;
+}
+interface SurfaceAgentBindOptions {
+    surfaceName: string;
+}
+interface SurfaceInspectorOptions {
+    surfaceName: string | null;
+    scope: unknown;
+    isEditable: boolean;
+    preferRuntime?: boolean | undefined;
+}
+interface CompareBaseInput {
+    content: string;
+    label: string;
+    language: string | null;
+}
+/** The quick launchers the menu's "Open" group offers. */
+interface ContextMenuQuickActions {
+    openChatWindow: () => void;
+    openQuickChat: () => void;
+    openQuickData: () => void;
+    openQuickFiles: () => void;
+    openQuickNotes: () => void;
+    openQuickTasks: () => void;
+    openVoicePad: () => void;
+}
+/** Everything the engine reads or opens per render. Returned by the host's `useBindings` HOOK. */
+interface ContextMenuHostBindings {
+    /** Admin DEBUGGING power on this page (surface key, menu version, Admin Tools). */
+    isAdminDebugger: boolean;
+    /** Admin POWER on this page (Surface Context Admin, admin document actions). */
+    hasAdminPower: boolean;
+    isDebugMode: boolean;
+    isAdminIndicatorOpen: boolean;
+    hasCompareBase: boolean;
+    /** The person's selected scopes/context, landed on the ambient scope key. */
+    activeScopeIds: unknown;
+    toggleDebugMode: () => void;
+    toggleAdminIndicator: () => void;
+    setCompareBase: (input: CompareBaseInput) => void;
+    /** Resolves false when there was no base to compare with. */
+    openCompareWithBase: (input: {
+        current: string;
+        currentLabel: string;
+    }) => Promise<boolean>;
+    openListenSummaryWindow: (options: ListenSummaryWindowOptions) => void;
+    openDiffWindow: (options: DiffWindowOptions) => void;
+    openFindReplace: (options: FindReplaceOptions) => void;
+    openReferencePicker: (options: ReferencePickerOptions) => void;
+    openContextAssignment: (options: ContextAssignmentOptions) => void;
+    openLinkRecordSheet: (options: LinkRecordSheetOptions) => void;
+    openShareModalWindow: (options: ShareModalOptions) => void;
+    openStateViewer: () => void;
+    openSurfaceInspector: (options: SurfaceInspectorOptions) => void;
+    openSurfaceContextWindow: (options: SurfaceContextWindowOptions) => void;
+    openBindAgent: (options: SurfaceAgentBindOptions) => void;
+    quickActions: ContextMenuQuickActions;
+}
+interface ManualCopyOptions {
+    text: string;
+    title?: string | undefined;
+    description?: string | undefined;
+}
+/** Props the host's document-review component receives (the "AI result replaces the selection" flow). */
+type DocumentAgentReviewProps = Record<string, unknown>;
+interface ContextMenuHost {
+    /** A React HOOK, called once per open menu, unconditionally. */
+    useBindings: () => ContextMenuHostBindings;
+    /** The host's surface-manifest registry. */
+    getSurfaceManifest: (surfaceName: string) => ResolvedSurfaceManifest | undefined;
+    /** The render-definition ("content block") rows already in the host store. */
+    selectRenderDefinitions: (state: unknown) => readonly SklRenderDefinition[];
+    confirm: (options: ConfirmOptions) => Promise<boolean>;
+    /** The last-resort dialog when the clipboard refuses a write. */
+    showManualCopy: (options: ManualCopyOptions) => void;
+    /** The surface whose `spoken_summary` role every surface falls back to. */
+    listeningHomeSurface: string;
+    /** The host's document agent review (rendered when an AI result can replace a selection). */
+    DocumentAgentReview: ComponentType<DocumentAgentReviewProps> | null;
+}
+declare const DEFAULT_CONTEXT_MENU_HOST: ContextMenuHost;
+/** Register the host's answers. Partial: anything omitted keeps its default. */
+declare function configureContextMenuHost(host: Partial<ContextMenuHost>): void;
+/** The registered host (defaults where the host registered nothing). */
+declare function getContextMenuHost(): ContextMenuHost;
+/** Tests: back to the shipped defaults. */
+declare function resetContextMenuHost(): void;
+/** The per-render bindings — a hook; call it at the top level of a component or hook. */
+declare function useContextMenuHostBindings(): ContextMenuHostBindings;
+
+type AgentMenuEntry = ({
+    entryType: "agent_shortcut";
+    scopeLevel: Scope;
+} & AgentShortcutRecord) | ({
+    entryType: "content_block";
+    scopeLevel: Scope;
+} & SklRenderDefinition);
+interface AgentMenuCategoryGroup {
+    category: AgentShortcutCategoryRecord & {
+        scopeLevel: Scope;
+    };
+    items: AgentMenuEntry[];
+    children: AgentMenuCategoryGroup[];
+}
+interface UseUnifiedAgentContextMenuArgs {
+    /**
+     * Which placement submenus this host renders. LAYOUT ONLY — see
+     * `buildCategoryGroups`. It never decides whether an ITEM is available.
+     */
+    placementTypes: string[];
+    /**
+     * The Surface Registry `ui_surface.name` (`<client>/<surface>`) this menu is
+     * mounted on, or null on a page the platform cannot name. It is the
+     * page-level rung of the scope hierarchy and the key to the exclusion valve.
+     */
+    surfaceName?: string | null | undefined;
+    /**
+     * Every surface value name that has a READ PATH here: the manifest's
+     * declared values + the baseline floor + whatever actually landed in the
+     * resolved scope. Built by `buildAvailableKeys` in the engine.
+     */
+    availableKeys: ReadonlySet<string>;
+    /** True when the resolved scope carries a non-empty `selection`. */
+    hasSelection: boolean;
+    /** The surface's exclusion valve (`menu` surface-config namespace). */
+    excludedItemIds?: ReadonlySet<string> | undefined;
+    enabled?: boolean | undefined;
+    scope?: Scope | undefined;
+    scopeId?: string | null | undefined;
+}
+interface UseUnifiedAgentContextMenuResult {
+    categoryGroups: AgentMenuCategoryGroup[];
+    loading: boolean;
+    error: string | null;
+    refresh: () => Promise<void>;
+}
+interface BuildCategoryGroupsArgs {
+    placementTypes: string[];
+    surfaceName?: string | null | undefined;
+    availableKeys: ReadonlySet<string>;
+    hasSelection: boolean;
+    excludedItemIds?: ReadonlySet<string> | undefined;
+    shortcuts: AgentShortcutRecord[];
+    categories: AgentShortcutCategoryRecord[];
+    contentBlocks: SklRenderDefinition[];
+}
+/**
+ * THE grouping function — pure and unit-tested
+ * (`__tests__/build-category-groups.test.ts`,
+ * `../model/__tests__/requirement-gate.test.ts`). Turns the fetched
+ * shortcut/category/content-block rows into the nested category tree each
+ * placement submenu renders.
+ *
+ * 🚨 PHASE 6.7 — AVAILABILITY IS DERIVED (THE-MODEL law 3). An item is
+ * offered here iff every surface value it consumes has a read path on this
+ * surface; then its authored scope (global / domain / page) must reach here;
+ * then the surface's exclusion valve gets the last word. The 16 hardcoded
+ * `enabled_features` slugs and the RED `legacyMatch` rows they produced are
+ * GONE: an item qualifies or is absent, and nothing renders as broken.
+ *
+ * 🚨 CATEGORIES GROUP, THEY NEVER GATE. A category's `placementType` still
+ * decides WHICH placement submenu it renders under — that is layout, and it
+ * is the only thing `placementTypes` does here. A category is never dropped
+ * for failing a context filter, and an item's availability never consults its
+ * category.
+ *
+ * Guarantees the tests certify:
+ *  - the derived gate: missing key → absent; key declared-but-empty → present;
+ *  - the hierarchy: global reaches everywhere, a domain reaches its surfaces,
+ *    a page-pinned item reaches only its page;
+ *  - the valve: an excluded id is absent even though it qualified;
+ *  - placement fidelity: a row renders under exactly its category's
+ *    placementType;
+ *  - nested categories nest under their parent, sorted by sortOrder then label;
+ *  - an EMPTY category still returns (with `items: []`) so the UI can render it
+ *    greyed — never silently dropped;
+ *  - an entry with no agent is kept (the renderer disables it as "Not configured");
+ *  - scope precedence dedupe (task > project > user > organization > global),
+ *    ties broken by screen specificity (page > domain > global), then id —
+ *    never by row order.
+ */
+declare function buildCategoryGroups(args: BuildCategoryGroupsArgs): AgentMenuCategoryGroup[];
+declare function useUnifiedAgentContextMenu(args: UseUnifiedAgentContextMenuArgs): UseUnifiedAgentContextMenuResult;
+
+interface ResolveScopeArgs {
+    /** Live scope builder from the surface — wins when present. */
+    getApplicationScope?: (() => ApplicationScope) | undefined;
+    /** Static + per-target-merged value payload from the surface. */
+    contextData: Record<string, unknown>;
+    /** The text the user has selected (captured by the shell at open). */
+    selectedText: string;
+    /** The captured selection range (drives text_before / text_after / content). */
+    selectionRange: SelectionRange | null;
+    /**
+     * Plain text of the right-clicked DOM subtree, captured by the shell. Used as
+     * `content` ONLY when nothing else resolved it — the net that stops a
+     * read-only surface from presenting a dead Copy.
+     */
+    fallbackContent?: string | undefined;
+    /**
+     * The surface this menu declared. Used to adopt the LIVE mounted
+     * `SurfaceRuntime` for that same surface as an underlay (see
+     * `adoptMountedRuntimeScope`).
+     */
+    surfaceName?: string | undefined;
+    /**
+     * AMBIENT STATE — what is true around the user right now (active org, active
+     * scopes, surface, whether a run is streaming). Collected by the engine from
+     * Redux and landed on ONE namespaced `ambient` key, never spread across the
+     * scope. The weakest layer there is: a surface that emits its own `ambient`
+     * keeps it untouched.
+     */
+    ambient?: Record<string, unknown> | undefined;
+}
+declare function resolveApplicationScope(args: ResolveScopeArgs): ApplicationScope;
+/**
+ * The text Copy / AI actions should operate on: the selection if there is one,
+ * otherwise the resolved primary content. This is what makes Copy work on a
+ * read-only surface where the user merely right-clicked.
+ */
+interface ResolvedActionText {
+    text: string;
+    source: "selection" | "content" | "none";
+}
+declare function resolveActionText(scope: ApplicationScope): ResolvedActionText;
+/** True when there is anything for the content-acting half of the menu to do. */
+declare function hasActionableContent(scope: ApplicationScope): boolean;
+interface InertMenuDiagnostic {
+    /** True when the menu opened with nothing meaningful to do. */
+    inert: boolean;
+    reasons: string[];
+}
+/**
+ * A menu is INERT when, on a read-only surface, there is no selection, no
+ * resolvable content, and the surface injected no items of its own — i.e. the
+ * user sees Copy/AI rows that do nothing. (Editable surfaces are never inert:
+ * Paste is always meaningful.)
+ */
+declare function detectInertMenu(args: {
+    scope: ApplicationScope;
+    isEditable: boolean;
+    hasExtraSections: boolean;
+}): InertMenuDiagnostic;
+/**
+ * Compare a surface's DECLARED `alwaysAvailable` values against what actually
+ * landed in the resolved scope. A declared-but-missing value silently breaks
+ * the shortcuts/agents that depend on it — the exact "values not passed"
+ * failure. Baseline values are skipped (they are empty-floored by design, so a
+ * missing one is not an error). Returns human-readable warnings.
+ */
+declare function auditSurfaceScope(surfaceName: string | undefined, scope: ApplicationScope): string[];
+/**
+ * Run both loud guards and SCREAM in dev. A recovery/diagnostic layer that fires
+ * means a real defect got past the surface wiring — per doctrine it must be
+ * impossible to miss, not a silent default. No-op in production.
+ */
+declare function reportMenuDiagnostics(args: {
+    surfaceName: string | undefined;
+    scope: ApplicationScope;
+    isEditable: boolean;
+    hasExtraSections: boolean;
+}): InertMenuDiagnostic;
+
+interface JsonMenuAction {
+    id: string;
+    label: string;
+    /** Real before -> after size, e.g. "13 lines -> 3 lines". */
+    hint?: string | undefined;
+    disabled?: boolean | undefined;
+    run: () => void | Promise<void>;
+}
+interface JsonMenuSection {
+    /** The detection that produced this section (null when the text isn't JSON-ish). */
+    detection: JsonDetection;
+    /** True when the surface will rewrite text; false when actions copy instead. */
+    writes: boolean;
+    actions: JsonMenuAction[];
+}
+interface BuildJsonMenuActionsParams {
+    /** The text the menu is acting on (selection, else resolved content). */
+    text: string;
+    /** True when the action should REWRITE the text rather than copy it. */
+    canWrite: boolean;
+    /** Rewrite the acted-on text with `next`. Only called when `canWrite`. */
+    onReplace: (next: string) => void;
+    /** Copy `next` to the clipboard. Used on read-only surfaces. */
+    onCopy: (next: string) => void | Promise<void>;
+}
+/**
+ * Build the JSON section for the given text, or `null` when the text is not
+ * JSON-shaped at all (the overwhelmingly common case — the section simply
+ * does not render).
+ */
+declare function buildJsonMenuSection(params: BuildJsonMenuActionsParams): JsonMenuSection | null;
+/** Short label for the submenu trigger, e.g. "JSON · 13 lines". */
+declare function jsonSectionLabel(section: JsonMenuSection): string;
+
+declare const DEFAULT_PLACEMENT_MODE: Record<PlacementKey, PlacementVisibility>;
+declare const ALL_DB_PLACEMENTS: PlacementKey[];
+/** User-facing relabels matching the v3 taxonomy (My Items / Org Items). */
+declare const PLACEMENT_LABEL_OVERRIDE: Partial<Record<string, string>>;
+declare const PLACEMENT_COLOR: Record<string, string>;
+declare function getPlacementIcon(placementType: string): lucide_react.LucideIcon;
+declare function getPlacementLabel(placementType: string): string;
+declare function resolveIcon(iconName: string | null | undefined, fallback?: string): _ai_matrx_icons.IconComponentType;
+declare function groupsByPlacement(groups: AgentMenuCategoryGroup[]): Record<string, AgentMenuCategoryGroup[]>;
+declare function hasItemsRecursive(group: AgentMenuCategoryGroup): boolean;
+/** Resolve a rich-document action's label + disabled state for rendering. */
+declare function resolveRichActionView(action: RichDocumentAction, ctx: RichDocumentActionContext): {
+    label: string;
+    disabled: boolean;
+};
+interface ContextMenuActions {
+    scope: ApplicationScope;
+    actionText: ResolvedActionText;
+    /** The name of the field the menu opened in (its label), or null. */
+    fieldLabel: string | null;
+    /** JSON verbs for a JSON-shaped selection/content. `null` = not JSON. */
+    jsonSection: JsonMenuSection | null;
+    resolvedPlacementMode: Record<PlacementKey, PlacementVisibility>;
+    categoryGroups: AgentMenuCategoryGroup[];
+    grouped: Record<string, AgentMenuCategoryGroup[]>;
+    loading: boolean;
+    /** Why the agent libraries (AI Actions, My Items, …) did not load — e.g. past the menu's deadline. */
+    librariesError: string | null;
+    boundAgentSections: SurfaceBoundAgentSection[];
+    boundAgentsLoading: boolean;
+    boundAgentsError: string | null;
+    /** Re-run the library fetches after a failure or a missed deadline. */
+    retryLibraries: () => void;
+    /** Rich-document action ids this menu must not draw (surface exclusions + already-here). */
+    excludedRichActionIds: string[];
+    richDocCtx: RichDocumentActionContext;
+    /** The registry actions this menu shows — rendered as the ONE tree. */
+    registryActions: RichDocumentAction[];
+    copyVariantActions: RichDocumentAction[];
+    exportActions: RichDocumentAction[];
+    convertActions: RichDocumentAction[];
+    hasCompareBase: boolean;
+    isAdmin: boolean;
+    isDebugMode: boolean;
+    isAdminIndicatorOpen: boolean;
+    canNativeUndo: boolean;
+    handleCopy: () => Promise<void>;
+    handleSpeak: () => void;
+    handleSpokenSummary: () => void;
+    handleSpokenSummaryLive: () => void;
+    spokenSummaryAvailable: boolean;
+    handleCut: () => Promise<void>;
+    handlePaste: () => Promise<void>;
+    handleSelectAll: () => void;
+    handleUndo: () => void;
+    handleRedo: () => void;
+    handleCompareClipboard: () => Promise<void>;
+    handleSetCompareBase: () => void;
+    handleCompareWithBase: () => Promise<void>;
+    handleShortcutExecute: (entry: Extract<AgentMenuEntry, {
+        entryType: "agent_shortcut";
+    }>) => Promise<void>;
+    handleBoundAgentExecute: (entry: SurfaceBoundAgentEntry) => Promise<void>;
+    handleContentBlockInsert: (entry: Extract<AgentMenuEntry, {
+        entryType: "content_block";
+    }>) => void;
+    handleEntrySelect: (entry: AgentMenuEntry) => void;
+    handleDelete: () => Promise<void>;
+    handleFind: () => void;
+    /** "Insert reference…" (editable) / "Copy reference…" (read-only). */
+    handleInsertReference: () => void;
+    handleAttach: () => void;
+    /** "Link a record…" — the ONE record picker pointed at this menu's entity. */
+    handleLinkRecord: () => void;
+    handleShare: () => void;
+    handleInspectValues: () => void;
+    handleInspectState: () => void;
+    handleToggleDebugMode: () => void;
+    handleToggleAdminIndicator: () => void;
+    quickActions: ContextMenuQuickActions;
+    /**
+     * The page's surface, as ONE nested menu entry titled with the surface's
+     * display label (e.g. "Notes", "Marketing Site Workspace") — the same data
+     * and actions the shell-header Agents button offers: location, Surface
+     * Context, Surface Context Admin, the bound agents + bind action, related
+     * surfaces, and (admins) the menu revision. Shaped as an extra section so
+     * BOTH renderers draw it with their existing extra-item code.
+     */
+    surfaceSection: ContextMenuExtraSection;
+}
+declare function useContextMenuActions(props: Omit<MenuContentProps, "variant">): ContextMenuActions;
+
+/** One submenu the grouping creates. The label is a plain, conventional word. */
+interface MenuGroupDef {
+    key: string;
+    label: string;
+    /** One line: what the person gets from a row in this submenu. */
+    definition: string;
+    /** Icon KEY for the Alchemy icon port. */
+    icon?: string | undefined;
+    /** Decides where the submenu row sits among the other rows (the package's group order). */
+    category: ActionCategory;
+    order: number;
+}
+type GroupingDestination = 
+/** Top level, lifted to the very top: the page's own actions. */
+{
+    kind: "page-first";
+}
+/** Top level, where the package places it (verbs stay in the icon strip). */
+ | {
+    kind: "top";
+} | {
+    kind: "group";
+    key: string;
+};
+interface GroupingRule {
+    /** Matches when ANY listed condition matches. */
+    when: {
+        ids?: readonly string[] | undefined;
+        idPrefixes?: readonly string[] | undefined;
+        categories?: readonly ActionCategory[] | undefined;
+        /** The clicked thing's own section (a row's or a note's actions). */
+        pageOwn?: boolean | undefined;
+        /**
+         * A page's OWN row whose label matches one of these (case-insensitive
+         * regular expressions): a record action that duplicates a category
+         * ("Export as Markdown", "Share link…") moves into that category.
+         */
+        pageOwnLabels?: readonly string[] | undefined;
+    };
+    to: GroupingDestination;
+    /**
+     * Universal rows that do the same thing. When one of them is in the menu,
+     * the matched row merges into it (one row, recorded as merged) instead of
+     * sitting beside it.
+     */
+    mergeWithIds?: readonly string[] | undefined;
+}
+interface MenuGrouping {
+    name: string;
+    groups: readonly MenuGroupDef[];
+    /** First match wins. */
+    rules: readonly GroupingRule[];
+    /** Where an action no rule names goes. */
+    fallback: GroupingDestination;
+    /** A group with fewer members than this is not made: its member stays at the top level. */
+    minMembers: number;
+}
+interface RegroupOptions {
+    /** Inside one submenu, a second row with the same name as an earlier one is merged into it. */
+    mergeSameName: boolean;
+}
+/** Why an action sits where it sits in the proposed menu. */
+type ProposedHome = {
+    kind: "page-first";
+} | {
+    kind: "top";
+    note?: string;
+} | {
+    kind: "group";
+    key: string;
+    label: string;
+} | {
+    kind: "merged";
+    intoId: string;
+    intoLabel: string;
+    groupLabel: string;
+    /** The merged row runs THIS page's handler under the twin's label and place. */
+    pageActionKept?: boolean | undefined;
+};
+interface RegroupResult {
+    /** What the proposed menu resolves: top-level actions plus one submenu action per group. */
+    resolved: ResolvedAction[];
+    /** The rows inside each submenu, by group key, in order. */
+    members: Map<string, ResolvedAction[]>;
+    home: Map<string, ProposedHome>;
+}
+declare const REGROUP_ID_PREFIX = "regroup:";
+declare function actionLabel(action: Action, target: ClickTarget): string;
+/** The rule that places this action, or null when it falls through to `fallback`. */
+declare function matchRule(grouping: MenuGrouping, action: Pick<Action, "id" | "category" | "section"> & {
+    label?: Action["label"];
+}, target?: ClickTarget): GroupingRule | null;
+declare function destinationFor(grouping: MenuGrouping, action: Action, target?: ClickTarget): GroupingDestination;
+declare function currentModel(target: ClickTarget, resolved: readonly ResolvedAction[]): MenuModel;
+/**
+ * Apply a grouping to the resolved actions. Actions greyed with a reason stay
+ * at the top level: a submenu row is always drawn runnable, so moving a greyed
+ * row into one would make it look usable when it is not.
+ */
+declare function regroupResolved(target: ClickTarget, resolved: readonly ResolvedAction[], grouping: MenuGrouping, options: RegroupOptions): RegroupResult;
+/** Where each top-level action id is drawn in a context arrangement. */
+declare function drawnPlaces(model: MenuModel, arrangement: ContextArrangement): Map<string, string>;
+/** How many rows a person sees when the menu opens (strip icons count as one row). */
+declare function topLevelRowCount(model: MenuModel, arrangement: ContextArrangement): number;
+interface AuditRow {
+    id: string;
+    label: string;
+    category: ActionCategory;
+    isSubmenu: boolean;
+    /** The clicked thing's own row (surface-specific), not a universal one. */
+    pageOwn: boolean;
+    current: string;
+    proposed: ProposedHome | null;
+    proposedPlace: string;
+}
+interface RegroupAudit {
+    rows: AuditRow[];
+    /** Current actions the regrouped menu does not hold anywhere and does not explain. */
+    lost: AuditRow[];
+    currentRows: number;
+    proposedRows: number;
+}
+/**
+ * Recompute, from what the regrouped menu HOLDS, where every current action
+ * went. An action counts as placed only if it is a top-level action of the
+ * regrouped menu, a member of one of its submenus, or recorded as merged into
+ * a row that is itself placed.
+ */
+declare function auditRegroup(target: ClickTarget, resolved: readonly ResolvedAction[], grouping: MenuGrouping, options: RegroupOptions, arrangement: ContextArrangement, 
+/** The regroup under audit (tests hand in a broken one to prove the guard fires). */
+regroup?: typeof regroupResolved): RegroupAudit;
+
+export { topLevelRowCount as $, type AuditRow as A, type BuildJsonMenuActionsParams as B, type ContextMenuActions as C, DEFAULT_CONTEXT_MENU_HOST as D, configureContextMenuHost as E, type FindReplaceOptions as F, type GroupingDestination as G, currentModel as H, type InertMenuDiagnostic as I, type JsonMenuAction as J, destinationFor as K, type LinkRecordSheetOptions as L, type MenuGrouping as M, detectInertMenu as N, drawnPlaces as O, type ProposedHome as P, getContextMenuHost as Q, REGROUP_ID_PREFIX as R, type ShareModalOptions as S, hasActionableContent as T, jsonSectionLabel as U, matchRule as V, regroupResolved as W, reportMenuDiagnostics as X, resetContextMenuHost as Y, resolveActionText as Z, resolveApplicationScope as _, type CompareBaseInput as a, useContextMenuHostBindings as a0, ALL_DB_PLACEMENTS as a1, type AgentMenuCategoryGroup as a2, type AgentMenuEntry as a3, type BuildCategoryGroupsArgs as a4, DEFAULT_PLACEMENT_MODE as a5, PLACEMENT_COLOR as a6, PLACEMENT_LABEL_OVERRIDE as a7, type UseUnifiedAgentContextMenuArgs as a8, type UseUnifiedAgentContextMenuResult as a9, buildCategoryGroups as aa, getPlacementIcon as ab, getPlacementLabel as ac, groupsByPlacement as ad, hasItemsRecursive as ae, resolveIcon as af, resolveRichActionView as ag, useContextMenuActions as ah, useUnifiedAgentContextMenu as ai, type ContextAssignmentOptions as b, type ContextMenuHost as c, type ContextMenuHostBindings as d, type ContextMenuQuickActions as e, type DiffWindowOptions as f, type DocumentAgentReviewProps as g, type GroupingRule as h, type JsonMenuSection as i, type ListenSummaryWindowOptions as j, type ManualCopyOptions as k, type MenuGroupDef as l, type ReferencePick as m, type ReferencePickerOptions as n, type RegroupAudit as o, type RegroupOptions as p, type RegroupResult as q, type ResolveScopeArgs as r, type ResolvedActionText as s, type SurfaceAgentBindOptions as t, type SurfaceContextWindowOptions as u, type SurfaceInspectorOptions as v, actionLabel as w, auditRegroup as x, auditSurfaceScope as y, buildJsonMenuSection as z };