@adia-ai/a2ui-compose 0.4.5 → 0.4.6

package/CHANGELOG.md

@@ -12,6 +12,42 @@ generator graph.
 
 _No pending changes._
 
+## [0.4.6] - 2026-05-12
+
+### Changed — `core/` retirement follow-through (§64, v0.4.6)
+
+Companion to `@adia-ai/a2ui-retrieval@0.4.6` retiring `pattern-library.js`:
+
+- **`compose/core/pattern-export.js`** retired — no consumers post-§64 (the export shape targeted the retired pattern-library surface).
+- **`compose/core/reference.js`** — updated to delegate to `composition-library` instead of the retired `pattern-library`.
+- **`compose/core/generator.js`** — dropped pattern-export wiring; system-prompt path consumes compositions directly via §66's `adaptV09Component()`.
+
+### Changed — `buildSystemPrompt` reads canonical `.a2ui.json` sidecars (§66, v0.4.6)
+
+Closes the catalog-drift surface that §56 explicitly deferred ("different schema shapes; restructuring `getComponentCatalog()` is its own arc"). The monolithic prompt builder now reads from the v0.9 `.a2ui.json` sidecars (generated from yamls by `npm run components`) instead of the legacy hand-maintained `_components.json` catalog.
+
+**Root cause uncovered during audit:** `strategies/monolithic/_shared.js` (pre-§66) called `getComponentData(typeName)` returning the raw v0.9 sidecar — `{title, description, properties, x-adiaui}` (JSON Schema shape) — but the prompt builder code did `a2uiData.props ? Object.entries(a2uiData.props)`. The v0.9 shape uses `properties`, not `props`. **Every prompt was silently falling through to the legacy `_components.json` catalog** because every v0.9 lookup looked empty. The "canonical sidecar reads" path was wired but dead code.
+
+**Fix:** new `adaptV09Component()` helper at the top of `_shared.js` (~90 LOC) normalizes the v0.9 sidecar shape to the legacy `{tag, category, description, props, events, slots, examples, aliases, keywords}` shape the rest of the prompt builder was written for. Properties map 1:1 (skipping `component` discriminator + `children` container + `const`-only fields). Type names map JSON-Schema lowercase → legacy Title-Case (`string`→`String`, `boolean`→`Boolean`, etc.).
+
+**Empirical fidelity gain** (Button as canonical primitive):
+
+| Source | Props surfaced |
+|---|---|
+| `_components.json` (legacy, before §66) | 7: `text, variant, size, disabled, block, icon, type` (`block` is stale — removed from yaml in an earlier arc but never cleaned up in the hand-maintained catalog) |
+| v0.9 sidecar (canonical, after §66) | 10: `type, aria-label, color, disabled, icon, size, stretch, text, textContent, variant` |
+
+**§66 surfaces ~30% more catalog data** for the LLM, all traceable to a yaml SoT that `npm run components` regenerates on demand. This is exactly the catalog drift §56 flagged: when the team added `Select.size` (§50) and `inputmode`/`autocomplete` (§51) to the yamls, those props went into the v0.9 sidecars but never propagated to `_components.json`. The LLM was getting a stale catalog view that excluded recent additions. After §66, the LLM gets the actual ground truth.
+
+**Pitfalls encoded in the adapter** (5 v0.9-shape gotchas):
+1. `events` is an object `{eventName: {description}}`, not an array. Normalize to `string[]`.
+2. `slots` is also object-shaped. Same fix.
+3. `synonyms.tags` may be null/undefined. Wrap in `Array.isArray()` guard.
+4. `component` and `children` properties on every v0.9 sidecar are discriminator/container fields, not user-facing props. Skip in the adapter loop.
+5. `const` fields (e.g. `{const: 'Button'}`) are discriminator-only. Skip.
+
+Source: `packages/a2ui/compose/strategies/monolithic/_shared.js` (+91, -2 lines, commit `afda98f5`).
+
 ## [0.4.5] - 2026-05-12
 
 ### Changed — GenUI overhaul prompt-engineering (§56, v0.4.5)

package/core/generator.js

@@ -17,7 +17,6 @@ import { store, engine } from './state.js';
 import { checkIntentAlignment } from '../../retrieval/intent/intent-alignment.js';
 import { decomposeIntent, composeSubtasks } from '../../retrieval/intent/decomposer.js';
 import { getWiringCatalog } from '../../retrieval/wiring-catalog.js';
-import { getComponentData } from '../../retrieval/pattern-library.js';
 
 import { StubLLMAdapter } from '../../../llm/llm-stub.js';
 import { createAdapter } from '../../../llm/llm-bridge.js';

package/core/reference.js

@@ -1,16 +1,44 @@
 /**
- * Reference Tools — Delegates to A003 intelligence system.
+ * Reference Tools — stable generative-system API surface.
  *
- * Thin wrappers that provide a stable generative-system API surface
- * over the intelligence module. Used by the generator and pipeline stages
- * to look up components, patterns, and domain context.
+ * Thin wrappers used by the monolithic engines + generator pipeline.
+ * §64 migrated the "pattern" surface from `pattern-library.js` (retired)
+ * to the zettel `composition-library.js`. Function names kept
+ * (searchBlocks/lookupPattern/listPatterns/searchBlocksSemantic) for
+ * back-compat with engine call sites; internally they hit compositions.
  */
 
 import { getCatalog, getComponent, getComponentsByCategory } from '../../retrieval/index.js';
 import { classifyIntent, assembleContext } from '../../retrieval/index.js';
-import { getAllPatterns, searchPatterns, getPattern, semanticSearchPatterns } from '../../retrieval/index.js';
 import { checkAllAntiPatterns } from '../../retrieval/index.js';
 import { serializeEntry } from '../../retrieval/index.js';
+import {
+  searchAll as searchCompositions,
+  getComposition,
+  getAllCompositions,
+} from '../strategies/zettel/composition-library.js';
+
+/**
+ * Compositions have `tags: { purpose: [...], complexity: "", layout: "" }`
+ * but the monolithic engines (instant/pro/thinking) all assume the old
+ * pattern shape `tags: [string]` and call `.map(...)` on it. Flatten on
+ * the way out so legacy call sites keep working without re-templating
+ * every engine. Annotated chunks expose flat-but-shallow `tags`; both
+ * are handled.
+ */
+function normalize(record) {
+  if (!record) return record;
+  let tags = record.tags;
+  if (Array.isArray(tags)) return record;
+  if (tags && typeof tags === 'object') {
+    tags = Object.values(tags)
+      .flat()
+      .filter((v) => typeof v === 'string');
+  } else {
+    tags = [];
+  }
+  return { ...record, tags };
+}
 
 /**
  * Look up a single component by A2UI type name.
@@ -50,40 +78,47 @@ export async function getComponentsByGroup(category) {
 }
 
 /**
- * Search the pattern library by query.
+ * Search the composition library by query.
+ * Returns full composition records (rehydrated from name hits).
  * @param {string} query — Natural language or keyword query
  * @returns {object[]}
  */
 export function searchBlocks(query, { domain } = {}) {
-  return searchPatterns(query, { domain });
+  const hits = searchCompositions(query);
+  const records = hits.map((h) => getComposition(h.name)).filter(Boolean);
+  const filtered = domain ? records.filter((c) => c.domain === domain) : records;
+  return filtered.map(normalize);
 }
 
 /**
- * Get a specific named pattern.
- * @param {string} name — Pattern name (e.g. 'stat-cards', 'user-profile')
+ * Get a specific named composition.
+ * @param {string} name — Composition name
  * @returns {object|null}
  */
 export function lookupPattern(name) {
-  return getPattern(name);
+  return normalize(getComposition(name));
 }
 
 /**
- * Get all available patterns.
+ * Get all available compositions.
  * @returns {object[]}
  */
 export function listPatterns() {
-  return getAllPatterns();
+  return getAllCompositions().map(normalize);
 }
 
 /**
- * Semantic search — LLM-enhanced pattern matching.
- * Falls back to keyword search if no adapter provided.
+ * Keyword search wrapped as the legacy `{ matches }` return shape so the
+ * monolithic-thinking engine's call site keeps working. The historical
+ * LLM-driven semantic path retired with `pattern-library.js` in §64;
+ * compositions don't have a semantic search backend yet.
+ *
  * @param {string} query
- * @param {object} [options] — { llmAdapter, remix }
- * @returns {Promise<{ matches: object[], remix?: object }>}
+ * @param {object} [_options] — accepted for back-compat; llmAdapter/remix ignored
+ * @returns {Promise<{ matches: object[] }>}
  */
-export async function searchBlocksSemantic(query, options = {}) {
-  return semanticSearchPatterns(query, options);
+export async function searchBlocksSemantic(query, _options = {}) {
+  return { matches: searchBlocks(query) };
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/a2ui-compose",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "description": "AdiaUI A2UI compose engine — framework-agnostic. Takes natural-language intents + a catalog and produces A2UI protocol messages. Pairs with `@adia-ai/a2ui-retrieval` (intent classification, catalog lookup) and `@adia-ai/a2ui-validator` (schema + semantic checks).",
   "type": "module",
   "exports": {

package/strategies/_shared/chunk-loader.js

@@ -1,10 +1,11 @@
 /**
  * Dual-environment chunk loader — Node + browser.
  *
- * Mirrors the pattern in packages/a2ui/retrieval/pattern-library.js so the
- * gen-UI training chunks at packages/a2ui/corpus/chunks/*.json are reachable
- * from BOTH server-side engines (monolithic-pro via /api/generate's Node
- * process) AND browser-side engines (monolithic-pro called directly from
+ * Mirrors the dual-environment loading approach historically used by
+ * pattern-library.js (retired §64) so the gen-UI training chunks at
+ * packages/a2ui/corpus/chunks/*.json are reachable from BOTH server-side
+ * engines (monolithic-pro via /api/generate's Node process) AND
+ * browser-side engines (monolithic-pro called directly from
  * gen-ui playground's IIFE).
  *
  * The existing packages/a2ui/corpus/scripts/chunk-library.js is Node-only

package/strategies/monolithic/_shared.js

@@ -12,7 +12,91 @@ import { store } from '../../core/state.js';
 import { checkIntentAlignment } from '../../../retrieval/intent/intent-alignment.js';
 import { composeSubtasks } from '../../../retrieval/intent/decomposer.js';
 import { getWiringCatalog } from '../../../retrieval/wiring-catalog.js';
-import { getComponentData } from '../../../retrieval/pattern-library.js';
+import { getComponentData } from '../../../retrieval/component-catalog.js';
+
+// ── v0.9 .a2ui.json sidecar → prompt-catalog adapter ─────────────
+//
+// §66 (v0.4.6): the `.a2ui.json` sidecars produced by `npm run components`
+// are v0.9 JSON Schemas with `{title, description, properties, x-adiaui}`.
+// The legacy `_components.json` catalog this prompt builder originally
+// read had a flatter `{tag, category, description, props, events, slots,
+// examples, aliases, keywords}` shape. This adapter normalizes the v0.9
+// sidecar into the legacy shape so the rest of the prompt builder can stay
+// unchanged.
+//
+// Before §66, this code did `a2uiData.props` — which silently returned 0
+// props for every component (the v0.9 shape uses `properties`, not
+// `props`), causing every prompt to fall through to the `_components.json`
+// catalog. After §66, the canonical sidecar drives the prompt directly
+// and `_components.json` is retired (§64/§65).
+function adaptV09Component(a2uiData) {
+  if (!a2uiData || typeof a2uiData !== 'object') return null;
+  const ext = a2uiData['x-adiaui'] || {};
+  const properties = a2uiData.properties || {};
+
+  // Map v0.9 property → legacy prop shape. Skip the always-present
+  // `component` (const PascalCase name) + `children` (slot container)
+  // fields since they aren't user-facing props.
+  const props = {};
+  for (const [name, spec] of Object.entries(properties)) {
+    if (name === 'component' || name === 'children') continue;
+    if (spec?.const) continue; // discriminator-only fields
+    const out = {};
+    // JSON Schema type names are lowercase; legacy catalog used Title-Case.
+    if (spec.type) {
+      out.type = spec.type === 'string' ? 'String'
+        : spec.type === 'boolean' ? 'Boolean'
+        : spec.type === 'number' || spec.type === 'integer' ? 'Number'
+        : spec.type === 'array' ? 'Array'
+        : spec.type === 'object' ? 'Object'
+        : String(spec.type);
+    }
+    if (spec.enum) out.enum = spec.enum;
+    if (spec.default !== undefined) out.default = spec.default;
+    if (spec.description) out.description = spec.description;
+    props[name] = out;
+  }
+
+  // Events in the legacy catalog were a flat string[]. The v0.9 sidecar
+  // stores them as an object: `{eventName: {description}}` (verified
+  // across all 94 sidecars on 2026-05-12). Older code paths accepted
+  // either shape; normalize to a string[] of event names.
+  const eventsRaw = ext.events;
+  let events = [];
+  if (Array.isArray(eventsRaw)) {
+    events = eventsRaw.map((e) => (typeof e === 'string' ? e : e?.name)).filter(Boolean);
+  } else if (eventsRaw && typeof eventsRaw === 'object') {
+    events = Object.keys(eventsRaw);
+  }
+
+  // Slots — also object-shaped (`{slotName: {description, type}}`) in v0.9.
+  // Legacy catalog stored a string[]. Normalize.
+  const slotsRaw = ext.slots;
+  let slots = [];
+  if (Array.isArray(slotsRaw)) {
+    slots = slotsRaw.map((s) => (typeof s === 'string' ? s : s?.name)).filter(Boolean);
+  } else if (slotsRaw && typeof slotsRaw === 'object') {
+    slots = Object.keys(slotsRaw);
+  }
+
+  // Aliases live under `x-adiaui.synonyms.tags` in v0.9. The synonyms
+  // field is always an object (verified across all 94 sidecars). Surface
+  // the `tags` array — the prompt renders them as "Button (also: SubmitButton)".
+  const synonyms = (ext.synonyms && typeof ext.synonyms === 'object') ? ext.synonyms : null;
+  const aliases = Array.isArray(synonyms?.tags) ? synonyms.tags : null;
+
+  return {
+    tag: ext.tag || null,
+    category: ext.category || 'layout',
+    description: a2uiData.description || '',
+    props,
+    events,
+    slots,
+    examples: Array.isArray(ext.examples) ? ext.examples : [],
+    aliases,
+    keywords: Array.isArray(ext.keywords) ? ext.keywords : [],
+  };
+}
 
 // Component prop catalog — loaded lazily for prompt injection
 let _componentCatalog = null;
@@ -160,8 +244,13 @@ KEY RULES:
       return Array.isArray(a) && a.length ? `  (also: ${a.join(', ')})` : '';
     };
     for (const typeName of relevantTypes) {
-      // Prefer .a2ui.json data (new source of truth), fallback to _components.json
-      const a2uiData = getComponentData(typeName);
+      // §66 (v0.4.6): .a2ui.json sidecar is the canonical source of truth.
+      // The raw v0.9 shape uses `properties` (JSON Schema); adapt to the
+      // legacy `props` shape this prompt builder was originally written
+      // for. Falls back to the (soon-retired) `_components.json` only
+      // when no sidecar exists.
+      const v09Raw = getComponentData(typeName);
+      const a2uiData = v09Raw ? adaptV09Component(v09Raw) : null;
       if (a2uiData) {
         const props = a2uiData.props ? Object.entries(a2uiData.props).map(([k, v]) => {
           let desc = k;

package/strategies/monolithic/generate-instant.js

@@ -163,7 +163,7 @@ export async function generateInstant({ intent, executionId, storeId, analysis,
 
   engine.submitStage(execId, 'generate', {
     messages,
-    source: bestMatch ? 'pattern-library' : 'fallback',
+    source: bestMatch ? 'composition-library' : 'fallback',
     confidence: bestMatch ? 0.95 : 0.4,
   });
 

package/strategies/zettel/composition-library.js

@@ -62,6 +62,13 @@ function chunkToComposition(chunkDoc, sourcePath) {
   };
 }
 
+/**
+ * Track whether the eager top-level load has run. Multiple `loadAll`
+ * call sites (mcp/server.js bootstrap + any other consumer) re-clear
+ * + re-build, which is wasted work but not incorrect.
+ */
+let _autoLoaded = false;
+
 export function loadAll() {
   compositions.clear();
 
@@ -99,6 +106,7 @@ export function loadAll() {
     annotatedChunkCount++;
   });
 
+  _autoLoaded = true;
   return {
     compositionCount: compositions.size,
     handAuthoredCount: compositions.size - annotatedChunkCount,
@@ -106,6 +114,12 @@ export function loadAll() {
   };
 }
 
+// Eager top-level load so synchronous getters (getComposition,
+// getAllCompositions, searchAll) work for consumers that don't call
+// loadAll themselves — test harnesses, smoke scripts, and the
+// retrieval-side helpers migrated off pattern-library in §64.
+if (!_autoLoaded) loadAll();
+
 // Back-compat shims removed in §38 — fragment-library.js → composition-library.js
 // rename. The retired `getFragment` / `getAllFragments` exports had zero
 // external callers; drop them.

package/core/pattern-export.js

@@ -1,149 +0,0 @@
-/**
- * Pattern Export — Save generated UI as reusable named patterns.
- *
- * Produces two downloadable files:
- *   {name}.json — A2UI flat adjacency pattern (importable into pattern-library)
- *   {name}.html — Rendered HTML snapshot from the canvas
- *
- * Also supports importing patterns back into the runtime library.
- */
-
-import { registerPattern } from '../../retrieval/pattern-library.js';
-
-/**
- * Build a pattern-library-compatible JSON object from generation results.
- *
- * @param {string} name — Pattern name (kebab-case, e.g. "my-pricing-page")
- * @param {object} opts
- * @param {object[]} opts.components — Flat adjacency array from messages[0].components
- * @param {string} opts.intent — Original user intent
- * @param {string} [opts.domain] — Domain classification (forms, data, layout, agent, navigation)
- * @param {string} [opts.description] — Human description (falls back to intent)
- * @returns {object} — Pattern object matching pattern-library format
- */
-export function buildPatternJSON(name, { components, intent, domain, description }) {
-  const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
-
-  // Extract unique component type names
-  const componentTypes = [...new Set(
-    components.map(c => c.component).filter(Boolean)
-  )];
-
-  // Clean components: strip internal fields
-  const template = components.map(c => {
-    const { _surfaceId, ...rest } = c;
-    return rest;
-  });
-
-  return {
-    name: slug,
-    description: description || intent || slug,
-    domain: domain || 'layout',
-    components: componentTypes,
-    template,
-  };
-}
-
-/**
- * Save a generation as a named pattern. Downloads .json + .html files.
- *
- * @param {string} name — Pattern name
- * @param {object} opts
- * @param {object[]} opts.messages — A2UI messages array
- * @param {object} opts.validation — Validation result (must have score >= 95)
- * @param {string} opts.intent — Original user intent
- * @param {string} [opts.domain] — Domain classification
- * @param {string} [opts.canvasHTML] — Rendered HTML from canvas
- * @param {number} [opts.minScore=95] — Minimum score to allow save
- * @returns {{ json: object, html: string }} — The saved payloads
- */
-export function savePattern(name, { messages, validation, intent, domain, canvasHTML, minScore = 95 }) {
-  if (!validation || validation.score < minScore) {
-    throw new Error(`Score ${validation?.score ?? 0} is below minimum ${minScore} for pattern save`);
-  }
-
-  const components = messages?.[0]?.components;
-  if (!components || !components.length) {
-    throw new Error('No components to save');
-  }
-
-  const json = buildPatternJSON(name, { components, intent, domain });
-
-  // Download .json
-  downloadFile(`${json.name}.json`, JSON.stringify(json, null, 2), 'application/json');
-
-  // Download .html (if available)
-  const html = canvasHTML || '';
-  if (html) {
-    const htmlDoc = `<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>${json.name} — A2UI Pattern</title>
-  <style>body { font-family: system-ui, sans-serif; padding: 2rem; }</style>
-</head>
-<body>
-${html}
-</body>
-</html>`;
-    downloadFile(`${json.name}.html`, htmlDoc, 'text/html');
-  }
-
-  // Also register in the runtime library
-  registerPattern(json);
-
-  return { json, html };
-}
-
-/**
- * Import a pattern JSON object into the runtime pattern library.
- *
- * @param {object|string} patternJSON — Pattern object or JSON string
- * @returns {{ success: boolean, name?: string, error?: string }}
- */
-export function importPattern(patternJSON) {
-  let pattern = patternJSON;
-  if (typeof pattern === 'string') {
-    try { pattern = JSON.parse(pattern); }
-    catch { return { success: false, error: 'Invalid JSON' }; }
-  }
-
-  if (!pattern?.name) return { success: false, error: 'Missing pattern name' };
-  if (!pattern?.template || !Array.isArray(pattern.template)) {
-    return { success: false, error: 'Missing or invalid template array' };
-  }
-
-  const registered = registerPattern(pattern);
-  if (!registered) {
-    return { success: false, error: `Pattern "${pattern.name}" already exists` };
-  }
-
-  return { success: true, name: pattern.name };
-}
-
-/**
- * Trigger a file download in the browser.
- *
- * @param {string} filename
- * @param {string} content
- * @param {string} [mimeType='application/json']
- */
-export function downloadFile(filename, content, mimeType = 'application/json') {
-  if (typeof document === 'undefined') {
-    throw new Error('downloadFile requires a browser environment');
-  }
-
-  const blob = new Blob([content], { type: mimeType });
-  const url = URL.createObjectURL(blob);
-  const a = document.createElement('a');
-  a.href = url;
-  a.download = filename;
-  a.style.display = 'none';
-  // Prevent SPA router from intercepting the blob URL click
-  a.addEventListener('click', (e) => e.stopPropagation());
-  document.body.appendChild(a);
-  a.click();
-  document.body.removeChild(a);
-  URL.revokeObjectURL(url);
-}