@ai-matrx/rich-content 0.2.10 → 0.2.16

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

@@ -0,0 +1,78 @@
+import * as React from "react";
+import { type SpecimenMode } from "../display/specimen/SpecimenContext.js";
+import type { ContentSource, RichDocumentAction, RichDocumentActionId, RichDocumentActionsProp, RichDocumentActionsVariant, RichDocumentActionsPosition, RichDocumentActionsBehavior } from "./types.js";
+import type { AnnotationRecord, ServerProcessedBlock } from "./host-types.js";
+import type { TypedStreamEvent } from "../display/chat-markdown/types.js";
+export interface RichDocumentProps {
+    content?: string;
+    events?: TypedStreamEvent[];
+    serverProcessedBlocks?: ServerProcessedBlock[];
+    taskId?: string;
+    requestId?: string;
+    turnId?: string;
+    conversationId?: string;
+    isStreamActive?: boolean;
+    /** Required. Use { type: "raw" } when the source is genuinely unknown. */
+    source: ContentSource;
+    renderer?: "basic" | "configurable" | "stream";
+    actions?: RichDocumentActionsProp;
+    actionsVariant?: RichDocumentActionsVariant;
+    /** Where the action surface sits. Default "below". */
+    actionsPosition?: RichDocumentActionsPosition;
+    /** Visibility. Default "always". */
+    actionsBehavior?: RichDocumentActionsBehavior;
+    /** Required when actionsVariant === "remote". */
+    actionsSurfaceId?: string;
+    /**
+     * DECLARE that this content is a specimen — generated work that is meant to
+     * look right and be wrong (the Bad Example probe, a wrong explanation, a
+     * decoy option). Suppresses every action surface, the right-click menu, and
+     * the actions inside the content itself (table export / workbook / Google
+     * Sheet / edit / open-in-window), and prints the specimen banner in their
+     * place. Pass `true` for the default wording, or override the two lines.
+     * See @ai-matrx/rich-content/display/specimen/SpecimenContext.tsx.
+     */
+    specimen?: boolean | Partial<SpecimenMode>;
+    /**
+     * Enable a right-click context menu over the content. Lazy-loaded (the
+     * menu chunk only ships after the first right-click) and streaming-safe
+     * (yields to the native browser menu while isStreamActive). Pass an object
+     * to add context-menu-only `extra` actions or `exclude` specific ones.
+     * This is the extension point for future per-surface right-click actions.
+     */
+    enableContextMenu?: boolean | {
+        extra?: RichDocumentAction[];
+        exclude?: (RichDocumentActionId | string)[];
+    };
+    /**
+     * The SAVED RECORD this content is, for the reading set (highlight, comment,
+     * suggest, link) and its Notes & comments dock. Derived from `source` for a
+     * note, a chat answer and a saved working document; pass it when the source
+     * does not say (the studio previewing a loaded document), or `null` to turn
+     * the reading set off. A read-only copy, a stream in flight and a specimen
+     * never get one.
+     */
+    annotationRecord?: AnnotationRecord | null;
+    className?: string;
+    contentClassName?: string;
+    actionsClassName?: string;
+    onContentChange?: (newContent: string) => void;
+    applyLocalEdits?: boolean;
+    analysisData?: unknown;
+    messageId?: string;
+    allowFullScreenEditor?: boolean;
+    hideCopyButton?: boolean;
+    onError?: (error: string) => void;
+    onPhaseUpdate?: (phase: string) => void;
+    strictServerData?: boolean;
+    /**
+     * WHO WROTE this content — "ai" (a model), "other" (someone else) or "self"
+     * (the viewer). Decides whether remote images load by themselves
+     * (components/rich-content/prose/remote-image-policy.tsx, chair ruling
+     * 2026-09-25). Declare it at every call site — guard:
+     * components/rich-content/__tests__/image-policy-declared.test.ts.
+     */
+    imagePolicy?: "self" | "other" | "ai" | "inherit";
+}
+export declare function RichDocument(props: RichDocumentProps): React.ReactElement;
+export default RichDocument;

package/dist/rich-document/RichDocument.js

@@ -0,0 +1,218 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { cn } from "@ai-matrx/design-system";
+import { useActionSurfaceProvider } from "./runtime/useActionSurfaceProvider.js";
+import { RegistryContextMenu } from "./RegistryContextMenu.js";
+import { getSourceAdapter } from "./actions/sources/index.js";
+import {
+  convertOriginForSource,
+  useDocumentDialogsHost,
+  RecordAnnotations,
+  annotationRecordOf,
+  recordKeyOf,
+  MarkdownStream
+} from "../host/app-bindings.js";
+import { ActionBar } from "./variants/ActionBar.js";
+import { MiniActionBar } from "./variants/MiniActionBar.js";
+import { MenuVariant } from "./variants/MenuVariant.js";
+import { contextMenuFor } from "./runtime/contextMenuFor.js";
+import {
+  SpecimenProvider,
+  SpecimenBanner,
+  resolveSpecimenMode
+} from "../display/specimen/SpecimenContext.js";
+function RichDocument(props) {
+  const {
+    source,
+    actions: actionsProp,
+    actionsVariant = "none",
+    actionsPosition = "below",
+    actionsBehavior = "always",
+    actionsSurfaceId,
+    specimen,
+    enableContextMenu,
+    className,
+    contentClassName,
+    actionsClassName,
+    content,
+    events,
+    serverProcessedBlocks,
+    taskId,
+    requestId,
+    turnId,
+    conversationId,
+    isStreamActive,
+    onContentChange,
+    applyLocalEdits,
+    analysisData,
+    messageId,
+    allowFullScreenEditor,
+    hideCopyButton,
+    onError,
+    onPhaseUpdate,
+    strictServerData,
+    imagePolicy,
+    annotationRecord
+  } = props;
+  const specimenMode = resolveSpecimenMode(specimen);
+  const effectiveActionsVariant = specimenMode ? "none" : actionsVariant;
+  const dialogsHost = useDocumentDialogsHost({
+    convertOrigin: convertOriginForSource(
+      source,
+      source.type === "note" ? "Note" : "Chat response"
+    ),
+    text: content ?? "",
+    // Clean up / Help / Custom agent need somewhere to APPLY the result.
+    writable: !source.readOnly && Boolean(getSourceAdapter(source.type).edit) && !(actionsProp?.extensions?.type === "chat-message" && (actionsProp.extensions.contentIsStructuredRaw || actionsProp.extensions.role === "user")),
+    chatMessage: source.type === "chat-message" && !source.readOnly ? {
+      conversationId: source.conversationId,
+      messageId: source.messageId,
+      surfaceKey: actionsProp?.surfaceKey ?? null
+    } : null
+  });
+  const record = annotationRecord !== void 0 ? annotationRecord : source.readOnly ? null : annotationRecordOf(source);
+  const hostedActions = {
+    ...actionsProp,
+    callbacks: {
+      ...dialogsHost.callbacks,
+      // A host that names its record explicitly (the studio's loaded document
+      // rides a raw source) tells the ⋯ "Notes & comments" row which dock it is.
+      ...record && annotationRecord !== void 0 ? { annotationRecordKey: () => recordKeyOf(record) } : {},
+      ...actionsProp?.callbacks
+    }
+  };
+  const { ctx, getCtx, resolvedActions, target } = useActionSurfaceProvider({
+    content,
+    source,
+    actions: hostedActions,
+    actionsVariant: effectiveActionsVariant,
+    actionsSurfaceId
+  });
+  let variantNode = null;
+  switch (effectiveActionsVariant) {
+    case "bar":
+      variantNode = /* @__PURE__ */ jsx(
+        ActionBar,
+        {
+          actions: resolvedActions,
+          getCtx,
+          target,
+          sourceId: ctx.instanceKey("alchemy")
+        }
+      );
+      break;
+    case "mini-bar":
+      variantNode = /* @__PURE__ */ jsx(
+        MiniActionBar,
+        {
+          actions: resolvedActions,
+          getCtx,
+          target,
+          sourceId: ctx.instanceKey("alchemy")
+        }
+      );
+      break;
+    case "menu":
+    case "icon-only":
+      variantNode = /* @__PURE__ */ jsx(MenuVariant, { getCtx, target });
+      break;
+    case "remote":
+    case "none":
+    default:
+      variantNode = null;
+  }
+  const isAbsolute = actionsPosition === "top-right" || actionsPosition === "top-left" || actionsPosition === "middle-right" || actionsPosition === "middle-left";
+  const absolutePositionClass = isAbsolute ? cn(
+    "absolute z-10",
+    actionsPosition === "top-right" && "right-1 top-1",
+    actionsPosition === "top-left" && "left-1 top-1",
+    actionsPosition === "middle-right" && "right-1 top-1/2 -translate-y-1/2",
+    actionsPosition === "middle-left" && "left-1 top-1/2 -translate-y-1/2"
+  ) : null;
+  const hoverClass = actionsBehavior === "hover-only" ? "opacity-0 transition-opacity group-hover:opacity-100 focus-within:opacity-100" : null;
+  const inFlowClass = !isAbsolute ? actionsPosition === "above" ? "mb-1" : "mt-1" : null;
+  const actionsNode = variantNode ? /* @__PURE__ */ jsx(
+    "div",
+    {
+      className: cn(
+        absolutePositionClass,
+        hoverClass,
+        inFlowClass,
+        actionsClassName
+      ),
+      children: variantNode
+    }
+  ) : null;
+  const rootClassName = cn(
+    "rich-document",
+    (isAbsolute || actionsBehavior === "hover-only") && "relative group",
+    className
+  );
+  const annotationSource = record && !specimenMode && !isStreamActive && typeof content === "string" && content.trim() ? {
+    token: record.token,
+    id: record.id,
+    title: record.title ?? "",
+    body: content,
+    contentVersion: Math.max(1, record.contentVersion ?? 1),
+    ...record.href ? { href: record.href } : {},
+    ...record.conversationId ? { conversationId: record.conversationId } : {}
+  } : null;
+  const engineInner = /* @__PURE__ */ jsx(RecordAnnotations, { record: annotationSource, children: /* @__PURE__ */ jsx("div", { className: cn("rich-document__content", contentClassName), children: /* @__PURE__ */ jsx(
+    MarkdownStream,
+    {
+      imagePolicy,
+      content,
+      events,
+      serverProcessedBlocks,
+      taskId,
+      requestId,
+      turnId,
+      conversationId,
+      isStreamActive,
+      onContentChange,
+      applyLocalEdits,
+      analysisData,
+      messageId,
+      allowFullScreenEditor,
+      hideCopyButton,
+      onError,
+      onPhaseUpdate,
+      strictServerData
+    }
+  ) }) });
+  let engine = engineInner;
+  const contextMenu = contextMenuFor(enableContextMenu, effectiveActionsVariant);
+  if (contextMenu && !specimenMode) {
+    const cmOptions = typeof contextMenu === "object" ? contextMenu : {};
+    engine = /* @__PURE__ */ jsx(
+      RegistryContextMenu,
+      {
+        content: content ?? "",
+        source,
+        actions: hostedActions,
+        extra: cmOptions.extra,
+        exclude: cmOptions.exclude,
+        suppressed: isStreamActive,
+        children: engineInner
+      }
+    );
+  }
+  if (specimenMode) {
+    return /* @__PURE__ */ jsxs("div", { className: rootClassName, children: [
+      /* @__PURE__ */ jsx(SpecimenBanner, { mode: specimenMode }),
+      /* @__PURE__ */ jsx(SpecimenProvider, { value: specimenMode, children: engine })
+    ] });
+  }
+  return /* @__PURE__ */ jsxs("div", { className: rootClassName, children: [
+    isAbsolute ? actionsNode : null,
+    !isAbsolute && actionsPosition === "above" ? actionsNode : null,
+    engine,
+    !isAbsolute && actionsPosition !== "above" ? actionsNode : null,
+    dialogsHost.dialogs
+  ] });
+}
+var RichDocument_default = RichDocument;
+export {
+  RichDocument,
+  RichDocument_default as default
+};

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

@@ -0,0 +1,18 @@
+import * as React from "react";
+import type { ContentSource, RichDocumentActionsProp } from "./types.js";
+export interface RichDocumentActionProviderProps {
+    /** Live content the actions operate on (re-read at click time via the bridge). */
+    content: string;
+    /** Source identity — drives which actions show + save-to-task parent linking. */
+    source: ContentSource;
+    /** The surface a <RichDocumentActionSurface/> consumes. Required. */
+    surfaceId: string;
+    /** Trim/extend the action set + supply host callbacks (same shape as RichDocument). */
+    actions?: RichDocumentActionsProp;
+}
+/**
+ * Registers a remote RichDocument action provider for `surfaceId`. Renders
+ * nothing. See the file header for when to reach for this over RichDocument.
+ */
+export declare function RichDocumentActionProvider(props: RichDocumentActionProviderProps): React.ReactElement | null;
+export default RichDocumentActionProvider;

package/dist/rich-document/RichDocumentActionProvider.js

@@ -0,0 +1,18 @@
+"use client";
+import { useActionSurfaceProvider } from "./runtime/useActionSurfaceProvider.js";
+function RichDocumentActionProvider(props) {
+  const { content, source, surfaceId, actions } = props;
+  useActionSurfaceProvider({
+    content,
+    source,
+    actions,
+    actionsVariant: "remote",
+    actionsSurfaceId: surfaceId
+  });
+  return null;
+}
+var RichDocumentActionProvider_default = RichDocumentActionProvider;
+export {
+  RichDocumentActionProvider,
+  RichDocumentActionProvider_default as default
+};

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

@@ -0,0 +1,11 @@
+import * as React from "react";
+export interface RichDocumentActionSurfaceProps {
+    surfaceId: string;
+    /** Which inline variant to render. Defaults to "bar". */
+    variant?: "bar" | "mini-bar" | "menu";
+    className?: string;
+    /** Rendered when no provider is currently registered. */
+    fallback?: React.ReactNode;
+}
+export declare function RichDocumentActionSurface(props: RichDocumentActionSurfaceProps): React.ReactElement | null;
+export default RichDocumentActionSurface;

package/dist/rich-document/RichDocumentActionSurface.js

@@ -0,0 +1,59 @@
+"use client";
+import { Fragment, jsx } from "react/jsx-runtime";
+import { cn } from "@ai-matrx/design-system";
+import { useTopProvider } from "./runtime/actionSurfacesStore.js";
+import { getBridge } from "./runtime/providerBridge.js";
+import { ActionBar } from "./variants/ActionBar.js";
+import { MiniActionBar } from "./variants/MiniActionBar.js";
+import { MenuVariant } from "./variants/MenuVariant.js";
+function RichDocumentActionSurface(props) {
+  const { surfaceId, variant = "bar", className, fallback = null } = props;
+  const provider = useTopProvider(surfaceId);
+  if (!provider) {
+    return /* @__PURE__ */ jsx(Fragment, { children: fallback });
+  }
+  const bridge = getBridge(provider.providerId);
+  if (!bridge) {
+    return /* @__PURE__ */ jsx(Fragment, { children: fallback });
+  }
+  switch (variant) {
+    case "bar":
+      return /* @__PURE__ */ jsx(
+        ActionBar,
+        {
+          actions: bridge.resolvedActions,
+          getCtx: bridge.getCtx,
+          target: bridge.target,
+          sourceId: provider.contentSourceId,
+          className
+        }
+      );
+    case "mini-bar":
+      return /* @__PURE__ */ jsx(
+        MiniActionBar,
+        {
+          actions: bridge.resolvedActions,
+          getCtx: bridge.getCtx,
+          target: bridge.target,
+          sourceId: provider.contentSourceId,
+          className
+        }
+      );
+    case "menu":
+      return /* @__PURE__ */ jsx(
+        MenuVariant,
+        {
+          target: bridge.target,
+          getCtx: bridge.getCtx,
+          className: cn(className)
+        }
+      );
+    default:
+      return null;
+  }
+}
+var RichDocumentActionSurface_default = RichDocumentActionSurface;
+export {
+  RichDocumentActionSurface,
+  RichDocumentActionSurface_default as default
+};

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

@@ -0,0 +1,12 @@
+import * as React from "react";
+import type { ContentSource, RichDocumentActionsProp } from "./types.js";
+export interface RichDocumentActionsProps {
+    content: string;
+    source: ContentSource;
+    actions?: RichDocumentActionsProp;
+    className?: string;
+    /** Hide the ⋯ overflow menu (the primary row still renders). */
+    hideOverflow?: boolean;
+}
+export declare function RichDocumentActions(props: RichDocumentActionsProps): React.ReactElement;
+export default RichDocumentActions;

package/dist/rich-document/RichDocumentActions.js

@@ -0,0 +1,29 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { useActionSurfaceProvider } from "./runtime/useActionSurfaceProvider.js";
+import { ActionBar } from "./variants/ActionBar.js";
+function RichDocumentActions(props) {
+  const { content, source, actions, className, hideOverflow } = props;
+  const { ctx, getCtx, resolvedActions, target } = useActionSurfaceProvider({
+    content,
+    source,
+    actions,
+    actionsVariant: "bar"
+  });
+  return /* @__PURE__ */ jsx(
+    ActionBar,
+    {
+      actions: resolvedActions,
+      getCtx,
+      target,
+      sourceId: ctx.instanceKey("alchemy"),
+      className,
+      hideOverflow
+    }
+  );
+}
+var RichDocumentActions_default = RichDocumentActions;
+export {
+  RichDocumentActions,
+  RichDocumentActions_default as default
+};

package/dist/rich-document/actions/hostActions.d.ts

@@ -0,0 +1,5 @@
+import type { RichDocumentAction } from "../types.js";
+/** "Clear" — the host empties its own content (a transcript pad). */
+export declare function clearContentAction(onClear: () => void, label?: string): RichDocumentAction;
+/** A host copy that joins more than this content (transcript + cleaned text). */
+export declare function hostCopyAction(id: string, label: string, run: () => void | Promise<void>): RichDocumentAction;

package/dist/rich-document/actions/hostActions.js

@@ -0,0 +1,31 @@
+import { Files, Trash2 } from "lucide-react";
+function clearContentAction(onClear, label = "Clear") {
+  return {
+    id: "host:clear-content",
+    label,
+    icon: Trash2,
+    iconColor: "text-muted-foreground",
+    category: "edit",
+    supportedSources: "*",
+    renderSlot: "both",
+    order: 90,
+    run: () => onClear()
+  };
+}
+function hostCopyAction(id, label, run) {
+  return {
+    id: `host:${id}`,
+    label,
+    icon: Files,
+    iconColor: "text-muted-foreground",
+    category: "copy",
+    supportedSources: "*",
+    renderSlot: "both",
+    order: 80,
+    run: () => run()
+  };
+}
+export {
+  clearContentAction,
+  hostCopyAction
+};

package/dist/rich-document/actions/labels.d.ts

@@ -0,0 +1,9 @@
+/** The engine half of the rich-document action helpers (the host keeps its handler helpers). */
+import type { RichDocumentActionContext } from "../types.js";
+/** Storage key for "do this action after the person signs in" payloads. */
+export declare const PENDING_ACTION_KEY = "matrx_pending_post_auth_action";
+/**
+ * Resolve an action label to a string. Supports both static labels and `(ctx) => string`
+ * callbacks so labels like "Edit history (3)" can pull counts from the live context.
+ */
+export declare function resolveActionLabel(label: string | ((ctx: RichDocumentActionContext) => string), ctx: RichDocumentActionContext): string;

package/dist/rich-document/actions/labels.js

@@ -0,0 +1,8 @@
+const PENDING_ACTION_KEY = "matrx_pending_post_auth_action";
+function resolveActionLabel(label, ctx) {
+  return typeof label === "function" ? label(ctx) : label;
+}
+export {
+  PENDING_ACTION_KEY,
+  resolveActionLabel
+};

package/dist/rich-document/actions/markdownTable.d.ts

@@ -0,0 +1,9 @@
+export interface ParsedTable {
+    headers: string[];
+    rows: string[][];
+}
+export declare function cleanCell(text: string): string;
+/** The first markdown table in `content`, or null when there is none. */
+export declare function parseFirstMarkdownTable(content: string): ParsedTable | null;
+/** RFC 4180 CSV (comma) or TSV (tab) text for a parsed table. */
+export declare function tableToDelimited(table: ParsedTable, delimiter: "," | "\t"): string;

package/dist/rich-document/actions/markdownTable.js

@@ -0,0 +1,39 @@
+import { tableToCsv } from "../../display/tables/table-csv.js";
+import { unwrapCodeSpans } from "@ai-matrx/content-ir/source";
+import {
+  findTableEnd,
+  rowCells,
+  tableStartsAt,
+  unescapeCellPipes
+} from "../../display/markdown-classification/processors/utils/gfm-table-lines.js";
+function splitRow(line) {
+  return rowCells(line).map((cell) => cleanCell(unescapeCellPipes(cell)));
+}
+function cleanCell(text) {
+  return unwrapCodeSpans(text).replace(/\*\*([^*]+)\*\*/g, "$1").replace(/__([^_]+)__/g, "$1").replace(/\*([^*]+)\*/g, "$1").replace(/~~([^~]+)~~/g, "$1").replace(/\[([^\]]+)\]\(([^)]+)\)/g, "$1").replace(/<br\s*\/?>/gi, " ").trim();
+}
+function parseFirstMarkdownTable(content) {
+  const lines = content.split("\n");
+  for (let i = 0; i + 1 < lines.length; i += 1) {
+    if (!tableStartsAt(lines, i)) continue;
+    const headers = splitRow(lines[i]);
+    const rows = [];
+    const end = findTableEnd(lines, i);
+    for (let j = i + 2; j < end; j += 1) {
+      const cells = splitRow(lines[j]);
+      rows.push(headers.map((_, k) => cells[k] ?? ""));
+    }
+    return { headers, rows };
+  }
+  return null;
+}
+function tableToDelimited(table, delimiter) {
+  if (delimiter === ",") return tableToCsv(table.headers, table.rows);
+  const flat = (value) => value.replace(/[\t\r\n]+/g, " ");
+  return [table.headers, ...table.rows].map((row) => row.map(flat).join("	")).join("\n");
+}
+export {
+  cleanCell,
+  parseFirstMarkdownTable,
+  tableToDelimited
+};

package/dist/rich-document/actions/provider.d.ts

@@ -0,0 +1,58 @@
+import { type Action, type ActionProvider, type ClickTarget } from "@ai-matrx/alchemy/actions";
+import type { WriteTarget } from "@ai-matrx/alchemy/declare";
+import type { RichDocumentAction, RichDocumentActionContext, RichDocumentActionId } from "../types.js";
+export declare const RICH_DOCUMENT_PROVIDER_ID = "rich-document";
+/** The write target every source adapter serves (edit, delete, regenerate, fork…). */
+export declare const RICH_DOCUMENT_SOURCE_TARGET = "rich_document_source";
+export declare const SOURCE_WRITE_TARGET: WriteTarget;
+/** Register an action at module load. A duplicate id is refused. */
+export declare function registerAction(action: RichDocumentAction): void;
+/** Get one action by ID. Returns undefined if unregistered. */
+export declare function getAction(id: RichDocumentActionId | string): RichDocumentAction | undefined;
+/** Get all registered actions. */
+export declare function getAllActions(): RichDocumentAction[];
+/** The one id for a named menu group, shared with the context-menu provider. */
+export declare function richDocumentSectionId(label: string): string;
+export interface RichDocumentTargetHost {
+    kind: "rich-document";
+    /** Render-time context: labels, shown/hidden, toggle state. */
+    ctx: RichDocumentActionContext;
+    /** Click-time context factory: what handlers run against (live content). */
+    getCtx: () => RichDocumentActionContext;
+    /** This host's own actions (the `actions.extra` prop). */
+    extra: readonly RichDocumentAction[];
+}
+/** The rich-document half of a composite host, for hosts that build one. */
+export declare function richDocumentTargetHost(ctx: RichDocumentActionContext, options?: {
+    getCtx?: () => RichDocumentActionContext;
+    extra?: readonly RichDocumentAction[];
+}): RichDocumentTargetHost;
+/** THE ClickTarget for a rich-document context. */
+export declare function richDocumentClickTarget(ctx: RichDocumentActionContext, options?: {
+    getCtx?: () => RichDocumentActionContext;
+    exclude?: readonly string[];
+    extra?: readonly RichDocumentAction[];
+}): ClickTarget;
+export declare function toAlchemyAction(rd: RichDocumentAction): Action;
+/**
+ * Register this provider into the app's one registry, once per registry.
+ * Called by the rich-document layouts (the only hosts that need it), so the
+ * app's root host never imports the handler graph.
+ */
+export declare function ensureRichDocumentProvider(registry: {
+    register(p: ActionProvider): () => void;
+}): void;
+/** The provider registered into the app's Alchemy action registry. */
+export declare const richDocumentActionProvider: ActionProvider;
+/** Re-render hook for hosts: the list changed (a handler module loaded). */
+export declare function subscribeRichDocumentActions(listener: () => void): () => void;
+/**
+ * The actions eligible for a context — synchronously, through the package's
+ * ONE eligibility pass. Used where a host needs the list during render (the
+ * remote-surface spec snapshot, the code-block bridge, the parity tests).
+ * A host extra whose id collides with a built-in is refused (the built-in wins).
+ */
+export declare function resolveActions(ctx: RichDocumentActionContext, options?: {
+    exclude?: (RichDocumentActionId | string)[];
+    extra?: RichDocumentAction[];
+}): RichDocumentAction[];