Imported from JonSvitna/CraftedByChris (hyperframes/instagram-reel-cbc/AGENTS.md). Install upstream with npx skills add JonSvitna/CraftedByChris --skill instagram-reel-cbc. Copyright stays with the author.

HyperFrames Composition Project

Skills

This project uses AI agent skills for framework-specific patterns. Install them if not already present:

npx skills add heygen-com/hyperframes

Skills encode patterns like window.__timelines registration, data-* attribute semantics, Tailwind v4 browser-runtime styling for --tailwind projects, and shader-compatible CSS rules that are not in generic web docs. Using them produces correct compositions from the start.

Commands

npm run dev          # start the preview server (long-running — keep it alive in background)
npm run check        # lint + validate + inspect
npm run render       # render to MP4
npm run publish      # publish and get a shareable link
npx hyperframes docs <topic> # reference docs in terminal

npm run dev is a long-running server, not a one-shot command. It blocks until stopped. Always run it as a background process so it stays alive while you edit compositions. Running it in the foreground will time out and kill the server, breaking the browser preview.

Project Structure

• index.html — main composition (root timeline)
• compositions/ — sub-compositions referenced via data-composition-src
• assets/ — media files (video, audio, images)
• meta.json — project metadata (id, name)
• transcript.json — whisper word-level transcript (if generated)

Linting — Always Run After Changes

After creating or editing any .html composition, run the full check before considering the task complete:

npm run check

Fix all errors before presenting the result.

Key Rules

1. Every timed element needs data-start, data-duration, and data-track-index
2. Visible timed elements must have class="clip" — the framework uses this for visibility control
3. GSAP timelines must be paused and registered on window.__timelines:

   window.__timelines = window.__timelines || {};
   window.__timelines["composition-id"] = gsap.timeline({ paused: true });

4. Videos use muted with a separate <audio> element for the audio track
5. Sub-compositions use data-composition-src="compositions/file.html"
6. Only deterministic logic — no Date.now(), no Math.random(), no network fetches

Documentation

Full docs: https://hyperframes.heygen.com/introduction

Machine-readable index for AI tools: https://hyperframes.heygen.com/llms.txt