@ai-matrx/content-ir-react 0.7.1 → 0.8.0

package/dist/route-C55jsF4B.d.cts

@@ -0,0 +1,433 @@
+import { C as ComponentResolutionSource, b as ContentIrErrorReporter, a as ComponentResolution } from './component-resolution.types-fvR92hW7.cjs';
+import { ReactNode } from 'react';
+import { KindDefinition, CanonicalBlockIR, PartialKindEvent } from '@ai-matrx/content-ir';
+
+/**
+ * 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;
+
+/**
+ * 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"
+/**
+ * An ACTIVE component row exists and names `generic_structured` — i.e. the
+ * fallback, registered under a component's name. This reads as coverage to
+ * every count-the-rows check on the platform and is not: the reader still
+ * gets a key/value dump. Kept as its own reason because the repair differs
+ * (author a component AND retire the decoy row), and because a page that
+ * silently marked itself `by: "bundled"` here is how 226 of 428 active
+ * kinds came to be certified as renderable while rendering generically
+ * (found 2026-08-23).
+ */
+ | "generic-row"
+/**
+ * The envelope carries a kind-preserved RAW: the payload identified a
+ * registered kind and its value FAILED a check — a schema violation, an
+ * array-item kind mismatch, a duplicate key, a contradicted speculation.
+ * The instance is BROKEN, not component-less — the repair is fixing the
+ * payload or the schema, and the generic floor must acknowledge the kind and
+ * surface the recorded problems.
+ *
+ * NOT this: a kind whose schema was never available (`kindState:
+ * "unverified"`). Nothing checked that value, so calling it broken is a
+ * false accusation — it routes to its component. The two were one state
+ * until 2026-08-29 and conflating them was a platform-wide outage.
+ */
+ | "broken-instance"
+/**
+ * The slug is not in the registry at all (typo, foreign emitter, a shape
+ * not yet created). Routed anyway — Arman's 2026-08-29 ruling: a root
+ * `__kind` key means the kind system owns the render, no exceptions. The
+ * repair is creating/registering the shape (or fixing the slug).
+ */
+ | "unregistered";
+interface IrRouteMarker {
+    by: ComponentResolution["resolvedBy"] | "generic";
+    key: string;
+    /**
+     * 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 BOUND ROUTE — the pure route functions with a host's env and owned
+ * types partially applied, built ONCE in a host wiring module.
+ *
+ * Every host was writing the same wrapper file by hand: one function per pure
+ * route, each forwarding `matrx…Env` + `ownedTypes` (matrx-frontend carried
+ * two such modules; the dashboard a third). Per C22 that repeated delta is
+ * package-provided: a host module now only INJECTS (its env, its owned block
+ * types) and re-exports what this factory returns.
+ *
+ * The functions are the exact pure routes — read `kind-route.ts` /
+ * `partial-kind-route.ts` for semantics; nothing behavioral lives here.
+ */
+
+interface KindRouteBinding {
+    /** Route one block through the bound registries. */
+    applyIrKindRoute<T extends IrRoutableBlock>(block: T): T;
+    /**
+     * Rehydration route for STRUCTURED persisted artifacts: 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.
+     */
+    kindServerDataFromStoredValue(value: unknown): Record<string, unknown> | null;
+    /** Has this kind opted in to being handed a provisional value? */
+    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).
+     */
+    resolveProvisionalKindRender<T extends IrRoutableBlock & {
+        metadata?: Record<string, unknown>;
+    }>(block: T, options?: Pick<PartialRenderOptions, "streamActive">): ProvisionalKindRender<T> | null;
+}
+/** Bind the pure routes to one host's env + owned block types. */
+declare function createKindRouteBinding(env: KindRouteEnv, options?: KindRouteOptions): KindRouteBinding;
+
+export { type ContentIrHost as C, DB_KIND_COMPONENT_KEY as D, GENERIC_STRUCTURED_COMPONENT_KEY as G, IR_PROVISIONAL_KEY as I, type KindRouteEnv as K, type PartialRenderOptions as P, type StructuredValueRenderProps as S, type KindDefinitionSource as a, type ContentIrRenderSeams as b, type GenericFallbackReason as c, IR_ROUTE_KEY as d, type IrRenderBlock as e, type IrRoutableBlock as f, type IrRouteMarker as g, type KindRouteBinding as h, type KindRouteOptions as i, type ProvisionalKindRender as j, applyIrKindRoute as k, createKindRouteBinding as l, envelopeFromPartialKind as m, isPartialReadyKind as n, isProvisionalBlock as o, kindServerDataFromStoredValue as p, markKindPartialUnsafe as q, readIrRouteMarker as r, resetPartialUnsafeKinds as s, resetSourcelessDbRowReports as t, resolveAnnouncedKindLoading as u, resolveProvisionalKindRender as v, routeEnvOf as w };