Visual Debug

Automated post-implementation visual comparison — original vs implementation. Zero vision tokens via AE/SSIM CLI tools.

Primary trigger: Diagnose post-implementation mismatch between a reference and an implementation, then provide concrete repair guidance. Non-goals: Do not use this to build or regenerate the React component, orchestrate a full live URL clone, or perform baseline/reference capture; route build/clone work to ui-reverse-engineering and capture/reference work to ui-capture.

Boundary and handoff

• Direct invocation: Use when reference/implementation evidence already exists and the user asks for mismatch, diff, diagnosis, comparison, or repair guidance.
• Routed invocation: ui-reverse-engineering may route here after a failed visual diff, failed post-implementation gate, or completed-state mismatch request.
• Missing evidence: If baseline/reference capture is missing, return to ui-capture first; if implementation or regeneration is needed, return to ui-reverse-engineering or the active caller pipeline.
• Return contract: Send the caller concrete findings: failing artifact, mismatched selector/region, likely root cause, recommended fix, and verification command. visual-debug diagnoses and guides; the caller owns implementation, build, regeneration, and full clone orchestration.
• Evidence-pack first: If brief/WORKER_BRIEF.md or evidence-pack.json exists under the ref dir, read the brief before raw diff/DOM/style artifacts. Use the pack as a compact selector/bbox/style/trigger index and open only the named drill-down paths needed for the failing hotspot.

When to use

• After implementing a section, before declaring "done"
• When user says "it's different", "doesn't match"
• After ui-reverse-engineering reports a failed visual diff or post-implementation gate
• Instead of Read-ing screenshots for comparison

HARD RULE: Never Read ref/impl images for comparison. For FAIL positions, use auto-diagnose.sh first (zero vision tokens). Only Read diff images as fallback if auto-diagnose finds nothing. Exception: Phase E reads ref+impl pairs, and Phase E must run in a delegated subagent context so its 44K vision tokens stay out of the main context (see Phase E section).

Browser cleanup rule (MANDATORY at end of every run): agent-browser --session <name> close for each session you opened. Never close --all because other agent-browser sessions may own active browsers. The detailed section near the end of this file may be clipped after auto-compaction; this one-liner is the survival copy.

Token rule

Pipe large eval output to a file, then Read only what you need:

agent-browser --session <s> eval "<script>" > tmp/ref/<name>.json

Never let large JSON print to stdout — it wastes tokens.

Dependencies — preflight (run once per session)

npx skills add installs the SKILL files but skips system tooling. Run this check at session start; if anything is missing, halt and surface the bootstrap one-liner to the user (do not auto-execute a remote installer on their behalf).

miss=""
for c in agent-browser ffmpeg dssim; do command -v "$c" >/dev/null 2>&1 || miss+=" $c"; done
{ command -v magick >/dev/null 2>&1 || command -v convert >/dev/null 2>&1; } || miss+=" imagemagick"
if [ -n "$miss" ]; then
  printf 'Missing system deps:%s\n\nFastest fix:\n  tmp=$(mktemp) && curl -LsSf -o "$tmp" https://raw.githubusercontent.com/voidmatcha/ui-clone-skills/main/install.sh && bash "$tmp" && rm -f "$tmp"\n\nOr install manually:\n  brew install ffmpeg imagemagick dssim   # macOS  (Linux: apt install ffmpeg imagemagick && cargo install dssim)\n  npm i -g agent-browser\n' "$miss"
  exit 1
fi

Scripts

SCRIPTS_DIR="${VISUAL_DEBUG_SCRIPTS_DIR:-}"
if [ -z "$SCRIPTS_DIR" ]; then
  for root in "${PLUGIN_ROOT:-}" "${CODEX_PLUGIN_ROOT:-}" "${CLAUDE_PLUGIN_ROOT:-}" "${UI_CLONE_ROOT:-}" "$PWD" "$PWD/.." "$PWD/../.." "${INSTALL_DIR:-$HOME/.local/share/ui-clone-skills}"; do
    [ -n "$root" ] && [ -f "$root/skills/visual-debug/scripts/ae-compare.sh" ] && SCRIPTS_DIR=$(cd "$root/skills/visual-debug/scripts" && pwd) && break
  done
fi
[ -n "$SCRIPTS_DIR" ] || { echo "Set VISUAL_DEBUG_SCRIPTS_DIR or PLUGIN_ROOT" >&2; exit 1; }

Reference selectors: common-selectors.md — ready-to-use selector sets (typography, CSS reset canaries, Tailwind preflight issues, news/portal patterns, general e-commerce)

Cost ladder — cheapest detection first

The diff tools below have a 100x cost spread (sub-second to multi-minute, plus token cost when their output gets read). The most common avoidable waste is jumping to L3/L4 when an L1/L2 check would have answered the same question. Always start at L1 and stop as soon as a tier gives you the answer.

Read-summary-first rule (L1 specifics): scripts that write per-section/per-element detail also write a summary. Read the summary, then drill into detail files only for entries marked FAIL.

Reading a 50KB per-section JSON when result.txt would have answered the question is the single most common token waste in this workflow. If you don't see a summary file, that's a sign no run has been done yet — go to L2/L3, don't manually grep raw artifacts.

When borrowing ideas from a static design-evaluation harness, translate its "section mismatch ranking" into this summary-first flow. Avoid fixed y-coordinate bands or design-size assumptions in live-URL debugging; use section-compare.sh's semantic section matching and severity-sorted summaries, then drill into only the failing sections.

Pick the right diff tool

Five computed-style/geometry diff tools exist; each answers a different question. Run the targeted tool first, then escalate if the answer is "nothing wrong" but AE still fails.

Heuristics:

• tree-diff and layout-tree-diff are siblings, not redundant — first asks "is the style right on this element?", second asks "is this element in the right place?". Run tree-diff first; if it's clean and AE still fails, run layout-tree-diff.
• transition-compare.sh is the predefined-set hover gate (Step 8c of ui-reverse-engineering); hover-tree-diff.sh is the impl-side exhaustive hover gate in comprehensive plans and remains a manual escalation elsewhere. Use it when transition-compare reports PASS but the impl still feels wrong, or when you suspect extra hover motion on elements the ref leaves static. If a site stamps one class on many controls, rely on the semantic pairing report (matchKey in transitions/*-elements.json) instead of forcing a generic selector match.
• transition-spec-coverage.sh and reveal-trigger-check.sh are the first two transition gates, not escalations — run them before transition-compare.sh. Coverage catches "entry never wired", reveal-trigger catches "wired but stuck". transition-compare.sh only verifies idle→hover diffs, so it can pass while intersection/scroll-driven entries are completely broken.
• Scroll state-machine proof: when bundle/spec evidence contains window.scrollTo, scrollYProgress, setTimeout, velocity / getVelocity, a guard ref around scroll-stop logic, or ScrollTrigger pin/scrub, do not accept a single endpoint frame. Require initial → active/expanded → settled/returned proof and run scroll-state-machine-check.sh before declaring the transition matched.
• Don't run all five by default — they are slower and noisier than the standard auto-diagnose workflow.

Workflow

Step 0-pre: pass the chrome-hidden impl URL to every script

Before running ANY compare script (stray-absolute-check, section-compare, transition-compare, batch-compare, auto-diagnose), confirm the impl shell is not painting fixed-position chrome that the ref doesn't have — dev banners, attribution / "made with X" badges, Vite/Next dev-overlay buttons, devtools widgets, locale switchers, env labels. Any element with position: fixed and a non-trivial bounding box will dominate AE in its corner every frame, turning a passing clone into FAIL while the diff image points at the chrome — not at any code you wrote.

Quick scan:

agent-browser --session <s> open <impl-url>
agent-browser --session <s> wait 1500   # let chrome (dev banners, badges) mount
agent-browser --session <s> eval "
(() => {
  const fixed = [...document.querySelectorAll('*')].filter(el => {
    const st = getComputedStyle(el);
    if (st.position !== 'fixed') return false;
    const r = el.getBoundingClientRect();
    return r.width >= 40 && r.height >= 20;
  }).map(el => ({ tag: el.tagName.toLowerCase(), id: el.id, cls: (el.className && el.className.toString) ? el.className.toString().slice(0,80) : '', w: el.getBoundingClientRect().width|0, h: el.getBoundingClientRect().height|0 }));
  return JSON.stringify(fixed);
})()
" > tmp/fixed-scan.json

Pipe to a file (per the token rule) — chrome scans are small but writing through Read keeps the pattern uniform.

If the scan returns elements that don't exist on the ref, the impl needs a hide-mechanism (query flag like ?embed=true, env var like NEXTPUBLICHIDECHROME=1, dev-only NODEENV guard, CSS display:none injected via a fixture stylesheet). Standardize on one and pass the hidden URL to every script. Document the flag in the impl repo's CLAUDE.md so it survives compaction.

Failure signature when you forget: AE delta image shows a clean rectangular hotspot in one corner (top-right, bottom-right, etc.); auto-diagnose.sh reports the badge element as the only mismatch; section-compare passes for every section except the one that includes the chrome's vertical band. Fix is a query-flag swap, not a code change — verify before opening any source file.

Step 0: structural checks FIRST (before AE)

Always run structural checks before pixel comparison. AE catches that something is wrong; structural checks catch why — and fix the root cause immediately without hunting through diff images.

SCRIPTS="$SCRIPTS_DIR"

# 0a. Stray absolute positioning — catches the "footer disappeared" bug class.
#     Run on EVERY viewport you care about; the bug often only manifests on shorter pages.
bash "$SCRIPTS/stray-absolute-check.sh" <session>-stray <impl> 375 812
bash "$SCRIPTS/stray-absolute-check.sh" <session>-stray <impl> 1280 800

# 0a-bis. Stuck reveals — catches the IO+overflow:hidden bug class. Mandatory if
#         the spec has any `intersection`/`inview` trigger entries.
bash "$SCRIPTS/reveal-trigger-check.sh" <session>-reveal <impl> 1280 800

# 0a-quater. Breakpoint collision — catches the "broken at exactly 768" bug class.
#            Mandatory whenever impl mixes Tailwind responsive utilities AND a
#            project-scoped @media (max-width: <bp>px) rule (root font-size,
#            container padding, mobile-only stack). One run sweeps every Tailwind
#            boundary ±1; cheap (single page load, ~15 viewport sets).
bash "$SCRIPTS/breakpoint-collision-check.sh" <session>-bp <impl>

# 0a-ter. Spec coverage — every transition-spec entry must have an impl artifact.
#         Mandatory before per-trigger verification (transition-compare etc.) so
#         entirely-missing entries are caught BEFORE you waste a hover sweep.
bash "$SCRIPTS/transition-spec-coverage.sh" tmp/ref/<component> <impl-src-dir>

# 0b. Broad sweep: CSS reset canaries + page structure
bash "$SCRIPTS/computed-diff.sh" <session> <orig> <impl> \
  "h1" "h2" "h3" "h4" \
  "img" "button" "a" \
  "body" "header" "main" "footer"

# 0c. Domain-specific selectors from common-selectors.md
# IGNORE_FONT_SIZE=1 to skip OS text-scaling false positives
IGNORE_FONT_SIZE=1 bash "$SCRIPTS/computed-diff.sh" <session> <orig> <impl> \
  "[class*=title]" "[class*=logo]" "[class*=search]" "[class*=nav]"

See common-selectors.md for ready-to-use selector sets by domain.

Full-page comparison (broad sweep)

0. Structural    stray-absolute-check.sh + computed-diff.sh (CSS reset canaries + page structure)
1. Capture        batch-scroll.sh <orig> <impl> <session>
2. AE diff        batch-compare.sh <dir>
3. DSSIM          dssim-compare.sh <dir>
4. Diagnose       auto-diagnose.sh <session> <orig> <impl> <diff.png>
                  → auto-finds mismatched elements, runs computed-diff with severity
                  → zero vision tokens. Only Read diff image if auto-diagnose finds nothing.
5. Fix            Targeted code change (critical severity first)
6. Re-compare     Repeat 0–3
7. LLM review     Read ref+impl pairs for ALL positions (Phase E)
8. Gate           All axes PASS → DONE

Section-level comparison (precise — preferred for post-gen verification)

0. Structural    stray-absolute-check.sh + computed-diff.sh (CSS reset + section selectors)
1. Section compare  section-compare.sh <orig> <impl> <session> "$(pwd)/tmp/ref/<component>"
   → Per-section AE + severity (critical/major/minor) + structure diff
   ⚠️  The 4th argument (ref dir path) is MANDATORY — the Stop gate reads result.txt from that
       exact path. Omitting it writes result.txt to the wrong location and the gate never clears.
2. Transition compare  transition-compare.sh <orig> <impl> <session>
   → Per-element idle/hover style + timing diff
3. Diagnose     For FAIL sections: auto-diagnose.sh <session> <orig> <impl> <diff.png>
                → auto-finds mismatched elements within that section (zero vision tokens)
4. Fix          Targeted code change (critical severity first, then major, skip minor until Phase E)
5. Re-compare   Repeat 0–2
6. Gate         All sections PASS + all transitions PASS → DONE

Use section-level for ui-reverse-engineering Step 8b/8c. Use full-page for standalone /visual-debug invocations.

ONLYIFCHANGED=1 (skip if impl unchanged): when re-running section-compare during iteration, set ONLYIFCHANGED=1 + IMPLSRCDIR=<path-to-impl-source> to short-circuit if no .tsx/.jsx/.ts/.js/.css/.scss file has changed since the last run. The prior sections/result.txt stays in place (Stop gate passes against it).

ONLY_IF_CHANGED=1 IMPL_SRC_DIR=~/projects/foo/src \
  bash $SCRIPTS/section-compare.sh <orig> <impl> <session> "$(pwd)/tmp/ref/<c>"

Hash is SHA-256 of (sorted paths + content) — mtime-resilient. Delete <ref-dir>/sections/.last-impl-hash to force a full run. Use this for the second/third/Nth re-run after a fix; skip it on the first run after extraction (no prior result.txt to reuse).

Escalation diagnostics (when the standard workflow misses the bug)

The standard workflow (AE + DSSIM + auto-diagnose.sh + computed-diff.sh) catches most mismatches. When AE keeps reporting failures but auto-diagnose returns clean — escalate to the tree-diff family. These walk every element on the page rather than a fixed selector list, so they catch what targeted diagnostics miss.

bash "$SCRIPTS/tree-diff.sh"        <session> <orig> <impl>   # full-element style diff
bash "$SCRIPTS/layout-tree-diff.sh" <session> <orig> <impl>   # geometry deltas
bash "$SCRIPTS/hover-tree-diff.sh"  <session> <orig> <impl>   # hover style + timing
bash "$SCRIPTS/keyframes-diff.sh"   <session> <orig> <impl>   # @keyframes declarations

These are diagnostic, not gate-blocking. Use them when section-compare / transition-compare keep failing without a clear cause — they produce a markdown report (severity-sorted) that names the culprit elements and properties. Do not run all four by default — they are slower and more expensive than the standard workflow.

Three-axis verification (ALL required)

A position is PASS only when all three agree (or LLM explicitly approves a known difference).

Phase E: LLM Review (MANDATORY)

NOTE: Quick comparison (Phases A-D) uses zero vision tokens via AE/SSIM diff. Phase E (LLM verification) is mandatory for full verification workflow and DOES use vision tokens for the final review.

After AE + DSSIM, read every position's ref+impl pair. Judge PASS / PARTIAL / FAIL. Not optional — automated metrics can silently pass wrong results. ~44K tokens.

Always delegate Phase E to a subagent context. In Claude Code-style hosts, prefer the plugin's subagenttype: "ui-clone-skills:visual-debug-reviewer" — it pins model: opus so vision verdict quality is consistent regardless of the parent agent's model. In Codex/OMX hosts, use the Codex native subagent visual-debug-reviewer backed by .codex/agents/visual-debug-reviewer.toml. As a fallback, subagenttype: "general-purpose" or an inline fallback works but may inherit the parent's model (lower-tier defaults can degrade Phase E judgment). Other hosts should use their equivalent delegated-worker mechanism with an opus-equivalent model. The 44K vision tokens stay in the subagent context, and only the verdict table (~500 tokens) returns. See comparison-fix.md Phase E section for the example invocation.

Thresholds

AE=500 allows anti-aliasing variance. Bump to 2000 for dynamic content.

Dynamic content (canvas/video) — EXCLUDE_DYNAMIC=1

RAF-driven canvases (Three.js shaders, particle fields) and <video> elements run on independent clocks in ref vs impl, so their per-frame pixel diff is unmatchable — they dominate AE without indicating a real defect.

section-compare.sh accepts an opt-in mask:

EXCLUDE_DYNAMIC=1 bash section-compare.sh <orig> <impl> <session> "$(pwd)/tmp/ref/<component>"

When set, the script injects visibility: hidden !important for the masked selectors into both ref and impl screenshots — identical hide rule on both sides, so layout is preserved while the noisy region drops out of AE.

Spec-driven (recommended): add "dynamic": true to every transition-spec.json entry whose visual is RAF-driven (auto-timer canvas, looping shader, <video> autoplay). Then EXCLUDE_DYNAMIC=1 masks them all without enumerating selectors at the call site.

Selector caveat: Selectors must not contain quote characters of either kind. " would close the injected JS string and ' would close the surrounding Python r-string. Use bare attribute matchers (e.g. [data-canvas=hero]) or class/id selectors (e.g. .canvas-hero, #hero-canvas). The script aborts if it sees " or '.

Full verification

• verification.md — Phase A/B (capture) + D (pixel-perfect gate) + auxiliary checks
• comparison-fix.md — Phase C (AE+DSSIM comparison, computed-style diagnosis, Phase E LLM review, Phase H self-healing loop)

Browser cleanup (MANDATORY)

Every skill run MUST end with browser cleanup — success, failure, or interruption.

# Always close your own session(s) by name
agent-browser --session <session-name> close

• Close every --session <name> you opened during the comparison
• Run cleanup before returning control to the user, even on error/early exit
• Unclosed sessions spawn Chrome Helper processes (GPU + Renderer) that persist indefinitely
• Never use close --all because other agent-browser sessions may have active browsers. Only close sessions you own.

Bulk cleanup helper (multi-session sweeps): if a long verification run accumulated many ad-hoc sessions under a common prefix, use scripts/verify/cleanup-sessions.sh <prefix> (dry-run with --dry) to close them all in one pass. Refuses prefixes shorter than 3 chars; never matches across other agent-browser sessions.

Integration

visual-debug owns comparison and diagnosis only. After it identifies a fix target or a PASS/FAIL result, resume the caller's pipeline (ui-reverse-engineering, ui-capture, or standalone task) for implementation, regeneration, and the next gate.