HyperFrames CLI

Everything runs through npx hyperframes. Requires Node.js >= 22 and FFmpeg.

Workflow

1. Scaffold — npx hyperframes init my-video
2. Write — author HTML composition (see the hyperframes skill)
3. Publish + auto-render — call the create_hyperframes_composition tool. It writes the HTML under artifacts/compositions/, renders it to an MP4 under artifacts/renders/, uploads the MP4 to storage, and returns a signed video_mp4_url you can give the user.
4. (Optional) Lint — npx hyperframes lint artifacts/ (only needed if you want stricter validation)
5. (Optional) Preview — cd artifacts && npx hyperframes preview (studio/hot-reload iteration)

Do NOT separately run npx hyperframes render — create_hyperframes_composition already rendered the MP4 and registered a tracked video artifact. Running render a second time would overwrite the MP4 but skip storage upload + artifact registration, and the user would lose the signed URL. If you need to re-render (e.g. you changed the HTML), just call create_hyperframes_composition again with the same path — the tool upserts.

Success criteria: render_status=ready plus a playable video_mp4_url means the render pipeline completed. It does not guarantee the composition is visually good. A READY render can still be a blank frame, a static frame, clipped text, or bad choreography if the HTML/CSS/GSAP is wrong.

Lint before preview — catches missing data-composition-id, overlapping tracks, unregistered timelines.

Agent sandbox note: inside the Cofounder sandbox, create_hyperframes_composition writes to artifacts/compositions/*.html, stages the render in hidden workspace scratch if needed, promotes the finished MP4 into artifacts/renders/<slug>.mp4, and registers artifacts/compositions/<slug>.video.json. Lint and preview target artifacts/ so the CLI scans the same tree the tool writes to.