@wallarm-org/gen-ui 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,154 @@
-# Temporary Holding Version
+# @wallarm-org/gen-ui
 
-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.
+Generative UI catalog for the Wallarm design system: an agent answers with design-system
+components instead of text. Each component is defined once and rendered from
+[A2UI](https://a2ui.org) v1.0 messages, [json-render](https://json-render.dev) specs or
+[OpenUI](https://www.openui.com) Lang programs.
+
+Experimental: published to npm as `@wallarm-org/gen-ui`, released from `main` with its own tags
+(`gen-ui-v*`, see `RELEASE.md`). The user docs are on the site under
+**AI → Generative UI** (`apps/website/docs/ai/generative-ui.mdx`).
+
+## Where things are
+
+```text
+src/
+├── index.ts              @wallarm-org/gen-ui: the catalog + the API to define entries
+├── core/                 format-agnostic: no format library, React only as types
+│   ├── check.ts          checkNodes / describeIssues: the answer check every format shares
+│   ├── define.ts         GenUiComponent (an entry's contract), defineComponent,
+│   │                     subsetOf / allOf / Values (enums from DS types), seriesKey, unique
+│   ├── format.ts         named number and time formats (formatNumber, formatTime)
+│   └── guards.ts         isRecord: narrow untrusted agent output
+├── render/               React pieces every format shares
+│   ├── GuardedView.tsx   validates props against the schema, then View or Skeleton
+│   ├── Placeholder.tsx   what stands in for a part that isn't renderable yet
+│   ├── ChartSkeleton.tsx the chart card skeleton the chart entries use
+│   ├── SurfaceBoundary.tsx  error boundary: a View that throws blanks its own surface only
+│   └── warn.ts           the one console.warn for rejected agent output
+├── components/           THE CATALOG: one file per entry, index.ts lists them in order
+├── a2ui/                 @wallarm-org/gen-ui/a2ui
+│   ├── catalog.tsx       createA2uiCatalog: entries → A2UI Catalog (toJson() for the agent)
+│   ├── A2uiSurfaces.tsx  feeds messages to a MessageProcessor, renders its surfaces
+│   ├── express.tsx       /a2ui/express: A2UI Express, the compact text form, compiled by @a2ui/agent
+│   ├── prompt.ts         /a2ui/prompt: a2uiPrompt, the system prompt (Express or JSON) with the actions
+│   ├── check.ts          checkA2uiAnswer: the agent's mistakes in a finished answer
+│   └── toA2uiSchema.ts   zod 4 props → the zod 3 schema A2UI's binder reads
+├── json-render/          @wallarm-org/gen-ui/json-render
+│   ├── catalog.tsx       createJsonRenderCatalog: entries → catalog (prompt()) + registry
+│   ├── check.ts          checkJsonRenderAnswer: the same check for a spec
+│   ├── spec.ts           specFromLines (stream → spec, never throws), sanitizeSpec (allowlist)
+│   └── JsonRenderSurface.tsx  renders a spec; keeps its state in step as the app fills it
+├── openui/               @wallarm-org/gen-ui/openui
+│   ├── catalog.tsx       createOpenUiLibrary: entries → OpenUI library (prompt()), props in order
+│   ├── check.ts          checkOpenUiAnswer: the same check for a program
+│   └── OpenUiSurface.tsx renders a program; the app's data arrives as $variables
+├── fixtures/             @wallarm-org/gen-ui/fixtures: recorded answers, every format
+│   ├── stream.ts         the scenario builder: layout chunks + app data → every stream (toStreams)
+│   ├── scenarios.ts      SCENARIOS: every answer a demo can replay, in picker order
+│   ├── attackSummary.ts  a chat answer written by hand in A2UI and json-render
+│   ├── openui.ts         a recorded A2UI answer as OpenUI Lang (toOpenUiLines, openUiAnswer)
+│   ├── liveMonitor.ts    the live example: the app refreshes the page every 2 s
+│   └── dashboard.ts, …   one scenario per file, built with stream.ts
+├── playground/           @wallarm-org/gen-ui/playground: the demos the playground app and the
+│   │                     docs site embed
+│   ├── GenUiPlayground.tsx  pick a prompt, replay its answer, read the stream beside it
+│   ├── GenUiChatDemo.tsx    answers inside the Wally chat, with an approval before Block
+│   └── useEmulatedAgent.ts  the scripted agent behind the chat demo
+└── tests/                all tests (formats.test.tsx covers the shared behaviour)
+```
+
+## How a render works
+
+```text
+components/Metric.tsx (one definition)
+  ├─ a2ui/catalog.tsx        → A2UI catalog ─┐
+  └─ json-render/catalog.tsx → json-render ──┴→ agent output → GuardedView → View (DS components)
+                                                               └ props don't pass yet → Skeleton
+```
+
+1. The app builds both catalogs once, at module scope, from `wallarmComponents`.
+2. The agent is prompted with the catalog: `toJson()` (A2UI) or `catalog.prompt()` (json-render).
+3. Its output streams in. `A2uiSurfaces` takes the messages so far; `JsonRenderSurface` takes
+   `specFromLines(lines)`.
+4. For every component, `GuardedView` checks the props against the entry's zod schema. Passing
+   props reach the `View`; failing ones (data not here yet, or a mistake) show the entry's
+   `Skeleton`. A child the agent hasn't sent yet shows a plain `Placeholder`.
+5. A pressed button fires an event; only actions in the app's allowlist reach `onAction`.
+
+## Add a component
+
+1. Create `src/components/<Name>.tsx` with `defineComponent({ name, description, props, View })`.
+   Copy the closest entry: `Badge.tsx` for a leaf, `Section.tsx` for a container, `BarList.tsx` for
+   a chart.
+2. Add it to `wallarmComponents` and the `export *` list in `src/components/index.ts`.
+3. Add a test in `src/tests/<Name>.test.tsx` that renders it through every format, with literal
+   and bound props, and with data that hasn't arrived (see `LineChart.test.tsx`).
+
+An entry must follow these rules. Tests or typecheck enforce the ones marked ✓.
+
+- Props are data: strings, numbers, booleans, enums, arrays, objects. No functions or ReactNode.
+- No prop named `id`, `component`, `children` or `child` (A2UI puts props next to them).
+- ✓ Every enum value comes from a DS type: `subsetOf<BadgeColor>()([...])` for some values,
+  `allOf<…>()([...])` for all of them, or a typed `Record<…, DSType>` map. No `as` casts in a
+  definition.
+- Numbers and times take a named format from `core/format.ts`, never a formatter function.
+- Events carry no arguments: `events: ['press']`, then `emit('press')`.
+- A container sets `hasChildren: true` and renders `children`.
+- The `View` gets props that already passed the schema, so it needn't guard against missing data;
+  declare a `Skeleton` shaped like the loaded component.
+- The root of a widget fills its cell (`h-full`), so a Grid row lines up.
+- The `description` is for the model: when to use it and the data shape, not how it looks.
+
+## Add a recorded answer
+
+1. Create `src/fixtures/<name>.ts` exporting a `Scenario` (see `dashboard.ts`): the prompt, the
+   agent's layout in the chunks it sends them (`node`, with every figure a `bind('/path')`), and
+   the app's data batches with the chunk each arrives after.
+2. Add `{ ...scenario, ...toStreams(scenario) }` to `SCENARIOS` in `src/fixtures/scenarios.ts`:
+   the playground and the docs page list it from there.
+3. Add a test that renders it through every format and leaves no skeleton at the end.
+
+## Commands
+
+```bash
+pnpm --filter @wallarm-org/gen-ui test:run    # rstest, every format
+pnpm --filter @wallarm-org/gen-ui typecheck
+pnpm --filter @wallarm-org/gen-ui build       # rslib → dist/, same layout as src/
+```
+
+The playground app has two demos that replay the fixtures: `/gen-ui` (answers in the Wally chat)
+and `/gen-ui-playground` (pick a prompt, watch the agent lay out the answer while the app fills its
+data). The docs site embeds the same `GenUiPlayground` on its Generative UI playground page.
+
+```bash
+pnpm turbo run build --filter=@wallarm-org/design-system   # the playground reads the built theme
+pnpm --filter @wallarm-org/playground dev
+```
+
+## Bundle size
+
+What each entry point adds to an app, minified (gzip), with React and the DS external. Measured
+with esbuild from `dist` on 2026-11-12; re-measure after a dependency bump.
+
+| Entry | Size | Most of it |
+| --- | --- | --- |
+| `.` (the catalog) | 110K (33K) | zod 4 |
+| `/a2ui` + the catalog | 498K (137K) | `@a2ui/web_core`, zod 3 and zod 4 |
+| `/a2ui/express` | 634K (176K) | `@a2ui/web_core`, `antlr4ng`, `@a2ui/agent` |
+| `/json-render` + the catalog | 532K (119K) | zod 4 with all its locales |
+| `/openui` + the catalog | 564K (132K) | zod 4 with all its locales, `@openuidev/lang-core` |
+
+- Import zod as `import * as z from 'zod'`. `import { z } from 'zod'` keeps every zod locale in the
+  bundle (443K instead of 83K). json-render and OpenUI import it that way themselves, so their entries still pay for them.
+- Express and the prompt have their own entry points because `@a2ui/agent` and its parser are most
+  of the weight. Compile Express on the server when you can, and send the browser A2UI JSON.
+- `@a2ui/agent` imports `fs` and `path` in modules gen-ui doesn't use. Rspack drops them; a
+  bundler that resolves them anyway needs `fs: false, path: false` as fallbacks.
+
+## Why two versions of zod
+
+json-render needs zod 4, and the definitions are in zod 4. `@a2ui/web_core` pins zod 3 and reads
+zod 3 internals to decide what binds, what's an action and what holds children.
+`a2ui/toA2uiSchema.ts` rewrites each schema with the `zod/v3` API that zod 4 ships. The two
+packages' TS types don't match, so `a2ui/catalog.tsx` casts at that one boundary.

package/dist/a2ui/A2uiSurfaces.d.ts

@@ -0,0 +1,16 @@
+import { type FC } from 'react';
+import { type Catalog, type ComponentApi, type RendererErrorMessage } from '@a2ui/web_core';
+import type { GenUiAction, GenUiActionHandler } from '../core/define.js';
+import type { A2uiMessage } from './catalog.js';
+export interface A2uiSurfacesProps {
+    catalog: Catalog<ComponentApi>;
+    /** Every message the agent has sent so far, in order; new ones are appended while it streams. */
+    messages: readonly A2uiMessage[];
+    /** The only action names that reach `onAction`; anything else the agent names is dropped. */
+    actions: readonly GenUiAction[];
+    onAction: GenUiActionHandler;
+    /** Messages the processor rejected (bad ids, unknown surface, catalog mismatch). Default: console.warn. */
+    onError?: (errors: readonly RendererErrorMessage[]) => void;
+}
+/** Feeds the messages to one MessageProcessor and renders every surface it holds. */
+export declare const A2uiSurfaces: FC<A2uiSurfacesProps>;

package/dist/a2ui/A2uiSurfaces.js

@@ -0,0 +1,61 @@
+import { jsx } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
+import { A2uiSurface } from "@a2ui/react";
+import { MessageProcessor } from "@a2ui/web_core";
+import { SurfaceBoundary } from "../render/SurfaceBoundary.js";
+import { warn } from "../render/warn.js";
+const A2uiSurfaces = ({ catalog, messages, actions, onAction, onError = warnErrors })=>{
+    const latest = useRef({
+        actions,
+        onAction,
+        onError
+    });
+    useEffect(()=>{
+        latest.current = {
+            actions,
+            onAction,
+            onError
+        };
+    });
+    const [processor] = useState(()=>new MessageProcessor([
+            catalog
+        ], (action)=>{
+            const { actions: allowed, onAction: dispatch } = latest.current;
+            if (allowed.some((a)=>a.name === action.name)) dispatch(action.name, action.context);
+            else warn(`dropped A2UI action '${action.name}', not in the allowlist`);
+        }));
+    const [surfaces, setSurfaces] = useState(()=>[
+            ...processor.model.surfacesMap.values()
+        ]);
+    useEffect(()=>{
+        const sync = ()=>setSurfaces([
+                ...processor.model.surfacesMap.values()
+            ]);
+        const created = processor.onSurfaceCreated(sync);
+        const deleted = processor.onSurfaceDeleted(sync);
+        return ()=>{
+            created.unsubscribe();
+            deleted.unsubscribe();
+        };
+    }, [
+        processor
+    ]);
+    const fed = useRef(0);
+    useEffect(()=>{
+        if (messages.length <= fed.current) return;
+        const batch = messages.slice(fed.current);
+        fed.current = messages.length;
+        const errors = processor.processMessagesWithErrors(batch);
+        if (errors.length) latest.current.onError(errors);
+    }, [
+        messages,
+        processor
+    ]);
+    return surfaces.map((surface)=>/*#__PURE__*/ jsx(SurfaceBoundary, {
+            children: /*#__PURE__*/ jsx(A2uiSurface, {
+                surface: surface
+            })
+        }, surface.id));
+};
+const warnErrors = (errors)=>warn('A2UI errors', errors);
+export { A2uiSurfaces };

package/dist/a2ui/catalog.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The A2UI catalog: what the agent is prompted with (`toJson()`) and how the React renderer draws
+ * each entry. The children of a container wait in a ChildSlot until the agent has sent them.
+ */
+import { Catalog, type ComponentApi } from '@a2ui/web_core';
+import type { AgentToRendererMessage } from '@a2ui/web_core/v1_0';
+import type { GenUiComponent } from '../core/define.js';
+/** A v1.0 agent → renderer message: createSurface, updateComponents, updateDataModel, deleteSurface. */
+export type A2uiMessage = AgentToRendererMessage;
+export declare const WALLARM_A2UI_CATALOG_ID = "https://wallarm.github.io/design-system/gen-ui/catalog/v1.json";
+/**
+ * A2UI glue: each component's zod props become an A2UI API (bindable leaves, one Action prop
+ * per event, a ChildList when it has children) and its View renders the binder's resolved props.
+ * `toJson()` on the result is the catalog document the agent is prompted with.
+ */
+export declare const createA2uiCatalog: (components: readonly GenUiComponent[], id?: string) => Catalog<ComponentApi>;

package/dist/a2ui/catalog.js

@@ -0,0 +1,66 @@
+import { jsx } from "react/jsx-runtime";
+import { useSyncExternalStore } from "react";
+import { createComponentImplementation, useA2uiSurface } from "@a2ui/react";
+import { Catalog } from "@a2ui/web_core";
+import { GuardedView } from "../render/GuardedView.js";
+import { Placeholder } from "../render/Placeholder.js";
+import { A2UI_ACTION, A2UI_CHILD_LIST, toA2uiProps } from "./toA2uiSchema.js";
+const WALLARM_A2UI_CATALOG_ID = 'https://wallarm.github.io/design-system/gen-ui/catalog/v1.json';
+const implement = createComponentImplementation;
+const createA2uiCatalog = (components, id = WALLARM_A2UI_CATALOG_ID)=>new Catalog(id, '1.0', components.map((component)=>{
+        const { name, description, props, events = [], hasChildren } = component;
+        const schema = toA2uiProps(props).extend(Object.fromEntries(events.map((event)=>[
+                event,
+                A2UI_ACTION.optional()
+            ]))).extend(hasChildren ? {
+            children: A2UI_CHILD_LIST.optional()
+        } : {}).describe(description);
+        const impl = implement({
+            name,
+            schema
+        }, ({ props: resolved, buildChild, context })=>{
+            const { children, ...rest } = resolved;
+            const values = rest;
+            const raw = context.componentModel.properties.children;
+            const rawIds = Array.isArray(raw) ? raw : void 0;
+            const emit = (event)=>{
+                const action = values[event];
+                if ('function' == typeof action) action();
+            };
+            return /*#__PURE__*/ jsx(GuardedView, {
+                component: component,
+                props: values,
+                emit: emit,
+                children: children?.map((child, index)=>{
+                    const ref = 'string' == typeof child ? {
+                        id: child,
+                        basePath: void 0
+                    } : child;
+                    const agentId = rawIds?.[index];
+                    return /*#__PURE__*/ jsx(ChildSlot, {
+                        id: ref.id,
+                        agentId: 'string' == typeof agentId ? agentId : void 0,
+                        basePath: ref.basePath,
+                        buildChild: buildChild
+                    }, `${ref.id}@${ref.basePath ?? ''}`);
+                })
+            });
+        });
+        return impl;
+    }));
+const ChildSlot = ({ id, agentId, basePath, buildChild })=>{
+    const components = useA2uiSurface()?.componentsModel;
+    const subscribe = (onChange)=>{
+        const created = components?.onCreated.subscribe(onChange);
+        const deleted = components?.onDeleted.subscribe(onChange);
+        return ()=>{
+            created?.unsubscribe();
+            deleted?.unsubscribe();
+        };
+    };
+    const arrived = useSyncExternalStore(subscribe, ()=>!agentId || (components?.has(agentId) ?? true));
+    return arrived || !agentId ? buildChild(id, basePath) : /*#__PURE__*/ jsx(Placeholder, {
+        id: agentId
+    });
+};
+export { WALLARM_A2UI_CATALOG_ID, createA2uiCatalog };

package/dist/a2ui/check.d.ts

@@ -0,0 +1,4 @@
+import { type CheckOptions, type GenUiIssue } from '../core/check.js';
+import type { A2uiMessage } from './catalog.js';
+/** The agent's mistakes in a finished A2UI answer (one surface), per component. */
+export declare const checkA2uiAnswer: (messages: readonly A2uiMessage[], options: CheckOptions) => GenUiIssue[];

package/dist/a2ui/check.js

@@ -0,0 +1,34 @@
+import { checkNodes } from "../core/check.js";
+import { isRecord } from "../core/guards.js";
+const isBinding = (value)=>isRecord(value) && ('@path' in value || '@call' in value);
+const checkA2uiAnswer = (messages, options)=>{
+    const byId = new Map();
+    for (const message of messages){
+        const components = 'createSurface' in message ? message.createSurface.components : 'updateComponents' in message ? message.updateComponents.components : void 0;
+        for (const raw of components ?? [])byId.set(raw.id, toNode(raw, options));
+    }
+    return checkNodes([
+        ...byId.values()
+    ], 'root', isBinding, options);
+};
+const toNode = ({ id, component, children, ...rest }, { components })=>{
+    const events = components.find((c)=>c.name === component)?.events ?? [];
+    const props = Object.fromEntries(Object.entries(rest).filter(([key])=>!events.includes(key)));
+    const actions = events.flatMap((event)=>{
+        const value = rest[event];
+        return isRecord(value) && isRecord(value.event) && 'string' == typeof value.event.name ? [
+            value.event.name
+        ] : [];
+    });
+    const ids = Array.isArray(children) ? children.filter((child)=>'string' == typeof child) : isRecord(children) && 'string' == typeof children.componentId ? [
+        children.componentId
+    ] : [];
+    return {
+        id,
+        type: component,
+        props,
+        children: ids,
+        actions
+    };
+};
+export { checkA2uiAnswer };

package/dist/a2ui/express.d.ts

@@ -0,0 +1,38 @@
+/**
+ * A2UI Express: the compact text a model writes instead of A2UI JSON, one statement per
+ * component (`m = Metric("Attacks", $/kpi/attacks, "compact")`). Arguments follow the order of
+ * the entry's props, bindings are `$/path`. The official @a2ui/agent compiler turns it into the
+ * same v1.0 messages, so everything downstream is unchanged.
+ *
+ * `@wallarm-org/gen-ui/a2ui/express`: its own entry point, since the compiler is most of its weight.
+ */
+import { type FC } from 'react';
+import { ExpressParser } from '@a2ui/agent';
+import type { Catalog, ComponentApi } from '@a2ui/web_core';
+import type { GenUiAction, GenUiActionHandler } from '../core/define.js';
+import type { A2uiMessage } from './catalog.js';
+type A2uiCatalog = Catalog<ComponentApi>;
+/** A compiler (and decompiler) for one surface. */
+export declare const createExpressParser: (catalog: A2uiCatalog, surfaceId: string) => ExpressParser;
+/**
+ * Recorded v1.0 messages as the Express a model would have written, one statement per line, in
+ * order: feed the lines one by one to replay it streaming. The answer is decompiled as a whole,
+ * because Express creates a surface in the scope that defines its root.
+ */
+export declare const toExpressLines: (catalog: A2uiCatalog, surfaceId: string, messages: readonly A2uiMessage[]) => string[];
+export interface ExpressSurfacesProps {
+    catalog: A2uiCatalog;
+    surfaceId: string;
+    /** The Express text so far, in the chunks it arrived in; new chunks are appended. */
+    chunks: readonly string[];
+    actions: readonly GenUiAction[];
+    onAction: GenUiActionHandler;
+    /** A block the compiler rejected, or a message the renderer did. Default: console.warn. */
+    onError?: (errors: readonly unknown[]) => void;
+}
+/**
+ * Renders a streaming Express answer: each new chunk goes into one streaming compiler, which
+ * emits v1.0 messages as soon as they're complete, and those render like any A2UI answer.
+ */
+export declare const ExpressSurfaces: FC<ExpressSurfacesProps>;
+export {};

package/dist/a2ui/express.js

@@ -0,0 +1,64 @@
+import { jsx } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
+import { ExpressParser } from "@a2ui/agent";
+import { A2uiSurfaces } from "./A2uiSurfaces.js";
+const createExpressParser = (catalog, surfaceId)=>new ExpressParser(catalog, surfaceId, '1.0');
+const toExpressLines = (catalog, surfaceId, messages)=>createExpressParser(catalog, surfaceId).decompile(withRootInCreate(messages)).split('\n').filter((line)=>'' !== line.trim());
+const withRootInCreate = (messages)=>{
+    const holdsRoot = (m)=>'updateComponents' in m && m.updateComponents.components.some((c)=>'root' === c.id);
+    const create = messages.find((m)=>'createSurface' in m);
+    const rootUpdate = messages.find(holdsRoot);
+    if (!create || !('createSurface' in create) || create.createSurface.components || !rootUpdate) return [
+        ...messages
+    ];
+    if (!('updateComponents' in rootUpdate)) return [
+        ...messages
+    ];
+    const merged = {
+        ...create,
+        createSurface: {
+            ...create.createSurface,
+            components: rootUpdate.updateComponents.components
+        }
+    };
+    return messages.flatMap((m)=>m === create ? [
+            merged
+        ] : m === rootUpdate ? [] : [
+            m
+        ]);
+};
+const ExpressSurfaces = ({ catalog, surfaceId, chunks, actions, onAction, onError })=>{
+    const [stream] = useState(()=>createExpressParser(catalog, surfaceId).openStream({
+            wrapped: false,
+            afterRejectedBlock: 'continue'
+        }));
+    const [messages, setMessages] = useState([]);
+    const onErrorRef = useRef(onError);
+    useEffect(()=>{
+        onErrorRef.current = onError;
+    });
+    const fed = useRef(0);
+    useEffect(()=>{
+        if (chunks.length <= fed.current) return;
+        const parts = chunks.slice(fed.current).flatMap((chunk)=>stream.feed(`${chunk}\n`));
+        fed.current = chunks.length;
+        const compiled = parts.flatMap((part)=>'a2ui' === part.type ? part.a2ui : []);
+        const rejected = parts.filter((part)=>'error' === part.type);
+        if (compiled.length) setMessages((list)=>[
+                ...list,
+                ...compiled
+            ]);
+        if (rejected.length) onErrorRef.current?.(rejected);
+    }, [
+        chunks,
+        stream
+    ]);
+    return /*#__PURE__*/ jsx(A2uiSurfaces, {
+        catalog: catalog,
+        messages: messages,
+        actions: actions,
+        onAction: onAction,
+        onError: onError
+    });
+};
+export { ExpressSurfaces, createExpressParser, toExpressLines };

package/dist/a2ui/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `@wallarm-org/gen-ui/a2ui`: render the catalog from A2UI v1.0 messages. What needs the A2UI
+ * agent library (and its parser) has its own entry points: `/a2ui/express` and `/a2ui/prompt`.
+ */
+export { A2uiSurfaces, type A2uiSurfacesProps } from './A2uiSurfaces.js';
+export { type A2uiMessage, createA2uiCatalog, WALLARM_A2UI_CATALOG_ID } from './catalog.js';
+export { checkA2uiAnswer } from './check.js';
+export { toA2uiProps, toA2uiSchema } from './toA2uiSchema.js';

package/dist/a2ui/index.js

@@ -0,0 +1,4 @@
+export { A2uiSurfaces } from "./A2uiSurfaces.js";
+export { WALLARM_A2UI_CATALOG_ID, createA2uiCatalog } from "./catalog.js";
+export { checkA2uiAnswer } from "./check.js";
+export { toA2uiProps, toA2uiSchema } from "./toA2uiSchema.js";

package/dist/a2ui/prompt.d.ts

@@ -0,0 +1,16 @@
+import type { Catalog, ComponentApi } from '@a2ui/web_core';
+import type { GenUiAction } from '../core/define.js';
+export interface A2uiPromptOptions {
+    /** What the model writes: A2UI Express (compact, the default) or the v1.0 JSON messages. */
+    format?: 'express' | 'json';
+    /** The actions the app accepts: the model may fire only these. */
+    actions: readonly GenUiAction[];
+}
+/**
+ * `@wallarm-org/gen-ui/a2ui/prompt`, meant for the server that calls the model.
+ *
+ * The system prompt for an A2UI agent: the format's rules and a signature per catalog entry (from
+ * @a2ui/agent), plus the app's actions, which an A2UI catalog doesn't carry. Append your own
+ * instructions, e.g. which data paths the app fills.
+ */
+export declare const a2uiPrompt: (catalog: Catalog<ComponentApi>, { format, actions }: A2uiPromptOptions) => string;

package/dist/a2ui/prompt.js

@@ -0,0 +1,17 @@
+import { DirectJsonFormat, ExpressFormat } from "@a2ui/agent";
+const a2uiPrompt = (catalog, { format = 'express', actions })=>{
+    const generator = 'express' === format ? new ExpressFormat([
+        catalog
+    ], {
+        version: '1.0'
+    }).promptGenerator : new DirectJsonFormat([
+        catalog
+    ]).promptGenerator;
+    return [
+        generator.generate(),
+        '## Actions',
+        'A button fires an action by name; the app ignores any name not listed here.',
+        ...actions.map((a)=>`- ${a.name}: ${a.description}`)
+    ].join('\n');
+};
+export { a2uiPrompt };

package/dist/a2ui/toA2uiSchema.d.ts

@@ -0,0 +1,19 @@
+import type * as z from 'zod';
+import { z as z3 } from 'zod/v3';
+/**
+ * Rewrites a gen-ui zod 4 props schema into the zod 3 schema A2UI's binder walks.
+ *
+ * @a2ui/web_core pins zod 3 and recognises its schemas by `_def.typeName` and `REF:`
+ * descriptions (not `instanceof`), so `zod/v3` from our zod 4 works next to its own copy.
+ * - string / number / boolean leaves become `DynamicString` / `DynamicNumber` / `DynamicBoolean`:
+ *   a literal, or `{ "@path": "/..." }` into the surface's data model.
+ * - arrays and objects take a literal, or one binding for the whole value.
+ * - enums stay literal.
+ * Field descriptions carry over, except onto a dynamic leaf or any wrapper of one: the binder
+ * finds `REF:DynamicString` and the like by the first description up the wrapper chain.
+ */
+export declare const toA2uiSchema: (schema: z.ZodType, dynamic?: boolean, description?: string | undefined) => z3.ZodTypeAny;
+/** The props object itself: its fields are bound one by one, not as a whole. */
+export declare const toA2uiProps: (props: z.ZodObject) => z3.AnyZodObject;
+export declare const A2UI_ACTION: z3.ZodTypeAny;
+export declare const A2UI_CHILD_LIST: z3.ZodTypeAny;

package/dist/a2ui/toA2uiSchema.js

@@ -0,0 +1,61 @@
+import { CommonSchemas } from "@a2ui/web_core/v1_0";
+import { z } from "zod/v3";
+const toA2uiSchema = (schema, dynamic = true, description = schema.description)=>{
+    const def = schema._zod.def;
+    const leaf = 'string' === def.type || 'number' === def.type || 'boolean' === def.type;
+    const out = convert(schema, dynamic, description);
+    return description && !(dynamic && leaf) && 'optional' !== def.type ? out.describe(description) : out;
+};
+const convert = (schema, dynamic, description)=>{
+    const def = schema._zod.def;
+    switch(def.type){
+        case 'string':
+            return dynamic ? common(CommonSchemas.DynamicString) : z.string();
+        case 'number':
+            return dynamic ? common(CommonSchemas.DynamicNumber) : z.number();
+        case 'boolean':
+            return dynamic ? common(CommonSchemas.DynamicBoolean) : z.boolean();
+        case 'enum':
+            {
+                const values = Object.values(def.entries).map(String);
+                return z["enum"](values);
+            }
+        case 'optional':
+            return toA2uiSchema(def.innerType, dynamic, description ?? def.innerType.description).optional();
+        case 'array':
+            {
+                const literal = z.array(toA2uiSchema(def.element, false));
+                return dynamic ? z.union([
+                    literal,
+                    common(CommonSchemas.DataBinding)
+                ]) : literal;
+            }
+        case 'object':
+            {
+                const { shape, catchall } = def;
+                const fixed = z.object(Object.fromEntries(Object.entries(shape).map(([key, value])=>[
+                        key,
+                        toA2uiSchema(value, false)
+                    ])));
+                const literal = catchall ? fixed.catchall(toA2uiSchema(catchall, false)) : fixed;
+                return dynamic ? z.union([
+                    literal,
+                    common(CommonSchemas.DataBinding)
+                ]) : literal;
+            }
+        case 'nullable':
+            return toA2uiSchema(def.innerType, dynamic, description).nullable();
+        case 'unknown':
+            return z.unknown();
+        default:
+            throw new Error(`gen-ui: prop type '${def.type}' has no A2UI mapping`);
+    }
+};
+const toA2uiProps = (props)=>z.object(Object.fromEntries(Object.entries(props.shape).map(([key, value])=>[
+            key,
+            toA2uiSchema(value)
+        ])));
+const common = (schema)=>schema;
+const A2UI_ACTION = common(CommonSchemas.Action);
+const A2UI_CHILD_LIST = common(CommonSchemas.ChildList);
+export { A2UI_ACTION, A2UI_CHILD_LIST, toA2uiProps, toA2uiSchema };

package/dist/components/Alert.d.ts

@@ -0,0 +1,11 @@
+import * as z from 'zod';
+export declare const AlertComponent: import("../index.js").GenUiComponent<z.ZodObject<{
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    tone: z.ZodOptional<z.ZodEnum<{
+        destructive: "destructive";
+        info: "info";
+        success: "success";
+        warning: "warning";
+    }>>;
+}, z.core.$strip>>;

package/dist/components/Alert.js

@@ -0,0 +1,43 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Alert, AlertContent, AlertDescription, AlertIcon, AlertTitle } from "@wallarm-org/design-system/Alert";
+import { Skeleton } from "@wallarm-org/design-system/Skeleton";
+import { defineComponent, subsetOf } from "../core/define.js";
+import * as __rspack_external_zod from "zod";
+const AlertComponent = defineComponent({
+    name: 'Alert',
+    description: 'A highlighted message about something the user should know or act on.',
+    props: __rspack_external_zod.object({
+        title: __rspack_external_zod.string(),
+        description: __rspack_external_zod.string().optional(),
+        tone: __rspack_external_zod["enum"](subsetOf()([
+            'info',
+            'warning',
+            'destructive',
+            'success'
+        ])).optional()
+    }),
+    Skeleton: ()=>/*#__PURE__*/ jsx(Skeleton, {
+            width: "100%",
+            height: "56px",
+            rounded: 12,
+            transparent: false
+        }),
+    View: ({ props })=>/*#__PURE__*/ jsxs(Alert, {
+            color: props.tone ?? 'info',
+            minWidth: 0,
+            children: [
+                /*#__PURE__*/ jsx(AlertIcon, {}),
+                /*#__PURE__*/ jsxs(AlertContent, {
+                    children: [
+                        /*#__PURE__*/ jsx(AlertTitle, {
+                            children: props.title
+                        }),
+                        props.description && /*#__PURE__*/ jsx(AlertDescription, {
+                            children: props.description
+                        })
+                    ]
+                })
+            ]
+        })
+});
+export { AlertComponent };