chati-dev 4.2.1 → 4.3.0

package/framework/scripts/reference-capture.js

@@ -0,0 +1,430 @@
+#!/usr/bin/env node
+/**
+ * reference-capture.js — Visual Reference Capture for UX Planning
+ *
+ * Uses Playwright to capture screenshots + extract real CSS tokens from
+ * reference websites. Outputs data the UX Brand Architect uses to base
+ * visual direction proposals on REAL data, not AI guesses.
+ *
+ * Usage:
+ *   node reference-capture.js --urls "https://oryzo.ai" "https://landonorris.com" --output artifacts/4-UX/references/
+ *
+ * Per-site output:
+ *   <output>/<slug>/
+ *     ├── full-page.png
+ *     ├── scroll-{0,25,50,75,100}.png
+ *     ├── hover-{0..4}.png
+ *     ├── mobile.png, tablet.png
+ *     └── extracted-tokens.json
+ */
+
+import { mkdirSync, writeFileSync, readdirSync, renameSync, existsSync } from 'fs';
+import { join } from 'path';
+import { execSync } from 'child_process';
+
+// ---------------------------------------------------------------------------
+// Args
+// ---------------------------------------------------------------------------
+const args = process.argv.slice(2);
+let urls = [];
+let output = 'artifacts/4-UX/references';
+const TIMEOUT_PER_SITE = 45000;
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--urls') {
+    while (i + 1 < args.length && !args[i + 1].startsWith('--')) {
+      urls.push(args[++i]);
+    }
+  } else if (args[i] === '--output') output = args[++i];
+  else if (args[i] === '--help') {
+    console.log(`Usage: node reference-capture.js [options]
+  --urls "https://site1.com" "https://site2.com"   Reference URLs to analyze
+  --output artifacts/4-UX/references/               Output directory (default)
+  --help                                            Show this help`);
+    process.exit(0);
+  }
+}
+
+if (urls.length === 0) {
+  console.error('Error: No URLs provided. Use --urls "https://example.com"');
+  process.exit(1);
+}
+
+// ---------------------------------------------------------------------------
+// URL to slug
+// ---------------------------------------------------------------------------
+function urlToSlug(url) {
+  try {
+    const u = new URL(url);
+    return u.hostname.replace(/\./g, '-').replace(/^www-/, '');
+  } catch {
+    return url.replace(/[^a-z0-9]/gi, '-').slice(0, 40);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// CSS Token Extraction (runs inside the browser via page.evaluate)
+// ---------------------------------------------------------------------------
+const extractTokensScript = () => {
+  const tokens = {
+    colors: { backgrounds: {}, text: {}, all: {} },
+    typography: { families: {}, sizes: {}, weights: {} },
+    spacing: { sectionGaps: [], contentMaxWidth: null },
+    animations: {
+      gsap_loaded: typeof gsap !== 'undefined',
+      lenis_active: !!window.lenis,
+      scroll_trigger_count: 0,
+      transition_durations: {},
+    },
+    layout: { breakpoints: [], gridColumns: null },
+  };
+
+  // Helper: normalize color to hex
+  function rgbToHex(rgb) {
+    if (!rgb || rgb === 'transparent' || rgb === 'rgba(0, 0, 0, 0)') return null;
+    const match = rgb.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)/);
+    if (!match) return rgb;
+    return '#' + [match[1], match[2], match[3]].map(n => parseInt(n).toString(16).padStart(2, '0')).join('');
+  }
+
+  // Sample up to 500 visible elements for style data
+  const elements = document.querySelectorAll('body *');
+  const sample = Array.from(elements).slice(0, 500);
+
+  for (const el of sample) {
+    const style = getComputedStyle(el);
+    const rect = el.getBoundingClientRect();
+    if (rect.width === 0 && rect.height === 0) continue; // skip invisible
+
+    // Colors
+    const bg = rgbToHex(style.backgroundColor);
+    if (bg) tokens.colors.backgrounds[bg] = (tokens.colors.backgrounds[bg] || 0) + 1;
+    const color = rgbToHex(style.color);
+    if (color) tokens.colors.text[color] = (tokens.colors.text[color] || 0) + 1;
+    if (bg) tokens.colors.all[bg] = (tokens.colors.all[bg] || 0) + 1;
+    if (color) tokens.colors.all[color] = (tokens.colors.all[color] || 0) + 1;
+
+    // Typography (text elements only)
+    if (el.textContent.trim().length > 0 && ['P', 'H1', 'H2', 'H3', 'H4', 'H5', 'H6', 'SPAN', 'A', 'LI', 'TD', 'TH', 'LABEL', 'BUTTON'].includes(el.tagName)) {
+      const family = style.fontFamily.split(',')[0].trim().replace(/['"]/g, '');
+      tokens.typography.families[family] = (tokens.typography.families[family] || 0) + 1;
+      tokens.typography.sizes[style.fontSize] = (tokens.typography.sizes[style.fontSize] || 0) + 1;
+      tokens.typography.weights[style.fontWeight] = (tokens.typography.weights[style.fontWeight] || 0) + 1;
+    }
+
+    // Transition durations
+    if (style.transitionDuration && style.transitionDuration !== '0s') {
+      tokens.animations.transition_durations[style.transitionDuration] =
+        (tokens.animations.transition_durations[style.transitionDuration] || 0) + 1;
+    }
+  }
+
+  // Spacing: section-level gaps
+  const sections = document.querySelectorAll('section, [class*="section"], main > div');
+  for (const sec of Array.from(sections).slice(0, 20)) {
+    const style = getComputedStyle(sec);
+    const gap = parseInt(style.paddingTop) + parseInt(style.paddingBottom);
+    if (gap > 20) tokens.spacing.sectionGaps.push(`${gap}px`);
+  }
+  tokens.spacing.sectionGaps = [...new Set(tokens.spacing.sectionGaps)].sort((a, b) => parseInt(a) - parseInt(b));
+
+  // Content max-width
+  const main = document.querySelector('main') || document.querySelector('[class*="container"]');
+  if (main) tokens.spacing.contentMaxWidth = getComputedStyle(main).maxWidth;
+
+  // ScrollTrigger count
+  try {
+    if (typeof ScrollTrigger !== 'undefined') {
+      tokens.animations.scroll_trigger_count = ScrollTrigger.getAll().length;
+    }
+  } catch { /* not available */ }
+
+  // CSS custom properties count
+  const rootStyles = getComputedStyle(document.documentElement);
+  let customPropCount = 0;
+  for (let i = 0; i < rootStyles.length; i++) {
+    if (rootStyles[i].startsWith('--')) customPropCount++;
+  }
+  tokens.layout.customProperties = customPropCount;
+
+  // Sort colors/typography by frequency, keep top entries
+  function topN(obj, n = 10) {
+    return Object.entries(obj)
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, n)
+      .map(([value, count]) => ({ value, count }));
+  }
+
+  return {
+    colors: {
+      backgrounds: topN(tokens.colors.backgrounds),
+      text: topN(tokens.colors.text),
+      all: topN(tokens.colors.all, 15),
+    },
+    typography: {
+      families: topN(tokens.typography.families, 5),
+      sizes: topN(tokens.typography.sizes, 10),
+      weights: topN(tokens.typography.weights, 5),
+    },
+    spacing: tokens.spacing,
+    animations: {
+      gsap_loaded: tokens.animations.gsap_loaded,
+      lenis_active: tokens.animations.lenis_active,
+      scroll_trigger_count: tokens.animations.scroll_trigger_count,
+      transition_durations: topN(tokens.animations.transition_durations, 5),
+    },
+    layout: {
+      customProperties: tokens.layout.customProperties,
+    },
+  };
+};
+
+// ---------------------------------------------------------------------------
+// Capture single site
+// ---------------------------------------------------------------------------
+async function captureSite(browser, url, siteOutput) {
+  mkdirSync(siteOutput, { recursive: true });
+  const exec = execSync;
+
+  const consoleErrors = [];
+  const VIEWPORTS = [
+    { name: 'desktop', width: 1280, height: 800 },
+    { name: 'tablet',  width: 768,  height: 1024 },
+    { name: 'mobile',  width: 375,  height: 812 },
+  ];
+
+  // -------------------------------------------------------------------------
+  // Phase 1: Scroll videos — 3 viewports IN PARALLEL
+  // Each viewport: 5s load + up to 120s scroll = max 125s video
+  // -------------------------------------------------------------------------
+  console.log(`  Recording 3 viewports in parallel...`);
+
+  const scrollResults = await Promise.all(VIEWPORTS.map(async (vp) => {
+    const vpDir = join(siteOutput, vp.name);
+    mkdirSync(vpDir, { recursive: true });
+    const framesDir = join(vpDir, 'frames');
+    mkdirSync(framesDir, { recursive: true });
+
+    let ctx, page, scrollHeight = 0, maxScroll = 0, durationS = 0, frameCount = 0;
+
+    // Step 1: Open browser + navigate + scroll (video records automatically)
+    try {
+      ctx = await browser.newContext({
+        viewport: { width: vp.width, height: vp.height },
+        recordVideo: { dir: vpDir, size: { width: vp.width, height: vp.height } },
+      });
+      page = await ctx.newPage();
+      if (vp.name === 'desktop') {
+        page.on('console', msg => { if (msg.type() === 'error') consoleErrors.push(msg.text()); });
+        page.on('pageerror', err => consoleErrors.push(err.message));
+      }
+
+      await page.goto(url, { waitUntil: 'networkidle', timeout: TIMEOUT_PER_SITE });
+      await page.waitForTimeout(5000); // 5s load — user looks at hero
+
+      scrollHeight = await page.evaluate(() => document.documentElement.scrollHeight);
+      maxScroll = Math.max(0, scrollHeight - vp.height);
+
+      const MAX_SCROLL_MS = 120_000;
+      const PREFERRED_SPEED = 30;
+      const durationMs = Math.min(MAX_SCROLL_MS, Math.round((maxScroll / PREFERRED_SPEED) * 1000));
+      durationS = Math.round(durationMs / 1000);
+
+      // Time-based smooth scroll
+      const scrollStart = Date.now();
+      while (Date.now() - scrollStart < durationMs) {
+        const elapsed = Date.now() - scrollStart;
+        const targetY = Math.floor(maxScroll * elapsed / durationMs);
+        await page.evaluate(y => window.scrollTo(0, y), targetY);
+        await page.waitForTimeout(16);
+      }
+      await page.evaluate(y => window.scrollTo(0, y), maxScroll);
+      await page.waitForTimeout(1500);
+    } catch (scrollErr) {
+      // Scroll crashed — video is still partially recorded
+      console.log(`  ${vp.name}: scroll error (${scrollErr.message?.slice(0, 60)}) — extracting from partial video`);
+    }
+
+    // Step 2: Close page/context to FINALIZE video file (even after crash)
+    try { if (page) await page.close(); } catch { /* already closed */ }
+    try { if (ctx) await ctx.close(); } catch { /* already closed */ }
+
+    // Step 3: Rename ANY .webm found (works even if scroll crashed)
+    const videoPath = join(vpDir, `scroll-${vp.name}.webm`);
+    try {
+      const vids = readdirSync(vpDir).filter(f => f.endsWith('.webm') && !f.startsWith('scroll-'));
+      if (vids.length > 0) renameSync(join(vpDir, vids[0]), videoPath);
+    } catch { /* ignore */ }
+
+    // Step 4: Extract frames from video (works on partial videos too)
+    try {
+      const videoToExtract = existsSync(videoPath) ? videoPath : readdirSync(vpDir).find(f => f.endsWith('.webm'));
+      if (videoToExtract) {
+        const fullVideoPath = existsSync(videoPath) ? videoPath : join(vpDir, videoToExtract);
+        exec(`ffmpeg -i "${fullVideoPath}" -vf "fps=0.5" "${join(framesDir, 'frame-%03d.png')}" -y`, { stdio: 'ignore', timeout: 60000 });
+        frameCount = readdirSync(framesDir).filter(f => f.endsWith('.png')).length;
+      }
+    } catch { /* ffmpeg not available or video corrupt */ }
+
+    return { viewport: vp.name, scrollHeight, maxScroll, durationS, frameCount };
+  }));
+
+  for (const r of scrollResults) {
+    console.log(`  ${r.viewport}: ${r.maxScroll}px in ${r.durationS}s, ${r.frameCount} frames`);
+  }
+
+  // -------------------------------------------------------------------------
+  // Phase 2: Static captures (desktop only, no video recording)
+  // Full-page screenshot + hover states
+  // -------------------------------------------------------------------------
+  const ctx2 = await browser.newContext({ viewport: { width: 1280, height: 800 } });
+  const page2 = await ctx2.newPage();
+  await page2.goto(url, { waitUntil: 'networkidle', timeout: TIMEOUT_PER_SITE });
+  await page2.waitForTimeout(2000);
+
+  // Full-page screenshot
+  await page2.screenshot({ path: join(siteOutput, 'desktop', 'full-page.png'), fullPage: true });
+
+  // Scroll through once to trigger animations for token extraction
+  const scrollHeight = await page2.evaluate(() => document.documentElement.scrollHeight);
+  const maxScroll = Math.max(0, scrollHeight - 800);
+  const quickScrollStart = Date.now();
+  while (Date.now() - quickScrollStart < 10000) {
+    const elapsed = Date.now() - quickScrollStart;
+    await page2.evaluate(y => window.scrollTo(0, y), Math.floor(maxScroll * elapsed / 10000));
+    await page2.waitForTimeout(16);
+  }
+  await page2.evaluate(y => window.scrollTo(0, y), maxScroll);
+  await page2.waitForTimeout(1000);
+
+  // Hover states
+  await page2.evaluate(() => window.scrollTo(0, 0));
+  await page2.waitForTimeout(500);
+  const interactive = await page2.locator('button:visible, a[href]:visible, [role="button"]:visible').all();
+  for (let i = 0; i < Math.min(interactive.length, 5); i++) {
+    try {
+      await interactive[i].hover({ timeout: 3000 });
+      await page2.waitForTimeout(500);
+      await page2.screenshot({ path: join(siteOutput, 'desktop', `hover-${i}.png`) });
+    } catch { /* element may be obscured */ }
+  }
+
+  // Extract CSS tokens after full scroll
+  const tokens = await page2.evaluate(extractTokensScript);
+  tokens.url = url;
+  tokens.capturedAt = new Date().toISOString();
+  tokens.consoleErrors = consoleErrors;
+  tokens.scroll = {
+    height: scrollHeight,
+    viewports: scrollResults.map(r => ({ name: r.viewport, maxScroll: r.maxScroll, duration: r.durationS, frames: r.frameCount })),
+  };
+
+  writeFileSync(join(siteOutput, 'extracted-tokens.json'), JSON.stringify(tokens, null, 2));
+  await page2.close();
+  await ctx2.close();
+
+  return tokens;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+async function main() {
+  mkdirSync(output, { recursive: true });
+
+  let chromium;
+  // Try multiple resolution paths for playwright:
+  // 1. Project node_modules (normal npm install)
+  // 2. Bundled _cli/node_modules (chati.dev self-contained install)
+  // 3. NODE_PATH (set by handleAdvance)
+  const pwCandidates = [
+    () => import('playwright'),
+    () => import(join('..', '_cli', 'node_modules', 'playwright', 'index.mjs')),
+  ];
+  for (const tryImport of pwCandidates) {
+    try {
+      const pw = await tryImport();
+      chromium = pw.chromium || pw.default?.chromium;
+      if (chromium) break;
+    } catch { /* try next */ }
+  }
+  if (!chromium) {
+    console.error('Error: Playwright not installed. Run: npx playwright install chromium');
+    process.exit(1);
+  }
+
+  const browser = await chromium.launch({ headless: true });
+  const results = [];
+
+  for (const url of urls) {
+    const slug = urlToSlug(url);
+    const siteOutput = join(output, slug);
+    console.log(`\nCapturing: ${url} → ${slug}/`);
+
+    try {
+      const tokens = await captureSite(browser, url, siteOutput);
+      console.log(`  Colors: ${tokens.colors.all.length} unique`);
+      console.log(`  Fonts: ${tokens.typography.families.map(f => f.value).join(', ')}`);
+      console.log(`  GSAP: ${tokens.animations.gsap_loaded}, Lenis: ${tokens.animations.lenis_active}`);
+      console.log(`  Screenshots: full-page + 5 scroll + 5 hover + tablet + mobile`);
+      results.push({ url, slug, status: 'ok', tokens });
+    } catch (err) {
+      console.error(`  FAILED: ${err.message}`);
+      results.push({ url, slug, status: 'error', error: err.message });
+    }
+  }
+
+  await browser.close();
+
+  // Summary + completion marker
+  // capture-complete.json is the single file that Brand Architect polls for.
+  // Written ONLY when ALL sites finished (success or failure).
+  const siteResults = {};
+  for (const r of results) {
+    const framesDesktop = join(output, r.slug, 'desktop', 'frames');
+    const framesMobile = join(output, r.slug, 'mobile', 'frames');
+    const desktopCount = existsSync(framesDesktop) ? readdirSync(framesDesktop).filter(f => f.endsWith('.png')).length : 0;
+    const mobileCount = existsSync(framesMobile) ? readdirSync(framesMobile).filter(f => f.endsWith('.png')).length : 0;
+    siteResults[r.slug] = {
+      url: r.url,
+      status: r.status,
+      error: r.error || null,
+      frames: { desktop: desktopCount, mobile: mobileCount },
+      hasTokens: existsSync(join(output, r.slug, 'extracted-tokens.json')),
+    };
+  }
+
+  const captureComplete = {
+    completed: true,
+    completedAt: new Date().toISOString(),
+    totalSites: results.length,
+    totalCaptured: results.filter(r => r.status === 'ok').length,
+    totalFailed: results.filter(r => r.status === 'error').length,
+    sites: siteResults,
+  };
+
+  writeFileSync(join(output, 'capture-complete.json'), JSON.stringify(captureComplete, null, 2));
+  writeFileSync(join(output, 'capture-summary.json'), JSON.stringify(captureComplete, null, 2));
+  console.log(`\nSummary: ${captureComplete.totalCaptured} captured, ${captureComplete.totalFailed} failed`);
+  console.log(`Output: ${output}/`);
+
+  process.exit(captureComplete.totalFailed > 0 && captureComplete.totalCaptured === 0 ? 1 : 0);
+}
+
+main().catch(err => {
+  // Always write capture-complete.json even on crash — so wait-for-capture
+  // doesn't hang forever waiting for a file that will never appear.
+  try {
+    mkdirSync(output, { recursive: true });
+    writeFileSync(join(output, 'capture-complete.json'), JSON.stringify({
+      completed: true,
+      completedAt: new Date().toISOString(),
+      totalSites: 0,
+      totalCaptured: 0,
+      totalFailed: 1,
+      sites: {},
+      error: err.message?.slice(0, 200) || 'Unknown crash',
+    }, null, 2));
+  } catch { /* last resort — nothing we can do */ }
+  process.exit(1);
+});