@ai-matrx/content-ir-react

The shared render layer for AI Matrx Content IR.

@ai-matrx/content-ir is the pure kernel — it parses a kind, validates it, reads a streaming partial, and reads a runtime wrapper. This package is the layer above it: the one that decides which component a kind renders through, and draws the chrome around that decision.

It is framework-portable React. No Next.js, no Redux, no Supabase, no router, no host error capture. Every host-specific capability enters through an explicit seam.

npm install @ai-matrx/content-ir-react @ai-matrx/content-ir react

Wire your host once

import {
  ComponentResolver,
  ContentIrRenderProvider,
  applyIrKindRoute,
  type ContentIrHost,
} from "@ai-matrx/content-ir-react";

const components = new ComponentResolver({
  loadAll: () => fetchKindComponentRows(),
  loadForKind: (kind, platform) => fetchKindComponentRows({ kind, platform }),
  reportError: (report) => myErrorLog(report),
});

const host: ContentIrHost = {
  platform: "web",
  kinds: myKindDefinitionSource,
  components,
  reportError: (report) => myErrorLog(report),
  // The host's dispatch table — the ONE place a component key becomes a
  // component. Run the route here.
  renderBlock: (block) => <MyBlockRenderer block={applyIrKindRoute(block, env)} />,
  // The FLOOR: any JSON value as a human document.
  renderValue: ({ value, kind, note }) => (
    <MyStructuredValueView value={value} kind={kind} note={note} />
  ),
};

<ContentIrRenderProvider host={host}>
  <App />
</ContentIrRenderProvider>;

What you get

| Export | What it is | |---|---| | applyIrKindRoute | THE kind route: envelope → registered kind → the right component key. Pure; callable from a reducer or a stream accumulator. | | resolveProvisionalKindRender / resolveAnnouncedKindLoading | The streaming partial-kinds route — a provisional value renders through the SAME component the final value will. | | ComponentResolver | (kind, platform, role) → component, compiled floor + DB override, granular repaint counters, cold-fetch dedupe. | | KindInstanceRender | Render one canonical kind instance through the real production path, with the "no component yet" floor beneath it. | | GenericStructuredView | The R6 disposition for a known shape nothing render-trusted claims — readable, honest, never an error. | | NodeOutcomeView / RunResultView | The runtime-wrapper chrome. Transparent routers: they delegate, they never render a payload. | | ProvisionalKindBoundary / ProvisionalKindFrame | The mid-stream safety net and the "still arriving" affordance. | | useContentIrKindVersion | Granular late-arrival repaint for one kind. |

The rule this package exists to enforce

A shape has exactly one component, everywhere. A second implementation of the routing decisions — in a dashboard, an extension, a desktop webview, a customer's app — is a guaranteed divergence, and it is banned. If this package cannot express what your host needs, add a seam; never fork the route.

Docs

• Package internals and boundary: FEATURE.md beside this file.
• Cross-repo system-of-record: common-docs/systems/content-ir-twin/FEATURE.md.
• Shape System semantics: matrx-frontend/features/content-ir/docs/SHAPE_SYSTEM.md.