@texuli/tools 0.0.0-stage → 0.1.0-next.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dailybot, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,34 @@
-# Temporary Holding Version
+# @texuli/tools
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Layer L7: tools.** Agent and developer tooling over the library: the
+copy-in CLI, the agent docs bundle, the A2UI adapter, custom elements, the
+golden set and the read-only MCP server. Private workspace package
+(`"private": true`), not published: every bin below runs inside this
+repository only.
+
+## What exists today
+
+Every area has source in `src/` and a unit test in `tests/`. All areas
+except the MCP server also have a doc in [`docs/`](docs/) and an exported
+subpath in `package.json`.
+
+| Area | Source | Subpath | Bin | What it does |
+| --- | --- | --- | --- | --- |
+| Copy-in CLI | `src/cli-add/` | `@texuli/tools/cli-add` | `texuli-add` | Copies styled component source into a consumer app with a provenance header. Never copies `@texuli/primitives`; local paths only. [Docs](docs/cli-add.md) |
+| Init and themes | `src/cli-init/` | `@texuli/tools/cli-init` | `texuli-init` | Wires tokens and CSS into a Vite, Astro or SvelteKit project, then lists, previews and applies themes from the theme library (210 themes). Local files only. [Docs](docs/cli-init.md) |
+| Update | `src/cli-update/` | `@texuli/tools/cli-update` | `texuli-update` | Updates a component copied with `texuli add` to new source by three-way merge: base from the provenance headers, the consumer's edits, the new upstream. [Docs](docs/cli-update.md) |
+| Agent docs bundle | `src/llms/` | `@texuli/tools/llms` | `texuli-llms` | Generates the llms.txt bundle and agent-facing docs from catalog manifests. [Docs](docs/llms.md) |
+| A2UI adapter (experimental) | `src/a2ui/` | `@texuli/tools/a2ui` | — | Converts between catalog trees and A2UI v0.9 server-to-client messages, on plain data only. [Docs](docs/a2ui.md) |
+| Custom elements | `src/elements/` | `@texuli/tools/elements` | — | Light-DOM custom elements that render catalog trees with the real content components, for hosts that do not use Svelte. [Docs](docs/elements.md) |
+| Golden set | `src/golden/` | `@texuli/tools/golden` | CLI source only: `src/golden/cli.ts`, not a registered bin | Thirty pre-registered interface tasks for agents, each with a reference tree, plus an offline scorer. [Docs](docs/golden.md) |
+| MCP server | `src/mcp/` | — | — | The read-only local stdio MCP server over the catalog and themes (`catalog`, `component`, `validate`, `example`, `theme` tools). Source and tests only: no export, no published binary. |
+
+The root entry (`@texuli/tools`) re-exports the A2UI, copy-in CLI, update
+and llms helpers.
+
+## Status
+
+Implemented and gated in this repository: unit tests per area, including
+`tests/mcp.test.ts`. Nothing is delivered outside it yet — no npm release
+and no published MCP binary
+([ARCHITECTURE](../../docs/ARCHITECTURE.md) tracks the delivery plan).

package/dist/a2ui/from-a2ui.d.ts

@@ -0,0 +1,35 @@
+import type { CatalogTreeInput } from '@texuli/catalog/render/renderer';
+import { type A2uiDiagnostic, type A2uiLimits } from './types.js';
+export interface FromA2uiOptions extends A2uiLimits {
+    /** The surface to read (default: the first one the messages name). */
+    surfaceId?: string;
+    /** When set, a `createSurface` naming another catalog fails the conversion. */
+    catalogId?: string;
+}
+export type FromA2uiResult = {
+    ok: true;
+    surfaceId: string;
+    /** From `createSurface`, when the messages include one. */
+    catalogId?: string;
+    /** The catalog tree's top-level nodes (empty after `deleteSurface`). */
+    roots: CatalogTreeInput[];
+    /** Components no path from `root` reaches; they are left out. */
+    unused: string[];
+} | {
+    ok: false;
+    diagnostics: A2uiDiagnostic[];
+};
+/**
+ * Convert untrusted A2UI v0.9 messages (one message or a list, already
+ * parsed from JSON) back into a catalog tree.
+ *
+ * The messages are checked against {@link A2UI_MESSAGE_SCHEMA} first. For
+ * the chosen surface, `updateComponents` messages upsert components by id;
+ * `deleteSurface` clears them; `updateDataModel` is ignored (catalog trees
+ * carry no data model). The tree is rebuilt from `root`. Missing children,
+ * cycles, a component used twice, data-bound child templates, bindings,
+ * prototype keys and size limits fail the conversion. Messages for other
+ * surfaces are ignored. Pass the result to `renderCatalogTree`, which applies
+ * the catalog's ids, tiers and prop schemas.
+ */
+export declare function a2uiToCatalogTree(input: unknown, options?: FromA2uiOptions): FromA2uiResult;

package/dist/a2ui/from-a2ui.js

@@ -0,0 +1,180 @@
+import { copyProps, isPlainRecord } from "./props.js";
+import { validateA2uiMessages } from "./schema.js";
+import { A2UI_RESERVED_KEYS, A2UI_ROOT_ID, A2UI_ROOTS_COMPONENT, } from "./types.js";
+function tooManyComponents(message, max) {
+    if (!isPlainRecord(message) || !isPlainRecord(message.updateComponents))
+        return false;
+    const { components } = message.updateComponents;
+    if (!Array.isArray(components) || components.length > max)
+        return Array.isArray(components);
+    return components.some((c) => isPlainRecord(c) && Array.isArray(c.children) && c.children.length > max);
+}
+function surfaceOf(message) {
+    if ('createSurface' in message)
+        return message.createSurface.surfaceId;
+    if ('updateComponents' in message)
+        return message.updateComponents.surfaceId;
+    if ('updateDataModel' in message)
+        return message.updateDataModel.surfaceId;
+    return message.deleteSurface.surfaceId;
+}
+/**
+ * Convert untrusted A2UI v0.9 messages (one message or a list, already
+ * parsed from JSON) back into a catalog tree.
+ *
+ * The messages are checked against {@link A2UI_MESSAGE_SCHEMA} first. For
+ * the chosen surface, `updateComponents` messages upsert components by id;
+ * `deleteSurface` clears them; `updateDataModel` is ignored (catalog trees
+ * carry no data model). The tree is rebuilt from `root`. Missing children,
+ * cycles, a component used twice, data-bound child templates, bindings,
+ * prototype keys and size limits fail the conversion. Messages for other
+ * surfaces are ignored. Pass the result to `renderCatalogTree`, which applies
+ * the catalog's ids, tiers and prop schemas.
+ */
+export function a2uiToCatalogTree(input, options = {}) {
+    const maxComponents = options.maxComponents ?? 1000;
+    const maxDepth = options.maxDepth ?? 64;
+    const list = Array.isArray(input) ? input : [input];
+    // Bound the work before the schema walks every item.
+    const oversized = list.length > maxComponents || list.some((m) => tooManyComponents(m, maxComponents));
+    if (oversized) {
+        return {
+            ok: false,
+            diagnostics: [
+                { code: 'limit', path: '$', message: `More than ${maxComponents} components or messages.` },
+            ],
+        };
+    }
+    const invalid = validateA2uiMessages(list);
+    if (invalid.length > 0)
+        return { ok: false, diagnostics: invalid };
+    const messages = list;
+    const surfaceId = options.surfaceId ?? (messages[0] ? surfaceOf(messages[0]) : undefined);
+    if (surfaceId === undefined) {
+        return { ok: false, diagnostics: [{ code: 'surface', path: '$', message: 'No messages.' }] };
+    }
+    const diagnostics = [];
+    const components = new Map();
+    let created = false;
+    let catalogId;
+    messages.forEach((message, i) => {
+        if (surfaceOf(message) !== surfaceId)
+            return;
+        if ('createSurface' in message) {
+            if (created) {
+                diagnostics.push({
+                    code: 'surface',
+                    path: `$[${i}]`,
+                    message: `Surface "${surfaceId}" is created twice without a deleteSurface between.`,
+                });
+            }
+            if (options.catalogId !== undefined &&
+                message.createSurface.catalogId !== options.catalogId) {
+                diagnostics.push({
+                    code: 'surface',
+                    path: `$[${i}].createSurface.catalogId`,
+                    message: `Expected catalog "${options.catalogId}".`,
+                });
+            }
+            created = true;
+            catalogId = message.createSurface.catalogId;
+        }
+        else if ('deleteSurface' in message) {
+            created = false;
+            components.clear();
+        }
+        else if ('updateComponents' in message) {
+            message.updateComponents.components.forEach((value, j) => {
+                components.set(value.id, { value, path: `$[${i}].updateComponents.components[${j}]` });
+            });
+            if (components.size > maxComponents) {
+                diagnostics.push({
+                    code: 'limit',
+                    path: `$[${i}]`,
+                    message: `More than ${maxComponents} components.`,
+                });
+            }
+        }
+    });
+    if (diagnostics.length > 0)
+        return { ok: false, diagnostics };
+    const base = { ok: true, surfaceId, ...(catalogId === undefined ? {} : { catalogId }) };
+    if (components.size === 0)
+        return { ...base, roots: [], unused: [] };
+    const used = new Set();
+    const onPath = new Set();
+    const build = (id, from, depth) => {
+        if (diagnostics.length >= 50)
+            return null;
+        const entry = components.get(id);
+        if (!entry) {
+            diagnostics.push(id === A2UI_ROOT_ID
+                ? { code: 'missing-root', path: from, message: 'No component has the id "root".' }
+                : { code: 'missing-child', path: from, message: `No component has the id "${id}".` });
+            return null;
+        }
+        if (onPath.has(id)) {
+            diagnostics.push({ code: 'cycle', path: from, message: `"${id}" contains itself.` });
+            return null;
+        }
+        if (used.has(id)) {
+            diagnostics.push({
+                code: 'shared-child',
+                path: from,
+                message: `"${id}" already has a parent; a tree uses each component once.`,
+            });
+            return null;
+        }
+        if (depth > maxDepth) {
+            diagnostics.push({
+                code: 'limit',
+                path: entry.path,
+                message: `Nesting deeper than ${maxDepth}.`,
+            });
+            return null;
+        }
+        const { value, path } = entry;
+        used.add(id);
+        if (value.component === A2UI_ROOTS_COMPONENT && depth > 1) {
+            diagnostics.push({
+                code: 'invalid-node',
+                path: `${path}.component`,
+                message: `"${A2UI_ROOTS_COMPONENT}" may only be the root.`,
+            });
+            return null;
+        }
+        if (value.children !== undefined && value.child !== undefined) {
+            diagnostics.push({
+                code: 'invalid-node',
+                path,
+                message: 'A component has "children" or "child", not both.',
+            });
+            return null;
+        }
+        if (value.children !== undefined && !Array.isArray(value.children)) {
+            diagnostics.push({
+                code: 'template-children',
+                path: `${path}.children`,
+                message: 'Data-bound child templates are not supported; list child ids.',
+            });
+            return null;
+        }
+        const props = copyProps(value, A2UI_RESERVED_KEYS, path, null, diagnostics);
+        const childIds = value.child !== undefined ? [value.child] : value.children;
+        onPath.add(id);
+        const children = childIds?.map((childId, k) => build(childId, value.child !== undefined ? `${path}.child` : `${path}.children[${k}]`, depth + 1));
+        onPath.delete(id);
+        const node = {
+            id: value.component,
+            ...(Object.keys(props).length > 0 ? { props } : {}),
+            ...(children ? { children: children.filter((c) => c !== null) } : {}),
+        };
+        return node;
+    };
+    const root = build(A2UI_ROOT_ID, '$', 1);
+    if (diagnostics.length > 0 || root === null)
+        return { ok: false, diagnostics };
+    const unused = [...components.keys()].filter((id) => !used.has(id)).sort();
+    const roots = root.id === A2UI_ROOTS_COMPONENT ? [...(root.children ?? [])] : [root];
+    return { ...base, roots, unused };
+}

package/dist/a2ui/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `@texuli/tools/a2ui` — experimental A2UI v0.9 adapter.
+ *
+ * Converts catalog trees to A2UI-shaped server-to-client messages and back,
+ * checked against a Texuli subset of the v0.9 message schema. Plain data
+ * only: no DOM, no network.
+ */
+export { a2uiToCatalogTree, type FromA2uiOptions, type FromA2uiResult } from './from-a2ui.js';
+export { A2UI_MESSAGE_SCHEMA, checkJsonSchema, type JsonSchema, validateA2uiMessages, } from './schema.js';
+export { catalogTreeToA2ui, type ToA2uiOptions, type ToA2uiResult } from './to-a2ui.js';
+export { A2UI_RESERVED_KEYS, A2UI_ROOT_ID, A2UI_ROOTS_COMPONENT, A2UI_VERSION, type A2uiChildList, type A2uiComponent, type A2uiCreateSurfaceMessage, type A2uiDeleteSurfaceMessage, type A2uiDiagnostic, type A2uiIssueCode, type A2uiLimits, type A2uiMessage, type A2uiUpdateComponentsMessage, type A2uiUpdateDataModelMessage, } from './types.js';

package/dist/a2ui/index.js

@@ -0,0 +1,11 @@
+/**
+ * `@texuli/tools/a2ui` — experimental A2UI v0.9 adapter.
+ *
+ * Converts catalog trees to A2UI-shaped server-to-client messages and back,
+ * checked against a Texuli subset of the v0.9 message schema. Plain data
+ * only: no DOM, no network.
+ */
+export { a2uiToCatalogTree } from "./from-a2ui.js";
+export { A2UI_MESSAGE_SCHEMA, checkJsonSchema, validateA2uiMessages, } from "./schema.js";
+export { catalogTreeToA2ui } from "./to-a2ui.js";
+export { A2UI_RESERVED_KEYS, A2UI_ROOT_ID, A2UI_ROOTS_COMPONENT, A2UI_VERSION, } from "./types.js";

package/dist/a2ui/props.d.ts

@@ -0,0 +1,10 @@
+import { type A2uiDiagnostic } from './types.js';
+/** A Texuli or A2UI component id: kebab-case, like the catalog renderer's. */
+export declare const COMPONENT_ID: RegExp;
+export declare function isPlainRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * Copy the props of one node into a fresh object, or report why they cannot
+ * travel: reserved structure keys, prototype keys, non-JSON values, and
+ * bindings or function calls (this adapter carries literals only).
+ */
+export declare function copyProps(source: Readonly<Record<string, unknown>>, skip: readonly string[], path: string, reservedCode: 'reserved-prop' | null, out: A2uiDiagnostic[]): Record<string, unknown>;

package/dist/a2ui/props.js

@@ -0,0 +1,94 @@
+import { A2UI_RESERVED_KEYS } from "./types.js";
+/** Keys that could reach an object's prototype when copied. */
+const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+/** A Texuli or A2UI component id: kebab-case, like the catalog renderer's. */
+export const COMPONENT_ID = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+export function isPlainRecord(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * Whether a prop value would mean something other than a literal to an A2UI
+ * client: a data binding (`{ path }`) or a function call (`{ call }`).
+ */
+function isDynamic(value) {
+    if (!isPlainRecord(value))
+        return false;
+    const keys = Object.keys(value);
+    return ((keys.length === 1 && typeof value.path === 'string') ||
+        (typeof value.call === 'string' &&
+            keys.every((k) => ['call', 'args', 'returnType'].includes(k))));
+}
+/** Check that `value` is plain JSON data with no prototype-reaching keys. */
+function checkJson(value, path, out) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return;
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            out.push({ code: 'not-json', path, message: 'Numbers must be finite.' });
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((item, i) => {
+            checkJson(item, `${path}[${i}]`, out);
+        });
+        return;
+    }
+    if (!isPlainRecord(value)) {
+        out.push({ code: 'not-json', path, message: `A ${typeof value} is not JSON data.` });
+        return;
+    }
+    for (const key of Object.keys(value)) {
+        if (UNSAFE_KEYS.has(key)) {
+            out.push({
+                code: 'unsafe-key',
+                path: `${path}.${key}`,
+                message: `"${key}" is never copied.`,
+            });
+        }
+        else {
+            checkJson(value[key], `${path}.${key}`, out);
+        }
+    }
+}
+/**
+ * Copy the props of one node into a fresh object, or report why they cannot
+ * travel: reserved structure keys, prototype keys, non-JSON values, and
+ * bindings or function calls (this adapter carries literals only).
+ */
+export function copyProps(source, skip, path, reservedCode, out) {
+    const props = {};
+    for (const key of Object.keys(source)) {
+        if (skip.includes(key))
+            continue;
+        const at = `${path}.${key}`;
+        if (UNSAFE_KEYS.has(key)) {
+            out.push({ code: 'unsafe-key', path: at, message: `"${key}" is never copied.` });
+            continue;
+        }
+        if (reservedCode && A2UI_RESERVED_KEYS.includes(key)) {
+            out.push({
+                code: reservedCode,
+                path: at,
+                message: `"${key}" is A2UI structure, so a prop cannot use that name.`,
+            });
+            continue;
+        }
+        const value = source[key];
+        if (isDynamic(value)) {
+            out.push({
+                code: 'binding',
+                path: at,
+                message: 'Data bindings and function calls are not supported; pass a literal value.',
+            });
+            continue;
+        }
+        const before = out.length;
+        checkJson(value, at, out);
+        if (out.length === before)
+            props[key] = structuredClone(value);
+    }
+    return props;
+}

package/dist/a2ui/schema.d.ts

@@ -0,0 +1,26 @@
+import { type A2uiDiagnostic } from './types.js';
+/** A JSON Schema document (the subset of keywords {@link checkJsonSchema} reads). */
+export type JsonSchema = {
+    readonly [keyword: string]: unknown;
+};
+/**
+ * The A2UI v0.9 server-to-client message schema, as Texuli checks it.
+ *
+ * A hand-written subset of the upstream `server_to_client.json` and
+ * `common_types.json` (`https://a2ui.org/specification/v0_9/`): the same four
+ * messages, required fields, `additionalProperties: false` and `ChildList`.
+ * Upstream leaves the component shape to the catalog; here a component is
+ * `id` plus a Texuli catalog id in `component`, with props beside them.
+ */
+export declare const A2UI_MESSAGE_SCHEMA: JsonSchema;
+/**
+ * Validate `value` against `schema`, resolving `#/$defs/*` refs in `root`.
+ *
+ * Reads only the keywords Texuli's schemas use: `$ref`, `type`, `const`,
+ * `enum`, `required`, `properties`, `additionalProperties`, `items`,
+ * `minItems`, `minLength`, `pattern`, `oneOf` and `anyOf`. Any other keyword
+ * is ignored, so this is not a general JSON Schema validator.
+ */
+export declare function checkJsonSchema(schema: JsonSchema, value: unknown, path?: string, root?: JsonSchema): A2uiDiagnostic[];
+/** Validate a list of A2UI messages against {@link A2UI_MESSAGE_SCHEMA}. */
+export declare function validateA2uiMessages(messages: unknown): A2uiDiagnostic[];

package/dist/a2ui/schema.js

@@ -0,0 +1,193 @@
+import { A2UI_VERSION } from "./types.js";
+const KEBAB_ID = '^[a-z][a-z0-9]*(-[a-z0-9]+)*$';
+const ref = (name) => ({ $ref: `#/$defs/${name}` });
+const message = (key, body) => ({
+    type: 'object',
+    required: ['version', key],
+    additionalProperties: false,
+    properties: { version: { const: A2UI_VERSION }, [key]: body },
+});
+/**
+ * The A2UI v0.9 server-to-client message schema, as Texuli checks it.
+ *
+ * A hand-written subset of the upstream `server_to_client.json` and
+ * `common_types.json` (`https://a2ui.org/specification/v0_9/`): the same four
+ * messages, required fields, `additionalProperties: false` and `ChildList`.
+ * Upstream leaves the component shape to the catalog; here a component is
+ * `id` plus a Texuli catalog id in `component`, with props beside them.
+ */
+export const A2UI_MESSAGE_SCHEMA = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $id: 'texuli:a2ui/v0.9/server-to-client',
+    title: 'A2UI v0.9 server-to-client message (Texuli catalog)',
+    oneOf: [
+        ref('CreateSurfaceMessage'),
+        ref('UpdateComponentsMessage'),
+        ref('UpdateDataModelMessage'),
+        ref('DeleteSurfaceMessage'),
+    ],
+    $defs: {
+        CreateSurfaceMessage: message('createSurface', {
+            type: 'object',
+            required: ['surfaceId', 'catalogId'],
+            additionalProperties: false,
+            properties: {
+                surfaceId: ref('SurfaceId'),
+                catalogId: { type: 'string', minLength: 1 },
+                theme: { type: 'object' },
+                sendDataModel: { type: 'boolean' },
+            },
+        }),
+        UpdateComponentsMessage: message('updateComponents', {
+            type: 'object',
+            required: ['surfaceId', 'components'],
+            additionalProperties: false,
+            properties: {
+                surfaceId: ref('SurfaceId'),
+                components: { type: 'array', minItems: 1, items: ref('AnyComponent') },
+            },
+        }),
+        UpdateDataModelMessage: message('updateDataModel', {
+            type: 'object',
+            required: ['surfaceId'],
+            additionalProperties: false,
+            properties: { surfaceId: ref('SurfaceId'), path: { type: 'string' }, value: {} },
+        }),
+        DeleteSurfaceMessage: message('deleteSurface', {
+            type: 'object',
+            required: ['surfaceId'],
+            additionalProperties: false,
+            properties: { surfaceId: ref('SurfaceId') },
+        }),
+        SurfaceId: { type: 'string', minLength: 1 },
+        ComponentId: { type: 'string', minLength: 1 },
+        ChildList: {
+            oneOf: [
+                { type: 'array', items: ref('ComponentId') },
+                {
+                    type: 'object',
+                    required: ['componentId', 'path'],
+                    additionalProperties: false,
+                    properties: { componentId: ref('ComponentId'), path: { type: 'string' } },
+                },
+            ],
+        },
+        AnyComponent: {
+            type: 'object',
+            required: ['id', 'component'],
+            properties: {
+                id: ref('ComponentId'),
+                component: { type: 'string', pattern: KEBAB_ID },
+                children: ref('ChildList'),
+                child: ref('ComponentId'),
+            },
+        },
+    },
+};
+function typeOf(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    if (typeof value === 'number')
+        return Number.isInteger(value) ? 'integer' : 'number';
+    return typeof value;
+}
+function typeMatches(actual, expected) {
+    const list = Array.isArray(expected) ? expected : [expected];
+    return list.some((t) => t === actual || (t === 'number' && actual === 'integer'));
+}
+const isRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const own = (record, key) => Object.hasOwn(record, key);
+/**
+ * Validate `value` against `schema`, resolving `#/$defs/*` refs in `root`.
+ *
+ * Reads only the keywords Texuli's schemas use: `$ref`, `type`, `const`,
+ * `enum`, `required`, `properties`, `additionalProperties`, `items`,
+ * `minItems`, `minLength`, `pattern`, `oneOf` and `anyOf`. Any other keyword
+ * is ignored, so this is not a general JSON Schema validator.
+ */
+export function checkJsonSchema(schema, value, path = '$', root = schema) {
+    const errors = [];
+    const fail = (at, text) => errors.push({ code: 'schema', path: at, message: text });
+    if (typeof schema.$ref === 'string') {
+        const name = schema.$ref.replace(/^#\/\$defs\//, '');
+        const defs = root.$defs;
+        const target = isRecord(defs) && own(defs, name) ? defs[name] : undefined;
+        if (!isRecord(target))
+            return [{ code: 'schema', path, message: `Unknown $ref ${schema.$ref}` }];
+        return checkJsonSchema(target, value, path, root);
+    }
+    if (schema.type !== undefined && !typeMatches(typeOf(value), schema.type)) {
+        fail(path, `Expected ${String(schema.type)}, got ${typeOf(value)}.`);
+        return errors;
+    }
+    if (own(schema, 'const') && value !== schema.const) {
+        fail(path, `Expected ${JSON.stringify(schema.const)}.`);
+    }
+    if (Array.isArray(schema.enum) && !schema.enum.includes(value)) {
+        fail(path, `Expected one of ${schema.enum.map((v) => JSON.stringify(v)).join(', ')}.`);
+    }
+    if (typeof value === 'string') {
+        if (typeof schema.minLength === 'number' && value.length < schema.minLength) {
+            fail(path, `Expected at least ${schema.minLength} characters.`);
+        }
+        if (typeof schema.pattern === 'string' && !new RegExp(schema.pattern, 'u').test(value)) {
+            fail(path, `Does not match ${schema.pattern}.`);
+        }
+    }
+    if (Array.isArray(value)) {
+        if (typeof schema.minItems === 'number' && value.length < schema.minItems) {
+            fail(path, `Expected at least ${schema.minItems} items.`);
+        }
+        if (isRecord(schema.items)) {
+            const items = schema.items;
+            value.forEach((item, i) => {
+                errors.push(...checkJsonSchema(items, item, `${path}[${i}]`, root));
+            });
+        }
+    }
+    if (isRecord(value)) {
+        const properties = isRecord(schema.properties) ? schema.properties : {};
+        if (Array.isArray(schema.required)) {
+            for (const key of schema.required) {
+                if (typeof key === 'string' && !own(value, key))
+                    fail(path, `Missing required "${key}".`);
+            }
+        }
+        for (const key of Object.keys(value)) {
+            const at = `${path}.${key}`;
+            const sub = own(properties, key) ? properties[key] : undefined;
+            if (isRecord(sub))
+                errors.push(...checkJsonSchema(sub, value[key], at, root));
+            else if (schema.additionalProperties === false)
+                fail(at, `Unexpected property "${key}".`);
+            else if (isRecord(schema.additionalProperties)) {
+                errors.push(...checkJsonSchema(schema.additionalProperties, value[key], at, root));
+            }
+        }
+    }
+    for (const keyword of ['oneOf', 'anyOf']) {
+        const branches = schema[keyword];
+        if (!Array.isArray(branches))
+            continue;
+        const results = branches.map((b) => (isRecord(b) ? checkJsonSchema(b, value, path, root) : []));
+        const passing = results.filter((r) => r.length === 0).length;
+        if (keyword === 'anyOf' ? passing === 0 : passing !== 1) {
+            // Report the closest branch so the message names the real problem.
+            const closest = results.reduce((best, r) => (r.length < best.length ? r : best));
+            if (passing > 1)
+                fail(path, 'Matches more than one oneOf branch.');
+            else
+                errors.push(...closest);
+        }
+    }
+    return errors;
+}
+/** Validate a list of A2UI messages against {@link A2UI_MESSAGE_SCHEMA}. */
+export function validateA2uiMessages(messages) {
+    if (!Array.isArray(messages)) {
+        return [{ code: 'schema', path: '$', message: 'Expected an array of A2UI messages.' }];
+    }
+    return messages.flatMap((m, i) => checkJsonSchema(A2UI_MESSAGE_SCHEMA, m, `$[${i}]`));
+}

package/dist/a2ui/to-a2ui.d.ts

@@ -0,0 +1,30 @@
+import type { CatalogTreeInput } from '@texuli/catalog/render/renderer';
+import { type A2uiDiagnostic, type A2uiLimits, type A2uiMessage } from './types.js';
+export interface ToA2uiOptions extends A2uiLimits {
+    /** The A2UI surface the components belong to. */
+    surfaceId: string;
+    /** The catalog the client resolves `component` ids in, e.g. `catalog-<sha256>.json`. */
+    catalogId: string;
+    /** Start with a `createSurface` message (default true). */
+    createSurface?: boolean;
+}
+export type ToA2uiResult = {
+    ok: true;
+    messages: A2uiMessage[];
+} | {
+    ok: false;
+    diagnostics: A2uiDiagnostic[];
+};
+/**
+ * Convert a catalog tree (one node or a list of roots) into A2UI v0.9
+ * messages: an optional `createSurface`, then one `updateComponents` whose
+ * flat component list references children by id.
+ *
+ * Ids are deterministic: the root is `root` and the rest are `n1`, `n2`… in
+ * the order they are visited. Zero or several roots are wrapped in a
+ * `texuli-roots` component. Props must be literal JSON; reserved names
+ * (`id`, `component`, `children`, `child`), prototype keys, bindings and
+ * function calls fail the conversion. The output is checked against
+ * {@link A2UI_MESSAGE_SCHEMA} before it is returned.
+ */
+export declare function catalogTreeToA2ui(tree: CatalogTreeInput | readonly CatalogTreeInput[], options: ToA2uiOptions): ToA2uiResult;