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

package/dist/messages.d.ts

@@ -0,0 +1,308 @@
+/**
+ * A2UI server → client message shapes for the V1 provisional subset.
+ *
+ * V1 accepts only the write-path messages needed to render a
+ * server-assembled provisional surface:
+ *
+ *   - `createSurface`  — open a surface with a named catalog.
+ *   - `updateComponents` — add/replace components by id.
+ *   - `deleteSurface`  — tear down the surface (cancellation, handoff).
+ *
+ * Intentionally deferred (see `@ggui-ai/preview-a2ui` scope lock):
+ *
+ *   - `updateDataModel` — interactive data-binding surface. Not used
+ *     while the provisional UI is non-interactive in V1.
+ *   - Client → server `action` / `error` messages. Preview accepts no
+ *     user interactions in V1; these would reject cleanly here if a
+ *     client ever tried to forward them into this parser.
+ *
+ * Message shape note: A2UI wraps each envelope under a discriminator
+ * key (not a `type` field). `{version, createSurface: {...}}` vs
+ * `{version, updateComponents: {...}}`. We honor that shape; the Zod
+ * union keys on presence of the payload key rather than on a
+ * dedicated discriminator string.
+ */
+import { z } from 'zod';
+/** A2UI protocol version our V1 subset targets. */
+export declare const A2UI_MESSAGE_VERSION = "v0.9";
+/**
+ * `createSurface` — opens a named surface tied to a catalog id. In
+ * ggui's wiring, `surfaceId` equals the stack item id; `catalogId`
+ * points at a ggui preview catalog manifest (see `./catalog`).
+ *
+ * Theming / data-model bootstrapping fields from the upstream spec
+ * are deferred — they're not on the V1 path and would invite scope
+ * creep to accept here.
+ */
+export declare const CreateSurfaceMessageSchema: z.ZodObject<{
+    version: z.ZodLiteral<"v0.9">;
+    createSurface: z.ZodObject<{
+        surfaceId: z.ZodString;
+        catalogId: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type CreateSurfaceMessage = z.infer<typeof CreateSurfaceMessageSchema>;
+/**
+ * `updateComponents` — ships a batch of components for the surface.
+ * Each component's id is the replace key; the client accumulates
+ * them into a flat adjacency-list tree.
+ *
+ * Empty component arrays are legal (no-op). This matters because the
+ * preamble may emit an initial `updateComponents` with just the root
+ * placeholder and fill children in later frames.
+ */
+export declare const UpdateComponentsMessageSchema: z.ZodObject<{
+    version: z.ZodLiteral<"v0.9">;
+    updateComponents: z.ZodObject<{
+        surfaceId: z.ZodString;
+        components: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            id: z.ZodString;
+            component: z.ZodLiteral<"Row">;
+            children: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            gap: z.ZodOptional<z.ZodString>;
+            align: z.ZodOptional<z.ZodEnum<{
+                start: "start";
+                center: "center";
+                end: "end";
+                stretch: "stretch";
+            }>>;
+            justify: z.ZodOptional<z.ZodEnum<{
+                start: "start";
+                center: "center";
+                end: "end";
+                between: "between";
+                around: "around";
+                evenly: "evenly";
+            }>>;
+        }, z.core.$strip>, z.ZodObject<{
+            id: z.ZodString;
+            component: z.ZodLiteral<"Column">;
+            children: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            gap: z.ZodOptional<z.ZodString>;
+            align: z.ZodOptional<z.ZodEnum<{
+                start: "start";
+                center: "center";
+                end: "end";
+                stretch: "stretch";
+            }>>;
+            justify: z.ZodOptional<z.ZodEnum<{
+                start: "start";
+                center: "center";
+                end: "end";
+                between: "between";
+                around: "around";
+                evenly: "evenly";
+            }>>;
+        }, z.core.$strip>, z.ZodObject<{
+            id: z.ZodString;
+            component: z.ZodLiteral<"Card">;
+            child: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            id: z.ZodString;
+            component: z.ZodLiteral<"List">;
+            children: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>, z.ZodObject<{
+            id: z.ZodString;
+            component: z.ZodLiteral<"Divider">;
+            orientation: z.ZodOptional<z.ZodEnum<{
+                horizontal: "horizontal";
+                vertical: "vertical";
+            }>>;
+        }, z.core.$strip>, z.ZodObject<{
+            id: z.ZodString;
+            component: z.ZodLiteral<"Text">;
+            text: z.ZodString;
+            variant: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            id: z.ZodString;
+            component: z.ZodLiteral<"Image">;
+            src: z.ZodString;
+            alt: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            id: z.ZodString;
+            component: z.ZodLiteral<"Icon">;
+            name: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            id: z.ZodString;
+            component: z.ZodLiteral<"Button">;
+            label: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            id: z.ZodString;
+            component: z.ZodLiteral<"TextField">;
+            label: z.ZodOptional<z.ZodString>;
+            placeholder: z.ZodOptional<z.ZodString>;
+            value: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            id: z.ZodString;
+            component: z.ZodLiteral<"CheckBox">;
+            label: z.ZodOptional<z.ZodString>;
+            checked: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>, z.ZodObject<{
+            id: z.ZodString;
+            component: z.ZodLiteral<"ChoicePicker">;
+            label: z.ZodOptional<z.ZodString>;
+            options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                label: z.ZodString;
+                value: z.ZodString;
+            }, z.core.$strip>>>;
+            value: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>], "component">>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type UpdateComponentsMessage = z.infer<typeof UpdateComponentsMessageSchema>;
+/**
+ * `deleteSurface` — closes the surface. Emitted on preamble
+ * cancellation (fast-path hit arrived) or on handoff (final
+ * component code committed and the crossfade is complete).
+ */
+export declare const DeleteSurfaceMessageSchema: z.ZodObject<{
+    version: z.ZodLiteral<"v0.9">;
+    deleteSurface: z.ZodObject<{
+        surfaceId: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type DeleteSurfaceMessage = z.infer<typeof DeleteSurfaceMessageSchema>;
+/**
+ * Server → client message — the V1 write-path union.
+ *
+ * A2UI keys its envelopes on the payload key rather than a dedicated
+ * discriminator. Using `z.union` (not `z.discriminatedUnion`) is
+ * deliberate: the envelope keys are distinct object keys, not values
+ * of a single discriminator field, so Zod can't narrow by discriminator.
+ */
+export declare const ServerMessageSchema: z.ZodUnion<readonly [z.ZodObject<{
+    version: z.ZodLiteral<"v0.9">;
+    createSurface: z.ZodObject<{
+        surfaceId: z.ZodString;
+        catalogId: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    version: z.ZodLiteral<"v0.9">;
+    updateComponents: z.ZodObject<{
+        surfaceId: z.ZodString;
+        components: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            id: z.ZodString;
+            component: z.ZodLiteral<"Row">;
+            children: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            gap: z.ZodOptional<z.ZodString>;
+            align: z.ZodOptional<z.ZodEnum<{
+                start: "start";
+                center: "center";
+                end: "end";
+                stretch: "stretch";
+            }>>;
+            justify: z.ZodOptional<z.ZodEnum<{
+                start: "start";
+                center: "center";
+                end: "end";
+                between: "between";
+                around: "around";
+                evenly: "evenly";
+            }>>;
+        }, z.core.$strip>, z.ZodObject<{
+            id: z.ZodString;
+            component: z.ZodLiteral<"Column">;
+            children: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            gap: z.ZodOptional<z.ZodString>;
+            align: z.ZodOptional<z.ZodEnum<{
+                start: "start";
+                center: "center";
+                end: "end";
+                stretch: "stretch";
+            }>>;
+            justify: z.ZodOptional<z.ZodEnum<{
+                start: "start";
+                center: "center";
+                end: "end";
+                between: "between";
+                around: "around";
+                evenly: "evenly";
+            }>>;
+        }, z.core.$strip>, z.ZodObject<{
+            id: z.ZodString;
+            component: z.ZodLiteral<"Card">;
+            child: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            id: z.ZodString;
+            component: z.ZodLiteral<"List">;
+            children: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>, z.ZodObject<{
+            id: z.ZodString;
+            component: z.ZodLiteral<"Divider">;
+            orientation: z.ZodOptional<z.ZodEnum<{
+                horizontal: "horizontal";
+                vertical: "vertical";
+            }>>;
+        }, z.core.$strip>, z.ZodObject<{
+            id: z.ZodString;
+            component: z.ZodLiteral<"Text">;
+            text: z.ZodString;
+            variant: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            id: z.ZodString;
+            component: z.ZodLiteral<"Image">;
+            src: z.ZodString;
+            alt: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            id: z.ZodString;
+            component: z.ZodLiteral<"Icon">;
+            name: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            id: z.ZodString;
+            component: z.ZodLiteral<"Button">;
+            label: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            id: z.ZodString;
+            component: z.ZodLiteral<"TextField">;
+            label: z.ZodOptional<z.ZodString>;
+            placeholder: z.ZodOptional<z.ZodString>;
+            value: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            id: z.ZodString;
+            component: z.ZodLiteral<"CheckBox">;
+            label: z.ZodOptional<z.ZodString>;
+            checked: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>, z.ZodObject<{
+            id: z.ZodString;
+            component: z.ZodLiteral<"ChoicePicker">;
+            label: z.ZodOptional<z.ZodString>;
+            options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                label: z.ZodString;
+                value: z.ZodString;
+            }, z.core.$strip>>>;
+            value: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>], "component">>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    version: z.ZodLiteral<"v0.9">;
+    deleteSurface: z.ZodObject<{
+        surfaceId: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>]>;
+export type ServerMessage = CreateSurfaceMessage | UpdateComponentsMessage | DeleteSurfaceMessage;
+/** Narrow parse result — mirror of the component parse result shape. */
+export type ServerMessageParseResult = {
+    readonly ok: true;
+    readonly value: ServerMessage;
+} | {
+    readonly ok: false;
+    readonly issues: ReadonlyArray<{
+        path: ReadonlyArray<PropertyKey>;
+        message: string;
+    }>;
+};
+/**
+ * Safe-parse one server → client A2UI message. Returns a narrow
+ * discriminated result without leaking Zod internals; callers handle
+ * rejection by surfacing the `issues` list or by logging + dropping.
+ */
+export declare function parseServerMessage(input: unknown): ServerMessageParseResult;
+/**
+ * Narrow type guards for the discriminated consumer code. Reading
+ * the payload key is the canonical shape — avoids consumers having
+ * to introspect Zod-parsed objects by presence of unrelated fields.
+ */
+export declare function isCreateSurfaceMessage(msg: ServerMessage): msg is CreateSurfaceMessage;
+export declare function isUpdateComponentsMessage(msg: ServerMessage): msg is UpdateComponentsMessage;
+export declare function isDeleteSurfaceMessage(msg: ServerMessage): msg is DeleteSurfaceMessage;
+//# sourceMappingURL=messages.d.ts.map

package/dist/messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,mDAAmD;AACnD,eAAO,MAAM,oBAAoB,SAAS,CAAC;AAK3C;;;;;;;;GAQG;AACH,eAAO,MAAM,0BAA0B;;;;;;iBAMrC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAMxC,CAAC;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAC3C,OAAO,6BAA6B,CACrC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,0BAA0B;;;;;iBAKrC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mBAI9B,CAAC;AAEH,MAAM,MAAM,aAAa,GACrB,oBAAoB,GACpB,uBAAuB,GACvB,oBAAoB,CAAC;AAEzB,wEAAwE;AACxE,MAAM,MAAM,wBAAwB,GAChC;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAA;CAAE,GACpD;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;QAAE,IAAI,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACvF,CAAC;AAEN;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,wBAAwB,CAU3E;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,aAAa,GACjB,GAAG,IAAI,oBAAoB,CAE7B;AAED,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,aAAa,GACjB,GAAG,IAAI,uBAAuB,CAEhC;AAED,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,aAAa,GACjB,GAAG,IAAI,oBAAoB,CAE7B"}

package/dist/messages.js

@@ -0,0 +1,117 @@
+/**
+ * A2UI server → client message shapes for the V1 provisional subset.
+ *
+ * V1 accepts only the write-path messages needed to render a
+ * server-assembled provisional surface:
+ *
+ *   - `createSurface`  — open a surface with a named catalog.
+ *   - `updateComponents` — add/replace components by id.
+ *   - `deleteSurface`  — tear down the surface (cancellation, handoff).
+ *
+ * Intentionally deferred (see `@ggui-ai/preview-a2ui` scope lock):
+ *
+ *   - `updateDataModel` — interactive data-binding surface. Not used
+ *     while the provisional UI is non-interactive in V1.
+ *   - Client → server `action` / `error` messages. Preview accepts no
+ *     user interactions in V1; these would reject cleanly here if a
+ *     client ever tried to forward them into this parser.
+ *
+ * Message shape note: A2UI wraps each envelope under a discriminator
+ * key (not a `type` field). `{version, createSurface: {...}}` vs
+ * `{version, updateComponents: {...}}`. We honor that shape; the Zod
+ * union keys on presence of the payload key rather than on a
+ * dedicated discriminator string.
+ */
+import { z } from 'zod';
+import { ComponentSchema } from './components.js';
+/** A2UI protocol version our V1 subset targets. */
+export const A2UI_MESSAGE_VERSION = 'v0.9';
+const VersionLiteral = z.literal(A2UI_MESSAGE_VERSION);
+const SurfaceId = z.string().min(1);
+/**
+ * `createSurface` — opens a named surface tied to a catalog id. In
+ * ggui's wiring, `surfaceId` equals the stack item id; `catalogId`
+ * points at a ggui preview catalog manifest (see `./catalog`).
+ *
+ * Theming / data-model bootstrapping fields from the upstream spec
+ * are deferred — they're not on the V1 path and would invite scope
+ * creep to accept here.
+ */
+export const CreateSurfaceMessageSchema = z.object({
+    version: VersionLiteral,
+    createSurface: z.object({
+        surfaceId: SurfaceId,
+        catalogId: z.string().min(1),
+    }),
+});
+/**
+ * `updateComponents` — ships a batch of components for the surface.
+ * Each component's id is the replace key; the client accumulates
+ * them into a flat adjacency-list tree.
+ *
+ * Empty component arrays are legal (no-op). This matters because the
+ * preamble may emit an initial `updateComponents` with just the root
+ * placeholder and fill children in later frames.
+ */
+export const UpdateComponentsMessageSchema = z.object({
+    version: VersionLiteral,
+    updateComponents: z.object({
+        surfaceId: SurfaceId,
+        components: z.array(ComponentSchema),
+    }),
+});
+/**
+ * `deleteSurface` — closes the surface. Emitted on preamble
+ * cancellation (fast-path hit arrived) or on handoff (final
+ * component code committed and the crossfade is complete).
+ */
+export const DeleteSurfaceMessageSchema = z.object({
+    version: VersionLiteral,
+    deleteSurface: z.object({
+        surfaceId: SurfaceId,
+    }),
+});
+/**
+ * Server → client message — the V1 write-path union.
+ *
+ * A2UI keys its envelopes on the payload key rather than a dedicated
+ * discriminator. Using `z.union` (not `z.discriminatedUnion`) is
+ * deliberate: the envelope keys are distinct object keys, not values
+ * of a single discriminator field, so Zod can't narrow by discriminator.
+ */
+export const ServerMessageSchema = z.union([
+    CreateSurfaceMessageSchema,
+    UpdateComponentsMessageSchema,
+    DeleteSurfaceMessageSchema,
+]);
+/**
+ * Safe-parse one server → client A2UI message. Returns a narrow
+ * discriminated result without leaking Zod internals; callers handle
+ * rejection by surfacing the `issues` list or by logging + dropping.
+ */
+export function parseServerMessage(input) {
+    const result = ServerMessageSchema.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,
+        })),
+    };
+}
+/**
+ * Narrow type guards for the discriminated consumer code. Reading
+ * the payload key is the canonical shape — avoids consumers having
+ * to introspect Zod-parsed objects by presence of unrelated fields.
+ */
+export function isCreateSurfaceMessage(msg) {
+    return 'createSurface' in msg;
+}
+export function isUpdateComponentsMessage(msg) {
+    return 'updateComponents' in msg;
+}
+export function isDeleteSurfaceMessage(msg) {
+    return 'deleteSurface' in msg;
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@ggui-ai/preview-a2ui",
+  "version": "0.1.0-rc.1",
+  "description": "Narrow A2UI boundary for ggui's provisional UI assembly channel. Framework-neutral types and validators for the server-write subset (createSurface / updateComponents / deleteSurface) used to paint shimmering placeholder UI before the final generated interface arrives.",
+  "keywords": [
+    "ggui",
+    "a2ui",
+    "ui",
+    "preview",
+    "validation"
+  ],
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/ggui-ai/ggui/tree/main/packages/preview-a2ui",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ggui-ai/ggui.git",
+    "directory": "packages/preview-a2ui"
+  },
+  "bugs": {
+    "url": "https://github.com/ggui-ai/ggui/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./emitters": {
+      "types": "./dist/emitters/index.d.ts",
+      "import": "./dist/emitters/index.js",
+      "default": "./dist/emitters/index.js"
+    }
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "author": "ggui contributors <hello@ggui.ai>",
+  "scripts": {
+    "build": "tsc && node ../scripts/fix-esm-imports.mjs dist",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}