@adia-ai/gen-ui 0.8.37

package/compose/README.md

@@ -0,0 +1,215 @@
+# @adia-ai/a2ui-compose
+
+Framework-agnostic UI generation engine. Constitution doc:
+[`.claude/docs/specs/compose-constitution.md`](../../../.claude/docs/specs/compose-constitution.md).
+Takes a natural-language intent +
+an A2UI component catalog and produces a tree of A2UI protocol messages
+ready for a renderer.
+
+> This package is pipeline runtime only. UI components live in
+> [`@adia-ai/web-components`](../../web-components); the A2UI runtime (renderer,
+> registry, streams, wiring) in [`@adia-ai/a2ui-runtime`](../../a2ui);
+> the pattern corpus in [`@adia-ai/a2ui-corpus`](../corpus);
+> the MCP server in [`@adia-ai/mcp`](../../mcp) (its `gen-ui` surface).
+>
+> Published to the public `@adia-ai` scope on 2026-04-24 alongside
+> `a2ui-corpus`, `a2ui-mcp`, `a2ui-retrieval`, and `a2ui-validator`.
+
+## Install
+
+```bash
+npm install @adia-ai/a2ui-compose
+```
+
+Typically paired with `@adia-ai/a2ui-corpus` (the pattern corpus the engine reads from) and `@adia-ai/llm` (the LLM client; runtime peer-dep):
+
+```bash
+npm install @adia-ai/a2ui-compose @adia-ai/a2ui-corpus @adia-ai/llm
+```
+
+## What it does
+
+```
+intent  ─▶  classify  ─▶  retrieve  ─▶  compose / adapt  ─▶  validate  ─▶  A2UI
+           (concepts)    (patterns)     (engine-specific)     (score ≥70)    JSON
+```
+
+One entry point, two generation strategies, pluggable LLM back-end.
+
+```javascript
+import { generateUI } from '@adia-ai/a2ui-compose/core';
+
+const result = await generateUI({
+  intent: 'login form with email, password, and remember-me',
+  engine: 'zettel',        // 'monolithic' | 'zettel' | 'free-form' | 'chunk-zettel' | 'auto'
+  mode:   'pro',           // monolithic only: instant | pro | thinking
+  model:  'claude-sonnet-4-7',
+});
+
+// result.components   — A2UI message array
+// result.validation   — { score, checks, warnings }
+// result.debug        — pattern matches, LLM prompt, token usage, …
+```
+
+## Layout
+
+```
+a2ui-compose/
+├── core/                   orchestrator — state, dispatch, pipeline (formerly engine/)
+│   ├── generator.js        generateUI() — the one public entry point
+│   ├── state.js            ArtifactStore + PipelineEngine singletons
+│   └── pipeline/           6-stage pipeline engine
+│
+├── strategies/             pluggable engines via registerEngine() (formerly engines/)
+│   ├── registry.js         engine selector + reserved-name guard
+│   ├── cascade.js          the escalation ladder as an @adia-ai/agent workflow
+│   ├── escalation.js       the one hit-or-climb rule the ladder reads
+│   ├── monolithic/         pattern-match + LLM-adapt (3 modes)
+│   │   ├── generate-instant.js   no LLM — pattern-match only
+│   │   ├── generate-pro.js       pattern + LLM adaptation, non-streaming
+│   │   └── generate-thinking.js  streaming LLM + repair loop
+│   └── zettel/             fragment-graph composition
+│       ├── generator-adapter.js  entry point
+│       ├── composer.js           assembles fragments → compositions
+│       └── session-store.js      multi-turn state (Phase A)
+│
+├── retrieval/
+│   ├── catalog.js          loads component schemas from sibling .a2ui.json
+│   ├── pattern-library.js  keyword-ranked pattern search (corpus + embeddings)
+│   ├── fragments.js        atomic-shape lookup for zettel
+│   ├── anti-patterns.js    catalog of canonical anti-patterns
+│   └── feedback-store.js   accumulates user feedback → disk
+│
+├── llm/
+│   ├── llm-bridge.js       unified adapter (Anthropic / OpenAI / Gemini)
+│   ├── env.js              Vite + Node env-var routing
+│   └── prompts/            system prompts per engine mode
+│
+├── validation/
+│   └── validator.js        15-check A2UI validator, weighted 0–100 score
+│
+├── intelligence/           intent classification + concept extraction
+│   ├── classifier.js
+│   ├── concepts.js
+│   └── steelman.js
+│
+└── evals/
+    └── harness.mjs         held-out intent benchmark runner
+```
+
+## Engines
+
+**Monolithic** — pattern-match against full-canvas templates, optionally
+adapt via LLM. Three modes:
+
+| Mode       | LLM? | Speed  | Use for                                         |
+|------------|------|--------|-------------------------------------------------|
+| `instant`  | no   | <50ms  | High-confidence intents with exact pattern hit  |
+| `pro`      | yes  | ~2s    | Most requests — adapt a template to the intent  |
+| `thinking` | yes  | ~5s    | Complex requests; streams + runs a repair loop  |
+
+**Zettel** — fragment-graph composition. Retrieves atomic fragments
+(form-field, card-header, action-row, …) by keyword + concept-tag overlap
+and assembles them into compositions. Verbatim retrieval above a threshold
+(score ≥ 40); LLM synthesis from fragments below. Preserves session state
+across multi-turn iterations.
+
+```javascript
+import { registerEngine } from '@adia-ai/a2ui-compose/strategies/registry';
+
+registerEngine('my-engine', async (ctx) => {
+  // ctx: intent, catalog, patterns, concepts, session, llm, …
+  return { components: [...], validation: {...}, debug: {...} };
+});
+```
+
+**Auto** — the escalation ladder over the engines above: `zettel` →
+`free-form` → `monolithic-instant` → `monolithic-pro`, cheapest first, each
+step accepted or rejected by the shared escalation rule
+(`strategies/escalation.js`) and the last step terminal. It is declared as an
+[`@adia-ai/agent`](../../agent/README.md) workflow in
+`strategies/cascade.js`, so the ladder is data — `ENGINE_LADDER` — and the
+result carries `escalations` (`{from, to, trigger}`) as its trace.
+
+```javascript
+const result = await generateUI({ intent, engine: 'auto' });
+result.engine;        // the engine that won
+result.escalations;   // [{ from: 'zettel', to: 'free-form', trigger: 'non-emission-strategy' }]
+```
+
+Pass `gate` on the context for an extra async accept check (a schema +
+catalog exit gate); pass `ladder` to run a different tier order.
+
+Reserved names: `monolithic`, `monolithic-*`, `zettel`, `chunk-zettel`,
+`free-form`, `auto`.
+
+## Validation
+
+Every generated output runs through `validation/validator.js` — 15 weighted
+checks covering structural validity, card/grid conventions, intent
+alignment (F1), and anti-patterns. Result:
+
+```javascript
+{
+  score: 92,                    // 0-100
+  passed: true,                 // score ≥ 70
+  checks: [
+    { id: 'structure',   ok: true,  weight: 10 },
+    { id: 'intent-f1',   ok: true,  weight: 8, value: 0.84 },
+    { id: 'card-grid',   ok: true,  weight: 6 },
+    { id: 'anti-pattern', ok: false, weight: 4, hit: 'chart-legend' },
+    …
+  ]
+}
+```
+
+`_fallback` surfaces score 0 by design — ensure the engine returns real
+output, not a safety net.
+
+## LLM bridge
+
+Multi-provider adapter with a common interface:
+
+```javascript
+import { getAdapter } from '@adia-ai/llm';
+
+const adapter = getAdapter('anthropic');     // or 'openai', 'gemini'
+const stream = await adapter.streamChat({ model, messages, tools });
+```
+
+Env-var routing via `llm/env.js` — works under Node (`process.env`) and
+Vite (`import.meta.env`). Browser calls proxy through `server.js` at the
+repo root (holds API keys); Node calls go direct.
+
+## Evals
+
+```bash
+npm run evals              # held-out intent benchmark
+npm run eval:diff -- --engine zettel    # diff against baseline
+```
+
+The held-out fixture lives in `@adia-ai/a2ui-corpus`'s `evals/held-out.jsonl`.
+Regression thresholds the pipeline must hold:
+
+- Zettel coverage **100%**, avgScore **≥ 88**, MRR **≥ 0.94**
+- Monolithic coverage **100%**, avgScore **≥ 95**
+- Fragment reuse ratio **≥ 29.9%** (167 refs / 559 nodes)
+
+Full gate sweep: see `AGENTS.md` at repo root, or run `/verification-sweep`.
+
+## Gotchas
+
+- **Component catalog is read-only.** `.a2ui.json` sidecars in
+  `web-components/components/*/` are build outputs; edit the sibling YAML
+  instead.
+- **Zettel loading is lazy.** The corpus is only parsed on first zettel
+  call — avoids Node `fs`/`path` imports reaching the browser bundle.
+- **Validator score ≥ 70 is required** for downstream consumers to trust
+  the output. Below that, callers should treat the tree as advisory.
+- **Engine name reservations** are enforced at registration time —
+  `registerEngine('zettel-v2', …)` passes; `registerEngine('zettel', …)`
+  throws.
+
+## License
+
+MIT

package/compose/core/artifacts.js

@@ -0,0 +1,262 @@
+/**
+ * ArtifactStore — In-memory artifact storage for pipeline executions.
+ *
+ * Stores A2UI message sequences keyed by executionId, with multi-turn
+ * history (iterations). Each turn records the messages, optional HTML
+ * render, a human-readable summary, and the intent that produced it.
+ *
+ * Drift detection: measures structural divergence between turns to flag
+ * scope creep in iterative generation sessions.
+ */
+
+export class ArtifactStore {
+  #artifacts = new Map(); // executionId → { turns: [], metadata }
+
+  /**
+   * Record a turn (iteration) for an execution.
+   *
+   * @param {string} executionId
+   * @param {object} opts
+   * @param {object[]} opts.messages — A2UI message sequence
+   * @param {string} [opts.html] — Optional rendered HTML snapshot
+   * @param {string} [opts.summary] — Human-readable description
+   * @param {object} [opts.validation] — Validation result from validateSchema
+   * @param {string} [opts.intent] — The user intent for this turn
+   */
+  record(executionId, { messages, html = null, summary = '', validation = null, intent = '', analysis = null }) {
+    let artifact = this.#artifacts.get(executionId);
+    if (!artifact) {
+      artifact = {
+        executionId,
+        turns: [],
+        metadata: {
+          created: Date.now(),
+          updated: Date.now(),
+          originalIntent: intent || summary || '',
+          // Stash the first turn's analyzer output so iteration turns can
+          // recover the original brief's concepts/entities/components for
+          // canvas-aware downstream decisions (e.g. suggestion generation,
+          // drift detection). Iteration turns skip the analyzer, so this is
+          // the only durable handle on what the user originally asked for.
+          originalAnalysis: analysis || null,
+        },
+      };
+      this.#artifacts.set(executionId, artifact);
+    }
+
+    // Extract structural snapshot for drift tracking
+    const components = messages?.flatMap(m => m.components || []) || [];
+    const snapshot = _buildStructuralSnapshot(components);
+
+    artifact.turns.push({
+      turn: artifact.turns.length,
+      messages,
+      html,
+      summary,
+      validation,
+      intent: intent || summary || '',
+      snapshot,
+      timestamp: Date.now(),
+    });
+
+    artifact.metadata.updated = Date.now();
+  }
+
+  /**
+   * Get a specific turn for an execution.
+   *
+   * @param {string} executionId
+   * @param {number} [turn=-1] — Turn index (negative counts from end; -1 = latest)
+   * @returns {object|null}
+   */
+  get(executionId, turn = -1) {
+    const artifact = this.#artifacts.get(executionId);
+    if (!artifact || artifact.turns.length === 0) return null;
+
+    const idx = turn < 0 ? artifact.turns.length + turn : turn;
+    return artifact.turns[idx] ?? null;
+  }
+
+  /**
+   * Get all turns for an execution.
+   *
+   * @param {string} executionId
+   * @returns {object[]|null}
+   */
+  getAll(executionId) {
+    const artifact = this.#artifacts.get(executionId);
+    if (!artifact) return null;
+    return [...artifact.turns];
+  }
+
+  /**
+   * Get the original (first turn) prompt analyzer output for an execution.
+   * Used by iteration turns that need to recover the original concepts /
+   * implied components / steelman to drive canvas-aware decisions.
+   * @param {string} executionId
+   * @returns {object|null}
+   */
+  getOriginalAnalysis(executionId) {
+    const artifact = this.#artifacts.get(executionId);
+    return artifact?.metadata?.originalAnalysis || null;
+  }
+
+  /**
+   * Get the original (first turn) intent for an execution.
+   * @param {string} executionId
+   * @returns {string|null}
+   */
+  getOriginalIntent(executionId) {
+    const artifact = this.#artifacts.get(executionId);
+    return artifact?.metadata?.originalIntent || null;
+  }
+
+  /**
+   * Compute drift metrics between the first turn and the latest turn.
+   *
+   * Returns null if there are fewer than 2 turns.
+   *
+   * @param {string} executionId
+   * @returns {{ componentGrowth: number, sectionGrowth: number, newSections: string[], driftScore: number, turnCount: number, warning: string|null }|null}
+   */
+  getDriftMetrics(executionId) {
+    const artifact = this.#artifacts.get(executionId);
+    if (!artifact || artifact.turns.length < 2) return null;
+
+    const first = artifact.turns[0].snapshot;
+    const latest = artifact.turns[artifact.turns.length - 1].snapshot;
+    if (!first || !latest) return null;
+
+    // Component count growth ratio
+    const componentGrowth = first.componentCount > 0
+      ? latest.componentCount / first.componentCount
+      : latest.componentCount;
+
+    // Section count growth ratio
+    const sectionGrowth = first.sectionCount > 0
+      ? latest.sectionCount / first.sectionCount
+      : latest.sectionCount;
+
+    // New sections added since turn 0
+    const originalSections = new Set(first.sectionNames);
+    const newSections = latest.sectionNames.filter(s => !originalSections.has(s));
+
+    // Component type diversity change
+    const originalTypes = new Set(first.componentTypes);
+    const newTypes = latest.componentTypes.filter(t => !originalTypes.has(t));
+
+    // Drift score: 0 = no drift, 1 = extreme drift
+    // Weighted: 40% component growth, 30% section growth, 30% new sections
+    const growthFactor = Math.min(componentGrowth / 3, 1); // 3x = max
+    const sectionFactor = Math.min(sectionGrowth / 3, 1);
+    const newSectionFactor = Math.min(newSections.length / 4, 1); // 4+ new = max
+    const driftScore = Math.round((growthFactor * 0.4 + sectionFactor * 0.3 + newSectionFactor * 0.3) * 100) / 100;
+
+    // Warning thresholds
+    let warning = null;
+    if (driftScore >= 0.7) {
+      warning = `High canvas drift detected (score: ${driftScore}). Canvas grew from ${first.componentCount} to ${latest.componentCount} components across ${artifact.turns.length} turns. ${newSections.length} new sections added: ${newSections.join(', ')}. Consider confirming with user that this matches original intent: "${artifact.metadata.originalIntent}"`;
+    } else if (driftScore >= 0.4) {
+      warning = `Moderate canvas drift (score: ${driftScore}). Canvas: ${first.componentCount} → ${latest.componentCount} components. ${newSections.length} new sections added.`;
+    }
+
+    return {
+      componentGrowth: Math.round(componentGrowth * 100) / 100,
+      sectionGrowth: Math.round(sectionGrowth * 100) / 100,
+      newSections,
+      newTypes,
+      driftScore,
+      turnCount: artifact.turns.length,
+      originalIntent: artifact.metadata.originalIntent,
+      warning,
+    };
+  }
+
+  /**
+   * List all execution summaries.
+   *
+   * @returns {object[]}
+   */
+  list() {
+    const results = [];
+    for (const [id, artifact] of this.#artifacts) {
+      const latest = artifact.turns[artifact.turns.length - 1];
+      results.push({
+        executionId: id,
+        turnCount: artifact.turns.length,
+        latestSummary: latest?.summary ?? '',
+        latestScore: latest?.validation?.score ?? null,
+        originalIntent: artifact.metadata.originalIntent ?? '',
+        created: artifact.metadata.created,
+        updated: artifact.metadata.updated,
+      });
+    }
+    return results;
+  }
+
+  /**
+   * Delete an execution's artifacts.
+   *
+   * @param {string} executionId
+   * @returns {boolean} — true if deleted
+   */
+  delete(executionId) {
+    return this.#artifacts.delete(executionId);
+  }
+
+  /**
+   * Clear all artifacts.
+   */
+  clear() {
+    this.#artifacts.clear();
+  }
+
+  /** Number of stored executions */
+  get size() {
+    return this.#artifacts.size;
+  }
+}
+
+/**
+ * Build a structural snapshot of the canvas for drift comparison.
+ * Extracts component count, section names, component types —
+ * the metrics that indicate structural changes.
+ *
+ * @param {object[]} components — flat A2UI component array
+ * @returns {{ componentCount: number, sectionCount: number, sectionNames: string[], componentTypes: string[] }}
+ */
+function _buildStructuralSnapshot(components) {
+  if (!components || components.length === 0) {
+    return { componentCount: 0, sectionCount: 0, sectionNames: [], componentTypes: [] };
+  }
+
+  const sectionNames = [];
+  for (const c of components) {
+    if (c.component === 'Card') {
+      // Find the title of this Card section
+      const headerChild = components.find(
+        h => h.parentId === c.id && (h.component === 'Header' || h.component === 'CardHeader')
+      );
+      if (headerChild) {
+        const titleChild = components.find(
+          t => t.parentId === headerChild.id && t.component === 'Text'
+        );
+        sectionNames.push(titleChild?.text || titleChild?.children || headerChild.title || c.id);
+      } else {
+        sectionNames.push(c.id);
+      }
+    }
+  }
+
+  const typeSet = new Set();
+  for (const c of components) {
+    if (c.component) typeSet.add(c.component);
+  }
+
+  return {
+    componentCount: components.length,
+    sectionCount: sectionNames.length,
+    sectionNames,
+    componentTypes: [...typeSet].sort(),
+  };
+}

package/compose/core/context-store.js

@@ -0,0 +1,218 @@
+/**
+ * Context Store — Cross-surface shared state (A008 §8).
+ *
+ * Manages named contexts that multiple surfaces can read from and write to.
+ * When the first participating surface mounts, the context is populated.
+ * When the last participating surface unmounts, the context is eligible
+ * for garbage collection.
+ *
+ * This is the horizontal equivalent of A007's provider (vertical, parent→child).
+ * Contexts live outside any single surface's lifecycle.
+ */
+
+/**
+ * @typedef {object} ContextEntry
+ * @property {string} name
+ * @property {object} shape — Schema of the context data
+ * @property {object} data — Current data
+ * @property {Set<string>} participants — Surface IDs consuming this context
+ * @property {object} source — How to populate { uri, refresh, params }
+ * @property {boolean} populated — Whether data has been fetched
+ * @property {Set<(data: object) => void>} listeners — Change listeners
+ */
+
+export class ContextStore {
+  /** @type {Map<string, ContextEntry>} */
+  #contexts = new Map();
+
+  /**
+   * Define a shared context (usually from a surface manifest).
+   *
+   * @param {string} name — Context name
+   * @param {object} config
+   * @param {object} config.shape — Data shape schema
+   * @param {object} [config.source] — { uri, refresh, params }
+   */
+  define(name, config) {
+    if (this.#contexts.has(name)) return; // Already defined
+
+    this.#contexts.set(name, {
+      name,
+      shape: config.shape || {},
+      data: {},
+      participants: new Set(),
+      source: config.source || null,
+      populated: false,
+      listeners: new Set(),
+    });
+  }
+
+  /**
+   * Register a surface as a participant in a context.
+   * If this is the first participant and a source is defined, triggers population.
+   *
+   * @param {string} contextName
+   * @param {string} surfaceId
+   * @param {(uri: string, params: Record<string, string>) => Promise<unknown>} [fetcher] — Data fetcher
+   * @param {Record<string, string>} [params]
+   */
+  async join(contextName, surfaceId, fetcher, params = {}) {
+    let ctx = this.#contexts.get(contextName);
+    if (!ctx) {
+      // Auto-define if not pre-defined
+      ctx = { name: contextName, shape: {}, data: {}, participants: new Set(), source: null, populated: false, listeners: new Set() };
+      this.#contexts.set(contextName, ctx);
+    }
+
+    ctx.participants.add(surfaceId);
+
+    // Populate on first join (if source exists and not already populated)
+    if (!ctx.populated && ctx.source && fetcher) {
+      try {
+        let uri = ctx.source.uri;
+        const resolvedParams = { ...ctx.source.params, ...params };
+        for (const [key, spec] of Object.entries(resolvedParams)) {
+          const value = typeof spec === 'string' ? spec : spec.value || '';
+          uri = uri.replace(`{${key}}`, encodeURIComponent(value));
+        }
+        ctx.data = await fetcher(uri, resolvedParams);
+        ctx.populated = true;
+        this.#notify(contextName);
+      } catch (err) {
+        console.warn(`ContextStore: failed to populate "${contextName}":`, err.message);
+      }
+    }
+
+    return ctx.data;
+  }
+
+  /**
+   * Unregister a surface from a context.
+   * If no participants remain, mark for potential cleanup.
+   *
+   * @param {string} contextName
+   * @param {string} surfaceId
+   */
+  leave(contextName, surfaceId) {
+    const ctx = this.#contexts.get(contextName);
+    if (!ctx) return;
+
+    ctx.participants.delete(surfaceId);
+
+    // Eligible for GC when no participants
+    if (ctx.participants.size === 0) {
+      ctx.populated = false;
+      ctx.data = {};
+    }
+  }
+
+  /**
+   * Get the current data for a context.
+   *
+   * @param {string} contextName
+   * @returns {object | null}
+   */
+  get(contextName) {
+    return this.#contexts.get(contextName)?.data ?? null;
+  }
+
+  /**
+   * Read a specific key from a context.
+   *
+   * @param {string} contextName
+   * @param {string} key — Dot-separated path (e.g., "patient.name")
+   * @returns {unknown}
+   */
+  read(contextName, key) {
+    const data = this.get(contextName);
+    if (!data || !key) return data;
+
+    const segments = key.split('.');
+    let current = data;
+    for (const seg of segments) {
+      if (current == null || typeof current !== 'object') return undefined;
+      current = current[seg];
+    }
+    return current;
+  }
+
+  /**
+   * Update data in a context. Notifies all listeners.
+   *
+   * @param {string} contextName
+   * @param {object} data — Partial or full data update (merged)
+   */
+  update(contextName, data) {
+    const ctx = this.#contexts.get(contextName);
+    if (!ctx) return;
+
+    ctx.data = { ...ctx.data, ...data };
+    ctx.populated = true;
+    this.#notify(contextName);
+  }
+
+  /**
+   * Subscribe to context changes.
+   *
+   * @param {string} contextName
+   * @param {(data: object) => void} listener
+   * @returns {() => void} — Unsubscribe function
+   */
+  subscribe(contextName, listener) {
+    const ctx = this.#contexts.get(contextName);
+    if (!ctx) return () => {};
+
+    ctx.listeners.add(listener);
+    return () => ctx.listeners.delete(listener);
+  }
+
+  /**
+   * Check if a context is populated with data.
+   * @param {string} contextName
+   * @returns {boolean}
+   */
+  isPopulated(contextName) {
+    return this.#contexts.get(contextName)?.populated ?? false;
+  }
+
+  /**
+   * Get all defined context names.
+   * @returns {string[]}
+   */
+  get contextNames() {
+    return [...this.#contexts.keys()];
+  }
+
+  /**
+   * Get diagnostic info for a context.
+   * @param {string} contextName
+   */
+  inspect(contextName) {
+    const ctx = this.#contexts.get(contextName);
+    if (!ctx) return null;
+    return {
+      name: ctx.name,
+      populated: ctx.populated,
+      participantCount: ctx.participants.size,
+      participants: [...ctx.participants],
+      listenerCount: ctx.listeners.size,
+      dataKeys: Object.keys(ctx.data),
+    };
+  }
+
+  /** Clear all contexts. */
+  clear() {
+    this.#contexts.clear();
+  }
+
+  #notify(contextName) {
+    const ctx = this.#contexts.get(contextName);
+    if (!ctx) return;
+    for (const listener of ctx.listeners) {
+      try { listener(ctx.data); } catch { /* listener error */ }
+    }
+  }
+}
+
+/** Singleton shared context store for the application. */
+export const sharedContextStore = new ContextStore();

package/compose/core/generator.d.ts

@@ -0,0 +1,4 @@
+// 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 {};