Diff

stardust:diff — prototype ↔ build reconcile

Two probes that compare a source prototype against a built page. They catch disjoint failure classes — run BOTH; either alone gives a false "looks fine".

Both are framework-agnostic Playwright probes that compare two rendered URLs by computed style + DOM (not pixels). All stack-specific language lives in a profile (--profile eds|generic); the comparison logic is generic.

When to use

• After converting a prototype to EDS (the stardust deploy skill's Step 10) — use --profile eds.
• Any "does the build match the design?" check between two rendered URLs (a Figma export vs a React build, a legacy page vs a rebuild) — use --profile generic.
• Inside a conversion/QA workflow as the validation gate (see Workflow use).

Not for: a single static file with no JS decoration (use the build/harness URL so components are decorated — a raw .plain.html has no roles to classify).

The two probes

content-diff extracts an ordered, role-classified inventory (heading / eyebrow / cta+href / body) from each root — the --main root(s) plus, by default, the header and footer chrome roots — classifying by computed style + tag so the prototype's DOM and the built DOM compare symmetrically, then diffs them root by root; a second inventory per root carries the placeholder / aria-label / title values and the icons.

Run it

# Prereq 0: playwright importable from the project root — probe
#   node -e "import('playwright').then(()=>process.exit(0))"
# and on failure install it AS A devDependency (npm i -D playwright pixelmatch pngjs cheerio
# --legacy-peer-deps — never --no-save: a --no-save install is PRUNED by the next real npm i,
# recorded twice in one run; extract SKILL.md § Setup). Run the copied scripts from the project
# root, not the plugin: ESM resolves `playwright` from the script's own location.
# Copy the WHOLE skills/diff/scripts/ dir: content-diff imports its local diff-profiles.mjs
# AND content-inventory.mjs. (The deploy gates #93/#94 now use their OWN synced copies in
# skills/deploy/scripts/ — A6/A2 are independent of this skill; the two copies must stay in
# sync until the diff-skill abrasion PR consolidates them.)
# Prereq: a RENDERABLE source. Static → serve from its own dir (python3 -m http.server).
# The build URL must be the DECORATED page (live/preview or a local harness), not raw markup.
# ONE server, ONE port — probe before starting one (curl is always present, lsof is not):
curl -sI localhost:8791/ | head -1                   # 200/404 = something serves the port; no line = free
curl -sI localhost:8791/<prototype>.html | head -1   # 200 = it serves YOUR dir: reuse it
command -v lsof >/dev/null && lsof -nP -iTCP:8791 -sTCP:LISTEN   # optional: names the pid
# Nothing answered → start yours. Answers but not your file → a foreign server: never kill
# a listener you did not start; prefer a per-project port — a stale server from another
# project makes both probes measure a foreign page. `lsof … || echo free` is not a probe —
# without lsof it prints "free" beside a live listener (recorded: a second server on the
# same port died at once and the round chased 404s).
PROTO="http://localhost:8791/<prototype>.html"
BUILD="https://<branch>--<repo>--<owner>.aem.page/<path>"   # or http://localhost:3000/<harness>

# 1. PIXEL/layout
node skills/diff/scripts/visual-diff.mjs   "$PROTO" "$BUILD" --profile eds --sections ".hero"

# 2. STRUCTURAL content + type
node skills/diff/scripts/content-diff.mjs  "$PROTO" "$BUILD" --profile eds   # --json dumps both inventories

Flags (both tools): --profile eds|generic (default eds), --width <px> (default 1280), --main <selector[,selector…]> (content root; content-diff defaults from the profile and takes a comma-separated list — every root is inventoried and diffed on its own and each finding line carries its root as [root]; visual-diff takes one selector, default main), content-diff only: --chrome / --no-chrome (default on — the header and footer roots, resolved as the first <header>/[role=banner] and <footer>/[role=contentinfo] outside the main root(s), are compared beside it; a side lacking one is measured as empty there and the root line says so), plus the live-target set (shared engine: scripts/live-session.mjs — every context sends the real-Chrome UA and the standard Chrome request headers; the UA alone still 403s on Akamai-class bot management):

• --ua <string> — user agent override (default: real-Chrome desktop UA).

• --wait-until <state> — goto wait override. Default rule (one shared defaultWaitUntil in scripts/live-session.mjs), decided per URL side, three tiers:

  • localhost/127.0.0.1 → networkidle (local prototypes / harnesses, unchanged);
  • EDS build/preview origins — hostnames ending in .aem.page, .aem.live, .hlx.page, .hlx.live → networkidle (they decorate asynchronously and reliably reach networkidle; measuring at domcontentloaded reads the pre-decoration DOM — flaky false reds / FONT FORK on deploy Step 10);
  • all other live http(s) → domcontentloaded (live sites with analytics beacons never reach networkidle).

  --wait-until overrides all three tiers.

• --dismiss [sel,...] — dismiss overlays on both sides: cookie consent (clicked, not removed) AND timed marketing/newsletter modals, plus optional extra site-specific selectors; the mouse is parked afterwards.

• --headed — escalation for bot-managed sites: headed stealth real Chrome.

• --locale <tag> — pin Accept-Language + context locale (geo-redirecting sites capture a different locale per run otherwise).

visual-diff also: --out <dir>, --sections a,b (per-section screenshots).

A bot-management challenge/blocked interstitial on either navigation fails LOUD with exit 3 — it is never measured as the source. Escalate with --headed; if that is still blocked, the site needs crawl.mjs-class capture and the check cannot run headless.

A plain (non-challenge) HTTP error on either side — e.g. a 404 build side, normal on aem.page before preview propagation — is NOT fatal: the probe logs a loud warning, measures the error page, and the flags (BLANK RENDER / content asymmetry) carry the signal with exit 0. That is the probes' advisory contract: 0 = ran (flags advisory), 1 = probe error, 3 = bot challenge.

The published-origin probes (#125)

content-diff reconciles a prototype with its build; against a LIVE commerce origin its per-node findings were false, and the pixel gate passed a page whose every card was clipped (../replica/reference/source-fidelity-gate.md § The all-pages published-origin gate). Three probes ask the checkable questions; all load both sides in the same window-free real-Chrome tier and settle them the same way (scripts/measure-live.mjs).

ORIGIN="https://www.example.com/<path>"; SERVED="https://main--repo--owner.aem.live/<path>"
node stardust/scripts/diff/clip-probe.mjs "$SERVED" [--json clip.json]                       # D1: exit 2 on cut / hidden text or controls
node stardust/scripts/diff/content-presence.mjs "$ORIGIN" "$SERVED" [--variable "<selO>=<selE>"]  # D2: exit 2 on MISSING/HIDDEN link or heading
node stardust/scripts/diff/unit-geometry.mjs "$ORIGIN" "$SERVED" --unit "<selO>=<selE>" --n 2      # D3: exit 2 on an element off / hidden / missing

Reading: a 🔴 clip group names the clipper (a fixed-height box with overflow: hidden) — fix that block's CSS, never the content. HIDDEN LINK = in the DOM but clipped (CSS); MISSING LINK = not served (encoder); CONTROL STATE = same control, another value; COUNT … = session-variable region, confirm by eye. The origin side fails loud on HTTP ≥ 400 (exit 4) and a bot challenge (exit 3). Traps: an infinite-scroll origin keeps loading under the settle — mark the region --variable; a live origin without <main> compares whole page against whole page (the scope line says so), header / footer left to the chrome crop gate unless --chrome; the count-phrase and "read more" heuristics are English word lists (--count-words, --more-words).