@trueclone/cli 0.1.0 → 0.3.0

package/scripts/explain.mjs

@@ -0,0 +1,87 @@
+// One look at one place on the page: what every check saw there, so a gap is read from the tool's own data instead of
+// re-measured by hand. Given a page y (or a section label) at one width, it prints the layout section's score, the
+// scroll states near it, the detail probes that differ, the hover rows that differ, and writes a side-by-side crop
+// (reference | clone | diff, masked) around that y.
+// usage: node scripts/explain.mjs <name> <y | "section label"> [--viewport desktop] [--range 800]
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { PNG, parseArgs, crop } from './lib.mjs';
+
+const { pos, flags } = parseArgs(process.argv.slice(2));
+const [name, where] = pos;
+if (!name || where === undefined) {
+  console.error('usage: trueclone explain <name> <y | "section label"> [--viewport desktop] [--range 800]');
+  process.exit(1);
+}
+const vp = flags.viewport || 'desktop';
+const range = Number(flags.range || 800);
+const root = path.resolve('sites', name);
+const read = async (rel) => fs.readFile(path.join(root, rel), 'utf8').then(JSON.parse).catch(() => null);
+
+const layout = await read('compare/report.mask.json');
+const lv = layout?.viewports.find((v) => v.viewport === vp);
+if (!lv) {
+  console.error(`no layout score for ${vp} yet: run trueclone score ${name} first`);
+  process.exit(1);
+}
+const section = /^\d+$/.test(where)
+  ? lv.sections.find((s) => Number(where) >= s.y && Number(where) < s.y + s.height) || null
+  : lv.sections.find((s) => String(s.label).toLowerCase().includes(where.toLowerCase())) || null;
+const y = /^\d+$/.test(where) ? Number(where) : section?.y;
+if (y === undefined) {
+  console.error(`no section labelled like "${where}" at ${vp}; sections: ${lv.sections.map((s) => `${s.y} ${String(s.label).slice(0, 24)}`).join(' | ')}`);
+  process.exit(1);
+}
+const lo = Math.max(0, y - range / 2), hi = y + range / 2;
+const within = (v) => v >= lo && v <= hi;
+
+console.log(`${name} @ ${vp} y ${y} (±${range / 2}px)`);
+console.log(`\nLayout: page ${lv.heightRef}px vs clone ${lv.heightClone}px (${lv.match}% overall)`);
+if (section) console.log(`  section "${String(section.label).slice(0, 60)}" y ${section.y} h ${section.height}: ${section.match}%`);
+for (const s of lv.sections.filter((s) => s !== section && (within(s.y) || within(s.y + s.height)))) console.log(`  nearby "${String(s.label).slice(0, 40)}" y ${s.y}: ${s.match}%`);
+
+const states = await read('compare/states/report.mask.json');
+const sv = states?.viewports?.find((v) => v.viewport === vp);
+const steps = (sv?.steps || sv?.states || []).filter((st) => within(st.scrollY ?? st.y ?? st.scroll ?? -1));
+if (steps.length) console.log(`\nScroll states scrolled to here: ${steps.map((st) => `${st.scrollY ?? st.y ?? st.scroll}px ${st.match ?? st.score}%`).join(', ')}`);
+
+const detail = await read('compare/detail.json');
+const dv = detail?.viewports?.find((v) => v.viewport === vp);
+if (dv) {
+  const here = dv.issues.filter((it) => within(it.y));
+  const unstable = (dv.unstableProbes || []).filter((it) => within(it.y));
+  console.log(`\nDetail: ${here.length} differing probe(s) here${unstable.length ? `, ${unstable.length} unstable on the reference (not scored)` : ''}`);
+  const groups = new Map();
+  for (const it of here) { const k = `${it.ref} -> ${it.clone}: ${it.props.join('; ')}`; const g = groups.get(k) || { ...it, n: 0 }; g.n++; groups.set(k, g); }
+  [...groups.values()].sort((a, b) => b.n - a.n).slice(0, 12).forEach((g) => console.log(`  x${String(g.n).padEnd(3)} y${String(g.y).padEnd(6)} ${g.ref} -> ${g.clone}: ${g.props.join('; ')}`));
+}
+
+const hovers = await read(`compare/hovers.${vp}.json`);
+if (hovers) {
+  const rows = hovers.rows.filter((r) => within(r.y) && !['static', 'ok', 'unstable'].includes(r.status));
+  if (rows.length) { console.log(`\nHovers differing here:`); rows.slice(0, 10).forEach((r) => console.log(`  y${r.y} ${r.ref}: reference changes ${r.refChanges}, clone ${r.cloneChanges} (${r.status})`)); }
+}
+
+// the crop: reference | clone | diff, masked, half size
+try {
+  const imgs = await Promise.all([`reference/${vp}.mask.png`, `compare/${vp}.mask.clone.png`, `compare/${vp}.mask.diff.png`].map(async (f) => PNG.sync.read(await fs.readFile(path.join(root, f)))));
+  const top = Math.max(0, Math.round(lo)), h = Math.min(Math.round(hi) - top, Math.min(...imgs.map((i) => i.height)) - top);
+  const parts = imgs.map((img) => crop(img, top, h));
+  const scale = 0.5, w = Math.round(parts[0].width * scale), hh = Math.round(h * scale);
+  const out = new PNG({ width: w * 3 + 20, height: hh });
+  out.data.fill(255);
+  parts.forEach((p, k) => {
+    for (let yy = 0; yy < hh; yy++) for (let x = 0; x < w; x++) {
+      const sx = Math.min(p.width - 1, Math.round(x / scale)), sy = Math.min(p.height - 1, Math.round(yy / scale));
+      const si = (sy * p.width + sx) * 4, di = (yy * out.width + x + k * (w + 10)) * 4;
+      out.data[di] = p.data[si]; out.data[di + 1] = p.data[si + 1]; out.data[di + 2] = p.data[si + 2]; out.data[di + 3] = 255;
+    }
+  });
+  const file = path.join(root, 'compare', 'explain', `${vp}-${y}.png`);
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  await fs.writeFile(file, PNG.sync.write(out));
+  console.log(`\nCrop (reference | clone | diff, y ${top}-${top + h}): ${path.relative(process.cwd(), file)}`);
+} catch (e) {
+  console.log(`\n(no crop: ${e.message.split('\n')[0]})`);
+}
+console.log(`\nNext: npx trueclone rules ${name} "<selector>" --viewport ${vp} (the reference's CSS) and --clone (the clone's), or npx trueclone score ${name} --only layout,detail --viewport ${vp} after a fix.`);

package/scripts/hovers.mjs

@@ -86,15 +86,23 @@ async function hoverAll(browser, url, list) {
     const after = await page.evaluate(signature, [t.x, vy]);
     out.push({ sel: before?.sel || null, kinds: before && after && before.sel === after.sel ? changedKinds(before, after) : [] });
   }
+  const pageHeight = await page.evaluate(() => document.documentElement.scrollHeight).catch(() => null);
   await context.close();
-  return { list, out };
+  return { list, out, pageHeight };
 }
 
 const browser = await openBrowser(flags.cdp);
 let ref, cl;
 try {
-  // reference hovers are cached until the next capture (--refresh-ref to re-measure)
-  ref = await cached(root, { tool: 'hovers', vp: vp.name, max: MAX, v: 2 }, () => hoverAll(browser, meta.url, null), Boolean(flags['refresh-ref']));
+  // reference hovers are cached until the next capture (--refresh-ref to re-measure); read twice, so a hover effect
+  // that comes and goes by timing on the reference itself is set aside as unstable rather than demanded of the clone
+  ref = await cached(root, { tool: 'hovers', vp: vp.name, max: MAX, v: 3 }, async () => {
+    const first = await hoverAll(browser, meta.url, null);
+    const captured = meta.viewports?.find((v) => v.viewport === vp.name)?.pageHeight;
+    if (captured && first.pageHeight && Math.abs(first.pageHeight - captured) > Math.max(40, captured * 0.01)) console.warn(`WARNING reference drift (${vp.name}): the live page is ${first.pageHeight}px tall, the capture was ${captured}px (${meta.capturedAt}); re-capture before trusting this score`);
+    const again = await hoverAll(browser, meta.url, first.list);
+    return { ...first, unstable: first.out.map((a, i) => a.sel !== again.out[i]?.sel || a.kinds.join() !== (again.out[i]?.kinds || []).join()) };
+  }, Boolean(flags['refresh-ref']));
   cl = await hoverAll(browser, cloneUrl, ref.list);
 } finally {
   if (!flags.cdp) await browser.close();
@@ -102,15 +110,16 @@ try {
 }
 const rows = ref.list.map((t, i) => {
   const a = ref.out[i], b = cl.out[i];
-  const status = !a.kinds.length ? (b.kinds.length ? 'extra' : 'static') : !b.sel ? 'no element' : !b.kinds.length ? 'MISSING' : a.kinds.some((k) => b.kinds.includes(k)) ? 'ok' : 'different';
+  const status = ref.unstable?.[i] ? 'unstable' : !a.kinds.length ? (b.kinds.length ? 'extra' : 'static') : !b.sel ? 'no element' : !b.kinds.length ? 'MISSING' : a.kinds.some((k) => b.kinds.includes(k)) ? 'ok' : 'different';
   return { y: t.y, ref: a.sel || t.sel, refChanges: a.kinds.join(',') || '-', clone: b.sel || '-', cloneChanges: b.kinds.join(',') || '-', status };
 });
-const withHover = rows.filter((r) => r.refChanges !== '-');
+const withHover = rows.filter((r) => r.refChanges !== '-' && r.status !== 'unstable');
+const unstable = rows.filter((r) => r.status === 'unstable').length;
 const ok = withHover.filter((r) => r.status === 'ok').length;
-const report = { name, viewport: vp.name, at: new Date().toISOString(), score: +(100 * ok / Math.max(1, withHover.length)).toFixed(1), rows };
+const report = { name, viewport: vp.name, at: new Date().toISOString(), score: +(100 * ok / Math.max(1, withHover.length)).toFixed(1), unstable, rows };
 const out = path.join(root, 'compare', `hovers.${vp.name}.json`);
 await fs.mkdir(path.dirname(out), { recursive: true });
 await fs.writeFile(out, JSON.stringify(report, null, 2));
-console.log(`hover match (${vp.name}): ${report.score}% of ${withHover.length} reference hover effects reproduced (${rows.length} interactive elements probed)`);
-console.table(rows.filter((r) => r.status !== 'static' && r.status !== 'ok').slice(0, 25));
+console.log(`hover match (${vp.name}): ${report.score}% of ${withHover.length} reference hover effects reproduced (${rows.length} interactive elements probed${unstable ? `, ${unstable} unstable on the reference itself, not scored` : ''})`);
+console.table(rows.filter((r) => r.status !== 'static' && r.status !== 'ok' && r.status !== 'unstable').slice(0, 25));
 console.log(`-> ${path.relative(process.cwd(), out)}`);

package/scripts/interact.mjs

@@ -64,7 +64,7 @@ const stateOf = (page, selector) => page.evaluate((sel) => {
   const r = el.getBoundingClientRect();
   // Besides geometry and visibility: text, state attributes and canvas pixels, so a button that changes its label,
   // a tab that flips aria-pressed or a game that redraws its canvas counts as a change too.
-  const attrs = ['class', 'aria-pressed', 'aria-current', 'aria-expanded', 'open', 'hidden', 'disabled']
+  const attrs = ['class', 'aria-pressed', 'aria-current', 'aria-expanded', 'aria-selected', 'data-state', 'open', 'hidden', 'disabled']
     .map((a) => (el.hasAttribute(a) ? `${a}=${el.getAttribute(a)}` : '')).join(',') // boolean attributes are "" + (el.value !== undefined ? `,${el.value}` : '');
   const text = el.textContent.replace(/\s+/g, ' ').trim().slice(0, 200);
   let pixels = '';
@@ -88,7 +88,7 @@ async function runSide(url, side, list) {
       await warmUp(page);
       const atSel = sc.at?.[side];
       if (atSel && atSel !== 'body') {
-        const y = await page.evaluate((s) => { const el = document.querySelector(s); return el ? el.getBoundingClientRect().top + scrollY : 0; }, atSel);
+        const y = await page.evaluate((sel) => { const [s, idx] = sel.split('@'); const el = document.querySelectorAll(s)[Number(idx || 0)]; return el ? el.getBoundingClientRect().top + scrollY : 0; }, atSel);
         await wheelTo(page, Math.max(0, Math.round(y + (sc.at.offset || 0))), vp);
       } else {
         await wheelTo(page, sc.at?.offset || 0, vp);
@@ -121,7 +121,11 @@ async function runSide(url, side, list) {
         else if (st.click) {
           const target = Array.isArray(st.click) ? st.click : st.click[side];
           if (Array.isArray(target)) await page.mouse.click(...px(target));
-          else await page.click(target, { timeout: 5000 }).catch((e) => results.push({ name: sc.name, error: `click ${target}: ${e.message.split('\n')[0]}` }));
+          else {
+            // selector@n: the n-th match, as everywhere else in the scenario file
+            const [s, idx] = target.split('@');
+            await page.locator(s).nth(Number(idx || 0)).click({ timeout: 5000 }).catch((e) => results.push({ name: sc.name, error: `click ${target}: ${e.message.split('\n')[0]}` }));
+          }
         } else if (st.key) await page.keyboard.press(st.key);
         else if (st.wait) await page.waitForTimeout(st.wait);
         else if (st.shot) await shot(st.shot);

package/scripts/lib.mjs

@@ -124,23 +124,51 @@ const MASK_CSS = `*,*::before,*::after{color:transparent!important;text-shadow:n
 ::placeholder{color:transparent!important}
 img,video{object-position:-99999px -99999px!important;background:#888!important}
 svg{background:#888!important} svg *{visibility:hidden!important} iframe{visibility:hidden!important}
-canvas{background:#888!important;filter:contrast(0) brightness(1.066)!important}`; // canvas = media (WebGL heroes, 3D models): flat grey box like images
+canvas{background:#888!important;filter:contrast(0) brightness(1.066)!important}
+[data-lab-cliptext]{background:none!important;-webkit-text-fill-color:transparent!important}
+[data-lab-bgi]{background-image:none!important;background-color:#888!important}
+[data-lab-bgb]::before,[data-lab-bga]::after{background-image:none!important;background-color:#888!important}`; // canvas = media (WebGL heroes, 3D models): flat grey box like images
+
+// What CSS alone can't select: photo backgrounds (a script that rewrites an element's inline background every frame
+// would undo an inline override, so the mask is a stylesheet rule on a marker attribute, which inline styles lose
+// to), gradient text (background-clip: text paints the glyphs with its background, so a transparent colour still
+// shows the letters) and photo backgrounds on ::before/::after. `off` removes the markers.
+function maskExtrasInPage(enable) {
+  const marks = ['data-lab-bgi', 'data-lab-cliptext', 'data-lab-bgb', 'data-lab-bga'];
+  if (!enable) {
+    for (const m of marks) for (const el of document.querySelectorAll(`[${m}]`)) el.removeAttribute(m);
+    return;
+  }
+  for (const el of document.querySelectorAll('*')) {
+    const s = getComputedStyle(el);
+    if (s.backgroundImage.includes('url(')) el.setAttribute('data-lab-bgi', '');
+    if (s.backgroundClip === 'text' || s.webkitBackgroundClip === 'text') el.setAttribute('data-lab-cliptext', '');
+    if (getComputedStyle(el, '::before').backgroundImage.includes('url(')) el.setAttribute('data-lab-bgb', '');
+    if (getComputedStyle(el, '::after').backgroundImage.includes('url(')) el.setAttribute('data-lab-bga', '');
+  }
+}
 
 export async function mask(page) {
   const tag = await page.addStyleTag({ content: MASK_CSS });
   await tag.evaluate((el) => el.setAttribute('data-lab-freeze', ''));
+  await page.evaluate(maskExtrasInPage, true);
+  await page.waitForTimeout(200);
+}
+
+// Endless animations (marquees, rotating borders, pulsing glows) sit at whatever phase the page's clock happens to
+// be at, so two screenshots of the same page differ. Before a still comparison, every infinite animation is put on
+// its first frame and paused, on both sides. Continuous motion is scored by the motion checks, not by stills.
+export async function freezeLoops(page) {
   await page.evaluate(() => {
-    for (const el of document.querySelectorAll('*')) {
-      if (getComputedStyle(el).backgroundImage.includes('url(')) {
-        el.style.setProperty('background-image', 'none', 'important');
-        el.style.setProperty('background-color', '#888', 'important');
-      }
+    for (const a of document.getAnimations()) {
+      if (a.effect?.getTiming().iterations !== Infinity) continue;
+      a.currentTime = 0;
+      a.pause();
     }
-  });
-  await page.waitForTimeout(200);
+  }).catch(() => {});
 }
 
-// Reversible version of mask() for live pages: on() masks, off() restores every inline style it touched.
+// Reversible version of mask() for live pages: on() masks, off() removes the stylesheet and every marker.
 export async function maskToggle(page, on) {
   await page.evaluate(([css, enable]) => {
     if (enable) {
@@ -149,21 +177,11 @@ export async function maskToggle(page, on) {
       tag.setAttribute('data-lab-freeze', '');
       tag.textContent = css;
       document.head.appendChild(tag);
-      for (const el of document.querySelectorAll('*')) {
-        if (getComputedStyle(el).backgroundImage.includes('url(')) {
-          el.setAttribute('data-lab-bg', el.style.cssText);
-          el.style.setProperty('background-image', 'none', 'important');
-          el.style.setProperty('background-color', '#888', 'important');
-        }
-      }
     } else {
       document.getElementById('lab-mask')?.remove();
-      for (const el of document.querySelectorAll('[data-lab-bg]')) {
-        el.style.cssText = el.getAttribute('data-lab-bg');
-        el.removeAttribute('data-lab-bg');
-      }
     }
   }, [MASK_CSS, on]);
+  await page.evaluate(maskExtrasInPage, on);
   await page.waitForTimeout(on ? 150 : 50);
 }
 

package/scripts/load.mjs

@@ -0,0 +1,102 @@
+// Load sequence: what a visitor sees between the first byte and the settled page, on both sides, measured the same
+// way. Each side loads in a fresh context (cold cache, cache disabled) on the same emulated network, and the visible
+// viewport is photographed 250, 500, 1000, 2000 and 4000 ms after navigation starts, then once more when the page has
+// settled. "Settled at t" is how much the frame at t already matches the final frame (pixel match), so a clone that
+// paints a wrong skeleton for two seconds, or settles much later or earlier than the original, shows up as a gap
+// between the two curves. The score is 100 minus the mean gap. Reference curves are cached per capture.
+//
+// usage: node scripts/load.mjs <name> [--viewport desktop|tablet|mobile|all] [--url <clone url>] [--refresh-ref]
+//   -> sites/<name>/compare/load.json, frames in compare/load/ and reference/load/
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { VIEWPORTS, parseArgs, openBrowser, newPage, serve, matchPct, cached, PNG, withTimeout } from './lib.mjs';
+
+const { pos, flags } = parseArgs(process.argv.slice(2));
+const [name] = pos;
+if (!name) {
+  console.error('usage: trueclone load <name> [--viewport desktop|all] [--url <clone url>] [--refresh-ref]');
+  process.exit(1);
+}
+const root = path.resolve('sites', name);
+const meta = JSON.parse(await fs.readFile(path.join(root, 'reference', 'meta.json'), 'utf8'));
+const vps = !flags.viewport || flags.viewport === 'all' ? VIEWPORTS : [VIEWPORTS.find((v) => v.name === flags.viewport)].filter(Boolean);
+const TIMES = [250, 500, 1000, 2000, 4000];
+const SETTLED = 98; // a frame this close to the final one counts as settled
+const NOISE_LIMIT = 15; // two runs of one side further apart than this: that side is unstable, the width is not scored
+// the same network for both sides: the clone is served from this machine, the reference from a CDN, so both are
+// bounded by the emulated link, not by where they come from
+const NETWORK = { offline: false, latency: 40, downloadThroughput: 1.25e6, uploadThroughput: 6e5 };
+
+async function sequence(browser, url, vp, dir) {
+  const { context, page } = await newPage(browser, vp, { reducedMotion: 'no-preference' });
+  try {
+    const cdp = await context.newCDPSession(page);
+    await cdp.send('Network.enable');
+    await cdp.send('Network.setCacheDisabled', { cacheDisabled: true });
+    await cdp.send('Network.emulateNetworkConditions', NETWORK);
+    await fs.mkdir(dir, { recursive: true });
+    const frames = {};
+    const t0 = Date.now();
+    const nav = page.goto(url, { waitUntil: 'load', timeout: 60000 }).catch(() => null);
+    for (const t of TIMES) {
+      const wait = t0 + t - Date.now();
+      if (wait > 0) await new Promise((r) => setTimeout(r, wait));
+      // the frame may be blank before the first byte (a valid part of the sequence)
+      const shot = await withTimeout(page.screenshot({ fullPage: false, animations: 'allow' }), 5000, `load shot ${t}`).catch(() => null);
+      frames[t] = shot ? PNG.sync.read(shot) : null;
+      if (shot) await fs.writeFile(path.join(dir, `${vp.name}-${t}.png`), shot);
+    }
+    await nav;
+    await page.waitForLoadState('networkidle', { timeout: 15000 }).catch(() => {});
+    await page.evaluate(() => document.fonts.ready).catch(() => {});
+    await page.waitForTimeout(1500);
+    const finalShot = await page.screenshot({ fullPage: false, animations: 'allow' });
+    await fs.writeFile(path.join(dir, `${vp.name}-final.png`), finalShot);
+    const final = PNG.sync.read(finalShot);
+    const curve = {};
+    for (const t of TIMES) curve[t] = frames[t] ? matchPct(frames[t], final).pct : 0;
+    const settledAt = TIMES.find((t) => curve[t] >= SETTLED) ?? null;
+    return { curve, settledAt };
+  } finally {
+    await context.close();
+  }
+}
+
+const cloneUrl = typeof flags.url === 'string' ? flags.url : null;
+const server = cloneUrl ? null : await serve(path.join(root, 'clone'));
+const browser = await openBrowser(flags.cdp);
+const viewports = [];
+try {
+  // each side twice: a load is never the same twice (an image that arrives a frame later moves an intro), so the
+  // curve is the mean of two runs and the spread between them is reported as the measurement's own noise
+  const twice = async (url, dir, vp) => {
+    const a = await sequence(browser, url, vp, dir);
+    const b = await sequence(browser, url, vp, dir);
+    const curve = Object.fromEntries(TIMES.map((t) => [t, +((a.curve[t] + b.curve[t]) / 2).toFixed(2)]));
+    const noise = +Math.max(...TIMES.map((t) => Math.abs(a.curve[t] - b.curve[t]))).toFixed(2);
+    return { curve, noise, settledAt: TIMES.find((t) => curve[t] >= SETTLED) ?? null, runs: [a, b] };
+  };
+  for (const vp of vps) {
+    const ref = await cached(root, { tool: 'load', vp: vp.name, times: TIMES, network: NETWORK, v: 2 }, () => twice(meta.url, path.join(root, 'reference', 'load'), vp), Boolean(flags['refresh-ref']));
+    const clone = await twice(cloneUrl || `${server.url}index.html`, path.join(root, 'compare', 'load'), vp);
+    const gap = Object.fromEntries(TIMES.map((t) => [t, +Math.abs(ref.curve[t] - clone.curve[t]).toFixed(2)]));
+    const noise = +Math.max(ref.noise, clone.noise).toFixed(2);
+    // a side that does not agree with itself (an intro that starts a second later in one run) cannot be scored
+    // against anything: the width is reported as unstable, like a probe, instead of as a number
+    const unstable = noise > NOISE_LIMIT;
+    const score = unstable ? null : +(100 - TIMES.reduce((s, t) => s + gap[t], 0) / TIMES.length).toFixed(2);
+    viewports.push({ viewport: vp.name, score, unstable, noise, gap, ref, clone });
+    console.log(unstable
+      ? `${vp.name}: load unstable (noise ±${noise} between two runs of the ${ref.noise > clone.noise ? 'reference' : 'clone'} itself; not scored; curves ref ${TIMES.map((t) => ref.curve[t]).join('/')} clone ${TIMES.map((t) => clone.curve[t]).join('/')})`
+      : `${vp.name}: load match ${score}% (noise ±${noise}; settled: reference ${ref.settledAt ?? '>4000'}ms, clone ${clone.settledAt ?? '>4000'}ms; curves ref ${TIMES.map((t) => ref.curve[t]).join('/')} clone ${TIMES.map((t) => clone.curve[t]).join('/')})`);
+  }
+} finally {
+  if (!flags.cdp) await browser.close();
+  server?.close();
+}
+await fs.mkdir(path.join(root, 'compare'), { recursive: true });
+const out = path.join(root, 'compare', 'load.json');
+const previous = await fs.readFile(out, 'utf8').then(JSON.parse).catch(() => null);
+const merged = vps.length === VIEWPORTS.length || !previous ? viewports : [...(previous.viewports || []).filter((v) => !viewports.some((n) => n.viewport === v.viewport)), ...viewports];
+await fs.writeFile(out, JSON.stringify({ at: new Date().toISOString(), clone: cloneUrl || server?.url, times: TIMES, network: NETWORK, viewports: merged }, null, 2));
+console.log(`-> ${path.relative(process.cwd(), out)}`);