cortena-ui 1.3.0 → 1.4.0

package/README.md

@@ -8,6 +8,66 @@ with the tokens, from this repo's `packages/ui`.
 Intent and decisions: `cortena-docs/cortenaUI&Design/02-ui-components.md`.
 Consuming it: `../../CONSUMING.md`, section "cortena-ui".
 
+## Entry points
+
+The root barrel is the convenient path and exports everything:
+
+```tsx
+import { Button, DataTable, Chart } from "cortena-ui";
+```
+
+It tree-shakes. `"sideEffects": false` for JavaScript, no component module runs
+anything at import time, and the build is unbundled — `dist` keeps `src`'s
+module graph one-for-one rather than flattening it into chunks a bundler has to
+unpick. An app importing only `Button` carries **37.7 kB** of cortena-ui and its
+dependencies, React excluded; on 1.3.1 the same import carried 2,479 kB.
+
+For a size-critical bundle — an MCP app inlined into a single HTML file, a
+widget with a hard cap — import the area entry and do not depend on the
+consumer's bundler getting tree-shaking right:
+
+| entry | what it holds | what it costs |
+| --- | --- | --- |
+| `cortena-ui/core` | primitives, overlays, light form controls, `cn`, `useCortenaTheme` | nothing heavy |
+| `cortena-ui/form` | `Form`, `useForm`, `zodResolver`, date pickers, `Dropzone` | react-hook-form, zod, react-day-picker, react-dropzone |
+| `cortena-ui/data-table` | `DataTable` and its parts | TanStack Table and Virtual; exceljs on the first export |
+| `cortena-ui/chart` | `Chart`, themed Recharts primitives | an engine on the first chart drawn, not on import |
+| `cortena-ui/markdown` | `Markdown` | react-markdown, remark-gfm, rehype-sanitize |
+| `cortena-ui/a2ui` | the A2UI catalogue and renderer | most of the package, by design |
+| `cortena-ui/sortable-list` | `SortableList`, `SortableHandle`, `arrayMove` | dnd-kit |
+
+Each component has exactly one home, so the barrel re-exports every entry
+without an ambiguous name. **Adding a component means adding it to its area
+entry in `src/entries/`, not to `src/index.ts`.**
+
+`SortableList` has its own entry for a specific reason rather than a stylistic
+one: `@dnd-kit/core` and `@dnd-kit/sortable` declare no `"sideEffects"` in their
+package.json, so a bundler must assume importing them does something observable
+and keeps them whether or not anything is used. Every other dependency here
+declares itself side-effect free and shakes out on its own.
+
+Measured numbers, and how to re-measure them, are in `../../CONSUMING.md`,
+"Bundle size". `pnpm bundle:probe` prints the table.
+
+## Keeping it tree-shakeable
+
+The whole thing turns on one property: **no module-level statement may do work
+a bundler cannot skip.** It is easy to break by accident and produces no error
+when broken — the app builds, renders and passes its tests at five times the
+size — so two things guard it.
+
+- `src/lib/shakeable.ts`, for a module-scope constant built by a call whose
+  *arguments* contain calls: `tableFeatures({ filteredRowModel: createFilteredRowModel() })`,
+  a `z.enum(...).describe(...)` chain, `Object.freeze` over a spread. A bundler
+  evaluates arguments even when the call around them is annotated pure, so the
+  work goes behind a thunk and the thunk call is annotated instead. Nothing is
+  deferred at runtime; only the bundler sees a difference.
+- A bare `/* @__PURE__ */` where the arguments are literals: `cva(...)`,
+  `cn(...)`, `React.createContext(...)`.
+
+`test/bundle-probe.test.mjs` builds real consumer apps and fails on a
+regression; `test/chart-bundle.test.tsx` says which line caused it.
+
 ## Rules for components in this package
 
 - **Every visual value is a token.** `pnpm lint:design` runs the same
@@ -115,7 +175,9 @@ from `@a2ui/*` is installed, so `vitest.config.ts` has no entry for it.
 pnpm check        # types
 pnpm lint:design  # no literals where a token exists; no dangling var()
 pnpm build        # dist/ via tsdown (ESM + d.ts); also runs on prepack
-pnpm test         # Vitest browser mode, chromium light + dark
+pnpm test         # the browser suite, then the bundle budgets
+pnpm test:bundle  # bundle budgets alone (builds first, then real Vite apps)
+pnpm bundle:probe # the size table, printed, without asserting anything
 pnpm guide        # three-theme guide on a local Vite server
 pnpm a2ui:catalogue  # dist-a2ui/catalogue.json + .md from the A2UI catalogue
 ```
@@ -125,20 +187,29 @@ From the repo root the same are `pnpm ui:check`, `ui:build`, `ui:test`, `ui:guid
 ## Layout
 
 ```
-src/index.ts          public surface; add an export per component
+src/index.ts          the barrel: a union of the area entries, nothing else
+src/entries/*.ts      the area entries behind the subpaths; a component's
+                      export line goes in exactly one of them
 src/components/*.tsx  one file per component, shadcn shape, Base UI primitives
 src/a2ui/             A2UI catalogue, React renderer and doc generator
 src/lib/cn.ts         clsx + tailwind-merge
+src/lib/shakeable.ts  the thunk that keeps module-scope work tree-shakeable
 src/styles/index.css  what consumers import after the tokens: animation
                       utilities and the Base UI data-attribute variants
+scripts/bundle-probe.mjs  builds a consumer app per entry and weighs it
 test/                 browser tests; setup.css is the consumer recipe verbatim
+                      *.test.mjs are the Node-side bundle budgets
 guide/                Vite app: ?theme=light|dark|system frames, or all three
 ```
 
 ## Releasing
 
 ```bash
-pnpm ui:check && pnpm ui:test
+pnpm ui:check && pnpm ui:test        # browser suite, then the bundle budgets
 cd packages/ui && npm version minor && npm publish   # prepack builds dist/
 git push --follow-tags
 ```
+
+If the bundle numbers moved, re-run `pnpm bundle:probe` and update the table in
+`../../CONSUMING.md`. A size regression is not a cosmetic detail here: the MCP
+app documents travel inside a tool result and are capped at 512 kB.

package/dist/a2ui/catalogue-doc.d.ts

@@ -0,0 +1,44 @@
+"use client";
+import { A2UIComponentSpec } from "./message.js";
+import { A2UICatalogue, A2UIGroup } from "./catalogue.js";
+//#region src/a2ui/catalogue-doc.d.ts
+/** A JSON Schema object, as far as this module cares. */
+export type JsonSchema = Record<string, unknown>;
+export interface A2UIComponentDoc {
+  name: string;
+  group: A2UIGroup;
+  summary: string;
+  /** Whether the component takes a `children` list. */
+  children: "none" | "many";
+  /** Event names the component raises through `onAction`. */
+  events: string[];
+  /** JSON Schema of the resolved properties, derived from the zod schema. */
+  props: JsonSchema;
+  /** Property names that must be present. */
+  required: string[];
+  /** A complete, renderable example: the components and any data they bind to. */
+  example: {
+    components: A2UIComponentSpec[];
+    data?: Record<string, unknown>;
+  };
+}
+export interface A2UICatalogueDoc {
+  catalogueId: string;
+  protocol: string;
+  generator: string;
+  components: A2UIComponentDoc[];
+}
+/** Build the machine-readable catalogue document. */
+export declare function buildCatalogueDoc(catalogue?: A2UICatalogue): A2UICatalogueDoc;
+/**
+ * Render the catalogue document as markdown.
+ *
+ * The output is written to be pasted into a system prompt: one table per
+ * component listing every property with its type, whether it is required and
+ * what it means, then a fenced example an agent can copy.
+ */
+export declare function catalogueMarkdown(doc?: A2UICatalogueDoc): string;
+/** Turn an entry's example into the messages an agent would actually send. */
+export declare function exampleMessages(component: A2UIComponentDoc): unknown[];
+//#endregion
+//# sourceMappingURL=catalogue-doc.d.ts.map

package/dist/a2ui/catalogue-doc.js

@@ -0,0 +1,169 @@
+"use client";
+import { A2UI_CATALOGUE_ID, defaultCatalogue } from "./catalogue.js";
+import { A2UI_VERSION } from "./message.js";
+import { z } from "zod";
+//#region src/a2ui/catalogue-doc.ts
+/**
+* Catalogue documentation generator.
+*
+* Emits a machine-readable description of the catalogue — every component's
+* name, group, summary, property schema, events and a worked example — plus a
+* markdown rendering of the same thing.
+*
+* This exists so the "Rich Content" system-prompt section can be *generated*
+* from the catalogue rather than written beside it (DESIGN-34). A prompt that
+* describes a component the renderer does not have, or omits one it does, is
+* the failure `05-agent-ui.md` calls out; the only way to prevent it is for
+* both to come from one object.
+*
+* `pnpm a2ui:catalogue` writes `dist-a2ui/catalogue.json` and `.md`.
+*/
+/**
+* zod 4 ships `toJSONSchema`; zod 3 does not.
+*
+* The package's zod peer allows both, so this is checked rather than assumed —
+* emitting `{}` for every component would produce a doc that passes every test
+* and teaches an agent nothing, which is the silent-success failure this whole
+* package's lint exists to avoid.
+*/
+function toJsonSchema(schema) {
+	const converter = z.toJSONSchema;
+	if (typeof converter !== "function") throw new Error("Generating the A2UI catalogue doc needs zod 4 (z.toJSONSchema). The installed zod is 3.x.");
+	return converter(schema, {
+		io: "input",
+		unrepresentable: "any"
+	});
+}
+/** Build the machine-readable catalogue document. */
+function buildCatalogueDoc(catalogue = defaultCatalogue) {
+	const components = Object.values(catalogue).map((entry) => {
+		const schema = toJsonSchema(entry.props);
+		const properties = schema.properties ?? {};
+		const required = Array.isArray(schema.required) ? schema.required : [];
+		return {
+			name: entry.name,
+			group: entry.group,
+			summary: entry.summary,
+			children: entry.children,
+			events: [...entry.events],
+			props: properties,
+			required,
+			example: {
+				components: entry.example.components,
+				...entry.example.data ? { data: entry.example.data } : {}
+			}
+		};
+	}).sort((a, b) => a.name.localeCompare(b.name));
+	return {
+		catalogueId: A2UI_CATALOGUE_ID,
+		protocol: A2UI_VERSION,
+		generator: "cortena-ui/a2ui",
+		components
+	};
+}
+const GROUP_ORDER = [
+	"layout",
+	"text",
+	"input",
+	"feedback",
+	"data"
+];
+const GROUP_TITLE = {
+	layout: "Layout",
+	text: "Text and media",
+	input: "Inputs and actions",
+	feedback: "Feedback",
+	data: "Data"
+};
+/** One-line type summary for a JSON Schema property, for the markdown table. */
+function describeType(schema) {
+	if (typeof schema !== "object" || schema === null) return "any";
+	const node = schema;
+	if (Array.isArray(node.enum)) return node.enum.map((value) => JSON.stringify(value)).join(" \\| ");
+	if (Array.isArray(node.anyOf) || Array.isArray(node.oneOf)) return (node.anyOf ?? node.oneOf).map((option) => describeType(option)).join(" \\| ");
+	if (node.const !== void 0) return JSON.stringify(node.const);
+	if (node.type === "array") return `${describeType(node.items)}[]`;
+	if (typeof node.type === "string") return node.type;
+	if (Array.isArray(node.type)) return node.type.join(" \\| ");
+	return "any";
+}
+function escapeCell(text) {
+	return text.replace(/\|/g, "\\|").replace(/\n+/g, " ").trim();
+}
+/**
+* Render the catalogue document as markdown.
+*
+* The output is written to be pasted into a system prompt: one table per
+* component listing every property with its type, whether it is required and
+* what it means, then a fenced example an agent can copy.
+*/
+function catalogueMarkdown(doc = buildCatalogueDoc()) {
+	const lines = [];
+	lines.push("# A2UI catalogue — cortena-ui");
+	lines.push("");
+	lines.push(`Protocol \`${doc.protocol}\`, catalogue \`${doc.catalogueId}\`. Generated from the catalogue definition in \`cortena-ui\`; do not edit by hand.`);
+	lines.push("");
+	lines.push("A surface is described by three message kinds: `createSurface` names it, `updateComponents` sends the component tree, `updateDataModel` sends the data those components bind to. Any property may be a literal or a `{ \"path\": \"/pointer\" }` binding into the data model. A component takes children through `children`, either a list of ids or `{ \"componentId\": \"…\", \"path\": \"/items\" }` to repeat one component per array item.");
+	lines.push("");
+	lines.push(`${doc.components.length} components:`);
+	lines.push("");
+	for (const group of GROUP_ORDER) {
+		const inGroup = doc.components.filter((component) => component.group === group);
+		if (inGroup.length === 0) continue;
+		lines.push(`## ${GROUP_TITLE[group]}`);
+		lines.push("");
+		for (const component of inGroup) {
+			lines.push(`### ${component.name}`);
+			lines.push("");
+			lines.push(component.summary);
+			lines.push("");
+			lines.push(`Children: ${component.children === "many" ? "yes" : "no"}. Events: ${component.events.length > 0 ? component.events.map((e) => `\`${e}\``).join(", ") : "none"}.`);
+			lines.push("");
+			const propertyNames = Object.keys(component.props);
+			if (propertyNames.length > 0) {
+				lines.push("| Property | Type | Required | Description |");
+				lines.push("| --- | --- | --- | --- |");
+				for (const name of propertyNames) {
+					const schema = component.props[name];
+					const description = typeof schema?.description === "string" ? schema.description : "";
+					lines.push(`| \`${name}\` | ${escapeCell(describeType(schema))} | ${component.required.includes(name) ? "yes" : "no"} | ${escapeCell(description)} |`);
+				}
+				lines.push("");
+			}
+			lines.push("```json");
+			lines.push(JSON.stringify(exampleMessages(component), null, 2));
+			lines.push("```");
+			lines.push("");
+		}
+	}
+	return `${lines.join("\n").trimEnd()}\n`;
+}
+/** Turn an entry's example into the messages an agent would actually send. */
+function exampleMessages(component) {
+	const messages = [{
+		version: "v0.9",
+		createSurface: {
+			surfaceId: "demo",
+			root: component.example.components[0]?.id ?? "root"
+		}
+	}, {
+		version: "v0.9",
+		updateComponents: {
+			surfaceId: "demo",
+			components: component.example.components
+		}
+	}];
+	if (component.example.data) messages.push({
+		version: "v0.9",
+		updateDataModel: {
+			surfaceId: "demo",
+			path: "/",
+			value: component.example.data
+		}
+	});
+	return messages;
+}
+//#endregion
+export { buildCatalogueDoc, catalogueMarkdown, exampleMessages };
+
+//# sourceMappingURL=catalogue-doc.js.map

package/dist/a2ui/catalogue-doc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalogue-doc.js","names":[],"sources":["../../src/a2ui/catalogue-doc.ts"],"sourcesContent":["/**\n * Catalogue documentation generator.\n *\n * Emits a machine-readable description of the catalogue — every component's\n * name, group, summary, property schema, events and a worked example — plus a\n * markdown rendering of the same thing.\n *\n * This exists so the \"Rich Content\" system-prompt section can be *generated*\n * from the catalogue rather than written beside it (DESIGN-34). A prompt that\n * describes a component the renderer does not have, or omits one it does, is\n * the failure `05-agent-ui.md` calls out; the only way to prevent it is for\n * both to come from one object.\n *\n * `pnpm a2ui:catalogue` writes `dist-a2ui/catalogue.json` and `.md`.\n */\n\nimport { z } from \"zod\";\nimport { A2UI_CATALOGUE_ID, defaultCatalogue, type A2UICatalogue, type A2UIGroup } from \"./catalogue\";\nimport { A2UI_VERSION, type A2UIComponentSpec } from \"./message\";\n\n/** A JSON Schema object, as far as this module cares. */\nexport type JsonSchema = Record<string, unknown>;\n\nexport interface A2UIComponentDoc {\n  name: string;\n  group: A2UIGroup;\n  summary: string;\n  /** Whether the component takes a `children` list. */\n  children: \"none\" | \"many\";\n  /** Event names the component raises through `onAction`. */\n  events: string[];\n  /** JSON Schema of the resolved properties, derived from the zod schema. */\n  props: JsonSchema;\n  /** Property names that must be present. */\n  required: string[];\n  /** A complete, renderable example: the components and any data they bind to. */\n  example: { components: A2UIComponentSpec[]; data?: Record<string, unknown> };\n}\n\nexport interface A2UICatalogueDoc {\n  catalogueId: string;\n  protocol: string;\n  generator: string;\n  components: A2UIComponentDoc[];\n}\n\n/**\n * zod 4 ships `toJSONSchema`; zod 3 does not.\n *\n * The package's zod peer allows both, so this is checked rather than assumed —\n * emitting `{}` for every component would produce a doc that passes every test\n * and teaches an agent nothing, which is the silent-success failure this whole\n * package's lint exists to avoid.\n */\nfunction toJsonSchema(schema: z.ZodType<unknown>): JsonSchema {\n  const converter = (z as unknown as { toJSONSchema?: (s: unknown, o?: unknown) => JsonSchema })\n    .toJSONSchema;\n  if (typeof converter !== \"function\") {\n    throw new Error(\n      \"Generating the A2UI catalogue doc needs zod 4 (z.toJSONSchema). The installed zod is 3.x.\",\n    );\n  }\n  return converter(schema, { io: \"input\", unrepresentable: \"any\" });\n}\n\n/** Build the machine-readable catalogue document. */\nexport function buildCatalogueDoc(catalogue: A2UICatalogue = defaultCatalogue): A2UICatalogueDoc {\n  const components = Object.values(catalogue)\n    .map((entry): A2UIComponentDoc => {\n      const schema = toJsonSchema(entry.props as unknown as z.ZodType<unknown>);\n      const properties = (schema.properties ?? {}) as JsonSchema;\n      const required = Array.isArray(schema.required) ? (schema.required as string[]) : [];\n      return {\n        name: entry.name,\n        group: entry.group,\n        summary: entry.summary,\n        children: entry.children,\n        events: [...entry.events],\n        props: properties,\n        required,\n        example: {\n          components: entry.example.components,\n          ...(entry.example.data ? { data: entry.example.data } : {}),\n        },\n      };\n    })\n    .sort((a, b) => a.name.localeCompare(b.name));\n\n  return {\n    catalogueId: A2UI_CATALOGUE_ID,\n    protocol: A2UI_VERSION,\n    generator: \"cortena-ui/a2ui\",\n    components,\n  };\n}\n\nconst GROUP_ORDER: A2UIGroup[] = [\"layout\", \"text\", \"input\", \"feedback\", \"data\"];\n\nconst GROUP_TITLE: Record<A2UIGroup, string> = {\n  layout: \"Layout\",\n  text: \"Text and media\",\n  input: \"Inputs and actions\",\n  feedback: \"Feedback\",\n  data: \"Data\",\n};\n\n/** One-line type summary for a JSON Schema property, for the markdown table. */\nfunction describeType(schema: unknown): string {\n  if (typeof schema !== \"object\" || schema === null) {\n    return \"any\";\n  }\n  const node = schema as JsonSchema;\n  if (Array.isArray(node.enum)) {\n    return node.enum.map((value) => JSON.stringify(value)).join(\" \\\\| \");\n  }\n  if (Array.isArray(node.anyOf) || Array.isArray(node.oneOf)) {\n    const options = (node.anyOf ?? node.oneOf) as unknown[];\n    return options.map((option) => describeType(option)).join(\" \\\\| \");\n  }\n  if (node.const !== undefined) {\n    return JSON.stringify(node.const);\n  }\n  if (node.type === \"array\") {\n    return `${describeType(node.items)}[]`;\n  }\n  if (typeof node.type === \"string\") {\n    return node.type;\n  }\n  if (Array.isArray(node.type)) {\n    return node.type.join(\" \\\\| \");\n  }\n  return \"any\";\n}\n\nfunction escapeCell(text: string): string {\n  return text.replace(/\\|/g, \"\\\\|\").replace(/\\n+/g, \" \").trim();\n}\n\n/**\n * Render the catalogue document as markdown.\n *\n * The output is written to be pasted into a system prompt: one table per\n * component listing every property with its type, whether it is required and\n * what it means, then a fenced example an agent can copy.\n */\nexport function catalogueMarkdown(doc: A2UICatalogueDoc = buildCatalogueDoc()): string {\n  const lines: string[] = [];\n  lines.push(\"# A2UI catalogue — cortena-ui\");\n  lines.push(\"\");\n  lines.push(\n    `Protocol \\`${doc.protocol}\\`, catalogue \\`${doc.catalogueId}\\`. Generated from the catalogue definition in \\`cortena-ui\\`; do not edit by hand.`,\n  );\n  lines.push(\"\");\n  lines.push(\n    \"A surface is described by three message kinds: `createSurface` names it, `updateComponents` sends the component tree, `updateDataModel` sends the data those components bind to. Any property may be a literal or a `{ \\\"path\\\": \\\"/pointer\\\" }` binding into the data model. A component takes children through `children`, either a list of ids or `{ \\\"componentId\\\": \\\"…\\\", \\\"path\\\": \\\"/items\\\" }` to repeat one component per array item.\",\n  );\n  lines.push(\"\");\n  lines.push(`${doc.components.length} components:`);\n  lines.push(\"\");\n\n  for (const group of GROUP_ORDER) {\n    const inGroup = doc.components.filter((component) => component.group === group);\n    if (inGroup.length === 0) {\n      continue;\n    }\n    lines.push(`## ${GROUP_TITLE[group]}`);\n    lines.push(\"\");\n    for (const component of inGroup) {\n      lines.push(`### ${component.name}`);\n      lines.push(\"\");\n      lines.push(component.summary);\n      lines.push(\"\");\n      lines.push(\n        `Children: ${component.children === \"many\" ? \"yes\" : \"no\"}. Events: ${\n          component.events.length > 0 ? component.events.map((e) => `\\`${e}\\``).join(\", \") : \"none\"\n        }.`,\n      );\n      lines.push(\"\");\n      const propertyNames = Object.keys(component.props);\n      if (propertyNames.length > 0) {\n        lines.push(\"| Property | Type | Required | Description |\");\n        lines.push(\"| --- | --- | --- | --- |\");\n        for (const name of propertyNames) {\n          const schema = component.props[name] as JsonSchema | undefined;\n          const description =\n            typeof schema?.description === \"string\" ? schema.description : \"\";\n          lines.push(\n            `| \\`${name}\\` | ${escapeCell(describeType(schema))} | ${\n              component.required.includes(name) ? \"yes\" : \"no\"\n            } | ${escapeCell(description)} |`,\n          );\n        }\n        lines.push(\"\");\n      }\n      lines.push(\"```json\");\n      lines.push(JSON.stringify(exampleMessages(component), null, 2));\n      lines.push(\"```\");\n      lines.push(\"\");\n    }\n  }\n  return `${lines.join(\"\\n\").trimEnd()}\\n`;\n}\n\n/** Turn an entry's example into the messages an agent would actually send. */\nexport function exampleMessages(component: A2UIComponentDoc): unknown[] {\n  const root = component.example.components[0]?.id ?? \"root\";\n  const messages: unknown[] = [\n    { version: \"v0.9\", createSurface: { surfaceId: \"demo\", root } },\n    { version: \"v0.9\", updateComponents: { surfaceId: \"demo\", components: component.example.components } },\n  ];\n  if (component.example.data) {\n    messages.push({\n      version: \"v0.9\",\n      updateDataModel: { surfaceId: \"demo\", path: \"/\", value: component.example.data },\n    });\n  }\n  return messages;\n}\n"],"mappings":"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"}

package/dist/a2ui/catalogue.d.ts

@@ -0,0 +1,44 @@
+"use client";
+import { A2UIComponentSpec } from "./message.js";
+import { A2UIView } from "./views.js";
+import { z } from "zod";
+//#region src/a2ui/catalogue.d.ts
+/** The five families the doc and the prompt group components by. */
+export type A2UIGroup = "layout" | "text" | "input" | "feedback" | "data";
+/** A ready-to-render example: the components, plus any data model they bind to. */
+export interface A2UIExample {
+  /** Components for this entry. The first is the one being demonstrated. */
+  components: A2UIComponentSpec[];
+  /** Seed data for `{ path }` bindings used by the example. */
+  data?: Record<string, unknown>;
+}
+export interface A2UICatalogueEntry<P = unknown> {
+  /** The name an agent writes in `component`. */
+  name: string;
+  group: A2UIGroup;
+  /** One sentence, used verbatim in the generated prompt section. */
+  summary: string;
+  /** Schema of the resolved properties. */
+  props: z.ZodType<P>;
+  /** Event names this component can raise through `onAction`. */
+  events: readonly string[];
+  /** `many` takes a `children` list; `none` ignores one. */
+  children: "none" | "many";
+  example: A2UIExample;
+  view: A2UIView<P>;
+}
+export type A2UICatalogue = Readonly<Record<string, A2UICatalogueEntry<never>>>;
+/**
+ * The catalogue an agent draws from, and the renderer's default.
+ *
+ * A host may narrow it (hand the renderer a subset) but should not widen it
+ * with components the prompt does not describe: an agent can only usefully
+ * emit what `catalogue-doc.ts` told it about.
+ */
+export declare const defaultCatalogue: A2UICatalogue;
+/** Catalogue id an agent may echo in `createSurface.catalogId`. */
+export declare const A2UI_CATALOGUE_ID = "https://cortena.ai/a2ui/catalogues/cortena-ui/v1.json";
+/** Every component name in the catalogue, sorted. */
+export declare function catalogueNames(catalogue?: A2UICatalogue): string[];
+//#endregion
+//# sourceMappingURL=catalogue.d.ts.map