@ai-matrx/rich-content 0.2.3 → 0.2.6

package/dist/display/chat-markdown/block-registry/BlockRenderer.d.ts

@@ -0,0 +1,126 @@
+import type { AnswerEditRemarkMeta } from "../../block-interaction.js";
+import React from "react";
+import { resolveProvisionalKindRender } from "../../../kinds/react/partial-kind-route.js";
+import { type CanonicalBlockIR } from "@ai-matrx/content-ir";
+import { type RenderBlock } from "./block-dispatch.js";
+export type { RenderBlock } from "./block-dispatch.js";
+interface BlockRendererProps {
+    requestId?: string;
+    block: RenderBlock;
+    index: number;
+    isStreamActive?: boolean;
+    onContentChange?: (newContent: string) => void;
+    /** Owning message context forwarded to canonical artifact renderers. */
+    conversationId?: string;
+    messageId?: string;
+    taskId?: string;
+    isLastReasoningBlock?: boolean;
+    /** Generic handler: replaces `original` substring with `replacement` in the full content string. */
+    replaceBlockContent: (original: string, replacement: string, remark?: AnswerEditRemarkMeta) => void;
+    handleOpenEditor: () => void;
+    /**
+     * Streaming partial kinds ONLY. Set on the recursive render of a
+     * PROVISIONAL block so the loading gates below (which exist to hide a
+     * half-arrived payload) stand down and the real kind component renders the
+     * provisional value. Never set by an ordinary caller.
+     */
+    suppressLoadingGate?: boolean;
+    outputSchema?: unknown | null;
+}
+export declare function pendingStructuredEnvelope(block: {
+    type: string;
+    content?: string | null;
+    language?: string;
+    metadata?: Record<string, unknown>;
+    isStreamingBlock?: boolean;
+}): CanonicalBlockIR | null;
+/**
+ * The terminal envelope for a settled block that arrived without one: reload
+ * has only the original text when an interrupted run could not stamp a
+ * COMPLETE persistence envelope, so the stream's parser runs at this terminal
+ * boundary — never on a live prefix — and keeps its error status intact.
+ */
+export declare function withTerminalEnvelope<T extends {
+    content?: string | null;
+    language?: string;
+    metadata?: Record<string, unknown>;
+    isStreamingBlock?: boolean;
+}>(block: T, isStreamActive: boolean | undefined): T;
+/**
+ * A SETTLED json region that names its kind in its text while the parser
+ * could not name it — the payload broke before (or around) its `__kind`, or
+ * no envelope exists at all — is that kind's BROKEN state, never the raw JSON
+ * card (A10, the never-raw law). The route takes it with `kindState: "raw"`
+ * (the kernel's "checked and failed" word, FEATURE.md), which is the
+ * broken-instance floor. A complete kindless envelope is genuine JSON (its
+ * nested kinds are the recovery pass's), and a streaming block is the pending
+ * gate's.
+ */
+export declare function settleBrokenKindRoute<T extends {
+    type: string;
+    content?: string | null;
+    language?: string;
+    metadata?: Record<string, unknown>;
+    isStreamingBlock?: boolean;
+}>(block: T): T;
+/**
+ * What the renderer shows in place of the block's own dispatch while its kind
+ * is still arriving: the provisional render (Stage 1.5), or a kind loader
+ * (Stages 1.6, 2, 2.5 and the kind half of Stage 3). Null → the block is
+ * dispatched by its routed type.
+ */
+export type BlockRenderGate = {
+    kind: "provisional";
+    provisional: NonNullable<ReturnType<typeof resolveProvisionalKindRender<RenderBlock>>>;
+} | {
+    kind: "loader";
+    envelope: CanonicalBlockIR;
+} | null;
+export interface BlockRenderDecision {
+    /** The input with its terminal envelope (settled blocks of a settled message). */
+    rawBlock: RenderBlock;
+    /** The routed block — what the dispatch registry receives. */
+    block: RenderBlock;
+    gate: BlockRenderGate;
+}
+/**
+ * THE DECISION BlockRenderer makes, as a pure function (V5): terminal
+ * envelope, kind route, broken-kind settle, then the loading gates in order.
+ * BlockRenderer calls it; so does the frame judge (`draws-raw-kind-json.ts`),
+ * so a guard can never drift from what the reader sees. `isStreamActive` is
+ * the MESSAGE's stream state, exactly as the renderer receives it — a settled
+ * block inside a still-streaming message is judged the way it is drawn.
+ * `route` is the kind route at a registry version (BlockRenderer passes its
+ * versioned, memoised route; pure callers take the uncached one).
+ */
+export declare function decideBlockRender(inputBlock: RenderBlock, { isStreamActive, suppressLoadingGate, route, }?: {
+    isStreamActive?: boolean;
+    suppressLoadingGate?: boolean;
+    route?: (block: RenderBlock) => RenderBlock;
+}): BlockRenderDecision;
+/**
+ * Renders individual content blocks through four ordered stages:
+ *
+ *  1. KIND ROUTE (Shape blocks, first-class) — `applyIrKindRoute`: a block
+ *     whose `metadata.__ir` envelope resolved a REGISTERED kind routes through
+ *     the kind registry (`resolveComponent` / legacy bridge) before any
+ *     type-keyed dispatch. This is how bare/fenced JSON `flashcard_set` —
+ *     which the legacy detectors can only call "code" — becomes real
+ *     flashcards, live while streaming.
+ *  1.5 PROVISIONAL KIND (streaming partial kinds) — a block carrying a
+ *     `metadata.__ir_partial` `partial` event for an opted-in kind renders
+ *     that provisional value through the SAME component the final value uses,
+ *     marked "still arriving". Terminal events produce nothing here, so the
+ *     final value replaces the provisional render in one frame.
+ *  2. PENDING SKELETON — a still-streaming JSON region with an unresolved
+ *     kind shows a neutral skeleton instead of flashing raw text.
+ *  3. UNIFIED ARTIFACT RENDERER — standalone materializable blocks render
+ *     through the single shared artifact path (chat/canvas/artifact identical).
+ *  4. DISPATCH REGISTRY — the declarative, crosswalk-classified table in
+ *     block-dispatch.tsx (protocol / scalar_generic / shape / opaque). An
+ *     unregistered type SCREAMS (reportUnregisteredBlockType) and renders as
+ *     basic markdown — never a silent default.
+ *
+ * Components are lazy-loaded (see BlockComponentRegistry) for code splitting.
+ */
+export declare const BlockRenderer: React.FC<BlockRendererProps>;

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

@@ -0,0 +1,473 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { durableRecordId } from "@ai-matrx/kit/ids";
+import React, { useCallback } from "react";
+import { BlockComponents, LoadingComponents } from "./BlockComponentRegistry.js";
+import { resolveArtifactDef } from "../../../host/app-bindings.js";
+import {
+  ArtifactRender,
+  hasArtifactRenderer
+} from "../../../host/app-bindings.js";
+import { useMachineFramesVisible, useHideReasoning, useHideToolResults } from "../../../host/app-bindings.js";
+import { GENERIC_STRUCTURED_COMPONENT_KEY } from "../../../kinds/react/kind-route.js";
+import {
+  routeBlockAtRegistryVersion,
+  routeBlockNow
+} from "../../../kinds/react/route-at-version.js";
+import { useContentIrKindVersion } from "../../../kinds/react/use-registry-repaint.js";
+import { useEnsureKindRenderable } from "../../../kinds/react/ensure-kind-renderable.js";
+import { resolveKindLoadingComponent } from "../../../kinds/react/loading/kind-loading-registry.js";
+import { resolveLoadingSlugForKind } from "../../../kinds/react/loading/resolve-loading-slug.js";
+import { earlyKeysFromValue } from "../../../kinds/react/loading/kind-loading.types.js";
+import { readEnvelope } from "../../../kinds/redux/render-block-envelope.js";
+import {
+  firstKindSlug,
+  hasKindKey,
+  isJsonFenceLanguage,
+  isJson5Language,
+  kindObjectProseBreak,
+  isKindSlug,
+  json5AsJson,
+  jsonKindSignal,
+  withoutLeadingJsonComments
+} from "@ai-matrx/content-ir/surfaces";
+import { withIrEnvelope } from "../../../kinds/registry/region-envelope-memo.js";
+import {
+  resolveAnnouncedKindLoading,
+  resolveProvisionalKindRender
+} from "../../../kinds/react/partial-kind-route.js";
+import {
+  ProvisionalKindBoundary,
+  ProvisionalKindFrame
+} from "../../../kinds/react/ProvisionalKindBoundary.js";
+import { applyIrKindRoute } from "../../../kinds/react/kind-route.js";
+import { componentRegistry } from "../../../host/component-registry.js";
+import {
+  IR_ENVELOPE_KEY,
+  IR_VERSION,
+  readPartialKindEvent,
+  reconstructRegionValue
+} from "@ai-matrx/content-ir";
+import {
+  KindRecordChrome,
+  kindHasRecordChrome
+} from "../../../host/app-bindings.js";
+import {
+  isBlockLoading,
+  resolveBlockDispatch,
+  reportUnregisteredBlockType
+} from "./block-dispatch.js";
+const ARTIFACT_LOADING_COMPONENTS = {
+  quiz: LoadingComponents.QuizLoading,
+  presentation: LoadingComponents.PresentationLoading,
+  recipe: LoadingComponents.RecipeLoading,
+  timeline: LoadingComponents.TimelineLoading,
+  research: LoadingComponents.ResearchLoading,
+  resources: LoadingComponents.ResourcesLoading,
+  progress: LoadingComponents.ProgressLoading,
+  comparison: LoadingComponents.ComparisonLoading,
+  troubleshooting: LoadingComponents.TroubleshootingLoading,
+  "decision-tree": LoadingComponents.DecisionTreeLoading,
+  diagram: LoadingComponents.DiagramLoading,
+  math_problem: LoadingComponents.MathProblemLoading
+};
+function readRecordValue(block) {
+  const envelope = readEnvelope(block.metadata);
+  const value = envelope ? reconstructRegionValue(envelope) : (() => {
+    try {
+      return JSON.parse(block.content ?? "");
+    } catch {
+      return null;
+    }
+  })();
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+}
+function pendingStructuredEnvelope(block) {
+  if (block.type !== "code") return null;
+  const envelope = readEnvelope(block.metadata);
+  if (!envelope) return unparsedKindPendingEnvelope(block);
+  if (envelope.root.status !== "streaming") {
+    if (envelope.root.kind) {
+      if (block.isStreamingBlock) return envelope;
+      return componentRegistry.hasSettled() ? null : envelope;
+    }
+    return unparsedKindPendingEnvelope(block);
+  }
+  if (envelope.root.kind) {
+    return envelope;
+  }
+  return jsonKindSignal(block.content, { json5: isJson5Language(block.language) }) === "not_kind" ? null : envelope;
+}
+function withTerminalEnvelope(block, isStreamActive) {
+  const settled = block.isStreamingBlock === false || !isStreamActive && !block.isStreamingBlock;
+  if (!settled || readEnvelope(block.metadata)) {
+    return block;
+  }
+  if (block.type === "text" && kindObjectProseBreak((block.content ?? "").trimStart()) !== null) {
+    return block;
+  }
+  const source = isJson5Language(block.language) ? json5AsJson(block.content ?? "") ?? block.content ?? "" : block.content ?? "";
+  const metadata = withIrEnvelope(source, block.metadata, {
+    allowTerminalError: true
+  });
+  return metadata !== block.metadata ? { ...block, metadata } : block;
+}
+function settleBrokenKindRoute(block) {
+  if (block.type !== "code" || block.isStreamingBlock) return block;
+  const slug = firstKindSlug(block.content ?? "", { json5: isJson5Language(block.language) });
+  if (!slug) return settleUnnamedKindRoute(block);
+  const envelope = readEnvelope(block.metadata);
+  if (envelope?.root.kind || envelope?.root.status === "complete") return block;
+  const broken = {
+    v: IR_VERSION,
+    engine: "fe-kind-parser",
+    fingerprint: "broken-kind-text",
+    root: {
+      role: "structured",
+      kind: slug,
+      kindState: "raw",
+      discriminator: { format: "json", key: "__kind" },
+      status: "error",
+      path: [],
+      value: {},
+      residue: null
+    }
+  };
+  return applyIrKindRoute({
+    ...block,
+    metadata: { ...block.metadata ?? {}, [IR_ENVELOPE_KEY]: broken }
+  });
+}
+function settleUnnamedKindRoute(block) {
+  const content = block.content ?? "";
+  if (!isJsonFenceLanguage(block.language) || !hasKindKey(content, { json5: isJson5Language(block.language) })) {
+    return block;
+  }
+  if (isKindSlug(readEnvelope(block.metadata)?.root.kind)) return block;
+  const broken = {
+    v: IR_VERSION,
+    engine: "fe-kind-parser",
+    fingerprint: "broken-unnamed-kind",
+    root: {
+      role: "structured",
+      kind: "",
+      kindState: "raw",
+      discriminator: { format: "json", key: "__kind" },
+      status: "error",
+      path: [],
+      value: {},
+      residue: {
+        extra: null,
+        optionalMissing: null,
+        notices: [
+          {
+            code: "parse_error",
+            message: "Broken structured output: its __kind is missing or unreadable."
+          }
+        ]
+      }
+    }
+  };
+  return {
+    ...block,
+    type: GENERIC_STRUCTURED_COMPONENT_KEY,
+    metadata: { ...block.metadata ?? {}, [IR_ENVELOPE_KEY]: broken }
+  };
+}
+function unparsedKindPendingEnvelope(block) {
+  if (!block.isStreamingBlock) return null;
+  const text = block.content ?? "";
+  const leadingComment = /^\s*\/[/*]/.test(text);
+  if (leadingComment && !isJsonFenceLanguage(block.language)) return null;
+  const body = leadingComment ? withoutLeadingJsonComments(text) : text;
+  if (!/^\s*[[{]/.test(body) && !(leadingComment && !body.trim())) return null;
+  const json5 = { json5: isJson5Language(block.language) };
+  if (jsonKindSignal(text, json5) === "not_kind") return null;
+  return {
+    v: IR_VERSION,
+    engine: "fe-kind-parser",
+    fingerprint: "first-key-signal",
+    root: {
+      role: "structured",
+      kind: firstKindSlug(text, json5) ?? "",
+      kindState: "pending_kind",
+      discriminator: { format: "json", key: "__kind" },
+      status: "streaming",
+      path: [],
+      value: {},
+      residue: null
+    }
+  };
+}
+function decideBlockRender(inputBlock, {
+  isStreamActive,
+  suppressLoadingGate = false,
+  route = routeBlockNow
+} = {}) {
+  const rawBlock = withTerminalEnvelope(inputBlock, isStreamActive);
+  const block = settleBrokenKindRoute(route(rawBlock));
+  const decided = (gate) => ({
+    rawBlock,
+    block,
+    gate
+  });
+  const provisional = suppressLoadingGate ? null : resolveProvisionalKindRender(rawBlock, { streamActive: isStreamActive });
+  if (provisional) return decided({ kind: "provisional", provisional });
+  const announced = suppressLoadingGate ? null : resolveAnnouncedKindLoading(rawBlock, { streamActive: isStreamActive });
+  if (announced) return decided({ kind: "loader", envelope: announced.envelope });
+  const pendingEnvelope = pendingStructuredEnvelope(block);
+  if (pendingEnvelope) return decided({ kind: "loader", envelope: pendingEnvelope });
+  if (block.type === GENERIC_STRUCTURED_COMPONENT_KEY && !suppressLoadingGate) {
+    const genericEnvelope = readEnvelope(block.metadata);
+    if (genericEnvelope?.root.kind && genericEnvelope.root.status === "streaming") {
+      return decided({ kind: "loader", envelope: genericEnvelope });
+    }
+  }
+  if (block.type !== "artifact" && !suppressLoadingGate) {
+    const def = resolveArtifactDef(block.type);
+    if (def && hasArtifactRenderer(def.canvasType) && isBlockLoading(block)) {
+      const kindEnvelope = readEnvelope(block.metadata);
+      if (kindEnvelope?.root.kind && block.serverData === void 0) {
+        return decided({ kind: "loader", envelope: kindEnvelope });
+      }
+    }
+  }
+  return decided(null);
+}
+const PendingStructuredBlock = ({
+  envelope
+}) => {
+  const kind = envelope.root.kind || void 0;
+  const slug = resolveLoadingSlugForKind(kind).slug;
+  const early = earlyKeysFromValue(envelope.root.value, kind);
+  return React.createElement(resolveKindLoadingComponent(slug), {
+    ...early,
+    value: envelope.root.value ?? null
+  });
+};
+const BlockRenderer = ({
+  requestId,
+  block: inputBlock,
+  index,
+  isStreamActive,
+  onContentChange,
+  conversationId,
+  messageId,
+  taskId,
+  isLastReasoningBlock,
+  replaceBlockContent,
+  handleOpenEditor,
+  suppressLoadingGate = false,
+  outputSchema = null
+}) => {
+  const durableMessageId = durableRecordId(messageId) ?? void 0;
+  const terminalBlock = withTerminalEnvelope(inputBlock, isStreamActive);
+  const partialEvent = readPartialKindEvent(terminalBlock.metadata);
+  const announcedKind = partialEvent?.state === "partial" ? partialEvent.root.kind : partialEvent?.kind;
+  const envelopeKind = readEnvelope(terminalBlock.metadata)?.root.kind ?? announcedKind ?? null;
+  const kindRouteVersion = useContentIrKindVersion(envelopeKind);
+  useEnsureKindRenderable(envelopeKind);
+  const decision = decideBlockRender(inputBlock, {
+    isStreamActive,
+    suppressLoadingGate,
+    route: (b) => routeBlockAtRegistryVersion(b, kindRouteVersion)
+  });
+  const block = decision.block;
+  const interruptedEnvelope = readEnvelope(block.metadata);
+  const hasInterruptedKind = Boolean(
+    !isStreamActive && interruptedEnvelope?.root.kind && interruptedEnvelope.root.status === "error"
+  );
+  const hideReasoning = Boolean(useHideReasoning(conversationId ?? null));
+  const hideToolResults = Boolean(useHideToolResults(conversationId ?? null));
+  const machineFramesVisible = useMachineFramesVisible();
+  const recordChromeKind = envelopeKind && !suppressLoadingGate && (kindHasRecordChrome(envelopeKind) || Boolean(durableMessageId)) ? envelopeKind : null;
+  const withRecordChrome = (el) => {
+    if (el && hasInterruptedKind) {
+      return /* @__PURE__ */ jsxs("div", { "data-incomplete-kind": interruptedEnvelope?.root.kind, children: [
+        /* @__PURE__ */ jsx(
+          "p",
+          {
+            role: "status",
+            className: "mb-2 rounded-md border border-amber-500/30 bg-amber-500/5 px-3 py-2 text-xs text-amber-800 dark:text-amber-200",
+            children: "This response is incomplete. The content received so far is shown below."
+          }
+        ),
+        el
+      ] }, index);
+    }
+    if (!el || !recordChromeKind || isStreamActive || isBlockLoading(block) || readEnvelope(block.metadata)?.root.status !== "complete") {
+      return el;
+    }
+    return /* @__PURE__ */ jsxs("div", { "data-kind-record-host": recordChromeKind, children: [
+      el,
+      /* @__PURE__ */ jsx(
+        KindRecordChrome,
+        {
+          kind: recordChromeKind,
+          durableMessageId,
+          conversationId,
+          value: readRecordValue(block),
+          fingerprint: readEnvelope(block.metadata)?.fingerprint ?? null
+        }
+      )
+    ] }, index);
+  };
+  const renderFallbackContent = useCallback(
+    (content, language = "json") => {
+      return /* @__PURE__ */ jsx(
+        BlockComponents.CodeBlock,
+        {
+          code: content,
+          language,
+          fontSize: 16,
+          className: "my-3",
+          isStreamActive
+        },
+        index
+      );
+    },
+    [index, isStreamActive]
+  );
+  const blockType = String(block.type);
+  const renderBasicMarkdown = useCallback(
+    (content) => {
+      return /* @__PURE__ */ jsx(
+        BlockComponents.BasicMarkdownContent,
+        {
+          content,
+          isStreamActive,
+          onEditRequest: onContentChange ? handleOpenEditor : void 0,
+          messageId,
+          showCopyButton: false,
+          tableRenderDiagnostic: {
+            blockType,
+            conversationId,
+            messageId,
+            requestId
+          }
+        },
+        index
+      );
+    },
+    [
+      index,
+      isStreamActive,
+      onContentChange,
+      handleOpenEditor,
+      messageId,
+      blockType,
+      conversationId,
+      requestId
+    ]
+  );
+  if (decision.gate?.kind === "provisional") {
+    const provisional = decision.gate.provisional;
+    return /* @__PURE__ */ jsx(
+      ProvisionalKindBoundary,
+      {
+        kind: provisional.kind,
+        fallback: /* @__PURE__ */ jsx(PendingStructuredBlock, { envelope: provisional.envelope }),
+        children: /* @__PURE__ */ jsx(ProvisionalKindFrame, { children: /* @__PURE__ */ jsx(
+          BlockRenderer,
+          {
+            requestId,
+            block: provisional.block,
+            index,
+            isStreamActive,
+            onContentChange,
+            conversationId,
+            messageId,
+            taskId,
+            isLastReasoningBlock,
+            replaceBlockContent,
+            handleOpenEditor,
+            suppressLoadingGate: true,
+            outputSchema
+          }
+        ) })
+      },
+      index
+    );
+  }
+  if (decision.gate?.kind === "loader") {
+    return /* @__PURE__ */ jsx(PendingStructuredBlock, { envelope: decision.gate.envelope }, index);
+  }
+  if (block.type !== "artifact") {
+    const _def = resolveArtifactDef(block.type);
+    if (_def && hasArtifactRenderer(_def.canvasType)) {
+      const loading = !suppressLoadingGate && isBlockLoading(block);
+      const kindEnvelope = loading ? readEnvelope(block.metadata) : null;
+      if (loading && !kindEnvelope?.root.kind) {
+        const Loader = ARTIFACT_LOADING_COMPONENTS[_def.canvasType];
+        if (Loader) {
+          return /* @__PURE__ */ jsx(Loader, {}, index);
+        }
+      }
+      return withRecordChrome(
+        /* @__PURE__ */ jsx(
+          ArtifactRender,
+          {
+            canvasType: _def.canvasType,
+            mode: "inline",
+            raw: block.content,
+            serverData: block.serverData,
+            metadata: block.metadata,
+            taskId,
+            conversationId,
+            messageId,
+            blockIndex: index,
+            isStreamActive: loading,
+            onContentChange: !loading && replaceBlockContent ? (updated) => replaceBlockContent(block.content, updated, { origin: "kind" }) : void 0
+          },
+          index
+        )
+      );
+    }
+  }
+  const ctx = {
+    block,
+    index,
+    isStreamActive,
+    conversationId,
+    messageId,
+    durableMessageId,
+    taskId,
+    requestId,
+    isLastReasoningBlock,
+    hideReasoning,
+    hideToolResults,
+    machineFramesVisible,
+    replaceBlockContent,
+    renderBasicMarkdown,
+    outputSchema
+  };
+  const dispatch = resolveBlockDispatch(block.type);
+  if (dispatch) {
+    return withRecordChrome(dispatch(ctx));
+  }
+  reportUnregisteredBlockType(block.type, {
+    conversationId,
+    messageId,
+    requestId
+  });
+  if (block.content) return renderBasicMarkdown(block.content);
+  const UnknownDataEventBlock = BlockComponents.UnknownDataEventBlock;
+  if (!UnknownDataEventBlock) return renderBasicMarkdown("```json\n" + JSON.stringify({ type: block.type, data: block.serverData ?? null }, null, 2) + "\n```");
+  return /* @__PURE__ */ jsx(
+    UnknownDataEventBlock,
+    {
+      dataType: block.type,
+      data: block.serverData ?? {},
+      conversationId,
+      messageId
+    },
+    index
+  );
+};
+export {
+  BlockRenderer,
+  decideBlockRender,
+  pendingStructuredEnvelope,
+  settleBrokenKindRoute,
+  withTerminalEnvelope
+};