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

package/dist/react.d.cts

@@ -0,0 +1,195 @@
+import { c as KindDefinitionSource, C as ContentIrHost } from './host-types-DvGv8s9L.cjs';
+import { d as ComponentResolutionSource } from './component-resolution.types-BS1ySIg-.cjs';
+import * as React from 'react';
+import React__default, { ReactNode } from 'react';
+import '@ai-matrx/content-ir';
+
+/**
+ * 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}).
+ */
+/**
+ * Is there a render path for this kind that is NOT the generic key/value floor?
+ *
+ * 🚨 READ THIS BEFORE USING IT AS A HEALTH SIGNAL. It answers a narrow
+ * question — "will a direct-object render mount something other than the
+ * generic view?" — and it is the right question for the fallback decision it
+ * was written for. It is the WRONG question for "does this kind work".
+ *
+ * It cannot see any of: whether the kind's schema loads, whether a streamed
+ * payload is recognized from text, or what `applyIrKindRoute` returns for a
+ * real envelope. On 2026-08-29 every one of ~221 kinds that had stopped
+ * rendering in chat still answered `true` here, because their component rows
+ * were fine — the recognition step ahead of the component was not.
+ *
+ * For "does this kind work", run the render paths
+ * (`features/content-ir/render-paths`) and read the route's actual answer.
+ */
+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 { DelegatedOutput, type DelegatedOutputProps, GenericStructuredView, type GenericStructuredViewProps, KindInstanceRender, type KindInstanceRenderProps, type KindVersionSources, NodeOutcomeView, type NodeOutcomeViewProps, ProvisionalKindBoundary, ProvisionalKindFrame, RunResultView, type RunResultViewProps, isRecordValue, kindIsRoutable, useContentIrKindVersion };

package/dist/react.d.ts

@@ -0,0 +1,195 @@
+import { c as KindDefinitionSource, C as ContentIrHost } from './host-types-CZ_Bkp4R.js';
+import { d as ComponentResolutionSource } from './component-resolution.types-BS1ySIg-.js';
+import * as React from 'react';
+import React__default, { ReactNode } from 'react';
+import '@ai-matrx/content-ir';
+
+/**
+ * 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}).
+ */
+/**
+ * Is there a render path for this kind that is NOT the generic key/value floor?
+ *
+ * 🚨 READ THIS BEFORE USING IT AS A HEALTH SIGNAL. It answers a narrow
+ * question — "will a direct-object render mount something other than the
+ * generic view?" — and it is the right question for the fallback decision it
+ * was written for. It is the WRONG question for "does this kind work".
+ *
+ * It cannot see any of: whether the kind's schema loads, whether a streamed
+ * payload is recognized from text, or what `applyIrKindRoute` returns for a
+ * real envelope. On 2026-08-29 every one of ~221 kinds that had stopped
+ * rendering in chat still answered `true` here, because their component rows
+ * were fine — the recognition step ahead of the component was not.
+ *
+ * For "does this kind work", run the render paths
+ * (`features/content-ir/render-paths`) and read the route's actual answer.
+ */
+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 { DelegatedOutput, type DelegatedOutputProps, GenericStructuredView, type GenericStructuredViewProps, KindInstanceRender, type KindInstanceRenderProps, type KindVersionSources, NodeOutcomeView, type NodeOutcomeViewProps, ProvisionalKindBoundary, ProvisionalKindFrame, RunResultView, type RunResultViewProps, isRecordValue, kindIsRoutable, useContentIrKindVersion };