@dudousxd/nestjs-agent-react 0.18.0 → 0.19.0

package/README.md

@@ -352,46 +352,50 @@ menu (`ChatCommandPalette`, grown into the combobox's listbox) above the compose
 
 `@dudousxd/nestjs-agent-react/genui` draws server-pushed components (`ui` frames, persisted `ui[]`)
 with YOUR renderers. Headless: it adds no element and no style — only what your registry renders.
+Set it up once, at the root; `MessageItem` / `MessageList` then draw every pushed component with no
+`renderUi` of their own:
 
 ```tsx
-import { GenerativeUI, type GenuiRegistry } from '@dudousxd/nestjs-agent-react/genui';
-import { catalog } from './catalog'; // optional: a @dudousxd/nestjs-agent-genui catalog
+import { GenuiProvider, type GenuiRegistry } from '@dudousxd/nestjs-agent-react/genui';
+import { catalog } from './catalog'; // optional: the same file the server uses (@dudousxd/nestjs-agent-core/genui)
 
 const registry: GenuiRegistry = { DataTable: MyTable, Chart: MyChart, Card: MyCard, Text: MyText };
 
-<MessageItem
-  message={message}
-  renderUi={(block) => (
-    <GenerativeUI
-      part={block}
-      registry={registry}
-      catalog={catalog}
-      resolveComponent={(name, version) => loadTenantComponent(name, version)}
-      fallback={({ reason, item }) => <UnknownComponent name={item.component} reason={reason} />}
-      loading={<Skeleton />}
-    />
-  )}
-/>;
+<GenuiProvider
+  registry={registry}
+  catalog={catalog}
+  resolveComponent={(name, version) => loadTenantComponent(name, version)}
+  fallback={({ reason, item }) => <UnknownComponent name={item.component} reason={reason} />}
+  loading={<Skeleton />}
+>
+  <App />
+</GenuiProvider>;
 ```
 
 | Prop | |
 |---|---|
-| `part` | A transcript `ui` block, a `data-ui` message part, or a stored `{ id, component, props, version? }`. |
 | `registry` | Component name → your renderer. It receives the props spread (and `children` as a tree layout node). |
 | `catalog?` | Validate props before drawing (`catalog.validateSync` when it can, so no placeholder flashes). Components the catalog does not know render unvalidated. |
 | `resolveComponent?(name, version)` | For components the registry lacks, e.g. a tenant's own, at the exact version a message was rendered with. Sync or async, cached per resolver/name/version. |
 | `fallback?` | A node, or `({ reason: 'unknown' \| 'invalid' \| 'error', item, issues?, error? }) => node`. Default: nothing. |
 | `loading?`, `onError?` | While a resolver or async validation is pending; a renderer threw (each item has its own error boundary). |
+| `treeRenderer?` | Draws a whole `genui:tree` frame (e.g. json-render, below). Default: node by node through `registry`. |
+
+`<GenerativeUI part={block} />` draws one component (a transcript `ui` block, a `data-ui` message
+part, or a stored `{ id, component, props, version? }`) with the provider's settings; any of the
+props above passed to it win over the provider's. An explicit `renderUi` on `MessageItem` still
+wins too, and `useAmbientRenderUi()` (main entry) hands a custom transcript the provider's renderer.
 
 A `genui:tree` frame (tree mode) is drawn node by node through the same registry, catalog and
-fallbacks, each node in its own boundary; put a `genui:tree` entry in the registry to take over.
-`useGenerativeUI(part, options)` returns the state (`ready` with `Component`/`props`, `loading`,
-`problem`) for your own chrome; wrap it in `<GenerativeUIScope>` when it may draw a tree.
-
-**json-render** (optional peer `@json-render/react` >= 0.21):
-`@dudousxd/nestjs-agent-react/genui/json-render` renders tree frames through json-render's
-`Renderer` — `registry[GENUI_TREE_COMPONENT] = jsonRenderTree(toJsonRenderRegistry(registry))` —
-plus `JsonRenderTree` and `treeToJsonRenderSpec`.
+fallbacks, each node in its own boundary. `useGenerativeUI(part, options?)` returns the state
+(`ready` with `Component`/`props`, `loading`, `problem`) for your own chrome, defaulting to the
+provider's settings; wrap it in `<GenerativeUIScope>` when it may draw a tree.
+
+**json-render** (optional peer `@json-render/react` >= 0.21): import `GenuiProvider` from
+`@dudousxd/nestjs-agent-react/genui/json-render` instead — the same provider plus
+`jsonRender={myJsonRenderRegistry}` (or `jsonRender` alone, to derive one from `registry`), which
+draws tree frames through json-render's `Renderer`. `JsonRenderTree`, `jsonRenderTree`,
+`toJsonRenderRegistry` and `treeToJsonRenderSpec` are exported for hand wiring.
 
 ### Designed components, as copy-in source
 

package/dist/generative-ui-BhXFni8j.d.ts

@@ -0,0 +1,167 @@
+import * as React from 'react';
+import { ComponentType, ReactNode } from 'react';
+import { T as TranscriptUiBlock } from './model-gHqjNjLJ.js';
+
+/** The `ui` frame component a composed tree is pushed under (`GENUI_TREE_COMPONENT` of `@dudousxd/nestjs-agent-core/genui`). */
+declare const GENUI_TREE_COMPONENT = "genui:tree";
+/** One pushed component, normalized from whatever carried it (a transcript block, a `data-ui` part, a stored entry). */
+interface GenerativeUIItem {
+    id: string;
+    component: string;
+    props: Record<string, unknown>;
+    version: number | null;
+    toolCallId: string | null;
+}
+/** A node of a composed tree (`genui:tree` frames): `{ type, props, children? }`. */
+interface GenerativeUIElement {
+    type: string;
+    props: Record<string, unknown>;
+    children?: GenerativeUIElement[];
+}
+/**
+ * An app's renderer for one component: it receives the component's props spread, plus `children`
+ * when it is a layout node in a tree. Any React component — the library never styles anything.
+ */
+type GenuiRenderer<P = any> = ComponentType<P & {
+    children?: ReactNode;
+}>;
+/** Component name → the app's renderer. */
+type GenuiRegistry = Record<string, GenuiRenderer>;
+/**
+ * Resolve a component the registry does not have — typically a tenant's own component, fetched for
+ * the exact `version` a message was rendered with. Return `null`/`undefined` for "no such
+ * component". May be async; results are cached per resolver, name and version.
+ */
+type ResolveComponent = (name: string, version: number | null) => GenuiRenderer | null | undefined | Promise<GenuiRenderer | null | undefined>;
+interface GenuiIssueLike {
+    path: (string | number)[];
+    message: string;
+}
+type ValidationLike = {
+    ok: true;
+    value: Record<string, unknown>;
+} | {
+    ok: false;
+    issues: GenuiIssueLike[];
+};
+/**
+ * What the renderer needs from a catalog to validate props before drawing them. A `Catalog` from
+ * `@dudousxd/nestjs-agent-core/genui` satisfies it; declared structurally so any catalog-shaped
+ * object does too.
+ */
+interface GenuiCatalogLike {
+    has(name: string): boolean;
+    validate(name: string, props: unknown): Promise<ValidationLike>;
+    validateSync?(name: string, props: unknown): ValidationLike | undefined;
+}
+interface GenerativeUIOptions {
+    registry: GenuiRegistry;
+    /** Validate props against it before rendering. Components the catalog does not know render unvalidated. */
+    catalog?: GenuiCatalogLike;
+    resolveComponent?: ResolveComponent;
+    /**
+     * Draws a composed tree frame (`genui:tree`) whole — e.g. through json-render (see the
+     * `/genui/json-render` subpath's `GenuiProvider`). Omitted → trees render node by node through
+     * `registry`.
+     */
+    treeRenderer?: GenuiRenderer<{
+        root?: GenerativeUIElement;
+    }>;
+}
+/** Why an item did not render. */
+type GenerativeUIProblem = {
+    reason: 'unknown';
+    item: GenerativeUIItem;
+} | {
+    reason: 'invalid';
+    item: GenerativeUIItem;
+    issues: GenuiIssueLike[];
+} | {
+    reason: 'error';
+    item: GenerativeUIItem;
+    error: unknown;
+};
+type GenerativeUIState = {
+    status: 'ready';
+    item: GenerativeUIItem;
+    Component: GenuiRenderer;
+    props: Record<string, unknown>;
+} | {
+    status: 'loading';
+    item: GenerativeUIItem;
+} | ({
+    status: 'problem';
+} & GenerativeUIProblem);
+
+/** What to draw instead of a component that did not render. Default: nothing. */
+type GenerativeUIFallback = ReactNode | ((problem: GenerativeUIProblem) => ReactNode);
+/**
+ * Renders a `genui:tree` frame's `{ root }` node by node through the same registry, catalog and
+ * resolver as top-level components. Used automatically for tree frames unless a `treeRenderer`
+ * (e.g. the json-render one) or a registry entry for `genui:tree` takes over.
+ */
+declare function GenuiTree({ root }: {
+    root?: GenerativeUIElement;
+}): React.JSX.Element | null;
+interface GenerativeUIScopeProps extends GenerativeUIOptions {
+    fallback?: GenerativeUIFallback;
+    loading?: ReactNode;
+    onError?: (error: unknown, item: GenerativeUIItem) => void;
+    children?: ReactNode;
+}
+/**
+ * The registry, catalog and fallbacks tree nodes render with. `<GenerativeUI>` provides it; wrap
+ * your own chrome in it when you draw `useGenerativeUI`'s `Component` yourself and it may be a tree.
+ */
+declare function GenerativeUIScope({ registry, catalog, resolveComponent, fallback, loading, onError, children, }: GenerativeUIScopeProps): React.JSX.Element;
+/** What `<GenuiProvider>` hands every `<GenerativeUI>` / `useGenerativeUI` below it. */
+interface GenuiProviderValue extends Partial<GenerativeUIOptions> {
+    fallback?: GenerativeUIFallback;
+    loading?: ReactNode;
+    onError?: (error: unknown, item: GenerativeUIItem) => void;
+}
+/** The enclosing `<GenuiProvider>`'s settings, or `null` outside one. */
+declare function useGenuiProvider(): GenuiProviderValue | null;
+interface GenuiProviderProps extends GenuiProviderValue {
+    children?: ReactNode;
+}
+/**
+ * Set generative UI up once, at the app root: the registry of your renderers, the catalog to
+ * validate against, a resolver for components the registry lacks, and what to draw when one does
+ * not render. Every `<GenerativeUI>` below reads it (its own props still win), and `MessageItem` /
+ * `MessageList` draw pushed components with it — no `renderUi` per message.
+ *
+ * ```tsx
+ * <GenuiProvider registry={registry} catalog={catalog} fallback={({ item }) => <Unknown name={item.component} />}>
+ *   <App />
+ * </GenuiProvider>
+ * ```
+ */
+declare function GenuiProvider({ registry, catalog, resolveComponent, treeRenderer, fallback, loading, onError, children, }: GenuiProviderProps): React.JSX.Element;
+/**
+ * The headless half of {@link GenerativeUI}: what to draw for one pushed component, or `null` when
+ * `part` is not one. Options default to the enclosing `<GenuiProvider>`'s.
+ */
+declare function useGenerativeUI(part: unknown, options?: Partial<GenerativeUIOptions>): GenerativeUIState | null;
+interface GenerativeUIProps extends Partial<GenerativeUIOptions> {
+    /** A transcript `ui` block, a `data-ui` message part, or a stored `{ id, component, props, version? }`. */
+    part: TranscriptUiBlock | GenerativeUIItem | unknown;
+    /** Drawn for an unknown component, invalid props, or a renderer that threw. Default: the provider's, else nothing. */
+    fallback?: GenerativeUIFallback;
+    /** Drawn while a resolver or an async validation is pending. Default: the provider's, else nothing. */
+    loading?: ReactNode;
+    /** A renderer threw (the item shows `fallback`). */
+    onError?: (error: unknown, item: GenerativeUIItem) => void;
+}
+/**
+ * Draws one server-pushed component with the app's own renderer. Headless: it adds no element and
+ * no style of its own — only what the registry's component renders (and whatever `fallback` /
+ * `loading` you pass). Everything but `part` defaults to the enclosing `<GenuiProvider>`.
+ *
+ * ```tsx
+ * <GenerativeUI part={block} />
+ * ```
+ */
+declare function GenerativeUI({ part, registry, catalog, resolveComponent, treeRenderer, fallback: ownFallback, loading: ownLoading, onError: ownOnError, }: GenerativeUIProps): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | React.JSX.Element | null | undefined;
+
+export { type GenerativeUIItem as G, type ResolveComponent as R, GENUI_TREE_COMPONENT as a, GenerativeUI as b, type GenerativeUIElement as c, type GenerativeUIFallback as d, type GenerativeUIOptions as e, type GenerativeUIProblem as f, type GenerativeUIProps as g, GenerativeUIScope as h, type GenerativeUIScopeProps as i, type GenerativeUIState as j, type GenuiCatalogLike as k, type GenuiIssueLike as l, GenuiProvider as m, type GenuiProviderProps as n, type GenuiProviderValue as o, type GenuiRegistry as p, type GenuiRenderer as q, GenuiTree as r, useGenuiProvider as s, useGenerativeUI as u };

package/dist/generative-ui-C53b3FoA.d.cts

@@ -0,0 +1,167 @@
+import * as React from 'react';
+import { ComponentType, ReactNode } from 'react';
+import { T as TranscriptUiBlock } from './model-gHqjNjLJ.cjs';
+
+/** The `ui` frame component a composed tree is pushed under (`GENUI_TREE_COMPONENT` of `@dudousxd/nestjs-agent-core/genui`). */
+declare const GENUI_TREE_COMPONENT = "genui:tree";
+/** One pushed component, normalized from whatever carried it (a transcript block, a `data-ui` part, a stored entry). */
+interface GenerativeUIItem {
+    id: string;
+    component: string;
+    props: Record<string, unknown>;
+    version: number | null;
+    toolCallId: string | null;
+}
+/** A node of a composed tree (`genui:tree` frames): `{ type, props, children? }`. */
+interface GenerativeUIElement {
+    type: string;
+    props: Record<string, unknown>;
+    children?: GenerativeUIElement[];
+}
+/**
+ * An app's renderer for one component: it receives the component's props spread, plus `children`
+ * when it is a layout node in a tree. Any React component — the library never styles anything.
+ */
+type GenuiRenderer<P = any> = ComponentType<P & {
+    children?: ReactNode;
+}>;
+/** Component name → the app's renderer. */
+type GenuiRegistry = Record<string, GenuiRenderer>;
+/**
+ * Resolve a component the registry does not have — typically a tenant's own component, fetched for
+ * the exact `version` a message was rendered with. Return `null`/`undefined` for "no such
+ * component". May be async; results are cached per resolver, name and version.
+ */
+type ResolveComponent = (name: string, version: number | null) => GenuiRenderer | null | undefined | Promise<GenuiRenderer | null | undefined>;
+interface GenuiIssueLike {
+    path: (string | number)[];
+    message: string;
+}
+type ValidationLike = {
+    ok: true;
+    value: Record<string, unknown>;
+} | {
+    ok: false;
+    issues: GenuiIssueLike[];
+};
+/**
+ * What the renderer needs from a catalog to validate props before drawing them. A `Catalog` from
+ * `@dudousxd/nestjs-agent-core/genui` satisfies it; declared structurally so any catalog-shaped
+ * object does too.
+ */
+interface GenuiCatalogLike {
+    has(name: string): boolean;
+    validate(name: string, props: unknown): Promise<ValidationLike>;
+    validateSync?(name: string, props: unknown): ValidationLike | undefined;
+}
+interface GenerativeUIOptions {
+    registry: GenuiRegistry;
+    /** Validate props against it before rendering. Components the catalog does not know render unvalidated. */
+    catalog?: GenuiCatalogLike;
+    resolveComponent?: ResolveComponent;
+    /**
+     * Draws a composed tree frame (`genui:tree`) whole — e.g. through json-render (see the
+     * `/genui/json-render` subpath's `GenuiProvider`). Omitted → trees render node by node through
+     * `registry`.
+     */
+    treeRenderer?: GenuiRenderer<{
+        root?: GenerativeUIElement;
+    }>;
+}
+/** Why an item did not render. */
+type GenerativeUIProblem = {
+    reason: 'unknown';
+    item: GenerativeUIItem;
+} | {
+    reason: 'invalid';
+    item: GenerativeUIItem;
+    issues: GenuiIssueLike[];
+} | {
+    reason: 'error';
+    item: GenerativeUIItem;
+    error: unknown;
+};
+type GenerativeUIState = {
+    status: 'ready';
+    item: GenerativeUIItem;
+    Component: GenuiRenderer;
+    props: Record<string, unknown>;
+} | {
+    status: 'loading';
+    item: GenerativeUIItem;
+} | ({
+    status: 'problem';
+} & GenerativeUIProblem);
+
+/** What to draw instead of a component that did not render. Default: nothing. */
+type GenerativeUIFallback = ReactNode | ((problem: GenerativeUIProblem) => ReactNode);
+/**
+ * Renders a `genui:tree` frame's `{ root }` node by node through the same registry, catalog and
+ * resolver as top-level components. Used automatically for tree frames unless a `treeRenderer`
+ * (e.g. the json-render one) or a registry entry for `genui:tree` takes over.
+ */
+declare function GenuiTree({ root }: {
+    root?: GenerativeUIElement;
+}): React.JSX.Element | null;
+interface GenerativeUIScopeProps extends GenerativeUIOptions {
+    fallback?: GenerativeUIFallback;
+    loading?: ReactNode;
+    onError?: (error: unknown, item: GenerativeUIItem) => void;
+    children?: ReactNode;
+}
+/**
+ * The registry, catalog and fallbacks tree nodes render with. `<GenerativeUI>` provides it; wrap
+ * your own chrome in it when you draw `useGenerativeUI`'s `Component` yourself and it may be a tree.
+ */
+declare function GenerativeUIScope({ registry, catalog, resolveComponent, fallback, loading, onError, children, }: GenerativeUIScopeProps): React.JSX.Element;
+/** What `<GenuiProvider>` hands every `<GenerativeUI>` / `useGenerativeUI` below it. */
+interface GenuiProviderValue extends Partial<GenerativeUIOptions> {
+    fallback?: GenerativeUIFallback;
+    loading?: ReactNode;
+    onError?: (error: unknown, item: GenerativeUIItem) => void;
+}
+/** The enclosing `<GenuiProvider>`'s settings, or `null` outside one. */
+declare function useGenuiProvider(): GenuiProviderValue | null;
+interface GenuiProviderProps extends GenuiProviderValue {
+    children?: ReactNode;
+}
+/**
+ * Set generative UI up once, at the app root: the registry of your renderers, the catalog to
+ * validate against, a resolver for components the registry lacks, and what to draw when one does
+ * not render. Every `<GenerativeUI>` below reads it (its own props still win), and `MessageItem` /
+ * `MessageList` draw pushed components with it — no `renderUi` per message.
+ *
+ * ```tsx
+ * <GenuiProvider registry={registry} catalog={catalog} fallback={({ item }) => <Unknown name={item.component} />}>
+ *   <App />
+ * </GenuiProvider>
+ * ```
+ */
+declare function GenuiProvider({ registry, catalog, resolveComponent, treeRenderer, fallback, loading, onError, children, }: GenuiProviderProps): React.JSX.Element;
+/**
+ * The headless half of {@link GenerativeUI}: what to draw for one pushed component, or `null` when
+ * `part` is not one. Options default to the enclosing `<GenuiProvider>`'s.
+ */
+declare function useGenerativeUI(part: unknown, options?: Partial<GenerativeUIOptions>): GenerativeUIState | null;
+interface GenerativeUIProps extends Partial<GenerativeUIOptions> {
+    /** A transcript `ui` block, a `data-ui` message part, or a stored `{ id, component, props, version? }`. */
+    part: TranscriptUiBlock | GenerativeUIItem | unknown;
+    /** Drawn for an unknown component, invalid props, or a renderer that threw. Default: the provider's, else nothing. */
+    fallback?: GenerativeUIFallback;
+    /** Drawn while a resolver or an async validation is pending. Default: the provider's, else nothing. */
+    loading?: ReactNode;
+    /** A renderer threw (the item shows `fallback`). */
+    onError?: (error: unknown, item: GenerativeUIItem) => void;
+}
+/**
+ * Draws one server-pushed component with the app's own renderer. Headless: it adds no element and
+ * no style of its own — only what the registry's component renders (and whatever `fallback` /
+ * `loading` you pass). Everything but `part` defaults to the enclosing `<GenuiProvider>`.
+ *
+ * ```tsx
+ * <GenerativeUI part={block} />
+ * ```
+ */
+declare function GenerativeUI({ part, registry, catalog, resolveComponent, treeRenderer, fallback: ownFallback, loading: ownLoading, onError: ownOnError, }: GenerativeUIProps): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | React.JSX.Element | null | undefined;
+
+export { type GenerativeUIItem as G, type ResolveComponent as R, GENUI_TREE_COMPONENT as a, GenerativeUI as b, type GenerativeUIElement as c, type GenerativeUIFallback as d, type GenerativeUIOptions as e, type GenerativeUIProblem as f, type GenerativeUIProps as g, GenerativeUIScope as h, type GenerativeUIScopeProps as i, type GenerativeUIState as j, type GenuiCatalogLike as k, type GenuiIssueLike as l, GenuiProvider as m, type GenuiProviderProps as n, type GenuiProviderValue as o, type GenuiRegistry as p, type GenuiRenderer as q, GenuiTree as r, useGenuiProvider as s, useGenerativeUI as u };