@adia-ai/a2ui 0.8.39 → 0.8.41

package/catalog/tiers/README.md

@@ -2,7 +2,13 @@
 
 The authoring home for the upper rungs of the catalog ladder (ADR-0050,
 gh#1243). **L0 is not authored here** — it derives from the assembled catalog
-(`../catalog-a2ui_0_9.json`, itself derived from component YAML).
+(`../catalog-a2ui_0_9.json`, itself derived from component YAML sourced from
+BOTH `packages/web-components/components` (primitives) and
+`packages/web-modules` (composite modules) — one shared YAML contract, one
+catalog. Every L0 entry in `../tier-index.json` carries `origin: "primitive"
+| "module"` recording which (ADR-0066 §2) — a module's component API sits at
+L0 same as a primitive's; its *assembled* composition is separately an L3
+unit (see ADR-0066 for the full component/module/pattern tier model).
 
     l1-<set>.json    widgets  — chat-scale functional units, composed of L0 entries
     l2-<set>.json    layouts  — composed of L1 entries
@@ -27,6 +33,18 @@ that resolves to neither — a native element (`FormContainer`,
 `DescriptionTerm`), a sub-descriptor (`ColDef`), or an upper-rung unit
 (`AdminShell`) — has no L0 entry and fails the build.
 
+The **emitted** index speaks the standard's vocabulary, not this authoring
+one: genui-system SPEC R-C13 rules that `composes` edges carry component
+TYPE names — the R-C7 catalogs' `components` keys, the same identifiers a
+wire node's `component` field carries (gh#1478, genui-system#16). After both
+law checks pass in catalog names, the derivation re-spells every
+L0-composing entry's `composes` into type names through
+`derive-genui-catalog.mjs`'s `canonicalTagTypeNames()` — the exact mapping
+that keys `base.json`/`adia-pack.json` — so `Col`/`Check`/`Select`/
+`Textarea` land in `tier-index.json` as `Column`/`CheckBox`/`ChoicePicker`/
+`TextArea`. Authored sources here stay in catalog names; only the artifact
+re-spells.
+
 ## File shape
 
 ```jsonc

package/catalog/tiers/l1-widgets.json

@@ -123,7 +123,7 @@
         "Timeline",
         "TimelineItem"
       ],
-      "version": "1.0.0",
+      "version": "1.0.1",
       "domain": "agent",
       "description": "Agent reasoning trace — thought process, tool calls, and interim results rendered as a timeline-ui of timeline-item rows. (agent-reasoning-ui is JS-property-driven and can't be authored statically — gh#916/gh#938; this is the documented static equivalent.)",
       "keywords": [
@@ -166,7 +166,7 @@
           "component": "TimelineItem",
           "description": "Detected intent: summarize churn risk for accounts renewing next month",
           "icon": "chat-circle-text",
-          "status": "done",
+          "status": "completed",
           "text": "Interpreted request"
         },
         {
@@ -175,7 +175,7 @@
           "description": "warehouse.accounts_renewals · 214 rows · filtered to next-30-days",
           "duration": "480ms",
           "icon": "database",
-          "status": "done",
+          "status": "completed",
           "text": "Queried account data"
         },
         {
@@ -184,7 +184,7 @@
           "description": "scoring_model.churn_v3(account_ids=214) → 214 scores",
           "duration": "1.1s",
           "icon": "function",
-          "status": "done",
+          "status": "completed",
           "text": "Called risk-scoring tool"
         },
         {
@@ -192,7 +192,7 @@
           "component": "TimelineItem",
           "description": "Kept scores > 0.6 · 18 accounts flagged high-risk",
           "icon": "funnel",
-          "status": "done",
+          "status": "completed",
           "text": "Ranked and filtered results"
         },
         {
@@ -200,7 +200,7 @@
           "component": "TimelineItem",
           "description": "Grouped by risk tier · drafted the response below",
           "icon": "pencil-simple",
-          "status": "done",
+          "status": "completed",
           "text": "Composed summary"
         },
         {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/a2ui",
-  "version": "0.8.39",
+  "version": "0.8.41",
   "description": "The A2UI protocol — runtime (renderer, registry, streams, surface manifest, wiring primitives, dockable base classes) plus protocol-side validation. Framework-agnostic and dependency-free; pairs with any A2UI-conformant component set. Folded from @adia-ai/a2ui-runtime + the protocol half of @adia-ai/a2ui-validator (ADR-0048).",
   "type": "module",
   "exports": {

package/registry.js

@@ -231,6 +231,12 @@ export const registry = new Map([
   // returning no real callers). Was a §175 baseline orphan; removing
   // the registry entry closes it cleanly.
   ['ChatThread',       'chat-thread'],          // §49 — re-routed to the chat web-module (was: chat-thread-ui primitive). The module owns scroll-to-bottom + streaming; primitive remains accessible via bare `chat-thread-ui` tag.
+  // gh#1427 — the primitive's own yaml `component:` field was still
+  // `ChatThread`, colliding with the module above at the catalog-build
+  // key (same defect class as the AppShell/admin-shell collision this
+  // ticket fixed); renamed to `UIChatThread` (matching its own `name:`)
+  // so it has a unique catalog key, mapped here to its existing bare tag.
+  ['UIChatThread',     'chat-thread-ui'],
   ['ChatInput',        'chat-input-ui'],
   ['OptionCard',       'option-card-ui'],
   ['Option',           'option-card-ui'],       // bare Option → option-card-ui

package/renderer.d.ts

@@ -17,6 +17,43 @@ export interface SurfaceState {
   elements: Map<string, HTMLElement>;
   dataModel: Record<string, unknown>;
   bindings: Map<string, unknown>;
+  /** False for a synthetic surface (updateComponents with no prior createSurface) — see `lifecycle`. */
+  synthetic: boolean;
+  /** Null for a synthetic surface — outside the lifecycle contract (spec-a2ui-surface-lifecycle.md). This is the LIVE internal record, not a copy — mutating it is undefined behavior; use the renderer's own API (beginSurfaceUpdate/commitSurfaceUpdate/abortSurfaceUpdate) to change it. */
+  lifecycle: Readonly<SurfaceLifecycle> | null;
+}
+
+/** Surface lifecycle state (spec-a2ui-surface-lifecycle.md, ADR-0061, gh#1364). */
+export type SurfaceLifecycleState =
+  | 'empty' | 'pending-first' | 'live' | 'pending-stale' | 'error-empty' | 'error-stale';
+
+/** Per-surface lifecycle record, stored alongside elements/dataModel/bindings. */
+export interface SurfaceLifecycle {
+  state: SurfaceLifecycleState;
+  /** Current in-flight generation id, or null when not pending. */
+  generationId: string | null;
+  /** Messages buffered since the last begin, applied atomically at commit. */
+  buffer: (A2UIMessage | Record<string, unknown>)[] | null;
+  mode: 'replace' | 'patch';
+  /** Advisory reason recorded by the currently (or most recently) open bracket, or null. */
+  reason: 'refine' | 'revalidate' | 'regenerate' | null;
+  /** True while the surface carries an unhealed abort (error-empty/error-stale); the next successful commit clears it (REQ-007). */
+  hadError: boolean;
+}
+
+export interface BeginSurfaceUpdateOptions {
+  /** Caller-supplied generation id; minted when omitted. */
+  generationId?: string;
+  /** Advisory — why this bracket opened. */
+  reason?: 'refine' | 'revalidate' | 'regenerate';
+  /** `replace` (default) sweeps components the new answer no longer declares; `patch` is upsert-only. */
+  mode?: 'replace' | 'patch';
+}
+
+export interface SurfaceLifecycleError {
+  code?: string;
+  message?: string;
+  [key: string]: unknown;
 }
 
 export declare class A2UIRenderer {
@@ -64,4 +101,44 @@ export declare class A2UIRenderer {
 
   /** Enable or disable RAF batching at runtime. */
   batching: boolean;
+
+  // ── Surface lifecycle (spec-a2ui-surface-lifecycle.md, ADR-0061, gh#1364) ──
+
+  /**
+   * Begin a regeneration bracket for `surfaceId`. Returns the minted/echoed
+   * generationId, or null (no-op) for a missing or synthetic surface.
+   */
+  beginSurfaceUpdate(surfaceId: string, opts?: BeginSurfaceUpdateOptions): string | null;
+
+  /**
+   * Apply messages targeting `surfaceId` — buffers while pending, applies
+   * immediately otherwise (identical to process() per message).
+   */
+  applyTo(surfaceId: string, messages: (A2UIMessage | Record<string, unknown>) | (A2UIMessage | Record<string, unknown>)[]): void;
+
+  /**
+   * Commit the in-flight generation — applies the buffered bracket
+   * atomically. Returns false when there was nothing to commit or the
+   * generationId was superseded (ignored, not an error). `async`: awaits
+   * any buffered `wireComponents` (and the dynamic import + docking it
+   * may trigger) before the replace-mode sweep runs, so swept ids that
+   * were also freshly wired this same bracket are correctly undocked.
+   */
+  commitSurfaceUpdate(surfaceId: string, generationId?: string): Promise<boolean>;
+
+  /**
+   * Abort the in-flight generation — stale content (if any) stays visible.
+   * Returns false when there was nothing to abort or the generationId was
+   * superseded.
+   */
+  abortSurfaceUpdate(surfaceId: string, generationId?: string, error?: SurfaceLifecycleError): boolean;
+
+  /** Read-only lifecycle snapshot for `surfaceId`, or null (missing/synthetic). Live internal record — see SurfaceState.lifecycle. */
+  getLifecycle(surfaceId: string): Readonly<SurfaceLifecycle> | null;
+
+  /** True while `surfaceId` has an in-flight generation. */
+  isPending(surfaceId: string): boolean;
+
+  /** IDs of every surface currently pending. */
+  readonly pendingSurfaces: string[];
 }