@adia-ai/a2ui-compose 0.4.6 → 0.4.7

package/CHANGELOG.md

@@ -12,6 +12,14 @@ 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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/a2ui-compose",
-  "version": "0.4.6",
+  "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/monolithic/_shared.js

@@ -98,24 +98,43 @@ function adaptV09Component(a2uiData) {
   };
 }
 
-// Component prop catalog — loaded lazily for prompt injection
+// 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 = {};

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.
   }
 }
 
@@ -68,57 +76,94 @@ function chunkToComposition(chunkDoc, sourcePath) {
  * + re-build, which is wasted work but not incorrect.
  */
 let _autoLoaded = false;
+let _loadStats = { compositionCount: 0, handAuthoredCount: 0, annotatedChunkCount: 0 };
 
-export function loadAll() {
-  compositions.clear();
+/**
+ * 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;
+}
 
-  // 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);
-  });
+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;
+}
+
+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;
-  return {
+  _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.
-if (!_autoLoaded) loadAll();
+//
+// 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
 // rename. The retired `getFragment` / `getAllFragments` exports had zero