@ai-matrx/content-ir-react 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## 0.11.0 — 2026-09-08
+
+**THE DIRECTIVE TIER — `/directives`.** Every AI Matrx UI draws a Kind
+Directive through ONE renderer, from the package. Until now the side-effect
+card, the fallback floor, the Apply control and the renderer registry with
+THE PREFIX TIER lived only in matrx-frontend (`features/matrx-envelope/`);
+Workflow Studio had none of it and showed the agent builder's
+`directive_v1_action_create_agent_definition` envelope as raw JSON text.
+
+- `DirectiveRender` — decode (JSON text or a value) → host-registered
+  renderer (exact slug, then class) → `SideEffectDirectiveCard` for every
+  create/update/delete/action shape → `DirectiveFallbackCard` for any other
+  class. Never null; a non-directive is a raw `<pre>`; an unhonourable shell is
+  REPORTED through the host and falls to raw.
+- `SideEffectDirectiveCard` — the card a person approves a write from: named
+  from the catalog, one flat row per item titled from authority, scalar fact
+  chips, `View` through the host's open seam with `__kind` stamped (THE
+  DIRECTIVE⇄KIND SEAM), copy through the host's chrome, Apply through the
+  host's confirm seam. `DirectiveFallbackCard` and `ApplyDirectiveButton` are
+  exported too. Glyphs are inline SVG (Lucide paths) — this package depends on
+  no icon library.
+- `registerDirectiveRenderer` / `getDirectiveRenderer` — the registry on a
+  `globalThis` slot; a host registers its bespoke renderers (reference chips,
+  plan trees) and they win over the package tier.
+- `DirectiveHostProvider` + `useDirectiveHost` + `DirectiveHost` — the seams:
+  `confirm` (absent → the Apply control is ABSENT, never dead), `openItem`,
+  `renderCopy`, `nouns`, `itemKind`, `reportError`. `ContentIrHost` gained an
+  optional `directives` field and `ContentIrRenderProvider` provides it; a host
+  that has not adopted the render provider mounts `DirectiveHostProvider`
+  alone.
+- **The route**: `applyIrKindRoute` types a reserved-slug block to
+  `DIRECTIVE_BLOCK_TYPE` (`"matrx"`, marker `{ by: "directive" }`) BEFORE the
+  component resolver — a directive has no `kind_component` row by design, so
+  the `unregistered` / `no-component` floors must never claim one.
+  `KindInstanceRender` draws a reserved slug through `DirectiveRender` and
+  `kindIsRoutable` answers true for it.
+
+### Consumer action
+
+- **matrx-frontend**: `MatrxEnvelopeBlock` becomes a thin wrapper around
+  `DirectiveRender`; delete `EnvelopeFallbackCard`, `ApplyDirectiveButton`,
+  `directives/sideEffect/{SideEffectDirectiveCard,classIcon}` and the
+  registry core in `features/matrx-envelope/registry.tsx` (keep the
+  reference-chip / plan-tree / context-groom / create-project registrations,
+  now calling the package's `registerDirectiveRenderer`). Wire
+  `matrxContentIrHost.directives` (`confirm` → `confirmDirective`, `openItem`
+  → the directive-item window, `renderCopy` → `CopyButtons`, `nouns` /
+  `itemKind` → the generated catalog tables).
+- **Workflow Studio**: adopted in the same commit (`StudioDirectiveHost`).
+
 ## 0.10.0 — 2026-08-31
 
 - **A failed list load is not truth — retry, then settle.** 0.9.0's posture

package/dist/db-component.d.cts

@@ -1,4 +1,4 @@
-import * as React from 'react';
+import * as react from 'react';
 import { C as ComponentResolution, a as ContentIrErrorReporter } from './component-resolution.types-C1MzCf2s.cjs';
 
 /**
@@ -97,7 +97,7 @@ interface DbKindComponentRenderProps {
     uiOptions?: KindComponentUiOptions;
 }
 interface CompiledDbKindComponent {
-    Component: React.ComponentType<DbKindComponentRenderProps>;
+    Component: react.ComponentType<DbKindComponentRenderProps>;
     /** Compiled `props_transform`, or null when the row declares none. */
     transform: ((data: unknown) => unknown) | null;
 }
@@ -147,7 +147,7 @@ type DbKindComponentCompiler = (args: {
     code: string;
     allowedImports: string[];
 }) => {
-    Component: React.ComponentType<Record<string, unknown>> | null;
+    Component: react.ComponentType<Record<string, unknown>> | null;
     error: string | null;
 };
 interface DbKindComponentCachePorts {
@@ -234,8 +234,8 @@ interface DbKindComponentErrorBoundaryProps {
     kind: string;
     /** The resolved component's `updated_at`; a change means a new version. */
     resetSignal: string | null;
-    fallback: React.ReactNode;
-    children: React.ReactNode;
+    fallback: react.ReactNode;
+    children: react.ReactNode;
     /**
      * Where the catch lands. A host binds structured capture + incident filing
      * here; the default screams to the console. NOTE for hosts whose console
@@ -256,12 +256,12 @@ interface State {
      */
     signalAtLastRender: string | null;
 }
-declare class DbKindComponentErrorBoundary extends React.Component<DbKindComponentErrorBoundaryProps, State> {
+declare class DbKindComponentErrorBoundary extends react.Component<DbKindComponentErrorBoundaryProps, State> {
     constructor(props: DbKindComponentErrorBoundaryProps);
     static getDerivedStateFromError(): Partial<State>;
     static getDerivedStateFromProps(props: DbKindComponentErrorBoundaryProps, state: State): State | null;
-    componentDidCatch(error: Error, errorInfo: React.ErrorInfo): void;
-    render(): React.ReactNode;
+    componentDidCatch(error: Error, errorInfo: react.ErrorInfo): void;
+    render(): react.ReactNode;
 }
 
 export { type CompiledDbKindComponent, type DbKindActionResult, type DbKindCompileResult, type DbKindComponentCache, type DbKindComponentCachePorts, type DbKindComponentCompiler, DbKindComponentErrorBoundary, type DbKindComponentErrorBoundaryProps, type DbKindComponentIncident, type DbKindComponentIncidentSink, type DbKindComponentIncidentType, type DbKindComponentRenderProps, type KindComponentUiOptions, type ResolveKindValue, type RunDbKindAction, createDbKindComponentCache, isDbKindComponentBodyPending };

package/dist/db-component.d.ts

@@ -1,4 +1,4 @@
-import * as React from 'react';
+import * as react from 'react';
 import { C as ComponentResolution, a as ContentIrErrorReporter } from './component-resolution.types-C1MzCf2s.js';
 
 /**
@@ -97,7 +97,7 @@ interface DbKindComponentRenderProps {
     uiOptions?: KindComponentUiOptions;
 }
 interface CompiledDbKindComponent {
-    Component: React.ComponentType<DbKindComponentRenderProps>;
+    Component: react.ComponentType<DbKindComponentRenderProps>;
     /** Compiled `props_transform`, or null when the row declares none. */
     transform: ((data: unknown) => unknown) | null;
 }
@@ -147,7 +147,7 @@ type DbKindComponentCompiler = (args: {
     code: string;
     allowedImports: string[];
 }) => {
-    Component: React.ComponentType<Record<string, unknown>> | null;
+    Component: react.ComponentType<Record<string, unknown>> | null;
     error: string | null;
 };
 interface DbKindComponentCachePorts {
@@ -234,8 +234,8 @@ interface DbKindComponentErrorBoundaryProps {
     kind: string;
     /** The resolved component's `updated_at`; a change means a new version. */
     resetSignal: string | null;
-    fallback: React.ReactNode;
-    children: React.ReactNode;
+    fallback: react.ReactNode;
+    children: react.ReactNode;
     /**
      * Where the catch lands. A host binds structured capture + incident filing
      * here; the default screams to the console. NOTE for hosts whose console
@@ -256,12 +256,12 @@ interface State {
      */
     signalAtLastRender: string | null;
 }
-declare class DbKindComponentErrorBoundary extends React.Component<DbKindComponentErrorBoundaryProps, State> {
+declare class DbKindComponentErrorBoundary extends react.Component<DbKindComponentErrorBoundaryProps, State> {
     constructor(props: DbKindComponentErrorBoundaryProps);
     static getDerivedStateFromError(): Partial<State>;
     static getDerivedStateFromProps(props: DbKindComponentErrorBoundaryProps, state: State): State | null;
-    componentDidCatch(error: Error, errorInfo: React.ErrorInfo): void;
-    render(): React.ReactNode;
+    componentDidCatch(error: Error, errorInfo: react.ErrorInfo): void;
+    render(): react.ReactNode;
 }
 
 export { type CompiledDbKindComponent, type DbKindActionResult, type DbKindCompileResult, type DbKindComponentCache, type DbKindComponentCachePorts, type DbKindComponentCompiler, DbKindComponentErrorBoundary, type DbKindComponentErrorBoundaryProps, type DbKindComponentIncident, type DbKindComponentIncidentSink, type DbKindComponentIncidentType, type DbKindComponentRenderProps, type KindComponentUiOptions, type ResolveKindValue, type RunDbKindAction, createDbKindComponentCache, isDbKindComponentBodyPending };

package/dist/directive-host-DAb7Keg8.d.cts

@@ -0,0 +1,63 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { DecodedDirective, DirectiveNounCatalog, DirectiveItemKindLookup } from '@ai-matrx/content-ir';
+
+interface DirectiveApplyResult {
+    applied: number;
+    failed: number;
+}
+interface DirectiveOpenItemOptions {
+    /** The item, `__kind`-stamped when the shape has an item kind. */
+    item: Record<string, unknown>;
+    /** The content-IR kind this item IS, or null when the shape has none. */
+    itemKind: string | null;
+    /** What the item is called — the same title the card shows. */
+    title: string;
+    /** "Run Create agent definition · item 1 of 1". */
+    subtitle: string | null;
+    directive: DecodedDirective;
+    index: number;
+    total: number;
+}
+interface DirectiveCopyProps {
+    label: string;
+    /** The value to copy — the whole shell or one item. */
+    value: unknown;
+    /** The item's kind, when copying an item. */
+    kind?: string | null;
+    size: "icon" | "xs";
+}
+interface DirectiveHost {
+    /**
+     * Apply a side-effect directive as the user (the server re-validates every
+     * item against the registered model and runs the ONE handler; idempotent).
+     * Reject with an Error whose message is safe to show.
+     */
+    confirm?: (shell: {
+        __kind: string;
+        items: Record<string, unknown>[];
+    }) => Promise<DirectiveApplyResult>;
+    /** Open ONE item to read it properly before approving the write. */
+    openItem?: (options: DirectiveOpenItemOptions) => void;
+    /** Host copy controls. */
+    renderCopy?: (props: DirectiveCopyProps) => ReactNode;
+    /** The mirrored noun catalog (label / family / title column). */
+    nouns?: DirectiveNounCatalog;
+    /** slug → the kind ONE item is (THE DIRECTIVE⇄KIND SEAM), or null. */
+    itemKind?: DirectiveItemKindLookup;
+    /** Where a decode failure or an unhonourable shell is reported. Default: console.error. */
+    reportError?: (message: string) => void;
+}
+interface DirectiveHostProviderProps {
+    host: DirectiveHost;
+    children: ReactNode;
+}
+declare function DirectiveHostProvider({ host, children }: DirectiveHostProviderProps): react.JSX.Element;
+/**
+ * The wired directive host. Unlike the render host this does NOT throw when
+ * unwired: a directive still renders (named, itemised, copy-less, apply-less)
+ * — degrading the chrome is honest, hiding the content is not.
+ */
+declare function useDirectiveHost(): DirectiveHost;
+
+export { type DirectiveApplyResult as D, type DirectiveCopyProps as a, type DirectiveHost as b, DirectiveHostProvider as c, type DirectiveHostProviderProps as d, type DirectiveOpenItemOptions as e, useDirectiveHost as u };

package/dist/directive-host-DAb7Keg8.d.ts

@@ -0,0 +1,63 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { DecodedDirective, DirectiveNounCatalog, DirectiveItemKindLookup } from '@ai-matrx/content-ir';
+
+interface DirectiveApplyResult {
+    applied: number;
+    failed: number;
+}
+interface DirectiveOpenItemOptions {
+    /** The item, `__kind`-stamped when the shape has an item kind. */
+    item: Record<string, unknown>;
+    /** The content-IR kind this item IS, or null when the shape has none. */
+    itemKind: string | null;
+    /** What the item is called — the same title the card shows. */
+    title: string;
+    /** "Run Create agent definition · item 1 of 1". */
+    subtitle: string | null;
+    directive: DecodedDirective;
+    index: number;
+    total: number;
+}
+interface DirectiveCopyProps {
+    label: string;
+    /** The value to copy — the whole shell or one item. */
+    value: unknown;
+    /** The item's kind, when copying an item. */
+    kind?: string | null;
+    size: "icon" | "xs";
+}
+interface DirectiveHost {
+    /**
+     * Apply a side-effect directive as the user (the server re-validates every
+     * item against the registered model and runs the ONE handler; idempotent).
+     * Reject with an Error whose message is safe to show.
+     */
+    confirm?: (shell: {
+        __kind: string;
+        items: Record<string, unknown>[];
+    }) => Promise<DirectiveApplyResult>;
+    /** Open ONE item to read it properly before approving the write. */
+    openItem?: (options: DirectiveOpenItemOptions) => void;
+    /** Host copy controls. */
+    renderCopy?: (props: DirectiveCopyProps) => ReactNode;
+    /** The mirrored noun catalog (label / family / title column). */
+    nouns?: DirectiveNounCatalog;
+    /** slug → the kind ONE item is (THE DIRECTIVE⇄KIND SEAM), or null. */
+    itemKind?: DirectiveItemKindLookup;
+    /** Where a decode failure or an unhonourable shell is reported. Default: console.error. */
+    reportError?: (message: string) => void;
+}
+interface DirectiveHostProviderProps {
+    host: DirectiveHost;
+    children: ReactNode;
+}
+declare function DirectiveHostProvider({ host, children }: DirectiveHostProviderProps): react.JSX.Element;
+/**
+ * The wired directive host. Unlike the render host this does NOT throw when
+ * unwired: a directive still renders (named, itemised, copy-less, apply-less)
+ * — degrading the chrome is honest, hiding the content is not.
+ */
+declare function useDirectiveHost(): DirectiveHost;
+
+export { type DirectiveApplyResult as D, type DirectiveCopyProps as a, type DirectiveHost as b, DirectiveHostProvider as c, type DirectiveHostProviderProps as d, type DirectiveOpenItemOptions as e, useDirectiveHost as u };