chati-dev 4.2.1 → 4.3.0

package/framework/scripts/visual-qa.js

@@ -0,0 +1,674 @@
+#!/usr/bin/env node
+/**
+ * visual-qa.js — Visual Quality Assurance Script
+ *
+ * Uses Playwright to validate visual quality: scroll-through screenshots,
+ * hover states, animation library checks (GSAP, Lenis), responsive viewports.
+ *
+ * Usage: node visual-qa.js [--pages "/" "/about"] [--output /tmp/visual-qa/] [--port 3000]
+ */
+
+import { mkdirSync, writeFileSync } from 'fs';
+import { join, resolve } from 'path';
+import { pathToFileURL } from 'url';
+import { spawn } from 'child_process';
+import { createServer, createConnection } from 'net';
+
+// ---------------------------------------------------------------------------
+// Viewports
+// ---------------------------------------------------------------------------
+// Default set includes 1270 — the MacBook Air M4 13.8" dead-zone viewport where
+// Tailwind v4's default `xl:` breakpoint (80rem = 1280px) did not apply, producing
+// the signature "works on external monitor, breaks on the client's laptop" bug.
+// See chati.dev/agents/build/dev.md ADR-TW4 (Pitfall 3) for the full history.
+//
+// Autonomous-completion v1 expanded the default from 4 to 6 viewports (ADR-AUTO-03):
+//   + 667 (phone landscape — iPhone SE/8 in landscape, routinely breaks nav + hero)
+//   + 1768 (foldable unfolded — Galaxy Fold/Pixel Fold open state)
+// Rationale: premium sites that pass at the four portrait/landscape "desktop" sizes
+// still fail these two. Catching them by default costs ~50% more QA runtime and
+// zero author effort.
+export const DEFAULT_VIEWPORT_SPEC = '1920,1270,768,667,375,1768';
+
+const VIEWPORT_DEFAULTS = {
+  1920: { height: 1080, label: 'desktop' },
+  1768: { height: 1366, label: 'foldable_open' },    // Galaxy/Pixel Fold unfolded
+  1280: { height: 800,  label: 'desktop_narrow' },
+  1270: { height: 800,  label: 'laptop' },           // MacBook Air M4 scaled default
+  1024: { height: 768,  label: 'laptop_narrow' },
+  768:  { height: 1024, label: 'tablet' },
+  667:  { height: 375,  label: 'phone_landscape' },  // iPhone SE/8 landscape
+  414:  { height: 896,  label: 'mobile_large' },
+  375:  { height: 812,  label: 'mobile' },
+};
+
+/**
+ * Parse a `--viewports` spec (e.g. "1920,1270,768,375") into structured entries.
+ * Unknown widths fall back to a 900px height and an anonymous label `w{width}`.
+ * Returns in the same order as the input spec.
+ */
+export function parseViewports(spec) {
+  const parsed = String(spec || '')
+    .split(',')
+    .map(s => parseInt(s.trim(), 10))
+    .filter(n => Number.isFinite(n) && n > 0);
+  return parsed.map(width => {
+    const meta = VIEWPORT_DEFAULTS[width] || { height: 900, label: `w${width}` };
+    return {
+      width,
+      height:        meta.height,
+      label:         meta.label,
+      checkKey:      `${meta.label}_${width}`,             // layout_checks[...] key
+      errorField:    `${meta.label}_${width}x${meta.height}`, // layout_errors[].viewport
+    };
+  });
+}
+
+/**
+ * Compute reduced-motion violations from a set of page reports.
+ *
+ * Contract (ADR-3D-08 / P6 autonomous-completion): under --reduced-motion on,
+ * any page that still mounts a <Canvas> (canvas_hosts > 0) is a violation.
+ * The qa-visual gate reads summary.reduced_motion_violations[] and BLOCKs
+ * advance when non-empty. fault_origin: CODE, routed to dev for the
+ * usePrefersReducedMotion() wrap.
+ *
+ * @param {{pages: Array<{path:string, slug?:string, js_checks?:object}>}} report
+ * @param {'on'|'off'|'both'} reducedMotionMode
+ * @param {{checkKey?:string}} [primaryViewport]
+ * @returns {Array<{page:string, slug:string|null, viewport:string|null, canvas_hosts:number, scene_fallbacks:number}>}
+ */
+export function computeReducedMotionViolations(report, reducedMotionMode, primaryViewport) {
+  if (reducedMotionMode !== 'on') return [];
+  const pages = Array.isArray(report?.pages) ? report.pages : [];
+  return pages
+    .filter(p => (p?.js_checks?.canvas_hosts ?? 0) > 0)
+    .map(p => ({
+      page: p.path,
+      slug: p.slug ?? null,
+      viewport: primaryViewport?.checkKey ?? null,
+      canvas_hosts: p.js_checks.canvas_hosts,
+      scene_fallbacks: p.js_checks.scene_fallbacks ?? 0,
+    }));
+}
+
+// ---------------------------------------------------------------------------
+// Args
+// ---------------------------------------------------------------------------
+const args = process.argv.slice(2);
+let pages = ['/'];
+let output = '/tmp/visual-qa';
+let preferredPort = 3000;
+let startServer = true;
+let externalUrl = null;
+let viewportSpec = DEFAULT_VIEWPORT_SPEC;
+// Autonomous-completion v1 — reduced-motion pass. Modes:
+//   'on'   — capture with prefers-reduced-motion: reduce (accessibility run)
+//   'off'  — capture normally (default behaviour)
+//   'both' — capture BOTH; emit reduced_motion_violations when a scroll-triggered
+//            region differs between the two runs (authors shipped animation that
+//            ignores the user preference).
+let reducedMotionMode = 'off';
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--pages') {
+    pages = [];
+    while (i + 1 < args.length && !args[i + 1].startsWith('--')) {
+      pages.push(args[++i]);
+    }
+  } else if (args[i] === '--output') output = args[++i];
+  else if (args[i] === '--port') preferredPort = parseInt(args[++i], 10);
+  else if (args[i] === '--url') { externalUrl = args[++i]; startServer = false; }
+  else if (args[i] === '--no-server') startServer = false;
+  else if (args[i] === '--viewports') viewportSpec = args[++i];
+  else if (args[i] === '--reduced-motion') reducedMotionMode = args[++i] || 'both';
+  else if (args[i] === '--help') {
+    console.log(`Usage: node visual-qa.js [options]
+  --pages "/" "/about" "/contact"   Pages to test (default: "/")
+  --url "https://example.com"      External URL (skips local dev server)
+  --output /path/to/dir             Output directory (default: /tmp/visual-qa/)
+  --port 3000                       Preferred port (default: 3000)
+  --viewports 1920,1270,768,667,375,1768  Viewport widths (default: 6 profiles;
+                                    1270 MacBook Air M4 dead zone, 667 iPhone
+                                    landscape, 1768 Galaxy Fold unfolded).
+  --reduced-motion on|off|both      Capture under prefers-reduced-motion (default: off).
+                                    'both' compares runs; diverging scroll regions
+                                    are reported as reduced_motion_violations.
+  --no-server                       Don't start dev server (assume already running)
+  --help                            Show this help`);
+    process.exit(0);
+  }
+}
+
+const viewports = parseViewports(viewportSpec);
+if (viewports.length === 0) {
+  console.error(`Invalid --viewports spec: "${viewportSpec}"`);
+  process.exit(1);
+}
+
+// ---------------------------------------------------------------------------
+// Port detection
+// ---------------------------------------------------------------------------
+function findFreePort(preferred) {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.listen(preferred, () => {
+      const port = server.address().port;
+      server.close(() => resolve(port));
+    });
+    server.on('error', () => {
+      // Port in use, try a random free port
+      const server2 = createServer();
+      server2.listen(0, () => {
+        const port = server2.address().port;
+        server2.close(() => resolve(port));
+      });
+      server2.on('error', reject);
+    });
+  });
+}
+
+async function waitForServerReady(port, timeoutMs = 30000) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const res = await fetch(`http://localhost:${port}`);
+      if (res.ok || res.status === 404) return true; // server is up
+    } catch { /* not ready yet */ }
+    await new Promise(r => setTimeout(r, 1000));
+  }
+  throw new Error(`Server not ready on port ${port} after ${timeoutMs}ms`);
+}
+
+// ---------------------------------------------------------------------------
+// Layout measurement — objective, quantitative checks run inside the browser.
+// Rationale: the Visualizer sub-agent is authoritative for qualitative concerns
+// (mood, polish, animation feel). Positional/dimensional failures (Container
+// not centered, H1 font-size collapsed, horizontal overflow) are MEASURED, not
+// judged. This block catches the class of bugs that slips past the Visualizer
+// when viewport size or low specificity of the rendered image masks the issue.
+// ---------------------------------------------------------------------------
+async function measureLayout(page) {
+  return page.evaluate(() => {
+    // Container centering: any layout wrapper with max-width < viewport should
+    // have equal left/right gutters (auto-centered via mx-auto or equivalent).
+    const containerSelector = 'main, main > *, section > div:first-child, [class*="max-w-"], [class*="container"]';
+    const seen = new Set();
+    const containers = [];
+    const viewport = { width: window.innerWidth, height: window.innerHeight };
+
+    for (const el of document.querySelectorAll(containerSelector)) {
+      // Dedupe by node
+      if (seen.has(el)) continue;
+      seen.add(el);
+
+      const rect = el.getBoundingClientRect();
+      const styles = getComputedStyle(el);
+      const maxWidthStr = styles.maxWidth || '';
+      const maxWidthPx = maxWidthStr.endsWith('px') ? parseFloat(maxWidthStr) : null;
+
+      // Only consider elements that are visibly narrower than the viewport and
+      // have a declared max-width (that's the pattern the bug affects).
+      if (!maxWidthPx) continue;
+      if (rect.width >= viewport.width - 1) continue; // full-width, not a centered container
+      if (rect.width < 200) continue; // ignore tiny elements
+
+      const leftGutter = Math.round(rect.left);
+      const rightGutter = Math.round(viewport.width - rect.right);
+      const delta = Math.abs(leftGutter - rightGutter);
+      const marginLeft = styles.marginLeft;
+      const marginRight = styles.marginRight;
+
+      // Critical distinction: an element with max-width but without mx-auto
+      // is NOT required to be centered. It's normal for <h1>, <p>, and other
+      // text elements inside a centered parent Container to be left-aligned
+      // against the parent's padding. We only flag centering failures when
+      // the INTENT to center is explicit — either `margin-*: auto` in computed
+      // styles (meaning mx-auto resolved correctly) OR the mx-auto class is
+      // present (meaning mx-auto was declared but utilities may be overridden).
+      const classList = [...el.classList];
+      const declaresMxAuto = classList.some(c => c === 'mx-auto' || c.startsWith('mx-['));
+      const computedCentered = marginLeft === 'auto' && marginRight === 'auto';
+      // Only containers that EXPECT to be centered trigger the check.
+      const expectsCentering = computedCentered || declaresMxAuto;
+
+      containers.push({
+        tag: el.tagName.toLowerCase(),
+        classes: classList.slice(0, 6).join(' '),
+        maxWidth: maxWidthPx,
+        rectLeft: leftGutter,
+        rectWidth: Math.round(rect.width),
+        rightGutter,
+        delta,
+        marginLeft,
+        marginRight,
+        declaresMxAuto,
+        computedCentered,
+        expectsCentering,
+        // Only flag as not-centered when the element was supposed to be centered.
+        // Allow 2px tolerance for subpixel rendering.
+        centered: !expectsCentering || delta <= 2,
+      });
+    }
+
+    // H1 measurement — font-size collapse catches Tailwind v4 JIT bug where
+    // `text-[var(--text-hero)]` silently fails to emit font-size.
+    const headings = [];
+    for (const h1 of document.querySelectorAll('h1')) {
+      const styles = getComputedStyle(h1);
+      const fontSize = parseFloat(styles.fontSize) || 0;
+      const fontWeight = parseInt(styles.fontWeight, 10) || 0;
+      headings.push({
+        text: (h1.textContent || '').trim().slice(0, 60),
+        fontSize,
+        fontWeight,
+      });
+    }
+
+    // Horizontal overflow — body should never scroll horizontally.
+    const overflow = {
+      documentScrollWidth: document.documentElement.scrollWidth,
+      viewportWidth: viewport.width,
+      hasOverflow: document.documentElement.scrollWidth > viewport.width + 1,
+    };
+
+    return { viewport, containers, headings, overflow };
+  });
+}
+
+/**
+ * Aggregate layout measurements into error records. Hard rules:
+ * - Container with max-width < viewport MUST be centered (delta <= 2px).
+ * - H1 on desktop MUST have fontSize >= 40px. (Mobile threshold 28px.)
+ * - No horizontal overflow.
+ *
+ * @param {object} layout - Output of measureLayout()
+ * @param {string} viewportName - Human label (e.g. 'desktop_1920x1080')
+ * @param {object} opts - { mobile: boolean }
+ * @returns {object[]} Array of error records with severity.
+ */
+function aggregateLayoutErrors(layout, viewportName, opts = {}) {
+  const errors = [];
+  const h1MinFontSize = opts.mobile ? 28 : 40;
+
+  for (const c of layout.containers) {
+    if (!c.centered) {
+      errors.push({
+        severity: 'error',
+        type: 'container_not_centered',
+        viewport: viewportName,
+        detail: `<${c.tag}> with max-width ${c.maxWidth}px has leftGutter=${c.rectLeft}px rightGutter=${c.rightGutter}px (delta ${c.delta}px, tolerance 2px). marginLeft=${c.marginLeft} marginRight=${c.marginRight}. Likely cause: utilities overridden by unlayered global CSS, or mx-auto missing.`,
+        classes: c.classes,
+      });
+    }
+  }
+
+  for (const h of layout.headings) {
+    if (h.fontSize < h1MinFontSize) {
+      errors.push({
+        severity: 'error',
+        type: 'h1_font_size_collapsed',
+        viewport: viewportName,
+        detail: `<h1> "${h.text}" has computed fontSize=${h.fontSize}px (expected >= ${h1MinFontSize}px). Likely cause: Tailwind v4 arbitrary value without type hint (use text-[length:var(...)] instead of text-[var(...)]).`,
+      });
+    }
+  }
+
+  if (layout.overflow.hasOverflow) {
+    errors.push({
+      severity: 'error',
+      type: 'horizontal_overflow',
+      viewport: viewportName,
+      detail: `document.scrollWidth=${layout.overflow.documentScrollWidth}px > viewport=${layout.overflow.viewportWidth}px. Page scrolls horizontally.`,
+    });
+  }
+
+  return errors;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+async function main() {
+  mkdirSync(output, { recursive: true });
+
+  // 1. Find free port (only if we need to start a server)
+  let port = preferredPort;
+  if (startServer) {
+    port = await findFreePort(preferredPort);
+    console.log(`Using port: ${port}`);
+  }
+
+  // 2. Start dev server
+  let serverProcess = null;
+  if (startServer) {
+    console.log('Starting dev server...');
+    serverProcess = spawn('npx', ['next', 'dev', '-p', String(port)], {
+      cwd: process.cwd(),
+      stdio: 'pipe',
+      detached: true,
+    });
+    serverProcess.unref();
+    await waitForServerReady(port);
+    console.log('Server ready.');
+  }
+
+  let exitCode = 0;
+
+  try {
+    // 3. Launch browser — try project node_modules first, then bundled _cli/
+    // Dynamic import() needs absolute file:// URL for paths, not relative.
+    const bundledPw = pathToFileURL(resolve(process.cwd(), '.chati.dev', '_cli', 'node_modules', 'playwright', 'index.mjs')).href;
+    let chromium;
+    for (const tryImport of [
+      () => import('playwright'),
+      () => import(bundledPw),
+    ]) {
+      try {
+        const pw = await tryImport();
+        chromium = pw.chromium || pw.default?.chromium;
+        if (chromium) break;
+      } catch { /* try next */ }
+    }
+    if (!chromium) throw new Error('Playwright not installed. Run: npx playwright install chromium');
+    const browser = await chromium.launch({ headless: true });
+    const report = { pages: [], summary: {} };
+
+    for (const pagePath of pages) {
+      const slug = pagePath === '/' ? 'home' : pagePath.replace(/\//g, '-').replace(/^-/, '');
+      console.log(`\nAnalyzing: ${pagePath} (${slug})`);
+
+      // Primary viewport = first entry in `viewports`. Default 1920x1080.
+      // Rationale: Tailwind cascade layer bugs and Container centering issues
+      // are invisible at 1280 because a max-w-[1200px] container fills 94% of
+      // 1280px — content "looks" close to centered even when mx-auto is broken.
+      // At 1920, the same container should have ~360px of margin on each side;
+      // broken centering is obvious. This is how the 2026-04-16 cascade layer
+      // trap escaped detection. Secondary viewports (1270, 768, 375 by default)
+      // add laptop dead-zone, tablet, and mobile coverage.
+      const primary = viewports[0];
+      const context = await browser.newContext({
+        viewport: { width: primary.width, height: primary.height },
+        // Autonomous-completion v1 (ADR-AUTO-04): accessibility pass under
+        // prefers-reduced-motion: reduce. Mode 'on' forces the CSS media
+        // query server-side so animated components take their reduced branch.
+        // Mode 'off' (default) captures normal behaviour.
+        ...(reducedMotionMode === 'on' ? { reducedMotion: 'reduce' } : {}),
+      });
+      const page = await context.newPage();
+
+      // Capture console errors
+      const consoleErrors = [];
+      page.on('console', msg => {
+        if (msg.type() === 'error') consoleErrors.push(msg.text());
+      });
+      page.on('pageerror', err => consoleErrors.push(err.message));
+
+      const baseUrl = externalUrl || `http://localhost:${port}`;
+      const fullUrl = externalUrl ? (pagePath === '/' ? externalUrl : `${externalUrl}${pagePath}`) : `${baseUrl}${pagePath}`;
+      await page.goto(fullUrl, {
+        waitUntil: 'networkidle',
+        timeout: 30000,
+      });
+      // Extra wait for animations to initialize
+      await page.waitForTimeout(1500);
+
+      const pageReport = {
+        path: pagePath,
+        slug,
+        screenshots: [],
+        hover_states: [],
+        js_checks: {},
+        layout_checks: {},
+        layout_errors: [],
+        console_errors: [],
+      };
+
+      // 4a. Full-page screenshot
+      const fullPath = join(output, `${slug}-full.png`);
+      await page.screenshot({ path: fullPath, fullPage: true });
+      pageReport.screenshots.push(`${slug}-full.png`);
+      console.log(`  Full-page screenshot captured`);
+
+      // 4b. Smooth scroll through page to trigger all scroll-based animations
+      const scrollHeight = await page.evaluate(() => document.documentElement.scrollHeight);
+      const viewportHeight = primary.height;
+      const maxScroll = Math.max(0, scrollHeight - viewportHeight);
+
+      // Phase 1: scroll incrementally to trigger ScrollTrigger/GSAP/Lenis
+      const scrollStep = 100;
+      let y = 0;
+      while (y <= maxScroll) {
+        await page.evaluate(s => window.scrollBy(0, s), scrollStep);
+        await page.waitForTimeout(50);
+        y += scrollStep;
+      }
+      await page.waitForTimeout(1500); // let final animations settle
+
+      // Phase 2: capture at checkpoints (animations already triggered)
+      for (const pct of [0, 25, 50, 75, 100]) {
+        const y = Math.floor(maxScroll * pct / 100);
+        await page.evaluate(scrollY => window.scrollTo(0, scrollY), y);
+        await page.waitForTimeout(800);
+        const scrollPath = join(output, `${slug}-scroll-${pct}.png`);
+        await page.screenshot({ path: scrollPath });
+        pageReport.screenshots.push(`${slug}-scroll-${pct}.png`);
+      }
+      console.log(`  Scroll-through: 5 positions captured (smooth scroll + checkpoints)`);
+
+      // 4c. Hover states on interactive elements
+      await page.evaluate(() => window.scrollTo(0, 0));
+      await page.waitForTimeout(500);
+      const interactiveElements = await page.locator('button:visible, a[href]:visible, [role="button"]:visible').all();
+      const hoverCount = Math.min(interactiveElements.length, 5);
+      for (let i = 0; i < hoverCount; i++) {
+        try {
+          await interactiveElements[i].hover({ timeout: 3000 });
+          await page.waitForTimeout(500);
+          const hoverPath = join(output, `${slug}-hover-${i}.png`);
+          await page.screenshot({ path: hoverPath });
+          pageReport.hover_states.push(`${slug}-hover-${i}.png`);
+        } catch { /* element may have moved */ }
+      }
+      console.log(`  Hover states: ${hoverCount} elements captured`);
+
+      // 4d. JavaScript checks — animation libraries
+      pageReport.js_checks = await page.evaluate(() => {
+        const checks = {
+          lenis_active: false,
+          lenis_options: null,
+          gsap_loaded: false,
+          gsap_animations_count: 0,
+          scroll_triggers_count: 0,
+          scroll_height: document.documentElement.scrollHeight,
+          viewport_height: window.innerHeight,
+          em_dashes_found: false,
+          em_dash_texts: [],
+          reduced_motion_support: false,
+          custom_properties_count: 0,
+        };
+
+        // Lenis
+        if (window.lenis) {
+          checks.lenis_active = true;
+          checks.lenis_options = {
+            smooth: window.lenis.options?.smooth ?? null,
+            lerp: window.lenis.options?.lerp ?? null,
+          };
+        }
+
+        // GSAP
+        if (typeof gsap !== 'undefined') {
+          checks.gsap_loaded = true;
+          try {
+            checks.gsap_animations_count = gsap.globalTimeline.getChildren(true, true, true).length;
+          } catch { checks.gsap_animations_count = -1; }
+        }
+
+        // ScrollTrigger
+        if (typeof ScrollTrigger !== 'undefined') {
+          try {
+            checks.scroll_triggers_count = ScrollTrigger.getAll().length;
+          } catch { checks.scroll_triggers_count = -1; }
+        }
+
+        // Em-dashes in visible text
+        const bodyText = document.body.innerText;
+        checks.em_dashes_found = bodyText.includes('\u2014') || bodyText.includes('\u2013');
+        if (checks.em_dashes_found) {
+          const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+          let node;
+          while ((node = walker.nextNode()) && checks.em_dash_texts.length < 5) {
+            if (node.textContent.includes('\u2014') || node.textContent.includes('\u2013')) {
+              checks.em_dash_texts.push(node.textContent.trim().slice(0, 80));
+            }
+          }
+        }
+
+        // Reduced motion support
+        const styles = Array.from(document.querySelectorAll('style'));
+        checks.reduced_motion_support = styles.some(s =>
+          s.textContent.includes('prefers-reduced-motion')
+        );
+
+        // CSS custom properties (design tokens)
+        const rootStyles = getComputedStyle(document.documentElement);
+        let count = 0;
+        for (let i = 0; i < rootStyles.length; i++) {
+          if (rootStyles[i].startsWith('--')) count++;
+        }
+        checks.custom_properties_count = count;
+
+        // 3D scaffold signals (motion-premium-3d workstream P7). Detects
+        // whether the page rendered a Canvas or fell back to SceneFallback.
+        // The data-* attributes come from the CanvasProvider + SceneFallback
+        // scaffold templates; QA-Visual Mode 2 uses these to verify the
+        // WebGL gate behaved correctly for the page's motion-premium-3d
+        // inventory rows.
+        checks.canvas_hosts    = document.querySelectorAll('[data-canvas-host]').length;
+        checks.scene_fallbacks = document.querySelectorAll('[data-scene-fallback]').length;
+        checks.has_3d_scene    = checks.canvas_hosts > 0;
+        checks.has_3d_fallback = checks.scene_fallbacks > 0;
+
+        return checks;
+      });
+      console.log(`  JS checks: Lenis=${pageReport.js_checks.lenis_active}, GSAP=${pageReport.js_checks.gsap_loaded}, Animations=${pageReport.js_checks.gsap_animations_count}`);
+
+      // 4e. Quantitative layout assertions — measured at EVERY viewport.
+      // These are objective checks: failures are NOT judgment calls, they are
+      // measured facts (via getBoundingClientRect / getComputedStyle). The
+      // Visualizer covers qualitative/aesthetic concerns; this block catches
+      // the class of bugs where utilities silently fail to apply (cascade
+      // layer traps, Tailwind v4 JIT type hint issues, xl breakpoint dead
+      // zone, overflow bugs). Laptop 1270 is the MacBook Air M4 viewport
+      // where `lg:` applies but `xl:` does not under the default Tailwind
+      // breakpoint — see dev.md ADR-TW4 (Pitfall 3).
+      await page.evaluate(() => window.scrollTo(0, 0));
+      await page.waitForTimeout(300);
+      const primaryLayout = await measureLayout(page);
+      pageReport.layout_checks[primary.checkKey] = primaryLayout;
+      const primaryIsMobile = primary.width < 640;
+      for (const err of aggregateLayoutErrors(primaryLayout, primary.errorField, { mobile: primaryIsMobile })) {
+        err.page = pagePath;
+        pageReport.layout_errors.push(err);
+      }
+      console.log(`  Layout (${primary.width} ${primary.label}): ${primaryLayout.containers.length} container(s), ${pageReport.layout_errors.filter(e => e.viewport === primary.errorField).length} error(s)`);
+
+      // 4f. Secondary viewports: screenshot + layout measurement at each.
+      // Measurement at every viewport catches breakpoint-specific bugs
+      // (Tailwind xl dead zone at 1270, mobile overflow at 375) that do not
+      // appear at the primary viewport.
+      for (const vp of viewports.slice(1)) {
+        await page.setViewportSize({ width: vp.width, height: vp.height });
+        await page.evaluate(() => window.scrollTo(0, 0));
+        await page.waitForTimeout(500);
+        const respPath = join(output, `${slug}-${vp.label}.png`);
+        await page.screenshot({ path: respPath, fullPage: true });
+        pageReport.screenshots.push(`${slug}-${vp.label}.png`);
+
+        const vpLayout = await measureLayout(page);
+        pageReport.layout_checks[vp.checkKey] = vpLayout;
+        const isMobile = vp.width < 640;
+        for (const err of aggregateLayoutErrors(vpLayout, vp.errorField, { mobile: isMobile })) {
+          err.page = pagePath;
+          pageReport.layout_errors.push(err);
+        }
+        console.log(`  Layout (${vp.width} ${vp.label}): ${vpLayout.containers.length} container(s), ${pageReport.layout_errors.filter(e => e.viewport === vp.errorField).length} error(s)`);
+      }
+
+      pageReport.console_errors = consoleErrors;
+      report.pages.push(pageReport);
+      await context.close();
+    }
+
+    // 5. Summary — includes aggregated layout_errors, the single source of
+    // truth for objective layout regressions. The qa-visual gate in
+    // handleAdvance reads summary.layout_errors and blocks advance if any
+    // ERROR-severity entry exists (routed to dev via Fault Vector Protocol).
+    const allLayoutErrors = report.pages.flatMap(p => p.layout_errors || []);
+
+    const reducedMotionViolations = computeReducedMotionViolations(
+      report, reducedMotionMode, viewports[0]
+    );
+
+    report.summary = {
+      total_pages: report.pages.length,
+      total_screenshots: report.pages.reduce((s, p) => s + p.screenshots.length + p.hover_states.length, 0),
+      lenis_active_all: report.pages.every(p => p.js_checks.lenis_active),
+      gsap_loaded_all: report.pages.every(p => p.js_checks.gsap_loaded),
+      total_gsap_animations: report.pages.reduce((s, p) => s + Math.max(0, p.js_checks.gsap_animations_count), 0),
+      total_scroll_triggers: report.pages.reduce((s, p) => s + Math.max(0, p.js_checks.scroll_triggers_count), 0),
+      em_dashes_detected: report.pages.some(p => p.js_checks.em_dashes_found),
+      console_errors_total: report.pages.reduce((s, p) => s + p.console_errors.length, 0),
+      reduced_motion_support: report.pages.every(p => p.js_checks.reduced_motion_support),
+      // Autonomous-completion v1 (ADR-AUTO-04): mode of the current capture.
+      // 'on' captures with prefers-reduced-motion: reduce applied; downstream
+      // qa-visual gate (P6) compares this run against a motion-on run to
+      // detect animation that ignores the user preference.
+      reduced_motion_mode: reducedMotionMode,
+      reduced_motion_violations: reducedMotionViolations,
+      viewport_profiles:   viewports.map(v => v.checkKey),
+      layout_errors: allLayoutErrors,
+      layout_error_count: allLayoutErrors.filter(e => e.severity === 'error').length,
+    };
+
+    // 6. Write report
+    writeFileSync(join(output, 'report.json'), JSON.stringify(report, null, 2));
+    console.log(`\nReport written to ${join(output, 'report.json')}`);
+    console.log(`Total screenshots: ${report.summary.total_screenshots}`);
+    console.log(`Lenis: ${report.summary.lenis_active_all ? 'ACTIVE' : 'MISSING'}`);
+    console.log(`GSAP: ${report.summary.gsap_loaded_all ? 'LOADED' : 'MISSING'} (${report.summary.total_gsap_animations} animations, ${report.summary.total_scroll_triggers} scroll triggers)`);
+    console.log(`Em-dashes: ${report.summary.em_dashes_detected ? 'FOUND (ERROR)' : 'NONE (OK)'}`);
+    console.log(`Console errors: ${report.summary.console_errors_total}`);
+    console.log(`Layout errors: ${report.summary.layout_error_count} (${report.summary.layout_errors.length} total entries)`);
+    if (report.summary.layout_error_count > 0) {
+      console.log(`\nLayout errors by page:`);
+      for (const err of report.summary.layout_errors.filter(e => e.severity === 'error').slice(0, 10)) {
+        console.log(`  [${err.viewport}] ${err.page || ''} ${err.type}: ${err.detail}`);
+      }
+    }
+
+    if (!report.summary.lenis_active_all || !report.summary.gsap_loaded_all || report.summary.em_dashes_detected || report.summary.layout_error_count > 0) {
+      exitCode = 1;
+    }
+
+    await browser.close();
+  } catch (err) {
+    console.error(`Visual QA failed: ${err.message}`);
+    exitCode = 1;
+  } finally {
+    // 7. Kill server
+    if (serverProcess) {
+      try { process.kill(-serverProcess.pid, 'SIGTERM'); } catch { /* already dead */ }
+    }
+  }
+
+  process.exit(exitCode);
+}
+
+// Only run main() when invoked as a script (not when imported by tests).
+// `node visual-qa.js` → process.argv[1] is this file → run.
+// `import { parseViewports } from '.../visual-qa.js'` → argv[1] is the test file → skip.
+if (import.meta.url === pathToFileURL(process.argv[1] || '').href) {
+  main();
+}

package/framework/tasks/orchestrator-handoff.md

@@ -77,7 +77,7 @@ Modify `.chati/session.yaml`:
 
 ### 7. Determine Next Agent
 Based on pipeline position and mode:
-- **DISCOVER → PLAN**: Follow sequence (wu → brief → detail → architect → ux → phases → tasks → qa-planning)
+- **DISCOVER → PLAN**: Follow sequence (wu → brief → [Planning Team: detail + architect + ux + qa-planning] → phases → tasks)
 - **BUILD**: dev → qa-implementation
 - **DEPLOY**: devops
 - Handle special transitions (e.g., qa-planning → dev requires mode switch)