@dudousxd/nestjs-agent-core 0.44.0 → 0.45.0

package/dist/genui/index.d.cts

@@ -1,8 +1,8 @@
-import { a as Catalog, J as JsonSchema, G as GenuiValidation, b as GenuiIssue } from '../catalog-G8usJpx5.cjs';
-export { A as AjvLike, c as COMPONENT_NAME, d as CatalogOptions, C as ComponentDefinition, e as JsonSchemaValidator, P as PropsSchema, f as ajvValidator, g as builtinJsonSchemaValidator, h as defineCatalog, i as defineComponent, j as flatComponents, k as formatIssues, l as isStandardSchema, t as toJsonSchema, m as toSnakeCase, n as toolNameFor, v as validateProps, o as validatePropsSync } from '../catalog-G8usJpx5.cjs';
+import { a as Catalog, J as JsonSchema, G as GenuiValidation, b as GenuiStreaming, c as GenuiIssue } from '../catalog-BUmTnAqU.cjs';
+export { A as AjvLike, d as COMPONENT_NAME, e as CatalogOptions, C as ComponentDefinition, f as JsonSchemaValidator, P as PropsSchema, g as ajvValidator, h as builtinJsonSchemaValidator, i as defineCatalog, j as defineComponent, k as flatComponents, l as formatIssues, m as isStandardSchema, t as toJsonSchema, n as toSnakeCase, o as toolNameFor, v as validateProps, p as validatePropsSync } from '../catalog-BUmTnAqU.cjs';
+import { P as PartialToolInput, a as Actor, T as ToolSpec, b as ToolHandler, c as ToolPresentation } from '../stream-events-qB6NOOvn.cjs';
+export { C as ChartProps, d as ComponentFactory, e as ComponentManifest, f as ComponentPresentation, g as ComponentRegistry, h as ComponentRenderer, i as PreparedUiEmission, j as TableCell, k as TableProps, U as UiCapabilities, l as chart, m as createComponent, n as createComponentRegistry, o as negotiateCatalog, p as prepareUiEmission, s as snapshotComponentPresentation, t as table, v as validatePresentationBatch, q as validateUiCapabilities } from '../stream-events-qB6NOOvn.cjs';
 import { StandardSchemaV1, StandardJSONSchemaV1 } from '@standard-schema/spec';
-import { a as Actor, T as ToolSpec, b as ToolHandler, c as ToolPresentation } from '../stream-events-BfxJAckJ.cjs';
-export { C as ChartProps, d as ComponentFactory, e as ComponentManifest, f as ComponentPresentation, g as ComponentRegistry, h as ComponentRenderer, P as PreparedUiEmission, i as TableCell, j as TableProps, U as UiCapabilities, k as chart, l as createComponent, m as createComponentRegistry, n as negotiateCatalog, p as prepareUiEmission, s as snapshotComponentPresentation, t as table, v as validatePresentationBatch, o as validateUiCapabilities } from '../stream-events-BfxJAckJ.cjs';
 
 /**
  * One node of a composed UI: a catalog component, its props, and — for components declared with
@@ -40,12 +40,33 @@ interface TreeLimits {
  */
 declare function validateTree(catalog: Catalog, tree: unknown, limits?: TreeLimits, phase?: 'input' | 'output'): Promise<GenuiValidation<GenuiElement>>;
 /**
- * The JSON Schema of a tree-mode tool's input: a recursive `{ type, props, children? }` node whose
- * `type` is one of the catalog's model-facing component names. Per-component props are described
- * to the model in the tool description (see `catalogToModelText`) and checked by
- * {@link validateTree}, which keeps this schema small enough for every provider.
+ * How exactly a tree-mode tool's input is described to the model ({@link treeJsonSchema}):
+ *
+ * - `'strict'` (default): every node's `props` is its component's own props schema, and `children`
+ *   is a discriminated union by `type` over the components — each variant with its exact props, and
+ *   `children` only on components that take them (recursive, through `$defs` / `$ref`).
+ * - `'loose'`: one `{ type, props: object, children }` node shape — for a provider that refuses
+ *   `$ref` in tool parameters. The props are then only described in the tool's text.
+ */
+type TreeSchemaMode = 'strict' | 'loose';
+/**
+ * The JSON Schema of a tree-mode tool's input. Whatever it says, {@link validateTree} remains the
+ * check every call goes through: a provider is free to ignore the schema.
+ *
+ * Strict (the default), it is shaped for what the providers accept in tool parameters:
+ *  - the root is a plain `type: 'object'` — OpenAI and Anthropic both refuse a union at the top
+ *    level of a tool's parameters — whose `type` lists every component and whose `props` is any of
+ *    their props schemas;
+ *  - every `children` item is `{ $ref: '#/$defs/node' }`, an `anyOf` of one variant per component
+ *    (`type` a one-value `enum`, `props` that component's schema, `children` only where taken,
+ *    `additionalProperties: false`);
+ *  - a component whose props schema is not self-contained (it carries its own `$ref`, `$defs` or
+ *    `definitions`, as a recursive Zod schema does) is described as `{ type: 'object' }`, since its
+ *    references would not resolve once embedded; `$schema` is dropped.
  */
-declare function treeJsonSchema(catalog: Catalog): JsonSchema;
+declare function treeJsonSchema(catalog: Catalog, options?: {
+    schema?: TreeSchemaMode;
+}): JsonSchema;
 /** A json-render flat spec: `{ root, elements: { [id]: { type, props, children: id[] } } }`. */
 interface FlatSpec {
     root: string;
@@ -58,6 +79,47 @@ interface FlatSpec {
 /** Convert a tree to a json-render flat spec (ids are `el-0`, `el-1`, … in depth-first order). */
 declare function treeToFlatSpec(root: GenuiElement): FlatSpec;
 
+/**
+ * One node of a tree the model is still writing — what a partial `genui:tree` frame carries.
+ *
+ * `id` is the node's position: `root`, then `<parent id>.<index>` (`root.1.0`). It never changes as
+ * the tree grows (a model only ever appends), and the final tree's nodes are addressed by the same
+ * rule, so a renderer keyed on it keeps every node mounted from the first preview to the final frame.
+ */
+interface GenuiPartialElement {
+    id: string;
+    type: string;
+    props: Record<string, unknown>;
+    children?: GenuiPartialElement[];
+    /** The model has not finished writing this node: its props (or children) may still grow. */
+    incomplete?: true;
+    /**
+     * The node's component streams `complete`: its props and children are held back until its whole
+     * subtree has arrived (`props` is `{}`). Draw a placeholder, never the component.
+     */
+    held?: true;
+}
+/** The id of the child at `index` of the node `parentId` (the root is `root`). */
+declare function treeNodeId(parentId: string, index: number): string;
+interface PartialTreeOptions {
+    /** How a component without its own `streaming` appears. Default `'complete'`. */
+    streaming?: GenuiStreaming;
+    limits?: TreeLimits;
+}
+/**
+ * The part of a streaming `ui__render` input worth drawing: every node whose `type` has fully
+ * arrived and names a component of `catalog` (the negotiated one: what this client draws), with its
+ * props so far — unvalidated, and flagged `incomplete` while still open. A node whose component
+ * streams `complete` is a `held` placeholder until it closes.
+ *
+ * `{ root: null }` while nothing is drawable yet. `null` when the input can no longer become a tree
+ * this client draws (an unknown or undrawable component, children where none are taken, past the
+ * size limits): the preview stops there, and the final push decides what is shown.
+ */
+declare function partialTree(catalog: Catalog, input: PartialToolInput, options?: PartialTreeOptions): {
+    root: GenuiPartialElement | null;
+} | null;
+
 /**
  * Plain text (Slack mrkdwn compatible) for a pushed component: its definition's `fallbackText`, or
  * the props as a JSON block when the catalog has no text for it. A tree frame
@@ -117,12 +179,20 @@ interface GenuiCatalogScope {
 type ResolveGenuiCatalog = (scope: GenuiCatalogScope) => Catalog | Promise<Catalog>;
 interface GenuiToolsOptions {
     /**
-     * `per-component` (default): one tool per model-facing component, `ui__show_<snake>`, whose input
-     * IS the component's props — except layout components (`children: true`), which a flat input
-     * cannot fill. `tree`: a single tool whose input is a nested
-     * `{ type, props, children }` tree composed from the catalog (json-render's nested shape).
+     * `tree` (default): a single `ui__render` tool whose input is a nested `{ type, props, children }`
+     * tree composed from the catalog (json-render's nested shape). A tree of one component with no
+     * children is pushed as that component, exactly as its `ui__show_*` tool would push it.
+     * `per-component`: one tool per model-facing component, `ui__show_<snake>`, whose input IS the
+     * component's props — for small models, or when each tool should carry its exact schema. Layouts
+     * (`children: true`) get none: a flat input cannot fill them.
      */
     mode?: 'per-component' | 'tree';
+    /**
+     * How the tree tool's input schema describes the nodes (see {@link treeJsonSchema}): `'strict'`
+     * (default) — a recursive union by `type` with each component's exact props; `'loose'` — one
+     * generic node shape, for a provider that refuses `$ref` in tool parameters.
+     */
+    treeSchema?: TreeSchemaMode;
     /**
      * The model's turn ends once a genui call succeeds — no further model call to narrate what the UI
      * already shows. Stamped as `spec.terminal`.
@@ -136,6 +206,21 @@ interface GenuiToolsOptions {
     treeInstructions?: string;
     /** Size limits for `tree`. */
     treeLimits?: TreeLimits;
+    /**
+     * Tree mode: whether the layout is drawn WHILE the model writes it.
+     *
+     * - `'complete'` (default): nothing is drawn until the call has run; then the validated tree
+     *   appears whole.
+     * - `'partial'`: the server parses the streaming `ui__render` arguments and pushes the tree so far
+     *   as `partial` `ui` frames under the id the final push replaces — throttled, unvalidated, never
+     *   persisted, never sent to a text channel. Nodes still being written are flagged `incomplete`; a
+     *   component declared `streaming: 'complete'` is a `held` placeholder until its subtree closes.
+     *
+     * A component's own {@link ComponentDefinition.streaming} overrides this per component.
+     */
+    streaming?: GenuiStreaming;
+    /** Least time between two partial tree frames of one call, in ms. Default 100. */
+    streamingThrottleMs?: number;
     /**
      * Also offer ONE generic tool taking `{ component, props }`, validated against the (resolved)
      * catalog — how a model reaches components that only exist per request (a tenant's own), which a
@@ -175,4 +260,4 @@ type JsonStandardSchema = StandardSchemaV1 & StandardJSONSchemaV1;
  */
 declare function jsonStandardSchema(schema: JsonSchema, validate: (value: unknown) => GenuiIssue[]): JsonStandardSchema;
 
-export { Catalog, type CatalogTextOptions, type FlatSpec, GENUI_SHOW_TOOL, GENUI_TREE_COMPONENT, type GenuiCatalogScope, type GenuiElement, GenuiIssue, type GenuiTool, type GenuiToolOutput, type GenuiToolsOptions, type GenuiTreeProps, GenuiValidation, JsonSchema, type ResolveGenuiCatalog, type TreeLimits, catalogToModelText, componentToText, fillTemplate, genuiTools, getPath, jsonStandardSchema, showToolJsonSchema, summarizeSchema, treeJsonSchema, treeToFlatSpec, treeToText, validateTree };
+export { Catalog, type CatalogTextOptions, type FlatSpec, GENUI_SHOW_TOOL, GENUI_TREE_COMPONENT, type GenuiCatalogScope, type GenuiElement, GenuiIssue, type GenuiPartialElement, GenuiStreaming, type GenuiTool, type GenuiToolOutput, type GenuiToolsOptions, type GenuiTreeProps, GenuiValidation, JsonSchema, type PartialTreeOptions, type ResolveGenuiCatalog, type TreeLimits, type TreeSchemaMode, catalogToModelText, componentToText, fillTemplate, genuiTools, getPath, jsonStandardSchema, partialTree, showToolJsonSchema, summarizeSchema, treeJsonSchema, treeNodeId, treeToFlatSpec, treeToText, validateTree };

package/dist/genui/index.d.ts

@@ -1,8 +1,8 @@
-import { a as Catalog, J as JsonSchema, G as GenuiValidation, b as GenuiIssue } from '../catalog-G8usJpx5.js';
-export { A as AjvLike, c as COMPONENT_NAME, d as CatalogOptions, C as ComponentDefinition, e as JsonSchemaValidator, P as PropsSchema, f as ajvValidator, g as builtinJsonSchemaValidator, h as defineCatalog, i as defineComponent, j as flatComponents, k as formatIssues, l as isStandardSchema, t as toJsonSchema, m as toSnakeCase, n as toolNameFor, v as validateProps, o as validatePropsSync } from '../catalog-G8usJpx5.js';
+import { a as Catalog, J as JsonSchema, G as GenuiValidation, b as GenuiStreaming, c as GenuiIssue } from '../catalog-BUmTnAqU.js';
+export { A as AjvLike, d as COMPONENT_NAME, e as CatalogOptions, C as ComponentDefinition, f as JsonSchemaValidator, P as PropsSchema, g as ajvValidator, h as builtinJsonSchemaValidator, i as defineCatalog, j as defineComponent, k as flatComponents, l as formatIssues, m as isStandardSchema, t as toJsonSchema, n as toSnakeCase, o as toolNameFor, v as validateProps, p as validatePropsSync } from '../catalog-BUmTnAqU.js';
+import { P as PartialToolInput, a as Actor, T as ToolSpec, b as ToolHandler, c as ToolPresentation } from '../stream-events-CqCqYjJw.js';
+export { C as ChartProps, d as ComponentFactory, e as ComponentManifest, f as ComponentPresentation, g as ComponentRegistry, h as ComponentRenderer, i as PreparedUiEmission, j as TableCell, k as TableProps, U as UiCapabilities, l as chart, m as createComponent, n as createComponentRegistry, o as negotiateCatalog, p as prepareUiEmission, s as snapshotComponentPresentation, t as table, v as validatePresentationBatch, q as validateUiCapabilities } from '../stream-events-CqCqYjJw.js';
 import { StandardSchemaV1, StandardJSONSchemaV1 } from '@standard-schema/spec';
-import { a as Actor, T as ToolSpec, b as ToolHandler, c as ToolPresentation } from '../stream-events-DFa2Do42.js';
-export { C as ChartProps, d as ComponentFactory, e as ComponentManifest, f as ComponentPresentation, g as ComponentRegistry, h as ComponentRenderer, P as PreparedUiEmission, i as TableCell, j as TableProps, U as UiCapabilities, k as chart, l as createComponent, m as createComponentRegistry, n as negotiateCatalog, p as prepareUiEmission, s as snapshotComponentPresentation, t as table, v as validatePresentationBatch, o as validateUiCapabilities } from '../stream-events-DFa2Do42.js';
 
 /**
  * One node of a composed UI: a catalog component, its props, and — for components declared with
@@ -40,12 +40,33 @@ interface TreeLimits {
  */
 declare function validateTree(catalog: Catalog, tree: unknown, limits?: TreeLimits, phase?: 'input' | 'output'): Promise<GenuiValidation<GenuiElement>>;
 /**
- * The JSON Schema of a tree-mode tool's input: a recursive `{ type, props, children? }` node whose
- * `type` is one of the catalog's model-facing component names. Per-component props are described
- * to the model in the tool description (see `catalogToModelText`) and checked by
- * {@link validateTree}, which keeps this schema small enough for every provider.
+ * How exactly a tree-mode tool's input is described to the model ({@link treeJsonSchema}):
+ *
+ * - `'strict'` (default): every node's `props` is its component's own props schema, and `children`
+ *   is a discriminated union by `type` over the components — each variant with its exact props, and
+ *   `children` only on components that take them (recursive, through `$defs` / `$ref`).
+ * - `'loose'`: one `{ type, props: object, children }` node shape — for a provider that refuses
+ *   `$ref` in tool parameters. The props are then only described in the tool's text.
+ */
+type TreeSchemaMode = 'strict' | 'loose';
+/**
+ * The JSON Schema of a tree-mode tool's input. Whatever it says, {@link validateTree} remains the
+ * check every call goes through: a provider is free to ignore the schema.
+ *
+ * Strict (the default), it is shaped for what the providers accept in tool parameters:
+ *  - the root is a plain `type: 'object'` — OpenAI and Anthropic both refuse a union at the top
+ *    level of a tool's parameters — whose `type` lists every component and whose `props` is any of
+ *    their props schemas;
+ *  - every `children` item is `{ $ref: '#/$defs/node' }`, an `anyOf` of one variant per component
+ *    (`type` a one-value `enum`, `props` that component's schema, `children` only where taken,
+ *    `additionalProperties: false`);
+ *  - a component whose props schema is not self-contained (it carries its own `$ref`, `$defs` or
+ *    `definitions`, as a recursive Zod schema does) is described as `{ type: 'object' }`, since its
+ *    references would not resolve once embedded; `$schema` is dropped.
  */
-declare function treeJsonSchema(catalog: Catalog): JsonSchema;
+declare function treeJsonSchema(catalog: Catalog, options?: {
+    schema?: TreeSchemaMode;
+}): JsonSchema;
 /** A json-render flat spec: `{ root, elements: { [id]: { type, props, children: id[] } } }`. */
 interface FlatSpec {
     root: string;
@@ -58,6 +79,47 @@ interface FlatSpec {
 /** Convert a tree to a json-render flat spec (ids are `el-0`, `el-1`, … in depth-first order). */
 declare function treeToFlatSpec(root: GenuiElement): FlatSpec;
 
+/**
+ * One node of a tree the model is still writing — what a partial `genui:tree` frame carries.
+ *
+ * `id` is the node's position: `root`, then `<parent id>.<index>` (`root.1.0`). It never changes as
+ * the tree grows (a model only ever appends), and the final tree's nodes are addressed by the same
+ * rule, so a renderer keyed on it keeps every node mounted from the first preview to the final frame.
+ */
+interface GenuiPartialElement {
+    id: string;
+    type: string;
+    props: Record<string, unknown>;
+    children?: GenuiPartialElement[];
+    /** The model has not finished writing this node: its props (or children) may still grow. */
+    incomplete?: true;
+    /**
+     * The node's component streams `complete`: its props and children are held back until its whole
+     * subtree has arrived (`props` is `{}`). Draw a placeholder, never the component.
+     */
+    held?: true;
+}
+/** The id of the child at `index` of the node `parentId` (the root is `root`). */
+declare function treeNodeId(parentId: string, index: number): string;
+interface PartialTreeOptions {
+    /** How a component without its own `streaming` appears. Default `'complete'`. */
+    streaming?: GenuiStreaming;
+    limits?: TreeLimits;
+}
+/**
+ * The part of a streaming `ui__render` input worth drawing: every node whose `type` has fully
+ * arrived and names a component of `catalog` (the negotiated one: what this client draws), with its
+ * props so far — unvalidated, and flagged `incomplete` while still open. A node whose component
+ * streams `complete` is a `held` placeholder until it closes.
+ *
+ * `{ root: null }` while nothing is drawable yet. `null` when the input can no longer become a tree
+ * this client draws (an unknown or undrawable component, children where none are taken, past the
+ * size limits): the preview stops there, and the final push decides what is shown.
+ */
+declare function partialTree(catalog: Catalog, input: PartialToolInput, options?: PartialTreeOptions): {
+    root: GenuiPartialElement | null;
+} | null;
+
 /**
  * Plain text (Slack mrkdwn compatible) for a pushed component: its definition's `fallbackText`, or
  * the props as a JSON block when the catalog has no text for it. A tree frame
@@ -117,12 +179,20 @@ interface GenuiCatalogScope {
 type ResolveGenuiCatalog = (scope: GenuiCatalogScope) => Catalog | Promise<Catalog>;
 interface GenuiToolsOptions {
     /**
-     * `per-component` (default): one tool per model-facing component, `ui__show_<snake>`, whose input
-     * IS the component's props — except layout components (`children: true`), which a flat input
-     * cannot fill. `tree`: a single tool whose input is a nested
-     * `{ type, props, children }` tree composed from the catalog (json-render's nested shape).
+     * `tree` (default): a single `ui__render` tool whose input is a nested `{ type, props, children }`
+     * tree composed from the catalog (json-render's nested shape). A tree of one component with no
+     * children is pushed as that component, exactly as its `ui__show_*` tool would push it.
+     * `per-component`: one tool per model-facing component, `ui__show_<snake>`, whose input IS the
+     * component's props — for small models, or when each tool should carry its exact schema. Layouts
+     * (`children: true`) get none: a flat input cannot fill them.
      */
     mode?: 'per-component' | 'tree';
+    /**
+     * How the tree tool's input schema describes the nodes (see {@link treeJsonSchema}): `'strict'`
+     * (default) — a recursive union by `type` with each component's exact props; `'loose'` — one
+     * generic node shape, for a provider that refuses `$ref` in tool parameters.
+     */
+    treeSchema?: TreeSchemaMode;
     /**
      * The model's turn ends once a genui call succeeds — no further model call to narrate what the UI
      * already shows. Stamped as `spec.terminal`.
@@ -136,6 +206,21 @@ interface GenuiToolsOptions {
     treeInstructions?: string;
     /** Size limits for `tree`. */
     treeLimits?: TreeLimits;
+    /**
+     * Tree mode: whether the layout is drawn WHILE the model writes it.
+     *
+     * - `'complete'` (default): nothing is drawn until the call has run; then the validated tree
+     *   appears whole.
+     * - `'partial'`: the server parses the streaming `ui__render` arguments and pushes the tree so far
+     *   as `partial` `ui` frames under the id the final push replaces — throttled, unvalidated, never
+     *   persisted, never sent to a text channel. Nodes still being written are flagged `incomplete`; a
+     *   component declared `streaming: 'complete'` is a `held` placeholder until its subtree closes.
+     *
+     * A component's own {@link ComponentDefinition.streaming} overrides this per component.
+     */
+    streaming?: GenuiStreaming;
+    /** Least time between two partial tree frames of one call, in ms. Default 100. */
+    streamingThrottleMs?: number;
     /**
      * Also offer ONE generic tool taking `{ component, props }`, validated against the (resolved)
      * catalog — how a model reaches components that only exist per request (a tenant's own), which a
@@ -175,4 +260,4 @@ type JsonStandardSchema = StandardSchemaV1 & StandardJSONSchemaV1;
  */
 declare function jsonStandardSchema(schema: JsonSchema, validate: (value: unknown) => GenuiIssue[]): JsonStandardSchema;
 
-export { Catalog, type CatalogTextOptions, type FlatSpec, GENUI_SHOW_TOOL, GENUI_TREE_COMPONENT, type GenuiCatalogScope, type GenuiElement, GenuiIssue, type GenuiTool, type GenuiToolOutput, type GenuiToolsOptions, type GenuiTreeProps, GenuiValidation, JsonSchema, type ResolveGenuiCatalog, type TreeLimits, catalogToModelText, componentToText, fillTemplate, genuiTools, getPath, jsonStandardSchema, showToolJsonSchema, summarizeSchema, treeJsonSchema, treeToFlatSpec, treeToText, validateTree };
+export { Catalog, type CatalogTextOptions, type FlatSpec, GENUI_SHOW_TOOL, GENUI_TREE_COMPONENT, type GenuiCatalogScope, type GenuiElement, GenuiIssue, type GenuiPartialElement, GenuiStreaming, type GenuiTool, type GenuiToolOutput, type GenuiToolsOptions, type GenuiTreeProps, GenuiValidation, JsonSchema, type PartialTreeOptions, type ResolveGenuiCatalog, type TreeLimits, type TreeSchemaMode, catalogToModelText, componentToText, fillTemplate, genuiTools, getPath, jsonStandardSchema, partialTree, showToolJsonSchema, summarizeSchema, treeJsonSchema, treeNodeId, treeToFlatSpec, treeToText, validateTree };

package/dist/genui/index.js

@@ -355,6 +355,7 @@ function defineComponent(definition) {
   }
   if (definition.version !== void 0 && (!Number.isSafeInteger(definition.version) || definition.version <= 0)) throw new RangeError("genui: component version must be a positive safe integer");
   if (definition.fallbackText !== void 0 && typeof definition.fallbackText !== "function") throw new TypeError("genui: fallbackText must be a function");
+  if (definition.streaming !== void 0 && definition.streaming !== "partial" && definition.streaming !== "complete") throw new TypeError("genui: streaming must be 'partial' or 'complete'");
   return definition;
 }
 __name(defineComponent, "defineComponent");
@@ -439,6 +440,97 @@ function toolNameFor(component, prefix = "ui__show_") {
 }
 __name(toolNameFor, "toolNameFor");
 
+// src/genui/progressive.ts
+function treeNodeId(parentId, index) {
+  return `${parentId}.${index}`;
+}
+__name(treeNodeId, "treeNodeId");
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+__name(isRecord, "isRecord");
+function partialTree(catalog, input, options = {}) {
+  const maxDepth = options.limits?.maxDepth ?? 12;
+  const maxNodes = options.limits?.maxNodes ?? 200;
+  const fallback = options.streaming ?? "complete";
+  let nodes = 0;
+  let broken = false;
+  const visit = /* @__PURE__ */ __name((value, id, depth) => {
+    if (broken) return void 0;
+    if (!isRecord(value)) {
+      if (value !== void 0) broken = true;
+      return void 0;
+    }
+    const open = input.isOpen(value);
+    const type = value.type;
+    if (typeof type !== "string" || open && input.pendingMember(value) === "type") {
+      if (!open) broken = true;
+      return void 0;
+    }
+    const definition = catalog.get(type);
+    nodes += 1;
+    if (definition === void 0 || definition.internal === true || nodes > maxNodes || depth > maxDepth) {
+      broken = true;
+      return void 0;
+    }
+    const mode = definition.streaming ?? fallback;
+    if (mode === "complete") {
+      const checked = open ? void 0 : validatePropsSync(definition.props, value.props ?? {}, catalog.validator);
+      if (checked === void 0 || !checked.ok) {
+        return {
+          id,
+          type,
+          props: {},
+          incomplete: true,
+          held: true
+        };
+      }
+      const children2 = childrenOf(value, id, depth, definition.children === true);
+      return {
+        id,
+        type,
+        props: checked.value,
+        ...children2 !== void 0 && children2.length > 0 ? {
+          children: children2
+        } : {}
+      };
+    }
+    const props = isRecord(value.props) ? value.props : {};
+    const children = childrenOf(value, id, depth, definition.children === true);
+    return {
+      id,
+      type,
+      props,
+      ...children !== void 0 && children.length > 0 ? {
+        children
+      } : {},
+      ...open ? {
+        incomplete: true
+      } : {}
+    };
+  }, "visit");
+  const childrenOf = /* @__PURE__ */ __name((value, id, depth, takesChildren) => {
+    const raw = value.children;
+    if (!Array.isArray(raw)) return void 0;
+    if (raw.length > 0 && !takesChildren) {
+      broken = true;
+      return void 0;
+    }
+    const children = [];
+    for (const [index, child] of raw.entries()) {
+      const next = visit(child, treeNodeId(id, index), depth + 1);
+      if (next !== void 0) children.push(next);
+    }
+    return children;
+  }, "childrenOf");
+  const root = visit(input.value, "root", 1);
+  if (broken) return null;
+  return {
+    root: root ?? null
+  };
+}
+__name(partialTree, "partialTree");
+
 // src/genui/tree.ts
 var GENUI_TREE_COMPONENT = "genui:tree";
 async function validateTree(catalog, tree, limits = {}, phase = "output") {
@@ -571,34 +663,120 @@ async function validateTree(catalog, tree, limits = {}, phase = "output") {
   };
 }
 __name(validateTree, "validateTree");
-function treeJsonSchema(catalog) {
+function treeJsonSchema(catalog, options = {}) {
+  const components = catalog.modelComponents();
+  const names = components.map((component) => component.name);
+  if (options.schema === "loose") {
+    return {
+      type: "object",
+      properties: {
+        type: {
+          type: "string",
+          enum: names,
+          description: "Component name from the catalog"
+        },
+        props: {
+          type: "object",
+          description: "The component's props, as the catalog describes them"
+        },
+        children: {
+          type: "array",
+          items: {
+            $ref: "#"
+          },
+          description: "Nested elements, only for components that take children. A literal JSON array, never a JSON-stringified one."
+        }
+      },
+      required: [
+        "type",
+        "props"
+      ]
+    };
+  }
+  const defs = {};
+  const childrenSchema = {
+    type: "array",
+    items: {
+      $ref: "#/$defs/node"
+    },
+    description: "Nested elements. A literal JSON array, never a JSON-stringified one."
+  };
+  for (const component of components) {
+    defs[`props_${component.name}`] = embeddableProps(toJsonSchema(component.props));
+    defs[`node_${component.name}`] = {
+      type: "object",
+      properties: {
+        type: {
+          type: "string",
+          enum: [
+            component.name
+          ]
+        },
+        props: {
+          $ref: `#/$defs/props_${component.name}`
+        },
+        ...component.children === true ? {
+          children: childrenSchema
+        } : {}
+      },
+      required: [
+        "type",
+        "props"
+      ],
+      additionalProperties: false
+    };
+  }
+  defs.node = {
+    anyOf: components.map((component) => ({
+      $ref: `#/$defs/node_${component.name}`
+    }))
+  };
   return {
     type: "object",
     properties: {
       type: {
         type: "string",
-        enum: catalog.modelComponents().map((component) => component.name),
-        description: "Component name from the catalog"
+        enum: names,
+        description: "Component name from the catalog. A single component (no children) is a valid tree."
       },
       props: {
-        type: "object",
-        description: "The component's props, as the catalog describes them"
+        description: "The component's props: the schema of the component named by `type`",
+        anyOf: components.map((component) => ({
+          $ref: `#/$defs/props_${component.name}`
+        }))
       },
       children: {
-        type: "array",
-        items: {
-          $ref: "#"
-        },
+        ...childrenSchema,
         description: "Nested elements, only for components that take children. A literal JSON array, never a JSON-stringified one."
       }
     },
     required: [
       "type",
       "props"
-    ]
+    ],
+    additionalProperties: false,
+    $defs: defs
   };
 }
 __name(treeJsonSchema, "treeJsonSchema");
+function embeddableProps(schema) {
+  if (schema === void 0 || typeof schema !== "object" || schema === null) {
+    return {
+      type: "object"
+    };
+  }
+  const references = /* @__PURE__ */ __name((value) => {
+    if (Array.isArray(value)) return value.some(references);
+    if (typeof value !== "object" || value === null) return false;
+    return Object.entries(value).some(([key, nested]) => key === "$ref" || key === "$defs" || key === "definitions" || references(nested));
+  }, "references");
+  if (references(schema)) return {
+    type: "object"
+  };
+  const { $schema: _schema, ...rest } = schema;
+  return rest;
+}
+__name(embeddableProps, "embeddableProps");
 function treeToFlatSpec(root) {
   const elements = {};
   let next = 0;
@@ -869,9 +1047,9 @@ __name(prepareUiEmission, "prepareUiEmission");
 // src/genui/tools.ts
 var GENUI_SHOW_TOOL = "ui__show";
 function genuiTools(catalog, options = {}) {
-  const tools = options.mode === "tree" ? [
+  const tools = options.mode === "per-component" ? flatComponents(catalog).map((component) => componentTool(catalog, component, options)) : [
     treeTool(catalog, options)
-  ] : flatComponents(catalog).map((component) => componentTool(catalog, component, options));
+  ];
   if (options.showTool !== void 0 && options.showTool !== false) {
     tools.push(showTool(catalog, options));
   }
@@ -982,6 +1160,9 @@ function treeTool(catalog, options) {
     })
   ].join("\n"), "describeFor");
   const dynamic = options.resolveCatalog !== void 0;
+  const treeSchemaOptions = options.treeSchema !== void 0 ? {
+    schema: options.treeSchema
+  } : {};
   const handler = {
     async execute(input, ctx) {
       const resolved = await catalogFor(catalog, options, scopeOf(ctx));
@@ -990,6 +1171,10 @@ function treeTool(catalog, options) {
         throw new Error(`invalid UI tree: ${formatIssues(result.issues)}`);
       }
       const root = result.value;
+      const single = flatComponent(resolved, root.type);
+      if (root.children === void 0 && single !== void 0) {
+        return push(ctx, root.type, root.props, single.version);
+      }
       return push(ctx, GENUI_TREE_COMPONENT, {
         root
       });
@@ -1000,7 +1185,36 @@ function treeTool(catalog, options) {
     return {
       available: resolved.modelComponents().length > 0,
       description: describeFor(resolved),
-      inputSchema: permissiveSchema(treeJsonSchema(resolved))
+      inputSchema: permissiveSchema(treeJsonSchema(resolved, treeSchemaOptions))
+    };
+  };
+  handler.previewInput = async (scope) => {
+    const resolved = negotiateCatalog(await catalogFor(catalog, options, scopeOf(scope)), scope.uiCapabilities);
+    const streaming = options.streaming ?? "complete";
+    if (!resolved.modelComponents().some((each) => (each.streaming ?? streaming) === "partial")) {
+      return void 0;
+    }
+    return {
+      ...options.streamingThrottleMs !== void 0 ? {
+        throttleMs: options.streamingThrottleMs
+      } : {},
+      render(input) {
+        const tree = partialTree(resolved, input, {
+          streaming,
+          ...options.treeLimits !== void 0 ? {
+            limits: options.treeLimits
+          } : {}
+        });
+        if (tree === null) return null;
+        if (tree.root === null) return void 0;
+        return {
+          component: GENUI_TREE_COMPONENT,
+          props: {
+            root: tree.root
+          },
+          version: 1
+        };
+      }
     };
   };
   return {
@@ -1008,7 +1222,7 @@ function treeTool(catalog, options) {
       name,
       kind: "read",
       description: describeFor(catalog),
-      inputSchema: dynamic ? permissiveSchema(treeJsonSchema(catalog)) : asyncJsonStandardSchema(treeJsonSchema(catalog), async (value) => {
+      inputSchema: dynamic ? permissiveSchema(treeJsonSchema(catalog, treeSchemaOptions)) : asyncJsonStandardSchema(treeJsonSchema(catalog, treeSchemaOptions), async (value) => {
         const result = await validateTree(catalog, value, options.treeLimits, "input");
         return result.ok ? {
           value: result.value
@@ -1856,6 +2070,7 @@ export {
   isStandardSchema,
   jsonStandardSchema,
   negotiateCatalog,
+  partialTree,
   prepareUiEmission,
   showToolJsonSchema,
   snapshotComponentPresentation,
@@ -1865,6 +2080,7 @@ export {
   toSnakeCase,
   toolNameFor,
   treeJsonSchema,
+  treeNodeId,
   treeToFlatSpec,
   treeToText,
   validatePresentationBatch,