@ai-matrx/rich-content 0.2.10 → 0.2.16

package/dist/rich-document/types.d.ts

@@ -0,0 +1,384 @@
+import type { ApplicationScope } from "./host-types.js";
+import type { LucideIcon } from "lucide-react";
+import type { AppDispatch, RootState } from "./host-types.js";
+import type { Note } from "./host-types.js";
+import type { NoteSaveReceipt } from "./host-types.js";
+export type ContentSourceType = "chat-message" | "note" | "prompt-result" | "artifact" | "scraper-result" | "working-document" | "raw";
+export interface NoteEditBase {
+    noteId: string;
+    organizationId: string;
+    /** The persisted CAS revision. Revision zero is valid. */
+    version: number;
+    actorId: string;
+}
+/** Full physical values displayed when a Notes editor was opened. */
+export type NoteDisplayedPhysicalSnapshot = Omit<Pick<Note, "id" | "organization_id" | "version" | "content" | "label" | "folder_name" | "folder_id" | "tags" | "metadata" | "shown_to" | "published_to_web" | "position" | "project_id" | "task_id">, "content"> & {
+    content: string;
+};
+export type NoteIdentityContentSource = {
+    type: "note";
+    mode: "identity";
+    noteId: string;
+    sourceId: string;
+};
+export type NoteEditableContentSource = {
+    type: "note";
+    mode: "editable";
+    noteId: string;
+    sourceId: string;
+    snapshotId: string;
+    editBase: NoteEditBase;
+    /** Full persisted physical state for the captured CAS base. */
+    acknowledgedPhysicalSnapshot: NoteDisplayedPhysicalSnapshot;
+    displayedPhysicalSnapshot: NoteDisplayedPhysicalSnapshot;
+    /** A selection is an action target only; it is never the persisted body. */
+    actingSelection?: string;
+};
+/**
+ * A source can be a READ-ONLY copy (the proving route loads a real record into
+ * a scratch buffer). The flag rides the source itself, so every surface that
+ * shows it — bar, ⋯ menu, right-click, hosted dialogs — honors it: no action
+ * with `writesSource` is offered, and editors open without Save.
+ */
+export type ContentSource = ContentSourceIdentity & {
+    readOnly?: boolean;
+};
+type ContentSourceIdentity = {
+    type: "chat-message";
+    messageId: string;
+    conversationId: string;
+    streamRequestId?: string | null;
+} | NoteIdentityContentSource | NoteEditableContentSource | {
+    type: "prompt-result";
+    executionId: string;
+    promptId?: string;
+} | {
+    type: "artifact";
+    artifactId: string;
+} | {
+    type: "scraper-result";
+    runId: string;
+} | {
+    type: "working-document";
+    conversationId: string;
+    kind: "working" | "scratch";
+    documentId?: string | null;
+} | {
+    type: "raw";
+    /** What this content is called (a report, a transcript) — seeds titles and file names. */
+    title?: string;
+};
+export type RichDocumentActionId = "thumbs-up" | "thumbs-down" | "copy" | "copy-with-thinking" | "save-as-file" | "save-to-notes" | "save-to-scratch" | "save-code-to-scratch" | "save-to-code" | "save-to-task" | "html-preview" | "copy-html-page" | "email-to-me" | "print" | "full-print" | "edit" | "edit-history" | "fork-at-message" | "delete-message" | "tts-play" | "open-fullscreen-editor" | "analyze-response" | "debug-stream" | "submit-feedback" | "add-to-docs" | "add-to-rulebook" | "set-context-value" | "save-as-message-template" | "save-to-files" | "save-as-pdf" | "save-shape-instance" | "convert-to-study" | "share-webpage" | "send-google-doc" | "summarize-for-listening" | "summarize-and-listen" | "copy-markdown" | "copy-plain-text" | "copy-html-source" | "copy-table-csv" | "copy-table-tsv" | "save-table-as-data" | "download-html" | "download-pdf" | "save-as-flashcard" | "quote-into-chat" | "ask-followup" | "send-to-agent" | "apply-to-source" | "save-run-as-shortcut" | "bind-run-to-page" | "notes-and-comments" | "text-cleanup" | "text-help" | "text-custom-agent" | "edit-and-resubmit" | "fork-and-regenerate" | "server-api-admin";
+export type ActionCategory = "feedback" | "copy" | "export" | "save" | "edit" | "share" | "creator" | "app" | "listen" | "study" | "ask" | "ai" | "admin";
+export type SourceExtensions = ChatMessageExtensions | {
+    type: "note";
+    isOwner: boolean;
+} | {
+    type: "prompt-result";
+    canReRun: boolean;
+} | {
+    type: "artifact";
+    canEdit: boolean;
+} | {
+    type: "scraper-result";
+} | {
+    type: "working-document";
+} | {
+    type: "raw";
+};
+/**
+ * What a chat message carries beyond its identity. `ctx.content` is what the
+ * reader SEES (the whole multi-iteration turn when the host groups one);
+ * `messageContent` is the ONE cx_message row the write-back actions (edit,
+ * HTML publish save) mutate. Built by `buildChatMessageActions` — the single
+ * builder every chat host and the proving route share.
+ */
+export interface ChatMessageExtensions {
+    type: "chat-message";
+    role: "assistant" | "user";
+    /** Single-message text of `source.messageId` (write-back target). */
+    messageContent: string;
+    /** True when the text is the JSON raw view of a structured payload. */
+    contentIsStructuredRaw: boolean;
+    /** Text-bearing row the assistant editor saves to (grouped turns). */
+    editTarget: {
+        content: string;
+        messageId: string;
+        isStructuredRaw: boolean;
+    } | null;
+    streamRequestId: string | null;
+    contentHistoryCount: number;
+    showFullPrint: boolean;
+    isCapturing: boolean;
+    groupMessageIds: string[];
+}
+export interface ContentSourceAdapter {
+    /**
+     * Persist edited content back to the source. Implementations dispatch the
+     * appropriate thunk or call the service. For chat-message this dispatches
+     * editMessage; for note this calls NotesAPI.update; etc.
+     */
+    edit?: (args: {
+        newContent: string;
+        /**
+         * The text the editor opened on, when that was a DISPLAY projection rather
+         * than the stored bytes (chat: whitespace-normalized) — the adapter then
+         * splices only the changed span into what is stored.
+         */
+        previousContent?: string;
+        source: ContentSource;
+        dispatch: AppDispatch;
+    }) => Promise<void | NoteSaveReceipt | ChatAnswerSaveReceipt>;
+    /**
+     * Resolves an action's editable snapshot before an overlay or callback group
+     * exists. Non-note adapters may omit this; Notes uses it to turn an identity
+     * trigger into one authorized, actor-bound physical snapshot.
+     */
+    prepareEdit?: (args: {
+        source: ContentSource;
+        actionText: string;
+        dispatch: AppDispatch;
+        isAuthenticated: boolean;
+    }) => Promise<{
+        source: ContentSource;
+        content: string;
+    }>;
+    /** Delete the source record. */
+    delete?: (args: {
+        source: ContentSource;
+        dispatch: AppDispatch;
+    }) => Promise<void> | void;
+    /** Re-run / regenerate the content (prompt-result only at first). */
+    reRun?: (args: {
+        source: ContentSource;
+        dispatch: AppDispatch;
+    }) => Promise<void> | void;
+    /**
+     * Returns a stable, source-specific prefix used to build overlay
+     * instanceIds. Example for note: `note-${noteId}`. Implementations should
+     * include enough of the source identifier that two distinct sources never
+     * collide. Used by ctx.instanceKey(prefix).
+     */
+    instanceKeyPrefix: (source: ContentSource) => string;
+}
+export interface PreparedContentEdit {
+    source: ContentSource;
+    /** Always the complete displayed physical body for prepared Notes sources. */
+    content: string;
+}
+export interface RichDocumentActionContextCallbacks {
+    /** Notify the host that the user committed an edit. Used by chat to route
+     * through OverlayController's atomic edit path (no closure in Redux). */
+    onEdit?: (newContent: string) => void;
+    /** Trigger the parent's full-page print pipeline (chat only today). */
+    onFullPrint?: () => void;
+    /** Open the host-owned destructive-vs-fork dialog (chat only today). */
+    onRequestDelete?: () => void;
+    /** Open the host-owned edit-history dialog (chat only today). */
+    onRequestEditHistory?: () => void;
+    /** Open the host-owned ConvertContentDialog (the ONE convert-source dialog). */
+    onRequestConvert?: () => void;
+    /** Open the host-owned "save as flashcard" prompt (the text is the answer). */
+    onRequestFlashcard?: (answer: string) => void;
+    /**
+     * Run one of a text field's own AI powers (clean up, help with this, custom
+     * agent). Only a host that can APPLY a result back into the text supplies
+     * it — ProTextarea today — so elsewhere those actions are absent.
+     */
+    onRequestTextAgentAction?: (actionId: "cleanup" | "help" | "customAgent", ctx: RichDocumentActionContext) => void;
+    /**
+     * The saved record this content is (`token:id`) when the source does not say —
+     * the studio previewing a loaded document over a raw source. The ⋯ "Notes &
+     * comments" row reads it (annotations/RecordAnnotations).
+     */
+    annotationRecordKey?: () => string | null;
+    /**
+     * The rows this content already IS — a transcript's lines, a thread's messages — for content
+     * whose text has no table shape of its own. "Save to a table" offers them (typed columns) when
+     * neither the selection nor the text reads as rows. `selection` is the selected words, when any,
+     * so the host can narrow to that part; null or [] means "nothing to offer".
+     */
+    tableRows?: (selection: string | null) => ReadonlyArray<Record<string, unknown>> | null;
+    /**
+     * The rendered table the right-click landed on, as table text with its shape kept (header +
+     * rows) — set by the context-menu shell from the clicked element, so "Save to a table" opens on
+     * THAT table, not on the first list or table in the whole answer. Null when the click was not
+     * inside a table.
+     */
+    tableAtTarget?: () => string | null;
+}
+/** What a chat-answer save actually wrote (RC-B5) — the source of any "saved" sentence. */
+export interface ChatAnswerSaveReceipt {
+    kind: "chat-answer";
+    written: boolean;
+    /** Places (lines) of the answer that changed; everything else is byte-identical. */
+    changedSpans: number;
+    /** The change touched most of the answer — reported as a rewrite, not a count. */
+    mostlyRewritten: boolean;
+}
+export interface RichDocumentActionContext {
+    content: string;
+    source: ContentSource;
+    metadata: Record<string, unknown> | null;
+    dispatch: AppDispatch;
+    /** Synchronous store read — titles, the answered question, org, roles. */
+    getState: () => RootState;
+    /** Active organization supplied by the action host for note writes. */
+    organizationId: string | null;
+    isAuthenticated: boolean;
+    isAdmin: boolean;
+    isCreator: boolean;
+    surfaceKey: string | null;
+    onClose: () => void;
+    /** Build an overlay instanceId stable per source — e.g. `save-notes-${noteId}`. */
+    instanceKey: (prefix: string) => string;
+    /** Source-specific edit/delete/re-run bridge. */
+    sourceAdapter: ContentSourceAdapter;
+    /** Per-instance callbacks the host wants to plug in. */
+    callbacks?: RichDocumentActionContextCallbacks;
+    /** Source-specific extensions. Discriminated so chat-only fields don't pollute the base shape. */
+    extensions?: SourceExtensions;
+    /**
+     * The scope the right-click menu captured for this open (selection, whole
+     * content, text around it, every surface value). Absent on bars.
+     */
+    applicationScope?: ApplicationScope;
+}
+export interface RichDocumentAction {
+    /** Unique ID. Built-ins use RichDocumentActionId; extras may use any string. */
+    id: RichDocumentActionId | string;
+    label: string | ((ctx: RichDocumentActionContext) => string);
+    icon: LucideIcon;
+    /**
+     * Optional Tailwind color class(es) applied to the icon. Preserves the
+     * per-action visual variety from the legacy registry (text-blue-500
+     * dark:text-blue-400, etc.). Variant renderers may ignore this if they
+     * have a stricter visual system.
+     */
+    iconColor?: string;
+    category: ActionCategory;
+    /** Which source types this action operates on. "*" = all sources. */
+    supportedSources: ContentSourceType[] | "*";
+    /** Optional show predicate. Default: true. */
+    visible?: (ctx: RichDocumentActionContext) => boolean;
+    /** Optional disabled predicate. Returns boolean OR a reason for tooltips. */
+    disabled?: (ctx: RichDocumentActionContext) => boolean | {
+        reason: string;
+    };
+    /** The handler. May be async. */
+    run: (ctx: RichDocumentActionContext) => void | Promise<void>;
+    /**
+     * Default render slot.
+     * "primary" — inline bar only.
+     * "overflow" — ⋯ menu only.
+     * "both" — mirrored in both.
+     * Default: "overflow".
+     */
+    renderSlot?: "primary" | "overflow" | "both";
+    /** Default sort weight within category (lower = earlier). */
+    order?: number;
+    /** Action requires authentication. Hidden when isAuthenticated is false. */
+    requiresAuth?: boolean;
+    /**
+     * The action changes the SOURCE record (edit, delete, fork, pin, regenerate,
+     * apply an AI result…). Absent on a read-only source.
+     */
+    writesSource?: boolean;
+    /**
+     * A toggle's live state (a thumb's verdict, read-aloud playing). Renderers
+     * paint the action "on" (its iconColor, aria-pressed) only while true; an
+     * action with `active` defined reads as muted otherwise.
+     */
+    active?: (ctx: RichDocumentActionContext) => boolean;
+    /**
+     * A toggle's live glyph (read-aloud: Pause while playing, Play while paused,
+     * a spinner while starting). Null/absent = the static `icon`.
+     */
+    stateIcon?: (ctx: RichDocumentActionContext) => {
+        icon: LucideIcon;
+        spin?: boolean;
+    } | null;
+    /**
+     * Subscribe to whatever `active`/`label` read (a module store). Called by
+     * the renderer; returns the unsubscribe. May also start a hydration read.
+     */
+    subscribe?: (onChange: () => void, ctx: RichDocumentActionContext) => () => void;
+    /**
+     * Keep the reader's text selection alive through the click (mousedown would
+     * clear it) — read-aloud reads the selection when there is one.
+     */
+    preserveSelection?: boolean;
+}
+export type RichDocumentActionsVariant = 
+/** Full inline action bar with primary buttons + overflow menu. */
+"bar"
+/** Condensed icons-only bar + overflow. */
+ | "mini-bar"
+/** Single ⋯ overflow button, all actions in dropdown. */
+ | "menu"
+/** Single ⋯ trigger — same renderer as "menu", named for absolute/hover use. */
+ | "icon-only"
+/** No inline UI — registers to a remote <RichDocumentActionSurface/>. */
+ | "remote"
+/** Hide actions entirely. */
+ | "none";
+/** Where the action surface sits relative to the content. */
+export type RichDocumentActionsPosition = 
+/** In-flow, below the content (default). */
+"below"
+/** In-flow, above the content. */
+ | "above"
+/** Absolutely positioned, layered over the content. */
+ | "top-right" | "top-left" | "middle-right" | "middle-left";
+/** Visibility behavior of the action surface. */
+export type RichDocumentActionsBehavior = 
+/** Always visible (default). */
+"always"
+/** Hidden until the content is hovered/focused (fades in). */
+ | "hover-only";
+export interface RichDocumentActionsProp {
+    /** Built-in action IDs (or custom IDs) to hide. All built-ins included by default. */
+    exclude?: (RichDocumentActionId | string)[];
+    /** Custom actions appended to the registry. Typically open an overlay via dispatch. */
+    extra?: RichDocumentAction[];
+    /** Optional callbacks the registry's handlers can call. */
+    callbacks?: RichDocumentActionContextCallbacks;
+    /** Source-specific extensions to merge into the context. */
+    extensions?: SourceExtensions;
+    /** Source metadata (cx_message.metadata, …) — rides into saves/exports. */
+    metadata?: Record<string, unknown> | null;
+    /** Viewer owns the agent that produced the content (creator tools). */
+    isCreator?: boolean;
+    /** UI surface the host belongs to — fork/delete outcomes route through it. */
+    surfaceKey?: string | null;
+}
+/**
+ * A snapshot of action metadata stored in Redux for a remote surface.
+ *
+ * Intentionally CONTAINS NO FUNCTIONS — handlers, getters, and callbacks are
+ * kept out of Redux state. The renderer looks up handlers by `id` from the
+ * in-memory registry at render time, using the live getters supplied via the
+ * provider's imperative API (registered on mount, kept in module scope).
+ */
+export interface RichDocumentActionSpec {
+    id: RichDocumentActionId | string;
+    label: string;
+    iconName: string;
+    category: ActionCategory;
+    renderSlot: "primary" | "overflow" | "both";
+    order: number;
+    disabled: boolean;
+    disabledReason?: string;
+}
+export interface RichDocumentSurfaceRegistration {
+    /** Stable per-instance ID generated by the registering RichDocument. */
+    providerId: string;
+    /** Pure metadata; no functions. Registration order is encoded by the
+     * provider stack's array order, so no timestamp is needed. */
+    computedActionSpecs: RichDocumentActionSpec[];
+    /** Render-safe canonical identity for transfer workspace cache ownership. */
+    contentSourceId: string;
+    /** The source type — useful for the renderer to label the surface. */
+    sourceType: ContentSourceType;
+}
+export {};

package/dist/rich-document/variants/ActionBar.d.ts

@@ -0,0 +1,17 @@
+import * as React from "react";
+import type { ClickTarget } from "@ai-matrx/alchemy/actions";
+import type { RichDocumentAction, RichDocumentActionContext } from "../types.js";
+export interface ActionBarProps {
+    actions: RichDocumentAction[];
+    getCtx: () => RichDocumentActionContext;
+    /** The click target the host built (`richDocumentClickTarget`). */
+    target: ClickTarget;
+    sourceId: string;
+    className?: string;
+    /** Hide the ⋯ overflow (a host setting turned the options off). */
+    hideOverflow?: boolean;
+    /** Condensed presentation (the "mini-bar" variant). */
+    mini?: boolean;
+}
+export declare function ActionBar(props: ActionBarProps): React.ReactElement;
+export default ActionBar;

package/dist/rich-document/variants/ActionBar.js

@@ -0,0 +1,48 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { ActionBar as AlchemyActionBar } from "@ai-matrx/alchemy/react/bar";
+import { useRichDocumentProvider } from "../actions/useRichDocumentProvider.js";
+import { cn } from "@ai-matrx/design-system";
+import { AlchemyDocumentMenu } from "./shared/AlchemyDocumentMenu.js";
+import { OpenOneMenuButton, useOneMenuFor } from "./shared/OpenOneMenuButton.js";
+import { StandaloneOneMenu } from "./shared/StandaloneOneMenu.js";
+const BAR_RESTRICT = { exclude: ["copy"] };
+function ActionBar(props) {
+  const { actions, getCtx, target, sourceId, className, hideOverflow = false, mini = false } = props;
+  useRichDocumentProvider();
+  const oneMenu = useOneMenuFor(getCtx().source);
+  const hasCopy = actions.some((action) => action.category === "copy");
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className: cn(
+        // flex-wrap, never squeeze: a host narrower than the row (the compact
+        // modal, the Chat window at 375) wrapped nothing, so the 44px touch
+        // targets shrank-and-spilled under the ⋯ — tapping 👍 opened the menu.
+        // Wrapping keeps every target whole and apart (guard:
+        // answer-bar-targets-never-overlap).
+        mini ? "inline-flex max-w-full flex-wrap items-center gap-0.5 px-0.5 py-0.5" : "inline-flex max-w-full flex-wrap items-center gap-1 px-1 py-1",
+        className
+      ),
+      children: [
+        hasCopy ? /* @__PURE__ */ jsx(AlchemyDocumentMenu, { getCtx, sourceId, size: mini ? "xs" : "sm" }, sourceId) : null,
+        /* @__PURE__ */ jsx(
+          AlchemyActionBar,
+          {
+            target,
+            mini,
+            restrict: BAR_RESTRICT,
+            className: "flex-wrap",
+            hideOverflow: true
+          }
+        ),
+        hideOverflow ? null : oneMenu ? /* @__PURE__ */ jsx(OpenOneMenuButton, { source: getCtx().source }) : /* @__PURE__ */ jsx(StandaloneOneMenu, { getCtx, target })
+      ]
+    }
+  );
+}
+var ActionBar_default = ActionBar;
+export {
+  ActionBar,
+  ActionBar_default as default
+};

package/dist/rich-document/variants/MenuVariant.d.ts

@@ -0,0 +1,15 @@
+import * as React from "react";
+import type { ClickTarget } from "@ai-matrx/alchemy/actions";
+import type { RichDocumentActionContext } from "../types.js";
+export interface MenuVariantProps {
+    getCtx: () => RichDocumentActionContext;
+    target: ClickTarget;
+    className?: string;
+}
+/**
+ * "menu" / "icon-only" — a single ⋯ that opens THE ONE context-menu engine:
+ * the enclosing right-click menu for this content, else a shell of the same
+ * content. Desktop dropdown and phone sheet are that engine's layouts.
+ */
+export declare function MenuVariant(props: MenuVariantProps): React.ReactElement;
+export default MenuVariant;

package/dist/rich-document/variants/MenuVariant.js

@@ -0,0 +1,17 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { useRichDocumentProvider } from "../actions/useRichDocumentProvider.js";
+import { cn } from "@ai-matrx/design-system";
+import { OpenOneMenuButton, useOneMenuFor } from "./shared/OpenOneMenuButton.js";
+import { StandaloneOneMenu } from "./shared/StandaloneOneMenu.js";
+function MenuVariant(props) {
+  const { getCtx, target, className } = props;
+  useRichDocumentProvider();
+  const oneMenu = useOneMenuFor(getCtx().source);
+  return /* @__PURE__ */ jsx("div", { className: cn("inline-flex items-center", className), children: oneMenu ? /* @__PURE__ */ jsx(OpenOneMenuButton, { source: getCtx().source }) : /* @__PURE__ */ jsx(StandaloneOneMenu, { getCtx, target }) });
+}
+var MenuVariant_default = MenuVariant;
+export {
+  MenuVariant,
+  MenuVariant_default as default
+};

package/dist/rich-document/variants/MiniActionBar.d.ts

@@ -0,0 +1,5 @@
+import * as React from "react";
+import { type ActionBarProps } from "./ActionBar.js";
+export type MiniActionBarProps = Omit<ActionBarProps, "mini" | "hideOverflow">;
+export declare function MiniActionBar(props: MiniActionBarProps): React.ReactElement;
+export default MiniActionBar;

package/dist/rich-document/variants/MiniActionBar.js

@@ -0,0 +1,11 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { ActionBar } from "./ActionBar.js";
+function MiniActionBar(props) {
+  return /* @__PURE__ */ jsx(ActionBar, { ...props, mini: true });
+}
+var MiniActionBar_default = MiniActionBar;
+export {
+  MiniActionBar,
+  MiniActionBar_default as default
+};

package/dist/rich-document/variants/RegistryActionList.d.ts

@@ -0,0 +1,17 @@
+import * as React from "react";
+import type { ContentSource, RichDocumentActionsProp } from "../types.js";
+export interface RegistryActionListProps {
+    content: string;
+    source: ContentSource;
+    actions?: RichDocumentActionsProp;
+    /** Called after a row runs (the host closes its popover). */
+    onClose: () => void;
+    /**
+     * The host's own AI rows (ProTextarea's bound agents) — rendered INSIDE the
+     * "Improve with AI" group, never as a parallel AI family.
+     */
+    aiSlot?: React.ReactNode;
+    className?: string;
+}
+export declare function RegistryActionList(props: RegistryActionListProps): React.ReactElement | null;
+export default RegistryActionList;

package/dist/rich-document/variants/RegistryActionList.js

@@ -0,0 +1,94 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { ChevronRight } from "lucide-react";
+import { cn } from "@ai-matrx/design-system";
+import { useActionSurfaceProvider } from "../runtime/useActionSurfaceProvider.js";
+import {
+  AI_SUBMENU_LABEL,
+  buildMenuTree,
+  withAiSlot
+} from "./shared/menuStructure.js";
+import { resolveActionDisplay, runAction } from "./shared/runAction.js";
+import { menuActions } from "./RegistryActionMenu.js";
+const ROW = "flex w-full items-center gap-2 rounded-sm px-2 py-1.5 text-left text-sm text-foreground transition-colors hover:bg-accent hover:text-accent-foreground disabled:opacity-50";
+function RegistryActionList(props) {
+  const { content, source, actions, onClose, className, aiSlot } = props;
+  const { ctx, getCtx, resolvedActions } = useActionSurfaceProvider({
+    content,
+    source,
+    actions,
+    actionsVariant: "none"
+  });
+  const [openGroup, setOpenGroup] = React.useState(null);
+  const getListCtx = () => ({
+    ...getCtx(),
+    onClose
+  });
+  const tree = buildMenuTree(menuActions(resolvedActions), { aiSlot: Boolean(aiSlot) });
+  const submenus = withAiSlot(tree.submenus, Boolean(aiSlot));
+  if (!aiSlot && tree.topLevel.length === 0 && tree.submenus.length === 0 && tree.extras.length === 0) {
+    return null;
+  }
+  const row = (action, nested = false) => {
+    const display = resolveActionDisplay(action, ctx);
+    const Icon = display.Icon;
+    return /* @__PURE__ */ jsxs(
+      "button",
+      {
+        type: "button",
+        disabled: display.isDisabled,
+        title: display.disabledReason,
+        onClick: () => {
+          runAction(action, getListCtx);
+          if (action.category !== "ai") onClose();
+        },
+        className: cn(ROW, nested && "pl-7"),
+        children: [
+          /* @__PURE__ */ jsx(Icon, { className: cn("h-4 w-4 shrink-0", display.iconColor) }),
+          /* @__PURE__ */ jsx("span", { className: "truncate", children: display.label })
+        ]
+      },
+      action.id
+    );
+  };
+  return /* @__PURE__ */ jsxs("div", { className: cn("flex flex-col", className), children: [
+    tree.topLevel.map((a) => row(a)),
+    submenus.map((submenu) => {
+      const Icon = submenu.icon ?? submenu.actions[0]?.icon ?? ChevronRight;
+      const isOpen = openGroup === submenu.label;
+      return /* @__PURE__ */ jsxs(React.Fragment, { children: [
+        /* @__PURE__ */ jsxs(
+          "button",
+          {
+            type: "button",
+            "aria-expanded": isOpen,
+            onClick: () => setOpenGroup(isOpen ? null : submenu.label),
+            className: ROW,
+            children: [
+              /* @__PURE__ */ jsx(Icon, { className: "h-4 w-4 shrink-0 text-muted-foreground" }),
+              /* @__PURE__ */ jsx("span", { className: "flex-1 truncate", children: submenu.label }),
+              /* @__PURE__ */ jsx(
+                ChevronRight,
+                {
+                  className: cn(
+                    "h-3.5 w-3.5 text-muted-foreground transition-transform",
+                    isOpen && "rotate-90"
+                  )
+                }
+              )
+            ]
+          }
+        ),
+        isOpen ? submenu.actions.map((a) => row(a, true)) : null,
+        isOpen && submenu.label === AI_SUBMENU_LABEL && aiSlot ? /* @__PURE__ */ jsx("div", { className: "pl-5", children: aiSlot }) : null
+      ] }, submenu.label);
+    }),
+    tree.extras.map((a) => row(a))
+  ] });
+}
+var RegistryActionList_default = RegistryActionList;
+export {
+  RegistryActionList,
+  RegistryActionList_default as default
+};

package/dist/rich-document/variants/RegistryActionMenu.d.ts

@@ -0,0 +1,24 @@
+import * as React from "react";
+import { type MenuItem } from "../../host/app-bindings.js";
+import { registryMenuActions } from "./shared/menuStructure.js";
+import type { ContentSource, RichDocumentAction, RichDocumentActionContext, RichDocumentActionsProp } from "../types.js";
+export interface RegistryActionMenuProps {
+    isOpen: boolean;
+    onClose: () => void;
+    content: string;
+    source: ContentSource;
+    actions?: RichDocumentActionsProp;
+    anchorElement?: HTMLElement | null;
+    title?: string;
+}
+/** Overflow-slot actions only — the host renders the primary row inline. */
+/** The one menu selector (shared/menuStructure.ts). */
+export declare const menuActions: typeof registryMenuActions;
+/** The registry tree → AdvancedMenu rows (submenus become drill-in rows). */
+export declare function toAdvancedMenuItems(actions: RichDocumentAction[], 
+/** Render-time context — labels and disabled state only. */
+ctx: RichDocumentActionContext, 
+/** Click-time context factory — what handlers run against. */
+getCtx: () => RichDocumentActionContext): MenuItem[];
+export declare function RegistryActionMenu(props: RegistryActionMenuProps): React.ReactElement;
+export default RegistryActionMenu;