Capture real evidence at the HTML preview gate

[leochenpm]

Stacked on #4 (which is stacked on #3). Merge in order; GitHub retargets automatically.

Why

The HTML preview gate exists to catch design problems before paying for an mp4 render. But snapshot only ever captured --at 0 — a single opening frame. One frame cannot show a scene that reads as a generic slide, starts blank, or drops its hero visual, so the gate could approve a composition whose problems only surfaced after a full render. The gate was asking for a judgement it never supplied the evidence for.

What

Evidence (render.ts, composition-qa.ts)

• snapshot now captures the hook frame, one midpoint per scene, and the payoff frame in a single hyperframes call — --at accepts a timestamp list, so this is one browser session, not N.
• Returns first_frame, contact_sheet (HyperFrames writes a grid view itself — no need to build one), and labelled frames. path/bytes are unchanged for existing callers.
• Scene times come from the existing loadSceneMap + loadCompositionMeta. If metadata can't be read, it degrades to the old single-frame capture instead of failing.
• New pure helpers buildPreviewSamplePlan / matchPreviewFrames, bounded by PREVIEW_MAX_FRAMES = 8 (each capture is a real browser seek; hook and payoff always survive the thinning).

Discipline (skills)

• stage-compose step 5: read the contact sheet as a design checkpoint, make one localized repair before opening the gate, show the sheet as the primary artifact.
• frontend-design: judge every returned frame, not frame 0 alone.

Two bugs found while building this

• The old "newest PNG wins" rule. Fine for one frame; with several timestamps the newest file is the payoff, so first_frame would have silently been the closing frame. Results are now joined on the frame-<NN>- index prefix hyperframes actually writes.
• The payoff frame seeked past the end. duration - 0.05 rounds up to duration at hyperframes' one-decimal seek granularity (11.95 → 12.0). Caught by a unit test; times are now rounded before clamping to the last seekable tenth.

Verification

• pnpm build + typecheck green. pnpm test 137 passed / 8 skipped (+9 new; 128 was the baseline).
• Driven end-to-end against real hyperframes 0.7.21, not just unit tests: a real hyperframes init composition with a 3-scene map returned 5 correctly-labelled frames (hook-frame 0s, intro-mid 1s, body-mid 3s, outro-mid 5s, payoff-frame 9.9s) plus the contact sheet. Verified first_frame is byte-identical to frame-00 (the hook), and that a shorter rerun leaves no stale frames behind.
• Filename parsing has fixtures for the real shape and for rejected look-alikes (frame-0-at-0.0s.jpg, my-frame-00-..., ...png.bak).

Scope note

The plan's PR3 bundled 7 upstream commits. Most of them (32691008a, 40d0477c1, 4ea928a7a, 173f9fed8) implement the upstream host's native composition.* state machine — durable production state, approve_plan/approve_preview/approve_draft ops, and chat-UI artifact publishing. None of that exists here and porting the prompts alone would describe gates this repo does not have. What was genuinely portable is the preview-evidence half, which needed code before the prompt could be honest — that's this PR.