@lynx-js/genui 0.0.1 → 0.0.3

package/a2ui/docs/system-prompts.md

@@ -0,0 +1,187 @@
+# System prompts
+
+Generate and customize the system instructions that teach an LLM to emit valid A2UI messages.
+
+Generate a reusable prompt with the CLI for most deployments, or build one programmatically when the backend needs request-specific catalog or policy inputs. The prompt tells the model how to produce A2UI v0.9 JSON. It includes the protocol rules, the component catalog, function signatures, validated examples, and hard constraints that keep the renderer output safe and parseable.
+
+## 1. CLI
+
+Use `npx @lynx-js/genui a2ui generate prompt` when the backend only needs a static prompt file.
+
+Generate a prompt with the built-in A2UI basic catalog:
+
+```bash
+npx @lynx-js/genui a2ui generate prompt --out dist/a2ui-system-prompt.txt
+```
+
+Print the prompt to stdout:
+
+```bash
+npx @lynx-js/genui a2ui generate prompt
+```
+
+Append deployment-specific instructions:
+
+```bash
+npx @lynx-js/genui a2ui generate prompt \
+  --appendix "Prefer compact mobile layouts for travel booking flows." \
+  --out dist/a2ui-system-prompt.txt
+```
+
+`generate prompt` uses the built-in A2UI basic catalog by default. The generated prompt requires `createSurface.catalogId` to match the catalog id embedded in the prompt.
+
+### Custom catalogs
+
+For custom components, first generate catalog artifacts:
+
+```bash
+npx @lynx-js/genui a2ui generate catalog \
+  --catalog-dir src/catalog \
+  --source src/functions \
+  --out-dir dist
+```
+
+Then generate the prompt from those artifacts:
+
+```bash
+npx @lynx-js/genui a2ui generate prompt \
+  --catalog-dir dist \
+  --catalog-id https://example.com/catalogs/custom/v1/catalog.json \
+  --out dist/a2ui-system-prompt.txt
+```
+
+`--catalog-dir` must point at the generated catalog root. The prompt generator prefers a full catalog file such as `dist/catalog.json`, and falls back to component files such as `catalog/<Component>/catalog.json`.
+
+The package exposes the same commands through the `genui` binary after installation, so project scripts may use `genui a2ui ...` when `@lynx-js/genui` is already installed locally. Existing A2UI-only scripts may also use the `a2ui-cli` compatibility alias.
+
+## 2. Programmatic usage
+
+Use `@lynx-js/genui/a2ui-prompt` when the backend needs to construct prompts in Node.js code.
+
+Build the default prompt:
+
+```ts
+import { buildA2UISystemPrompt } from '@lynx-js/genui/a2ui-prompt';
+
+const systemPrompt = buildA2UISystemPrompt();
+```
+
+Add request- or deployment-specific instructions:
+
+```ts
+import { buildA2UISystemPrompt } from '@lynx-js/genui/a2ui-prompt';
+
+const systemPrompt = buildA2UISystemPrompt({
+  appendix: [
+    'Prefer concise mobile-first layouts.',
+    'When the user asks for charts, use LineChart only when numeric series are available.',
+  ].join('\n'),
+});
+```
+
+Read a generated custom catalog and build a prompt for it:
+
+```ts
+import {
+  buildA2UISystemPrompt,
+  readA2UICatalogFromDirectory,
+} from '@lynx-js/genui/a2ui-prompt';
+
+const catalog = readA2UICatalogFromDirectory({
+  catalogDir: 'dist/catalog',
+  catalogId: 'https://example.com/catalogs/custom/v1/catalog.json',
+  label: 'Example app catalog',
+  version: 'v1',
+});
+
+const systemPrompt = buildA2UISystemPrompt({ catalog });
+```
+
+For fully in-memory catalog construction, use `createA2UICatalogFromManifests(...)` with component JSON schemas and optional function specs, then pass the resulting catalog to `buildA2UISystemPrompt`.
+
+## What gets generated
+
+The generated prompt includes:
+
+- A2UI v0.9 protocol overview and design principles.
+- Required server-to-client message types: `createSurface`, `updateComponents`, `updateDataModel`, and `deleteSurface`.
+- Required message ordering for a fresh response.
+- Data binding rules for `{ "path": "/..." }` values and list children.
+- Client action rules for events and function calls.
+- A rendered catalog reference with component summaries, props, required fields, container shape, enum values, and function signatures.
+- Hard rules for JSON-only output, catalog id matching, flat component trees, `root` component requirements, button labels/actions, modal confirmation flows, image query handling, and action-response patches.
+- Validated examples from the catalog, when the catalog provides examples.
+- Optional appendix text supplied by the CLI or programmatic API.
+
+The model should return a JSON array of A2UI messages, not Markdown or prose:
+
+```json
+[
+  {
+    "version": "v0.9",
+    "createSurface": {
+      "surfaceId": "main",
+      "catalogId": "https://a2ui.org/specification/v0_9/basic_catalog.json"
+    }
+  },
+  {
+    "version": "v0.9",
+    "updateComponents": {
+      "surfaceId": "main",
+      "components": [
+        {
+          "id": "root",
+          "component": "Text",
+          "text": "Hello A2UI"
+        }
+      ]
+    }
+  }
+]
+```
+
+## Backend usage example
+
+The prompt can be used with any model provider that accepts a system message. The backend should send the system prompt before user messages and then parse or stream the model output as A2UI JSON.
+
+```ts
+import OpenAI from 'openai';
+import { buildA2UISystemPrompt } from '@lynx-js/genui/a2ui-prompt';
+
+const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+const systemPrompt = buildA2UISystemPrompt();
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+  const completion = await client.chat.completions.create({
+    model: process.env.OPENAI_MODEL ?? 'your-model',
+    stream: true,
+    messages: [
+      { role: 'system', content: systemPrompt },
+      ...messages,
+    ],
+  });
+
+  return new Response(completion.toReadableStream(), {
+    headers: { 'Content-Type': 'text/event-stream' },
+  });
+}
+```
+
+If the backend supports interactive A2UI actions, preserve the conversation history and pass client action messages back to the model. Action responses should update the existing surface with `updateDataModel` and/or `updateComponents` instead of creating a new surface.
+
+## Choosing an approach
+
+Use the CLI when:
+
+- The catalog changes at build time.
+- The backend can read a checked-in or generated prompt file.
+- Multiple services should share exactly the same prompt text.
+
+Use programmatic generation when:
+
+- The catalog, appendix, or safety policy changes per deployment or request.
+- The backend already loads generated catalog artifacts.
+- You need to compose custom `A2UICatalog` objects in code.
+
+For custom renderer catalogs and manifest generation, see [Catalogs and manifests](./catalog-guide.md).

package/a2ui/docs/system-prompts_zh.md

@@ -0,0 +1,187 @@
+# System Prompts
+
+生成和定制用于指导 LLM 输出合法 A2UI 消息的系统提示词。
+
+大多数部署场景可以用 CLI 生成一份可复用的 prompt 文件；如果后端需要按请求、环境或 catalog 动态拼装提示词，也可以在 Node.js 代码里通过 API 构建。生成的 prompt 会告诉模型如何输出 A2UI v0.9 JSON，内容包含协议规则、组件 catalog、函数签名、已验证示例，以及保证渲染输出安全、可解析的硬性约束。
+
+## 1. CLI
+
+如果后端只需要一份静态 prompt 文件，可以使用 `npx @lynx-js/genui a2ui generate prompt`。
+
+使用内置 A2UI basic catalog 生成 prompt：
+
+```bash
+npx @lynx-js/genui a2ui generate prompt --out dist/a2ui-system-prompt.txt
+```
+
+输出到 stdout：
+
+```bash
+npx @lynx-js/genui a2ui generate prompt
+```
+
+追加部署侧的额外指令：
+
+```bash
+npx @lynx-js/genui a2ui generate prompt \
+  --appendix "Prefer compact mobile layouts for travel booking flows." \
+  --out dist/a2ui-system-prompt.txt
+```
+
+默认情况下，`generate prompt` 会使用内置 A2UI basic catalog。生成出的 prompt 会要求 `createSurface.catalogId` 与 prompt 中的 catalog id 一致。
+
+### 自定义 catalog
+
+如果使用自定义组件，需要先生成 catalog 产物：
+
+```bash
+npx @lynx-js/genui a2ui generate catalog \
+  --catalog-dir src/catalog \
+  --source src/functions \
+  --out-dir dist
+```
+
+然后基于这些产物生成 prompt：
+
+```bash
+npx @lynx-js/genui a2ui generate prompt \
+  --catalog-dir dist \
+  --catalog-id https://example.com/catalogs/custom/v1/catalog.json \
+  --out dist/a2ui-system-prompt.txt
+```
+
+`--catalog-dir` 必须指向生成后的 catalog 根目录。prompt 生成器会优先读取完整 catalog 文件，例如 `dist/catalog.json`；如果不存在，再回退到 `catalog/<Component>/catalog.json`。
+
+安装 `@lynx-js/genui` 后，包内也会暴露同样的 `genui` 命令。因此项目脚本里可以使用 `genui a2ui ...`。已有的 A2UI-only 脚本也可以继续使用 `a2ui-cli` 兼容别名。
+
+## 2. 程序化用法
+
+当后端需要在 Node.js 代码中构建 prompt 时，可以使用 `@lynx-js/genui/a2ui-prompt`。
+
+构建默认 prompt：
+
+```ts
+import { buildA2UISystemPrompt } from '@lynx-js/genui/a2ui-prompt';
+
+const systemPrompt = buildA2UISystemPrompt();
+```
+
+追加请求级或部署级指令：
+
+```ts
+import { buildA2UISystemPrompt } from '@lynx-js/genui/a2ui-prompt';
+
+const systemPrompt = buildA2UISystemPrompt({
+  appendix: [
+    'Prefer concise mobile-first layouts.',
+    'When the user asks for charts, use LineChart only when numeric series are available.',
+  ].join('\n'),
+});
+```
+
+读取已生成的自定义 catalog，并为它构建 prompt：
+
+```ts
+import {
+  buildA2UISystemPrompt,
+  readA2UICatalogFromDirectory,
+} from '@lynx-js/genui/a2ui-prompt';
+
+const catalog = readA2UICatalogFromDirectory({
+  catalogDir: 'dist/catalog',
+  catalogId: 'https://example.com/catalogs/custom/v1/catalog.json',
+  label: 'Example app catalog',
+  version: 'v1',
+});
+
+const systemPrompt = buildA2UISystemPrompt({ catalog });
+```
+
+如果 catalog 已经在内存中，可以使用 `createA2UICatalogFromManifests(...)` 传入组件 JSON Schema 和可选函数定义，构建出 `A2UICatalog` 后再交给 `buildA2UISystemPrompt`。
+
+## 生成内容
+
+生成的 prompt 会包含：
+
+- A2UI v0.9 协议概览和设计原则。
+- 必需的服务端到客户端消息类型：`createSurface`、`updateComponents`、`updateDataModel` 和 `deleteSurface`。
+- 新 UI 响应的消息顺序要求。
+- `{ "path": "/..." }` 数据绑定和列表 children 的规则。
+- 客户端 action、event 和 function call 的规则。
+- catalog reference：组件摘要、props、必填字段、容器形态、枚举值和函数签名。
+- 硬性规则：只能输出 JSON、catalog id 必须匹配、组件树必须扁平、必须有 `root` 组件、Button 标签和 action 规则、Modal 确认流程、图片查询处理，以及 action response 的 patch 规则。
+- catalog 提供的已验证示例。
+- CLI 或程序化 API 传入的可选 appendix。
+
+模型应该返回 A2UI 消息组成的 JSON 数组，而不是 Markdown 或自然语言说明：
+
+```json
+[
+  {
+    "version": "v0.9",
+    "createSurface": {
+      "surfaceId": "main",
+      "catalogId": "https://a2ui.org/specification/v0_9/basic_catalog.json"
+    }
+  },
+  {
+    "version": "v0.9",
+    "updateComponents": {
+      "surfaceId": "main",
+      "components": [
+        {
+          "id": "root",
+          "component": "Text",
+          "text": "Hello A2UI"
+        }
+      ]
+    }
+  }
+]
+```
+
+## 后端接入示例
+
+只要模型服务支持 system message，就可以使用生成的 prompt。后端应当先发送 system prompt，再发送用户消息，然后解析或流式转发模型输出的 A2UI JSON。
+
+```ts
+import OpenAI from 'openai';
+import { buildA2UISystemPrompt } from '@lynx-js/genui/a2ui-prompt';
+
+const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+const systemPrompt = buildA2UISystemPrompt();
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+  const completion = await client.chat.completions.create({
+    model: process.env.OPENAI_MODEL ?? 'your-model',
+    stream: true,
+    messages: [
+      { role: 'system', content: systemPrompt },
+      ...messages,
+    ],
+  });
+
+  return new Response(completion.toReadableStream(), {
+    headers: { 'Content-Type': 'text/event-stream' },
+  });
+}
+```
+
+如果后端支持 A2UI 交互 action，需要保留会话历史，并把客户端 action 消息继续传回模型。action response 应该针对已有 surface 输出 `updateDataModel` 和/或 `updateComponents`，而不是重新创建一个新 surface。
+
+## 如何选择
+
+适合使用 CLI 的场景：
+
+- catalog 在构建时确定。
+- 后端可以读取一份已提交或已生成的 prompt 文件。
+- 多个服务需要共享完全一致的 prompt 文本。
+
+适合程序化生成的场景：
+
+- catalog、appendix 或安全策略会按环境或请求变化。
+- 后端本来就会加载生成后的 catalog 产物。
+- 需要在代码里组合自定义 `A2UICatalog`。
+
+自定义 renderer catalog 和 manifest 生成流程可继续阅读 [Catalogs and manifests](./catalog-guide_zh.md)。

package/a2ui/src/catalog/README.md

@@ -0,0 +1,12 @@
+# Catalog composition
+
+The catalog documentation now lives in one place:
+
+➡️ **[docs/catalog-guide.md](../../docs/catalog-guide.md)**
+
+It covers composing a catalog, the built-in components, adding manifests for
+the Agent handshake, the basic-catalog functions, why there is no
+`catalog/all` aggregate, the paste-able "every built-in" recipe, custom
+components, and the full catalog API reference.
+
+中文版见 [docs/catalog-guide_zh.md](../../docs/catalog-guide_zh.md)。

package/a2ui/src/catalog/index.ts

@@ -0,0 +1,51 @@
+// Copyright 2026 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+import type { CatalogManifest } from './defineCatalog.js';
+
+export {
+  defineCatalog,
+  defineFunction,
+  mergeCatalogs,
+  resolveCatalog,
+  serializeCatalog,
+} from './defineCatalog.js';
+export type {
+  Catalog,
+  CatalogComponent,
+  CatalogFunctionDefinition,
+  CatalogFunctionEntry,
+  CatalogInput,
+  CatalogManifest,
+  CatalogSchema,
+  FunctionManifest,
+  ResolvedCatalogEntry,
+  SerializedCatalog,
+} from './defineCatalog.js';
+
+export const catalogManifests: Record<string, CatalogManifest> = {};
+
+// Per-component re-exports so consumers can pick exactly what they need.
+// Each is an independently tree-shakeable ESM re-export — pulling `Text`
+// does not drag `Button` into the bundle.
+export { Button } from './Button/index.jsx';
+export { Card } from './Card/index.jsx';
+export { CheckBox } from './CheckBox/index.jsx';
+export { ChoicePicker } from './ChoicePicker/index.jsx';
+export { DateTimeInput } from './DateTimeInput/index.jsx';
+export { LineChart } from './LineChart/index.jsx';
+export { PieChart } from './PieChart/index.jsx';
+export { Column } from './Column/index.jsx';
+export { Divider } from './Divider/index.jsx';
+export { Icon } from './Icon/index.jsx';
+export { Image } from './Image/index.jsx';
+export { List } from './List/index.jsx';
+export { Loading } from './Loading/index.jsx';
+export { Modal } from './Modal/index.jsx';
+export { RadioGroup } from './RadioGroup/index.jsx';
+export { Row } from './Row/index.jsx';
+export { Slider } from './Slider/index.jsx';
+export { Tabs } from './Tabs/index.jsx';
+export { Text } from './Text/index.jsx';
+export { TextField } from './TextField/index.jsx';
+export { DEFAULT_CHART_COLORS, escapeXml, formatValue } from './utils/chart.js';

package/a2ui/src/catalog/readme_zh.md

@@ -0,0 +1,11 @@
+# Catalog 组合
+
+catalog 文档现在统一收在一处：
+
+➡️ **[docs/catalog-guide_zh.md](../../docs/catalog-guide_zh.md)**
+
+它覆盖了组合 catalog、内置组件、为 Agent handshake 加入 manifest、basic-catalog
+functions、为什么没有 `catalog/all` 聚合、可粘贴的「全部内置」配方、自定义组件，
+以及完整的 catalog API 参考。
+
+English version: [docs/catalog-guide.md](../../docs/catalog-guide.md)。

package/a2ui/src/index.ts

@@ -0,0 +1,115 @@
+// Copyright 2026 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+
+// React surface — `<A2UI>` is the all-in-one entry point. The hooks +
+// `NodeRenderer` are the contract for custom catalog components.
+export {
+  A2UI,
+  NodeRenderer,
+  useAction,
+  useChecks,
+  useDataBinding,
+  useResolvedProps,
+} from './react/index.js';
+export type { A2UIProps, ActionProps, CheckLike } from './react/index.js';
+
+// Store — a pure raw-message buffer. The developer's IO module pushes
+// protocol messages into it; `<A2UI>` subscribes and processes them.
+// `MessageProcessor` is exposed for protocol-aware consumers who want to
+// build their own renderer instead of using `<A2UI>`.
+export { createMessageStore, MessageProcessor } from './store/index.js';
+export type {
+  A2UIClientEventMessage,
+  ComponentInstance,
+  GenericComponentProps,
+  MessageStore,
+  MessageStoreOptions,
+  Resource,
+  ResourceInfo,
+  ServerToClientMessage,
+  Surface,
+  SurfaceId,
+  UserActionPayload,
+} from './store/index.js';
+// Helpers for IO that returns free-form text instead of structured
+// protocol messages.
+export {
+  createFallbackMessagesFromPlainText,
+  createTextCardMessages,
+  normalizePayloadToMessages,
+  prepareMessagesForProcessing,
+} from './store/index.js';
+// Function registry primitives. Consumers building a custom renderer reach
+// the impls through these; `<A2UI>` consumers usually just spread
+// `basicFunctions` into `catalogs`.
+export {
+  executeFunctionCall,
+  functionRegistry,
+  FunctionRegistry,
+  resolveDynamicValue,
+} from './store/index.js';
+export type {
+  FunctionCallContext,
+  FunctionEntry,
+  FunctionImpl,
+  ResolveFunctionOptions,
+} from './store/index.js';
+
+// Catalog — declarative composition.
+export {
+  defineCatalog,
+  defineFunction,
+  mergeCatalogs,
+  resolveCatalog,
+  serializeCatalog,
+} from './catalog/index.js';
+export type {
+  Catalog,
+  CatalogComponent,
+  CatalogFunctionDefinition,
+  CatalogFunctionEntry,
+  CatalogInput,
+  CatalogManifest,
+  CatalogSchema,
+  FunctionManifest,
+  ResolvedCatalogEntry,
+  SerializedCatalog,
+} from './catalog/index.js';
+
+// Built-in components — re-exported individually so apps can pick exactly
+// what they need:
+//
+//   import { Text, Button } from '@lynx-js/genui/a2ui';
+//   <A2UI catalogs={[Text, Button]} ... />
+//
+// There is intentionally no all-in-one aggregate — see
+// `packages/genui/a2ui/docs/catalog-guide.md`.
+export {
+  Button,
+  Card,
+  CheckBox,
+  ChoicePicker,
+  DateTimeInput,
+  Column,
+  Divider,
+  Image,
+  LineChart,
+  PieChart,
+  List,
+  Loading,
+  Modal,
+  RadioGroup,
+  Row,
+  Slider,
+  Tabs,
+  Text,
+  TextField,
+  Icon,
+} from './catalog/index.js';
+
+// A2UI 0.9 basic-catalog functions — registered + announced when spread
+// into `<A2UI catalogs={[..., ...basicFunctions]}>`. Impls come from
+// `@a2ui/web_core` (the upstream basic-catalog package), so the wire
+// contract stays aligned with the spec for free.
+export { basicFunctions, registerBasicFunctions } from './functions/index.js';

package/a2ui/styles/catalog/Button.css

@@ -28,12 +28,12 @@
 }
 
 .button-primary {
-  background-color: var(--a2ui-color-primary);
-  border-color: var(--a2ui-color-primary);
-  color: var(--a2ui-color-on-primary);
+  background-color: var(--a2ui-color-surface-strong);
+  border-color: var(--a2ui-color-border-strong);
+  color: var(--a2ui-color-on-surface);
   box-shadow:
-    0 10px 24px rgba(0, 85, 217, 0.16),
-    0 1px 0 rgba(255, 255, 255, 0.22) inset;
+    0 10px 24px var(--a2ui-color-overlay),
+    0 1px 0 rgba(255, 255, 255, 0.4) inset;
 }
 
 .button-borderless {