FOYER-V3 R1: assert-gated walkthroughs for node-foyer

[HomenShum]

Summary

Three single-pane walkthrough specs for Node Foyer's own surfaces (walkthrough.foyer.specs.mjs, captured by walkthrough.foyer.mjs, rendered via src/foyer-index.js reusing Walkthrough.jsx's new captureViewport geometry). New mechanism in this capturer, not present in any existing walkthrough.*.mjs: every cap op carries an assert checked against the live DOM immediately before the screenshot — fail-closed on a mismatch (aborts the spec, keeps zz-fail.png), so a capture that would show a wrong or stale state never ships. Each capture also reads the wall's own foyer-build-sha via a same-origin fetch at the first and last frame and discards the run if the served build moved mid-capture.

Step 0 (separate commit, 4cffdba): hand-applied the captureViewport geometry change from wip/slidelang-capture-viewport-20260912 (5088aaa) onto the current Walkthrough.jsx (which had since gained the chromeless/FILL refactor upstream) — geometryFor(wt) replaces the hardcoded 1280x800 CAP_VW/IMG_H/SX/SY constants so a 1440x900 wall and a 390x844 phone capture each get their own aspect ratio.

Storyboard

Capture	Viewport	Source	Beats
FYwall	1440x900	production (https://node-foyer.vercel.app/)	header provenance → all 22 cards → a verified card (NodeVoice) beside a reachable-only one (NodeProof) → a stable-sweeps line → NodeRoom's hover apparatus (probe URL, HTTP status, sha256) → __fixture_dead UNKNOWN with its tried URL → the Foyer's own card verified on both layers
FYphone	390x844	production	soft-hyphenated long name → Details opens a real dialog with the wall now inert behind it → a 44px Open target → Close returns focus to Details
FYagent	1440x900	built preview, VITE_CONVEX_URL unset	the wall root's own data-foyer-snapshot-source="file" fallback attribute → the same build's /.well-known/agent-ui.json and /api/apps.json served raw

Each capture carries the seven STORYBOARD.md beats (premise/question/axis/conflict/evidence/verdict/exit) as one storyboard object, matching node-foyer's WalkthroughCapture type exactly.

Judge results (gemini-3.6-flash, key resolved from env, never printed)

• FYwall — fix-then-publish, 20/22.
• FYphone — fix-then-publish, 22/22.
• FYagent — sampled 3 times (this repo's own documented judge variance): 13/22 fix-then-publish, then 8/22 and 6/22 rework. Recorded as rework (2 of 3, most recent run) rather than resampled until a good score appeared. The defect repeats every run for a structural reason: the goto beats navigate to a raw JSON response with no in-app element to animate a cursor onto, and STORYBOARD.md forbids faking an interaction the frame doesn't show. The judge's own fix — a terminal/curl panel showing the actual fetch — is real but out of scope for this round.

Media budget

Three GIFs (979KB + 399KB + 998KB) + three posters (126KB + 87KB + 120KB) = ~2.58MB, under node-foyer's WALKTHROUGH_MEDIA_BUDGET_BYTES (4MB). Posters and GIFs are copied into node-foyer/public/media/walkthroughs/<id>/; the manifest draft is at node-foyer/data/walkthroughs.manifest.json for the planner to re-hash and promote to public/media/walkthroughs.json.

Test plan

• npm run check — 60/60 JS files parse, 36/36 tour steps and 34/34 prose citations match (fixed the line-number drift the geometry commit caused in docs/START_HERE.md and .tours/01-primary-user-flow.tour)
• All 15 capture-time asserts held across the three specs (7 + 5 + 3 frames)
• npx playwright test e2e/foyer.spec.ts against the FYagent preview: 12 passed, 1 skipped, 1 failed (pre-existing registry/adapters.json vs public/data/snapshot.json drift from a concurrent planner commit — both protected/runner-owned files outside this PR's scope)
• Rendered MP4s spot-checked frame-by-frame; GIFs and posters visually verified after re-encoding for size

🤖 Generated with Claude Code