@adia-ai/a2ui-runtime 0.6.2 → 0.6.6

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog — @adia-ai/a2ui-runtime
 
+## [0.6.6] — 2026-05-18
+
+### Changed
+- Lockstep version bump for §304 `<field-ui align>` prop.
+## [0.6.5] — 2026-05-18
+
+### Changed
+- Lockstep version bump for TS Phase 6 sealing (ADR-0029).
 Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 [Semantic Versioning](https://semver.org/).
 
@@ -12,6 +20,28 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 
 _No pending changes._
 
+## [0.6.4] - 2026-05-18
+
+### v0.6.4 §359 — TypeScript-first Phase 5: `a2ui.schema.json` + schema-driven codegen
+
+`packages/a2ui/runtime/a2ui.schema.json` — JSON Schema 2020-12 for the full A2UI protocol.
+`scripts/build/a2ui-schema-types.mjs` codegen emits `a2ui.schema.d.ts` from schema.
+`npm run verify:a2ui-schema` drift-detection gate added to `npm run check`.
+`./schema` + `./types` subpath exports added. `types.d.ts` now re-exports from schema.
+**No BREAKING changes.**
+
+
+
+## [0.6.3] - 2026-05-18
+
+### v0.6.3 §358 — TypeScript-first Phase 5: real `.d.ts` + `A2UIMessage` discriminated union
+
+18 real declaration files replace Phase 1 `export {}` stubs across runtime, dockables,
+surface-manifest, and wiring-registry. `A2UIMessage` discriminated union added.
+`index.ts` typed barrel. **No BREAKING changes.**
+
+
+
 ## [0.6.2] - 2026-05-18
 
 ### v0.6.2 — Lockstep ride-along

package/a2ui.schema.d.ts

@@ -0,0 +1,169 @@
+// AUTO-GENERATED FROM packages/a2ui/runtime/a2ui.schema.json. DO NOT EDIT.
+// Regenerate with: node scripts/build/a2ui-schema-types.mjs
+// Verify drift with: node scripts/build/a2ui-schema-types.mjs --verify
+
+/**
+ * Any valid A2UI protocol message. Discriminated on `type`.
+ */
+export type A2UIMessage =
+  | CreateSurfaceMessage
+  | UpdateComponentsMessage
+  | UpdateDataModelMessage
+  | WireComponentsMessage
+  | DeleteSurfaceMessage
+  | MetaMessage;
+
+/**
+ * Initialises a new rendering surface.
+ */
+export interface CreateSurfaceMessage {
+  type: 'createSurface';
+  /**
+   * Unique surface identifier.
+   */
+  surfaceId: string;
+  /**
+   * Optional catalog URL override for this surface.
+   */
+  catalogId?: string;
+  /**
+   * Component ID to use as the surface root (defaults to 'root').
+   */
+  root?: string;
+}
+/**
+ * Upserts component nodes on a surface. The renderer reconciles against existing nodes.
+ */
+export interface UpdateComponentsMessage {
+  type: 'updateComponents';
+  /**
+   * Legacy alias for type; renderer accepts both.
+   */
+  messageType?: string;
+  surfaceId: string;
+  /**
+   * @minItems 1
+   */
+  components: [A2UIComponent, ...A2UIComponent[]];
+}
+/**
+ * A single component node in the A2UI component tree.
+ */
+export interface A2UIComponent {
+  /**
+   * Unique identifier within the surface.
+   */
+  id: string;
+  /**
+   * A2UI type name — resolved via the registry to a custom-element tag name.
+   */
+  component: string;
+  /**
+   * Ordered list of child component IDs.
+   */
+  children?: string[];
+  /**
+   * Single child component ID (shorthand when there is exactly one child).
+   */
+  child?: string;
+  [k: string]: unknown;
+}
+/**
+ * Updates the surface data model at a JSON Pointer path.
+ */
+export interface UpdateDataModelMessage {
+  type: 'updateDataModel';
+  surfaceId: string;
+  /**
+   * JSON Pointer path within the data model (e.g. '/user/name'). '/' or '' = replace root.
+   */
+  path: string;
+  value: unknown;
+}
+/**
+ * Attaches interactive behaviour (actions, data sources, controllers) to a surface.
+ */
+export interface WireComponentsMessage {
+  type: 'wireComponents';
+  surfaceId: string;
+  /**
+   * Event → handler bindings.
+   */
+  actions?: WireAction[];
+  /**
+   * Data-source dockables.
+   */
+  data?: WireDataSource[];
+  /**
+   * Controller dockables.
+   */
+  state?: WireState[];
+  /**
+   * Lifecycle hook dockables.
+   */
+  lifecycle?: {
+    [k: string]: unknown;
+  }[];
+}
+/**
+ * An event → handler binding for interactive wiring.
+ */
+export interface WireAction {
+  /**
+   * The UIEvent that triggers this action.
+   */
+  event:
+    | string
+    | {
+        event: string;
+        /**
+         * Component ID that emits the event.
+         */
+        target?: string;
+        debounce?: number;
+      };
+  /**
+   * Handler name registered in the wiring registry.
+   */
+  handler: string;
+  /**
+   * Handler-specific configuration.
+   */
+  config?: {
+    [k: string]: unknown;
+  };
+}
+/**
+ * A data-source dockable: connects a model path to a component property.
+ */
+export interface WireDataSource {
+  source: string;
+  target: string;
+  transform?: string;
+  [k: string]: unknown;
+}
+/**
+ * A controller dockable: attaches a stateful controller to a component.
+ */
+export interface WireState {
+  controller: string;
+  target: string;
+  config?: {
+    [k: string]: unknown;
+  };
+  [k: string]: unknown;
+}
+/**
+ * Removes a surface and all its elements from the DOM.
+ */
+export interface DeleteSurfaceMessage {
+  type: 'deleteSurface';
+  surfaceId: string;
+}
+/**
+ * LLM self-critique or metadata. Not rendered; passed through for logging.
+ */
+export interface MetaMessage {
+  type: 'meta';
+  [k: string]: unknown;
+}

package/dockables/action.d.ts

@@ -0,0 +1,55 @@
+/**
+ * ActionDock — Binds a UIEvent on a component to a handler function.
+ */
+
+import type { Dockable } from './base.js';
+import type { SurfaceContext } from '../surface.js';
+
+/** Mapping of A2UI semantic event names to DOM event names. */
+export declare const A2UI_EVENT_TO_DOM: Record<string, string>;
+
+export interface UIEventDecl {
+  /** A2UI semantic event name (press, submit, input, change, …). */
+  event: string;
+  /** Component ID to listen on. Defaults to the surface root. */
+  target?: string;
+  /** Debounce delay in ms. */
+  debounce?: number;
+  /** Throttle interval in ms. */
+  throttle?: number;
+  /** Optional condition guard. */
+  condition?: {
+    path: string;
+    equals?: unknown;
+    notEquals?: unknown;
+    exists?: boolean;
+  };
+}
+
+export interface ActionDecl {
+  /** DOM event descriptor. */
+  event: UIEventDecl;
+  /** Handler name from the wiring registry. */
+  handler: string;
+  config?: Record<string, unknown>;
+  onSuccess?: Array<{ handler: string; config?: Record<string, unknown> }> | null;
+  onError?: Array<{ handler: string; config?: Record<string, unknown> }> | null;
+}
+
+export declare class ActionDock extends Dockable {
+  readonly kind: 'action';
+  readonly id: string;
+  readonly event: UIEventDecl;
+  readonly handler: string;
+  readonly config: Record<string, unknown>;
+  readonly onSuccess: Array<{ handler: string; config?: Record<string, unknown> }> | null;
+  readonly onError: Array<{ handler: string; config?: Record<string, unknown> }> | null;
+
+  constructor(
+    decl: ActionDecl,
+    resolveHandler: (name: string) => ((config: unknown, ctx: SurfaceContext, event: unknown) => Promise<unknown>) | null,
+  );
+
+  dock(ctx: SurfaceContext): (() => void) | void;
+  undock(): void;
+}

package/dockables/base.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Dockable — Base class for objects that attach to a Surface.
+ */
+
+import type { SurfaceContext } from '../surface.js';
+
+/** The kinds of dockable objects. */
+export type DockableKind = 'controller' | 'source' | 'action' | 'provider' | 'lifecycle';
+
+export declare abstract class Dockable {
+  /** Port type — determines dock ordering. */
+  abstract readonly kind: DockableKind;
+
+  /** Unique identifier within the surface. */
+  abstract readonly id: string;
+
+  /**
+   * Attach to a surface. Return a cleanup function, or void.
+   */
+  dock(ctx: SurfaceContext): (() => void) | void;
+
+  /**
+   * Detach from the surface. The cleanup fn from dock() is called first.
+   */
+  undock(): void;
+}

package/dockables/controller.d.ts

@@ -0,0 +1,35 @@
+/**
+ * ControllerDock — Wraps an AdiaUI controller as a dockable.
+ */
+
+import type { Dockable } from './base.js';
+import type { SurfaceContext } from '../surface.js';
+
+export interface ControllerDecl {
+  id: string;
+  /** Controller type name, e.g. 'FormController'. */
+  type: string;
+  /** Component ID of the host element to attach to. */
+  host: string;
+  config?: Record<string, unknown>;
+  /** Model path bindings: { stateKey: '/model/path' } */
+  bind?: Record<string, string> | null;
+}
+
+export declare class ControllerDock extends Dockable {
+  readonly kind: 'controller';
+  readonly id: string;
+  readonly type: string;
+  readonly hostId: string;
+  readonly config: Record<string, unknown>;
+  readonly bind: Record<string, string> | null;
+  controller: unknown | null;
+
+  constructor(
+    decl: ControllerDecl,
+    resolveClass: (type: string) => Promise<(new (...args: unknown[]) => unknown) | null>,
+  );
+
+  dock(ctx: SurfaceContext): Promise<(() => void) | void>;
+  undock(): void;
+}

package/dockables/data-source.d.ts

@@ -0,0 +1,35 @@
+/**
+ * DataSourceDock — Fetches data and pushes it into the surface model.
+ */
+
+import type { Dockable } from './base.js';
+import type { SurfaceContext } from '../surface.js';
+
+export interface DataSourceDecl {
+  id: string;
+  /** URI template, e.g., "resource://users/{userId}" */
+  uri: string;
+  /** Model path to write fetched data to. */
+  path: string;
+  /** Refresh strategy: 'once' | 'on-focus' | 'interval:<ms>' | 'stream'. Default: 'once'. */
+  refresh?: string;
+}
+
+export declare class DataSourceDock extends Dockable {
+  readonly kind: 'source';
+  readonly id: string;
+  readonly uri: string;
+  readonly path: string;
+  readonly refresh: string;
+
+  constructor(
+    decl: DataSourceDecl,
+    resolveData: (uri: string, ctx: unknown) => Promise<unknown>,
+  );
+
+  dock(ctx: SurfaceContext): (() => void) | void;
+  undock(): void;
+
+  /** Manually re-fetch the data source. */
+  refetch(): void;
+}

package/dockables/index.d.ts

@@ -1,4 +1,21 @@
-// v0.5.21 hotfix stub — TS-migration Phase 1 (568bb998d) declared this
-// types: export but Phase 2 hasn't generated real declarations yet.
-// Replace with real type declarations when Phase 2 lands.
-export {};
+/**
+ * Dockables barrel — re-exports all dockable classes and the event mapping.
+ */
+
+export { Dockable } from './base.js';
+export type { DockableKind } from './base.js';
+
+export { ControllerDock } from './controller.js';
+export type { ControllerDecl } from './controller.js';
+
+export { DataSourceDock } from './data-source.js';
+export type { DataSourceDecl } from './data-source.js';
+
+export { ActionDock, A2UI_EVENT_TO_DOM } from './action.js';
+export type { ActionDecl, UIEventDecl } from './action.js';
+
+export { ProviderDock } from './provider.js';
+export type { ProviderDecl } from './provider.js';
+
+export { LifecycleDock } from './lifecycle.js';
+export type { LifecycleDecl, LifecycleAction, ModelChangeWatcher } from './lifecycle.js';

package/dockables/lifecycle.d.ts

@@ -0,0 +1,38 @@
+/**
+ * LifecycleDock — Runs actions on mount, unmount, and model changes.
+ */
+
+import type { Dockable } from './base.js';
+import type { SurfaceContext } from '../surface.js';
+
+export interface LifecycleAction {
+  handler: string;
+  config?: Record<string, unknown>;
+}
+
+export interface ModelChangeWatcher extends LifecycleAction {
+  path: string;
+  debounce?: number;
+}
+
+export interface LifecycleDecl {
+  onMount?: LifecycleAction[];
+  onUnmount?: LifecycleAction[];
+  onModelChange?: ModelChangeWatcher[];
+}
+
+export declare class LifecycleDock extends Dockable {
+  readonly kind: 'lifecycle';
+  readonly id: 'lifecycle';
+  readonly onMount: LifecycleAction[];
+  readonly onUnmount: LifecycleAction[];
+  readonly onModelChange: ModelChangeWatcher[];
+
+  constructor(
+    decl: LifecycleDecl,
+    resolveHandler: (name: string) => ((config: unknown, ctx: SurfaceContext) => Promise<unknown>) | null,
+  );
+
+  dock(ctx: SurfaceContext): (() => void) | void;
+  undock(): void;
+}

package/dockables/provider.d.ts

@@ -0,0 +1,28 @@
+/**
+ * ProviderDock — Injects shared context into a component subtree.
+ */
+
+import type { Dockable } from './base.js';
+import type { SurfaceContext } from '../surface.js';
+
+export interface ProviderDecl {
+  /** Context name, e.g. "auth". The dock id is set to "provider:<name>". */
+  name: string;
+  /** Component ID to wrap. Defaults to the surface root. */
+  host?: string;
+  /** Initial context value. */
+  value?: unknown;
+}
+
+export declare class ProviderDock extends Dockable {
+  readonly kind: 'provider';
+  /** "provider:<name>" */
+  readonly id: string;
+  readonly hostId: string | null;
+  readonly value: unknown;
+
+  constructor(decl: ProviderDecl);
+
+  dock(ctx: SurfaceContext): (() => void) | void;
+  undock(): void;
+}

package/index.js

@@ -1,45 +1,51 @@
-/**
- * @adia-ai/a2ui-runtime — A2UI runtime surface.
- *
- * Framework-agnostic leaf: no runtime dep on @adia-ai/web-components.
- * Pairs with any A2UI-conformant custom-element catalog.
- *
- * Tier 1 — Render: resolve A2UI protocol → custom-element tags, run the
- * renderer, consume transports.
- *
- * Tier 2 — Wire: surface-manifest + wiring-engine + dockable primitives
- * for cross-surface data flow and lifecycle.
- */
-
-// ── Tier 1: Render ─────────────────────────────────────────────────
-export { registry, resolveTag, registerType } from './registry.js';
-export { A2UIRenderer } from './renderer.js';
-export { sseStream, wsStream, mockStream, mcpStream, jsonlStream } from './stream.js';
-
-// ── Tier 2: Wire ───────────────────────────────────────────────────
-export { SurfaceManifest } from './surface-manifest.js';
-export { Surface } from './surface.js';
-
-// Wiring primitives
-export { createDockables } from './wire-factory.js';
-export { WiringEngine } from './wiring-engine.js';
-export {
+import { registry, resolveTag, registerType } from "./registry.js";
+import { A2UIRenderer } from "./renderer.js";
+import { sseStream, wsStream, mockStream, mcpStream, jsonlStream } from "./stream.js";
+import { SurfaceManifest } from "./surface-manifest.js";
+import { Surface } from "./surface.js";
+import { createDockables } from "./wire-factory.js";
+import { WiringEngine } from "./wiring-engine.js";
+import {
   wiringRegistry,
   registerController,
   registerHandler,
   registerResolver,
   resolveController,
   resolveHandler,
-  resolveData,
-} from './wiring-registry.js';
-
-// Dockable base + implementations
+  resolveData
+} from "./wiring-registry.js";
+import { Dockable } from "./dockables/base.js";
+import { ControllerDock } from "./dockables/controller.js";
+import { DataSourceDock } from "./dockables/data-source.js";
+import { ActionDock, A2UI_EVENT_TO_DOM } from "./dockables/action.js";
+import { ProviderDock } from "./dockables/provider.js";
+import { LifecycleDock } from "./dockables/lifecycle.js";
 export {
-  Dockable,
+  A2UIRenderer,
+  A2UI_EVENT_TO_DOM,
+  ActionDock,
   ControllerDock,
   DataSourceDock,
-  ActionDock,
-  A2UI_EVENT_TO_DOM,
-  ProviderDock,
+  Dockable,
   LifecycleDock,
-} from './dockables/index.js';
+  ProviderDock,
+  Surface,
+  SurfaceManifest,
+  WiringEngine,
+  createDockables,
+  jsonlStream,
+  mcpStream,
+  mockStream,
+  registerController,
+  registerHandler,
+  registerResolver,
+  registerType,
+  registry,
+  resolveController,
+  resolveData,
+  resolveHandler,
+  resolveTag,
+  sseStream,
+  wiringRegistry,
+  wsStream
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/a2ui-runtime",
-  "version": "0.6.2",
+  "version": "0.6.6",
   "description": "A2UI runtime \u2014 renderer, registry, streams, surface manifest, and wiring primitives for the A2UI (Agent-to-UI) protocol. Framework-agnostic; pairs with any A2UI-conformant component set.",
   "type": "module",
   "exports": {
@@ -38,6 +38,14 @@
       "types": "./dockables/index.d.ts",
       "import": "./dockables/index.js",
       "default": "./dockables/index.js"
+    },
+    "./schema": {
+      "types": "./a2ui.schema.d.ts",
+      "default": "./a2ui.schema.d.ts"
+    },
+    "./types": {
+      "types": "./types.d.ts",
+      "default": "./types.d.ts"
     }
   },
   "files": [
@@ -45,7 +53,9 @@
     "dockables/",
     "controllers/",
     "README.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "a2ui.schema.d.ts",
+    "types.d.ts"
   ],
   "publishConfig": {
     "access": "public",

package/types.d.ts

@@ -0,0 +1,26 @@
+// AUTO-GENERATED re-export: runtime/types.d.ts now delegates to the schema codegen.
+// The schema (a2ui.schema.json) is the authoritative source for A2UIMessage shapes.
+// Regenerate with: node scripts/build/a2ui-schema-types.mjs
+
+export type {
+  A2UIMessage,
+  A2UIComponent,
+  CreateSurfaceMessage,
+  UpdateComponentsMessage,
+  UpdateDataModelMessage,
+  WireComponentsMessage,
+  WireAction,
+  WireDataSource,
+  WireState,
+  DeleteSurfaceMessage,
+  MetaMessage,
+} from './a2ui.schema.js';
+
+/** String literal union of all valid A2UI message type discriminators. */
+export type A2UIMessageType =
+  | 'createSurface'
+  | 'updateComponents'
+  | 'updateDataModel'
+  | 'wireComponents'
+  | 'deleteSurface'
+  | 'meta';