@ai-matrx/content-ir-react 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+## 0.1.0 — 2026-08-23
+
+First release: the shared Content IR RENDER layer, extracted from
+matrx-frontend so the dashboard, the Chrome extension, the desktop app, and
+customers building on the platform render kinds through ONE implementation
+(KINDS_EVERYWHERE_PLAN §10d-A4).
+
+- `route/kind-route` — `applyIrKindRoute`, the marker helpers, and
+  `kindServerDataFromStoredValue`. Was matrx-frontend's
+  `features/content-ir/react/kind-route.ts`; the registries, the resolution
+  platform, and the error sink are now a `KindRouteEnv` argument, and the
+  `artifact` special case became the host's `ownedTypes` option.
+- `route/partial-kind-route` — `resolveProvisionalKindRender`,
+  `resolveAnnouncedKindLoading`, the partial-unsafe session latch.
+- `resolver/component-resolver` — `ComponentResolver`, was matrx-frontend's
+  `ComponentRegistry`: compiled floor, DB override, granular per-kind repaint
+  counters, cold-fetch dedupe, warm/refresh with loud recovery. Its two loaders
+  and its error sink are constructor arguments.
+  - **Fixed in the move:** `lastRefreshAt` used `0` as "never refreshed", so a
+    host supplying a clock that starts near zero had its FIRST refresh silently
+    rate-limited away. It is now explicitly nullable.
+- `react/` — `KindInstanceRender`, `GenericStructuredView`, `NodeOutcomeView` /
+  `RunResultView` / `DelegatedOutput`, `ProvisionalKindBoundary` /
+  `ProvisionalKindFrame`, `useContentIrKindVersion`.
+- `NodeOutcomeView` / `RunResultView` / `DelegatedOutput` take `fallback` as a
+  RENDER FUNCTION `(output) => ReactNode`, not a node: the fallback needs the
+  payload, and the only component that has read the wrapper is the view. A
+  static node would force every host to re-read the wrapper — a second reader,
+  which is exactly what this family exists to prevent.
+- `host/` — the seam contract (`ContentIrHost`) and
+  `ContentIrRenderProvider`. Reading the host outside a provider throws rather
+  than defaulting: a silent default would render the wrong component for every
+  kind in an app and look like a data problem for weeks.
+
+Peer dependencies: `react >= 19` and `@ai-matrx/content-ir` 0.2.0 (exact).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AI Matrix Engine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# @ai-matrx/content-ir-react
+
+The shared **render layer** for AI Matrx Content IR.
+
+[`@ai-matrx/content-ir`](https://www.npmjs.com/package/@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.
+
+```bash
+npm install @ai-matrx/content-ir-react @ai-matrx/content-ir react
+```
+
+## Wire your host once
+
+```tsx
+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`.