@adia-ai/gen-ui 0.8.37

package/retrieval/README.md

@@ -0,0 +1,71 @@
+# `@adia-ai/a2ui-retrieval`
+
+Retrieval layer for the A2UI (Agent-to-UI) protocol — catalog lookup,
+intent classification, domain routing, pattern + anti-pattern matching,
+clarity + context assembly. Consumed by
+[`@adia-ai/a2ui-compose`](../compose/) and any A2UI-protocol tooling
+that needs to reason about user intent against the catalog.
+
+## Install
+
+```bash
+npm install @adia-ai/a2ui-retrieval
+```
+
+## What's here
+
+The package groups its 26 source files into 4 sub-concerns plus a
+top-level lookup surface. Importers can pull the top-level barrel
+(`@adia-ai/a2ui-retrieval`) for the previously-public surface, the
+per-subdir barrels (`@adia-ai/a2ui-retrieval/intent` etc.), or
+individual files for fine-grained imports.
+
+```
+a2ui-retrieval/
+├── catalog.js              top-level — catalog lookup (loaded from corpus)
+├── pattern-library.js      top-level — keyword + semantic pattern search
+├── concept-mapper.js       top-level — concept → catalog-entry mapping
+├── domain-router.js        top-level — intent → catalog-domain classifier
+├── wiring-catalog.js       top-level — controller / handler reference
+├── anti-patterns.js        top-level — known-bad pattern detector
+├── context-assembler.js    top-level — retrieval results → LLM context
+├── component-entry.js      top-level — catalog row serializer
+├── index.js                top-level — barrel
+│
+├── intent/                 intent classification + decomposition
+│   ├── intent-alignment.js
+│   ├── intent-categorizer.js
+│   ├── intent-gate.js          UI-generating vs conversational
+│   ├── prompt-analyzer.js
+│   ├── decomposer.js           compound intents → subtasks
+│   └── clarity.js              clarity scoring
+│
+├── embedding/              dense-vector retrieval
+│   ├── embedding-provider.js   adapter (Voyage / OpenAI / fallback)
+│   ├── embedding-retriever.js  top-N pattern retrieval
+│   └── chunk-embedding-retriever.js  chunk-level retrieval
+│
+├── feedback/               user-feedback ingestion loop
+│   ├── feedback.js
+│   ├── feedback-store.js       JSONL store under .brain/feedback/
+│   ├── feedback-analyzer.js
+│   ├── dialog-recorder.js      LLM round-trip capture (gated by env)
+│   └── gap-registry.js         tracked gaps in catalog coverage
+│
+└── authoring/              corpus-authoring helpers (upstream of retrieval)
+    ├── synthetic-data.js
+    ├── web-research.js
+    └── pattern-promotion.js
+```
+
+## Runtime
+
+Framework-agnostic JS. Depends only on
+[`@adia-ai/a2ui-runtime`](https://www.npmjs.com/package/@adia-ai/a2ui-runtime)
+for the A2UI registry + runtime primitives.
+
+## Links
+
+- Repo: [`adiahealth/gen-ui-kit`](https://github.com/adiahealth/gen-ui-kit)
+- Architecture: [`.claude/docs/specs/package-architecture.md`](https://github.com/adiahealth/gen-ui-kit/blob/main/docs/specs/package-architecture.md)
+- CHANGELOG: [`CHANGELOG.md`](./CHANGELOG.md)

package/retrieval/anti-patterns.js

@@ -0,0 +1,189 @@
+/**
+ * Anti-Pattern Registry — known bad patterns from AdiaUI best practices.
+ *
+ * Each anti-pattern has:
+ *   - name: machine identifier
+ *   - description: what the anti-pattern is
+ *   - check: regex or function to detect it in HTML strings
+ *   - fix: guidance on how to correct it
+ */
+
+import { registry } from '@adia-ai/a2ui/registry';
+import { getAllComponentData } from './component-catalog.js';
+
+// `noInventedComponents`'s allowlist, below, used to be a hand-frozen Set —
+// it drifted stale at least once in production (missing field-ui, a core
+// primitive) before being "regenerated" as a one-time manual snapshot on
+// 2026-06-10, which is itself already stale again. Built live instead, from
+// the two sources every registered tag actually comes from:
+//   - `registry` (@adia-ai/a2ui) — the A2UI-emittable compose types
+//     (validator.js's checkAllTypesRegistered already imports this same Map).
+//   - `component-catalog.js`'s per-component `.a2ui.json` sidecars (the
+//     dual-mode Node/browser/static loader AGENTS.md names as the canonical
+//     pattern for this directory) — covers every component with a yaml SoT,
+//     including ones like agent-artifact-ui/aside-ui/preview-ui that exist
+//     but were never wired into the compose-emission registry.
+// `CORE_INFRA_TAGS` covers the residual few real elements neither source
+// carries: `router-ui` is defined directly in core/provider.js with no
+// yaml/generated sidecar and is never an A2UI-emittable type.
+const CORE_INFRA_TAGS = ['router-ui'];
+
+function buildKnownTags() {
+  const tags = new Set(registry.values());
+  for (const data of Object.values(getAllComponentData())) {
+    const tag = data?.['x-adiaui']?.tag;
+    if (tag) tags.add(tag);
+  }
+  for (const tag of CORE_INFRA_TAGS) tags.add(tag);
+  return tags;
+}
+
+const KNOWN_TAGS = buildKnownTags();
+
+const antiPatterns = [
+  {
+    name: 'noBareDivs',
+    description: 'All elements should be AdiaUI components, not bare <div> elements.',
+    check: /<div[\s>]/i,
+    fix: 'Replace <div> with the appropriate AdiaUI layout component: Row, Column, Grid, Card, or Section.',
+  },
+  {
+    name: 'noBareInputs',
+    description: 'Form controls should use component wrappers, not native <input>/<select>/<textarea>.',
+    check: /<(input|select|textarea)[\s>]/i,
+    fix: 'Use input-ui, select-ui, textarea-ui, check-ui, switch-ui, slider-ui, or datetime-ui instead.',
+  },
+  {
+    name: 'cardStructure',
+    description: 'Card children must follow the header/section/footer anatomy. Header and footer are direct children of card.',
+    check: (html) => {
+      // Detect section > header or section > footer (wrong nesting)
+      return /<section[^>]*>\s*<header/i.test(html) || /<section[^>]*>\s*<footer/i.test(html);
+    },
+    fix: 'Header and Footer must be direct children of Card, not nested inside Section. Structure: Card > Header + Section + Footer.',
+  },
+  {
+    name: 'flatAdjacency',
+    description: 'AdiaUI uses flat component lists with ID references, not deeply nested component trees.',
+    check: (html) => {
+      // Heuristic: detect 5+ levels of nesting with AdiaUI components
+      const nested = html.match(/<[a-z]+-(?:n|ui)[^>]*>\s*<[a-z]+-(?:n|ui)[^>]*>\s*<[a-z]+-(?:n|ui)[^>]*>\s*<[a-z]+-(?:n|ui)[^>]*>\s*<[a-z]+-(?:n|ui)/i);
+      return !!nested;
+    },
+    fix: 'Use a flat adjacency list with unique IDs and children arrays referencing IDs.',
+  },
+  {
+    name: 'columnWrap',
+    description: 'Content inside Section must be wrapped in a Column (col-ui), not placed directly.',
+    check: (html) => {
+      // Detect section > text-ui or section > p (without col-ui wrapper)
+      return /<section[^>]*>\s*<(text-ui|p |p>|h[1-6])/i.test(html);
+    },
+    fix: 'Wrap section content in <col-ui>: Section > Column > Text/content.',
+  },
+  {
+    name: 'noHardcodedColors',
+    description: 'Use design token colors (--a-*) instead of hardcoded hex/rgb/hsl values.',
+    check: /(style\s*=\s*"[^"]*(?:color|background)\s*:\s*(?:#[0-9a-f]{3,8}|rgb|hsl))/i,
+    fix: 'Use token-based colors via variant attributes or CSS custom properties (--a-canvas-*, --a-primary-*, etc.).',
+  },
+  {
+    name: 'noInlineLayout',
+    description: 'Use declarative layout attributes instead of inline display/flex/grid styles.',
+    check: /(style\s*=\s*"[^"]*(?:display\s*:|flex|grid-template))/i,
+    fix: 'Use Row, Column, Grid components with gap/columns attributes instead of inline CSS layout.',
+  },
+  {
+    name: 'noInventedComponents',
+    description: 'Only use components from the AdiaUI registry. Do not invent custom component tags.',
+    check: (html) => {
+      const tags = html.match(/<([a-z]+-(?:n|ui))\b/gi) || [];
+      for (const match of tags) {
+        const tag = match.slice(1).toLowerCase();
+        if (!KNOWN_TAGS.has(tag)) return true;
+      }
+      return false;
+    },
+    fix: 'Only use registered AdiaUI types. Check the registry for available components.',
+  },
+  {
+    name: 'noCssPropAttrs',
+    description: 'CSS properties (display, visibility) are not markup attributes. Components silently ignore unknown attributes, so display="none" content renders VISIBLY — overlapping its siblings.',
+    check: /\s(?:display|visibility)\s*=\s*"/i,
+    fix: 'Remove the attribute. To hide content conditionally, omit the element from the tree (or use the component\'s documented state attribute, e.g. [hidden] on plain containers).',
+  },
+  {
+    name: 'inputTypeTextarea',
+    description: 'input-ui has no type="textarea" — multi-line input is its own component.',
+    check: /<input-ui[^>]*\btype\s*=\s*"textarea"/i,
+    fix: 'Use <textarea-ui rows="…"> for multi-line text input.',
+  },
+  {
+    name: 'fieldOwnsLabelHintError',
+    description: 'field-ui OWNS the label / hint / error chrome via its label= / hint= / error= attributes. Emitting a sibling text-ui "label", a raw <label>, or a <small> error inside field-ui double-renders and breaks the label-to-control binding (field-ui binds the first slot-less child as the control — a text-ui label steals that binding).',
+    check: (html) => {
+      // LLM-emitted label-ish children inside field-ui. The stamped internal
+      // label carries data-field-label — exclude it so post-render HTML
+      // doesn't false-positive.
+      if (/<field-ui[^>]*>\s*(?:<text-ui[^>]*variant\s*=\s*"label"|<label(?![^>]*data-field-label))/i.test(html)) return true;
+      // <small> is not an AdiaUI component anywhere; inside field-ui it is
+      // always a hand-rolled error line.
+      return /<field-ui[^>]*>[\s\S]*?<small[\s>]/i.test(html);
+    },
+    fix: 'Use <field-ui label="Full Name" hint="…" error="…"><input-ui …/></field-ui> — exactly ONE slot-less child (the control); field-ui renders the label, hint, and error itself.',
+  },
+  {
+    name: 'slotOnContainer',
+    description: 'Slot attributes (slot="heading", slot="description", slot="action") must go on the content children inside Header/Footer, not on Header/Footer elements themselves.',
+    check: (html) => {
+      return /<header[^>]*\bslot\s*=/i.test(html) || /<footer[^>]*\bslot\s*=/i.test(html);
+    },
+    fix: 'Move slot="heading" from <header> to the Text/heading child inside it. Header is a grid container — slots go on its children.',
+  },
+];
+
+/**
+ * Get all registered anti-patterns.
+ * @returns {Array<{name: string, description: string, fix: string}>}
+ */
+export function getAntiPatterns() {
+  return antiPatterns.map(({ name, description, fix }) => ({ name, description, fix }));
+}
+
+/**
+ * Check an HTML string against a specific anti-pattern.
+ *
+ * @param {string} name — Anti-pattern name
+ * @param {string} html — HTML string to check
+ * @returns {{ violated: boolean, name: string, description: string, fix: string } | null}
+ *   Returns the violation object if detected, null if the pattern name is unknown.
+ */
+export function checkAntiPattern(name, html) {
+  const pattern = antiPatterns.find(p => p.name === name);
+  if (!pattern) return null;
+
+  const violated = typeof pattern.check === 'function'
+    ? pattern.check(html)
+    : pattern.check.test(html);
+
+  return {
+    violated,
+    name: pattern.name,
+    description: pattern.description,
+    fix: pattern.fix,
+  };
+}
+
+/**
+ * Check HTML against all anti-patterns. Returns only violations.
+ *
+ * @param {string} html — HTML string to check
+ * @returns {Array<{name: string, description: string, fix: string}>}
+ */
+export function checkAllAntiPatterns(html) {
+  return antiPatterns
+    .filter(p => {
+      return typeof p.check === 'function' ? p.check(html) : p.check.test(html);
+    })
+    .map(({ name, description, fix }) => ({ name, description, fix }));
+}

package/retrieval/authoring/index.d.ts

@@ -0,0 +1,4 @@
+// v0.5.21 hotfix stub — TS-migration Phase 1 (568bb998d) declared this
+// types: export but Phase 2 hasn't generated real declarations yet.
+// Replace with real type declarations when Phase 2 lands.
+export {};

package/retrieval/authoring/index.js

@@ -0,0 +1,9 @@
+/**
+ * @adia-ai/gen-ui/retrieval/authoring — corpus authoring helpers.
+ *
+ * Web-research helpers used by `compose/core/generator.js` to enrich
+ * intent before generation. Synthetic-data + pattern-promotion retired
+ * in §64 alongside `pattern-library.js`.
+ */
+
+export * from './web-research.js';

package/retrieval/authoring/web-research.js

@@ -0,0 +1,220 @@
+/**
+ * Web Research — Enriches generation context with web search results.
+ *
+ * Detects reference mentions in intents ("like Stripe", "Notion-style"),
+ * generates targeted search queries, fetches results, and extracts
+ * UI-relevant patterns to feed into the generation prompt.
+ *
+ * Works with any search function that matches:
+ *   search(query) → Promise<{ results: { title, snippet, url }[] }>
+ *
+ * Falls back to LLM knowledge when no search function is provided.
+ */
+
+// ── Reference detection ──────────────────────────────────────────────────
+
+/**
+ * Patterns split by signal strength:
+ *
+ *   EXPLICIT_PATTERNS — the surrounding language declares the captured
+ *     token IS a brand reference ("like X", "X-style", "similar to X").
+ *     The capture is accepted as a reference even if not in KNOWN_REFERENCES.
+ *
+ *   IMPLICIT_PATTERNS — the surrounding language is a UI-shape verb
+ *     ("X pricing page"); the capture COULD be a brand or COULD be a
+ *     generic noun. Accept ONLY if in KNOWN_REFERENCES, otherwise drop.
+ *
+ * Splitting this way fixes the 2026-05-02 bug where "tier pricing page"
+ * extracted "tier" as a reference and seeded a research query for it. The
+ * regex was working as designed — `\w+ pricing page` captures the prefix
+ * word — but a generic noun like "tier" or "subscription" or "fancy"
+ * isn't a brand reference, so research and downstream prompt enrichment
+ * shouldn't act on it.
+ */
+const EXPLICIT_PATTERNS = [
+  /\blike\s+(\w[\w\s]*?)(?:\s*['']s|\s+style|\s+design|\s*$)/i,
+  /\b(\w[\w\s]*?)[\s-]style\b/i,
+  /\b(\w[\w\s]*?)[\s-]inspired\b/i,
+  /\bsimilar\s+to\s+(\w[\w\s]*?)(?:\s|$|,)/i,
+  /\bbased\s+on\s+(\w[\w\s]*?)(?:\s|$|,)/i,
+  /\bcopy\s+(\w[\w\s]*?)(?:\s|$|,)/i,
+  /\bclone\s+(\w[\w\s]*?)(?:\s|$|,)/i,
+];
+
+const IMPLICIT_PATTERNS = [
+  /\b(\w+)\s+(?:pricing|dashboard|landing|login|settings|profile)\s+page\b/i,
+];
+
+/** Well-known product/brand names for UI reference */
+const KNOWN_REFERENCES = new Set([
+  'stripe', 'notion', 'linear', 'figma', 'slack', 'discord', 'spotify',
+  'github', 'vercel', 'netlify', 'supabase', 'firebase', 'tailwind',
+  'shadcn', 'radix', 'chakra', 'material', 'ant', 'bootstrap',
+  'shopify', 'airbnb', 'uber', 'twitter', 'instagram', 'dribbble',
+  'apple', 'google', 'microsoft', 'amazon', 'netflix',
+]);
+
+/**
+ * Detect product/brand references in an intent.
+ *
+ * @param {string} intent
+ * @returns {{ references: string[], queries: string[] }}
+ */
+export function detectReferences(intent) {
+  const references = [];
+  const lower = intent.toLowerCase();
+
+  // Explicit-signal patterns — accept the capture as a reference.
+  for (const pattern of EXPLICIT_PATTERNS) {
+    const match = intent.match(pattern);
+    if (match) {
+      let ref = (match[1] || '').trim();
+      ref = ref.replace(/^(the|a|an)\s+/i, '');
+      if (ref && ref.length > 1 && ref.length < 30) {
+        references.push(ref);
+      }
+    }
+  }
+
+  // Implicit-signal patterns — gate by KNOWN_REFERENCES so generic nouns
+  // ("tier", "fancy", "simple") don't get treated as brands.
+  for (const pattern of IMPLICIT_PATTERNS) {
+    const match = intent.match(pattern);
+    if (match) {
+      let ref = (match[1] || '').trim();
+      ref = ref.replace(/^(the|a|an)\s+/i, '');
+      if (ref && ref.length > 1 && ref.length < 30 && KNOWN_REFERENCES.has(ref.toLowerCase())) {
+        references.push(ref);
+      }
+    }
+  }
+
+  // Direct brand name detection (only as whole words)
+  for (const brand of KNOWN_REFERENCES) {
+    const re = new RegExp(`\\b${brand}\\b`, 'i');
+    if (re.test(lower) && !references.some(r => r.toLowerCase() === brand)) {
+      references.push(brand);
+    }
+  }
+
+  // Filter out non-brand captures from the explicit patterns — words like
+  // "inspired" can sneak through when the intent is "X-inspired" with no
+  // X (e.g. "is this AI-inspired?"). Belt and suspenders.
+  const NON_BRANDS = new Set(['inspired', 'style', 'based', 'like', 'similar', 'the']);
+  for (let i = references.length - 1; i >= 0; i--) {
+    if (NON_BRANDS.has(references[i].toLowerCase())) references.splice(i, 1);
+  }
+
+  // Generate search queries from references + intent context
+  const queries = [];
+  const uniqueRefs = [...new Set(references.map(r => r.toLowerCase()))];
+
+  for (const ref of uniqueRefs.slice(0, 2)) {
+    // Extract the UI type from the intent
+    const uiType = extractUIType(intent);
+    if (uiType) {
+      queries.push(`${ref} ${uiType} UI design components`);
+    } else {
+      queries.push(`${ref} UI design pattern layout`);
+    }
+  }
+
+  // If no references but intent mentions specific UI patterns
+  if (queries.length === 0) {
+    const uiType = extractUIType(intent);
+    if (uiType && intent.split(/\s+/).length < 6) {
+      // Short intent about a UI type — search for best practices
+      queries.push(`best ${uiType} UI design patterns 2024`);
+    }
+  }
+
+  return { references: uniqueRefs, queries };
+}
+
+/**
+ * Extract the UI type/pattern from an intent (pricing, dashboard, login, etc.)
+ */
+function extractUIType(intent) {
+  const lower = intent.toLowerCase();
+  const types = [
+    'pricing', 'dashboard', 'landing page', 'login', 'signup', 'settings',
+    'profile', 'onboarding', 'checkout', 'notification', 'kanban', 'calendar',
+    'chat', 'sidebar', 'navbar', 'hero', 'footer', 'table', 'form',
+    'modal', 'card', 'timeline', 'analytics', 'admin',
+  ];
+  return types.find(t => lower.includes(t)) || null;
+}
+
+/**
+ * Research UI patterns for an intent using web search.
+ *
+ * @param {string} intent — User's generation intent
+ * @param {object} [options]
+ * @param {(query: string) => Promise<{ results: { title: string, snippet: string, url: string }[] }>} [options.search] — Search function
+ * @param {object} [options.llmAdapter] — LLM adapter for summarization
+ * @returns {Promise<{ references: string[], insights: string[], searchResults: object[], context: string }>}
+ */
+export async function researchIntent(intent, options = {}) {
+  const { search, llmAdapter } = options;
+  const { references, queries } = detectReferences(intent);
+
+  // No references and no search → return empty
+  if (references.length === 0 && queries.length === 0) {
+    return { references: [], insights: [], searchResults: [], context: '' };
+  }
+
+  // ── Fetch search results ──
+  const searchResults = [];
+  if (search && queries.length > 0) {
+    for (const query of queries.slice(0, 2)) {
+      try {
+        const result = await search(query);
+        if (result?.results?.length) {
+          searchResults.push(...result.results.slice(0, 3));
+        }
+      } catch {
+        // Search failed — continue without it
+      }
+    }
+  }
+
+  // ── Build context from results ──
+  const insights = [];
+
+  if (searchResults.length > 0) {
+    // Extract UI-relevant snippets
+    for (const result of searchResults) {
+      if (result.snippet) {
+        insights.push(`${result.title}: ${result.snippet}`);
+      }
+    }
+  }
+
+  // ── LLM-powered reference description (when search has no results) ──
+  if (insights.length === 0 && llmAdapter && references.length > 0) {
+    try {
+      const refList = references.join(', ');
+      const uiType = extractUIType(intent) || 'UI';
+      const response = await llmAdapter.complete({
+        messages: [{ role: 'user', content: `Briefly describe the ${uiType} design of ${refList}. Focus on: layout structure, key components, visual hierarchy, and interaction patterns. 3-4 sentences max.` }],
+        systemPrompt: 'You are a UI design expert. Give concise, factual descriptions of well-known product UIs. Focus on structure and components, not opinions.',
+      });
+      if (response.content) {
+        insights.push(response.content);
+      }
+    } catch {
+      // LLM failed — continue without it
+    }
+  }
+
+  // ── Compile context string for the generation prompt ──
+  let context = '';
+  if (references.length > 0) {
+    context += `Reference designs: ${references.join(', ')}\n`;
+  }
+  if (insights.length > 0) {
+    context += `Design insights:\n${insights.map(i => `- ${i}`).join('\n')}`;
+  }
+
+  return { references, insights, searchResults, context };
+}