feat(skills): wire HyperFrames as a video provider

[wesleysimplicio]

Summary

Adds HyperFrames — an HTML→MP4 local renderer — as a first-class video provider, following the three-step Adding a Provider contract in CLAUDE.md.

The motor can now emit deterministic, parametrized motion typography, data-viz reels, and programmatic shorts that re-render byte-identically from declared variables (e.g. weekly KPI reel, daily price update) without re-prompting an AI generator.

What changed

Skills

• .skills/hyperframes/ — composition authoring rules adapted from upstream (layout-before-animation, timelines paused + registered on window.__timelines, no Math.random()/time-based logic, variables declared via data-composition-variables).
• .skills/hyperframes-cli/ — wraps npx hyperframes lint → inspect → render. Pipeline always renders with --strict --strict-variables.
• .skills/hyperframes-prompt-builder/ — specialist invoked by video-prompt-builder when the matrix resolves to hyperframes; loads brand tokens from clients/<slug>/design.md, picks a template per task_kind, and returns a composition spec + render args.
• .skills/video-prompt-builder/SKILL.md — dispatcher now recognizes the new task kinds and the new specialist.

Provider layer

• lib/providers/types.ts — VideoTask adds motion-typography, data-viz-reel, programmatic-short.
• lib/providers/video.ts — adds HyperframesVideoProvider (gated on HYPERFRAMES_ACTIVE=true) and registers it in the real registry.
• lib/providers/__mocks__/video.ts — adds MockHyperframesVideoProvider (DRY_RUN-safe).
• lib/providers/matrix.ts — extends EMBEDDED_DEFAULTS and TASK_LABEL_MAP.

Routing & docs

• .specs/architecture/PROVIDERS.md — three new rows in the Video Routing table, all defaulting to hyperframes with rationale.
• .env.example — adds HYPERFRAMES_ACTIVE=false with a note about the npx hyperframes doctor preflight (Node ≥ 22, FFmpeg on PATH).
• CLAUDE.md — Stack table and Skills Available list updated.
• PROGRESS.md — Checkpoint 3 recorded.

Routing matrix (Video) after this change

Task	Provider	Reason
Cinematic reel	higgsfield	Seedance 2.0
Motion control	higgsfield	DoP
UGC product holder	topview	avatar holds product
Product demo (URL)	topview	scrape + auto script
Talking head	topview	AI presenter
Batch hook test	wavespeed	cheap/fast
Motion typography	hyperframes	HTML/GSAP kinetic type, brand-faithful, deterministic
Data viz reel	hyperframes	declared variables → re-renderable charts
Programmatic short	hyperframes	parametrized HTML composition; byte-identical re-renders

Provider-agnostic contract

• No skill or agent body names hyperframes directly; selection flows through PROVIDERS.md + lib/router.ts + per-piece provider_override.video.
• DRY_RUN=true keeps everything on the mock; only flip HYPERFRAMES_ACTIVE=true after npx hyperframes doctor passes locally.

Test plan

• npm run typecheck (note: repo currently has a pre-existing missing-@types/node warning unrelated to this PR — should be fixed separately).
• Parse .specs/architecture/PROVIDERS.md via lib/providers/matrix.ts and assert the three new task kinds resolve to hyperframes (verified locally via the parser logic).
• DRY_RUN piece run with task_kind: programmatic_short resolves through video-prompt-builder → hyperframes-prompt-builder and writes a mock MP4 under outputs/.../mock-hyperframes-*.mp4.
• Once a credentialed environment has Node ≥ 22 + FFmpeg, HYPERFRAMES_ACTIVE=true + npx hyperframes doctor passes, then a real render produces an MP4 next to a manifest.json.
• npm run test:e2e stays green.

https://claude.ai/code/session_01H7AkCb3czV1qAwvUjPGWJC

---

Generated by Claude Code