codeply-cli 0.5.5 → 0.6.0

package/skills/codeply-taste/scripts/inspect.mjs

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+// tasteskill / inspect — render the page in a real browser, measure it, and photograph it.
+//
+//   node inspect.mjs <url | path/to/file.html> [--out DIR] [--widths 1440,768,390] [--allow rule,rule] [--json]
+//
+// Exit code 0 = no FAIL findings. Exit code 1 = at least one FAIL (the page is not done).
+// Zero dependencies: drives an installed Chrome/Edge/Chromium. Node 22+.
+import { existsSync, mkdirSync, readFileSync, writeFileSync, statSync, createReadStream, readdirSync, unlinkSync } from 'node:fs';
+import { resolve, join, relative, dirname, extname, sep } from 'node:path';
+import { createServer } from 'node:http';
+import { Browser, sleep } from './lib/cdp.mjs';
+import { probe, frame } from './lib/probe.mjs';
+import { judge } from './lib/rules.mjs';
+
+const args = process.argv.slice(2);
+const flag = (name, def) => { const i = args.indexOf('--' + name); if (i === -1) return def; const v = args[i + 1]; args.splice(i, 2); return v; };
+const has = (name) => { const i = args.indexOf('--' + name); if (i === -1) return false; args.splice(i, 1); return true; };
+const outDir = resolve(flag('out', '.taste-skill/inspect'));
+const widths = flag('widths', '1440,768,390').split(',').map(Number).filter(Boolean);
+let allow = flag('allow', '').split(',').filter(Boolean);
+const asJson = has('json');
+const target = args[0];
+if (!target || target === '-h' || target.startsWith('--')) {
+  console.error('usage: node inspect.mjs <url | file.html> [--out DIR] [--widths 1440,768,390] [--allow rule,rule] [--json]');
+  process.exit(2);
+}
+// Allowances granted by the drawn direction (written by draw.mjs) apply automatically.
+for (const p of ['.taste-skill/direction.json', join(outDir, '..', 'direction.json')]) {
+  if (existsSync(p)) { try { allow = [...new Set([...allow, ...(JSON.parse(readFileSync(p, 'utf8')).allow || [])])]; } catch {} break; }
+}
+// A local file is served over http from a throwaway server on 127.0.0.1, so the browser never has to
+// open a file path (some sandboxes show Node and the browser different views of the disk) and relative
+// assets, fetch() and module scripts behave as they will when the page is hosted.
+let url = target; let server = null;
+if (!/^https?:\/\//.test(target)) {
+  const file = resolve(target);
+  if (!existsSync(file)) { console.error('No such file: ' + file); process.exit(2); }
+  const cwd = resolve('.');
+  const root = file.startsWith(cwd + sep) ? cwd : dirname(file);
+  const MIME = { '.html': 'text/html; charset=utf-8', '.htm': 'text/html; charset=utf-8', '.css': 'text/css; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.mjs': 'text/javascript; charset=utf-8', '.json': 'application/json', '.svg': 'image/svg+xml', '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.avif': 'image/avif', '.gif': 'image/gif', '.ico': 'image/x-icon', '.woff': 'font/woff', '.woff2': 'font/woff2', '.ttf': 'font/ttf', '.otf': 'font/otf', '.mp4': 'video/mp4', '.webm': 'video/webm', '.txt': 'text/plain; charset=utf-8', '.xml': 'application/xml', '.webmanifest': 'application/manifest+json' };
+  server = createServer((req, res) => {
+    try {
+      let f = resolve(join(root, decodeURIComponent(new URL(req.url, 'http://x').pathname)));
+      if (f !== root && !f.startsWith(root + sep)) { res.writeHead(403); return res.end(); }
+      if (statSync(f).isDirectory()) f = join(f, 'index.html');
+      res.writeHead(200, { 'content-type': MIME[extname(f).toLowerCase()] || 'application/octet-stream', 'content-length': statSync(f).size, 'cache-control': 'no-store' });
+      createReadStream(f).pipe(res);
+    } catch { res.writeHead(404); res.end('not found'); }
+  });
+  await new Promise((r) => server.listen(0, '127.0.0.1', r));
+  url = `http://127.0.0.1:${server.address().port}/${relative(root, file).split(sep).map(encodeURIComponent).join('/')}`;
+}
+const HEIGHT = { 1440: 900, 1280: 800, 1024: 768, 768: 1024, 390: 844, 375: 812 };
+const name = (w) => (w >= 1100 ? 'desktop' : w >= 600 ? 'tablet' : 'mobile');
+
+mkdirSync(outDir, { recursive: true });
+// Screenshots from an earlier run would sit beside the new ones when the page got shorter.
+for (const f of readdirSync(outDir)) if (/^(desktop|tablet|mobile)-(fold|page-\d+)\.jpg$/.test(f)) unlinkSync(join(outDir, f));
+const browser = await Browser.launch();
+const helper = await browser.newPage({ width: 1600, height: 1000 });
+const report = { url: server ? target : url, at: new Date().toISOString(), allow, viewports: [], findings: [], images: [] };
+
+const MOTION_MIN = 8, MOTION_GOOD = 16; // distinct moving elements over load + one scroll through the page
+// Runs in the page before any of its own scripts: counts the distinct elements that actually move while
+// the page loads and is scrolled (CSS animations, CSS transitions, Web Animations, and script-driven
+// transform/opacity changes such as GSAP), so a page that never moves can be told from one that does.
+const MOTION_RECORDER = `(() => {
+  const seen = new WeakSet(); const c = { elements: 0, css: 0, transitions: 0, scripted: 0 };
+  const note = (t, k) => { if (!(t instanceof Element) || seen.has(t)) return; seen.add(t); c.elements++; c[k]++; };
+  addEventListener('animationstart', (e) => note(e.target, 'css'), true);
+  addEventListener('transitionrun', (e) => note(e.target, 'transitions'), true);
+  const watch = () => new MutationObserver((list) => { for (const m of list) { const s = m.target.getAttribute && m.target.getAttribute('style') || ''; if (/transform|translate|opacity|scale|rotate|clip-path/.test(s)) note(m.target, 'scripted'); } })
+    .observe(document.documentElement, { attributes: true, attributeFilter: ['style'], subtree: true });
+  if (document.documentElement) watch(); else addEventListener('DOMContentLoaded', watch);
+  window.__motionSample = () => { for (const a of document.getAnimations ? document.getAnimations() : []) { const t = a.effect && a.effect.target; if (t) note(t, a.constructor && a.constructor.name === 'CSSTransition' ? 'transitions' : 'css'); } };
+  window.__motion = () => { window.__motionSample(); const v = [...document.querySelectorAll('video')]; return { ...c, videos: v.length, playingVideos: v.filter((x) => x.autoplay || !x.paused).length }; };
+})();`;
+
+async function sheet(frames, cols, cellW, cellH, path) {
+  const rows = Math.ceil(frames.length / cols);
+  await helper.setViewport({ width: cols * cellW, height: rows * cellH, dsf: 1 });
+  await helper.eval((a) => {
+    document.body.style.cssText = `margin:0;background:#888;display:grid;grid-template-columns:repeat(${a.cols},${a.cellW}px)`;
+    document.body.innerHTML = a.frames.map((s) => `<img src="data:image/jpeg;base64,${s}" style="width:${a.cellW}px;height:${a.cellH}px;display:block;outline:1px solid #888">`).join('');
+    return Promise.all([...document.images].map((i) => i.decode().catch(() => {})));
+  }, { frames, cols, cellW, cellH });
+  await helper.screenshot({ path, quality: 76 });
+}
+
+try {
+  for (const w of widths) {
+    const h = HEIGHT[w] || Math.round(w * 0.625);
+    const label = name(w);
+    const page = await browser.newPage({ width: w, height: h, dsf: 1, mobile: w < 600 });
+    await page.send('Page.addScriptToEvaluateOnNewDocument', { source: MOTION_RECORDER }).catch(() => {});
+    const how = await page.goto(url, { timeoutMs: 30000, settleMs: 600 });
+    await page.eval('document.fonts.ready.then(() => true)').catch(() => {});
+    await sleep(1400); // let the load choreography finish before judging the first screen
+    const fold = join(outDir, `${label}-fold.jpg`);
+    await page.screenshot({ path: fold, quality: 82 });
+    const metrics = await page.eval(probe);
+
+    // walk the page one screen at a time so scroll reveals fire, photographing each screen
+    const frames = [readFileSync(fold).toString('base64')];
+    const frameChecks = [await page.eval(frame).catch(() => null)];
+    const screens = Math.min(11, Math.max(0, Math.ceil(metrics.page.height / h) - 1));
+    for (let i = 1; i <= screens; i++) {
+      await page.eval(`window.scrollTo({ top: ${i * h}, behavior: 'instant' })`).catch(() => {});
+      await page.wheel(2);
+      await sleep(650);
+      frames.push(await page.screenshot({ quality: 78 }));
+      frameChecks.push(await page.eval(frame).catch(() => null));
+      await page.eval('window.__motionSample && window.__motionSample()').catch(() => {});
+    }
+    const motion = await page.eval('window.__motion ? window.__motion() : null').catch(() => null);
+    // re-measure after everything has revealed (catches content that only exists post-reveal)
+    await page.eval(`window.scrollTo({ top: 0, behavior: 'instant' })`).catch(() => {});
+    await sleep(350);
+    const after = await page.eval(probe).catch(() => metrics);
+    const m = after.headings.length >= metrics.headings.length ? after : metrics;
+
+    const cols = w >= 1100 ? 2 : w >= 600 ? 3 : 4;
+    const cellW = w >= 1100 ? 800 : w >= 600 ? 512 : 390;
+    const cellH = Math.round((cellW * h) / w);
+    const perSheet = w >= 1100 ? 4 : w >= 600 ? 6 : 8;
+    const sheets = [];
+    for (let i = 0; i < frames.length; i += perSheet) {
+      const p = join(outDir, `${label}-page-${String(i / perSheet + 1).padStart(2, '0')}.jpg`);
+      await sheet(frames.slice(i, i + perSheet), cols, cellW, cellH, p);
+      sheets.push(p);
+    }
+    const findings = judge(m, { width: w, allow });
+    // what only shows up while scrolling: text hidden under something, and screens with almost nothing on them
+    const coveredText = [...new Map(frameChecks.filter(Boolean).flatMap((f, i) => f.covered.map((c) => [c.text, { ...c, screen: i + 1 }]))).values()];
+    if (coveredText.length && !allow.includes('covered-text')) findings.push({ level: 'FAIL', id: 'covered-text', width: w, message: `Large text lies under another element at some scroll position: ` + coveredText.slice(0, 4).map((c) => `"${c.text}" (screen ${c.screen}, ${Math.round(c.share * 100)}% hidden)`).join('; '), fix: 'Nothing may sit on top of a headline or statement. Move the picture, shorten the pinned run, or raise the text above it (z-index) and give it a ground.' });
+    const clippedText = [...new Map(frameChecks.filter(Boolean).flatMap((f, i) => (f.clipped || []).map((c) => [c.text, { ...c, screen: i + 1 }]))).values()];
+    if (clippedText.length && !allow.includes('clipped-text')) findings.push({ level: 'FAIL', id: 'clipped-text', width: w, message: 'Large text is cut off along its top by the box that holds it: ' + clippedText.slice(0, 3).map((c) => `"${c.text}" (screen ${c.screen})`).join('; '), fix: 'Jurors read a wordmark sliced at the top as broken. Give the box room for the ascenders (line-height and padding), or crop at the bottom or a side edge on purpose.' });
+    const overPictures = [...new Map(frameChecks.filter(Boolean).flatMap((f, i) => (f.pinnedOver || []).map((c) => [c.text, { ...c, screen: i + 1 }]))).values()];
+    if (overPictures.length && !allow.includes('pinned-over-picture')) findings.push({ level: 'WARN', id: 'pinned-over-picture', width: w, message: 'Pinned large text slides across pictures while the page scrolls: ' + overPictures.slice(0, 3).map((c) => `"${c.text}" (screen ${c.screen}, ${Math.round(c.share * 100)}% over a picture)`).join('; '), fix: 'Jurors read a pinned title crossing drawings or photographs as a collision. Keep the pictures in the column the title does not occupy, or unpin it.' });
+    const empty = frameChecks.map((f, i) => ({ f, i })).filter(({ f }) => f && f.filled < 0.2);
+    // the same large statement on screen for three screens or more in a row
+    const runs = new Map();
+    frameChecks.forEach((f, i) => { for (const t of f?.big || []) { const r = runs.get(t) || { start: i, last: i - 1, best: 0 }; if (r.last === i - 1) r.last = i; else { r.start = i; r.last = i; } r.best = Math.max(r.best, r.last - r.start + 1); runs.set(t, r); } });
+    const longPins = [...runs.entries()].filter(([, r]) => r.best >= 3);
+    if (w >= 1100 && longPins.length && !allow.includes('long-pin')) findings.push({ level: 'WARN', id: 'long-pin', width: w, message: `The same large text stays on screen for ${Math.max(...longPins.map(([, r]) => r.best))} screens in a row: ` + longPins.slice(0, 2).map(([t]) => `"${t}"`).join('; '), fix: 'A pinned element earns two screens, and something must change at each. Shorten the run or give every screen its own content.' });
+    // a page that barely moves: counted from what really animated while it loaded and was scrolled
+    if (w >= 1100 && motion && !allow.includes('still-page')) {
+      const moving = motion.elements + motion.playingVideos * 4;
+      if (moving < MOTION_MIN) findings.push({ level: 'FAIL', id: 'still-page', width: w, message: `Only ${motion.elements} element(s) moved while the page loaded and scrolled${motion.playingVideos ? ` (plus ${motion.playingVideos} playing video)` : ''}.`, fix: 'Build the motion layer (SKILL.md step 9, references/motion.md): the signature move, an entrance for the parts of every section, feedback on every control, and one moving picture. Transform and opacity only, with a reduced-motion fallback.' });
+      else if (moving < MOTION_GOOD) findings.push({ level: 'WARN', id: 'still-page', width: w, message: `Little motion: ${motion.elements} element(s) moved while the page loaded and scrolled.`, fix: 'Give every section an entrance for its parts (not one fade of the whole block) and add one moving picture: a looping clip or a slow move on a photograph.' });
+    }
+    if (w >= 1100 && empty.length >= 2 && !allow.includes('empty-screens')) findings.push({ level: 'FAIL', id: 'empty-screens', width: w, message: `${empty.length} of ${frameChecks.length} desktop screens are almost empty ground (under 20% of the screen holds text, a picture or a colour field): screens ${empty.map(({ i }) => i + 1).join(', ')}.`, fix: 'An empty screen is a rest only once per page. Elsewhere it means the section is underbuilt: set its content larger, give it the full information, put it on a colour field, or cut it.' });
+    report.viewports.push({ width: w, height: h, load: how, screens: frames.length, filled: frameChecks.map((f) => f?.filled ?? null), motion, metrics: m, consoleErrors: page.consoleErrors.slice(0, 5) });
+    report.findings.push(...findings);
+    report.images.push({ viewport: label, width: w, fold, pages: sheets });
+    await page.close();
+  }
+} finally {
+  await browser.close();
+  if (server) server.close();
+}
+
+// de-duplicate findings that repeat across viewports (keep the widest occurrence, note the others)
+const merged = [];
+for (const f of report.findings) {
+  const same = merged.find((x) => x.id === f.id && x.level === f.level);
+  if (same && f.id !== 'headline-lines' && f.id !== 'overflow') { same.alsoAt = [...(same.alsoAt || []), f.width]; continue; }
+  merged.push(f);
+}
+report.findings = merged;
+writeFileSync(join(outDir, 'report.json'), JSON.stringify(report, null, 1));
+
+if (asJson) { console.log(JSON.stringify(report, null, 1)); process.exit(merged.some((f) => f.level === 'FAIL') ? 1 : 0); }
+
+const d = report.viewports[0].metrics;
+const line = (s = '') => console.log(s);
+line(`TASTESKILL · INSPECT   ${report.url}`);
+line('');
+line('MEASURED (first viewport listed)');
+if (d.hero) line(`  hero headline   "${d.hero.text.slice(0, 70)}"  ${d.hero.words} words · ${d.hero.lines} line(s) · ${d.hero.size}px (${d.hero.vw}vw) · ${d.hero.font} ${d.hero.weight} · tracking ${d.hero.tracking}em · leading ${d.hero.leading}`);
+for (const v of report.viewports.slice(1)) if (v.metrics.hero) line(`  @${v.width}px          ${v.metrics.hero.lines} line(s) · ${v.metrics.hero.size}px`);
+line(`  typefaces       ${d.type.families.filter((f) => f.share >= 0.02).map((f) => `${f.family} ${Math.round(f.share * 100)}%`).join(', ')}`);
+line(`  sizes in use    ${d.type.sizes.join(' / ')} px${d.type.body ? `   body ${d.type.body.size}px / ${d.type.body.leading}` : ''}`);
+line(`  colour          page ${d.color.bodyBg}${d.color.sectionBgs.length ? ' · sections ' + d.color.sectionBgs.map((s) => s.color).slice(0, 6).join(' ') : ''}${d.color.button ? ' · button ' + d.color.button.bg : ''}`);
+line(`  page            ${d.page.screens} screens · ${d.page.words} words · ${d.page.img} images · hero media ${d.heroMedia[0] ? Math.round(d.heroMedia[0].ratio * 100) + '% ' + d.heroMedia[0].type : 'none'}`);
+line(`  headings        ${d.headingSummary.count} · longest ${d.headingSummary.maxLines} line(s) · median ${d.headingSummary.medianWords ?? '-'} words`);
+line('');
+const fails = merged.filter((f) => f.level === 'FAIL'), warns = merged.filter((f) => f.level === 'WARN');
+if (!fails.length && !warns.length) line('FINDINGS  none. Measurements are clean — now judge the pictures.');
+for (const [title, list] of [['FAIL — fix every one of these', fails], ['WARN — fix, or be able to defend', warns]]) {
+  if (!list.length) continue;
+  line(title);
+  for (const f of list) {
+    line(`  [${f.id}] @${f.width}px${f.alsoAt ? ' (+' + f.alsoAt.join(', ') + ')' : ''}  ${f.message}`);
+    line(`      → ${f.fix}`);
+  }
+  line('');
+}
+line('LOOK AT THE RENDER — open these with your image viewer / Read tool before saying anything about quality:');
+const rel = (p) => relative(process.cwd(), p).split('\\').join('/');
+for (const im of report.images) { line(`  ${(im.viewport + ' ' + im.width + 'px').padEnd(15)} ${rel(im.fold)}`); for (const p of im.pages) line(`  ${''.padEnd(15)} ${rel(p)}`); }
+line('');
+line(`report: ${rel(join(outDir, 'report.json'))}`);
+line(fails.length ? `RESULT: ${fails.length} FAIL, ${warns.length} WARN — not done.` : `RESULT: 0 FAIL, ${warns.length} WARN — measurements pass. Passing the meter is the floor, not the grade: score the screenshots with references/critique.md.`);
+process.exit(fails.length ? 1 : 0);

package/skills/codeply-taste/scripts/lib/cdp.mjs

@@ -0,0 +1,205 @@
+// Zero-dependency Chrome DevTools Protocol client.
+// Drives an installed Chrome / Edge / Chromium in headless mode over Node's built-in WebSocket.
+// Requires Node 22+. No npm install.
+import { spawn } from 'node:child_process';
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+export function findChrome() {
+  const env = process.env.CHROME_PATH || process.env.PUPPETEER_EXECUTABLE_PATH;
+  if (env && existsSync(env)) return env;
+  const home = process.env.HOME || process.env.USERPROFILE || '';
+  const local = process.env.LOCALAPPDATA || '';
+  const pf = process.env.PROGRAMFILES || 'C:\\Program Files';
+  const pf86 = process.env['PROGRAMFILES(X86)'] || 'C:\\Program Files (x86)';
+  const candidates = [
+    // Windows
+    join(pf, 'Google/Chrome/Application/chrome.exe'),
+    join(pf86, 'Google/Chrome/Application/chrome.exe'),
+    join(local, 'Google/Chrome/Application/chrome.exe'),
+    join(pf86, 'Microsoft/Edge/Application/msedge.exe'),
+    join(pf, 'Microsoft/Edge/Application/msedge.exe'),
+    join(pf, 'BraveSoftware/Brave-Browser/Application/brave.exe'),
+    // macOS
+    '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+    '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
+    join(home, 'Applications/Google Chrome.app/Contents/MacOS/Google Chrome'),
+    // Linux
+    '/usr/bin/google-chrome', '/usr/bin/google-chrome-stable', '/usr/bin/chromium',
+    '/usr/bin/chromium-browser', '/snap/bin/chromium', '/usr/bin/microsoft-edge',
+  ];
+  for (const c of candidates) if (c && existsSync(c)) return c;
+  return null;
+}
+
+export class Browser {
+  static async launch({ width = 1440, height = 900, extraArgs = [] } = {}) {
+    if (typeof WebSocket === 'undefined') {
+      throw new Error('Node 22+ is required (built-in WebSocket missing). Current: ' + process.version);
+    }
+    const exe = findChrome();
+    if (!exe) {
+      throw new Error('No Chrome/Edge/Chromium found. Install one or set CHROME_PATH to its executable.');
+    }
+    const dir = mkdtempSync(join(tmpdir(), 'ad-chrome-'));
+    const args = [
+      '--headless=new', '--remote-debugging-port=0', `--user-data-dir=${dir}`,
+      '--no-first-run', '--no-default-browser-check', '--mute-audio', '--hide-scrollbars',
+      '--disable-background-timer-throttling', '--disable-renderer-backgrounding',
+      '--disable-backgrounding-occluded-windows', '--disable-features=Translate,MediaRouter',
+      '--force-color-profile=srgb', '--autoplay-policy=no-user-gesture-required',
+      '--enable-unsafe-swiftshader', `--window-size=${width},${height}`, ...extraArgs, 'about:blank',
+    ];
+    const proc = spawn(exe, args, { stdio: ['ignore', 'ignore', 'pipe'] });
+    const wsUrl = await new Promise((resolve, reject) => {
+      let buf = '';
+      const t = setTimeout(() => reject(new Error('Chrome did not start within 20s')), 20000);
+      proc.stderr.on('data', (d) => {
+        buf += d.toString();
+        const m = buf.match(/DevTools listening on (ws:\/\/[^\s]+)/);
+        if (m) { clearTimeout(t); resolve(m[1]); }
+      });
+      proc.on('exit', (code) => { clearTimeout(t); reject(new Error('Chrome exited early, code ' + code + '\n' + buf.slice(-600))); });
+    });
+    const b = new Browser();
+    b.proc = proc; b.dir = dir; b.nextId = 1; b.pending = new Map(); b.listeners = new Map();
+    b.ws = new WebSocket(wsUrl);
+    await new Promise((res, rej) => { b.ws.onopen = res; b.ws.onerror = () => rej(new Error('CDP socket failed')); });
+    b.ws.onmessage = (ev) => {
+      const msg = JSON.parse(typeof ev.data === 'string' ? ev.data : Buffer.from(ev.data).toString());
+      if (msg.id && b.pending.has(msg.id)) {
+        const { resolve, reject, timer } = b.pending.get(msg.id);
+        clearTimeout(timer); b.pending.delete(msg.id);
+        if (msg.error) reject(new Error(msg.error.message)); else resolve(msg.result);
+      } else if (msg.method) {
+        const fns = b.listeners.get((msg.sessionId || '') + '|' + msg.method);
+        if (fns) for (const fn of [...fns]) fn(msg.params);
+      }
+    };
+    return b;
+  }
+
+  send(method, params = {}, sessionId, timeoutMs = 30000) {
+    const id = this.nextId++;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => { this.pending.delete(id); reject(new Error('CDP timeout: ' + method)); }, timeoutMs);
+      this.pending.set(id, { resolve, reject, timer });
+      this.ws.send(JSON.stringify(sessionId ? { id, method, params, sessionId } : { id, method, params }));
+    });
+  }
+
+  on(sessionId, method, fn) {
+    const k = (sessionId || '') + '|' + method;
+    if (!this.listeners.has(k)) this.listeners.set(k, new Set());
+    this.listeners.get(k).add(fn);
+    return () => this.listeners.get(k)?.delete(fn);
+  }
+
+  async newPage({ width = 1440, height = 900, dsf = 1, mobile = false, reducedMotion = false } = {}) {
+    const { targetId } = await this.send('Target.createTarget', { url: 'about:blank', newWindow: true });
+    const { sessionId } = await this.send('Target.attachToTarget', { targetId, flatten: true });
+    const p = new Page(this, targetId, sessionId);
+    await p.send('Page.enable');
+    await p.send('Runtime.enable');
+    await p.setViewport({ width, height, dsf, mobile });
+    if (reducedMotion) {
+      await p.send('Emulation.setEmulatedMedia', { features: [{ name: 'prefers-reduced-motion', value: 'reduce' }] });
+    }
+    return p;
+  }
+
+  async close() {
+    try { await this.send('Browser.close', {}, undefined, 3000); } catch {}
+    try { this.ws.close(); } catch {}
+    try { this.proc.kill(); } catch {}
+    await sleep(300);
+    try { rmSync(this.dir, { recursive: true, force: true, maxRetries: 3 }); } catch {}
+  }
+}
+
+export class Page {
+  constructor(browser, targetId, sessionId) {
+    this.browser = browser; this.targetId = targetId; this.sessionId = sessionId;
+    this.consoleErrors = [];
+    browser.on(sessionId, 'Runtime.exceptionThrown', (p) => {
+      this.consoleErrors.push((p.exceptionDetails?.exception?.description || p.exceptionDetails?.text || '').slice(0, 300));
+    });
+    // Never let a JS dialog block the page.
+    browser.on(sessionId, 'Page.javascriptDialogOpening', () => {
+      this.send('Page.handleJavaScriptDialog', { accept: false }).catch(() => {});
+    });
+  }
+
+  send(method, params = {}, timeoutMs = 30000) {
+    return this.browser.send(method, params, this.sessionId, timeoutMs);
+  }
+
+  async setViewport({ width, height, dsf = 1, mobile = false }) {
+    this.viewport = { width, height, dsf, mobile };
+    await this.send('Emulation.setDeviceMetricsOverride', { width, height, deviceScaleFactor: dsf, mobile });
+    await this.send('Emulation.setTouchEmulationEnabled', { enabled: !!mobile });
+  }
+
+  // Navigates and resolves after the load event (or timeout), then waits `settleMs` for intros to finish.
+  async goto(url, { timeoutMs = 25000, settleMs = 1500 } = {}) {
+    let off;
+    const loaded = new Promise((resolve) => { off = this.browser.on(this.sessionId, 'Page.loadEventFired', () => resolve('load')); });
+    const nav = await this.send('Page.navigate', { url }, timeoutMs).catch((e) => ({ errorText: e.message }));
+    if (nav.errorText && !/ERR_ABORTED/.test(nav.errorText)) { off(); throw new Error('navigate: ' + nav.errorText); }
+    const how = await Promise.race([loaded, sleep(timeoutMs).then(() => 'timeout')]);
+    off();
+    await sleep(settleMs);
+    return how;
+  }
+
+  // Evaluates a function (serialised) or an expression string in the page and returns its JSON value.
+  async eval(fnOrExpr, arg) {
+    const expression = typeof fnOrExpr === 'function'
+      ? `(${fnOrExpr.toString()})(${arg === undefined ? '' : JSON.stringify(arg)})`
+      : fnOrExpr;
+    const r = await this.send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true }, 30000);
+    if (r.exceptionDetails) {
+      throw new Error('page eval: ' + (r.exceptionDetails.exception?.description || r.exceptionDetails.text));
+    }
+    return r.result?.value;
+  }
+
+  async screenshot({ path, format = 'jpeg', quality = 72, fullPage = false, clip } = {}) {
+    const params = { format, captureBeyondViewport: !!fullPage };
+    if (format !== 'png') params.quality = quality;
+    if (fullPage) {
+      const m = await this.send('Page.getLayoutMetrics');
+      const s = m.cssContentSize || m.contentSize;
+      params.clip = { x: 0, y: 0, width: Math.ceil(s.width), height: Math.min(Math.ceil(s.height), 16000), scale: 1 };
+    } else if (clip) {
+      params.clip = { scale: 1, ...clip };
+    }
+    const { data } = await this.send('Page.captureScreenshot', params, 45000);
+    if (path) writeFileSync(path, Buffer.from(data, 'base64'));
+    return data;
+  }
+
+  // Real wheel input, so smooth-scroll libraries and scroll-driven reveals behave as they do for a visitor.
+  async wheel(totalDeltaY, { step = 240, pauseMs = 45 } = {}) {
+    const { width, height } = this.viewport;
+    const dir = Math.sign(totalDeltaY) || 1;
+    let left = Math.abs(totalDeltaY);
+    while (left > 0) {
+      const d = Math.min(step, left);
+      await this.send('Input.dispatchMouseEvent', { type: 'mouseWheel', x: Math.round(width / 2), y: Math.round(height / 2), deltaX: 0, deltaY: d * dir }).catch(() => {});
+      left -= d;
+      await sleep(pauseMs);
+    }
+  }
+
+  async close() {
+    try { await this.browser.send('Target.closeTarget', { targetId: this.targetId }, undefined, 5000); } catch {}
+  }
+}
+
+export { sleep };