@adia-ai/gen-ui 0.8.37

package/retrieval/intent/intent-alignment.js

@@ -0,0 +1,172 @@
+const FIELD_PATTERNS = [
+  /\b(email|password|username|name|phone|address|city|state|zip|country|company|title|role|bio|url|website|date|time|description|message|subject|amount|price|quantity|search|notes?)\b/gi
+];
+const COMPONENT_PATTERNS = [
+  /\b(button|form|table|chart|card|avatar|badge|alert|modal|drawer|tabs?|sidebar|navbar|breadcrumb|pagination|progress|slider|toggle|checkbox|radio|dropdown|select|upload|calendar|timeline|steps?|accordion)\b/gi
+];
+const QUANTITY_MAP = { one: 1, two: 2, three: 3, four: 4, five: 5, six: 6, seven: 7, eight: 8, nine: 9, ten: 10 };
+const QUANTITY_PATTERN = /\b(\d+|one|two|three|four|five|six|seven|eight|nine|ten)\s+(cards?|columns?|items?|fields?|buttons?|sections?|rows?|tiles?|steps?|tabs?|metrics?|stats?)\b/gi;
+const ACTION_PATTERNS = [
+  /\b(submit|cancel|save|delete|edit|close|open|search|filter|sort|login|signup|register|checkout|confirm|reset|send|upload|download|share|copy|print)\b/gi
+];
+const CONTENT_PATTERNS = [
+  /["']([^"']+)["']/g,
+  // quoted strings
+  /\$[\d,.]+/g,
+  // dollar amounts
+  /\d+%/g
+  // percentages
+];
+function extractExpectations(intent) {
+  const lower = intent.toLowerCase();
+  const fields = [];
+  for (const pattern of FIELD_PATTERNS) {
+    pattern.lastIndex = 0;
+    let match;
+    while (match = pattern.exec(lower)) {
+      const f = (match[1] ?? "").toLowerCase();
+      if (!fields.includes(f)) fields.push(f);
+    }
+  }
+  const componentTypes = [];
+  for (const pattern of COMPONENT_PATTERNS) {
+    pattern.lastIndex = 0;
+    let match;
+    while (match = pattern.exec(lower)) {
+      const t = (match[1] ?? "").toLowerCase();
+      if (!componentTypes.includes(t)) componentTypes.push(t);
+    }
+  }
+  const quantities = [];
+  QUANTITY_PATTERN.lastIndex = 0;
+  let qMatch;
+  while (qMatch = QUANTITY_PATTERN.exec(lower)) {
+    const raw = qMatch[1] ?? "";
+    const num = QUANTITY_MAP[raw] ?? parseInt(raw, 10);
+    const type = (qMatch[2] ?? "").replace(/s$/, "");
+    if (!isNaN(num)) quantities.push({ count: num, type });
+  }
+  const actions = [];
+  for (const pattern of ACTION_PATTERNS) {
+    pattern.lastIndex = 0;
+    let match;
+    while (match = pattern.exec(lower)) {
+      const a = (match[1] ?? "").toLowerCase();
+      if (!actions.includes(a)) actions.push(a);
+    }
+  }
+  const content = [];
+  for (const pattern of CONTENT_PATTERNS) {
+    pattern.lastIndex = 0;
+    let match;
+    while (match = pattern.exec(intent)) {
+      content.push(match[1] ?? match[0]);
+    }
+  }
+  return { fields, componentTypes, quantities, actions, content };
+}
+const TYPE_MAP = {
+  button: ["Button"],
+  form: ["FormContainer", "TextField", "Column"],
+  table: ["Table"],
+  chart: ["Chart"],
+  card: ["Card"],
+  avatar: ["Avatar"],
+  badge: ["Badge"],
+  alert: ["Alert"],
+  modal: ["Modal", "Dialog"],
+  drawer: ["Drawer"],
+  tab: ["Tabs", "Tab"],
+  sidebar: ["Sidebar"],
+  navbar: ["Nav"],
+  breadcrumb: ["Breadcrumb"],
+  pagination: ["Pagination"],
+  progress: ["Progress"],
+  slider: ["Slider"],
+  toggle: ["Toggle"],
+  checkbox: ["CheckBox"],
+  radio: ["Radio"],
+  dropdown: ["ChoicePicker", "Select"],
+  select: ["ChoicePicker", "Select"],
+  upload: ["Upload"],
+  calendar: ["CalendarPicker", "DateTimeInput"],
+  timeline: ["Timeline"],
+  step: ["Steps"],
+  accordion: ["Accordion"]
+};
+function verifyAlignment(components, expectations) {
+  const checks = [];
+  const gaps = [];
+  const allText = components.map((c) => {
+    const texts = [c["textContent"], c["text"], c["label"], c["placeholder"], c["description"], c["name"]];
+    return texts.filter(Boolean).join(" ").toLowerCase();
+  }).join(" ");
+  const allTypes = new Set(components.map((c) => c.component));
+  for (const field of expectations.fields) {
+    const found = allText.includes(field) || components.some((c) => (c["label"] ?? "").toLowerCase().includes(field) || (c["placeholder"] ?? "").toLowerCase().includes(field) || (c["name"] ?? "").toLowerCase().includes(field));
+    checks.push({
+      category: "field",
+      expected: field,
+      found,
+      detail: found ? `Found "${field}" in component properties` : `Missing field: "${field}"`
+    });
+    if (!found) gaps.push(`Missing field "${field}"`);
+  }
+  for (const type of expectations.componentTypes) {
+    const mappedTypes = TYPE_MAP[type] ?? [type.charAt(0).toUpperCase() + type.slice(1)];
+    const found = mappedTypes.some((t) => allTypes.has(t));
+    checks.push({
+      category: "componentType",
+      expected: type,
+      found,
+      detail: found ? `Found ${type} component` : `Missing component type: ${type}`
+    });
+    if (!found) gaps.push(`Missing ${type} component`);
+  }
+  for (const { count, type } of expectations.quantities) {
+    const mappedTypes = TYPE_MAP[type] ?? [type.charAt(0).toUpperCase() + type.slice(1)];
+    const actual = components.filter((c) => mappedTypes.some((t) => c.component === t)).length;
+    const found = actual >= count;
+    checks.push({
+      category: "quantity",
+      expected: `${count} ${type}(s)`,
+      found,
+      detail: found ? `Found ${actual} ${type}(s) (expected ${count})` : `Only ${actual} ${type}(s), expected ${count}`
+    });
+    if (!found) gaps.push(`Expected ${count} ${type}(s), found ${actual}`);
+  }
+  for (const action of expectations.actions) {
+    const found = allText.includes(action) || components.some((c) => c.component === "Button" && (c["text"] ?? "").toLowerCase().includes(action));
+    checks.push({
+      category: "action",
+      expected: action,
+      found,
+      detail: found ? `Found "${action}" action` : `Missing action: "${action}"`
+    });
+    if (!found) gaps.push(`Missing "${action}" action`);
+  }
+  for (const text of expectations.content) {
+    const found = allText.includes(text.toLowerCase());
+    checks.push({
+      category: "content",
+      expected: text,
+      found,
+      detail: found ? `Found content "${text}"` : `Missing content: "${text}"`
+    });
+    if (!found) gaps.push(`Missing content "${text}"`);
+  }
+  const total = checks.length;
+  const passed = checks.filter((c) => c.found).length;
+  const score = total > 0 ? Math.round(passed / total * 100) / 100 : 1;
+  return { score, checks, gaps };
+}
+function checkIntentAlignment(intent, components) {
+  const expectations = extractExpectations(intent);
+  const result = verifyAlignment(components, expectations);
+  return { ...result, expectations };
+}
+export {
+  checkIntentAlignment,
+  extractExpectations,
+  verifyAlignment
+};

package/retrieval/intent/intent-categorizer.js

@@ -0,0 +1,69 @@
+const CATEGORY_RULES = [
+  // Form categories
+  { category: "form/login", keywords: ["login", "sign in", "signin", "log in", "authentication"] },
+  { category: "form/signup", keywords: ["signup", "sign up", "register", "registration", "create account", "onboarding"] },
+  { category: "form/contact", keywords: ["contact", "contact us", "reach out", "get in touch", "enquiry", "inquiry"] },
+  { category: "form/settings", keywords: ["settings", "preferences", "config", "configuration", "account settings", "profile edit"] },
+  { category: "form/checkout", keywords: ["checkout", "check out", "payment", "billing", "purchase"] },
+  // Data categories
+  { category: "data/table", keywords: ["table", "data table", "spreadsheet", "grid view", "list view", "datagrid"] },
+  { category: "data/dashboard", keywords: ["dashboard", "kpi", "metrics", "analytics", "overview", "summary panel", "stats"] },
+  { category: "data/chart", keywords: ["chart", "graph", "visualization", "pie chart", "bar chart", "line chart", "histogram"] },
+  // Layout categories
+  { category: "layout/landing", keywords: ["landing", "landing page", "homepage", "hero", "splash"] },
+  { category: "layout/profile", keywords: ["profile", "user profile", "avatar", "bio", "about me"] },
+  { category: "layout/pricing", keywords: ["pricing", "pricing table", "plans", "subscription", "tier"] },
+  // Navigation categories
+  { category: "nav/sidebar", keywords: ["sidebar", "side nav", "navigation menu", "drawer", "side panel"] },
+  { category: "nav/tabs", keywords: ["tabs", "tab bar", "tabbed", "tab navigation", "tab panel"] },
+  // Agent categories
+  { category: "agent/chat", keywords: ["chat", "chatbot", "messenger", "conversation", "messaging", "chat interface"] },
+  { category: "agent/notification", keywords: ["notification", "alert", "toast", "snackbar", "banner", "announcement"] },
+  // Content categories
+  { category: "content/blog", keywords: ["blog", "article", "post", "news", "editorial", "content feed"] },
+  { category: "content/faq", keywords: ["faq", "frequently asked", "questions", "help center", "knowledge base", "accordion"] },
+  // Commerce categories
+  { category: "commerce/product", keywords: ["product", "product card", "product page", "product detail", "item detail", "catalog"] },
+  { category: "commerce/cart", keywords: ["cart", "shopping cart", "basket", "bag"] },
+  { category: "commerce/order", keywords: ["order", "order history", "order summary", "receipt", "invoice", "order tracking"] },
+  // Workflow categories
+  { category: "workflow/wizard", keywords: ["wizard", "stepper", "multi-step", "step form", "onboard flow", "setup wizard"] },
+  { category: "workflow/kanban", keywords: ["kanban", "board", "task board", "trello", "project board", "drag and drop"] },
+  // Status categories
+  { category: "status/error", keywords: ["error", "error page", "404", "500", "not found", "something went wrong"] },
+  { category: "status/empty", keywords: ["empty state", "no results", "no data", "zero state", "blank slate"] },
+  { category: "status/loading", keywords: ["loading", "skeleton", "spinner", "progress", "placeholder"] }
+];
+function categorizeIntent(intent) {
+  if (!intent || typeof intent !== "string") {
+    return { category: "other", confidence: 0 };
+  }
+  const lower = intent.toLowerCase().trim();
+  let bestCategory = "other";
+  let bestScore = 0;
+  for (const rule of CATEGORY_RULES) {
+    let matchCount = 0;
+    let longestMatch = 0;
+    for (const kw of rule.keywords) {
+      if (lower.includes(kw)) {
+        matchCount++;
+        longestMatch = Math.max(longestMatch, kw.length);
+      }
+    }
+    if (matchCount === 0) continue;
+    const kwLenBonus = longestMatch / lower.length;
+    const multiMatchBonus = Math.min(matchCount * 0.15, 0.3);
+    const score = 0.5 + kwLenBonus * 0.3 + multiMatchBonus;
+    if (score > bestScore) {
+      bestScore = score;
+      bestCategory = rule.category;
+    }
+  }
+  return {
+    category: bestCategory,
+    confidence: Math.min(Math.round(bestScore * 100) / 100, 1)
+  };
+}
+export {
+  categorizeIntent
+};

package/retrieval/intent/intent-gate.js

@@ -0,0 +1,96 @@
+const QUESTION_STARTERS = /^\s*(what|how|why|can you|could you|tell me|explain|describe|help|who|where|when|is there|are there|do you|does|did|will|should|would|which|list|show me how)\b/i;
+const GREETINGS = /^\s*(hi|hey|hello|thanks|thank you|bye|goodbye|ok|okay|sure|great|nice|cool|awesome|good|perfect)\b/i;
+const META_PATTERNS = [
+  /what\s+(components?|types?|elements?)\s+(are|do|can)/i,
+  /available\s+(components?|types?|elements?)/i,
+  /how\s+(does|do)\s+(this|it|the system|gen ui|a2ui)/i,
+  /what\s+can\s+(you|this|it)\s+(do|generate|create|build)/i,
+  /help\s+me\s+understand/i,
+  /list\s+(of\s+)?(components?|types?|elements?)/i,
+  /what\s+(is|are)\s+(a2ui|agentui|agent ui|gen ui)/i,
+  /show\s+me\s+(the\s+)?(components?|options?|catalog)/i,
+  /explain\s+(the|how|what|a)/i,
+  /how\s+(to|do\s+I)\s+(use|create|build|make)/i,
+  /what\s+would\s+.+\s+look\s+like/i,
+  /show\s+me\s+how/i
+];
+const NOISE_PATTERNS = [
+  /^<[^>]+>/,
+  // Starts with HTML tag
+  /^\s*[^\w\s]{3,}/
+  // Starts with 3+ non-word chars
+];
+const VAGUE_PATTERNS = [
+  /^(do|just|go|let'?s|get|keep|stay|stop|try|move|make it|finish|start|begin|end|run)\b.{0,30}$/i,
+  // short imperative without UI nouns
+  /\b(you gotta|gotta do|no excuses|believe|motivat|inspir|goal|dream|life|love|hate|feel|think about)\b/i,
+  /\b(what is preventing|what stops|why can't|why won't)\b/i,
+  // philosophical/motivational questions
+  /\b(do it|get it done|let'?s go|make it happen|just do it|never give up)\b/i
+  // motivational slogans
+];
+const TOOL_USE_PATTERNS = [
+  /\b(create|file|write|open|submit|log)\s+(a\s+)?(ticket|bug|issue|report|feature request)/i,
+  /\b(report|flag)\s+(a\s+)?(bug|issue|problem|error|regression)/i,
+  /\b(why|how come)\s+(does|did|is|was|are)\b/i,
+  // "why does X do Y" — asking for rationale
+  /\bthis\s+(is|looks?)\s+(broken|wrong|buggy|off|weird|strange)/i,
+  /\b(fix|repair|debug|investigate)\s+(this|the|that)/i,
+  /\bsomething\s+(is|seems|looks?)\s+(wrong|broken|off)/i,
+  /\bmark\s+(this|it)\s+as\b/i,
+  /\b(save|bookmark|pin)\s+(this|the)\s+(pattern|output|result)/i
+];
+function isConversational(text, classifyResult) {
+  const trimmed = (text ?? "").trim();
+  let cls = classifyResult && typeof classifyResult === "object" ? classifyResult : { confidence: 0, matchedSignals: [] };
+  if (trimmed.length < 5 && cls.confidence === 0) {
+    return { conversational: true, reason: "short-input" };
+  }
+  for (const pattern of NOISE_PATTERNS) {
+    if (pattern.test(trimmed) && cls.confidence === 0) {
+      return { conversational: true, reason: "noise-input" };
+    }
+  }
+  for (const pattern of META_PATTERNS) {
+    if (pattern.test(trimmed)) {
+      return { conversational: true, reason: "meta-question" };
+    }
+  }
+  for (const pattern of TOOL_USE_PATTERNS) {
+    if (pattern.test(trimmed)) {
+      return { conversational: true, reason: "tool-use" };
+    }
+  }
+  if (cls.confidence < 0.2) {
+    for (const pattern of VAGUE_PATTERNS) {
+      if (pattern.test(trimmed)) {
+        return { conversational: true, reason: "vague-or-abstract" };
+      }
+    }
+  }
+  if (GREETINGS.test(trimmed) && cls.confidence === 0) {
+    return { conversational: true, reason: "greeting" };
+  }
+  if (cls.confidence >= 0.3) {
+    return { conversational: false, reason: "high-domain-confidence" };
+  }
+  if ((cls.matchedSignals?.length ?? 0) >= 2) {
+    return { conversational: false, reason: "multiple-domain-signals" };
+  }
+  if (QUESTION_STARTERS.test(trimmed) && (cls.matchedSignals?.length ?? 0) <= 1) {
+    return { conversational: true, reason: "question-single-signal" };
+  }
+  if (GREETINGS.test(trimmed) && cls.confidence < 0.2) {
+    return { conversational: true, reason: "greeting-low-confidence" };
+  }
+  if (cls.confidence > 0) {
+    return { conversational: false, reason: "has-domain-signal" };
+  }
+  if (trimmed.endsWith("?")) {
+    return { conversational: true, reason: "ends-with-question-mark" };
+  }
+  return { conversational: true, reason: "no-ui-signals" };
+}
+export {
+  isConversational
+};

package/retrieval/intent/prompt-analyzer.js

@@ -0,0 +1,162 @@
+let _vocab = null;
+async function getVocab() {
+  if (_vocab) return _vocab;
+  let catalogJson = {};
+  try {
+    const IS_NODE = typeof process !== "undefined" && process.versions?.node;
+    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/catalog-a2ui_0_9.json"), "utf8");
+      catalogJson = JSON.parse(raw);
+    } else {
+      const resp = await fetch(new URL("../../corpus/catalog-a2ui_0_9.json", import.meta.url));
+      if (resp.ok) catalogJson = await resp.json();
+    }
+  } catch {
+  }
+  const comps = catalogJson?.["components"] ?? {};
+  const displayList = [];
+  const allowedSet = /* @__PURE__ */ new Set();
+  for (const [name, def] of Object.entries(comps)) {
+    allowedSet.add(name);
+    const ext = def?.["x-adiaui"] ?? {};
+    const syns = ext && typeof ext === "object" ? ext["synonyms"] : null;
+    const tags = syns && typeof syns === "object" ? syns["tags"] : null;
+    const aliases = Array.isArray(tags) ? tags.filter((t) => typeof t === "string") : [];
+    for (const a of aliases) allowedSet.add(a);
+    displayList.push(aliases.length ? `${name} (also: ${aliases.join(", ")})` : name);
+  }
+  _vocab = { displayList, allowedSet };
+  return _vocab;
+}
+async function analyzePrompt({ intent, llmAdapter, domain }) {
+  const passthrough = {
+    raw: intent,
+    concepts: [],
+    entities: [],
+    impliedComponents: [],
+    styleHints: [],
+    steelman: intent,
+    analyzed: false
+  };
+  if (!intent || !llmAdapter) return passthrough;
+  const { displayList, allowedSet } = await getVocab();
+  const componentList = displayList.length ? displayList.join(", ") : "Card, Section, Header, Footer, Column, Row, Grid, Button, Input, Text, Image, Badge, Icon, Avatar, Alert, Modal, Tabs, Accordion";
+  const domainHint = domain?.["domain"] && (domain?.["confidence"] ?? 0) > 0 ? `
+Domain classifier suggests: ${domain["domain"]} (confidence ${domain["confidence"]})` : "";
+  const systemPrompt = `You are a UI brief enricher for the AdiaUI design system. Given a terse or under-specified user prompt, you extract structured signals and produce an enriched brief that a downstream UI generator can use to produce a polished, complete UI.
+
+Your output is JSON with this exact shape \u2014 no markdown, no explanation:
+{
+  "concepts": [string],          // 2-5 short concept tags (e.g. "commerce", "authentication", "data-display", "navigation")
+  "entities": [string],          // explicit nouns from the prompt (lowercase, singular)
+  "implied_components": [string],// 4-12 AdiaUI components a good designer would include
+  "style_hints": [string],       // visual/style adjectives ("minimal", "dense", "3D", "playful"), [] if none stated
+  "steelman": string             // 1-2 sentence enriched brief
+}
+
+AdiaUI components you may name in implied_components (use these names exactly): ${componentList}
+
+Rules:
+- Extract entities verbatim from the prompt \u2014 do not invent.
+- implied_components should include both the obvious (Card, Button) AND the ones a thoughtful designer would add (Badge for sale tag on a product, Avatar for a user row, EmptyState for empty data).
+- The steelman expands the prompt into what the user MEANT, not what they SAID. Add the implicit requirements: typical sub-elements, sensible defaults, a header, a footer, common variants. Do NOT add scope the user wouldn't want (e.g. don't turn "login form" into "login form with social auth" unless that's a near-universal expectation).
+- Keep steelman under 250 characters.
+- If the prompt is already well-specified (>15 words, multiple entities), the steelman is mostly a faithful restatement.
+
+Examples:
+Input: "product card"
+Output: {"concepts":["commerce","product-display"],"entities":["product"],"implied_components":["Card","Image","Text","Badge","Button"],"style_hints":[],"steelman":"E-commerce product card with image, title, price, optional sale badge, and primary 'Add to cart' button. Card layout, single product."}
+
+Input: "settings page with toggles for notifications, dark mode, and privacy"
+Output: {"concepts":["settings","preferences"],"entities":["notifications","dark mode","privacy","toggles"],"implied_components":["Card","Header","Section","Toggle","Text","Divider"],"style_hints":[],"steelman":"Settings page with three toggle rows for notifications, dark mode, and privacy. Each row has a label, description, and toggle. Grouped under a header card."}
+
+Input: "make it 3D"
+Output: {"concepts":["style-modifier"],"entities":[],"implied_components":[],"style_hints":["3D","depth","shadow"],"steelman":"Modify the existing canvas to feel three-dimensional \u2014 add elevation, layered shadows, and depth-suggesting transforms. Apply to existing components without changing structure."}`;
+  const userMsg = `Prompt: "${intent}"${domainHint}`;
+  let response;
+  try {
+    response = await llmAdapter.complete({
+      messages: [{ role: "user", content: userMsg }],
+      systemPrompt
+    });
+  } catch {
+    return passthrough;
+  }
+  const text = response?.content;
+  if (!text) return passthrough;
+  if (response.stopReason && response.stopReason !== "end" && response.stopReason !== "end_turn" && response.stopReason !== "stop") {
+    return passthrough;
+  }
+  let parsed = null;
+  try {
+    parsed = JSON.parse(text.trim());
+  } catch {
+  }
+  if (!parsed) {
+    const fence = text.match(/```(?:json)?\s*\n?([\s\S]*?)```/);
+    if (fence) try {
+      parsed = JSON.parse((fence[1] ?? "").trim());
+    } catch {
+    }
+  }
+  if (!parsed) {
+    const start = text.indexOf("{");
+    const end = text.lastIndexOf("}");
+    if (start >= 0 && end > start) {
+      try {
+        parsed = JSON.parse(text.slice(start, end + 1));
+      } catch {
+      }
+    }
+  }
+  if (!parsed || typeof parsed !== "object") return passthrough;
+  const p = parsed;
+  const impliedComponents = Array.isArray(p["implied_components"]) ? p["implied_components"].filter((c) => typeof c === "string" && (allowedSet.size === 0 || allowedSet.has(c))) : [];
+  return {
+    raw: intent,
+    concepts: asStringArray(p["concepts"]).slice(0, 8),
+    entities: asStringArray(p["entities"]).slice(0, 16),
+    impliedComponents: impliedComponents.slice(0, 16),
+    styleHints: asStringArray(p["style_hints"]).slice(0, 8),
+    steelman: typeof p["steelman"] === "string" && p["steelman"].trim() || intent,
+    analyzed: true
+  };
+}
+function asStringArray(v) {
+  if (!Array.isArray(v)) return [];
+  return v.filter((x) => typeof x === "string" && x.trim().length > 0).map((x) => x.trim());
+}
+function formatAnalysisForPrompt(analysis) {
+  if (!analysis || !analysis.analyzed) return "";
+  const parts = [];
+  if (analysis.steelman && analysis.steelman !== analysis.raw) {
+    parts.push(`ENRICHED BRIEF: ${analysis.steelman}`);
+  }
+  if (analysis.impliedComponents?.length) {
+    parts.push(`EXPECTED COMPONENTS: ${analysis.impliedComponents.join(", ")}`);
+  }
+  if (analysis.concepts?.length) {
+    parts.push(`CONCEPTS: ${analysis.concepts.join(", ")}`);
+  }
+  if (analysis.styleHints?.length) {
+    parts.push(`STYLE HINTS: ${analysis.styleHints.join(", ")}`);
+  }
+  return parts.join("\n");
+}
+export {
+  analyzePrompt,
+  formatAnalysisForPrompt
+};

package/retrieval/wiring-catalog.js

@@ -0,0 +1,168 @@
+const adiaEvents = [
+  { event: "press", payload: null, description: "Button or interactive element activated." },
+  { event: "submit", payload: "form-values", description: "Form submission with validated field values." },
+  { event: "input", payload: "target-value", description: "Value changed (fires on every keystroke)." },
+  { event: "change", payload: "event-detail", description: "Value committed (fires on blur or selection)." },
+  { event: "select", payload: "event-detail", description: "Item selected from list, table, or menu." },
+  { event: "toggle", payload: "boolean", description: "Boolean state flipped (switch, checkbox)." },
+  { event: "dismiss", payload: null, description: "Close/dismiss (dialog, toast, popover)." },
+  { event: "navigate", payload: "route", description: "Internal navigation request." },
+  { event: "mount", payload: null, description: "Surface or component entered the DOM." },
+  { event: "unmount", payload: null, description: "Surface or component left the DOM." },
+  { event: "focus", payload: null, description: "Element received focus." },
+  { event: "blur", payload: null, description: "Element lost focus." },
+  { event: "drag", payload: "event-detail", description: "Drag operation on a sortable/draggable." },
+  { event: "drop", payload: "event-detail", description: "Drop completed on a sortable/draggable." }
+];
+function getWiringCatalog() {
+  return {
+    // ── ADIA EVENTS ──
+    adiaEvents,
+    // ── DATA: how the surface gets its data ──
+    data: {
+      description: "Fetch external data into the surface model. Sources are URI-based with refresh strategies.",
+      paramSources: ["route", "store", "literal", "query", "parent"],
+      uriSchemes: ["resource://", "api://", "mock://", "ws://", "sse://"],
+      refreshStrategies: ["once", "on-focus", "interval:{ms}", "stream"],
+      example: {
+        params: { userId: { from: "route", key: "id" } },
+        sources: [
+          { id: "user", uri: "resource://users/{userId}", path: "/user", refresh: "once" },
+          { id: "activity", uri: "resource://users/{userId}/activity", path: "/activity", refresh: "on-focus" }
+        ]
+      }
+    },
+    // ── STATE: controllers that manage component behavior ──
+    controllers: [
+      {
+        type: "FormController",
+        description: "Manages field values, validation, dirty/pristine tracking. Attach to a Column/Section containing form fields.",
+        config: {
+          validateOn: { type: "string", enum: ["blur", "change", "submit"], default: "blur" }
+        },
+        commands: ["validate", "reset", "setFieldError"],
+        bind: { values: "/form/values", valid: "/form/valid", dirty: "/form/dirty" }
+      },
+      {
+        type: "DataStreamController",
+        description: "Live data buffer for charts, tables, feeds. Supports push, SSE, WebSocket, polling.",
+        config: {
+          max: { type: "number", default: 100, description: "FIFO buffer size" },
+          throttle: { type: "number", default: 0, description: "Min ms between renders" }
+        },
+        commands: ["push", "pushMany", "connect", "poll", "consume", "stop", "clear"],
+        bind: { data: "/stream/data", status: "/stream/status" }
+      },
+      {
+        type: "SelectionController",
+        description: "Single or multi-select state for lists, tables, grids.",
+        config: { mode: { type: "string", enum: ["single", "multi"], default: "single" } },
+        commands: ["select", "deselect", "toggle", "selectAll", "clear"],
+        bind: { selected: "/selection/items", count: "/selection/count" }
+      },
+      {
+        type: "ToggleController",
+        description: "Boolean on/off state with attribute reflection.",
+        config: {},
+        commands: ["toggle", "set"],
+        bind: { value: "/toggle/on" }
+      },
+      {
+        type: "AccordionController",
+        description: "Panel expand/collapse with mutual exclusion.",
+        config: { multiple: { type: "boolean", default: false } },
+        commands: ["open", "close", "toggle"],
+        bind: { openPanels: "/accordion/open" }
+      },
+      // ADR-0048 P4: this entry was MISSING. The runtime has resolved
+      // StateMachineController since it was registered, but this hand-written
+      // list never gained a row, so every generation reading the wiring
+      // catalog was told a controller it could legally emit did not exist.
+      // Found by diffing this list against `@adia-ai/a2ui`'s live
+      // wiringRegistry (6 controllers vs the 5 listed here) while building the
+      // protocol MCP's registry-derived get_wiring_catalog.
+      //
+      // Fields below mirror `packages/a2ui/controllers/state-machine.js`'s
+      // `static schema` — `commands` and `config` verbatim, `bind` keyed on
+      // its two state keys (`current`, `history`) with example model paths in
+      // the same shape as its siblings above. If a controller is added to the
+      // registry again, this list is what goes stale: check it against
+      // wiringRegistry.controllers, not against memory.
+      {
+        type: "StateMachineController",
+        description: "Named finite-state machine for multi-step flows (wizards, checkout, approval states). Transitions on events; reflects the active state to data-state on the host for CSS targeting.",
+        config: {
+          initial: { type: "string", description: "Starting state name (defaults to the first key of `states`)" },
+          states: { type: "object", description: "State graph: { [name]: { on: { [event]: targetState } } }" }
+        },
+        commands: ["send", "transition", "reset"],
+        bind: { current: "/flow/state", history: "/flow/history" }
+      }
+    ],
+    // ── ACTIONS: event → handler chains ──
+    handlers: [
+      { name: "submit-resource", description: "POST/PUT/PATCH/DELETE to a resource URI.", config: ["uri", "method", "body"] },
+      { name: "update-model", description: "Update the surface data model at a path.", config: ["path", "value"] },
+      { name: "navigate", description: "Route to a path (supports {param} templates).", config: ["navigate"] },
+      { name: "navigate-back", description: "Go back in browser history.", config: [] },
+      { name: "controller-command", description: "Invoke a command on a controller.", config: ["controllerId", "command", "args"] },
+      { name: "emit-event", description: "Dispatch a named CustomEvent on the surface.", config: ["eventName", "detail"] },
+      { name: "refresh-source", description: "Re-fetch a named data source.", config: ["sourceId"] },
+      { name: "notify", description: "Show a toast/alert notification.", config: ["message", "variant"] }
+    ],
+    // ── ACTION SHAPE (UIEvent → handler) ──
+    actionShape: {
+      event: "UIEvent object: { event, target?, debounce?, throttle?, condition? }",
+      handler: "Handler name from the handlers list.",
+      config: "Handler-specific configuration object.",
+      onSuccess: "Follow-up actions array (each is { handler, config }).",
+      onError: "Follow-up actions array on failure."
+    },
+    // ── PROVIDES: context injection ──
+    provides: {
+      description: "Inject shared state into a component subtree via a2ui-provider. Children consume via context name.",
+      example: { name: "auth", host: "root", value: { user: null, token: null } }
+    },
+    // ── LIFECYCLE hooks ──
+    lifecycle: {
+      onMount: "Actions to run when the surface first renders (fetch initial data, start streams).",
+      onUnmount: "Cleanup actions when the surface is destroyed (close WebSocket, stop polling).",
+      onModelChange: "Watch a model path and fire actions when it changes (debounce supported)."
+    },
+    // ── VALUE EXTRACTION (how actions read data) ──
+    valueSources: [
+      { from: "event-detail", description: "Read from event.detail (key = property)" },
+      { from: "event-target", description: "Read from event.target (key = property, e.g., value)" },
+      { from: "model", description: "Read from data model (path = JSON Pointer)" },
+      { from: "literal", description: "Static value (value = the value)" },
+      { from: "param", description: "Read from resolved parameters (key = param name)" },
+      { from: "controller", description: "Read from a controller state (controllerId + key)" }
+    ],
+    // ── MULTI-SURFACE ASSOCIATIONS ──
+    associations: [
+      { name: "routes-to", description: "Navigation \u2014 source links to target." },
+      { name: "feeds", description: "Data flow \u2014 source output \u2192 target input." },
+      { name: "shares-context", description: "Shared state \u2014 both read/write same context." },
+      { name: "depends-on", description: "Lifecycle \u2014 source waits for target." },
+      { name: "triggers", description: "Side effect \u2014 source event \u2192 target update." },
+      { name: "contains", description: "Composition \u2014 target renders inside source." }
+    ]
+  };
+}
+function getAdiaEvent(type) {
+  return adiaEvents.find((e) => e.event === type) ?? void 0;
+}
+function getControllerInfo(type) {
+  const catalog = getWiringCatalog();
+  return catalog["controllers"].find((c) => c.type === type) ?? void 0;
+}
+function getHandlerInfo(name) {
+  const catalog = getWiringCatalog();
+  return catalog["handlers"].find((h) => h.name === name) ?? void 0;
+}
+export {
+  getAdiaEvent,
+  getControllerInfo,
+  getHandlerInfo,
+  getWiringCatalog
+};