@intentface/ui 0.0.0 → 0.7.0

package/dist/generative/catalog.d.ts

@@ -0,0 +1,177 @@
+import type { InferInput, InferOutput, StandardJSONSchema, StandardSchema } from "../internal/standard-schema.js";
+export type JsonObject = Record<string, unknown>;
+export declare const isObject: (value: unknown) => value is Record<string, unknown>;
+/**
+ * A component's schema: it validates the props, and converts to the JSON
+ * Schema the model is shown. zod 4.2+ and ArkType 2.1.28+ do both; Valibot
+ * through `toStandardJsonSchema`.
+ */
+export type ComponentSchema = StandardSchema & StandardJSONSchema;
+type BindKey<Schema extends ComponentSchema> = unknown extends InferOutput<Schema> ? string : keyof InferOutput<Schema> & string;
+/** One component the model may use. */
+export type ComponentDefinition<Schema extends ComponentSchema = ComponentSchema> = {
+    /** When to use it, written for the model. */
+    description: string;
+    /** Validates its props, and converts to the JSON Schema the model is shown. */
+    props: Schema;
+    /** Whether it holds other components. */
+    container?: boolean;
+    /** Props the model may point at data (`{ "$data": ref }`) instead of writing out. */
+    bind?: readonly BindKey<Schema>[];
+    /** How it reads as Markdown. `children` is its children's Markdown. */
+    markdown?(props: InferOutput<Schema>, children: string): string;
+};
+/** The components the model may use, by type. */
+export type Catalog<Schemas extends Record<string, ComponentSchema> = Record<string, ComponentSchema>> = {
+    components: {
+        [Type in keyof Schemas]: ComponentDefinition<Schemas[Type]>;
+    };
+    /** Caps on one call: shown to the model in the tool's schema, and checked. */
+    limits?: Partial<Limits>;
+    /** What a ref looks like, in the model's terms. */
+    refDescription?: string;
+};
+type NoOtherKeys<Components> = {
+    [Type in keyof Components]: {
+        [Key in Exclude<keyof Components[Type], keyof ComponentDefinition>]: never;
+    };
+};
+/**
+ * Types a catalog from each component's schema. The catalog stays plain data,
+ * typed exactly as written, so the props each component binds are known too.
+ */
+export declare const defineCatalog: <Schemas extends Record<string, ComponentSchema>, const Written extends {
+    components: Record<string, unknown>;
+}>(catalog: Written & Catalog<Schemas> & {
+    components: NoOtherKeys<Written["components"]>;
+}) => Written;
+/** Any catalog: the bound for the helpers' type parameters, so every typed catalog fits. */
+export type AnyCatalog = {
+    components: Record<string, {
+        description: string;
+        props: ComponentSchema;
+        container?: boolean;
+        bind?: readonly string[];
+        markdown?(props: never, children: string): string;
+    }>;
+    limits?: Partial<Limits>;
+    refDescription?: string;
+};
+/** One component of any catalog, as the helpers read it. */
+export type AnyComponent = AnyCatalog["components"][string];
+/**
+ * The component a type names, if it's one of the catalog's own. A name the
+ * catalog only inherits, such as `"constructor"`, is not a component.
+ */
+export declare const componentOf: (catalog: AnyCatalog, type: unknown) => AnyComponent | undefined;
+type ComponentType<C extends AnyCatalog> = keyof C["components"] & string;
+type PropsOf<C extends AnyCatalog, Type extends ComponentType<C>> = InferOutput<C["components"][Type]["props"]>;
+/** The props a component binds, from its `bind` as written. */
+type BoundKey<C extends AnyCatalog, Type extends ComponentType<C>> = C["components"][Type] extends {
+    bind?: infer Keys;
+} ? Keys extends readonly (infer Key)[] ? Key : never : never;
+/** A component's props in a checked tree: a prop it binds may still hold its binding. */
+type CheckedProps<C extends AnyCatalog, Type extends ComponentType<C>> = unknown extends PropsOf<C, Type> ? unknown : {
+    [Key in keyof PropsOf<C, Type>]: Key extends BoundKey<C, Type> ? PropsOf<C, Type>[Key] | Binding : PropsOf<C, Type>[Key];
+};
+/** One element of a checked tree. A prop its component binds may still hold its `Binding`. */
+export type TreeElement<C extends AnyCatalog = AnyCatalog> = {
+    [Type in ComponentType<C>]: {
+        type: Type;
+        props: CheckedProps<C, Type>;
+        children?: string[];
+    };
+}[ComponentType<C>];
+/** One element of a resolved tree: every prop holds its data. */
+export type ResolvedTreeElement<C extends AnyCatalog = AnyCatalog> = {
+    [Type in ComponentType<C>]: {
+        type: Type;
+        props: PropsOf<C, Type>;
+        children?: string[];
+    };
+}[ComponentType<C>];
+interface TreeOf<Element> {
+    root: string;
+    elements: Record<string, Element>;
+}
+/** A checked call: the root's id and every element by id. Plain JSON, safe to store. */
+export type Tree<C extends AnyCatalog = AnyCatalog> = TreeOf<TreeElement<C>>;
+/** A checked call with its bindings resolved, as `bindings.resolve` returns it. */
+export type ResolvedTree<C extends AnyCatalog = AnyCatalog> = TreeOf<ResolvedTreeElement<C>>;
+type BindingInput = {
+    $data: string;
+    columns?: string[] | null;
+    column?: string | null;
+};
+/** A component's props as its schema takes them in. */
+type InputPropsOf<C extends AnyCatalog, Type extends ComponentType<C>> = InferInput<C["components"][Type]["props"]>;
+/** A component's props as the model writes them, per the tool's schema. */
+type InputProps<C extends AnyCatalog, Type extends ComponentType<C>> = unknown extends InputPropsOf<C, Type> ? unknown : {
+    [Key in keyof InputPropsOf<C, Type>]: InputPropsOf<C, Type>[Key] | (Key extends BoundKey<C, Type> ? BindingInput : never) | (undefined extends InputPropsOf<C, Type>[Key] ? null : never);
+};
+/** Whether a component holds children, from its `container` as written. */
+type IsContainer<C extends AnyCatalog, Type extends ComponentType<C>> = C["components"][Type] extends {
+    container: true;
+} ? true : false;
+/**
+ * One component on its own, as the model writes it when the tool's schema
+ * comes from `tree.schema(catalog, { single: true })`.
+ */
+export type ComponentInput<C extends AnyCatalog = AnyCatalog> = {
+    [Type in ComponentType<C>]: {
+        type: Type;
+        props: InputProps<C, Type>;
+    };
+}[ComponentType<C>];
+/** A call as the model writes it, per `tree.schema(catalog)`, which types a tool's input with it. */
+export type TreeInput<C extends AnyCatalog = AnyCatalog> = {
+    root: string;
+    elements: {
+        [Type in ComponentType<C>]: {
+            id: string;
+            type: Type;
+            props: InputProps<C, Type>;
+        } & (IsContainer<C, Type> extends true ? {
+            children: string[];
+        } : unknown);
+    }[ComponentType<C>][];
+};
+/** One node, ready to draw. Its props are typed once its status is `ready`. */
+export type TreeNode<C extends AnyCatalog = AnyCatalog> = {
+    [Type in ComponentType<C>]: {
+        id: string;
+        type: Type;
+        status: "ready";
+        props: PropsOf<C, Type>;
+        children: TreeNode<C>[];
+    } | {
+        id: string;
+        type: Type;
+        status: "pending";
+        props: unknown;
+        children: TreeNode<C>[];
+    };
+}[ComponentType<C>];
+/** Caps on one call. The node and children caps are also in the tool's schema. */
+export type Limits = {
+    nodes: number;
+    depth: number;
+    children: number;
+};
+export declare const DEFAULT_LIMITS: Limits;
+/** A catalog's limits, each one it leaves out at its default. */
+export declare const limitsOf: (catalog: AnyCatalog) => Limits;
+/** Data by reference: a tool result's ref, and the columns to pick from its rows. */
+export type Binding = {
+    $data: string;
+    columns?: string[];
+    column?: string;
+};
+/** A binding found in a tree, and where it sits. */
+export type FoundBinding = Binding & {
+    id: string;
+    prop: string;
+};
+export declare const DEFAULT_REF_DESCRIPTION = "Where the data comes from: its ref, exactly as given.";
+export declare const isBinding: (value: unknown) => value is Binding;
+export {};

package/dist/generative/catalog.js

@@ -0,0 +1,20 @@
+// The catalog and the shapes the generative helpers read and return: what the
+// model may use, the tree it writes, and the small lookups over both.
+export const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * Types a catalog from each component's schema. The catalog stays plain data,
+ * typed exactly as written, so the props each component binds are known too.
+ */
+export const defineCatalog = (catalog) => catalog;
+/**
+ * The component a type names, if it's one of the catalog's own. A name the
+ * catalog only inherits, such as `"constructor"`, is not a component.
+ */
+export const componentOf = (catalog, type) => typeof type === "string" && Object.hasOwn(catalog.components, type)
+    ? catalog.components[type]
+    : undefined;
+export const DEFAULT_LIMITS = { nodes: 40, depth: 6, children: 24 };
+/** A catalog's limits, each one it leaves out at its default. */
+export const limitsOf = (catalog) => ({ ...DEFAULT_LIMITS, ...catalog.limits });
+export const DEFAULT_REF_DESCRIPTION = "Where the data comes from: its ref, exactly as given.";
+export const isBinding = (value) => isObject(value) && typeof value.$data === "string";

package/dist/generative/index.d.ts

@@ -0,0 +1,26 @@
+export { type AnyCatalog, type Binding, type Catalog, type ComponentDefinition, type ComponentSchema, DEFAULT_LIMITS, DEFAULT_REF_DESCRIPTION, defineCatalog, type FoundBinding, isBinding, type Limits, type ResolvedTree, type ResolvedTreeElement, type Tree, type TreeElement, type TreeNode, } from "./catalog.js";
+export type { TreeSchemaOptions } from "./json-schema.js";
+export type { ReadTreeOptions, ResolvedTreeResult, TreeIssue, TreeIssueCode, TreeRead, TreeResult, } from "./tree.js";
+export { type UseTreeOptions, useTree } from "./use-tree.js";
+/** What the model writes: its schema, a whole call checked, a partial one read, and issues worded for the model. */
+export declare const tree: {
+    schema: <C extends import("./catalog.js").AnyCatalog, const Options extends import("./json-schema.js").TreeSchemaOptions = import("./json-schema.js").TreeSchemaOptions>(catalog: C, options?: Options) => import("./json-schema.js").TreeSchema<Options extends {
+        single: true;
+    } ? import("./catalog.js").ComponentInput<C> : import("./catalog.js").TreeInput<C>>;
+    validate: <C extends import("./catalog.js").AnyCatalog>(input: unknown, catalog: C) => Promise<import("./tree.js").TreeResult<C>>;
+    read: <C extends import("./catalog.js").AnyCatalog>(input: unknown, catalog: C, options?: import("./tree.js").ReadTreeOptions) => import("./tree.js").TreeRead<C>;
+    formatIssues: (issues: readonly import("./tree.js").TreeIssue[], max?: number) => string;
+};
+/** Data by reference: the bindings in a tree, and the tree with their data in place. */
+export declare const bindings: {
+    find: <C extends import("./catalog.js").AnyCatalog>(tree: import("./catalog.js").Tree<C>) => import("./catalog.js").FoundBinding[];
+    resolve: <C extends import("./catalog.js").AnyCatalog>(tree: import("./catalog.js").Tree<C>, catalog: C, resolve: (binding: import("./catalog.js").FoundBinding) => unknown | Promise<unknown>) => Promise<import("./tree.js").ResolvedTreeResult<C>>;
+};
+/** A tree as Markdown, and the helpers that keep text the model wrote literal in it. */
+export declare const markdown: {
+    tree: <C extends import("./catalog.js").AnyCatalog>(tree: import("./catalog.js").Tree<C>, catalog: C) => string;
+    text: (text: string) => string;
+    paragraph: (text: string) => string;
+    heading: (level: number, text: string) => string;
+    table: (header: readonly string[], rows: readonly (readonly unknown[])[]) => string;
+};

package/dist/generative/index.js

@@ -0,0 +1,20 @@
+// Public surface of @intentface/ui/generative. Experimental: it may change or
+// be removed before 1.0. No directive, so the helpers stay importable on a
+// server; the hook arrives there as a client reference.
+import { treeSchema } from "./json-schema.js";
+import { markdownHeading, markdownParagraph, markdownTable, markdownText, toMarkdown, } from "./markdown.js";
+import { findBindings, formatIssues, readTree, resolveBindings, validateTree } from "./tree.js";
+export { DEFAULT_LIMITS, DEFAULT_REF_DESCRIPTION, defineCatalog, isBinding, } from "./catalog.js";
+export { useTree } from "./use-tree.js";
+/** What the model writes: its schema, a whole call checked, a partial one read, and issues worded for the model. */
+export const tree = { schema: treeSchema, validate: validateTree, read: readTree, formatIssues };
+/** Data by reference: the bindings in a tree, and the tree with their data in place. */
+export const bindings = { find: findBindings, resolve: resolveBindings };
+/** A tree as Markdown, and the helpers that keep text the model wrote literal in it. */
+export const markdown = {
+    tree: toMarkdown,
+    text: markdownText,
+    paragraph: markdownParagraph,
+    heading: markdownHeading,
+    table: markdownTable,
+};

package/dist/generative/json-schema.d.ts

@@ -0,0 +1,45 @@
+import type { StandardSchema } from "../internal/standard-schema.js";
+import { type AnyCatalog, type AnyComponent, type ComponentInput, type JsonObject, type TreeInput } from "./catalog.js";
+export type TreeSchemaOptions = {
+    /** The model writes one component as `{ type, props }` instead of a tree. */
+    single?: boolean;
+};
+/** The JSON Schema of a tool's input: always an object. */
+type ObjectSchema = {
+    type: "object";
+    properties: JsonObject;
+    required: string[];
+    additionalProperties: false;
+};
+/**
+ * The tool's input schema: plain JSON Schema, which any model SDK takes as is,
+ * carrying a typed Standard Schema the AI SDK infers the tool's input from.
+ */
+export type TreeSchema<Input> = ObjectSchema & {
+    readonly "~standard": StandardSchema<Input>["~standard"] & {
+        readonly jsonSchema: {
+            readonly input: (options: {
+                readonly target: string;
+            }) => ObjectSchema;
+            readonly output: (options: {
+                readonly target: string;
+            }) => ObjectSchema;
+        };
+    };
+};
+/** What the model writes under a schema built with these options. */
+type InputOf<C extends AnyCatalog, Options extends TreeSchemaOptions> = Options extends {
+    single: true;
+} ? ComponentInput<C> : TreeInput<C>;
+/**
+ * The tool's input schema, typed as what the model writes, so an AI SDK tool
+ * infers its input. It passes the call through as written: `tree.validate`
+ * checks it, so the issues reach the model as the tool's result. Pass it as is:
+ * a spread copy loses the Standard Schema.
+ */
+export declare const treeSchema: <C extends AnyCatalog, const Options extends TreeSchemaOptions = TreeSchemaOptions>(catalog: C, options?: Options) => TreeSchema<InputOf<C, Options>>;
+/** A component's props as JSON Schema, or `null` when its schema can't convert. */
+export declare const jsonSchemaOf: (definition: AnyComponent) => JsonObject | null;
+/** A strict schema's nulls read back as absent, where the component's own schema has no null. */
+export declare const dropNulls: (value: unknown, schema: unknown) => unknown;
+export {};

package/dist/generative/json-schema.js

@@ -0,0 +1,216 @@
+// The tool's input schema: each component's own JSON Schema, made strict for
+// structured-output modes, and the nulls that strictness adds read back out.
+import { DEFAULT_REF_DESCRIPTION, isBinding, isObject, limitsOf, } from "./catalog.js";
+/**
+ * The tool's input schema, typed as what the model writes, so an AI SDK tool
+ * infers its input. It passes the call through as written: `tree.validate`
+ * checks it, so the issues reach the model as the tool's result. Pass it as is:
+ * a spread copy loses the Standard Schema.
+ */
+export const treeSchema = (catalog, options) => {
+    // Built now, so a component schema that can't convert throws here.
+    const schema = toJSONSchema(catalog, options);
+    const jsonSchema = ({ target }) => {
+        if (target !== "draft-07")
+            throw new Error(`tree.schema converts to draft-07, not ${target}.`);
+        return schema;
+    };
+    const standard = {
+        version: 1,
+        vendor: "intentface",
+        validate: (value) => ({ value: value }),
+        jsonSchema: { input: jsonSchema, output: jsonSchema },
+    };
+    // Not enumerable, so an SDK that sends the schema as JSON leaves it out; the AI SDK still finds it.
+    return Object.defineProperty(schema, "~standard", { value: standard });
+};
+/**
+ * The schema itself, built from each component's own. Strict, for
+ * structured-output modes: every object closed, every property required, and
+ * optional props nullable. `tree.validate` reads the nulls back as absent.
+ */
+const toJSONSchema = (catalog, options = {}) => {
+    const limits = limitsOf(catalog);
+    const refDescription = catalog.refDescription ?? DEFAULT_REF_DESCRIPTION;
+    const components = Object.entries(catalog.components);
+    const types = components.map(([type]) => type);
+    const propsOf = (type, definition) => strict(withBindings(requireJsonSchema(type, definition), definition, refDescription));
+    if (options.single) {
+        return {
+            type: "object",
+            properties: {
+                type: { type: "string", enum: types, description: "Which component to show." },
+                props: {
+                    anyOf: components.map(([type, definition]) => ({
+                        ...propsOf(type, definition),
+                        description: `Props for ${type}: ${definition.description}`,
+                    })),
+                },
+            },
+            required: ["type", "props"],
+            additionalProperties: false,
+        };
+    }
+    const element = ([type, definition]) => {
+        const children = {
+            type: "array",
+            items: { type: "string" },
+            maxItems: limits.children,
+            description: "The ids of the elements inside, in order.",
+        };
+        return {
+            type: "object",
+            description: definition.description,
+            properties: {
+                id: { type: "string", description: "Unique within the call." },
+                type: { type: "string", enum: [type] },
+                props: propsOf(type, definition),
+                ...(definition.container ? { children } : {}),
+            },
+            required: ["id", "type", "props", ...(definition.container ? ["children"] : [])],
+            additionalProperties: false,
+        };
+    };
+    return {
+        type: "object",
+        properties: {
+            root: { type: "string", description: "The id of the element at the top." },
+            elements: {
+                type: "array",
+                maxItems: limits.nodes,
+                description: "Every element, each with its own id. Containers list their children by id.",
+                items: { anyOf: components.map(element) },
+            },
+        },
+        required: ["root", "elements"],
+        additionalProperties: false,
+    };
+};
+const conversions = new WeakMap();
+/** A schema as JSON Schema, converted once; the conversion's error when it can't. */
+const convert = (schema) => {
+    let converted = conversions.get(schema);
+    if (!converted) {
+        try {
+            converted = schema["~standard"].jsonSchema.input({ target: "draft-07" });
+        }
+        catch (error) {
+            converted = error instanceof Error ? error : new Error(String(error));
+        }
+        conversions.set(schema, converted);
+    }
+    return converted;
+};
+/** A component's props as JSON Schema, or `null` when its schema can't convert. */
+export const jsonSchemaOf = (definition) => {
+    const converted = convert(definition.props);
+    return converted instanceof Error ? null : converted;
+};
+/** The JSON Schema the model is shown. A conversion's own error comes through. */
+const requireJsonSchema = (type, definition) => {
+    // Typed as required, but a JavaScript caller can still pass an older validator.
+    if (!definition.props["~standard"].jsonSchema) {
+        throw new Error(`"${type}" needs a schema that converts to JSON Schema: zod 4.2+, ArkType 2.1.28+, or Valibot through toStandardJsonSchema.`);
+    }
+    const schema = convert(definition.props);
+    if (schema instanceof Error)
+        throw schema;
+    if (JSON.stringify(schema).includes('"$ref"')) {
+        throw new Error(`"${type}" uses $ref in its JSON Schema, which isn't supported yet.`);
+    }
+    return schema;
+};
+const bindingSchema = (refDescription) => ({
+    type: "object",
+    description: "Data by reference instead of written out: a tool result's ref, and what to pick.",
+    properties: {
+        $data: { type: "string", description: refDescription },
+        columns: {
+            type: "array",
+            items: { type: "string" },
+            description: "Columns to pick from each row, in order, for a list of rows.",
+        },
+        column: { type: "string", description: "One column to pick from each row." },
+    },
+    required: ["$data"],
+    additionalProperties: false,
+});
+const withBindings = (schema, definition, refDescription) => {
+    if (!definition.bind?.length || !isObject(schema.properties))
+        return schema;
+    const properties = { ...schema.properties };
+    for (const key of definition.bind) {
+        if (key in properties) {
+            properties[key] = { anyOf: [properties[key], bindingSchema(refDescription)] };
+        }
+    }
+    return { ...schema, properties };
+};
+const SCHEMA_LISTS = new Set(["anyOf", "oneOf", "allOf", "prefixItems"]);
+const SCHEMA_SLOTS = new Set(["items", "not", "additionalProperties"]);
+const strict = (schema) => {
+    if (!isObject(schema))
+        return schema;
+    const next = {};
+    for (const [key, value] of Object.entries(schema)) {
+        switch (true) {
+            case key === "$schema":
+                break;
+            case key === "properties" && isObject(value):
+                next[key] = Object.fromEntries(Object.entries(value).map(([name, property]) => [name, strict(property)]));
+                break;
+            case SCHEMA_LISTS.has(key) && Array.isArray(value):
+                next[key] = value.map(strict);
+                break;
+            case SCHEMA_SLOTS.has(key) && isObject(value):
+                next[key] = strict(value);
+                break;
+            default:
+                next[key] = value;
+        }
+    }
+    if (isObject(next.properties)) {
+        const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+        const properties = Object.fromEntries(Object.entries(next.properties).map(([name, property]) => [
+            name,
+            required.has(name) ? property : nullable(property),
+        ]));
+        next.properties = properties;
+        next.required = Object.keys(properties);
+        next.additionalProperties = false;
+    }
+    return next;
+};
+const nullable = (schema) => 
+// An enum or a const still pins the value, so only the anyOf form lets null through.
+isObject(schema) && typeof schema.type === "string" && !("enum" in schema) && !("const" in schema)
+    ? { ...schema, type: [schema.type, "null"] }
+    : { anyOf: [schema, { type: "null" }] };
+const allowsNull = (schema) => isObject(schema) &&
+    (schema.type === "null" ||
+        (Array.isArray(schema.type) && schema.type.includes("null")) ||
+        schema.const === null ||
+        (Array.isArray(schema.enum) && schema.enum.includes(null)) ||
+        [schema.anyOf, schema.oneOf].some((branches) => Array.isArray(branches) && branches.some(allowsNull)));
+/** A strict schema's nulls read back as absent, where the component's own schema has no null. */
+export const dropNulls = (value, schema) => {
+    if (!isObject(schema))
+        return value;
+    if (Array.isArray(value))
+        return value.map((item) => dropNulls(item, schema.items));
+    if (!isObject(value) || !isObject(schema.properties))
+        return value;
+    const properties = schema.properties;
+    const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+    return Object.fromEntries(Object.entries(value).flatMap(([key, item]) => item === null && !required.has(key) && !allowsNull(properties[key])
+        ? []
+        : [
+            [
+                key,
+                // A binding's optional parts come back null in strict mode; none of them allow it.
+                isBinding(item)
+                    ? Object.fromEntries(Object.entries(item).filter(([, part]) => part !== null))
+                    : dropNulls(item, properties[key]),
+            ],
+        ]));
+};

package/dist/generative/markdown.d.ts

@@ -0,0 +1,21 @@
+import { type AnyCatalog, type Tree } from "./catalog.js";
+/**
+ * One line of literal text, for a label, a cell or a heading. A marker that
+ * would open a block is escaped, so it stays text on a line of its own too.
+ */
+export declare const markdownText: (text: string) => string;
+/**
+ * Literal text over several lines, such as a paragraph. A line that would open
+ * a block has its marker escaped, and indentation is dropped.
+ */
+export declare const markdownParagraph: (text: string) => string;
+/** A heading of literal text. A trailing `#` stays text. */
+export declare const markdownHeading: (level: number, text: string) => string;
+/** A GitHub-flavoured table. Every cell is literal text, so a pipe can't split a column. */
+export declare const markdownTable: (header: readonly string[], rows: readonly (readonly unknown[])[]) => string;
+/**
+ * A tree as Markdown, through each component's `markdown`. A container
+ * without one reads as its children. An element still holding a binding is
+ * left out: resolve the tree first.
+ */
+export declare const toMarkdown: <C extends AnyCatalog>(tree: Tree<C>, catalog: C) => string;

package/dist/generative/markdown.js

@@ -0,0 +1,76 @@
+// A tree as Markdown, and the escaping that keeps model-written text literal.
+import { componentOf, isBinding, isObject } from "./catalog.js";
+// ---------------------------------------------------------------------------
+// Markdown
+// ---------------------------------------------------------------------------
+//
+// Text from the model or a source must read as written: it may not format,
+// link, or break the structure around it. Links come only from the consumer.
+// What opens emphasis, code, a link or image, HTML, strikethrough or a table
+// cell; and `@`, which GFM turns into a mailto link.
+const INLINE = /[\\`*_[\]<>|~@]/g;
+// An entity reference (`&amp;`) would be decoded, so its ampersand is escaped.
+const ENTITY = /&(?=#?[a-zA-Z0-9]+;)/g;
+// GFM links bare addresses too; escaping the colon or the dot breaks the pattern.
+const SCHEME = /(https?|mailto|xmpp):/gi;
+const WWW = /\b(www)\./gi;
+const escapeCharacters = (text) => text
+    .replace(INLINE, "\\$&")
+    .replace(ENTITY, "\\&")
+    .replace(SCHEME, "$1\\:")
+    .replace(WWW, "$1\\.");
+// A lone `\r` ends a line in Markdown, the same as `\n`.
+const LINE_BREAK = /[\r\n]/;
+// Each run of whitespace is matched once, whole, so this stays linear on long runs.
+const oneLine = (text) => text.replace(/\s+/g, (run) => (LINE_BREAK.test(run) ? " " : run));
+// A marker that would open a block at a line's start: a heading, a list item,
+// a setext underline or a numbered item.
+const escapeBlockStart = (line) => line.replace(/^(\s*)([#+=-])/, "$1\\$2").replace(/^(\s*)(\d{1,9})([.)])/, "$1$2\\$3");
+/**
+ * One line of literal text, for a label, a cell or a heading. A marker that
+ * would open a block is escaped, so it stays text on a line of its own too.
+ */
+export const markdownText = (text) => escapeBlockStart(escapeCharacters(oneLine(text)));
+/**
+ * Literal text over several lines, such as a paragraph. A line that would open
+ * a block has its marker escaped, and indentation is dropped.
+ */
+export const markdownParagraph = (text) => text
+    .split(/\r\n?|\n/)
+    .map((line) => escapeBlockStart(escapeCharacters(line.trim())))
+    .join("\n");
+/** A heading of literal text. A trailing `#` stays text. */
+export const markdownHeading = (level, text) => `${"#".repeat(level)} ${markdownText(text).replace(/(^|\s)(#+)$/, "$1\\$2")}`;
+/** A GitHub-flavoured table. Every cell is literal text, so a pipe can't split a column. */
+export const markdownTable = (header, rows) => {
+    const line = (cells) => `| ${header.map((_, index) => markdownText(String(cells[index] ?? ""))).join(" | ")} |`;
+    return [line(header), `| ${header.map(() => "---").join(" | ")} |`, ...rows.map(line)].join("\n");
+};
+const hasBinding = (props) => isObject(props) && Object.values(props).some(isBinding);
+/**
+ * A tree as Markdown, through each component's `markdown`. A container
+ * without one reads as its children. An element still holding a binding is
+ * left out: resolve the tree first.
+ */
+export const toMarkdown = (tree, catalog) => {
+    // Each element writes once, so a cycle or a shared child in a stored tree stops at the first.
+    const written = new Set();
+    const write = (id) => {
+        const element = tree.elements[id];
+        if (!element || written.has(id) || hasBinding(element.props))
+            return "";
+        written.add(id);
+        const children = (element.children ?? [])
+            .map((child) => write(child))
+            .filter((block) => block.trim() !== "")
+            .join("\n\n");
+        const definition = componentOf(catalog, element.type);
+        // Typed per component in the catalog; the element's props are that component's.
+        if (definition?.markdown)
+            return definition.markdown(element.props, children);
+        if (definition?.container)
+            return children;
+        throw new Error(`"${element.type}" has no markdown.`);
+    };
+    return write(tree.root);
+};

package/dist/generative/tree.d.ts

@@ -0,0 +1,56 @@
+import { type AnyCatalog, type FoundBinding, type ResolvedTree, type Tree, type TreeNode } from "./catalog.js";
+export type TreeIssueCode = "invalid_input" | "missing_id" | "duplicate_id" | "duplicate_child" | "missing_root" | "root_not_found" | "unknown_type" | "unexpected_children" | "dangling_child" | "shared_child" | "cycle" | "too_deep" | "too_many_nodes" | "too_many_children" | "invalid_props" | "invalid_binding" | "unresolved_binding";
+/** One problem with a call, in words the model can act on. */
+export type TreeIssue = {
+    code: TreeIssueCode;
+    message: string;
+    path: (string | number)[];
+};
+type Result<Value> = {
+    value: Value;
+    issues?: undefined;
+} | {
+    value?: undefined;
+    issues: TreeIssue[];
+};
+/** A checked call, or what's wrong with it. */
+export type TreeResult<C extends AnyCatalog> = Result<Tree<C>>;
+/** A tree with its data in place, or what couldn't be resolved. */
+export type ResolvedTreeResult<C extends AnyCatalog> = Result<ResolvedTree<C>>;
+/** Issues as text for the model, one per line: where, then what's wrong. */
+export declare const formatIssues: (issues: readonly TreeIssue[], max?: number) => string;
+/** Every binding in a tree, for the host to resolve. */
+export declare const findBindings: <C extends AnyCatalog>(tree: Tree<C>) => FoundBinding[];
+/**
+ * The tree with every binding replaced by its data, each element validated
+ * again with the data in place. `resolve` returns what a ref names, such as a
+ * tool result's rows, and may fetch it; the binding's columns are picked from
+ * it. `undefined` means not found.
+ */
+export declare const resolveBindings: <C extends AnyCatalog>(tree: Tree<C>, catalog: C, resolve: (binding: FoundBinding) => unknown | Promise<unknown>) => Promise<ResolvedTreeResult<C>>;
+/**
+ * A whole call checked against the catalog: its shape read as meant, its
+ * structure and limits checked, and each element's props validated. Issues
+ * name the field, so `tree.formatIssues` can send them straight back to the model.
+ */
+export declare const validateTree: <C extends AnyCatalog>(input: unknown, catalog: C) => Promise<TreeResult<C>>;
+export type ReadTreeOptions = {
+    /**
+     * Returns what a ref names from data already at hand, such as a tool
+     * result's rows among the message's parts; the binding's columns are picked
+     * from it. It answers within a render, so `undefined`, or a promise, keeps
+     * the node pending.
+     */
+    resolve?: (binding: FoundBinding) => unknown;
+};
+/** The root node, once there is one to draw. */
+export type TreeRead<C extends AnyCatalog> = {
+    root?: TreeNode<C>;
+};
+/**
+ * Partial or whole input as nodes to draw, without throwing. A node whose type
+ * isn't known yet is skipped; one whose props don't validate yet, or whose
+ * data isn't resolved, is pending.
+ */
+export declare const readTree: <C extends AnyCatalog>(input: unknown, catalog: C, options?: ReadTreeOptions) => TreeRead<C>;
+export {};