diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index f305f6ed8..e5d61e0ec 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "hyperframes", - "description": "HyperFrames by HeyGen. Write HTML, render video. Compositions, GSAP and runtime adapter animations, captions, voiceovers, audio-reactive visuals, and website-to-video capture for HyperFrames.", + "description": "HyperFrames by HeyGen. Write HTML, render video. Default lightweight video skill with CLI preflight, GSAP, and runtime adapter animation patterns.", "version": "0.1.0", "author": { "name": "HeyGen", diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index a7ed04b3d..58a485f1e 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "hyperframes", "version": "0.1.0", - "description": "Write HTML, render video. Compositions, Tailwind v4 styles, GSAP and runtime adapter animations, captions, voiceovers, audio-reactive visuals, and website-to-video capture for HyperFrames.", + "description": "Write HTML, render video. Default lightweight HyperFrames video skill with CLI preflight, Tailwind v4 styles, GSAP, and runtime adapter animation patterns.", "author": { "name": "HeyGen", "email": "hyperframes@heygen.com", @@ -31,7 +31,7 @@ "interface": { "displayName": "HyperFrames by HeyGen", "shortDescription": "Write HTML, render video", - "longDescription": "Build videos from HTML with HyperFrames. Author compositions with HTML, CSS, Tailwind v4 browser-runtime styles, GSAP, Anime.js, Lottie, Three.js, and WAAPI adapter patterns, use the CLI for init/preview/render/transcribe/tts, install reusable registry blocks and components, and turn any website into a video with the 7-step capture-to-video pipeline.", + "longDescription": "Build videos from HTML with HyperFrames. Use the lightweight default video skill to check local runtime dependencies before invoking the CLI, author compositions with HTML, CSS, Tailwind v4 browser-runtime styles, GSAP, Anime.js, Lottie, Three.js, and WAAPI adapter patterns, and install reusable registry blocks and components.", "developerName": "HeyGen", "category": "Design", "capabilities": ["Read", "Write"], diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index 8d0d060d3..f797830c0 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -3,7 +3,7 @@ "name": "hyperframes", "displayName": "HyperFrames by HeyGen", "version": "0.1.0", - "description": "Write HTML, render video. Compositions, Tailwind v4 styles, GSAP and runtime adapter animations, captions, voiceovers, audio-reactive visuals, and website-to-video capture for HyperFrames.", + "description": "Write HTML, render video. Default lightweight HyperFrames video skill with CLI preflight, Tailwind v4 styles, GSAP, and runtime adapter animation patterns.", "author": { "name": "HeyGen", "email": "hyperframes@heygen.com" diff --git a/README.md b/README.md index 9cf27eaf5..6ecbfd355 100644 --- a/README.md +++ b/README.md @@ -29,41 +29,43 @@ Hyperframes is an open-source video rendering framework that lets you create, pr Install the HyperFrames skills, then describe the video you want: ```bash -npx skills add heygen-com/hyperframes +npx skills add heygen-com/hyperframes --full-depth ``` -This teaches your agent (Claude Code, Cursor, Gemini CLI, Codex) how to write correct compositions, GSAP timelines, Tailwind v4 browser-runtime styles, and first-party adapter animations. In Claude Code, the skills register as slash commands — invoke `/hyperframes` to author compositions, `/hyperframes-cli` for CLI commands, `/tailwind` for `init --tailwind` projects, `/gsap` for timeline animation help, or the adapter skills (`/animejs`, `/css-animations`, `/lottie`, `/three`, `/waapi`) when a composition uses those runtimes. +This teaches your agent (Claude Code, Cursor, Gemini CLI, Codex) to use HyperFrames as the default HTML video path, check local runtime dependencies before invoking the CLI, write correct GSAP timelines, use Tailwind v4 browser-runtime styles, and follow first-party adapter animation patterns. In Claude Code, the skills register as slash commands — invoke `/hyperframes` for the lightweight video entry point, `/hyperframes-cli` for CLI commands, `/tailwind` for `init --tailwind` projects, `/gsap` for timeline animation help, or the adapter skills (`/animejs`, `/css-animations`, `/lottie`, `/three`, `/waapi`) when a composition uses those runtimes. For Claude Design, open [`docs/guides/claude-design-hyperframes.md`](https://github.com/heygen-com/hyperframes/blob/main/docs/guides/claude-design-hyperframes.md) on GitHub and click the download button (↓) to save it, then attach the file to your Claude Design chat. It produces a valid first draft; refine in any AI coding agent. See the [Claude Design guide](https://hyperframes.heygen.com/guides/claude-design). For Codex specifically, the same skills are also exposed as an [OpenAI Codex plugin](./.codex-plugin/plugin.json) — sparse-install just the plugin surface: ```bash -codex plugin marketplace add heygen-com/hyperframes --sparse .codex-plugin --sparse skills --sparse assets +codex plugin marketplace add heygen-com/hyperframes --sparse .codex-plugin --sparse skills --sparse optional-skills --sparse assets ``` +The default `skills/hyperframes` video entry point is intentionally lightweight. It verifies the local CLI/runtime environment before use and routes agents to optional production guidance only when detailed authoring references are explicitly enabled. + For Claude Code, the repo also ships a [Claude Code plugin manifest](./.claude-plugin/plugin.json): test it locally with `claude --plugin-dir .`. The manifest intentionally omits `skills` because Claude Code auto-discovers the root `skills/` directory by convention, and for marketplace submission use the title `HyperFrames by HeyGen` plus the black/white icon assets at [`assets/claude-code-icon-dark.svg`](./assets/claude-code-icon-dark.svg) and [`assets/claude-code-icon-light.svg`](./assets/claude-code-icon-light.svg) for the two theme slots. For Cursor, the same skills are packaged as a [Cursor plugin](./.cursor-plugin/plugin.json) — install from the Cursor Marketplace, or sideload by cloning this repo and pointing **Settings → Plugins → Load unpacked** at the repo root. #### Try it: example prompts -Copy any of these into your agent to get started. The `/hyperframes` prefix loads the skill context explicitly so you get correct output the first time. +Copy any of these into your agent to get started. The `/hyperframes` prefix loads the lightweight entry point so the agent checks the local environment before using the CLI. **Cold start — describe what you want:** -> Using `/hyperframes`, create a 10-second product intro with a fade-in title, a background video, and background music. +> Create a 10-second product intro with a fade-in title, a background video, and background music. Use `/hyperframes` first to check the local environment. **Warm start — turn existing context into a video:** -> Take a look at this GitHub repo https://github.com/heygen-com/hyperframes and explain its uses and architecture to me using `/hyperframes`. +> Take a look at this GitHub repo https://github.com/heygen-com/hyperframes and explain its uses and architecture to me with a short HyperFrames video. -> Summarize the attached PDF into a 45-second pitch video using `/hyperframes`. +> Summarize the attached PDF into a 45-second pitch video. -> Turn this CSV into an animated bar chart race using `/hyperframes`. +> Turn this CSV into an animated bar chart race. **Format-specific:** -> Make a 9:16 TikTok-style hook video about [topic] using `/hyperframes`, with bouncy captions synced to a TTS narration. +> Make a 9:16 TikTok-style hook video about [topic], with bouncy captions synced to a TTS narration. **Iterate — talk to the agent like a video editor:** @@ -182,15 +184,14 @@ Full documentation at **[hyperframes.heygen.com/introduction](https://hyperframe HyperFrames ships [skills](https://github.com/vercel-labs/skills) that teach AI agents framework-specific patterns that generic docs don't cover. ```bash -npx skills add heygen-com/hyperframes +npx skills add heygen-com/hyperframes --full-depth ``` | Skill | What it teaches | | ------------------------- | ------------------------------------------------------------------------------------------------------------------- | -| `hyperframes` | HTML composition authoring, captions, TTS, audio-reactive animation, transitions | +| `hyperframes` | Lightweight default entry point, environment preflight, and routing to the CLI/docs or optional production skill | | `hyperframes-cli` | CLI commands: init, lint, preview, render, transcribe, tts, doctor | | `hyperframes-registry` | Block and component installation via `hyperframes add` | -| `website-to-hyperframes` | Capture a URL and turn it into a video — full website-to-video pipeline | | `remotion-to-hyperframes` | Translate a Remotion (React) composition into a HyperFrames HTML composition | | `gsap` | GSAP timelines for HyperFrames: paused registration, deterministic seeking, easing, sequencing, performance | | `animejs` | Anime.js animations and timelines registered on `window.__hfAnime` for deterministic HyperFrames seeking | @@ -199,6 +200,14 @@ npx skills add heygen-com/hyperframes | `three` | Three.js scenes that render from HyperFrames `hf-seek` events and `window.__hfThreeTime` instead of wall-clock time | | `waapi` | Web Animations API `element.animate()` patterns seeked through `document.getAnimations()` | +Optional skills live under `optional-skills/` so default skill bundles do not need to carry the detailed authoring references and helper assets unless those workflows are explicitly enabled. +The install command above uses `--full-depth` so people explicitly installing HyperFrames get these production workflows too. + +| Optional skill | What it adds | +| ------------------------ | ----------------------------------------------------------------------------------------------------------------- | +| `hyperframes-production` | Full production authoring workflow: design systems, captions, TTS, audio-reactive animation, transitions, helpers | +| `website-to-hyperframes` | Full website-to-video pipeline for capturing a URL and turning it into a video | + ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. @@ -222,7 +231,7 @@ winget install GitHub.GitLFS git lfs install ``` -If you hit `git-lfs filter-process: command not found` during `git clone` or `npx skills add heygen-com/hyperframes`, install Git LFS and retry. You can also skip LFS content if you only need the source files: +If you hit `git-lfs filter-process: command not found` during `git clone` or `npx skills add heygen-com/hyperframes --full-depth`, install Git LFS and retry. You can also skip LFS content if you only need the source files: ```bash GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/heygen-com/hyperframes.git diff --git a/docs/guides/claude-design-hyperframes.md b/docs/guides/claude-design-hyperframes.md index 86f5bb0f6..e022d4804 100644 --- a/docs/guides/claude-design-hyperframes.md +++ b/docs/guides/claude-design-hyperframes.md @@ -496,7 +496,7 @@ Opens the HyperFrames Studio at `http://localhost:3002` with frame-accurate scru This project was drafted in Claude Design. To polish animations, timing, and pacing: ```bash -npx skills add heygen-com/hyperframes # install HyperFrames skills (one-time) +npx skills add heygen-com/hyperframes --full-depth # install HyperFrames skills (one-time) npx hyperframes lint # verify structure (should pass with zero errors) npx hyperframes preview # open the studio for live feedback ``` @@ -1222,8 +1222,8 @@ tl.to("#s5-headline", { backgroundSize: "100% 30%", duration: 0.6, ease: "power2 Everything critical is inlined above. These are for edge cases: - Core composition contract (data attributes, sub-comp wiring): https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes/SKILL.md -- Motion theory (easing as emotion, direction rules): https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes/references/motion-principles.md -- Typography (full banned list, weight contrast, OpenType): https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes/references/typography.md -- Transitions (shader catalog, CSS transition patterns): https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes/references/transitions.md -- Captions synced to audio: https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes/references/captions.md +- Motion theory (easing as emotion, direction rules): https://github.com/heygen-com/hyperframes/blob/main/optional-skills/hyperframes/references/motion-principles.md +- Typography (full banned list, weight contrast, OpenType): https://github.com/heygen-com/hyperframes/blob/main/optional-skills/hyperframes/references/typography.md +- Transitions (shader catalog, CSS transition patterns): https://github.com/heygen-com/hyperframes/blob/main/optional-skills/hyperframes/references/transitions.md +- Captions synced to audio: https://github.com/heygen-com/hyperframes/blob/main/optional-skills/hyperframes/references/captions.md - Full docs: https://hyperframes.heygen.com/ diff --git a/docs/guides/claude-design.mdx b/docs/guides/claude-design.mdx index 60cbfd31f..ecd757415 100644 --- a/docs/guides/claude-design.mdx +++ b/docs/guides/claude-design.mdx @@ -23,7 +23,7 @@ Claude Design produces a **valid first draft** of a HyperFrames video — brand Open the project in Claude Code, Cursor, Codex, or any agent with terminal access for animation polish, timing, and production QA. ```bash - npx skills add heygen-com/hyperframes # install skills (one-time) + npx skills add heygen-com/hyperframes --full-depth # install skills (one-time) npx hyperframes lint # should pass with zero errors npx hyperframes preview # open the studio ``` @@ -39,8 +39,8 @@ Claude Design produces a **valid first draft** of a HyperFrames video — brand | Surface | Recommended setup | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | Claude Design | Download [`claude-design-hyperframes.md`](https://github.com/heygen-com/hyperframes/blob/main/docs/guides/claude-design-hyperframes.md) from GitHub and attach to your chat | -| Claude Code | `npx skills add heygen-com/hyperframes`, then use `/hyperframes` | -| Cursor / Codex / Gemini CLI | `npx skills add heygen-com/hyperframes` | +| Claude Code | `npx skills add heygen-com/hyperframes --full-depth`, then use `/hyperframes` | +| Cursor / Codex / Gemini CLI | `npx skills add heygen-com/hyperframes --full-depth` | ## How it works @@ -124,7 +124,7 @@ The more specific your prompt, the better the output. Include palette, fonts, du Claude Design's output is a valid first draft. Open it in Claude Code, Cursor, Codex, or any AI coding agent with terminal access: ```bash -npx skills add heygen-com/hyperframes # one-time setup +npx skills add heygen-com/hyperframes --full-depth # one-time setup npx hyperframes lint # verify structure npx hyperframes preview # open the studio ``` diff --git a/docs/guides/open-design.mdx b/docs/guides/open-design.mdx index d79acf514..1e3c93760 100644 --- a/docs/guides/open-design.mdx +++ b/docs/guides/open-design.mdx @@ -35,7 +35,7 @@ Open Design produces a **valid first draft** of a HyperFrames composition — pa The Open Design project folder is already a real on-disk working directory. Hand it off to Claude Code, Cursor, Codex, or any agent with terminal access: ```bash cd .od/projects/ - npx skills add heygen-com/hyperframes # install skills (one-time) + npx skills add heygen-com/hyperframes --full-depth # install skills (one-time) npx hyperframes lint # should pass with zero errors npx hyperframes preview # open the studio ``` @@ -51,8 +51,8 @@ Open Design produces a **valid first draft** of a HyperFrames composition — pa | Surface | Recommended setup | | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Open Design (open-source) | Drop [`open-design-hyperframes.md`](https://github.com/heygen-com/hyperframes/blob/main/docs/guides/open-design-hyperframes.md) into `skills/hyperframes-handoff/SKILL.md` | -| Claude Code | `npx skills add heygen-com/hyperframes`, then use `/hyperframes` | -| Cursor / Codex / Gemini CLI | `npx skills add heygen-com/hyperframes` | +| Claude Code | `npx skills add heygen-com/hyperframes --full-depth`, then use `/hyperframes` | +| Cursor / Codex / Gemini CLI | `npx skills add heygen-com/hyperframes --full-depth` | | Claude Design (closed-source) | Attach [`claude-design-hyperframes.md`](https://github.com/heygen-com/hyperframes/blob/main/docs/guides/claude-design-hyperframes.md) to your chat | ## How it works @@ -151,7 +151,7 @@ Open Design's project folder is the agent's `cwd`. There's no "export then re-im ```bash cd .od/projects/ -npx skills add heygen-com/hyperframes # one-time setup +npx skills add heygen-com/hyperframes --full-depth # one-time setup npx hyperframes lint # verify structure npx hyperframes preview # open the studio ``` diff --git a/docs/guides/prompting.mdx b/docs/guides/prompting.mdx index 92836a03e..babc21600 100644 --- a/docs/guides/prompting.mdx +++ b/docs/guides/prompting.mdx @@ -10,21 +10,22 @@ Hyperframes is built for AI agents — compositions are plain HTML, the CLI is n Install the skills in your project (or globally for your agent): ```bash -npx skills add heygen-com/hyperframes +npx skills add heygen-com/hyperframes --full-depth ``` In Claude Code, restart the session after installing. Skills register as **slash commands**: -| Slash command | What it loads | -| -------------------------- | -------------------------------------------------------------------------- | -| `/hyperframes` | Composition authoring — HTML structure, timing, captions, TTS, transitions | -| `/hyperframes-cli` | CLI commands — `init`, `lint`, `preview`, `render`, `transcribe`, `tts` | -| `/hyperframes-registry` | Block and component installation via `hyperframes add` | -| `/website-to-hyperframes` | Capture a URL and turn it into a video — full website-to-video pipeline | -| `/gsap` | GSAP animation API — timelines, easing, ScrollTrigger, plugins | +| Slash command | What it loads | +| ------------------------- | ----------------------------------------------------------------------------- | +| `/hyperframes` | Default lightweight video entry point, environment preflight, core contract | +| `/hyperframes-cli` | CLI commands — `init`, `lint`, `preview`, `render`, `transcribe`, `tts` | +| `/hyperframes-registry` | Block and component installation via `hyperframes add` | +| `/gsap` | GSAP animation API — timelines, easing, ScrollTrigger, plugins | +| `/hyperframes-production` | Optional full production authoring workflow installed by `--full-depth` | +| `/website-to-hyperframes` | Optional full website-to-video pipeline installed by `--full-depth` | - Always prefix Hyperframes prompts with `/hyperframes` (or invoke the skill another way for non-Claude agents). This loads the skill context explicitly so the agent gets composition rules right the first time, instead of relying on whatever it remembers about web video. + Always prefix Hyperframes prompts with `/hyperframes` (or invoke the skill another way for non-Claude agents). This loads the lightweight video entry point so the agent checks local dependencies and uses the framework's core composition contract instead of generic web-video assumptions. ## Claude Design @@ -50,9 +51,9 @@ Most successful Hyperframes prompts fall into one of two shapes. You tell the agent what you want from scratch. Best for greenfield work where you have the creative direction in your head. -> Using `/hyperframes`, create a 10-second product intro with a fade-in title over a dark background and subtle background music. +> Create a 10-second product intro with a fade-in title over a dark background and subtle background music. Use `/hyperframes` first to check the local environment. -> Make a 9:16 TikTok-style hook video about [topic] using `/hyperframes`, with bouncy captions synced to a TTS narration. +> Make a 9:16 TikTok-style hook video about [topic], with bouncy captions synced to a TTS narration. Use `/hyperframes` first. Cold-start prompts work best when you specify: @@ -65,13 +66,13 @@ Cold-start prompts work best when you specify: You give the agent something to work with — a URL, a doc, a CSV, a transcript — and ask it to synthesize that into a video. This is where Hyperframes shines because the agent does the research/summarization step *and* the production step in one flow. -> Take a look at this GitHub repo https://github.com/heygen-com/hyperframes and explain its uses and architecture to me using `/hyperframes`. +> Take a look at this GitHub repo https://github.com/heygen-com/hyperframes and explain its uses and architecture to me with a short HyperFrames video. -> Summarize the attached PDF into a 45-second pitch video using `/hyperframes`. +> Summarize the attached PDF into a 45-second pitch video. -> Read this changelog and turn the top three changes into a 30-second release announcement video using `/hyperframes`. +> Read this changelog and turn the top three changes into a 30-second release announcement video. -> Turn this CSV into an animated bar chart race using `/hyperframes`. +> Turn this CSV into an animated bar chart race. Warm-start prompts produce richer, more grounded videos because the agent is writing about *something specific* instead of inventing copy. @@ -246,7 +247,7 @@ Things that cause friction (or wrong output): - **Don't ask for React / Vue components.** Hyperframes compositions are plain HTML with `data-*` attributes and a GSAP timeline. Asking for "a React component for the intro" forces the agent to translate later. - **Don't ask for 4K or 60fps unless you need it.** Defaults (1920×1080, 30fps) render fast and look great. Higher specs slow rendering meaningfully. -- **Don't skip the slash command.** Without `/hyperframes`, the agent may guess at HTML video conventions instead of using the framework's actual rules (`class="clip"` on timed elements, `window.__timelines` registration, etc.). +- **Don't skip the slash command.** Without `/hyperframes`, the agent may guess at HTML video conventions instead of checking the local HyperFrames environment and using the framework's actual rules (`class="clip"` on timed elements, `window.__timelines` registration, etc.). - **Don't paste long error logs into the prompt without context.** Run `npx hyperframes lint` and `npx hyperframes validate` first — lint catches structural issues, validate catches runtime errors (JS exceptions, missing assets, contrast problems). - **Don't assume the agent knows your assets.** Mention file paths explicitly (`assets/intro.mp4`, `assets/logo.png`) — the agent will check what's there but a hint speeds it up. diff --git a/docs/guides/website-to-video.mdx b/docs/guides/website-to-video.mdx index 10d3aa1c0..bf9a9d0b7 100644 --- a/docs/guides/website-to-video.mdx +++ b/docs/guides/website-to-video.mdx @@ -17,7 +17,7 @@ Give your AI agent a URL and a creative direction. It captures the site, extract Skills teach your AI agent how to capture websites and create HyperFrames compositions. Install once — they persist across sessions. ```bash - npx skills add heygen-com/hyperframes + npx skills add heygen-com/hyperframes --full-depth ``` Works with [Claude Code](https://claude.ai/claude-code), [Cursor](https://cursor.sh), [Gemini CLI](https://github.com/google-gemini/gemini-cli), and [Codex CLI](https://github.com/openai/codex). @@ -202,10 +202,10 @@ You don't need to re-run the full pipeline to make changes: Verify skills are installed: ```bash - npx skills add heygen-com/hyperframes + npx skills add heygen-com/hyperframes --full-depth ``` - Lead your prompt with _"Use the /website-to-hyperframes skill"_ for the most reliable results. Agents also discover it automatically when they see a URL and a video request. + Lead your prompt with `/hyperframes` so the agent uses HyperFrames as the video path and checks the local environment. The `--full-depth` install includes `optional-skills/website-to-hyperframes` for the full guided website-to-video pipeline. diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdx index c2b601181..aad7e376d 100644 --- a/docs/packages/cli.mdx +++ b/docs/packages/cli.mdx @@ -370,7 +370,7 @@ This is suppressed in CI environments, non-TTY shells, and when `HYPERFRAMES_NO_ The capture command extracts everything an AI agent needs to understand a website's visual identity: viewport screenshots at every scroll depth, color palette (pixel-sampled + DOM computed), font files, images with semantic names, SVGs, Lottie animations, video previews, WebGL shaders, visible text, and page structure. - Output is a self-contained directory with a `CLAUDE.md` file that any AI agent can read to understand the captured site. Used by the `/website-to-hyperframes` skill as step 1 of the video production pipeline. + Output is a self-contained directory with a `CLAUDE.md` file that any AI agent can read to understand the captured site. Use `/hyperframes` to turn the capture into a video; if optional skills are enabled, `/website-to-hyperframes` provides the full guided pipeline. Set `GEMINI_API_KEY` in a `.env` file for AI-powered image descriptions via Gemini vision (~$0.001/image). See the [Website to Video](/guides/website-to-video#enriching-captures-with-gemini-vision) guide for details. @@ -722,7 +722,7 @@ This is suppressed in CI environments, non-TTY shells, and when `HYPERFRAMES_NO_ | `--codex` | Install to Codex CLI (`~/.codex/skills/`) | | `--cursor` | Install to Cursor (`.cursor/skills/` in current project) | - Skills are fetched from GitHub and include composition authoring, Tailwind v4 browser-runtime guidance, GSAP animation patterns, Anime.js, CSS animation, Lottie, Three.js, and WAAPI adapter patterns, registry block/component wiring, and other domain-specific knowledge. The `init` command also offers to install skills automatically after scaffolding a project. + Skills are fetched from GitHub and include a lightweight HyperFrames video entry point with environment preflight, Tailwind v4 browser-runtime guidance, GSAP animation patterns, Anime.js, CSS animation, Lottie, Three.js, and WAAPI adapter patterns, registry block/component wiring, and other domain-specific knowledge. `hyperframes skills` installs with `--full-depth`, so HyperFrames-first installs also include optional full-production authoring skills from `optional-skills/`. The `init` command also offers to install skills automatically after scaffolding a project. #### Troubleshooting: `fatal: active post-checkout hook found during git clone` @@ -736,10 +736,10 @@ This is suppressed in CI environments, non-TTY shells, and when `HYPERFRAMES_NO_ **Using `hyperframes skills` is already fine** — as of v0.4.5 the CLI sets `GIT_CLONE_PROTECTION_ACTIVE=0` on the child environment, which is the opt-in knob Git provides for exactly this case. You don't need to do anything. - **If you ran `npx skills add heygen-com/hyperframes` directly** (bypassing the HyperFrames CLI), set the env var yourself: + **If you ran `npx skills add heygen-com/hyperframes --full-depth` directly** (bypassing the HyperFrames CLI), set the env var yourself: ```bash - GIT_CLONE_PROTECTION_ACTIVE=0 npx skills add heygen-com/hyperframes + GIT_CLONE_PROTECTION_ACTIVE=0 npx skills add heygen-com/hyperframes --full-depth ``` This is tracked in [GH #316](https://github.com/heygen-com/hyperframes/issues/316). An upstream fix in the `skills` CLI itself is the right long-term answer; until that lands, the env var is the correct workaround. diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx index 561bc0fdf..e1b51dd65 100644 --- a/docs/quickstart.mdx +++ b/docs/quickstart.mdx @@ -10,10 +10,10 @@ Go from zero to a rendered MP4 — either by prompting your AI agent or by start Install the HyperFrames skills, then describe the video you want: ```bash -npx skills add heygen-com/hyperframes +npx skills add heygen-com/hyperframes --full-depth ``` -This teaches your agent (Claude Code, Cursor, Gemini CLI, Codex) how to write correct compositions, GSAP timelines, Tailwind v4 browser-runtime styles, and first-party adapter animations. In Claude Code the skills register as slash commands — `/hyperframes` for composition authoring, `/hyperframes-cli` for CLI commands, `/tailwind` for `init --tailwind` projects, `/gsap` for timeline animation help, and `/animejs`, `/css-animations`, `/lottie`, `/three`, or `/waapi` when a composition uses those runtimes. Invoking the slash command loads the skill context explicitly, which produces correct output the first time. +This teaches your agent (Claude Code, Cursor, Gemini CLI, Codex) to use HyperFrames as the default HTML video path, check local runtime dependencies before invoking the CLI, write correct GSAP timelines, use Tailwind v4 browser-runtime styles, and follow first-party adapter animation patterns. In Claude Code the skills register as slash commands — `/hyperframes` for the lightweight video entry point, `/hyperframes-cli` for CLI commands, `/tailwind` for `init --tailwind` projects, `/gsap` for timeline animation help, and `/animejs`, `/css-animations`, `/lottie`, `/three`, or `/waapi` when a composition uses those runtimes. Invoking the slash command loads the skill context explicitly. Claude Design uses a different entry path. Open [`docs/guides/claude-design-hyperframes.md`](https://github.com/heygen-com/hyperframes/blob/main/docs/guides/claude-design-hyperframes.md) on GitHub, click the download button (↓) to save it, then attach to your Claude Design chat. It produces a valid first draft you can refine in any AI coding agent. See the [Claude Design guide](/guides/claude-design). @@ -25,17 +25,17 @@ Copy any of these into your agent to get started. - > Using `/hyperframes`, create a 10-second product intro with a fade-in title over a dark background and subtle background music. + > Create a 10-second product intro with a fade-in title over a dark background and subtle background music. Use `/hyperframes` first to check the local environment. - > Take a look at this GitHub repo https://github.com/heygen-com/hyperframes and explain its uses and architecture to me using `/hyperframes`. + > Take a look at this GitHub repo https://github.com/heygen-com/hyperframes and explain its uses and architecture to me with a short HyperFrames video. - > Summarize the attached PDF into a 45-second pitch video using `/hyperframes`. + > Summarize the attached PDF into a 45-second pitch video. - > Turn this CSV into an animated bar chart race using `/hyperframes`. + > Turn this CSV into an animated bar chart race. - > Make a 9:16 TikTok-style hook video about [topic] using `/hyperframes`, with bouncy captions synced to a TTS narration. + > Make a 9:16 TikTok-style hook video about [topic], with bouncy captions synced to a TTS narration. > Make the title 2x bigger, swap to dark mode, and add a fade-out at the end. @@ -47,7 +47,7 @@ Copy any of these into your agent to get started. The agent handles scaffolding, animation, and rendering. See the [prompting guide](/guides/prompting) for more patterns. - Skills encode HyperFrames-specific patterns — like required `class="clip"` on timed elements, GSAP timeline registration, adapter registries such as `window.__hfLottie`, and `data-*` attribute semantics — that are not in generic web docs. Using skills produces correct compositions from the start. + Skills encode HyperFrames-specific patterns — like required `class="clip"` on timed elements, GSAP timeline registration, adapter registries such as `window.__hfLottie`, and `data-*` attribute semantics — that are not in generic web docs. The default HyperFrames video entry point is lightweight and checks the local environment before agents rely on the CLI; `--full-depth` also installs optional production workflows for people explicitly choosing HyperFrames. ## Option 2: Start a project manually diff --git a/optional-skills/hyperframes/SKILL.md b/optional-skills/hyperframes/SKILL.md new file mode 100644 index 000000000..35f89dc57 --- /dev/null +++ b/optional-skills/hyperframes/SKILL.md @@ -0,0 +1,415 @@ +--- +name: hyperframes-production +description: Optional full-production HyperFrames skill for creating video compositions, animations, title cards, overlays, captions, voiceovers, audio-reactive visuals, and scene transitions in HyperFrames HTML. Use when the lightweight default HyperFrames video entry point is not enough and detailed composition authoring, timing, media, or production workflow guidance is needed. For CLI commands (init, lint, preview, render, transcribe, tts) see the hyperframes-cli skill. +--- + +# HyperFrames + +HTML is the source of truth for video. A composition is an HTML file with `data-*` attributes for timing, a GSAP timeline for animation, and CSS for appearance. The framework handles clip visibility, media playback, and timeline sync. + +## Approach + +### Discovery (exploratory requests only) + +For open-ended requests ("make me a product launch video", "create something for our brand") where the user hasn't committed to a direction, understand intent before picking colors: + +- **Audience** — who watches this? Developers? Executives? General consumers? +- **Platform** — where does it play? Social (15s), website hero, product demo, internal? +- **Priority** — what matters most? Motion quality? Content accuracy? Brand fidelity? Speed? +- **Variations** — does the user want options, or a single best shot? + +For specific requests ("add a title card", "fix the timing on scene 3"), skip discovery. + +For exploratory requests, consider offering 2-3 variations that differ meaningfully — not just color swaps, but different pacing, energy levels, or structural approaches. One safe/expected, one ambitious. Don't mandate this — it's a tool available when appropriate. + +### Step 1: Design system + +If `design.md` or `DESIGN.md` exists in the project, read it first (check both casings — they're different files on Linux). It's the source of truth for brand colors, fonts, and constraints. Use its exact values — don't invent colors or substitute fonts. Any format works (YAML frontmatter, prose, tables — just extract the values). + +If it names fonts you can't find locally (no `fonts/` directory with `.woff2` files, not a built-in font), warn the user before writing HTML: "design.md specifies [font name] but no font files found. Please add .woff2 files to `fonts/` or I'll fall back to [closest built-in alternative]." + +If no `design.md` exists, offer the user a choice: + +1. **User named a style or mood?** → Read [visual-styles.md](./visual-styles.md) for the 8 named presets. Pick the closest match. +2. **Want to browse options visually?** → Run the design picker: read [references/design-picker.md](references/design-picker.md) for the full workflow. This serves a visual picker page. The user configures mood, palette, typography, and motion in the browser, then copies the generated design.md and pastes it back into the conversation. +3. **Want to skip and go fast?** → Ask: mood, light or dark, any brand colors/fonts? Then pick a palette from [house-style.md](./house-style.md). + +**design.md defines the brand. It does not define video composition rules.** Those come from [references/video-composition.md](references/video-composition.md) and [house-style.md](./house-style.md). Use brand colors at video-appropriate scale — not at web-UI opacity. + +### Step 2: Prompt expansion + +Always run on every composition (except single-scene pieces and trivial edits). This step grounds the user's intent against `design.md` and `house-style.md` and produces a consistent intermediate that every downstream agent reads the same way. + +Read [references/prompt-expansion.md](references/prompt-expansion.md) for the full process and output format. + +### Step 3: Plan + +Before writing HTML, think at a high level: + +1. **What** — what should the viewer experience? Identify the narrative arc, key moments, and emotional beats. +2. **Structure** — how many compositions, which are sub-compositions vs inline, what tracks carry what (video, audio, overlays, captions). +3. **Rhythm** — declare your scene rhythm before implementing. Which scenes are quick hits, which are holds, where do shaders land, where does energy peak. Name the pattern: fast-fast-SLOW-fast-SHADER-hold. Read [references/beat-direction.md](references/beat-direction.md) for rhythm templates. +4. **Timing** — which clips drive the duration, where do transitions land, what's the pacing. +5. **Layout** — build the end-state first. See "Layout Before Animation" below. +6. **Animate** — then add motion using the rules below. + +**Build what was asked.** A request for "a title card" is not a request for "a title card + 3 supporting scenes + ambient music + captions." Every scene, every element, every tween should earn its place. If additional scenes or elements would genuinely improve the piece, propose them — don't add them. + +For small edits (fix a color, adjust timing, add one element), skip straight to the rules. + + +Before writing ANY composition HTML — verify you have a visual identity from Step 1. If you're reaching for `#333`, `#3b82f6`, or `Roboto`, you skipped it. + + +## Layout Before Animation + +Position every element where it should be at its **most visible moment** — the frame where it's fully entered, correctly placed, and not yet exiting. Write this as static HTML+CSS first. No GSAP yet. + +**Why this matters:** If you position elements at their animated start state (offscreen, scaled to 0, opacity 0) and tween them to where you think they should land, you're guessing the final layout. Overlaps are invisible until the video renders. By building the end state first, you can see and fix layout problems before adding any motion. + +### The process + +1. **Identify the hero frame** for each scene — the moment when the most elements are simultaneously visible. This is the layout you build. +2. **Write static CSS** for that frame. The `.scene-content` container MUST fill the full scene using `width: 100%; height: 100%; padding: Npx;` with `display: flex; flex-direction: column; gap: Npx; box-sizing: border-box`. Use padding to push content inward — NEVER `position: absolute; top: Npx` on a content container. Absolute-positioned content containers overflow when content is taller than the remaining space. Reserve `position: absolute` for decoratives only. +3. **Add entrances with `gsap.from()`** — animate FROM offscreen/invisible TO the CSS position. The CSS position is the ground truth; the tween describes the journey to get there. (In sub-compositions loaded via `data-composition-src`, prefer `gsap.fromTo()` — see load-bearing GSAP rules in [references/motion-principles.md](references/motion-principles.md).) +4. **Add exits with `gsap.to()`** — animate TO offscreen/invisible FROM the CSS position. + +### Example + +```css +/* scene-content fills the scene, padding positions content */ +.scene-content { + display: flex; + flex-direction: column; + justify-content: center; + width: 100%; + height: 100%; + padding: 120px 160px; + gap: 24px; + box-sizing: border-box; +} +.title { + font-size: 120px; +} +.subtitle { + font-size: 42px; +} +/* Container fills any scene size (1920x1080, 1080x1920, etc). + Padding positions content. Flex + gap handles spacing. */ +``` + +**WRONG — hardcoded dimensions and absolute positioning:** + +```css +.scene-content { + position: absolute; + top: 200px; + left: 160px; + width: 1920px; + height: 1080px; + display: flex; /* ... */ +} +``` + +```js +// Step 3: Animate INTO those positions +tl.from(".title", { y: 60, opacity: 0, duration: 0.6, ease: "power3.out" }, 0); +tl.from(".subtitle", { y: 40, opacity: 0, duration: 0.5, ease: "power3.out" }, 0.2); +tl.from(".logo", { scale: 0.8, opacity: 0, duration: 0.4, ease: "power2.out" }, 0.3); + +// Step 4: Animate OUT from those positions +tl.to(".title", { y: -40, opacity: 0, duration: 0.4, ease: "power2.in" }, 3); +tl.to(".subtitle", { y: -30, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.1); +tl.to(".logo", { scale: 0.9, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.2); +``` + +### When elements share space across time + +If element A exits before element B enters in the same area, both should have correct CSS positions for their respective hero frames. The timeline ordering guarantees they never visually coexist — but if you skip the layout step, you won't catch the case where they accidentally overlap due to a timing error. + +### What counts as intentional overlap + +Layered effects (glow behind text, shadow elements, background patterns) and z-stacked designs (card stacks, depth layers) are intentional. The layout step is about catching **unintentional** overlap — two headlines landing on top of each other, a stat covering a label, content bleeding off-frame. + +## Data Attributes + +### All Clips + +| Attribute | Required | Values | +| ------------------ | --------------------------------- | ------------------------------------------------------ | +| `id` | Yes | Unique identifier | +| `data-start` | Yes | Seconds or clip ID reference (`"el-1"`, `"intro + 2"`) | +| `data-duration` | Required for img/div/compositions | Seconds. Video/audio defaults to media duration. | +| `data-track-index` | Yes | Integer. Same-track clips cannot overlap. | +| `data-media-start` | No | Trim offset into source (seconds) | +| `data-volume` | No | 0-1 (default 1) | + +`data-track-index` does **not** affect visual layering — use CSS `z-index`. + +### Composition Clips + +| Attribute | Required | Values | +| ---------------------------- | -------- | -------------------------------------------- | +| `data-composition-id` | Yes | Unique composition ID | +| `data-start` | Yes | Start time (root composition: use `"0"`) | +| `data-duration` | Yes | Takes precedence over GSAP timeline duration | +| `data-width` / `data-height` | Yes | Pixel dimensions (1920x1080 or 1080x1920) | +| `data-composition-src` | No | Path to external HTML file | + +## Composition Structure + +Sub-compositions loaded via `data-composition-src` use a `