@ai-matrx/content-ir-react 0.1.0 → 0.4.0

package/dist/index.d.cts

@@ -42,8 +42,19 @@ declare const consoleErrorReporter: ContentIrErrorReporter;
  */
 /** JSON object, restated locally so this package depends on no host type. */
 type JsonObject = Record<string, unknown>;
-/** Which half of the shape a component draws. */
-type ComponentRole = "output" | "input";
+/**
+ * Which face of the shape a component draws.
+ *
+ * - `output` — the shape's finished value, the component a reader sees.
+ * - `input`  — the authoring form for a value of this shape.
+ * - `loading` — the shape's LOADING face: what renders from the instant the
+ *   kind is identified until its output component has a renderable frame.
+ *   Authored per kind like any other component and fed the region's partial
+ *   value each frame, so it can PERFORM the arrival (surface real text as it
+ *   lands) instead of drawing a shapeless skeleton. Optional: a kind with no
+ *   `loading` component falls back to the host's loading library.
+ */
+type ComponentRole = "output" | "input" | "loading";
 /**
  * One `content_ir.kind_component` row, projected to exactly what rendering
  * needs. Hosts map their own query result onto this.
@@ -430,7 +441,33 @@ type GenericFallbackReason =
 /** No compiled bridge and no `content_ir.kind_component` row at all. */
 "no-component"
 /** A component row exists but is held `is_active = false`. */
- | "inactive";
+ | "inactive"
+/**
+ * An ACTIVE component row exists and names `generic_structured` — i.e. the
+ * fallback, registered under a component's name. This reads as coverage to
+ * every count-the-rows check on the platform and is not: the reader still
+ * gets a key/value dump. Kept as its own reason because the repair differs
+ * (author a component AND retire the decoy row), and because a page that
+ * silently marked itself `by: "bundled"` here is how 226 of 428 active
+ * kinds came to be certified as renderable while rendering generically
+ * (found 2026-08-23).
+ */
+ | "generic-row"
+/**
+ * The envelope carries a kind-preserved RAW: the payload identified a
+ * registered kind but its value failed the schema (or the schema never
+ * arrived before the region closed). The instance is BROKEN, not
+ * component-less — the repair is fixing the payload/schema, and the generic
+ * floor must acknowledge the kind and surface the recorded problems.
+ */
+ | "broken-instance"
+/**
+ * The slug is not in the registry at all (typo, foreign emitter, a shape
+ * not yet created). Routed anyway — Arman's 2026-08-29 ruling: a root
+ * `__kind` key means the kind system owns the render, no exceptions. The
+ * repair is creating/registering the shape (or fixing the slug).
+ */
+ | "unregistered";
 interface IrRouteMarker {
     by: ComponentResolution["resolvedBy"] | "generic";
     key: string;

package/dist/index.d.ts

@@ -42,8 +42,19 @@ declare const consoleErrorReporter: ContentIrErrorReporter;
  */
 /** JSON object, restated locally so this package depends on no host type. */
 type JsonObject = Record<string, unknown>;
-/** Which half of the shape a component draws. */
-type ComponentRole = "output" | "input";
+/**
+ * Which face of the shape a component draws.
+ *
+ * - `output` — the shape's finished value, the component a reader sees.
+ * - `input`  — the authoring form for a value of this shape.
+ * - `loading` — the shape's LOADING face: what renders from the instant the
+ *   kind is identified until its output component has a renderable frame.
+ *   Authored per kind like any other component and fed the region's partial
+ *   value each frame, so it can PERFORM the arrival (surface real text as it
+ *   lands) instead of drawing a shapeless skeleton. Optional: a kind with no
+ *   `loading` component falls back to the host's loading library.
+ */
+type ComponentRole = "output" | "input" | "loading";
 /**
  * One `content_ir.kind_component` row, projected to exactly what rendering
  * needs. Hosts map their own query result onto this.
@@ -430,7 +441,33 @@ type GenericFallbackReason =
 /** No compiled bridge and no `content_ir.kind_component` row at all. */
 "no-component"
 /** A component row exists but is held `is_active = false`. */
- | "inactive";
+ | "inactive"
+/**
+ * An ACTIVE component row exists and names `generic_structured` — i.e. the
+ * fallback, registered under a component's name. This reads as coverage to
+ * every count-the-rows check on the platform and is not: the reader still
+ * gets a key/value dump. Kept as its own reason because the repair differs
+ * (author a component AND retire the decoy row), and because a page that
+ * silently marked itself `by: "bundled"` here is how 226 of 428 active
+ * kinds came to be certified as renderable while rendering generically
+ * (found 2026-08-23).
+ */
+ | "generic-row"
+/**
+ * The envelope carries a kind-preserved RAW: the payload identified a
+ * registered kind but its value failed the schema (or the schema never
+ * arrived before the region closed). The instance is BROKEN, not
+ * component-less — the repair is fixing the payload/schema, and the generic
+ * floor must acknowledge the kind and surface the recorded problems.
+ */
+ | "broken-instance"
+/**
+ * The slug is not in the registry at all (typo, foreign emitter, a shape
+ * not yet created). Routed anyway — Arman's 2026-08-29 ruling: a root
+ * `__kind` key means the kind system owns the render, no exceptions. The
+ * repair is creating/registering the shape (or fixing the slug).
+ */
+ | "unregistered";
 interface IrRouteMarker {
     by: ComponentResolution["resolvedBy"] | "generic";
     key: string;

package/dist/index.js

@@ -381,6 +381,12 @@ function applyIrKindRoute(block, env, options) {
   if (envelope.root.kindState === "pending_schema") return block;
   const def = env.kinds.getDefinition(kind);
   const resolution = env.components.resolve(kind, env.platform, "output");
+  if (envelope.root.kindState === "raw") {
+    return routeToGeneric(
+      block,
+      def || resolution ? "broken-instance" : "unregistered"
+    );
+  }
   const dbRouted = routeToDbComponent(block, kind, resolution, env);
   if (dbRouted) return dbRouted;
   if (def?.legacyBlockType) {
@@ -397,6 +403,9 @@ function applyIrKindRoute(block, env, options) {
     };
   }
   if (resolution?.isActive) {
+    if (resolution.componentKey === GENERIC_STRUCTURED_COMPONENT_KEY) {
+      return routeToGeneric(block, "generic-row");
+    }
     if (block.type === resolution.componentKey) return block;
     return {
       ...block,
@@ -410,7 +419,7 @@ function applyIrKindRoute(block, env, options) {
   if (def) {
     return routeToGeneric(block, resolution ? "inactive" : "no-component");
   }
-  return block;
+  return routeToGeneric(block, "unregistered");
 }
 function kindServerDataFromStoredValue(value, env) {
   if (!isRecord(value)) return null;
@@ -644,7 +653,7 @@ function GenericStructuredView({
   const { value, recovered } = readStructuredValue(content, metadata);
   const kind = envelope?.root.kind ?? (typeof value === "object" && value !== null && !Array.isArray(value) ? readObjectKind(value) : null) ?? "";
   const marker = readIrRouteMarker(metadata);
-  const note = marker?.reason === "inactive" ? "a custom view is registered but held inactive" : "no custom view yet";
+  const note = marker?.reason === "inactive" ? "a custom view is registered but held inactive" : marker?.reason === "broken-instance" ? "this instance did not match the shape's schema" : marker?.reason === "unregistered" ? "this shape isn't registered on this platform" : "no custom view yet";
   return /* @__PURE__ */ jsxs("div", { className: className ? `my-2 min-w-0 ${className}` : "my-2 min-w-0", children: [
     status === "streaming" ? streamingIndicator ?? /* @__PURE__ */ jsx("div", { className: "mb-2 text-xs text-muted-foreground", children: "Still arriving\u2026" }) : null,
     recovered ? host.renderValue({ value, ...kind ? { kind } : {}, note }) : (