@adia-ai/a2ui-compose 0.0.1

package/transpiler/transpiler.js

@@ -0,0 +1,820 @@
+/**
+ * HTML → A2UI Transpiler
+ *
+ * Converts arbitrary HTML/DOM into A2UI flat adjacency component messages.
+ * Three layers:
+ *   Layer 1: Deterministic tag mapping (HTML tag → A2UI type)
+ *   Layer 2: Structure inference (div/span → Column/Row/Card via styles)
+ *   Layer 3: LLM reasoning (optional, for ambiguous structures)
+ *
+ * @module transpiler
+ */
+
+import {
+  reverseRegistry, HTML_TAG_MAP, INPUT_TYPE_MAP, ARIA_ROLE_MAP,
+  SKIP_TAGS, extractProps, inferGap,
+} from './transpiler-maps.js';
+import { validateSchema } from '../../validator/validator.js';
+import { getContext } from '../engine/reference.js';
+
+// ═══════════════════════════════════════════════════════════════
+// PUBLIC API
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Transpile an HTML string to A2UI messages.
+ *
+ * @param {string} html — Raw HTML markup
+ * @param {object} [options]
+ * @param {'instant'|'reasoning'} [options.mode='instant']
+ * @param {object} [options.llmAdapter] — Required for reasoning mode
+ * @param {string} [options.surfaceId='default']
+ * @returns {Promise<{ messages: object[], validation: object, suggestions: string[] }>}
+ */
+export async function transpileHTML(html, options = {}) {
+  const { mode = 'instant', llmAdapter, surfaceId = 'default' } = options;
+
+  if (!html || typeof html !== 'string' || !html.trim()) {
+    return {
+      messages: [...fallbackMessage('No HTML content to convert')],
+      validation: { score: 0, valid: false, checks: [] },
+      suggestions: ['Provide HTML markup to convert'],
+    };
+  }
+
+  // Parse HTML into a walkable tree
+  const root = parseHTMLMinimal(html);
+
+  // Walk the tree — Layer 1 + Layer 2
+  const context = {
+    usedIds: new Set(),
+    components: [],
+    isRoot: true,
+  };
+
+  const rootId = walkNode(root, context);
+
+  // Ensure root component has id "root"
+  if (rootId && context.components.length > 0) {
+    const rootComp = context.components.find(c => c.id === rootId);
+    if (rootComp && rootComp.id !== 'root') {
+      // Rename to "root" and update any parent references
+      const oldId = rootComp.id;
+      rootComp.id = 'root';
+      for (const comp of context.components) {
+        if (comp.children) {
+          comp.children = comp.children.map(id => id === oldId ? 'root' : id);
+        }
+      }
+    }
+  }
+
+  const messages = [{
+    type: 'updateComponents',
+    surfaceId,
+    components: context.components,
+  }];
+
+  let validation = validateSchema(messages);
+  const suggestions = generateSuggestions(html, context.components, validation);
+
+  // Layer 3: LLM reasoning if instant mode scored low
+  if (mode === 'reasoning' && llmAdapter && validation.score < 85) {
+    try {
+      const improved = await reasoningPass(html, messages, validation, llmAdapter);
+      if (improved) {
+        const improvedValidation = validateSchema(improved);
+        if (improvedValidation.score > validation.score) {
+          return {
+            messages: improved,
+            validation: improvedValidation,
+            suggestions: generateSuggestions(html, improved[0]?.components || [], improvedValidation),
+          };
+        }
+      }
+    } catch {
+      // Keep instant result on LLM failure
+    }
+  }
+
+  return { messages, validation, suggestions };
+}
+
+/**
+ * Transpile a live DOM element to A2UI messages (browser-only).
+ * Uses getComputedStyle for better structure inference.
+ *
+ * @param {HTMLElement} rootElement
+ * @param {object} [options]
+ * @returns {Promise<{ messages: object[], validation: object, suggestions: string[] }>}
+ */
+export async function transpileDOM(rootElement, options = {}) {
+  const html = rootElement.outerHTML;
+  return transpileHTML(html, options);
+}
+
+// ═══════════════════════════════════════════════════════════════
+// TREE WALKER
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Recursively walk a DOM node and produce A2UI components.
+ *
+ * @param {MinimalElement} el
+ * @param {object} context — { usedIds, components, isRoot }
+ * @returns {string|null} — The generated ID for this node, or null if skipped
+ */
+function walkNode(el, context) {
+  const tag = (el.tagName || '').toLowerCase();
+
+  // Skip non-element nodes, skip tags, empty text
+  if (!tag) {
+    // Text node
+    const text = (el.textContent || '').trim();
+    if (!text) return null;
+    // Create a Text component for bare text
+    const id = generateId('Text', el, context.usedIds);
+    context.components.push({ id, component: 'Text', textContent: text, variant: 'body' });
+    return id;
+  }
+
+  if (SKIP_TAGS.has(tag)) return null;
+
+  // ── Resolve A2UI type ──
+
+  let a2uiType = null;
+  let defaultProps = {};
+
+  // 1. Already an A2UI component (*-n tag)?
+  if (reverseRegistry.has(tag)) {
+    a2uiType = reverseRegistry.get(tag);
+  }
+  // 2. ARIA role?
+  else if (el.getAttribute('role') && ARIA_ROLE_MAP[el.getAttribute('role')]) {
+    a2uiType = ARIA_ROLE_MAP[el.getAttribute('role')];
+  }
+  // 3. Input element? Use type sub-map
+  else if (tag === 'input') {
+    const inputType = el.getAttribute('type') || 'text';
+    const mapped = INPUT_TYPE_MAP[inputType];
+    if (mapped) {
+      a2uiType = mapped.type;
+      defaultProps = { ...mapped.props };
+    } else {
+      a2uiType = 'TextField';
+    }
+    // Hidden inputs are skipped
+    if (inputType === 'hidden') return null;
+  }
+  // 4. HTML tag map?
+  else if (HTML_TAG_MAP[tag]) {
+    a2uiType = HTML_TAG_MAP[tag].type;
+    defaultProps = { ...HTML_TAG_MAP[tag].props };
+  }
+  // 5. div/span → Layer 2 structure inference
+  else if (tag === 'div' || tag === 'span') {
+    const inferred = inferStructure(el);
+    a2uiType = inferred.type;
+    defaultProps = inferred.props || {};
+  }
+  // 6. Unknown → Column (container)
+  else {
+    a2uiType = 'Column';
+  }
+
+  // ── Generate ID ──
+  const id = context.isRoot ? 'root' : generateId(a2uiType, el, context.usedIds);
+  context.isRoot = false;
+
+  // ── Extract props ──
+  const extractedProps = extractProps(el, a2uiType);
+  const props = { ...defaultProps, ...extractedProps };
+
+  // ── Handle children ──
+
+  // Leaf types: these render their own text, don't recurse into children
+  const LEAF_TYPES = new Set([
+    'Text', 'Button', 'Kbd', 'Code', 'Badge', 'Image', 'Divider',
+    'TextField', 'CheckBox', 'Toggle', 'Radio', 'Slider', 'Search',
+    'Upload', 'ColorPicker', 'DateTimeInput', 'TextArea', 'OtpInput',
+  ]);
+
+  if (LEAF_TYPES.has(a2uiType)) {
+    context.components.push({ id, component: a2uiType, ...props });
+    return id;
+  }
+
+  const children = el.children || [];
+  const childElements = children.filter(c => c.tagName || (c.textContent || '').trim());
+
+  // Container with no children
+  if (childElements.length === 0) {
+    context.components.push({ id, component: a2uiType, ...props });
+    return id;
+  }
+
+  const childIds = [];
+  for (const child of childElements) {
+    const childId = walkNode(child, context);
+    if (childId) childIds.push(childId);
+  }
+
+  // Flatten: single-child container chains (div > div > div > content → just content)
+  if (childIds.length === 1 && ['Column', 'Row'].includes(a2uiType) && !Object.keys(props).length) {
+    // This container adds nothing — return the child directly
+    return childIds[0];
+  }
+
+  // ── Card content model enforcement ──
+  // Card must follow: Card > Header + Section > Column + Footer
+  if (a2uiType === 'Card') {
+    return buildCardStructure(id, childIds, props, context);
+  }
+
+  const component = { id, component: a2uiType, ...props };
+  if (childIds.length > 0) component.children = childIds;
+  context.components.push(component);
+
+  return id;
+}
+
+/**
+ * Build a proper Card structure: Card > Header + Section > Column + Footer.
+ * Classifies child components into header (headings), footer (buttons), and
+ * body (everything else wrapped in Section > Column).
+ *
+ * @param {string} cardId
+ * @param {string[]} childIds — IDs of already-created child components
+ * @param {Record<string, unknown>} cardProps
+ * @param {object} context
+ * @returns {string} — The card's ID
+ */
+function buildCardStructure(cardId, childIds, cardProps, context) {
+  const headerIds = [];
+  const footerIds = [];
+  const bodyIds = [];
+
+  for (const childId of childIds) {
+    const child = context.components.find(c => c.id === childId);
+    if (!child) { bodyIds.push(childId); continue; }
+
+    const type = child.component;
+
+    // Header and Footer pass through directly (already correct type)
+    if (type === 'Header') { headerIds.push(childId); continue; }
+    if (type === 'Footer') { footerIds.push(childId); continue; }
+
+    // Headings (Text h1-h5) go into a synthesized Header
+    if (type === 'Text' && child.variant && /^h[1-5]$/.test(child.variant)) {
+      headerIds.push(childId);
+      continue;
+    }
+
+    // Buttons go into a synthesized Footer
+    if (type === 'Button') { footerIds.push(childId); continue; }
+
+    // Section passes through (but needs Column wrapping check)
+    if (type === 'Section') { bodyIds.push(childId); continue; }
+
+    // Everything else → body
+    bodyIds.push(childId);
+  }
+
+  const cardChildren = [];
+
+  // ── Build Header ──
+  if (headerIds.length > 0) {
+    // Check if there's already a Header component among them
+    const existingHeader = headerIds.find(id => context.components.find(c => c.id === id)?.component === 'Header');
+    if (existingHeader) {
+      cardChildren.push(existingHeader);
+      // Add any remaining header items as body instead
+      for (const hid of headerIds) {
+        if (hid !== existingHeader) bodyIds.unshift(hid);
+      }
+    } else {
+      // Wrap headings in a new Header — ensure data-heading is set
+      for (const hid of headerIds) {
+        const child = context.components.find(c => c.id === hid);
+        if (child && child.variant && /^h[1-5]$/.test(child.variant) && !child['data-heading']) {
+          child['data-heading'] = 'section';
+        }
+      }
+      const hdrId = generateId('Header', null, context.usedIds);
+      context.components.push({ id: hdrId, component: 'Header', children: headerIds });
+      cardChildren.push(hdrId);
+    }
+  }
+
+  // ── Build Section > Column for body content ──
+  if (bodyIds.length > 0) {
+    // Check if there's already a Section among them
+    const existingSection = bodyIds.find(id => context.components.find(c => c.id === id)?.component === 'Section');
+    if (existingSection && bodyIds.length === 1) {
+      // Single Section — ensure it has a Column wrapper
+      ensureSectionColumn(existingSection, context);
+      cardChildren.push(existingSection);
+    } else {
+      // Wrap body in Section > Column
+      const colId = generateId('Column', null, context.usedIds);
+      context.components.push({ id: colId, component: 'Column', children: bodyIds });
+
+      const secId = generateId('Section', null, context.usedIds);
+      context.components.push({ id: secId, component: 'Section', children: [colId] });
+      cardChildren.push(secId);
+    }
+  }
+
+  // ── Build Footer ──
+  if (footerIds.length > 0) {
+    // Check if there's already a Footer component among them
+    const existingFooter = footerIds.find(id => context.components.find(c => c.id === id)?.component === 'Footer');
+    if (existingFooter) {
+      cardChildren.push(existingFooter);
+    } else {
+      const ftrId = generateId('Footer', null, context.usedIds);
+      context.components.push({ id: ftrId, component: 'Footer', children: footerIds });
+      cardChildren.push(ftrId);
+    }
+  }
+
+  const card = { id: cardId, component: 'Card', ...cardProps };
+  if (cardChildren.length > 0) card.children = cardChildren;
+  context.components.push(card);
+  return cardId;
+}
+
+/**
+ * Ensure a Section component has a Column wrapper for its children.
+ * If the Section's children are not wrapped in a Column, insert one.
+ */
+function ensureSectionColumn(sectionId, context) {
+  const section = context.components.find(c => c.id === sectionId);
+  if (!section || !section.children?.length) return;
+
+  // Already has a Column as direct child — good
+  const firstChild = context.components.find(c => c.id === section.children[0]);
+  if (firstChild?.component === 'Column') return;
+
+  // Wrap all children in a Column
+  const colId = generateId('Column', null, context.usedIds);
+  context.components.push({ id: colId, component: 'Column', children: [...section.children] });
+  section.children = [colId];
+}
+
+// ═══════════════════════════════════════════════════════════════
+// LAYER 2: STRUCTURE INFERENCE
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Infer the A2UI type for a div/span based on its structure and inline styles.
+ *
+ * @param {MinimalElement} el
+ * @returns {{ type: string, props?: Record<string, unknown> }}
+ */
+function inferStructure(el) {
+  const style = parseInlineStyle(el.getAttribute('style') || '');
+  const display = style.get('display') || '';
+  const flexDir = style.get('flex-direction') || '';
+  const flexWrap = style.get('flex-wrap') || '';
+  const tag = (el.tagName || '').toLowerCase();
+
+  // Grid
+  if (display.includes('grid')) {
+    const cols = style.get('grid-template-columns') || '';
+    const colCount = cols ? cols.split(/\s+/).filter(s => s && s !== 'auto').length : 0;
+    return { type: 'Grid', props: colCount > 0 ? { columns: String(colCount) } : {} };
+  }
+
+  // Flex row
+  if (display.includes('flex') && (flexDir === 'row' || flexDir === '' || !flexDir)) {
+    const gap = style.get('gap') || style.get('column-gap') || '';
+    const props = {};
+    if (gap) props.gap = inferGap(gap);
+    if (flexWrap === 'wrap') props.wrap = true;
+    return { type: 'Row', props };
+  }
+
+  // Flex column
+  if (display.includes('flex') && flexDir === 'column') {
+    const gap = style.get('gap') || style.get('row-gap') || '';
+    const props = {};
+    if (gap) props.gap = inferGap(gap);
+    return { type: 'Column', props };
+  }
+
+  // Has header + footer children → Card
+  const children = el.children || [];
+  const childTags = children.map(c => (c.tagName || '').toLowerCase());
+  if (childTags.includes('header') && childTags.includes('footer')) {
+    return { type: 'Card' };
+  }
+  if (childTags.includes('header') || childTags.some(t => /^h[1-6]$/.test(t))) {
+    return { type: 'Card' };
+  }
+
+  // Text-only div
+  const hasElementChildren = children.some(c => c.tagName);
+  if (!hasElementChildren) {
+    const text = (el.textContent || '').trim();
+    if (text) return { type: 'Text', props: { variant: 'body' } };
+  }
+
+  // Span defaults to Text
+  if (tag === 'span') {
+    return { type: 'Text', props: { variant: 'body' } };
+  }
+
+  // Default div → Column
+  return { type: 'Column' };
+}
+
+// ═══════════════════════════════════════════════════════════════
+// LAYER 3: LLM REASONING
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Run the LLM reasoning pass on HTML that scored low in instant mode.
+ *
+ * @param {string} html — Original HTML
+ * @param {object[]} instantMessages — Instant mode result
+ * @param {object} validation — Instant mode validation
+ * @param {object} llmAdapter — LLM adapter instance
+ * @returns {Promise<object[]|null>} — Improved A2UI messages, or null
+ */
+async function reasoningPass(html, instantMessages, validation, llmAdapter) {
+  const context = getContext('convert html', 2);
+  const failedChecks = validation.checks?.filter(c => !c.passed) || [];
+
+  const systemPrompt = buildTranspilerPrompt(context);
+  const userPrompt = `Convert this HTML to A2UI flat adjacency components:\n\n${html}\n\n`
+    + (failedChecks.length > 0
+      ? `The instant conversion had these issues:\n${failedChecks.map(c => `- ${c.name}: ${c.detail}`).join('\n')}\n\nFix these issues in your output.`
+      : '');
+
+  const response = await llmAdapter.complete({
+    messages: [{ role: 'user', content: userPrompt }],
+    systemPrompt,
+  });
+
+  return parseA2UIResponse(response.content);
+}
+
+/**
+ * Build the LLM system prompt for HTML → A2UI conversion.
+ */
+function buildTranspilerPrompt(context) {
+  const parts = [];
+
+  parts.push(`You are an A2UI transpiler. Convert HTML markup into A2UI flat adjacency components.
+Output ONLY a valid JSON array. No markdown fences, no explanation.
+
+Output: [{ "type": "updateComponents", "surfaceId": "default", "components": [...] }]
+Each component: { "id": "<unique>", "component": "<A2UIType>", "children": ["<id>", ...], ...props }
+Root must have id "root".
+
+RULES:
+- Use ONLY registered A2UI types (never raw HTML tags like div, span, input, form)
+- Card anatomy: Card > Header + Section + Footer. Section > Column > content.
+- Header children: use Text with variant h3/h4 for title (+ data-heading="section"), variant caption for subtitle. Card CSS auto-targets native heading/small — no slot="heading" needed. Only action buttons need slot="action".
+- Text: variant h1-h6 for headings, body for paragraphs, caption for small text
+- TextField for text inputs, ChoicePicker for selects, CheckBox for checkboxes
+- Button: text prop for label, variant primary/outline/ghost/danger
+- Preserve all text content, form field names, placeholders, image src/alt`);
+
+  if (context.components?.length > 0) {
+    const catalog = context.components.map(c => {
+      const props = Array.isArray(c.properties)
+        ? c.properties.map(p => typeof p === 'string' ? p : p.name).join(', ')
+        : '';
+      return `- ${c.type}: ${props || '(no props)'}`;
+    }).join('\n');
+    parts.push(`AVAILABLE TYPES:\n${catalog}`);
+  }
+
+  return parts.join('\n\n');
+}
+
+// ═══════════════════════════════════════════════════════════════
+// HTML PARSER (lightweight, Node.js compatible)
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * @typedef {object} MinimalElement
+ * @property {string} tagName
+ * @property {Map<string, string>} attributes
+ * @property {MinimalElement[]} children
+ * @property {string} textContent
+ * @property {(name: string) => string|null} getAttribute
+ */
+
+const SELF_CLOSING = new Set([
+  'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
+  'link', 'meta', 'param', 'source', 'track', 'wbr',
+]);
+
+/**
+ * Parse an HTML string into a minimal element tree.
+ * Not a full HTML parser — handles common patterns for transpilation.
+ *
+ * @param {string} html
+ * @returns {MinimalElement}
+ */
+export function parseHTMLMinimal(html) {
+  // Strip doctype, comments
+  let src = html.replace(/<!DOCTYPE[^>]*>/gi, '').replace(/<!--[\s\S]*?-->/g, '').trim();
+
+  // If wrapped in <html>, extract <body> content
+  const bodyMatch = src.match(/<body[^>]*>([\s\S]*)<\/body>/i);
+  if (bodyMatch) src = bodyMatch[1].trim();
+
+  // Parse into tokens
+  const tokens = tokenize(src);
+
+  // Build tree
+  const root = { tagName: '', attributes: new Map(), children: [], textContent: '' };
+  root.getAttribute = (name) => root.attributes.get(name) ?? null;
+
+  const stack = [root];
+
+  for (const token of tokens) {
+    const parent = stack[stack.length - 1];
+
+    if (token.type === 'text') {
+      const text = token.value.trim();
+      if (text) {
+        parent.children.push({
+          tagName: '',
+          attributes: new Map(),
+          children: [],
+          textContent: text,
+          getAttribute: () => null,
+        });
+      }
+    } else if (token.type === 'open') {
+      const el = {
+        tagName: token.tag,
+        attributes: token.attrs,
+        children: [],
+        textContent: '',
+        getAttribute(name) { return this.attributes.get(name) ?? null; },
+      };
+      parent.children.push(el);
+
+      if (!SELF_CLOSING.has(token.tag) && !token.selfClose) {
+        stack.push(el);
+      }
+    } else if (token.type === 'close') {
+      // Pop stack until we find the matching open tag
+      for (let i = stack.length - 1; i > 0; i--) {
+        if (stack[i].tagName === token.tag) {
+          // Compute textContent for the closed element
+          stack[i].textContent = getTextContent(stack[i]);
+          stack.length = i;
+          break;
+        }
+      }
+    }
+  }
+
+  // Compute textContent for root
+  root.textContent = getTextContent(root);
+
+  // If root has exactly one child, return it directly
+  if (root.children.length === 1 && root.children[0].tagName) {
+    return root.children[0];
+  }
+
+  return root;
+}
+
+/**
+ * Tokenize HTML into open/close/text tokens.
+ */
+function tokenize(html) {
+  const tokens = [];
+  let i = 0;
+
+  while (i < html.length) {
+    if (html[i] === '<') {
+      // Closing tag
+      if (html[i + 1] === '/') {
+        const end = html.indexOf('>', i);
+        if (end === -1) break;
+        const tag = html.slice(i + 2, end).trim().toLowerCase();
+        tokens.push({ type: 'close', tag });
+        i = end + 1;
+      } else {
+        // Opening tag
+        const end = html.indexOf('>', i);
+        if (end === -1) break;
+        const content = html.slice(i + 1, end);
+        const selfClose = content.endsWith('/');
+        const clean = selfClose ? content.slice(0, -1).trim() : content.trim();
+
+        // Parse tag name and attributes
+        const spaceIdx = clean.search(/[\s/]/);
+        const tag = (spaceIdx === -1 ? clean : clean.slice(0, spaceIdx)).toLowerCase();
+        const attrStr = spaceIdx === -1 ? '' : clean.slice(spaceIdx).trim();
+        const attrs = parseAttributes(attrStr);
+
+        tokens.push({ type: 'open', tag, attrs, selfClose });
+        i = end + 1;
+      }
+    } else {
+      // Text content
+      const nextTag = html.indexOf('<', i);
+      const text = nextTag === -1 ? html.slice(i) : html.slice(i, nextTag);
+      if (text) tokens.push({ type: 'text', value: text });
+      i = nextTag === -1 ? html.length : nextTag;
+    }
+  }
+
+  return tokens;
+}
+
+/**
+ * Parse HTML attribute string into a Map.
+ */
+function parseAttributes(str) {
+  const attrs = new Map();
+  if (!str) return attrs;
+
+  const re = /([a-zA-Z_:][\w:.-]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|(\S+)))?/g;
+  let match;
+  while ((match = re.exec(str))) {
+    const name = match[1].toLowerCase();
+    const value = match[2] ?? match[3] ?? match[4] ?? '';
+    attrs.set(name, value);
+  }
+
+  return attrs;
+}
+
+/**
+ * Recursively get text content from a minimal element.
+ */
+function getTextContent(el) {
+  if (!el.children || el.children.length === 0) {
+    return el.textContent || '';
+  }
+  return el.children.map(c => c.textContent || getTextContent(c)).join(' ').replace(/\s+/g, ' ').trim();
+}
+
+// ═══════════════════════════════════════════════════════════════
+// HELPERS
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Parse an inline style attribute into a Map.
+ */
+function parseInlineStyle(style) {
+  const map = new Map();
+  if (!style) return map;
+  for (const decl of style.split(';')) {
+    const colon = decl.indexOf(':');
+    if (colon === -1) continue;
+    const prop = decl.slice(0, colon).trim().toLowerCase();
+    const value = decl.slice(colon + 1).trim();
+    if (prop && value) map.set(prop, value);
+  }
+  return map;
+}
+
+/**
+ * Generate a unique, semantic ID for an A2UI component.
+ */
+function generateId(type, el, usedIds) {
+  // Try semantic hints
+  const candidates = [
+    el?.getAttribute?.('id'),
+    el?.getAttribute?.('name'),
+    el?.getAttribute?.('aria-label'),
+  ].filter(Boolean);
+
+  for (const hint of candidates) {
+    const id = slugify(hint);
+    if (id && !usedIds.has(id)) {
+      usedIds.add(id);
+      return id;
+    }
+  }
+
+  // Fallback: type-based with counter
+  const base = slugify(type);
+  let id = base;
+  let counter = 1;
+  while (usedIds.has(id)) {
+    id = `${base}-${++counter}`;
+  }
+  usedIds.add(id);
+  return id;
+}
+
+/**
+ * Convert a string to a kebab-case slug suitable for IDs.
+ */
+function slugify(str) {
+  if (!str) return '';
+  return str
+    .replace(/([a-z])([A-Z])/g, '$1-$2')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, 30);
+}
+
+/**
+ * Create a fallback A2UI message array with wired retry button.
+ * @returns {object[]} Array of A2UI messages (updateComponents + wireComponents)
+ */
+function fallbackMessage(reason) {
+  const updateMsg = {
+    type: 'updateComponents',
+    surfaceId: 'default',
+    components: [
+      { id: 'root', component: 'Card', children: ['sec', 'ftr'] },
+      { id: 'sec', component: 'Section', children: ['alert'] },
+      { id: 'alert', component: 'Alert', variant: 'error', title: 'Conversion Error', description: reason },
+      { id: 'ftr', component: 'Footer', children: ['retry'] },
+      { id: 'retry', component: 'Button', text: 'Try Again', icon: 'arrow-clockwise', variant: 'primary' },
+    ],
+  };
+
+  const wireMsg = {
+    type: 'wireComponents',
+    surfaceId: 'default',
+    actions: [
+      {
+        event: { event: 'press', target: 'retry' },
+        handler: 'emit-event',
+        config: { eventName: 'a2ui-retry', detail: { source: 'transpiler' } },
+      },
+    ],
+  };
+
+  return [updateMsg, wireMsg];
+}
+
+/**
+ * Parse an LLM response string into A2UI messages (reused from generator pattern).
+ */
+function parseA2UIResponse(content) {
+  if (!content || typeof content !== 'string') return null;
+
+  let json = content.trim();
+  const fenceMatch = json.match(/```(?:json)?\s*\n?([\s\S]*?)```/);
+  if (fenceMatch) json = fenceMatch[1].trim();
+
+  try {
+    const parsed = JSON.parse(json);
+    if (Array.isArray(parsed)) {
+      if (parsed[0]?.type === 'updateComponents') return parsed;
+      if (parsed[0]?.id && parsed[0]?.component) {
+        return [{ type: 'updateComponents', surfaceId: 'default', components: parsed }];
+      }
+    }
+    if (parsed?.type === 'updateComponents') return [parsed];
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Generate suggestions based on the transpilation result.
+ */
+function generateSuggestions(html, components, validation) {
+  const suggestions = [];
+  const types = new Set(components.map(c => c.component));
+
+  // Check for raw HTML that couldn't be converted
+  if (html.includes('<svg')) {
+    suggestions.push('SVG elements were skipped — use icon-ui for icons or image-ui for illustrations');
+  }
+
+  if (!types.has('Card') && components.length > 3) {
+    suggestions.push('Consider wrapping in a Card for proper container semantics');
+  }
+
+  if (types.has('Section') && !components.some(c => c.component === 'Section' && c.children?.some(id => {
+    const child = components.find(x => x.id === id);
+    return child?.component === 'Column';
+  }))) {
+    suggestions.push('Section content should be wrapped in Column');
+  }
+
+  if (html.includes('style=') && (html.includes('#') || html.includes('rgb'))) {
+    suggestions.push('Source HTML contained hardcoded colors — A2UI output uses design tokens');
+  }
+
+  if (validation.score < 85) {
+    suggestions.push('Try "reasoning" mode for better structure inference');
+  }
+
+  if (components.some(c => ['TextField', 'CheckBox', 'Radio'].includes(c.component) && !c.label)) {
+    suggestions.push('Add label prop to form fields for accessibility');
+  }
+
+  return suggestions.slice(0, 4);
+}