pixel-perfect-kit 0.1.0

package/harness/capture-build.js

@@ -0,0 +1,323 @@
+// harness/capture-build.js <name> [dom.html] [--qa-toolbar] — build the clone BY CAPTURE.
+//
+// WHY THIS EXISTS (LEARNINGS #19). The gate's chronic blind spot is TECHNIQUE mismatches —
+// a clone that lands the same numbers by a different construction and rasterises
+// differently (#12 #14 #15 #17 #18). Every one of those is self-inflicted by hand-rebuilding.
+// A clone built FROM the captured post-hydration DOM inherits live's doctype, authored
+// line-heights, font-feature-settings, and drawing primitives BY CONSTRUCTION — the whole
+// defect class never exists. Evidence across this repo's targets: the one capture-built
+// clone (github) passed 3136 comparisons with 0 fails and 0 structural deltas in a single
+// pipeline pass; the hand-rebuilt ones burned 3 (hn) and 8 (stripe) human QA rounds on
+// exactly the misses capture eliminates.
+//
+// WHAT IT DOES — from a captured DOM serialization (get it with `pxSendDom(...)`, see
+// tools/RUNBOOK.md "Build by capture") it writes targets/<name>/clone/index.html that
+// renders standalone:
+//   - downloads every linked stylesheet          → clone/assets/css/   (self-hosted)
+//   - downloads every font the CSS references    → clone/assets/fonts/ (self-hosted —
+//     the assets gate verifies their wOF2 magic; cross-origin fonts need CORS anyway)
+//   - rewrites every other css/html asset ref to the ABSOLUTE live URL (byte-identical
+//     bytes from the origin/CDN; nothing redrawn, nothing re-encoded)
+//   - strips <script> (a static clone must not re-hydrate/redirect), script preloads,
+//     the CSP <meta> (it would block the local assets), and <base> (refs are absolutized)
+//   - forces loading="lazy" → "eager" (a lazy image in a hidden container never fires
+//     its viewport check on a static page)
+//   - PRESERVES THE DOCTYPE — or its absence — byte-for-byte. Never "fixes" it: a live
+//     site with no doctype renders in quirks mode, and the capture must too (#18).
+//
+// WHAT STAYS YOURS: JS-driven behavior and generative content (animations, WebGL,
+// carousels) cannot be captured statically — reproduce them separately, and spend human
+// QA rounds there, not on statics the gate proves. The measure→visual→coverage→strict
+// gates run unchanged on a capture-built clone: they still catch a font that failed to
+// self-host, a stripped script that removed a load-bearing class, and environment drift.
+//
+// USAGE
+//   node harness/capture-build.js <name> [domFile] [--qa-toolbar] [--fixes]
+//   ppk capture-build <name> [domFile] [--qa-toolbar] [--fixes]
+// domFile defaults to targets/<name>/dom.html. --qa-toolbar injects the PingHumans
+// toolbar before </head> for human QA rounds (off by default: keep the clone byte-honest).
+// --fixes injects <script src="fixes.js" defer></script> before </body> — the ONE vanilla
+// reproduction script for the `behavior` phase (WORKFLOW.md; method: lovable_dupe_html's
+// CLONE_PLAYBOOK.md §8). It's a flag, not automatic, for the same reason --qa-toolbar is:
+// a capture-built clone defaults to byte-honest (no script tags at all — the whole point of
+// §18/#19 is that a static clone renders identically to a stripped-JS snapshot of live). Only
+// once you've written targets/<name>/clone/fixes.js do you opt in to loading it. Re-running
+// capture-build (e.g. after a live re-capture) is idempotent: it re-adds the tag if missing,
+// never duplicates it, and never touches fixes.js itself (that file is source you maintain by
+// hand, capture-build only wires the <script> tag). Downloads use node's built-in fetch
+// (node >= 18) — no curl, no subprocess.
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const WORK = process.cwd();
+
+// ── url helpers ───────────────────────────────────────────────────────────────
+// A ref we must leave untouched: data:/blob:/about:, fragments, javascript:, mailto:.
+const isOpaqueRef = (ref) => /^(data:|blob:|about:|javascript:|mailto:|tel:|#)/i.test(ref.trim());
+
+// Resolve any URL reference (root-relative, relative, protocol-relative, absolute)
+// against a base absolute URL. Returns null for refs that must not be rewritten.
+function absolutize(ref, baseUrl) {
+  const r = (ref || "").trim();
+  if (!r || isOpaqueRef(r)) return null;
+  try { return new URL(r, baseUrl).href; } catch (e) { return null; }
+}
+
+const sanitizeFile = (s) => (s.replace(/[^a-zA-Z0-9._-]/g, "") || "asset");
+const baseNameOfUrl = (u) => sanitizeFile(path.posix.basename(new URL(u).pathname.split("?")[0]) || "asset");
+
+// file:// origins are first-class: point target.json's url at a saved page (e.g. a
+// SingleFile dump) and assets resolve from disk — also what makes the selftest run
+// offline and inside sandboxes that block sockets.
+async function fetchTo(url, dest) {
+  if (url.startsWith("file://")) { fs.copyFileSync(new URL(url), dest); return; }
+  const r = await fetch(url, { redirect: "follow", signal: AbortSignal.timeout(60_000) });
+  if (!r.ok) throw new Error(`HTTP ${r.status}`);
+  fs.writeFileSync(dest, Buffer.from(await r.arrayBuffer()));
+}
+
+// ── css processing (scan is separate from rewrite: downloads are async, replace
+//    callbacks can't await — so we collect font URLs first, download, THEN rewrite) ──
+const FONT_RE = /\.(woff2?|ttf|otf|eot)([?#]|$)/i;
+const CSS_URL_RE = /url\(\s*(?:"([^"]*)"|'([^']*)'|([^)'"\s][^)]*?))\s*\)/gi;
+
+function scanCssFontUrls(css, cssUrl) {
+  const found = [];
+  for (const m of css.matchAll(CSS_URL_RE)) {
+    const abs = absolutize(m[1] != null ? m[1] : m[2] != null ? m[2] : m[3], cssUrl);
+    if (abs && FONT_RE.test(abs)) found.push(abs);
+  }
+  return found;
+}
+
+// Rewrite one CSS text: fonts → their fontMap entry, everything else → absolute.
+// `cssUrl` is the absolute URL this CSS came from (relative refs resolve against IT).
+function rewriteCss(css, cssUrl, state) {
+  // @import targets are absolutized but NOT recursed into — fonts behind an @import
+  // won't be self-hosted. Loud, never silent: each one is listed in the report.
+  css = css.replace(/@import\s+(?:url\(\s*(?:"([^"]*)"|'([^']*)'|([^)'"\s]+))\s*\)|"([^"]*)"|'([^']*)')/gi, (m, a, b, c, d, e) => {
+    const ref = a || b || c || d || e;
+    const abs = absolutize(ref, cssUrl);
+    if (!abs) return m;
+    state.imports.push(abs);
+    return m.replace(ref, abs);
+  });
+  return css.replace(CSS_URL_RE, (m, dq, sq, bare) => {
+    const abs = absolutize(dq != null ? dq : sq != null ? sq : bare, cssUrl);
+    if (!abs) return m; // data:/blob:/fragment/unparseable — leave byte-identical
+    if (state.fontMap.has(abs)) return `url(${state.fontMap.get(abs)})`;
+    return `url(${abs})`;
+  });
+}
+
+async function downloadFonts(urls, state) {
+  for (const abs of urls) {
+    if (state.fontMap.has(abs)) continue;
+    let file = baseNameOfUrl(abs);
+    // same basename from a different URL → disambiguate, never silently overwrite
+    if ([...state.fontMap.values()].includes(`/assets/fonts/${file}`)) file = `${state.fontMap.size}-${file}`;
+    try {
+      await fetchTo(abs, path.join(state.fontDir, file));
+      state.fontMap.set(abs, `/assets/fonts/${file}`);
+    } catch (e) {
+      state.failures.push(`font ${abs} — ${e.message}`);
+      state.fontMap.set(abs, abs); // keep the absolute URL so the page still tries the CDN
+    }
+  }
+}
+
+// ── html attribute helpers ────────────────────────────────────────────────────
+// Attribute values are HTML-entity-encoded in the source (a multi-query-param URL like
+// Google Fonts' combined css2?family=A&family=B legally authors the "&" as "&amp;" inside
+// an attribute). Passing that raw string straight to `new URL()` parses "&amp;family=B" as
+// a single bogus param named "amp;family" — the server silently drops every family after
+// the first, which is a silent, load-bearing asset loss (LEARNINGS-class miss: a captured
+// clone falls back to a system font while every measured metric quietly drifts). Decode the
+// handful of entities legally found in attribute values before treating them as URLs.
+const decodeAttrEntities = (s) =>
+  s.replace(/&amp;/gi, "&").replace(/&quot;/gi, '"').replace(/&#39;|&apos;/gi, "'").replace(/&lt;/gi, "<").replace(/&gt;/gi, ">");
+const attrValue = (tag, name) => {
+  const m = tag.match(new RegExp(`\\b${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s>]+))`, "i"));
+  const raw = m ? (m[1] != null ? m[1] : m[2] != null ? m[2] : m[3]) : null;
+  return raw != null ? decodeAttrEntities(raw) : null;
+};
+const setAttrValue = (tag, name, value) =>
+  tag.replace(new RegExp(`\\b(${name}\\s*=\\s*)(?:"[^"]*"|'[^']*'|[^\\s>]+)`, "i"), `$1"${value}"`);
+const dropAttr = (tag, name) => tag.replace(new RegExp(`\\s+${name}\\s*=\\s*(?:"[^"]*"|'[^']*'|[^\\s>]+)`, "gi"), "");
+
+async function main() {
+  const args = process.argv.slice(2);
+  const flags = new Set(args.filter((a) => a.startsWith("--")));
+  const [name, domArg] = args.filter((a) => !a.startsWith("--"));
+  if (!name) { console.error("usage: ppk capture-build <name> [domFile] [--qa-toolbar]"); process.exit(2); }
+  if (typeof fetch !== "function") { console.error("capture-build needs node >= 18 (built-in fetch)"); process.exit(1); }
+
+  const dir = path.join(WORK, "targets", name);
+  const targetPath = path.join(dir, "target.json");
+  if (!fs.existsSync(targetPath)) { console.error(`targets/${name}/target.json missing — run: ppk new ${name} <url> [width]`); process.exit(1); }
+  const target = JSON.parse(fs.readFileSync(targetPath, "utf8"));
+  if (!target.url) { console.error(`targets/${name}/target.json has no url`); process.exit(1); }
+
+  const domFile = domArg ? path.resolve(WORK, domArg) : path.join(dir, "dom.html");
+  if (!fs.existsSync(domFile)) {
+    console.error(`captured DOM not found: ${path.relative(WORK, domFile)}
+capture it off the LIVE page first (tools/RUNBOOK.md "Build by capture"):
+  1. inject tools/browser-capture.js as plain source on the live tab
+  2. await pxSendDom('http://localhost:7799/dom.html')   // sink running in targets/${name}/
+     (CSP-blocked POST → pxStash(null, 900, pxDomHtml()) + batched pxRead)`);
+    process.exit(1);
+  }
+  let html = fs.readFileSync(domFile, "utf8");
+  if (!html.trim()) { console.error(`${path.relative(WORK, domFile)} is empty — the capture failed; re-capture.`); process.exit(1); }
+
+  const cloneDir = path.join(dir, "clone");
+  const cssDir = path.join(cloneDir, "assets", "css");
+  const fontDir = path.join(cloneDir, "assets", "fonts");
+  fs.mkdirSync(cssDir, { recursive: true });
+  fs.mkdirSync(fontDir, { recursive: true });
+
+  const state = { fontMap: new Map(), imports: [], failures: [], fontDir };
+
+  // ── the doctype is a pixel-determining property of the whole page (#18) ─────
+  // Preserve exactly what was captured; only REPORT the implied rendering mode.
+  const hasDoctype = /^\s*<!doctype/i.test(html);
+  const mode = hasDoctype ? "standards (CSS1Compat)" : "QUIRKS (BackCompat — live ships no doctype; preserved, do not add one)";
+
+  // ── pass 1: discover + download stylesheets, then fonts, then rewrite CSS ───
+  // cssMap: absolute stylesheet URL → local /assets/css/ path (used to rewrite both
+  // the <link rel=stylesheet> tags and any rel=preload as=style pointing at the same URL).
+  const cssMap = new Map();   // absUrl → local path
+  const cssText = new Map();  // absUrl → { dest, css }
+  let cssIdx = 0;
+  for (const tag of html.match(/<link\b[^>]*>/gi) || []) {
+    const rel = (attrValue(tag, "rel") || "").toLowerCase();
+    if (!/\bstylesheet\b/.test(rel)) continue;
+    const href = attrValue(tag, "href");
+    const abs = href && absolutize(href, target.url);
+    if (!abs || cssMap.has(abs)) continue;
+    const file = `${String(cssIdx++).padStart(2, "0")}-${baseNameOfUrl(abs).replace(/\.css$|$/i, ".css")}`;
+    const dest = path.join(cssDir, file);
+    try {
+      await fetchTo(abs, dest);
+      cssText.set(abs, { dest, css: fs.readFileSync(dest, "utf8") });
+      cssMap.set(abs, `/assets/css/${file}`);
+    } catch (e) {
+      state.failures.push(`stylesheet ${abs} — ${e.message}`);
+    }
+  }
+
+  // fonts referenced by downloaded CSS or inline <style> blocks — collect, then fetch
+  const fontUrls = [];
+  for (const [abs, { css }] of cssText) fontUrls.push(...scanCssFontUrls(css, abs));
+  for (const m of html.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style\s*>/gi)) fontUrls.push(...scanCssFontUrls(m[1], target.url));
+  await downloadFonts(fontUrls, state);
+
+  for (const [abs, { dest, css }] of cssText) fs.writeFileSync(dest, rewriteCss(css, abs, state));
+
+  // ── pass 2: rewrite the HTML ─────────────────────────────────────────────────
+  // scripts: a static clone must never re-hydrate, redirect, or blank itself
+  html = html.replace(/<script\b[^>]*>[\s\S]*?<\/script\s*>/gi, "").replace(/<script\b[^>]*\/>/gi, "");
+  // CSP meta would block the self-hosted assets we just created
+  html = html.replace(/<meta\b[^>]*http-equiv\s*=\s*["']?content-security-policy["']?[^>]*>/gi, "");
+  // <base> would re-relativize everything — we absolutize instead, so it must go
+  const hadBase = /<base\b[^>]*>/i.test(html);
+  html = html.replace(/<base\b[^>]*>/gi, "");
+
+  html = html.replace(/<link\b[^>]*>/gi, (tag) => {
+    const rel = (attrValue(tag, "rel") || "").toLowerCase();
+    const as = (attrValue(tag, "as") || "").toLowerCase();
+    if (/\bmodulepreload\b/.test(rel) || (/\bpreload\b/.test(rel) && as === "script")) return ""; // script preloads: gone with the scripts
+    const href = attrValue(tag, "href");
+    const abs = href && absolutize(href, target.url);
+    if (!abs) return tag;
+    let local = null;
+    if (cssMap.has(abs)) local = cssMap.get(abs);
+    else if (state.fontMap.has(abs) && state.fontMap.get(abs) !== abs) local = state.fontMap.get(abs);
+    let out = setAttrValue(tag, "href", local || abs);
+    // SRI/crossorigin were computed for the ORIGINAL bytes at the original origin —
+    // they'd block the rewritten local copy
+    if (local) out = dropAttr(dropAttr(out, "integrity"), "crossorigin");
+    return out;
+  });
+
+  // src/poster on img/video/iframe/source/etc → absolute (bytes come from the live origin/CDN)
+  html = html.replace(/\b(src|poster)\s*=\s*(?:"([^"]*)"|'([^']*)')/gi, (m, attr, dq, sq) => {
+    const abs = absolutize(dq != null ? dq : sq, target.url);
+    return abs ? `${attr}="${abs}"` : m;
+  });
+  html = html.replace(/\bsrcset\s*=\s*(?:"([^"]*)"|'([^']*)')/gi, (m, dq, sq) => {
+    const val = dq != null ? dq : sq;
+    if (/^data:/i.test(val.trim())) return m;
+    const rewritten = val.split(",").map((entry) => {
+      const t = entry.trim();
+      if (!t) return t;
+      const [u, ...desc] = t.split(/\s+/);
+      const abs = absolutize(u, target.url);
+      return [abs || u, ...desc].join(" ");
+    }).join(", ");
+    return `srcset="${rewritten}"`;
+  });
+  // a lazy image inside a hidden/JS-toggled container never fires its viewport check
+  html = html.replace(/\bloading\s*=\s*(?:"lazy"|'lazy'|lazy\b)/gi, 'loading="eager"');
+
+  // inline <style> blocks get the same treatment as downloaded CSS (base = the page URL)
+  html = html.replace(/(<style\b[^>]*>)([\s\S]*?)(<\/style\s*>)/gi, (m, open, css, close) => open + rewriteCss(css, target.url, state) + close);
+
+  if (flags.has("--qa-toolbar")) html = html.replace(/<\/head>/i, '<script src="https://pinghumans.com/qa-toolbar.js"></script></head>');
+
+  // --fixes: wire the ONE vanilla behavior-reproduction script (never generated here — you
+  // write clone/fixes.js by hand, per-target, following lovable_dupe_html/CLONE_PLAYBOOK.md
+  // §8). Idempotent: skip if a fixes.js tag is already present (re-running capture-build
+  // after a live re-capture must not duplicate it or clobber a hand-edited script tag).
+  let fixesWired = false;
+  if (flags.has("--fixes")) {
+    if (/\bsrc\s*=\s*["']?\.?\/?fixes\.js\b/i.test(html)) { fixesWired = true; }
+    else { html = html.replace(/<\/body>/i, '<script src="fixes.js" defer></script></body>'); fixesWired = true; }
+  }
+
+  fs.writeFileSync(path.join(cloneDir, "index.html"), html);
+  // Scaffold a starter fixes.js ONLY if --fixes was requested and none exists yet — never
+  // overwrite one you've already written (that's the file discovery + measurement feeds).
+  const fixesPath = path.join(cloneDir, "fixes.js");
+  if (flags.has("--fixes") && !fs.existsSync(fixesPath)) {
+    fs.writeFileSync(fixesPath, `// clone/fixes.js — one vanilla IIFE that re-drives this target's JS-driven dynamics.
+// No framework. The HTML/CSS stay byte-exact; this only animates what a static capture
+// can't show. Method: lovable_dupe_html/CLONE_PLAYBOOK.md §8 (ported, not reinvented).
+// Discover behaviors on LIVE first with tools/behavior-capture.js (pxBehaviorDiscover) —
+// that inventory (behaviors-live.json) is your to-do list; each entry here should
+// correspond to one key in it. Guard each behavior in its own try so one bug doesn't
+// blank the rest of the page.
+(function () {
+  "use strict";
+  const ready = (fn) => (document.readyState === "loading" ? document.addEventListener("DOMContentLoaded", fn) : fn());
+  ready(function () {
+    // try { initYourBehaviorHere(); } catch (e) { console.error("fixes.js:", e); }
+  });
+})();
+`);
+  }
+
+  // ── report — loud about everything that is NOT a byte-identical capture ─────
+  console.log(`clone/index.html written — ${html.length} bytes (from ${path.relative(WORK, domFile)})
+  doctype:    ${mode}
+  css:        ${cssMap.size} stylesheet(s) self-hosted → clone/assets/css/
+  fonts:      ${[...state.fontMap.values()].filter((v) => v.startsWith("/assets/")).length} self-hosted → clone/assets/fonts/  (assets gate checks their wOF2 magic)
+  stripped:   <script> tags, script preloads, CSP <meta>${hadBase ? ", <base> (refs absolutized)" : ""}
+  fixes.js:   ${fixesWired ? `wired (<script src="fixes.js" defer> before </body>)` : "not wired — pass --fixes once you have targets/" + name + "/clone/fixes.js (behavior phase)"}`);
+  if (state.imports.length) console.log(`  ⚠ @import: ${state.imports.length} absolutized, NOT recursed — fonts behind them are not self-hosted:\n      ${state.imports.join("\n      ")}`);
+  if (state.failures.length) {
+    console.error(`  ❌ ${state.failures.length} download(s) FAILED — these are pixel-determining; fix before advancing build:\n      ${state.failures.join("\n      ")}`);
+    process.exit(1);
+  }
+  console.log(`
+next: serve + capture the clone (RUNBOOK), then the gates run unchanged:
+  ${process.env.PPK_ENTRY === "1" ? "ppk" : "node harness/workflow.js"} status ${name}
+JS-driven behavior + animated/generative content can't be captured statically — discover +
+measure it on live with tools/behavior-capture.js, reproduce in clone/fixes.js, rebuild with
+--fixes, then capture behaviors-clone.json the same way. See WORKFLOW.md's \`behavior\` phase.`);
+}
+
+if (require.main === module) main().catch((e) => { console.error(`capture-build failed: ${e.message}`); process.exit(1); });
+module.exports = { absolutize, scanCssFontUrls, rewriteCss };

package/harness/doctor-selftest.js

@@ -0,0 +1,58 @@
+// harness/doctor-selftest.js — guards the new-user onboarding surface: `ppk doctor`'s
+// check/report logic and `ppk agent-setup`'s skill install. Offline + socket-free.
+"use strict";
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { checkNode, checkPingHumansToken, report } = require("./doctor.js");
+const { install } = require("./agent-setup.js");
+
+let failed = 0;
+const ok = (cond, msg) => { if (cond) console.log(`  ✓ ${msg}`); else { failed++; console.log(`  ✗ ${msg}`); } };
+
+console.log("doctor-selftest — onboarding preflight + agent skill install");
+
+// ── doctor checks (pure) ──────────────────────────────────────────────────────
+ok(checkNode("22.1.0").ok && checkNode("18.0.0").ok, "node 18/22 pass the version check");
+ok(!checkNode("16.20.0").ok && checkNode("16.20.0").fix.includes("18"), "node 16 fails with an actionable fix");
+ok(checkPingHumansToken(() => "tok_abc").ok, "token resolver returning a token passes");
+const noTok = checkPingHumansToken(() => null);
+ok(!noTok.ok && /cpyany setup/.test(noTok.fix), "missing token fails, fix names `npx cpyany setup`");
+ok(!checkPingHumansToken(() => { throw new Error("boom"); }).ok, "a throwing resolver counts as no token, never crashes doctor");
+
+// report(): exit code reflects REQUIRED failures only; optional misses are warnings
+{
+  const logs = [];
+  const orig = console.log;
+  console.log = (...a) => logs.push(a.join(" "));
+  const codeAllGreen = report([{ name: "x", ok: true, detail: "d", required: true }]);
+  const codeOptionalMiss = report([{ name: "x", ok: true, detail: "d", required: true }, { name: "opt", ok: false, detail: "d", fix: "f", required: false }]);
+  const codeRequiredMiss = report([{ name: "x", ok: false, detail: "d", fix: "f", required: true }]);
+  console.log = orig;
+  ok(codeAllGreen === 0, "all green → exit 0");
+  ok(codeOptionalMiss === 0, "an optional miss is a warning, not a failure");
+  ok(codeRequiredMiss === 1, "a required miss → exit 1");
+  ok(logs.some((l) => /browser automation/i.test(l)), "report always names the browser-agent requirement (undetectable from node)");
+  ok(logs.some((l) => /agent-setup/.test(l)), "the all-green report points at the next step (ppk agent-setup)");
+}
+
+// ── agent-setup install (real files, fake HOME) ───────────────────────────────
+{
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), "ppk-doctor-"));
+  const r1 = install(home, false);
+  const dest = path.join(home, ".claude", "skills", "pixel-perfect-clone", "SKILL.md");
+  const destDitto = path.join(home, ".claude", "skills", "ditto-finish", "SKILL.md");
+  ok(r1.ok && fs.existsSync(dest) && fs.existsSync(destDitto), "installs ALL kit skills (pixel-perfect-clone + ditto-finish) into ~/.claude/skills/");
+  const body = fs.readFileSync(dest, "utf8");
+  ok(/^---\nname: pixel-perfect-clone/.test(body) && /description: .*[Cc]lone/.test(body), "installed skill has the frontmatter Claude Code discovers it by");
+  ok(/ppk doctor/.test(body) && /ppk where/.test(body) && /verdict button/i.test(body), "skill teaches preflight, kit location, and the reviewer contract");
+  const ditto = fs.readFileSync(destDitto, "utf8");
+  ok(/^---\nname: ditto-finish/.test(ditto) && /ppk adopt/.test(ditto) && /--changelog/.test(ditto) && /verdict/i.test(ditto), "ditto-finish skill teaches adopt → tunnel --url → human loop with changelogs + verdicts");
+  const r2 = install(home, false);
+  ok(!r2.ok && /--force/.test(r2.message), "refuses to overwrite an existing install without --force");
+  ok(install(home, true).ok, "--force overwrites");
+  fs.rmSync(home, { recursive: true, force: true });
+}
+
+console.log(failed ? `\n❌ doctor-selftest: ${failed} assertion(s) failed.` : "\n✓ doctor-selftest: all assertions pass.");
+process.exit(failed ? 1 : 0);

package/harness/doctor.js

@@ -0,0 +1,85 @@
+// harness/doctor.js — `ppk doctor`: the one-command preflight for new installs.
+//
+// WHY: the kit's failure surface for a NEWCOMER is spread across four tools that fail at
+// the worst possible moments — wrong node errors on the first fetch, missing cloudflared
+// only at tunnel time (an hour into a run), a missing PingHumans login only at the human
+// phase (hours in). Each failure is self-describing WHEN HIT; doctor moves all of them to
+// minute one, with the fix command per miss. Run it right after install, and have agents
+// run it before starting a clone (LAUNCH-PROMPT / the clone-site skill both say to).
+//
+// USAGE:  ppk doctor      (exit 0 = ready for the full pipeline, 1 = something missing)
+"use strict";
+
+const { spawnSync } = require("child_process");
+
+// Each check: { name, ok, detail, fix?, required } — pure data so the selftest can drive
+// the report logic without real binaries. Exported builders take injectable probes.
+function checkNode(versionString) {
+  const major = parseInt((versionString || "").split(".")[0], 10);
+  return {
+    name: "node >= 18",
+    ok: major >= 18,
+    detail: `found ${versionString}`,
+    fix: "install Node 18+ (https://nodejs.org)",
+    required: true,
+  };
+}
+
+function checkBinary(name, args, why, fix, required) {
+  let ok = false, detail = "not found on PATH";
+  try {
+    const r = spawnSync(name, args, { stdio: "pipe", timeout: 10_000 });
+    if (r.status === 0 || (r.stdout && r.stdout.length) || (r.stderr && r.stderr.length && !r.error)) {
+      ok = !r.error;
+      detail = ok ? String(r.stdout || r.stderr).split("\n")[0].trim().slice(0, 60) : detail;
+    }
+  } catch (e) { /* not found */ }
+  return { name: `${name} (${why})`, ok, detail, fix, required };
+}
+
+function checkPingHumansToken(resolveToken) {
+  let token = null;
+  try { token = resolveToken(); } catch (e) {}
+  return {
+    name: "PingHumans login (marketplace review rounds)",
+    ok: !!token,
+    detail: token ? "token found" : "no token found",
+    fix: "run: npx cpyany setup — OR skip it: LOCAL review mode needs no account (`ppk human <name> file --local`, you review at /__review yourself)",
+    required: false,
+  };
+}
+
+function report(checks) {
+  let failedRequired = 0;
+  for (const c of checks) {
+    const mark = c.ok ? "✓" : c.required ? "❌" : "⚠";
+    console.log(`${mark} ${c.name} — ${c.detail}`);
+    if (!c.ok && c.fix) console.log(`    fix: ${c.fix}`);
+    if (!c.ok && c.required) failedRequired++;
+  }
+  console.log(`
+ℹ your AI agent needs BROWSER AUTOMATION to drive live-site captures (e.g. Claude Code
+  with the Chrome extension / claude-in-chrome MCP) — doctor can't verify that from here;
+  make sure your agent can open and script a browser tab.`);
+  if (failedRequired) {
+    console.log(`\n❌ ${failedRequired} required check(s) failed — fix the lines above, then re-run: ppk doctor`);
+    return 1;
+  }
+  console.log(`\n✓ ready. Teach your agent next (once): ppk agent-setup
+  then just ask it: "Clone https://example.com pixel-perfect."`);
+  return 0;
+}
+
+function main() {
+  const { resolveToken } = require("./human-qa.js");
+  const checks = [
+    checkNode(process.versions.node),
+    checkBinary("cloudflared", ["--version"], "public tunnels — needed for marketplace review, not for local mode", "brew install cloudflared   (or https://developers.cloudflare.com/cloudflared)", false),
+    checkPingHumansToken(resolveToken),
+    checkBinary("ffmpeg", ["-version"], "optional — frame-level video verification", "brew install ffmpeg", false),
+  ];
+  process.exit(report(checks));
+}
+
+if (require.main === module) main();
+module.exports = { checkNode, checkBinary, checkPingHumansToken, report };

package/harness/fixtures/01-backdrop-color.js

@@ -0,0 +1,51 @@
+// fixtures/01-backdrop-color.js — a painted BACKDROP colour (announcement bar /
+// button / badge) is a mark the gate must compare. Found on aloyoga: the blue
+// announcement bar lives on a CONTAINER, not the text leaf, so `background-color`
+// was never captured — a bright-red bar passed a green --visual (the red-bar
+// snapshot was byte-identical to the good one). The fix: capture `bg` = the nearest
+// painted background behind each mark (transparent chain → the white canvas), and
+// compare it in --visual. This fixture fails WITHOUT that comparison.
+const { diffSnapshots } = require("../../tools/pixel-diff.js");
+let bad = 0; const check = (n, c) => { console.log(`${c ? "✓" : "✗"} ${n}`); if (!c) bad++; };
+
+// minimal text target carrying a painted backdrop colour
+const el = (bg) => ({
+  present: true,
+  rect: { x: 15, y: 15, w: 1698, h: 20, top: 15, right: 1713, bottom: 35 },
+  font: { weight: "600", size: 14, color: "rgb(0, 0, 0)" },
+  box: {}, layout: {}, parent: null,
+  text: { x: 522, right: 1205, top: 16, bottom: 35, w: 683, h: 19 },
+  underline: { present: false },
+  bg,
+});
+const snap = (e) => ({ viewport: { width: 1728 }, elements: { announce: e } });
+
+// 1) a wrong backdrop colour (live blue bar vs a red clone bar) must FAIL on `bg`
+{
+  const res = diffSnapshots(snap(el("rgb(113, 198, 235)")), snap(el("rgb(255, 0, 0)")), { visual: true });
+  check("gate catches wrong backdrop colour", !res.ok && res.rows.some((r) => !r.pass && r.prop === "bg"));
+}
+// 2) an identical backdrop must PASS (no false positive)
+{
+  const res = diffSnapshots(snap(el("rgb(113, 198, 235)")), snap(el("rgb(113, 198, 235)")), { visual: true });
+  check("identical backdrop passes", res.ok);
+}
+// 3) transparent-on-both must be SKIPPED (text/icons on the canvas add no noise)
+{
+  const res = diffSnapshots(snap(el("rgba(0, 0, 0, 0)")), snap(el("rgba(0, 0, 0, 0)")), { visual: true });
+  check("transparent backdrop adds no bg row", res.ok && !res.rows.some((r) => r.prop === "bg"));
+}
+// 4) TRANSLUCENT backdrops are out of scope — the gate compares only OPAQUE colours
+// (a translucent layer composites to pixels we can't reconstruct from the string, so
+// comparing it would false-positive a translucent-vs-solid pair that looks identical).
+{
+  const res = diffSnapshots(snap(el("rgba(0, 0, 0, 0.5)")), snap(el("rgb(128,128,128)")), { visual: true });
+  check("translucent-vs-solid adds no bg row (no false positive)", res.ok && !res.rows.some((r) => r.prop === "bg"));
+}
+// 5) whitespace in the colour string must not matter ("rgb(0,0,0)" == "rgb(0, 0, 0)")
+{
+  const res = diffSnapshots(snap(el("rgb(113,198,235)")), snap(el("rgb(113, 198, 235)")), { visual: true });
+  check("colour compare is whitespace-insensitive", res.ok);
+}
+
+process.exit(bad ? 1 : 0);

package/harness/fixtures/02-line-strut.js

@@ -0,0 +1,53 @@
+// fixtures/02-line-strut.js — the line-box CONTAINER's line-height (the strut) positions
+// the glyphs; the leaf's own line-height can match live exactly while the container
+// differs. Found on the HN header (human-flagged after a green --visual): live authored
+// `line-height:12pt` (16px) on the td, the clone left the td `normal` — every measured
+// leaf matched (12 vs 12), the same-machine offset was 0.25px (under tolerance), but
+// `normal` resolves differently across platforms so the text sat visibly lower for the
+// human tester. The fix: capture `font.strut` = the nearest line-box container's
+// line-height and compare it in --visual — `normal` vs a number is a technique mismatch
+// that fails loudly regardless of the sub-pixel same-machine delta. LEARNINGS #17.
+const { diffSnapshots } = require("../../tools/pixel-diff.js");
+let bad = 0; const check = (n, c) => { console.log(`${c ? "✓" : "✗"} ${n}`); if (!c) bad++; };
+
+// minimal text target: leaf line-height matches (12 vs 12); only the strut varies
+const el = (strut) => ({
+  present: true,
+  rect: { x: 30, y: 10, w: 300, h: 20, top: 10, right: 330, bottom: 30 },
+  font: { weight: "700", size: 13.33, line: 12, spacing: "normal", transform: "none",
+    color: "rgb(0, 0, 0)", decoration: "none", smoothing: "auto",
+    ...(strut === undefined ? {} : { strut }) },
+  box: {}, layout: {}, parent: null,
+  text: { x: 30, right: 330, top: 11.5, bottom: 28, w: 300, h: 16.5 },
+  underline: { present: false },
+  bg: "rgb(255, 102, 0)",
+});
+const snap = (e) => ({ viewport: { width: 1512 }, elements: { title: e } });
+
+// 1) authored strut (16px) vs `normal` must FAIL on font.strut — the exact HN defect
+{
+  const res = diffSnapshots(snap(el(16)), snap(el("normal")), { visual: true });
+  check("gate catches strut mismatch (16 vs normal) even when the leaf line matches", !res.ok && res.rows.some((r) => !r.pass && r.prop === "font.strut"));
+}
+// 2) two different NUMBERS over tolerance must fail too (16 vs 18)
+{
+  const res = diffSnapshots(snap(el(16)), snap(el(18)), { visual: true });
+  check("gate catches numeric strut delta (16 vs 18)", !res.ok && res.rows.some((r) => !r.pass && r.prop === "font.strut"));
+}
+// 3) identical struts pass (no false positive)
+{
+  const res = diffSnapshots(snap(el(16)), snap(el(16)), { visual: true });
+  check("identical strut passes", res.ok);
+}
+// 4) both `normal` passes — same technique on both sides is a match
+{
+  const res = diffSnapshots(snap(el("normal")), snap(el("normal")), { visual: true });
+  check("normal-vs-normal passes (same technique)", res.ok);
+}
+// 5) schema back-compat: a capture that predates strut (undefined) must add NO strut row
+{
+  const res = diffSnapshots(snap(el(undefined)), snap(el(16)), { visual: true });
+  check("old-schema snapshot adds no strut row (no mixed-capture false positive)", res.ok && !res.rows.some((r) => r.prop === "font.strut"));
+}
+
+process.exit(bad ? 1 : 0);

package/harness/fixtures/03-compat-mode.js

@@ -0,0 +1,44 @@
+// fixtures/03-compat-mode.js — the rendering MODE is a pixel-determining property of the
+// whole page. Found on the HN header (human-flagged, round 3): live HN ships NO doctype →
+// quirks mode ("BackCompat"); the clone's `<!doctype html>` → standards mode. Quirks
+// computes table-cell line boxes differently, so the login line sat 0.25px lower with
+// EVERY computed style byte-identical — no element-level property could ever catch it.
+// The fix: capture `mode` (document.compatMode) in the snapshot root and fail loudly on a
+// mismatch. LEARNINGS #18.
+const { diffSnapshots } = require("../../tools/pixel-diff.js");
+let bad = 0; const check = (n, c) => { console.log(`${c ? "✓" : "✗"} ${n}`); if (!c) bad++; };
+
+const el = () => ({
+  present: true,
+  rect: { x: 30, y: 10, w: 300, h: 20, top: 10, right: 330, bottom: 30 },
+  font: { weight: "400", size: 13.33, line: 12, spacing: "normal", transform: "none",
+    color: "rgb(0, 0, 0)", decoration: "none", smoothing: "auto", strut: 16 },
+  box: {}, layout: {}, parent: null,
+  text: { x: 30, right: 330, top: 11.5, bottom: 28, w: 300, h: 16.5 },
+  underline: { present: false },
+  bg: "rgb(255, 102, 0)",
+});
+const snap = (mode) => ({ viewport: { width: 1512 }, ...(mode ? { mode } : {}), elements: { title: el() } });
+
+// 1) quirks vs standards must FAIL on page.mode — the exact HN defect
+{
+  const res = diffSnapshots(snap("BackCompat"), snap("CSS1Compat"), { visual: true });
+  check("gate catches quirks-vs-standards mode mismatch", !res.ok && res.rows.some((r) => !r.pass && r.target === "page" && r.prop === "mode"));
+}
+// 2) same mode on both sides passes
+{
+  const res = diffSnapshots(snap("BackCompat"), snap("BackCompat"), { visual: true });
+  check("same mode passes", res.ok);
+}
+// 3) schema back-compat: a capture that predates `mode` adds NO row (no false positive)
+{
+  const res = diffSnapshots(snap(null), snap("BackCompat"), { visual: true });
+  check("old-schema snapshot adds no mode row", res.ok && !res.rows.some((r) => r.prop === "mode"));
+}
+// 4) strict mode fails on it too (it's a defect in both modes of the diff)
+{
+  const res = diffSnapshots(snap("BackCompat"), snap("CSS1Compat"), {});
+  check("strict also fails on mode mismatch", !res.ok && res.rows.some((r) => !r.pass && r.prop === "mode"));
+}
+
+process.exit(bad ? 1 : 0);