@adia-ai/a2ui 0.8.37

package/validate/validator.js

@@ -0,0 +1,1232 @@
+/**
+ * A2UI Schema Validator — 15 quality checks with weighted scoring.
+ *
+ * Validates A2UI message sequences against structural rules from the
+ * best-practices spec. Each check returns { name, passed, score, detail }.
+ * Final score is a weighted average (0-100). Valid if score >= 70.
+ *
+ * No DOM dependencies — usable from browser and Node.
+ */
+
+// Intra-package import (ADR-0048 P3): the runtime IS this package's root, so
+// the validator's only dependency is a relative one — which is what lets
+// @adia-ai/a2ui ship with zero `dependencies`.
+// Imported from the two leaf modules, not the `../index.js` barrel: that
+// barrel pulls in renderer.js/surface.js, and this module's contract is
+// "no DOM dependencies" (see the docstring above).
+import { registry } from '../registry.js';
+import { wiringRegistry } from '../wiring-registry.js';
+
+// ── Check weights (must sum to 100 for component checks) ──
+
+const WEIGHTS = {
+  validMessageFormat:   8,
+  hasRootComponent:     6,
+  allTypesRegistered:   8,
+  noOrphanedChildren:   8,
+  cardStructure:        5,
+  flatAdjacency:        4,
+  noBareDivs:           6,
+  noHardcodedColors:    2,
+  noInlineLayout:       4,
+  textContentSet:       4,
+  idUniqueness:         4,
+  interactiveHasLabel:  4,
+  imagesHaveAlt:        2,
+  headingHierarchy:     2,
+  tabStructure:         2,
+  gridVsColumn:         2,
+  landmarkStructure:    2,
+  intentAlignment:      7,
+  ontologyAlignment:   15,
+  componentsHaveRenderableContent: 5,  // §165 (v0.5.4) — the 3rd safety layer
+};
+
+/**
+ * Validate an A2UI message sequence.
+ *
+ * @param {object[]} messages — Array of A2UI messages (e.g. updateComponents)
+ * @param {{ intent?: string }} [options] — Optional validation context
+ * @returns {{ score: number, checks: object[], valid: boolean }}
+ */
+export function validateSchema(messages, options = {}) {
+  if (!Array.isArray(messages) || messages.length === 0) {
+    return {
+      score: 0,
+      checks: [{ name: 'validMessageFormat', passed: false, score: 0, detail: 'No messages provided' }],
+      valid: false,
+    };
+  }
+
+  // ── Fallback short-circuit ──
+  // The pipeline emits a structurally-valid Card+Alert+Button surface when the
+  // LLM call fails, returns empty, or produces unparseable output. That surface
+  // would otherwise score ~89/100 because it passes every structural check —
+  // making generation failures look like successful generations and silently
+  // poisoning eval baselines. Detected via the `_fallback: true` marker stamped
+  // by `fallbackMessage()` in engines/monolithic/_shared.js.
+  // See diagnosis report 2026-04-19.
+  const fallbackMsg = messages.find(m => m && m._fallback === true);
+  if (fallbackMsg) {
+    return {
+      score: 0,
+      checks: [{
+        name: 'fallbackSurface',
+        passed: false,
+        score: 0,
+        detail: `Generation failure surface: ${fallbackMsg._fallbackReason || 'unknown reason'}`,
+      }],
+      valid: false,
+      isFallback: true,
+      fallbackReason: fallbackMsg._fallbackReason || null,
+    };
+  }
+
+  // Collect all components across all updateComponents messages
+  const allComponents = [];
+  for (const msg of messages) {
+    if (msg?.type === 'updateComponents' && Array.isArray(msg.components)) {
+      for (const c of msg.components) {
+        if (c && typeof c === 'object') allComponents.push(c);
+      }
+    }
+  }
+
+  // Collect wireComponents messages
+  const wireMessages = messages.filter(m => m?.type === 'wireComponents');
+
+  const checks = [
+    checkValidMessageFormat(messages),
+    checkHasRootComponent(allComponents),
+    checkAllTypesRegistered(allComponents),
+    checkNoOrphanedChildren(allComponents),
+    checkCardStructure(allComponents),
+    checkFlatAdjacency(messages),
+    checkNoBareDivs(allComponents),
+    checkNoHardcodedColors(allComponents),
+    checkNoInlineLayout(allComponents),
+    checkTextContentSet(allComponents),
+    checkIdUniqueness(allComponents),
+    checkInteractiveHasLabel(allComponents),
+    checkComponentsHaveRenderableContent(allComponents),
+    checkImagesHaveAlt(allComponents),
+    checkHeadingHierarchy(allComponents),
+    checkTabStructure(allComponents),
+    checkGridVsColumn(allComponents),
+    checkLandmarkStructure(allComponents),
+    checkIntentAlignment(allComponents, options.intent),
+    checkOntologyAlignment(allComponents, options.context),
+  ];
+
+  // Wiring checks (only scored when wireComponents present)
+  if (wireMessages.length > 0) {
+    const componentIds = new Set(allComponents.map(c => c.id));
+    for (const wire of wireMessages) {
+      checks.push(...checkWiring(wire, componentIds));
+    }
+  }
+
+  // Weighted score (component checks only — wiring checks reported but don't affect score)
+  let score = 0;
+  for (const check of checks) {
+    const weight = WEIGHTS[check.name] || 0;
+    score += (check.score * weight) / 100;
+  }
+
+  // Normalize to 0-100
+  score = Math.round(score * 100);
+
+  // Hard-fail: bare HTML elements or unregistered types mean the output is fundamentally wrong
+  const hardFails = ['noBareDivs', 'allTypesRegistered', 'hasRootComponent', 'tabStructure', 'ontologyAlignment'];
+  const hasHardFail = checks.some(c => hardFails.includes(c.name) && !c.passed);
+
+  // Severe intent mismatch: if intentAlignment score < 0.3 and intent was provided,
+  // apply a penalty multiplier to the total score — wrong pattern is fundamentally wrong
+  const intentCheck = checks.find(c => c.name === 'intentAlignment');
+  if (intentCheck && intentCheck.score < 0.3 && options.intent) {
+    // Scale the total score down: a 0.17 intent score → multiplier ~0.42
+    const intentPenalty = 0.25 + (intentCheck.score * 2.5); // range 0.25-1.0
+    score = Math.round(score * intentPenalty);
+  }
+
+  return {
+    score,
+    checks,
+    valid: score >= 70 && !hasHardFail,
+  };
+}
+
+// ── Individual checks ──
+
+/**
+ * 1. validMessageFormat — each message has `type` and required fields.
+ */
+function checkValidMessageFormat(messages) {
+  const issues = [];
+
+  for (let i = 0; i < messages.length; i++) {
+    const msg = messages[i];
+    if (!msg || typeof msg !== 'object') {
+      issues.push(`Message ${i}: not an object`);
+      continue;
+    }
+    if (!msg.type) {
+      issues.push(`Message ${i}: missing "type" field`);
+      continue;
+    }
+
+    if (msg.type === 'updateComponents') {
+      if (!msg.surfaceId) issues.push(`Message ${i}: updateComponents missing "surfaceId"`);
+      if (!Array.isArray(msg.components)) issues.push(`Message ${i}: updateComponents missing "components" array`);
+    } else if (msg.type === 'updateDataModel') {
+      if (!msg.surfaceId) issues.push(`Message ${i}: updateDataModel missing "surfaceId"`);
+      if (msg.data === undefined && msg.model === undefined) issues.push(`Message ${i}: updateDataModel missing "data" or "model"`);
+    }
+    // Unknown message types are allowed (extensibility)
+  }
+
+  const passed = issues.length === 0;
+  return {
+    name: 'validMessageFormat',
+    passed,
+    score: passed ? 1 : Math.max(0, 1 - issues.length / messages.length),
+    detail: passed ? 'All messages have valid format' : issues.join('; '),
+  };
+}
+
+/**
+ * 2. hasRootComponent — at least one component with id: 'root'.
+ */
+function checkHasRootComponent(components) {
+  const hasRoot = components.some(c => c.id === 'root');
+  return {
+    name: 'hasRootComponent',
+    passed: hasRoot,
+    score: hasRoot ? 1 : 0,
+    detail: hasRoot ? 'Root component found' : 'No component with id "root" found',
+  };
+}
+
+/**
+ * 3. allTypesRegistered — all component types exist in the AdiaUI registry.
+ */
+function checkAllTypesRegistered(components) {
+  const unregistered = [];
+
+  // Native card children that are valid but not in the main registry lookup
+  const nativeTypes = new Set(['Section', 'Header', 'Footer']);
+
+  for (const comp of components) {
+    const type = comp.component;
+    if (!type) continue;
+    if (nativeTypes.has(type)) continue;
+    if (!registry.has(type)) {
+      unregistered.push(`"${type}" (id: ${comp.id})`);
+    }
+  }
+
+  const passed = unregistered.length === 0;
+  return {
+    name: 'allTypesRegistered',
+    passed,
+    score: passed ? 1 : Math.max(0, 1 - unregistered.length / Math.max(1, components.length)),
+    detail: passed ? 'All component types are registered' : `Unregistered types: ${unregistered.join(', ')}`,
+  };
+}
+
+/**
+ * 4. noOrphanedChildren — all IDs referenced in children arrays exist.
+ */
+function checkNoOrphanedChildren(components) {
+  const ids = new Set(components.map(c => c.id));
+  const orphans = [];
+
+  for (const comp of components) {
+    if (!Array.isArray(comp.children)) continue;
+    for (const childId of comp.children) {
+      if (!ids.has(childId)) {
+        orphans.push(`"${childId}" referenced by "${comp.id}"`);
+      }
+    }
+  }
+
+  const passed = orphans.length === 0;
+  return {
+    name: 'noOrphanedChildren',
+    passed,
+    score: passed ? 1 : Math.max(0, 1 - orphans.length / Math.max(1, components.length)),
+    detail: passed ? 'All child references resolve' : `Orphaned children: ${orphans.join(', ')}`,
+  };
+}
+
+/**
+ * 5. cardStructure — Cards have header/section/footer as direct children.
+ *
+ * Checks:
+ * - Card children should only be Header, Section, or Footer
+ * - Header and Footer should not be nested inside Section
+ * - Section content should be wrapped in Column
+ */
+function checkCardStructure(components) {
+  const byId = new Map(components.map(c => [c.id, c]));
+  const issues = [];
+
+  for (const comp of components) {
+    if (comp.component !== 'Card') continue;
+    if (!Array.isArray(comp.children)) continue;
+
+    for (const childId of comp.children) {
+      const child = byId.get(childId);
+      if (!child) continue;
+
+      const childType = child.component;
+      if (!['Header', 'Section', 'Footer'].includes(childType)) {
+        issues.push(`Card "${comp.id}" has direct child "${childId}" of type "${childType}" (expected Header/Section/Footer)`);
+      }
+    }
+
+    // Check that Sections don't contain Header or Footer
+    for (const childId of comp.children) {
+      const child = byId.get(childId);
+      if (!child || child.component !== 'Section') continue;
+      if (!Array.isArray(child.children)) continue;
+
+      for (const sectionChildId of child.children) {
+        const sectionChild = byId.get(sectionChildId);
+        if (!sectionChild) continue;
+        if (['Header', 'Footer'].includes(sectionChild.component)) {
+          issues.push(`Section "${childId}" contains "${sectionChild.component}" — must be direct child of Card`);
+        }
+      }
+    }
+  }
+
+  const passed = issues.length === 0;
+  const cardCount = components.filter(c => c.component === 'Card').length;
+  return {
+    name: 'cardStructure',
+    passed,
+    score: cardCount === 0 ? 1 : (passed ? 1 : Math.max(0, 1 - issues.length / Math.max(1, cardCount))),
+    detail: passed ? (cardCount === 0 ? 'No cards to validate' : 'Card structure is correct') : issues.join('; '),
+  };
+}
+
+/**
+ * 6. flatAdjacency — components are a flat list with ID references.
+ *
+ * Checks that updateComponents messages contain a flat array, not nested objects.
+ */
+function checkFlatAdjacency(messages) {
+  const issues = [];
+
+  for (const msg of messages) {
+    if (!msg || typeof msg !== 'object') continue;
+    if (msg.type !== 'updateComponents') continue;
+    if (!Array.isArray(msg.components)) continue;
+
+    for (let i = 0; i < msg.components.length; i++) {
+      const comp = msg.components[i];
+      if (!comp || typeof comp !== 'object') continue;
+
+      // Children should be string IDs, not nested objects
+      if (Array.isArray(comp.children)) {
+        for (const child of comp.children) {
+          if (typeof child !== 'string') {
+            issues.push(`Component "${comp.id}" has non-string child in children array`);
+            break;
+          }
+        }
+      }
+    }
+  }
+
+  const passed = issues.length === 0;
+  return {
+    name: 'flatAdjacency',
+    passed,
+    score: passed ? 1 : 0,
+    detail: passed ? 'All components use flat adjacency (string ID references)' : issues.join('; '),
+  };
+}
+
+/**
+ * 7. noBareDivs — no component: 'div' or other raw HTML tags.
+ */
+function checkNoBareDivs(components) {
+  const bareTypes = new Set(['div', 'span', 'main', 'aside', 'article', 'nav', 'ul', 'ol', 'li', 'table', 'tr', 'td', 'th']);
+  const offenders = [];
+
+  for (const comp of components) {
+    const type = comp.component;
+    if (!type) continue;
+    // Registered A2UI types are exempt: the lowercase collision used to
+    // hard-fail every document containing the legitimate `Nav` or `Table`
+    // constructs (they lowercase onto the bare-HTML set).
+    if (registry.has(type)) continue;
+    if (bareTypes.has(type.toLowerCase())) {
+      offenders.push(`"${type}" (id: ${comp.id})`);
+    }
+  }
+
+  const passed = offenders.length === 0;
+  return {
+    name: 'noBareDivs',
+    passed,
+    score: passed ? 1 : 0,
+    detail: passed ? 'No bare HTML element types' : `Bare elements: ${offenders.join(', ')}`,
+  };
+}
+
+/**
+ * 8. noHardcodedColors — no inline style with color: or background:.
+ */
+function checkNoHardcodedColors(components) {
+  const pattern = /(?:^|;)\s*(?:color|background|background-color)\s*:/i;
+  const offenders = [];
+
+  for (const comp of components) {
+    if (typeof comp.style === 'string' && pattern.test(comp.style)) {
+      offenders.push(`"${comp.id}" has hardcoded color in style`);
+    }
+    // Also check style as object
+    if (comp.style && typeof comp.style === 'object') {
+      for (const key of Object.keys(comp.style)) {
+        const lower = key.toLowerCase().replace(/[A-Z]/g, m => '-' + m.toLowerCase());
+        if (['color', 'background', 'background-color'].includes(lower)) {
+          offenders.push(`"${comp.id}" has hardcoded "${key}" in style object`);
+        }
+      }
+    }
+  }
+
+  const passed = offenders.length === 0;
+  return {
+    name: 'noHardcodedColors',
+    passed,
+    score: passed ? 1 : Math.max(0, 1 - offenders.length / Math.max(1, components.length)),
+    detail: passed ? 'No hardcoded colors' : offenders.join('; '),
+  };
+}
+
+/**
+ * 9. noInlineLayout — no inline style with display:, flex:, or grid:.
+ */
+function checkNoInlineLayout(components) {
+  const pattern = /(?:^|;)\s*(?:display|flex|grid|flex-direction|justify-content|align-items|gap)\s*:/i;
+  const offenders = [];
+
+  for (const comp of components) {
+    if (typeof comp.style === 'string' && pattern.test(comp.style)) {
+      offenders.push(`"${comp.id}" has inline layout in style`);
+    }
+    if (comp.style && typeof comp.style === 'object') {
+      for (const key of Object.keys(comp.style)) {
+        const lower = key.toLowerCase().replace(/[A-Z]/g, m => '-' + m.toLowerCase());
+        if (['display', 'flex', 'grid', 'flex-direction', 'justify-content', 'align-items', 'gap'].includes(lower)) {
+          offenders.push(`"${comp.id}" has inline "${key}" in style object`);
+        }
+      }
+    }
+  }
+
+  const passed = offenders.length === 0;
+  return {
+    name: 'noInlineLayout',
+    passed,
+    score: passed ? 1 : Math.max(0, 1 - offenders.length / Math.max(1, components.length)),
+    detail: passed ? 'No inline layout styles' : offenders.join('; '),
+  };
+}
+
+/**
+ * 10. textContentSet — Text components with native variants use textContent or text.
+ *
+ * Text components with variant h1-h5, body, caption should have textContent or text set.
+ */
+function checkTextContentSet(components) {
+  const nativeVariants = new Set(['h1', 'h2', 'h3', 'h4', 'h5', 'body', 'caption']);
+  const issues = [];
+
+  for (const comp of components) {
+    if (comp.component !== 'Text') continue;
+    if (!comp.variant || !nativeVariants.has(comp.variant)) continue;
+
+    const hasContent = comp.textContent != null || comp.text != null;
+    if (!hasContent) {
+      issues.push(`Text "${comp.id}" (variant: ${comp.variant}) has no textContent or text`);
+    }
+  }
+
+  const textCount = components.filter(c => c.component === 'Text').length;
+  const passed = issues.length === 0;
+  return {
+    name: 'textContentSet',
+    passed,
+    score: textCount === 0 ? 1 : (passed ? 1 : Math.max(0, 1 - issues.length / Math.max(1, textCount))),
+    detail: passed ? (textCount === 0 ? 'No text components to validate' : 'All text components have content') : issues.join('; '),
+  };
+}
+
+/**
+ * 11. idUniqueness — all component IDs are unique within a surface.
+ */
+function checkIdUniqueness(components) {
+  const seen = new Map(); // id → count
+  for (const comp of components) {
+    if (!comp.id) continue;
+    seen.set(comp.id, (seen.get(comp.id) || 0) + 1);
+  }
+
+  const dupes = [];
+  for (const [id, count] of seen) {
+    if (count > 1) dupes.push(`"${id}" appears ${count} times`);
+  }
+
+  const passed = dupes.length === 0;
+  return {
+    name: 'idUniqueness',
+    passed,
+    score: passed ? 1 : Math.max(0, 1 - dupes.length / Math.max(1, seen.size)),
+    detail: passed ? 'All IDs are unique' : `Duplicate IDs: ${dupes.join(', ')}`,
+  };
+}
+
+/**
+ * 12. interactiveHasLabel — interactive components must carry an
+ * accessible name: text, label, textContent, or aria-label. aria-label
+ * joined 2026-07-12 (TKT-0003): rejecting it forced the docs-transpiler
+ * to propagate a VISIBLE `label` onto controls already labelled by their
+ * wrapping Field — every transpiled form rendered its labels twice
+ * ("Workspace name Workspace name"). An aria-label IS an accessible
+ * name; a control inside a labelled Field needs no second visible one.
+ */
+function checkInteractiveHasLabel(components) {
+  const interactiveTypes = new Set(['Button', 'TextField', 'Select', 'Toggle', 'Check', 'Slider', 'Search']);
+  const unlabeled = [];
+
+  for (const comp of components) {
+    if (!interactiveTypes.has(comp.component)) continue;
+    const hasLabel = comp.text != null || comp.label != null || comp.textContent != null
+      || comp['aria-label'] != null;
+    if (!hasLabel) {
+      unlabeled.push(`"${comp.id}"`);
+    }
+  }
+
+  const interactiveCount = components.filter(c => interactiveTypes.has(c.component)).length;
+  const passed = unlabeled.length === 0;
+  return {
+    name: 'interactiveHasLabel',
+    passed,
+    score: interactiveCount === 0 ? 1 : (passed ? 1 : Math.max(0, 1 - unlabeled.length / Math.max(1, interactiveCount))),
+    detail: passed
+      ? (interactiveCount === 0 ? 'No interactive components to validate' : 'All interactive components have labels')
+      : `Missing labels: ${unlabeled.join(', ')}`,
+  };
+}
+
+/**
+ * §165 (v0.5.4): componentsHaveRenderableContent — the 3rd safety layer.
+ *
+ * Catches the bug class diagnosed 2026-05-14 (commit `964885e70` postmortem):
+ * components that ARE registered (Layer 1 passes) AND structurally valid
+ * (Layer 2 passes) AND still render as blank rectangles because they have
+ * NO content-bearing props.
+ *
+ * Bug-class examples that this check catches:
+ *   { id: "password", component: "Input" }                          ← no label/placeholder
+ *   { id: "remember", component: "CheckBox", name: "remember" }     ← no label
+ *   { id: "btn-magic", component: "Button" }                        ← no text/icon
+ *   { id: "title", component: "Text" }                              ← no textContent
+ *   { id: "logo", component: "Image" }                              ← no src
+ *
+ * Broader scope than `interactiveHasLabel` (check #12):
+ *   - covers Input/CheckBox/Switch (the registry-aliased forms missed by #12's
+ *     `Check/Toggle` set)
+ *   - accepts icon-only buttons (with `icon` OR `aria-label`)
+ *   - accepts container nodes with children (Card/Section/Header pass on
+ *     structural-not-leaf grounds; the check enforces content for LEAF
+ *     interactive types)
+ *
+ * Score semantics: per-violation deduction. Each empty interactive primitive
+ * subtracts 1/total from the score. 0 violations = 1.0; all-empty = 0.
+ */
+function checkComponentsHaveRenderableContent(components) {
+  // Interactive types: must have at least one content-bearing prop OR be
+  // non-leaf (has children that provide content).
+  const INTERACTIVE_LEAF_TYPES = new Set([
+    'Button', 'Input', 'TextField', 'TextArea',
+    'CheckBox', 'Check', 'Toggle', 'Switch', 'Radio',
+    'Select', 'ChoicePicker', 'Slider', 'Range', 'Rating',
+    'Search', 'OtpInput', 'CalendarPicker', 'DateTimeInput',
+    'ColorPicker', 'Upload',
+  ]);
+  // Content-bearing props that satisfy the "renderable" requirement.
+  const CONTENT_PROPS = ['label', 'placeholder', 'text', 'aria-label',
+                          'icon', 'textContent', 'value', 'alt', 'src'];
+
+  const hasContent = (comp) => {
+    for (const k of CONTENT_PROPS) {
+      const v = comp[k];
+      if (v !== undefined && v !== null && v !== '') return true;
+    }
+    // Non-leaf interactives (e.g. CalendarPicker with named children) pass
+    if (Array.isArray(comp.children) && comp.children.length > 0) return true;
+    return false;
+  };
+
+  const violations = [];
+  let interactiveCount = 0;
+  for (const comp of components) {
+    if (!INTERACTIVE_LEAF_TYPES.has(comp.component)) continue;
+    interactiveCount++;
+    if (!hasContent(comp)) {
+      violations.push(`"${comp.id}" (${comp.component})`);
+    }
+  }
+
+  // Also check Text components — empty Text is a degenerate case worth surfacing.
+  // Text-specific: needs textContent OR children (Text + nested Strong etc.)
+  let textCount = 0;
+  let emptyTextCount = 0;
+  for (const comp of components) {
+    if (comp.component !== 'Text') continue;
+    textCount++;
+    const t = comp.textContent;
+    if ((t === undefined || t === null || t === '') &&
+        !(Array.isArray(comp.children) && comp.children.length > 0)) {
+      emptyTextCount++;
+      violations.push(`"${comp.id}" (Text: empty)`);
+    }
+  }
+
+  // Also check Image — needs src (catalog-mandatory)
+  let imageCount = 0;
+  let imageNoSrc = 0;
+  for (const comp of components) {
+    if (comp.component !== 'Image') continue;
+    imageCount++;
+    if (!comp.src) {
+      imageNoSrc++;
+      violations.push(`"${comp.id}" (Image: no src)`);
+    }
+  }
+
+  const total = interactiveCount + textCount + imageCount;
+  const passed = violations.length === 0;
+  return {
+    name: 'componentsHaveRenderableContent',
+    passed,
+    score: total === 0
+      ? 1
+      : (passed ? 1 : Math.max(0, 1 - violations.length / total)),
+    detail: passed
+      ? (total === 0 ? 'No interactive/Text/Image components to validate'
+                     : 'All interactive/Text/Image components have renderable content')
+      : `Empty components (registered + valid but render blank): ${violations.join(', ')}`,
+  };
+}
+
+/**
+ * 13. imagesHaveAlt — Image components should have an alt property.
+ */
+function checkImagesHaveAlt(components) {
+  const missing = [];
+
+  for (const comp of components) {
+    if (comp.component !== 'Image') continue;
+    if (comp.alt == null) {
+      missing.push(`"${comp.id}"`);
+    }
+  }
+
+  const imageCount = components.filter(c => c.component === 'Image').length;
+  const passed = missing.length === 0;
+  return {
+    name: 'imagesHaveAlt',
+    passed,
+    score: imageCount === 0 ? 1 : (passed ? 1 : Math.max(0, 1 - missing.length / Math.max(1, imageCount))),
+    detail: passed
+      ? (imageCount === 0 ? 'No image components to validate' : 'All images have alt text')
+      : `Missing alt: ${missing.join(', ')}`,
+  };
+}
+
+/**
+ * 14. headingHierarchy — Text components with variant h1-h5 should not skip levels.
+ *
+ * Warns but doesn't fail hard — score degrades per skip.
+ */
+function checkHeadingHierarchy(components) {
+  const headingLevels = [];
+
+  for (const comp of components) {
+    if (comp.component !== 'Text') continue;
+    const match = /^h([1-5])$/.exec(comp.variant);
+    if (match) headingLevels.push(Number(match[1]));
+  }
+
+  if (headingLevels.length === 0) {
+    return { name: 'headingHierarchy', passed: true, score: 1, detail: 'No headings to validate' };
+  }
+
+  const sorted = [...new Set(headingLevels)].sort((a, b) => a - b);
+  const skips = [];
+
+  for (let i = 1; i < sorted.length; i++) {
+    if (sorted[i] - sorted[i - 1] > 1) {
+      skips.push(`h${sorted[i - 1]} → h${sorted[i]}`);
+    }
+  }
+
+  const passed = skips.length === 0;
+  return {
+    name: 'headingHierarchy',
+    passed,
+    score: passed ? 1 : Math.max(0.5, 1 - skips.length * 0.25),
+    detail: passed ? 'Heading hierarchy is sequential' : `Skipped heading levels: ${skips.join(', ')}`,
+  };
+}
+
+/**
+ * 15. tabStructure — Tabs children must only be Tab components, and a Tab
+ * must not nest another Tab.
+ *
+ * Tab IS the panel. `<tab-ui>` renders its default slot as the tab panel and
+ * `<tabs-ui>` toggles `[hidden]` + `role="tabpanel"` on the inactive ones
+ * (`tabs.class.js`); the strip BUTTON is drawn by the parent from the child's
+ * [text]/[icon]/[value]. The catalog says so too — "the tab's default slot is
+ * the panel content that the parent auto-hides when inactive"
+ * (`components/tabs/tab.yaml` → `catalog-a2ui_0_9_rules.txt` §Tab).
+ *
+ * This check formerly hard-failed any Tab with a non-Text child ("Tab is a
+ * button, not a container", cda69a0aa, Apr 2026) — doctrine that predates the
+ * Tab catalog entry and contradicts the component. It made the canonical
+ * tabs/modal demo pages unconvertible (gh#754). Content inside Tab is CORRECT.
+ *
+ * WRONG:  Tabs > Card          (arbitrary markup directly in the strip)
+ * WRONG:  Tab  > Tab           (catalog: "Do not nest <tab-ui> inside another")
+ * RIGHT:  Tabs > Tab > Column  (panel content lives in its Tab)
+ */
+function checkTabStructure(components) {
+  const byId = new Map(components.map(c => [c.id, c]));
+  const issues = [];
+
+  for (const comp of components) {
+    if (comp.component !== 'Tabs') continue;
+    if (!Array.isArray(comp.children)) continue;
+
+    for (const childId of comp.children) {
+      const child = byId.get(childId);
+      if (!child) continue;
+      if (child.component !== 'Tab') {
+        issues.push(`Tabs "${comp.id}" has child "${childId}" of type "${child.component}" (only Tab allowed)`);
+      }
+    }
+  }
+
+  // Tab children ARE the panel content — any construct is allowed except a
+  // nested Tab (catalog: "Do not nest <tab-ui> inside another <tab-ui>").
+  for (const comp of components) {
+    if (comp.component !== 'Tab') continue;
+    if (!Array.isArray(comp.children)) continue;
+    for (const childId of comp.children) {
+      if (byId.get(childId)?.component === 'Tab') {
+        issues.push(`Tab "${comp.id}" nests Tab "${childId}" — tabs do not nest inside a tab panel`);
+      }
+    }
+  }
+
+  const tabCount = components.filter(c => c.component === 'Tabs').length;
+  const passed = issues.length === 0;
+  return {
+    name: 'tabStructure',
+    passed,
+    score: tabCount === 0 ? 1 : (passed ? 1 : 0),
+    detail: passed
+      ? (tabCount === 0 ? 'No tabs to validate' : 'Tab structure is correct')
+      : issues.join('; '),
+  };
+}
+
+/**
+ * 16. gridVsColumn — Column with 3+ Card children should be Grid.
+ *
+ * Catches the common LLM mistake of stacking repeating items (task cards,
+ * stat tiles, image cards) in a Column instead of a multi-column Grid.
+ * This is a layout quality check, not a hard error — some legitimate UIs
+ * have many cards in a single column (e.g. feed, timeline).
+ */
+function checkGridVsColumn(components) {
+  const byId = new Map(components.map(c => [c.id, c]));
+  const issues = [];
+
+  for (const comp of components) {
+    if (comp.component !== 'Column') continue;
+    if (!Array.isArray(comp.children) || comp.children.length < 3) continue;
+
+    // Count Card children
+    const cardChildren = comp.children.filter(childId => {
+      const child = byId.get(childId);
+      return child && child.component === 'Card';
+    });
+
+    if (cardChildren.length >= 3) {
+      issues.push(`Column "${comp.id}" has ${cardChildren.length} Card children — consider using Grid with columns="2"|"3" for multi-column layout`);
+    }
+  }
+
+  const passed = issues.length === 0;
+  return {
+    name: 'gridVsColumn',
+    passed,
+    score: passed ? 1 : 0.5,
+    detail: passed ? 'Layout containers appropriate' : issues.join('; '),
+  };
+}
+
+/**
+ * 17. landmarkStructure — at least one Header, Section, or Footer component should exist.
+ */
+function checkLandmarkStructure(components) {
+  const landmarkTypes = new Set(['Header', 'Section', 'Footer']);
+  const hasLandmark = components.some(c => landmarkTypes.has(c.component));
+
+  return {
+    name: 'landmarkStructure',
+    passed: hasLandmark,
+    score: hasLandmark ? 1 : 0,
+    detail: hasLandmark ? 'Landmark structure present' : 'No Header, Section, or Footer components found',
+  };
+}
+
+/**
+ * 17. intentAlignment — semantic alignment between intent and output.
+ *
+ * Three sub-checks weighted together:
+ *   A. Keyword matching  (40%) — intent keywords map to expected component types
+ *   B. Pattern mismatch  (35%) — dominant output types should be relevant to the intent
+ *   C. Complexity match   (25%) — compound intents need more than a handful of components
+ *
+ * Returns score 1 (no intent provided or all matched), degrades per miss.
+ */
+function checkIntentAlignment(components, intent) {
+  if (!intent || typeof intent !== 'string') {
+    return { name: 'intentAlignment', passed: true, score: 1, detail: 'No intent provided' };
+  }
+
+  // Map intent keywords → expected component types
+  const KEYWORD_TO_COMPONENT = {
+    'table':        ['Table'],
+    'chart':        ['Chart'],
+    'graph':        ['Chart'],
+    'form':         ['Input', 'Button'],
+    'input':        ['Input', 'TextArea'],
+    'button':       ['Button'],
+    'avatar':       ['Avatar'],
+    'badge':        ['Badge'],
+    'progress':     ['Progress'],
+    'slider':       ['Slider'],
+    'toggle':       ['Switch', 'Toggle'],
+    'switch':       ['Switch'],
+    'checkbox':     ['CheckBox'],
+    'radio':        ['Radio'],
+    'select':       ['Select'],
+    'upload':       ['Upload'],
+    'tabs':         ['Tabs', 'Tab'],
+    'tab':          ['Tabs', 'Tab'],
+    'accordion':    ['Accordion', 'AccordionItem'],
+    'modal':        ['Modal'],
+    'dialog':       ['Modal'],
+    'drawer':       ['Drawer'],
+    'toast':        ['Toast'],
+    'alert':        ['Alert'],
+    'tooltip':      ['Tooltip'],
+    'popover':      ['Popover'],
+    'breadcrumb':   ['Breadcrumb'],
+    'pagination':   ['Pagination'],
+    'timeline':     ['Timeline', 'TimelineItem'],
+    'carousel':     ['Swiper'],
+    'swiper':       ['Swiper'],
+    'calendar':     ['CalendarPicker'],
+    'color picker': ['ColorPicker'],
+    'otp':          ['OtpInput'],
+    'code':         ['Code'],
+    'image':        ['Image'],
+    'icon':         ['Icon'],
+    'divider':      ['Divider'],
+    'skeleton':     ['Skeleton'],
+    'embed':        ['Embed'],
+    'command':      ['Command'],
+    'stat':         ['Stat'],
+    'tag':          ['Tag'],
+    'menu':         ['Menu'],
+    'toolbar':      ['Toolbar'],
+    // Composite patterns — intent describes a UI pattern, not a single component
+    'inbox':        ['Column', 'Row', 'Avatar', 'Text', 'CheckBox'],
+    'email inbox':  ['Column', 'Row', 'Avatar', 'Text'],
+    'notification': ['Column', 'Row', 'Text', 'Badge'],
+    'shopping':     ['Column', 'Row', 'Text', 'Button'],
+    'cart':         ['Column', 'Row', 'Text', 'Button'],
+    'kanban':       ['Grid', 'Column', 'Card'],
+    'dashboard':    ['Grid', 'Card'],
+    'settings':     ['Card', 'Column', 'Row'],
+    'profile':      ['Card', 'Avatar', 'Text'],
+    'login':        ['Card', 'Input', 'Button'],
+    'signup':       ['Card', 'Input', 'Button', 'CheckBox'],
+  };
+
+  // ── Reverse mapping: component type → which intent keywords expect it ──
+  const COMPONENT_TO_KEYWORDS = {};
+  for (const [keyword, types] of Object.entries(KEYWORD_TO_COMPONENT)) {
+    for (const t of types) {
+      if (!COMPONENT_TO_KEYWORDS[t]) COMPONENT_TO_KEYWORDS[t] = [];
+      COMPONENT_TO_KEYWORDS[t].push(keyword);
+    }
+  }
+
+  // ── Semantic domain mapping: component types → semantic categories ──
+  const SEMANTIC_DOMAIN = {
+    'Toast':          'notification',
+    'Alert':          'notification',
+    'Badge':          'notification',
+    'Table':          'data-display',
+    'Chart':          'data-display',
+    'Stat':           'data-display',
+    'Form':           'data-entry',
+    'Input':          'data-entry',
+    'TextField':      'data-entry',
+    'TextArea':       'data-entry',
+    'Select':         'data-entry',
+    'ChoicePicker':   'data-entry',
+    'CheckBox':       'data-entry',
+    'Radio':          'data-entry',
+    'Toggle':         'data-entry',
+    'Switch':         'data-entry',
+    'Slider':         'data-entry',
+    'Upload':         'data-entry',
+    'Modal':          'overlay',
+    'Dialog':         'overlay',
+    'Drawer':         'overlay',
+    'Popover':        'overlay',
+    'Tooltip':        'overlay',
+    'Tabs':           'navigation',
+    'Tab':            'navigation',
+    'Breadcrumb':     'navigation',
+    'Pagination':     'navigation',
+    'Menu':           'navigation',
+    'Sidebar':        'navigation',
+    'Nav':            'navigation',
+    'Avatar':         'identity',
+    'Image':          'media',
+    'Embed':          'media',
+    'Card':           'layout',
+    'Column':         'layout',
+    'Row':            'layout',
+    'Grid':           'layout',
+    'Text':           'layout',
+    'Button':         'action',
+    'Icon':           'decoration',
+    'Divider':        'decoration',
+  };
+
+  // Intent → expected semantic domains
+  const INTENT_DOMAINS = {
+    'inbox':        ['identity', 'data-entry', 'navigation'],
+    'email':        ['identity', 'data-entry', 'navigation'],
+    'dashboard':    ['data-display', 'navigation'],
+    'admin':        ['data-display', 'navigation', 'data-entry'],
+    'analytics':    ['data-display'],
+    'menu':         ['navigation', 'action'],
+    'restaurant':   ['layout', 'action', 'media'],
+    'form':         ['data-entry', 'action'],
+    'login':        ['data-entry', 'action'],
+    'signup':       ['data-entry', 'action'],
+    'settings':     ['data-entry', 'action'],
+    'profile':      ['identity', 'media'],
+    'chat':         ['data-entry', 'identity'],
+    'shopping':     ['media', 'action'],
+    'cart':         ['data-display', 'action'],
+    'kanban':       ['layout'],
+    'calendar':     ['data-display'],
+  };
+
+  // ── Domains that should NOT dominate for certain intents ──
+  const ANTI_DOMAINS = {
+    'inbox':        ['notification', 'overlay'],
+    'email':        ['notification', 'overlay'],
+    'dashboard':    ['notification', 'overlay'],
+    'restaurant':   ['notification', 'overlay'],
+    'menu':         ['notification', 'overlay'],
+    'form':         ['notification'],
+    'profile':      ['notification'],
+    'shopping':     ['notification'],
+    'calendar':     ['notification'],
+    'admin':        ['notification', 'overlay'],
+    'analytics':    ['notification'],
+  };
+
+  const lower = intent.toLowerCase();
+  const outputTypes = new Set(components.map(c => c.component));
+
+  // Count component types (excluding layout containers for dominance check)
+  const typeCounts = {};
+  for (const c of components) {
+    typeCounts[c.component] = (typeCounts[c.component] || 0) + 1;
+  }
+
+  const details = [];
+  let keywordScore = 1;
+  let patternScore = 1;
+  let complexityScore = 1;
+
+  // ─── Sub-check A: Keyword matching (existing logic, enhanced) ───
+
+  const matched = [];
+  const missed = [];
+
+  for (const [keyword, expectedTypes] of Object.entries(KEYWORD_TO_COMPONENT)) {
+    const pattern = new RegExp(`\\b${keyword.replace(/\s+/g, '\\s+')}\\b`);
+    if (!pattern.test(lower)) continue;
+
+    const foundTypes = expectedTypes.filter(t => outputTypes.has(t));
+    const minRequired = expectedTypes.length >= 3 ? Math.ceil(expectedTypes.length / 2) : 1;
+
+    if (foundTypes.length >= minRequired) {
+      matched.push(keyword);
+    } else {
+      const missingTypes = expectedTypes.filter(t => !outputTypes.has(t));
+      missed.push(`"${keyword}" → missing ${missingTypes.join(', ')}`);
+    }
+  }
+
+  const keywordTotal = matched.length + missed.length;
+  if (keywordTotal > 0) {
+    keywordScore = matched.length / keywordTotal;
+    if (missed.length > 0) {
+      details.push(`Missing components for: ${missed.join('; ')}`);
+    }
+  }
+
+  // ─── Sub-check B: Pattern mismatch — dominant irrelevant types ───
+
+  // Find the semantic domains present in the output (weighted by count)
+  const domainCounts = {};
+  const nonLayoutTypes = components.filter(c =>
+    !['Column', 'Row', 'Grid', 'Card', 'Text', 'Header', 'Section', 'Footer', 'Button', 'Icon', 'Divider'].includes(c.component)
+  );
+
+  for (const c of nonLayoutTypes) {
+    const domain = SEMANTIC_DOMAIN[c.component];
+    if (domain) {
+      domainCounts[domain] = (domainCounts[domain] || 0) + 1;
+    }
+  }
+
+  // Check if any anti-domain dominates (>50% of non-layout components)
+  const nonLayoutCount = nonLayoutTypes.length;
+  if (nonLayoutCount > 0) {
+    for (const [intentKey, antiDomains] of Object.entries(ANTI_DOMAINS)) {
+      const keyPattern = new RegExp(`\\b${intentKey}\\b`);
+      if (!keyPattern.test(lower)) continue;
+
+      for (const antiDomain of antiDomains) {
+        const antiCount = domainCounts[antiDomain] || 0;
+        const ratio = antiCount / nonLayoutCount;
+        if (ratio > 0.4 && antiCount >= 2) {
+          // Heavy penalty — wrong pattern entirely
+          const penalty = Math.min(0.8, ratio);
+          patternScore = Math.min(patternScore, 1 - penalty);
+          details.push(`Semantic mismatch: "${antiDomain}" components dominate (${antiCount}/${nonLayoutCount}) but intent is "${intentKey}"`);
+        }
+      }
+    }
+
+    // Also check: if output is dominated by a single specific component type
+    // (e.g., 4 Toast components) and that type isn't mentioned in the intent
+    for (const [type, count] of Object.entries(typeCounts)) {
+      if (['Column', 'Row', 'Grid', 'Card', 'Text', 'Header', 'Section', 'Footer', 'Button', 'Icon', 'Divider'].includes(type)) continue;
+      const ratio = count / components.length;
+      if (ratio > 0.25 && count >= 3) {
+        // This type dominates — is it mentioned in the intent?
+        const keywords = COMPONENT_TO_KEYWORDS[type] || [];
+        const mentionedInIntent = keywords.some(kw => {
+          const kwPattern = new RegExp(`\\b${kw.replace(/\s+/g, '\\s+')}\\b`);
+          return kwPattern.test(lower);
+        });
+        if (!mentionedInIntent) {
+          const penalty = Math.min(0.7, ratio * 1.5);
+          patternScore = Math.min(patternScore, 1 - penalty);
+          details.push(`Dominant irrelevant type: ${count}× ${type} (${Math.round(ratio * 100)}% of output) not mentioned in intent`);
+        }
+      }
+    }
+  }
+
+  // ─── Sub-check C: Complexity adequacy ───
+
+  // Compound intents should produce enough components
+  const COMPOUND_PATTERNS = [
+    { pattern: /\b(?:inbox|email\s+inbox|email\s+client)\b/, minComponents: 12 },
+    { pattern: /\b(?:dashboard|admin\s+dashboard|analytics)\b/, minComponents: 10 },
+    { pattern: /\b(?:restaurant\s+menu|food\s+menu)\b/, minComponents: 10 },
+    { pattern: /\b(?:kanban|project\s+board)\b/, minComponents: 10 },
+    { pattern: /\b(?:shopping|e-?commerce|product\s+list)\b/, minComponents: 10 },
+    { pattern: /\b(?:settings|preferences)\b/, minComponents: 8 },
+    { pattern: /\b(?:chat|messaging)\b/, minComponents: 8 },
+    { pattern: /\b(?:profile|user\s+profile)\b/, minComponents: 8 },
+    { pattern: /\b(?:login|sign\s*in)\b/, minComponents: 6 },
+    { pattern: /\b(?:signup|sign\s*up|register)\b/, minComponents: 7 },
+  ];
+
+  for (const { pattern, minComponents } of COMPOUND_PATTERNS) {
+    if (!pattern.test(lower)) continue;
+    if (components.length < minComponents) {
+      const ratio = components.length / minComponents;
+      complexityScore = Math.min(complexityScore, ratio);
+      details.push(`Too few components: ${components.length} for "${pattern.source}" (expected ≥${minComponents})`);
+    }
+  }
+
+  // Also: count distinct words in intent as a rough complexity measure
+  const intentWords = lower.split(/\s+/).filter(w => w.length > 3).length;
+  if (intentWords >= 4 && components.length < 8) {
+    const penalty = Math.max(0, (8 - components.length) / 8) * 0.5;
+    complexityScore = Math.min(complexityScore, 1 - penalty);
+    details.push(`Sparse output: ${components.length} components for multi-word intent (${intentWords} significant words)`);
+  }
+
+  // ─── Composite score ───
+  // A: keyword match (40%), B: pattern mismatch (35%), C: complexity (25%)
+  const score = Math.max(0, Math.min(1,
+    keywordScore * 0.40 +
+    patternScore * 0.35 +
+    complexityScore * 0.25
+  ));
+
+  const passed = score >= 0.8;
+
+  return {
+    name: 'intentAlignment',
+    passed,
+    score,
+    detail: details.length > 0
+      ? details.join('; ')
+      : (keywordTotal > 0
+        ? `All ${matched.length} intent keywords have matching components`
+        : 'No keyword-to-component mappings matched intent'),
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════
+// WIRING CHECKS (A007 §9.4)
+// Only scored when wireComponents messages are present.
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Validate a wireComponents message against the wiring registry and component tree.
+ * @param {object} wire — wireComponents message
+ * @param {Set<string>} componentIds — IDs from updateComponents
+ * @returns {object[]} — Array of check results
+ */
+function checkOntologyAlignment(components, context) {
+  if (!context || !context.domain || !context.domain.entities) {
+    return { name: 'ontologyAlignment', passed: true, score: 1, detail: 'No ontology context provided' };
+  }
+
+  // Check if at least one entity or task from the context appears in the components
+  const entities = context.domain.entities.map(e => e.toLowerCase());
+  const tasks = (context.tasks?.primary || []).map(t => t.toLowerCase());
+  const terms = [...entities, ...tasks];
+
+  if (terms.length === 0) {
+    return { name: 'ontologyAlignment', passed: true, score: 1, detail: 'Empty ontology context' };
+  }
+
+  const jsonStr = JSON.stringify(components).toLowerCase();
+  
+  const foundTerms = terms.filter(t => jsonStr.includes(t));
+  
+  // Need at least one term match. If 0, it hallucinates completely different data.
+  const score = foundTerms.length > 0 ? 1 : 0;
+  
+  return {
+    name: 'ontologyAlignment',
+    passed: score > 0,
+    score: score,
+    detail: score > 0 
+      ? `Ontology respected (Found terms: ${foundTerms.join(', ')})`
+      : `Ontology violation: None of the planned domain entities or tasks were found in the UI tree.`,
+  };
+}
+
+function checkWiring(wire, componentIds) {
+  const checks = [];
+
+  // ── Controllers exist in registry ──
+  if (wire.state?.controllers?.length) {
+    const unknown = wire.state.controllers.filter(c => !wiringRegistry.controllers.has(c.type));
+    checks.push({
+      name: 'wiringControllersExist',
+      passed: unknown.length === 0,
+      score: unknown.length === 0 ? 1 : Math.max(0, 1 - unknown.length * 0.5),
+      detail: unknown.length === 0
+        ? `All ${wire.state.controllers.length} controller types registered`
+        : `Unknown controllers: ${unknown.map(c => c.type).join(', ')}`,
+    });
+  }
+
+  // ── Controller hosts reference existing component IDs ──
+  if (wire.state?.controllers?.length) {
+    const missing = wire.state.controllers.filter(c => !componentIds.has(c.host));
+    checks.push({
+      name: 'wiringHostsExist',
+      passed: missing.length === 0,
+      score: missing.length === 0 ? 1 : 0,
+      detail: missing.length === 0
+        ? 'All controller hosts reference valid component IDs'
+        : `Missing hosts: ${missing.map(c => `${c.id}→${c.host}`).join(', ')}`,
+    });
+  }
+
+  // ── Action handlers exist in registry ──
+  if (wire.actions?.length) {
+    const unknown = wire.actions.filter(a => !wiringRegistry.handlers.has(a.handler));
+    checks.push({
+      name: 'wiringHandlersExist',
+      passed: unknown.length === 0,
+      score: unknown.length === 0 ? 1 : Math.max(0, 1 - unknown.length * 0.5),
+      detail: unknown.length === 0
+        ? `All ${wire.actions.length} action handlers registered`
+        : `Unknown handlers: ${unknown.map(a => a.handler).join(', ')}`,
+    });
+  }
+
+  // ── Action sources reference existing component IDs ──
+  if (wire.actions?.length) {
+    const missing = wire.actions.filter(a => !componentIds.has(a.source));
+    checks.push({
+      name: 'wiringSourcesExist',
+      passed: missing.length === 0,
+      score: missing.length === 0 ? 1 : 0,
+      detail: missing.length === 0
+        ? 'All action sources reference valid component IDs'
+        : `Missing sources: ${missing.map(a => `${a.event}→${a.source}`).join(', ')}`,
+    });
+  }
+
+  // ── Data source paths are valid JSON Pointers ──
+  if (wire.data?.sources?.length) {
+    const invalid = wire.data.sources.filter(s => !s.path || !s.path.startsWith('/'));
+    checks.push({
+      name: 'wiringDataPathsValid',
+      passed: invalid.length === 0,
+      score: invalid.length === 0 ? 1 : 0,
+      detail: invalid.length === 0
+        ? 'All data source paths are valid JSON Pointers'
+        : `Invalid paths: ${invalid.map(s => `${s.id}:"${s.path}"`).join(', ')}`,
+    });
+  }
+
+  return checks;
+}