Verify

A scroll page cannot be checked by looking at it. It has no single state: every scroll position is a different frame, and the failures live between the two you happened to look at. So walk it mechanically.

cd <build project>
npm i playwright-core                       # once

node <skill>/scripts/serve.mjs --root . --port 4500 &
node <skill>/scripts/shoot.mjs --url http://localhost:4500 --out lab/shots
node <skill>/scripts/shoot.mjs --url http://localhost:4500 --out lab/mobile --width 390 --height 844
node <skill>/scripts/shoot.mjs --url http://localhost:4500 --out lab/reduced --reduced-motion

Then read sheet.png. The whole point of shooting contiguously is looking at the frames side by side; a folder of PNGs does not get looked at that way.

Two setup facts that will otherwise waste a pass:

• Serve it. file:// blocks the Blob fetch the engine uses for clips, so the page silently falls back to posters and proves nothing.
• Real Chrome, not bundled Chromium. Chromium ships without an h264 decoder, so every clip fails to paint and the run "passes" against posters. shoot.mjs already resolves installed Chrome; override with SCROLLCRAFT_CHROME.

---

What the harness reports

It samples within each act (default 6 positions per act) rather than uniformly down the document. Uniform sampling moves every position whenever you change any section's height, so findings appear and vanish with unrelated edits.

DEAD SCROLL: consecutive positions where nothing changed: no cue moved, no clip time advanced, no rail travelled, no wipe progressed, no stage shifted. Real dead scroll means the reader is turning the wheel and being given nothing. Fix by shortening the act's span or adding a cue.

Bespoke fixed stages must report their visible state. A split stage, live canvas, or other page-local system can use ordinary flow acts only as scroll markers while every visible change happens on a fixed layer outside the engine. The harness cannot infer that layer's semantics. Put data-sc-verify-state on the fixed stage and update its value to a compact signature of the values that actually paint: divider position, scene opacity, canvas phase, custom film time, or similar. The detector then checks those flow spans too.

Do not publish raw scroll progress just to make the check green. If progress is changing while the composition is not, that is the exact failure this path is meant to catch. Round and publish the rendered values. For an intentional resolved hold, set data-sc-verify-hold="true" only while the hold is active. Reduced-motion fixed stages may use the same attribute for deliberately stable frames, which still require manual contact-sheet review.

FROZEN CLIP: a scrub stage is on screen, the reader is scrolling, and the clip's playhead is not moving. Dead scroll cannot see this, because the stage itself is moving: a still photograph is sliding up the page, which is the worst-looking failure this kit can produce and the one that most reliably makes a page feel broken.

The harness samples each scrub act's entry and exit slides, not only its pinned travel. That gap is why this went undetected for four builds: a pinned act's samples were taken at top + (h - vh) * p, which never visits the viewport of scroll on either side where the stage is visible and the clip is parked. A hold on the first or last frame is always reported. A hold in the middle is only reported once it outlasts any plausible data-sc-dwell settle, since that settle is a deliberate effect. The check is skipped under reduced motion, where no clip is ever fetched on purpose.

The fix is almost never per-page: the engine maps clip time across the stage's whole visible life by default. A page that reports this has usually opted out with data-sc-clip-map="travel", or is running an engine copy from before that default existed. See devices.md §1.

CUES THAT NEVER PEAK: an element that never reaches full opacity anywhere. Usually a cue window too narrow for its act, or ramps that eat the whole window. Widen the window or set explicit ramps. A kinetic heading is read through its line units, not through the element: the engine forces the element itself to opacity 1 and carries the real value on .sc-split__i, so reading the element reports every kinetic headline as fully present even on frames where every line is at 0.

CONTRAST: measured on the composited page, not on the source video. The harness hides the text, re-shoots the same frame, and samples the real background under each line, so scrims, gradients and blends are all included. Elements with their own opaque background are graded against that fill instead.

Three things it gets right that a hand-rolled version usually does not:

• The direction is picked per line. Light type on a dark page fails on the brightest patch under it; dark type on a light page fails on the darkest one, and grading that against the brightest patch is the most lenient reading available, so a high-key page can report clean over text that is failing. The harness compares the ink to the mean background and grades against whichever extreme is on the ink's own side.
• The sampled rect is clamped to the viewport. The part of a pinned act's copy that has scrolled above the fold is not on screen, so what sits in those pixels is not behind anything the reader can see.
• Fixed chrome is hidden with the text. A fixed bar paints in front of what scrolls under it, so its own mark is not the background behind a headline passing beneath it.

This is the check no static audit can do: the frame under a headline changes as the clip scrubs, so text can clear 4.5:1 against the poster and fail badly three hundred pixels later.

The scrim has to be a SIBLING of the copy, never a child

The pass hides [data-sc-cue],[data-sc-cue] *,[data-sc-copy],[data-sc-copy] * before photographing the frame underneath a line. visibility: hidden hides an element's pseudo-elements too, so a scrim written as .mycopy::before is hidden along with the text it exists to protect, and the pass grades the line against the raw film every time.

The tell is unmistakable once you know it: you strengthen the scrim and the reported numbers do not move at all. Not "improve slightly", not "move by a tenth": byte-identical, because the thing you changed was never in the measurement. If a contrast number is unchanged to two decimals after a real change, stop tuning and check what is actually being composited.

A very high mean against a very low worst (1.21:1 (mean 12.83)) is the same finding seen from the other side: the type is fine almost everywhere and there is a bright patch under it that nothing is covering.

Two shapes that work:

• .sc-world__scrim in the copy layer, which is what worldflight.md ships and which survives the hide because it carries no data-sc-copy.
• One plate per block, mounted as a sibling and driven from the page's own JS. orrery sizes each plate off its block's untransformed box (set transform:'none', read the rect, put it back, so the engine's ±2vh copy drift does not skew the measurement) and each frame copies the block's own inline opacity onto its plate, so the plate tracks the engine's window with no duplicated window maths.

Known limitations of the contrast pass

Real, and worth knowing before you trust a green run:

• Cues are keyed by their text. Two cues that share a string, which taste.md's "one label per intent" rule actively encourages, are collapsed into one row, and the reported worst frame is the worse of the two.

• Lines under 0.85 opacity are skipped. A headline parked at 0.6 over a bright frame is never graded, so "contrast clean" can still hide a legibility problem. Look at the sheet for anything that reads washed out.

  Author the fade-outs to land between sample positions. The harness samples a fixed number of positions per act, so a ramp-out that happens to straddle one puts a half-faded headline on the sheet: graded by nobody, and read by eye as ghost type over the frame. Fix the ramp, not the sampling. Shorten rampOut so the cue is at full opacity at one sample and gone by the next, rather than sitting at 0.5 on the sample in between. Widening the sample count only finds more half-faded frames; it does not make the page look better, because a real reader stopping on that pixel sees exactly what the sheet shows. A cue caught mid-fade over a bright frame is a real defect, not a sampling artefact.

• The floor is not size-aware. It reports below 3:1 as a failure and 3:1 to 4.5:1 as thin. WCAG allows 3:1 for large text, so a display headline in the thin band is usually fine and a 16px caption in it is not.

• Acts with no [data-sc-cue] elements are not graded at all. Copy on plain canvas is a static case, but it is unmeasured.

• Ordinary flow acts are excluded from dead-scroll checks. Static flow is normally correct. A bespoke fixed experience built over flow markers must use data-sc-verify-state, or the harness will skip its visible timeline and can report a dead opening as healthy.

• A pan act whose rail does not overflow is reported as healthy. The pigment build ran a rail measuring 1368px inside a 1440px viewport, so it travelled zero for its entire 2.1vh span, and every pass printed no dead scroll detected. Measure rail.scrollWidth - innerWidth yourself; a green run does not cover it. See devices.md §3.

Console errors and failed requests: a 404 on a clip degrades to a poster silently, which looks fine and is not.

---

What the harness cannot tell you

Read the sheet for these. They are the ones that matter most.

• Whether the composition is any good. Copy landing on the busiest part of the frame, a subject cropped at an unfortunate point, an act whose end frame is a dark empty corner.
• Whether the motion is smooth. Contiguous frames prove the clip advances; they do not prove it advances evenly. Watch the contact sheet for a move that lurches, reverses, or stalls in the middle.
• Whether the page means anything. Six acts that each work and together say nothing is the most expensive failure available here.

---

The manual passes

Reduced motion. Clips are never fetched, posters hold, copy still cues. The page must remain comprehensible, not merely not-crash. This doubles as the low-bandwidth check.

Comprehensible includes reachable: check that no content was deleted rather than merely stilled. A pan rail is the case that bites, because zeroing its transform parks it on its first screenful. The engine now hands the stage back as a native scroll region, so confirm on the sheet that the rail shows real content and that items past the fold can still be got to. Nothing in the harness reports this; it reads as a page behaving correctly.

Credit accounting. kie.mjs probe reports a balance, not a delta, so a build's spend is a before-and-after subtraction. That subtraction is only valid if nothing else is generating against the same key. When builds run in parallel, or when a settlement lands late, the deltas overlap and each build will claim some of another's spend (three parallel builds each read the same 7597 → 7067 and each reported 530). Either serialise generation, or cost the build from the per-call model prices in assets.md against the calls you actually made, and treat the probe delta as a ceiling.

And the per-call sum overstates real spend in the other direction. Two reconciliations against the account ledger, each with no other consumer, put actual debits at roughly 0.4x the documented unit rates: a fleet whose per-call sums came to ~1447 credits was debited 530, and a three-build run whose per-call sums came to 2252 was debited 856. Both land near the same ratio. So a build report should say what the per-call sum is and that it is a planning ceiling rather than the amount billed. Reporting the sum as the cost is the honest default, because it never under-claims; reporting it as measured spend is wrong. Neither number is the other's substitute: the probe delta bounds a parallel run from above, the per-call sum bounds a serial one from above, and only a ledger read with a single consumer settles it.

Mobile. Pinned stages use 100svh so the URL bar does not cause a jump. Copy reflows and does not collide with the fixed bar. Confirm the phone encodes actually load. Check the portrait crop of every clip: a 16:9 move composed around left-hand negative space loses exactly that space at 9:16 (see assets.md). Mobile is a first-class target, not a check at the end: the phone clips are cut portrait, the lerp is retuned for touch, tap targets are grown, and every one of those is authored, not inherited.

The phone is a different machine

Headless Chrome on the build box cannot reproduce an iPhone's video decoder, its autoplay policy, Low Power Mode, or touch scrolling. On one build every probe reported the hero clip scrubbing perfectly for four consecutive rounds while the real phone showed a frozen frame. A green harness run says the page is correct where the harness runs. It says nothing about iOS video.

What iOS does to a scrub clip, and what the engine now handles for you:

• iOS will not paint a muted video that has never been played. Seeks land, seeked fires, and the picture stays on one frame. The decoder has to be primed with one play()/pause().
• The engine primes each clip at loadedmetadata (a muted inline play() needs no gesture outside Low Power Mode) and retries on touchstart, touchend, pointerdown, click and scroll. touchend matters: the HTML spec's activation-triggering events include touchend but not touchstart, so a Low Power Mode phone that rejects the touchstart attempt gets a valid one when the finger lifts.
• A prime must be re-attemptable per clip. A one-shot prime on first touch loses a race: the reader touches to scroll within the first second, while the hero's megabytes are still downloading, and the shot is spent on a sourceless element. The tell is exactly "the first clip is frozen and every later one works".
• iOS may leave a play() promise pending forever, and may leave seeking true forever. Both were permanent silent freezes; the engine now releases the priming flag on a timer and re-issues any seek stuck past 700ms. The reveal also fires on a 2.5s timeout, never only on seeked.

Do not re-implement any of that in page JS, and do not strip it when copying the engine. If a phone still shows a frozen clip, the cause is past what this machine can measure, which is what the next section is for.

Ship the diagnostic with the site

You get one question per round with a real device, so make the round count. references/device-diag.html is a standalone page that scrubs the suspect clip two ways (blob URL, exactly as the engine loads it, and direct file src) beside a known-good clip, prints a MOVING / FROZEN verdict over each pane, and reports prime results, seek counts and distinct painted frames. Edit its TESTS array to point at the build's own clips, deploy it next to the site, and one screenshot from the phone isolates the layer: blob loading, the file, the device's decode policy, or the engine's lifecycle. Deploy it with the first mobile fix, not after the fourth.

Ask what differs before asking what's broken

The debugging lesson that cost three wasted rounds: "desktop works, the phone does not" reads as a platform difference and invites platform theories (codecs, keyframes, resolution). "One clip works and another does not, on the same device" cannot be a platform difference. Before theorising, write down every way the working case differs from the broken one; the bug lives in that list. On the build above the list had one entry: the hero is first, so it loads while the first touch is being spent.

Keyboard. Tab through. Focus order matches visual order, the focus ring is visible against every ground it crosses, and nothing reachable is parked at opacity 0. Cues set pointer-events: none when faded, but a focusable element inside a faded cue is still a trap.

The engine helps here but does not finish the job, and the gap is specific:

• It handles the ordinary case. On focusin, if the focused element is inside a [data-sc-act] and its own cue computes under 0.85, the engine scrolls it to the centre of the viewport with behavior: 'instant' (smooth would animate a multi-screen glide with focus off screen the whole way). On a flow act, centring the element also opens its cue, because the element's viewport position and the act's progress move together.
• It does not fix a pinned act, and cannot with this approach. A pinned stage is position: sticky, so the control holds one viewport position for the entire act. Centring it is then only achievable by scrolling backwards out of the act, which parks progress at 0 and leaves the cue dark. Measured: a CTA cued at 0.75 on a 3vh pinned act sits at viewport y=70 from progress 0 to 0.875; scrollIntoView({block:'center'}) from inside the act lands before the act's top, at progress 0, cue opacity 0. The control is on screen and still invisible.

On a pinned act, park the act at the progress where the focused element's own cue is open. That is page-local work, because only the page knows which cue belongs to which control, and because act progress runs through dwell() when the act has any, so the scroll target is not a straight inverse of the cue window. The descent build does exactly this. If a pinned act carries a focusable control, write that handler and assert it; do not assume the engine covered you.

Fresh eyes. Look again later. Timing you tuned for twenty minutes reads differently when you have forgotten what it is supposed to do.

---

Failures worth knowing about

Each of these shipped once during this skill's own build, and each looked fine until it was measured.

The first three are invisible to every check except looking at rendered output. That is the argument for this whole pass.

Operational note: a shoot.mjs run can take the background server process down with it when it finishes. Check the port before the next pass and restart serve.mjs if it dropped.

The harness will photograph the wrong site without telling you

serve.mjs fails with EADDRINUSE if something already holds the port. When that server was started in the background, the failure is in a log nobody is reading, and shoot.mjs then gets a perfectly good 200 from whatever else is on that port. It walks that page, finds its worldflight, and writes a full contact sheet and a clean report for a site you did not build.

Confirm the port is serving YOUR build before trusting any run:

curl -s http://localhost:45XX | grep -o "<title>.*</title>"
curl -s -o /dev/null -w "%{http_code}
" http://localhost:45XX/assets/leg01.mp4

A 404 on an asset you know exists is the fastest tell.