@adia-ai/a2ui-compose 0.0.1

package/engines/monolithic/_shared.js

@@ -0,0 +1,1320 @@
+/**
+ * @adia-ai/a2ui-compose — monolithic engine, shared helpers.
+ *
+ * Pure helpers extracted from engine/generator.js per spec §11 Phase 2:
+ * prompt builders, JSON parsers, canvas diff utilities, suggestion
+ * generators. All stateless (the only module-level state is the lazy
+ * component-catalog cache inside getComponentCatalog).
+ */
+
+import { listPatterns } from '../../engine/reference.js';
+import { store } from '../../engine/state.js';
+import { checkIntentAlignment } from '../../../retrieval/intent-alignment.js';
+import { composeSubtasks } from '../../../retrieval/decomposer.js';
+import { getWiringCatalog } from '../../../retrieval/wiring-catalog.js';
+import { getComponentData } from '../../../retrieval/pattern-library.js';
+
+// Component prop catalog — loaded lazily for prompt injection
+let _componentCatalog = null;
+async function getComponentCatalog() {
+  if (_componentCatalog) return _componentCatalog;
+  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/patterns/_components.json'), 'utf8');
+      _componentCatalog = JSON.parse(raw);
+    } else {
+      // Browser: use fetch (works in all Vite modes)
+      const resp = await fetch(new URL('../../../corpus/patterns/_components.json', import.meta.url));
+      if (resp.ok) _componentCatalog = await resp.json();
+      else _componentCatalog = {};
+    }
+  } catch {
+    _componentCatalog = {};
+  }
+  return _componentCatalog;
+}
+
+export async function buildSystemPrompt(context, patterns, researchContext = '', intent = '', composition = null) {
+  const parts = [];
+
+  // ── Role + output format ──
+  parts.push(`You are an A2UI component generator for the AdiaUI design system.
+Output ONLY a valid JSON array of A2UI messages. No markdown fences, no explanation.
+
+Output format: [{ "type": "updateComponents", "surfaceId": "default", "components": [...] }]
+
+Each component: { "id": "<unique>", "component": "<Type>", "children": ["<childId>", ...], ...props }
+The root must have id "root". Use short, descriptive IDs (e.g., "hdr", "email-field", "submit-btn").`);
+
+  // ── Card-N content model (critical for quality) ──
+  parts.push(`CARD-N CONTENT MODEL (mandatory for any card surface):
+- Card > Header: for title/description. Use Text children with heading variants (h3, h4).
+  Card header uses a grid with slots: slot="icon" (leading icon), slot="heading" (title), slot="description" (subtitle), slot="action" (badge/button).
+  Card CSS auto-targets native h1-h6 and small/p for heading/description roles.
+- Card > Section: for body content. Always wrap section children in a Column component.
+  Section > Column > [content children]
+- Card > Footer: for action buttons. Buttons go here, not in Section.
+
+LAYOUT PRIMITIVES:
+- Column (col-ui): vertical stack. Use numeric gap: gap="2", gap="4", gap="6".
+- Row (row-ui): horizontal. Use gap="2", justify="space-between"|"end"|"center".
+- Grid (grid-ui): CSS grid. Use columns="2"|"3"|"4", gap="4".
+
+TEXT TYPES (component="Text"):
+- variant="h1" through "h6" for headings (renders native heading tags)
+- variant="body" for paragraphs
+- for small text
+- Use textContent prop for the display text
+
+TABS (component="Tabs"):
+- Tabs is a tab BUTTON STRIP only — it holds Tab children, NOT content panels.
+- Tab children have text and value props. They are buttons, not containers.
+- Content panels are SIBLINGS of Tabs, not children. Show/hide based on active tab.
+- WRONG: Tabs > Tab > Card (puts content inside tab buttons)
+- CORRECT: Column > [Tabs, Card, Card, Card] (tabs and panels are siblings)
+
+GLOBAL ATTRIBUTES (work on any element — span, p, h1-h6, div, and all *-n components):
+- variant="heading|title|section|label|caption|body|kicker|deck|display|metric|code" — sets typography role
+- weight="thin|light|normal|medium|semibold|bold" — overrides font weight
+- color="text|text-strong|subtle|muted|accent|success|warning|danger|info" — sets text color
+- nomargin — removes block margins
+- truncate — single-line ellipsis
+- grow — flex: 1 (fills remaining space in row/col)
+
+PREFER <span> WITH GLOBAL ATTRIBUTES for styled text:
+- CORRECT: { component: "Text", variant: "label", color: "muted", slot: "description", textContent: "Subtitle" }
+- WRONG: wrapping in unnecessary component wrappers
+The renderer maps Text components to <span> elements. Global attributes (variant, weight, color) are set as HTML attributes on the span. This is lighter than using dedicated text components.
+
+KEY RULES:
+- IMPORTANT: Generate comprehensive, production-quality UIs. A login form should have 10+ components. A dashboard should have 20+ components. Never return a minimal stub — include all the fields, labels, buttons, and chrome that a real UI would have.
+- Never use raw HTML tags (div, form, input, span). Only A2UI component types.
+- Use Input for text inputs (not "TextField" or "TextInput").
+- Use CheckBox for checkboxes. Use Switch/Toggle for on/off toggles.
+- Use Select for dropdowns (not "ChoicePicker").
+- Use Stat for KPI/metric cards: { component: "Stat", label: "Revenue", value: "$48.2k", change: "+12%", trend: "up" }. Do NOT manually build stat cards with Header+Section+Text — use the Stat component directly.
+- Use Table for tabular data (set data/columns via JS props, not Text children).
+- Use EmptyState for no-content/error states (icon, heading, description, action slot).
+- Use Skeleton for loading placeholders (variant: text|circle|rect).
+- Button: use variant="primary" for main action, "outline" for secondary, "ghost" for tertiary.
+- Button: use text prop for button label.
+- NEVER use Text for clickable/interactive actions. "View logs", "Contact support", "Learn more" = Button (variant="ghost" or "link"), NOT Text. Text is for static content only.
+- For error/status dialogs: use Alert for the error message, Button for recovery actions (retry, view logs, contact support). Don't render action labels as Text captions.
+- For forms: wrap fields in Column with gap="3". Put submit button in a separate Row or Footer.
+- Tab children must ONLY be Tab components. Never put Card, Column, or any content inside Tab.
+- Every Header child MUST have a slot: slot="heading" for title, slot="description" for subtitle, slot="action" for badges/buttons, slot="icon" for leading icons.`);
+
+  // ── Component prop catalog (ground truth from _components.json) ──
+  const catalog = await getComponentCatalog();
+  if (catalog && Object.keys(catalog).length > 0) {
+    // Pick components most relevant to the intent — show top 20 most used
+    const relevantTypes = new Set();
+    // Always include core types
+    for (const t of ['Column', 'Row', 'Grid', 'Card', 'Header', 'Section', 'Footer',
+      'Text', 'Button', 'Input', 'Badge', 'Icon', 'Avatar', 'Image', 'Divider']) {
+      relevantTypes.add(t);
+    }
+    // Add types from matched patterns
+    for (const p of patterns) {
+      for (const c of (p.components || [])) relevantTypes.add(c);
+    }
+
+    const catalogLines = [];
+    // Aliases live on the canonical catalog entry; surface them inline so the
+    // LLM knows it can write "Carousel" / "Slideshow" and the runtime registry
+    // will map to the right tag (verified 2026-04-19 — without this, the LLM
+    // emits Carousel only to have it ignored, swap-fallback breaks).
+    const aliasSuffix = (typeName) => {
+      const a = catalog[typeName]?.aliases;
+      return Array.isArray(a) && a.length ? `  (also: ${a.join(', ')})` : '';
+    };
+    for (const typeName of relevantTypes) {
+      // Prefer .a2ui.json data (new source of truth), fallback to _components.json
+      const a2uiData = getComponentData(typeName);
+      if (a2uiData) {
+        const props = a2uiData.props ? Object.entries(a2uiData.props).map(([k, v]) => {
+          let desc = k;
+          if (v.enum) desc += `=(${v.enum.join('|')})`;
+          else if (v.type) desc += `:${v.type}`;
+          if (v.default !== undefined) desc += `[${v.default}]`;
+          return desc;
+        }).join(', ') : '';
+        const events = a2uiData.events?.length ? ` events: ${a2uiData.events.join(', ')}` : '';
+        catalogLines.push(`- ${typeName}${aliasSuffix(typeName)}: ${a2uiData.description || ''}  props: ${props || 'none'}${events}`);
+        // Include a brief example snippet if the component is relevant. Pick
+        // the example whose NAME best matches words in the intent (so a chart
+        // prompt gets the chart-legend example, not the first one in the
+        // array). Falls back to examples[0] when no name overlap.
+        if (a2uiData.examples?.length > 0 && intent) {
+          const intentLower = intent.toLowerCase();
+          const keywords = a2uiData.keywords || [];
+          const isRelevant = keywords.some(kw => intentLower.includes(kw)) ||
+            intentLower.includes(typeName.toLowerCase());
+          if (isRelevant) {
+            const intentTokens = new Set(intentLower.split(/\W+/).filter(w => w.length > 2));
+            let bestExample = a2uiData.examples[0];
+            let bestScore = 0;
+            for (const ex of a2uiData.examples) {
+              const nameTokens = String(ex.name || '').toLowerCase().split(/[\s_-]+/);
+              const score = nameTokens.filter(t => intentTokens.has(t)).length;
+              if (score > bestScore) { bestScore = score; bestExample = ex; }
+            }
+            if (bestExample?.template) {
+              const exSnippet = JSON.stringify(bestExample.template.slice(0, 6));
+              catalogLines.push(`  example (${bestExample.name || 'default'}): ${exSnippet}`);
+              if (bestExample.description) catalogLines.push(`  guidance: ${bestExample.description}`);
+            }
+          }
+        }
+      } else {
+        const comp = catalog[typeName];
+        if (!comp) continue;
+        const props = comp.props ? Object.entries(comp.props).map(([k, v]) => {
+          let desc = k;
+          if (v.enum) desc += `=(${v.enum.join('|')})`;
+          else if (v.type) desc += `:${v.type}`;
+          if (v.default !== undefined) desc += `[${v.default}]`;
+          return desc;
+        }).join(', ') : '';
+        const events = comp.events?.length ? ` events: ${comp.events.join(', ')}` : '';
+        catalogLines.push(`- ${typeName}${aliasSuffix(typeName)}: ${comp.description || ''}  props: ${props || 'none'}${events}`);
+      }
+    }
+    parts.push(`COMPONENT CATALOG (typed props — use these, not guesses):\n${catalogLines.join('\n')}`);
+  } else if (context.components.length > 0) {
+    // Fallback to old-style catalog if _components.json not available
+    const oldCatalog = context.components.map(c => {
+      let props = '';
+      if (Array.isArray(c.properties)) {
+        props = c.properties.map(p => {
+          if (typeof p === 'string') return p;
+          if (p && typeof p === 'object') return p.name || p.attribute || JSON.stringify(p);
+          return String(p);
+        }).join(', ');
+      }
+      return `- ${c.type}: ${props || '(no props)'}`;
+    }).join('\n');
+    parts.push(`AVAILABLE COMPONENTS:\n${oldCatalog}`);
+  }
+
+  // ── Anti-patterns ──
+  if (context.antiPatterns?.length > 0) {
+    const rules = context.antiPatterns.map(ap => `- ${ap.description}`).join('\n');
+    parts.push(`AVOID:\n${rules}`);
+  }
+
+  // ── Matched pattern (use as base, adapt content) ──
+  if (patterns.length > 0 && patterns[0].template) {
+    const best = patterns[0];
+    const full = JSON.stringify(best.template, null, 1);
+    parts.push(`MATCHED PATTERN: "${best.name}"
+USE THIS AS YOUR BASE STRUCTURE. Adapt the text content and values to match the user's intent, but KEEP the structural patterns:
+- Keep the same component hierarchy and nesting
+- Keep slot attributes (slot="heading", slot="action", slot="description", slot="icon")
+- Keep variant attributes on cards and buttons
+- Adjust textContent, labels, and counts to match the user's request
+
+Template:
+${full}`);
+  } else if (patterns.length > 0) {
+    // No exact match — show top 3 partial matches so the LLM can compose from parts
+    const partials = patterns.slice(0, 3);
+    const partialList = partials.map(p => {
+      const comps = p.components?.join(', ') || '';
+      return `- "${p.name}" (${p.domain}): ${p.description}. Components: [${comps}]`;
+    }).join('\n');
+    parts.push(`NO EXACT PATTERN MATCH. Here are the closest patterns for reference:
+${partialList}
+
+COMPOSE from scratch using the AVAILABLE COMPONENTS list above. Follow these composition rules:
+1. Start with a Card as the root container (or Column/Grid for multi-card layouts)
+2. Card anatomy: Header (slot="heading" + slot="description") → Section > Column → content → Footer (actions)
+3. Pick the most specific component for each UI element — don't default to Card+Text for everything
+4. Use the component catalog to find the right type: Table for data, Timeline for sequences, Accordion for collapsible sections, etc.
+5. Every Header child MUST have a slot attribute: slot="heading", slot="description", slot="action", or slot="icon"
+6. Use Grid for equal-width columns, Row for content-sized horizontal layouts, Column for vertical stacks`);
+  } else {
+    parts.push(`NO MATCHING PATTERNS. Generate from scratch using the AVAILABLE COMPONENTS list and CARD-N CONTENT MODEL rules above.
+Compose the UI by picking the most specific component types available — don't just use Card+Text for everything.`);
+  }
+
+  // ── Diverse pattern examples (always included when no exact match) ──
+  // Give the LLM structural examples even when keyword search returned nothing.
+  // This is the single biggest quality improvement for unmapped intents.
+  if (!patterns.length || !patterns[0]?.template) {
+    const allPatterns = listPatterns().filter(p => p.template && Array.isArray(p.template) && p.template.length >= 3);
+    if (allPatterns.length > 0) {
+      // Pick up to 3 diverse examples from different domains
+      const seen = new Set();
+      const diverse = [];
+      for (const p of allPatterns) {
+        const d = p.domain || 'general';
+        if (!seen.has(d) && diverse.length < 3) {
+          seen.add(d);
+          diverse.push(p);
+        }
+      }
+      // If we didn't get 3 from unique domains, fill from remaining
+      if (diverse.length < 3) {
+        for (const p of allPatterns) {
+          if (!diverse.includes(p) && diverse.length < 3) diverse.push(p);
+        }
+      }
+      const examples = diverse.map(p => {
+        const compact = JSON.stringify(p.template).slice(0, 500);
+        return `"${p.name}" (${p.domain || 'general'}): ${compact}${p.template.length > 500 ? '...' : ''}`;
+      }).join('\n\n');
+      parts.push(`REFERENCE EXAMPLES — diverse patterns from the library to show structural conventions:\n${examples}\n\nUse these as structural guidance, NOT to copy directly. Adapt to the user's intent.`);
+    }
+  }
+
+  // ── HTML exemplar (golden output showing AdiaUI markup conventions) ──
+  parts.push(`GOLDEN HTML OUTPUT EXAMPLE — this is what correctly rendered AdiaUI markup looks like:
+
+<section prose>
+  <col-ui gap="12">
+    <header align="center" size="lg">
+      <col-ui gap="4">
+        <span variant="kicker">Category</span>
+        <h1 variant="display" nomargin>Page Title</h1>
+        <p variant="deck" nomargin>Subtitle description text.</p>
+      </col-ui>
+    </header>
+    <grid-ui columns="3">
+      <card-ui>
+        <header>
+          <icon-ui name="lightning" slot="icon" color="accent"></icon-ui>
+          <h3 slot="heading" variant="section" nomargin>Card Title</h3>
+          <p slot="description" color="subtle" nomargin>Card subtitle</p>
+        </header>
+        <section>
+          <col-ui gap="2">
+            <p variant="body" color="subtle" nomargin>Body text content.</p>
+          </col-ui>
+        </section>
+        <footer>
+          <button-ui text="Action" variant="primary" stretch></button-ui>
+        </footer>
+      </card-ui>
+    </grid-ui>
+  </col-ui>
+</section>
+
+KEY CONVENTIONS from this example:
+- Section content wrapped in col-ui (never bare text in section)
+- Header uses slot="icon", slot="heading", slot="description", slot="action"
+- Typography via variant attribute on semantic elements (h1, h3, p, span)
+- color="subtle" and color="muted" for secondary text
+- nomargin on all typography inside cards
+- Numeric gap values (gap="2", gap="4", gap="12")
+- icon-ui uses Phosphor names with color attribute
+Your A2UI JSON output should produce HTML that follows these conventions.`);
+
+  // ── Styling & theming guidance ──
+  parts.push(`STYLING & THEMING:
+You control visual appearance through component attributes and token overrides — NEVER generate raw CSS.
+
+APPEARANCE ATTRIBUTES (set directly on component props):
+- variant: "primary|outline|ghost|danger|link" (buttons), "success|warning|danger|info|accent" (badges/alerts)
+- size: "sm|md|lg" — shifts component sizing + all typography
+- color: "text|text-strong|subtle|muted|accent|success|warning|danger|info" — text/icon color
+- weight: "thin|light|normal|medium|semibold|bold" — font weight
+- density: "compact|spacious" — tightens or loosens spacing on a container
+- radius: "sharp|rounded|round" — border radius presets on a container
+- align: "left|center|right" — text/content alignment
+
+THEMING (apply to any container to theme its entire subtree):
+- { component: "Column", "data-theme": "ocean" } — named theme (ocean, forest, sunset, lavender, rose, slate, midnight)
+- Or use the theme-ui provider: { component: "Theme", preset: "ocean", children: [...] }
+
+TOKEN OVERRIDES (use style prop for precise control — sparingly):
+- { component: "Card", style: "--card-bg: var(--a-accent-muted)" } — override card background
+- { component: "Button", style: "--button-radius: 999px" } — pill-shaped button
+- The renderer sets el.style.cssText for the style prop.
+- Prefer semantic attributes (variant, size, color) over style overrides.
+
+LAYOUT ATTRIBUTES:
+- gap: "1" through "16" — spacing between children (numeric, maps to --a-space-*)
+- columns: "2|3|4|5|6" — grid column count
+- grow: true — flex: 1 (fill available space)
+- block: true — full-width (buttons, inputs)
+- prose: true — content-optimized spacing and typography
+- nomargin: true — remove default margins on typography elements`);
+
+  // ── Composition rules (when composing from fragment patterns) ──
+  if (composition?.fragmentPatterns?.length >= 2) {
+    const { fragmentPatterns, decomposition } = composition;
+    const layoutComponent = decomposition?.layout?.component || 'Column';
+    const layoutChild = decomposition?.layout?.child || 'Card';
+    parts.push(`COMPOSITION RULES (multi-section intent detected):
+You are composing ${fragmentPatterns.length} independent sections into a single cohesive UI.
+
+LAYOUT: Use ${layoutComponent} as the root container${layoutComponent === 'Tabs' ? ' — Tab buttons are siblings of content panels, NOT parents' : ''}.
+Each section becomes a ${layoutChild} child of the root.
+
+COMPOSITION PRINCIPLES:
+1. UNIQUE IDS: Prefix component IDs per section to avoid collisions (e.g., stats-root, table-hdr, form-submit)
+2. COHESION: Add a page-level Header above all sections with the overall title
+3. VISUAL HIERARCHY: Each section should be wrapped in a Card for visual separation (unless using Tabs)
+4. CONSISTENCY: Use the same sizing, spacing tokens, and theme across all sections
+5. CROSS-SECTION WIRING: If sections share data (e.g., stats + table both show user data), use shared data sources
+
+SECTIONS TO COMPOSE:
+${fragmentPatterns.map((f, i) => `${i + 1}. ${f.label} — based on "${f.pattern.name}" pattern (${f.pattern.components?.join(', ') || 'various components'})`).join('\n')}`);
+  }
+
+  // ── Web research context (if available) ──
+  if (researchContext) {
+    parts.push(`DESIGN RESEARCH:\n${researchContext}\nUse these insights to inform your component choices, layout, and content — but output must still be valid A2UI.`);
+  }
+
+  // ── Wiring capabilities — interactive behavior via wireComponents message ──
+  // Include when the intent suggests any interactivity, data binding, or user actions
+  const wiringKeywords = /\b(form|submit|save|data|api|fetch|navigate|login|checkout|filter|sort|crud|search|delete|edit|update|toggle|select|drag|drop|realtime|stream|websocket|poll|refresh|validate|upload|download|subscribe|notify|toast|modal|dialog|confirm|paginate|infinite.?scroll|load.?more)\b/i;
+  if (wiringKeywords.test(intent || '')) {
+    const wc = getWiringCatalog();
+    parts.push(`WIRING — Declarative Interactivity (5 docking points):
+When the UI needs behavior beyond display, emit a wireComponents message. Each layer is optional — use only what the intent requires.
+
+┌─────────────────────────────────────────────────────────────────┐
+│  DATA      — where the surface gets its data                    │
+│  STATE     — controllers that manage component behavior         │
+│  ACTIONS   — trigger → handler chains (what happens on events)  │
+│  PROVIDES  — context injection into subtrees                    │
+│  LIFECYCLE — onMount, onUnmount, onModelChange hooks            │
+└─────────────────────────────────────────────────────────────────┘
+
+DATA LAYER:
+  "data": {
+    "params": { "userId": { "from": "route", "key": "id" } },
+    "sources": [
+      { "id": "users", "uri": "resource://users", "path": "/users", "refresh": "once" },
+      { "id": "feed", "uri": "sse://events/{userId}", "path": "/feed", "refresh": "stream" }
+    ]
+  }
+  URI schemes: resource://, api://, mock://, ws://, sse://
+  Refresh: once, on-focus, interval:{ms}, stream
+  To re-fetch after an action, use refresh-source in onSuccess — not a refresh strategy.
+
+STATE LAYER:
+  "state": {
+    "controllers": [
+      { "id": "form1", "type": "FormController", "host": "form-col", "config": { "validateOn": "submit" },
+        "bind": { "values": "/form/values", "valid": "/form/valid" } }
+    ],
+    "model": { "filter": "", "page": 1 }
+  }
+  Controllers: ${wc.controllers.map(c => c.type).join(', ')} (extensible via registerController)
+  "bind" maps controller state ↔ model paths for two-way sync.
+
+ACTIONS LAYER — AdiaEvent → handler chains:
+  Each action binds a AdiaEvent to a handler. The event is a typed object, not a string.
+
+  AdiaEvent types: ${wc.adiaEvents.map(e => e.event).join(', ')}
+  Each carries a typed payload:
+${wc.adiaEvents.filter(e => e.payload).map(e => `    ${e.event} → ${e.payload}`).join('\n')}
+
+  "actions": [
+    {
+      "event": { "event": "submit", "target": "save-btn" },
+      "handler": "submit-resource",
+      "config": { "uri": "api://users", "method": "POST" },
+      "onSuccess": [{ "handler": "notify", "config": { "message": "Saved!", "variant": "success" } }],
+      "onError":   [{ "handler": "notify", "config": { "message": "Failed", "variant": "error" } }]
+    },
+    {
+      "event": { "event": "input", "target": "search-input", "debounce": 300 },
+      "handler": "update-model",
+      "config": { "path": "/filter" }
+    }
+  ]
+
+  AdiaEvent shape: { "event": "<type>", "target": "<componentId>", "debounce"?: ms, "throttle"?: ms, "condition"?: { "path", "equals"|"notEquals"|"exists" } }
+  "target" scopes to a component id. Omit for surface-level events (mount, unmount).
+  "onSuccess" / "onError" are follow-up action arrays — NOT separate entries.
+  Handlers: ${wc.handlers.map(h => h.name).join(', ')} (extensible via registerHandler)
+
+LIFECYCLE LAYER:
+  "lifecycle": {
+    "onMount": [{ "handler": "refresh-source", "config": { "sourceId": "users" } }],
+    "onModelChange": [{ "path": "/filter", "handler": "refresh-source", "config": { "sourceId": "search" }, "debounce": 300 }]
+  }
+
+FULL EXAMPLE — Dashboard with data fetch + search + pagination:
+[
+  { "type": "updateComponents", "surfaceId": "default", "components": [
+    { "id": "root", "component": "Column", "gap": "4", "children": ["toolbar", "table-card"] },
+    { "id": "toolbar", "component": "Row", "gap": "2", "children": ["search", "refresh-btn"] },
+    { "id": "search", "component": "Input", "type": "search", "placeholder": "Search...", "name": "q", "grow": true },
+    { "id": "refresh-btn", "component": "Button", "icon": "arrows-clockwise", "variant": "ghost" },
+    { "id": "table-card", "component": "Card", "children": ["table-sec", "table-ftr"] },
+    { "id": "table-sec", "component": "Section", "children": ["tbl"] },
+    { "id": "tbl", "component": "Table", "sortable": true },
+    { "id": "table-ftr", "component": "Footer", "children": ["pager"] },
+    { "id": "pager", "component": "Pagination", "total": 100, "pageSize": 10 }
+  ]},
+  { "type": "wireComponents", "surfaceId": "default",
+    "data": {
+      "sources": [
+        { "id": "items", "uri": "resource://items?q={filter}&page={page}", "path": "/items", "refresh": "once" }
+      ]
+    },
+    "state": {
+      "controllers": [
+        { "id": "tbl-ctrl", "type": "SelectionController", "host": "tbl", "config": { "mode": "multi" },
+          "bind": { "selected": "/selection" } }
+      ],
+      "model": { "filter": "", "page": 1 }
+    },
+    "actions": [
+      { "event": { "event": "input", "target": "search", "debounce": 300 },
+        "handler": "update-model", "config": { "path": "/filter", "value": { "from": "event-target", "key": "value" } } },
+      { "event": { "event": "press", "target": "refresh-btn" },
+        "handler": "refresh-source", "config": { "sourceId": "items" } },
+      { "event": { "event": "change", "target": "pager" },
+        "handler": "update-model", "config": { "path": "/page", "value": { "from": "event-detail", "key": "page" } } }
+    ],
+    "lifecycle": {
+      "onMount": [{ "handler": "refresh-source", "config": { "sourceId": "items" } }],
+      "onModelChange": [{ "path": "/filter", "handler": "refresh-source", "config": { "sourceId": "items" }, "debounce": 500 }]
+    }
+  }
+]
+
+WHEN TO INCLUDE wireComponents:
+- Forms → FormController + submit-resource + navigate/notify
+- Tables with data → DataStreamController or data sources + SelectionController
+- Search/filter → update-model with debounce + refresh-source
+- CRUD → submit-resource (POST/PUT/DELETE) + success/error notify
+- Real-time → data source with refresh:"stream" or "interval:{ms}"
+- Toggles/accordions → ToggleController or AccordionController
+- Navigation → navigate handler
+
+DO NOT include wireComponents for purely static/display UIs (stat cards, hero sections, profiles without edit).`);
+  }
+
+  return parts.join('\n\n');
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// MULTI-TURN (Feature 3: conversation history as context)
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Build chat messages for the LLM, including previous turn context for
+ * multi-turn iteration. If this is the first turn, just the user intent.
+ * If iterating, includes the previous A2UI output as assistant context.
+ *
+ * @param {string} intent — Current user intent
+ * @param {string} executionId — Execution ID (may have previous turns)
+ * @returns {{ role: string, content: string }[]}
+ */
+export function buildChatMessages(intent, executionId) {
+  const messages = [];
+  const prevTurns = store.getAll(executionId);
+
+  if (prevTurns && prevTurns.length > 0) {
+    // Include up to last 2 turns as context
+    const recentTurns = prevTurns.slice(-2);
+    for (const turn of recentTurns) {
+      // Previous user intent
+      if (turn.summary) {
+        messages.push({ role: 'user', content: turn.summary });
+      }
+      // Previous A2UI output (compact — just component tree, no full message wrapper)
+      if (turn.messages?.length > 0) {
+        const components = turn.messages.flatMap(m => m.components || []);
+        const compact = components.map(c => {
+          const { _surfaceId, ...rest } = c;
+          return rest;
+        });
+        messages.push({
+          role: 'assistant',
+          content: JSON.stringify(compact),
+        });
+      }
+    }
+  }
+
+  // Current turn
+  messages.push({ role: 'user', content: intent });
+
+  return messages;
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// STREAMING HELPERS (Feature 1)
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Try to parse a partial LLM text buffer as A2UI JSON.
+ * Handles incomplete JSON by attempting to close open brackets/braces.
+ * Returns null if not parseable yet.
+ *
+ * @param {string} text — Accumulated LLM output so far
+ * @returns {object[]|null}
+ */
+export function tryParsePartial(text) {
+  if (!text) return null;
+
+  // Strip markdown fences if present
+  let json = text.trim();
+  const fenceMatch = json.match(/```(?:json)?\s*\n?([\s\S]*)/);
+  if (fenceMatch) {
+    json = fenceMatch[1].trim();
+  }
+
+  // Must start with [ or { to be JSON
+  if (!json.startsWith('[') && !json.startsWith('{')) return null;
+
+  // Try parsing as-is first (may be complete)
+  try {
+    const parsed = JSON.parse(json);
+    return wrapAsMessages(parsed);
+  } catch { /* expected for partial JSON */ }
+
+  // Try auto-closing: count open brackets and close them
+  let openBrackets = 0;
+  let openBraces = 0;
+  let inString = false;
+  let escaped = false;
+
+  for (const ch of json) {
+    if (escaped) { escaped = false; continue; }
+    if (ch === '\\') { escaped = true; continue; }
+    if (ch === '"') { inString = !inString; continue; }
+    if (inString) continue;
+    if (ch === '[') openBrackets++;
+    if (ch === ']') openBrackets--;
+    if (ch === '{') openBraces++;
+    if (ch === '}') openBraces--;
+  }
+
+  // Close any open strings, objects, arrays
+  let patched = json;
+  if (inString) patched += '"';
+  for (let i = 0; i < openBraces; i++) patched += '}';
+  for (let i = 0; i < openBrackets; i++) patched += ']';
+
+  try {
+    const parsed = JSON.parse(patched);
+    return wrapAsMessages(parsed);
+  } catch {
+    return null;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// CANVAS DIFF HELPERS — compact summary + merge for multi-turn iteration
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Produce a compact summary of existing canvas components.
+ * Instead of full JSON (~7K tokens for 100+ components), this yields ~500 tokens.
+ * Format:
+ *   148 components in 5 sections: Task Summary, Recent Activity, ...
+ *   root: Column
+ *   hdr: Header
+ *   title: Text(heading)
+ *   ...
+ */
+function compactCanvasSummary(components) {
+  if (!components || components.length === 0) return '';
+
+  // Detect sections (Cards with Header children)
+  const sections = [];
+  const cardIds = new Set();
+  for (const c of components) {
+    if (c.component === 'Card') {
+      cardIds.add(c.id);
+      // Try to find the section name from a child Header or Text with heading variant
+      const headerChild = components.find(
+        h => h.parentId === c.id && (h.component === 'Header' || h.component === 'CardHeader')
+      );
+      if (headerChild) {
+        const titleChild = components.find(
+          t => t.parentId === headerChild.id && t.component === 'Text'
+        );
+        sections.push(titleChild?.text || titleChild?.children || headerChild.title || c.id);
+      } else {
+        sections.push(c.id);
+      }
+    }
+  }
+
+  const lines = [];
+  const sectionSummary = sections.length > 0
+    ? ` in ${sections.length} sections: ${sections.slice(0, 8).join(', ')}${sections.length > 8 ? `, ... +${sections.length - 8} more` : ''}`
+    : '';
+  lines.push(`${components.length} components${sectionSummary}`);
+  lines.push('');
+
+  // One-line-per-component summary: id: Component(variant) [slot]
+  // Layout containers get their structural props so the LLM preserves them
+  const LAYOUT_TYPES = new Set(['Grid', 'Row', 'Column', 'Stack']);
+  const LAYOUT_PROPS = ['columns', 'gap', 'justify', 'align', 'wrap', 'direction', 'responsive'];
+  for (const c of components) {
+    let desc = c.component;
+    if (c.variant) desc += `(${c.variant})`;
+    if (c.slot) desc += ` [slot=${c.slot}]`;
+    // Include layout-critical props for containers
+    if (LAYOUT_TYPES.has(c.component)) {
+      const lp = LAYOUT_PROPS.filter(p => c[p] != null).map(p => `${p}=${c[p]}`);
+      if (lp.length) desc += ` {${lp.join(', ')}}`;
+    }
+    if (c.text) desc += ` "${String(c.text).slice(0, 30)}"`;
+    else if (c.label) desc += ` "${String(c.label).slice(0, 30)}"`;
+    else if (c.title) desc += ` "${String(c.title).slice(0, 30)}"`;
+    if (c.parentId) desc += ` ^${c.parentId}`;
+    lines.push(`  ${c.id}: ${desc}`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Merge an LLM-produced diff response with the prior canvas.
+ *
+ * The diff response contains:
+ *   - New components (id not in prior): added to result
+ *   - Modified components ({ id: 'existing', ...changed props }): merged with existing
+ *   - Deleted components ({ id: 'existing', _delete: true }): removed
+ *   - Unchanged components: carried forward from prior automatically
+ *
+ * @param {Array} priorComponents — full component array from last turn
+ * @param {Array} diffComponents — sparse diff array from LLM
+ * @returns {Array} merged full component array
+ */
+export function mergeCanvasDiff(priorComponents, diffComponents) {
+  if (!diffComponents || diffComponents.length === 0) return priorComponents;
+  if (!priorComponents || priorComponents.length === 0) return diffComponents;
+
+  // ── Detect full-replacement response ──
+  // On iteration turns the LLM is instructed to return DIFF OBJECTS referring
+  // to the prior canvas's ids. If the returned array shares almost no ids
+  // with the prior canvas AND starts from 'root', the LLM hallucinated a new
+  // UI instead of iterating — not a legitimate regeneration.
+  //
+  // Old behavior: silently accept the replacement (threshold <20% id match).
+  // This caused iteration turns to produce entirely unrelated canvases (see
+  // kanban "add draggable traits" case, 2026-04-19).
+  // New behavior: on iteration, a low-match-ratio replacement is a failure,
+  // not a feature. PRESERVE the prior canvas and warn — the user is better
+  // off with the unchanged canvas than with a hallucinated one. The ≥60%
+  // band still accepts valid whole-canvas rewrites (e.g. major restructures
+  // that re-id most components intentionally).
+  const priorIds = new Set(priorComponents.map(c => c.id));
+  const matchCount = diffComponents.filter(c => priorIds.has(c.id)).length;
+  const matchRatio = matchCount / Math.max(diffComponents.length, 1);
+  const hasRoot = diffComponents.some(c => c.id === 'root');
+
+  if (hasRoot && diffComponents.length >= 5 && matchRatio < 0.2) {
+    console.warn(`[mergeCanvasDiff] Hallucinated replacement rejected: ${diffComponents.length} new components, only ${matchCount} matching ids (${Math.round(matchRatio * 100)}%). Preserving prior canvas — LLM ignored iteration instructions.`);
+    return priorComponents;
+  }
+  if (hasRoot && diffComponents.length >= 5 && matchRatio < 0.6) {
+    // Middle band — could be a valid major rewrite, could be a partial
+    // hallucination. Accept but flag. If this turns out to be wrong too,
+    // tighten to return priorComponents here as well.
+    console.warn(`[mergeCanvasDiff] Low-match rewrite accepted: ${matchCount}/${diffComponents.length} ids match (${Math.round(matchRatio * 100)}%). Treating as a deliberate restructure.`);
+    return diffComponents;
+  }
+
+  const priorMap = new Map(priorComponents.map(c => [c.id, c]));
+  const deletedIds = new Set();
+  const modifiedIds = new Set();
+  const newComponents = [];
+
+  for (const dc of diffComponents) {
+    if (!dc || !dc.id) continue;
+
+    if (dc._delete) {
+      // Deletion marker
+      deletedIds.add(dc.id);
+      continue;
+    }
+
+    if (priorMap.has(dc.id)) {
+      // Modification: merge props onto existing component
+      const existing = priorMap.get(dc.id);
+      // GUARD: Prevent component type changes on layout containers —
+      // changing Grid→Column collapses multi-column layouts
+      const LAYOUT_CONTAINERS = new Set(['Grid', 'Row', 'Column', 'Stack']);
+      if (dc.component && dc.component !== existing.component &&
+          (LAYOUT_CONTAINERS.has(existing.component) || LAYOUT_CONTAINERS.has(dc.component))) {
+        console.warn(`[mergeCanvasDiff] Blocked layout type change: ${existing.component}→${dc.component} on id="${dc.id}". Preserving original type.`);
+        delete dc.component;
+      }
+      const merged = { ...existing, ...dc };
+      // Remove internal _delete if somehow present
+      delete merged._delete;
+      priorMap.set(dc.id, merged);
+      modifiedIds.add(dc.id);
+    } else {
+      // New component
+      newComponents.push(dc);
+    }
+  }
+
+  // Build result: prior components (minus deleted) + new components
+  const result = [];
+  for (const c of priorComponents) {
+    if (deletedIds.has(c.id)) continue;
+    result.push(priorMap.get(c.id));
+  }
+
+  // Insert new components intelligently: after their parentId if specified, else at end
+  for (const nc of newComponents) {
+    if (nc.parentId) {
+      const parentIdx = result.findIndex(c => c.id === nc.parentId);
+      if (parentIdx !== -1) {
+        // Find the last sibling under the same parent to insert after
+        let insertIdx = parentIdx + 1;
+        while (insertIdx < result.length && result[insertIdx].parentId === nc.parentId) {
+          insertIdx++;
+        }
+        result.splice(insertIdx, 0, nc);
+        continue;
+      }
+    }
+    result.push(nc);
+  }
+
+  return result;
+}
+
+/**
+ * Build the diff-mode iteration prompt shared by all hasPriorCanvas branches.
+ * @param {string} intent — user's iteration request
+ * @param {Array} priorComponents — full prior canvas components
+ * @param {object} [opts]
+ * @param {string|null} [opts.originalIntent] — original design brief for drift anchoring
+ * @returns {string} prompt text for the canvas diff
+ */
+export function buildCanvasDiffPrompt(intent, priorComponents, { originalIntent = null } = {}) {
+  // Design intent anchor — prevents drift from the original brief
+  const intentAnchor = originalIntent && originalIntent !== intent
+    ? `\nORIGINAL DESIGN BRIEF (the user's first request — all changes must stay aligned with this): "${originalIntent}"\nThe current modification ("${intent}") should REFINE the original design, not replace its purpose.\n`
+    : '';
+
+  // Full-JSON path for most canvases — the LLM gets the actual component
+  // shape and can faithfully modify it. Compact-text summaries lose nesting
+  // and props, which sends the LLM into "regenerate from memory" mode and
+  // produces whole-new canvases instead of iterations (verified 2026-04-19).
+  // The threshold is conservative — 300 components at ~40-60 bytes each is
+  // ~15-20KB, well within 32k max_tokens output budget and 120k+ input.
+  if (priorComponents.length < 300) {
+    return `${intentAnchor}CURRENT CANVAS STATE (this is what the user sees right now — MODIFY it):
+${JSON.stringify(priorComponents, null, 2)}
+
+The user is ITERATING on their existing canvas shown above. They want to MODIFY it, not replace it.
+
+Instructions:
+- Preserve ALL existing components unless explicitly asked to remove them
+- Add new components where they logically belong
+- Change text content, labels, icons to match the new intent
+- Preserve slot attributes and Card anatomy rules
+- CRITICAL: Preserve layout container types — do NOT change Grid to Column or Row to Column. If the canvas has a Grid with columns="3" for a card collection, keep it as Grid. Only change layout types when the user explicitly requests a layout change.
+- CONTENT CARRY-OVER on component swaps: when the user asks to upgrade a component to a richer variant (e.g. Image → Carousel, Text → Stat, Toggle → ToggleGroup, Input → Select), the original's content props (src, alt, textContent, text, value, label, name) MUST be carried into the equivalent prop on the new component. The original src becomes the first slide of a Carousel; the original textContent becomes the first item; the original value becomes the default. NEVER emit a swapped component with placeholder/lorem content when real content was present in the original.
+- You MUST return the COMPLETE component array including all existing components plus your modifications
+- Generate at least ${priorComponents.length} components (the existing ones plus any additions)
+- SCOPE GUARD: Only add sections/components that the user explicitly requested. Do NOT speculatively add features, panels, or sections not mentioned in the intent. If adding more than 3 new top-level sections, reconsider whether the user actually asked for them.
+- Output ONLY the JSON array, no explanation`;
+  }
+
+  // For large canvases, use compact diff format to save tokens
+  const summary = compactCanvasSummary(priorComponents);
+  return `CURRENT CANVAS SUMMARY (${priorComponents.length} components — do NOT regenerate unchanged ones):
+${summary}
+${intentAnchor}
+The user wants to MODIFY their existing canvas. Return ONLY the components you need to ADD, MODIFY, or DELETE:
+CRITICAL PRESERVATION RULES:
+- NEVER change layout container types (Grid→Column, Row→Column, Grid→Row) unless the user explicitly asks to change the layout structure.
+- If a Grid has columns="3", keep it as Grid with columns="3". Adding a toggle/filter/button to a toolbar does NOT change the content layout below.
+- Preserve parent-child relationships — adding a control to a toolbar row doesn't affect sibling containers.
+- CONTENT CARRY-OVER on component swaps: when upgrading a component to a richer variant (Image→Carousel, Text→Stat, Toggle→ToggleGroup, Input→Select), the original's content props (src, alt, textContent, text, value, label, name) MUST flow into the equivalent prop on the new component (or become its first item, where applicable). NEVER emit a swapped component with placeholder content when real content was present.
+
+DIFF FORMAT:
+- To ADD a new component: include the full component JSON object (with a new unique id)
+- To MODIFY an existing component: { "id": "existing-id", ...only changed props }  (e.g. { "id": "title", "text": "New Title" })
+- To DELETE a component: { "id": "existing-id", "_delete": true }
+- UNCHANGED components: do NOT include them — they are preserved automatically
+
+CRITICAL: Do NOT change a component's "component" type in modifications (e.g. Grid→Column). Container types (Grid, Row, Column) define layout structure — changing them collapses layouts. To restructure, DELETE the old container and ADD a new one with the correct type and reparent its children.
+
+Return a JSON array of ONLY the diff objects. Keep it minimal — typically 2-15 objects for an iteration.
+Output ONLY the JSON array, no explanation.`;
+}
+
+/**
+ * Normalize parsed JSON into A2UI message array.
+ */
+function wrapAsMessages(parsed) {
+  if (Array.isArray(parsed)) {
+    // Array of messages (may include updateComponents + wireComponents)
+    const validTypes = new Set(['updateComponents', 'wireComponents', 'createSurface', 'updateDataModel', 'deleteSurface']);
+    if (parsed.length > 0 && validTypes.has(parsed[0].type)) return parsed;
+    // Bare components array
+    if (parsed.length > 0 && parsed[0].id && parsed[0].component) {
+      return [{ type: 'updateComponents', surfaceId: 'default', components: parsed }];
+    }
+    return parsed;
+  }
+  if (parsed && typeof parsed === 'object' && parsed.type === 'updateComponents') return [parsed];
+  if (parsed && typeof parsed === 'object' && parsed.type === 'wireComponents') return [parsed];
+  if (parsed && typeof parsed === 'object' && parsed.id && parsed.component) {
+    return [{ type: 'updateComponents', surfaceId: 'default', components: [parsed] }];
+  }
+  return null;
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// EXISTING HELPERS
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Parse raw LLM output into A2UI messages.
+ * Multi-strategy JSON extraction with repair for common LLM output issues.
+ *
+ * Strategies tried in order:
+ * 1. Direct parse (clean JSON)
+ * 2. Markdown code block extraction (```json ... ```)
+ * 3. Outermost JSON extraction (find first [ or { to last ] or })
+ * 4. Trailing comma / comment cleanup + re-parse
+ * 5. Auto-close brackets (reuse tryParsePartial logic)
+ *
+ * @param {string} content — Raw LLM response text
+ * @param {object} [ctx] — optional debug context forwarded to fallbackMessage
+ * @returns {object[]} — Array of A2UI messages
+ */
+/**
+ * Returns true if the given A2UI message array is a generation-failure
+ * fallback surface (Alert + Try Again + debug payload). Stamped at fallback
+ * construction via `_fallback: true` on the updateComponents message, so this
+ * is a deterministic O(1) check — no fingerprinting heuristics required.
+ *
+ * Use this in validators, scorers, and downstream consumers that need to
+ * distinguish a successful generation from a structurally-valid error surface.
+ */
+export function isFallbackResult(messages) {
+  if (!Array.isArray(messages) || messages.length === 0) return false;
+  return messages.some(m => m && m._fallback === true);
+}
+
+export function parseA2UIResponse(content, ctx) {
+  // Truncation short-circuit: if the LLM stopped because it hit max_tokens,
+  // any remaining JSON is missing tail components. Don't try to auto-close —
+  // surface the truncation explicitly so the validator and UI both know.
+  if (ctx?.stopReason && ctx.stopReason !== 'end' && ctx.stopReason !== 'end_turn' && ctx.stopReason !== 'stop') {
+    return [...fallbackMessage(`LLM response truncated (stop reason: ${ctx.stopReason}). Try a simpler intent or a model with larger output budget.`, { ...ctx, rawResponse: content })];
+  }
+  if (!content || typeof content !== 'string') {
+    return [...fallbackMessage('Empty LLM response', ctx)];
+  }
+
+  const trimmed = content.trim();
+
+  // Strategy 1: Direct parse (cleanest case)
+  const direct = _tryParseAndWrap(trimmed);
+  if (direct) return direct;
+
+  // Strategy 2: Extract from markdown code fences (try all code blocks, prefer ```json)
+  const fenceBlocks = [...trimmed.matchAll(/```(?:json)?\s*\n?([\s\S]*?)```/g)];
+  for (const match of fenceBlocks) {
+    const block = match[1].trim();
+    const result = _tryParseAndWrap(block);
+    if (result) return result;
+  }
+
+  // Strategy 3: Find outermost JSON — locate first [ or { and last ] or }
+  const extracted = _extractOutermostJSON(trimmed);
+  if (extracted) {
+    const result = _tryParseAndWrap(extracted);
+    if (result) return result;
+  }
+
+  // Strategy 4: Cleanup trailing commas, single-line comments, then re-parse
+  const candidates = [trimmed, ...(fenceBlocks.map(m => m[1].trim())), extracted].filter(Boolean);
+  for (const candidate of candidates) {
+    const cleaned = _cleanupJSON(candidate);
+    if (cleaned !== candidate) {
+      const result = _tryParseAndWrap(cleaned);
+      if (result) return result;
+    }
+  }
+
+  // Strategy 5: Auto-close brackets (LLM truncated mid-output)
+  for (const candidate of candidates) {
+    const cleaned = _cleanupJSON(candidate);
+    const closed = _autoCloseBrackets(cleaned);
+    if (closed !== cleaned) {
+      const result = _tryParseAndWrap(closed);
+      if (result) return result;
+    }
+  }
+
+  // All strategies failed — log raw content for debugging
+  _logParseFailure(content);
+  return [...fallbackMessage('Failed to parse LLM response as JSON', { ...ctx, rawResponse: content })];
+}
+
+/**
+ * Try JSON.parse + wrapAsMessages. Returns result or null.
+ */
+function _tryParseAndWrap(text) {
+  if (!text) return null;
+  try {
+    const parsed = JSON.parse(text);
+    return wrapAsMessages(parsed) || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Extract outermost JSON structure from text with surrounding prose.
+ * Finds the first [ or { and the matching last ] or }.
+ */
+function _extractOutermostJSON(text) {
+  // Find first JSON-start character
+  const arrStart = text.indexOf('[');
+  const objStart = text.indexOf('{');
+  if (arrStart === -1 && objStart === -1) return null;
+
+  let startIdx;
+  if (arrStart === -1) startIdx = objStart;
+  else if (objStart === -1) startIdx = arrStart;
+  else startIdx = Math.min(arrStart, objStart);
+
+  // Walk forward tracking nesting for both bracket types
+  let brackets = 0;
+  let braces = 0;
+  let inString = false;
+  let escaped = false;
+  let endIdx = -1;
+
+  for (let i = startIdx; i < text.length; i++) {
+    const ch = text[i];
+    if (escaped) { escaped = false; continue; }
+    if (ch === '\\' && inString) { escaped = true; continue; }
+    if (ch === '"') { inString = !inString; continue; }
+    if (inString) continue;
+    if (ch === '[') brackets++;
+    else if (ch === ']') brackets--;
+    else if (ch === '{') braces++;
+    else if (ch === '}') braces--;
+
+    // Balanced when we return to zero for the type we started with
+    if (brackets === 0 && braces === 0) {
+      endIdx = i;
+      break;
+    }
+  }
+
+  if (endIdx === -1) {
+    // No balanced close found — return from start to end for auto-closing
+    return text.slice(startIdx);
+  }
+  return text.slice(startIdx, endIdx + 1);
+}
+
+/**
+ * Clean up common LLM JSON issues: trailing commas, single-line comments.
+ */
+function _cleanupJSON(text) {
+  if (!text) return text;
+  let result = text;
+  // Remove single-line comments (// ...) outside strings
+  result = result.replace(/(?<="[^"]*".*?)\/\/[^\n]*/g, '');
+  // Simpler: remove lines that are just comments
+  result = result.replace(/^\s*\/\/.*$/gm, '');
+  // Remove trailing commas before } or ]
+  result = result.replace(/,\s*([}\]])/g, '$1');
+  return result;
+}
+
+/**
+ * Auto-close unclosed brackets/braces (LLM truncated mid-output).
+ */
+function _autoCloseBrackets(text) {
+  if (!text) return text;
+  // Must start with [ or {
+  const trimmed = text.trim();
+  if (!trimmed.startsWith('[') && !trimmed.startsWith('{')) return text;
+
+  let openBrackets = 0;
+  let openBraces = 0;
+  let inString = false;
+  let escaped = false;
+
+  for (const ch of trimmed) {
+    if (escaped) { escaped = false; continue; }
+    if (ch === '\\') { escaped = true; continue; }
+    if (ch === '"') { inString = !inString; continue; }
+    if (inString) continue;
+    if (ch === '[') openBrackets++;
+    if (ch === ']') openBrackets--;
+    if (ch === '{') openBraces++;
+    if (ch === '}') openBraces--;
+  }
+
+  if (openBrackets === 0 && openBraces === 0) return text;
+
+  let patched = trimmed;
+  if (inString) patched += '"';
+  for (let i = 0; i < openBraces; i++) patched += '}';
+  for (let i = 0; i < openBrackets; i++) patched += ']';
+  return patched;
+}
+
+/**
+ * Log raw LLM content on parse failure for debugging.
+ * Only logs in Node.js environment (not browser).
+ */
+function _logParseFailure(content) {
+  try {
+    const preview = content.length > 500 ? content.slice(0, 500) + '...' : content;
+    console.warn(`[A2UI] All JSON parse strategies failed (${content.length} chars). Preview:\n${preview}`);
+  } catch { /* ignore */ }
+}
+
+/**
+ * Create a fallback updateComponents message with an error hint.
+ * When debug metadata is available, renders execution context, mode, intent,
+ * a collapsible raw-response preview, and a copy-debug-info button.
+ *
+ * @param {string} reason
+ * @param {object} [opts]
+ * @param {string} [opts.executionId] — Pipeline execution ID
+ * @param {string} [opts.intent] — The user intent that triggered generation
+ * @param {string} [opts.mode] — Generation mode (instant/pro/thinking/stream)
+ * @param {string} [opts.rawResponse] — Raw LLM output (truncated for display)
+ * @returns {object[]} Array of A2UI messages (updateComponents + wireComponents)
+ */
+function fallbackMessage(reason, opts = {}) {
+  const { executionId, intent, mode, rawResponse } = opts;
+  const children = ['sec', 'ftr'];
+  const components = [
+    { id: 'sec', component: 'Section', children: ['alert'] },
+    { id: 'alert', component: 'Alert', variant: 'error', title: 'Generation Error', description: reason },
+  ];
+
+  // ── Debug metadata: execution ID, mode, intent ──
+  const hasMetadata = executionId || mode || intent;
+  if (hasMetadata) {
+    children.splice(1, 0, 'meta-sec');
+    const metaChildren = [];
+    if (executionId) {
+      metaChildren.push('meta-exec');
+      components.push({ id: 'meta-exec', component: 'Text', variant: 'caption', color: 'muted', textContent: `Execution: ${executionId}` });
+    }
+    if (mode) {
+      metaChildren.push('meta-mode');
+      components.push({ id: 'meta-mode', component: 'Badge', text: mode, variant: 'subtle' });
+    }
+    if (intent) {
+      const truncIntent = intent.length > 120 ? intent.slice(0, 120) + '…' : intent;
+      metaChildren.push('meta-intent');
+      components.push({ id: 'meta-intent', component: 'Text', variant: 'caption', color: 'subtle', textContent: `Prompt: "${truncIntent}"` });
+    }
+    components.push({ id: 'meta-sec', component: 'Section', children: metaChildren });
+  }
+
+  // ── Collapsible raw response preview ──
+  if (rawResponse && typeof rawResponse === 'string') {
+    children.splice(children.indexOf('ftr'), 0, 'raw-acc');
+    const preview = rawResponse.length > 2000 ? rawResponse.slice(0, 2000) + `\n… [truncated, ${rawResponse.length} chars total]` : rawResponse;
+    components.push(
+      { id: 'raw-acc', component: 'Accordion', children: ['raw-item'] },
+      { id: 'raw-item', component: 'AccordionItem', text: 'Raw LLM Response', children: ['raw-code'] },
+      { id: 'raw-code', component: 'Code', language: 'text', textContent: preview },
+    );
+  }
+
+  // ── Footer: Try Again + Copy Debug Info ──
+  const footerChildren = ['retry'];
+  const debugPayload = JSON.stringify({
+    error: reason,
+    ...(executionId && { executionId }),
+    ...(mode && { mode }),
+    ...(intent && { intent }),
+    ...(rawResponse && { rawResponsePreview: rawResponse.slice(0, 4000) }),
+  }, null, 2);
+
+  if (executionId || rawResponse) {
+    footerChildren.push('copy-btn');
+    components.push({ id: 'copy-btn', component: 'Button', text: 'Copy Debug Info', icon: 'clipboard', variant: 'outline', 'data-clipboard': debugPayload });
+  }
+
+  components.push(
+    { id: 'ftr', component: 'Footer', children: footerChildren },
+    { id: 'retry', component: 'Button', text: 'Try Again', icon: 'arrow-clockwise', variant: 'primary' },
+  );
+
+  const updateMsg = {
+    type: 'updateComponents',
+    surfaceId: 'default',
+    // Marker so validators / scorers / consumers can detect that this is a
+    // generation-failure surface (NOT a successful UI). Without this, the
+    // validator was scoring fallbacks ~89/100 because they're structurally
+    // a valid Card. See diagnosis report 2026-04-19.
+    _fallback: true,
+    _fallbackReason: reason,
+    components: [
+      { id: 'root', component: 'Card', children },
+      ...components,
+    ],
+  };
+
+  // ── Wiring: retry button emits a2ui-retry so consumers can re-run generation ──
+  const actions = [
+    {
+      event: { event: 'press', target: 'retry' },
+      handler: 'emit-event',
+      config: {
+        eventName: 'a2ui-retry',
+        detail: { intent: intent || '', mode: mode || 'pro', executionId: executionId || '' },
+      },
+    },
+  ];
+
+  const wireMsg = {
+    type: 'wireComponents',
+    surfaceId: 'default',
+    actions,
+  };
+
+  return [updateMsg, wireMsg];
+}
+
+/**
+ * Build a repair prompt from failed validation checks.
+ * @param {object[]} failedChecks
+ * @param {object[]} messages
+ * @returns {string}
+ */
+export function buildRepairPrompt(failedChecks, messages, catalogFailures = []) {
+  const blocks = [];
+
+  if (failedChecks.length > 0) {
+    const lines = failedChecks.map(c => `- ${c.name}: ${c.detail}`).join('\n');
+    blocks.push(`Heuristic validation errors:\n${lines}`);
+  }
+
+  if (catalogFailures.length > 0) {
+    // Each entry: { id, component, errors: string[] }. Show at most 20 to
+    // keep the prompt bounded; the LLM sees the pattern after a handful.
+    const slice = catalogFailures.slice(0, 20);
+    const lines = slice
+      .map(f => `- ${f.component} id="${f.id}": ${f.errors.slice(0, 3).join('; ')}`)
+      .join('\n');
+    const overflow = catalogFailures.length > 20 ? `\n  (+${catalogFailures.length - 20} more — same patterns apply)` : '';
+    blocks.push(`Catalog (v0.9 schema) validation errors:\n${lines}${overflow}\n\nFix by:\n- Removing unknown properties (use declared props only)\n- Aligning enum values (e.g. variant="primary" not variant="main")\n- Using correct types (number fields get numbers, not strings)`);
+  }
+
+  return [
+    `Fix these A2UI validation errors:\n`,
+    blocks.join('\n\n'),
+    `\n\nOriginal output:\n${JSON.stringify(messages)}`,
+  ].join('');
+}
+
+/**
+ * Generate 2-4 actionable follow-up suggestions based on what's already on
+ * the canvas. Canvas-aware (not domain-aware) so iteration turns don't drift
+ * into unrelated patterns — a login form should never get "add a chart"
+ * suggested, even when the LATEST turn's intent ("add status feedback")
+ * trips the data-domain classifier.
+ *
+ * Selection logic:
+ *   1. Prefer concept-specific extensions for the ORIGINAL canvas concepts
+ *      (e.g. "auth" → forgot-password, social sign-in, remember-me).
+ *   2. Fall back to the original analyzer's impliedComponents that aren't
+ *      yet present (e.g. "Add Avatar" if the analysis expected one).
+ *   3. Cap at 4. Never propose components that conflict with the canvas's
+ *      existing shape (no "data table" for a login form).
+ *
+ * @param {object} opts
+ * @param {string} opts.intent — Current turn's intent (most-recent)
+ * @param {object} opts.domain — Current turn's domain classification
+ * @param {object[]} opts.messages — Current canvas messages
+ * @param {object} [opts.originalAnalysis] — First turn's analyzer output (from store)
+ * @param {string} [opts.originalIntent] — First turn's intent (from store)
+ */
+export function generateSuggestions({ intent, domain, messages, originalAnalysis = null, originalIntent = null }) {
+  // Component types currently on canvas
+  const types = new Set();
+  for (const msg of messages || []) {
+    if (msg?.type === 'updateComponents' && Array.isArray(msg.components)) {
+      for (const c of msg.components) if (c?.component) types.add(c.component);
+    }
+  }
+
+  // Concepts that anchor what kind of canvas this IS. Prefer the original
+  // analysis (durable across iteration turns) over the current intent's
+  // domain (which drifts with each chip click).
+  const concepts = new Set((originalAnalysis?.concepts || []).map(c => c.toLowerCase()));
+  const impliedComponents = new Set(originalAnalysis?.impliedComponents || []);
+  const domainName = domain?.domain || 'layout';
+
+  // Concept-specific extension catalogues. Keys match the kind of tags the
+  // analyzer produces (concepts like "auth", "commerce"). When a concept
+  // matches, suggestions extend the canvas instead of drifting away.
+  const CONCEPT_EXTENSIONS = {
+    'auth':            ['Add forgot password link', 'Add Sign in with Google', 'Add Remember me checkbox', 'Add Sign up link'],
+    'authentication':  ['Add forgot password link', 'Add Sign in with Google', 'Add Remember me checkbox', 'Add Sign up link'],
+    'login':           ['Add forgot password link', 'Add Sign in with Google', 'Add Remember me checkbox', 'Add Sign up link'],
+    'commerce':        ['Add price comparison', 'Add product variants picker', 'Add quantity stepper', 'Add Save for later button'],
+    'product-display': ['Add price comparison', 'Add product variants picker', 'Add rating stars', 'Add Save for later button'],
+    'settings':        ['Add a Save / Cancel footer', 'Add an account section', 'Add a danger zone (delete account)', 'Add a billing section'],
+    'preferences':     ['Add a Save / Cancel footer', 'Add an account section', 'Add a notifications section'],
+    'navigation':      ['Add breadcrumbs', 'Add a sidebar', 'Add a search bar'],
+    'data-display':    ['Add filter controls', 'Add sort controls', 'Add a row-level action menu', 'Add a CSV export button'],
+    'agent':           ['Add a streaming response area', 'Add action buttons', 'Add a citation list'],
+  };
+
+  const suggestions = [];
+
+  // 1. Concept-driven extensions (the high-quality path)
+  for (const concept of concepts) {
+    const ext = CONCEPT_EXTENSIONS[concept];
+    if (ext) {
+      for (const s of ext) if (!suggestions.includes(s)) suggestions.push(s);
+      if (suggestions.length >= 4) break;
+    }
+  }
+
+  // 2. Fill from analyzer's impliedComponents that aren't on canvas yet.
+  //    "The brief said you'd want an Avatar but you don't have one."
+  if (suggestions.length < 4) {
+    for (const c of impliedComponents) {
+      if (!types.has(c)) {
+        const label = `Add ${prettyComponentName(c)}`;
+        if (!suggestions.includes(label)) suggestions.push(label);
+        if (suggestions.length >= 4) break;
+      }
+    }
+  }
+
+  // 3. Last resort — domain heuristics, but ONLY when no concepts AND no
+  //    implied components landed. Original generic catalogue, intentionally
+  //    weak so it loses to the better paths above.
+  if (suggestions.length === 0) {
+    if (domainName === 'forms')      suggestions.push('Add form validation', 'Add helper text');
+    else if (domainName === 'data')  suggestions.push('Add filter controls', 'Add a row-level action menu');
+    else                             suggestions.push('Add a header', 'Add interactive controls');
+  }
+
+  return suggestions.slice(0, 4);
+}
+
+/** "AvatarGroup" → "an avatar group", "Button" → "a button" — friendly suggestion text. */
+function prettyComponentName(name) {
+  const spaced = String(name).replace(/([a-z])([A-Z])/g, '$1 $2').toLowerCase();
+  const article = /^[aeiou]/i.test(spaced) ? 'an' : 'a';
+  return `${article} ${spaced}`;
+}