|
| 1 | +# HyperFrames Composition Project |
| 2 | + |
| 3 | +## Skills — USE THESE FIRST |
| 4 | + |
| 5 | +**Always invoke the relevant skill before writing or modifying compositions.** Skills encode framework-specific patterns (e.g., `window.__timelines` registration, `data-*` attribute semantics, shader-compatible CSS rules) that are NOT in generic web docs. Skipping them produces broken compositions. |
| 6 | + |
| 7 | +**Doing anything with HyperFrames?** Start at `/hyperframes` — it tells you what HyperFrames can do and which skill or workflow handles your intent (make a video, TTS / BGM, prep footage, author / animate, render, install blocks), confirms your brief up front (the intent layer), and routes every "make me a…" request (a video, a deck, a composition port) to the right workflow. Read it first, especially when there's no project context to orient you. The workflows it routes to: |
| 8 | + |
| 9 | +- `/product-launch-video` — any **website** URL or brief / script → a product launch / SaaS / promo video, or a site tour / showcase featuring the site's own captured visuals. |
| 10 | +- `/faceless-explainer` — arbitrary text (topic / article / notes), **no URL, no website capture** → 60-90s faceless explainer. |
| 11 | +- `/embedded-captions` — an existing talking-head video (MP4) → the same footage with captions / subtitles added (rail + embed, or pure-cinematic embed); the footage itself is untouched. |
| 12 | +- `/talking-head-recut` — an existing talking-head / interview / podcast video (MP4) → the same footage **packaged with designed graphic overlays** (kinetic titles, lower-thirds, data callouts, pull-quotes, side panels, pip) synced to the transcript; the clip plays unchanged underneath. (Plain captions/subtitles → `/embedded-captions`.) |
| 13 | +- `/pr-to-video` — a GitHub PR (URL / `owner/repo#N` / "this PR") → 30-90s code-change explainer (changelog / feature reveal / fix / refactor). |
| 14 | +- `/motion-graphics` — a short (typically under 10s) design-led **motion graphic**, motion-is-the-message, no narration: kinetic type, a stat / number count-up, a chart, a logo sting, a lower-third / overlay, or an animated tweet / headline / captured-page highlight; rendered to MP4 or a transparent overlay. Longer / narrated / custom → `/general-video`. |
| 15 | +- `/music-to-video` — a **music track** (audio file, video to pull audio from, or one generated from a mood brief) → beat-synced video (lyric / slideshow / kinetic promo). Music drives pacing; user-supplied images / videos are cut onto the same beat grid. |
| 16 | +- `/slideshow` — a **presentation / pitch deck / interactive deck** — discrete slides, fragment reveals, branching, hotspot navigation, presenter mode. Output is a navigable deck, not a rendered video. |
| 17 | +- `/general-video` — fallback for any other video (title card, longer brand / sizzle reel, multi-scene montage, static loop, custom composition) and the home of **companion mode** — co-create with the full HyperFrames toolbox; the original hyperframes authoring flow, any length. |
| 18 | + |
| 19 | +**Porting an existing composition?** `/remotion-to-hyperframes` translates a Remotion (React) composition into HyperFrames HTML — a source migration, separate from the creation workflows above. |
| 20 | + |
| 21 | +The domain skills (`/hyperframes-core`, `/hyperframes-animation`, `/hyperframes-keyframes`, `/hyperframes-creative`, `/hyperframes-cli`, `/media-use`, `/hyperframes-audio`, `/hyperframes-registry`, `/figma`) and the full capability map live inside `/hyperframes` — it is the single source of truth for which skill handles which intent. |
| 22 | + |
| 23 | +**Changing how real footage or images look or reveal?** Load `/media-use` and read its `references/media-treatments.md` before editing, even when the request only says dark, flat, boring, retro, private, or “make the reveal cooler.” It governs how footage is treated, never whether media may be used. Use canonical media treatments and seek-safe motion; do not improvise equivalent CSS/SVG filters or overlays. |
| 24 | + |
| 25 | +> **Tailwind v4 projects** (`hyperframes init --tailwind`): see `/hyperframes-core` → `references/tailwind.md`. |
| 26 | +
|
| 27 | +> **Skill missing or stale?** Run `npx hyperframes skills update <name>` to install/refresh |
| 28 | +> the specific skill you need (the `/hyperframes` router does this automatically before |
| 29 | +> entering a workflow), or bare `npx hyperframes skills update` to refresh the core set plus |
| 30 | +> everything already installed — neither pulls the full set. Restart the agent session so |
| 31 | +> newly installed skills load. |
| 32 | +
|
| 33 | +## Commands |
| 34 | + |
| 35 | +```bash |
| 36 | +npm run dev # human-operated foreground preview (blocks until stopped) |
| 37 | +npx hyperframes preview --background # agent-safe persistent Studio preview |
| 38 | +npx hyperframes preview --status # verify the persistent preview is listening |
| 39 | +npx hyperframes preview --stop # stop it when review is finished |
| 40 | +npm run check # lint + runtime + layout + motion + contrast (one command) |
| 41 | +npm run render # render to MP4 |
| 42 | +npm run publish # publish and get a shareable link |
| 43 | +npx hyperframes lint --verbose # include info-level findings |
| 44 | +npx hyperframes lint --json # machine-readable output for CI |
| 45 | +npx hyperframes docs <topic> # reference docs in terminal |
| 46 | +``` |
| 47 | + |
| 48 | +> **Agents must use `npx hyperframes preview --background` for Studio handoff.** Do not rely |
| 49 | +> on a shell/tool `run_in_background` wrapper around `npm run dev`: that foreground process |
| 50 | +> remains owned by the invoking session and can disappear while the browser stays open, |
| 51 | +> leaving refreshes at `ERR_CONNECTION_TIMED_OUT`. Verify with `preview --status`, keep it |
| 52 | +> alive through review, and stop it explicitly with `preview --stop` afterward. |
| 53 | +
|
| 54 | +> **Pinned CLI version.** These scripts pin an exact `hyperframes@X.Y.Z` so this project re-renders identically over time. Weeks later that pin lags fixes shipped since. To move up: `npx hyperframes@latest upgrade --project . --check` (shows the delta), then `npx hyperframes@latest upgrade --project .` to rewrite the pins. Always unpinned — the pinned script re-runs the old version against itself. |
| 55 | +
|
| 56 | +## Documentation |
| 57 | + |
| 58 | +**For quick reference**, use the local CLI docs command (no network required): |
| 59 | + |
| 60 | +```bash |
| 61 | +npx hyperframes docs <topic> |
| 62 | +``` |
| 63 | + |
| 64 | +Topics: `data-attributes`, `gsap`, `compositions`, `rendering`, `examples`, `troubleshooting` |
| 65 | + |
| 66 | +**For full documentation**, discover pages via the machine-readable index — do NOT guess URLs: |
| 67 | + |
| 68 | +``` |
| 69 | +https://hyperframes.heygen.com/llms.txt |
| 70 | +``` |
| 71 | + |
| 72 | +## Project Structure |
| 73 | + |
| 74 | +- `index.html` — main composition (root timeline) |
| 75 | +- `compositions/` — sub-compositions referenced via `data-composition-src` |
| 76 | +- `meta.json` — project metadata (id, name) |
| 77 | +- `transcript.json` — whisper word-level transcript (if generated) |
| 78 | + |
| 79 | +## Linting — ALWAYS RUN AFTER CHANGES |
| 80 | + |
| 81 | +After creating or editing any `.html` composition, **always** run the full check before considering the task complete: |
| 82 | + |
| 83 | +```bash |
| 84 | +npm run check |
| 85 | +``` |
| 86 | + |
| 87 | +Fix all errors before presenting the result. Warnings should be reviewed before rendering. |
| 88 | + |
| 89 | +## Key Rules |
| 90 | + |
| 91 | +1. Every timed element needs `data-start` and a duration. `data-start` is what marks it as timed; `data-track-index` is an optional Studio display lane the render never reads |
| 92 | +2. Give timed visual elements `class="clip"`. The framework keys visibility off `data-start`, not the class, but the shared `.clip` CSS is what gives a scene its full-frame box, and `lint` warns without it |
| 93 | +3. Register one paused root timeline per composition on `window.__timelines`: |
| 94 | + ```js |
| 95 | + window.__timelines = window.__timelines || {}; |
| 96 | + window.__timelines["composition-id"] = gsap.timeline({ paused: true }); |
| 97 | + ``` |
| 98 | + Scene timelines manually added to this root must not be paused. A paused |
| 99 | + child does not advance when the root is seeked. The runtime activates |
| 100 | + registered composition siblings, not arbitrary nested scene timelines. |
| 101 | +4. Videos use `muted` with a separate `<audio>` element for the audio track |
| 102 | +5. Sub-compositions use `data-composition-src="compositions/file.html"` to reference other HTML files |
| 103 | +6. Only deterministic logic — no `Date.now()`, no `Math.random()`, no network fetches |
0 commit comments