@ai-matrx/rich-content 0.2.10 → 0.2.16

package/dist/copy/copy-commands.d.ts

@@ -0,0 +1,42 @@
+import { markdownToReadableText } from "./markdown-readable-text.js";
+interface CopyOptions {
+    isMarkdown?: boolean;
+    formatForGoogleDocs?: boolean;
+    formatForWordPress?: boolean;
+    formatJson?: boolean;
+    showHtmlPreview?: boolean;
+    includeThinking?: boolean;
+    onSuccess?: () => void;
+    onError?: (err: unknown) => void;
+    onShowHtmlPreview?: (html: string) => boolean | void | Promise<boolean | void>;
+}
+/**
+ * Copy CONTENT (markdown, text, or any JSON-able value) through Alchemy's serialization and browser transport.
+ * Not the plain-string copy — that is `copyToClipboard` in `@/lib/clipboard/copy`.
+ */
+export declare function copyContent(content: unknown, options?: CopyOptions): Promise<boolean>;
+export type CopyFlavor = "default" | "markdown" | "text";
+export { markdownToReadableText };
+/** The knob that decides what a single Copy click puts in a plain field. */
+export declare const COPY_DEFAULT_FLAVOR_KNOB: {
+    readonly feature: "copy";
+    readonly key: "default_flavor";
+};
+/** The plain-text flavor of a single Copy click for this session ("markdown" until the knob answers). */
+export declare function defaultCopyFlavor(): "markdown" | "text";
+export interface RichCopyOptions {
+    /** Keep `<thinking>` / reasoning blocks (default: removed). */
+    includeThinking?: boolean;
+    /** Toast on success: a label, or false for none. Default: the flavor's label. */
+    toast?: string | false;
+}
+/** The bytes a flavor writes — pure enough to test; the HTML is loaded at click time. */
+export declare function richCopyPlainText(markdown: string, flavor: CopyFlavor, defaultFlavor?: "markdown" | "text"): string;
+/**
+ * Write the plain flavor, or html + plain in one clipboard item (kit's `copyRich`; `html` may be a
+ * promise so the item is created inside the click). A refused rich write degrades to plain text and
+ * says so; when nothing lands the person is handed the text to copy by hand.
+ */
+export declare function writeClipboardFlavors(plain: string, html?: Promise<string> | string): Promise<boolean>;
+/** THE copy of rich content. Returns true when the clipboard holds it. */
+export declare function copyRichContent(markdown: string, flavor?: CopyFlavor, options?: RichCopyOptions): Promise<boolean>;

package/dist/copy/copy-commands.js

@@ -0,0 +1,119 @@
+import {
+  createBrowserTransport,
+  createDraft,
+  capture,
+  formatAdapter,
+  normalizeTransferJson,
+  serialize
+} from "@ai-matrx/alchemy/operate";
+import { copyRich, copyText } from "@ai-matrx/kit/clipboard";
+import { showManualCopy } from "../host/manual-copy.js";
+import { toast } from "../host/toast.js";
+import { getSessionKnob } from "../host/session-knob.js";
+import { markdownToReadableText } from "./markdown-readable-text.js";
+import { formattedCopyHtml, removeThinkingContent } from "./markdown-copy-html.js";
+async function copyContent(content, options = {}) {
+  let capturedText;
+  try {
+    let payload;
+    if (typeof content === "string") {
+      const text = options.includeThinking ? content : removeThinkingContent(content);
+      payload = { kind: options.isMarkdown ? "markdown" : "text", text };
+      if (options.formatJson !== false) {
+        let parsed;
+        try {
+          parsed = JSON.parse(text);
+        } catch {
+          parsed = void 0;
+        }
+        if (parsed !== void 0)
+          payload = { kind: "json", value: normalizeTransferJson(parsed) };
+      }
+    } else {
+      payload = { kind: "json", value: normalizeTransferJson(content) };
+    }
+    const signal = new AbortController().signal;
+    const { snapshot } = await capture(payload, signal);
+    const draft = createDraft(snapshot);
+    const rich = payload.kind === "markdown" && (options.formatForGoogleDocs || options.formatForWordPress);
+    const artifact = rich ? await (await formatAdapter("rich-html").load()).build(
+      draft,
+      { profile: options.formatForGoogleDocs ? "google-docs" : "generic" },
+      signal
+    ) : serialize(
+      draft,
+      payload.kind === "json" ? options.formatJson === false ? "compact-json" : "json" : "plain"
+    );
+    capturedText = artifact.plainText;
+    if (options.showHtmlPreview) {
+      if (!options.onShowHtmlPreview || !artifact.html)
+        throw new Error(
+          "HTML preview requires a formatted Markdown source and a preview callback."
+        );
+      const previewDelivered = await options.onShowHtmlPreview(artifact.html);
+      if (previewDelivered === false) return false;
+      options.onSuccess?.();
+      return true;
+    }
+    const outcome = await createBrowserTransport().copy(artifact, signal);
+    if (outcome.status === "success") {
+      options.onSuccess?.();
+      return true;
+    }
+    if (outcome.status === "degraded") {
+      toast.info(`Copied as plain text: ${outcome.reason}`);
+      return false;
+    }
+    if (outcome.status === "cancelled") return false;
+    throw new Error(outcome.message);
+  } catch (error) {
+    if (capturedText !== void 0) {
+      showManualCopy({ text: capturedText });
+      return false;
+    }
+    options.onError?.(error);
+    if (!options.onError)
+      toast.error(
+        error instanceof Error ? error.message : "Could not copy content"
+      );
+    return false;
+  }
+}
+const COPY_DEFAULT_FLAVOR_KNOB = { feature: "copy", key: "default_flavor" };
+function defaultCopyFlavor() {
+  return getSessionKnob(COPY_DEFAULT_FLAVOR_KNOB) === "text" ? "text" : "markdown";
+}
+const FLAVOR_TOAST = {
+  default: "Copied",
+  markdown: "Markdown copied",
+  text: "Text copied"
+};
+function richCopyPlainText(markdown, flavor, defaultFlavor = "markdown") {
+  const plainFlavor = flavor === "default" ? defaultFlavor : flavor;
+  return plainFlavor === "text" ? markdownToReadableText(markdown) : markdown;
+}
+async function writeClipboardFlavors(plain, html) {
+  const landed = html === void 0 ? await copyText(plain) : await copyRich(
+    { text: plain, html },
+    { onDegraded: (reason) => toast.info(`Copied without formatting: ${reason}.`) }
+  );
+  if (!landed) showManualCopy({ text: plain });
+  return landed;
+}
+async function copyRichContent(markdown, flavor = "default", options = {}) {
+  const source = options.includeThinking ? markdown : removeThinkingContent(markdown);
+  const plain = richCopyPlainText(source, flavor, defaultCopyFlavor());
+  const ok = await writeClipboardFlavors(plain, flavor === "default" ? formattedCopyHtml(source) : void 0);
+  const label = options.toast === void 0 ? FLAVOR_TOAST[flavor] : options.toast;
+  if (ok && label) toast.success(label);
+  return ok;
+}
+export {
+  COPY_DEFAULT_FLAVOR_KNOB,
+  copyContent,
+  copyRichContent,
+  defaultCopyFlavor,
+  markdownToReadableText,
+  richCopyPlainText,
+  writeClipboardFlavors
+};

package/dist/copy/markdown-copy-html.d.ts

@@ -0,0 +1,3 @@
+export { removeThinkingContent } from "@ai-matrx/print/markdown";
+/** The formatted HTML for a copy (loaded at click time), or `undefined` when this host writes plain text only. */
+export declare function formattedCopyHtml(markdown: string): Promise<string> | undefined;

package/dist/copy/markdown-copy-html.js

@@ -0,0 +1,8 @@
+import { removeThinkingContent } from "@ai-matrx/print/markdown";
+function formattedCopyHtml(markdown) {
+  return import("@ai-matrx/print/markdown").then(({ markdownToHtml }) => markdownToHtml(markdown));
+}
+export {
+  formattedCopyHtml,
+  removeThinkingContent
+};

package/dist/copy/markdown-readable-text.d.ts

@@ -0,0 +1,4 @@
+/** Inline markup → its words. Code spans are kept as their text. */
+export declare function readableInline(line: string): string;
+/** Markdown → readable plain text (envelopes unwrapped first). */
+export declare function markdownToReadableText(markdown: string): string;

package/dist/copy/markdown-readable-text.js

@@ -0,0 +1,62 @@
+import { unwrapKindEnvelopes } from "@ai-matrx/content-ir/source";
+import {
+  findTableEnd,
+  rowCells,
+  tableStartsAt,
+  unescapeCellPipes
+} from "../display/markdown-classification/processors/utils/gfm-table-lines.js";
+const FENCE = /^( {0,3})(`{3,}|~{3,})/;
+function readableInline(line) {
+  const codes = [];
+  let out = line.replace(/(`+)([\s\S]*?[^`])\1(?!`)/g, (_m, _ticks, body) => {
+    codes.push(body.replace(/^ (.*) $/, "$1"));
+    return `\uE000${codes.length - 1}\uE000`;
+  });
+  out = out.replace(/!\[([^\]]*)\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g, (_m, alt, url) => alt ? `${alt} (${url})` : url).replace(/\[([^\]]+)\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g, (_m, text, url) => {
+    const bare = url.replace(/^mailto:/, "");
+    return text === url || text === bare ? bare : `${text} (${bare})`;
+  }).replace(/<((?:https?:\/\/|mailto:)[^>\s]+)>/g, (_m, url) => url.replace(/^mailto:/, "")).replace(/(\*\*\*|___)(?=\S)([\s\S]*?\S)\1/g, "$2").replace(/(\*\*|__)(?=\S)([\s\S]*?\S)\1/g, "$2").replace(/~~(?=\S)([\s\S]*?\S)~~/g, "$1").replace(/(^|[^\w*])\*(?=\S)([^*]*?\S)\*(?!\w)/g, "$1$2").replace(/(^|[^\w])_(?=\S)([^_]*?\S)_(?!\w)/g, "$1$2").replace(/ {2,}$|\\$/g, "").replace(/\\([!-/:-@[-`{-~])/g, "$1");
+  return out.replace(/\uE000(\d+)\uE000/g, (_m, i) => codes[Number(i)] ?? "");
+}
+function markdownToReadableText(markdown) {
+  const lines = unwrapKindEnvelopes(markdown).replace(/\r\n?/g, "\n").split("\n");
+  const out = [];
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    const fence = FENCE.exec(line);
+    if (fence) {
+      const marker = fence[2];
+      let j = i + 1;
+      while (j < lines.length && !new RegExp(`^ {0,3}${marker[0] === "`" ? "`" : "~"}{${marker.length},}\\s*$`).test(lines[j])) {
+        out.push(lines[j]);
+        j += 1;
+      }
+      i = j;
+      continue;
+    }
+    if (tableStartsAt(lines, i)) {
+      const end = findTableEnd(lines, i);
+      for (let j = i; j < end; j += 1) {
+        if (j === i + 1) continue;
+        out.push(rowCells(lines[j]).map((c) => readableInline(unescapeCellPipes(c).trim())).join("	"));
+      }
+      i = end - 1;
+      continue;
+    }
+    if (/^ {0,3}([-*_])( *\1){2,} *$/.test(line)) {
+      out.push("");
+      continue;
+    }
+    if (/^ {0,3}(=+|-+) *$/.test(line) && out.length && out[out.length - 1].trim()) continue;
+    let rest = line;
+    rest = rest.replace(/^ {0,3}(?:> ?)+/, "");
+    rest = rest.replace(/^ {0,3}#{1,6}[ \t]+/, "").replace(/[ \t]+#+[ \t]*$/, "");
+    rest = rest.replace(/^(\s*)[-*+][ \t]+\[[ ]\][ \t]+/, "$1\u2610 ").replace(/^(\s*)[-*+][ \t]+\[[xX]\][ \t]+/, "$1\u2611 ").replace(/^(\s*)[-*+][ \t]+/, "$1\u2022 ").replace(/^(\s*)(\d{1,9})[.)][ \t]+/, "$1$2. ");
+    out.push(readableInline(rest));
+  }
+  return out.join("\n").replace(/\n{3,}/g, "\n\n").trim();
+}
+export {
+  markdownToReadableText,
+  readableInline
+};

package/dist/display/chat-markdown/block-registry/BlockComponentRegistry.js

@@ -69,8 +69,10 @@ const BUILTIN_BLOCK_COMPONENTS = {
 const BUILTIN_LOADING_COMPONENTS = {
   DiagramLoading: () => /* @__PURE__ */ jsx(LazyBlockWrapper, { children: /* @__PURE__ */ jsx(DiagramLoadingVisualization, {}) })
 };
+import { ensureHostBlockRegistrations } from "../../../host/registry.js";
 const REGISTRY_KEY = /* @__PURE__ */ Symbol.for("ai-matrx.rich-content.block-components");
 function registry() {
+  ensureHostBlockRegistrations();
   const g = globalThis;
   return g[REGISTRY_KEY] ??= { blocks: {}, loading: {} };
 }

package/dist/display/chat-markdown/block-registry/block-dispatch.js

@@ -472,6 +472,7 @@ const BLOCK_DISPATCH_CLASSIFICATION = {
 const DISPATCH_MAP = new Map(
   Object.entries(BLOCK_DISPATCH)
 );
+import { ensureHostBlockRegistrations } from "../../../host/registry.js";
 const REGISTERED_KEY = /* @__PURE__ */ Symbol.for("ai-matrx.rich-content.block-dispatch");
 function registered() {
   const g = globalThis;
@@ -481,6 +482,7 @@ function registerBlockDispatch(entries) {
   for (const [type, fn] of Object.entries(entries)) if (fn) registered().set(type, fn);
 }
 function resolveBlockDispatch(type) {
+  ensureHostBlockRegistrations();
   return registered().get(type) ?? DISPATCH_MAP.get(type) ?? null;
 }
 export {

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;
@@ -128,6 +143,20 @@ 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;
@@ -142,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,6 +68,24 @@ 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");
@@ -84,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");
@@ -121,12 +144,17 @@ export {
   NonEditableContextMenu,
   OpenDestinationDialog,
   RawJsonExplorer,
+  RecordAnnotations,
   StructuredValueView,
+  annotationRecordOf,
   announceProposedGoogleWrite,
+  contentSourceKey,
+  convertOriginForSource,
   createMermaidEditorScope,
   ensureOrganizationContext,
   getArtifactDef,
   hasArtifactRenderer,
+  holdDeliberateIntent,
   hostCodeEditorAgents,
   hostHtmlPageService,
   hostMermaidEditorManifest,
@@ -136,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,
@@ -156,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
+};