@trueclone/cli 0.0.0-stage → 0.1.0

package/scripts/seed.mjs

@@ -0,0 +1,68 @@
+// Exact mode: start the clone from the reference mirror instead of an empty folder. The mirror is the rendered page
+// with every script and inline handler removed and its stylesheets and media saved locally, so the seeded clone has
+// the site's own markup, text, styles and media at the right paths. What it lacks is behaviour: write that in
+// clone/script.js (your own code, using the parameters you read from the site), then verify with the usual scores.
+//
+// Template clones are never seeded: their text and media must be placeholders.
+//
+// usage: node scripts/seed.mjs <name> [--force]   (--force overwrites an existing clone/)
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { parseArgs } from './lib.mjs';
+
+const { pos, flags } = parseArgs(process.argv.slice(2));
+const [name] = pos;
+if (!name) {
+  console.error('usage: npm run seed -- <name> [--force]');
+  process.exit(1);
+}
+const root = path.resolve('sites', name);
+const ref = path.join(root, 'reference');
+const meta = JSON.parse(await fs.readFile(path.join(ref, 'meta.json'), 'utf8'));
+if (meta.mode !== 'exact' || !meta.permission) {
+  console.error('seed is for exact mode only (capture with --mode exact --permission "<owner>"); template clones use placeholder content');
+  process.exit(1);
+}
+const mirror = path.join(ref, 'mirror');
+const clone = path.join(root, 'clone');
+const exists = await fs.stat(path.join(clone, 'index.html')).then(() => true, () => false);
+if (exists && !flags.force) {
+  console.error(`${path.relative(process.cwd(), clone)} already has an index.html; add --force to overwrite it`);
+  process.exit(1);
+}
+await fs.mkdir(path.join(clone, 'css'), { recursive: true });
+
+// Assets the mirror points at (../assets/... from the page, ../../assets/... from mirror/css) are copied into
+// clone/assets and the paths rewritten, so clone/ is self-contained.
+const copied = new Set();
+const pull = async (rel) => {
+  const clean = decodeURIComponent(rel.split(/[?#]/)[0]);
+  if (copied.has(clean)) return;
+  copied.add(clean);
+  const from = path.join(ref, 'assets', clean);
+  const to = path.join(clone, 'assets', clean);
+  await fs.mkdir(path.dirname(to), { recursive: true });
+  await fs.copyFile(from, to).catch(() => console.warn(`WARNING missing asset ${clean}`));
+};
+const rewrite = async (text, prefix, replacement) => {
+  const re = new RegExp(prefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + 'assets/([^"\')\\s]+)', 'g');
+  for (const m of text.matchAll(re)) await pull(m[1]);
+  return text.replace(re, (all, rel) => `${replacement}assets/${rel}`);
+};
+
+for (const file of await fs.readdir(path.join(mirror, 'css')).catch(() => [])) {
+  const css = await fs.readFile(path.join(mirror, 'css', file), 'utf8');
+  await fs.writeFile(path.join(clone, 'css', file), await rewrite(css, '../../', '../'));
+}
+let html = await fs.readFile(path.join(mirror, 'index.html'), 'utf8');
+html = await rewrite(html, '../', '');
+// the clone's own behaviour script, loaded once the DOM is parsed
+if (!/<script[^>]+src="script\.js"/.test(html)) html = html.replace(/<\/body>/i, '<script src="script.js" defer></script>\n</body>');
+await fs.writeFile(path.join(clone, 'index.html'), html);
+
+const scriptFile = path.join(clone, 'script.js');
+if (!(await fs.stat(scriptFile).then(() => true, () => false))) {
+  await fs.writeFile(scriptFile, `// ${meta.url} - clone behaviour (your own code). The markup, styles and media come from the mirror.\n// Rebuild every interaction from the reference's parameters; verify with npm run score -- ${name}.\n`);
+}
+console.log(`seeded ${path.relative(process.cwd(), clone)} from the mirror: index.html, ${(await fs.readdir(path.join(clone, 'css'))).length} stylesheet(s), ${copied.size} asset(s)`);
+console.log('next: write clone/script.js (behaviour), then npm run score -- ' + name);

package/scripts/spec.mjs

@@ -0,0 +1,78 @@
+// Measure the live page's layout as a build spec: per section, an element tree with page-relative
+// boxes and the computed styles that matter. Text is recorded as length only, never content.
+// usage: node scripts/spec.mjs <name> [--depth 6] [--hide "<selectors>"] [--cdp] [--clone [url]]
+// --clone measures the rebuild instead (default: sites/<name>/clone/index.html) into compare/<vp>.clone.spec.json
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { VIEWPORTS, parseArgs, openBrowser, newPage, settle } from './lib.mjs';
+
+const { pos, flags } = parseArgs(process.argv.slice(2));
+const [name] = pos;
+if (!name) {
+  console.error('usage: npm run spec -- <name> [--depth 6]');
+  process.exit(1);
+}
+const ref = path.resolve('sites', name, 'reference');
+const meta = JSON.parse(await fs.readFile(path.join(ref, 'meta.json'), 'utf8'));
+const depth = Number(flags.depth || 6);
+const clone = flags.clone ? (typeof flags.clone === 'string' ? flags.clone : pathToFileURL(path.resolve('sites', name, 'clone', 'index.html')).href) : null;
+const hide = clone ? [] : typeof flags.hide === 'string' ? flags.hide.split(',') : meta.hide || [];
+const outDir = clone ? path.resolve('sites', name, 'compare') : ref;
+await fs.mkdir(outDir, { recursive: true });
+
+function specInPage(maxDepth) {
+  const KEEP = ['display', 'position', 'top', 'right', 'bottom', 'left', 'z-index', 'overflow', 'flex-direction', 'justify-content',
+    'align-items', 'flex-wrap', 'gap', 'grid-template-columns', 'grid-template-rows', 'padding', 'margin', 'width', 'height',
+    'max-width', 'min-height', 'font-family', 'font-size', 'line-height', 'font-weight', 'letter-spacing', 'text-transform',
+    'text-align', 'color', 'background-color', 'background-image', 'border', 'border-bottom', 'border-left', 'border-radius',
+    'opacity', 'transform', 'object-fit', 'mix-blend-mode', 'filter'];
+  const DEFAULTS = new Set(['static', 'auto', 'visible', 'normal', 'none', '0px', 'nowrap', 'row', 'stretch', 'start',
+    'rgba(0, 0, 0, 0)', '1', 'fill', '0px none rgb(0, 0, 0)', 'flex-start', 'border-box']);
+  const visible = (el) => {
+    const r = el.getBoundingClientRect();
+    const s = getComputedStyle(el);
+    return r.width > 0 && r.height > 0 && s.display !== 'none' && s.visibility !== 'hidden' && !['SCRIPT', 'STYLE', 'NOSCRIPT'].includes(el.tagName);
+  };
+  const walk = (el, d) => {
+    const r = el.getBoundingClientRect();
+    const s = getComputedStyle(el);
+    const style = {};
+    for (const k of KEEP) {
+      const v = s.getPropertyValue(k);
+      if (v && !DEFAULTS.has(v)) style[k] = v.length > 160 ? v.slice(0, 160) + '…' : v;
+    }
+    const text = [...el.childNodes].filter((n) => n.nodeType === 3).map((n) => n.textContent.trim()).join(' ').trim();
+    const node = {
+      tag: el.tagName.toLowerCase(),
+      cls: [...el.classList].slice(0, 3).join(' ') || undefined,
+      box: [Math.round(r.left), Math.round(r.top + scrollY), Math.round(r.width), Math.round(r.height)],
+      textLen: text.length || undefined,
+      style,
+    };
+    if (el.tagName === 'IMG') node.img = { natural: [el.naturalWidth, el.naturalHeight] };
+    if (el.tagName === 'VIDEO') node.video = true;
+    const kids = [...el.children].filter(visible);
+    if (d < maxDepth && kids.length) node.children = kids.slice(0, 40).map((k) => walk(k, d + 1));
+    else if (kids.length) node.more = kids.length;
+    return node;
+  };
+  let root = document.body;
+  for (let kids = [...root.children].filter(visible); kids.length === 1; kids = [...root.children].filter(visible)) root = kids[0];
+  return [...root.children].filter(visible).map((el) => walk(el, 0));
+}
+
+const browser = await openBrowser(flags.cdp);
+try {
+  for (const vp of VIEWPORTS) {
+    const { context, page } = await newPage(browser, vp);
+    await page.goto(clone || meta.url, { waitUntil: 'load', timeout: 60000 });
+    await settle(page, hide);
+    const tree = await page.evaluate(specInPage, depth);
+    await fs.writeFile(path.join(outDir, `${vp.name}${clone ? '.clone' : ''}.spec.json`), JSON.stringify(tree));
+    console.log(`${vp.name}: ${tree.length} sections -> ${vp.name}.spec.json`);
+    await context.close();
+  }
+} finally {
+  if (!flags.cdp) await browser.close();
+}

package/scripts/states.mjs

@@ -0,0 +1,172 @@
+// Multi-state capture: scroll the live page like a user (animations running), and at every step record
+// a viewport screenshot (+ a masked one for structure scoring) and every element's opacity/transform/clip/
+// position. From that it derives a motion inventory: scroll reveals, parallax, pinned and fixed elements.
+// With --clone it replays the same scroll positions on the rebuild and scores each step.
+//
+// usage: node scripts/states.mjs <name> [--step 0.5] [--viewports desktop,mobile] [--cdp]
+//        node scripts/states.mjs <name> --clone [url] [--structure]
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { VIEWPORTS, parseArgs, openBrowser, newPage, serve, warmUp, waitStill, wheelTo, statesInPage, maskToggle, matchPct, PNG } from './lib.mjs';
+
+const { pos, flags } = parseArgs(process.argv.slice(2));
+const [name] = pos;
+if (!name) {
+  console.error('usage: npm run states -- <name> [--step 0.5] [--viewports desktop] | <name> --clone [url] [--structure]');
+  process.exit(1);
+}
+const root = path.resolve('sites', name);
+const ref = path.join(root, 'reference');
+const meta = JSON.parse(await fs.readFile(path.join(ref, 'meta.json'), 'utf8'));
+const cloneMode = Boolean(flags.clone);
+const structure = Boolean(flags.structure);
+const stepFrac = Number(flags.step || 0.5);
+const wanted = typeof flags.viewports === 'string' ? flags.viewports.split(',') : null;
+const viewports = VIEWPORTS.filter((v) => !wanted || wanted.includes(v.name));
+const outRoot = path.join(cloneMode ? path.join(root, 'compare') : ref, 'states');
+
+const server = cloneMode && typeof flags.clone !== 'string' ? await serve(path.join(root, 'clone')) : null;
+const target = cloneMode ? (typeof flags.clone === 'string' ? flags.clone : server.url) : meta.url;
+const browser = await openBrowser(flags.cdp);
+const report = { name, target, mode: cloneMode ? (structure ? 'clone-structure' : 'clone-visual') : 'reference', at: new Date().toISOString(), viewports: [] };
+
+// Viewports run side by side (one page each): most of a step is waiting for smooth scroll to glide.
+try {
+  report.viewports = await Promise.all(viewports.map(async (vp) => {
+    const dir = path.join(outRoot, vp.name);
+    await fs.rm(dir, { recursive: true, force: true });
+    await fs.mkdir(dir, { recursive: true });
+    const { context, page } = await newPage(browser, vp, { reducedMotion: 'no-preference' });
+    await page.goto(target, { waitUntil: 'load', timeout: 60000 });
+    await page.mouse.move(5, vp.height - 5);
+    const intro = await waitStill(page, { timeout: 15000, interval: 200 }); // let intros/loaders finish first
+    // Before the first scroll: one-shot reveals (Framer Motion whileInView once, IntersectionObserver classes) are
+    // still in their starting state here. The warm-up below fires them for good, so they must be read now.
+    const initial = cloneMode ? null : await page.evaluate(statesInPage);
+    await warmUp(page);
+    await wheelTo(page, 0, vp);
+
+    // Reference: step through the whole page. Clone: replay the reference's exact scroll positions.
+    // Guard: a clone whose page height runs away (e.g. a slider sizing loop) would make every step meaningless
+    const docH = await page.evaluate(() => document.documentElement.scrollHeight);
+    let ys;
+    if (cloneMode) {
+      const refMeta = JSON.parse(await fs.readFile(path.join(ref, 'meta.json'), 'utf8'));
+      const refH = refMeta.viewports?.find((v) => v.viewport === vp.name)?.pageHeight;
+      if (refH && Math.abs(docH - refH) / refH > 0.2) console.warn(`WARNING ${vp.name}: clone page height ${docH}px vs reference ${refH}px after the warm-up scroll - a layout is running away; fix that before reading state scores.`);
+      ys = JSON.parse(await fs.readFile(path.join(ref, 'states', `${vp.name}.json`), 'utf8')).steps.map((s) => s.y);
+    } else {
+      const max = await page.evaluate(() => document.documentElement.scrollHeight - innerHeight);
+      const step = Math.round(vp.height * stepFrac);
+      ys = [];
+      for (let y = 0; y < max; y += step) ys.push(y);
+      ys.push(max);
+    }
+
+    const steps = [];
+    const samples = []; // per step: { path: state }
+    for (const [i, y] of ys.entries()) {
+      const actual = await wheelTo(page, y, vp);
+      const still = await waitStill(page);
+      const file = `${String(i).padStart(2, '0')}`;
+      await page.screenshot({ path: path.join(dir, `${file}.png`) });
+      await maskToggle(page, true);
+      await page.screenshot({ path: path.join(dir, `${file}.mask.png`) });
+      await maskToggle(page, false);
+      if (!cloneMode) samples.push(await page.evaluate(statesInPage));
+      steps.push({ i, y: actual, target: y, settled: still.settled, settleMs: still.ms });
+    }
+    await context.close();
+
+    if (cloneMode) {
+      const sfx = structure ? '.mask' : '';
+      const scored = [];
+      for (const s of steps) {
+        const f = `${String(s.i).padStart(2, '0')}${sfx}.png`;
+        const a = PNG.sync.read(await fs.readFile(path.join(ref, 'states', vp.name, f)));
+        const b = PNG.sync.read(await fs.readFile(path.join(dir, f)));
+        scored.push({ ...s, match: matchPct(a, b).pct });
+      }
+      const avg = +(scored.reduce((n, s) => n + s.match, 0) / scored.length).toFixed(2);
+      return { viewport: vp.name, match: avg, worst: [...scored].sort((a, b) => a.match - b.match).slice(0, 5), steps: scored };
+    } else {
+      const summary = summarize(steps, samples, vp, initial);
+      await fs.writeFile(path.join(outRoot, `${vp.name}.json`), JSON.stringify({ viewport: vp, steps, samples }));
+      await fs.writeFile(path.join(outRoot, `${vp.name}.summary.json`), JSON.stringify(summary, null, 2));
+      return { viewport: vp.name, introMs: intro.ms, steps: steps.length, unsettled: steps.filter((s) => !s.settled).length, ...summary.counts };
+    }
+  }));
+} finally {
+  if (!flags.cdp) await browser.close();
+  server?.close();
+}
+
+await fs.writeFile(path.join(outRoot, cloneMode ? `report${structure ? '.mask' : ''}.json` : 'report.json'), JSON.stringify(report, null, 2));
+if (cloneMode) {
+  console.log(`state match (${report.mode}) - average over scroll steps`);
+  console.table(report.viewports.map((v) => ({ viewport: v.viewport, 'match %': v.match, worst: v.worst.map((s) => `#${s.i} y${s.y} ${s.match}%`).join('  ') })));
+} else {
+  console.table(report.viewports);
+}
+console.log(`States: ${path.relative(process.cwd(), outRoot)}`);
+
+// ---------- Motion inventory ----------
+// Classifies what changes between scroll steps, per element (keyed by DOM path).
+function summarize(steps, samples, vp, initial = {}) {
+  const inView = (st) => st.box[1] < vp.height && st.box[1] + st.box[3] > 0;
+  const paths = new Set(samples.flatMap((s) => Object.keys(s)));
+  const reveals = [], animated = [], parallax = [], pinned = [], fixed = [], revealsOnce = [];
+
+  // One-shot reveals: below the fold at load in a hidden or offset starting state (opacity ~0, a translate, a blur),
+  // and seen visible in view later. The starting state is the recipe the clone has to animate from.
+  const offset = (t) => { const m = /matrix\(([^)]+)\)/.exec(t || ''); if (!m) return 0; const v = m[1].split(',').map(Number); return Math.hypot(v[4], v[5]); };
+  for (const [p, s0] of Object.entries(initial || {})) {
+    if (s0.box[1] < vp.height) continue; // above the fold: part of the intro, not a scroll reveal
+    const hidden = s0.o <= 0.05 || !s0.v || offset(s0.t) >= 8 || /blur/.test(s0.f);
+    if (!hidden) continue;
+    const later = samples.map((s) => s[p]).find((s) => s && inView(s) && s.o > 0.5 && s.v);
+    if (!later || (later.o === s0.o && later.t === s0.t && later.f === s0.f)) continue;
+    revealsOnce.push({ path: p, cls: s0.cls, from: { opacity: s0.o, transform: s0.t || 'none', filter: s0.f || 'none' }, to: { opacity: later.o, transform: later.t || 'none', filter: later.f || 'none' }, box: later.box });
+  }
+  for (const p of paths) {
+    const seq = samples.map((s, i) => (s[p] ? { ...s[p], i, y: steps[i].y } : null));
+    const present = seq.filter(Boolean);
+    if (present.length < 2) continue;
+    const first = present[0];
+    const label = { path: p, cls: first.cls, media: first.media };
+
+    if (present.some((s) => s.pos === 'fixed')) fixed.push({ ...label, box: first.box });
+
+    // Hidden while in view at one step, visible while in view at a later step => scroll reveal.
+    const shownAt = present.find((s) => inView(s) && s.o > 0.05 && s.v);
+    const hiddenBefore = present.find((s) => inView(s) && (s.o <= 0.05 || !s.v) && (!shownAt || s.i < shownAt.i));
+    if (hiddenBefore && shownAt) reveals.push({ ...label, hiddenAtStep: hiddenBefore.i, shownAtStep: shownAt.i, box: shownAt.box });
+
+    // Properties that change between steps.
+    const props = ['o', 't', 'c', 'f'].filter((k) => new Set(present.map((s) => String(s[k]))).size > 1);
+    if (props.length) animated.push({ ...label, props: props.map((k) => ({ o: 'opacity', t: 'transform', c: 'clip-path', f: 'filter' })[k]), steps: present.length });
+
+    // Scroll speed relative to the page: 1 = normal, 0 = pinned, other = parallax.
+    const pairs = [];
+    for (let k = 1; k < present.length; k++) {
+      const a = present[k - 1], b = present[k];
+      const dScroll = b.y - a.y;
+      if (dScroll <= 0 || !inView(a) || !inView(b)) continue;
+      pairs.push(-(b.box[1] - a.box[1]) / dScroll);
+    }
+    if (pairs.length >= 2 && !present.some((s) => s.pos === 'fixed')) {
+      const speed = pairs.reduce((n, v) => n + v, 0) / pairs.length;
+      if (Math.abs(speed) < 0.05) pinned.push({ ...label, steps: pairs.length });
+      else if (Math.abs(speed - 1) > 0.08) parallax.push({ ...label, speed: +speed.toFixed(2) });
+    }
+  }
+  // Keep the list readable: outermost elements first (shorter paths), deduplicate children of listed parents.
+  const prune = (list) => {
+    list.sort((a, b) => a.path.length - b.path.length);
+    const kept = [];
+    for (const item of list) if (!kept.some((k) => item.path.startsWith(k.path + '>'))) kept.push(item);
+    return kept;
+  };
+  const result = { reveals: prune(reveals), revealsOnce: prune(revealsOnce), animated: prune(animated), parallax: prune(parallax), pinned: prune(pinned), fixed: prune(fixed) };
+  return { counts: Object.fromEntries(Object.entries(result).map(([k, v]) => [k, v.length])), ...result };
+}