Redesign an existing website to make it better. Built on top of impeccable.
88%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Low
Low-risk findings worth noting
The gate proves an archetype matches the LIVE site — three instruments, per breakpoint, with a hard iteration cap. It replaces the redesign pipeline's craft gates entirely: an archetype ships because it measured true, never because it looked right. Every fix in the loop comes off the instruments; eyeballing is not an input.
| Probe | Script | Catches | Blind to |
|---|---|---|---|
| Structural content + type | ../../diff/scripts/content-diff.mjs (project copy) | dropped/mis-slotted headings·eyebrows·CTAs, invented/dropped copy, rendered-face font forks (width probe); dropped placeholder/aria-label values, missing/wrong/moved icons — on the main root AND the chrome roots (header, footer) by default | geometry |
| Visual heuristics | ../../diff/scripts/visual-diff.mjs (project copy) | stretched images, dropped wraps, blank renders, surface/ground flips | "right text, wrong slot" |
| Pixel (replica-owned) | ../scripts/stitch-shot.mjs + ../scripts/pixel-compare.mjs | everything the other two abstract away: paint effects, scrims, exact geometry, image crops | semantics (a wrong-but-same-colored word) |
Run ALL three — they catch disjoint failure classes; any one alone gives a false "looks fine".
Breakpoints: 1440 AND 360 by default (--breakpoints; plus each target
step when one is set — § Target breakpoints). Mobile is not
free: UC1-E1's gate-passing 1440 prototype measured 24.2% / height Δ
−1572px at 360. Each breakpoint is its own full gate pass with its own
iteration budget. Gate 1440 first (the geometry lifted from desktop CSS),
then 360.
# Serve the prototype from its own dir so relative assets resolve. ONE server,
# ONE port — probe with curl before starting one (lsof is optional, often absent):
curl -sI localhost:8791/ | head -1 # 200/404 = something serves the port; no line = free
curl -sI localhost:8791/<slug>-proposed.html | head -1 # 200 = it serves YOUR dir: reuse it
# Answers but not your file → foreign server: never kill it, take a per-project port. gate.sh asserts
# a page marker (exit 4); on shared machines pass --marker "<brand string>" (a shared slug false-passes).
(cd stardust/prototypes && python3 -m http.server 8791 &) # only when nothing answered
PROTO="http://localhost:8791/<slug>-proposed.html"
LIVE="https://<site>/<path>"
W=1440 # then 360
GATE="stardust/replica/gates/<slug>-$W"
# 1. structural — --dismiss: rule 6's overlay dismissal, both sides.
# The header and footer roots are compared beside --main BY DEFAULT — this is
# the whole command, no chrome flag; the report has one block per root and a
# finding reads "[header]" / "[footer]" where it sits (--no-chrome = main only)
node stardust/scripts/diff/content-diff.mjs "$LIVE" "$PROTO" --profile generic --width $W \
--main "<content-root>" --dismiss | tee "$GATE/content-diff-iter<N>.txt"
# 2. visual heuristics — --main is a real flag here too (live sites often
# have no <main>; without it both sides false-flag BLANK RENDER)
node stardust/scripts/diff/visual-diff.mjs "$LIVE" "$PROTO" --profile generic --width $W \
--main "<content-root>" --dismiss --out "$GATE/vdiff" | tee "$GATE/visual-diff-iter<N>.txt"
# 3. pixel — stitched captures on BOTH sides (never fullPage:true); a consent manager the
# built-in candidates miss: the same --consent "<accept selector>" on both (rule 6)
node stardust/scripts/replica/stitch-shot.mjs "$LIVE" "$GATE/live.png" --width $W --settle
node stardust/scripts/replica/stitch-shot.mjs "$PROTO" "$GATE/proto.png" --width $W
node stardust/scripts/replica/pixel-compare.mjs "$GATE/live.png" "$GATE/proto.png" \
--out "$GATE/diff-iter<N>.png" --threshold 10On a geo-redirecting site add --locale <tag> to all three (a live side that
redirects to a different locale per run is a nondeterministic source); on a
bot-managed site that exits 3, escalate with --headed (§ Hardening rule 1).
The live capture is taken ONCE per breakpoint per full gate run and reused across iterations — re-take it only if it is genuinely stale (site changed, capture hardening changed). This is a bot-block control, not just a cost note: content-diff + visual-diff each navigate the live URL per run, so a full 3-iter, 2-breakpoint gate is already ≈12–18 live hits, and hard-CDN sites (recorded: an Akamai-defended luggage retailer) escalate to an IP block after a handful. The prototype capture is re-taken every iteration.
content-diff, two tiers, on the main and chrome roots (each finding
names its root): looks the same = 0 🔴; nothing lost = 0
nothing-lost 🟡 (a lost aria-label, sr-only text or heading — invisible,
still a defect). gate.sh fails on either (Tiers:). Look-neutral changes
are accepted, never findings; other 🟡 and 🟠 are advisory, confirmed
intended (a substituted licensed font is a permanent justified 🟠 —
ledger it once). An owner's per-change decision, with its reason, is one
entry in stardust/replica/accepted.json: content-diff and chrome-parity
print it 🟢, uncounted (schema and matching: their --help). An entry
without text accepts EVERY finding of its kind — always give one.
Cite the round's verdict-<label>.json — it names the evidence file of
every verdict.
visual-diff: flags none or justified — HEADING FACE included: a
licensed-font substitution is one ×N line, justified once like the 🟠
fork. A live page's own quirks are justified when the prototype mirrors
them (e.g. a 1×1 SEO h1 at x0, a carousel tile at a negative offset —
both real UC1-E1 justifications).
pixel diff ≤ 10% full-page — AND no band left unexplained (§ Band breakdown). 10% is the ship bar, not the target; the validated run landed at 1.31%.
height delta: |Δ| ≤ 8px — pixel-compare's own warning threshold is the bar (it prints ⚠ above 8px), so a −9px result is unambiguously a residual, not a pass. A large delta invalidates the % — the overlap crop silently discards the tail, so a short prototype can score deceptively well. Fix heights before trusting anything else.
Chrome crop gate: header band AND footer band each ≤ 2% diff (≥98%
match, #115). The full-page bar dilutes the chrome — header/footer are
a small share of page pixels but carry disproportionate visual weight
and repeat on every page of a rollout. Two field runs shipped
full-page-green pages whose chrome measured only 93–97% (lookalike
icons, wrong micro-weights, off-by-10px nav rows all fit inside a ≤10%
full-page bar). Run ../scripts/crop-compare.mjs over the SAME stitched
captures the pixel probe used — no extra live hit — once per breakpoint
($GATE is per width), header band then footer band:
B="$GATE/proto.png" # $GATE/build.png when gate.sh took the round's captures
NAV_H=<header bottom edge> FOOTER_H=<footer height>
LIVE_H=<live capture height> PROTO_H=<prototype capture height>
node stardust/scripts/replica/crop-compare.mjs "$GATE/live.png" "$B" \
--y 0 --height $NAV_H --threshold 2 --out "$GATE/chrome-header-diff.png"
node stardust/scripts/replica/crop-compare.mjs "$GATE/live.png" "$B" \
--y $((LIVE_H - FOOTER_H)) --y-b $((PROTO_H - FOOTER_H)) --height $FOOTER_H \
--threshold 2 --out "$GATE/chrome-footer-diff.png"Exit 2 = that band is over 2%. --y-b aligns the footer crop per side so
a small doc-height delta does not read as a false full-band diff. The
four numbers, none of them a new live hit:
NAV_H — the live header's bottom edge, rect.y + rect.h (y is 0 unless
a strip sits above the header): data.header.rect in
$GATE/chrome-live.json, the live cache gate.sh --full and
chrome-parity.mjs --live-cache write (json-query.mjs $GATE/chrome-live.json --path data.header.rect); no cache yet →
measure.mjs "$LIVE" --selectors header --width $W (one live hit).FOOTER_H — the h on the y … h … footer line anchor.mjs prints per
side (--json field footer: [y, h]; live side cached in
$GATE/anchor-live.json under data.footer). That line's y IS
docH − footerH while the footer is the last box — pass it straight to
--y / --y-b when you have it.LIVE_H, PROTO_H — the capture heights on pixel-compare's first verdict
line, A <w>x<h> B <w>x<h> → compare …, height delta …px
(run-bg.mjs wait surfaces it; stitch-shot's stitched <file>: <w>x<h>
line is the same number per side).Styles diagnose, pixels confirm — run the computed-style parity probe
BEFORE any pixel iteration on chrome. ../scripts/chrome-parity.mjs
probes the same regions on live and build (default header + footer;
add sticky strips with --region strip=<liveSel>|<buildSel>), pairs
every text-bearing element by its text, and prints only what differs:
family / size / weight / style / line-height / letter-spacing /
transform / colour / background (the painted one) / padding / radius,
the element rect, the clickable box of links and buttons, and the icon
inventory (count + size, paired by order; the same pixels are the same
icon). A page with no <header> gets its top bar auto-detected (the line
names it); a region moved as one block by the page above is one advisory
OFFSET line. Fix every delta, re-run until it is quiet (exit 0), THEN
crop-compare — a pixel loop on chrome with parity deltas outstanding is
wasted iterations. Each run is one live navigation (budget it like any
live probe); --json records both sides as the round's evidence.
node stardust/scripts/replica/chrome-parity.mjs "$LIVE" "$PROTO" --width $W # + --region strip=<sel>|<sel>Glyph-dense chrome has a pixel noise floor — the ONE justified way past
the 2% bar, and it is evidence-gated three ways. A footer of ~50 links
bottomed out at ~5% pixel diff with family, size, line-height, weight,
colour, pitch and positions all numerically identical (recorded): per-glyph
antialiasing between a hinted licensed face and the self-hosted webfont
dominates, and raw pixel bars over-iterate against noise. A chrome band
that FAILS crop-compare may be logged as a justified residual —
never a pass — only when ALL three hold, and each is an artifact in the
residual entry (§ Residual logging format, cause: "glyph-antialiasing"):
(1) chrome-parity.mjs exits 0 for that region at tolerance 1px — every
paired text's metrics and position match, no MISSING/EXTRA, icons paired;
(2) crop-compare.mjs reports the diff texture as thin-edge (≤15% of
differing pixels have ≥5 differing neighbours) — glyph antialiasing is
thin, misalignment and missing paint are thick; (3) the region is
text-dense (link columns, nav rows) — a band with imagery or icons never
qualifies (parity's ICONS finding would not be quiet anyway). One or two
of the three is not enough: a quiet parity probe with a THICK texture is
a paint defect the probe does not model; a thin texture with parity
deltas is a real metric error hiding in noise. The 2% bar itself is
unchanged, and the residual is re-verified every gate round like any
other justified flag.
Chrome crops are ELEMENT-ANCHORED per side, never fixed-y — and
"chrome" means every site-wide repeating band: header, sticky/quick-link
strips, footer. Recorded: the header measured 33.9% and a quick-links
strip 19.2% while the full page passed at 6.5% — chrome is small-area,
highest-salience and repeats on every page. Two traps: (a) a fixed-y crop
produces FALSE reads the moment either side's rhythm shifts — a 35px nav
fix moved everything below it and the strip crop read 66% while the strip
itself, re-anchored to its own band edges, was at 1.6%. Locate each
region on EACH side (its element rect via anchor.mjs, or its band
edges via row-profile.mjs's column scan) and pass both anchors
(--y/--y-b); every gate round re-reads the anchors. (b) Regions whose
live content is authored-volatile — campaign heroes, promo creatives that
change between capture and gate — are masked out of the fidelity number
with pixel-compare.mjs --mask <yA:h[@yB]> (printed on the verdict line,
never silent): they are authored content, not conversion fidelity, and
chasing them burns iterations on a moving target.
Applied inconsistency-register entries create expected deltas: cross-
reference the entry ID (R-<nn>) when justifying a flag over its zone
(preserve-direction.md § Gate interaction).
Outside the numbered bar, and outside the iteration cap: the
horizontal-overflow assert. document.documentElement.scrollWidth is
within 4 px of the viewport width (GATE_OVERFLOW_TOLERANCE, integer
rounding) at every gate breakpoint on the build side, evaluated on the
published origin for a delivered page. It is not a bar item because a
bar item can be traded for a documented residual; this cannot
(§ Iteration discipline, the HARD assert). gate.sh runs it every round
and prints the verdict line; measure.mjs prints the number on its root
line for any ad-hoc read.
% identically, so
a build that renders edge to edge (recorded: live 1920 px shell + 1600 px
article, build token declared and never applied) or a frozen fluid value
passes them by construction. node stardust/scripts/replica/cap-probe.mjs "$LIVE" --against "$PROTO" --design DESIGN.json --slug <slug> --main "<content-root>" — one live navigation at DESIGN.json's probeWidth
(max(2560, largest cap × 1.25); a probe AT a cap's width cannot see it —
never pin 1920). Pass = every live cap held within ±20 px at the same
KIND (wrapper, then one module per top-level section — never by DOM depth,
EDS section wrappers are full width by design), nothing capped only on
the prototype; a ✗ names the sizing rule (deploy Step 3 scaffold; re-lift
per recreation-procedure.md § Lift the sizing MODEL), never a pixel
iteration. Evidence: stardust/replica/gates/<slug>-<probeWidth>/cap-<label>.{json,txt}.Calibration honesty — two fidelity regimes, one bar. The validated numbers above (1.31%, Δ0) describe the prototype regime: a standalone prototype gated against the live page, on a typographic page. Pages converted to the delivery platform and gated against the published origin (§ The published-origin gate) carry justified block-model deltas — control UI, split anchors, nondeterministic elements — and landed at 6.9–9.9% in the field while visually faithful. The ≤10% bar covers both regimes; what burns iteration caps is chasing prototype-regime numbers on a published-origin gate. Record which regime a number belongs to in the ledger, and judge each against its own regime's precedent.
stardust/replica/gates/prototypes-<w>/summary.md (gate-all --stage prototype, run at the end of Phase 4) or …/all-<w>/summary.md (delivery), with
its measured number, height delta, clipped count, verdict and evidence dir.
gate-evidence.mjs reads the table as the source of record: a page without a row is
ungated, whatever its sidecar or a gate.sh log says. Inside a --full round the
element probes rule a PASS the way the overflow assert does: clip-probe: Clipped: n
with n > 0 (every regime), a content-presence MISSING / HIDDEN link or heading
(published regime), a required repeated unit off (stardust/replica/units.json).Only when DESIGN.json extensions.breakpoints.target is set (replica
--target-breakpoints); otherwise nothing here applies.
--breakpoints plus every target step, each a full pass
(optionally step − 1: the band below a step is otherwise unmeasured).breakpoint-map.md row, the widths between the
source breakpoint and its step. There the build legitimately shows the
layout the source shows only past its own breakpoint.live-tier.png in the gate dir; compare by one crop each), or the only
difference is a uniform vertical offset from the chrome swap. Logged as
tierShift[] against the register entry (§ Residual logging format);
never iterated; outside the 3-iteration cap.clip-probe and content-presence are never classified tier-shift.--detail, progress.json). At the delivery gate
a tier-shift page gets an overrides.json row — {"<slug>": {"verdict": "tier-shift", "reason": "R-<nn>", "waives": ["pixel", "height"]}} — only
when clip and content pass; the measured number stays beside it.--nav-height is reserved per target step.The overall % hides WHERE drift starts. pixel-compare.mjs prints per-500px
bands (--band to change); read them top-down:
The section-anchor probe names the section the band table only points
at. ../scripts/anchor.mjs prints [y, height] per top-level section
(+ footer + doc height), same shape on both sides:
node stardust/scripts/replica/anchor.mjs "$LIVE" --width $W # once per fix round at most (live hit)
node stardust/scripts/replica/anchor.mjs "$PROTO" --width $W # free — build-side onlyDiff the two outputs, fix the FIRST section whose [y, height] disagrees
(top-down — everything below it is offset-contaminated, the same rule as
the band table), re-run pixels. Field-validated (a financial-services site, 8 pages): this
loop roughly halved iterations vs band-reading alone. ../scripts/gate.sh
wraps one full pixel round (stitch both sides — live cached — + compare +
verdict) in one command.
When a band stays hot and diff-iter<N>.png doesn't show why,
../scripts/diff-report.mjs <gateDir> <buildURL> names the block: the
differing share per block (EDS [data-block-name], else sections) and a
report.html with live | build | diff crops of the hottest ones.
Two row-level instruments replace eyeballing crops (../scripts/row-profile.mjs,
runs over the same stitched PNGs — no live hit):
node stardust/scripts/replica/row-profile.mjs live.png proto.png --columns 7. Recorded: a stacked-crop visual read suggested a 415px photo
with a white band under it; the scan of the same capture proved the photo
full-bleed to 499px with the "white band" being an overlapping card — the
wrong read cost two build/measure cycles. Crop eyeballing is hypothesis;
the scan is the measurement.--color <#rrggbb> lists every row run dominated by it on both sides and
pairs them in order: the per-pair delta is each landmark's offset, and the
CHANGE in delta between consecutive pairs (gapShift) names the one
inter-landmark CSS gap that absorbed the shift. Patch that gap, re-measure,
top-down — the same contamination rule as the band table. Recorded: three
passes driven this way took a page 16.9% → 11.05% and a 1559px height
delta → 48px. Do not tune margins by eye against crops. (Crop with pngjs;
macOS sips --cropOffset is unreliable for band crops.)Hard cap: 3 iterations per breakpoint. Matching the validated run's discipline — convergence happened within 3 with the recreation procedure followed; more loops mean the inputs were wrong (values eyeballed instead of lifted, capture unhardened), and the fix is upstream, not a fourth loop.
chrome-parity.mjs and clear its deltas (§ Pass bar,
item 5); style deltas are named in one pass, pixels only say where.curl --compressed <css-url> | grep '<new-rule>'; the CSS is
gzip-encoded, a bare curl | grep scans binary and silently matches
nothing) and re-render in a fresh headless context; and a reviewer's
screenshot encodes their zoom — back-compute their CSS viewport from any
element with a known percentage rule (a card at 851px under width: 50%
→ viewport 1702px) and reproduce THAT viewport headlessly before letting
their numbers overturn a fix.anchor.mjs, § Band
breakdown): run it on both sides, fix the first mismatched section
top-down, re-run pixels. Build-side anchor/computed-style passes never
navigate the live origin and are FREE — the cap governs live-gate cycles,
not measurement.document.documentElement.scrollWidth
no more than 4 px over the viewport width at every gate breakpoint,
evaluated on the published origin (GATE_OVERFLOW_TOLERANCE, default 4:
scrollWidth and clientWidth are integers, so a correct page whose widest
box is 360.4 px reads +1; the qa skill's rendered sweep fails above the
same 4 px — a real overflow is 13 px and up). A recorded hands-off run delivered two pages that rendered 373 px
and 400 px wide at a 360 viewport — accordion headers and a blockquote
overflowing, text clipped — and the gate logged |Δ| 19–26 px at 360 … logged, not iterated further (3-iteration cap reached) and passed them.
Horizontal overflow is not a residual class. gate.sh runs measure.mjs
on the BUILD side every round (no live hit) and reads its root line —
root scrollWidth <n> viewport <n> scrollHeight <n> ◄◄ OVERFLOW +<n>px
— so a build wider than its viewport prints gate.sh: OVERFLOW at <w> — build scrollWidth <n> > viewport <n> (+<n>px) → FAIL and the round exits 2
whatever the pixel number says; gate-evidence.mjs records FAIL: horizontal overflow +<n>px over a PASS pixel line and withholds
pixel-gate-<w>. No iteration cap, residual entry or register entry
waives it: a page whose scrollWidth exceeds the viewport at any gate
breakpoint is not verified, and the published-origin round (§ The
published-origin gate) is where it finally counts. Diagnose with
measure.mjs "$BUILD" --selectors "<candidates>" --width 360 --all-matches
— the box whose x + w exceeds the viewport; the recorded causes are a
desktop px width or min-width carried into the mobile pass,
white-space: nowrap, an unbroken string without overflow-wrap, a
content-box / border-box fork that adds padding beyond 100 %
(recreation-procedure.md § Box model is a lifted value), a negative
margin, 100vw on a page with a scrollbar. When the LIVE side itself
overflows at a breakpoint (the root line on side A says so), the replica
does not mirror the defect: register the fix as an inconsistency entry and
build without overflow — the assert holds on the build regardless.--full) a recorded
hands-off run saw about 8 of 62 sibling gate rounds end in build capture failed (exit 1) and read them as verdicts. gate.sh retries a capture
that exits 1 — live, build or the overflow probe — ONCE before declaring
anything (gate.sh: <step> exited 1 — retrying once); when both attempts
exit 1 the round exits 1 with (twice: no verdict — re-queue the round).
Treat it exactly like exit 124: start the same round again through
run-bg.mjs, count no iteration, never write it into the ledger as a
FAIL (gate-evidence.mjs records it OPEN: no verdict (exit 1)). Exit 3
(bot challenge) and 4 (identity) are final on the first attempt. Do not
raise RUN_BG_SLOTS to make room — the default 3 is the pacing that keeps
the retry rare; lower it on a small machine.chrome-parity.mjs --live-cache <gates-dir>/chrome-live.json and anchor.mjs --cache <gates-dir>/anchor-live.json (live URL only) write the live measurement
on the first run and reuse it while URL, width and selectors match —
delete the file to re-probe. On hard-CDN sites
(Akamai-class), take the live captures with --headed and treat further
live hits as spent budget — the recorded failure mode (luggage retailer) was an
IP-level block escalating within ~3–4 automated requests, after which
iteration 2's numbers measure the block, not the site. A challenged
headless run costs exactly 1 hit: gotoLive throws
BotChallengeError on the first challenge-classified response (the
wait+reload solve window runs only under --headed, where clearance can
actually land) — so the block budget is still intact when you escalate.stitch-shot.mjs "$LIVE" "$GATE/baseline.png" --freeze-baseline --width $W --settle), then pass --gate-against-baseline to every
gate.sh round. It holds the pixel-compare's origin still and nothing
else — a --full round's diff probes still read the live page. The two
--help texts own the refusals, the records and the exit codes.gate.sh runs each
capture under run-capped.mjs (stitch 300 s, compare 120 s —
GATE_STITCH_TIMEOUT / GATE_COMPARE_TIMEOUT) and reaps this user's
replica instruments older than 15 minutes before a round (GATE_REAP_MIN,
0 disables); pixel-compare.mjs supervises its own --timeout (120 s)
when run alone. Exit 124 is "no verdict — re-run", never a FAIL. Do not
wrap the instruments in your own sleep N; kill guard: three field
migrations did, after pixel-compare sat at 0 % CPU for 10+ minutes
(a Node exit-path hang, fixed in the script and now reproduced in a
test), and a page's four rounds then spent a fixed 30 minutes sleeping.
When a capture legitimately needs longer (a 10k-px page under --settle),
raise the variable for that page and say so in the ledger.sleep 5|10|15; then two rounds and a content-diff — blocked for 15
minutes; the next call wrote 513k tokens of cache, $6.30 for one silent
gap, more than the rounds it waited for, while every other gap in that
session stayed under 184 s at a 96 % cache-hit ratio. So: run-bg.mjs start --name <slug>-<w>-<iter> -- gate.sh … for every round at once (the
default 3 slots, RUN_BG_SLOTS to move them, launch the rounds first come
first served — each capture is a Chromium, a --full round three, and the
slots replace the sleep N; staggering), then run-bg.mjs wait (returns within --max, default 100 s, ceiling 110 s — inside the
shell tool's ~2-minute default timeout, which applies only to a call that
declares none) prints one
line per job plus its verdict lines; exit 75 means "still going — wait
again as your NEXT step". Never wrap wait in a shell loop: that
recreates the blocked step; between waits do independent work, and read
a round's ledger at most every 4 minutes (the master skill's wait
discipline — recorded: 5–10-minute foreground sweeps, 58 % of which
re-wrote the whole prompt prefix). The full instrument output stays in
stardust/.work/replica/bg/<job>.log — read it with run-bg.mjs log <job> --grep <re>, not with cat; the same session carried 700k characters of
tool output in 77 minutes, and a verdict is four lines of it.Each of these was hit live; skipping one silently corrupts the measurement rather than erroring.
launchLiveBrowser; bundled Chromium only when Chrome is
missing, said on stderr), presents its user agent without the headless token,
and derives Chrome-tier client hints from its version; bundled hints ride (#151).
Main's automation-signal handling stays on: every context gets the navigator.webdriver
spoof and the headed tier its launch flags; STARDUST_STEALTH=0 turns both off.
The standard set (Accept, Accept-Language, Upgrade-Insecure-Requests, sec-ch-ua*)
avoids the missing-header fingerprint (F-R1). Every instrument sends it by default via the
shared skills/stardust/scripts/live-session.mjs; --ua states a caller's identity
instead. Live navigations to one host share cross-process pacing
(STARDUST_LIVE_PACE_MS, default 1000 ms) and an in-flight cap
(STARDUST_LIVE_MAX_PARALLEL, default 2), with
STARDUST_LIVE_MAX_WAIT_MS (default 300000; 0 disables) bounding slot waits, even during a hold;
bookkeeping lock waits cap at 10 s and failures warn once per host, then proceed unthrottled.
Transport response marks prevent duplicate challenge accounting. Bot signals reduce the cap to one
and back off the pace: edge challenges, denial pages, any 429, a 503 with Retry-After, and post-answer timeout or
connection errors; 50 clean navigations recover one pace step, one more window the parallelism, and the
backoff is forgotten STARDUST_LIVE_STATE_TTL_MS after the last signal; Retry-After holds are capped at 120 s.
0 disables either limit, not holds, and
fresh contexts reuse repository-scoped OS-temp browser state for up to
STARDUST_LIVE_STATE_TTL_MS (default 12 hours).
The header set rides document requests only (F-B2, financial-services site):
forcing it on every request makes cross-origin CORS-mode webfont fetches
non-simple and kills them with net::ERR_FAILED — the capture then
silently renders fallback type (see rule 14); bot managers fingerprint
the navigation request, which still carries the full set. Sanity check
when numbers shift inexplicably between runs: grep the content-diff
inventory for challenge-page strings.domcontentloaded, never networkidle, on live targets. Live sites
with analytics beacons never reach networkidle — hard timeout. Built in:
the diff scripts default domcontentloaded for non-localhost http(s)
URLs (decided per side; EDS build/preview origins — *.aem.page,
*.aem.live, *.hlx.page, *.hlx.live — are the exception and get
networkidle, they decorate async) and keep networkidle for local
prototypes; --wait-until overrides. stitch-shot is always
domcontentloaded.--main scoping — and never body. Live <main> often
contains header nav + hidden mega-menu; unscoped, those diff as ~dozens
of missing CTAs (UC1-E1 iteration 1: 41 of 50 reds were scoping
artifacts). Scope BOTH sides with the same selector — have the prototype
adopt the live content-root class so one --main value fits both. Both
diff scripts take --main (visual-diff's is the upstreamed flag: on
sites without a <main>, both sides otherwise false-flag BLANK RENDER
while the main-scoped checks silently no-op). --main body is never a
valid replica scope (the chrome lands in the content inventory).
Script / style payloads and the common consent managers' banners are not
inventoried — a skipped banner is named on its root's summary line. Reds
that cluster on cookie strings mean a manager the list misses, or a
banner the dismissal hid rather than removed: --consent <sel> (rule 6)
only adds an accept click — it does not extend the skip list, and the
inventory has no visibility filter. Verify the banner is actually gone
after dismissal before trusting an inventory (consent UIs render
nondeterministically between captures); if it lingers, the scope or the
dismissal is wrong, not the recreation.fullPage:true. Chromium's
captureBeyondViewport renders lazy-decoded images as gray placeholders
even when the DOM says loaded. Stitch on BOTH sides — the instrument
must be symmetric.dismissOverlays (stitch-shot and the diff probes alike; gate.sh
carries --consent <sel> / --dismiss <sel,...> to both captures AND
its probes, --no-dismiss turns it off everywhere in the round):
(a) cookie consent (clicked accept; the flags above for a banner the
built-in candidates miss); (b) timed marketing/newsletter interstitials —
recorded (fashion retailer): an undismissed "Sign up, stay updated!"
modal fired ~5–9s after load and baked a pixel-diff contributor into the
LIVE capture, repeated at every chunk seam, that no prototype fidelity
could null out. These fire on a timer, so the dismissal polls for late
arrivals and stitch-shot sweeps again after the settle pass.recreation-procedure.md § Granularity parity.recreation-procedure.md § Capture-state); a probe flag
over a logged capture-state zone is justified.recreation-procedure.md.:hover-styled element under the resting cursor is silently captured
in HOVER state (recorded: a hero's a.box-hover:hover img{opacity:.4}
shipped the live capture dimmed — measured 0.4 in capture, 1.0 in
reality). The shared dismissOverlays parks the mouse (bottom-left)
after every dismissal pass — all three instruments inherit it; mirror
it in any ad-hoc capture that clicks anything.live.png captured the old way, and a frozen
baseline from before is stale (re-freeze).
recreation-procedure.md § Fixed and sticky chrome.cf-mitigated: challenge, or
403/429/503 with a Cloudflare/Akamai/F5/Imperva/CloudFront-AWS WAF edge signature) and
exits 3 with a BotChallengeError naming the URL and the marker.
Recorded (luggage retailer): Akamai served "Access Denied" to the headless
instruments — which, without this rule, would have silently measured
the block page as the source and diffed it cleanly, wrongly. A 2xx
denial page — a vendor wall answering 200 with its denial text, so no
header classifies it — fails the same way: after the settle gotoLive
reads the page (pageDenial owns what counts) and throws the
same error (marker HTTP <status> denial page — …, "origin blocked");
stitch-shot reads once more after its dismissal sweeps and leaves no PNG
and no capture.json. The escalation ladder: default (real Chrome, its own
identity + standard headers, paced) → --headed (the same browser plus the
challenge-solve window and existing launch flags, window-free; STARDUST_STEALTH=0 disables
automation-signal handling, while STARDUST_HEADED_WINDOW=1 opens a window) → if STILL
blocked, the site needs crawl.mjs-class capture and the gate must
not silently degrade — record the breakpoint as gate-blocked in the
ledger and surface it to the user; a gate that can't read the live
source has no pass to report.html/body are
overflow:hidden and an inner container scrolls, the document reports
the full content height but window.scrollTo is a no-op — every chunk
would capture the top viewport and the rows below would stitch as
zero-filled black: a silently fictitious pixel diff. stitch-shot now
detects the stall and exits 1 with the signature stitch-shot error: scroll stall at chunk target …px: window scroll is a no-op (window.scrollY stuck at …px) while the document reports …px.
Capturing the inner scroller is future work; for now record the page as
gate-blocked for the pixel probe and rely on content-diff/visual-diff.document.fonts.ready for declared faces with FontFace status error
and warns loudly with the family names; mirror the check in any ad-hoc
capture. The capture record carries the dead faces as fontsFailed
(null = the check could not run — never a pass; stitch-shot's
deadFontFaces owns the rule, recreation-procedure.md § Fonts policy
the fix); gate.sh prints it per side, gate-all fails the row. On the
warning, decide before gating: load the face in a real
browser — if it loads there, the failure is instrument-induced (a
capture defect: fix the instrument, and the poisoned runs don't consume
the iteration cap per § Iteration discipline); if it fails there too,
fallback type is the truthful capture (capture-state — log it).The four manual adaptations this section used to prescribe are upstreamed
into the shipped scripts. All live-target hardening lives in one shared
module — skills/stardust/scripts/live-session.mjs (the browser's own identity + standard
headers, per-host pacing, challenge fail-loud, overlay dismissal, --headed
escalation) — and the diff
scripts expose it as flags:
# content-diff against a live source: no source edits, flags only (the header and
# footer roots are compared beside --main by default — no extra flag; --no-chrome opts out)
node stardust/scripts/diff/content-diff.mjs "$LIVE" "$PROTO" --profile generic \
--width 1440 --main "<content-root>" --dismiss
# visual-diff: --main is a real flag (rule 3), same live hardening
node stardust/scripts/diff/visual-diff.mjs "$LIVE" "$PROTO" --profile generic \
--width 1440 --main "<content-root>" --dismiss
# non-standard overlay closer / pinned locale / bot-managed site:
# --dismiss "#custom-close" --locale en-GB --headedDefaults without flags: rules 1, 2 and 12 as written; the diff probes
dismiss no overlay unless passed --dismiss (gate.sh passes it for you).
A project copy re-implementing retired adaptations is a defect, not
diligence: the edits were 10 distinct changes across 2 files, and a partial
application silently mis-measured (e.g. one main-scoped selector left
hardcoded in visual-diff). If you find // replica ADAPTATION: copies from
an older run, re-copy the shipped scripts and pass flags instead.
The narrow exception: a documented instrument-bug fix is the correct move when the shipped instrument measures falsely — fail-loud outranks script immutability. The rule above exists to kill stale re-implementations of upstreamed flags, not to force gating on an instrument known to lie (recorded, F-B2: the shipped header delivery silently killed live webfont loads; the session's most important fix was a hand-edit to the project's live-session.mjs). A legitimate instrument fix is (a) commented in the script with the defect it corrects, (b) recorded in the ledger with the runs it invalidates, and (c) flagged for upstreaming into the plugin. An uncommented, unledgered edit is still a defect.
The published round is the Phase 4 command with the preview origin as the
build URL — gate.sh <slug> "$LIVE" "<preview-url>" <width> pub1 --full --marker "<brand or domain string>" through run-bg.mjs — so the same four
probes, deadlines and verdict lines apply; no hand-written wrapper. The
--marker is required here: the identity assertion greps the served page for
the marker, and the slug sits in the prototype's file name, not in the
preview page. Keep the ordinary stardust/replica/gates/<slug>-<width>/
evidence dir — the pub<N> label keeps the round apart, and a new dir would
force a fresh live capture against the hit-minimisation rule.
The prototype gate above proves the RECREATION; it does not prove the DELIVERED page. Local render harnesses systematically understate deltas because the real delivery pipeline transforms the markup — field rule (financial-services site, 8 pages published): a page gating at X% on the harness lands at X±(large) on the published origin until the transforms below are handled. Only the published-origin number counts as the final gate for a platform-delivered page: re-run the full gate (same instruments, same pass bar, same iteration discipline) with the live site as source and the published page — preview or live origin — as build. Judge the result in the published-origin regime (§ Pass bar, calibration honesty), not against prototype-regime numbers.
Two rules for that final run:
<p><picture>,
fragment chrome): a gate-passed 8.4% prototype first published at 11.75%,
and two text-anchor rounds (anchor probe live-vs-published, patch section
paddings in block CSS, re-measure) brought it to 6.5% with exact anchor
parity (recorded). Treat the pre-publish harness number as provisional
and the reconcile round as expected work, not a regression.media-reconcile.mjs is a delivery-chain gate, not a prototype-gate
instrument. It resolves the images of the DELIVERED content file
(content/<path>.html — handoff contract § 1 row 7 and § 3 row C); run on a
prototype or a migrated file it exits 1 by construction, because no content
file exists before C-deliver, and a recorded hands-off run carried
media-reconcile: OPEN on every sibling sidecar until delivery for exactly
that reason. gate-evidence.mjs records n/a: no delivered content file yet (never OPEN) while the page's content file is absent and leaves the
gate out of the sibling acceptance set; once the file exists the gate is
required again and its verdict counts. Nothing in Phase 4 runs it.
Recurring EDS pipeline transforms that move the number (each recorded; none visible on a local harness):
<p><picture>. The pipeline emits every
authored image inside a paragraph. If any base rule makes that <p>
positioned, absolutely-positioned imgs inside it collapse to 0×0
(backgrounds vanish) and the now-empty paragraph box distorts flex/grid
flow. Style p:has(picture) as the media layer, and expect specificity
fights with :not()-heavy base selectors — junction/override rules must
match or exceed them..section divs carrying full
section padding — a ~96px phantom band, typically at the page tail (the
same class as deploy's emptySectionCollapse; the fix there is
main .section:empty { display: none }, see
../../deploy/SKILL.md § Runtime-detection probe)./media_<hash> renditions with width
params — size/ratio assumptions lifted from the authored URL don't
survive; read dimensions from the delivered rendition, not the authored
asset..section:has(.some-block)) can silently never match the delivered
page (recorded). Verify every :has() / block-class selector against the
delivered .plain.html and rendered DOM, not the authored file.The recorded case. A 96-page rollout of a pharmacy retailer gated its five archetypes and
shipped the other pages unmeasured; the owner's first feedback was that they "don't look
formatted as the original". A runner then gated every deployed page on stitched 1440 captures
and pixel-compare, and a fix program took the roster from 3 to 67 PASS. Then the coupon-listing
page PASSED at 6.7 % / Δh 69 px while every one of its 284 cards was broken: a fixed-height
card with overflow: hidden, the body ~30 px too low, the description clipped mid-glyph, the
details link pushed under the primary button — and the sort control reading a different default
than the origin. The links WERE in the served DOM; pure CSS geometry. Pixelmatch underweights
small text inside otherwise matching shapes (the text-only number, --text-boxes, read 16.5 %).
"PASS" meant "right shapes at the right places", not "every element present and legible".
Element presence and legibility are checkable — so gate-all.mjs checks them.
node stardust/scripts/replica/gate-all.mjs (project root; through run-bg.mjs) runs, for
every deployed page in stardust/state.json, the stitched captures and pixel-compare of the
archetype gate PLUS two DOM probes that load both pages in the same window-free real-Chrome tier
and settle them the same way (measure-live.mjs), and writes
stardust/replica/gates/all-<width>/<slug>/{origin,eds,diff}.png + pixel.json + content.json + clip.json [+ units.json] and summary.{json,md} (a passed page keeps no PNG, #156). Verdict, per page — all four:
--threshold (default 10).--height-tol × origin height (default 5 %). The overlap crop cannot see
a render thousands of px too tall; a union (white-padded) metric was tried and rejected
(white gaps score as matches), so the guard is explicit.clip-probe count ≤ --clip-max (default 0) + the page's allowance
in clip-allow.json. Counted: a text line cut across, whole lines behind an overflow-hidden
ancestor without a line-clamp, a link or button outside or cut by its clipping ancestor.
Advisory: line-clamp, "read more" collapsibles, scrollable containers, horizontal cuts.content-presence MISSING + HIDDEN links and h1–h3 headings = 0. Visible
headings, links (by visible text), buttons, images, text blocks per band (h1–h3 sequence
aligned by text) plus control STATE. Clipped past 50 % = HIDDEN, not present. Buttons,
control state and count deltas are reported, not blocking. Regions declared in
presence.json (rails, coupon walls, reviews) compare as counts — HIDDEN still counts.
Origin not probeable (edge 403, bot challenge) → content: n/a (<why>), never a fail,
never a silent pass.
(+ units — unit-geometry off / hidden / missing = 0 for units.json entries marked
required: true; others are advisory rows.)The table rule. --stage prototype (pages with a prototypePath, build = the served
prototype dir, origin = the archetype round's cached live.png when present) writes
gates/prototypes-<w>/summary.{json,md}; the default published stage writes
gates/all-<w>/. Both are read by gate-evidence.mjs: with a table for the width, a
page's row decides pixel-gate-<w> and a page without a row is OPEN: no table row;
without any table the gate.sh logs stand in and --check names the missing table. The
eval requires both summaries with a row per page. The pixel-only verdict (1 + 2) is
recorded beside the full one per page and in the totals: every run is calibration data. Sidecars in the gate dir, each entry documented: masks.json (printed
on the verdict, never reported unmasked), overrides.json (shown BESIDE the measured number,
never replacing it; each entry names the criteria it waives, "waives": ["fonts"] from capture, pixel,
height, clip, content, units, fonts, and the row is delivered only when every failing criterion is
named; an entry without waives covers capture, pixel, height and fonts, never clip, content or units), clip-allow.json, presence.json, units.json. Origin fallback: live
stitch → previous origin (--recapture-origin) → crawl fullPage screenshot (crawl-fullpage,
asymmetric, flagged). Browser tier: the best available, registered. The probes elect real
Chrome (channel: 'chrome', window-free) and fall back to bundled Chromium when it is not
installed; every probe writes the tier it actually ran (chrome | chromium-fallback |
chromium) into its JSON, summary.md carries a browser column and the calibration line
counts degraded pages — a run that quietly lost its origin measurements on a bot-managed site is
visible in the artifact. Sites without bot management measure identically on both tiers.
--eds-host gates a code branch against the same content (branch hosts
serve the LITERAL branch name — fix/x → push a mirror fix-x). Read a finding as one crop of
the two captures at the row's band, never the whole pages.
What a failing row means (#126). The row's evidence decides the fix, mechanically: clip
groups, HIDDEN links or unit deltas confined to one block → fix the BLOCK (CSS or encoder) and
re-gate every page sharing it; MISSING links or images whose content is in the capture → fix the
ENCODER and re-render the affected siblings; MISSING h1–h3 bands, hot bands over most of the
page or |Δh| far beyond 5 % (a banded layout flattened) → RE-PROTOTYPE: the page leaves the
template — the variance probe across the template's other pages decides a new archetype (two or
more share the composition: craft, gate, deploy, migrate its siblings) or a standalone prototype
(an archetype of one); tier and template change in state.json, the redirect row stays. Cap: 3
fix rounds per page at the published origin, then this decision — never a fourth round.
Calibration on the recorded roster (96 pages): pixel-only 66 PASS → full 28 PASS; failing by
criterion pixel 30, height 6, clip 23, content 31; content n/a on 37 (edge-blocked origins).
stardust/replica/progress.json is ONE file for the whole run: the map of every archetype under
types (this section's record per archetype, keyed by its slug) beside the siblings and migrate
blocks gate-evidence.mjs writes and the _provenance block every stardust JSON artifact carries.
Extend YOUR archetype's entry in place — read, merge, write back (gate-evidence.mjs preserves every
key it does not own). Never write one archetype's record as the file; gate-evidence.mjs wraps such
a file under types.<archetype> and refuses only a record that names no archetype. Per archetype per
breakpoint:
{
"_provenance": { "writtenBy": "…", "writtenAt": "…" },
"types": {
"home": {
"pageType": "landing",
"archetype": "home",
"breakpoints": {
"1440": {
"iterations": 3,
"result": { "structuralRed": 0, "visualFlags": "3 justified",
"pixelPct": 1.31, "heightDelta": 0, "pass": true },
"justified": [
{ "probe": "visual", "flag": "1x1 h1 at x0", "why": "mirrors live SEO h1" },
{ "probe": "content", "flag": "🟠 font fork ×2", "why": "licensed kit substituted, R-policy fonts", "permanent": true }
],
"residuals": [
{ "band": "y 4500–5000", "pct": 6.2, "cause": "capture-state: 3 CDN-403 placeholder tiles", "flaggedFor": "delivery" },
{ "region": "footer", "pct": 4.8, "cause": "glyph-antialiasing", "parity": "gates/home-1440/chrome-parity-iter3.json", "texture": { "thickPct": 6.1 }, "flaggedFor": "user" }
],
"captureState": [
{ "what": "product tiles 4–6 on placeholder data-URIs", "where": "carousel-2", "restoreAtDelivery": null },
{ "what": "hero video paused at frame 0, carousel-2 held on slide 1 (stitch-shot freeze)", "where": "hero, carousel-2",
"restoreAtDelivery": "hero: autoplay muted loop playsinline, paused under prefers-reduced-motion; carousel-2: auto-rotate 5 s, pause on hover" }
]
},
"900": { "...": "...", "tierShift": [
{ "band": "y 0–5200", "pct": 14.2, "register": "R-07", "why": "desktop header at 900 (source: 1024); uniform +40 px offset below it" } ] },
"360": { "...": "..." }
},
"motion": { "observed": "…", "implemented": "…", "dead": [] }
},
"<next archetype slug>": { "...": "..." }
},
"siblings": { "...": "written by gate-evidence.mjs" },
"migrate": { "...": "written by gate-evidence.mjs" }
}Rules: every residual names its band, its %, its cause, and who inherits it
(delivery for capture-state items, user for accepted trade-offs). A
residual without a cause is not a residual — it's an unfinished iteration;
either diagnose it or spend the remaining budget on it. Every captureState
entry carries restoreAtDelivery: the live behaviour the freeze or mask hid,
as observed (null only when live is static there too) — a promise C-deliver
implements (recreation-procedure.md § Carousels and animated sections). The rollout phase's
final report surfaces the residual list per page type so "gate passed"
can't hide "passed with 6% unexplained".
.tessl-plugin
skills
audit
reference
deploy
reference
scripts
test
diff
direct
dynamics
extract
migrate
prepare-migration
prototype
assets
motion
fixtures
reference
qa
replica
reference
scripts
test
reskin
rollout
spec
stardust
uplift
reference