pixel-perfect-kit 0.1.0

package/tools/behavior-capture.js

@@ -0,0 +1,307 @@
+// behavior-capture.js — the BROWSER half of the `behavior` phase, extracted verbatim (same
+// reason as browser-capture.js: inject as PLAIN SOURCE on a strict-CSP live site — never
+// base64/gzip/fetch+eval, see tools/RUNBOOK.md). Discovers and MEASURES JS-driven dynamics
+// (animations, rotations, reveals, marquees, counters, hover-mounted content) so the
+// `behavior` phase gate can compare live vs clone by NUMBER, never by eyeballing a replay.
+//
+// METHOD (ported from lovable_dupe_html/CLONE_PLAYBOOK.md §8a — port, don't reinvent):
+//   static pass    — grep candidates: @keyframes names in <style>/stylesheets, and DOM
+//                     markers (class/style hints for opacity-0, translate, blur, will-change,
+//                     animate-*, data-state, data-[starting-style]). Necessary but noisy —
+//                     every hit is a CANDIDATE, not a confirmed behavior.
+//   dynamic pass   — the authoritative one: attach a MutationObserver (class/style/data-*)
+//                     across the region, snapshot computed opacity/transform/filter PER
+//                     ELEMENT before and after a scripted scroll sweep + hover of each
+//                     candidate trigger, and diff. Whatever actually changed is a real
+//                     behavior; whatever stayed frozen in its start state is presentational
+//                     noise (a candidate that never fires isn't a behavior to reproduce).
+//   measure, don't eyeball — a marquee's speed is sampled translateX over a real time
+//                     window and converted to px/sec; a reveal's duration is the wall-clock
+//                     time between trigger and the computed style settling; there is no
+//                     "looks about right" path through this file.
+//
+// The discovery pass's OWN metadata (scroll range, observer duration, elements scanned) is
+// recorded in the output — this is what proves discovery ACTUALLY RAN on a page with zero
+// live behaviors, vs. a script that silently no-oped (WORKFLOW.md: "no dynamic behaviors
+// discovered" must be an evidenced gate result, never a free pass).
+(function (root) {
+  "use strict";
+  const num = (v) => { const n = parseFloat(v); return isNaN(n) ? v : Math.round(n * 1000) / 1000; };
+  const now = () => (root.performance ? root.performance.now() : Date.now());
+
+  root.pxRegion = root.pxRegion || { maxY: 200 };
+  const inRegion = (el) => {
+    const reg = root.pxRegion || {};
+    if (reg.sel && !el.closest(reg.sel)) return false;
+    const r = el.getBoundingClientRect();
+    if (reg.maxY != null && r.top > reg.maxY + (reg.maxYSlack || 4000)) return false; // generous: behaviors can occur below the fold (scroll reveals)
+    if (reg.minY != null && r.bottom < reg.minY) return false;
+    return true; // unlike browser-capture's inRegion, width===0 is still a candidate (opacity:0 start state has zero box until revealed)
+  };
+
+  // ── static pass: candidate discovery (necessary, noisy) ─────────────────────
+  // Grep every reachable stylesheet's cssText for @keyframes names — same-origin sheets only;
+  // a cross-origin sheet throws on .cssRules (SecurityError), which we swallow (can't read it
+  // from script anyway; its keyframes still fire and get caught by the dynamic pass).
+  function keyframeNames() {
+    const names = new Set();
+    for (const sheet of Array.from(document.styleSheets)) {
+      let rules;
+      try { rules = sheet.cssRules; } catch (e) { continue; }
+      if (!rules) continue;
+      for (const rule of Array.from(rules)) {
+        if (rule.type === CSSRule.KEYFRAMES_RULE) names.add(rule.name);
+      }
+    }
+    return names;
+  }
+  const MARKER_RE = /(^|[\s"'`])(opacity-0|translate-[xy]-|blur-|will-change|animate-|data-\[starting-style\]|data-state)/;
+  // Attributes whose NAME declares animation intent (site-authored choreography markers —
+  // apple ships data-anim-scroll-group / data-video-load-kf etc.; generic data-scroll-* and
+  // data-animate-* cover the common libraries).
+  const DECLARED_ATTR_RE = /^data-(anim|animate|scroll|video-load|autoplay|parallax|reveal|carousel|gallery|progress)/i;
+  function declaredHints(el, cs) {
+    const hints = [];
+    if (cs.animationName && cs.animationName !== "none") hints.push("animation-name:" + cs.animationName);
+    if (el.className && typeof el.className === "string" && MARKER_RE.test(el.className)) hints.push("class-marker");
+    if (el.hasAttribute("data-state") || el.hasAttribute("data-starting-style")) hints.push("data-state");
+    if (cs.willChange && cs.willChange !== "auto") hints.push("will-change:" + cs.willChange);
+    for (const a of el.attributes) if (DECLARED_ATTR_RE.test(a.name)) hints.push("attr:" + a.name);
+    // a transition paired with a hidden/offset start state = a reveal waiting for a trigger
+    if (cs.transitionDuration && cs.transitionDuration !== "0s" && (parseFloat(cs.opacity) === 0 || (cs.transform && cs.transform !== "none"))) hints.push("transition-from-start-state");
+    if (el.tagName === "VIDEO") hints.push(`video:${el.autoplay ? "autoplay" : "scripted"}:${el.preload || "auto"}`);
+    return hints;
+  }
+  function staticCandidates(root_) {
+    const kf = keyframeNames();
+    const out = [];
+    const all = root_.querySelectorAll("*");
+    for (const el of all) {
+      if (!inRegion(el)) continue;
+      const cs = getComputedStyle(el);
+      const hints = declaredHints(el, cs);
+      if (hints.length) out.push({ el, hints });
+    }
+    return { keyframes: [...kf], candidates: out };
+  }
+
+  // ── dynamic differential pass (authoritative) ────────────────────────────────
+  // Per-element snapshot: opacity/transform/filter, the three properties JS-driven reveals
+  // and rotations actually touch (per the playbook). Cheap enough to run on every candidate
+  // plus a bounded scan of the region without a real perf hit.
+  function styleSnap(el) {
+    const cs = getComputedStyle(el);
+    return { opacity: num(cs.opacity), transform: cs.transform === "none" ? "none" : cs.transform, filter: cs.filter === "none" ? "none" : cs.filter };
+  }
+  const styleSnapEq = (a, b) => a.opacity === b.opacity && a.transform === b.transform && a.filter === b.filter;
+
+  // Sample an element's transform translation over a wall-clock window → px/sec on the
+  // DOMINANT axis (a logo belt is usually horizontal, a ticker/credits roll is vertical —
+  // sampling only X would read a vertical marquee as 0 and "pass" a frozen one). Playbook §8:
+  // "measure the real speed — sample the transform over 1s → px/sec"; never eyeball.
+  function sampleTranslateSpeed(el, ms) {
+    return new Promise((resolve) => {
+      const read = () => {
+        const m = /matrix(3d)?\(([^)]+)\)/.exec(getComputedStyle(el).transform);
+        if (!m) return { x: 0, y: 0 };
+        const p = m[2].split(",").map((s) => parseFloat(s.trim()));
+        return m[1] ? { x: p[12], y: p[13] } : { x: p[4], y: p[5] }; // matrix3d tx/ty at 12/13; matrix at 4/5
+      };
+      const t0 = now(), s0 = read();
+      setTimeout(() => {
+        const t1 = now(), s1 = read();
+        const dtSec = (t1 - t0) / 1000;
+        const dx = Math.abs(s1.x - s0.x), dy = Math.abs(s1.y - s0.y);
+        const axis = dx >= dy ? "x" : "y";
+        const dist = Math.max(dx, dy);
+        resolve({ pxPerSec: dtSec > 0 ? num(dist / dtSec) : 0, axis, from: num(axis === "x" ? s0.x : s0.y), to: num(axis === "x" ? s1.x : s1.y), sampledMs: num(t1 - t0) });
+      }, ms);
+    });
+  }
+
+  // Wait for a MutationObserver to go quiet for `quietMs`, capped at `maxMs`. Used to let a
+  // one-shot reveal settle before snapshotting its end state (never a fixed guess-sleep).
+  function waitQuiet(target, quietMs, maxMs) {
+    return new Promise((resolve) => {
+      let timer, done = false;
+      const finish = () => { if (done) return; done = true; try { mo.disconnect(); } catch (e) {} resolve(); };
+      const mo = new MutationObserver(() => { clearTimeout(timer); timer = setTimeout(finish, quietMs); });
+      mo.observe(target, { attributes: true, attributeFilter: ["class", "style"], subtree: true, attributeOldValue: false });
+      timer = setTimeout(finish, quietMs);
+      setTimeout(finish, maxMs); // hard cap — a page that mutates forever must not hang discovery
+    });
+  }
+
+  // Scripted scroll sweep in increments, dwelling briefly at each stop so scroll-linked /
+  // IntersectionObserver-triggered reveals get a chance to fire (playbook §8a).
+  async function scrollSweep(steps, dwellMs) {
+    const max = Math.max(0, (document.scrollingElement || document.documentElement).scrollHeight - window.innerHeight);
+    const positions = [];
+    for (let i = 0; i <= steps; i++) {
+      const y = Math.round((max * i) / steps);
+      window.scrollTo(0, y);
+      positions.push(y);
+      await new Promise((r) => setTimeout(r, dwellMs));
+    }
+    window.scrollTo(0, 0);
+    await new Promise((r) => setTimeout(r, dwellMs));
+    return { from: 0, to: max, steps, positions };
+  }
+
+  // Dispatch a synthetic hover on `el` (pointerover/enter + mouseover/enter — physical hover
+  // doesn't persist across separate automation calls, playbook §9), wait for it to settle,
+  // return the snapshot delta on `scope` (the element or a documented ancestor scope).
+  async function probeHover(el, scope, settleMs) {
+    // A hover that MOUNTS content (a mega-menu portal) changes the scope's CHILDREN, not the
+    // scope's own opacity/transform — snapshotting only the scope's style would read a mounted
+    // menu as "nothing changed". Count descendants too; either delta counts as a real change.
+    const snapScope = (s) => Object.assign(styleSnap(s), { descendants: s.querySelectorAll("*").length });
+    const before = snapScope(scope);
+    for (const type of ["pointerover", "pointerenter", "mouseover", "mouseenter"])
+      el.dispatchEvent(new MouseEvent(type, { bubbles: true, cancelable: true }));
+    await waitQuiet(scope, 150, settleMs);
+    const after = snapScope(scope);
+    // reset — move focus away so a later probe doesn't inherit an open state
+    for (const type of ["pointerout", "pointerleave", "mouseout", "mouseleave"])
+      el.dispatchEvent(new MouseEvent(type, { bubbles: true, cancelable: true }));
+    await new Promise((r) => setTimeout(r, 60));
+    return { before, after, changed: !styleSnapEq(before, after) || before.descendants !== after.descendants };
+  }
+
+  // A stable key for a behavior: prefer an explicit id/data-testid/aria-label, else a
+  // class-based descriptor, else a structural path. Stability across live/clone captures
+  // matters more than prettiness — the gate keys off exact string match.
+  function keyOf(el, prefix) {
+    const id = el.id || el.getAttribute("data-testid") || el.getAttribute("aria-label");
+    if (id) return `${prefix}:${id}`;
+    const cls = (typeof el.className === "string" ? el.className : "").trim().split(/\s+/).filter(Boolean).slice(0, 2).join(".");
+    if (cls) return `${prefix}:${el.tagName.toLowerCase()}.${cls}`;
+    let path = el.tagName.toLowerCase(), e = el, hops = 0;
+    while (e.parentElement && hops < 3) { const i = [...e.parentElement.children].indexOf(e); path = `${e.parentElement.tagName.toLowerCase()}>${path}[${i}]`; e = e.parentElement; hops++; }
+    return `${prefix}:${path}`;
+  }
+
+  // ── the discovery + measurement pass ─────────────────────────────────────────
+  // opts: { scrollSteps=6, dwellMs=250, hoverTriggers=[[name, findFn]], marqueeSelectors=[…],
+  //         settleMs=1500 }
+  async function discover(opts) {
+    const o = Object.assign({ scrollSteps: 6, dwellMs: 250, hoverTriggers: [], marqueeSelectors: [], settleMs: 1500 }, opts || {});
+    const startedAt = new Date().toISOString();
+    const t0 = now();
+    const scanRoot = document.body;
+
+    const { keyframes, candidates } = staticCandidates(scanRoot);
+    const before = new Map(candidates.map((c) => [c.el, styleSnap(c.el)]));
+
+    // dynamic pass: MutationObserver across the whole region while we sweep+dwell
+    const mutated = new Set();
+    const mo = new MutationObserver((records) => { for (const r of records) if (r.target && r.target.nodeType === 1) mutated.add(r.target); });
+    mo.observe(scanRoot, { attributes: true, attributeFilter: ["class", "style"], subtree: true, attributeOldValue: false, childList: true });
+
+    const sweep = await scrollSweep(o.scrollSteps, o.dwellMs);
+    await waitQuiet(scanRoot, 200, o.settleMs);
+    mo.disconnect();
+
+    const behaviors = {};
+
+    // reconcile: candidate whose computed style moved from its captured start state is a
+    // confirmed one-shot/scroll-linked behavior. A candidate that NEVER moved is NOT
+    // discarded (the pre-iphone17 rule): its markers still DECLARE intent, and in an
+    // environment-inverted run (a site that gates its choreography behind no-js/bot
+    // detection) nothing fires while everything is still supposed to. Unfired candidates
+    // become the `declared` inventory — each gets an identity BEFORE any reproduction is
+    // engineered, so two distinct behaviors can't silently merge into one invented hybrid,
+    // and each row can be put in front of the human ("something happens here — what?").
+    const declared = {};
+    for (const { el, hints } of candidates) {
+      const b = before.get(el);
+      const a = styleSnap(el);
+      if (!styleSnapEq(a, b)) {
+        const key = keyOf(el, "reveal");
+        behaviors[key] = {
+          trigger: "scroll",
+          kind: "class-toggle-or-style-mutation",
+          hints,
+          measured: { before: b, after: a, mutatedDuringSweep: mutated.has(el) },
+        };
+      } else {
+        const key = keyOf(el, "declared");
+        if (!declared[key]) declared[key] = { hints, startState: b, text: (el.textContent || "").trim().slice(0, 60) || null };
+      }
+    }
+    // any element the observer saw mutate but that wasn't a static candidate (e.g. a purely
+    // JS-timed rotation with no CSS keyframe/class marker) still counts — MEASURE its delta
+    for (const el of mutated) {
+      if (!inRegion(el)) continue;
+      if (before.has(el)) continue; // already reconciled above
+      const key = keyOf(el, "mutation");
+      if (behaviors[key]) continue;
+      behaviors[key] = { trigger: "mutation", kind: "observed-mutation", measured: { after: styleSnap(el) } };
+    }
+
+    // marquees: explicit selectors (the caller names the moving belt — playbook §8: "animate
+    // the WHOLE wrapper, not one inner track", so discovery measures the wrapper the caller
+    // points at, never guesses which of several nested tracks is the real mover)
+    for (const [name, sel] of o.marqueeSelectors) {
+      const el = typeof sel === "function" ? sel() : document.querySelector(sel);
+      if (!el) continue;
+      const speed = await sampleTranslateSpeed(el, 1000);
+      const key = `marquee:${name}`;
+      behaviors[key] = { trigger: "load", kind: "marquee", measured: speed };
+    }
+
+    // hover-mounted content: caller supplies [name, triggerFindFn, scopeFindFn?]
+    for (const [name, findTrigger, findScope] of o.hoverTriggers) {
+      const trigger = typeof findTrigger === "function" ? findTrigger() : document.querySelector(findTrigger);
+      if (!trigger) continue;
+      const scope = (findScope ? (typeof findScope === "function" ? findScope() : document.querySelector(findScope)) : null) || document.body;
+      const result = await probeHover(trigger, scope, Math.min(o.settleMs, 1200));
+      const key = `hover:${name}`;
+      behaviors[key] = { trigger: "hover", kind: "hover-mount", measured: result };
+    }
+
+    const endedAt = new Date().toISOString();
+    return {
+      url: location.href,
+      viewport: { width: window.innerWidth, height: window.innerHeight, dpr: window.devicePixelRatio },
+      mode: document.compatMode,
+      // discovery pass metadata — the evidence that discovery ACTUALLY RAN (an absent/empty
+      // behaviors object could otherwise mean "nothing dynamic" OR "the script never fired").
+      discovery: {
+        startedAt, endedAt, durationMs: num(now() - t0),
+        scrollSweep: sweep,
+        observeMs: o.settleMs,
+        elementsScanned: scanRoot.querySelectorAll("*").length,
+        staticCandidateCount: candidates.length,
+        keyframesFound: keyframes,
+        hoverTriggersProbed: o.hoverTriggers.map(([n]) => n),
+        marqueeSelectorsProbed: o.marqueeSelectors.map(([n]) => n),
+      },
+      behaviors,
+      declared,
+    };
+  }
+
+  root.pxBehaviorDiscover = discover;
+  root.pxBehaviorCapture = function (opts) { return discover(opts).then((snap) => JSON.stringify(snap, null, 2)); };
+  // Same delivery pattern as browser-capture.js: direct POST preferred; stash/read fallback
+  // for a CSP that blocks page→localhost fetch.
+  root.pxBehaviorSend = function (url, opts) {
+    return discover(opts).then((snap) => fetch(url, { method: "POST", body: JSON.stringify(snap) }).then((r) => r.text()));
+  };
+  const DEFAULT_CHUNK = 900;
+  root.pxBehaviorStash = async function (opts, chunk) {
+    const json = JSON.stringify(await discover(opts));
+    const size = chunk || DEFAULT_CHUNK;
+    let ta = document.getElementById("__pxbehavior");
+    if (!ta) { ta = document.createElement("textarea"); ta.id = "__pxbehavior"; ta.style.cssText = "position:fixed;left:-9999px;top:0;width:1px;height:1px"; document.body.appendChild(ta); }
+    ta.value = json; ta.dataset.chunk = size;
+    return { bytes: json.length, chunks: Math.ceil(json.length / size), chunkSize: size };
+  };
+  root.pxBehaviorRead = function (i) {
+    const ta = document.getElementById("__pxbehavior");
+    if (!ta) return null;
+    const size = Number(ta.dataset.chunk) || DEFAULT_CHUNK;
+    return ta.value.slice(i * size, (i + 1) * size);
+  };
+})(typeof window !== "undefined" ? window : globalThis);

package/tools/behavior-worksheet.js

@@ -0,0 +1,82 @@
+// tools/behavior-worksheet.js <name> — the BEHAVIOR WORKSHEET: one row per animation/
+// dynamic the target is supposed to have, with its current disposition.
+//
+// WHY: when an agent doesn't know the complete list of things that are supposed to move,
+// it conflates — the iphone17 run engineered ONE invented animation where live had TWO
+// distinct behaviors (an intro animation + an inner phone video), and the reviewer had to
+// catch it. The worksheet gives every behavior an IDENTITY up front, from three sources:
+//   observed  — the dynamic pass saw it fire (behaviors in behaviors-live.json)
+//   declared  — markers/keyframes/transitions say something is SUPPOSED to happen but it
+//               never fired in this environment (`declared` in behaviors-live.json — the
+//               environment-inverted case: no-js fallbacks, bot-gated choreography)
+// and shows, per row: reproduced on the clone? excused in behavior-deviations.json? or
+// UNRESOLVED — with a ready-to-send one-sided poll question for the human ("something is
+// supposed to happen at X — on the real page, what?"), because when the machine can't
+// observe the truth, the human is the measurement instrument.
+//
+// Exit 0 when every row has a disposition; exit 1 with the unresolved list otherwise —
+// so "the worksheet is clean" is a checkable fact, and the behavior gate enforces the
+// declared rows the same way (harness/workflow.js).
+//
+// USAGE
+//   node tools/behavior-worksheet.js <name>
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const WORK = process.cwd();
+const dir = (name) => path.join(WORK, "targets", name);
+const read = (p) => JSON.parse(fs.readFileSync(p, "utf8"));
+const descriptorOf = (key) => key.replace(/^[a-z-]+:/i, "");
+
+// A declared row is REPRODUCED when the clone's dynamic pass observed the same element
+// (by descriptor) actually firing — any observed prefix counts (reveal/mutation/hover/
+// marquee): the clone made it move; which trigger class it landed under is secondary.
+function dispositionOf(key, entry, cloneObserved, deviations) {
+  const d = descriptorOf(key);
+  const cloneKey = cloneObserved.find((k) => descriptorOf(k) === d);
+  if (cloneKey) return { status: "reproduced", via: cloneKey };
+  if (deviations[key] && String(deviations[key].reason || "").trim()) return { status: "excused", via: deviations[key].reason.slice(0, 80) };
+  return { status: "UNRESOLVED" };
+}
+
+function main() {
+  const name = process.argv[2];
+  if (!name) { console.error("usage: node tools/behavior-worksheet.js <name>"); process.exit(2); }
+  const livePath = path.join(dir(name), "behaviors-live.json");
+  if (!fs.existsSync(livePath)) { console.error(`targets/${name}/behaviors-live.json missing — run discovery first (RUNBOOK "Behavior discovery")`); process.exit(1); }
+  const live = read(livePath);
+  let clone = {};
+  try { clone = read(path.join(dir(name), "behaviors-clone.json")); } catch (e) {}
+  let dev = {};
+  try { dev = read(path.join(dir(name), "behavior-deviations.json")); } catch (e) {}
+  const cloneObserved = Object.keys((clone && clone.behaviors) || {});
+
+  const observed = Object.entries(live.behaviors || {});
+  const declared = Object.entries(live.declared || {});
+  console.log(`behavior worksheet — ${name}  (${observed.length} observed, ${declared.length} declared-unfired)`);
+
+  const unresolved = [];
+  const row = (key, evidence, disp) => {
+    const mark = disp.status === "reproduced" ? "✓" : disp.status === "excused" ? "◦" : "✗";
+    console.log(`  ${mark} ${disp.status.padEnd(10)} ${key}\n      evidence: ${evidence}${disp.via ? `\n      via: ${disp.via}` : ""}`);
+    if (disp.status === "UNRESOLVED") unresolved.push(key);
+  };
+  for (const [key, b] of observed) row(key, `${b.trigger} | ${b.kind}${b.hints ? " | " + b.hints.join(",") : ""}`, dispositionOf(key, b, cloneObserved, dev));
+  for (const [key, b] of declared) row(key, `${(b.hints || []).join(",")}${b.text ? ` | "${b.text}"` : ""}`, dispositionOf(key, b, cloneObserved, dev));
+
+  if (unresolved.length) {
+    console.log(`\n❌ ${unresolved.length} row(s) UNRESOLVED — each needs: reproduction in clone/fixes.js, a reasoned entry in behavior-deviations.json, or the human's description of what live does. Ready-to-send one-sided poll questions:`);
+    for (const key of unresolved.slice(0, 8)) {
+      const b = (live.declared && live.declared[key]) || (live.behaviors && live.behaviors[key]) || {};
+      const where = b.text ? `the element reading "${b.text}"` : descriptorOf(key);
+      console.log(`  node harness/human-qa.js poll ${name} "On the real page, near ${where}: something is supposed to animate there (${(b.hints || [b.trigger]).slice(0, 2).join(", ")}). What happens as you scroll/interact?"`);
+    }
+    if (unresolved.length > 8) console.log(`  … and ${unresolved.length - 8} more`);
+    process.exit(1);
+  }
+  console.log(`\n✓ worksheet clean — every supposed-to-move row is reproduced or excused.`);
+}
+
+main();

package/tools/browser-capture.js

@@ -0,0 +1,240 @@
+// browser-capture.js — the BROWSER half of pixel-diff.js, extracted verbatim so it
+// can be injected as plain source on a strict-CSP live site (base64 transport of the
+// whole file proved fragile). Same measurement logic → schema-identical snapshots on
+// live and clone; diff them with `node tools/pixel-diff.js live.json clone.json`.
+(function (root) {
+  "use strict";
+  const num = (v) => { const n = parseFloat(v); return isNaN(n) ? v : Math.round(n * 100) / 100; };
+  const ownText = (el) => [...el.childNodes].filter((n) => n.nodeType === 3).map((n) => n.textContent).join("").trim();
+
+  root.pxRegion = root.pxRegion || { maxY: 200 };
+  const inRegion = (el) => {
+    const reg = root.pxRegion || {};
+    if (reg.sel && !el.closest(reg.sel)) return false;
+    const r = el.getBoundingClientRect();
+    if (reg.maxY != null && r.top > reg.maxY) return false;
+    if (reg.minY != null && r.bottom < reg.minY) return false;
+    return r.width > 0;
+  };
+  const byText = (re) => {
+    const hits = [...document.querySelectorAll("a,button,span,p,li,h1,h2,h3,h4,div,sup,small,strong")]
+      .filter((e) => re.test(ownText(e)) && inRegion(e));
+    return hits.sort((a, b) => ownText(a).length - ownText(b).length)[0] || null;
+  };
+  const byAria = (re) =>
+    [...document.querySelectorAll("[aria-label]")].find((e) => re.test(e.getAttribute("aria-label")) && inRegion(e)) || null;
+
+  const textBox = (el) => {
+    const tn = [...el.childNodes].find((n) => n.nodeType === 3 && n.textContent.trim());
+    if (!tn) return null;
+    const r = document.createRange();
+    r.selectNodeContents(tn);
+    const b = r.getBoundingClientRect();
+    return { x: num(b.x), right: num(b.right), top: num(b.top), bottom: num(b.bottom), w: num(b.width), h: num(b.height) };
+  };
+
+  // The STRUT of the line box that positions the glyphs: the nearest line-box CONTAINER's
+  // line-height. A leaf can match live exactly (12 vs 12) while the container differs
+  // (authored 16px vs `normal`) — sub-tolerance drift on the capture machine, visibly off
+  // where `normal` resolves differently (the HN header miss — LEARNINGS #17). Kept
+  // schema-identical with pixel-diff.js measure().
+  const strutOf = (el) => {
+    let e = el, hops = 0;
+    while (e && hops < 8) {
+      const s = getComputedStyle(e);
+      if (/^(block|table-cell|list-item|flex|grid|inline-block|table-caption)$/.test(s.display)) {
+        return s.lineHeight === "normal" ? "normal" : num(s.lineHeight);
+      }
+      e = e.parentElement; hops++;
+    }
+    return null;
+  };
+
+  // An underline is a painted mark with a BOX (thickness/x/width/y), not a boolean —
+  // measure the element that actually draws it (often an ANCESTOR border-bottom) and
+  // return its geometry, so a too-thin / too-short / mis-offset underline is caught by
+  // the sweep, not by a human three rounds later (LEARNINGS #12). Schema must match
+  // pixel-diff.js's underlineBox exactly.
+  const NO_UL = { present: false };
+  const underlineBox = (el) => {
+    let e = el, hops = 0;
+    while (e && hops < 4) {
+      const s = getComputedStyle(e);
+      if ((s.textDecorationLine || "").includes("underline")) {
+        const tb = textBox(el) || {};
+        const th = s.textDecorationThickness && s.textDecorationThickness !== "auto"
+          ? num(parseFloat(s.textDecorationThickness)) : "auto";
+        return { present: true, thickness: th, x: tb.x ?? null, right: tb.right ?? null, w: tb.w ?? null, top: null, bottom: null };
+      }
+      const bbw = parseFloat(s.borderBottomWidth) || 0;
+      const r = e.getBoundingClientRect();
+      if (bbw > 0 && s.borderBottomStyle !== "none" && r.height < 60)
+        return { present: true, thickness: num(bbw), x: num(r.x), right: num(r.right), w: num(r.width), top: num(r.bottom - bbw), bottom: num(r.bottom) };
+      e = e.parentElement; hops++;
+    }
+    const tb = textBox(el);
+    const base = el.closest("a,li") || el.parentElement;
+    if (tb && base) {
+      for (const cand of base.querySelectorAll("*")) {
+        if (cand === el || cand.contains(el)) continue;
+        const cs = getComputedStyle(cand);
+        const r = cand.getBoundingClientRect();
+        const bbw = parseFloat(cs.borderBottomWidth) || 0;
+        const isBorder = bbw > 0 && cs.borderBottomStyle !== "none";
+        const isFill = r.height <= 4;
+        if ((isBorder || isFill) && r.width >= tb.w * 0.4 && r.bottom >= tb.bottom - 1 && r.bottom <= tb.bottom + 8) {
+          const th = isBorder ? bbw : r.height;
+          return { present: true, thickness: num(th), x: num(r.x), right: num(r.right), w: num(r.width), top: num(r.bottom - th), bottom: num(r.bottom) };
+        }
+      }
+    }
+    return NO_UL;
+  };
+
+  // The painted BACKDROP behind an element — a solid background-color is a painted
+  // mark (bar/button/badge) that lives on a CONTAINER, not the leaf, so the gate
+  // never saw it: a red announcement bar passed a green --visual. Walk self→ancestors
+  // for the first non-transparent background-color. Schema must match pixel-diff.js.
+  const TRANSPARENT_BG = "rgba(0, 0, 0, 0)";
+  const isTransparent = (bc) => !bc || bc === TRANSPARENT_BG || bc === "transparent" || /,\s*0\)\s*$/.test(bc);
+  const paintedBg = (el) => {
+    // Walk to the ROOT for the first opaque background; a fully-transparent chain
+    // resolves to the canvas default (white) so an explicit body{background:#fff}
+    // clone compares EQUAL to a live canvas left transparent. Match pixel-diff.js.
+    let e = el, hops = 0;
+    while (e && hops < 40) {
+      const bc = getComputedStyle(e).backgroundColor;
+      if (!isTransparent(bc)) return bc;
+      e = e.parentElement; hops++;
+    }
+    return "rgb(255, 255, 255)";
+  };
+
+  const depth = (e) => { let d = 0; while ((e = e.parentElement)) d++; return d; };
+  const glyphBox = (el) => {
+    const wrap = (b, extra) => ({
+      cx: num(b.left + b.width / 2), cy: num(b.top + b.height / 2),
+      top: num(b.top), bottom: num(b.bottom), w: num(b.width), h: num(b.height), ...extra,
+    });
+    const svg = el.tagName.toLowerCase() === "svg" ? el : el.querySelector("svg");
+    if (svg) {
+      const shapes = [...svg.querySelectorAll("path,circle,rect,polygon,polyline,line,ellipse,use")];
+      let t = Infinity, l = Infinity, rr = -Infinity, bb = -Infinity;
+      for (const s of shapes) { const r = s.getBoundingClientRect(); if (r.width || r.height) { t = Math.min(t, r.top); l = Math.min(l, r.left); rr = Math.max(rr, r.right); bb = Math.max(bb, r.bottom); } }
+      if (isFinite(t)) return wrap({ left: l, top: t, width: rr - l, height: bb - t }, { src: "svg-path" });
+      return wrap(svg.getBoundingClientRect(), { src: "svg" });
+    }
+    const withBg = [...el.querySelectorAll("*"), el].filter((e) => getComputedStyle(e).backgroundImage !== "none");
+    const bgEl = withBg.sort((a, b) => depth(b) - depth(a))[0];
+    if (bgEl) {
+      const bc = getComputedStyle(bgEl);
+      return wrap(bgEl.getBoundingClientRect(), { src: "bg", bgPos: bc.backgroundPosition, bgSize: bc.backgroundSize });
+    }
+    return wrap(el.getBoundingClientRect(), { src: "box" });
+  };
+
+  function measure(el, want) {
+    if (!el) return { present: false };
+    const r = el.getBoundingClientRect();
+    const c = getComputedStyle(el);
+    const vw = window.innerWidth;
+    const parent = el.parentElement;
+    const pc = parent ? getComputedStyle(parent) : null;
+    const prev = el.previousElementSibling;
+    const out = {
+      present: true,
+      rect: { x: num(r.x), y: num(r.y), w: num(r.width), h: num(r.height), top: num(r.top), right: num(r.right), bottom: num(r.bottom), fromRight: num(vw - r.right) },
+      font: {
+        family: (c.fontFamily || "").split(",")[0].replace(/["']/g, "").trim(),
+        weight: c.fontWeight, size: num(c.fontSize),
+        line: c.lineHeight === "normal" ? "normal" : num(c.lineHeight),
+        spacing: c.letterSpacing === "normal" ? "normal" : num(c.letterSpacing),
+        transform: c.textTransform, color: c.color,
+        decoration: c.textDecorationLine || "none",
+        smoothing: c.webkitFontSmoothing || c.getPropertyValue("-webkit-font-smoothing") || "auto",
+      },
+      box: {
+        padT: num(c.paddingTop), padR: num(c.paddingRight), padB: num(c.paddingBottom), padL: num(c.paddingLeft),
+        marT: num(c.marginTop), marR: num(c.marginRight), marB: num(c.marginBottom), marL: num(c.marginLeft),
+        bT: num(c.borderTopWidth), bR: num(c.borderRightWidth), bB: num(c.borderBottomWidth), bL: num(c.borderLeftWidth),
+        sizing: c.boxSizing,
+      },
+      layout: {
+        display: c.display, position: c.position,
+        top: c.top === "auto" ? "auto" : num(c.top),
+        left: c.left === "auto" ? "auto" : num(c.left),
+        vAlign: c.verticalAlign,
+      },
+      parent: pc ? { display: pc.display, gap: pc.gap === "normal" ? 0 : num(pc.gap) } : null,
+      bg: paintedBg(el),   // painted backdrop colour (bar/button/badge) — compared by --visual
+    };
+    if (want && want.text) {
+      out.text = textBox(el);
+      out.font.strut = strutOf(el);            // the line-box container's line-height (LEARNINGS #17)
+      out.underline = underlineBox(el);        // the underline as a painted BOX
+      out.font.underline = out.underline.present; // boolean shorthand (back-compat)
+      if (prev) out.rect.prevGap = num(r.left - prev.getBoundingClientRect().right);
+    } else {
+      out.glyph = glyphBox(el);
+    }
+    return out;
+  }
+
+  function capture(targets, opts) {
+    const T = targets || root.pxTargets || [];
+    const elements = {};
+    for (const [name, find, text] of T) {
+      let el = null;
+      try { el = find(); } catch (e) {}
+      elements[name] = measure(el, { text });
+    }
+    const snap = {
+      url: location.href,
+      viewport: { width: window.innerWidth, height: window.innerHeight, dpr: window.devicePixelRatio },
+      // The rendering MODE is a pixel-determining property of the whole page: a quirks-mode
+      // site (no doctype → "BackCompat") computes table-cell line boxes differently than a
+      // standards-mode clone, shifting text with every computed style identical (LEARNINGS #18).
+      mode: document.compatMode,
+      elements,
+    };
+    return opts && opts.compact ? JSON.stringify(snap) : JSON.stringify(snap, null, 2);
+  }
+
+  root.pxByText = byText;
+  root.pxByAria = byAria;
+  root.pxMeasure = measure;
+  root.pxCapture = capture;
+  root.pxSend = function (url, targets) {
+    return fetch(url, { method: "POST", body: capture(targets, { compact: true }) }).then((r) => r.text());
+  };
+  // The full post-hydration DOM, doctype INCLUDED-OR-ABSENT exactly as live ships it —
+  // outerHTML alone drops the doctype, and adding a tidy one to a quirks-mode site moves
+  // pixels with every computed style identical (LEARNINGS #18). Feed the result to
+  // `ppk capture-build <name>` (the default build strategy).
+  root.pxDomHtml = function () {
+    const dt = document.doctype;
+    const doctype = dt
+      ? "<!DOCTYPE " + dt.name + (dt.publicId ? ' PUBLIC "' + dt.publicId + '"' : "") + (!dt.publicId && dt.systemId ? " SYSTEM" : "") + (dt.systemId ? ' "' + dt.systemId + '"' : "") + ">\n"
+      : "";
+    return doctype + document.documentElement.outerHTML;
+  };
+  root.pxSendDom = function (url) {
+    // CSP-blocked POST? Fall back to the stash path: pxStash(null, 900, pxDomHtml()) + pxRead.
+    return fetch(url, { method: "POST", body: root.pxDomHtml() }).then((r) => r.text());
+  };
+  const DEFAULT_CHUNK = 900;
+  root.pxStash = function (targets, chunk, preJson) {
+    const json = preJson != null ? preJson : capture(targets, { compact: true });
+    const size = chunk || DEFAULT_CHUNK;
+    let ta = document.getElementById("__pixeldiff");
+    if (!ta) { ta = document.createElement("textarea"); ta.id = "__pixeldiff"; ta.style.cssText = "position:fixed;left:-9999px;top:0;width:1px;height:1px"; document.body.appendChild(ta); }
+    ta.value = json; ta.dataset.chunk = size;
+    return { bytes: json.length, chunks: Math.ceil(json.length / size), chunkSize: size };
+  };
+  root.pxRead = function (i) {
+    const ta = document.getElementById("__pixeldiff");
+    if (!ta) return null;
+    const size = Number(ta.dataset.chunk) || DEFAULT_CHUNK;
+    return ta.value.slice(i * size, (i + 1) * size);
+  };
+})(typeof window !== "undefined" ? window : globalThis);