@vibecheckai/cli 3.2.5 → 3.3.0

package/bin/runners/lib/reality/semantic-snapshot.js

@@ -1,408 +1,408 @@
-/**
- * Semantic Snapshot v2
- * 
- * Creates stable, lightweight UI fingerprints for meaningful change detection.
- * Captures accessible DOM features while filtering noise.
- */
-
-"use strict";
-
-const crypto = require("crypto");
-
-// =============================================================================
-// CONSTANTS
-// =============================================================================
-
-const IGNORE_TAGS = new Set([
-  "script", "style", "link", "meta", "noscript", "template"
-]);
-
-const IGNORE_SELECTORS = [
-  "[data-hydration]",
-  "[data-nextjs-scroll-focus-boundary]",
-  "nextjs-portal",
-  "[data-overlay-container]",
-  "#__next-build-watcher",
-  "#__next-prerender-indicator",
-];
-
-const MEANINGFUL_ROLES = new Set([
-  "button", "link", "textbox", "checkbox", "radio", "combobox",
-  "listbox", "menu", "menuitem", "tab", "tabpanel", "dialog",
-  "alert", "alertdialog", "status", "progressbar", "form",
-  "navigation", "main", "region", "banner", "contentinfo"
-]);
-
-const TIMESTAMP_REGEX = /^\d{1,2}:\d{2}(:\d{2})?\s*(AM|PM)?$/i;
-const TIMER_REGEX = /^\d+(\.\d+)?\s*(s|ms|sec|seconds?)$/i;
-
-// =============================================================================
-// SEMANTIC SNAPSHOT CAPTURE (runs in browser context)
-// =============================================================================
-
-/**
- * Playwright script to capture semantic snapshot
- * Inject this into page.evaluate()
- */
-const CAPTURE_SCRIPT = `
-(function captureSemanticSnapshot(options = {}) {
-  const {
-    regions = ['main', '#__next', '[role="main"]', 'body'],
-    includeDialogs = true,
-    maxTextLength = 80,
-    ignoreTimestamps = true,
-  } = options;
-
-  const IGNORE_TAGS = new Set(['script', 'style', 'link', 'meta', 'noscript', 'template', 'svg']);
-  const TIMESTAMP_RE = /^\\d{1,2}:\\d{2}(:\\d{2})?\\s*(AM|PM)?$/i;
-  const TIMER_RE = /^\\d+(\\.\\d+)?\\s*(s|ms|sec|seconds?)$/i;
-
-  function normalizeText(text) {
-    if (!text) return '';
-    let t = text.trim().replace(/\\s+/g, ' ');
-    if (t.length > maxTextLength) t = t.slice(0, maxTextLength) + '...';
-    return t;
-  }
-
-  function isTimestamp(text) {
-    if (!ignoreTimestamps) return false;
-    return TIMESTAMP_RE.test(text) || TIMER_RE.test(text);
-  }
-
-  function getAccessibleName(el) {
-    // aria-label takes precedence
-    if (el.getAttribute('aria-label')) return normalizeText(el.getAttribute('aria-label'));
-    // aria-labelledby
-    const labelledBy = el.getAttribute('aria-labelledby');
-    if (labelledBy) {
-      const labelEl = document.getElementById(labelledBy);
-      if (labelEl) return normalizeText(labelEl.textContent);
-    }
-    // For inputs, check associated label
-    if (el.id) {
-      const label = document.querySelector('label[for="' + el.id + '"]');
-      if (label) return normalizeText(label.textContent);
-    }
-    // Fallback to text content for buttons/links
-    if (['BUTTON', 'A'].includes(el.tagName)) {
-      return normalizeText(el.textContent);
-    }
-    return '';
-  }
-
-  function getRole(el) {
-    if (el.getAttribute('role')) return el.getAttribute('role');
-    // Infer from tag
-    const tag = el.tagName.toLowerCase();
-    const roleMap = {
-      button: 'button', a: 'link', input: 'textbox',
-      select: 'combobox', textarea: 'textbox', nav: 'navigation',
-      main: 'main', header: 'banner', footer: 'contentinfo',
-      dialog: 'dialog', form: 'form', img: 'img'
-    };
-    if (roleMap[tag]) return roleMap[tag];
-    if (tag === 'input') {
-      const type = el.type?.toLowerCase();
-      if (type === 'checkbox') return 'checkbox';
-      if (type === 'radio') return 'radio';
-      if (type === 'submit' || type === 'button') return 'button';
-    }
-    return null;
-  }
-
-  function extractNode(el) {
-    if (!el || el.nodeType !== 1) return null;
-    if (IGNORE_TAGS.has(el.tagName.toLowerCase())) return null;
-    if (el.hidden || el.getAttribute('aria-hidden') === 'true') return null;
-    
-    const style = window.getComputedStyle(el);
-    if (style.display === 'none' || style.visibility === 'hidden') return null;
-
-    const role = getRole(el);
-    const name = getAccessibleName(el);
-    
-    // Skip if text looks like timestamp
-    if (name && isTimestamp(name)) return null;
-
-    const node = {
-      tag: el.tagName.toLowerCase(),
-      role: role,
-      name: name || undefined,
-      disabled: el.disabled || el.getAttribute('aria-disabled') === 'true' || undefined,
-      invalid: el.getAttribute('aria-invalid') === 'true' || undefined,
-      href: el.tagName === 'A' ? el.getAttribute('href')?.split('?')[0] : undefined,
-      type: el.tagName === 'INPUT' ? el.type : undefined,
-      checked: (el.type === 'checkbox' || el.type === 'radio') ? el.checked : undefined,
-      value: el.tagName === 'INPUT' && el.type !== 'password' ? (el.value?.slice(0, 50) || undefined) : undefined,
-    };
-
-    // Clean undefined
-    Object.keys(node).forEach(k => node[k] === undefined && delete node[k]);
-    
-    return node;
-  }
-
-  function walkTree(root, nodes = [], depth = 0) {
-    if (depth > 20) return nodes; // Prevent infinite recursion
-    
-    for (const el of root.children || []) {
-      const node = extractNode(el);
-      if (node && (node.role || node.name)) {
-        nodes.push(node);
-      }
-      walkTree(el, nodes, depth + 1);
-    }
-    return nodes;
-  }
-
-  // Find main region
-  let mainRegion = null;
-  for (const selector of regions) {
-    mainRegion = document.querySelector(selector);
-    if (mainRegion) break;
-  }
-
-  const nodes = [];
-  if (mainRegion) {
-    walkTree(mainRegion, nodes);
-  }
-
-  // Add dialogs/modals
-  if (includeDialogs) {
-    const dialogs = document.querySelectorAll('[role="dialog"], [aria-modal="true"], [data-state="open"]');
-    for (const dialog of dialogs) {
-      walkTree(dialog, nodes);
-    }
-  }
-
-  // Count by role
-  const counts = {};
-  for (const n of nodes) {
-    if (n.role) {
-      counts[n.role] = (counts[n.role] || 0) + 1;
-    }
-  }
-
-  // Count errors
-  const errorCount = nodes.filter(n => n.invalid).length;
-  const disabledCount = nodes.filter(n => n.disabled).length;
-
-  return {
-    nodes: nodes,
-    counts: counts,
-    errorCount: errorCount,
-    disabledCount: disabledCount,
-    region: mainRegion?.tagName?.toLowerCase() || 'body',
-    url: window.location.pathname + window.location.search,
-    timestamp: Date.now(),
-  };
-})
-`;
-
-/**
- * Compute semantic hash from snapshot
- */
-function computeSemanticHash(snapshot) {
-  // Create a stable string representation
-  const significantNodes = snapshot.nodes
-    .filter(n => n.role || n.name)
-    .map(n => `${n.role || ""}:${n.name || ""}:${n.disabled ? "d" : ""}:${n.invalid ? "i" : ""}`)
-    .sort();
-
-  const content = JSON.stringify({
-    nodes: significantNodes,
-    counts: snapshot.counts,
-    url: snapshot.url,
-  });
-
-  return "sha256:" + crypto.createHash("sha256").update(content).digest("hex").slice(0, 16);
-}
-
-/**
- * Compare two semantic snapshots and generate diff
- */
-function diffSnapshots(before, after) {
-  const diff = {
-    added: [],
-    removed: [],
-    changed: [],
-  };
-
-  // Create maps by role+name for comparison
-  const beforeMap = new Map();
-  const afterMap = new Map();
-
-  for (const n of before.nodes || []) {
-    const key = `${n.role || ""}:${n.name || ""}`;
-    beforeMap.set(key, n);
-  }
-
-  for (const n of after.nodes || []) {
-    const key = `${n.role || ""}:${n.name || ""}`;
-    afterMap.set(key, n);
-  }
-
-  // Find added
-  for (const [key, node] of afterMap) {
-    if (!beforeMap.has(key)) {
-      diff.added.push(`${node.role || node.tag}: ${node.name || "(unnamed)"}`);
-    } else {
-      // Check for changes
-      const beforeNode = beforeMap.get(key);
-      const changes = [];
-      if (beforeNode.disabled !== node.disabled) {
-        changes.push(node.disabled ? "disabled" : "enabled");
-      }
-      if (beforeNode.invalid !== node.invalid) {
-        changes.push(node.invalid ? "invalid" : "valid");
-      }
-      if (beforeNode.checked !== node.checked) {
-        changes.push(node.checked ? "checked" : "unchecked");
-      }
-      if (changes.length > 0) {
-        diff.changed.push(`${node.role || node.tag}: ${node.name || "(unnamed)"} -> ${changes.join(", ")}`);
-      }
-    }
-  }
-
-  // Find removed
-  for (const [key, node] of beforeMap) {
-    if (!afterMap.has(key)) {
-      diff.removed.push(`${node.role || node.tag}: ${node.name || "(unnamed)"}`);
-    }
-  }
-
-  // Check for route change
-  diff.routeChanged = before.url !== after.url;
-
-  // Check for error count change
-  diff.errorsChanged = before.errorCount !== after.errorCount;
-  diff.errorDelta = (after.errorCount || 0) - (before.errorCount || 0);
-
-  // Check for dialog changes
-  const beforeDialogCount = before.counts?.dialog || 0;
-  const afterDialogCount = after.counts?.dialog || 0;
-  diff.dialogOpened = afterDialogCount > beforeDialogCount;
-  diff.dialogClosed = afterDialogCount < beforeDialogCount;
-
-  return diff;
-}
-
-/**
- * Calculate meaningful change score
- */
-function calculateChangeScore(diff, signals = []) {
-  let score = 0;
-  const reasons = [];
-
-  // Route change is always meaningful
-  if (diff.routeChanged) {
-    score += 1.0;
-    reasons.push("route_changed");
-  }
-
-  // Dialog opened/closed
-  if (diff.dialogOpened) {
-    score += 0.8;
-    reasons.push("dialog_opened");
-  }
-  if (diff.dialogClosed) {
-    score += 0.8;
-    reasons.push("dialog_closed");
-  }
-
-  // Toast signals
-  const toastSuccess = signals.find(s => s.kind === "toast_success");
-  const toastError = signals.find(s => s.kind === "toast_error");
-  const toastAny = signals.find(s => s.kind?.startsWith("toast_"));
-
-  if (toastSuccess) {
-    score += 0.6;
-    reasons.push("toast_success");
-  }
-  if (toastError) {
-    score += 0.6;
-    reasons.push("toast_error");
-  } else if (toastAny && !toastSuccess) {
-    score += 0.5;
-    reasons.push("toast_appeared");
-  }
-
-  // Alert banner (role=alert, aria-live)
-  const alertSignal = signals.find(s => s.kind === "alert_appeared");
-  if (alertSignal) {
-    score += 0.7;
-    reasons.push("alert_banner");
-  }
-
-  // Form errors changed
-  if (diff.errorsChanged) {
-    score += 0.7;
-    reasons.push(diff.errorDelta > 0 ? "form_errors_appeared" : "form_errors_cleared");
-  }
-
-  // Significant semantic diff
-  const significantChanges = diff.added.length + diff.removed.length + diff.changed.length;
-  if (significantChanges > 2) {
-    score += 0.7;
-    reasons.push("semantic_hash_changed");
-  } else if (significantChanges > 0) {
-    score += 0.3;
-    reasons.push("minor_semantic_change");
-  }
-
-  // Key control state changed (disabled/enabled)
-  const controlChanges = diff.changed.filter(c => c.includes("enabled") || c.includes("disabled"));
-  if (controlChanges.length > 0) {
-    score += 0.6;
-    reasons.push("control_state_changed");
-  }
-
-  // Cap at 1.0
-  score = Math.min(score, 1.0);
-
-  return {
-    score,
-    meaningful: score >= 0.6 || diff.routeChanged,
-    reasons,
-  };
-}
-
-/**
- * Create UI change report from before/after snapshots and signals
- */
-function createUIChangeReport(before, after, signals = []) {
-  const beforeHash = computeSemanticHash(before);
-  const afterHash = computeSemanticHash(after);
-  const diff = diffSnapshots(before, after);
-  const { score, meaningful, reasons } = calculateChangeScore(diff, signals);
-
-  return {
-    score,
-    meaningful,
-    reasons,
-    beforeSemanticHash: beforeHash,
-    afterSemanticHash: afterHash,
-    semanticDiffSummary: {
-      added: diff.added.slice(0, 10),
-      removed: diff.removed.slice(0, 10),
-      changed: diff.changed.slice(0, 10),
-    },
-    routeChanged: diff.routeChanged,
-    dialogOpened: diff.dialogOpened,
-    dialogClosed: diff.dialogClosed,
-    errorsChanged: diff.errorsChanged,
-    errorDelta: diff.errorDelta,
-  };
-}
-
-module.exports = {
-  CAPTURE_SCRIPT,
-  computeSemanticHash,
-  diffSnapshots,
-  calculateChangeScore,
-  createUIChangeReport,
-  IGNORE_TAGS,
-  IGNORE_SELECTORS,
-  MEANINGFUL_ROLES,
-};
+/**
+ * Semantic Snapshot v2
+ * 
+ * Creates stable, lightweight UI fingerprints for meaningful change detection.
+ * Captures accessible DOM features while filtering noise.
+ */
+
+"use strict";
+
+const crypto = require("crypto");
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+const IGNORE_TAGS = new Set([
+  "script", "style", "link", "meta", "noscript", "template"
+]);
+
+const IGNORE_SELECTORS = [
+  "[data-hydration]",
+  "[data-nextjs-scroll-focus-boundary]",
+  "nextjs-portal",
+  "[data-overlay-container]",
+  "#__next-build-watcher",
+  "#__next-prerender-indicator",
+];
+
+const MEANINGFUL_ROLES = new Set([
+  "button", "link", "textbox", "checkbox", "radio", "combobox",
+  "listbox", "menu", "menuitem", "tab", "tabpanel", "dialog",
+  "alert", "alertdialog", "status", "progressbar", "form",
+  "navigation", "main", "region", "banner", "contentinfo"
+]);
+
+const TIMESTAMP_REGEX = /^\d{1,2}:\d{2}(:\d{2})?\s*(AM|PM)?$/i;
+const TIMER_REGEX = /^\d+(\.\d+)?\s*(s|ms|sec|seconds?)$/i;
+
+// =============================================================================
+// SEMANTIC SNAPSHOT CAPTURE (runs in browser context)
+// =============================================================================
+
+/**
+ * Playwright script to capture semantic snapshot
+ * Inject this into page.evaluate()
+ */
+const CAPTURE_SCRIPT = `
+(function captureSemanticSnapshot(options = {}) {
+  const {
+    regions = ['main', '#__next', '[role="main"]', 'body'],
+    includeDialogs = true,
+    maxTextLength = 80,
+    ignoreTimestamps = true,
+  } = options;
+
+  const IGNORE_TAGS = new Set(['script', 'style', 'link', 'meta', 'noscript', 'template', 'svg']);
+  const TIMESTAMP_RE = /^\\d{1,2}:\\d{2}(:\\d{2})?\\s*(AM|PM)?$/i;
+  const TIMER_RE = /^\\d+(\\.\\d+)?\\s*(s|ms|sec|seconds?)$/i;
+
+  function normalizeText(text) {
+    if (!text) return '';
+    let t = text.trim().replace(/\\s+/g, ' ');
+    if (t.length > maxTextLength) t = t.slice(0, maxTextLength) + '...';
+    return t;
+  }
+
+  function isTimestamp(text) {
+    if (!ignoreTimestamps) return false;
+    return TIMESTAMP_RE.test(text) || TIMER_RE.test(text);
+  }
+
+  function getAccessibleName(el) {
+    // aria-label takes precedence
+    if (el.getAttribute('aria-label')) return normalizeText(el.getAttribute('aria-label'));
+    // aria-labelledby
+    const labelledBy = el.getAttribute('aria-labelledby');
+    if (labelledBy) {
+      const labelEl = document.getElementById(labelledBy);
+      if (labelEl) return normalizeText(labelEl.textContent);
+    }
+    // For inputs, check associated label
+    if (el.id) {
+      const label = document.querySelector('label[for="' + el.id + '"]');
+      if (label) return normalizeText(label.textContent);
+    }
+    // Fallback to text content for buttons/links
+    if (['BUTTON', 'A'].includes(el.tagName)) {
+      return normalizeText(el.textContent);
+    }
+    return '';
+  }
+
+  function getRole(el) {
+    if (el.getAttribute('role')) return el.getAttribute('role');
+    // Infer from tag
+    const tag = el.tagName.toLowerCase();
+    const roleMap = {
+      button: 'button', a: 'link', input: 'textbox',
+      select: 'combobox', textarea: 'textbox', nav: 'navigation',
+      main: 'main', header: 'banner', footer: 'contentinfo',
+      dialog: 'dialog', form: 'form', img: 'img'
+    };
+    if (roleMap[tag]) return roleMap[tag];
+    if (tag === 'input') {
+      const type = el.type?.toLowerCase();
+      if (type === 'checkbox') return 'checkbox';
+      if (type === 'radio') return 'radio';
+      if (type === 'submit' || type === 'button') return 'button';
+    }
+    return null;
+  }
+
+  function extractNode(el) {
+    if (!el || el.nodeType !== 1) return null;
+    if (IGNORE_TAGS.has(el.tagName.toLowerCase())) return null;
+    if (el.hidden || el.getAttribute('aria-hidden') === 'true') return null;
+    
+    const style = window.getComputedStyle(el);
+    if (style.display === 'none' || style.visibility === 'hidden') return null;
+
+    const role = getRole(el);
+    const name = getAccessibleName(el);
+    
+    // Skip if text looks like timestamp
+    if (name && isTimestamp(name)) return null;
+
+    const node = {
+      tag: el.tagName.toLowerCase(),
+      role: role,
+      name: name || undefined,
+      disabled: el.disabled || el.getAttribute('aria-disabled') === 'true' || undefined,
+      invalid: el.getAttribute('aria-invalid') === 'true' || undefined,
+      href: el.tagName === 'A' ? el.getAttribute('href')?.split('?')[0] : undefined,
+      type: el.tagName === 'INPUT' ? el.type : undefined,
+      checked: (el.type === 'checkbox' || el.type === 'radio') ? el.checked : undefined,
+      value: el.tagName === 'INPUT' && el.type !== 'password' ? (el.value?.slice(0, 50) || undefined) : undefined,
+    };
+
+    // Clean undefined
+    Object.keys(node).forEach(k => node[k] === undefined && delete node[k]);
+    
+    return node;
+  }
+
+  function walkTree(root, nodes = [], depth = 0) {
+    if (depth > 20) return nodes; // Prevent infinite recursion
+    
+    for (const el of root.children || []) {
+      const node = extractNode(el);
+      if (node && (node.role || node.name)) {
+        nodes.push(node);
+      }
+      walkTree(el, nodes, depth + 1);
+    }
+    return nodes;
+  }
+
+  // Find main region
+  let mainRegion = null;
+  for (const selector of regions) {
+    mainRegion = document.querySelector(selector);
+    if (mainRegion) break;
+  }
+
+  const nodes = [];
+  if (mainRegion) {
+    walkTree(mainRegion, nodes);
+  }
+
+  // Add dialogs/modals
+  if (includeDialogs) {
+    const dialogs = document.querySelectorAll('[role="dialog"], [aria-modal="true"], [data-state="open"]');
+    for (const dialog of dialogs) {
+      walkTree(dialog, nodes);
+    }
+  }
+
+  // Count by role
+  const counts = {};
+  for (const n of nodes) {
+    if (n.role) {
+      counts[n.role] = (counts[n.role] || 0) + 1;
+    }
+  }
+
+  // Count errors
+  const errorCount = nodes.filter(n => n.invalid).length;
+  const disabledCount = nodes.filter(n => n.disabled).length;
+
+  return {
+    nodes: nodes,
+    counts: counts,
+    errorCount: errorCount,
+    disabledCount: disabledCount,
+    region: mainRegion?.tagName?.toLowerCase() || 'body',
+    url: window.location.pathname + window.location.search,
+    timestamp: Date.now(),
+  };
+})
+`;
+
+/**
+ * Compute semantic hash from snapshot
+ */
+function computeSemanticHash(snapshot) {
+  // Create a stable string representation
+  const significantNodes = snapshot.nodes
+    .filter(n => n.role || n.name)
+    .map(n => `${n.role || ""}:${n.name || ""}:${n.disabled ? "d" : ""}:${n.invalid ? "i" : ""}`)
+    .sort();
+
+  const content = JSON.stringify({
+    nodes: significantNodes,
+    counts: snapshot.counts,
+    url: snapshot.url,
+  });
+
+  return "sha256:" + crypto.createHash("sha256").update(content).digest("hex").slice(0, 16);
+}
+
+/**
+ * Compare two semantic snapshots and generate diff
+ */
+function diffSnapshots(before, after) {
+  const diff = {
+    added: [],
+    removed: [],
+    changed: [],
+  };
+
+  // Create maps by role+name for comparison
+  const beforeMap = new Map();
+  const afterMap = new Map();
+
+  for (const n of before.nodes || []) {
+    const key = `${n.role || ""}:${n.name || ""}`;
+    beforeMap.set(key, n);
+  }
+
+  for (const n of after.nodes || []) {
+    const key = `${n.role || ""}:${n.name || ""}`;
+    afterMap.set(key, n);
+  }
+
+  // Find added
+  for (const [key, node] of afterMap) {
+    if (!beforeMap.has(key)) {
+      diff.added.push(`${node.role || node.tag}: ${node.name || "(unnamed)"}`);
+    } else {
+      // Check for changes
+      const beforeNode = beforeMap.get(key);
+      const changes = [];
+      if (beforeNode.disabled !== node.disabled) {
+        changes.push(node.disabled ? "disabled" : "enabled");
+      }
+      if (beforeNode.invalid !== node.invalid) {
+        changes.push(node.invalid ? "invalid" : "valid");
+      }
+      if (beforeNode.checked !== node.checked) {
+        changes.push(node.checked ? "checked" : "unchecked");
+      }
+      if (changes.length > 0) {
+        diff.changed.push(`${node.role || node.tag}: ${node.name || "(unnamed)"} -> ${changes.join(", ")}`);
+      }
+    }
+  }
+
+  // Find removed
+  for (const [key, node] of beforeMap) {
+    if (!afterMap.has(key)) {
+      diff.removed.push(`${node.role || node.tag}: ${node.name || "(unnamed)"}`);
+    }
+  }
+
+  // Check for route change
+  diff.routeChanged = before.url !== after.url;
+
+  // Check for error count change
+  diff.errorsChanged = before.errorCount !== after.errorCount;
+  diff.errorDelta = (after.errorCount || 0) - (before.errorCount || 0);
+
+  // Check for dialog changes
+  const beforeDialogCount = before.counts?.dialog || 0;
+  const afterDialogCount = after.counts?.dialog || 0;
+  diff.dialogOpened = afterDialogCount > beforeDialogCount;
+  diff.dialogClosed = afterDialogCount < beforeDialogCount;
+
+  return diff;
+}
+
+/**
+ * Calculate meaningful change score
+ */
+function calculateChangeScore(diff, signals = []) {
+  let score = 0;
+  const reasons = [];
+
+  // Route change is always meaningful
+  if (diff.routeChanged) {
+    score += 1.0;
+    reasons.push("route_changed");
+  }
+
+  // Dialog opened/closed
+  if (diff.dialogOpened) {
+    score += 0.8;
+    reasons.push("dialog_opened");
+  }
+  if (diff.dialogClosed) {
+    score += 0.8;
+    reasons.push("dialog_closed");
+  }
+
+  // Toast signals
+  const toastSuccess = signals.find(s => s.kind === "toast_success");
+  const toastError = signals.find(s => s.kind === "toast_error");
+  const toastAny = signals.find(s => s.kind?.startsWith("toast_"));
+
+  if (toastSuccess) {
+    score += 0.6;
+    reasons.push("toast_success");
+  }
+  if (toastError) {
+    score += 0.6;
+    reasons.push("toast_error");
+  } else if (toastAny && !toastSuccess) {
+    score += 0.5;
+    reasons.push("toast_appeared");
+  }
+
+  // Alert banner (role=alert, aria-live)
+  const alertSignal = signals.find(s => s.kind === "alert_appeared");
+  if (alertSignal) {
+    score += 0.7;
+    reasons.push("alert_banner");
+  }
+
+  // Form errors changed
+  if (diff.errorsChanged) {
+    score += 0.7;
+    reasons.push(diff.errorDelta > 0 ? "form_errors_appeared" : "form_errors_cleared");
+  }
+
+  // Significant semantic diff
+  const significantChanges = diff.added.length + diff.removed.length + diff.changed.length;
+  if (significantChanges > 2) {
+    score += 0.7;
+    reasons.push("semantic_hash_changed");
+  } else if (significantChanges > 0) {
+    score += 0.3;
+    reasons.push("minor_semantic_change");
+  }
+
+  // Key control state changed (disabled/enabled)
+  const controlChanges = diff.changed.filter(c => c.includes("enabled") || c.includes("disabled"));
+  if (controlChanges.length > 0) {
+    score += 0.6;
+    reasons.push("control_state_changed");
+  }
+
+  // Cap at 1.0
+  score = Math.min(score, 1.0);
+
+  return {
+    score,
+    meaningful: score >= 0.6 || diff.routeChanged,
+    reasons,
+  };
+}
+
+/**
+ * Create UI change report from before/after snapshots and signals
+ */
+function createUIChangeReport(before, after, signals = []) {
+  const beforeHash = computeSemanticHash(before);
+  const afterHash = computeSemanticHash(after);
+  const diff = diffSnapshots(before, after);
+  const { score, meaningful, reasons } = calculateChangeScore(diff, signals);
+
+  return {
+    score,
+    meaningful,
+    reasons,
+    beforeSemanticHash: beforeHash,
+    afterSemanticHash: afterHash,
+    semanticDiffSummary: {
+      added: diff.added.slice(0, 10),
+      removed: diff.removed.slice(0, 10),
+      changed: diff.changed.slice(0, 10),
+    },
+    routeChanged: diff.routeChanged,
+    dialogOpened: diff.dialogOpened,
+    dialogClosed: diff.dialogClosed,
+    errorsChanged: diff.errorsChanged,
+    errorDelta: diff.errorDelta,
+  };
+}
+
+module.exports = {
+  CAPTURE_SCRIPT,
+  computeSemanticHash,
+  diffSnapshots,
+  calculateChangeScore,
+  createUIChangeReport,
+  IGNORE_TAGS,
+  IGNORE_SELECTORS,
+  MEANINGFUL_ROLES,
+};