@ai-matrx/rich-content 0.2.161 → 0.2.162

package/CHANGELOG.md

@@ -1,9 +1,16 @@
 # 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
 
-UNVERIFIED: this release has no Unreleased entry and the source comparison could not be made (the caller supplied no source comparison). Whether source changed is unknown; consumer action is unknown.
-Check the package's gitHead on npm against this version's gitHead: `git diff <previous gitHead> <this gitHead> -- apps/shared/rich-content/src`.
+- **`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
 

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.161",
+  "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,7 +130,6 @@
     "unist-util-visit": "^5.1.0",
     "unist-util-visit-parents": "^6.0.2",
     "yaml": "^2.9.1",
-    "@ai-matrx/agents": "latest",
     "@ai-matrx/alchemy": "latest",
     "@ai-matrx/api": "latest",
     "@ai-matrx/canvas": "latest",
@@ -139,11 +138,12 @@
     "@ai-matrx/data": "latest",
     "@ai-matrx/design-system": "latest",
     "@ai-matrx/icons": "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/kit": "latest",
     "@ai-matrx/diff": "latest"
   },
   "peerDependencies": {
@@ -205,5 +205,5 @@
     "verify:modules-tarball": "node ./scripts/verify-modules-tarball.mjs",
     "verify:tarball": "node ./scripts/verify-tarball.mjs"
   },
-  "gitHead": "8b9cb7a612f386ad8858deac531fe5db8778490d"
+  "gitHead": "3260b81ccf1721d1a6a0ba08b238fdfa7d609ba5"
 }