@adia-ai/a2ui-retrieval 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog — @adia-ai/a2ui-retrieval
+
+Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+_Nothing yet._
+
+---
+
+## [0.0.1] - 2026-04-24
+
+First public release. Extracted from
+[`@adia-ai/a2ui-compose`](../compose/) during the 2026-04-24
+consolidation so non-compose tooling (tests, MCP validator tools,
+CI gates) can depend on retrieval without pulling the full
+generator graph.
+
+### Included
+
+- **Pattern library** (`pattern-library.js`) — indexed search over the
+  catalog's patterns + fragments; domain-aware ranking; loads patterns
+  from `@adia-ai/a2ui-corpus` at runtime.
+- **Intent gate** (`intent-gate.js`) — classifies UI-generating vs
+  conversational intents based on domain-keyword signal. Zero-signal
+  defaults to conversational (prevents hallucinated UI from
+  motivational / abstract text).
+- **Domain router** (`domain-router.js`) — free-form text → catalog
+  domain (`forms`, `data`, `agent`, `navigation`, `layout`, etc.).
+- **Anti-pattern detector** (`anti-patterns.js`) — flags invented
+  components + bad attribute combos against the registry.
+- **Clarity analyzer** (`clarity.js`) — scores intent specificity;
+  drives clarification prompts when signal is too weak.
+- **Context assembly** (`context.js`) — stitches retrieval results
+  into prompt context for LLM adapters.
+- **Embedding retriever** (`embedding-retriever.js`) — dense-vector
+  pattern retrieval (optional; gated on the presence of embeddings
+  in `@adia-ai/a2ui-corpus`).
+- **Prompt analyzer** (`prompt-analyzer.js`) — prompt-side features
+  feeding domain + clarity scoring.
+- **Dialog recorder** (`dialog-recorder.js`) — opt-in JSONL capture
+  of LLM round-trips for offline replay + tuning (gated on
+  `ADIA_LOG_DIALOGS=1`).
+- **Synthetic data** (`synthetic-data.js`) — deterministic
+  pattern-match-only generator used by the `instant` engine mode.
+
+### Dependencies
+
+- `@adia-ai/a2ui-utils` — A2UI registry + runtime primitives.

package/README.md

@@ -0,0 +1,40 @@
+# `@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
+
+- **Pattern library** — indexed search over the catalog's patterns and
+  fragments; domain-aware ranking.
+- **Intent gate** — classifies a user intent as UI-generating vs
+  conversational based on domain-keyword signal.
+- **Domain router** — maps free-form text to catalog domains
+  (`forms`, `data`, `agent`, `navigation`, etc.).
+- **Anti-pattern detector** — flags compositions that violate invariants
+  (invented components, bad attribute combos).
+- **Clarity analyzer** — scores how specific an intent is; drives
+  clarification prompts when the signal is too weak to generate.
+- **Context assembly** — stitches retrieval results into the prompt
+  context consumed by the LLM adapters.
+
+## Runtime
+
+Framework-agnostic JS. Depends only on
+[`@adia-ai/a2ui-utils`](https://www.npmjs.com/package/@adia-ai/a2ui-utils)
+for the A2UI registry + runtime primitives.
+
+## Links
+
+- Repo: [`adiahealth/gen-ui-kit`](https://github.com/adiahealth/gen-ui-kit)
+- Architecture: [`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/anti-patterns.js

@@ -0,0 +1,148 @@
+/**
+ * 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
+ */
+
+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-accent-*, 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) || [];
+      const known = new Set([
+        'row-ui', 'col-ui', 'list-ui', 'grid-ui', 'text-ui', 'image-ui',
+        'icon-ui', 'divider-ui', 'badge-ui', 'avatar-ui', 'progress-ui',
+        'skeleton-ui', 'input-ui', 'input-ui', 'check-ui', 'switch-ui',
+        'slider-ui', 'select-ui', 'datetime-ui', 'search-ui', 'upload-ui',
+        'button-ui', 'card-ui', 'tabs-ui', 'tab-ui', 'pane-ui', 'modal-ui',
+        'drawer-ui', 'toast-ui', 'popover-ui', 'stream-ui', 'form-container-ui',
+        'table-ui', 'chart-ui', 'embed-ui', 'stack-ui', 'block-ui', 'code-ui',
+        'textarea-ui', 'radio-ui', 'radio-ui', 'tag-ui', 'accordion-ui',
+        'modal-ui', 'alert-ui', 'tooltip-ui', 'menu-ui', 'breadcrumb-ui',
+        'nav-n', 'pagination-ui', 'avatar-group-ui', 'segmented-ui',
+        'segment-ui', 'command-ui', 'command-item-ui', 'command-group-ui',
+        'calendar-picker-ui', 'color-picker-ui', 'kbd-ui', 'toolbar-ui',
+        'otp-input-ui',
+        'theme-ui', 'router-ui', 'adia-root', 'noodles-ui',
+        'listbox-ui', 'icon-provider',
+      ]);
+      for (const match of tags) {
+        const tag = match.slice(1).toLowerCase();
+        if (!known.has(tag)) return true;
+      }
+      return false;
+    },
+    fix: 'Only use registered AdiaUI types. Check the registry for available components.',
+  },
+  {
+    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/catalog.js

@@ -0,0 +1,215 @@
+/**
+ * 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-utils';
+
+// ── 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 {
+    try {
+      const modules = import.meta.glob('../../web-components/components/*/*.a2ui.json', { query: '?raw', import: 'default' });
+      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 */ }
+      }
+    } catch { /* glob not available */ }
+  }
+}
+
+/**
+ * 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-n': 'navigation', 'pagination-ui': 'navigation',
+  'segmented-ui': 'navigation', 'segment-ui': 'navigation', 'router-ui': 'navigation',
+  'toggle-group-ui': 'navigation', 'toggle-option-ui': 'navigation',
+};
+
+// ── Trait registry ──
+const traitRegistry = [
+  { name: 'pressable',      category: 'input-interaction',    description: 'Normalizes click/tap/keyboard into a single "press" event' },
+  { name: 'focusable',      category: 'input-interaction',    description: 'Keyboard-only focus ring, ignores pointer focus' },
+  { name: 'hoverable',      category: 'input-interaction',    description: 'Pointer hover enter/leave state tracking' },
+  { name: 'active-state',   category: 'input-interaction',    description: 'Tracks pointer down / active interaction state' },
+  { name: 'disabled-state', category: 'input-interaction',    description: 'Enforces disabled behavior and interaction blocking' },
+  { name: 'keyboard-nav',     category: 'keyboard-navigation', description: 'Arrow keys, Enter, Escape — semantic navigation events' },
+  { name: 'roving-tabindex',  category: 'keyboard-navigation', description: 'Focus management within composite widgets' },
+  { name: 'typeahead',        category: 'keyboard-navigation', description: 'Incremental search within a collection' },
+  { name: 'hotkey',           category: 'keyboard-navigation', description: 'Global or scoped keyboard shortcuts' },
+  { name: 'focus-trap',       category: 'keyboard-navigation', description: 'Traps Tab/Shift+Tab within a container' },
+  { name: 'form-associated', category: 'forms-data', description: 'ElementInternals integration for form participation' },
+  { name: 'validation',      category: 'forms-data', description: 'Validation rules: required, minlength, pattern, email' },
+  { name: 'value-sync',      category: 'forms-data', description: 'Syncs value between attribute/property/controller' },
+  { name: 'dirty-state',     category: 'forms-data', description: 'Tracks modified vs initial value' },
+  { name: 'resettable',      category: 'forms-data', description: 'Responds to form reset events' },
+  { name: 'resize-observer-trait',       category: 'layout-measurement', description: 'Reacts to element size changes' },
+  { name: 'intersection-observer-trait', category: 'layout-measurement', description: 'Visibility detection (viewport)' },
+  { name: 'anchor-positioning',          category: 'layout-measurement', description: 'Positions relative to an anchor element' },
+  { name: 'portal',                      category: 'layout-measurement', description: 'Renders content in a different DOM root' },
+  { name: 'scroll-lock',                 category: 'layout-measurement', description: 'Disables background scrolling' },
+  { name: 'draggable',    category: 'motion-positioning', description: 'Pointer drag to reposition' },
+  { name: 'tossable',     category: 'motion-positioning', description: 'Flick with momentum + viewport bounce' },
+  { name: 'resizable',    category: 'motion-positioning', description: 'Drag edges/corners to resize' },
+  { name: 'inertia-drag', category: 'motion-positioning', description: 'Momentum-based dragging, smooth deceleration' },
+  { name: 'snap-to-grid', category: 'motion-positioning', description: 'Snaps position to configurable grid' },
+  { name: 'drag-ghost',   category: 'motion-positioning', description: 'Ghost clone at origin during drag' },
+  { name: 'ripple',         category: 'animation-feedback', description: 'Material-style press ripple effect' },
+  { name: 'spring-animate', category: 'animation-feedback', description: 'Spring-based motion transitions' },
+  { name: 'fade-presence',  category: 'animation-feedback', description: 'Enter/exit fade with lifecycle' },
+  { name: 'scale-press',    category: 'animation-feedback', description: 'Subtle scale transform on press' },
+  { name: 'tilt-hover',     category: 'animation-feedback', description: 'Tilt based on pointer position' },
+  { name: 'glow-focus',       category: 'visual-dynamics', description: 'Animated pulsing glow on focus' },
+  { name: 'gradient-shift',   category: 'visual-dynamics', description: 'Animated rainbow gradient backgrounds' },
+  { name: 'parallax',         category: 'visual-dynamics', description: 'Layered motion relative to pointer' },
+  { name: 'shimmer-loading',  category: 'visual-dynamics', description: 'Skeleton shimmer effect' },
+  { name: 'noise-texture',    category: 'visual-dynamics', description: 'Procedural grain overlay' },
+  { name: 'magnetic-hover',  category: 'interaction-delight', description: 'Element subtly follows cursor' },
+  { name: 'confetti',        category: 'interaction-delight', description: 'Radial particle burst on press' },
+  { name: 'confetti-burst',  category: 'interaction-delight', description: 'Upward fountain particle burst' },
+  { name: 'sound-feedback',  category: 'audio-haptics-sensory', description: 'Synthesized tones via Web Audio API' },
+  { name: 'haptic-feedback', category: 'audio-haptics-sensory', description: 'Vibration API feedback' },
+  { name: 'typewriter',      category: 'audio-haptics-sensory', description: 'Animated text reveal character by character' },
+  { name: 'count-up',        category: 'audio-haptics-sensory', description: 'Animated numeric transitions' },
+  { name: 'attention-pulse', category: 'audio-haptics-sensory', description: 'Periodic pulse to draw attention' },
+];
+
+// ── 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/clarity.js

@@ -0,0 +1,207 @@
+/**
+ * Clarity Assessment — Evaluates whether a user intent is clear enough
+ * to generate quality UI, or needs clarifying questions first.
+ *
+ * Scores intents across 5 dimensions:
+ *   domain   — Is the domain clear? (forms, data, layout, etc.)
+ *   scope    — Is the scope defined? (how many items, what sections?)
+ *   content  — Is the content specified? (labels, values, data?)
+ *   layout   — Is the layout preference stated? (grid, stack, sidebar?)
+ *   action   — Are actions/interactions mentioned? (buttons, forms, links?)
+ *
+ * Returns a clarity score (0-1) and targeted questions for what's missing.
+ */
+
+import { classifyIntent } from './domain-router.js';
+import { searchPatterns } from './pattern-library.js';
+
+// ── Dimension detectors ──────────────────────────────────────────────────
+
+/** Scope indicators: quantity, enumeration, specificity */
+const SCOPE_SIGNALS = [
+  /\b\d+\b/,                        // contains a number
+  /\b(three|two|four|five|six)\b/i,  // spelled-out numbers
+  /\b(with|containing|including|showing|displaying)\b/i,  // enumerates content
+  /\b(and|plus|also)\b/i,            // multiple items
+  /\b(columns?|rows?|items?|cards?|sections?|fields?|buttons?|tabs?|steps?)\b/i,  // structural counts
+];
+
+/** Content specificity: labels, values, named data */
+const CONTENT_SIGNALS = [
+  /\b(name|email|password|title|description|price|date|status|role|avatar)\b/i,
+  /\b(revenue|users|growth|sales|orders|metrics|analytics)\b/i,
+  /\b(todo|done|in progress|pending|active|completed)\b/i,
+  /\b(bleed|margin|trim|crop|preview|artwork|brand|design system)\b/i,
+  /\b(approved|approval|production|settings|configure|preference)\b/i,
+  /["'][\w\s]+["']/,                // quoted strings (specific labels)
+  /\$[\d,.]+/,                      // dollar amounts
+  /\d+%/,                           // percentages
+];
+
+/** Layout preferences */
+const LAYOUT_SIGNALS = [
+  /\b(grid|row|column|sidebar|split|horizontal|vertical|stack|centered)\b/i,
+  /\b(full.?width|responsive|mobile|compact|wide|narrow)\b/i,
+  /\b(\d+.?col(umn)?s?)\b/i,       // "3 columns", "2-col"
+  /\b(left|right|top|bottom|center)\b/i,
+];
+
+/** Action/interaction indicators */
+const ACTION_SIGNALS = [
+  /\b(button|submit|cancel|save|delete|edit|close|open|toggle|click)\b/i,
+  /\b(form|input|select|search|filter|sort|upload|download)\b/i,
+  /\b(login|signup|register|checkout|confirm|approve|reject)\b/i,
+  /\b(navigate|link|redirect|route)\b/i,
+  /\b(drag|drop|resize|expand|collapse)\b/i,
+];
+
+/**
+ * Assess clarity of a user intent for UI generation.
+ *
+ * @param {string} intent — Raw user input
+ * @param {{ domain: string, confidence: number, matchedSignals: string[] }} [classification] — Pre-computed classification
+ * @returns {{
+ *   clear: boolean,
+ *   score: number,
+ *   dimensions: { domain: number, scope: number, content: number, layout: number, action: number },
+ *   questions: { text: string, dimension: string, priority: number }[],
+ *   summary: string,
+ * }}
+ */
+export function assessClarity(intent, classification) {
+  const text = (intent ?? '').trim();
+  if (!text) {
+    return {
+      clear: false,
+      score: 0,
+      dimensions: { domain: 0, scope: 0, content: 0, layout: 0, action: 0 },
+      questions: [{ text: 'What would you like me to build?', dimension: 'domain', priority: 1 }],
+      summary: 'No intent provided',
+    };
+  }
+
+  const cls = classification || classifyIntent(text);
+  const patterns = searchPatterns(text);
+  const lower = text.toLowerCase();
+  const wordCount = text.split(/\s+/).length;
+
+  // ── Score each dimension ──
+
+  // Domain: how confident is the domain classification?
+  const domainScore = cls.confidence >= 0.3 ? 1 : cls.confidence >= 0.15 ? 0.6 : cls.matchedSignals.length > 0 ? 0.3 : 0;
+
+  // Scope: is the scope specific?
+  const scopeHits = SCOPE_SIGNALS.filter(r => r.test(text)).length;
+  const scopeScore = Math.min(1, scopeHits / 2);
+
+  // Content: are concrete labels/values mentioned?
+  const contentHits = CONTENT_SIGNALS.filter(r => r.test(text)).length;
+  const contentScore = Math.min(1, contentHits / 2);
+
+  // Layout: is a layout preference stated?
+  const layoutHits = LAYOUT_SIGNALS.filter(r => r.test(text)).length;
+  const layoutScore = Math.min(1, layoutHits);
+
+  // Action: are interactions mentioned?
+  const actionHits = ACTION_SIGNALS.filter(r => r.test(text)).length;
+  const actionScore = Math.min(1, actionHits / 2);
+
+  // ── Overall score (weighted) ──
+  const score = (
+    domainScore * 0.25 +
+    scopeScore * 0.25 +
+    contentScore * 0.20 +
+    layoutScore * 0.15 +
+    actionScore * 0.15
+  );
+
+  // ── Bonus: pattern match adds confidence ──
+  const patternBonus = patterns.length > 0 ? 0.15 : 0;
+  // Bonus: long intents are usually more specific
+  const lengthBonus = wordCount > 10 ? 0.1 : wordCount > 6 ? 0.05 : 0;
+
+  const finalScore = Math.min(1, score + patternBonus + lengthBonus);
+
+  // ── Generate targeted questions for weak dimensions ──
+  const questions = [];
+
+  if (domainScore < 0.3) {
+    questions.push({
+      text: 'What type of UI is this? (e.g., a form, dashboard, profile card, settings page)',
+      dimension: 'domain',
+      priority: 1,
+    });
+  }
+
+  if (scopeScore < 0.5) {
+    const domainQuestions = {
+      forms: 'What fields should the form include?',
+      data: 'What data should be displayed? How many items or metrics?',
+      layout: 'How many sections or cards should it have?',
+      agent: 'What actions should the assistant support?',
+      navigation: 'What pages or sections should be navigable?',
+    };
+    questions.push({
+      text: domainQuestions[cls.domain] || 'Can you be more specific about what it should contain?',
+      dimension: 'scope',
+      priority: 2,
+    });
+  }
+
+  if (contentScore < 0.3 && scopeScore >= 0.3) {
+    const contentQuestions = {
+      forms: 'What labels should the fields have? (e.g., "Email", "Password", "Full Name")',
+      data: 'What metrics or values should be shown? (e.g., revenue, users, growth rate)',
+      layout: 'What content goes in each section?',
+      agent: 'What kind of messages or responses should be shown?',
+      navigation: 'What should the menu items or links be labeled?',
+    };
+    questions.push({
+      text: contentQuestions[cls.domain] || 'What specific content should be displayed?',
+      dimension: 'content',
+      priority: 3,
+    });
+  }
+
+  if (layoutScore < 0.3 && scopeScore >= 0.5) {
+    questions.push({
+      text: 'Any layout preference? (e.g., grid of cards, single column, sidebar + content)',
+      dimension: 'layout',
+      priority: 4,
+    });
+  }
+
+  if (actionScore < 0.3 && domainScore >= 0.3) {
+    questions.push({
+      text: 'What actions should users be able to take? (e.g., submit, edit, delete, filter)',
+      dimension: 'action',
+      priority: 5,
+    });
+  }
+
+  // Sort by priority, limit to 3
+  questions.sort((a, b) => a.priority - b.priority);
+  const topQuestions = questions.slice(0, 3);
+
+  // ── Determine if clear enough to proceed ──
+  // Clear only if dimensional score meets threshold
+  const clear = finalScore >= 0.4;
+
+  const summary = clear
+    ? `Intent is ${finalScore >= 0.7 ? 'clear' : 'adequate'} (${Math.round(finalScore * 100)}%)`
+    : `Intent needs clarification (${Math.round(finalScore * 100)}% — below 40% threshold)`;
+
+  return {
+    clear,
+    score: Math.round(finalScore * 100) / 100,
+    dimensions: {
+      domain: Math.round(domainScore * 100) / 100,
+      scope: Math.round(scopeScore * 100) / 100,
+      content: Math.round(contentScore * 100) / 100,
+      layout: Math.round(layoutScore * 100) / 100,
+      action: Math.round(actionScore * 100) / 100,
+    },
+    questions: topQuestions,
+    summary,
+  };
+}