starchy 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Danny Clark
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,122 @@
-# Temporary Holding Version
+# starchy
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Keep your layout crisp at every width.**
+
+starchy finds every screen width where your page's layout actually changes, and
+flags the changes that are bugs.
+
+```bash
+npx starchy https://example.com
+```
+
+Most responsive testing screenshots a handful of fixed breakpoints, such as 375,
+768 and 1440, so a bug that only appears at 912px goes unnoticed. starchy sweeps
+the whole range and lets the page show it where the layout shifts:
+
+1. Load the page at a max width (default 1920px) and fingerprint the layout:
+   for every container, how its children sit in rows (for example `3+3+1`),
+   which elements are visible, and any problems.
+2. Step down 8px at a time. When the fingerprint changes, binary-search to the
+   exact pixel.
+3. Take before/after screenshots with the changed elements outlined, and
+   classify the change:
+   - **Media query**: the width matches a `@media` breakpoint in your CSS, so
+     the change is expected.
+   - **Fluid change**: the layout changed with no media query. It came from
+     flex-wrap, auto-fit, or content size, so check that it's intended.
+   - **Problem**: something broke at this width.
+4. Continue down to the min width (default 320px), once for each viewport
+   height you list.
+5. Write `report.html` and a `fingerprint.json` you can compare against later.
+
+## What counts as a problem
+
+| Problem | What it means |
+|---|---|
+| Horizontal scroll | The page is wider than the screen. starchy names the element *causing* it by briefly hiding each candidate and checking whether the scroll width shrinks. |
+| Overlap | In-flow sibling elements overlap each other. |
+| Escapes container | An element sticks out of its parent's box. |
+| Clipped text | Text is cut off by `overflow: hidden`. |
+| Tiny text | Text is below `--min-font` (default 12px). |
+
+## Install
+
+```bash
+npm install -g starchy
+npx playwright install chromium
+```
+
+## Usage
+
+```bash
+starchy https://example.com
+starchy example.com                      # https:// is assumed
+starchy ./index.html --min 360 --heights 900,600
+```
+
+| Option | Default | |
+|---|---|---|
+| `--max` / `--min` | 1920 / 320 | Width range to sweep |
+| `--step` | 8 | Coarse step before bisecting. Lower is slower but more thorough. |
+| `--heights` | 900 | Comma-separated viewport heights, each swept separately |
+| `--dpr` | 1 | Device pixel ratio (affects images/hairlines, not layout) |
+| `--min-font` | 12 | Smallest acceptable text size in px |
+| `--ignore` | | Selectors to skip, e.g. `.carousel,.ad-slot` |
+| `--settle` | 0 | Extra ms to wait after each resize, for JS-driven layouts |
+| `--out` | `starchy-report` | Output folder |
+| `--baseline` | | An earlier `fingerprint.json` to compare against |
+| `--fail-on` | none | `problems` or `new` makes starchy exit 1, for CI |
+| `--no-screenshots` | | Faster runs, report without images |
+
+## In CI
+
+```bash
+# once, on a known-good build:
+starchy https://staging.example.com --out baseline
+
+# on every pull request:
+starchy https://staging.example.com --baseline baseline/fingerprint.json --fail-on new
+```
+
+The comparison is structural, not pixel-based, so it doesn't suffer the
+font-rendering noise that makes screenshot diffs flaky. The report lists new
+problems, fixed problems, and layout changes that appeared or disappeared.
+
+## Try it
+
+`test/fixture.html` is a sample landing page with six planted bugs, listed in
+the comments at the top of the file:
+
+```bash
+npm test
+open test-report/report.html
+```
+
+## Known limitations
+
+- **Change-and-revert inside one step is missed.** If the layout changes and
+  then changes back within 8px, the sweep won't see it. Use `--step 1` for an
+  exhaustive pass.
+- **Container queries show up as "fluid".** Only `@media` widths are matched
+  to breakpoints.
+- **Worst offender first.** When two elements both cause horizontal scroll,
+  the widest one is named. The other surfaces once the first is fixed.
+- **Some content isn't inspected.** Shadow DOM and iframes are skipped.
+  Auto-rotating carousels and other animated elements need `--ignore`.
+- **Inline text reflow is ignored on purpose.** It changes at almost every
+  pixel. Text is checked through the clipped-text and tiny-text rules instead.
+- **Chromium only for now.**
+
+## Project layout
+
+```
+cli.js              CLI, sweep loop, bisection, screenshots
+src/fingerprint.js  runs in the page: layout units, row signatures, problem checks
+src/analyze.js      fingerprint hashing, media-query parsing, diff + classification
+src/baseline.js     compare against an earlier fingerprint.json
+src/report.js       HTML report
+```
+
+## License
+
+MIT

package/cli.js

@@ -0,0 +1,259 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * starchy — keep your layout crisp at every width.
+ *
+ * Finds every width where a page's layout actually changes, and flags the bugs.
+ *
+ * 1. Load the page at a max width and fingerprint its layout structure.
+ * 2. Step down; when the fingerprint changes, bisect to the exact pixel.
+ * 3. Snapshot before/after, describe what changed, and classify it:
+ *      breakpoint — matches a media query in your CSS (expected)
+ *      fluid      — layout changed with no media query (wrap, auto-fit…) → review
+ *      problem    — a new overflow / overlap / clipped text / tiny text appeared
+ * 4. Repeat down to a min width, for each viewport height requested.
+ * 5. Write an HTML report + a JSON fingerprint you can diff against later.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { chromium } = require('playwright');
+const { fingerprint, mediaConditions } = require('./src/fingerprint');
+const { keyOf, parseBreakpoints, diffStates, issueRanges } = require('./src/analyze');
+const { renderReport } = require('./src/report');
+const { compareBaseline } = require('./src/baseline');
+
+const HELP = `
+Usage: starchy <url-or-file> [options]
+
+  e.g. starchy https://example.com
+       starchy ./index.html --min 360 --heights 900,600
+
+  --max <px>          widest width to test             (default 1920)
+  --min <px>          narrowest width to test          (default 320)
+  --step <px>         coarse step before bisecting      (default 8)
+  --heights <list>    viewport heights, comma-separated (default 900)
+  --dpr <n>           device pixel ratio                (default 1)
+  --min-font <px>     smallest acceptable text size     (default 12)
+  --ignore <sels>     comma-separated selectors to skip (carousels, ads…)
+  --settle <ms>       extra wait after each resize      (default 0)
+  --out <dir>         output folder                     (default ./starchy-report)
+  --baseline <file>   compare against an earlier fingerprint.json
+  --fail-on <mode>    exit 1 on: none | problems | new  (default none)
+  --no-screenshots    skip before/after images (faster)
+`;
+
+function parseArgs(argv) {
+  const o = {
+    max: 1920, min: 320, step: 8, heights: [900], dpr: 1, minFont: 12, ignore: [],
+    settle: 0, out: 'starchy-report', baseline: null, failOn: 'none', screenshots: true, url: null,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i], next = () => argv[++i];
+    switch (a) {
+      case '-h': case '--help': console.log(HELP); process.exit(0); break;
+      case '-v': case '--version': console.log(require('./package.json').version); process.exit(0); break;
+      case '--max': o.max = parseInt(next(), 10); break;
+      case '--min': o.min = parseInt(next(), 10); break;
+      case '--step': o.step = Math.max(1, parseInt(next(), 10)); break;
+      case '--heights': o.heights = next().split(',').map((h) => parseInt(h, 10)).filter(Boolean); break;
+      case '--dpr': o.dpr = parseFloat(next()); break;
+      case '--min-font': o.minFont = parseFloat(next()); break;
+      case '--ignore': o.ignore = next().split(',').map((s) => s.trim()).filter(Boolean); break;
+      case '--settle': o.settle = parseInt(next(), 10); break;
+      case '--out': o.out = next(); break;
+      case '--baseline': o.baseline = next(); break;
+      case '--fail-on': o.failOn = next(); break;
+      case '--no-screenshots': o.screenshots = false; break;
+      default:
+        if (a.startsWith('--')) { console.error('Unknown option ' + a); process.exit(2); }
+        o.url = a;
+    }
+  }
+  if (!o.url) { console.log(HELP); process.exit(2); }
+  o.url = o.url.replace(/^<|>$/g, ''); // tolerate copied placeholder brackets
+  if (!/^[a-z]+:\/\//i.test(o.url)) {
+    if (fs.existsSync(o.url)) o.url = 'file://' + path.resolve(o.url);
+    else if (/^(localhost|[\w-]+(\.[\w-]+)+)(:\d+)?(\/|$)/i.test(o.url)) {
+      o.url = (/^localhost|^127\./i.test(o.url) ? 'http://' : 'https://') + o.url;
+    } else { console.error(`Not a URL or an existing file: ${o.url}`); process.exit(2); }
+  }
+  if (o.min >= o.max) { console.error('--min must be below --max'); process.exit(2); }
+  return o;
+}
+
+async function settle(page, ms) {
+  // two animation frames = style + layout have run after the resize
+  await page.evaluate(() => new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r))));
+  if (ms) await page.waitForTimeout(ms);
+}
+
+async function collectBreakpoints(page, context) {
+  const { out, blocked } = await page.evaluate(mediaConditions);
+  const texts = out.slice();
+  for (const href of blocked) {
+    try {
+      const res = await context.request.get(href);
+      const css = await res.text();
+      const re = /@media([^{]+)\{/g;
+      let m;
+      while ((m = re.exec(css))) texts.push(m[1]);
+    } catch (e) { /* unreachable stylesheet: its breakpoints show as "fluid" */ }
+  }
+  return parseBreakpoints(texts);
+}
+
+async function shoot(page, width, height, paths, o) {
+  await page.setViewportSize({ width, height });
+  await settle(page, o.settle);
+  const info = await page.evaluate((paths) => {
+    let u = null;
+    for (const p of paths) {
+      let el = null;
+      try { el = document.querySelector(p); } catch (e) { /* skip */ }
+      if (!el) continue;
+      el.setAttribute('data-ls-hl', '');
+      const r = el.getBoundingClientRect();
+      const x = r.left + scrollX, y = r.top + scrollY;
+      u = u ? { x1: Math.min(u.x1, x), y1: Math.min(u.y1, y), x2: Math.max(u.x2, x + r.width), y2: Math.max(u.y2, y + r.height) }
+        : { x1: x, y1: y, x2: x + r.width, y2: y + r.height };
+    }
+    if (!document.getElementById('ls-hl-style')) {
+      const s = document.createElement('style');
+      s.id = 'ls-hl-style';
+      s.textContent = '[data-ls-hl]{outline:3px solid #e5484d!important;outline-offset:-3px!important}';
+      document.head.appendChild(s);
+    }
+    return { u, docH: document.documentElement.scrollHeight, docW: document.documentElement.scrollWidth };
+  }, paths.slice(0, 25));
+
+  const MAXH = 1000, PAD = 40;
+  const clipW = Math.min(info.docW, width + 480); // show what spills off-screen
+  let y = 0, h = Math.min(info.docH, 700);
+  if (info.u) {
+    y = Math.max(0, Math.floor(info.u.y1 - PAD));
+    h = Math.min(MAXH, Math.ceil(info.u.y2 - info.u.y1 + PAD * 2), info.docH - y);
+  }
+  const buf = await page.screenshot({
+    fullPage: true, type: 'jpeg', quality: 62,
+    clip: { x: 0, y, width: clipW, height: Math.max(40, h) },
+  });
+  await page.evaluate(() => document.querySelectorAll('[data-ls-hl]').forEach((e) => e.removeAttribute('data-ls-hl')));
+  return { data: buf.toString('base64'), viewport: width, clipW };
+}
+
+async function sweepHeight(page, height, breakpoints, o) {
+  const cache = new Map();
+  let evals = 0;
+  const at = async (w) => {
+    if (cache.has(w)) return cache.get(w);
+    await page.setViewportSize({ width: w, height });
+    await settle(page, o.settle);
+    const fp = await page.evaluate(fingerprint, { ignore: o.ignore, minFont: o.minFont });
+    fp.width = w;
+    fp.key = keyOf(fp);
+    cache.set(w, fp);
+    evals++;
+    return fp;
+  };
+
+  const first = await at(o.max);
+  const transitions = [];
+  let cur = first;
+  while (cur.width > o.min) {
+    const nextW = Math.max(o.min, cur.width - o.step);
+    const next = await at(nextW);
+    if (next.key === cur.key) { cur = next; continue; }
+    // bisect to the exact pixel where the layout stops matching `cur`
+    let hi = cur.width, lo = nextW;
+    while (hi - lo > 1) {
+      const mid = (hi + lo) >> 1;
+      if ((await at(mid)).key === cur.key) hi = mid; else lo = mid;
+    }
+    const before = await at(hi), after = await at(lo);
+    const diff = diffStates(before, after, breakpoints, hi);
+    transitions.push({ hi, lo, diff, issuesBefore: before.issues });
+    process.stdout.write(`  ${String(hi).padStart(5)}px  ${diff.category}\n`);
+    cur = after;
+  }
+
+  if (o.screenshots) {
+    for (const t of transitions) {
+      const d = t.diff;
+      const paths = [...new Set([
+        ...d.newIssues.flatMap((x) => x.paths), ...d.resolved.flatMap((x) => x.paths),
+        ...d.regrouped.map((x) => x.path), ...d.hidden.map((x) => x.path), ...d.shown.map((x) => x.path),
+      ])];
+      t.before = await shoot(page, t.hi, height, paths, o);
+      t.after = await shoot(page, t.lo, height, paths, o);
+    }
+  }
+
+  return { height, first: { width: first.width, issues: first.issues }, transitions, ranges: issueRanges(first, transitions, o.min, cur), evals };
+}
+
+async function main() {
+  const o = parseArgs(process.argv.slice(2));
+  const started = Date.now();
+  const browser = await chromium.launch();
+  const context = await browser.newContext({ deviceScaleFactor: o.dpr });
+  const page = await context.newPage();
+
+  console.log(`starchy ${o.url}\n  widths ${o.max}→${o.min}px, heights ${o.heights.join(', ')}px`);
+  await page.setViewportSize({ width: o.max, height: o.heights[0] });
+  await page.goto(o.url, { waitUntil: 'networkidle' });
+  await page.evaluate(() => document.fonts && document.fonts.ready);
+  // freeze animations/transitions so they can't masquerade as layout changes
+  await page.addStyleTag({ content: '*,*::before,*::after{transition:none!important;animation:none!important;caret-color:transparent!important}' });
+
+  const breakpoints = await collectBreakpoints(page, context);
+  console.log(`  media-query breakpoints found: ${breakpoints.map((b) => b.hi).join(', ') || 'none'}`);
+
+  const runs = [];
+  for (const h of o.heights) {
+    console.log(`\n  height ${h}px`);
+    runs.push(await sweepHeight(page, h, breakpoints, o));
+  }
+  await browser.close();
+
+  const result = {
+    url: o.url, generated: new Date().toISOString(), seconds: Math.round((Date.now() - started) / 100) / 10,
+    options: { max: o.max, min: o.min, step: o.step, heights: o.heights, dpr: o.dpr, minFont: o.minFont, ignore: o.ignore },
+    breakpoints, runs,
+  };
+
+  let comparison = null;
+  if (o.baseline) comparison = compareBaseline(result, JSON.parse(fs.readFileSync(o.baseline, 'utf8')));
+
+  fs.mkdirSync(o.out, { recursive: true });
+  const fingerprintJson = toFingerprint(result);
+  fs.writeFileSync(path.join(o.out, 'fingerprint.json'), JSON.stringify(fingerprintJson, null, 2));
+  fs.writeFileSync(path.join(o.out, 'report.html'), renderReport(result, comparison));
+
+  const all = runs.flatMap((r) => r.transitions);
+  const problems = runs.reduce((n, r) => n + r.ranges.length, 0);
+  console.log(`\n  ${all.length} layout changes · ${problems} problem${problems === 1 ? '' : 's'} · ${result.seconds}s`);
+  console.log(`  report → ${path.join(o.out, 'report.html')}`);
+
+  if (o.failOn === 'problems' && problems > 0) process.exit(1);
+  if (o.failOn === 'new' && comparison && (comparison.newProblems.length || comparison.newChanges.length)) process.exit(1);
+}
+
+/** Compact, screenshot-free record for baselines and CI diffs. */
+function toFingerprint(result) {
+  return {
+    url: result.url, generated: result.generated, options: result.options,
+    runs: result.runs.map((r) => ({
+      height: r.height,
+      changes: r.transitions.map((t) => ({
+        at: t.hi, category: t.diff.category,
+        regrouped: t.diff.regrouped.map((x) => ({ path: x.path, from: x.from, to: x.to })),
+        hidden: t.diff.hidden.map((x) => x.path), shown: t.diff.shown.map((x) => x.path),
+      })),
+      problems: r.ranges.map((x) => ({ key: x.issue.key, kind: x.issue.kind, labels: x.issue.labels, detail: x.issue.detail, from: x.from, to: x.to })),
+    })),
+  };
+}
+
+main().catch((e) => { console.error(e); process.exit(1); });

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "starchy",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Keep your layout crisp at every width. Finds every screen width where a page's layout changes, and flags the ones that are bugs.",
+  "homepage": "https://starchy.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dannyclarkdev/starchy.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dannyclarkdev/starchy/issues"
+  },
+  "bin": {
+    "starchy": "cli.js"
+  },
+  "main": "cli.js",
+  "files": [
+    "cli.js",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node cli.js test/fixture.html --out test-report"
+  },
+  "keywords": [
+    "responsive",
+    "layout",
+    "css",
+    "testing",
+    "visual-regression",
+    "breakpoints",
+    "playwright",
+    "overflow",
+    "accessibility",
+    "ci"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "playwright": "^1.50.0"
+  },
+  "license": "MIT"
+}

package/src/analyze.js

@@ -0,0 +1,119 @@
+'use strict';
+
+const crypto = require('crypto');
+
+/** Hash of everything that counts as "the layout changed". */
+function keyOf(fp) {
+  const g = Object.keys(fp.groups).sort().map((k) => k + '=' + fp.groups[k]).join(';');
+  const v = fp.visible.slice().sort().join(';');
+  const i = fp.issues.map((x) => x.key).sort().join(';');
+  return crypto.createHash('sha1').update(g + '\n' + v + '\n' + i).digest('hex');
+}
+
+/**
+ * Turn media-query condition texts into the exact sweep boundary each one
+ * should cause. A boundary is reported as `hi`: the layout differs between
+ * width `hi` and `hi - 1`.
+ */
+function parseBreakpoints(texts) {
+  const toPx = (n, unit) => (unit === 'px' ? n : n * 16);
+  const found = new Map();
+  const push = (hi, text) => { if (hi > 0 && !found.has(hi)) found.set(hi, text.trim()); };
+  for (const t of texts) {
+    let m;
+    const re1 = /(min|max)-width\s*:\s*([\d.]+)\s*(px|em|rem)/gi;
+    while ((m = re1.exec(t))) {
+      const px = toPx(parseFloat(m[2]), m[3].toLowerCase());
+      push(m[1].toLowerCase() === 'min' ? Math.ceil(px) : Math.floor(px) + 1, t);
+    }
+    const re2 = /\bwidth\s*(>=|<=|>|<)\s*([\d.]+)\s*(px|em|rem)/gi;
+    while ((m = re2.exec(t))) {
+      const px = toPx(parseFloat(m[2]), m[3].toLowerCase());
+      push(m[1] === '>=' || m[1] === '<' ? Math.ceil(px) : Math.floor(px) + 1, t);
+    }
+    const re3 = /([\d.]+)\s*(px|em|rem)\s*(>=|<=|>|<)\s*width\b/gi;
+    while ((m = re3.exec(t))) {
+      const px = toPx(parseFloat(m[1]), m[2].toLowerCase());
+      // "X < width" == "width > X", "X <= width" == "width >= X"
+      push(m[3] === '<=' || m[3] === '>' ? Math.ceil(px) : Math.floor(px) + 1, t);
+    }
+  }
+  return Array.from(found, ([hi, text]) => ({ hi, text })).sort((a, b) => b.hi - a.hi);
+}
+
+/** Paths in `list` that don't have an ancestor also in `list`. */
+function roots(list) {
+  const set = new Set(list);
+  return list.filter((p) => {
+    let i = p.lastIndexOf(' > ');
+    while (i > 0) {
+      const anc = p.slice(0, i);
+      if (set.has(anc)) return false;
+      i = anc.lastIndexOf(' > ');
+    }
+    return true;
+  });
+}
+
+/** What changed between the state just above a boundary and just below it. */
+function diffStates(a, b, breakpoints, hi) {
+  const va = new Set(a.visible), vb = new Set(b.visible);
+
+  const regrouped = [];
+  for (const p of new Set([...Object.keys(a.groups), ...Object.keys(b.groups)])) {
+    if (!(va.has(p) || p === 'body') || !(vb.has(p) || p === 'body')) continue;
+    const from = a.groups[p] || '1', to = b.groups[p] || '1';
+    if (from !== to) regrouped.push({ path: p, label: a.labels[p] || b.labels[p] || p, from, to });
+  }
+  const hidden = roots(a.visible.filter((p) => !vb.has(p))).map((p) => ({ path: p, label: a.labels[p] }));
+  const shown = roots(b.visible.filter((p) => !va.has(p))).map((p) => ({ path: p, label: b.labels[p] }));
+
+  const ia = new Map(a.issues.map((x) => [x.key, x])), ib = new Map(b.issues.map((x) => [x.key, x]));
+  const newIssues = b.issues.filter((x) => !ia.has(x.key));
+  const resolved = a.issues.filter((x) => !ib.has(x.key));
+
+  const matched = breakpoints.filter((bp) => Math.abs(bp.hi - hi) <= 1);
+  const layoutChanged = regrouped.length || hidden.length || shown.length;
+
+  let category;
+  if (newIssues.length) category = 'problem';
+  else if (layoutChanged && matched.length) category = 'breakpoint';
+  else if (layoutChanged) category = 'fluid';
+  else category = 'fixed';
+
+  return { category, matched, regrouped, hidden, shown, newIssues, resolved };
+}
+
+/** Width ranges over which each issue is present. */
+function issueRanges(first, transitions, min, last) {
+  const open = new Map();
+  const done = [];
+  for (const x of first.issues) open.set(x.key, { issue: x, from: first.width });
+  for (const t of transitions) {
+    for (const x of t.diff.resolved) {
+      const o = open.get(x.key);
+      if (o) {
+        const atEnd = (t.issuesBefore || []).find((y) => y.key === x.key);
+        done.push({ ...o, issue: atEnd || o.issue, to: t.hi });
+        open.delete(x.key);
+      }
+    }
+    for (const x of t.diff.newIssues) if (!open.has(x.key)) open.set(x.key, { issue: x, from: t.lo });
+  }
+  for (const o of open.values()) {
+    const atEnd = last && last.issues.find((y) => y.key === o.issue.key);
+    done.push({ ...o, issue: atEnd || o.issue, to: min });
+  }
+  const rank = { 'page-overflow': 0, overlap: 1, 'container-overflow': 2, 'text-clipped': 3, 'tiny-text': 4 };
+  return done.sort((a, b) => rank[a.issue.kind] - rank[b.issue.kind] || b.from - a.from);
+}
+
+const describeSig = (s) => {
+  const parts = s.split('+').map(Number);
+  const rows = parts.length, max = Math.max(...parts);
+  if (rows === 1) return `${max} side by side`;
+  if (max === 1) return `${rows} stacked`;
+  return `${rows} rows, up to ${max} across`;
+};
+
+module.exports = { keyOf, parseBreakpoints, diffStates, issueRanges, describeSig, roots };

package/src/baseline.js

@@ -0,0 +1,32 @@
+'use strict';
+
+/**
+ * Compare a fresh sweep against an earlier fingerprint.json.
+ * A change "matches" the baseline if one exists within ±4px touching the same
+ * containers; a problem matches if the same issue key exists at any width.
+ */
+function compareBaseline(result, base) {
+  const newChanges = [], goneChanges = [], newProblems = [], fixedProblems = [];
+  const sig = (c) => [...c.regrouped.map((x) => x.path), ...c.hidden, ...c.shown].sort().join('|');
+
+  for (const run of result.runs) {
+    const b = (base.runs || []).find((r) => r.height === run.height);
+    if (!b) continue;
+    const cur = run.transitions.map((t) => ({
+      at: t.hi, category: t.diff.category,
+      sig: sig({ regrouped: t.diff.regrouped, hidden: t.diff.hidden.map((x) => x.path), shown: t.diff.shown.map((x) => x.path) }),
+    }));
+    const old = b.changes.map((c) => ({ at: c.at, category: c.category, sig: sig(c) }));
+    const match = (x, list) => list.some((y) => Math.abs(y.at - x.at) <= 4 && y.sig === x.sig);
+    for (const x of cur) if (x.sig && !match(x, old)) newChanges.push({ height: run.height, ...x });
+    for (const x of old) if (x.sig && !match(x, cur)) goneChanges.push({ height: run.height, ...x });
+
+    const oldKeys = new Set(b.problems.map((p) => p.key));
+    const curKeys = new Set(run.ranges.map((r) => r.issue.key));
+    for (const r of run.ranges) if (!oldKeys.has(r.issue.key)) newProblems.push({ height: run.height, kind: r.issue.kind, labels: r.issue.labels, from: r.from, to: r.to });
+    for (const p of b.problems) if (!curKeys.has(p.key)) fixedProblems.push({ height: run.height, ...p });
+  }
+  return { baselineDate: base.generated, newChanges, goneChanges, newProblems, fixedProblems };
+}
+
+module.exports = { compareBaseline };

package/src/fingerprint.js

@@ -0,0 +1,244 @@
+'use strict';
+
+/**
+ * Runs INSIDE the page (via page.evaluate). Must be self-contained.
+ *
+ * Returns a structural fingerprint of the current layout:
+ *  - groups:  for every container with 2+ in-flow children, its row signature,
+ *             e.g. "3+3+1" = three rows holding 3, 3 and 1 items.
+ *  - visible: paths of every rendered layout unit (block-level boxes + replaced
+ *             elements like img/svg/button). Inline text runs are deliberately
+ *             ignored, because text reflows at nearly every pixel.
+ *  - issues:  things that are almost always bugs (page overflow, overlap,
+ *             content escaping its container, clipped text, tiny text).
+ */
+function fingerprint(opts) {
+  const SKIP = new Set(['SCRIPT', 'STYLE', 'LINK', 'META', 'HEAD', 'TITLE', 'NOSCRIPT',
+    'TEMPLATE', 'BR', 'WBR', 'SOURCE', 'TRACK']);
+  const REPLACED = new Set(['IMG', 'SVG', 'VIDEO', 'CANVAS', 'IFRAME', 'INPUT', 'BUTTON',
+    'SELECT', 'TEXTAREA', 'OBJECT', 'EMBED', 'METER', 'PROGRESS']);
+
+  let ignored = [];
+  if (opts.ignore && opts.ignore.length) {
+    try { ignored = Array.from(document.querySelectorAll(opts.ignore.join(','))); } catch (e) { /* bad selector */ }
+  }
+  const vw = document.documentElement.clientWidth;
+
+  // ---- stable element paths (usable as CSS selectors) ----
+  const pathCache = new Map();
+  const getPath = (el) => {
+    if (pathCache.has(el)) return pathCache.get(el);
+    let p;
+    if (el === document.body) p = 'body';
+    else {
+      const tag = el.tagName.toLowerCase();
+      let seg;
+      if (el.id && /^[A-Za-z][\w-]*$/.test(el.id)) seg = `${tag}#${el.id}`;
+      else {
+        let i = 1, s = el;
+        while ((s = s.previousElementSibling)) if (s.tagName === el.tagName) i++;
+        seg = `${tag}:nth-of-type(${i})`;
+      }
+      p = getPath(el.parentElement) + ' > ' + seg;
+    }
+    pathCache.set(el, p);
+    return p;
+  };
+  const label = (el) => {
+    if (el === document.body) return 'body';
+    let s = el.tagName.toLowerCase();
+    if (el.id) s += '#' + el.id;
+    const cls = (typeof el.className === 'string' ? el.className : '').trim().split(/\s+/).filter(Boolean).slice(0, 2);
+    if (cls.length) s += '.' + cls.join('.');
+    else if (!el.id && el.parentElement && el.parentElement !== document.body) {
+      const pe = el.parentElement, pc = (typeof pe.className === 'string' ? pe.className : '').trim().split(/\s+/).filter(Boolean)[0];
+      s += ' in ' + pe.tagName.toLowerCase() + (pe.id ? '#' + pe.id : pc ? '.' + pc : '');
+    }
+    return s;
+  };
+  const hasDirectText = (el) => {
+    for (const n of el.childNodes) if (n.nodeType === 3 && n.textContent.trim()) return true;
+    return false;
+  };
+
+  // ---- collect layout units ----
+  const units = new Map();
+  for (const el of document.body.querySelectorAll('*')) {
+    const TAG = el.tagName.toUpperCase();
+    if (SKIP.has(TAG)) continue;
+    if (el.ownerSVGElement) continue; // inside an <svg>
+    if (ignored.length && ignored.some((ig) => ig.contains(el))) continue;
+    const cs = getComputedStyle(el);
+    if (cs.display === 'none' || cs.display === 'contents') continue;
+    if (cs.visibility === 'hidden' || cs.visibility === 'collapse') continue;
+    if (cs.display === 'inline' && !REPLACED.has(TAG)) continue;
+    const r = el.getBoundingClientRect();
+    if (r.width <= 1 || r.height <= 1) continue; // empty or sr-only
+    units.set(el, {
+      el, cs, r, path: getPath(el), label: label(el),
+      inFlow: cs.position !== 'absolute' && cs.position !== 'fixed',
+    });
+  }
+
+  // nearest ancestor that is itself a unit
+  const children = new Map();
+  for (const u of units.values()) {
+    let p = u.el.parentElement;
+    while (p && p !== document.body && !units.has(p)) p = p.parentElement;
+    u.parent = p && units.has(p) ? units.get(p) : null;
+    const key = u.parent ? u.parent.path : 'body';
+    if (!children.has(key)) children.set(key, []);
+    children.get(key).push(u);
+  }
+
+  // ---- row/column signature per container ----
+  const groups = {};
+  for (const [pkey, kids] of children) {
+    const flow = kids.filter((k) => k.inFlow);
+    if (flow.length < 2) continue;
+    const sorted = flow.slice().sort((a, b) => a.r.top - b.r.top || a.r.left - b.r.left);
+    const rows = [];
+    let cur = null;
+    for (const k of sorted) {
+      if (cur && k.r.top < cur.bottom - 1) { cur.n++; cur.bottom = Math.max(cur.bottom, k.r.bottom); }
+      else { cur = { n: 1, bottom: k.r.bottom }; rows.push(cur); }
+    }
+    groups[pkey] = rows.map((r) => r.n).join('+');
+  }
+
+  // ---- issue detection ----
+  const issues = [];
+  const add = (kind, us, detail) => issues.push({
+    kind, paths: us.map((u) => u.path), labels: us.map((u) => u.label), detail,
+    key: kind + '|' + us.map((u) => u.path).join('|'),
+  });
+  const clippedByAncestor = (el) => {
+    for (let a = el.parentElement; a && a !== document.documentElement; a = a.parentElement) {
+      if (getComputedStyle(a).overflowX !== 'visible') return true;
+    }
+    return false;
+  };
+
+  // 1. page overflows horizontally -> blame the deepest element(s) poking out,
+  //    i.e. the ones actually forcing the width, not the wrapper they stretch.
+  const pageOverflow = new Set();
+  if (document.documentElement.scrollWidth > vw + 1) {
+    // "passive" = only this wide because it fills its parent's content box
+    const passive = (u) => {
+      const p = u.parent;
+      if (!p || !u.inFlow || u.cs.float !== 'none') return false;
+      const inner = p.r.width - parseFloat(p.cs.paddingLeft) - parseFloat(p.cs.paddingRight)
+        - parseFloat(p.cs.borderLeftWidth) - parseFloat(p.cs.borderRightWidth);
+      const own = u.r.width + parseFloat(u.cs.marginLeft) + parseFloat(u.cs.marginRight);
+      return Math.abs(own - inner) <= 1;
+    };
+    const out = Array.from(units.values()).filter((u) => u.r.right > vw + 1 && !clippedByAncestor(u.el));
+    out.forEach((u) => pageOverflow.add(u.path));
+    const active = out.filter((u) => !passive(u));
+    // Ask the page directly: does removing this element shrink the scroll width?
+    // That separates real causes from elements merely carried along by a
+    // stretched parent. Deepest candidates first, capped for big pages.
+    const depth = (u) => u.path.split(' > ').length;
+    const baseSW = document.documentElement.scrollWidth;
+    const deepFirst = (a, b) => depth(b) - depth(a);
+    const tested = [...active.slice().sort(deepFirst), ...out.filter((u) => passive(u)).sort(deepFirst)].slice(0, 60);
+    const shrinks = tested.filter((u) => {
+      const prev = u.el.getAttribute('style');
+      u.el.style.setProperty('display', 'none', 'important');
+      const sw = document.documentElement.scrollWidth;
+      if (prev === null) u.el.removeAttribute('style'); else u.el.setAttribute('style', prev);
+      return sw < baseSW - 1;
+    });
+    // the cause is the deepest element whose removal helps; if none helps on its
+    // own (two equally wide offenders), fall back to the deepest active elements
+    const pool = shrinks.length ? shrinks : active;
+    const causes = pool.filter((u) => !pool.some((v) => v !== u && v.path.startsWith(u.path + ' > ')));
+    const byParent = new Map();
+    for (const u of causes) {
+      const k = u.parent ? u.parent.path : 'body';
+      if (!byParent.has(k)) byParent.set(k, []);
+      byParent.get(k).push(u);
+    }
+    for (const [pk, us] of byParent) {
+      const worst = Math.round(Math.max(...us.map((u) => u.r.right)) - vw);
+      const names = [...new Set(us.map((u) => u.label))];
+      issues.push({
+        kind: 'page-overflow', paths: us.map((u) => u.path),
+        labels: names.length === 1 && us.length > 1 ? [`${names[0]} ×${us.length}`] : names,
+        detail: `pushes the page ${worst}px wider than the screen`,
+        key: 'page-overflow|' + pk + '|' + names.join(','),
+      });
+    }
+  }
+
+  for (const u of units.values()) {
+    // 2. content escaping its container
+    const p = u.parent;
+    if (p && u.inFlow && p.cs.overflowX === 'visible' && !pageOverflow.has(u.path)) {
+      const over = u.r.right - p.r.right;
+      if (over > 1) add('container-overflow', [u, p], `extends ${Math.round(over)}px outside ${p.label}`);
+    }
+    // 3. text cut off by overflow:hidden
+    if ((u.cs.overflowX === 'hidden' || u.cs.overflowX === 'clip') && hasDirectText(u.el) &&
+        u.el.scrollWidth > u.el.clientWidth + 1) {
+      const ell = u.cs.textOverflow === 'ellipsis';
+      add('text-clipped', [u], ell ? 'text truncated with an ellipsis' : `${u.el.scrollWidth - u.el.clientWidth}px of text hidden`);
+    }
+    // 4. text below the minimum readable size
+    if (hasDirectText(u.el)) {
+      const fs = parseFloat(u.cs.fontSize);
+      if (fs < opts.minFont) add('tiny-text', [u], `font-size ${+fs.toFixed(2)}px (min ${opts.minFont}px)`);
+    }
+  }
+
+  // 5. in-flow siblings overlapping each other
+  for (const kids of children.values()) {
+    const flow = kids.filter((k) => (k.cs.position === 'static' || k.cs.position === 'relative') && k.cs.transform === 'none');
+    if (flow.length < 2 || flow.length > 120) continue;
+    for (let i = 0; i < flow.length; i++) {
+      for (let j = i + 1; j < flow.length; j++) {
+        const a = flow[i].r, b = flow[j].r;
+        const ix = Math.min(a.right, b.right) - Math.max(a.left, b.left);
+        const iy = Math.min(a.bottom, b.bottom) - Math.max(a.top, b.top);
+        if (ix > 2 && iy > 2 && ix * iy > 16) {
+          add('overlap', [flow[i], flow[j]], `overlap ${Math.round(ix)}×${Math.round(iy)}px`);
+        }
+      }
+    }
+  }
+
+  const labels = {};
+  for (const u of units.values()) labels[u.path] = u.label;
+  labels.body = 'body';
+
+  return {
+    viewportWidth: vw,
+    docWidth: document.documentElement.scrollWidth,
+    groups,
+    visible: Array.from(units.values(), (u) => u.path),
+    labels,
+    issues,
+  };
+}
+
+/** Runs inside the page: list media-query condition texts it can read. */
+function mediaConditions() {
+  const out = [], blocked = [];
+  const walk = (rules) => {
+    for (const r of rules) {
+      if (typeof CSSMediaRule !== 'undefined' && r instanceof CSSMediaRule) out.push(r.conditionText || r.media.mediaText);
+      if (r.cssRules) { try { walk(r.cssRules); } catch (e) { /* ignore */ } }
+    }
+  };
+  for (const s of document.styleSheets) {
+    try {
+      if (s.media && s.media.mediaText) out.push(s.media.mediaText);
+      walk(s.cssRules);
+    } catch (e) {
+      if (s.href) blocked.push(s.href); // cross-origin sheet; fetched from Node instead
+    }
+  }
+  return { out, blocked };
+}
+
+module.exports = { fingerprint, mediaConditions };

package/src/report.js

@@ -0,0 +1,219 @@
+'use strict';
+
+const { describeSig } = require('./analyze');
+
+const esc = (s) => String(s == null ? '' : s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+
+const KIND = {
+  'page-overflow': 'Horizontal scroll',
+  overlap: 'Overlap',
+  'container-overflow': 'Escapes container',
+  'text-clipped': 'Clipped text',
+  'tiny-text': 'Tiny text',
+};
+const CAT = {
+  problem: { name: 'Problem', cls: 'c-problem' },
+  fluid: { name: 'Fluid change', cls: 'c-fluid' },
+  breakpoint: { name: 'Media query', cls: 'c-bp' },
+  fixed: { name: 'Resolved', cls: 'c-fixed' },
+};
+
+const capList = (items, n = 8) => {
+  if (items.length <= n) return items.join('');
+  return items.slice(0, n).join('') + `<li class="more">and ${items.length - n} more</li>`;
+};
+const code = (s) => `<code>${esc(s)}</code>`;
+
+function ruler(run, opts, breakpoints) {
+  const { max, min } = opts;
+  const pos = (w) => ((max - w) / (max - min)) * 100;
+  const bands = run.ranges
+    .filter((r) => r.issue.kind !== 'tiny-text')
+    .map((r) => `<span class="band" style="left:${pos(r.from)}%;width:${Math.max(0.4, pos(r.to) - pos(r.from))}%"></span>`).join('');
+  const marks = run.transitions.map((t) =>
+    `<a class="mark ${CAT[t.diff.category].cls}" href="#h${run.height}-w${t.hi}" style="left:${pos(t.hi)}%" title="${t.hi}px · ${CAT[t.diff.category].name}"></a>`).join('');
+  const ticks = breakpoints.filter((b) => b.hi <= max && b.hi >= min)
+    .map((b) => `<span class="tick" style="left:${pos(b.hi)}%" title="${esc(b.text)}"></span>`).join('');
+  const scale = [max, Math.round(max - (max - min) / 3), Math.round(max - (2 * (max - min)) / 3), min]
+    .map((w, i) => `<span style="left:${[0, 33.33, 66.66, 100][i]}%">${w}</span>`).join('');
+  return `<div class="ruler" role="img" aria-label="Layout changes from ${max}px to ${min}px">
+    <div class="track">${bands}${marks}</div><div class="ticks">${ticks}</div><div class="scale">${scale}</div></div>`;
+}
+
+function problemList(run) {
+  if (!run.ranges.length) return '<p class="ok">No problems detected at any width.</p>';
+  const rows = run.ranges.map((r) => `<li>
+      <span class="kind k-${r.issue.kind}">${KIND[r.issue.kind]}</span>
+      <span class="who">${r.issue.labels.map(code).join(' ↔ ')}</span>
+      <span class="detail">${esc(r.issue.detail)}${r.from !== r.to ? ` <span class="at">at ${r.to}px</span>` : ''}</span>
+      <span class="range">${r.from === r.to ? r.from + 'px' : `${r.from} → ${r.to}px`}</span>
+    </li>`);
+  return `<ul class="problems">${capList(rows, 30)}</ul>`;
+}
+
+function changeCard(run, t) {
+  const d = t.diff, c = CAT[d.category];
+  const items = [
+    ...d.newIssues.map((x) => `<li class="bad"><b>${KIND[x.kind]}:</b> ${x.labels.map(code).join(' ↔ ')} — ${esc(x.detail)}</li>`),
+    ...d.regrouped.map((x) => `<li>${code(x.label)} ${esc(describeSig(x.from))} → <b>${esc(describeSig(x.to))}</b></li>`),
+    ...d.hidden.map((x) => `<li>${code(x.label)} hidden</li>`),
+    ...d.shown.map((x) => `<li>${code(x.label)} appears</li>`),
+    ...d.resolved.map((x) => `<li class="good">Resolved: ${KIND[x.kind]} on ${x.labels.map(code).join(' ↔ ')}</li>`),
+  ];
+  const why = d.matched.length
+    ? `<p class="why">Matches ${d.matched.map((m) => code('@media ' + m.text)).join(', ')}</p>`
+    : (d.category === 'fluid' ? '<p class="why">No media query here — caused by wrapping, auto-fit, or content size. Confirm it\'s intended.</p>' : '');
+  const shots = t.before && t.after ? `<div class="shots">
+      <figure><img loading="lazy" src="data:image/jpeg;base64,${t.before.data}" alt="Layout at ${t.hi}px"><figcaption>${t.hi}px</figcaption></figure>
+      <figure><img loading="lazy" src="data:image/jpeg;base64,${t.after.data}" alt="Layout at ${t.lo}px"><figcaption>${t.lo}px</figcaption></figure>
+    </div>` : '';
+  return `<article class="change" id="h${run.height}-w${t.hi}">
+    <header><span class="w">${t.hi}<small>→${t.lo}px</small></span><span class="cat ${c.cls}">${c.name}</span></header>
+    ${why}<ul class="what">${capList(items)}</ul>${shots}</article>`;
+}
+
+/**
+ * Collapse consecutive fluid changes to the same container(s) into one entry,
+ * e.g. a nav that rewraps 7 times is one thing to review, not seven.
+ */
+function groupTransitions(transitions) {
+  const items = [];
+  const sigOf = (t) => (t.diff.category === 'fluid' && !t.diff.hidden.length && !t.diff.shown.length
+    ? t.diff.regrouped.map((x) => x.path).sort().join('|') : null);
+  for (const t of transitions) {
+    const s = sigOf(t), last = items[items.length - 1];
+    if (s && last && last.sig === s) last.series.push(t);
+    else items.push({ sig: s, series: [t] });
+  }
+  return items;
+}
+
+function seriesCard(run, item) {
+  const s = item.series, first = s[0], last = s[s.length - 1];
+  const steps = s.map((t) => t.diff.regrouped.map((x) => `<li><span class="sw">${t.hi}px</span> ${code(x.label)} <b>${esc(x.to)}</b> <span class="muted">(${esc(describeSig(x.to))})</span></li>`).join(''));
+  const who = first.diff.regrouped.map((x) => code(x.label)).join(', ');
+  const shots = first.before && last.after ? `<div class="shots">
+      <figure><img loading="lazy" src="data:image/jpeg;base64,${first.before.data}" alt="Layout at ${first.hi}px"><figcaption>${first.hi}px</figcaption></figure>
+      <figure><img loading="lazy" src="data:image/jpeg;base64,${last.after.data}" alt="Layout at ${last.lo}px"><figcaption>${last.lo}px</figcaption></figure>
+    </div>` : '';
+  return `<article class="change" id="h${run.height}-w${first.hi}">
+    <header><span class="w">${first.hi}<small>→${last.lo}px</small></span><span class="cat c-fluid">Fluid change ×${s.length}</span></header>
+    <p class="why">${who} rewraps ${s.length} times with no media query, starting as ${esc(first.diff.regrouped[0].from)} (${esc(describeSig(first.diff.regrouped[0].from))}). Uneven rows like 5+1 usually mean it needs a breakpoint or a grid.</p>
+    <ul class="what steps">${steps.join('')}</ul>${shots}</article>`;
+}
+
+function baselineBlock(cmp) {
+  if (!cmp) return '';
+  const li = (arr, fmt) => arr.length ? `<ul>${arr.map(fmt).join('')}</ul>` : '<p class="muted">None</p>';
+  return `<section class="baseline"><h2>Compared with baseline <small>${esc(cmp.baselineDate)}</small></h2>
+    <div class="cols">
+      <div><h3>New problems</h3>${li(cmp.newProblems, (p) => `<li><span class="kind k-${p.kind}">${KIND[p.kind]}</span> ${p.labels.map(code).join(' ↔ ')} <span class="range">${p.from} → ${p.to}px</span></li>`)}</div>
+      <div><h3>Fixed problems</h3>${li(cmp.fixedProblems, (p) => `<li>${KIND[p.kind]} ${p.labels.map(code).join(' ↔ ')}</li>`)}</div>
+      <div><h3>New layout changes</h3>${li(cmp.newChanges, (c) => `<li>${c.at}px · ${CAT[c.category].name}</li>`)}</div>
+      <div><h3>Changes no longer happening</h3>${li(cmp.goneChanges, (c) => `<li>${c.at}px · ${CAT[c.category].name}</li>`)}</div>
+    </div></section>`;
+}
+
+function renderReport(result, comparison) {
+  const o = result.options;
+  const all = result.runs.flatMap((r) => r.transitions);
+  const grouped = result.runs.map((r) => groupTransitions(r.transitions));
+  const count = (cat) => grouped.flat().filter((g) => g.series[0].diff.category === cat).length;
+  const problems = result.runs.reduce((n, r) => n + r.ranges.length, 0);
+  let host = result.url;
+  try { const u = new URL(result.url); host = u.protocol === 'file:' ? u.pathname.split('/').pop() : u.host + u.pathname; } catch (e) { /* keep */ }
+
+  const runs = result.runs.map((run, ri) => `
+    <section class="run">
+      ${result.runs.length > 1 ? `<h2>Height ${run.height}px</h2>` : ''}
+      ${ruler(run, o, result.breakpoints)}
+      <div class="legend"><span class="c-problem">Problem</span><span class="c-fluid">Fluid change</span><span class="c-bp">Media query</span><span class="c-fixed">Resolved</span><span class="lg-band">Problem range</span><span class="lg-tick">Your breakpoints</span></div>
+      <h3>Problems by width range</h3>
+      ${problemList(run)}
+      <h3>Every layout change, widest first</h3>
+      ${run.transitions.length ? grouped[ri].map((g) => (g.series.length > 1 ? seriesCard(run, g) : changeCard(run, g.series[0]))).join('') : '<p class="ok">Layout never changes in this range.</p>'}
+    </section>`).join('');
+
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Starchy Report</title>
+<style>
+:root{--bg:#f7f7f5;--card:#fff;--ink:#1b1b1a;--muted:#6b6a66;--line:#e4e3df;--code:#f0efeb;
+--red:#d93a3f;--amber:#c98a06;--green:#2f8f5b;--gray:#8a8984;--accent:#3b5bdb}
+@media (prefers-color-scheme:dark){:root:not([data-theme=light]){--bg:#141413;--card:#1d1d1b;--ink:#ecebe7;--muted:#9b9a95;--line:#2e2e2b;--code:#262624;--red:#f0656a;--amber:#e3a826;--green:#53b582;--gray:#77766f;--accent:#7c95f0}}
+:root[data-theme=dark]{--bg:#141413;--card:#1d1d1b;--ink:#ecebe7;--muted:#9b9a95;--line:#2e2e2b;--code:#262624;--red:#f0656a;--amber:#e3a826;--green:#53b582;--gray:#77766f;--accent:#7c95f0}
+*{box-sizing:border-box}
+body{margin:0;background:var(--bg);color:var(--ink);font:15px/1.5 ui-sans-serif,system-ui,-apple-system,"Segoe UI",sans-serif}
+main{max-width:1080px;margin:0 auto;padding:28px 16px 64px}
+h1{font-size:26px;letter-spacing:-.02em;margin:0 0 4px}h1 .tag{font-size:13px;font-weight:500;letter-spacing:0;color:var(--muted);margin-left:6px}footer a{color:inherit}
+h2{font-size:19px;margin:36px 0 12px}h2 small{color:var(--muted);font-weight:400;font-size:13px}
+h3{font-size:12px;text-transform:uppercase;letter-spacing:.08em;color:var(--muted);margin:28px 0 10px}
+.sub{color:var(--muted);margin:0 0 18px;word-break:break-all}
+code{font:12.5px/1.4 ui-monospace,SFMono-Regular,Menlo,monospace;background:var(--code);padding:1px 5px;border-radius:4px;word-break:break-all}
+.stats{display:grid;grid-template-columns:repeat(4,1fr);gap:10px;margin:18px 0 8px}
+.stat{background:var(--card);border:1px solid var(--line);border-radius:10px;padding:12px 14px}
+.stat b{display:block;font-size:26px;line-height:1.1;font-variant-numeric:tabular-nums}
+.stat span{color:var(--muted);font-size:12.5px}
+.stat.s-problem b{color:var(--red)}.stat.s-fluid b{color:var(--amber)}.stat.s-bp b{color:var(--green)}
+.ruler{margin:22px 0 6px}
+.track{position:relative;height:34px;background:var(--card);border:1px solid var(--line);border-radius:8px;overflow:hidden}
+.band{position:absolute;top:0;bottom:0;background:color-mix(in srgb,var(--red) 16%,transparent)}
+.mark{position:absolute;top:5px;bottom:5px;width:4px;margin-left:-2px;border-radius:2px}
+.ticks{position:relative;height:9px}.tick{position:absolute;top:2px;width:2px;height:7px;margin-left:-1px;background:var(--accent)}
+.scale{position:relative;height:18px;font-size:11px;color:var(--muted);font-variant-numeric:tabular-nums}
+.scale span{position:absolute;transform:translateX(-50%)}.scale span:first-child{transform:none}.scale span:last-child{transform:translateX(-100%)}
+.legend{display:flex;flex-wrap:wrap;gap:6px 14px;font-size:12px;color:var(--muted);margin-top:6px}
+.legend span::before{content:"";display:inline-block;width:9px;height:9px;border-radius:2px;margin-right:5px;vertical-align:-1px}
+.mark.c-problem,.legend .c-problem::before{background:var(--red)}
+.mark.c-fluid,.legend .c-fluid::before{background:var(--amber)}
+.mark.c-bp,.legend .c-bp::before{background:var(--green)}
+.mark.c-fixed,.legend .c-fixed::before{background:var(--gray)}
+.legend .lg-band::before{background:color-mix(in srgb,var(--red) 25%,transparent)}
+.legend .lg-tick::before{background:var(--accent);width:3px}
+.problems{list-style:none;padding:0;margin:0;background:var(--card);border:1px solid var(--line);border-radius:10px}
+.problems li{display:grid;grid-template-columns:auto 1fr auto;gap:4px 12px;padding:10px 14px;border-top:1px solid var(--line);align-items:baseline}
+.problems li:first-child{border-top:0}
+.problems .detail{grid-column:2;color:var(--muted);font-size:13px}
+.problems .range{grid-column:3;grid-row:1;font-variant-numeric:tabular-nums;font-size:13px;white-space:nowrap}
+.problems .more{display:block;color:var(--muted)}.problems .kind{justify-self:start}.at{opacity:.75}
+.kind{font-size:11.5px;font-weight:600;padding:2px 8px;border-radius:99px;white-space:nowrap;color:var(--red);background:color-mix(in srgb,var(--red) 12%,transparent)}
+.k-text-clipped,.k-tiny-text{color:var(--amber);background:color-mix(in srgb,var(--amber) 14%,transparent)}
+.ok{background:var(--card);border:1px solid var(--line);border-radius:10px;padding:12px 14px;color:var(--green);margin:0}
+.change{background:var(--card);border:1px solid var(--line);border-radius:10px;padding:14px 16px;margin:0 0 12px;scroll-margin-top:12px}
+.change header{display:flex;align-items:center;justify-content:space-between;gap:10px}
+.w{font-size:20px;font-weight:650;font-variant-numeric:tabular-nums;letter-spacing:-.01em}
+.w small{font-size:12px;font-weight:400;color:var(--muted);margin-left:4px}
+.cat{font-size:12px;font-weight:600;padding:3px 10px;border-radius:99px}
+.cat.c-problem{color:var(--red);background:color-mix(in srgb,var(--red) 13%,transparent)}
+.cat.c-fluid{color:var(--amber);background:color-mix(in srgb,var(--amber) 15%,transparent)}
+.cat.c-bp{color:var(--green);background:color-mix(in srgb,var(--green) 14%,transparent)}
+.cat.c-fixed{color:var(--muted);background:var(--code)}
+.why{margin:6px 0 0;font-size:13px;color:var(--muted)}
+.what{margin:10px 0 0;padding-left:18px}.what li{margin:3px 0}
+.steps{list-style:none;padding:0}.steps li{display:flex;flex-wrap:wrap;gap:6px;align-items:baseline}.sw{font-variant-numeric:tabular-nums;color:var(--muted);min-width:52px;font-size:13px}
+.what .bad{color:var(--red)}.what .bad code{color:var(--ink)}.what .good{color:var(--green)}.what .more{list-style:none;color:var(--muted)}
+.shots{display:grid;grid-template-columns:1fr 1fr;gap:12px;margin-top:14px;align-items:start}
+figure{margin:0}figure img{display:block;width:100%;height:auto;max-height:420px;object-fit:contain;object-position:top left;border:1px solid var(--line);border-radius:6px;background:#fff}
+figcaption{font-size:12px;color:var(--muted);margin-top:4px;font-variant-numeric:tabular-nums}
+.baseline .cols{display:grid;grid-template-columns:1fr 1fr;gap:12px}
+.baseline .cols>div{background:var(--card);border:1px solid var(--line);border-radius:10px;padding:2px 14px 10px}
+.baseline ul{padding-left:18px;margin:0}.muted{color:var(--muted);margin:0}
+footer{margin-top:40px;color:var(--muted);font-size:12.5px}
+@media (max-width:640px){.stats{grid-template-columns:repeat(2,1fr)}.shots,.baseline .cols{grid-template-columns:1fr}
+.problems li{grid-template-columns:1fr auto}.problems .who,.problems .detail{grid-column:1/-1}.problems .range{grid-column:2;grid-row:1}}
+</style></head><body><main>
+<h1>Starchy <span class="tag">layout report</span></h1>
+<p class="sub">${esc(host)} · ${o.max}→${o.min}px${result.runs.length > 1 ? ' · heights ' + o.heights.join(', ') + 'px' : ' · ' + o.heights[0] + 'px tall'} · ${new Date(result.generated).toLocaleString('en-US', { dateStyle: 'medium', timeStyle: 'short' })}</p>
+<div class="stats">
+  <div class="stat s-problem"><b>${problems}</b><span>problems</span></div>
+  <div class="stat s-fluid"><b>${count('fluid')}</b><span>fluid changes to review</span></div>
+  <div class="stat s-bp"><b>${count('breakpoint')}</b><span>media-query changes</span></div>
+  <div class="stat"><b>${all.length}</b><span>layout changes total</span></div>
+</div>
+${baselineBlock(comparison)}
+${runs}
+<footer><a href="https://starchy.dev">starchy</a> · swept in ${result.seconds}s · ${result.runs.reduce((n, r) => n + r.evals, 0)} widths fingerprinted · breakpoints read from your CSS: ${result.breakpoints.map((b) => b.hi + 'px').join(', ') || 'none'}</footer>
+</main></body></html>`;
+}
+
+module.exports = { renderReport };