[tmashara]

Part of #59. This PR takes the remaining small, root-cause items from that feedback. The rest is either already fixed on main or should be split out (lists at the end).

Changes

• Heartbeat. When output is piped, stderr gets renderdiff: n/N shots every tenth of the run, plus one at the end. Stdout's compact summary is unchanged. SKILL.md now says to run long runs in the background and watch these lines. --help, README and reference.md are updated.
• Origin dies mid-run. When a shot errors with ERR_CONNECTION_REFUSED, renderdiff checks both origins again with the preflight's alive(), which moved to config.ts so cli and run share it.
  • If one is down, a shared down flag stops every worker's loop. A queue.push retry can't revive the run, because the loop checks the flag, not the queue.
  • The browser still closes, and renderdiff exits 2 with ✗ right (<url>) stopped responding mid-run.
  • This happens before saveRecording, so no partial --cache-right HAR is saved, and before any report is written.
  • A refused third-party URL can't trigger it.
• CSP.
  • Root cause: Playwright's addStyleTag runs inside _raceWithCSPError, so it rejects on any "Content Security Policy" console error logged while it injects. A site's own blocked analytics script is enough (docs/case-study.md); that's why these errors moved between routes and widths from run to run. A <style> is also subject to style-src.
  • Fix: renderdiff's CSS is now added as a constructed stylesheet in document.adoptedStyleSheets, through one helper used at both injection sites. CSP doesn't govern constructed sheets, and adopted sheets sort after the document's own.
  • One side effect: an @import in extraCss is ignored. That's noted on the option.
  • The case-study bullet now gives the cause and the fix.
• Height ceiling. The ceiling now tests the area actually shot (clip ?? page), so --selector or @sel on a very long page compares that element. An element that is itself past the ceiling is still refused (element is …).
• get.geojs.io is now in the default blocklist. It's a geo-IP lookup that decides whether a consent banner shows.
• results.json docs (reference.md and docs/output.md) say the per-line results sit inside one JSON document, with trailing commas.

Tests

• guardrails:
  • New fixture /csp: both sides send style-src 'self' and are styled only via /shared/base.css, and a consent banner is on the left only. The shot must compare with 0 diff pixels, which shows the hide selectors applied.
  • An inline right origin that dies after its first page: the run must exit 2, name the right side, and write no report.
  • /long @h1 at 1440 must compare.
  • The /hang fixture now wedges on the adoptedStyleSheets setter instead of a <style> mutation.
• controls: the piped run's stderr must end with renderdiff: 25/25 shots (the total), with 2–10 heartbeat lines.
• With the capture.ts change stashed, the CSP and selector-ceiling tests fail.

Verification: npm run typecheck, npm run lint and npm run format:check are clean. npm test passes 357/357 and npm run test:visual passes 389/389, both on macOS.

Already fixed on main since 0.5.0

• --computed origin normalization.
• Hung hooks and the shot deadline (Deadline per shot so a hung renderer can't hang the run #54).
• Retry of a goto timeout.
• Base-vs-base and suggested masks: the varies recheck (Recheck differing shots for load-to-load variation #47), probe (renderdiff probe: list elements whose box varies between loads #73) and grouped findings (Group identical pixel findings across routes and widths #48).
• Video seek (Video: after metadata, seek every video to 0, played or not #74).
• --sitemap (--sitemap: take routes from the reference's sitemap.xml #46) and the serve docs (Docs: serve static builds with serve.json (clean URLs, trailing slash, rewrites) #52).
• Page height re-read (Re-read page height in the lazy-load scroll pass #53).
• beforeShot (beforeShot hook: run after the scroll pass, right before the shot #71) and merge (renderdiff merge: fold a partial rerun into a full results.json #76).
• Stale files: the out dir is wiped on each run.
• Sharing: evidence.html is self-contained.

Left for separate issues

• A route's before chaining the global one (changes documented semantics).
• CLI routes reusing a config route's hooks, or warning.
• A route name or state field.
• waitFor and pinned iframe heights.
• A bounding box for unstable pixels, and folding small unstable counts.
• report --compact, WebP and gh-pages.
• --open over HTTP; renderdiff serve.
• --routes-file.
• --rerun-failed across config changes.
• A "lower --concurrency" hint on timeouts.

🤖 Generated with Claude Code