@adia-ai/gen-ui 0.8.37

package/compose/transpiler/transpiler.js

@@ -0,0 +1,962 @@
+/**
+ * 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 '@adia-ai/a2ui/validate';
+import { getContext } from '../core/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']
+ * @param {'silent'|'placeholder'} [options.unknownTagPolicy='silent'] — how an
+ *   unregistered custom-element tag degrades. `silent` keeps the historical
+ *   bare-container conversion (children preserved, props dropped); the caller
+ *   is expected to act on the returned `unmappedTags`. `placeholder` ALSO
+ *   emits a visible, semantically-tokened notice naming the tag — for
+ *   surfaces whose only channel to a human is the rendered page. See gh#848.
+ * @returns {Promise<{ messages: object[], validation: object, suggestions: string[], unmappedTags: string[] }>}
+ */
+export async function transpileHTML(html, options = {}) {
+  const { mode = 'instant', llmAdapter, surfaceId = 'default', unknownTagPolicy = 'silent' } = 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'],
+      unmappedTags: [],
+    };
+  }
+
+  // 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,
+    // gh#848 — every tag that reached the Unknown fallback, so NO caller has
+    // to rediscover the degrade by eyeballing the output.
+    unmappedTags: new Set(),
+    unknownTagPolicy,
+  };
+
+  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);
+  const unmappedTags = [...context.unmappedTags].sort();
+
+  // 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),
+            unmappedTags,
+          };
+        }
+      }
+    } catch {
+      // Keep instant result on LLM failure
+    }
+  }
+
+  return { messages, validation, suggestions, unmappedTags };
+}
+
+/**
+ * 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 = {};
+  let isUnknown = false;
+
+  // 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), NEVER silently (gh#848)
+  else {
+    a2uiType = 'Column';
+    isUnknown = true;
+  }
+
+  // ── 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 };
+
+  // ── Unknown tag: report always, degrade visibly on demand (gh#848) ──
+  // The old behavior was a bare Column with the element's props dropped and
+  // NOTHING said anywhere — a childless custom element (the common case for
+  // a data-driven composite like `<admin-roster-ui>`) became a literally
+  // empty box, and 24 site pages shipped blank sections for four days.
+  // Reporting is unconditional; the visible placeholder is opt-in because
+  // the corpus harvester and the zettel chunk-synthesizer feed REUSABLE
+  // composition templates, where an injected developer notice would travel
+  // into generated product UI.
+  if (isUnknown && el.tagName) {
+    context.unmappedTags?.add(tag);
+    if (context.unknownTagPolicy === 'placeholder') {
+      return emitUnmappedPlaceholder(el, id, tag, props, context);
+    }
+  }
+
+  // ── Handle children ──
+
+  // ChoicePicker / Select, Combobox, Command carry their <option>/<optgroup>
+  // children as an `options` prop (built in extractProps), not as child
+  // components. Recursing the <option>s would emit Text nodes that
+  // <select-ui>/<combobox-ui>/<command-ui> reject — renders empty +
+  // "ignoring unrecognized child" warning (FB-79; extended to Combobox per
+  // gh#860, to Command per gh#887). Treat as a self-contained leaf.
+  if (a2uiType === 'ChoicePicker' || a2uiType === 'Combobox' || a2uiType === 'Command') {
+    context.components.push({ id, component: a2uiType, ...props });
+    return id;
+  }
+
+  // Leaf types: these render their own text, don't recurse into children.
+  // Tag joined 2026-07-12 (TKT-0004): tag-ui renders its label via CSS
+  // attr(text) — as a container, its light-DOM label became a child Text
+  // at body size, inflating every converted chip site-wide (581 instances
+  // across 233 pages measured).
+  const LEAF_TYPES = new Set([
+    'Text', 'Button', 'Kbd', 'Code', 'Badge', 'Tag', 'Image', 'Divider',
+    'TextField', 'CheckBox', 'Toggle', 'Radio', 'Slider', 'Search',
+    'Upload', 'ColorPicker', 'DateTimeInput', 'TextArea', 'OtpInput',
+  ]);
+
+  if (LEAF_TYPES.has(a2uiType)) {
+    // Leaf types still need to carry slotted or container children in two
+    // shapes:
+    //
+    // (1) Trailing icons / kbd shortcuts inside Button:
+    //     `<button-ui text="Next"><icon-ui slot="trailing" name="caret-right">`
+    // (2) Slotted container wrappers that themselves transpile to a leaf
+    //     type but hold inline child elements:
+    //     `<span slot="heading"><text-ui strong>Title</text-ui> <badge-ui>...`
+    //     The span maps to Text via HTML_TAG_MAP, but it functions as a
+    //     flex container (per card.css `> [slot="heading"]`) and needs
+    //     to keep its children.
+    //
+    // Rule: if the element has ANY element children, recurse all of them.
+    // Pure text leaves (no element children) keep the text-prop path.
+    const elementChildren = (el.children || []).filter(c => c.tagName);
+    if (elementChildren.length === 0) {
+      context.components.push({ id, component: a2uiType, ...props });
+      return id;
+    }
+    // When a leaf has element children, the auto-extracted textContent prop
+    // would be the CONCATENATED descendant text (e.g.
+    //   <text-ui>$49<text-ui>/month</text-ui></text-ui>
+    // has textContent "$49/month"), causing every label to render twice
+    // alongside the child components. Replace it with the element's DIRECT
+    // text nodes only — text the element OWNS, not what its children own.
+    // The minimal HTML parser represents text nodes as pseudo-elements
+    // with tagName === '' inside the children array.
+    const directText = (el.children || [])
+      .filter(n => !n.tagName)
+      .map(n => n.textContent || '')
+      .join(' ').replace(/\s+/g, ' ').trim();
+    const containerProps = { ...props };
+    if (directText) {
+      // Preserve the direct text on whichever prop the type uses
+      if (a2uiType === 'Text' || a2uiType === 'Kbd' || a2uiType === 'Code') containerProps.textContent = directText;
+      else if (a2uiType === 'Button' || a2uiType === 'Badge' || a2uiType === 'Tag') {
+        if (containerProps.text === undefined) containerProps.text = directText;
+      }
+    } else {
+      delete containerProps.textContent;
+      delete containerProps.text;
+    }
+    const childIds = [];
+    for (const child of elementChildren) {
+      const childId = walkNode(child, context);
+      if (childId) childIds.push(childId);
+    }
+    context.components.push({ id, component: a2uiType, ...containerProps, children: childIds });
+    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;
+}
+
+/**
+ * gh#848 — the VISIBLE degrade for an unregistered component tag.
+ *
+ * Emits `Column[data-unmapped-tag] > Alert(warning) + <the element's own
+ * converted children>`. Three properties this shape must keep:
+ *   - it is built from REGISTERED constructs only (Column, Alert), so the
+ *     wire payload stays valid — validator.js's `allTypesRegistered` check
+ *     passes and the renderer resolves both through `resolveTag`;
+ *   - it carries NO raw CSS: alert-ui's `warning` variant is entirely
+ *     semantic-token driven (alert.css), so the notice themes with the page;
+ *   - it preserves the element's children, so nothing authored is lost —
+ *     only the unmapped element's OWN props are (they always were).
+ *
+ * `data-unmapped-tag` is the machine-readable half: a build gate or a
+ * browser probe can select `[data-unmapped-tag]` without parsing prose.
+ */
+function emitUnmappedPlaceholder(el, id, tag, props, context) {
+  const noticeId = generateId('Alert', el, context.usedIds);
+
+  const childIds = [];
+  for (const child of (el.children || [])) {
+    if (!child.tagName && !(child.textContent || '').trim()) continue;
+    const childId = walkNode(child, context);
+    if (childId) childIds.push(childId);
+  }
+
+  context.components.push({
+    id,
+    component: 'Column',
+    gap: 'sm',
+    'data-unmapped-tag': tag,
+    ...props,
+    children: [noticeId, ...childIds],
+  });
+  context.components.push({
+    id: noticeId,
+    component: 'Alert',
+    variant: 'warning',
+    icon: 'warning',
+    // title + description is alert.yaml's documented two-line shape
+    // ("headline + body"); `text` is the single-line alternative, not a
+    // companion to `title`.
+    title: `Unmapped component: <${tag}>`,
+    description: `No entry in the A2UI runtime registry (packages/a2ui/registry.js), so this element's own props and behaviour were not converted. Register the tag, or remove it from the source.`,
+  });
+
+  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);
+}