@adia-ai/gen-ui 0.8.37

package/retrieval/catalog.js

@@ -0,0 +1,250 @@
+/**
+ * CatalogManifest — Structured index of all AdiaUI components.
+ *
+ * Reads from the per-component a2ui.json sidecars co-located with each
+ * component (packages/web-components/components/<c>/<c>.a2ui.json), generated
+ * from the YAML single-source-of-truth by scripts/build-components.mjs.
+ */
+
+import { registry } from '@adia-ai/a2ui';
+
+// ── Schema loading ──
+const schemaByTag = new Map();
+let schemasLoaded = false;
+
+function tagFromSchema(schema) {
+  return schema?.['x-adiaui']?.tag || null;
+}
+
+async function loadSchemas() {
+  if (schemasLoaded) return;
+  schemasLoaded = true;
+
+  if (typeof process !== 'undefined' && process.versions?.node) {
+    try {
+      const { readdir, readFile, stat } = await import(/* @vite-ignore */ 'node:fs/promises');
+      const { fileURLToPath } = await import(/* @vite-ignore */ 'node:url');
+      const { dirname, join } = await import(/* @vite-ignore */ 'node:path');
+      const compsDir = join(dirname(fileURLToPath(import.meta.url)), '../../web-components/components');
+      const entries = await readdir(compsDir, { withFileTypes: true });
+      for (const e of entries) {
+        if (!e.isDirectory()) continue;
+        const path = join(compsDir, e.name, `${e.name}.a2ui.json`);
+        try {
+          const raw = await readFile(path, 'utf8');
+          const schema = JSON.parse(raw);
+          const tag = tagFromSchema(schema);
+          if (tag) schemaByTag.set(tag, schema);
+        } catch { /* skip missing / malformed */ }
+      }
+    } catch { /* components dir missing */ }
+  } else {
+    // Browser. Vite rewrites the glob CALL at transform time; on the static
+    // deploy that call throws (no Vite — `import.meta.glob` is a compile-time
+    // macro, undefined at runtime) → we fall through to fetching the
+    // CONSOLIDATED catalog. `typeof import.meta.glob` is undefined in BOTH
+    // contexts, so the only reliable discriminator is whether the CALL
+    // produced loaders. See composition-library.js for the full rationale.
+    let modules = null;
+    try {
+      modules = import.meta.glob('../../web-components/components/*/*.a2ui.json', { query: '?raw', import: 'default' });
+    } catch { /* no Vite transform — static deploy */ }
+
+    if (modules && Object.keys(modules).length > 0) {
+      // Vite dev — iterate the glob loaders.
+      for (const [, loader] of Object.entries(modules)) {
+        try {
+          const raw = await loader();
+          const schema = JSON.parse(raw);
+          const tag = tagFromSchema(schema);
+          if (tag) schemaByTag.set(tag, schema);
+        } catch { /* skip invalid */ }
+      }
+    } else {
+      // Static deploy — fetch the consolidated catalog once. Its `components`
+      // values carry the same `x-adiaui.tag` shape as the per-component
+      // sidecars (2026-06-10). Relative-to-module so it resolves under any
+      // mount point + the dist symlink layout.
+      try {
+        const url = new URL('../corpus/catalog-a2ui_0_9.json', import.meta.url);
+        const res = await fetch(url);
+        if (res.ok) {
+          const catalog = await res.json();
+          const comps = catalog?.components;
+          if (comps && typeof comps === 'object') {
+            for (const schema of Object.values(comps)) {
+              const tag = tagFromSchema(schema);
+              if (tag) schemaByTag.set(tag, schema);
+            }
+          }
+        }
+      } catch { /* consolidated catalog not present */ }
+    }
+  }
+}
+
+/**
+ * Register a JSON schema for a component tag (runtime).
+ */
+export function registerSchema(tag, schema) {
+  schemaByTag.set(tag, schema);
+}
+
+// ── Category classification ──
+const categoryMap = {
+  'row-ui': 'layout', 'col-ui': 'layout', 'list-ui': 'layout', 'grid-ui': 'layout',
+  'stack-ui': 'layout', 'block-ui': 'layout', 'toolbar-ui': 'layout',
+  'text-ui': 'display', 'image-ui': 'display', 'icon-ui': 'display',
+  'divider-ui': 'display', 'badge-ui': 'display', 'avatar-ui': 'display',
+  'avatar-group-ui': 'display', 'progress-ui': 'display', 'skeleton-ui': 'display',
+  'code-ui': 'display', 'kbd-ui': 'display', 'tag-ui': 'display',
+  'stat-ui': 'display', 'empty-state-ui': 'display',
+  'input-ui': 'input', 'check-ui': 'input', 'switch-ui': 'input',
+  'slider-ui': 'input', 'select-ui': 'input', 'search-ui': 'input',
+  'upload-ui': 'input', 'textarea-ui': 'input', 'radio-ui': 'input',
+  'otp-input-ui': 'input', 'calendar-picker-ui': 'input', 'color-picker-ui': 'input',
+  'range-ui': 'input',
+  'button-ui': 'action',
+  'card-ui': 'container', 'tabs-ui': 'container', 'tab-ui': 'container',
+  'pane-ui': 'container', 'modal-ui': 'container', 'drawer-ui': 'container',
+  'toast-ui': 'container', 'popover-ui': 'container', 'accordion-ui': 'container',
+  'alert-ui': 'container', 'tooltip-ui': 'container', 'menu-ui': 'container',
+  'command-ui': 'container',
+  'section': 'card-child', 'header': 'card-child', 'footer': 'card-child',
+  'stream-ui': 'agent', 'table-ui': 'agent', 'chart-ui': 'agent',
+  'embed-ui': 'agent', 'noodles-ui': 'agent',
+  'breadcrumb-ui': 'navigation', 'nav-ui': 'navigation', 'pagination-ui': 'navigation',
+  'segmented-ui': 'navigation', 'segment-ui': 'navigation', 'router-ui': 'navigation',
+  'toggle-group-ui': 'navigation', 'toggle-option-ui': 'navigation',
+};
+
+// ── Trait registry ──
+//
+// Loaded from packages/web-components/traits/_catalog.json — generated
+// by `node scripts/build/traits-catalog.mjs` from the live defineTrait()
+// metadata. Hand-edits here will be overwritten. Treat the trait file
+// itself as the single source of truth.
+let traitRegistry = [];
+
+async function loadTraitRegistry() {
+  if (typeof process !== 'undefined' && process.versions?.node) {
+    try {
+      const { readFile } = await import(/* @vite-ignore */ 'node:fs/promises');
+      const { fileURLToPath } = await import(/* @vite-ignore */ 'node:url');
+      const { dirname, join } = await import(/* @vite-ignore */ 'node:path');
+      const path = join(dirname(fileURLToPath(import.meta.url)), '../../web-components/traits/_catalog.json');
+      const raw = await readFile(path, 'utf8');
+      const data = JSON.parse(raw);
+      traitRegistry = data.traits.map(t => ({
+        name: t.name,
+        category: t.category,
+        description: t.description,
+        attributes: [...t.attributes],
+        events: [...t.events],
+        config: [...t.config],
+      }));
+    } catch (err) {
+      console.warn('[a2ui-corpus] could not load trait catalog:', err.message);
+    }
+  } else {
+    // Browser branch — fetch via HTTP, not `import('… .json', { with: { type: 'json' } })`.
+    // Vite's dev server transforms JSON imports into JS modules and serves them
+    // with `Content-Type: text/javascript`; Chrome's strict MIME check rejects
+    // that when the spec-correct `with: { type: 'json' }` attribute is present.
+    // (Site pages already use fetch() for the same file — see
+    //  site/pages/traits/_api-table.js + site/pages/traits/catalog/index.setup.js.)
+    try {
+      const res = await fetch('/packages/web-components/traits/_catalog.json');
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      const data = await res.json();
+      traitRegistry = data.traits.map(t => ({
+        name: t.name,
+        category: t.category,
+        description: t.description,
+        attributes: [...t.attributes],
+        events: [...t.events],
+        config: [...t.config],
+      }));
+    } catch { /* trait catalog not present in this build context */ }
+  }
+}
+
+await loadTraitRegistry();
+
+// ── Alias tracking ──
+const aliases = new Set([
+  'Select', 'LoadingIndicator', 'ErrorContainer',
+  'Keyboard', 'DatePicker', 'CommandPalette', 'Segmented', 'OTP', 'SideNav', 'IconSource',
+]);
+
+// ── Build the catalog ──
+let catalog = null;
+
+async function buildCatalog() {
+  if (catalog) return catalog;
+  await loadSchemas();
+
+  const entries = new Map();
+
+  for (const [type, tag] of registry) {
+    if (aliases.has(type)) continue;
+    // Skip -ui alias entries (lowercase with dash)
+    if (type.includes('-')) continue;
+
+    const schema = schemaByTag.get(tag) || null;
+    const category = categoryMap[tag] || 'other';
+
+    entries.set(type, {
+      type,
+      tag,
+      category,
+      description: schema?.description || '',
+      schema,
+    });
+  }
+
+  catalog = {
+    version: '0.1.0',
+    totalTypes: entries.size,
+    entries,
+  };
+
+  return catalog;
+}
+
+export async function getCatalog() {
+  return buildCatalog();
+}
+
+export async function getComponent(typeName) {
+  const cat = await buildCatalog();
+  if (cat.entries.has(typeName)) return cat.entries.get(typeName);
+  const tag = registry.get(typeName);
+  if (!tag) return null;
+  for (const entry of cat.entries.values()) {
+    if (entry.tag === tag) return entry;
+  }
+  return null;
+}
+
+export async function getComponentsByCategory(category) {
+  const cat = await buildCatalog();
+  return [...cat.entries.values()].filter(e => e.category === category);
+}
+
+export function getTraits() {
+  return traitRegistry;
+}
+
+export function getTraitsByCategory(category) {
+  return traitRegistry.filter(t => t.category === category);
+}
+
+export async function getFullCatalog() {
+  const cat = await buildCatalog();
+  return {
+    ...cat,
+    totalTraits: traitRegistry.length,
+    traits: traitRegistry,
+  };
+}

package/retrieval/component-catalog.js

@@ -0,0 +1,168 @@
+/**
+ * Component Catalog — Loads `.a2ui.json` sidecars from web-components/.
+ *
+ * The `.a2ui.json` sidecars are hand-authored component contracts that
+ * live alongside their components in `packages/web-components/components/`.
+ * They are part of the component library — NOT the training corpus — and
+ * are the canonical source of truth for component shape (v0.9 JSON Schema
+ * with `x-adiaui` extension for retrieval signals).
+ *
+ * §66 wired these into `buildSystemPrompt` as the authoritative component
+ * descriptor. §64 split this loader out of the now-retired
+ * `pattern-library.js` so it survives the patterns corpus deletion.
+ *
+ * Works in both Node.js (readdir/readFile) and the browser (Vite glob).
+ */
+
+const IS_NODE =
+  typeof process !== 'undefined' &&
+  typeof process.versions?.node === 'string';
+
+/** @type {Map<string, object>} */
+const _componentData = new Map();
+
+let _loaded = false;
+let _loadPromise = null;
+
+// Vite rewrites this CALL at transform time. On the static deploy the call
+// throws (no Vite) → `_globA2UIModules` null → fetch the CONSOLIDATED
+// catalog (one request) instead of 138 per-component sidecars.
+// `import.meta.glob` is a compile-time macro (undefined at runtime in both
+// Vite and static) — the only reliable discriminator is whether the CALL
+// produced loaders. See composition-library.js for the full rationale.
+let _globA2UIModules = null;
+if (!IS_NODE) {
+  try {
+    _globA2UIModules = import.meta.glob('../../web-components/components/**/*.a2ui.json', {
+      query: '?raw',
+      import: 'default',
+    });
+  } catch {
+    // No Vite transform here (static deploy) — fall through to the fetch branch.
+  }
+}
+const HAS_VITE_GLOB =
+  !IS_NODE && !!_globA2UIModules && Object.keys(_globA2UIModules).length > 0;
+
+// Static-deploy source: the consolidated catalog co-located in the corpus.
+// Its `components` map values are byte-shape-identical to the standalone
+// `.a2ui.json` sidecars (verified 2026-06-10), so one fetch replaces 138.
+// Relative-to-module from retrieval/ → ../a2ui-corpus is `../corpus/`.
+const _CONSOLIDATED_CATALOG_URL =
+  !IS_NODE && !HAS_VITE_GLOB
+    ? new URL('../corpus/catalog-a2ui_0_9.json', import.meta.url)
+    : null;
+
+async function _loadNode() {
+  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 componentsDir = path.resolve(__dirname, '..', '..', 'web-components', 'components');
+
+  let compEntries;
+  try {
+    compEntries = await fs.readdir(componentsDir, { withFileTypes: true });
+  } catch {
+    return; // components dir doesn't exist — skip
+  }
+
+  for (const compEntry of compEntries) {
+    if (!compEntry.isDirectory()) continue;
+    const a2uiPath = path.join(componentsDir, compEntry.name, `${compEntry.name}.a2ui.json`);
+    try {
+      const raw = await fs.readFile(a2uiPath, 'utf8');
+      const data = JSON.parse(raw);
+      if (data?.title) _componentData.set(data.title, data);
+    } catch {
+      // No .a2ui.json for this component — skip
+    }
+    // §172 (v0.5.4): also pick up SIBLING .a2ui.json files in the same
+    // component dir. Some components live as sibling files inside a
+    // parent's folder (e.g. <chat-input-ui> in components/chat-thread/).
+    // Pre-§172 these were invisible to the retrieval catalog +
+    // system-prompt's getComponentData() lookup, causing the LLM to emit
+    // them without schema awareness (e.g. the 2026-05-14 redundant-send-
+    // button regression on ChatInput). The build scanner gained the same
+    // sibling-discovery treatment in `scripts/build/components.mjs`.
+    try {
+      const sibs = await fs.readdir(path.join(componentsDir, compEntry.name), { withFileTypes: true });
+      for (const s of sibs) {
+        if (!s.isFile() || !s.name.endsWith('.a2ui.json')) continue;
+        if (s.name === `${compEntry.name}.a2ui.json`) continue; // already loaded
+        try {
+          const raw = await fs.readFile(path.join(componentsDir, compEntry.name, s.name), 'utf8');
+          const data = JSON.parse(raw);
+          if (data?.title) _componentData.set(data.title, data);
+        } catch {
+          // skip malformed sibling sidecar
+        }
+      }
+    } catch {
+      // skip on read error
+    }
+  }
+}
+
+async function _loadBrowser() {
+  if (!_globA2UIModules) return;
+
+  for (const [, loader] of Object.entries(_globA2UIModules)) {
+    try {
+      const raw = await loader();
+      const data = JSON.parse(raw);
+      if (data?.title) _componentData.set(data.title, data);
+    } catch {
+      // skip malformed .a2ui.json
+    }
+  }
+}
+
+async function _loadStatic() {
+  if (!_CONSOLIDATED_CATALOG_URL) return;
+  try {
+    const res = await fetch(_CONSOLIDATED_CATALOG_URL);
+    if (!res.ok) return;
+    const catalog = await res.json();
+    const comps = catalog?.components;
+    if (!comps || typeof comps !== 'object') return;
+    for (const data of Object.values(comps)) {
+      if (data?.title) _componentData.set(data.title, data);
+    }
+  } catch {
+    // Consolidated catalog not present / unparseable — leave empty.
+  }
+}
+
+export async function loadCatalog() {
+  if (_loaded) return;
+  if (_loadPromise) return _loadPromise;
+  _loadPromise = (async () => {
+    if (IS_NODE) await _loadNode();
+    else if (HAS_VITE_GLOB) await _loadBrowser();
+    else await _loadStatic();
+  })();
+  await _loadPromise;
+  _loaded = true;
+}
+
+// Eager load on module import so the synchronous getters below are safe.
+await loadCatalog();
+
+/**
+ * Get `.a2ui.json` data for a named component.
+ * @param {string} name — PascalCase component name (e.g., "Swiper")
+ * @returns {object|null} raw .a2ui.json document, or null
+ */
+export function getComponentData(name) {
+  return _componentData.get(name) || null;
+}
+
+/**
+ * Get all loaded `.a2ui.json` component data.
+ * @returns {Object.<string, object>} component name → .a2ui.json data
+ */
+export function getAllComponentData() {
+  return Object.fromEntries(_componentData);
+}

package/retrieval/component-entry.js

@@ -0,0 +1,80 @@
+/**
+ * ComponentEntry — Detail level serialization for catalog entries.
+ *
+ * Three progressive-disclosure levels:
+ *   Index    (~10 tokens):  { type, tag, category }
+ *   Summary  (~50 tokens):  index + { description, properties: [names] }
+ *   Reference (~200 tokens): summary + { properties: [full], slots, events, children, tokens }
+ */
+
+/** @typedef {'index' | 'summary' | 'reference'} DetailLevel */
+
+/**
+ * Serialize a component entry to the requested detail level.
+ *
+ * @param {object} entry — Full component entry from the catalog
+ * @param {DetailLevel} level — Detail level
+ * @returns {object} — Serialized entry at the requested level
+ */
+export function serializeEntry(entry, level = 'index') {
+  if (level === 'index') return serializeIndex(entry);
+  if (level === 'summary') return serializeSummary(entry);
+  return serializeReference(entry);
+}
+
+function serializeIndex(entry) {
+  return {
+    type: entry.type,
+    tag: entry.tag,
+    category: entry.category,
+  };
+}
+
+function serializeSummary(entry) {
+  const index = serializeIndex(entry);
+  const result = {
+    ...index,
+    description: entry.description || '',
+  };
+  if (entry.schema?.properties) {
+    result.properties = Object.keys(entry.schema.properties);
+  }
+  return result;
+}
+
+function serializeReference(entry) {
+  const summary = serializeSummary(entry);
+  const schema = entry.schema;
+  if (!schema) return summary;
+
+  const result = { ...summary };
+
+  // Full property definitions
+  if (schema.properties) {
+    result.properties = Object.entries(schema.properties).map(([name, def]) => ({
+      name,
+      type: def.type,
+      ...(def.enum ? { enum: def.enum } : {}),
+      ...(def.default !== undefined ? { default: def.default } : {}),
+      ...(def.description ? { description: def.description } : {}),
+    }));
+  }
+
+  if (schema.slots && Object.keys(schema.slots).length > 0) {
+    result.slots = schema.slots;
+  }
+
+  if (schema.events && Object.keys(schema.events).length > 0) {
+    result.events = schema.events;
+  }
+
+  if (schema.children) {
+    result.children = schema.children;
+  }
+
+  if (schema.tokens) {
+    result.tokens = schema.tokens;
+  }
+
+  return result;
+}

package/retrieval/context-assembler.js

@@ -0,0 +1,174 @@
+/**
+ * Context Assembler — Progressive-disclosure context packaging with token budgets.
+ *
+ * Assembles context at 5 budget tiers, combining component entries,
+ * domain-relevant patterns, and anti-patterns within token limits.
+ *
+ * Token estimation: ~1 token per 4 characters of JSON output.
+ */
+
+import { getCatalog, getComponentsByCategory } from './catalog.js';
+import { serializeEntry } from './component-entry.js';
+import { classifyIntent, getDomain } from './domain-router.js';
+import { getAntiPatterns } from './anti-patterns.js';
+import {
+  searchAll as searchCompositions,
+  getComposition,
+  getAllCompositions,
+} from '../compose/strategies/zettel/composition-library.js';
+
+/** Token budget per tier */
+const TIER_BUDGETS = {
+  0: 500,
+  1: 2000,
+  2: 5000,
+  3: 10000,
+  4: 20000,
+};
+
+/**
+ * Estimate token count from a JavaScript value (serialized as JSON).
+ * @param {*} value
+ * @returns {number}
+ */
+function estimateTokens(value) {
+  const json = JSON.stringify(value);
+  return Math.ceil(json.length / 4);
+}
+
+/**
+ * Assemble context for a given intent at a specific budget tier.
+ *
+ * @param {object} options
+ * @param {string} [options.intent] — Natural language intent (used for domain classification)
+ * @param {number} [options.tier=1] — Budget tier (0-4)
+ * @param {string} [options.domain] — Override domain (skips classification)
+ * @returns {{ components: object[], patterns: object[], antiPatterns: object[], domain: object, estimatedTokens: number }}
+ */
+export async function assembleContext({ intent = '', tier = 1, domain: overrideDomain } = {}) {
+  const budget = TIER_BUDGETS[tier] ?? TIER_BUDGETS[1];
+
+  // Classify domain
+  const classification = intent ? classifyIntent(intent) : null;
+  const domainName = overrideDomain || classification?.domain || 'layout';
+  const domainConfig = getDomain(domainName);
+
+  let usedTokens = 0;
+  const result = {
+    components: [],
+    patterns: [],
+    antiPatterns: [],
+    domain: {
+      name: domainName,
+      confidence: classification?.confidence ?? 1,
+      matchedSignals: classification?.matchedSignals ?? [],
+    },
+    estimatedTokens: 0,
+  };
+
+  // Account for domain metadata
+  usedTokens += estimateTokens(result.domain);
+
+  const catalog = await getCatalog();
+
+  // ── Tier 0: Component index only ──
+  if (tier === 0) {
+    for (const entry of catalog.entries.values()) {
+      const serialized = serializeEntry(entry, 'index');
+      const cost = estimateTokens(serialized);
+      if (usedTokens + cost > budget) break;
+      result.components.push(serialized);
+      usedTokens += cost;
+    }
+    result.estimatedTokens = usedTokens;
+    return result;
+  }
+
+  // ── Tier 1+: Domain-relevant summaries first ──
+  const domainComponents = domainConfig?.components || [];
+  const addedTypes = new Set();
+
+  // Add domain-relevant components as summaries
+  for (const typeName of domainComponents) {
+    const entry = findEntry(catalog, typeName);
+    if (!entry) continue;
+
+    const level = tier >= 2 ? 'reference' : 'summary';
+    const serialized = serializeEntry(entry, level);
+    const cost = estimateTokens(serialized);
+    if (usedTokens + cost > budget) break;
+
+    result.components.push(serialized);
+    addedTypes.add(entry.type);
+    usedTokens += cost;
+  }
+
+  // ── Tier 2+: Fill remaining budget with other components ──
+  if (tier >= 2) {
+    for (const entry of catalog.entries.values()) {
+      if (addedTypes.has(entry.type)) continue;
+
+      const level = tier >= 3 ? 'reference' : 'summary';
+      const serialized = serializeEntry(entry, level);
+      const cost = estimateTokens(serialized);
+      if (usedTokens + cost > budget) break;
+
+      result.components.push(serialized);
+      addedTypes.add(entry.type);
+      usedTokens += cost;
+    }
+  }
+
+  // ── Tier 1+: Add anti-patterns ──
+  if (tier >= 1) {
+    const ap = getAntiPatterns();
+    const apCost = estimateTokens(ap);
+    if (usedTokens + apCost <= budget) {
+      result.antiPatterns = ap;
+      usedTokens += apCost;
+    }
+  }
+
+  // ── Tier 3+: Add matching compositions ──
+  // §64 migrated from pattern-library to composition-library. Compositions
+  // are the canonical retrieval surface post-§65.
+  if (tier >= 3) {
+    const matchedCompositions = intent
+      ? searchCompositions(intent).map((hit) => getComposition(hit.name)).filter(Boolean)
+      : getAllCompositions().filter((c) => c.domain === domainName);
+
+    for (const composition of matchedCompositions) {
+      const cost = estimateTokens(composition);
+      if (usedTokens + cost > budget) break;
+      result.patterns.push(composition);
+      usedTokens += cost;
+    }
+  }
+
+  // ── Tier 4: Full exploration — add remaining compositions ──
+  if (tier >= 4) {
+    const added = new Set(result.patterns.map((c) => c.name));
+    for (const composition of getAllCompositions()) {
+      if (added.has(composition.name)) continue;
+      const cost = estimateTokens(composition);
+      if (usedTokens + cost > budget) break;
+      result.patterns.push(composition);
+      usedTokens += cost;
+    }
+  }
+
+  result.estimatedTokens = usedTokens;
+  return result;
+}
+
+/**
+ * Find an entry in the catalog by type name.
+ */
+function findEntry(catalog, typeName) {
+  if (catalog.entries.has(typeName)) return catalog.entries.get(typeName);
+  // Search by tag fallback
+  for (const entry of catalog.entries.values()) {
+    if (entry.type === typeName) return entry;
+  }
+  return null;
+}