@ai-matrx/rich-content 0.0.0-stage → 0.2.2

package/dist/kinds/react/loading/kind-loading.types.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The kind loading-component contract — the EARLY-KEY interface between a
+ * streaming `__kind` payload and the hardcoded loading library.
+ *
+ * THE EARLY-KEY CONTRACT (teach emitters to send these FIRST):
+ * While a kind instance streams — and especially while its schema/component
+ * are still cold-fetching — the parser surfaces the region's top-level
+ * SCALAR values as they arrive. The loading layer reads this default key set
+ * from the envelope's early value:
+ *
+ *   - `title`            string — the instance's display title
+ *   - `description`      string — one-line summary of the content
+ *   - `loading_message`  string — what to show while the rest streams
+ *                        (e.g. "Pouring your wine tasting…")
+ *   - `loading_subtext`  string — secondary line under the message
+ *   - `icon`             string — icon hint (a slug from ICON_HINTS; unknown
+ *                        hints fall back to the component's default)
+ *   - `count`            number — expected item count (drives how many
+ *                        skeleton rows/cells render)
+ *
+ * A kind that wants a meaningful loading state should order these keys FIRST
+ * in its schema/sample so they stream in before the heavy fields. All keys
+ * are optional — every loader renders sensibly with none of them.
+ *
+ * WHICH LOADER RENDERS: `kind_definition.metadata.loading_component` names a
+ * slug from the library (see kind-loading-registry.ts). Missing/unknown slug
+ * → the `generic` skeleton. The library is hardcoded (zero fetch delay) and
+ * intentionally light — no heavy deps, semantic tokens, Lucide only.
+ */
+/**
+ * THE TWO PHASES of a loading silhouette (Arman, 2026-08-25).
+ *
+ * - `reserved` — the PLACEHOLDER. The slot exists and holds the footprint its
+ *   content will need, but nothing has happened yet: no spinner, no shimmer,
+ *   one slow breath on the icon. "It looks like a loading one, but it's
+ *   fairly steady… without looking like it's actively, instantly loading."
+ *   Modelled on `PodcastCompositionPlaceholder`, which proved the look.
+ * - `arriving` — the LOADING state. Same silhouette, now visibly working:
+ *   spinner, shimmering bars, live early keys filling in as they stream.
+ *
+ * Same component, same footprint, so the placeholder→loading transition moves
+ * nothing on screen. Defaults to `arriving`, which is what every pre-2026-08-25
+ * call site meant.
+ */
+export type KindLoadingPhase = "reserved" | "arriving";
+export interface KindLoadingProps {
+    /** The identified kind slug (shown as a subtle chip when no title yet). */
+    kind?: string;
+    /** Placeholder (footprint only) vs actively loading. Default `arriving`. */
+    phase?: KindLoadingPhase;
+    /**
+     * `full` (default) draws the loader's own frame and header — the right
+     * thing when it stands alone in a chat stream. `bare` draws ONLY the
+     * skeleton body, for a host that already renders the frame, icon, and
+     * title: a component never repeats chrome its host provides. Mirrors
+     * `LiveRunDisplay variant="bare"`.
+     */
+    chrome?: "full" | "bare";
+    title?: string;
+    description?: string;
+    loadingMessage?: string;
+    loadingSubtext?: string;
+    /** Icon hint slug (ICON_HINTS key); unknown → the loader's default. */
+    icon?: string;
+    /** Expected item count — clamped by each loader to a sane skeleton count. */
+    count?: number;
+    /**
+     * THE SMART-LOADER FEED: the region's full partial value, exactly as it
+     * stands this frame (grows monotonically, never rewrites). Library
+     * skeletons ignore it; a data-fed loader reads it to PERFORM the arrival —
+     * surface real text as it lands, step counts up, soft-fade each piece in
+     * (Arman, 2026-08-24: animated, intelligent, never generic). Always
+     * provided by the pending render path; optional so static previews can
+     * render a loader with no stream behind it.
+     */
+    value?: Record<string, unknown> | null;
+}
+/** Read the early-key set out of an envelope's (partial) root value. */
+export declare function earlyKeysFromValue(value: Record<string, unknown> | null | undefined, kind?: string): KindLoadingProps;

package/dist/kinds/react/loading/kind-loading.types.js

@@ -0,0 +1,31 @@
+function earlyKeysFromValue(value, kind) {
+  const v = value ?? {};
+  const str = (k) => typeof v[k] === "string" && v[k].length > 0 ? v[k] : void 0;
+  const num = (k) => typeof v[k] === "number" && Number.isFinite(v[k]) ? v[k] : void 0;
+  const props = {};
+  if (kind) props.kind = kind;
+  const title = str("title");
+  if (title) props.title = title;
+  const description = str("description");
+  if (description) props.description = description;
+  const loadingMessage = str("loading_message");
+  if (loadingMessage) props.loadingMessage = loadingMessage;
+  const loadingSubtext = str("loading_subtext");
+  if (loadingSubtext) props.loadingSubtext = loadingSubtext;
+  const icon = str("icon");
+  if (icon) props.icon = icon;
+  const count = num("count");
+  if (count !== void 0) {
+    props.count = count;
+  } else {
+    let largest = 0;
+    for (const item of Object.values(v)) {
+      if (Array.isArray(item) && item.length > largest) largest = item.length;
+    }
+    if (largest > 0) props.count = largest;
+  }
+  return props;
+}
+export {
+  earlyKeysFromValue
+};

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

@@ -0,0 +1,29 @@
+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 interface LoadingSlugResolution {
+    /** The library slug, or null when nothing beat the generic skeleton. */
+    slug: KindLoadingSlug | null;
+    origin: LoadingSlugOrigin;
+    /**
+     * The declared value when it was NOT a library slug — a data defect that
+     * resolution routed around. Present means "this kind declares a lie".
+     */
+    invalidDeclared?: string;
+}
+/** Test seam — resets the once-per-kind scream dedupe. */
+export declare function resetInvalidLoadingDeclarationReports(): void;
+/**
+ * Which loading silhouette does this kind get?
+ *
+ * 1. DECLARED — `metadata.loading_component` (read through the registry, not
+ *    off the definition: a Python-owned kind never produces a definition, so
+ *    its owner's choice lives only in the catalog side map) when it names a
+ *    real library slug.
+ * 2. DERIVED — from the kind's own parser schema, else from its emitted JSON
+ *    Schema (the only shape description most kinds carry). Costs nothing to
+ *    author and gives 857-of-868 undeclared kinds a shaped loader.
+ * 3. GENERIC — nothing distinctive enough; `null` lets the registry's own
+ *    default answer.
+ */
+export declare function resolveLoadingSlugForKind(kind: string | null | undefined): LoadingSlugResolution;

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

@@ -0,0 +1,51 @@
+"use client";
+import { captureError } from "../../../host/diagnostics.js";
+import { kindRegistry } from "../../../host/kind-registry.js";
+import {
+  inferLoadingSlug,
+  inferLoadingSlugFromJsonSchema
+} from "./infer-loading-slug.js";
+import { isKnownKindLoadingSlug } from "./kind-loading-slugs.js";
+const GENERIC = { slug: null, origin: "generic" };
+const reportedInvalidDeclarations = /* @__PURE__ */ new Set();
+function reportInvalidDeclaration(kind, declared) {
+  const seenKey = `${kind}\0${declared}`;
+  if (reportedInvalidDeclarations.has(seenKey)) return;
+  reportedInvalidDeclarations.add(seenKey);
+  const message = `[content-ir] kind "${kind}" declares loading_component "${declared}", which is not in the loading library (kind-loading-slugs.ts). Falling back to the DERIVED loader so the declaration cannot make the render worse \u2014 but the declaration is a defect: fix the row or add "${declared}" to the library.`;
+  console.error(message);
+  try {
+    captureError({
+      source: "content-ir",
+      message,
+      relation: kind,
+      callSite: "resolveLoadingSlugForKind",
+      hint: "kind_definition.metadata.loading_component must name a slug from KIND_LOADING_SLUGS.",
+      raw: { kind, declared }
+    });
+  } catch {
+  }
+}
+function resetInvalidLoadingDeclarationReports() {
+  reportedInvalidDeclarations.clear();
+}
+function resolveLoadingSlugForKind(kind) {
+  if (!kind) return GENERIC;
+  const raw = kindRegistry.getDeclaredLoadingComponent(kind)?.trim() ?? "";
+  if (raw && isKnownKindLoadingSlug(raw)) {
+    return { slug: raw, origin: "declared" };
+  }
+  const invalidDeclared = raw || void 0;
+  if (invalidDeclared !== void 0) {
+    reportInvalidDeclaration(kind, invalidDeclared);
+  }
+  const derived = inferLoadingSlug(kindRegistry.getDefinition(kind)?.schema) ?? inferLoadingSlugFromJsonSchema(kindRegistry.getEmittedJsonSchema(kind));
+  if (derived) {
+    return invalidDeclared === void 0 ? { slug: derived, origin: "derived" } : { slug: derived, origin: "derived", invalidDeclared };
+  }
+  return invalidDeclared === void 0 ? GENERIC : { slug: null, origin: "generic", invalidDeclared };
+}
+export {
+  resetInvalidLoadingDeclarationReports,
+  resolveLoadingSlugForKind
+};

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

@@ -0,0 +1,32 @@
+/**
+ * The Matrix binding of the PROVISIONAL (streaming partial kinds) route.
+ *
+ * Contract: `common-docs/systems/architecture/content-ir/FEATURE.md`.
+ * The reader/validator half is `@ai-matrx/content-ir` (`wire/partial-kind`);
+ * the ROUTE half — withhold-by-default, the per-kind opt-in, the
+ * anti-stuck-skeleton backstop, the terminal rules — is
+ * `@ai-matrx/content-ir-react` (`route/partial-kind-route.ts`), and since
+ * 0.8.0 the per-host partial application is `createKindRouteBinding`. Read
+ * the semantics there; this module only injects our registries.
+ *
+ * The wire gate runs in the execution system's `process-stream.ts`.
+ */
+export { IR_PROVISIONAL_KEY, envelopeFromPartialKind, isProvisionalBlock, markKindPartialUnsafe, resetPartialUnsafeKinds, resolveAnnouncedKindLoading, type ProvisionalKindRender, } from "@ai-matrx/content-ir-react";
+/** Has this kind opted in to being handed a provisional value? */
+export declare const isPartialReadyKind: (kind: string) => boolean;
+/**
+ * Resolve a block's provisional render, or null when there is nothing to show
+ * provisionally (no event, a terminal event, a withheld kind, a kind nothing
+ * can route, or a verified envelope that already won).
+ */
+export declare const resolveProvisionalKindRender: <T extends import("@ai-matrx/content-ir-react").IrRoutableBlock & {
+    metadata?: Record<string, unknown>;
+}>(block: T, options?: Pick<import("@ai-matrx/content-ir-react").PartialRenderOptions, "streamActive">) => import("@ai-matrx/content-ir-react").ProvisionalKindRender<T> | null;
+/**
+ * Route the completed JSON already present on a workflow block when its
+ * partial-kind channel closes before the canonical envelope is attached.
+ */
+export declare const resolveSupersededKindRender: <T extends import("@ai-matrx/content-ir-react").IrRoutableBlock & {
+    content: string;
+    metadata?: Record<string, unknown>;
+}>(block: T) => import("@ai-matrx/content-ir-react").SupersededKindRender<T> | null;

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

@@ -0,0 +1,27 @@
+import { createKindRouteBinding } from "@ai-matrx/content-ir-react";
+import { MATRX_OWNED_BLOCK_TYPES, matrxKindRouteEnv } from "../host/route-env.js";
+import {
+  IR_PROVISIONAL_KEY,
+  envelopeFromPartialKind,
+  isProvisionalBlock,
+  markKindPartialUnsafe,
+  resetPartialUnsafeKinds,
+  resolveAnnouncedKindLoading
+} from "@ai-matrx/content-ir-react";
+const binding = createKindRouteBinding(matrxKindRouteEnv, {
+  ownedTypes: MATRX_OWNED_BLOCK_TYPES
+});
+const isPartialReadyKind = binding.isPartialReadyKind;
+const resolveProvisionalKindRender = binding.resolveProvisionalKindRender;
+const resolveSupersededKindRender = binding.resolveSupersededKindRender;
+export {
+  IR_PROVISIONAL_KEY,
+  envelopeFromPartialKind,
+  isPartialReadyKind,
+  isProvisionalBlock,
+  markKindPartialUnsafe,
+  resetPartialUnsafeKinds,
+  resolveAnnouncedKindLoading,
+  resolveProvisionalKindRender,
+  resolveSupersededKindRender
+};

package/dist/kinds/react/registry-versioned.d.ts

@@ -0,0 +1,54 @@
+/**
+ * THE REGISTRY-VERSIONED READ — the primitive that survives the React Compiler.
+ *
+ * 🚨 THE DEFECT THIS CLOSES (DD-215c, observed on production 2026-09-14).
+ *
+ * Kind rendering reads MODULE SINGLETONS during render (`componentRegistry`,
+ * `kindRegistry`). Nothing in React state changes when a row lands, so every
+ * such reader pairs its read with `useContentIrKindVersion(kind)`, which
+ * subscribes to that kind's counter and returns it. The counter was then used
+ * as a memo INVALIDATION KEY in the only way a number can be used when the
+ * computation does not need it:
+ *
+ *     const block = useMemo(() => {
+ *       void kindRouteVersion;            // registry-arrival invalidation key
+ *       return applyIrKindRoute(rawBlock);
+ *     }, [rawBlock, kindRouteVersion]);
+ *
+ * That idiom is correct without the React Compiler and WRONG with it — and
+ * `next.config.js` sets `reactCompiler: true`. The compiler re-infers
+ * memoization from data flow: `void kindRouteVersion;` produces nothing, so the
+ * version is not an input, and the emitted cache is keyed on the block alone:
+ *
+ *     if ($[13] !== rawBlock) { t6 = applyIrKindRoute(rawBlock); $[13] = rawBlock; ... }
+ *
+ * The subscription still fires and the component still re-renders — the route
+ * simply comes back out of the cache, so a block that mounted before its
+ * organization's component row landed keeps the platform's bundled component
+ * for the life of the mount. Jest does not run the compiler, so every test of
+ * that code passes on source semantics production does not have. Three lanes
+ * shipped fixes proven that way and production disproved each one.
+ *
+ * THE RULE, therefore: a registry read that must follow a registry version
+ * takes that version AS AN ARGUMENT, through this module. The version is a real
+ * input to a real cache key here, so no compiler pass can decide it is dead —
+ * and if the compiler memoizes the call site too, it memoizes on the same two
+ * values and the answer is identical. Guard: `pnpm check:registry-repaint`.
+ */
+interface VersionedEntry<T> {
+    version: number;
+    value: T;
+}
+/**
+ * Read `compute()` for an OBJECT subject, re-running it whenever the registry
+ * version moves. One entry per subject; the WeakMap lets the subject (a block,
+ * a node) be collected with its answer.
+ */
+export declare function readAtVersionFor<K extends object, T>(cache: WeakMap<K, VersionedEntry<T>>, subject: K, version: number, compute: () => T): T;
+/**
+ * Read `compute()` for a STRING subject (a kind slug), re-running it whenever
+ * the registry version moves. One entry per key — the map is bounded by the
+ * number of distinct kinds a tab renders, never by version churn.
+ */
+export declare function readAtVersionForKey<T>(cache: Map<string, VersionedEntry<T>>, key: string, version: number, compute: () => T): T;
+export {};

package/dist/kinds/react/registry-versioned.js

@@ -0,0 +1,18 @@
+function readAtVersionFor(cache, subject, version, compute) {
+  const hit = cache.get(subject);
+  if (hit !== void 0 && hit.version === version) return hit.value;
+  const value = compute();
+  cache.set(subject, { version, value });
+  return value;
+}
+function readAtVersionForKey(cache, key, version, compute) {
+  const hit = cache.get(key);
+  if (hit !== void 0 && hit.version === version) return hit.value;
+  const value = compute();
+  cache.set(key, { version, value });
+  return value;
+}
+export {
+  readAtVersionFor,
+  readAtVersionForKey
+};

package/dist/kinds/react/route-at-version.d.ts

@@ -0,0 +1,38 @@
+/**
+ * THE ROUTE, KEYED ON THE REGISTRY STATE THAT PRODUCED IT (DD-215c).
+ *
+ * A block's route is not a function of the block alone — it is a function of
+ * the block AND of what the component resolver held when the decision was
+ * made. Writing it as `f(block)` and hanging the registry version off a memo
+ * dependency array is what froze `/shapes/<kind>/instances` on the platform's
+ * bundled component for a reader whose organization had authored its own: the
+ * React Compiler re-infers memo inputs from data flow, the version was only
+ * ever `void`-ed, and the emitted cache was keyed on the block alone. The whole
+ * story, and the rule, are in `registry-versioned.ts`.
+ *
+ * So the version is an ARGUMENT here. Call it with
+ * `useContentIrKindVersion(envelopeKind)` and the route follows every arrival;
+ * there is no way to call it and silently lose the invalidation.
+ */
+import { type IrRoutableBlock } from "./kind-route.js";
+/**
+ * Route one block at a known registry version — the seam every render path
+ * calls instead of `applyIrKindRoute` directly.
+ *
+ * `resolveSupersededKindRender` runs first for the same reason it always has:
+ * a block whose partial channel was superseded routes off the completed value,
+ * not off the partial envelope.
+ */
+/**
+ * The route itself, uncached — what `routeBlockAtRegistryVersion` computes and
+ * memoises. For pure callers that ask the renderer's question without a
+ * registry version (the frame judge, `draws-raw-kind-json.ts`).
+ */
+export declare function routeBlockNow<T extends IrRoutableBlock & {
+    content: string;
+}>(block: T): T;
+export declare function routeBlockAtRegistryVersion<T extends IrRoutableBlock & {
+    content: string;
+}>(block: T, registryVersion: number): T;
+/** Test seam — drops the per-session dedupe. */
+export declare function resetStaleRouteReports(): void;

package/dist/kinds/react/route-at-version.js

@@ -0,0 +1,78 @@
+"use client";
+import {
+  applyIrKindRoute,
+  DB_KIND_COMPONENT_KEY,
+  readIrRouteMarker
+} from "./kind-route.js";
+import { resolveSupersededKindRender } from "./partial-kind-route.js";
+import { readAtVersionFor } from "./registry-versioned.js";
+import { readEnvelope } from "../redux/render-block-envelope.js";
+import { componentRegistry } from "../../host/component-registry.js";
+import {
+  MATRX_CONTENT_IR_PLATFORM,
+  MATRX_OWNED_BLOCK_TYPES
+} from "../host/route-env.js";
+const routed = /* @__PURE__ */ new WeakMap();
+function routeBlockNow(block) {
+  return resolveSupersededKindRender(block)?.block ?? applyIrKindRoute(block);
+}
+function routeBlockAtRegistryVersion(block, registryVersion) {
+  const answer = readAtVersionFor(
+    routed,
+    block,
+    registryVersion,
+    () => routeBlockNow(block)
+  );
+  announceStaleRoute(answer);
+  return answer;
+}
+const announced = /* @__PURE__ */ new Set();
+function resetStaleRouteReports() {
+  announced.clear();
+}
+function announceStaleRoute(block) {
+  const marker = readIrRouteMarker(block.metadata);
+  if (marker && (marker.by === "generic" || marker.by === "directive")) return;
+  const envelope = readEnvelope(block.metadata);
+  const kind = envelope?.root.kind;
+  if (!kind) return;
+  const resolution = componentRegistry.resolve(
+    kind,
+    MATRX_CONTENT_IR_PLATFORM,
+    "output"
+  );
+  if (!resolution) return;
+  if (marker && marker.by === resolution.resolvedBy && marker.key === resolution.componentKey) {
+    return;
+  }
+  if (!marker) {
+    const routable = resolution.resolvedBy === "db" && resolution.source === "db" && resolution.isActive && resolution.hasComponentSource;
+    const exempt = MATRX_OWNED_BLOCK_TYPES.includes(block.type) || envelope?.root.kindState === "raw" || envelope?.root.kindState === "pending_schema";
+    if (!routable || exempt || block.type === DB_KIND_COMPONENT_KEY) return;
+  }
+  const renderedBy = marker?.by ?? "no route marker";
+  const renderedKey = marker?.key ?? block.type;
+  const seen = `${kind}|${renderedBy}:${renderedKey}|${resolution.resolvedBy}:${resolution.componentKey}`;
+  if (announced.has(seen)) return;
+  announced.add(seen);
+  void (async () => {
+    try {
+      const { reportKindComponentIncident } = await import("../../host/kind-incident.js");
+      reportKindComponentIncident({
+        kind,
+        errorType: "stale_route_render",
+        platform: MATRX_CONTENT_IR_PLATFORM,
+        role: "output",
+        componentKey: resolution.componentKey,
+        componentUpdatedAt: resolution.updatedAt,
+        message: `The reader is being shown "${renderedKey}" (resolved by ${renderedBy}) for kind "${kind}", but this browser's resolver already answers "${resolution.componentKey}" (resolved by ${resolution.resolvedBy}${resolution.hasComponentSource ? ", body present" : ", no body"}). The rendered block is a STALE route decision: the component row arrived after the block mounted and the route was not recomputed. Nothing on screen says so \u2014 the wrong component looks like the right one. Rendered at ${block.type}.`
+      });
+    } catch {
+    }
+  })();
+}
+export {
+  resetStaleRouteReports,
+  routeBlockAtRegistryVersion,
+  routeBlockNow
+};

package/dist/kinds/react/slot/KindSlot.d.ts

@@ -0,0 +1,87 @@
+/**
+ * THE KIND SLOT — one reserved place on a surface, from first paint to final
+ * content, without ever moving anything above it.
+ *
+ * Ratified by Arman 2026-08-25, from the podcast run page: a slot "takes up
+ * the space… it's sort of animated, but it's fairly steady, and it tries to
+ * look a little bit like it's gonna look eventually, but without looking like
+ * it's actively, instantly loading. And then when the content actually starts
+ * coming, boom — that's when it switches to the loading component."
+ *
+ * ─── The four phases ────────────────────────────────────────────────────────
+ *   reserved  the kind's silhouette, STILL — holds the footprint, nothing has
+ *             started. (`PodcastCompositionPlaceholder` is the reference look.)
+ *   arriving  the same silhouette, now working — spinner, shimmer, live early
+ *             keys. The switch moves nothing: same component, same footprint.
+ *   settled   the real kind component, growing downward from its first
+ *             renderable unit (THE ONE LOADING SEQUENCE).
+ *   failed    an honest failure, inside the same reserved footprint.
+ *
+ * ─── Why the placeholder is a PHASE, not a third component ──────────────────
+ * A separately-authored loader would mean a second artifact per kind to keep
+ * in sync with the schema (868 of them), and — worse — swapping between two
+ * components unmounts and remounts, so the layout jumps and animations
+ * restart at exactly the moment we are trying to keep calm. One silhouette in
+ * two moods keeps the transition continuous, and every kind gets a
+ * shape-appropriate placeholder for free via the declared-or-derived slug
+ * (`resolveLoadingSlugForKind`) — including the 857 that declare nothing.
+ *
+ * ─── Who owns the footprint ─────────────────────────────────────────────────
+ * The slot owns the SHAPE; the HOST owns the floor. A surface that knows how
+ * much room a region deserves already applies it to its own box — see
+ * `ReadoutTile`'s authored `minHeight` in `RunSurfaceView.tsx` ("the zero
+ * page-shift law") — and a second floor inside the slot would fight it, or
+ * silently lose to an `overflow-y-auto` ancestor. So there is deliberately no
+ * `minHeight` prop here: the silhouette's own height does the reserving, and
+ * content longer than it grows DOWNWARD, the one direction that disturbs
+ * nothing the reader is already looking at.
+ *
+ * ─── Identity ───────────────────────────────────────────────────────────────
+ * `slotKey` is the slot's OWN identity and must be stable from first paint —
+ * it exists before any producer does, which is exactly why it cannot be a
+ * request id (there is no request yet when the slot is reserved). A producer
+ * id (a streaming lane's requestId, a workflow `invocationKeyOf(...)`) is a
+ * BINDING the caller resolves later and feeds in as `phase` + `children`.
+ */
+import React from "react";
+import type { KindLoadingProps } from "../loading/kind-loading.types.js";
+export type KindSlotPhase = "reserved" | "arriving" | "settled" | "failed";
+export interface KindSlotProps {
+    /**
+     * Stable identity for this slot, known at first paint and never changing.
+     * Surfaces derive it from their own structure (a workflow invocation key, a
+     * podcast asset index, an authored slot id) — never from a producer id.
+     */
+    slotKey: string;
+    /** The kind expected here, when known. Drives which silhouette reserves. */
+    kind?: string | null;
+    phase: KindSlotPhase;
+    /**
+     * Early keys for the arriving phase (title / count / loading_message …) and
+     * the partial value a data-fed smart loader performs. Ignored when settled.
+     */
+    early?: KindLoadingProps;
+    /** The settled content — the real kind component. */
+    children?: React.ReactNode;
+    /** Rendered in the `failed` phase. */
+    error?: React.ReactNode;
+    /**
+     * `bare` when the host already draws the frame/icon/title around this slot
+     * (a workflow deliverable card does) — the silhouette then contributes only
+     * its body, never a second header.
+     */
+    chrome?: "full" | "bare";
+    className?: string;
+}
+export declare function KindSlot({ slotKey, kind, phase, early, children, error, chrome, className, }: KindSlotProps): React.JSX.Element;
+/**
+ * The phase a slot is in, from the two facts every producer surface has: has
+ * anything started, and has it finished. Kept here so a surface never invents
+ * its own phase vocabulary — the workflow run board, a podcast slot, and an
+ * authored page all map into the SAME four phases.
+ */
+export declare function kindSlotPhase(input: {
+    started: boolean;
+    settled: boolean;
+    failed?: boolean;
+}): KindSlotPhase;

package/dist/kinds/react/slot/KindSlot.js

@@ -0,0 +1,65 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import React from "react";
+import { resolveKindLoadingComponent } from "../loading/kind-loading-registry.js";
+import { resolveLoadingSlugForKind } from "../loading/resolve-loading-slug.js";
+import { useContentIrKindVersion } from "../use-registry-repaint.js";
+import { readAtVersionForKey } from "../registry-versioned.js";
+import { useEnsureKindRenderable } from "../ensure-kind-renderable.js";
+const loadingSlugCache = /* @__PURE__ */ new Map();
+function KindSlot({
+  slotKey,
+  kind,
+  phase,
+  early,
+  children,
+  error,
+  chrome,
+  className
+}) {
+  useEnsureKindRenderable(kind ?? null);
+  const kindVersion = useContentIrKindVersion(kind ?? null);
+  const slug = readAtVersionForKey(
+    loadingSlugCache,
+    kind ?? "",
+    kindVersion,
+    () => resolveLoadingSlugForKind(kind).slug
+  );
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      "data-kind-slot": slotKey,
+      "data-kind-slot-phase": phase,
+      "data-kind-slot-kind": kind ?? void 0,
+      className,
+      children: phase === "settled" ? children : phase === "failed" ? error : /* @__PURE__ */ jsx(
+        PendingSilhouette,
+        {
+          slug,
+          kind,
+          phase,
+          early,
+          chrome
+        }
+      )
+    }
+  );
+}
+const PendingSilhouette = ({ slug, kind, phase, early, chrome }) => {
+  const Loader = resolveKindLoadingComponent(slug);
+  return React.createElement(Loader, {
+    ...early,
+    kind: kind ?? early?.kind,
+    phase,
+    chrome
+  });
+};
+function kindSlotPhase(input) {
+  if (input.failed) return "failed";
+  if (input.settled) return "settled";
+  return input.started ? "arriving" : "reserved";
+}
+export {
+  KindSlot,
+  kindSlotPhase
+};

package/dist/kinds/react/use-registry-repaint.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Subscribes the caller to registry changes FOR ONE KIND and returns that
+ * kind's combined version. Pass null for blocks with no envelope kind —
+ * they never repaint from registries (nothing to learn about them).
+ */
+export declare function useContentIrKindVersion(kind: string | null): number;

package/dist/kinds/react/use-registry-repaint.js

@@ -0,0 +1,36 @@
+"use client";
+import { useCallback, useSyncExternalStore } from "react";
+import { kindRegistry } from "../../host/kind-registry.js";
+import { componentRegistry } from "../../host/component-registry.js";
+const noopSubscribe = () => () => {
+};
+const zero = () => 0;
+function useContentIrKindVersion(kind) {
+  const subscribe = useCallback(
+    (onStoreChange) => {
+      if (!kind) return noopSubscribe();
+      const unsubKinds = kindRegistry.subscribeKind(kind, onStoreChange);
+      const unsubComponents = componentRegistry.subscribeKind(
+        kind,
+        onStoreChange
+      );
+      return () => {
+        unsubKinds();
+        unsubComponents();
+      };
+    },
+    [kind]
+  );
+  const getSnapshot = useCallback(
+    () => kind ? (
+      // Both counters are monotonic, so the sum is monotonic — a change
+      // in either registry produces a new snapshot value for this kind.
+      kindRegistry.getKindVersion(kind) + componentRegistry.getKindVersion(kind)
+    ) : 0,
+    [kind]
+  );
+  return useSyncExternalStore(subscribe, getSnapshot, zero);
+}
+export {
+  useContentIrKindVersion
+};

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

@@ -0,0 +1,9 @@
+import { type IrPath } from "@ai-matrx/content-ir";
+import type { IrTreeNode } from "@ai-matrx/content-ir";
+export declare function useIrNode(identity: string | null, path: IrPath | string): IrTreeNode | null;
+/**
+ * Structural subscription: the list of node pathKeys for a session, updated
+ * when nodes are added/removed/changed. Containers use this to know which
+ * children to mount without subscribing to every child's data.
+ */
+export declare function useIrNodePaths(identity: string | null): string[];