@ai-matrx/rich-content 0.2.160 → 0.2.162

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.2.162
+### Unreleased
+
+- **THE RENDER RATCHET** (`display/chat-markdown/block-registry/render-ratchet.ts`; Arman, 2026-10-14: "once you go forward, you do not go back"). `BlockRenderer` keeps, per mounted block, the furthest render stage it drew (text → loader → generic → component) and a backward frame mid-stream (a bridge declining a half-arrived item, a mid-string parse, an emptied/retracted frame, a late row) keeps the last good decision on screen instead of swapping the component for its loader and back (each swap was an unmount + remount). It lets go when the block settles (the final value is the truth), when a different block takes the slot, or mid-stream only after `RATCHET_RELEASE_MIN_FRAMES` (120) distinct frames AND `RATCHET_RELEASE_MIN_MS` (8 s). Consumer action: none.
+- **One measured loader answer** (SHAPES-BUGS 2.5): `resolveLoadingSlugForKind` answers `origin: "pending"` while the kind's schema is still being read (host port `schemaState`, optional), never a premature "generic". New `useLoadingSlugForKind(kind)` (`kinds/react/loading/use-loading-slug`) demands the schema and re-reads on arrival — every surface reads it. Consumer action: matrx-frontend's Stream-tab facts and Preview loading path use the hook.
+- **A wrapping XML tag is consumed** (SHAPES-BUGS 2.2): `<output>\n{…kind…}\n</output>` no longer leaves `<output>` / `</output>` as two stray code cards around the component, live or reloaded. Consumer action: none.
+
+## 0.2.161
+### Unreleased
+
+- **`KindRenderHarness` / `useInsideKindRenderHarness`** (`kinds/react/render-harness`): a harness (kind-registry Preview, Shape Studio) wraps its renders in it, and `GenericStructuredBlock` files no `generic_floor_render` sighting from inside one. Scoped to the subtree — a generic block elsewhere on the same page still files. Consumer action: matrx-frontend wraps `KindRenderPaths` output in `<KindRenderHarness>`.
+
 ## 0.2.160
 
 Automatic changed-only republish (docs/metadata drift since the last tag — see

package/dist/display/blocks/diagram/InteractiveDiagramBlock.js

@@ -2,7 +2,7 @@
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { renderElement } from "@ai-matrx/alchemy/operate/capture";
 import { downloadFile, downloadUrl } from "@ai-matrx/kit/download";
-import { Button, Chip } from "@ai-matrx/design-system/controls";
+import { Button, Chip, Select } from "@ai-matrx/design-system/controls";
 import {
   useState,
   useCallback,
@@ -1408,18 +1408,19 @@ const DiagramFlow = ({
                 ] }),
                 selectedIsSection ? /* @__PURE__ */ jsxs("label", { className: "block text-[11px] font-medium text-foreground", children: [
                   "Border",
-                  /* @__PURE__ */ jsxs(
-                    "select",
+                  /* @__PURE__ */ jsx(
+                    Select,
                     {
+                      "aria-label": "Border",
+                      className: "mt-1 w-full",
                       value: selectedNode.data.groupStyle === "solid" || selectedNode.data.groupStyle === "dotted" ? selectedNode.data.groupStyle : "dashed",
-                      onChange: (event) => patchSelectedNode({
-                        groupStyle: event.target.value
+                      onValueChange: (v) => patchSelectedNode({
+                        groupStyle: v
                       }),
-                      className: "mt-1 w-full rounded-md border border-border bg-background px-2 py-1.5 text-xs text-foreground outline-none focus:border-primary",
-                      children: [
-                        /* @__PURE__ */ jsx("option", { value: "dashed", children: "Dashed" }),
-                        /* @__PURE__ */ jsx("option", { value: "dotted", children: "Dotted" }),
-                        /* @__PURE__ */ jsx("option", { value: "solid", children: "Solid" })
+                      options: [
+                        { value: "dashed", label: "Dashed" },
+                        { value: "dotted", label: "Dotted" },
+                        { value: "solid", label: "Solid" }
                       ]
                     }
                   )
@@ -1442,36 +1443,38 @@ const DiagramFlow = ({
                   /* @__PURE__ */ jsxs("div", { className: "grid grid-cols-2 gap-2", children: [
                     /* @__PURE__ */ jsxs("label", { className: "block text-[11px] font-medium text-foreground", children: [
                       "Style",
-                      /* @__PURE__ */ jsxs(
-                        "select",
+                      /* @__PURE__ */ jsx(
+                        Select,
                         {
+                          "aria-label": "Style",
+                          className: "mt-1 w-full",
                           value: typeof selectedNode.data.nodeType === "string" ? selectedNode.data.nodeType : "default",
-                          onChange: (event) => patchSelectedNode({ nodeType: event.target.value }),
-                          className: "mt-1 w-full rounded-md border border-border bg-background px-2 py-1.5 text-xs text-foreground outline-none focus:border-primary",
-                          children: [
-                            /* @__PURE__ */ jsx("option", { value: "default", children: "Plain" }),
-                            /* @__PURE__ */ jsx("option", { value: "start", children: "Start" }),
-                            /* @__PURE__ */ jsx("option", { value: "process", children: "Step" }),
-                            /* @__PURE__ */ jsx("option", { value: "decision", children: "Decision" }),
-                            /* @__PURE__ */ jsx("option", { value: "data", children: "Information" }),
-                            /* @__PURE__ */ jsx("option", { value: "end", children: "Finish" })
+                          onValueChange: (v) => patchSelectedNode({ nodeType: v }),
+                          options: [
+                            { value: "default", label: "Plain" },
+                            { value: "start", label: "Start" },
+                            { value: "process", label: "Step" },
+                            { value: "decision", label: "Decision" },
+                            { value: "data", label: "Information" },
+                            { value: "end", label: "Finish" }
                           ]
                         }
                       )
                     ] }),
                     /* @__PURE__ */ jsxs("label", { className: "block text-[11px] font-medium text-foreground", children: [
                       "Section",
-                      /* @__PURE__ */ jsxs(
-                        "select",
+                      /* @__PURE__ */ jsx(
+                        Select,
                         {
+                          "aria-label": "Section",
+                          className: "mt-1 w-full",
                           value: selectedNode.parentId ?? "none",
-                          onChange: (event) => moveSelectedBoxToSection(
-                            event.target.value === "none" ? null : event.target.value
+                          onValueChange: (v) => moveSelectedBoxToSection(
+                            v === "none" ? null : v
                           ),
-                          className: "mt-1 w-full rounded-md border border-border bg-background px-2 py-1.5 text-xs text-foreground outline-none focus:border-primary",
-                          children: [
-                            /* @__PURE__ */ jsx("option", { value: "none", children: "No section" }),
-                            sections.map((section) => /* @__PURE__ */ jsx("option", { value: section.id, children: String(section.data.label ?? "Section") }, section.id))
+                          options: [
+                            { value: "none", label: "No section" },
+                            ...sections.map((section) => ({ value: section.id, label: String(section.data.label ?? "Section") }))
                           ]
                         }
                       )
@@ -1533,39 +1536,41 @@ const DiagramFlow = ({
                   /* @__PURE__ */ jsxs("div", { className: "grid grid-cols-2 gap-2", children: [
                     /* @__PURE__ */ jsxs("label", { className: "block text-[11px] font-medium text-foreground", children: [
                       "Shape",
-                      /* @__PURE__ */ jsxs(
-                        "select",
+                      /* @__PURE__ */ jsx(
+                        Select,
                         {
+                          "aria-label": "Shape",
+                          className: "mt-1 w-full",
                           value: String(selectedNode.data.shape ?? "rounded"),
-                          onChange: (event) => patchSelectedNode({
-                            shape: event.target.value
+                          onValueChange: (v) => patchSelectedNode({
+                            shape: v
                           }),
-                          className: "mt-1 w-full rounded-md border border-border bg-background px-2 py-1.5 text-xs text-foreground outline-none focus:border-primary",
-                          children: [
-                            /* @__PURE__ */ jsx("option", { value: "rounded", children: "Rounded" }),
-                            /* @__PURE__ */ jsx("option", { value: "rectangle", children: "Rectangle" }),
-                            /* @__PURE__ */ jsx("option", { value: "pill", children: "Pill" }),
-                            /* @__PURE__ */ jsx("option", { value: "circle", children: "Circle" }),
-                            /* @__PURE__ */ jsx("option", { value: "diamond", children: "Diamond" }),
-                            /* @__PURE__ */ jsx("option", { value: "hexagon", children: "Hexagon" })
+                          options: [
+                            { value: "rounded", label: "Rounded" },
+                            { value: "rectangle", label: "Rectangle" },
+                            { value: "pill", label: "Pill" },
+                            { value: "circle", label: "Circle" },
+                            { value: "diamond", label: "Diamond" },
+                            { value: "hexagon", label: "Hexagon" }
                           ]
                         }
                       )
                     ] }),
                     /* @__PURE__ */ jsxs("label", { className: "block text-[11px] font-medium text-foreground", children: [
                       "Border",
-                      /* @__PURE__ */ jsxs(
-                        "select",
+                      /* @__PURE__ */ jsx(
+                        Select,
                         {
+                          "aria-label": "Border",
+                          className: "mt-1 w-full",
                           value: String(selectedNode.data.borderStyle ?? "solid"),
-                          onChange: (event) => patchSelectedNode({
-                            borderStyle: event.target.value
+                          onValueChange: (v) => patchSelectedNode({
+                            borderStyle: v
                           }),
-                          className: "mt-1 w-full rounded-md border border-border bg-background px-2 py-1.5 text-xs text-foreground outline-none focus:border-primary",
-                          children: [
-                            /* @__PURE__ */ jsx("option", { value: "solid", children: "Solid" }),
-                            /* @__PURE__ */ jsx("option", { value: "dashed", children: "Dashed" }),
-                            /* @__PURE__ */ jsx("option", { value: "dotted", children: "Dotted" })
+                          options: [
+                            { value: "solid", label: "Solid" },
+                            { value: "dashed", label: "Dashed" },
+                            { value: "dotted", label: "Dotted" }
                           ]
                         }
                       )
@@ -1573,17 +1578,18 @@ const DiagramFlow = ({
                   ] }),
                   /* @__PURE__ */ jsxs("label", { className: "block text-[11px] font-medium text-foreground", children: [
                     "Text",
-                    /* @__PURE__ */ jsxs(
-                      "select",
+                    /* @__PURE__ */ jsx(
+                      Select,
                       {
+                        "aria-label": "Text",
+                        className: "mt-1 w-full",
                         value: String(selectedNode.data.textAlign ?? "left"),
-                        onChange: (event) => patchSelectedNode({
-                          textAlign: event.target.value
+                        onValueChange: (v) => patchSelectedNode({
+                          textAlign: v
                         }),
-                        className: "mt-1 w-full rounded-md border border-border bg-background px-2 py-1.5 text-xs text-foreground outline-none focus:border-primary",
-                        children: [
-                          /* @__PURE__ */ jsx("option", { value: "left", children: "Left" }),
-                          /* @__PURE__ */ jsx("option", { value: "center", children: "Centered" })
+                        options: [
+                          { value: "left", label: "Left" },
+                          { value: "center", label: "Centered" }
                         ]
                       }
                     )
@@ -1609,37 +1615,39 @@ const DiagramFlow = ({
                 /* @__PURE__ */ jsxs("div", { className: "grid grid-cols-2 gap-2", children: [
                   /* @__PURE__ */ jsxs("label", { className: "block text-[11px] font-medium text-foreground", children: [
                     "Path",
-                    /* @__PURE__ */ jsxs(
-                      "select",
+                    /* @__PURE__ */ jsx(
+                      Select,
                       {
+                        "aria-label": "Path",
+                        className: "mt-1 w-full",
                         value: selectedEdge.data?.edgeType === "smoothstep" || selectedEdge.data?.edgeType === "step" || selectedEdge.data?.edgeType === "straight" ? selectedEdge.data.edgeType : "bezier",
-                        onChange: (event) => patchSelectedEdge({
-                          edgeType: event.target.value
+                        onValueChange: (v) => patchSelectedEdge({
+                          edgeType: v
                         }),
-                        className: "mt-1 w-full rounded-md border border-border bg-background px-2 py-1.5 text-xs text-foreground outline-none focus:border-primary",
-                        children: [
-                          /* @__PURE__ */ jsx("option", { value: "bezier", children: "Curved" }),
-                          /* @__PURE__ */ jsx("option", { value: "smoothstep", children: "Rounded" }),
-                          /* @__PURE__ */ jsx("option", { value: "step", children: "Stepped" }),
-                          /* @__PURE__ */ jsx("option", { value: "straight", children: "Straight" })
+                        options: [
+                          { value: "bezier", label: "Curved" },
+                          { value: "smoothstep", label: "Rounded" },
+                          { value: "step", label: "Stepped" },
+                          { value: "straight", label: "Straight" }
                         ]
                       }
                     )
                   ] }),
                   /* @__PURE__ */ jsxs("label", { className: "block text-[11px] font-medium text-foreground", children: [
                     "Line",
-                    /* @__PURE__ */ jsxs(
-                      "select",
+                    /* @__PURE__ */ jsx(
+                      Select,
                       {
+                        "aria-label": "Line",
+                        className: "mt-1 w-full",
                         value: selectedEdge.data?.lineStyle === "dashed" || selectedEdge.data?.lineStyle === "dotted" ? selectedEdge.data.lineStyle : "solid",
-                        onChange: (event) => patchSelectedEdge({
-                          lineStyle: event.target.value
+                        onValueChange: (v) => patchSelectedEdge({
+                          lineStyle: v
                         }),
-                        className: "mt-1 w-full rounded-md border border-border bg-background px-2 py-1.5 text-xs text-foreground outline-none focus:border-primary",
-                        children: [
-                          /* @__PURE__ */ jsx("option", { value: "solid", children: "Solid" }),
-                          /* @__PURE__ */ jsx("option", { value: "dashed", children: "Dashed" }),
-                          /* @__PURE__ */ jsx("option", { value: "dotted", children: "Dotted" })
+                        options: [
+                          { value: "solid", label: "Solid" },
+                          { value: "dashed", label: "Dashed" },
+                          { value: "dotted", label: "Dotted" }
                         ]
                       }
                     )
@@ -1648,38 +1656,40 @@ const DiagramFlow = ({
                 /* @__PURE__ */ jsxs("div", { className: "grid grid-cols-2 gap-2", children: [
                   /* @__PURE__ */ jsxs("label", { className: "block text-[11px] font-medium text-foreground", children: [
                     "Direction",
-                    /* @__PURE__ */ jsxs(
-                      "select",
+                    /* @__PURE__ */ jsx(
+                      Select,
                       {
+                        "aria-label": "Direction",
+                        className: "mt-1 w-full",
                         value: String(selectedEdge.data?.marker ?? "end"),
-                        onChange: (event) => patchSelectedEdge({
-                          marker: event.target.value
+                        onValueChange: (v) => patchSelectedEdge({
+                          marker: v
                         }),
-                        className: "mt-1 w-full rounded-md border border-border bg-background px-2 py-1.5 text-xs text-foreground outline-none focus:border-primary",
-                        children: [
-                          /* @__PURE__ */ jsx("option", { value: "end", children: "Forward" }),
-                          /* @__PURE__ */ jsx("option", { value: "start", children: "Backward" }),
-                          /* @__PURE__ */ jsx("option", { value: "both", children: "Both ends" }),
-                          /* @__PURE__ */ jsx("option", { value: "none", children: "No arrowheads" })
+                        options: [
+                          { value: "end", label: "Forward" },
+                          { value: "start", label: "Backward" },
+                          { value: "both", label: "Both ends" },
+                          { value: "none", label: "No arrowheads" }
                         ]
                       }
                     )
                   ] }),
                   /* @__PURE__ */ jsxs("label", { className: "block text-[11px] font-medium text-foreground", children: [
                     "Weight",
-                    /* @__PURE__ */ jsxs(
-                      "select",
+                    /* @__PURE__ */ jsx(
+                      Select,
                       {
+                        "aria-label": "Weight",
+                        className: "mt-1 w-full",
                         value: String(selectedEdge.data?.strokeWidth ?? 2),
-                        onChange: (event) => patchSelectedEdge({
-                          strokeWidth: Number(event.target.value)
+                        onValueChange: (v) => patchSelectedEdge({
+                          strokeWidth: Number(v)
                         }),
-                        className: "mt-1 w-full rounded-md border border-border bg-background px-2 py-1.5 text-xs text-foreground outline-none focus:border-primary",
-                        children: [
-                          /* @__PURE__ */ jsx("option", { value: "1", children: "Fine" }),
-                          /* @__PURE__ */ jsx("option", { value: "2", children: "Regular" }),
-                          /* @__PURE__ */ jsx("option", { value: "3", children: "Bold" }),
-                          /* @__PURE__ */ jsx("option", { value: "4", children: "Heavy" })
+                        options: [
+                          { value: "1", label: "Fine" },
+                          { value: "2", label: "Regular" },
+                          { value: "3", label: "Bold" },
+                          { value: "4", label: "Heavy" }
                         ]
                       }
                     )
@@ -1730,37 +1740,39 @@ const DiagramFlow = ({
                 /* @__PURE__ */ jsxs("div", { className: "grid grid-cols-2 gap-2", children: [
                   /* @__PURE__ */ jsxs("label", { className: "block text-[11px] font-medium text-foreground", children: [
                     "Background",
-                    /* @__PURE__ */ jsxs(
-                      "select",
+                    /* @__PURE__ */ jsx(
+                      Select,
                       {
+                        "aria-label": "Background",
+                        className: "mt-1 w-full",
                         value: diagram.renderHints?.background ?? "dots",
-                        onChange: (event) => chooseBackground(
-                          event.target.value === "lines" ? BackgroundVariant.Lines : event.target.value === "cross" ? BackgroundVariant.Cross : BackgroundVariant.Dots
+                        onValueChange: (v) => chooseBackground(
+                          v === "lines" ? BackgroundVariant.Lines : v === "cross" ? BackgroundVariant.Cross : BackgroundVariant.Dots
                         ),
-                        className: "mt-1 w-full rounded-md border border-border bg-background px-2 py-1.5 text-xs text-foreground outline-none focus:border-primary",
-                        children: [
-                          /* @__PURE__ */ jsx("option", { value: "dots", children: "Dots" }),
-                          /* @__PURE__ */ jsx("option", { value: "lines", children: "Lines" }),
-                          /* @__PURE__ */ jsx("option", { value: "cross", children: "Crosses" })
+                        options: [
+                          { value: "dots", label: "Dots" },
+                          { value: "lines", label: "Lines" },
+                          { value: "cross", label: "Crosses" }
                         ]
                       }
                     )
                   ] }),
                   /* @__PURE__ */ jsxs("label", { className: "block text-[11px] font-medium text-foreground", children: [
                     "Flow",
-                    /* @__PURE__ */ jsxs(
-                      "select",
+                    /* @__PURE__ */ jsx(
+                      Select,
                       {
+                        "aria-label": "Flow",
+                        className: "mt-1 w-full",
                         value: diagram.layout?.direction ?? "TB",
-                        onChange: (event) => patchLayout({
-                          direction: event.target.value
+                        onValueChange: (v) => patchLayout({
+                          direction: v
                         }),
-                        className: "mt-1 w-full rounded-md border border-border bg-background px-2 py-1.5 text-xs text-foreground outline-none focus:border-primary",
-                        children: [
-                          /* @__PURE__ */ jsx("option", { value: "TB", children: "Top to bottom" }),
-                          /* @__PURE__ */ jsx("option", { value: "LR", children: "Left to right" }),
-                          /* @__PURE__ */ jsx("option", { value: "BT", children: "Bottom to top" }),
-                          /* @__PURE__ */ jsx("option", { value: "RL", children: "Right to left" })
+                        options: [
+                          { value: "TB", label: "Top to bottom" },
+                          { value: "LR", label: "Left to right" },
+                          { value: "BT", label: "Bottom to top" },
+                          { value: "RL", label: "Right to left" }
                         ]
                       }
                     )

package/dist/display/blocks/generic/GenericStructuredBlock.js

@@ -10,6 +10,7 @@ import { collectKindProblems } from "../../../kinds/react/kind-problems.js";
 import { readEnvelope } from "../../../kinds/redux/render-block-envelope.js";
 import { reportKindComponentIncident } from "../../../host/kind-incident.js";
 import { KindFixItBar } from "../../../host/app-bindings.js";
+import { useInsideKindRenderHarness } from "../../../kinds/react/render-harness.js";
 import { StructuredValueTabs } from "./StructuredValueTabs.js";
 const StillArriving = /* @__PURE__ */ jsxs("div", { className: "mb-2 flex items-center gap-1.5 text-xs text-muted-foreground", children: [
   /* @__PURE__ */ jsx(Braces, { className: "h-3.5 w-3.5 shrink-0 animate-pulse" }),
@@ -18,14 +19,15 @@ const StillArriving = /* @__PURE__ */ jsxs("div", { className: "mb-2 flex items-
 function useGenericFloorAlarm(metadata) {
   const kind = readEnvelope(metadata)?.root.kind ?? null;
   const reason = readIrRouteMarker(metadata)?.reason ?? null;
+  const insideHarness = useInsideKindRenderHarness();
   useEffect(() => {
-    if (!kind) return;
+    if (!kind || insideHarness) return;
     reportKindComponentIncident({
       kind,
       errorType: "generic_floor_render",
       message: `"${kind}" rendered through the GENERIC structured viewer` + (reason === "inactive" ? " \u2014 a component row exists but is held is_active=false." : " \u2014 no component is bound, so the reader sees a key/value dump.")
     });
-  }, [kind, reason]);
+  }, [kind, reason, insideHarness]);
 }
 const GenericStructuredBlock = (props) => {
   useGenericFloorAlarm(props.metadata);

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

@@ -1,7 +1,7 @@
 "use client";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { durableRecordId } from "@ai-matrx/kit/ids";
-import React, { useCallback } from "react";
+import React, { useCallback, useRef } from "react";
 import { RichContentHostGate } from "../../../host/RichContentHostGate.js";
 import { BlockComponents, LoadingComponents } from "./BlockComponentRegistry.js";
 import { resolveArtifactDef } from "../../../host/app-bindings.js";
@@ -53,6 +53,7 @@ import {
   KindRecordChrome,
   kindHasRecordChrome
 } from "../../../host/app-bindings.js";
+import { advanceRatchet, EMPTY_RATCHET } from "./render-ratchet.js";
 import {
   isBlockLoading,
   resolveBlockDispatch,
@@ -292,11 +293,19 @@ const BlockRendererGated = ({
   const envelopeKind = readEnvelope(terminalBlock.metadata)?.root.kind ?? announcedKind ?? null;
   const kindRouteVersion = useContentIrKindVersion(envelopeKind);
   useEnsureKindRenderable(envelopeKind);
-  const decision = decideBlockRender(inputBlock, {
+  const frameDecision = decideBlockRender(inputBlock, {
     isStreamActive,
     suppressLoadingGate,
     route: (b) => routeBlockAtRegistryVersion(b, kindRouteVersion)
   });
+  const ratchetRef = useRef(EMPTY_RATCHET);
+  const settledBlock = !isStreamActive || inputBlock.isStreamingBlock === false;
+  const ratcheted = suppressLoadingGate ? { state: ratchetRef.current, decision: frameDecision } : advanceRatchet(ratchetRef.current, frameDecision, {
+    settled: settledBlock,
+    now: Date.now()
+  });
+  ratchetRef.current = ratcheted.state;
+  const decision = ratcheted.decision;
   const block = decision.block;
   const interruptedEnvelope = readEnvelope(block.metadata);
   const hasInterruptedKind = Boolean(

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

@@ -0,0 +1,76 @@
+/**
+ * THE RENDER RATCHET — a streaming block's render only moves FORWARD.
+ *
+ * Arman, 2026-10-14: "Going forwards is ok, but once you go forward, you do not go back
+ * unless we're ABSOLUTELY CONFIDENT something has gone wrong and we have multiple pieces of
+ * evidence." The stages, in order:
+ *
+ *   0 TEXT       — prose, or a raw code/JSON card
+ *   1 LOADER     — a JSON region that could be (or is) a kind, still arriving
+ *   2 GENERIC    — the structured floor drew it
+ *   3 COMPONENT  — the kind's own component (routed, provisional, artifact, dispatch)
+ *
+ * `decideBlockRender` is a pure function of ONE frame, and a single frame of a token stream
+ * is often not valid: a bridge declines a half-arrived item, a nested value is mid-string, a
+ * component row is a beat late, a parser has not seen the closing brace. Each of those used
+ * to drop the block a stage (component → loader → component), and because each stage is a
+ * different element, React unmounted the component and mounted it again — the "re-render"
+ * the reader sees. The ratchet sits on top of that decision at the ONE place every block is
+ * drawn (`BlockRenderer`): a frame that would move the block BACKWARD keeps the last good
+ * decision on screen (its block, its props) and waits for the next frame.
+ *
+ * It lets go only on strong evidence:
+ *   - the block SETTLED (its own `isStreamingBlock === false`, or the message stream ended):
+ *     the final decision is the truth, whatever stage it is;
+ *   - the content stopped CONTINUING the held block (the slot now holds a different block):
+ *     the ratchet starts over for the new one;
+ *   - mid-stream, the frames have disagreed for at least RATCHET_RELEASE_MIN_FRAMES distinct
+ *     content updates AND RATCHET_RELEASE_MIN_MS of wall time, both — a region that really
+ *     turned into something else keeps saying so, a transient hiccup never lasts that long.
+ *
+ * Pure: `advanceRatchet` takes the previous state and returns the next; the hook that keeps
+ * the state per mounted block lives in BlockRenderer.
+ */
+import type { BlockRenderDecision } from "./BlockRenderer.js";
+/**
+ * Distinct content updates a backward verdict must survive before it is believed mid-stream.
+ * A token stream sends roughly one update per animation frame; transient invalid states
+ * (mid-string, mid-key, a declined half item) last a handful. 120 is ~2 s of steady tokens.
+ */
+export declare const RATCHET_RELEASE_MIN_FRAMES = 120;
+/**
+ * Wall time a backward verdict must persist mid-stream, AND-ed with the frame count, so a
+ * burst of fast chunks cannot meet the bar in a blink and a stalled stream cannot meet it on
+ * time alone. Generous on purpose: the stream's end is the normal release.
+ */
+export declare const RATCHET_RELEASE_MIN_MS = 8000;
+export type RenderStage = 0 | 1 | 2 | 3;
+export declare const RENDER_STAGE_NAMES: readonly ["text", "loader", "generic", "component"];
+/** Where a single frame's decision sits on the forward path. */
+export declare function renderStageOf(decision: BlockRenderDecision): RenderStage;
+export interface RatchetState {
+    /** The decision on screen. */
+    held: BlockRenderDecision | null;
+    heldStage: RenderStage;
+    /** The held block's content — the continuation check reads it. */
+    heldContent: string;
+    /** The last content seen (frames are counted on content CHANGE, so a re-render is not a frame). */
+    lastContent: string;
+    /** Consecutive distinct frames that wanted to go backward, and since when. */
+    disagreeFrames: number;
+    disagreeSince: number | null;
+}
+export declare const EMPTY_RATCHET: RatchetState;
+export interface RatchetInput {
+    /** The block settled: its own stream closed, or the message stream ended. */
+    settled: boolean;
+    /** Wall clock (ms). */
+    now: number;
+}
+/**
+ * One frame through the ratchet: the state to keep and the decision to draw.
+ */
+export declare function advanceRatchet(state: RatchetState, next: BlockRenderDecision, { settled, now }: RatchetInput): {
+    state: RatchetState;
+    decision: BlockRenderDecision;
+};

package/dist/display/chat-markdown/block-registry/render-ratchet.js

@@ -0,0 +1,73 @@
+import { GENERIC_STRUCTURED_COMPONENT_KEY } from "../../../kinds/react/kind-route.js";
+const RATCHET_RELEASE_MIN_FRAMES = 120;
+const RATCHET_RELEASE_MIN_MS = 8e3;
+const CONTINUATION_PREFIX = 48;
+const RENDER_STAGE_NAMES = ["text", "loader", "generic", "component"];
+const TEXT_TYPES = /* @__PURE__ */ new Set(["text", "code"]);
+function renderStageOf(decision) {
+  if (decision.gate?.kind === "provisional") return 3;
+  if (decision.gate?.kind === "loader") return 1;
+  const type = String(decision.block.type);
+  if (TEXT_TYPES.has(type)) return 0;
+  if (type === GENERIC_STRUCTURED_COMPONENT_KEY) return 2;
+  return 3;
+}
+const EMPTY_RATCHET = {
+  held: null,
+  heldStage: 0,
+  heldContent: "",
+  lastContent: "",
+  disagreeFrames: 0,
+  disagreeSince: null
+};
+function contentOf(decision) {
+  const content = decision.rawBlock.content;
+  return typeof content === "string" ? content : "";
+}
+function continues(heldContent, next) {
+  const prefix = heldContent.slice(0, CONTINUATION_PREFIX).trimEnd();
+  if (!prefix) return true;
+  return next.startsWith(prefix) || prefix.startsWith(next.slice(0, CONTINUATION_PREFIX).trimEnd());
+}
+function accept(next, stage, content) {
+  return {
+    held: next,
+    heldStage: stage,
+    heldContent: content,
+    lastContent: content,
+    disagreeFrames: 0,
+    disagreeSince: null
+  };
+}
+function advanceRatchet(state, next, { settled, now }) {
+  const stage = renderStageOf(next);
+  const content = contentOf(next);
+  const take = () => {
+    const accepted = accept(next, stage, content);
+    return { state: accepted, decision: next };
+  };
+  if (!state.held || settled) return take();
+  if (!content.trim() && state.heldContent.trim()) {
+    return { state: { ...state, lastContent: content }, decision: state.held };
+  }
+  if (!continues(state.heldContent, content)) return take();
+  if (stage >= state.heldStage) return take();
+  const isNewFrame = content !== state.lastContent;
+  const disagreeFrames = state.disagreeFrames + (isNewFrame ? 1 : 0);
+  const disagreeSince = state.disagreeSince ?? now;
+  if (disagreeFrames >= RATCHET_RELEASE_MIN_FRAMES && now - disagreeSince >= RATCHET_RELEASE_MIN_MS) {
+    return take();
+  }
+  return {
+    state: { ...state, lastContent: content, disagreeFrames, disagreeSince },
+    decision: state.held
+  };
+}
+export {
+  EMPTY_RATCHET,
+  RATCHET_RELEASE_MIN_FRAMES,
+  RATCHET_RELEASE_MIN_MS,
+  RENDER_STAGE_NAMES,
+  advanceRatchet,
+  renderStageOf
+};

package/dist/display/markdown-classification/processors/utils/content-splitter-core.js

@@ -96,6 +96,10 @@ function withFenceSurface(metadata, language, content, envelopes) {
   const envelope = envelopes.fenceRegion(language, content);
   return envelope ? { ...metadata ?? {}, [IR_ENVELOPE_KEY]: envelope } : metadata;
 }
+const XML_TAG = /<\/?[A-Za-z][\w:.-]*(?:\s[^<>]*)?\/?>/g;
+function isBareXmlTagPiece(content) {
+  return /</.test(content) && !content.replace(XML_TAG, "").trim();
+}
 const wrapperSources = /* @__PURE__ */ new WeakMap();
 function wrapperSourceOf(block) {
   return wrapperSources.get(block);
@@ -166,6 +170,7 @@ function recoverEmbeddedKindJsonBlocksWith(input, envelopes) {
       );
       followsKind = false;
       if (!content) continue;
+      if (genericXml && isBareXmlTagPiece(content)) continue;
       recovered.push({
         ...block,
         content,

package/dist/host/types.d.ts

@@ -11,6 +11,12 @@ export interface RichContentKindRegistry {
     getSchema(kind: string): KindSchema | undefined;
     getEmittedJsonSchema(kind: string): unknown;
     getDeclaredLoadingComponent(kind: string): string | null;
+    /**
+     * Has this kind's schema been read yet? "pending" until the read settles. Optional: a host
+     * without it is treated as always settled. The loading-slug answer reads it so a cold
+     * registry says "checking" instead of a wrong "generic" (one measured answer, 2026-10-14).
+     */
+    schemaState?(kind: string): "loaded" | "pending" | "absent" | "failed";
     isKnownKind(kind: string): boolean;
     isRenderableKind(kind: string): boolean;
     listDefinitions(): KindDefinition[];

package/dist/kinds/react/loading/resolve-loading-slug.d.ts

@@ -1,6 +1,6 @@
 import { type KindLoadingSlug } from "./kind-loading-slugs.js";
 /** Where the answer came from — surfaced so the Stream tab / doctor can say. */
-export type LoadingSlugOrigin = "declared" | "derived" | "generic";
+export type LoadingSlugOrigin = "declared" | "derived" | "generic" | "pending";
 export interface LoadingSlugResolution {
     /** The library slug, or null when nothing beat the generic skeleton. */
     slug: KindLoadingSlug | null;

package/dist/kinds/react/loading/resolve-loading-slug.js

@@ -43,6 +43,9 @@ function resolveLoadingSlugForKind(kind) {
   if (derived) {
     return invalidDeclared === void 0 ? { slug: derived, origin: "derived" } : { slug: derived, origin: "derived", invalidDeclared };
   }
+  if (invalidDeclared === void 0 && kindRegistry.schemaState?.(kind) === "pending") {
+    return { slug: null, origin: "pending" };
+  }
   return invalidDeclared === void 0 ? GENERIC : { slug: null, origin: "generic", invalidDeclared };
 }
 export {

package/dist/kinds/react/loading/use-loading-slug.d.ts

@@ -0,0 +1,4 @@
+import { type LoadingSlugResolution } from "./resolve-loading-slug.js";
+export declare function useLoadingSlugForKind(kind: string | null | undefined): LoadingSlugResolution;
+/** The version is an ARGUMENT so no compiler pass can memoise the answer past an arrival. */
+export declare function readLoadingSlugAtVersion(kind: string | null | undefined, version: number): LoadingSlugResolution;

package/dist/kinds/react/loading/use-loading-slug.js

@@ -0,0 +1,17 @@
+"use client";
+import { useContentIrKindVersion } from "../use-registry-repaint.js";
+import { useEnsureKindRenderable } from "../ensure-kind-renderable.js";
+import { resolveLoadingSlugForKind } from "./resolve-loading-slug.js";
+function useLoadingSlugForKind(kind) {
+  const version = useContentIrKindVersion(kind ?? null);
+  useEnsureKindRenderable(kind ?? null);
+  return readLoadingSlugAtVersion(kind, version);
+}
+function readLoadingSlugAtVersion(kind, version) {
+  void version;
+  return resolveLoadingSlugForKind(kind);
+}
+export {
+  readLoadingSlugAtVersion,
+  useLoadingSlugForKind
+};

package/dist/kinds/react/render-harness.d.ts

@@ -0,0 +1,17 @@
+/**
+ * RENDER HARNESSES ARE NOT READERS (defect 2026-10-14).
+ *
+ * A harness — the kind-registry Preview, the Shape Studio — renders every path
+ * on purpose: streaming frames, partial payloads, a component landing after
+ * first paint. A block that reaches the generic floor INSIDE one is the harness
+ * doing its job, not a reader being let down, so it must not file a
+ * "a reader got the generic view" sighting. Scoped to the harness's own
+ * subtree: a block rendered anywhere else on the same page (a chat dock, a
+ * second surface) still files.
+ */
+import React from "react";
+export declare function KindRenderHarness({ children }: {
+    children: React.ReactNode;
+}): React.JSX.Element;
+/** True when this component renders inside a {@link KindRenderHarness}. */
+export declare function useInsideKindRenderHarness(): boolean;

package/dist/kinds/react/render-harness.js

@@ -0,0 +1,14 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+const KindRenderHarnessContext = createContext(false);
+function KindRenderHarness({ children }) {
+  return /* @__PURE__ */ jsx(KindRenderHarnessContext.Provider, { value: true, children });
+}
+function useInsideKindRenderHarness() {
+  return useContext(KindRenderHarnessContext);
+}
+export {
+  KindRenderHarness,
+  useInsideKindRenderHarness
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/rich-content",
-  "version": "0.2.160",
+  "version": "0.2.162",
   "description": "The AI Matrx formatted-text engine: the one markdown renderer, streaming markdown, the block splitter and renderer, the generic blocks, <RichContent> levels, the rich-document action registry and menus, copy, and the selection toolbar — as portable React.",
   "type": "module",
   "license": "MIT",
@@ -130,21 +130,21 @@
     "unist-util-visit": "^5.1.0",
     "unist-util-visit-parents": "^6.0.2",
     "yaml": "^2.9.1",
-    "@ai-matrx/canvas": "latest",
+    "@ai-matrx/alchemy": "latest",
     "@ai-matrx/api": "latest",
+    "@ai-matrx/canvas": "latest",
     "@ai-matrx/content-ir": "latest",
-    "@ai-matrx/agents": "latest",
-    "@ai-matrx/data": "latest",
     "@ai-matrx/content-ir-react": "latest",
-    "@ai-matrx/alchemy": "latest",
+    "@ai-matrx/data": "latest",
     "@ai-matrx/design-system": "latest",
     "@ai-matrx/icons": "latest",
-    "@ai-matrx/diff": "latest",
-    "@ai-matrx/kit": "latest",
+    "@ai-matrx/agents": "latest",
     "@ai-matrx/media": "latest",
     "@ai-matrx/print": "latest",
     "@ai-matrx/records": "latest",
-    "@ai-matrx/records-ui": "latest"
+    "@ai-matrx/records-ui": "latest",
+    "@ai-matrx/kit": "latest",
+    "@ai-matrx/diff": "latest"
   },
   "peerDependencies": {
     "react": ">=19.0.0",
@@ -205,5 +205,5 @@
     "verify:modules-tarball": "node ./scripts/verify-modules-tarball.mjs",
     "verify:tarball": "node ./scripts/verify-tarball.mjs"
   },
-  "gitHead": "4d6a83481c2d4de4a5a1561f666fc8eba07e2617"
+  "gitHead": "3260b81ccf1721d1a6a0ba08b238fdfa7d609ba5"
 }