pixel-perfect-kit 0.1.0

package/tools/reassemble.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/**
+ * reassemble.js — join pxRead() chunks into a validated snapshot file.
+ *
+ * Hand-concatenating pxStash/pxRead chunks is the single most error-prone step in the
+ * capture loop: a dropped character at a chunk boundary produced a silently-corrupt
+ * live.json that only surfaced rounds later as unexplainable diffs (found during the
+ * HN dogfood run). This makes reassembly a verified operation instead:
+ *   1. joins the chunk files IN THE ORDER GIVEN,
+ *   2. checks the total byte count against pxStash's reported `bytes` (pass --bytes),
+ *   3. JSON-parses the result and requires the snapshot shape (.elements),
+ * and only then writes the output. Any failure names the exact problem and exits 2.
+ *
+ * usage: node tools/reassemble.js <out.json> [--bytes N] <chunk-file> [<chunk-file>…]
+ *   Save each pxRead(i) result to its own file (chunk-00.txt, chunk-01.txt, …), then:
+ *   node tools/reassemble.js targets/hn/live.json --bytes 18342 chunk-*.txt
+ *   (shell glob order is lexicographic — zero-pad chunk indexes so it matches read order.)
+ */
+"use strict";
+const fs = require("fs");
+
+const argv = process.argv.slice(2);
+const files = [];
+let out = null, bytes = null, bytesRaw;
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a === "--bytes") { bytesRaw = argv[++i]; bytes = parseInt(bytesRaw, 10); }
+  else if (a.startsWith("--")) { console.error(`unknown flag "${a}". valid: --bytes <n>`); process.exit(2); }
+  else if (out === null) out = a;
+  else files.push(a);
+}
+if (!out || !files.length) {
+  console.error("usage: node tools/reassemble.js <out.json> [--bytes N] <chunk-file> [<chunk-file>…]\n  --bytes  the `bytes` value pxStash() reported — verifies nothing was lost in transit");
+  process.exit(2);
+}
+if (bytesRaw !== undefined && !(Number.isInteger(bytes) && bytes > 0)) {
+  console.error(`--bytes needs a positive integer (got "${bytesRaw}").`);
+  process.exit(2);
+}
+
+let joined = "";
+for (const f of files) {
+  if (!fs.existsSync(f)) { console.error(`chunk file ${f} not found — save each pxRead(i) result to its own file first.`); process.exit(2); }
+  joined += fs.readFileSync(f, "utf8");
+}
+
+if (bytes !== null && joined.length !== bytes) {
+  console.error(`byte count mismatch: pxStash reported ${bytes}, chunks join to ${joined.length} (${joined.length < bytes ? "missing" : "extra"} ${Math.abs(joined.length - bytes)} bytes).\n  A chunk was dropped, duplicated, or truncated — re-run the pxRead(i) that looks short and check the file order (zero-pad indexes so glob order matches).`);
+  process.exit(2);
+}
+
+let snap;
+try { snap = JSON.parse(joined); } catch (e) {
+  console.error(`joined chunks are not valid JSON: ${e.message}\n  A chunk boundary is corrupt — re-read the chunk around the reported position; do not hand-edit the JSON.`);
+  process.exit(2);
+}
+if (!snap || !snap.elements) {
+  console.error(`joined JSON has no "elements" — this isn't a pxCapture() snapshot (a pxInspect() dump is fine to save directly, no reassembly needed).`);
+  process.exit(2);
+}
+
+fs.writeFileSync(out, joined);
+console.log(`✓ ${out} written — ${joined.length} bytes, ${Object.keys(snap.elements).length} elements, JSON valid${bytes !== null ? ", byte count matches pxStash" : ""}.`);

package/tools/selftest.js

@@ -0,0 +1,67 @@
+// selftest.js — guards the DIFF ENGINE itself (run: node tools/selftest.js)
+//
+// The kit's whole promise is "a green --visual means it looks identical." That promise
+// is only as good as the properties the diff actually compares. Two classes of miss
+// (an underline measured as a boolean; -webkit-font-smoothing not measured) each cost
+// several human rounds before they were added to the gate (LEARNINGS #12, #13). This
+// file locks those in: it feeds diffSnapshots synthetic snapshots and asserts that
+//   (a) an identical pair PASSES, and
+//   (b) the exact defects that used to slip a green sweep now FAIL, on the named props.
+// If someone later refactors pixel-diff.js and drops one of these comparisons, this
+// test goes red — the guarantee can't silently regress. Zero deps.
+
+const { diffSnapshots } = require("./pixel-diff.js");
+
+let failures = 0;
+const check = (name, cond) => { console.log(`${cond ? "✓" : "✗"} ${name}`); if (!cond) failures++; };
+
+// A minimal text target (the "sign in" label) with the marks the gate must compare.
+const signin = (over = {}) => ({
+  present: true,
+  rect: { x: 1395, y: 81, w: 186, h: 17, top: 81, right: 1581, bottom: 98, fromRight: 147 },
+  font: {
+    family: "proxima-nova", weight: "600", size: 14, line: 18.2, spacing: 0.7,
+    transform: "uppercase", color: "rgb(0, 0, 0)", decoration: "none",
+    smoothing: "antialiased", underline: true,
+    ...(over.font || {}),
+  },
+  box: {}, layout: {}, parent: { display: "flex", gap: 8 },
+  text: { x: 1395, right: 1581, top: 81, bottom: 98, w: 186, h: 17 },
+  // the underline as a BOX (drawn by an ancestor border-bottom), not a boolean:
+  underline: { present: true, thickness: 2, x: 1369, right: 1581, w: 212, top: 100, bottom: 102,
+    ...(over.underline || {}) },
+});
+
+const snap = (el) => ({ viewport: { width: 1728 }, elements: { signin: el } });
+const failedProps = (res) => res.rows.filter((r) => !r.pass).map((r) => r.prop);
+
+// 1) identical → --visual PASSES
+{
+  const res = diffSnapshots(snap(signin()), snap(signin()), { visual: true });
+  check("identical pair passes --visual", res.ok);
+}
+
+// 2) the ORIGINAL defects (LEARNINGS #12/#13) → --visual FAILS on the named props
+{
+  const bad = signin({
+    font: { smoothing: "auto" },                                   // #13 perceived weight
+    underline: { thickness: 1, x: 1395, w: 186, top: 98, bottom: 99 }, // #12 thin / text-only / wrong Y
+  });
+  const res = diffSnapshots(snap(signin()), snap(bad), { visual: true });
+  const props = failedProps(res);
+  check("smoothing regression fails", !res.ok && props.includes("font.smoothing"));
+  check("underline thickness fails", props.includes("underline.thickness"));
+  check("underline width fails", props.includes("underline.w"));
+  check("underline x-offset fails", props.includes("underline.x"));
+  check("underline vertical fails", props.includes("underline.top") || props.includes("underline.bottom"));
+}
+
+// 3) a present underline on one side only is caught (not silently skipped)
+{
+  const noUnderline = signin({ font: { underline: false }, underline: { present: false } });
+  const res = diffSnapshots(snap(signin()), snap(noUnderline), { visual: true });
+  check("missing underline is caught", !res.ok && failedProps(res).includes("underline.present"));
+}
+
+console.log(failures ? `\n❌ selftest: ${failures} check(s) failed — the diff gate has a hole.` : "\n✓ selftest: the gate compares underline-box + smoothing as required.");
+process.exit(failures ? 1 : 0);

package/tools/sink.js

@@ -0,0 +1,80 @@
+// sink.js — a small receiver for snapshots (run: node tools/sink.js, or `ppk sink`)
+//
+// The clone (same-origin localhost, no strict CSP) can POST its capture straight
+// to a file with one call — `pxSend("http://localhost:7799/clone.json")` — instead
+// of the stash/read dance the live CSP site needs. This is that receiver: it writes
+// the POST body to ./<name> where <name> comes from the URL path.
+//
+//   ppk sink
+//   // in the clone page console / automation:
+//   await pxSend("http://localhost:7799/clone.json")        // full snapshot
+//   await pxSend("http://localhost:7799/el_clone.json", null) // (or stash an inspect dump)
+const http = require("http"), fs = require("fs");
+
+// A snapshot is KBs; anything near this is a mistake, not a capture. Env-overridable so the
+// mid-stream abort below is testable with a small limit (PPK_SINK_MAX_BYTES) and the port
+// doesn't collide in tests (PPK_SINK_PORT).
+const MAX_BYTES = +(process.env.PPK_SINK_MAX_BYTES || 20 * 1024 * 1024);
+const PORT = +(process.env.PPK_SINK_PORT || 7799);
+
+// Decide what to do with a received body BEFORE writing it, so we never silently persist
+// garbage (an empty POST, a "[BLOCKED…]" automation sentinel, or non-JSON under a .json name).
+// Pure + exported so it's unit-tested without opening a socket. Returns { status, write, message }.
+function classifyBody(name, body) {
+  if (!body || !body.trim()) return { status: 400, write: false, message: `empty body for ${name} — capture returned nothing (the finder/injection likely failed).` };
+  if (body.length > MAX_BYTES) return { status: 413, write: false, message: `body for ${name} is ${body.length} bytes (> ${MAX_BYTES}) — that's not a snapshot; refusing.` };
+  if (/^\s*\[BLOCKED/.test(body)) return { status: 422, write: false, message: `body for ${name} is a "[BLOCKED…]" automation sentinel, not a snapshot — the return was blocked; use the stash/read path (RUNBOOK).` };
+  if (/\.json$/i.test(name)) { try { JSON.parse(body); } catch (e) { return { status: 200, write: true, message: `⚠ wrote ${name} but it is NOT valid JSON (${e.message}) — pixel-diff will reject it; re-capture.` }; } }
+  return { status: 200, write: true, message: `ok ${name}` };
+}
+
+// A query string is transport noise, not part of the filename — strip it BEFORE sanitizing,
+// or `/clone.json?t=1` would fuse into `clone.jsont1` and the artifact lands under the wrong
+// name while the caller sees "ok".
+function sanitizeName(url) {
+  const raw = url.split("?")[0].replace(/^\//, "");
+  const clean = raw.replace(/[^a-z0-9._-]/gi, "") || "snap.json";
+  return { clean, renamed: clean !== raw };
+}
+
+if (require.main === module) {
+  http
+    .createServer((q, s) => {
+      s.setHeader("Access-Control-Allow-Origin", "*");
+      if (q.method === "OPTIONS") { s.end(); return; }
+      const { clean: name, renamed } = sanitizeName(q.url);
+      if (renamed) console.warn(`⚠ POST path "${q.url}" sanitized to ./${name} (only a-z0-9._- kept — sub-paths are flattened).`);
+      let body = "", aborted = false;
+      // Enforce the size bound DURING streaming — checking only at `end` would accumulate an
+      // unbounded body in memory first (a runaway stream could OOM the process).
+      q.on("data", (d) => {
+        if (aborted) return;
+        body += d;
+        if (body.length > MAX_BYTES) {
+          aborted = true;
+          const msg = `body for ${name} exceeded ${MAX_BYTES} bytes — aborted mid-stream; that's not a snapshot.`;
+          console.log(msg);
+          s.writeHead(413);
+          s.end(msg);
+          q.destroy();
+          body = "";
+        }
+      });
+      q.on("end", () => {
+        if (aborted) return;
+        const r = classifyBody(name, body);
+        if (r.write) fs.writeFileSync(name, body);
+        console.log(r.message);
+        s.writeHead(r.status);
+        s.end(r.message);
+      });
+    })
+    .on("error", (e) => {
+      // self-describing, actionable — never a raw stack for a predictable failure
+      if (e.code === "EADDRINUSE") { console.error(`port ${PORT} is already in use (another sink running?) — stop it, or set PPK_SINK_PORT=<n>`); process.exit(1); }
+      console.error(`sink failed: ${e.message}`);
+      process.exit(1);
+    })
+    .listen(PORT, () => console.log(`sink on http://localhost:${PORT}  (POST /<name>.json → ./<name>.json)`));
+}
+module.exports = { classifyBody, sanitizeName, MAX_BYTES };