hyperframes: add HTML/CSS/GSAP as a parallel composition runtime
Separates creative grammar (renderer_family) from technical engine (render_runtime) so HyperFrames can stand alongside Remotion as a first-class runtime instead of masquerading as a Remotion sub-case. Locks runtime choice at proposal stage and enforces it end-to-end: the schemas require it, video_compose routes by it, the reviewer fails closed on silent swaps, and a parametrized contract test walks every pipeline manifest to ensure each planning-stage skill explains the conversation to the user. Adds hyperframes_compose (scaffold/lint/ validate/render/doctor/add_block), a playbook -> CSS style bridge, and vendored HyperFrames Layer 3 skills from commit d291358, pinned via PROVENANCE.md for future re-sync. Final_review now records render_runtime_used and runtime_swap_detected so compose lies are catchable after the fact.
This commit is contained in:
calesthio
@@ -1,18 +1,67 @@
|
||||
# Animation Runtime Selector
|
||||
|
||||
Meta-skill that answers: *"for the animated scene I'm about to build, which runtime + Layer 3 skills should I reach for?"*
|
||||
Meta-skill that answers two questions:
|
||||
|
||||
Read this before authoring any animated Remotion component or HyperFrames composition. It routes you to the right Layer 3 skill so you don't waste time hand-rolling what a plugin already solves.
|
||||
1. **Which composition runtime should this video use?** — Remotion, HyperFrames, or FFmpeg.
|
||||
2. **Which animation library / Layer 3 skills should this scene reach for?** — Remotion primitives, GSAP plugins, framer-motion, Lottie, Manim, D3.
|
||||
|
||||
Read this before authoring any animated component or composition, and whenever you're choosing `render_runtime` at proposal time. It routes you to the right Layer 3 skill so you don't waste time hand-rolling what a plugin already solves.
|
||||
|
||||
## When to use this skill
|
||||
|
||||
Apply when:
|
||||
- **Proposal stage** needs to lock `render_runtime` (remotion / hyperframes / ffmpeg)
|
||||
- A stage director (asset, edit, compose) needs to author an animated component
|
||||
- An agent is about to write Remotion JSX for a scene that involves text reveals, SVG motion, curved camera paths, shape morphs, or multi-stage choreography
|
||||
- An agent is asked to build a HyperFrames composition
|
||||
- An agent is uncertain whether to reach for a GSAP plugin vs inline `interpolate()`/`spring()`
|
||||
|
||||
## Decision matrix
|
||||
## Runtime choice (Remotion vs HyperFrames vs FFmpeg)
|
||||
|
||||
OpenMontage separates creative grammar (`renderer_family`) from technical
|
||||
engine (`render_runtime`). Both are locked at proposal and carried through
|
||||
`edit_decisions` unchanged. Silent runtime swaps at compose time are a
|
||||
contract violation.
|
||||
|
||||
### HARD RULE — present both runtimes, don't silently default
|
||||
|
||||
When both Remotion AND HyperFrames are available on the machine (check
|
||||
`video_compose.get_info()["render_engines"]`), the agent MUST present both
|
||||
options to the user before locking `render_runtime`. The decision matrix
|
||||
below is the agent's input for the conversation, NOT a license to silently
|
||||
pick the "default" entry. See `AGENT_GUIDE.md` → "Present Both Composition
|
||||
Runtimes" for the full contract.
|
||||
|
||||
Concretely, at the proposal stage:
|
||||
|
||||
1. Query `video_compose.get_info()["render_engines"]` to find which
|
||||
runtimes are available on this machine.
|
||||
2. If both Remotion and HyperFrames are available, present both to the
|
||||
user with: one-line description tailored to the brief, one-line
|
||||
honest tradeoff, agent's recommendation with reason.
|
||||
3. Wait for explicit user approval.
|
||||
4. Log the decision in `decision_log` with category
|
||||
`render_runtime_selection` and both runtimes in `options_considered`.
|
||||
5. Only then write `render_runtime` into `proposal_packet.production_plan`.
|
||||
|
||||
A `render_runtime_selection` decision with only one option considered
|
||||
when both were available is a CRITICAL reviewer finding.
|
||||
|
||||
| Brief characteristic | `render_runtime` | Read |
|
||||
|---|---|---|
|
||||
| Existing React scene stack (text_card, stat_card, chart, caption overlay, TalkingHead, CinematicRenderer) | **remotion** | `skills/core/remotion.md` |
|
||||
| Word-level caption burn / karaoke captions | **remotion** | `skills/core/remotion.md` |
|
||||
| Avatar / lip-sync / presenter | **remotion** | `skills/core/remotion.md` |
|
||||
| Kinetic typography, HTML/GSAP-native motion, product promo, launch reel | **hyperframes** | `skills/core/hyperframes.md` + `.agents/skills/hyperframes/SKILL.md` |
|
||||
| Website → video, UI-driven composition | **hyperframes** | `.agents/skills/website-to-hyperframes/SKILL.md` |
|
||||
| Registry block needed (data-chart, grain-overlay, shader transitions, etc.) | **hyperframes** | `.agents/skills/hyperframes-registry/SKILL.md` |
|
||||
| Pure concat / trim of source clips, no composition needed | **ffmpeg** | `skills/core/ffmpeg.md` |
|
||||
| Selected runtime is unavailable | **escalate** — do not substitute silently | `AGENT_GUIDE.md` → Escalate Blockers |
|
||||
|
||||
Read `skills/core/hyperframes.md` for the full Remotion-vs-HyperFrames
|
||||
decision matrix and the list of features that stay Remotion-only in Phase 1.
|
||||
|
||||
## Animation library decision matrix
|
||||
|
||||
| Animation need | Recommended runtime | Read first |
|
||||
|---|---|---|
|
||||
@@ -32,7 +81,9 @@ Apply when:
|
||||
| Mathematical / scientific visualization | Manim | `.agents/skills/manim-composer`, `.agents/skills/manimce-best-practices` |
|
||||
| D3 data-driven visualization | D3 | `.agents/skills/d3-viz` |
|
||||
| Data chart (bar/line/pie/KPI) | Remotion built-in chart components | `remotion-composer/SCENE_TYPES.md` |
|
||||
| HyperFrames composition (any motion) | HyperFrames + GSAP (mandatory) | `.agents/skills/gsap-core`, `.agents/skills/gsap-timeline` |
|
||||
| HyperFrames composition (any motion) | HyperFrames + GSAP (mandatory) | `.agents/skills/hyperframes` + `.agents/skills/gsap-core`, `.agents/skills/gsap-timeline` |
|
||||
| HyperFrames composition CLI work (lint/validate/render) | HyperFrames CLI | `.agents/skills/hyperframes-cli` |
|
||||
| HyperFrames registry block install (`hyperframes add ...`) | HyperFrames registry | `.agents/skills/hyperframes-registry` |
|
||||
|
||||
## The "keep it simple" bias
|
||||
|
||||
|
||||
@@ -40,12 +40,38 @@ Based on discovery, classify the setup:
|
||||
|
||||
| Tier | What's Available | Best Pipelines |
|
||||
|------|-----------------|----------------|
|
||||
| **Zero-key** | Piper TTS + Pexels/Pixabay stock (if keys added) + Remotion + FFmpeg | Animated Explainer (stock visuals + free narration) |
|
||||
| **Starter** | One configured image generation provider + free TTS + Remotion | Animated Explainer, Animation (AI-generated visuals) |
|
||||
| **Zero-key** | Piper TTS + Pexels/Pixabay stock (if keys added) + Remotion and/or HyperFrames + FFmpeg | Animated Explainer (stock visuals + free narration) |
|
||||
| **Starter** | One configured image generation provider + free TTS + Remotion and/or HyperFrames | Animated Explainer, Animation (AI-generated visuals) |
|
||||
| **Standard** | Image gen + TTS + music gen | Animated Explainer, Animation, Screen Demo, Hybrid |
|
||||
| **Full** | Video gen + image gen + premium TTS + music | All pipelines including Cinematic, Avatar, Talking Head |
|
||||
| **Full + GPU** | Cloud APIs + local video gen models | All pipelines with free local fallbacks |
|
||||
|
||||
**Composition runtimes** — both are first-class and surface as distinct
|
||||
entries in the provider menu. Report each one's availability separately:
|
||||
|
||||
- **Remotion** requires Node.js + `npx` + `remotion-composer/` + `node_modules`.
|
||||
Best for React-based scene components (text cards, stat cards, charts),
|
||||
word-level captions, and the `TalkingHead` avatar composition.
|
||||
- **HyperFrames** requires Node.js ≥ 22 + `npx` + FFmpeg. Consumed via
|
||||
`npx @hyperframes/cli` (no monorepo checkout required). Best for
|
||||
HTML/CSS/GSAP motion graphics — kinetic typography, product promos,
|
||||
launch reels, website-to-video workflows, registry blocks.
|
||||
|
||||
Name BOTH runtimes explicitly in the "Ready to go" summary when both are
|
||||
available — not "Remotion" alone. A fresh-session agent that doesn't
|
||||
mention HyperFrames by name will fail to present it at proposal time;
|
||||
naming it here sets the expectation that the agent is runtime-agnostic.
|
||||
|
||||
If only one is available, note it in the summary and mention what the
|
||||
other would unlock. If neither is available, tell the user their options
|
||||
are FFmpeg-only (simple concat/trim) and what's needed to unlock HTML/React
|
||||
composition.
|
||||
|
||||
**Do NOT pick a runtime during onboarding.** Runtime selection happens at
|
||||
the proposal stage, after the agent understands the brief. During
|
||||
onboarding you're reporting capabilities, not making production decisions.
|
||||
See `AGENT_GUIDE.md` → "Present Both Composition Runtimes (HARD RULE)".
|
||||
|
||||
### Step 3: Greet and Orient
|
||||
|
||||
Present a **short, friendly capability summary**. Do NOT dump the raw provider menu. Instead, translate it into plain language.
|
||||
|
||||
+13
-1
@@ -108,7 +108,7 @@ Structure your review as:
|
||||
| Stage | What matters most |
|
||||
|-------|-----------------|
|
||||
| research | Source diversity, claim verifiability, visual reference quality |
|
||||
| proposal | Delivery promise clarity, renderer family selection, music/voice plan, decision log started |
|
||||
| proposal | Delivery promise clarity, renderer family AND render runtime selection, music/voice plan, decision log started |
|
||||
| idea | Hook uniqueness, research depth, angle diversity |
|
||||
| script | Timing accuracy, narrative arc, enhancement cue density |
|
||||
| scene_plan | Full coverage, visual variety, asset feasibility, slideshow risk score |
|
||||
@@ -220,6 +220,18 @@ Run at **scene_plan** and **edit** stages. Prevents the "every video looks the s
|
||||
- Does `renderer_family` in edit_decisions match what was set at proposal?
|
||||
- If changed without documented reason in decision log → **CRITICAL**
|
||||
|
||||
5. **Render runtime match** (edit and compose stages):
|
||||
- `render_runtime` in edit_decisions must match proposal_packet.production_plan.render_runtime
|
||||
- If changed without a `render_runtime_selection` decision logged in decision_log → **CRITICAL**
|
||||
- At compose stage, `final_review.checks.promise_preservation.runtime_swap_detected` must be `false`. If `true` without an approved `render_runtime_selection` decision → **CRITICAL**
|
||||
- Runtime unavailable at compose time is not an excuse for silent swap — the correct behavior is to escalate, get approval, log a decision, then run.
|
||||
|
||||
6. **Runtime selection presented both options** (proposal stage, MANDATORY):
|
||||
- Query `video_compose.get_info()["render_engines"]`. If both `remotion` and `hyperframes` show `True`, the `render_runtime_selection` decision in `decision_log` MUST have BOTH runtimes in `options_considered`.
|
||||
- A `render_runtime_selection` with only one runtime in `options_considered` when both were available on the machine → **CRITICAL**. The agent silently defaulted; the user was not presented the alternative. Re-open the proposal stage and present both.
|
||||
- If only one runtime was available, `options_considered` must still list the unavailable one with `rejected_because: "runtime not available on this machine"` — otherwise the audit trail loses the fact that the choice was constrained, not discretionary.
|
||||
- Per AGENT_GUIDE.md > "Present Both Composition Runtimes (HARD RULE)": the pipeline's suggested "default" runtime is NOT a license to skip the conversation with the user.
|
||||
|
||||
## Delivery Promise Review
|
||||
|
||||
Run at **edit** and **compose** stages. Uses `lib/delivery_promise.py`.
|
||||
|
||||
Reference in New Issue
Block a user