luckiest-co 1.0.13 → 1.0.15

package/skills/luckiest-website-cloner/references/builtin-browser-recipes.md

@@ -0,0 +1,74 @@
+# Built-in browser recipes (no playwright-cli)
+
+Use these when the only browser you can drive is the in-app browser pane
+(`navigate`, `javascript_tool`, `computer`, `get_page_text`, `read_page`). This
+path has **no preload**, so `instrumentGetContext()` and `instrumentMotion()`
+cannot run before the page's own scripts. Everything here is post-hoc. That is
+still reliable for the common case; it is weaker for canvases that request their
+context once at startup and for motion that only fires on first paint.
+
+## Inject the probe bundle
+
+Build it once, then paste it in. `javascript_tool` cannot read local files, so
+inline the bundle's text rather than pointing at a path.
+
+```bash
+node scripts/build-bundle.cjs /tmp/probes.bundle.js
+```
+
+Then evaluate the file's contents in the page, followed by the probe call. Do it
+in two steps so a syntax error in the bundle is easy to tell apart from a probe
+error.
+
+## Settle the page before probing
+
+```js
+(async () => {
+  const h = document.documentElement.scrollHeight;
+  for (let y = 0; y < h; y += 700) { window.scrollTo(0, y); await new Promise(r => setTimeout(r, 120)); }
+  window.scrollTo(0, 0);
+  await new Promise(r => setTimeout(r, 800));
+  return h;
+})()
+```
+
+## Probe and write out
+
+`javascript_tool` returns its last expression as JSON, and large probe output
+will blow up the conversation. Take `motionSummary()` inline for a first look,
+and for the full `motionProbe()` / `tokensProbe()` output return it in chunks
+and write each chunk to the output directory from the shell, or keep only the
+fields you need:
+
+```js
+JSON.stringify(surfaceMap())          // small, safe inline
+JSON.stringify(motionSummary())       // small, safe inline
+JSON.stringify(tokensProbe()).length  // check size BEFORE returning the body
+```
+
+## Expect `instrumented: false`
+
+`motionProbe().instrumented` will be false on this path. That is expected, not a
+failure. Record it in the surface map so the teardown does not claim ground
+truth it does not have, and treat canvas routing as a hypothesis to confirm with
+a screenshot.
+
+## Screenshots and viewports
+
+Use `resize_window` for the 1440 / 768 / 390 passes and `computer` with
+`action: "screenshot"` for section references. Reload after a viewport change so
+load-time breakpoints re-run.
+
+## Assets
+
+```js
+JSON.stringify(performance.getEntriesByType('resource').map(e => e.name))
+```
+
+## Viewport reads can come back zero
+
+In a hidden or background pane, `window.innerWidth` / `innerHeight` can report
+`0` even though the page laid out correctly and every `getBoundingClientRect()`
+is real. Do not treat a zero viewport as a failed probe, and do not record it as
+the breakpoint you measured at. Front the tab, or take the width you asked
+`resize_window` for as the truth.

package/skills/luckiest-website-cloner/references/compositing.md

@@ -0,0 +1,65 @@
+# Compositing GPU effects into the DOM shell
+
+The DOM track leaves a **placeholder mount** wherever a GPU surface belonged.
+The GPU track produces a **self-contained effect module**. Compositing is the
+contract that joins them. Most "the clone looks off" bugs are composite bugs, not
+extraction bugs: the effect renders perfectly in its own baseline, then sits at
+the wrong depth, swallows clicks, or renders blurry once it's in the page.
+
+## The mount contract
+
+Each effect module should expose a tiny, framework-agnostic lifecycle so any
+shell (Vite, Next, plain HTML) can drive it the same way:
+
+```js
+// effect module (per GPU surface)
+export function mount(canvasEl, opts) { /* start renderer + rAF loop */ return handle }
+export function unmount(handle)        { /* cancel rAF, lose context, free GPU */ }
+export function resize(handle, w, h, dpr) { /* update drawing buffer + viewport */ }
+```
+
+The DOM shell mounts it into the placeholder container from the surface map:
+
+```js
+const el = document.querySelector(MOUNT_SELECTOR);
+const canvas = document.createElement('canvas');
+el.appendChild(canvas);
+const handle = mount(canvas, { /* uniforms captured by luckiest-website-cloner-shaders */ });
+```
+
+## Get these five things right (they are the usual failure points)
+
+1. **Sizing + DPR.** The drawing buffer must be `cssWidth * dpr` by
+   `cssHeight * dpr`, with the canvas CSS-sized to the container. Skipping DPR is
+   the #1 "why is the clone blurry / aliased" cause on retina displays. Re-run
+   `resize()` on container resize (ResizeObserver), not just window resize.
+2. **z-index + stacking.** Copy `zIndex` and `position` from `surface-map.json`.
+   A hero shader usually sits at a low z-index BEHIND the text, not on top. If it
+   covers the copy, the composite is wrong even though the effect is right.
+3. **pointer-events.** Copy the original's `pointerEvents`. A full-bleed
+   background canvas almost always needs `pointer-events: none` so buttons and
+   links under/over it stay clickable. An *interactive* effect (cursor-reactive
+   blob) needs pointer events ON — the surface map records which.
+4. **Teardown.** On route change / unmount, call `unmount()` and let the WebGL
+   context go (`loseContext()`). Leaking contexts hits the browser's ~16-context
+   limit fast on multi-effect pages and the later canvases silently go black.
+5. **Reduced motion + offscreen pause.** Respect
+   `prefers-reduced-motion: reduce` (render a static first frame or the captured
+   poster). Pause the rAF loop when the canvas is scrolled out of view
+   (IntersectionObserver) — the original may not, but it's cheap fidelity-neutral
+   insurance against jank, and matches how good sites ship these.
+
+## Multiple effects on one page
+
+Mount each into its own container from the surface map. Share a single renderer
+only if all effects came from the same driver and baseline; otherwise keep them
+independent so one failing effect can't black out the others. Watch the context
+budget (point 4).
+
+## When the effect can't be reconstructed
+
+If luckiest-website-cloner-shaders returned only an approximate or poster-only result (e.g.
+cross-origin readback was blocked, or the surface was `CANVAS_UNKNOWN`), mount
+its fallback (captured poster image or a low-fidelity approximation) and record
+the gap in the completion report. Do not silently ship a dead container — a
+poster still reads as intentional; an empty box reads as broken.

package/skills/luckiest-website-cloner/references/fidelity-fast-path.md

@@ -0,0 +1,92 @@
+# The fidelity fast path — reuse the original's CSS instead of rebuilding it
+
+Validated on a real clone run (Nuxt marketing site): this path reached a
+**0.02–0.06% pixel diff** on the DOM track in one pass, where rebuild-from-spec
+typically lands at 1–3% after several fix rounds. Prefer it whenever it applies.
+
+## When it applies
+
+The target ships **scope-attributed CSS** — Vue scoped styles (`data-v-*`),
+CSS Modules (hashed class names), styled-components (hashed classes), Angular
+(`_ngcontent-*`). The attributes/classes are baked into the rendered DOM, so:
+
+> post-hydration HTML + the site's own stylesheets + rewritten asset paths
+> = pixel-identical DOM layer, byte for byte.
+
+It does NOT apply when the goal is a *maintainable* codebase to keep developing
+(then use luckiest-website-cloner-dom's component rebuild), or when the user asked for a specific
+stack. Say which path you chose and why in the report.
+
+## The recipe
+
+1. **Capture post-hydration HTML** after a full settle scroll:
+   `document.documentElement.outerHTML` via Playwright. Not view-source — the
+   served HTML lacks client-rendered state.
+2. **Download every stylesheet** in document order (`<link rel=stylesheet>`
+   hrefs). Concatenate in that order — cascade order is load order.
+3. **Rewrite paths** in both HTML and CSS: absolute site URLs → local, CDN image
+   URLs (strip query params, keep a deterministic filename), `/fonts/`,
+   `url(...)` in CSS. Grep the result for `https?://` afterward — remaining
+   hits should only be outbound links, or you missed an asset.
+4. **Strip the runtime**: remove `<script>` tags and preload/prefetch links.
+   Keep everything else, including framework scope attributes and inline
+   `style=""` — they're part of the captured state.
+5. **Capture state you can't see at rest.** SPA frameworks render only the
+   ACTIVE state into the DOM — inactive tab panels, closed dropdowns, unfired
+   dialogs simply don't exist in the capture. For each stateful widget, drive
+   the live site (click each tab/accordion/menu) and save each state's
+   innerHTML; replay those snapshots from your own JS. The interaction sweep's
+   click step is where you find these.
+6. **Beware capture-time inline state**: elements the site's JS was mid-
+   animating carry inline `opacity`/`transform` from the moment of capture
+   (e.g. a bar captured at `opacity: 0`). Your rewritten behavior JS must own
+   those elements' initial state explicitly, not trust the captured inline value.
+7. **Rebuild only behaviors** (one small JS entry): smooth scroll, canvas/GPU
+   mounts, state machines, toggles — from `motion.json` params. CSS-driven
+   effects (scroll-timelines, keyframes, transitions) came along with the
+   stylesheets for free — do not reimplement them.
+
+## Trigger-position drift (bit us; will bite again)
+
+Scroll-triggered behaviors computed at load go stale when lazy images/fonts
+shift layout seconds later — symptom: effects fire at the wrong scroll position
+only on some breakpoints. Standard fix, include it by default:
+
+```js
+let lastH = 0, t = 0;
+new ResizeObserver(() => {
+  const h = document.documentElement.scrollHeight;
+  if (h === lastH) return; lastH = h;
+  clearTimeout(t); t = setTimeout(() => ScrollTrigger.refresh(), 120);
+}).observe(document.body);
+```
+
+## Matching state machines: measure thresholds, don't guess them
+
+For each observed state flip (header theme, content swap, element fade), sample
+the original at a FINE grain around the transition (±50px steps) and record the
+exact trigger geometry before implementing. Two traps proven real:
+- a flip can be **binary** where you'd assume scrubbed (and vice versa) — the
+  fine-grained samples tell you which;
+- the trigger element is often NOT the section that changes (a header flips on
+  the NEXT section's top edge, at an offset unrelated to the header's height).
+Also check for CSS-variable drivers before assuming classes: if a computed style
+uses `color-mix(... var(--x-progress) ...)`, the JS writes that var — toggling
+the class alone changes nothing visible.
+
+## When the GPU surface is a known library, reuse it (SOURCE fidelity)
+
+Before routing a canvas to luckiest-website-cloner-shaders, grep the bundles for library
+fingerprints: `data-paper-shader` / `@paper-design` (Paper Shaders),
+`unicorn.studio`, `spline-viewer`, `rive`, `lottie`, `r3f`/`@react-three`,
+`ogl`. If the effect is an off-the-shelf component, the bundle usually carries
+its **props verbatim** (Next.js app-router chunks are barely minified — read the
+page chunk, it IS the source). Install the same package and pass the same props:
+that's SOURCE fidelity for free, no capture/replay needed. Also copy the site's
+**render gate** (reduced-motion / pointer / width / cores / GPU-renderer
+checks) — it decides when the fallback shows, and the fallback is part of the
+look. Add a `?shaders=1|0` override so QA can exercise both paths.
+
+Mount-point rule: when the original renders the effect wrapper *conditionally*,
+your mount element must be visually inert (no background, no filter) — put the
+wrapper styling on the mounted component, or the fallback state shows a blank box.

package/skills/luckiest-website-cloner/references/playwright-cli-recipes.md

@@ -0,0 +1,68 @@
+# playwright-cli recipes for this skill
+
+`playwright-cli` is a CLI over a persistent browser session. Each invocation is
+a separate process, which shapes how you must use it here.
+
+## Running the probe scripts
+
+```bash
+# inject the probe bundle into the LIVE page, then evaluate
+playwright-cli -s=<name> run-code "async page => { await page.addScriptTag({ path: '<abs>/probes.bundle.js' }); return page.evaluate(() => motionSummary()); }"
+```
+Build `probes.bundle.js` with `node scripts/build-bundle.cjs [dest]` — it concatenates
+the three probe files AND exports them onto `window`. That export is mandatory:
+Playwright wraps `addInitScript`/`addScriptTag` code in a function scope, so
+bare `function` declarations are invisible to later `page.evaluate` calls
+(symptom: `motionSummary is not defined` even though the script ran). `run-code` has **no `fs`** — return data and redirect
+stdout, or use `eval` and parse the `### Result` block:
+
+```bash
+playwright-cli -s=<name> eval "JSON.stringify(tokensProbe())" > raw.txt
+# then unwrap: the JSON is the quoted string after the '### Result' line
+```
+`eval` treats an expression starting with `(` as a function — wrap IIFEs in
+`run-code` + `page.evaluate` instead.
+
+## Instrumented (preload) mode — do it in ONE run-code call
+
+`page.addInitScript()` registered in one `run-code` invocation does NOT
+survive into the next (the CLI's `page` binding is re-created). Do init +
+navigate + settle + probe in a single call:
+
+```bash
+playwright-cli -s=<name> run-code "async page => {
+  await page.addInitScript({ path: '<abs>/probes.bundle.js' });
+  await page.addInitScript(() => { instrumentGetContext(); instrumentMotion(); });
+  await page.goto('<url>', { waitUntil: 'domcontentloaded' });
+  await page.waitForTimeout(2500);
+  const h = await page.evaluate(() => document.documentElement.scrollHeight);
+  for (let y = 0; y < h; y += 700) { await page.mouse.wheel(0, 700); await page.waitForTimeout(120); }
+  await page.evaluate(() => window.scrollTo(0, 0)); await page.waitForTimeout(800);
+  return page.evaluate(() => ({ sm: surfaceMap(), mo: motionProbe() }));
+}" > raw-instrumented.txt
+```
+Verify `mo.instrumented === true`; if false the preload didn't take.
+
+## Capturing hidden SPA state
+
+```bash
+playwright-cli -s=<name> run-code "async page => { const tabs = page.locator('.tabs .tab'); const out = []; for (let i = 0; i < await tabs.count(); i++) { await tabs.nth(i).click(); await page.waitForTimeout(800); out.push(await page.evaluate(() => document.querySelector('.tabs-content').innerHTML)); } return out; }"
+```
+
+## Asset list
+
+`playwright-cli network` only logs from the moment it's first called. For the
+full list use the page's own record:
+`page.evaluate(() => performance.getEntriesByType('resource').map(e => e.name))`.
+
+## Screenshots
+
+`page.screenshot({ path })` inside `run-code` works and is the reliable way to
+get section references regardless of which browser tool is fronted.
+
+## Headless GPU note
+
+Headless Chromium on a desktop with a real GPU often exposes a real GPU renderer string, so sites
+that gate shaders on `WEBGL_debug_renderer_info` DO render them in QA — mask
+`[data-paper-shader]`, `canvas`, and any wrapper the library injects. Don't
+assume headless = software GL.

package/skills/luckiest-website-cloner/references/teardown.md

@@ -0,0 +1,142 @@
+# TEARDOWN.md — the human-readable blueprint
+
+`surface-map.json`, `motion.json`, and `tokens-*.json` are machine evidence.
+`TEARDOWN.md` is the same evidence written for a person: what the site is made
+of, how every effect actually works, and what it would take to rebuild it. It is
+the deliverable of `--analyze-only` runs, the briefing the builders work from on
+full runs, and — because the reveals are usually "that impressive thing is 54
+images swapped on mousemove" — the raw material for a video.
+
+Write it at the end of Phase 1, from the probe outputs + your scroll/hover sweep.
+Every claim carries an evidence tag:
+
+- **CONFIRMED** — read from a live runtime object or computed style
+  (`ScrollTrigger.getAll()`, `getComputedStyle`, `document.getAnimations()`).
+- **OBSERVED** — seen during the sweep (screenshots at scroll offsets, hover
+  before/after) but the mechanism wasn't exposed by a probe.
+- **INFERRED** — guessed from class names / markup / general patterns. The
+  builder should verify before relying on it.
+
+Never upgrade a tag. A clone built on INFERRED values needs a diff pass to prove
+them; one built on CONFIRMED values mostly needs a diff pass to catch typos.
+
+## Template
+
+```markdown
+# Teardown: {site name}
+
+**URL:** {url}   **Analyzed:** {YYYY-MM-DD} @ {1440/768/390}
+**Platform:** {Next.js / Webflow / Framer / WordPress / custom} — {evidence}
+**Built by:** {agency/dev, if a footer/meta credit exists; else omit}
+**Surfaces:** {N} DOM sections, {N} GPU surfaces ({drivers}), {N} video
+
+## Stack (from runtime)
+
+| Layer | What | Evidence |
+|---|---|---|
+| Framework | {…} | `__NEXT_DATA__` present / `data-framer-name` / … |
+| Animation | GSAP {ver} + ScrollTrigger ({n} triggers, {n} pinned, scrub on {n}) | `motion.json › gsap, scrollTrigger` |
+| Scroll | Lenis lerp {x} duration {y} | `motion.json › lenis.options` |
+| 3D / GPU | {three.js r{ver} / Unicorn Studio / none} | `surface-map.json` |
+| Sliders | {Swiper: loop, autoplay 4000, effect fade} | `motion.json › sliders` |
+| Fonts | {Family A (display), Family B (text)} — self-hosted woff2 / Google | `tokens.fontFaces` |
+
+## Design system (measured)
+
+**Palette** — top values by usage, role-labeled:
+| Role | Value | Uses |
+|---|---|---|
+| Page bg | {#…} | {n} |
+| Text | {#…} | {n} |
+| Accent | {#…} | {n} |
+
+**Type scale @1440** (size / line-height / weight — family):
+| Role | Value | Example |
+|---|---|---|
+| h1 | {…} | `.hero__title` |
+| h2 | {…} | |
+| body | {…} | |
+| label/eyebrow | {…, letter-spacing, uppercase} | |
+{Note what changes @768 and @390 — usually 2–4 lines.}
+
+**Spacing rhythm** — {base unit + the 5–8 values that carry the layout}.
+**Radii** {…} · **Shadows** {…} · **Max-width** {…} · **Breakpoints** {…}
+**Custom props** — {if the site exposes its own tokens, list the important ones;
+reuse their names in the clone}.
+
+## Effects (one row per distinct effect, top-to-bottom)
+
+| # | Section | Effect | Mechanism | Tag | Complexity |
+|---|---|---|---|---|---|
+| 1 | Hero | Title chars rise + fade in on load | SplitText → stagger 0.03, y 100%→0, power3.out, 1.2s | CONFIRMED | Low |
+| 2 | Hero | Background liquid gradient | WebGL2 fragment shader, three.js, 2 uniforms (time, mouse) | CONFIRMED (surface) / PARTIAL (replay) | High |
+| 3 | Features | Sticky mock swaps as copy scrolls | `position:sticky` + IntersectionObserver threshold 0.5 | CONFIRMED (IO instrumented) | Med |
+| … | | | | | |
+
+## Reveals — how the impressive ones actually work
+
+### {Effect #} — {name}
+**What it looks like:** {one sentence}
+**What it is:** {the mechanism in plain words — the "oh, that's all it is"}
+**Exact params (CONFIRMED):**
+```
+{paste the relevant motion.json entry: trigger, start/end, scrub, vars…}
+```
+**Rebuild note:** {the one thing that makes it feel right — easing, the lerp
+value, the DPR handling, the fact that it's 3 layers not 1}
+
+{Repeat for every effect rated Med/High, and any Low that's load-bearing.}
+
+## Assets
+
+| Asset | Role | Tier | Notes |
+|---|---|---|---|
+| hero-bg.mp4 | decorative bg | REAL | 1920×1080, 4.2 MB |
+| logo.svg | identity | PLACEHOLDER | don't copy brand |
+| noise.png | texture | RECONSTRUCT | generate with canvas |
+{Tiers from `luckiest-website-cloner-dom/references/asset-resolution.md`.}
+
+## Build plan
+
+**Substrate:** {Vite+TS / Next+Tailwind} — {why, per Phase 2 rules}
+**Packages:** `npm i {gsap lenis three …}`
+**Order:** {section list top-to-bottom, each with: interaction model, which
+effects from the table, expected difficulty}
+**Known gaps:** {cross-origin stylesheets that hid @font-face, un-instrumented
+IO, surfaces flagged CANVAS_UNKNOWN, premium plugins (SplitText/ScrollSmoother
+need Club GSAP → use free alternatives or the now-free GSAP 3.13+)}
+```
+
+## Common reveals (look for these first)
+
+Most "how did they do that" effects on award sites are one of these. When the
+probe shows the signature, name it:
+
+- **Image sequence on scroll/mouse** — N preloaded frames, one visible. Signature:
+  many sibling `<img>`/canvas draws + a scrub ScrollTrigger or mousemove listener.
+- **SplitText reveal** — `.char/.word/.line` wrappers + staggered tween.
+- **Parallax layers** — several tweens on siblings with different `y`/`yPercent`
+  and the same trigger, or mousemove → `transform` with different multipliers.
+- **Scrub animation** — `ScrollTrigger.scrub: true|number`. Number = lerp delay.
+- **Pinned section** — `pin: true` with a long `end` (`+=200%`); inside it,
+  content swaps by progress.
+- **CSS-var driven** — JS writes `--progress`; CSS `calc()`s off it. Look for
+  custom props that change as you scroll.
+- **Smooth scroll** — Lenis on `<html class="lenis">`. Feel comes from `lerp`.
+- **Page transitions** — barba / Swup global + an overlay element with z-index
+  9999.
+- **Grain** — a fixed full-viewport div, noise PNG/SVG `feTurbulence`,
+  `mix-blend-mode: overlay|soft-light`, low opacity, sometimes animated
+  `background-position`.
+- **Custom cursor** — fixed small element + mousemove + `gsap.quickTo` /
+  `quickSetter`; often two elements (dot + ring) with different lerps.
+- **Marquee** — `@keyframes` translateX −50% on a duplicated track, or GSAP
+  `repeat:-1` with `xPercent`.
+- **Magnetic button** — mousemove inside a hit area → `x/y` tween toward cursor,
+  `elastic.out` on leave.
+- **Reveal on scroll** — IO (threshold 0.1–0.3) toggles a class; CSS transition
+  does the motion. Or ScrollTrigger `toggleActions: "play none none reverse"`.
+- **Theme flip by section** — IO or ScrollTrigger toggling a class on `<body>`;
+  CSS vars swap; 0.4–0.8s transition on background/color.
+- **Text scramble / counter** — rAF loop writing `textContent`; not an animation
+  the probe can see — OBSERVED, note the duration.

package/skills/luckiest-website-cloner/references/visual-qa.md

@@ -0,0 +1,102 @@
+# Automated visual QA
+
+Replace "look at a screenshot and call it done" with a real pixel diff. The catch
+is that a cloned page is two materials with opposite QA needs: DOM must match
+closely and deterministically; GPU effects animate and will never match pixel-
+for-pixel. So diff DOM, and **verify** GPU — don't diff GPU.
+
+## Harness
+
+Use Playwright's built-in visual comparison (`toHaveScreenshot()` / `expect(page)`
+compares via the pixelmatch library — pixel-by-pixel, local, no external
+service). Capture original and clone at the same viewport, DPR, and scroll state.
+
+```js
+// qa/clone.spec.ts — run per breakpoint
+import { test, expect } from '@playwright/test';
+
+const BREAKPOINTS = [1440, 768, 390];
+// GPU surface selectors come straight from surface-map.json.routingSummary.sendToShaderExtract
+const GPU_MASKS = ['#hero-canvas', '.bg-shader'];
+
+for (const width of BREAKPOINTS) {
+  test(`clone matches original @ ${width}`, async ({ page }) => {
+    await page.setViewportSize({ width, height: 900 });
+    await page.goto(CLONE_URL);
+    await page.waitForLoadState('networkidle');
+    await expect(page).toHaveScreenshot(`clone-${width}.png`, {
+      fullPage: true,
+      mask: GPU_MASKS.map((s) => page.locator(s)), // exclude animated GPU regions
+      maxDiffPixelRatio: 0.02,  // ~2% tolerance absorbs anti-aliasing noise
+      threshold: 0.2,           // per-pixel color sensitivity (default; lower = stricter)
+      animations: 'disabled',   // freeze CSS animations/transitions for a stable frame
+    });
+  });
+}
+```
+
+Generate the baseline from the **original** site (first run writes the reference
+screenshot), then run the **clone** against it. Or capture both to files and diff
+with a standalone pixelmatch script if you want the diff image saved as an
+artifact for the completion report.
+
+## Why the knobs, not zero-diff
+
+Pixel diffing is literal: it can't tell a real layout regression from a harmless
+anti-aliasing or subpixel-font difference, which is the main source of flaky
+"failures." So:
+
+- **`threshold`** (0–1, default 0.2) — per-pixel color sensitivity. Leave near
+  default; drop only when chasing a genuine color mismatch.
+- **`maxDiffPixelRatio`** — fraction of pixels allowed to differ. This is your
+  main dial. Start ~0.02 and tighten as the clone converges. A whole section
+  shifted will blow way past it; font AA won't.
+- **`mask`** — the GPU regions. Non-negotiable: without it, a single animating
+  shader frame makes every run "fail" and hides the DOM regressions you care about.
+- **`animations: 'disabled'`** — freezes CSS transitions so the DOM frame is
+  deterministic. (It does not stop a canvas rAF loop — that's why GPU regions are
+  masked, not just frozen.)
+
+## Verifying the GPU regions (separately)
+
+Masked out of the diff, so check them by behavior, not by pixel equality:
+
+1. **Renders at all** — the canvas is non-blank after load (sample a few pixels;
+   if cross-origin blocks readback, verify visually via screenshot).
+2. **Animates** — frames change over ~500ms (`isCanvasAnimating()` in
+   `scripts/surface-map.js`).
+3. **Responds** — if the original reacts to pointer/scroll, the clone does too.
+4. **Fidelity label** — carry luckiest-website-cloner-shaders's SOURCE / PARTIAL / approximate
+   verdict into the report. A masked region that "passes" the DOM diff has NOT
+   been proven faithful — only excluded. Say so honestly.
+
+## Reporting
+
+For each breakpoint: diff pass/fail, `maxDiffPixelRatio` achieved, and a link to
+the saved diff image. For each GPU surface: renders / animates / responds + the
+fidelity label. This is the evidence the clone is done — not a vibe.
+
+## Harness gotchas (learned the hard way)
+
+- **Don't set `reducedMotion: 'reduce'`** in the QA context. It changes the
+  ORIGINAL's JS behavior (sites branch on it), so heights and content diverge
+  and you chase phantom diffs. Freeze motion with injected CSS instead
+  (`animation-play-state: paused; transition: none`).
+- **`waitUntil: 'networkidle'` hangs against a Vite dev server** (HMR socket).
+  Use `domcontentloaded` + a fixed settle, then a full scroll-through so lazy
+  content loads before you measure.
+- **Measure both pages the same way.** Section heights differ between a fresh
+  load and a session that already scrolled (lazy images, fonts). Always scroll
+  top→bottom→top on both before comparing offsets, and compare fresh-load to
+  fresh-load.
+- **First check heights, then pixels.** Dump `[selector, top, height]` for every
+  section on both pages; a 0 px delta down the whole list means the DOM track is
+  right and any remaining diff is behavior/timing. A delta localizes the bug to
+  one section instantly.
+- **Per-viewport slices beat one fullPage shot.** Screenshot every 900 px of
+  scroll and diff slice-by-slice; the report then says *where* it's wrong
+  (`y=19800 16%`) instead of one useless global number. Fixed chrome (header)
+  shows in every slice — a header bug looks like "every slice over section X
+  fails", which is itself the diagnosis.
+- Mask GPU canvases **and** anything time-driven (marquees, morphing counters)
+  — they're verified separately, not diffed.

package/skills/luckiest-website-cloner/scripts/build-bundle.cjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// Concatenate the probes into one injectable file and EXPORT them onto window.
+// Playwright's addInitScript / addScriptTag wrap code in a function scope, so
+// bare `function` declarations are NOT globals — the explicit export is required.
+const fs = require('fs'), path = require('path');
+const strip = (s) => s.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '').replace(/^\s*[\r\n]/gm, '');
+const files = ['surface-map.js', 'motion-probe.js', 'tokens-probe.js'];
+let out = files.map((f) => strip(fs.readFileSync(path.join(__dirname, f), 'utf8'))).join('\n');
+out += '\n;(function(){ const g = typeof window !== "undefined" ? window : globalThis; Object.assign(g, { instrumentGetContext, surfaceMap, isCanvasAnimating, instrumentMotion, motionProbe, motionSummary, tokensProbe }); })();\n';
+const dest = process.argv[2] || path.join(__dirname, 'probes.bundle.js');
+fs.writeFileSync(dest, out);
+console.log(dest, out.length, 'bytes');