@dudousxd/nestjs-agent-core 0.39.0 → 0.41.0

package/dist/genui/index.cjs

@@ -27,7 +27,10 @@ __export(genui_exports, {
   ajvValidator: () => ajvValidator,
   builtinJsonSchemaValidator: () => builtinJsonSchemaValidator,
   catalogToModelText: () => catalogToModelText,
+  chart: () => chart,
   componentToText: () => componentToText,
+  createComponent: () => createComponent,
+  createComponentRegistry: () => createComponentRegistry,
   defineCatalog: () => defineCatalog,
   defineComponent: () => defineComponent,
   fillTemplate: () => fillTemplate,
@@ -36,17 +39,23 @@ __export(genui_exports, {
   getPath: () => getPath,
   isStandardSchema: () => isStandardSchema,
   jsonStandardSchema: () => jsonStandardSchema,
+  negotiateCatalog: () => negotiateCatalog,
+  prepareUiEmission: () => prepareUiEmission,
   showToolJsonSchema: () => showToolJsonSchema,
+  snapshotComponentPresentation: () => snapshotComponentPresentation,
   summarizeSchema: () => summarizeSchema,
+  table: () => table,
   toJsonSchema: () => toJsonSchema,
   toSnakeCase: () => toSnakeCase,
   toolNameFor: () => toolNameFor,
   treeJsonSchema: () => treeJsonSchema,
   treeToFlatSpec: () => treeToFlatSpec,
   treeToText: () => treeToText,
+  validatePresentationBatch: () => validatePresentationBatch,
   validateProps: () => validateProps,
   validatePropsSync: () => validatePropsSync,
-  validateTree: () => validateTree
+  validateTree: () => validateTree,
+  validateUiCapabilities: () => validateUiCapabilities
 });
 module.exports = __toCommonJS(genui_exports);
 
@@ -226,21 +235,21 @@ function check(schema, value, path, root, issues, depth) {
     });
     return;
   }
-  const s = schema;
-  if (typeof s.$ref === "string") {
-    const target = resolveRef(root, s.$ref);
+  const s2 = schema;
+  if (typeof s2.$ref === "string") {
+    const target = resolveRef(root, s2.$ref);
     if (target === void 0) {
       issues.push({
         path,
-        message: `references unknown schema ${s.$ref}`
+        message: `references unknown schema ${s2.$ref}`
       });
       return;
     }
     check(target, value, path, root, issues, depth + 1);
   }
-  if (s.type !== void 0) {
-    const types = Array.isArray(s.type) ? s.type : [
-      s.type
+  if (s2.type !== void 0) {
+    const types = Array.isArray(s2.type) ? s2.type : [
+      s2.type
     ];
     if (!types.some((type) => matchesType(type, value))) {
       issues.push({
@@ -250,76 +259,76 @@ function check(schema, value, path, root, issues, depth) {
       return;
     }
   }
-  if (Array.isArray(s.enum) && !s.enum.some((option) => deepEqual(option, value))) {
+  if (Array.isArray(s2.enum) && !s2.enum.some((option) => deepEqual(option, value))) {
     issues.push({
       path,
-      message: `must be one of ${s.enum.map((option) => JSON.stringify(option)).join(", ")}`
+      message: `must be one of ${s2.enum.map((option) => JSON.stringify(option)).join(", ")}`
     });
   }
-  if ("const" in s && !deepEqual(s.const, value)) {
+  if ("const" in s2 && !deepEqual(s2.const, value)) {
     issues.push({
       path,
-      message: `must be ${JSON.stringify(s.const)}`
+      message: `must be ${JSON.stringify(s2.const)}`
     });
   }
   if (typeof value === "string") {
-    if (typeof s.minLength === "number" && value.length < s.minLength) {
+    if (typeof s2.minLength === "number" && value.length < s2.minLength) {
       issues.push({
         path,
-        message: `must be at least ${s.minLength} characters`
+        message: `must be at least ${s2.minLength} characters`
       });
     }
-    if (typeof s.maxLength === "number" && value.length > s.maxLength) {
+    if (typeof s2.maxLength === "number" && value.length > s2.maxLength) {
       issues.push({
         path,
-        message: `must be at most ${s.maxLength} characters`
+        message: `must be at most ${s2.maxLength} characters`
       });
     }
-    if (typeof s.pattern === "string") {
+    if (typeof s2.pattern === "string") {
       let pattern;
       try {
-        pattern = new RegExp(s.pattern, "u");
+        pattern = new RegExp(s2.pattern, "u");
       } catch {
         pattern = void 0;
       }
       if (pattern !== void 0 && !pattern.test(value)) {
         issues.push({
           path,
-          message: `must match ${s.pattern}`
+          message: `must match ${s2.pattern}`
         });
       }
     }
   }
   if (typeof value === "number") {
-    if (typeof s.minimum === "number" && value < s.minimum) {
+    if (typeof s2.minimum === "number" && value < s2.minimum) {
       issues.push({
         path,
-        message: `must be >= ${s.minimum}`
+        message: `must be >= ${s2.minimum}`
       });
     }
-    if (typeof s.maximum === "number" && value > s.maximum) {
+    if (typeof s2.maximum === "number" && value > s2.maximum) {
       issues.push({
         path,
-        message: `must be <= ${s.maximum}`
+        message: `must be <= ${s2.maximum}`
       });
     }
   }
   if (Array.isArray(value)) {
-    if (typeof s.minItems === "number" && value.length < s.minItems) {
+    if (typeof s2.minItems === "number" && value.length < s2.minItems) {
       issues.push({
         path,
-        message: `must have at least ${s.minItems} items`
+        message: `must have at least ${s2.minItems} items`
       });
     }
-    if (typeof s.maxItems === "number" && value.length > s.maxItems) {
+    if (typeof s2.maxItems === "number" && value.length > s2.maxItems) {
       issues.push({
         path,
-        message: `must have at most ${s.maxItems} items`
+        message: `must have at most ${s2.maxItems} items`
       });
     }
-    if (s.items !== void 0 && !Array.isArray(s.items)) {
+    if (s2.items !== void 0 && !Array.isArray(s2.items)) {
       value.forEach((item, index) => {
-        check(s.items, item, [
+        check(s2.items, item, [
           ...path,
           index
         ], root, issues, depth + 1);
@@ -327,11 +336,11 @@ function check(schema, value, path, root, issues, depth) {
     }
   }
   if (matchesType("object", value)) {
-    const record = value;
-    const properties = typeof s.properties === "object" && s.properties !== null ? s.properties : {};
-    if (Array.isArray(s.required)) {
-      for (const key of s.required) {
-        if (record[key] === void 0) {
+    const record2 = value;
+    const properties = typeof s2.properties === "object" && s2.properties !== null ? s2.properties : {};
+    if (Array.isArray(s2.required)) {
+      for (const key of s2.required) {
+        if (record2[key] === void 0) {
           issues.push({
             path: [
               ...path,
@@ -342,7 +351,7 @@ function check(schema, value, path, root, issues, depth) {
         }
       }
     }
-    for (const [key, entry] of Object.entries(record)) {
+    for (const [key, entry] of Object.entries(record2)) {
       if (key in properties) {
         if (entry !== void 0) {
           check(properties[key], entry, [
@@ -350,7 +359,7 @@ function check(schema, value, path, root, issues, depth) {
             key
           ], root, issues, depth + 1);
         }
-      } else if (s.additionalProperties === false) {
+      } else if (s2.additionalProperties === false) {
         issues.push({
           path: [
             ...path,
@@ -358,34 +367,34 @@ function check(schema, value, path, root, issues, depth) {
           ],
           message: "is not a known property"
         });
-      } else if (typeof s.additionalProperties === "object" && s.additionalProperties !== null) {
-        check(s.additionalProperties, entry, [
+      } else if (typeof s2.additionalProperties === "object" && s2.additionalProperties !== null) {
+        check(s2.additionalProperties, entry, [
           ...path,
           key
         ], root, issues, depth + 1);
       }
     }
   }
-  if (Array.isArray(s.allOf)) {
-    for (const sub of s.allOf) check(sub, value, path, root, issues, depth + 1);
+  if (Array.isArray(s2.allOf)) {
+    for (const sub of s2.allOf) check(sub, value, path, root, issues, depth + 1);
   }
-  if (Array.isArray(s.anyOf) || Array.isArray(s.oneOf)) {
-    const options = Array.isArray(s.anyOf) ? s.anyOf : s.oneOf;
+  if (Array.isArray(s2.anyOf) || Array.isArray(s2.oneOf)) {
+    const options = Array.isArray(s2.anyOf) ? s2.anyOf : s2.oneOf;
     const passing = options.filter((sub) => {
       const nested = [];
       check(sub, value, path, root, nested, depth + 1);
       return nested.length === 0;
     }).length;
-    if (Array.isArray(s.anyOf) ? passing === 0 : passing !== 1) {
+    if (Array.isArray(s2.anyOf) ? passing === 0 : passing !== 1) {
       issues.push({
         path,
-        message: Array.isArray(s.anyOf) ? "does not match any allowed shape" : "must match exactly one allowed shape"
+        message: Array.isArray(s2.anyOf) ? "does not match any allowed shape" : "must match exactly one allowed shape"
       });
     }
   }
-  if (s.not !== void 0) {
+  if (s2.not !== void 0) {
     const nested = [];
-    check(s.not, value, path, root, nested, depth + 1);
+    check(s2.not, value, path, root, nested, depth + 1);
     if (nested.length === 0) {
       issues.push({
         path,
@@ -402,6 +411,8 @@ function defineComponent(definition) {
   if (!COMPONENT_NAME.test(definition.name)) {
     throw new Error(`genui: component name "${definition.name}" must be letters and digits, starting with a letter (e.g. DataTable)`);
   }
+  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");
   return definition;
 }
 __name(defineComponent, "defineComponent");
@@ -440,7 +451,7 @@ function buildCatalog(byName, validator) {
           ]
         };
       }
-      const result = await validateProps(definition.props, props, validator);
+      const result = await validateProps(definition.outputProps ?? definition.props, props, validator);
       return result;
     },
     validateSync(component, props) {
@@ -456,11 +467,11 @@ function buildCatalog(byName, validator) {
           ]
         };
       }
-      return validatePropsSync(definition.props, props, validator);
+      return validatePropsSync(definition.outputProps ?? definition.props, props, validator);
     },
     jsonSchemaFor(component) {
       const definition = byName.get(component);
-      return definition === void 0 ? void 0 : toJsonSchema(definition.props);
+      return definition === void 0 ? void 0 : toJsonSchema(definition.outputProps ?? definition.props);
     },
     extend(more) {
       const next = new Map(byName);
@@ -484,7 +495,7 @@ __name(toolNameFor, "toolNameFor");
 
 // src/genui/tree.ts
 var GENUI_TREE_COMPONENT = "genui:tree";
-async function validateTree(catalog, tree, limits = {}) {
+async function validateTree(catalog, tree, limits = {}, phase = "output") {
   const maxDepth = limits.maxDepth ?? 12;
   const maxNodes = limits.maxNodes ?? 200;
   const issues = [];
@@ -536,7 +547,7 @@ async function validateTree(catalog, tree, limits = {}) {
       });
       return void 0;
     }
-    const validated = await catalog.validate(element.type, element.props ?? {});
+    const validated = phase === "input" ? await validateProps(definition.props, element.props ?? {}, catalog.validator) : await catalog.validate(element.type, element.props ?? {});
     let props = {};
     if (!validated.ok) {
       for (const issue of validated.issues) {
@@ -710,7 +721,8 @@ function componentToText(catalog, component, props) {
   const fallback = catalog.get(component)?.fallbackText;
   if (fallback !== void 0) {
     try {
-      return fallback(props);
+      const text = fallback(props);
+      if (typeof text === "string" && text.trim().length > 0) return text;
     } catch {
     }
   }
@@ -724,7 +736,8 @@ function treeToText(catalog, root) {
     const definition = catalog.get(node.type);
     if (definition?.fallbackText !== void 0) {
       try {
-        out.push(definition.fallbackText(node.props));
+        const text = definition.fallbackText(node.props);
+        out.push(typeof text === "string" && text.trim().length > 0 ? text : jsonBlock(node.props));
       } catch {
         out.push(jsonBlock(node.props));
       }
@@ -741,7 +754,7 @@ function jsonBlock(props) {
   const title = typeof props.title === "string" && props.title.length > 0 ? `*${props.title}*
 ` : "";
   return `${title}\`\`\`
-${JSON.stringify(props, null, 2).slice(0, 2500)}
+${JSON.stringify(props, null, 2)}
 \`\`\``;
 }
 __name(jsonBlock, "jsonBlock");
@@ -756,7 +769,7 @@ function catalogToModelText(catalog, options = {}) {
     lines.push("Components you can show (one tool each):");
   }
   for (const component of catalog.modelComponents()) {
-    const schema = catalog.jsonSchemaFor(component.name);
+    const schema = toJsonSchema(component.props);
     const head = mode === "per-component" ? `- ${component.name} (tool \`${toolNameFor(component.name, options.namePrefix)}\`)` : `- ${component.name}`;
     lines.push(`${head}: ${component.description}`);
     if (schema !== void 0) {
@@ -771,38 +784,38 @@ function catalogToModelText(catalog, options = {}) {
 __name(catalogToModelText, "catalogToModelText");
 function summarizeSchema(schema, root, depth) {
   if (typeof schema !== "object" || schema === null) return "unknown";
-  const s = schema;
+  const s2 = schema;
   if (depth > 5) return "\u2026";
-  if (typeof s.$ref === "string") {
-    return s.$ref === "#" ? "Self" : s.$ref.split("/").pop() ?? "unknown";
+  if (typeof s2.$ref === "string") {
+    return s2.$ref === "#" ? "Self" : s2.$ref.split("/").pop() ?? "unknown";
   }
-  if (Array.isArray(s.enum)) {
-    return s.enum.map((option) => JSON.stringify(option)).join(" | ");
+  if (Array.isArray(s2.enum)) {
+    return s2.enum.map((option) => JSON.stringify(option)).join(" | ");
   }
-  if ("const" in s) return JSON.stringify(s.const);
-  const variants = s.anyOf ?? s.oneOf;
+  if ("const" in s2) return JSON.stringify(s2.const);
+  const variants = s2.anyOf ?? s2.oneOf;
   if (Array.isArray(variants)) {
     return variants.map((variant) => summarizeSchema(variant, root, depth + 1)).join(" | ");
   }
-  const types = Array.isArray(s.type) ? s.type : s.type !== void 0 ? [
-    s.type
+  const types = Array.isArray(s2.type) ? s2.type : s2.type !== void 0 ? [
+    s2.type
   ] : [];
   if (types.length > 1) {
     return types.map((type2) => summarizeSchema({
-      ...s,
+      ...s2,
       type: type2
     }, root, depth + 1)).join(" | ");
   }
   const type = types[0];
   if (type === "array") {
-    const item = s.items === void 0 ? "unknown" : summarizeSchema(s.items, root, depth + 1);
+    const item = s2.items === void 0 ? "unknown" : summarizeSchema(s2.items, root, depth + 1);
     return /[|\s]/.test(item) && !item.startsWith("{") ? `(${item})[]` : `${item}[]`;
   }
-  if (type === "object" || type === void 0 && s.properties !== void 0) {
-    const properties = s.properties ?? {};
+  if (type === "object" || type === void 0 && s2.properties !== void 0) {
+    const properties = s2.properties ?? {};
     const keys = Object.keys(properties);
     if (keys.length === 0) return "object";
-    const required = new Set(Array.isArray(s.required) ? s.required : []);
+    const required = new Set(Array.isArray(s2.required) ? s2.required : []);
     const fields = keys.map((key) => {
       const field = properties[key];
       const note = typeof field?.description === "string" && depth === 0 ? ` /* ${field.description} */` : "";
@@ -832,6 +845,81 @@ function getPath(source, path) {
 }
 __name(getPath, "getPath");
 
+// src/genui/capabilities.ts
+function validateUiCapabilities(value) {
+  if (!record(value) || Object.keys(value).some((key) => key !== "components") || !Array.isArray(value.components)) throw new TypeError("Invalid UI capabilities");
+  const seen = /* @__PURE__ */ new Set();
+  const components = value.components.map((component) => {
+    if (!record(component) || Object.keys(component).some((key) => key !== "name" && key !== "version") || typeof component.name !== "string" || !COMPONENT_NAME.test(component.name) || !Number.isSafeInteger(component.version) || Number(component.version) <= 0 || seen.has(component.name)) throw new TypeError("Invalid UI component capability");
+    seen.add(component.name);
+    return {
+      name: component.name,
+      version: Number(component.version)
+    };
+  });
+  return {
+    components
+  };
+}
+__name(validateUiCapabilities, "validateUiCapabilities");
+function record(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+__name(record, "record");
+function negotiateCatalog(catalog, capabilities) {
+  if (capabilities === void 0) return catalog;
+  const supported = validateUiCapabilities(capabilities).components;
+  return defineCatalog(catalog.components.filter((component) => supported.some((entry) => entry.name === component.name && entry.version === (component.version ?? 1))), {
+    jsonSchemaValidator: catalog.validator
+  });
+}
+__name(negotiateCatalog, "negotiateCatalog");
+async function prepareUiEmission(catalog, capabilities, component, props, version) {
+  const drawable = negotiateCatalog(catalog, capabilities);
+  if (component === GENUI_TREE_COMPONENT) {
+    if (version !== void 0 && version !== 1) throw new Error("Invalid UI tree version");
+    const validated2 = await validateTree(catalog, props.root);
+    if (!validated2.ok) throw new Error(`Invalid UI tree: ${formatIssues(validated2.issues)}`);
+    const supported = /* @__PURE__ */ __name((node) => drawable.has(node.type) && (node.children ?? []).every(supported), "supported");
+    const versions = /* @__PURE__ */ new Map();
+    const collectVersions = /* @__PURE__ */ __name((node) => {
+      versions.set(node.type, catalog.get(node.type)?.version ?? 1);
+      for (const child of node.children ?? []) collectVersions(child);
+    }, "collectVersions");
+    collectVersions(validated2.value);
+    return supported(validated2.value) ? {
+      kind: "ui",
+      component,
+      props: {
+        root: validated2.value
+      },
+      version: 1,
+      fallbackText: treeToText(catalog, validated2.value),
+      componentVersions: Object.fromEntries(versions)
+    } : {
+      kind: "text",
+      text: treeToText(catalog, validated2.value)
+    };
+  }
+  const definition = catalog.get(component);
+  if (definition === void 0) throw new Error(`Unknown UI component "${component}"`);
+  const currentVersion = definition.version ?? 1;
+  if (version !== void 0 && version !== currentVersion) throw new Error(`Invalid UI component version for "${component}"`);
+  const validated = await catalog.validate(component, props);
+  if (!validated.ok) throw new Error(`Invalid UI props: ${formatIssues(validated.issues)}`);
+  return drawable.has(component) ? {
+    kind: "ui",
+    component,
+    props: validated.value,
+    version: currentVersion,
+    fallbackText: componentToText(catalog, component, validated.value)
+  } : {
+    kind: "text",
+    text: componentToText(catalog, component, validated.value)
+  };
+}
+__name(prepareUiEmission, "prepareUiEmission");
+
 // src/genui/tools.ts
 var GENUI_SHOW_TOOL = "ui__show";
 function genuiTools(catalog, options = {}) {
@@ -895,30 +983,29 @@ function componentTool(catalog, component, options) {
       if (definition === void 0) {
         throw new Error(`component "${component.name}" is not available here`);
       }
-      const validated = await validateProps(definition.props, input, resolved.validator);
+      const validated = await validateProps(dynamic ? definition.props : definition.outputProps ?? definition.props, input, resolved.validator);
       if (!validated.ok) {
         throw new Error(`invalid ${component.name} props: ${formatIssues(validated.issues)}`);
       }
       return push(ctx, component.name, validated.value, definition.version);
     }
   };
-  if (dynamic) {
-    handler.describe = async (scope) => {
-      const resolved = await catalogFor(catalog, options, scopeOf(scope));
-      const definition = modelComponent(resolved, component.name);
-      if (definition === void 0) {
-        return {
-          description: `Not available in this conversation \u2014 do not call this tool. (${component.name})`
-        };
-      }
+  handler.describe = async (scope) => {
+    const resolved = negotiateCatalog(await catalogFor(catalog, options, scopeOf(scope)), scope.uiCapabilities);
+    const definition = modelComponent(resolved, component.name);
+    if (definition === void 0) {
       return {
-        description: describeFor(definition),
-        inputSchema: permissiveSchema(toJsonSchema(definition.props) ?? {
-          type: "object"
-        })
+        available: false,
+        description: `Not available in this conversation \u2014 do not call this tool. (${component.name})`
       };
+    }
+    return {
+      description: describeFor(definition),
+      inputSchema: permissiveSchema(toJsonSchema(definition.props) ?? {
+        type: "object"
+      })
     };
-  }
+  };
   return {
     spec: {
       name: toolNameFor(component.name, options.namePrefix),
@@ -952,7 +1039,7 @@ function treeTool(catalog, options) {
   const handler = {
     async execute(input, ctx) {
       const resolved = await catalogFor(catalog, options, scopeOf(ctx));
-      const result = await validateTree(resolved, input, options.treeLimits);
+      const result = await validateTree(resolved, input, options.treeLimits, dynamic ? "input" : "output");
       if (!result.ok) {
         throw new Error(`invalid UI tree: ${formatIssues(result.issues)}`);
       }
@@ -962,22 +1049,21 @@ function treeTool(catalog, options) {
       });
     }
   };
-  if (dynamic) {
-    handler.describe = async (scope) => {
-      const resolved = await catalogFor(catalog, options, scopeOf(scope));
-      return {
-        description: describeFor(resolved),
-        inputSchema: permissiveSchema(treeJsonSchema(resolved))
-      };
+  handler.describe = async (scope) => {
+    const resolved = negotiateCatalog(await catalogFor(catalog, options, scopeOf(scope)), scope.uiCapabilities);
+    return {
+      available: resolved.modelComponents().length > 0,
+      description: describeFor(resolved),
+      inputSchema: permissiveSchema(treeJsonSchema(resolved))
     };
-  }
+  };
   return {
     spec: {
       name,
       kind: "read",
       description: describeFor(catalog),
       inputSchema: dynamic ? permissiveSchema(treeJsonSchema(catalog)) : asyncJsonStandardSchema(treeJsonSchema(catalog), async (value) => {
-        const result = await validateTree(catalog, value, options.treeLimits);
+        const result = await validateTree(catalog, value, options.treeLimits, "input");
         return result.ok ? {
           value: result.value
         } : {
@@ -1012,7 +1098,7 @@ function showToolJsonSchema(catalog) {
   };
 }
 __name(showToolJsonSchema, "showToolJsonSchema");
-async function validateShow(catalog, input) {
+async function validateShow(catalog, input, phase = "input") {
   if (typeof input !== "object" || input === null || Array.isArray(input)) {
     return {
       ok: false,
@@ -1053,7 +1139,7 @@ async function validateShow(catalog, input) {
       ]
     };
   }
-  const validated = await validateProps(definition.props, props ?? {}, catalog.validator);
+  const validated = await validateProps(phase === "input" ? definition.props : definition.outputProps ?? definition.props, props ?? {}, catalog.validator);
   if (!validated.ok) {
     return {
       ok: false,
@@ -1093,22 +1179,21 @@ function showTool(catalog, options) {
   const handler = {
     async execute(input, ctx) {
       const resolved = await catalogFor(catalog, options, scopeOf(ctx));
-      const result = await validateShow(resolved, input);
+      const result = await validateShow(resolved, input, dynamic ? "input" : "output");
       if (!result.ok) {
         throw new Error(`invalid ${name} call: ${formatIssues(result.issues)}`);
       }
       return push(ctx, result.definition.name, result.props, result.definition.version);
     }
   };
-  if (dynamic) {
-    handler.describe = async (scope) => {
-      const resolved = await catalogFor(catalog, options, scopeOf(scope));
-      return {
-        description: describeFor(resolved),
-        inputSchema: permissiveSchema(showToolJsonSchema(resolved))
-      };
+  handler.describe = async (scope) => {
+    const resolved = negotiateCatalog(await catalogFor(catalog, options, scopeOf(scope)), scope.uiCapabilities);
+    return {
+      available: resolved.modelComponents().length > 0,
+      description: describeFor(resolved),
+      inputSchema: permissiveSchema(showToolJsonSchema(resolved))
     };
-  }
+  };
   return {
     spec: {
       name,
@@ -1193,6 +1278,586 @@ function asyncJsonStandardSchema(schema, validate) {
   };
 }
 __name(asyncJsonStandardSchema, "asyncJsonStandardSchema");
+
+// src/genui/builtins.ts
+var str = /* @__PURE__ */ __name((description, extra = {}) => ({
+  type: "string",
+  ...description !== void 0 ? {
+    description
+  } : {},
+  ...extra
+}), "str");
+var obj = /* @__PURE__ */ __name((properties, required = []) => ({
+  type: "object",
+  properties,
+  required,
+  additionalProperties: false
+}), "obj");
+var arr = /* @__PURE__ */ __name((items, extra = {}) => ({
+  type: "array",
+  items,
+  ...extra
+}), "arr");
+var cell = {
+  type: [
+    "string",
+    "number",
+    "boolean",
+    "null"
+  ]
+};
+var row = {
+  type: "object",
+  additionalProperties: cell
+};
+var s = /* @__PURE__ */ __name((value) => value === null || value === void 0 ? "" : String(value), "s");
+var heading = /* @__PURE__ */ __name((props) => props.title ? `*${s(props.title)}*
+` : "", "heading");
+function textTable(columns, rows, max = 15) {
+  const shown = rows.slice(0, max);
+  const widths = columns.map((column) => Math.min(28, Math.max(column.label.length, ...shown.map((r) => s(r[column.key]).length))));
+  const format = /* @__PURE__ */ __name((values) => values.map((value, index) => value.slice(0, widths[index]).padEnd(widths[index] ?? 0)).join("  "), "format");
+  const lines = [
+    format(columns.map((column) => column.label)),
+    widths.map((width) => "-".repeat(width)).join("  "),
+    ...shown.map((r) => format(columns.map((column) => s(r[column.key]))))
+  ];
+  if (rows.length > max) lines.push(`\u2026 ${rows.length - max} more rows`);
+  return `\`\`\`
+${lines.join("\n")}
+\`\`\``;
+}
+__name(textTable, "textTable");
+function lineDiff(before, after) {
+  const a = before.split("\n");
+  const b = after.split("\n");
+  if (a.length * b.length > 25e4) {
+    return [
+      ...a.map((text) => ({
+        op: "del",
+        text
+      })),
+      ...b.map((text) => ({
+        op: "add",
+        text
+      }))
+    ];
+  }
+  const dp = Array.from({
+    length: a.length + 1
+  }, () => new Array(b.length + 1).fill(0));
+  const at = /* @__PURE__ */ __name((i2, j2) => dp[i2]?.[j2] ?? 0, "at");
+  for (let i2 = a.length - 1; i2 >= 0; i2--) {
+    for (let j2 = b.length - 1; j2 >= 0; j2--) {
+      dp[i2][j2] = a[i2] === b[j2] ? at(i2 + 1, j2 + 1) + 1 : Math.max(at(i2 + 1, j2), at(i2, j2 + 1));
+    }
+  }
+  const out = [];
+  let i = 0;
+  let j = 0;
+  while (i < a.length && j < b.length) {
+    if (a[i] === b[j]) {
+      out.push({
+        op: "same",
+        text: a[i]
+      });
+      i++;
+      j++;
+    } else if (at(i + 1, j) >= at(i, j + 1)) {
+      out.push({
+        op: "del",
+        text: a[i++]
+      });
+    } else {
+      out.push({
+        op: "add",
+        text: b[j++]
+      });
+    }
+  }
+  while (i < a.length) out.push({
+    op: "del",
+    text: a[i++]
+  });
+  while (j < b.length) out.push({
+    op: "add",
+    text: b[j++]
+  });
+  return out;
+}
+__name(lineDiff, "lineDiff");
+function bar(value, max, width = 20) {
+  const n = max > 0 ? Math.round(Math.abs(value) / max * width) : 0;
+  return "\u2588".repeat(n) || "\u258F";
+}
+__name(bar, "bar");
+var DataTable = defineComponent({
+  name: "DataTable",
+  title: "Data table",
+  description: "Tabular data (records with the same fields) as a sortable table. Prefer it over markdown tables for more than 3 rows.",
+  props: obj({
+    title: str("Short caption"),
+    columns: arr(obj({
+      key: str("Field name in each row"),
+      label: str("Column header"),
+      align: str(void 0, {
+        enum: [
+          "left",
+          "right",
+          "center"
+        ]
+      }),
+      format: str("How to format values", {
+        enum: [
+          "text",
+          "number",
+          "currency",
+          "percent",
+          "date",
+          "link"
+        ]
+      })
+    }, [
+      "key",
+      "label"
+    ]), {
+      minItems: 1,
+      maxItems: 12
+    }),
+    rows: arr(row, {
+      maxItems: 500
+    })
+  }, [
+    "columns",
+    "rows"
+  ]),
+  fallbackText: /* @__PURE__ */ __name((props) => `${heading(props)}${textTable(props.columns ?? [], props.rows ?? [])}`, "fallbackText")
+});
+var Chart = defineComponent({
+  name: "Chart",
+  title: "Chart",
+  description: "`bar` to compare categories, `line` for a trend over time. `data` is a list of points; `xKey` names the category/time field and each series names a numeric field.",
+  props: obj({
+    type: str("Chart type", {
+      enum: [
+        "bar",
+        "line"
+      ]
+    }),
+    title: str(),
+    xKey: str("Field of each point used for the x axis"),
+    series: arr(obj({
+      key: str("Numeric field"),
+      label: str()
+    }, [
+      "key"
+    ]), {
+      minItems: 1,
+      maxItems: 6
+    }),
+    data: arr(row, {
+      minItems: 1,
+      maxItems: 200
+    }),
+    unit: str("Unit shown after values, e.g. `KB` or `%`")
+  }, [
+    "type",
+    "xKey",
+    "series",
+    "data"
+  ]),
+  fallbackText: /* @__PURE__ */ __name((props) => {
+    const series = props.series ?? [];
+    const data = props.data ?? [];
+    const first = series[0]?.key ?? "";
+    const max = Math.max(0, ...data.map((point) => Math.abs(Number(point[first]) || 0)));
+    const unit = props.unit ? ` ${s(props.unit)}` : "";
+    const lines = data.slice(0, 20).map((point) => `${s(point[props.xKey]).slice(0, 18).padEnd(18)} ${bar(Number(point[first]) || 0, max)} ${s(point[first])}${unit}`);
+    return `${heading(props)}\`\`\`
+${lines.join("\n")}
+\`\`\``;
+  }, "fallbackText")
+});
+var KpiCards = defineComponent({
+  name: "KpiCards",
+  title: "KPI cards",
+  description: "A few key numbers (metrics, totals, counts) as cards.",
+  props: obj({
+    title: str(),
+    items: arr(obj({
+      label: str(),
+      value: {
+        type: [
+          "string",
+          "number"
+        ]
+      },
+      delta: str("Change, e.g. `+12%`"),
+      trend: str(void 0, {
+        enum: [
+          "up",
+          "down",
+          "flat"
+        ]
+      }),
+      hint: str()
+    }, [
+      "label",
+      "value"
+    ]), {
+      minItems: 1,
+      maxItems: 8
+    })
+  }, [
+    "items"
+  ]),
+  fallbackText: /* @__PURE__ */ __name((props) => `${heading(props)}${(props.items ?? []).map((item) => `\u2022 *${s(item.label)}:* ${s(item.value)}${item.delta ? ` (${s(item.delta)})` : ""}`).join("\n")}`, "fallbackText")
+});
+var SourceCards = defineComponent({
+  name: "SourceCards",
+  title: "Sources",
+  description: "The documents, pages or links an answer is based on, as cards.",
+  props: obj({
+    title: str(),
+    items: arr(obj({
+      title: str(),
+      url: str(),
+      snippet: str(),
+      source: str("e.g. Wiki, GitHub")
+    }, [
+      "title"
+    ]), {
+      minItems: 1,
+      maxItems: 12
+    })
+  }, [
+    "items"
+  ]),
+  fallbackText: /* @__PURE__ */ __name((props) => `${heading(props)}${(props.items ?? []).map((item) => `\u2022 ${item.url ? `<${s(item.url)}|${s(item.title)}>` : s(item.title)}${item.source ? ` \u2014 ${s(item.source)}` : ""}`).join("\n")}`, "fallbackText")
+});
+var Checklist = defineComponent({
+  name: "Checklist",
+  title: "Checklist",
+  description: "Steps or a to-do list with done/not-done state.",
+  props: obj({
+    title: str(),
+    items: arr(obj({
+      label: str(),
+      done: {
+        type: "boolean"
+      },
+      note: str()
+    }, [
+      "label"
+    ]), {
+      minItems: 1,
+      maxItems: 50
+    })
+  }, [
+    "items"
+  ]),
+  fallbackText: /* @__PURE__ */ __name((props) => `${heading(props)}${(props.items ?? []).map((item) => `${item.done ? "\u2611" : "\u2610"} ${s(item.label)}${item.note ? ` \u2014 _${s(item.note)}_` : ""}`).join("\n")}`, "fallbackText")
+});
+var Timeline = defineComponent({
+  name: "Timeline",
+  title: "Timeline",
+  description: "Events in chronological order (the history of a project, an incident, a deal).",
+  props: obj({
+    title: str(),
+    events: arr(obj({
+      date: str(),
+      title: str(),
+      description: str()
+    }, [
+      "title"
+    ]), {
+      minItems: 1,
+      maxItems: 50
+    })
+  }, [
+    "events"
+  ]),
+  fallbackText: /* @__PURE__ */ __name((props) => `${heading(props)}${(props.events ?? []).map((event) => `\u2022 ${event.date ? `*${s(event.date)}* ` : ""}${s(event.title)}${event.description ? ` \u2014 ${s(event.description)}` : ""}`).join("\n")}`, "fallbackText")
+});
+var CodeBlock = defineComponent({
+  name: "CodeBlock",
+  title: "Code",
+  description: "A code snippet or file excerpt with syntax highlighting.",
+  props: obj({
+    title: str(),
+    language: str(),
+    code: str()
+  }, [
+    "code"
+  ]),
+  fallbackText: /* @__PURE__ */ __name((props) => `${heading(props)}\`\`\`
+${s(props.code)}
+\`\`\``, "fallbackText")
+});
+var Diff = defineComponent({
+  name: "Diff",
+  title: "Diff",
+  description: "A before/after change to a text or code file, as a line diff.",
+  props: obj({
+    title: str(),
+    language: str(),
+    before: str(),
+    after: str()
+  }, [
+    "before",
+    "after"
+  ]),
+  fallbackText: /* @__PURE__ */ __name((props) => `${heading(props)}\`\`\`
+${lineDiff(s(props.before), s(props.after)).map((line) => `${line.op === "add" ? "+" : line.op === "del" ? "-" : " "} ${line.text}`).join("\n")}
+\`\`\``, "fallbackText")
+});
+var Callout = defineComponent({
+  name: "Callout",
+  title: "Callout",
+  description: "A short note, warning or success message, emphasized.",
+  props: obj({
+    tone: str(void 0, {
+      enum: [
+        "info",
+        "success",
+        "warning",
+        "danger"
+      ]
+    }),
+    title: str(),
+    text: str()
+  }, [
+    "text"
+  ]),
+  fallbackText: /* @__PURE__ */ __name((props) => `${props.tone === "warning" || props.tone === "danger" ? ":warning: " : ":information_source: "}${heading(props)}${s(props.text)}`, "fallbackText")
+});
+var Stack = defineComponent({
+  name: "Stack",
+  title: "Stack",
+  description: "Lays its children out vertically (or horizontally with direction=row).",
+  props: obj({
+    direction: str(void 0, {
+      enum: [
+        "column",
+        "row"
+      ]
+    }),
+    gap: {
+      type: "number"
+    }
+  }),
+  children: true,
+  fallbackText: /* @__PURE__ */ __name(() => "", "fallbackText")
+});
+var Card = defineComponent({
+  name: "Card",
+  title: "Card",
+  description: "A box with an optional title around its children.",
+  props: obj({
+    title: str(),
+    subtitle: str()
+  }),
+  children: true,
+  fallbackText: /* @__PURE__ */ __name((props) => props.title ? `*${s(props.title)}*${props.subtitle ? ` \u2014 ${s(props.subtitle)}` : ""}` : "", "fallbackText")
+});
+var Heading = defineComponent({
+  name: "Heading",
+  title: "Heading",
+  description: "A heading.",
+  props: obj({
+    text: str()
+  }, [
+    "text"
+  ]),
+  fallbackText: /* @__PURE__ */ __name((props) => `*${s(props.text)}*`, "fallbackText")
+});
+var Text = defineComponent({
+  name: "Text",
+  title: "Text",
+  description: "A paragraph of plain text (no markdown).",
+  props: obj({
+    text: str(),
+    muted: {
+      type: "boolean"
+    }
+  }, [
+    "text"
+  ]),
+  fallbackText: /* @__PURE__ */ __name((props) => s(props.text), "fallbackText")
+});
+var Badge = defineComponent({
+  name: "Badge",
+  title: "Badge",
+  description: "A small label.",
+  props: obj({
+    text: str(),
+    tone: str(void 0, {
+      enum: [
+        "neutral",
+        "brand",
+        "success",
+        "warning",
+        "danger"
+      ]
+    })
+  }, [
+    "text"
+  ]),
+  fallbackText: /* @__PURE__ */ __name((props) => `[${s(props.text)}]`, "fallbackText")
+});
+var Link = defineComponent({
+  name: "Link",
+  title: "Link",
+  description: "A link to an http(s) URL.",
+  props: obj({
+    text: str(),
+    url: str(void 0, {
+      pattern: "^https?://"
+    })
+  }, [
+    "text",
+    "url"
+  ]),
+  fallbackText: /* @__PURE__ */ __name((props) => `<${s(props.url)}|${s(props.text || props.url)}>`, "fallbackText")
+});
+var Image = defineComponent({
+  name: "Image",
+  title: "Image",
+  description: "An image from an https URL.",
+  props: obj({
+    url: str(void 0, {
+      pattern: "^https://"
+    }),
+    alt: str()
+  }, [
+    "url"
+  ]),
+  fallbackText: /* @__PURE__ */ __name((props) => s(props.url), "fallbackText")
+});
+
+// src/genui/registry.ts
+function snapshotComponentPresentation(value) {
+  const seen = /* @__PURE__ */ new Set();
+  const check2 = /* @__PURE__ */ __name((entry) => {
+    if (entry === null || typeof entry === "string" || typeof entry === "boolean") return;
+    if (typeof entry === "number" && Number.isFinite(entry)) return;
+    if (typeof entry !== "object" || entry === null) throw new TypeError("genui: presentation must contain only JSON values");
+    if (seen.has(entry)) throw new TypeError("genui: presentation must contain acyclic JSON values");
+    if (!Array.isArray(entry) && Object.getPrototypeOf(entry) !== Object.prototype && Object.getPrototypeOf(entry) !== null) throw new TypeError("genui: presentation must contain plain JSON objects");
+    seen.add(entry);
+    for (const item of Object.values(entry)) check2(item);
+    seen.delete(entry);
+  }, "check");
+  check2(value);
+  return JSON.parse(JSON.stringify(value));
+}
+__name(snapshotComponentPresentation, "snapshotComponentPresentation");
+function createComponent(definition, options = {}) {
+  defineComponent(definition);
+  const catalog = defineCatalog([
+    definition
+  ], options);
+  const factory = /* @__PURE__ */ __name(async (props) => {
+    const result = await validateProps(definition.props, props, catalog.validator);
+    if (!result.ok) throw new Error(`genui: invalid ${definition.name} props: ${formatIssues(result.issues)}`);
+    const normalized = snapshotComponentPresentation(result.value);
+    if (typeof normalized !== "object" || normalized === null || Array.isArray(normalized)) throw new TypeError("genui: component props must be a JSON object");
+    const portable = await catalog.validate(definition.name, normalized);
+    if (!portable.ok || canonicalJson(snapshotComponentPresentation(portable.value)) !== canonicalJson(normalized)) {
+      throw new Error(`genui: ${definition.name} requires outputProps accepting stable normalized JSON props`);
+    }
+    return {
+      component: definition.name,
+      props: normalized,
+      version: definition.version ?? 1,
+      fallbackText: componentToText(catalog, definition.name, normalized)
+    };
+  }, "factory");
+  return Object.assign(factory, {
+    definition
+  });
+}
+__name(createComponent, "createComponent");
+function createComponentRegistry(options = {}) {
+  let catalog = defineCatalog([], options);
+  const channels = /* @__PURE__ */ new Map();
+  const registry = {
+    get catalog() {
+      return catalog;
+    },
+    get manifest() {
+      return catalog.components.map((definition) => {
+        const props = catalog.jsonSchemaFor(definition.name);
+        return {
+          name: definition.name,
+          title: definition.title,
+          description: definition.description,
+          version: definition.version ?? 1,
+          ...props === void 0 ? {} : {
+            props: snapshotComponentPresentation(props)
+          }
+        };
+      });
+    },
+    register(definition, renderers) {
+      if (catalog.has(definition.name)) throw new Error(`genui: component "${definition.name}" is already registered`);
+      catalog = catalog.extend([
+        definition
+      ]);
+      channels.set(definition.name, {
+        ...renderers
+      });
+      return this;
+    },
+    async prepare(presentation) {
+      const definition = catalog.get(presentation.component);
+      if (definition === void 0) throw new Error(`genui: unknown component "${presentation.component}"`);
+      if (presentation.version !== (definition.version ?? 1)) throw new Error(`genui: component "${presentation.component}" version mismatch`);
+      const validated = await catalog.validate(presentation.component, presentation.props);
+      if (!validated.ok) throw new Error(`genui: invalid ${presentation.component} props: ${formatIssues(validated.issues)}`);
+      const props = snapshotComponentPresentation(validated.value);
+      if (typeof props !== "object" || props === null || Array.isArray(props)) throw new TypeError("genui: component props must be a JSON object");
+      return {
+        component: definition.name,
+        props,
+        version: definition.version ?? 1,
+        fallbackText: componentToText(catalog, definition.name, props)
+      };
+    },
+    async render(presentation, channel, context) {
+      const prepared = await this.prepare(presentation);
+      const mapping = channels.get(prepared.component);
+      const renderer = mapping === void 0 ? void 0 : Object.hasOwn(mapping, channel) ? mapping[channel] : Object.hasOwn(mapping, "text") ? mapping.text : void 0;
+      return renderer === void 0 ? prepared.fallbackText : renderer(prepared.props, context);
+    }
+  };
+  return registry;
+}
+__name(createComponentRegistry, "createComponentRegistry");
+var table = createComponent(DataTable);
+var chart = createComponent(Chart);
+function validatePresentationBatch(presentations) {
+  const batch = Array.isArray(presentations) ? presentations : [
+    presentations
+  ];
+  return batch.map((item) => {
+    const presentation = snapshotComponentPresentation(item);
+    if (typeof presentation !== "object" || presentation === null || typeof presentation.component !== "string" || !/^[A-Za-z][A-Za-z0-9]{0,63}$/.test(presentation.component) || !Number.isSafeInteger(presentation.version) || presentation.version <= 0 || typeof presentation.fallbackText !== "string" || typeof presentation.props !== "object" || presentation.props === null || Array.isArray(presentation.props)) {
+      throw new TypeError("genui: invalid component presentation");
+    }
+    return presentation;
+  });
+}
+__name(validatePresentationBatch, "validatePresentationBatch");
+function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (typeof value === "object" && value !== null) {
+    const record2 = value;
+    return `{${Object.keys(record2).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(record2[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+__name(canonicalJson, "canonicalJson");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   COMPONENT_NAME,
@@ -1201,7 +1866,10 @@ __name(asyncJsonStandardSchema, "asyncJsonStandardSchema");
   ajvValidator,
   builtinJsonSchemaValidator,
   catalogToModelText,
+  chart,
   componentToText,
+  createComponent,
+  createComponentRegistry,
   defineCatalog,
   defineComponent,
   fillTemplate,
@@ -1210,16 +1878,22 @@ __name(asyncJsonStandardSchema, "asyncJsonStandardSchema");
   getPath,
   isStandardSchema,
   jsonStandardSchema,
+  negotiateCatalog,
+  prepareUiEmission,
   showToolJsonSchema,
+  snapshotComponentPresentation,
   summarizeSchema,
+  table,
   toJsonSchema,
   toSnakeCase,
   toolNameFor,
   treeJsonSchema,
   treeToFlatSpec,
   treeToText,
+  validatePresentationBatch,
   validateProps,
   validatePropsSync,
-  validateTree
+  validateTree,
+  validateUiCapabilities
 });
 //# sourceMappingURL=index.cjs.map