@ai-matrx/rich-content 0.0.0 → 0.2.3

package/dist/kinds/host/route-env.d.ts

@@ -0,0 +1,33 @@
+/**
+ * THE MATRIX BINDING of `@ai-matrx/content-ir-react`'s route environment.
+ *
+ * The render DECISIONS live in the package; the registries, the resolution
+ * platform, and the error sink are ours. This module is the one place those
+ * two halves meet, and it is deliberately React-free so reducers, stream
+ * accumulators, and tests can import it.
+ */
+import type { KindRouteEnv } from "@ai-matrx/content-ir-react";
+/**
+ * `web` is not a placeholder: `content_ir.kind_component.platform` already
+ * models react-native and friends, and a host that lies here renders the wrong
+ * component everywhere. This app is the web one.
+ */
+export declare const MATRX_CONTENT_IR_PLATFORM: "web";
+export declare const matrxKindRouteEnv: KindRouteEnv;
+/**
+ * Block types THIS app owns and the route must never re-type.
+ *
+ * An `artifact` block has an identity, a version, and a Canvas to open in, and
+ * since 2026-08-18 it carries `metadata.__ir` so SELECTORS can read the
+ * envelope (`selectKindEnvelope` — the live flashcard preview and every other
+ * wrapped-payload surface). That envelope is DATA there, not a route: routing
+ * it to the bare kind component would strip the artifact chrome and lose the
+ * door to the Canvas.
+ *
+ * A `matrx` block is a Kind Directive — its reserved-namespace slug is BY
+ * DESIGN never a kind_definition row, so any resolution the route could find
+ * for it would be wrong, and re-typing it away from MatrxEnvelopeBlock
+ * re-opens the raw-JSON break the Kind Directives merge closed (adversarial
+ * finding A-8: today the block survives only because the lookup misses).
+ */
+export declare const MATRX_OWNED_BLOCK_TYPES: readonly ["artifact", "matrx"];

package/dist/kinds/host/route-env.js

@@ -0,0 +1,16 @@
+import { captureError } from "../../host/diagnostics.js";
+import { kindRegistry } from "../../host/kind-registry.js";
+import { componentRegistry } from "../../host/component-registry.js";
+const MATRX_CONTENT_IR_PLATFORM = "web";
+const matrxKindRouteEnv = {
+  kinds: kindRegistry,
+  components: componentRegistry,
+  reportError: (report) => captureError(report),
+  platform: MATRX_CONTENT_IR_PLATFORM
+};
+const MATRX_OWNED_BLOCK_TYPES = ["artifact", "matrx"];
+export {
+  MATRX_CONTENT_IR_PLATFORM,
+  MATRX_OWNED_BLOCK_TYPES,
+  matrxKindRouteEnv
+};

package/dist/kinds/react/KindEscapedNotice.d.ts

@@ -0,0 +1,14 @@
+import React from "react";
+import type { FoundKindMarker } from "./kind-problems.js";
+export declare function KindEscapedNotice({ markers, rendered, }: {
+    markers: FoundKindMarker[];
+    /**
+     * The host already drew the value as its kind (the JSON block's settled
+     * kind route, Arman 2026-09-30). A REGISTERED slug is still reported — it
+     * escaped the promotion path — but the line saying it is "not rendering as
+     * its component" would now be false, so nothing is shown. An UNREGISTERED
+     * slug keeps its line.
+     */
+    rendered?: boolean;
+}): React.JSX.Element | null;
+export default KindEscapedNotice;

package/dist/kinds/react/KindEscapedNotice.js

@@ -0,0 +1,72 @@
+"use client";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { humanizeIdentifier } from "@ai-matrx/kit/text-case";
+import { useEffect } from "react";
+import { TriangleAlert } from "lucide-react";
+import { isTableKind } from "@ai-matrx/records";
+import { kindRegistry } from "../../host/kind-registry.js";
+import { useEnsureKindRenderable } from "./ensure-kind-renderable.js";
+import { useContentIrKindVersion } from "./use-registry-repaint.js";
+import { readAtVersionForKey } from "./registry-versioned.js";
+import { reportKindComponentIncident } from "../../host/kind-incident.js";
+import { captureError } from "../../host/diagnostics.js";
+const screamed = /* @__PURE__ */ new Set();
+const registeredCache = /* @__PURE__ */ new Map();
+function KindEscapedNotice({
+  markers,
+  rendered = false
+}) {
+  const first = markers[0] ?? null;
+  const slug = first?.slug ?? null;
+  useEnsureKindRenderable(slug);
+  const kindVersion = useContentIrKindVersion(slug);
+  const registered = readAtVersionForKey(
+    registeredCache,
+    slug ?? "",
+    kindVersion,
+    () => Boolean(slug && kindRegistry.isRenderableKind(slug))
+  );
+  const tableKind = isTableKind(slug);
+  useEffect(() => {
+    if (!slug || !registered || tableKind) return;
+    const firstPath = first?.path;
+    const key = `${slug}:${firstPath === void 0 ? "" : firstPath}`;
+    if (screamed.has(key)) return;
+    screamed.add(key);
+    captureError({
+      source: "content-ir",
+      relation: slug,
+      message: `Registered kind "${slug}" rendered as a raw JSON code block \u2014 it escaped the promotion path (path: ${first?.path || "root"}).`,
+      hint: "The accumulator/splitter should have promoted this region (or embedded-kind recovery should have caught it). Find which arrival path delivered it.",
+      recoverable: true
+    });
+    reportKindComponentIncident({
+      kind: slug,
+      errorType: "kind_escaped_render",
+      message: `Registered kind "${slug}" rendered as a raw JSON code block (escaped the promotion path at ${first?.path || "root"}).`
+    });
+  }, [slug, registered, tableKind, first?.path]);
+  if (!first) return null;
+  if (rendered && registered) return null;
+  return /* @__PURE__ */ jsxs("div", { className: "mb-1 flex items-start gap-1.5 text-xs text-amber-700 dark:text-amber-400", children: [
+    /* @__PURE__ */ jsx(TriangleAlert, { className: "mt-0.5 h-3.5 w-3.5 shrink-0" }),
+    /* @__PURE__ */ jsxs("span", { children: [
+      registered ? /* @__PURE__ */ jsxs(Fragment, { children: [
+        "This JSON contains a ",
+        /* @__PURE__ */ jsx("span", { className: "font-medium", children: humanizeIdentifier(first.slug) }),
+        " ",
+        "Shape instance that is not rendering as its component \u2014 this is a pipeline defect and has been reported."
+      ] }) : /* @__PURE__ */ jsxs(Fragment, { children: [
+        "This JSON declares a Shape (",
+        /* @__PURE__ */ jsx("span", { className: "font-medium", children: humanizeIdentifier(first.slug) }),
+        ") that isn't registered on this platform \u2014 check the name, or create the Shape to render it properly."
+      ] }),
+      markers.length > 1 ? ` (+${markers.length - 1} more)` : null
+    ] })
+  ] });
+}
+var KindEscapedNotice_default = KindEscapedNotice;
+export {
+  KindEscapedNotice,
+  KindEscapedNotice_default as default
+};

package/dist/kinds/react/ProvisionalKindBoundary.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The Matrix binding of the provisional-render safety net and the "still
+ * arriving" affordance (streaming partial kinds).
+ *
+ * Both live in `@ai-matrx/content-ir-react`: the boundary catches a component
+ * that throws on a provisional value, SCREAMS to the Error Inspector, drops the
+ * kind back to withhold for the session, and falls back to that kind's loading
+ * skeleton; the frame rides a `ShimmerText` chip on the block's top edge with
+ * no layout cost. Read the semantics there.
+ */
+import type { ReactNode } from "react";
+export declare function ProvisionalKindBoundary(props: {
+    kind: string;
+    fallback: ReactNode;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function ProvisionalKindFrame({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist/kinds/react/ProvisionalKindBoundary.js

@@ -0,0 +1,17 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import {
+  ProvisionalKindBoundary as SharedProvisionalKindBoundary,
+  ProvisionalKindFrame as SharedProvisionalKindFrame
+} from "@ai-matrx/content-ir-react";
+import { ContentIrHostBoundary } from "../../host/ContentIrHostBoundary.js";
+function ProvisionalKindBoundary(props) {
+  return /* @__PURE__ */ jsx(ContentIrHostBoundary, { children: /* @__PURE__ */ jsx(SharedProvisionalKindBoundary, { ...props }) });
+}
+function ProvisionalKindFrame({ children }) {
+  return /* @__PURE__ */ jsx(ContentIrHostBoundary, { children: /* @__PURE__ */ jsx(SharedProvisionalKindFrame, { children }) });
+}
+export {
+  ProvisionalKindBoundary,
+  ProvisionalKindFrame
+};

package/dist/kinds/react/ensure-kind-renderable.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Fire-and-forget: make sure this kind's schema and web output component are
+ * fetched (or known-missing). Safe to call redundantly — every layer dedupes.
+ *
+ * DD-215: the demand is UNCONDITIONAL for the component. See the comment in
+ * the body — a resolution that exists is not the same as a resolution that is
+ * settled, and the difference is which component a reader sees.
+ */
+export declare function ensureKindRenderable(kind: string): void;
+/**
+ * Hook form for render paths: request on mount and whenever the kind
+ * changes. Pass null for blocks with no envelope kind (nothing to fetch).
+ */
+export declare function useEnsureKindRenderable(kind: string | null): void;

package/dist/kinds/react/ensure-kind-renderable.js

@@ -0,0 +1,45 @@
+"use client";
+import { useEffect } from "react";
+import { kindRegistry } from "../../host/kind-registry.js";
+import { componentRegistry } from "../../host/component-registry.js";
+import { MATRX_CONTENT_IR_PLATFORM } from "../host/route-env.js";
+function ensureKindRenderable(kind) {
+  if (!kindRegistry.getSchema(kind)) {
+    kindRegistry.requestSchema(kind);
+  }
+  componentRegistry.requestComponent(kind, MATRX_CONTENT_IR_PLATFORM, "output");
+  announceWrongComponent(kind);
+}
+function announceWrongComponent(kind) {
+  const resolution = componentRegistry.resolve(
+    kind,
+    MATRX_CONTENT_IR_PLATFORM,
+    "output"
+  );
+  const sourcelessDbRow = resolution?.resolvedBy === "db" && resolution.source === "db" && resolution.isActive && !resolution.hasComponentSource;
+  if (!sourcelessDbRow && !componentRegistry.wasRefused(kind)) return;
+  void (async () => {
+    try {
+      const { reportKindComponentIncident } = await import("../../host/kind-incident.js");
+      reportKindComponentIncident({
+        kind,
+        errorType: "component_read_refused",
+        platform: MATRX_CONTENT_IR_PLATFORM,
+        role: "output",
+        componentKey: resolution?.componentKey ?? null,
+        componentUpdatedAt: resolution?.updatedAt ?? null,
+        message: sourcelessDbRow ? `"${kind}" is bound to the active component "${resolution?.componentKey}" (source='db'), but the resolver holds no body for it, so the route refused it and the reader was shown the platform's bundled component instead. Nothing will fetch the body again on its own.` : `The reader was shown the platform's bundled component for "${kind}" because this organization's component row could not be READ \u2014 the request carried no session and the door refused it.`
+      });
+    } catch {
+    }
+  })();
+}
+function useEnsureKindRenderable(kind) {
+  useEffect(() => {
+    if (kind) ensureKindRenderable(kind);
+  }, [kind]);
+}
+export {
+  ensureKindRenderable,
+  useEnsureKindRenderable
+};

package/dist/kinds/react/kind-problems.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The kind-problems reader — the ONE place the parser's recorded evidence of a
+ * broken / degraded / unroutable kind instance is flattened for human display.
+ *
+ * WHY THIS EXISTS (Arman, 2026-08-29): the parser has always recorded exactly
+ * what went wrong with a kind region — `residue.notices` carries `parse_error`,
+ * `raw_fallback` (schema violations, duplicate keys, missing `__kind`),
+ * `degrade_data_rescued`; `root.status`/`kindState` carry degradation; the
+ * route marker carries why no component rendered — and NOTHING in the UI ever
+ * read any of it. A shape that failed rendered as an anonymous key/value dump,
+ * indistinguishable from data that was never a shape at all. That silence is
+ * what made kind rendering feel random. This module turns that evidence into
+ * `KindProblem[]`, consumed by the Errors tab in `StructuredValueTabs` — so a
+ * broken kind is ACKNOWLEDGED as a kind, with its exact problems, everywhere
+ * the fallback renders.
+ *
+ * Pure over envelope data (`CanonicalBlockIR` is plain JSON from
+ * `@ai-matrx/content-ir`). Host diagnostics are host property (content-ir-twin
+ * boundary) — this makes no routing decision and renders nothing.
+ */
+import type { CanonicalBlockIR } from "@ai-matrx/content-ir";
+import type { IrRouteMarker } from "./kind-route.js";
+export type KindProblemSeverity = "error" | "warning" | "info";
+export interface KindProblem {
+    /** Stable machine code (`parse_error`, `raw_fallback`, `component_inactive`, …). */
+    code: string;
+    /** Human sentence — shown verbatim in the Errors tab. */
+    message: string;
+    /** Region-relative path of the node the problem is about ("" = root). */
+    path?: string;
+    severity: KindProblemSeverity;
+}
+/**
+ * Flatten everything the envelope + route marker recorded about why this kind
+ * instance is not rendering as its component. Empty array = a clean value that
+ * simply has no component yet (the fix-it bar's territory, not an error).
+ */
+export declare function collectKindProblems(envelope: CanonicalBlockIR | null | undefined, marker?: IrRouteMarker | null): KindProblem[];
+/** True when any collected problem is a real error (drives the tab's tint). */
+export declare function hasKindErrors(problems: KindProblem[]): boolean;
+export interface FoundKindMarker {
+    slug: string;
+    /** Dotted path inside the scanned value ("" = the value itself). */
+    path: string;
+}
+/**
+ * Deep-scan a parsed JSON value for `__kind` markers — the tripwire for a kind
+ * instance that escaped the promotion path and is being shown as anonymous
+ * JSON. Bounded (node + depth caps) so a pathological payload cannot stall a
+ * render; caps mean "found some", never an exhaustive census.
+ */
+export declare function findKindMarkers(value: unknown, limit?: number): FoundKindMarker[];
+/**
+ * Keep the raw-JSON tripwire about the boundary it can actually prove.
+ *
+ * A marker is escaped only when the canonical envelope did not already claim
+ * that exact path/kind. A schema-invalid kind deliberately remains on the raw
+ * JSON fallback, but it was still promoted; reporting it as a promotion crack
+ * sends repair patrols to the wrong producer and hides the real validation
+ * evidence carried by the envelope.
+ */
+export declare function findEscapedKindMarkers(value: unknown, envelope: CanonicalBlockIR | null | undefined, limit?: number): FoundKindMarker[];

package/dist/kinds/react/kind-problems.js

@@ -0,0 +1,134 @@
+const ERROR_NOTICE_CODES = /* @__PURE__ */ new Set(["parse_error", "raw_fallback"]);
+function noticeSeverity(code) {
+  if (ERROR_NOTICE_CODES.has(code)) return "error";
+  if (code === "partial_unvalidated") return "info";
+  return "warning";
+}
+function residueProblems(residue, path) {
+  if (!residue) return [];
+  const problems = [];
+  for (const notice of residue.notices ?? []) {
+    problems.push({
+      code: notice.code,
+      message: notice.message,
+      ...path ? { path } : {},
+      severity: noticeSeverity(notice.code)
+    });
+  }
+  const extraKeys = residue.extra ? Object.keys(residue.extra) : [];
+  if (extraKeys.length > 0) {
+    problems.push({
+      code: "unknown_keys",
+      message: `Keys not in this shape's schema (kept, not lost): ${extraKeys.join(", ")}`,
+      ...path ? { path } : {},
+      severity: "warning"
+    });
+  }
+  return problems;
+}
+function collectKindProblems(envelope, marker) {
+  const problems = [];
+  if (envelope) {
+    const root = envelope.root;
+    if (root.status === "error") {
+      problems.push({
+        code: "region_error",
+        message: "This region hit a fatal parse error \u2014 the payload below is what arrived before it broke.",
+        severity: "error"
+      });
+    }
+    if (root.kindState === "raw" && root.kind) {
+      problems.push({
+        code: "degraded_raw",
+        message: `This is a "${root.kind}" shape instance, but it could not be validated against the shape's schema, so it degraded to plain data.`,
+        severity: "error"
+      });
+    }
+    if (root.kindState === "pending_schema") {
+      problems.push({
+        code: "schema_unavailable",
+        message: `The schema for "${root.kind}" had not loaded when this region finished.`,
+        severity: "warning"
+      });
+    }
+    if (root.kindState === "unverified" && root.kind) {
+      problems.push({
+        code: "schema_unavailable",
+        message: `No field schema is registered for "${root.kind}", so this payload could not be checked. The data is shown as it arrived \u2014 this is a gap in the shape, not in the content.`,
+        severity: "warning"
+      });
+    }
+    problems.push(...residueProblems(root.residue, ""));
+    if (envelope.nodeIndex) {
+      for (const [pathKey, node] of Object.entries(envelope.nodeIndex)) {
+        if (node.kindState === "raw" && node.kind) {
+          problems.push({
+            code: "nested_degraded_raw",
+            message: `Nested "${node.kind}" at ${pathKey} failed validation and degraded to plain data.`,
+            path: pathKey,
+            severity: "error"
+          });
+        }
+        problems.push(...residueProblems(node.residue, pathKey));
+      }
+    }
+  }
+  if (marker?.reason === "inactive") {
+    problems.push({
+      code: "component_inactive",
+      message: "A component is registered for this shape but is held inactive \u2014 activate it to render this properly.",
+      severity: "warning"
+    });
+  } else if (marker?.reason === "generic-row") {
+    problems.push({
+      code: "generic_component_row",
+      message: "This shape's registered component IS the generic viewer \u2014 a real component still needs to be authored.",
+      severity: "warning"
+    });
+  }
+  return problems;
+}
+function hasKindErrors(problems) {
+  return problems.some((p) => p.severity === "error");
+}
+const KIND_KEY = "__kind";
+const SCAN_NODE_CAP = 2e3;
+const SCAN_DEPTH_CAP = 8;
+function findKindMarkers(value, limit = 5) {
+  const found = [];
+  let visited = 0;
+  const walk = (node, path, depth) => {
+    if (found.length >= limit) return;
+    if (visited++ > SCAN_NODE_CAP || depth > SCAN_DEPTH_CAP) return;
+    if (Array.isArray(node)) {
+      node.forEach(
+        (item, i) => walk(item, path ? `${path}.${i}` : String(i), depth + 1)
+      );
+      return;
+    }
+    if (typeof node !== "object" || node === null) return;
+    const record = node;
+    const slug = record[KIND_KEY];
+    if (typeof slug === "string" && slug.trim()) {
+      found.push({ slug: slug.trim(), path });
+    }
+    for (const [key, child] of Object.entries(record)) {
+      if (key === KIND_KEY) continue;
+      walk(child, path ? `${path}.${key}` : key, depth + 1);
+    }
+  };
+  walk(value, "", 0);
+  return found;
+}
+function findEscapedKindMarkers(value, envelope, limit = 5) {
+  return findKindMarkers(value, limit).filter((marker) => {
+    const claimedNode = marker.path ? envelope?.nodeIndex?.[marker.path] : envelope?.root;
+    return claimedNode?.kind !== marker.slug;
+  });
+}
+export {
+  collectKindProblems,
+  findEscapedKindMarkers,
+  findKindMarkers,
+  hasKindErrors
+};

package/dist/kinds/react/kind-route.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The Matrix binding of THE KIND ROUTE.
+ *
+ * The route itself — envelope → registered kind → the right component, with the
+ * db-override flip, the compiled-bridge path, the resolver path, and the R6
+ * generic fallback — lives in `@ai-matrx/content-ir-react`
+ * (`route/kind-route.ts`), and since 0.8.0 the per-host partial application
+ * does too (`createKindRouteBinding`). Read the semantics there.
+ *
+ * This module only INJECTS our env + owned block types (host/route-env.ts) and
+ * keeps the historical import path stable so ~60 call sites and every doc
+ * pointer still read the same.
+ */
+export { DB_KIND_COMPONENT_KEY, GENERIC_STRUCTURED_COMPONENT_KEY, IR_ROUTE_KEY, readIrRouteMarker, type GenericFallbackReason, type IrRoutableBlock, type IrRouteMarker, } from "@ai-matrx/content-ir-react";
+/** Route one block through the Matrix registries. */
+export declare const applyIrKindRoute: <T extends import("@ai-matrx/content-ir-react").IrRoutableBlock>(block: T) => T;
+/**
+ * Rehydration route for STRUCTURED persisted artifacts (Track 2B): given a
+ * stored zero-loss value object, derive the registered kind's legacy
+ * `serverData` with no re-parse. Null for non-objects, unregistered kinds, or
+ * kinds without a legacy bridge.
+ */
+export declare const kindServerDataFromStoredValue: (value: unknown) => Record<string, unknown> | null;

package/dist/kinds/react/kind-route.js

@@ -0,0 +1,24 @@
+import { createKindRouteBinding } from "@ai-matrx/content-ir-react";
+import {
+  MATRX_OWNED_BLOCK_TYPES,
+  matrxKindRouteEnv
+} from "../host/route-env.js";
+import {
+  DB_KIND_COMPONENT_KEY,
+  GENERIC_STRUCTURED_COMPONENT_KEY,
+  IR_ROUTE_KEY,
+  readIrRouteMarker
+} from "@ai-matrx/content-ir-react";
+const binding = createKindRouteBinding(matrxKindRouteEnv, {
+  ownedTypes: MATRX_OWNED_BLOCK_TYPES
+});
+const applyIrKindRoute = binding.applyIrKindRoute;
+const kindServerDataFromStoredValue = binding.kindServerDataFromStoredValue;
+export {
+  DB_KIND_COMPONENT_KEY,
+  GENERIC_STRUCTURED_COMPONENT_KEY,
+  IR_ROUTE_KEY,
+  applyIrKindRoute,
+  kindServerDataFromStoredValue,
+  readIrRouteMarker
+};

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

@@ -0,0 +1,58 @@
+/**
+ * DERIVED loading slugs — the smart floor under the declared one.
+ *
+ * A kind that never declared `metadata.loading_component` used to fall all
+ * the way through to the `generic` skeleton, which tells the reader nothing
+ * about what is coming. On 2026-08-25 that was 354 of the 357 renderable
+ * ACTIVE kinds: a backlog nobody can close one row at a time.
+ *
+ * So the fallback stops being dumb. A kind's own SCHEMA already says what
+ * shape it is — a long prose body is a document, a list of structured items
+ * is a list, image fields are media — and the loader whose silhouette
+ * matches the finished component is derivable from exactly that. Every kind
+ * therefore gets a shape-appropriate loader with zero authoring, zero DB
+ * writes, and zero deploys.
+ *
+ * PRECEDENCE — declaration always wins:
+ *   metadata.loading_component  →  this derivation  →  `generic`
+ * so setting a slug is still the way to override. The order is executed in
+ * ONE place, `resolve-loading-slug.ts` — never re-inline it as a `??` chain,
+ * because an INVALID declaration has to fall through to this derivation
+ * rather than short-circuit to `generic`.
+ *
+ * The shape doctor agrees with that precedence (2026-08-25): a kind with a
+ * DERIVED loader reads `ok` and raises no finding, because a shape-appropriate
+ * loader is a real loader however it was chosen. The `no-loading-component`
+ * yellow now fires only when derivation finds nothing distinctive either — the
+ * kinds that genuinely do stream behind the generic skeleton (428 yellows
+ * became 19).
+ *
+ * The rules read the schema, never the instance value: derivation must be
+ * stable for a kind, identical on every render, and available before a
+ * single byte of the value has arrived.
+ */
+import type { KindSchema } from "@ai-matrx/content-ir";
+import type { KindLoadingSlug } from "./kind-loading-slugs.js";
+/**
+ * The best-matching library slug for this schema, or null when nothing in the
+ * shape is distinctive enough to beat the generic skeleton.
+ *
+ * Ordered most-specific first. The order encodes a judgment made with Arman
+ * on 2026-08-24 while looking at real shapes: a kind with BOTH a prose body
+ * and structured lists (a newsjacking article: `article_body` + quotes +
+ * sources + faqs) reads as a DOCUMENT, because the body is what fills the
+ * screen — the lists are supporting material.
+ */
+export declare function inferLoadingSlug(schema: KindSchema | undefined | null): KindLoadingSlug | null;
+/**
+ * The SAME derivation over a raw JSON Schema.
+ *
+ * Most kinds have no parser `KindSchema` at all: Python owns them and stores
+ * only `emitted_json_schema` (344 of 392 undeclared renderable kinds on
+ * 2026-08-25, measured — `kind_definition.data` is NULL for every one). A
+ * derivation that reads only `KindSchema` is therefore blind to the large
+ * majority of the backlog it exists to serve, which is why this second door
+ * exists rather than a second set of rules: both doors normalize to the same
+ * `{name → type}` census and run the identical precedence above.
+ */
+export declare function inferLoadingSlugFromJsonSchema(jsonSchema: unknown): KindLoadingSlug | null;

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

@@ -0,0 +1,100 @@
+const MEDIA_NAME = /(^|_)(image|images|photo|photos|thumbnail|cover_image|video|videos|audio|media)(_|$)/i;
+const GALLERY_NAME = /(^|_)(gallery|images|photos|screenshots|slides_images)(_|$)/i;
+const BODY_NAME = /(^|_)(body|article_body|content|markdown|text|prose|transcript|summary_long|full_text|report|essay|description_long)(_|$)/i;
+const CODE_NAME = /(^|_)(code|snippet|source|diff|patch|sql|script)(_|$)/i;
+const DOC_ARRAY_NAME = /(^|_)(sections|chapters|paragraphs|pages)(_|$)/i;
+const CHART_NAME = /(^|_)(series|datapoints|data_points|metrics|chart|trend|timeseries)(_|$)/i;
+const TIMELINE_NAME = /(^|_)(timeline|events|milestones|history|phases|periods)(_|$)/i;
+const STEP_NAME = /(^|_)(steps|stages|progress|checklist|tasks)(_|$)/i;
+const STAT_NAME = /(^|_)(stats|statistics|totals|counts|kpis|summary_stats)(_|$)/i;
+function isStructuredArray(field) {
+  return field.type === "array" || field.type === "json[]";
+}
+function isProseField(name, field) {
+  return field.type === "string" && BODY_NAME.test(name);
+}
+function inferLoadingSlug(schema) {
+  if (!schema) return null;
+  if (schema.root) {
+    if (schema.root.type === "string") return "document";
+    if (isStructuredArray(schema.root)) return "list";
+    return null;
+  }
+  const entries = Object.entries(schema.fields ?? {}).filter(
+    ([name]) => name !== "__kind"
+  );
+  if (entries.length === 0) return null;
+  let hasProse = false;
+  let hasDocArray = false;
+  let structuredArrays = 0;
+  let hasMedia = false;
+  let hasGallery = false;
+  let hasCode = false;
+  let hasChart = false;
+  let hasTimeline = false;
+  let hasSteps = false;
+  let hasStats = false;
+  for (const [name, field] of entries) {
+    if (!field || typeof field !== "object") continue;
+    if (isProseField(name, field)) hasProse = true;
+    if (isStructuredArray(field)) {
+      structuredArrays += 1;
+      if (DOC_ARRAY_NAME.test(name)) hasDocArray = true;
+      if (GALLERY_NAME.test(name)) hasGallery = true;
+      if (CHART_NAME.test(name)) hasChart = true;
+      if (TIMELINE_NAME.test(name)) hasTimeline = true;
+      if (STEP_NAME.test(name)) hasSteps = true;
+      if (STAT_NAME.test(name)) hasStats = true;
+    }
+    if (MEDIA_NAME.test(name) && !isStructuredArray(field)) hasMedia = true;
+    if (CODE_NAME.test(name) && field.type === "string") hasCode = true;
+  }
+  if (hasGallery) return "gallery";
+  if (hasMedia) return "media";
+  if (hasProse || hasDocArray) return "document";
+  if (hasCode) return "code";
+  if (hasTimeline) return "timeline";
+  if (hasChart) return "chart";
+  if (hasSteps) return "progress";
+  if (hasStats) return "stat-grid";
+  if (structuredArrays > 0) return "list";
+  if (entries.length >= 2 && entries.length <= 12) return "card";
+  return null;
+}
+function inferLoadingSlugFromJsonSchema(jsonSchema) {
+  if (!jsonSchema || typeof jsonSchema !== "object" || Array.isArray(jsonSchema)) {
+    return null;
+  }
+  const root = jsonSchema;
+  const rootType = root.type;
+  if (rootType === "string") return "document";
+  if (rootType === "array") return "list";
+  const properties = root.properties;
+  if (!properties || typeof properties !== "object" || Array.isArray(properties)) {
+    return null;
+  }
+  const fields = {};
+  for (const [name, raw] of Object.entries(properties)) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) continue;
+    const prop = raw;
+    const type = prop.type;
+    if (type === "array") {
+      const items = prop.items;
+      const itemType = items && typeof items === "object" && !Array.isArray(items) ? items.type : void 0;
+      const structured = itemType === "object" || itemType === void 0 || // $ref'd child kind — structured by definition
+      items && typeof items === "object" && "$ref" in items;
+      fields[name] = { type: structured ? "array" : "string[]" };
+      continue;
+    }
+    if (type === "string") {
+      fields[name] = { type: "string" };
+      continue;
+    }
+    fields[name] = { type: typeof type === "string" ? type : "json" };
+  }
+  return inferLoadingSlug({ kind: "", fields });
+}
+export {
+  inferLoadingSlug,
+  inferLoadingSlugFromJsonSchema
+};