@ai-matrx/rich-content 0.2.4 → 0.2.7

package/dist/display/chat-markdown/internal-handlers/MarkdownErrorBoundary.js

@@ -0,0 +1,40 @@
+import React from "react";
+import { captureReactRenderError } from "../../../utils/lifted/captureReactError.js";
+import {
+  isChunkLoadError,
+  notifyChunkLoadError
+} from "../../../utils/lifted/chunk-load-recovery.js";
+class MarkdownErrorBoundary extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = { hasError: false };
+  }
+  static getDerivedStateFromError(_) {
+    return { hasError: true };
+  }
+  componentDidCatch(error, errorInfo) {
+    console.error(
+      "[MarkdownStream] Error caught by boundary:",
+      error,
+      errorInfo
+    );
+    if (isChunkLoadError(error)) {
+      notifyChunkLoadError(error);
+    } else {
+      captureReactRenderError(error, {
+        boundary: "MarkdownErrorBoundary",
+        componentStack: errorInfo.componentStack ?? null
+      });
+    }
+    this.props.onError?.(error, errorInfo);
+  }
+  render() {
+    if (this.state.hasError) {
+      return this.props.fallback;
+    }
+    return this.props.children;
+  }
+}
+export {
+  MarkdownErrorBoundary
+};

package/dist/display/chat-markdown/internal-handlers/PlainTextFallback.d.ts

@@ -0,0 +1,8 @@
+import React from "react";
+interface PlainTextFallbackProps {
+    requestId?: string;
+    content: string;
+    className?: string;
+}
+export declare const PlainTextFallback: React.FC<PlainTextFallbackProps>;
+export {};

package/dist/display/chat-markdown/internal-handlers/PlainTextFallback.js

@@ -0,0 +1,91 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Suspense, lazy } from "react";
+import { cn } from "@ai-matrx/design-system";
+import { MarkdownErrorBoundary } from "./MarkdownErrorBoundary.js";
+import { findEmbeddedKindJsonRegions } from "@ai-matrx/content-ir/surfaces";
+import {
+  firstKindSlug,
+  hasKindKey,
+  hasKindKeyAnySpelling,
+  kindObjectProseBreak,
+  normalizeKindSpellings
+} from "@ai-matrx/content-ir/surfaces";
+import { kindTextToMarkdown } from "@ai-matrx/content-ir/surfaces";
+import { humanizeKind } from "@ai-matrx/content-ir/surfaces";
+const KindInstanceRender = lazy(
+  () => import("../../../host/app-bindings.js").then((m) => ({ default: m.KindInstanceRender }))
+);
+const FENCE_LINE = /^[ \t]*(`{3,}|~{3,})[^\n`]*$/gm;
+function isKindObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && typeof value.__kind === "string";
+}
+function textPieces(text) {
+  const cleaned = text.replace(FENCE_LINE, "");
+  if (!hasKindKey(cleaned)) return cleaned.trim() ? [{ type: "text", text: cleaned }] : [];
+  const keyAt = cleaned.search(/"__kind"\s*:/);
+  const objectAt = cleaned.lastIndexOf("{", keyAt);
+  const before = cleaned.slice(0, objectAt < 0 ? keyAt : objectAt);
+  const out = [];
+  if (before.trim()) out.push({ type: "text", text: before });
+  out.push({ type: "broken", kind: firstKindSlug(cleaned) });
+  const proseBreak = objectAt < 0 ? null : kindObjectProseBreak(cleaned.slice(objectAt));
+  if (proseBreak !== null) out.push(...textPieces(cleaned.slice(objectAt + proseBreak)));
+  return out;
+}
+function piecesOf(content) {
+  const pieces = [];
+  let cursor = 0;
+  for (const region of findEmbeddedKindJsonRegions(content)) {
+    let value = null;
+    try {
+      value = JSON.parse(region.content);
+    } catch {
+      value = null;
+    }
+    if (!isKindObject(value)) continue;
+    pieces.push(...textPieces(content.slice(cursor, region.start)));
+    pieces.push({ type: "kind", kind: value.__kind, value, source: region.content });
+    cursor = region.end;
+  }
+  pieces.push(...textPieces(content.slice(cursor)));
+  return pieces;
+}
+function ReadableText({ text }) {
+  return /* @__PURE__ */ jsx("div", { className: "whitespace-pre-wrap break-words", children: text });
+}
+const PlainTextFallback = ({
+  requestId,
+  content,
+  className
+}) => {
+  const containerStyles = cn(
+    "py-3 px-4 space-y-2 font-sans text-md antialiased leading-relaxed tracking-wide whitespace-pre-wrap break-words overflow-x-hidden min-w-0",
+    "block rounded-lg w-full bg-textured",
+    className
+  );
+  if (!content || !hasKindKeyAnySpelling(content)) {
+    return /* @__PURE__ */ jsx("div", { className: "mb-3 w-full min-w-0 text-left overflow-x-hidden", children: /* @__PURE__ */ jsx("div", { className: containerStyles, children: content || "No content available" }) });
+  }
+  return /* @__PURE__ */ jsx("div", { className: "mb-3 w-full min-w-0 text-left overflow-x-hidden", children: /* @__PURE__ */ jsx("div", { className: cn(containerStyles, "whitespace-normal"), children: piecesOf(normalizeKindSpellings(content)).map((piece, i) => {
+    if (piece.type === "text") return /* @__PURE__ */ jsx(ReadableText, { text: piece.text }, i);
+    if (piece.type === "broken") {
+      return /* @__PURE__ */ jsxs("p", { className: "text-sm text-muted-foreground", "data-kind-fallback": "broken", children: [
+        piece.kind ? humanizeKind(piece.kind) : "This content",
+        " could not be read"
+      ] }, i);
+    }
+    const readable = /* @__PURE__ */ jsx(ReadableText, { text: kindTextToMarkdown(piece.source) });
+    return /* @__PURE__ */ jsx(MarkdownErrorBoundary, { fallback: readable, children: /* @__PURE__ */ jsx(Suspense, { fallback: readable, children: /* @__PURE__ */ jsx(
+      KindInstanceRender,
+      {
+        kind: piece.kind,
+        value: piece.value,
+        showRoutingNote: false,
+        variant: "bare"
+      }
+    ) }) }, i);
+  }) }) });
+};
+export {
+  PlainTextFallback
+};

package/dist/display/chat-markdown/internal-handlers/SafeBlockRenderer.d.ts

@@ -0,0 +1,20 @@
+import type { AnswerEditRemarkMeta } from "../../block-interaction.js";
+import React from "react";
+import { RenderBlock } from "../block-registry/BlockRenderer.js";
+interface SafeBlockRendererProps {
+    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;
+    replaceBlockContent: (original: string, replacement: string, remark?: AnswerEditRemarkMeta) => void;
+    handleOpenEditor: () => void;
+    outputSchema?: unknown | null;
+}
+export declare const SafeBlockRenderer: React.FC<SafeBlockRendererProps>;
+export {};

package/dist/display/chat-markdown/internal-handlers/SafeBlockRenderer.js

@@ -0,0 +1,72 @@
+import { jsx } from "react/jsx-runtime";
+import { MarkdownErrorBoundary } from "./MarkdownErrorBoundary.js";
+import { BlockFallback } from "./BlockFallback.js";
+import { clientLazy } from "../../../utils/client-lazy.js";
+import SuspenseLoader from "../../../utils/lifted/SuspenseLoader.js";
+const BlockRenderer = clientLazy(
+  () => import("../block-registry/BlockRenderer.js").then((m) => m.BlockRenderer),
+  {
+    loading: () => /* @__PURE__ */ jsx("div", { className: "py-2 px-1 text-sm text-neutral-400", children: /* @__PURE__ */ jsx(SuspenseLoader, { centered: false, message: "Loading content\u2026" }) })
+  }
+);
+function blockContextTags(block, index) {
+  const sd = block.serverData ?? {};
+  const md = block.metadata ?? {};
+  const str = (v) => typeof v === "string" && v.length > 0 ? v : void 0;
+  const artifactType = str(sd.artifact_type) ?? str(md.artifactType);
+  return {
+    "data-mtx-ctx": "block",
+    "data-block-type": block.type,
+    "data-block-id": str(sd.id) ?? str(md.blockId) ?? str(md.id) ?? String(index),
+    "data-tool-name": str(sd.tool_name) ?? str(sd.toolName) ?? str(md.toolName),
+    "data-language": str(block.language),
+    // Artifact identity for materialized refs (mermaid, etc.).
+    "data-artifact-type": artifactType,
+    "data-artifact-id": str(sd.artifact_id) ?? str(md.artifactId),
+    // Mermaid's rendered SVG text is node LABELS, not the diagram DSL — so the
+    // raw source must be tagged explicitly for the context menu to pass the
+    // real diagram to an agent. Bounded to mermaid; DSL is small (<2KB typical).
+    "data-block-source": block.type === "mermaid" || artifactType === "mermaid" ? str(block.content) : void 0
+  };
+}
+const SafeBlockRenderer = ({
+  requestId,
+  block,
+  index,
+  isStreamActive,
+  onContentChange,
+  conversationId,
+  messageId,
+  taskId,
+  isLastReasoningBlock,
+  replaceBlockContent,
+  handleOpenEditor,
+  outputSchema
+}) => {
+  return /* @__PURE__ */ jsx("div", { className: "contents", ...blockContextTags(block, index), children: /* @__PURE__ */ jsx(
+    MarkdownErrorBoundary,
+    {
+      fallback: /* @__PURE__ */ jsx(BlockFallback, { block, isStreamActive }),
+      children: /* @__PURE__ */ jsx(
+        BlockRenderer,
+        {
+          requestId,
+          block,
+          index,
+          isStreamActive,
+          onContentChange,
+          conversationId,
+          messageId,
+          taskId,
+          isLastReasoningBlock,
+          replaceBlockContent,
+          handleOpenEditor,
+          outputSchema
+        }
+      )
+    }
+  ) });
+};
+export {
+  SafeBlockRenderer
+};

package/dist/display/chat-markdown/kind-source-view.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The SOURCE VIEW context — a subtree that shows what the author wrote (a
+ * ```xml fence's card, ruling (a)): a kind-looking region there is code being
+ * shown and stays as written. Its own module so the leaves that honour it
+ * (`KindTextGate`, `StandardBlock`, `InlineCodeSnippet`) read it without
+ * importing the pipeline.
+ */
+import React from "react";
+/** Declares a subtree a source view — kind regions in it stay as written. */
+export declare function KindSourceView({ children }: {
+    children: React.ReactNode;
+}): React.JSX.Element;
+/** Whether this subtree is a source view (see `KindSourceView`). */
+export declare function useKindSourceView(): boolean;

package/dist/display/chat-markdown/kind-source-view.js

@@ -0,0 +1,14 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+const KindSourceViewContext = createContext(false);
+function KindSourceView({ children }) {
+  return /* @__PURE__ */ jsx(KindSourceViewContext.Provider, { value: true, children: /* @__PURE__ */ jsx("div", { "data-kind-source": "explicit", className: "contents", children }) });
+}
+function useKindSourceView() {
+  return useContext(KindSourceViewContext);
+}
+export {
+  KindSourceView,
+  useKindSourceView
+};

package/dist/display/chat-markdown/matrx-variables/MatrxVariableInline.d.ts

@@ -0,0 +1,28 @@
+import React from "react";
+/**
+ * Inline renderer for `{{variable_name}}` tokens.
+ *
+ * Spacing invariants (MUST preserve):
+ *  - Root element is a `<span>` with `display: inline` (not inline-block)
+ *    so it never breaks line flow or grows its parent line box.
+ *  - `font-size`, `font-weight`, and `line-height` inherit from the parent
+ *    (paragraph, heading, list item, blockquote, table cell, etc.). No
+ *    text-sizing classes are applied.
+ *  - Visual distinction comes from background + inset ring only
+ *    (`ring-inset` uses box-shadow → does not expand layout box).
+ *  - Horizontal padding (`px-1`) + tiny margin (`mx-0.5`) add breathing
+ *    room without affecting vertical rhythm.
+ *
+ * Data invariants:
+ *  - The raw snake_case name lives on the DOM as `data-name` (set by the
+ *    remark plugin) and is preserved on every re-render.
+ *  - The pretty-cased label shown to the user is derived at render time
+ *    and is never persisted anywhere.
+ */
+interface MatrxVariableInlineProps {
+    "data-name"?: string;
+    name?: string;
+    children?: React.ReactNode;
+}
+export declare const MatrxVariableInline: React.FC<MatrxVariableInlineProps>;
+export default MatrxVariableInline;

package/dist/display/chat-markdown/matrx-variables/MatrxVariableInline.js

@@ -0,0 +1,65 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import {
+  HoverCard,
+  HoverCardContent,
+  HoverCardTrigger
+} from "@ai-matrx/design-system";
+import { cn } from "@ai-matrx/design-system";
+import { humanizeIdentifier } from "@ai-matrx/kit/text-case";
+const MatrxVariableInline = (props) => {
+  const rawName = props["data-name"] ?? props.name ?? "";
+  if (!rawName) {
+    return null;
+  }
+  const prettyLabel = humanizeIdentifier(rawName) || rawName;
+  const tokenString = `{{${rawName}}}`;
+  return /* @__PURE__ */ jsxs(HoverCard, { openDelay: 120, closeDelay: 80, children: [
+    /* @__PURE__ */ jsx(HoverCardTrigger, { asChild: true, children: /* @__PURE__ */ jsx(
+      "span",
+      {
+        className: cn(
+          "inline rounded px-1 mx-0.5",
+          "bg-primary/50 text-foreground",
+          "ring-1 ring-inset ring-primary/20",
+          "hover:bg-primary/75 hover:ring-primary/85",
+          "cursor-help transition-colors",
+          "border border-dashed border-primary"
+        ),
+        "data-name": rawName,
+        "data-matrx-variable": "",
+        children: prettyLabel
+      }
+    ) }),
+    /* @__PURE__ */ jsx(
+      HoverCardContent,
+      {
+        align: "start",
+        side: "top",
+        sideOffset: 6,
+        className: "w-64 p-3 border border-border rounded-xl",
+        children: /* @__PURE__ */ jsxs("div", { className: "space-y-2", children: [
+          /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-1.5", children: [
+            /* @__PURE__ */ jsx("span", { className: "inline-block h-1.5 w-1.5 rounded-full bg-primary" }),
+            /* @__PURE__ */ jsx("span", { className: "text-[10px] uppercase tracking-wider font-semibold text-muted-foreground", children: "Variable" })
+          ] }),
+          /* @__PURE__ */ jsx("div", { className: "text-sm font-semibold text-foreground leading-tight", children: prettyLabel }),
+          /* @__PURE__ */ jsxs("div", { className: "flex flex-col gap-1", children: [
+            /* @__PURE__ */ jsx("span", { className: "text-[10px] uppercase tracking-wide text-muted-foreground", children: "Token" }),
+            /* @__PURE__ */ jsx("code", { className: "font-mono text-[11px] bg-muted text-foreground px-1.5 py-0.5 rounded self-start break-all", children: tokenString })
+          ] }),
+          /* @__PURE__ */ jsxs("div", { className: "flex flex-col gap-1", children: [
+            /* @__PURE__ */ jsx("span", { className: "text-[10px] uppercase tracking-wide text-muted-foreground", children: "Raw Name" }),
+            /* @__PURE__ */ jsx("code", { className: "font-mono text-[11px] text-muted-foreground self-start break-all", children: rawName })
+          ] }),
+          /* @__PURE__ */ jsx("div", { className: "text-[11px] text-muted-foreground pt-1.5 border-t border-border", children: "More details coming soon." })
+        ] })
+      }
+    )
+  ] });
+};
+var MatrxVariableInline_default = MatrxVariableInline;
+export {
+  MatrxVariableInline,
+  MatrxVariableInline_default as default
+};

package/dist/display/chat-markdown/progressive-mount.d.ts

@@ -0,0 +1,18 @@
+import { type ReactNode } from "react";
+/** Blocks mounted in the first commit — above any real chat answer. */
+export declare const PROGRESSIVE_FIRST_SLICE = 200;
+/** Blocks added per follow-up slice. */
+export declare const PROGRESSIVE_SLICE = 150;
+/** Blocks mounted without the reader scrolling; the rest follow the scroll. */
+export declare const PROGRESSIVE_AUTO_LIMIT = 600;
+/** Next count after one slice; pure so it is testable. */
+export declare function nextProgressiveCount(current: number, total: number): number;
+export interface ProgressiveMount {
+    /** How many blocks to render now. */
+    shown: number;
+    /** Render after the mounted blocks: null once everything is mounted. */
+    sentinel: ReactNode;
+}
+export declare function useProgressiveMount(total: number): ProgressiveMount;
+/** Back-compat shape for callers that only need the count. */
+export declare function useProgressiveCount(total: number): number;

package/dist/display/chat-markdown/progressive-mount.js

@@ -0,0 +1,90 @@
+"use client";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { nearestScrollRoot } from "../../utils/lifted/scroll-root.js";
+import { useRenderAllRequested } from "../../mermaid/lazy-draw.js";
+import { startTransition, useEffect, useRef, useState } from "react";
+import { formatCount } from "@ai-matrx/kit/format";
+import { Button } from "@ai-matrx/design-system/controls";
+const PROGRESSIVE_FIRST_SLICE = 200;
+const PROGRESSIVE_SLICE = 150;
+const PROGRESSIVE_AUTO_LIMIT = 600;
+function nextProgressiveCount(current, total) {
+  return Math.min(total, current + PROGRESSIVE_SLICE);
+}
+function useProgressiveMount(total) {
+  const [mounted, setMounted] = useState(() => Math.min(total, PROGRESSIVE_FIRST_SLICE));
+  if (total <= PROGRESSIVE_FIRST_SLICE && mounted > PROGRESSIVE_FIRST_SLICE) {
+    setMounted(PROGRESSIVE_FIRST_SLICE);
+  }
+  const renderAll = useRenderAllRequested();
+  const shown = renderAll ? total : Math.max(Math.min(total, PROGRESSIVE_FIRST_SLICE), Math.min(mounted, total));
+  const auto = shown < Math.min(total, PROGRESSIVE_AUTO_LIMIT);
+  useEffect(() => {
+    if (!auto) return void 0;
+    const timer = setTimeout(() => {
+      startTransition(
+        () => setMounted(
+          (m) => Math.min(PROGRESSIVE_AUTO_LIMIT, nextProgressiveCount(Math.max(m, shown), total))
+        )
+      );
+    }, 0);
+    return () => clearTimeout(timer);
+  }, [auto, shown, total]);
+  const more = () => startTransition(() => setMounted((m) => nextProgressiveCount(Math.max(m, shown), total)));
+  const sentinel = shown >= total ? null : /* @__PURE__ */ jsx(ScrollSentinel, { active: !auto, onVisible: more, shown, total }, shown);
+  return { shown, sentinel };
+}
+function useProgressiveCount(total) {
+  return useProgressiveMount(total).shown;
+}
+function ScrollSentinel({
+  active,
+  onVisible,
+  shown,
+  total
+}) {
+  const ref = useRef(null);
+  useEffect(() => {
+    const el = ref.current;
+    if (!active || !el || typeof IntersectionObserver === "undefined") return void 0;
+    const io = new IntersectionObserver(
+      (entries) => {
+        if (entries.some((e) => e.isIntersecting)) onVisible();
+      },
+      // Its own scroller, so the margin holds inside a panel or drawer too.
+      { root: nearestScrollRoot(el), rootMargin: "1500px 0px" }
+    );
+    io.observe(el);
+    return () => io.disconnect();
+  }, [active, onVisible]);
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      ref,
+      "data-progressive-sentinel": "",
+      role: "status",
+      className: "py-3 text-center text-xs text-muted-foreground",
+      children: active ? /* @__PURE__ */ jsxs(Button, { variant: "link", onClick: onVisible, children: [
+        "Showing ",
+        formatCount(shown),
+        " of ",
+        formatCount(total),
+        " blocks \u2014 more load as you scroll (or click)"
+      ] }) : /* @__PURE__ */ jsxs(Fragment, { children: [
+        "Loading ",
+        shown.toLocaleString(),
+        " of ",
+        total.toLocaleString(),
+        " blocks\u2026"
+      ] })
+    }
+  );
+}
+export {
+  PROGRESSIVE_AUTO_LIMIT,
+  PROGRESSIVE_FIRST_SLICE,
+  PROGRESSIVE_SLICE,
+  nextProgressiveCount,
+  useProgressiveCount,
+  useProgressiveMount
+};

package/dist/display/chat-markdown/render-block-to-content-block.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The live-stream hop: a Redux `RenderBlockPayload` (StreamBlockAccumulator
+ * output, `state.activeRequests[requestId].renderBlocks`) becomes the flat
+ * `RenderBlock` shape BlockRenderer consumes.
+ *
+ * LOAD-BEARING MAPPING: `rb.data` → `block.serverData`. For untyped code
+ * blocks (fenced ```json / bare JSON) the accumulator emits
+ * `data: { language: "json" }` — that annotation object arrives here as a
+ * TRUTHY `serverData`. Downstream consumers must therefore never treat "has
+ * serverData" as "has kind/typed data" for a block that still needs routing
+ * (see `applyIrKindRoute`, which derives routed serverData from the
+ * `metadata.__ir` envelope and discards this annotation).
+ *
+ * Extracted from EnhancedChatMarkdown so tests can drive the REAL hop —
+ * the 2026-07-04 "No flashcards available yet" bug lived exactly on this
+ * seam and was invisible to tests that built blocks by hand.
+ */
+import type { RenderBlockPayload } from "@ai-matrx/agents/generated/stream-events";
+import type { RenderBlock } from "./block-registry/BlockRenderer.js";
+/**
+ * THE ARTIFACT BODY. The accumulator keeps an `<artifact …>` block's tag lines
+ * in `content` (its `metadata.rawXml` must round-trip the source verbatim);
+ * the reload splitter hands the renderer only the body between the tags.
+ * ArtifactBlock parses `content` AS the payload, so the live block drew
+ * "No flashcards available yet" settled and the raw `__kind` JSON mid-stream
+ * while a reload drew the cards. Same body on both paths, by construction:
+ * the opening tag, the closing tag (or the closer's partial tail mid-stream)
+ * and the blank edges go; the body is untouched.
+ */
+export declare function artifactBodyOf(content: string): string;
+export declare function renderBlockToContentBlock(rb: RenderBlockPayload): RenderBlock;

package/dist/display/chat-markdown/render-block-to-content-block.js

@@ -0,0 +1,32 @@
+function artifactBodyOf(content) {
+  let body = content;
+  const open = /^\s*<artifact\b[^>]*>/i.exec(body);
+  if (open) body = body.slice(open[0].length);
+  else if (/^\s*<artifact\b/i.test(body)) return "";
+  const close = body.lastIndexOf("</artifact>");
+  if (close !== -1) {
+    body = body.slice(0, close);
+  } else {
+    const tail = /<\/?[a-z]*$/i.exec(body);
+    if (tail && "</artifact>".startsWith(tail[0].toLowerCase())) {
+      body = body.slice(0, tail.index);
+    }
+  }
+  return body.replace(/^\s*\n/, "").trimEnd();
+}
+function renderBlockToContentBlock(rb) {
+  return {
+    type: rb.type,
+    content: rb.type === "artifact" ? artifactBodyOf(rb.content ?? "") : rb.content ?? "",
+    serverData: rb.data ?? void 0,
+    metadata: rb.metadata,
+    language: rb.data?.language,
+    src: rb.data?.src,
+    alt: rb.data?.alt,
+    isStreamingBlock: rb.status === "streaming"
+  };
+}
+export {
+  artifactBodyOf,
+  renderBlockToContentBlock
+};

package/dist/display/chat-markdown/settle-stream-blocks.d.ts

@@ -0,0 +1,50 @@
+/**
+ * THE FINAL PASS: when a stream completes, the screen must equal the one-shot
+ * reading of the finished text — the same blocks a reload renders.
+ *
+ * Why this exists (chair ruling, 2026-09-26 — common-docs
+ * projects/rich-content-unification/REGISTER.md, RC-B3 rulings): while a
+ * message streams, "a settled block never changes" holds with ONE documented
+ * exception — an orphan `</thinking>` / `</think>` / `</reasoning>` closer
+ * that arrives late. Models do emit closer-only reasoning (the opener lost
+ * upstream); the one-shot splitter then folds everything before the closer
+ * into a thinking region (`metadata.continuation`), which no streaming reader
+ * can know in advance. The live StreamBlockAccumulator strips such a closer
+ * (and reports it) instead, so its final blocks differ from a reload's.
+ *
+ * So after completion, when the one-shot reading contains an orphan rescue,
+ * the renderer shows the one-shot blocks. Only client-produced accumulator
+ * blocks (`client_…`) are replaced: their reload path IS the one-shot split of
+ * the stored text; server-produced blocks carry server envelopes and stay.
+ */
+import { type SplitterBlock } from "../markdown-classification/processors/utils/content-splitter-v2.js";
+export interface SettleStreamInput {
+    /** The stream is still arriving (never settled). */
+    isStreamActive: boolean;
+    /** Ids of the accumulator's render blocks for this message. */
+    blockIds: readonly string[];
+    /** The finished text. */
+    content: string;
+}
+/**
+ * The one-shot blocks to show instead of the accumulator's, or null when the
+ * accumulator's final blocks already are the one-shot reading.
+ */
+export declare function settledOneShotBlocks({ isStreamActive, blockIds, content, }: SettleStreamInput): SplitterBlock[] | null;
+export interface SettledFromRecordInput {
+    /** The stream is still arriving. */
+    isStreamActive: boolean;
+    /** The committed message this turn renders, when there is one. */
+    messageId: string | null | undefined;
+    /** How many display segments the committed record holds (0 = not in the store yet). */
+    recordSegmentCount: number;
+}
+/**
+ * THE FINAL SCREEN IS THE RELOAD. A turn whose stream has ended and whose
+ * committed record is in the store renders from that record — the same parts,
+ * split the same one-shot way, that a reload renders — never from the live
+ * render blocks (server- or client-built), which are an incremental reading
+ * of a text still arriving (verify-RC-B3 F1/F2). A turn with no committed
+ * record yet keeps its live blocks (and the orphan-rescue pass above).
+ */
+export declare function renderSettledFromRecord({ isStreamActive, messageId, recordSegmentCount, }: SettledFromRecordInput): boolean;

package/dist/display/chat-markdown/settle-stream-blocks.js

@@ -0,0 +1,26 @@
+import {
+  splitContentIntoBlocksV2
+} from "../markdown-classification/processors/utils/content-splitter-v2.js";
+const REASONING_CLOSER = /<\/(?:thinking|think|reasoning)\s*>/i;
+function settledOneShotBlocks({
+  isStreamActive,
+  blockIds,
+  content
+}) {
+  if (isStreamActive || blockIds.length === 0) return null;
+  if (!blockIds.every((id) => id.startsWith("client_"))) return null;
+  if (!REASONING_CLOSER.test(content)) return null;
+  const oneShot = splitContentIntoBlocksV2(content);
+  return oneShot.some((block) => block.metadata?.continuation === true) ? oneShot : null;
+}
+function renderSettledFromRecord({
+  isStreamActive,
+  messageId,
+  recordSegmentCount
+}) {
+  return !isStreamActive && !!messageId && recordSegmentCount > 0;
+}
+export {
+  renderSettledFromRecord,
+  settledOneShotBlocks
+};

package/dist/display/chat-markdown/stable-blocks.d.ts

@@ -0,0 +1,15 @@
+/** Anything a splitter hands a renderer: a typed chunk of the document. */
+interface BlockLike {
+    type: string;
+    content: string;
+}
+/** Same block data, field by field (content strings compare by value). */
+export declare function sameBlock<T extends BlockLike>(a: T, b: T): boolean;
+/**
+ * Returns `next` with every block that equals a block of `prev` replaced by
+ * that previous object. Matching is by (type, content) in order of
+ * occurrence, so identity survives blocks shifting position. Returns `prev`
+ * itself when nothing changed at all.
+ */
+export declare function reuseUnchangedBlocks<T extends BlockLike>(prev: readonly T[], next: readonly T[]): T[];
+export {};