@ggui-ai/preview-a2ui 0.1.0-rc.1

package/dist/components.js

@@ -0,0 +1,177 @@
+/**
+ * A2UI component shapes for ggui's V1 provisional subset.
+ *
+ * Each component has:
+ *   - `id`: stable string identifier. Replace-by-id is the state model;
+ *     re-emitting a component with the same id replaces it.
+ *   - `component`: discriminator naming the catalog type.
+ *   - Type-specific fields per the A2UI Basic Catalog.
+ *
+ * Schema discipline:
+ *   - Unknown component names reject (discriminated union).
+ *   - Unknown fields on a known component are stripped silently
+ *     (Zod default). Tolerant because A2UI Basic Catalog evolves
+ *     upstream and Haiku may emit extra hints we simply don't need.
+ *   - Children references are plain strings — A2UI's "flat adjacency
+ *     list" model. We don't enforce reference integrity at parse time;
+ *     that's a renderer concern.
+ */
+import { z } from 'zod';
+/** Shared base: every component carries a stable string id. */
+const ComponentBase = z.object({
+    id: z.string().min(1),
+});
+/**
+ * Stable-id string reference to another component.
+ * Narrow alias so consumers can spot refs in the schema.
+ */
+const ComponentRef = z.string().min(1);
+/** Shared layout hints accepted by container components. */
+const Align = z.enum(['start', 'center', 'end', 'stretch']);
+const Justify = z.enum([
+    'start',
+    'center',
+    'end',
+    'between',
+    'around',
+    'evenly',
+]);
+/**
+ * Horizontal container. Children are referenced by id, in order.
+ * Non-interactive in V1 — a provisional Row visually mirrors the real
+ * final layout without wiring interaction.
+ */
+const RowComponent = ComponentBase.extend({
+    component: z.literal('Row'),
+    children: z.array(ComponentRef).optional(),
+    gap: z.string().optional(),
+    align: Align.optional(),
+    justify: Justify.optional(),
+});
+/** Vertical container. Same shape as Row, different axis. */
+const ColumnComponent = ComponentBase.extend({
+    component: z.literal('Column'),
+    children: z.array(ComponentRef).optional(),
+    gap: z.string().optional(),
+    align: Align.optional(),
+    justify: Justify.optional(),
+});
+/**
+ * Card — single-child container with surface treatment. A2UI's
+ * canonical example uses a singular `child` key (not `children`)
+ * for Card; we honor that shape.
+ */
+const CardComponent = ComponentBase.extend({
+    component: z.literal('Card'),
+    child: ComponentRef.optional(),
+});
+/** Generic ordered list of components referenced by id. */
+const ListComponent = ComponentBase.extend({
+    component: z.literal('List'),
+    children: z.array(ComponentRef).optional(),
+});
+/** Visual separator. No children, no payload. */
+const DividerComponent = ComponentBase.extend({
+    component: z.literal('Divider'),
+    orientation: z.enum(['horizontal', 'vertical']).optional(),
+});
+/**
+ * Text block. A2UI supports Markdown inside `text` and uses `variant`
+ * to carry semantic level (`h1`..`h6`, `body`, `caption`, `label`).
+ * We accept any variant string since Haiku may produce variants we
+ * hadn't anticipated — unknown variants degrade to default body text
+ * in the renderer, not a parse failure.
+ */
+const TextComponent = ComponentBase.extend({
+    component: z.literal('Text'),
+    text: z.string(),
+    variant: z.string().optional(),
+});
+/** Image. `alt` is recommended; not required for non-interactive preview. */
+const ImageComponent = ComponentBase.extend({
+    component: z.literal('Image'),
+    src: z.string().min(1),
+    alt: z.string().optional(),
+});
+/**
+ * Icon. `name` targets the upstream icon set (Material / Lucide
+ * family); the renderer maps it to its own icon registry.
+ */
+const IconComponent = ComponentBase.extend({
+    component: z.literal('Icon'),
+    name: z.string().min(1),
+});
+/**
+ * Button shell — always disabled/non-interactive in V1. The `label`
+ * is rendered; `action` (if any A2UI emits) is intentionally dropped
+ * at the renderer since we don't process interactions on the
+ * provisional surface.
+ */
+const ButtonComponent = ComponentBase.extend({
+    component: z.literal('Button'),
+    label: z.string(),
+});
+/** Text input shell. Non-interactive in V1. */
+const TextFieldComponent = ComponentBase.extend({
+    component: z.literal('TextField'),
+    label: z.string().optional(),
+    placeholder: z.string().optional(),
+    value: z.string().optional(),
+});
+/** Checkbox shell. Non-interactive in V1. */
+const CheckBoxComponent = ComponentBase.extend({
+    component: z.literal('CheckBox'),
+    label: z.string().optional(),
+    checked: z.boolean().optional(),
+});
+/**
+ * Single-choice picker shell. Options are tuples of label + value.
+ * Non-interactive in V1 — rendered as a disabled select affordance.
+ */
+const ChoicePickerOption = z.object({
+    label: z.string(),
+    value: z.string(),
+});
+const ChoicePickerComponent = ComponentBase.extend({
+    component: z.literal('ChoicePicker'),
+    label: z.string().optional(),
+    options: z.array(ChoicePickerOption).optional(),
+    value: z.string().optional(),
+});
+/**
+ * Component schema — discriminated union over `component`. Unknown
+ * discriminator values reject at parse time. This is the catalog
+ * gate.
+ */
+export const ComponentSchema = z.discriminatedUnion('component', [
+    RowComponent,
+    ColumnComponent,
+    CardComponent,
+    ListComponent,
+    DividerComponent,
+    TextComponent,
+    ImageComponent,
+    IconComponent,
+    ButtonComponent,
+    TextFieldComponent,
+    CheckBoxComponent,
+    ChoicePickerComponent,
+]);
+/**
+ * Safe-parse a single component. Returns a discriminated result so
+ * callers don't have to choose between throwing and inspecting
+ * `ZodError`. Kept narrow on purpose — we don't re-export Zod's
+ * internals.
+ */
+export function parseComponent(input) {
+    const result = ComponentSchema.safeParse(input);
+    if (result.success)
+        return { ok: true, value: result.data };
+    return {
+        ok: false,
+        issues: result.error.issues.map((issue) => ({
+            path: issue.path,
+            message: issue.message,
+        })),
+    };
+}

package/dist/emitters/deterministic.d.ts

@@ -0,0 +1,94 @@
+/**
+ * JSON-safe payload shape. Mirrors `@ggui-ai/protocol.JsonValue`
+ * structurally (mutable arrays, optional-undefined index entries)
+ * without importing it — keeps this package's zero cross-package
+ * dep boundary intact. The producer's A2UI frames are plain
+ * objects with string/number/boolean/null leaves, so every
+ * concrete emission satisfies this shape AND assigns into the
+ * orchestrator's `JsonValue`-typed `emit` sink.
+ */
+interface JsonPayloadObject {
+    [key: string]: JsonPayload | undefined;
+}
+type JsonPayload = string | number | boolean | null | JsonPayload[] | JsonPayloadObject;
+/**
+ * Minimum fields the producer reads from the orchestrator's context.
+ * Structurally compatible with `ProvisionalPreviewContext` so callers
+ * wrap with a one-line `{run: (ctx) => produceDeterministicPreview(ctx)}`.
+ */
+export interface DeterministicPreviewContext {
+    /**
+     * A2UI surface id. Defaults to `ctx.stackItemId` when
+     * {@link DeterministicPreviewOptions.surfaceId} is absent.
+     */
+    readonly stackItemId: string;
+    /**
+     * Push story. `intent` is the primary signal the producer reads;
+     * additional fields are accepted but ignored.
+     */
+    readonly story: {
+        readonly intent: string;
+    } & Record<string, unknown>;
+    /**
+     * Emit sink from the orchestrator. Declared over {@link JsonPayload}
+     * so callers whose `emit` narrows to `@ggui-ai/protocol.JsonValue`
+     * (the handler's `ProvisionalPreviewEmit` shape) assign in without
+     * a cast — `JsonPayload` is the same value-space. Return value is
+     * the wrapped `{seq?}`; the producer ignores it.
+     */
+    readonly emit: (payload: JsonPayload) => Promise<unknown>;
+    /**
+     * Cancellation signal from the orchestrator. Checked between
+     * frames; on aborted the producer returns without further emits.
+     */
+    readonly signal: AbortSignal;
+}
+export interface DeterministicPreviewOptions {
+    /**
+     * Override the surface id. Defaults to `ctx.stackItemId` — keeping the
+     * surface id aligned with the stackItemId makes the registry's
+     * stackItemId-keyed cancellation reach the right client surface when
+     * the renderer buffers on `createSurface.surfaceId`.
+     */
+    readonly surfaceId?: string;
+    /**
+     * Override the catalog id referenced in `createSurface`. Defaults
+     * to `ggui.preview.v1` — the published manifest this package's
+     * subset targets. Only override if the caller is pointing at a
+     * different deployed catalog.
+     */
+    readonly catalogId?: string;
+}
+/**
+ * Produce a provisional preview for the supplied story. Emits 3
+ * frames on the happy path; returns early on cancellation.
+ *
+ * **No `deleteSurface` on happy path.** The provisional preview is
+ * meant to stay visible until the authoritative final UI replaces
+ * it. Tearing down the surface in the producer would clear the
+ * rendered fragments and leave the viewer blank between
+ * "preview-done" and "final-code-arrives" — the wrong UX.
+ *
+ * Authoritative handoff is the cancellation site: when real
+ * component code lands, the orchestrator's
+ * `finalizeProvisionalPreview` aborts the runner with reason
+ * `'handoff'` and the renderer swaps in the real component. Until
+ * then (e.g. on OSS today, where final generation isn't wired),
+ * the assembled surface stays painted as the user-facing preview.
+ *
+ * The orchestrator still owns the channel-level close
+ * (`{payload: null, complete: true}`); that just latches the
+ * channel as drained without affecting the rendered surface.
+ */
+export declare function produceDeterministicPreview(ctx: DeterministicPreviewContext, options?: DeterministicPreviewOptions): Promise<void>;
+/**
+ * Default export as a factory that adapts the producer into the
+ * orchestrator's `ProvisionalPreviewEmitter` shape without forcing
+ * consumers to write the one-line wrapper. Typed structurally so no
+ * import from `@ggui-ai/mcp-server-handlers` is required.
+ */
+export declare function createDeterministicPreviewEmitter(options?: DeterministicPreviewOptions): {
+    run: (ctx: DeterministicPreviewContext) => Promise<void>;
+};
+export {};
+//# sourceMappingURL=deterministic.d.ts.map

package/dist/emitters/deterministic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deterministic.d.ts","sourceRoot":"","sources":["../../src/emitters/deterministic.ts"],"names":[],"mappings":"AAuCA;;;;;;;;GAQG;AACH,UAAU,iBAAiB;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;CACxC;AACD,KAAK,WAAW,GACZ,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,WAAW,EAAE,GACb,iBAAiB,CAAC;AAEtB;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtE;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1D;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED,MAAM,WAAW,2BAA2B;IAC1C;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAmBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,2BAA2B,CAC/C,GAAG,EAAE,2BAA2B,EAChC,OAAO,CAAC,EAAE,2BAA2B,GACpC,OAAO,CAAC,IAAI,CAAC,CAqEf;AAED;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAC/C,OAAO,CAAC,EAAE,2BAA2B,GACpC;IAAE,GAAG,EAAE,CAAC,GAAG,EAAE,2BAA2B,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAI9D"}

package/dist/emitters/deterministic.js

@@ -0,0 +1,184 @@
+/**
+ * Canonical catalog id for the V1 ggui preview subset. Kept in
+ * alignment with {@link GGUI_PREVIEW_CATALOG_V1_ID} via a type-level
+ * parity assertion below so a rename in one place can't silently
+ * desync.
+ */
+const DEFAULT_CATALOG_ID = 'ggui.preview.v1';
+/**
+ * Compile-time parity guard: the producer's default catalog id
+ * matches the canonical catalog manifest id. If the manifest id
+ * ever changes, this assignment fails to typecheck — the producer
+ * must be updated in lockstep.
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const _CATALOG_ID_PARITY = DEFAULT_CATALOG_ID;
+/**
+ * Produce a provisional preview for the supplied story. Emits 3
+ * frames on the happy path; returns early on cancellation.
+ *
+ * **No `deleteSurface` on happy path.** The provisional preview is
+ * meant to stay visible until the authoritative final UI replaces
+ * it. Tearing down the surface in the producer would clear the
+ * rendered fragments and leave the viewer blank between
+ * "preview-done" and "final-code-arrives" — the wrong UX.
+ *
+ * Authoritative handoff is the cancellation site: when real
+ * component code lands, the orchestrator's
+ * `finalizeProvisionalPreview` aborts the runner with reason
+ * `'handoff'` and the renderer swaps in the real component. Until
+ * then (e.g. on OSS today, where final generation isn't wired),
+ * the assembled surface stays painted as the user-facing preview.
+ *
+ * The orchestrator still owns the channel-level close
+ * (`{payload: null, complete: true}`); that just latches the
+ * channel as drained without affecting the rendered surface.
+ */
+export async function produceDeterministicPreview(ctx, options) {
+    const surfaceId = options?.surfaceId ?? ctx.stackItemId;
+    const catalogId = options?.catalogId ?? DEFAULT_CATALOG_ID;
+    // Frame 1 — surface creation.
+    await ctx.emit({
+        version: 'v0.9',
+        createSurface: { surfaceId, catalogId },
+    });
+    if (ctx.signal.aborted)
+        return;
+    // Frame 2 — root skeleton. Shows a heading derived from the
+    // intent so the user sees "what is being built" before the body
+    // + shells fill in.
+    const heading = deriveHeading(ctx.story.intent);
+    await ctx.emit({
+        version: 'v0.9',
+        updateComponents: {
+            surfaceId,
+            components: [
+                {
+                    id: 'root',
+                    component: 'Column',
+                    children: ['heading'],
+                    gap: '12',
+                    align: 'stretch',
+                },
+                {
+                    id: 'heading',
+                    component: 'Text',
+                    variant: 'h2',
+                    text: heading,
+                },
+            ],
+        },
+    });
+    if (ctx.signal.aborted)
+        return;
+    // Frame 3 — enriched layout. Adds a body caption + keyword-driven
+    // shells (form / list / …) so the surface reads as the rough
+    // outline of the final UI rather than a lone heading. This is
+    // the terminal frame on the happy path; the surface stays
+    // painted in the viewer until authoritative handoff aborts the
+    // runner (or the user navigates away).
+    const body = deriveBody(ctx.story.intent);
+    const shell = pickShell(ctx.story.intent);
+    const rootChildren = ['heading', 'body', ...shell.ids];
+    await ctx.emit({
+        version: 'v0.9',
+        updateComponents: {
+            surfaceId,
+            components: [
+                {
+                    id: 'root',
+                    component: 'Column',
+                    children: rootChildren,
+                    gap: '12',
+                    align: 'stretch',
+                },
+                {
+                    id: 'body',
+                    component: 'Text',
+                    variant: 'caption',
+                    text: body,
+                },
+                ...shell.fragments,
+            ],
+        },
+    });
+}
+/**
+ * Default export as a factory that adapts the producer into the
+ * orchestrator's `ProvisionalPreviewEmitter` shape without forcing
+ * consumers to write the one-line wrapper. Typed structurally so no
+ * import from `@ggui-ai/mcp-server-handlers` is required.
+ */
+export function createDeterministicPreviewEmitter(options) {
+    return {
+        run: (ctx) => produceDeterministicPreview(ctx, options),
+    };
+}
+// ─── Heuristics ────────────────────────────────────────────────────────
+/**
+ * First-sentence heading derivation. Takes the first
+ * sentence-terminating punctuation as the boundary, falls back to
+ * the first ~80 chars. Capitalizes the leading character so
+ * lowercase intents ("build a chat app") render as titles.
+ */
+function deriveHeading(intent) {
+    const trimmed = intent.trim();
+    if (trimmed.length === 0)
+        return 'Preparing your view…';
+    const firstSentence = trimmed.split(/[.!?\n]/)[0]?.trim() ?? trimmed;
+    const clipped = firstSentence.length <= 80 ? firstSentence : firstSentence.slice(0, 80);
+    const leading = clipped.charAt(0).toUpperCase();
+    return leading + clipped.slice(1);
+}
+/**
+ * Body caption. Tight clip so the provisional surface doesn't try
+ * to render the full intent — the final UI handles rich content;
+ * the preview just sets expectations.
+ */
+function deriveBody(intent) {
+    const trimmed = intent.trim();
+    if (trimmed.length === 0)
+        return '';
+    if (trimmed.length <= 120)
+        return trimmed;
+    return trimmed.slice(0, 117) + '…';
+}
+/**
+ * Keyword-driven shell selection. Tiny heuristics — not an NLP
+ * pass. The goal is "provisional looks broadly right for common
+ * intents", not "provisional is 95% accurate". When the heuristics
+ * miss, the rendered surface degrades to heading + caption, which
+ * is still honest about what's coming.
+ */
+function pickShell(intent) {
+    const lower = intent.toLowerCase();
+    if (/\b(form|input|sign\s?up|log\s?in|register|submit|feedback)\b/.test(lower)) {
+        return {
+            ids: ['form-card'],
+            fragments: [
+                { id: 'form-card', component: 'Card', child: 'form-col' },
+                {
+                    id: 'form-col',
+                    component: 'Column',
+                    children: ['tf', 'btn'],
+                    gap: '8',
+                },
+                { id: 'tf', component: 'TextField', label: 'Input' },
+                { id: 'btn', component: 'Button', label: 'Submit' },
+            ],
+        };
+    }
+    if (/\b(list|items|todos?|feed|posts?|grid|dashboard|table)\b/.test(lower)) {
+        return {
+            ids: ['list-card'],
+            fragments: [
+                { id: 'list-card', component: 'Card', child: 'list' },
+                { id: 'list', component: 'List', children: ['l1', 'l2', 'l3'] },
+                { id: 'l1', component: 'Text', variant: 'body', text: '—' },
+                { id: 'l2', component: 'Text', variant: 'body', text: '—' },
+                { id: 'l3', component: 'Text', variant: 'body', text: '—' },
+            ],
+        };
+    }
+    return { ids: [], fragments: [] };
+}

package/dist/emitters/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `@ggui-ai/preview-a2ui/emitters` — reference producers for the
+ * provisional preview pipeline.
+ *
+ * V1 ships a deterministic producer (`produceDeterministicPreview`
+ * + `createDeterministicPreviewEmitter`) that makes the server
+ * orchestration path real without requiring a fast-model LLM. A
+ * future fast-model-backed producer can layer onto the same contract.
+ *
+ * Keeping producers in a dedicated subpath lets consumers import
+ * exactly the bundle they need — hosted pods pulling a Haiku
+ * producer don't pay for the deterministic one, and vice-versa.
+ */
+export { createDeterministicPreviewEmitter, produceDeterministicPreview, type DeterministicPreviewContext, type DeterministicPreviewOptions, } from './deterministic';
+//# sourceMappingURL=index.d.ts.map

package/dist/emitters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/emitters/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EACL,iCAAiC,EACjC,2BAA2B,EAC3B,KAAK,2BAA2B,EAChC,KAAK,2BAA2B,GACjC,MAAM,iBAAiB,CAAC"}

package/dist/emitters/index.js

@@ -0,0 +1,14 @@
+/**
+ * `@ggui-ai/preview-a2ui/emitters` — reference producers for the
+ * provisional preview pipeline.
+ *
+ * V1 ships a deterministic producer (`produceDeterministicPreview`
+ * + `createDeterministicPreviewEmitter`) that makes the server
+ * orchestration path real without requiring a fast-model LLM. A
+ * future fast-model-backed producer can layer onto the same contract.
+ *
+ * Keeping producers in a dedicated subpath lets consumers import
+ * exactly the bundle they need — hosted pods pulling a Haiku
+ * producer don't pay for the deterministic one, and vice-versa.
+ */
+export { createDeterministicPreviewEmitter, produceDeterministicPreview, } from './deterministic.js';

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `@ggui-ai/preview-a2ui` — A2UI boundary for ggui's provisional
+ * assembly channel.
+ *
+ * V1 scope:
+ *   - Server → client write path only
+ *   - Three messages: createSurface / updateComponents / deleteSurface
+ *   - Narrow catalog (12 Basic Catalog components — see `./catalog`)
+ *   - Non-interactive provisional rendering
+ *
+ * Anything outside this scope (data model, interactive actions,
+ * broader catalog coverage) is deliberately deferred. Widen the
+ * surface intentionally, not accidentally.
+ *
+ * Deps: `zod` only. No React, no React Native, no `@ggui-ai/protocol`
+ * import — this package is framework-neutral and protocol-neutral.
+ * The reserved `_ggui:preview` channel constant lives in
+ * `@ggui-ai/protocol/validation/reserved-channels`; this package is
+ * the other side of the boundary and must not couple to the protocol
+ * root.
+ */
+export * from './catalog';
+export * from './components';
+export * from './messages';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,24 @@
+/**
+ * `@ggui-ai/preview-a2ui` — A2UI boundary for ggui's provisional
+ * assembly channel.
+ *
+ * V1 scope:
+ *   - Server → client write path only
+ *   - Three messages: createSurface / updateComponents / deleteSurface
+ *   - Narrow catalog (12 Basic Catalog components — see `./catalog`)
+ *   - Non-interactive provisional rendering
+ *
+ * Anything outside this scope (data model, interactive actions,
+ * broader catalog coverage) is deliberately deferred. Widen the
+ * surface intentionally, not accidentally.
+ *
+ * Deps: `zod` only. No React, no React Native, no `@ggui-ai/protocol`
+ * import — this package is framework-neutral and protocol-neutral.
+ * The reserved `_ggui:preview` channel constant lives in
+ * `@ggui-ai/protocol/validation/reserved-channels`; this package is
+ * the other side of the boundary and must not couple to the protocol
+ * root.
+ */
+export * from './catalog.js';
+export * from './components.js';
+export * from './messages.js';