Configuration

Scanner environment variables

Variable	Default	Purpose
WPDIFF_TOKEN	dev-token	Bearer token for all authenticated endpoints. Always set your own value.
WPDIFF_DATA	./data (/data in Docker)	Root directory for snapshots and diff output

Capture behaviour

• Screenshots are full page, Chromium, 1440px viewport width by default. The width can be set per scan request.
• CSS animations and transitions are frozen before capture, and the page is scrolled once to trigger lazy loaded images.
• Requested motion libraries are paused and reset to their first slide, and HTML5 videos are paused, before the screenshot is taken.
• Elements matching the requested ignore selectors are hidden with their layout space preserved.
• Pages that fail to load are recorded in the run manifest with their error and skipped in diffs.
• Invalid TLS certificates are accepted during capture, so staging hosts with self-signed certificates can be scanned.

Diff thresholds

Threshold	Default	Where set	Meaning
Structural	0.95	per /api/diff request	Minimum normalised correlation for a region to count as structurally matched
Colour delta	14	scanner constant	Mean per channel difference above which a structurally matched region is still flagged

See How diffing works for what these control.

Storage layout

<data root>/<host>/
  runs/<run-id>/
    manifest.json          # url list, capture timestamps, failures
    pages/<slug>.png       # full page screenshots
  diffs/<from>_vs_<to>/
    summary.json           # per page results with changed boxes
    summary-debug.json     # written by debug diffs
    <slug>-baseline.png    # annotated screenshots for changed pages
    <slug>-current.png
    <slug>-dbg-*.png       # pipeline stages, debug diffs only
    <slug>-dbg.json

Everything is plain files. There is no database, and deleting a directory is a safe way to remove a run or a cached diff.

WordPress plugin settings

Setting	Purpose
Backend URL	Scanner base URL
API token	Must match WPDIFF_TOKEN
Max pages per scan	Caps the URL inventory the plugin sends, 0 for no cap
Ignore selectors	Hidden during capture, one CSS selector per line
Email address	Alert recipient when a scan finds changes, sent with wp_mail
ntfy topic URL	Alert channel on ntfy.sh or a self-hosted ntfy server
Developer mode	Requests debug diffs and shows the pipeline panel