@ai-matrx/rich-content 0.2.9 → 0.2.15

package/dist/host/app-bindings.d.ts

@@ -32,6 +32,21 @@ export interface RichContentAppBindings {
     useHostUser: HostFn;
     useIsAdminDebugger: HostFn;
     useIsAuthenticated: HostFn;
+    useHostDispatch: HostFn;
+    useHostGetState: HostFn;
+    useIsSuperAdmin: HostFn;
+    useActiveOrganizationId: HostFn;
+    holdDeliberateIntent: HostFn;
+    useAlchemyDisclosure: HostFn;
+    useRegistryMenuSource: HostFn;
+    sameContentSource: HostFn;
+    contentSourceKey: HostFn;
+    openContextMenuForElement: HostFn;
+    convertOriginForSource: HostFn;
+    useDocumentDialogsHost: HostFn;
+    RecordAnnotations: HostComponent;
+    annotationRecordOf: HostFn;
+    recordKeyOf: HostFn;
     useMermaidPreferences: HostFn;
     useSetMermaidPreferences: HostFn;
     useImageKnob: HostFn;
@@ -47,6 +62,7 @@ export interface RichContentAppBindings {
     MarkdownStream: HostComponent;
     CitationMarkerInline: HostComponent;
     InlineCopyButton: HostComponent;
+    CopyButtons: HostComponent;
     AdvancedMenu: HostComponent;
     useAdvancedMenu: HostFn;
     EntityRef: HostComponent;
@@ -127,8 +143,23 @@ export declare const KindInstanceRender: HostComponent;
 export declare const KindRecordChrome: HostComponent;
 export declare const kindHasRecordChrome: HostFn;
 export declare const KindFixItBar: HostComponent;
+export declare const useHostDispatch: HostFn;
+export declare const useHostGetState: HostFn;
+export declare const useIsSuperAdmin: HostFn;
+export declare const useActiveOrganizationId: HostFn;
+export declare const useAlchemyDisclosure: HostFn;
+export declare const useRegistryMenuSource: HostFn;
+export declare const sameContentSource: HostFn;
+export declare const contentSourceKey: HostFn;
+export declare const openContextMenuForElement: HostFn;
+export declare const convertOriginForSource: HostFn;
+export declare const useDocumentDialogsHost: HostFn;
+export declare const RecordAnnotations: HostComponent;
+export declare const annotationRecordOf: HostFn;
+export declare const recordKeyOf: HostFn;
 export declare const MarkdownStream: HostComponent;
 export declare const CitationMarkerInline: HostComponent;
+export declare const CopyButtons: HostComponent;
 export declare const InlineCopyButton: HostComponent;
 export declare const AdvancedMenu: HostComponent;
 export declare const useAdvancedMenu: HostFn;
@@ -140,6 +171,7 @@ export declare const IconInputWithValidation: HostComponent;
 export declare const LocatedTableViewer: HostComponent;
 export declare const OpenDestinationDialog: HostComponent;
 export declare function hostHtmlPageService(): unknown;
+export declare const holdDeliberateIntent: <T>(work: () => T | Promise<T>) => Promise<T>;
 export declare const ensureOrganizationContext: HostFn;
 export declare const isOrganizationSelectionCancelled: HostFn;
 export declare const loadExportTargets: HostFn;

package/dist/host/app-bindings.js

@@ -68,8 +68,27 @@ const KindInstanceRender = component("KindInstanceRender", ValueFloor, "kind ins
 const KindRecordChrome = component("KindRecordChrome", Passthrough, "kind records show without record chrome");
 const kindHasRecordChrome = fn("kindHasRecordChrome", () => false, "kind records show without record chrome");
 const KindFixItBar = component("KindFixItBar", null, "no fix-it bar on broken kinds");
+const useHostDispatch = fn("useHostDispatch", () => (action) => action, "actions dispatch nowhere");
+const useHostGetState = fn("useHostGetState", () => () => ({}), "actions read an empty host state");
+const useIsSuperAdmin = fn("useIsSuperAdmin", () => false, "admin-only actions are absent");
+const useActiveOrganizationId = fn("useActiveOrganizationId", () => null, "no organization is active");
+const useAlchemyDisclosure = fn("useAlchemyDisclosure", noop, "no Alchemy disclosure");
+const useRegistryMenuSource = fn("useRegistryMenuSource", () => null, "no menu carries a content source");
+const sameContentSource = fn(
+  "sameContentSource",
+  (a, b) => Boolean(a && b && JSON.stringify(a) === JSON.stringify(b)),
+  "content sources compare by value"
+);
+const contentSourceKey = fn("contentSourceKey", (s) => JSON.stringify(s), "content sources key by value");
+const openContextMenuForElement = fn("openContextMenuForElement", noop, "no context menu opens");
+const convertOriginForSource = fn("convertOriginForSource", () => null, "convert is absent");
+const useDocumentDialogsHost = fn("useDocumentDialogsHost", () => ({ callbacks: {} }), "document dialogs are absent");
+const RecordAnnotations = component("RecordAnnotations", Passthrough, "no reading set on saved records");
+const annotationRecordOf = fn("annotationRecordOf", () => null, "no saved record is known");
+const recordKeyOf = fn("recordKeyOf", (r) => `${r.token}:${r.id}`, "records key as token:id");
 const MarkdownStream = component("MarkdownStream", null, "the full renderer is not registered");
 const CitationMarkerInline = component("CitationMarkerInline", TextOnly, "citation markers show as text");
+const CopyButtons = component("CopyButtons", null, "no copy menu on rendered content");
 const InlineCopyButton = component("InlineCopyButton", null, "no inline copy button");
 const AdvancedMenu = component("AdvancedMenu", null, "no block menus");
 const useAdvancedMenu = fn("useAdvancedMenu", () => ({ isOpen: false, open: noop, close: noop, toggle: noop, menuProps: {} }), "no block menus");
@@ -83,6 +102,11 @@ const OpenDestinationDialog = component("OpenDestinationDialog", null, "no desti
 function hostHtmlPageService() {
   return binding("HTMLPageService") ?? null;
 }
+const holdDeliberateIntent = fn(
+  "holdDeliberateIntent",
+  (work) => Promise.resolve().then(work),
+  "actions run without an intent hold"
+);
 const ensureOrganizationContext = fn("ensureOrganizationContext", async () => null, "no organization can be chosen");
 const isOrganizationSelectionCancelled = fn("isOrganizationSelectionCancelled", () => false, "no organization can be chosen");
 const loadExportTargets = fn("loadExportTargets", async () => null, "no workbook export");
@@ -105,6 +129,7 @@ export {
   ArtifactRender,
   CitationMarkerInline,
   CodeBlockWithContextAttach,
+  CopyButtons,
   EntityRef,
   IconInputWithValidation,
   InlineCopyButton,
@@ -119,12 +144,17 @@ export {
   NonEditableContextMenu,
   OpenDestinationDialog,
   RawJsonExplorer,
+  RecordAnnotations,
   StructuredValueView,
+  annotationRecordOf,
   announceProposedGoogleWrite,
+  contentSourceKey,
+  convertOriginForSource,
   createMermaidEditorScope,
   ensureOrganizationContext,
   getArtifactDef,
   hasArtifactRenderer,
+  holdDeliberateIntent,
   hostCodeEditorAgents,
   hostHtmlPageService,
   hostMermaidEditorManifest,
@@ -134,19 +164,28 @@ export {
   kindHasRecordChrome,
   loadExportTargets,
   loadSendToGoogle,
+  openContextMenuForElement,
+  recordKeyOf,
   reportCanvasOpenDrop,
   resolveArtifactDef,
+  sameContentSource,
   setImageKnobMapEntry,
+  useActiveOrganizationId,
   useAdvancedMenu,
+  useAlchemyDisclosure,
   useCanvas,
   useCanvasOpenGuard,
   useDiagramAgents,
+  useDocumentDialogsHost,
   useHideReasoning,
   useHideToolResults,
+  useHostDispatch,
+  useHostGetState,
   useHostUser,
   useImageKnob,
   useIsAdminDebugger,
   useIsAuthenticated,
+  useIsSuperAdmin,
   useMachineFramesVisible,
   useMermaidPreferences,
   useOpenArtifactInCanvas,
@@ -154,6 +193,7 @@ export {
   useOpenOverlay,
   useOpenSmartCodeEditorWindow,
   useOpenTableViewerWindow,
+  useRegistryMenuSource,
   useSaveAndOpenInCodeEditor,
   useSetMermaidPreferences,
   useThemeMode

package/dist/host/feedback-subject.d.ts

@@ -0,0 +1,16 @@
+/**
+ * What a feedback report points at (matrx-frontend: features/overlays/openers/feedbackDialog
+ * `FeedbackSubject`). The engine only builds the text-passage subject; the host owns the rest.
+ */
+export interface TextPassageFeedbackSubject {
+    kind: "text_passage";
+    sourceToken: string;
+    sourceId: string;
+    sourceTitle: string;
+    quote: string;
+    anchor?: unknown;
+    [extra: string]: unknown;
+}
+export type FeedbackSubject = TextPassageFeedbackSubject | ({
+    kind: string;
+} & Record<string, unknown>);

package/dist/host/manual-copy.d.ts

@@ -0,0 +1,7 @@
+export interface ManualCopyOptions {
+    /** The text the person needs on their clipboard. */
+    text: string;
+    title?: string;
+    description?: string;
+}
+export declare function showManualCopy(opts: ManualCopyOptions): void;

package/dist/host/manual-copy.js

@@ -0,0 +1,11 @@
+import { announceBareHost, hostCapability } from "./registry.js";
+function showManualCopy(opts) {
+  if (!opts.text) return;
+  const show = hostCapability("showManualCopy");
+  if (show) return show(opts);
+  announceBareHost("showManualCopy", "a refused copy is written to the console");
+  console.warn("[rich-content] the clipboard refused this copy; the text follows:\n" + opts.text);
+}
+export {
+  showManualCopy
+};

package/dist/host/registry.d.ts

@@ -25,3 +25,5 @@ export declare function announceBareHost(capability: string, degraded: string):
 export declare const BARE_HOST_ATTR: {
     readonly "data-rich-content-host": "bare";
 };
+/** Run the host's `ensureBlockRegistrations` once (see RichContentHost). */
+export declare function ensureHostBlockRegistrations(): void;

package/dist/host/registry.js

@@ -44,10 +44,20 @@ function announceBareHost(capability, degraded) {
   console.warn(`[@ai-matrx/rich-content] The host registered no "${capability}", so ${degraded}.`);
 }
 const BARE_HOST_ATTR = { "data-rich-content-host": "bare" };
+const ENSURED_KEY = /* @__PURE__ */ Symbol.for("ai-matrx.rich-content.block-registrations-ensured");
+function ensureHostBlockRegistrations() {
+  const g = globalThis;
+  if (g[ENSURED_KEY]) return;
+  const ensure = hostCapability("ensureBlockRegistrations");
+  if (!ensure) return;
+  g[ENSURED_KEY] = true;
+  ensure();
+}
 export {
   BARE_HOST_ATTR,
   announceBareHost,
   configureRichContent,
+  ensureHostBlockRegistrations,
   hostCapability,
   resetRichContentHost,
   richContentHostVersion,

package/dist/host/session-knob.d.ts

@@ -0,0 +1,5 @@
+export interface KnobRef {
+    feature: string;
+    key: string;
+}
+export declare function getSessionKnob(knob: KnobRef): unknown;

package/dist/host/session-knob.js

@@ -0,0 +1,7 @@
+import { hostCapability } from "./registry.js";
+function getSessionKnob(knob) {
+  return hostCapability("readSessionKnob")?.(knob);
+}
+export {
+  getSessionKnob
+};

package/dist/host/types.d.ts

@@ -149,6 +149,30 @@ export interface RichContentHost {
     splitterEnvelopes: RichContentSplitterEnvelopes;
     /** A hook returning the host's "save these rows as a table" opener, or null. Default: no opener (the button is absent). */
     useOpenSaveToTable: () => ((options: Record<string, unknown>) => unknown) | null;
+    /**
+     * Loads the host's own block registrations on first use (matrx-frontend's Jest setup requires its
+     * registration module here, so suites that mock a block still see the mock). Called once, on the
+     * first block-registry or dispatch lookup. Default: none (registrations arrive by import).
+     */
+    ensureBlockRegistrations: () => void;
+    /** Loads the host's rich-document registrations (handlers, source adapters) on first registry read. */
+    ensureRichDocumentRegistrations: () => void;
+    /** The manual-copy dialog for a copy the clipboard refused. Default: the console. */
+    showManualCopy: (opts: {
+        text: string;
+        title?: string;
+        description?: string;
+    }) => void;
+    /** A knob's effective value for the signed-in person, synchronously. Default: undefined. */
+    readSessionKnob: (knob: {
+        feature: string;
+        key: string;
+    }) => unknown;
+    /**
+     * The editor's HTML → markdown converter (matrx-frontend: @ai-matrx/rich-editor core), loaded at
+     * copy time. Default: none — a copied selection keeps its shape text (tables and lists).
+     */
+    loadHtmlToMarkdown: () => Promise<(html: string) => string>;
     /** Loads mermaid (`() => import("mermaid").then((m) => m.default)`). Default: none — diagrams show their source. */
     loadMermaid: () => Promise<unknown>;
     /** Loads the ELK layout loaders (`() => import("@mermaid-js/layout-elk").then((m) => m.default)`). Default: dagre only. */

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

@@ -0,0 +1,29 @@
+import * as React from "react";
+import { NonEditableContextMenu } from "../host/app-bindings.js";
+import type { ContentSource, RichDocumentAction, RichDocumentActionId, RichDocumentActionsProp } from "./types.js";
+export interface RegistryContextMenuProps {
+    content: string;
+    source: ContentSource;
+    actions?: RichDocumentActionsProp;
+    /** Context-menu-only additions / removals. */
+    extra?: RichDocumentAction[];
+    exclude?: (RichDocumentActionId | string)[];
+    /** Yield to the native menu (e.g. while the content streams). */
+    suppressed?: boolean;
+    sourceFeature?: React.ComponentProps<typeof NonEditableContextMenu>["sourceFeature"];
+    surfaceName?: string;
+    /**
+     * The surface's declared values (e.g. `conversation_id` for the assistant
+     * message surface) — merged into the menu scope so bound agents and
+     * shortcuts receive them.
+     */
+    contextData?: Record<string, unknown>;
+    /**
+     * Which agent-menu placements show (e.g. `{ "content-block": "hide" }` over
+     * a rendered answer, where a block could only be copied, never inserted).
+     */
+    placementMode?: React.ComponentProps<typeof NonEditableContextMenu>["placementMode"];
+    children: React.ReactNode;
+}
+export declare function RegistryContextMenu(props: RegistryContextMenuProps): React.ReactElement;
+export default RegistryContextMenu;

package/dist/rich-document/RegistryContextMenu.js

@@ -0,0 +1,40 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { NonEditableContextMenu } from "../host/app-bindings.js";
+import { useActionSurfaceProvider } from "./runtime/useActionSurfaceProvider.js";
+function RegistryContextMenu(props) {
+  const { content, source, actions, extra, exclude, suppressed, children } = props;
+  const { ctx } = useActionSurfaceProvider({
+    content,
+    source,
+    actions,
+    actionsVariant: "none"
+  });
+  const excludes = [...actions?.exclude ?? [], ...exclude ?? []];
+  return /* @__PURE__ */ jsx(
+    NonEditableContextMenu,
+    {
+      sourceFeature: props.sourceFeature ?? "documents",
+      surfaceName: props.surfaceName,
+      suppressed,
+      contentSource: source,
+      contextData: { ...props.contextData, content: ctx.content },
+      placementMode: props.placementMode,
+      excludedRichActions: excludes,
+      richDocCtxExtras: {
+        callbacks: actions?.callbacks,
+        extensions: actions?.extensions,
+        metadata: actions?.metadata ?? null,
+        isCreator: actions?.isCreator ?? false,
+        surfaceKey: actions?.surfaceKey ?? null
+      },
+      extraRichActions: [...actions?.extra ?? [], ...extra ?? []],
+      children
+    }
+  );
+}
+var RegistryContextMenu_default = RegistryContextMenu;
+export {
+  RegistryContextMenu,
+  RegistryContextMenu_default as default
+};

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;