feat(capture): pipeline improvements — contact sheets, design styles, snapshot

[ukimsanov]

What

Capture pipeline work that came out of the 11-round website-to-video eval branch. Five clusters of changes touch 12 files in packages/cli/src/capture/ and packages/cli/src/commands/:

1. Paginated labeled contact sheets (contactSheet.ts, new)
2. Design-styles extractor (designStyleExtractor.ts, new)
3. Snapshot tool fixes — HyperShader-aware wait + local-time seek for sub-comps + Gemini per-frame analysis runs by default
4. Screenshot capture — overlay-scan replaced with TreeWalker + early-exit; cookie-dismiss selectors scoped under cookie/consent/gdpr ancestors
5. CLI ergonomics — .env auto-load from CWD, transcribe defaults output dir next to the input

2 of 5 in the pipeline-quality stack. Stacked on #987.

Why

The wins that actually moved video quality across the evals were the artifacts agents read (contact sheets, design-styles JSON) and the snapshot-tool visual-verification fixes. Without the contact sheet pagination, sites with 30+ assets showed asset-1 at full size and nothing else. Without local-time seek, every beat after the first showed as black or final-opacity-zero in the snapshot. The Gemini frame-by-frame descriptions.md is the only objective check on what the video actually shows.

How

Contact sheets (contactSheet.ts, new) — paginated labeled grids (3-col screenshots / 4-col raster / 5-col SVG; 9–15 cells per page with filename labels via SVG text overlay). fit: "contain" keeps every asset visible at its real aspect ratio. createSvgContactSheet scans both assets/svgs/ and assets/ root, de-dupes by filename — sites with all-external SVGs (huly.io) now get coverage. escapeXml covers &<>"'.

Design styles (designStyleExtractor.ts, new) — walks the live DOM, reads computed styles, writes extracted/design-styles.json: typography hierarchy with exact metrics, button variants, card/container/nav styles, spacing scale with base unit, border-radius scale, box-shadow values with usage counts. Primary data source for DESIGN.md at Step 1.

Snapshot tool (snapshot.ts) — wait signal is now window.__hf.shaderTransitions[].ready (set after both warm and cold cache paths complete); local-time seek for sub-comps means exit fades read at their own t=0..duration. --describe resolution: runs by default, --describe "custom Q" overrides the prompt, --describe false opts out.

Screenshot capture (screenshotCapture.ts) — querySelectorAll('*') + getComputedStyle overlay scan replaced with a TreeWalker that early-exits on cheap rect checks before the expensive style read. Caps at 5000 elements per page. Cookie/consent dismissal selectors scoped under cookie/consent/gdpr ancestors so we don't click "Accept invitation" on unrelated buttons.

Agent prompt (agentPromptGenerator.ts) — auto-discovers contact-sheet page count (matches base name plus paginated -NNN digits only; regex metachars escaped; numeric sort for 10+ pages). inferColorRole classifies extracted hex colors as bg-dark / bg-light / accent / surface / neutral so the agent prompt shows #533AFD (accent). design-styles.json row gated on existsSync.

Other CLI ergonomics — cli.ts auto-loads .env from CWD on startup (handles export FOO=bar, quoted values, inline # comments). commands/transcribe.ts default output dir is the input file's directory.

Test plan

• Unit tests added/updated — no new tests; functionality is end-to-end. Existing CLI tests pass.
• Manual testing performed — capture run on 7 sites (arc, daylight, framer, huly, mercury, raycast, workos) confirms contact sheets, design-styles.json, fonts-manifest.json, and snapshot/descriptions.md all produced correctly. Typecheck clean. Build succeeds.
• Documentation updated (if applicable) — skill prose documentation for the new artifacts lands in PR feat(studio): consolidate into single OSS-ready NLE editor #4 of the stack.

[ukimsanov]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• feat(skill): hyperframes core — remove prescriptive tables, bundle text-effects #991
• feat(skill): website-to-hyperframes — concept-first authoring + per-beat read protocol #990
• feat(lint): font loading + invalid capture path composition rules #989
• feat(capture): pipeline improvements — contact sheets, design styles, snapshot #988 👈 (View in Graphite)
• feat(capture): identify hashed fonts via OpenType name table #987
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[miguel-heygen]

Good capture pipeline work. Issues from the original #984 review addressed in the split:

• Cookie-dismiss selectors now scoped under cookie/consent/gdpr ancestors (not bare button[id*="accept"])
• Regex interpolation uses escapedBase — no longer fragile for special chars
• escapeXml covers all 5 entities including apostrophe
• --describe running by default is now documented as intentional (opt-out with --describe false)

Contact sheet pagination, design-styles extractor, and TreeWalker overlay scan are all clean.

[jrusso1020]

Approve at 29baca1e. Magi covered the cookie-selector ancestor scope, regex escape, and escapeXml 5-entity coverage. Additive notes:

• --describe resolution — PR body explicitly addresses my prior hf#984 concern: "runs by default, --describe \"custom Q\" overrides the prompt, --describe false opts out." The three-valued semantic is well-thought-out; verify the boolean-parsing layer accepts "false" / "0" / "no" consistently with citty conventions elsewhere in the CLI (snapshot defaults to a numeric flag pattern; the docs and the parser need to agree).
• .env auto-load from CWD — same loader implementation I reviewed in hf#984. Safe shape (only sets if !(key in process.env), parses quoted values, silent on missing file). Standard dotenv convention. Acceptable.
• Contact sheet pagination — agentPromptGenerator.ts auto-discovers page count by matching <base>-NNN.<ext> digits with regex metachars escaped + numeric sort. Solid; the 10+-pages numeric-sort fix is the kind of off-by-one-character edge case worth pinning by test. Recommend adding a unit test for the discovery function (12 → 9, 10, 11, 12; not lexicographic).
• TreeWalker overlay scan + 5000-element cap — sensible defense-in-depth. The 5000 cap will silently truncate on extreme pages (e.g., asset-heavy CRM dashboards). Worth a one-line log when the cap is hit so we know the scan was incomplete.
• Snapshot wait signal via window.__hf.shaderTransitions[].ready — cross-PR consistency: this assumes hyperframes core's runtime exposes that object. Verify the contract is documented in the runtime API surface (or pin it by test on the engine side).

Stack base correctly set to feat/capture-font-extractor. Direction is the bag of wins Ular identified as actually moving quality.

— Rames Jusso