pixel-perfect-kit 0.1.0

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "pixel-perfect-kit",
+  "version": "0.1.0",
+  "description": "Clone a website's visual identity and prove the clone is pixel-perfect with numbers, never by eye — driven by an enforced, gated workflow (ppk).",
+  "keywords": [
+    "pixel-perfect",
+    "clone",
+    "css",
+    "visual-regression",
+    "diff",
+    "devtools",
+    "workflow",
+    "agent"
+  ],
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "ppk": "bin/ppk"
+  },
+  "files": [
+    "bin/",
+    "harness/",
+    "tools/",
+    "skill/",
+    "PLAYBOOK.md",
+    "WORKFLOW.md",
+    "LEARNINGS.md",
+    "DEVELOP.md",
+    "LAUNCH-PROMPT.md",
+    "CLONE-ANY-SITE.md",
+    "CLONE-ANY-HEADER.md",
+    "CLONE-ALOYOGA-HEADER.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node harness/regression.js"
+  }
+}

package/skill/ditto-finish/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: ditto-finish
+description: Clone a site with ditto (ditto.site) and finish it with human review rounds via PingHumans. Use when the user asks to clone/copy a site using ditto, or to polish/finish/verify a ditto-generated clone until a human approves it. Ditto's capture-to-code output is the starting point (~90%); the human-in-the-loop rounds close the gap.
+---
+
+# Ditto → human review rounds (the last 9%)
+
+Ditto compiles a URL into a runnable Next.js/Vite React codebase from the rendered
+page — by its own README, "starting points, not production-ready replicas." This skill
+finishes the job: publish the ditto build, put it in front of a real human side-by-side
+with the original, fix what they pin, and repeat until they press approve. The
+pixel-perfect-kit (`ppk`) provides the loop machinery; ditto provides the build.
+
+## Steps
+
+1. **Preflight.** `ppk doctor` (surface failures to the user). `ppk where` → KIT.
+
+2. **Build with ditto.** Use whichever ditto interface is available, in this order:
+   the ditto MCP server (https://api.ditto.site/mcp) if connected; the REST API if the
+   user has DITTO_API_KEY; else the local CLI per ditto's README. Input: the user's URL.
+   Output: a generated project — install and run it (`npm i && npm run dev`), note the
+   local port. Fix any build errors first; the loop needs a rendering page.
+
+3. **Register + publish.**
+   ```sh
+   ppk adopt <name> <original-url>              # registers the build for the human loop
+   ppk tunnel <name> --url http://localhost:<port>   # public, reachability-verified (background task)
+   ```
+
+4. **Run the human loop** (this is the product — do not skip ahead):
+   - `ppk human <name> file [--region "…"]` files a side-by-side compare round; the
+     user reviews (pins + a MANDATORY verdict button). No PingHumans login → local mode:
+     `ppk human <name> file --local` and tell the user to open /__review; never open or
+     submit it yourself.
+   - On every rejection: root-cause each pin, fix it IN THE DITTO CODEBASE (its
+     components/content files — prefer minimal, targeted edits; re-run the dev server),
+     then refile with `--changelog "what changed since your last review"`. Never respond
+     to a reviewer comment outside the loop; the verdict is the only decision channel.
+   - Polls (`ppk human <name> poll "…"`) are for ONE-SIDED questions only ("on the real
+     page, what happens when…?"); anything comparing clone to original must be a filed
+     round.
+   - Repeat until the verdict is the approving option. Expect 1–3 rounds typically;
+     pins get smaller each round if your fixes are root-caused rather than patched.
+
+5. **Report**: the round history (ping ids, what was pinned, what you changed), the final
+   approving verdict, where the codebase lives, and how to run it. The deliverable is
+   ditto's codebase, human-approved — not a claim, a receipt.
+
+Useful background from the kit's failure catalog (KIT/LEARNINGS.md): the reviewer's
+browser is the ground truth and may receive a different variant of the original than
+your browser does (#20); comment-only reviews cannot pass (approval is never inferred
+from prose); a refile without a changelog wastes the reviewer's pass.

package/skill/pixel-perfect-clone/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: pixel-perfect-clone
+description: Clone, copy, or replicate a website/page pixel-perfect using the pixel-perfect-kit (ppk). Use when the user asks to clone a site, copy a webpage's design, replicate a page, or make a pixel-perfect copy of a URL. Drives the full enforced pipeline - capture, numeric gates, behavior reproduction, and human review rounds - and treats the user as the reviewer.
+---
+
+# Clone a site pixel-perfect (ppk)
+
+The pixel-perfect-kit is an enforced, receipt-driven pipeline: a phase is done because
+its gate command exits 0, never because anyone says so. Your job is to drive it end to
+end; the user's job is to answer review pings.
+
+## Steps
+
+1. **Preflight.** Run `ppk doctor`. If anything required fails, show the user the fix
+   lines and stop until resolved. Run `ppk where` → KIT (the installed kit's directory;
+   all docs below live there).
+
+2. **Get the three values.** URL (ask if not given). WIDTH: default 1512 unless the user
+   specifies. NAME: a short slug from the domain (e.g. `stripe` for stripe.com). Targets
+   are created under the CURRENT working directory (`targets/<NAME>/`) — cd to the user's
+   preferred workspace first.
+
+3. **Follow the kit's own instructions exactly.** Read KIT/LAUNCH-PROMPT.md (the run
+   contract + environment notes) and KIT/CLONE-ANY-SITE.md (the method), and execute them
+   with the three values. They override any assumption you have. Key expectations:
+   - Build by CAPTURE (`ppk capture-build`), never hand-reconstruction.
+   - Every phase advances only through its gate: `ppk advance <NAME> <phase>`. Never
+     use --force. `ppk status <NAME>` always tells you what's next.
+   - Sink + `node <KIT>/harness/tunnel.js --sink` first for one-call capture delivery.
+   - All human contact through `ppk human <NAME> …` (file/poll/verify) — never through
+     any MCP directly. Refiles carry `--changelog "what changed"`.
+   - No PingHumans login (doctor shows it missing)? Use LOCAL review mode:
+     `ppk human <NAME> file --local`, then tell the user to open
+     `http://localhost:<serve-port>/__review` and review there. You must NEVER open or
+     submit the /__review page yourself — the verdict must come from the human.
+
+4. **Tell the user they are the reviewer** (first run especially): review pings arrive
+   with a side-by-side compare UI; they steer by PINNING comments on what looks wrong,
+   in their own words; a VERDICT BUTTON pick is required — comment-only reviews stall
+   the pipeline; their browser's rendering of the original is the ground truth (the
+   reference site may serve their browser a different variant than yours — LEARNINGS #20).
+
+5. **Iterate until done.** Act on every verdict immediately: fix from the site's own
+   captured artifacts (authored mechanisms, never invented values), re-green the gates,
+   refile with a changelog. Done = `ppk gate <NAME> done` exits 0 — all ten phases,
+   including a real approving verdict from the user.
+
+6. **Report with receipts**: the final `ppk status <NAME>` table, gate outputs, the round
+   history, and the clone's location (`targets/<NAME>/clone/`).

package/tools/RUNBOOK.md

@@ -0,0 +1,228 @@
+# RUNBOOK — the fast live-vs-clone diff sequence
+
+The verified fast path. Target: **~2–4 browser round-trips + 1 local `node` call**,
+not ~20. Every browser-automation call is a slow CDP round-trip, and a blocked
+`fetch`/`eval` on a strict-CSP live site doesn't error — it *hangs to a 45s timeout*.
+So the rules below are about avoiding slow/blocked paths, not compute.
+
+## Golden rules (these are what make it fast)
+- **Probe the delivery path FIRST — don't assume it's blocked** (see Step 0). On many
+  "strict-CSP" sites a direct `fetch` POST to `http://localhost:7799` actually
+  succeeds; `connect-src` is often looser than expected. If it works you skip the
+  entire stash/read chunking dance. *Measured cost of assuming-blocked-without-testing
+  on the aloyoga run: the whole 9-chunk manual reassembly, ~6 min wasted.*
+- **Inject the capture code as PLAIN SOURCE, never base64/gzip.** Paste
+  `tools/browser-capture.js` (the browser half of `pixel-diff.js`, extracted so it
+  drops in as-is) directly as the code to evaluate. CDP-injected source isn't gated by
+  `script-src`. Base64/gzip transports of the whole file are fragile — they corrupt or
+  trip the automation harness's content filter. **Never `fetch(...).then(eval)`** on a
+  strict-CSP origin — that path *is* gated and hangs to a 45s timeout.
+- **Don't return URLs / data-URIs / base64 through the JS tool.** The automation
+  harness may silently blank the result (`[BLOCKED: …]`). Deliver payloads by POSTing
+  to the sink, or stash to a `window` var and read one clean dump — never inline them
+  in a return value.
+- **Batch.** Fold independent calls into one `browser_batch` (both page captures
+  together; all chunk reads together).
+- **One capture per page, all targets at once.** Not one call per element.
+- **Same viewport width on both**, or the diff won't trust x-positions.
+- **Check `~/Downloads` before re-running `extractFonts`/`extractIcons`.** They dump
+  zips to disk; a prior run's `<host>-fonts.zip` / `<host>-icons.zip` may already be
+  there (`ls ~/Downloads/*<host>*`).
+
+## Prereqs
+- Your clone dev server running (note its port).
+- The sink running to receive the clone snapshot: `node tools/sink.js` (listens on 7799).
+
+## Build by capture (the DEFAULT build step — do once, before the diff loop)
+Don't hand-rebuild the markup: capture it (LEARNINGS #19 — a reconstruction manufactures
+exactly the technique mismatches the gate is blind to; a capture inherits live's doctype,
+authored line-heights, and drawing primitives by construction).
+
+1. Let the live page **settle** at the target width: load, wait ~2s, scroll to the bottom
+   and back (mounts lazy/animated content), wait, confirm `scrollHeight` + node count are
+   stable across two reads.
+2. Inject `tools/browser-capture.js` as plain source on the live tab (same rules as
+   measurement — never fetch+eval), then with the sink running in `targets/<name>/`:
+   ```js
+   await pxSendDom('http://localhost:7799/dom.html')   // doctype-exact post-hydration DOM
+   ```
+   CSP-blocked POST → `pxStash(null, 900, pxDomHtml())` + batched `pxRead` (Step 3 below).
+3. Build the standalone clone from it:
+   ```sh
+   ppk capture-build <name>          # or: node harness/capture-build.js <name>
+   ```
+   Downloads + self-hosts every stylesheet and font, absolutizes other asset refs, strips
+   scripts/CSP/`<base>`, and **preserves the doctype or its absence byte-for-byte**. A
+   `file://` url in `target.json` also works (build from a saved page). Failed downloads
+   exit 1 — fix them before advancing the `build` phase.
+4. The gates run unchanged from here: measure live, capture the clone, `--visual`,
+   coverage, strict. What capture can NOT give you — JS-driven behavior, animated or
+   generative content — you reproduce separately, and spend human QA rounds only there.
+
+## Behavior discovery (the `behavior` phase — after the pixel gates are green)
+Same injection + delivery rules as everything else here (plain source, probe the POST,
+stash/read fallback). `tools/behavior-capture.js` provides `pxBehaviorDiscover(opts)` /
+`pxBehaviorSend(url, opts)` / `pxBehaviorStash(opts)` + `pxBehaviorRead(i)`.
+
+1. **On the LIVE tab:** inject `tools/behavior-capture.js`, set `pxRegion`, name what you
+   can see moving — `opts = { marqueeSelectors: [["logo_belt", ".belt-wrapper"]],
+   hoverTriggers: [["nav_product", "nav a[href*=product]"]] }` — then
+   `await pxBehaviorSend('http://localhost:7799/behaviors-live.json', opts)`. The pass
+   greps `@keyframes` + markers for candidates, then confirms and MEASURES what actually
+   fires across a scripted scroll sweep (a candidate that never moves is noise, not a
+   behavior). Its own sweep metadata is recorded — that's the gate's evidence discovery ran.
+2. **Reproduce** each inventoried behavior in one vanilla `clone/fixes.js` (each in its own
+   guarded `try`), using the MEASURED values. Rebuild: `ppk capture-build <name> --fixes`.
+3. **On the CLONE tab:** same discovery, same opts → `behaviors-clone.json`.
+4. `node harness/workflow.js gate <name> behavior` — misses are named with exact deltas;
+   irreproducible content goes in `behavior-deviations.json` with a reason, never silent.
+5. **The worksheet — the complete "supposed to move" list.** Discovery keeps
+   declared-but-unfired candidates (markers, keyframes, transitions-from-hidden, videos)
+   as `declared` inventory instead of discarding them — critical on sites that gate their
+   choreography behind no-js/bot detection, where NOTHING fires for automation but
+   everything is still supposed to. `node tools/behavior-worksheet.js <name>` prints one
+   row per behavior (observed + declared) with its disposition; every UNRESOLVED row gets
+   a ready-to-send one-sided poll question so the HUMAN describes what live does before
+   you engineer anything. Each behavior having an identity up front is what prevents two
+   real behaviors merging into one invented hybrid — the gate refuses undisposed declared
+   rows for the same reason.
+
+## Step 0 — probe live delivery (do this before anything else)
+Inject `tools/browser-capture.js` source on the live tab, then try a direct POST:
+```js
+fetch('http://localhost:7799/live.json', {method:'POST', body: pxCapture(null,{compact:true})})
+  .then(r=>r.text()).then(t=>window.__post=t).catch(e=>window.__post='ERR:'+e.message)
+```
+Check whether `./live.json` appeared on disk. **If it did, you're done delivering** —
+capture both pages with one `pxSend` each and skip Steps 3. Diagnose a refusal by its
+timing: a **clean ~4s abort** on a site that sends no CSP header is the *automation
+extension* blocking page→localhost fetch (environment-level); a **45s hang** is the
+site's `connect-src` (CSP-level).
+
+**Blocked either way? Tunnel the SINK — this replaces the stash/chunk dance:**
+```sh
+node tools/sink.js &                      # the receiver, as usual
+node harness/tunnel.js --sink &           # public HTTPS in front of it (verified by the
+                                          # sink's own signature; records ./sink-tunnel.json)
+```
+then from any page, live or clone: `await pxSend('<sink-tunnel-url>/live.json')` /
+`pxSendDom('<url>/dom.html')` / `pxBehaviorSend('<url>/behaviors-live.json')` — one call,
+full payload, no truncation caps. Stash + chunked `pxRead` (Step 3) is the LAST resort,
+only for when outbound HTTPS itself is blocked (rare — that's a real site CSP with a
+strict `connect-src`, and even those often allow `*.trycloudflare.com`... probe it).
+
+## Step 1 — both windows to the same width
+Resize the clone tab and the live tab to the same width (e.g. 1728). Confirm
+`innerWidth` matches on both (scrollbars/devtools can shrink it).
+
+## Step 2 — capture BOTH pages in ONE browser_batch
+- **Clone (same-origin localhost, no CSP → 1-call send):** load the capture code
+  (`eval(await fetch('/browser-capture.js').then(r=>r.text()))` works on localhost — no
+  strict CSP there; copy `browser-capture.js` into the clone's served dir), set
+  `pxRegion`, define `pxTargets`, then:
+  ```js
+  await pxSend('http://localhost:7799/clone.json')   // capture + POST, returns "ok clone.json"
+  ```
+- **Live:** inject `tools/browser-capture.js` **source directly** as plain text (paste
+  the whole file — do NOT fetch+eval, do NOT base64/gzip it), set `pxRegion` +
+  `pxTargets`. Then **prefer the direct POST from Step 0** (`pxSend('…/live.json')`).
+  Only if that's blocked, stash:
+  ```js
+  pxStash(null, 900)   // compact capture into a hidden <textarea>; returns {bytes, chunks}
+  ```
+  (900-char chunks fit a typical ~1KB automation result cap; a human DevTools console
+  has no cap → just `copy(pxCapture())`.)
+
+## Step 3 — read all live chunks in ONE browser_batch *(only if POST was blocked)*
+Issue `pxRead(0) … pxRead(chunks-1)` as separate actions in a single `browser_batch`,
+save each slice to its own file (zero-padded: `chunk-00.txt`, `chunk-01.txt`, …), then
+**reassemble with the validator — never hand-concatenate** (a dropped character at a chunk
+boundary silently corrupts the snapshot and only surfaces rounds later as unexplainable diffs):
+```sh
+node tools/reassemble.js live.json --bytes <bytes-from-pxStash> chunk-*.txt
+```
+It verifies the byte count against pxStash's report, JSON-parses, and checks the snapshot
+shape before writing — any mismatch names the broken chunk instead of writing garbage.
+
+## Step 4 — diff locally
+```sh
+node tools/pixel-diff.js live.json clone.json --visual   # "does it look identical?" exit 0 = pass
+node tools/pixel-diff.js live.json clone.json            # strict: also flags structural CSS
+```
+
+## Sanity checks
+- Each target's `rect.y` lands where you expect (catches a finder grabbing the same
+  text elsewhere — that's why `pxRegion` exists).
+- The diff warns and refuses x-comparisons if the two snapshots' widths differ.
+- A `present:false` on either side is a finder failure, not a match — fix the finder.
+- A **`text.present` failure** means a finder resolved a non-text *wrapper* (its own
+  text node is empty), which nearly skipped `font.color`/size. Fix the finder to land
+  on the text element — use `byText(/…/)` (own-text match), not a hand-rolled
+  `children.length<=1` filter that can match a full-width container.
+- **Read the strict table for colour/underline rows before declaring a pass.**
+  `font.color`, `font.decoration`, `font.underline` are *visible* marks, not
+  structure — a strict `font.color … ❌` under a green `--visual` is a real defect.
+
+## Coverage (don't skip)
+After `--visual` is green, enumerate every painted element in the region (own text,
+background-image, or `<svg>`) that has **no** `pxTargets` entry, and add one. A green
+diff only proves the elements you measured.
+
+**Coverage is elements *and* the marks on them.** The gate now measures the marks that
+used to slip a green sweep — `font.smoothing`, the **underline box** (`underline.*`,
+taken off whichever element draws it, ancestor included), and the **painted backdrop**
+(`bg` — the bar/button/badge colour behind a mark, transparent chain → white canvas) —
+and `--visual` compares them, so you don't re-derive them by hand. What's still on you: **enumerate
+every painted leaf** (own text / background-image / `<svg>`) so each has a target, and
+for a mark the tool doesn't special-case (a `box-shadow`, an `outline`) measure the
+drawing element's box with `--inspect`. Set the clone root to `antialiased` / `grayscale`.
+
+## The fast fix loop (incremental re-verify + micro-polls)
+Two tools that keep iteration at seconds/minutes instead of full-round scale:
+
+- **Partial re-capture + merge.** After a scoped fix, don't re-capture all N targets —
+  capture just the affected ones (`pxSend('<sink-url>/partial.json', subsetTargets)`) and
+  fold them in: `node tools/merge-snapshot.js targets/<name>/clone.json partial.json`.
+  Gates re-run instantly on the merged file. The merge stamps the snapshot and **the done
+  gate refuses stamped snapshots** — one final FULL capture is always required (a fix can
+  displace things outside your subset: astryx's bento-height fix moved the footer).
+- **Micro-polls before full rounds.** With a responsive reviewer, ask the ~$0.05 question
+  mid-round instead of spending a whole test round discovering the answer:
+  `node harness/human-qa.js poll <name> "do the 3 template tiles look right now?"
+  --choices "Yes,No"` (draft+original urls auto-appended; blocks up to ~5 min; answers
+  recorded in human-qa.json). Polls are ADVISORY — the human gate still requires an
+  approving verdict on a full scope-pinned round. Use them to decide, not to certify.
+
+## Human flags one element → exhaustive drill-down (`--inspect`)
+When a human says "*this* looks wrong" (not a full sweep), don't guess the property —
+measure the whole element **that paints the mark** (which may be an ancestor):
+
+1. On **both** pages resolve the flagged element and dump its full computed style:
+   ```js
+   copy(pxInspect({ text: "sign in" }))   // {aria}, {sel}, {at:[x,y]} also work
+   ```
+   (live CSP → `pxStashInspect(resolver)` + batched `pxRead`; clone → `copy()` or POST to sink.)
+   **If the paint bucket is empty but the human still sees it, you inspected the wrong
+   element** — the mark is drawn by an ancestor/sibling (e.g. an underline that's a
+   `border-bottom` on a wrapping group). Resolve that element (`{sel:".loyalty-name-part"}`)
+   and measure **its box**: `top`, `height`, `box-sizing`, `border-bottom` — that box
+   positions the mark.
+2. Diff, paint-first:
+   ```sh
+   node tools/pixel-diff.js --inspect el_live.json el_clone.json
+   ```
+   **PAINT** = the fix list (colour, border, decoration/underline, background,
+   transform, geometry…); **STRUCTURAL** demoted; irrelevant props hidden.
+3. **Fix by reproducing the box model + technique, and fix the whole mark at once.**
+   Rebuild the same drawing element (same `border`, `height`, `box-sizing`) so the
+   mark's position/size *emerge* — don't nudge the text with a magic offset (it drifts
+   and rasterises unlike a real border, failing a flicker compare even at ~0.01px). A
+   decoration has thickness + width + offset + technique; set them together, or the
+   human iterates once per facet.
+4. **Re-run step 2** — done = PAINT bucket empty (exit 0). Then flicker/overlay the two
+   at 1:1 as a final check: a technique mismatch survives a green number.
+
+## Human shortcut (no automation)
+At the keyboard: paste `pxCapture()` (or `pxInspect(resolver)`) into the real DevTools
+console on each page (no CSP-on-console, no truncation, `copy()` works), save the two
+files, and run Step 4 / `--inspect`. This skips injection, the sink, and chunking.