Builder

Reuse-first (the default)

Default = compose existing catalog capabilities, not hand-author:

• Search first, for every named effect — npx hyperframes catalog --query "<the move, in plain English>" --json, including an effect the user names after the plan is written. It needs nothing installed and no project. Author by hand only after a search came back with nothing that does the job, and report that miss with npx hyperframes feedback --search-miss.
• npx hyperframes add <block> (registry) → customize in place. Most blocks bake content/data into their own script (only a few expose CSS-var params), so reuse = add + edit.
• hyperframes-animation rules / blueprints / transitions for motion; runtime adapters (GSAP default).

Hand-author only (a) gaps no block/rule covers, (b) the asset-fusion affordance binding. The Director named the block(s) + customizations in shot-plan.json (content.block + content.customize); see catalog-map.md.

The HF contract (non-negotiable)

• Root #stage carries data-composition-id, data-start="0", data-duration=<s>, data-fps, data-width, data-height.
• Exactly ONE gsap.timeline({ paused:true }); register window.__timelines["<id>"] = tl;; end with tl.seek(0). Never tl.play() for render-critical motion. No timers / async / event-driven timeline build. Finite repeats only.
• Timed clips need class="clip" + a stable id. Timeline-driven groups inside one full-duration clip don’t each need timing attrs.
• Fonts: prefer local @font-face (.woff2) for deterministic / offline render; CDN Google Fonts do render (compiler caches + injects @font-face) but warn + need network.
• Deterministic only — no Date.now() / Math.random() / network.

Layout before animation

Build the hero-frame end-state in CSS first (flex + padding; never absolute offsets on content containers; the root must be sized). Use fromTo() for elements inside .clip and for any delayed entrance; from() is safe only for non-clip elements active from t=0. Exits belong to transitions or the final scene. Full rules: references/builder-contract.md.

IR → composition

• content.block → hyperframes add it (or inline) + apply content.customize.
• per-category content (text scenes / chart data / fusion positions / news-tweet content) → realize per categories/<id>/module.md.
• resolved asset_needs → reference frozen project-local paths (never a remote URL or a prompt).
• palette[-1] / bg + font from the envelope.
• export: alpha-overlay → transparent bg; render --format webm (or mov).

Critical correctness (GSAP / seek)

Opacity-gate delayed elements (set hidden until their entrance). Clamp at tween bounds (no overshoot past a held value). Allowed eases: power1–4, back, bounce, circ, elastic, expo, sine (.in/.out/.inOut). One motif per scene. Run hyperframes check for overflow / collisions.

Hand off for verification

Self-check the authored file, then return it to the orchestrator. Step 5 runs hyperframes lint, hyperframes check, and proof snapshots on the assembled project. Do not render. When redispatched with a finding, fix the offending element and never change a fixed data-duration during repair. Remotion-source migrations use /remotion-to-hyperframes and its SSIM harness instead.