@ai-matrx/content-ir-react 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,782 @@
+import * as react from 'react';
+import react__default, { ReactNode } from 'react';
+import { KindDefinition, CanonicalBlockIR, PartialKindEvent } from '@ai-matrx/content-ir';
+
+/**
+ * THE SCREAM SEAM.
+ *
+ * Every recovery path in this package is loud: a defective component row, a
+ * failed resolver load, a kind whose component throws on a provisional value.
+ * The package refuses to own where those screams land — matrx-frontend routes
+ * them to the Error Inspector, the dashboard to its own log, the extension to
+ * its background page. Each host binds one function.
+ *
+ * A host that binds a no-op has chosen silence, which is a defect in itself;
+ * {@link consoleErrorReporter} is the honest default.
+ */
+interface ContentIrErrorReport {
+    /** Always `"content-ir"` — hosts key their capture stores on it. */
+    source: "content-ir";
+    message: string;
+    name?: string;
+    stack?: string;
+    /** Free-form grouping key (the host's `relation`), e.g. `"partial-kind"`. */
+    relation?: string;
+    raw?: unknown;
+}
+type ContentIrErrorReporter = (report: ContentIrErrorReport) => void;
+/** The default when a host binds nothing: never silent. */
+declare const consoleErrorReporter: ContentIrErrorReporter;
+
+/**
+ * The (kind, platform, role) → component vocabulary — the Shape System's
+ * resolver contract (rulings R1 + R6), stated once for every UI.
+ *
+ * Cross-repo system-of-record:
+ * `common-docs/systems/content-ir-twin/FEATURE.md` (package boundary) and
+ * `matrx-frontend/features/content-ir/docs/SHAPE_SYSTEM.md` (the semantics).
+ *
+ * Nothing here knows where a row comes from. A host supplies rows from
+ * `content_ir.kind_component` (Supabase, a REST call, a fixture); the resolver
+ * only knows the shape.
+ */
+/** 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";
+/**
+ * One `content_ir.kind_component` row, projected to exactly what rendering
+ * needs. Hosts map their own query result onto this.
+ */
+interface KindComponentRow {
+    kind: string;
+    platform: string;
+    role: ComponentRole;
+    componentKey: string;
+    /** `source` column vocabulary: "bundled" | "db" (db = web sandbox only). */
+    source: string;
+    config: JsonObject;
+    isActive: boolean;
+    componentSource: string | null;
+    propsTransform: string | null;
+    pinnedKindVersion: number | null;
+    updatedAt: string | null;
+    createdBy: string | null;
+}
+/**
+ * One COMPILED bootstrap entry — the trusted-at-boot floor a host ships in its
+ * bundle, available synchronously from the first streamed byte.
+ */
+interface SystemComponentEntry {
+    kind: string;
+    platform: string;
+    role: ComponentRole;
+    componentKey: string;
+    source: string;
+    config: JsonObject;
+}
+/** The resolver's answer for one (kind, platform, role). */
+interface ComponentResolution {
+    /** The component key the renderer routes on (e.g. "flashcards"). */
+    componentKey: string;
+    source: string;
+    config: JsonObject;
+    /**
+     * Render-trust verdict (R6). Compiled entries are always active (trusted at
+     * bootstrap); DB rows carry their own `is_active`.
+     */
+    isActive: boolean;
+    /** Which tier produced this answer — the verification hook's `by`. */
+    resolvedBy: "compiled" | "db";
+    componentSource: string | null;
+    propsTransform: string | null;
+    pinnedKindVersion: number | null;
+    /** The db row's `updated_at` — the compile-cache staleness key. */
+    updatedAt: string | null;
+    createdBy: string | null;
+}
+/**
+ * The read side of a component resolver, as the render layer consumes it.
+ * The package ships {@link ComponentResolver}; a host with its own resolver
+ * only has to satisfy this.
+ */
+interface ComponentResolutionSource {
+    /** Synchronous — the render seam's per-block call. */
+    resolve(kind: string, platform: string, role: ComponentRole): ComponentResolution | null;
+    /** Eager targeted fetch for one kind; fire-and-forget, never awaited on the hot path. */
+    requestComponent(kind: string, platform: string, role: ComponentRole): void;
+    /** One list fetch per session. */
+    ensureWarm(): Promise<void>;
+    /** Refresh-on-view; rate-limited and deduped by the implementation. */
+    refresh(maxAgeMs?: number): Promise<void>;
+    /** Monotonic tier version — has anything at all changed? */
+    getVersion(): number;
+    /** Monotonic per-kind version (+ wholesale epoch) — the granular repaint key. */
+    getKindVersion(kind: string): number;
+    subscribe(listener: () => void): () => void;
+    subscribeKind(kind: string, listener: () => void): () => void;
+}
+
+/**
+ * THE HOST CONTRACT — everything this package refuses to decide.
+ *
+ * The kernel (`@ai-matrx/content-ir`) proved the shape: extract the portable
+ * part, let host capability enter through explicit named seams. The render
+ * layer needs four things it must never own:
+ *
+ *  1. WHERE KIND DEFINITIONS COME FROM (a bundled table, `content_ir`, a REST
+ *     call). The route only asks "is this kind registered, and does it carry a
+ *     legacy bridge / a partial-ready opt-in".
+ *  2. WHERE COMPONENT ROWS COME FROM — {@link ComponentResolutionSource}. The
+ *     package ships `ComponentResolver`, which any host can construct with its
+ *     own loaders; a host with its own resolver only has to satisfy the type.
+ *  3. HOW A ROUTED BLOCK ACTUALLY DRAWS. `applyIrKindRoute` decides a block's
+ *     TYPE; turning that type into pixels is the host's dispatch table
+ *     (matrx-frontend's `BlockRenderer`, the dashboard's small map). The
+ *     package never imports a component library.
+ *  4. WHERE SCREAMS LAND — {@link ContentIrErrorReporter}.
+ *
+ * No Next.js, no Redux, no Supabase, no router, no host error capture. If a
+ * seam is missing, ADD A SEAM — never an import.
+ */
+
+/**
+ * The minimum a render block must expose for the kind route to work. Hosts
+ * pass their own richer block type through; the route is generic over `T` and
+ * preserves every extra field.
+ */
+interface IrRoutableBlock {
+    type: string;
+    serverData?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}
+/** A routable block that also carries its source text (the raw region). */
+interface IrRenderBlock extends IrRoutableBlock {
+    content: string;
+    language?: string;
+}
+/**
+ * Where registered kinds come from. `getDefinition` is the only method the
+ * pure route needs; the rest drive the granular repaint and the warm-up tick
+ * that keeps a cold registry from being mistaken for "this kind has no
+ * component".
+ */
+interface KindDefinitionSource {
+    getDefinition(kind: string): KindDefinition | undefined;
+    /** Monotonic per-kind version — the repaint snapshot key. */
+    getKindVersion(kind: string): number;
+    subscribeKind(kind: string, listener: () => void): () => void;
+    /** One definition load per app session. */
+    ensureWarm(): Promise<void>;
+}
+/**
+ * The rendering seams. Everything here returns host UI; the package supplies
+ * the DECISIONS and the chrome-free structure around them.
+ */
+interface ContentIrRenderSeams {
+    /**
+     * Draw a block the kind route has already typed. This is the host's dispatch
+     * table — the single place a component key becomes a component.
+     */
+    renderBlock(block: IrRenderBlock): ReactNode;
+    /**
+     * THE FLOOR: render ANY JSON value as a human document. Reached when a kind
+     * has no render-trusted component, when the value is not an object at all,
+     * and by the generic structured view.
+     *
+     * This is deliberately a seam and not a bundled component. Rendering a value
+     * WELL means prose through the host's markdown renderer, media through the
+     * host's file handler, and uniform arrays through the host's data table —
+     * all of which are host property. A host that has none of those can pass a
+     * `<pre>`; it will be honest, just plain.
+     */
+    renderValue(props: StructuredValueRenderProps): ReactNode;
+    /**
+     * The "still arriving" indicator used by the provisional frame. Optional —
+     * hosts without a shimmer get plain text.
+     */
+    renderShimmer?(text: string): ReactNode;
+    /**
+     * The honest "this shape has no custom component yet" notice. Optional: the
+     * package draws a plain amber line when a host supplies nothing, and a host
+     * with an icon set or its own callout component supplies that instead. It is
+     * a seam and not a bundled component because this package depends on no icon
+     * library.
+     */
+    renderNotice?(text: string): ReactNode;
+}
+interface StructuredValueRenderProps {
+    value: unknown;
+    /** The kind slug this value claims, when known. Honesty line only — never a renderer choice. */
+    kind?: string;
+    /** Why this shape has no custom view, in human words. */
+    note?: string;
+    /** Show the "what this is / raw data" footer. Default true. */
+    footer?: boolean;
+}
+/**
+ * One host, wired once, read by every component in this package through
+ * {@link ContentIrRenderProvider}.
+ */
+interface ContentIrHost extends ContentIrRenderSeams {
+    kinds: KindDefinitionSource;
+    components: ComponentResolutionSource;
+    reportError: ContentIrErrorReporter;
+    /**
+     * The `kind_component.platform` this host resolves as. "web" for every
+     * browser UI; the column already models "react-native" and friends, and a
+     * host that lies here renders the wrong component everywhere.
+     */
+    platform: string;
+}
+/**
+ * The pure route's dependencies — a strict subset of {@link ContentIrHost},
+ * because `applyIrKindRoute` is called OUTSIDE React (reducers, stream
+ * accumulators, tests) where there is no provider to read.
+ */
+interface KindRouteEnv {
+    kinds: Pick<KindDefinitionSource, "getDefinition">;
+    components: Pick<ComponentResolutionSource, "resolve">;
+    reportError: ContentIrErrorReporter;
+    platform: string;
+}
+/** Narrow a host (or anything host-shaped) to what the pure route needs. */
+declare function routeEnvOf(host: ContentIrHost): KindRouteEnv;
+
+interface ContentIrRenderProviderProps {
+    host: ContentIrHost;
+    children: ReactNode;
+}
+declare function ContentIrRenderProvider({ host, children, }: ContentIrRenderProviderProps): react.JSX.Element;
+/**
+ * The wired host, or null. For the rare consumer that can legitimately run
+ * without a provider because it was handed its sources explicitly (see
+ * `useContentIrKindVersion`). Everything else uses {@link useContentIrHost}.
+ */
+declare function useContentIrHostOrNull(): ContentIrHost | null;
+/** The wired host. Throws outside a provider — see the module doc. */
+declare function useContentIrHost(): ContentIrHost;
+/** The wired host narrowed to what the pure route functions take. */
+declare function useKindRouteEnv(): KindRouteEnv;
+
+/**
+ * The Shape System component RESOLVER (rulings R1 + R6): (kind, platform,
+ * role) → component, with two tiers:
+ *
+ * - eager: a COMPILED bootstrap the host ships in its bundle — the
+ *   trusted-at-boot floor, available at import so the render seam can gate
+ *   synchronously from the first streamed byte.
+ * - warm:  one `content_ir.kind_component` list fetch per app session
+ *   (`ensureWarm`). A DB row for a (kind, platform, role) OVERRIDES the
+ *   compiled entry once warm; the compiled floor keeps answering until then
+ *   (and forever, on DB failure).
+ *
+ * Resolution is SYNCHRONOUS (the render seam calls it per block); the only
+ * async work is the loading, off the render path.
+ *
+ * WHAT MOVED AND WHY. This class was matrx-frontend's `ComponentRegistry`. It
+ * is a large part of why a second UI could not render a kind: every tier rule,
+ * every repaint counter, every dedupe latch lived in one app. Nothing about it
+ * is Next.js, Redux, or Supabase — the only host-specific parts were the two
+ * loaders and the error sink, which are now constructor arguments.
+ */
+
+interface ComponentResolverOptions {
+    /**
+     * The compiled bootstrap, as a THUNK resolved on first use: a host's system
+     * component table is often mid-initialization when this module evaluates
+     * (matrx-frontend's registry cluster has a deliberate import cycle).
+     */
+    compiledEntries?: () => SystemComponentEntry[];
+    /** The warm/refresh list load — every `kind_component` row the user may see. */
+    loadAll?: () => Promise<KindComponentRow[]>;
+    /** The eager single-kind load fired the moment a kind is identified mid-stream. */
+    loadForKind?: (kind: string, platform: string) => Promise<KindComponentRow[]>;
+    /** Where recovery screams land. Defaults to `console.error`, never silence. */
+    reportError?: ContentIrErrorReporter;
+    /** Clock seam — the refresh rate limiter. Defaults to `Date.now`. */
+    now?: () => number;
+}
+declare class ComponentResolver implements ComponentResolutionSource {
+    private compiled;
+    private readonly db;
+    private warmPromise;
+    private warmFailureLogged;
+    /**
+     * When the last successful wholesale refresh landed, or null for "never".
+     * Explicitly nullable rather than 0: with a host-supplied clock that starts
+     * near zero, a `0` sentinel makes the FIRST refresh look rate-limited and
+     * silently skip.
+     */
+    private lastRefreshAt;
+    private refreshPromise;
+    private readonly listeners;
+    /**
+     * Cold single-kind fetch dedupe (streaming eager path). In-flight is keyed
+     * by (kind, platform) — the fetch unit; misses are keyed by (kind, platform,
+     * role) so a miss on web/output never suppresses other roles, and CLEARED on
+     * every wholesale refresh (a component created mid-session becomes eagerly
+     * fetchable again — misses are cheap to re-verify).
+     */
+    private readonly coldInFlight;
+    private readonly coldMisses;
+    /** Monotonic db-tier version — the repaint hook's snapshot key. */
+    private version;
+    /** Per-kind versions + listeners (granular repaint) + wholesale epoch. */
+    private readonly kindVersions;
+    private readonly kindListeners;
+    private epoch;
+    private readonly reportError;
+    private readonly now;
+    private readonly options;
+    constructor(options?: ComponentResolverOptions);
+    private compiledMap;
+    /**
+     * Synchronous resolve — the render seam's per-block call. DB override first
+     * (once warm), compiled floor second, null for unknown.
+     */
+    resolve(kind: string, platform: string, role: ComponentRole): ComponentResolution | null;
+    /** R6 floor check: compiled-bootstrap membership = always render-trusted. */
+    hasCompiled(kind: string, platform: string, role: ComponentRole): boolean;
+    /**
+     * Pure ingest — the warm landing point and the unit-test seam. First row per
+     * key wins: rows arrive is_default-first / sort_order-asc from the source.
+     */
+    ingestDbRows(rows: readonly KindComponentRow[]): void;
+    /**
+     * Refresh landing point: REPLACE the db tier wholesale (same
+     * first-row-per-key contract as {@link ingestDbRows}) so edits, deletions,
+     * and is_active flips all take effect. Always notifies.
+     */
+    replaceDbRows(rows: readonly KindComponentRow[]): void;
+    getVersion(): number;
+    getKindVersion(kind: string): number;
+    subscribeKind(kind: string, listener: () => void): () => void;
+    subscribe(listener: () => void): () => void;
+    private bumpKind;
+    private notifyChanged;
+    /**
+     * The eager lightweight single-kind fetch (streaming path): the moment a
+     * cloud kind is identified mid-stream, pull ONLY that kind's resolver rows
+     * and ingest them so {@link resolve} can answer before — or shortly after —
+     * the region completes. Deduped in-flight and by known-miss. Fire-and-forget;
+     * failures are loud (the warm list remains the backstop).
+     */
+    requestComponent(kind: string, platform: string, role: ComponentRole): void;
+    /**
+     * Refresh-on-view: re-fetch the warm list and REPLACE the db tier, so an
+     * edited `source='db'` component (its `updated_at` bump re-keys the host's
+     * compile cache) renders fresh on the next view. Deduped in-flight and
+     * rate-limited by `maxAgeMs` (default 10s) — mounting several previews costs
+     * one fetch. Server-side edits do NOT push to open clients; the contract is
+     * refresh-on-view via this call.
+     */
+    refresh(maxAgeMs?: number): Promise<void>;
+    /** One list fetch per app session; failed loads retry on the next call. */
+    ensureWarm(): Promise<void>;
+}
+
+/**
+ * THE KIND ROUTE — the render flip, as a pure block transform.
+ *
+ * A block whose `metadata.__ir` envelope resolved a REGISTERED kind is routed
+ * to that kind's component: via the legacy-bridge facet (`legacyBlockType` +
+ * `toLegacyServerData`) when the kind has one, so the block enters the host's
+ * existing renderer as its real type with envelope-derived serverData;
+ * otherwise via the component resolver. Blocks with no envelope, an
+ * unregistered kind, or no bridge facet pass through UNTOUCHED — the strangler
+ * seam.
+ *
+ * This is where a bare/fenced JSON flashcard_set — which a text detector could
+ * only ever call "code" — becomes real flashcards, live while streaming.
+ *
+ * PORTABILITY. This function was matrx-frontend's `react/kind-route.ts` and is
+ * the single most-copied thing in the system: every UI that renders a kind has
+ * to make exactly these decisions in exactly this order, and a second
+ * implementation of them is a guaranteed divergence. It takes its registries,
+ * its platform, and its error sink as an {@link KindRouteEnv} argument rather
+ * than importing them, so it is callable from a reducer, a stream accumulator,
+ * a test, or a React render — in any app.
+ *
+ * Semantics: `matrx-frontend/features/content-ir/docs/SHAPE_SYSTEM.md`
+ * (registry, dual gate, `kind_component` resolution, rulings R1 + R6).
+ */
+
+/**
+ * Runtime routing marker (the Shape System's verification hook): stamped on
+ * `metadata.__ir_route` whenever a block routes AND the component resolver
+ * produced the decision. `by` says which resolver tier answered ("compiled"
+ * floor vs a warm `content_ir.kind_component` row) — the live proof of
+ * registry-resolution vs hard-coded fallback. Metadata-only, non-breaking.
+ */
+declare const IR_ROUTE_KEY: "__ir_route";
+/**
+ * The component key the R6 generic fallback routes to — the official renderer
+ * for a KNOWN shape that nothing render-trusted claims. Hosts map this key to
+ * their generic structured view (the package ships one: `GenericStructuredView`).
+ */
+declare const GENERIC_STRUCTURED_COMPONENT_KEY: "generic_structured";
+/**
+ * The block type a DB-sourced (user-authored) kind component renders as.
+ * FE-synthesized: produced ONLY here, never emitted upstream. A host that has
+ * no sandbox for user components simply does not map this key — the block then
+ * falls to that host's unknown-type handling, which is honest.
+ */
+declare const DB_KIND_COMPONENT_KEY: "db_kind_component";
+/** Test-only reset of the once-per-kind console latch. */
+declare function resetSourcelessDbRowReports(): void;
+/** Why a block landed on the generic viewer instead of a real renderer. */
+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";
+interface IrRouteMarker {
+    by: ComponentResolution["resolvedBy"] | "generic";
+    key: string;
+    /**
+     * Only on the generic fallback: the shape is NOT render-trusted, so the
+     * viewer must say so out loud (R6 — never an error, never hidden content).
+     */
+    unverified?: true;
+    reason?: GenericFallbackReason;
+}
+/** Read the routing marker a block picked up at the seam (or null). */
+declare function readIrRouteMarker(metadata: Record<string, unknown> | null | undefined): IrRouteMarker | null;
+interface KindRouteOptions {
+    /**
+     * Block types this host OWNS and the route must never re-type, however good
+     * the envelope on them looks.
+     *
+     * matrx-frontend passes `["artifact"]`: 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. That envelope is DATA
+     * there, not a route — re-typing it to the bare kind component would strip
+     * the artifact chrome and lose the door to the Canvas.
+     */
+    ownedTypes?: readonly string[];
+}
+declare function applyIrKindRoute<T extends IrRoutableBlock>(block: T, env: KindRouteEnv, options?: KindRouteOptions): T;
+/**
+ * Rehydration route for STRUCTURED persisted artifacts.
+ *
+ * A materialized kind artifact stores its zero-loss value object (carrying
+ * `__kind`) alongside its row. Given that stored value, derive the registered
+ * kind's legacy `serverData` WITHOUT re-parsing any text: the value wraps into
+ * a complete envelope and runs through the same `toLegacyServerData` bridge the
+ * live stream uses. Returns null for non-objects, unregistered kinds, or kinds
+ * without a legacy bridge — callers fall back to their string-payload path.
+ */
+declare function kindServerDataFromStoredValue(value: unknown, env: Pick<KindRouteEnv, "kinds">): Record<string, unknown> | null;
+
+/**
+ * Routing the PROVISIONAL half of the streaming partial-kinds contract.
+ *
+ * Cross-repo system-of-record (read it before changing anything here):
+ * `common-docs/systems/content-ir-system/STREAMING_PARTIAL_KINDS.md` §8.
+ * The reader/validator half lives in `@ai-matrx/content-ir` (`wire/partial-kind`);
+ * the wire gate runs in each host's stream ingest.
+ *
+ * WHAT THIS DOES
+ * --------------
+ * While a structured region streams, the server announces what it thinks the
+ * region IS and what has arrived so far (`metadata.__ir_partial`). This module
+ * turns that provisional event into a routed block that renders through the
+ * EXACT SAME component the final value renders in — which is the entire point:
+ * a bespoke skeleton renderer would be a second render path and is banned.
+ *
+ * HOW, without touching the verified channel
+ * ------------------------------------------
+ * `root` is deliberately `IrStructuredNode`-shaped, so the event wraps into a
+ * `CanonicalBlockIR` and every existing reader — the compiled bridge, the
+ * component resolver, the db-component flip, the generic viewer — works
+ * unchanged. That provisional envelope is placed on a RENDER-LOCAL COPY of the
+ * block's metadata under `__ir`, never on the wire and never in host state. The
+ * block also carries `__ir_provisional: true` so any downstream reader can tell
+ * a provisional render from a verified one.
+ *
+ * THE POSTURE: WITHHOLD BY DEFAULT, OPT IN PER KIND
+ * -------------------------------------------------
+ * A provisional value MAY be missing required fields — that is what the
+ * `partial_unvalidated` notice declares — and §8 of the contract requires that
+ * a component which throws on an absent field is not routed one. Rather than
+ * audit every component, the default is WITHHOLD: nothing changes and the block
+ * keeps its loading skeleton. A kind opts in with `partialReady: true` on its
+ * registry definition. If an opted-in component throws anyway,
+ * `ProvisionalKindBoundary` screams and calls `markKindPartialUnsafe`, which
+ * drops that kind back to withhold for the rest of the session — loud recovery,
+ * never a broken surface.
+ *
+ * TERMINALS
+ * ---------
+ * `superseded` and `retracted` produce NO provisional render, so the swap to
+ * the final value happens in the same frame the terminal arrives — never a
+ * flicker through an empty state. Both are explicit EVENTS: the terminal is
+ * never inferred from the arrival of `__ir`, because a completed block often
+ * has no `__ir` at all (unregistered kind, schema drift, cold catalog) and
+ * inferring it would leave the skeleton up forever in exactly those cases.
+ */
+
+/**
+ * Marker stamped on a render-local block whose `__ir` is PROVISIONAL. Never
+ * emitted by a producer, never persisted, never on the wire.
+ */
+declare const IR_PROVISIONAL_KEY: "__ir_provisional";
+/** True when this block's metadata carries a provisional (not verified) envelope. */
+declare function isProvisionalBlock(metadata: Record<string, unknown> | null | undefined): boolean;
+/** Wrap a validated `partial` event into the envelope shape every IR reader consumes. */
+declare function envelopeFromPartialKind(event: PartialKindEvent): CanonicalBlockIR;
+/** Loud recovery hook — called by ProvisionalKindBoundary when a render throws. */
+declare function markKindPartialUnsafe(kind: string): void;
+/** Test-only reset of the session latch. */
+declare function resetPartialUnsafeKinds(): void;
+/**
+ * Has this kind opted in to being handed a provisional value? Withhold is the
+ * default; see the module doc.
+ */
+declare function isPartialReadyKind(kind: string, env: Pick<KindRouteEnv, "kinds">): boolean;
+interface PartialRenderOptions extends KindRouteOptions {
+    /**
+     * Is the STREAM still running? Message-wide, deliberately — not this block's
+     * own completion.
+     *
+     * 🚨 THE ANTI-STUCK-SKELETON BACKSTOP. Law 1 of the contract says every
+     * partial ends in exactly one terminal, and that law is the ONLY thing
+     * standing between a user and a "Still arriving" skeleton that never
+     * resolves. It is a producer guarantee with at least three ways to not fire:
+     * the drain skips a block missing from the final block list, the emitter
+     * early-returns once the stream ended or was cancelled (so a client abort
+     * drops every retraction), and a flush failure is swallowed so it never kills
+     * a run.
+     *
+     * Once the stream is over, no terminal can ever arrive, so a still-open
+     * provisional is stuck by definition — drop it and let the block's own
+     * content and `__ir` be the truth. Correct to be message-wide: a terminal for
+     * THIS block may still be in flight while the block itself looks finished.
+     *
+     * `undefined` reads as active, so a caller that does not thread stream state
+     * keeps live rendering rather than silently losing it.
+     */
+    streamActive?: boolean;
+}
+/**
+ * The ANNOUNCED-but-not-yet-renderable state: the server has said what this
+ * region is, and the region cannot render its real component yet.
+ *
+ * WHY THIS EXISTS SEPARATELY FROM THE VERIFIED CHANNEL. On a chat stream the
+ * host's own accumulator fills `__ir` in as it parses. A WORKFLOW run's lane
+ * does not: when the server opens the block scope it marks the text channel
+ * `block_shadowed` and the lane stops feeding its accumulator, precisely so one
+ * region is never rendered twice under two sets of block ids
+ * (STREAMING_PARTIAL_KINDS.md §7b rule 4). So on a run page there is NO
+ * streaming `__ir` — the ONLY thing that knows what the region is, is the
+ * partial channel. Without this, a workflow node's structured answer fell
+ * through to the raw-text renderer: a generic loader, then raw JSON
+ * accumulating, then a swap at the end.
+ *
+ * Returns the provisional envelope to feed the kind's loading component, or
+ * null when there is nothing announced (no event, a terminal, a dead stream).
+ * Deliberately independent of `partialReady`: withholding a VALUE from a
+ * component that might throw on it is a real decision, but withholding the
+ * kind's own loading state is not — a skeleton cannot throw, and the reader
+ * seeing what is coming is the whole point.
+ */
+declare function resolveAnnouncedKindLoading(block: {
+    metadata?: Record<string, unknown>;
+}, options?: Pick<PartialRenderOptions, "streamActive">): {
+    kind: string;
+    envelope: CanonicalBlockIR;
+} | null;
+interface ProvisionalKindRender<T> {
+    /** The routed block — same type/serverData shape the final value produces. */
+    block: T;
+    /** The announced (speculative) kind. */
+    kind: string;
+    /** Per-block ordering key, for diagnostics. */
+    seq: number;
+    /** The provisional envelope — feeds the loading skeleton used as the throw fallback. */
+    envelope: CanonicalBlockIR;
+}
+/**
+ * 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).
+ *
+ * Pure: no React, no host state, no side effects beyond the registry reads.
+ */
+declare function resolveProvisionalKindRender<T extends IrRoutableBlock & {
+    metadata?: Record<string, unknown>;
+}>(block: T, env: KindRouteEnv, options?: PartialRenderOptions): ProvisionalKindRender<T> | null;
+
+/**
+ * The two registries this hook watches. Passed explicitly by a host whose
+ * render path sits BELOW no provider — matrx-frontend's block renderer runs
+ * deep inside chat, workflow, and canvas trees that predate this package, and
+ * threading a provider through all of them to read two counters would be the
+ * tail wagging the dog.
+ */
+interface KindVersionSources {
+    kinds: Pick<KindDefinitionSource, "getKindVersion" | "subscribeKind">;
+    components: Pick<ComponentResolutionSource, "getKindVersion" | "subscribeKind">;
+}
+/**
+ * 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).
+ *
+ * `sources` defaults to the provider's host. Passing them explicitly is the
+ * supported way to use this hook outside a provider.
+ */
+declare function useContentIrKindVersion(kind: string | null, sources?: KindVersionSources): number;
+
+declare function isRecordValue(value: unknown): value is Record<string, unknown>;
+/**
+ * True when `applyIrKindRoute` has a registered render path for this kind — a
+ * compiled legacy bridge OR any ACTIVE resolver row (including db-sourced user
+ * components, which route to `db_kind_component`). Mirrors the route's own
+ * decision order; requires the resolver warm tier for db rows (see the warm
+ * tick in {@link KindInstanceRender}).
+ */
+declare function kindIsRoutable(kind: string, host: ContentIrHost): boolean;
+interface KindInstanceRenderProps {
+    kind: string;
+    /** The canonical instance value (a `kind_example.data` row, a form-emitted instance, a node output). */
+    value: unknown;
+    /** Show the honest "no component registered" notice when unroutable. Default true. */
+    showRoutingNote?: boolean;
+    /**
+     * What to render when the routing decision lands on "no component exists for
+     * this kind". The universal document view is the right answer almost
+     * everywhere — it reads well and hides nothing. It is still the wrong answer
+     * when the raw value is an internal ENVELOPE rather than content: an
+     * `agent_result` dumped the verbatim prompt, the model id and the token bill
+     * into the box a learner was waiting on. Passing a fallback lets that caller
+     * show what the reader actually wants WITHOUT anyone second-guessing the
+     * routing decision — this component stays the ONE place that decides whether
+     * a kind has a component.
+     *
+     * Omitted → the host's floor, exactly as before.
+     */
+    unroutableFallback?: ReactNode;
+    /**
+     * Chrome, per THE WRAPPER LAW: a host frame either IS the chrome or has none.
+     * "card" (default) keeps a bordered surface for preview surfaces. "bare"
+     * renders with NO border/background/pad — for a host that already draws a
+     * titled card, where the default produced a two-tone box-in-a-box with a dead
+     * band around it.
+     */
+    variant?: "card" | "bare";
+    className?: string;
+}
+declare function KindInstanceRender({ kind, value, showRoutingNote, unroutableFallback, variant, className, }: KindInstanceRenderProps): react.JSX.Element;
+
+/**
+ * The safety net + the "still arriving" affordance for a provisional kind
+ * render (streaming partial kinds — see `route/partial-kind-route.ts` and
+ * `common-docs/systems/content-ir-system/STREAMING_PARTIAL_KINDS.md`).
+ *
+ * TWO JOBS
+ * --------
+ * 1. **Never let a component throw mid-stream.** A provisional value may be
+ *    missing required fields. The routed kind opted in to tolerating that
+ *    (`partialReady`), but an opt-in is a claim, not a proof — so a throw is
+ *    caught here, SCREAMS through the host's error reporter, drops the kind
+ *    back to withhold for the session (`markKindPartialUnsafe`), and falls back
+ *    to the kind's own loading skeleton. The user sees the pre-partial
+ *    behavior, not a broken message.
+ * 2. **Say it is still arriving.** The user must be able to tell a live fill-in
+ *    from a finished render, and it must not read as an error. A quiet chip
+ *    rides the block's top edge — absolutely positioned and
+ *    `pointer-events-none`, so it costs the content no layout and cannot shift
+ *    the page when it disappears. It sits ON the border rather than inside the
+ *    block: a routed kind often renders its own chrome, and a chip inside the
+ *    box lands on top of those controls.
+ *
+ * No wrapper chrome: no border, no background, no padding. The kind component
+ * already carries its own (THE WRAPPER LAW).
+ */
+
+interface ProvisionalKindBoundaryOwnProps {
+    kind: string;
+    /** Rendered instead of the children when the provisional render throws. */
+    fallback: ReactNode;
+    children: ReactNode;
+}
+declare function ProvisionalKindBoundary(props: ProvisionalKindBoundaryOwnProps): react__default.JSX.Element;
+/**
+ * The "still arriving" frame. `aria-busy` carries the same fact to assistive
+ * tech that the chip carries visually. The chip's own rendering is a host seam
+ * (`renderShimmer`) so an app with a shimmer primitive uses it and one without
+ * still says the true thing, plainly.
+ */
+declare function ProvisionalKindFrame({ children }: {
+    children: ReactNode;
+}): react__default.JSX.Element;
+
+interface GenericStructuredViewProps {
+    /** The raw region source — the zero-loss floor when no envelope survived. */
+    content: string;
+    /** Carries `__ir` (the parsed envelope) and `__ir_route` (the seam marker). */
+    metadata?: Record<string, unknown>;
+    /**
+     * What to show while the region is still streaming. Hosts with a shimmer or
+     * an icon set pass theirs; the default is the same sentence, plainly.
+     */
+    streamingIndicator?: ReactNode;
+    className?: string;
+}
+declare function GenericStructuredView({ content, metadata, streamingIndicator, className, }: GenericStructuredViewProps): react.JSX.Element;
+
+interface DelegatedOutputProps {
+    output: unknown;
+    /** The wrapper's `output_kind` — the node's DECLARATION, the fallback. */
+    declaredKind: string | null;
+    /**
+     * What to draw for a value with no kind at all, and as the unroutable
+     * fallback. Hosts with a settled-output body (the same one their readout
+     * uses — never a second reader) pass it; otherwise the floor draws it.
+     *
+     * A RENDER FUNCTION, not a node: the fallback needs the payload, and the only
+     * component that has read it is this one. Handing back a static node would
+     * force every host to re-read the wrapper itself — a second reader, which is
+     * exactly what this family exists to prevent.
+     */
+    fallback?: (output: unknown) => ReactNode;
+    /** What to say when the step produced nothing. */
+    emptyLabel?: string;
+}
+/**
+ * The delegation seam — the ONLY thing these components do with a payload.
+ *
+ * In-band `__kind` wins over the node's DECLARATION, the same law a run reducer
+ * follows: the discriminator inside the value describes what we are actually
+ * holding, so it is what routes. With no kind at all there is nothing to route
+ * to, and the host's fallback (or the floor) shows what the step produced.
+ */
+declare function DelegatedOutput({ output, declaredKind, fallback, emptyLabel, }: DelegatedOutputProps): react.JSX.Element;
+interface NodeOutcomeViewProps {
+    serverData?: unknown;
+    /** Passed through to {@link DelegatedOutput}. */
+    fallback?: (output: unknown) => ReactNode;
+}
+/** THE renderer for the `node_outcome` runtime wrapper kind. */
+declare function NodeOutcomeView({ serverData, fallback }: NodeOutcomeViewProps): react.JSX.Element | null;
+interface RunResultViewProps {
+    serverData?: unknown;
+    fallback?: (output: unknown) => ReactNode;
+}
+/**
+ * THE renderer for the `run_result` runtime wrapper kind.
+ *
+ * One finished run: one `node_outcome` per TERMINAL node — each delegated to
+ * {@link NodeOutcomeView}, which delegates the payload inside it to the data
+ * kind's own component. Recursion all the way down; no payload is rendered
+ * here, and no `final_text` is read here.
+ *
+ * The run's own `output` is rendered ONLY when the run declared no terminal
+ * outcomes — otherwise it is the same content the outcomes already carry, and
+ * showing both is the duplication the wrapper exists to prevent.
+ */
+declare function RunResultView({ serverData, fallback }: RunResultViewProps): react.JSX.Element | null;
+
+export { type ComponentResolution, type ComponentResolutionSource, ComponentResolver, type ComponentResolverOptions, type ComponentRole, type ContentIrErrorReport, type ContentIrErrorReporter, type ContentIrHost, ContentIrRenderProvider, type ContentIrRenderProviderProps, type ContentIrRenderSeams, DB_KIND_COMPONENT_KEY, DelegatedOutput, type DelegatedOutputProps, GENERIC_STRUCTURED_COMPONENT_KEY, type GenericFallbackReason, GenericStructuredView, type GenericStructuredViewProps, IR_PROVISIONAL_KEY, IR_ROUTE_KEY, type IrRenderBlock, type IrRoutableBlock, type IrRouteMarker, type JsonObject, type KindComponentRow, type KindDefinitionSource, KindInstanceRender, type KindInstanceRenderProps, type KindRouteEnv, type KindRouteOptions, type KindVersionSources, NodeOutcomeView, type NodeOutcomeViewProps, type PartialRenderOptions, ProvisionalKindBoundary, ProvisionalKindFrame, type ProvisionalKindRender, RunResultView, type RunResultViewProps, type StructuredValueRenderProps, type SystemComponentEntry, applyIrKindRoute, consoleErrorReporter, envelopeFromPartialKind, isPartialReadyKind, isProvisionalBlock, isRecordValue, kindIsRoutable, kindServerDataFromStoredValue, markKindPartialUnsafe, readIrRouteMarker, resetPartialUnsafeKinds, resetSourcelessDbRowReports, resolveAnnouncedKindLoading, resolveProvisionalKindRender, routeEnvOf, useContentIrHost, useContentIrHostOrNull, useContentIrKindVersion, useKindRouteEnv };