@adia-ai/a2ui-compose 0.4.2 → 0.4.4

package/strategies/zettel/composer.js

@@ -1,148 +1,60 @@
 /**
- * Composer — resolves compositions and fragment references into flat A2UI templates.
+ * Composer — passes A2UI composition templates straight through.
  *
- * Input:  a composition (or any template array containing $fragment nodes)
- * Output: a standard A2UI flat-adjacency node list, ready to validate / render.
+ * History: this file used to expand `$fragment` refs in compositions
+ * via a slot-binding mechanism (zettel-style fragment graph). As of
+ * §37 (2026-05-12) fragments are retired — all compositions are
+ * pre-inlined into flat A2UI templates by /tmp/inline-compositions.py.
+ * `resolveComposition` is now a defensive copy + strip pass; any
+ * lingering `$fragment` ref is treated as a placeholder (the LLM /
+ * renderer will fail noisily, surfacing corpus drift).
  *
- * Algorithm:
- *   For each node in the composition template:
- *     If node.$fragment:
- *       - clone the fragment's template
- *       - prefix every internal id with the composition-node id (to avoid collisions)
- *       - apply slot bindings (set the attribute on the slot's targetId)
- *       - if node.children was provided, append those ids to the fragment root's children
- *       - emit the fragment root under node.id, then the rest of the fragment nodes
- *     Else:
- *       - emit the node as-is
+ * Kept as a thin wrapper rather than deleted because zettel's
+ * generator-adapter still calls `resolveComposition(comp)` —
+ * downstream rename is a follow-up arc.
  */
 
-import { getFragment } from './fragment-library.js';
+const ID_PREFIX_SEPARATOR = '--';
 
 /**
- * Separator used when prefixing a fragment's internal node ids with the
- * composition node id. Format: `{compNode}{ID_PREFIX_SEPARATOR}{fragNode}`.
+ * Return a defensive copy of a composition's flat template.
  *
- * Why double-dash: single `-` collides with kebab-case ids that primitives
- * commonly emit (`auth-card-header`, `card-header-heading`); double-dash
- * has no observed natural occurrence in either composition node ids or
- * fragment node ids, so the parse is unambiguous if anyone ever needs to
- * reverse the prefixing.
+ * Compositions are pre-inlined, so there's nothing to expand. We
+ * still strip zettel-era fields that may linger in the corpus —
+ * future-proof against accidental re-introduction.
  *
- * EXTERNAL CONTRACT: the renderer treats node ids as opaque strings, so
- * changing this separator does not break A2UI consumers. But anything
- * upstream that splits on `--` (issue-reporter ticket rendering, eval
- * trace inspection, debug logs) will need to be updated in lockstep.
- */
-export const ID_PREFIX_SEPARATOR = '--';
-
-function cloneFragmentWithPrefix(fragment, prefix) {
-  const idMap = new Map();
-  const cloned = fragment.template.map((n) => ({ ...n }));
-
-  // Generate new ids
-  for (const node of cloned) {
-    const newId = `${prefix}${ID_PREFIX_SEPARATOR}${node.id}`;
-    idMap.set(node.id, newId);
-  }
-  // Rewrite ids and children refs
-  for (const node of cloned) {
-    node.id = idMap.get(node.id);
-    if (Array.isArray(node.children)) {
-      node.children = node.children
-        .map((c) => (typeof c === 'string' ? idMap.get(c) || c : c));
-    }
-  }
-  return { cloned, idMap, rootId: idMap.get(fragment.template[0].id) };
-}
-
-function applyBindings(nodes, fragment, idMap, bindings = {}) {
-  if (!bindings) return;
-  for (const slot of fragment.slots || []) {
-    const internalId = idMap.get(slot.targetId);
-    const target = nodes.find((n) => n.id === internalId);
-    if (!target) continue;
-
-    const value = bindings[slot.name] ?? slot.defaultValue;
-    if (value === undefined) continue;
-
-    const attr = slot.attribute || 'textContent';
-    target[attr] = value;
-  }
-}
-
-/**
- * Expand a composition (or any template) into a flat A2UI node list.
  * @param {object} composition - { template: [...] }
- * @returns {Array<object>} resolved flat nodes
+ * @returns {Array<object>}
  */
 export function resolveComposition(composition) {
+  const template = composition?.template || [];
   const out = [];
-  const template = composition.template || [];
-
   for (const node of template) {
-    if (!node.$fragment) {
-      out.push({ ...node });
-      continue;
-    }
-
-    const fragment = getFragment(node.$fragment);
-    if (!fragment) {
+    if (!node || typeof node !== 'object') continue;
+    if (node.$fragment) {
+      // Stale $fragment refs shouldn't exist after the §37 inline pass.
+      // Surface them as a visible placeholder so corpus drift is easy
+      // to spot at render time.
       out.push({
-        id: node.id,
+        id: node.id || `stale-${node.$fragment}`,
         component: 'Text',
-        textContent: `⚠ unresolved fragment: ${node.$fragment}`,
+        textContent: `⚠ stale $fragment ref (compositions are pre-inlined): ${node.$fragment}`,
       });
       continue;
     }
-
-    const { cloned, idMap, rootId } = cloneFragmentWithPrefix(fragment, node.id);
-    applyBindings(cloned, fragment, idMap, node.bindings);
-
-    // Substitute: composition-node id becomes the fragment root id.
-    // So any sibling that references node.id still resolves to the expanded root.
-    const rootNode = cloned.find((n) => n.id === rootId);
-    if (rootNode) {
-      rootNode.id = node.id;
-      // fix up any sibling refs inside cloned
-      for (const n of cloned) {
-        if (Array.isArray(n.children)) {
-          n.children = n.children.map((c) => (c === rootId ? node.id : c));
-        }
-      }
-    }
-
-    // Allow composition to inject extra children into the fragment root.
-    //   children        — alias for appendChildren (legacy; append to end)
-    //   appendChildren  — append composition-owned nodes to the fragment's children
-    //   prependChildren — prepend composition-owned nodes before the fragment's children
-    // This lets a composition add things INSIDE a fragment's root (e.g. a logo above
-    // a card-header's title) without having to inline the whole fragment.
-    if (rootNode) {
-      const prepend = Array.isArray(node.prependChildren) ? node.prependChildren : [];
-      const append = Array.isArray(node.appendChildren)
-        ? node.appendChildren
-        : (Array.isArray(node.children) ? node.children : []);
-      if (prepend.length || append.length) {
-        rootNode.children = [
-          ...prepend,
-          ...(rootNode.children || []),
-          ...append,
-        ];
-      }
-    }
-
-    out.push(...cloned);
+    const {
+      // Strip composition-only fields that never reach the renderer
+      $fragment, bindings, prependChildren, appendChildren,
+      ...rest
+    } = node;
+    out.push({ ...rest });
   }
-
   return out;
 }
 
 /**
- * Convert a resolved flat template into A2UI `beginComponent` messages
- * compatible with the existing validator / renderer. Strips zettel-only
- * fields (`$fragment`, `bindings`, `prependChildren`, `appendChildren`) that
- * were already consumed by resolveComposition — they'd be dead weight in the
- * emitted A2UI messages.
+ * Convert a flat A2UI template into `beginComponent` messages for the
+ * validator / renderer. Strips composition-era fields.
  */
 export function templateToMessages(template) {
   return template.map((node) => {
@@ -161,3 +73,6 @@ export function templateToMessages(template) {
     };
   });
 }
+
+// Re-export the separator for any downstream code that still uses it.
+export { ID_PREFIX_SEPARATOR };

package/strategies/zettel/composition-library.js

@@ -0,0 +1,207 @@
+/**
+ * Composition Library — zettel-style loader for A2UI compositions.
+ *
+ * Loads two kinds of records into a single in-memory map:
+ *
+ *   1. `corpus/compositions/<domain>/<name>.json` — hand-authored A2UI
+ *      templates. The legacy path.
+ *
+ *   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.
+ *
+ * Renamed from fragment-library.js in §38. Fragments retired §37.
+ * Annotated-chunk loading added §41.
+ */
+
+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');
+
+/** @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);
+  }
+}
+
+/**
+ * Promote an annotated chunk record to composition shape. Lifts
+ * `metadata.{domain,description,keywords,related,tags}` to top-level
+ * fields so the existing searchAll scorer can read them uniformly.
+ */
+function chunkToComposition(chunkDoc, sourcePath) {
+  const meta = chunkDoc.metadata || {};
+  return {
+    _kind: 'annotated-chunk',
+    _sourceFile: sourcePath,
+    name: chunkDoc.name,
+    kind: 'composition', // honest with the searchAll filter
+    domain: meta.domain,
+    description: meta.description,
+    keywords: meta.keywords || [],
+    related: meta.related || [],
+    tags: meta.tags || {},
+    template: chunkDoc.template,
+  };
+}
+
+export function loadAll() {
+  compositions.clear();
+
+  // 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);
+  });
+
+  // 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++;
+  });
+
+  return {
+    compositionCount: compositions.size,
+    handAuthoredCount: compositions.size - annotatedChunkCount,
+    annotatedChunkCount,
+  };
+}
+
+// Back-compat shims removed in §38 — fragment-library.js → composition-library.js
+// rename. The retired `getFragment` / `getAllFragments` exports had zero
+// external callers; drop them.
+
+export function getComposition(name) { return compositions.get(name); }
+export function getAllCompositions() { return [...compositions.values()]; }
+
+/**
+ * Keyword search across compositions. (Fragments retired; only one
+ * corpus class to search now.)
+ *
+ * Ranking design:
+ *   1. Tokenize query, drop generic UI stop-words ("form", "page", "view"…)
+ *      so they can't be the sole evidence for a match.
+ *   2. Whole-word match, not substring — prevents "form" matching "login-form".
+ *   3. Require ≥2 content-token hits (compositions are concrete templates —
+ *      promiscuous matching is expensive). Exception: a direct name-token
+ *      match is strong enough on its own.
+ *   4. Tiered weights: name hit > keyword hit > description.
+ */
+const STOP_WORDS = new Set([
+  'a', 'an', 'the', 'and', 'or', 'but', 'of', 'to', 'in', 'on', 'at', 'for', 'with',
+  'form', 'forms', 'page', 'pages', 'view', 'views', 'screen', 'screens',
+  'ui', 'component', 'components', 'widget', 'widgets', 'block', 'blocks',
+  'section', 'sections', 'layout', 'layouts',
+]);
+
+function tokenize(str) {
+  return (str || '')
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((t) => t.length >= 2);
+}
+
+export function searchAll(query, { limit = 20 } = {}) {
+  const q = (query || '').trim();
+  if (!q) return [];
+  const queryTokens = tokenize(q);
+
+  const scoreDoc = (doc) => {
+    const nameTokens = new Set(tokenize(doc.name));
+    const keywordTokens = new Set((doc.keywords || []).flatMap((k) => tokenize(k)));
+    const descTokens = new Set(tokenize(doc.description || ''));
+    const tagTokens = new Set(
+      Object.values(doc.tags || {}).flat().flatMap((v) => tokenize(String(v))),
+    );
+
+    let s = 0;
+    const contentMatched = new Set();
+
+    for (const t of queryTokens) {
+      const isStop = STOP_WORDS.has(t);
+      let matched = false;
+      if (nameTokens.has(t))    { s += isStop ? 1 : 12; matched = true; }
+      if (keywordTokens.has(t)) { s += isStop ? 1 : 8;  matched = true; }
+      if (tagTokens.has(t))     { s += isStop ? 0 : 3;  matched = true; }
+      if (descTokens.has(t))    { s += isStop ? 0 : 2;  matched = true; }
+      if (matched && !isStop) {
+        contentMatched.add(t);
+      }
+    }
+    const contentHits = contentMatched.size;
+
+    // Gate: compositions require ≥2 content-token hits, OR a direct
+    // name-token match (the query contains the composition's primary
+    // concept word — strong evidence on its own).
+    const nameHit = queryTokens.some((t) => !STOP_WORDS.has(t) && nameTokens.has(t));
+    if (contentHits < 2 && !nameHit) return 0;
+
+    // Coverage bonus: more distinct content tokens matched = better match
+    s += contentHits * 3;
+
+    return s;
+  };
+
+  return getAllCompositions()
+    .map((doc) => ({ doc, score: scoreDoc(doc) }))
+    .filter((x) => x.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit)
+    .map((x) => ({
+      type: 'composition',
+      name: x.doc.name,
+      score: Math.round(x.score * 100) / 100,
+      description: x.doc.description,
+      domain: x.doc.domain,
+    }));
+}
+
+/** Return composition catalog for inspection / visualization. */
+export function getGraph() {
+  return {
+    compositions: getAllCompositions().map((c) => ({
+      name: c.name,
+      domain: c.domain,
+      node_count: (c.template || []).length,
+    })),
+  };
+}

package/strategies/zettel/generator-adapter.js

@@ -22,7 +22,7 @@ import {
   loadAll,
   getComposition,
   searchAll,
-} from './fragment-library.js';
+} from './composition-library.js';
 import { resolveComposition, templateToMessages } from './composer.js';
 import { synthesizeComposition } from './synthesizer.js';
 import {

package/strategies/zettel/state-cache.js

@@ -27,7 +27,12 @@
 const DEFAULT_MAX_SIZE = 64;
 
 function envMaxSize() {
-  const v = process.env.A2UI_STATE_CACHE_SIZE;
+  // Node-only: `process` is undefined in the browser. Without this guard the
+  // StateCache constructor throws `ReferenceError: process is not defined`
+  // the moment the zettel engine is selected in the gen-ui playground.
+  // Matches the convention used in retrieval/* and compose/core/generator.js.
+  const IS_NODE = typeof process !== 'undefined' && process.versions?.node;
+  const v = IS_NODE ? process.env.A2UI_STATE_CACHE_SIZE : null;
   if (!v) return null;
   const n = parseInt(v, 10);
   return Number.isFinite(n) && n > 0 ? n : null;