@adia-ai/a2ui-compose 0.4.5 → 0.4.7

package/CHANGELOG.md

@@ -12,6 +12,50 @@ generator graph.
 
 _No pending changes._
 
+## [0.4.7] - 2026-05-12
+
+### Changed — `strategies/monolithic/_shared.js` `getComponentCatalog()` reads canonical catalog (§72)
+
+The legacy reader of `@adia-ai/a2ui-corpus/patterns/_components.json` has been migrated to read `@adia-ai/a2ui-corpus/catalog-a2ui_0_9.json` (the canonical v0.9 catalog, already the package root export). Per-component aliases are now lifted from `components[name].x-adiaui.synonyms.tags`. Same legacy output shape (`{ <Name>: { aliases: string[] } }`); zero behavior change for downstream callers.
+
+Closes the §65 carry-over from v0.4.6 — `@adia-ai/a2ui-corpus` `patterns/` + `compositions/` are now deleted from disk + tarball.
+
+## [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.7",
   "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,26 +12,129 @@ 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);
+  }
 
-// Component prop catalog — loaded lazily for prompt injection
+  // 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.
+//
+// Since §65 (v0.4.7), reads from the canonical v0.9 catalog at
+// `corpus/catalog-a2ui_0_9.json` (assembled from yamls by `npm run
+// components`). Previously read the hand-maintained
+// `corpus/patterns/_components.json` which was retired in §65.
+// Aliases come from `x-adiaui.synonyms.tags` per the v0.9 sidecar shape;
+// migrated in §65 step 1 — 17 yamls populated with synonyms.tags from
+// the prior `_components.json` aliases field.
 let _componentCatalog = null;
 async function getComponentCatalog() {
   if (_componentCatalog) return _componentCatalog;
   try {
     const IS_NODE = typeof process !== 'undefined' && process.versions?.node;
+    let catalogJson;
     if (IS_NODE) {
       const fs = await import(/* @vite-ignore */ 'node:fs/promises');
       const path = await import(/* @vite-ignore */ 'node:path');
       const url = await import(/* @vite-ignore */ 'node:url');
       const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
-      const raw = await fs.readFile(path.join(__dirname, '../../../corpus/patterns/_components.json'), 'utf8');
-      _componentCatalog = JSON.parse(raw);
+      const raw = await fs.readFile(path.join(__dirname, '../../../corpus/catalog-a2ui_0_9.json'), 'utf8');
+      catalogJson = JSON.parse(raw);
     } else {
-      // Browser: use fetch (works in all Vite modes)
-      const resp = await fetch(new URL('../../../corpus/patterns/_components.json', import.meta.url));
-      if (resp.ok) _componentCatalog = await resp.json();
-      else _componentCatalog = {};
+      const resp = await fetch(new URL('../../../corpus/catalog-a2ui_0_9.json', import.meta.url));
+      catalogJson = resp.ok ? await resp.json() : {};
+    }
+    // Adapt the v0.9 catalog (JSON Schema with `components: {Name: {x-adiaui: {...}}}`)
+    // into the legacy {Name: {aliases, ...}} shape getComponentCatalog consumers
+    // expect. Aliases live at `x-adiaui.synonyms.tags`.
+    const comps = catalogJson?.components || {};
+    _componentCatalog = {};
+    for (const [name, def] of Object.entries(comps)) {
+      const ext = def?.['x-adiaui'] || {};
+      const syns = (ext.synonyms && typeof ext.synonyms === 'object') ? ext.synonyms : null;
+      _componentCatalog[name] = {
+        aliases: Array.isArray(syns?.tags) ? syns.tags : [],
+      };
     }
   } catch {
     _componentCatalog = {};
@@ -160,8 +263,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

@@ -1,43 +1,51 @@
 /**
- * Composition Library — zettel-style loader for A2UI compositions.
+ * Composition Library — zettel-style loader for harvested A2UI chunks.
  *
- * Loads two kinds of records into a single in-memory map:
+ * Reads `corpus/chunks/<name>.json` whenever the chunk carries both
+ * `metadata` (from `data-chunk-*` source-HTML attrs per §40) AND
+ * `template` (from the harvester's transpileHTML pass per §41). Chunks
+ * are normalized to composition shape by hoisting `metadata.*` to
+ * top level so consumers can search them uniformly.
  *
- *   1. `corpus/compositions/<domain>/<name>.json` — hand-authored A2UI
- *      templates. The legacy path.
+ * The legacy `corpus/compositions/<domain>/<name>.json` glob was
+ * retired in v0.4.7 (§65). The harvested-chunks substrate (~30
+ * annotated chunks at landing time) is the canonical retrieval
+ * surface; per the project's "source-of-truth = shipped /site/"
+ * principle, anything not in a shipped surface should fall through
+ * to LLM generation rather than be retrieval-matched from a curated
+ * JSON. The 199 MODE-C-MAYBE + 9 KEEP-AS-CHUNK + 3 DELETE
+ * composition/pattern files all retired alongside the dir.
  *
- *   2. `corpus/chunks/<name>.json` — harvested from production HTML —
- *      WHEN the chunk carries both `metadata` (from `data-chunk-*`
- *      source-HTML attrs per §40) AND `template` (from the harvester's
- *      transpileHTML pass per §41). Such chunks are normalized to
- *      composition shape by hoisting `metadata.*` to top level, so they
- *      compete with hand-authored compositions in the same search.
- *
- * Records from chunks carry `_kind: 'annotated-chunk'` and the
- * source-of-truth path so consumers can distinguish if they care; most
- * shouldn't.
+ * Records carry `_kind: 'annotated-chunk'` and the source-of-truth
+ * path so consumers can distinguish if they care; most shouldn't.
  *
  * Renamed from fragment-library.js in §38. Fragments retired §37.
- * Annotated-chunk loading added §41.
+ * Annotated-chunk loading added §41. Compositions-glob retired §65.
  */
 
-import fs from 'node:fs';
-import path from 'node:path';
-import url from 'node:url';
-
-const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
-const COMPOSITIONS_ROOT = path.resolve(__dirname, '../../../corpus/compositions');
-const CHUNKS_ROOT = path.resolve(__dirname, '../../../corpus/chunks');
+// §72 follow-up (v0.4.7): dual-mode loader so this module is safe to
+// statically import from browser entrypoints. Previously the top-level
+// `import 'node:fs'` poisoned the browser bundle the moment any
+// app/playground reached `core/reference.js` → composition-library.
+// Pattern mirrors `retrieval/component-catalog.js`.
+const IS_NODE =
+  typeof process !== 'undefined' &&
+  typeof process.versions?.node === 'string';
 
 /** @type {Map<string, object>} */
 const compositions = new Map();
 
-function walk(dir, cb) {
-  if (!fs.existsSync(dir)) return;
-  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-    const p = path.join(dir, entry.name);
-    if (entry.isDirectory()) walk(p, cb);
-    else if (entry.name.endsWith('.json') && !entry.name.startsWith('_')) cb(p);
+// Vite resolves this at build time; at runtime in Node the variable is unused.
+let _globChunkModules = null;
+if (!IS_NODE) {
+  try {
+    _globChunkModules = import.meta.glob('../../../corpus/chunks/*.json', {
+      query: '?raw',
+      import: 'default',
+      eager: false,
+    });
+  } catch {
+    // Not in a Vite context — no chunk data in this realm.
   }
 }
 
@@ -62,48 +70,99 @@ function chunkToComposition(chunkDoc, sourcePath) {
   };
 }
 
-export function loadAll() {
-  compositions.clear();
+/**
+ * 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;
+let _loadStats = { compositionCount: 0, handAuthoredCount: 0, annotatedChunkCount: 0 };
 
-  // 1. Hand-authored compositions.
-  walk(COMPOSITIONS_ROOT, (p) => {
-    const doc = JSON.parse(fs.readFileSync(p, 'utf8'));
-    if (doc.kind !== 'composition') return;
-    doc._sourceFile = p;
-    compositions.set(doc.name, doc);
-  });
+/**
+ * Filter + register an annotated chunk. Returns 1 if it qualified
+ * (had `metadata` + non-empty `template` + domain/keywords), else 0.
+ */
+function registerChunk(doc, sourcePath) {
+  if (!doc?.metadata) return 0;
+  if (!doc.template || !Array.isArray(doc.template) || doc.template.length === 0) return 0;
+  const meta = doc.metadata;
+  if (!meta.domain && !(meta.keywords && meta.keywords.length > 0)) return 0;
+  compositions.set(doc.name, chunkToComposition(doc, sourcePath));
+  return 1;
+}
+
+async function _loadAllNode() {
+  const fs = await import(/* @vite-ignore */ 'node:fs');
+  const path = await import(/* @vite-ignore */ 'node:path');
+  const url = await import(/* @vite-ignore */ 'node:url');
+
+  const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+  const CHUNKS_ROOT = path.resolve(__dirname, '../../../corpus/chunks');
+
+  function walk(dir, cb) {
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const p = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(p, cb);
+      else if (entry.name.endsWith('.json') && !entry.name.startsWith('_')) cb(p);
+    }
+  }
 
-  // 2. Annotated chunks (§41). Filter: must have metadata.domain (or
-  // metadata.keywords) AND a template field — otherwise the harvester
-  // doesn't have enough to treat the chunk as a retrieval candidate.
   let annotatedChunkCount = 0;
   walk(CHUNKS_ROOT, (p) => {
     const doc = JSON.parse(fs.readFileSync(p, 'utf8'));
-    if (!doc.metadata) return;
-    if (!doc.template || !Array.isArray(doc.template) || doc.template.length === 0) return;
-    const meta = doc.metadata;
-    if (!meta.domain && !(meta.keywords && meta.keywords.length > 0)) return;
-
-    // Chunk name MUST NOT collide with a hand-authored composition.
-    // Hand-authored wins; warn so authors can reconcile (rename one or
-    // delete the composition once the chunk supersedes it).
-    if (compositions.has(doc.name)) {
-      console.warn(
-        `[composition-library] name collision: annotated chunk "${doc.name}" ` +
-        `shadowed by hand-authored composition. Annotated chunk ignored — ` +
-        `rename one or retire the composition.`
-      );
-      return;
-    }
-    compositions.set(doc.name, chunkToComposition(doc, p));
-    annotatedChunkCount++;
+    annotatedChunkCount += registerChunk(doc, p);
   });
+  return annotatedChunkCount;
+}
 
-  return {
+async function _loadAllBrowser() {
+  if (!_globChunkModules) return 0;
+  let annotatedChunkCount = 0;
+  for (const [globPath, loader] of Object.entries(_globChunkModules)) {
+    try {
+      const raw = await loader();
+      const doc = JSON.parse(raw);
+      annotatedChunkCount += registerChunk(doc, globPath);
+    } catch {
+      // skip malformed chunk JSON
+    }
+  }
+  return annotatedChunkCount;
+}
+
+/**
+ * Load all annotated chunks into the in-memory map. Returns a stats
+ * snapshot. In Node, runs synchronously via `fs.readFileSync`; in the
+ * browser, dispatches the Vite glob loaders in parallel.
+ */
+export async function loadAll() {
+  compositions.clear();
+  const annotatedChunkCount = IS_NODE ? await _loadAllNode() : await _loadAllBrowser();
+  _autoLoaded = true;
+  _loadStats = {
     compositionCount: compositions.size,
-    handAuthoredCount: compositions.size - annotatedChunkCount,
+    handAuthoredCount: 0,
     annotatedChunkCount,
   };
+  return _loadStats;
+}
+
+// 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.
+//
+// In Node we top-level-await the load so the map is populated before
+// any importer reaches the synchronous getters. In the browser the
+// auto-load is fire-and-forget (the map fills as chunk JSONs come back
+// from Vite's glob loaders); callers that need the map populated MUST
+// `await loadAll()` themselves. Documented in §72-follow-up.
+if (IS_NODE && !_autoLoaded) {
+  await loadAll();
+} else if (!IS_NODE && !_autoLoaded) {
+  // Fire-and-forget; do not block module import on the network round-trips.
+  loadAll().catch(() => { /* swallow; browsers that don't need this path won't trip */ });
 }
 
 // Back-compat shims removed in §38 — fragment-library.js → composition-library.js

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);
-}