docs: add runtime adapter skills (#572)

* docs: add runtime adapter skills

* docs: address adapter skill review comments

Author: miguel-heygen

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "hyperframes",
-  "description": "HyperFrames by HeyGen. Write HTML, render video. Compositions, GSAP animations, captions, voiceovers, audio-reactive visuals, and website-to-video capture for 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.",
   "version": "0.1.0",
   "author": {
     "name": "HeyGen",

.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "hyperframes",
   "version": "0.1.0",
-  "description": "Write HTML, render video. Compositions, GSAP animations, captions, voiceovers, audio-reactive visuals, and website-to-video capture for HyperFrames.",
+  "description": "Write HTML, render video. Compositions, GSAP and runtime adapter animations, captions, voiceovers, audio-reactive visuals, and website-to-video capture for HyperFrames.",
   "author": {
     "name": "HeyGen",
     "email": "hyperframes@heygen.com",
@@ -15,6 +15,10 @@
     "video",
     "html",
     "gsap",
+    "lottie",
+    "three",
+    "waapi",
+    "animejs",
     "animation",
     "composition",
     "rendering",
@@ -26,7 +30,7 @@
   "interface": {
     "displayName": "HyperFrames by HeyGen",
     "shortDescription": "Write HTML, render video",
-    "longDescription": "Build videos from HTML with HyperFrames. Author compositions with HTML + CSS + GSAP, use the CLI for init/preview/render/transcribe/tts, install reusable registry blocks and components, follow the GSAP animation reference, and turn any website into a video with the 7-step capture-to-video pipeline.",
+    "longDescription": "Build videos from HTML with HyperFrames. Author compositions with HTML, CSS, 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.",
     "developerName": "HeyGen",
     "category": "Design",
     "capabilities": ["Read", "Write"],

.cursor-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "hyperframes",
   "displayName": "HyperFrames by HeyGen",
   "version": "0.1.0",
-  "description": "Write HTML, render video. Compositions, GSAP animations, captions, voiceovers, audio-reactive visuals, and website-to-video capture for HyperFrames.",
+  "description": "Write HTML, render video. Compositions, GSAP and runtime adapter animations, captions, voiceovers, audio-reactive visuals, and website-to-video capture for HyperFrames.",
   "author": {
     "name": "HeyGen",
     "email": "hyperframes@heygen.com"
@@ -19,6 +19,10 @@
     "video",
     "html",
     "gsap",
+    "lottie",
+    "three",
+    "waapi",
+    "animejs",
     "animation",
     "composition",
     "rendering",

CLAUDE.md

@@ -67,4 +67,4 @@ will not match CI. Use it only for local-only experimentation.
 
 ## Skills
 
-Composition authoring (not repo development) is guided by skills installed via `npx skills add heygen-com/hyperframes`. See `skills/` for source. Invoke `/hyperframes`, `/hyperframes-cli`, `/hyperframes-registry`, or `/gsap` when authoring compositions. When a user provides a website URL and wants a video, invoke `/website-to-hyperframes` — it runs the full 7-step capture-to-video pipeline.
+Composition authoring (not repo development) is guided by skills installed via `npx skills add heygen-com/hyperframes`. See `skills/` for source. Invoke `/hyperframes`, `/hyperframes-cli`, `/hyperframes-registry`, or `/gsap` when authoring compositions. Use `/animejs`, `/css-animations`, `/lottie`, `/three`, or `/waapi` when a composition uses those first-party runtime adapters. When a user provides a website URL and wants a video, invoke `/website-to-hyperframes` — it runs the full 7-step capture-to-video pipeline.

README.md

@@ -32,7 +32,7 @@ Install the HyperFrames skills, then describe the video you want:
 npx skills add heygen-com/hyperframes
 ```
 
-This teaches your agent (Claude Code, Cursor, Gemini CLI, Codex) how to write correct compositions and GSAP animations. In Claude Code, the skills register as slash commands — invoke `/hyperframes` to author compositions, `/hyperframes-cli` for CLI commands, and `/gsap` for animation help.
+This teaches your agent (Claude Code, Cursor, Gemini CLI, Codex) how to write correct compositions, GSAP timelines, and first-party adapter animations. In Claude Code, the skills register as slash commands — invoke `/hyperframes` to author compositions, `/hyperframes-cli` for CLI commands, `/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).
 
@@ -185,14 +185,19 @@ HyperFrames ships [skills](https://github.com/vercel-labs/skills) that teach AI
 npx skills add heygen-com/hyperframes
 ```
 
-| Skill                     | What it teaches                                                                              |
-| ------------------------- | -------------------------------------------------------------------------------------------- |
-| `hyperframes`             | HTML composition authoring, captions, TTS, audio-reactive animation, transitions             |
-| `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 animation API, timelines, easing, ScrollTrigger, plugins, React/Vue/Svelte, performance |
+| Skill                     | What it teaches                                                                                                     |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `hyperframes`             | HTML composition authoring, captions, TTS, audio-reactive animation, transitions                                    |
+| `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            |
+| `css-animations`          | CSS keyframe animation patterns that HyperFrames can discover, pause, and seek                                      |
+| `lottie`                  | `lottie-web` and dotLottie players registered on `window.__hfLottie` with local assets and paused playback          |
+| `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()`                           |
 
 ## Contributing
 

docs/concepts/frame-adapters.mdx

@@ -104,15 +104,16 @@ These rules are non-negotiable for any adapter. They are the foundation of Hyper
 
 ## Supported Runtimes
 
-First-party adapters:
-
-| Runtime | Seek Method | Status |
-|---------|------------|--------|
-| [GSAP](/guides/gsap-animation) | `timeline.seek(frame / fps)` | Available |
-| CSS/WAAPI | `animation.currentTime` | Planned |
-| Lottie | Set animation frame/progress | Planned |
-| Three.js/WebGL | Compute deterministic scene state | Planned |
-| SVG/Anime | Implement seek + duration contract | Planned |
+First-party runtime adapters:
+
+| Runtime | Seek Method | Skill |
+|---------|-------------|-------|
+| [GSAP](/guides/gsap-animation) | `timeline.totalTime(timeSeconds)` or `timeline.seek(timeSeconds)` | `/gsap` |
+| Anime.js | `instance.seek(timeMs)` for animations registered on `window.__hfAnime` | `/animejs` |
+| CSS keyframes | Browser `Animation.currentTime`, with paused negative-delay fallback | `/css-animations` |
+| Lottie / dotLottie | `goToAndStop(timeMs, false)`, raw-frame setters, or player seek APIs | `/lottie` |
+| Three.js / WebGL | `hf-seek` events plus `window.__hfThreeTime` for deterministic scene rendering | `/three` |
+| Web Animations API | `document.getAnimations()` and `animation.currentTime` | `/waapi` |
 
 Community adapters are welcome -- if it can seek by frame, it belongs in Hyperframes.
 

docs/packages/cli.mdx

@@ -697,7 +697,7 @@ This is suppressed in CI environments, non-TTY shells, and when `HYPERFRAMES_NO_
 
     ### `skills`
 
-    Install HyperFrames and GSAP skills for AI coding tools:
+    Install HyperFrames skills for AI coding tools, including first-party runtime adapter skills:
 
     ```bash
     # Install to all default targets (Claude Code, Gemini CLI, Codex CLI)
@@ -716,7 +716,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, GSAP animation 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 composition authoring, 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.
 
     #### Troubleshooting: `fatal: active post-checkout hook found during git clone`
 

docs/quickstart.mdx

@@ -13,7 +13,7 @@ Install the HyperFrames skills, then describe the video you want:
 npx skills add heygen-com/hyperframes
 ```
 
-This teaches your agent (Claude Code, Cursor, Gemini CLI, Codex) how to write correct compositions and GSAP animations. In Claude Code the skills register as slash commands — `/hyperframes` for composition authoring, `/hyperframes-cli` for CLI commands, and `/gsap` for animation help. 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) how to write correct compositions, GSAP timelines, and first-party adapter animations. In Claude Code the skills register as slash commands — `/hyperframes` for composition authoring, `/hyperframes-cli` for CLI commands, `/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.
 
 <Note>
   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).
@@ -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.
 
 <Tip>
-  Skills encode HyperFrames-specific patterns — like required `class="clip"` on timed elements, GSAP timeline registration, 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. Using skills produces correct compositions from the start.
 </Tip>
 
 ## Option 2: Start a project manually

packages/cli/src/templates/_shared/CLAUDE.md

@@ -11,6 +11,11 @@
 | **hyperframes-registry**   | `/hyperframes-registry`   | Installing blocks and components via `hyperframes add`                                            |
 | **website-to-hyperframes** | `/website-to-hyperframes` | Capturing a URL and turning it into a video — full website-to-video pipeline                      |
 | **gsap**                   | `/gsap`                   | GSAP animations for HyperFrames — tweens, timelines, easing, performance                          |
+| **animejs**                | `/animejs`                | Anime.js animations registered on `window.__hfAnime`                                              |
+| **css-animations**         | `/css-animations`         | CSS keyframes that HyperFrames can pause and seek                                                 |
+| **lottie**                 | `/lottie`                 | `lottie-web` and dotLottie players registered on `window.__hfLottie`                              |
+| **three**                  | `/three`                  | Three.js scenes rendered from HyperFrames `hf-seek` events                                        |
+| **waapi**                  | `/waapi`                  | Web Animations API motion driven through `document.getAnimations()`                               |
 
 > **Skills not available?** Ask the user to run `npx hyperframes skills` and restart their
 > agent session, or install manually: `npx skills add heygen-com/hyperframes`.

skills/animejs/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: animejs
+description: Anime.js adapter patterns for HyperFrames. Use when writing Anime.js animations or timelines inside HyperFrames compositions, registering animations on window.__hfAnime, making Anime.js seek-driven and deterministic, or translating Anime.js examples into render-safe HyperFrames HTML.
+---
+
+# Anime.js for HyperFrames
+
+HyperFrames can seek Anime.js instances through its `animejs` runtime adapter. The composition owns the animation objects; HyperFrames owns the clock.
+
+## Contract
+
+- Create animations or timelines synchronously during composition initialization.
+- Set `autoplay: false` so Anime.js does not advance on its own clock.
+- Register every returned animation or timeline on `window.__hfAnime`.
+- Use finite durations and loop counts.
+- Avoid callbacks that mutate DOM based on wall-clock time, network state, or unseeded randomness.
+
+The adapter seeks every registered instance with `instance.seek(timeMs)`, where `timeMs` is HyperFrames time in milliseconds.
+
+## Basic Pattern
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/animejs@4.0.2/lib/anime.iife.min.js"></script>
+<script>
+  const anim = anime({
+    targets: ".mark",
+    translateX: 280,
+    rotate: "1turn",
+    opacity: [0, 1],
+    duration: 1200,
+    easing: "easeOutExpo",
+    autoplay: false,
+  });
+
+  window.__hfAnime = window.__hfAnime || [];
+  window.__hfAnime.push(anim);
+</script>
+```
+
+## Timeline Pattern
+
+```html
+<script>
+  const tl = anime.timeline({
+    autoplay: false,
+    easing: "easeOutCubic",
+  });
+
+  tl.add({
+    targets: ".title",
+    translateY: [40, 0],
+    opacity: [0, 1],
+    duration: 650,
+  }).add(
+    {
+      targets: ".accent",
+      scaleX: [0, 1],
+      duration: 450,
+    },
+    250,
+  );
+
+  window.__hfAnime = window.__hfAnime || [];
+  window.__hfAnime.push(tl);
+</script>
+```
+
+## Module Builds
+
+If you use an ES module build, the adapter does not care how the instance was created. It only needs the returned object to expose `seek()`, `pause()`, and preferably `play()`:
+
+```html
+<script type="module">
+  import { animate } from "https://cdn.jsdelivr.net/npm/animejs/+esm";
+
+  const anim = animate(".chip", {
+    x: "18rem",
+    duration: 900,
+    autoplay: false,
+  });
+
+  window.__hfAnime = window.__hfAnime || [];
+  window.__hfAnime.push(anim);
+</script>
+```
+
+## Good Uses
+
+- Small SVG and DOM flourishes where Anime.js syntax is compact.
+- Imported Anime.js examples that can be made seek-driven.
+- Multiple independent micro-animations pushed into the same registry.
+
+Use GSAP for complex scene sequencing unless the user specifically asks for Anime.js. GSAP is still the primary HyperFrames authoring path.
+
+## Avoid
+
+- Leaving `autoplay` at the Anime.js default.
+- Depending on `anime.running` auto-discovery instead of explicit `window.__hfAnime.push(...)`.
+- Infinite loops. Compute a finite repeat count from the composition duration.
+- Building animations in timers, promises, event handlers, or after async asset loads.
+
+## Validation
+
+After editing a composition that uses Anime.js:
+
+```bash
+npx hyperframes lint
+npx hyperframes validate
+```
+
+## Credits And References
+
+- HyperFrames adapter source: `packages/core/src/runtime/adapters/animejs.ts`.
+- Anime.js documentation for `autoplay`, `pause()`, and `seek()`: https://animejs.com/documentation/