mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-14 18:01:20 +08:00
James
5ed196c53a
Applied a pass of review feedback that concentrates on correctness,
shared constants, and cleanup.
- Lift ITEM_TYPE_DIRS to @hyperframes/core/registry. Replaces an
exhaustiveness-fragile switch in remote.ts and the hardcoded
"examples" literal in scripts/generate-registry-items.ts. One
constant, three consumers, checked against the ItemType union.
- remote.ts readCache: drop existsSync pre-check (TOCTOU double
syscall) and rely on the existing try/catch for cache miss.
- templates/remote.ts: hoist the listRegistryItems/loadAllItems
dynamic import to static — had no reason to be async-lazy.
- resolver.ts loadAllItems: accept an optional onWarn callback
instead of calling console.warn directly. Default writes to stderr
with a "hyperframes:registry" prefix so structured output (JSON,
clack prompts) can opt in to silence.
- Scrub PR-number references from inline comments in the registry
and compat-shim files. Intent language instead ("future item types",
"compat shim for legacy init.ts callers").
- Fix stale test description in remote.test.ts that claimed PR 3
renamed MANIFEST_FILENAME to registry.json (the rename didn't
happen — the filename stays templates.json for the compat shim).
Skipped (documented as intentional in PR thread):
- Lifting assertSafeTarget to @hyperframes/core — CLI-specific
concern, keeps core lean
- Extracting readCache/writeCache to utils/cache.ts — one consumer
today; revisit when the CLI gets a second
- Hashing the cache-key slug — theoretical collision for a single-
digit registry count; revisit when PR 14 adds custom registries
- Removing assertSafeTarget's layered checks — reviewer confirmed
defense-in-depth is worth keeping for diagnostic clarity
Core: 452 tests pass. CLI: 70 tests pass (4 pre-existing failures
unchanged, unrelated to this PR). Format + lint clean.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Hyperframes
Write HTML. Render video. Built for agents.
Hyperframes is an open-source video rendering framework that lets you create, preview, and render HTML-based video compositions — with first-class support for AI agents via MCP.
Why Hyperframes?
- HTML-native — AI agents already speak HTML. No React required.
- Frame Adapter pattern — bring your own animation runtime (GSAP, Lottie, CSS, Three.js).
- Deterministic rendering — same input = identical output. Built for automated pipelines.
- AI-first design — not a bolted-on afterthought.
Quick Start
npx hyperframes init my-video
cd my-video
Then open the project with your AI coding agent (Claude Code, Cursor, etc.) — it has HyperFrames skills installed and knows how to create and edit compositions.
npx hyperframes preview # preview in browser (live reload)
npx hyperframes render # render to MP4
Requirements: Node.js >= 22, FFmpeg
Documentation
Full documentation at hyperframes.heygen.com — start with the Quickstart, then explore guides, concepts, API reference, and package docs.
How It Works
Define your video as HTML with data attributes:
<div id="stage" data-composition-id="my-video" data-start="0" data-width="1920" data-height="1080">
<video
id="clip-1"
data-start="0"
data-duration="5"
data-track="0"
src="intro.mp4"
muted
playsinline
></video>
<img id="overlay" data-start="2" data-duration="3" data-track="1" src="logo.png" />
<audio
id="bg-music"
data-start="0"
data-duration="9"
data-track="2"
data-volume="0.5"
src="music.wav"
></audio>
</div>
Preview instantly in the browser. Render to MP4 locally. Let AI agents compose videos using tools they already understand.
Packages
| Package | Description |
|---|---|
hyperframes |
CLI — create, preview, lint, and render compositions |
@hyperframes/core |
Types, parsers, generators, linter, runtime, frame adapters |
@hyperframes/engine |
Seekable page-to-video capture engine (Puppeteer + FFmpeg) |
@hyperframes/producer |
Full rendering pipeline (capture + encode + audio mix) |
@hyperframes/studio |
Browser-based composition editor UI |
AI Agent Skills
HyperFrames ships skills that teach AI coding agents (Claude Code, Gemini CLI, Codex, Cursor) how to write correct compositions and GSAP animations. Use these instead of writing from scratch — they encode framework-specific patterns that generic docs don't cover.
Install via CLI (recommended)
# Install all skills (HyperFrames + GSAP) — runs automatically during `hyperframes init`
npx hyperframes skills
# Or install to a specific agent
npx hyperframes skills --claude
npx hyperframes skills --cursor
Or via npx skills add
# HyperFrames skills (hyperframes-compose, hyperframes-captions)
npx skills add heygen-com/hyperframes
# GSAP skills (gsap-core, gsap-timeline, gsap-scrolltrigger, gsap-plugins, gsap-performance, gsap-utils, gsap-react, gsap-frameworks)
npx skills add greensock/gsap-skills
Installed Skills
| Source | Skills | What they teach |
|---|---|---|
| HyperFrames | hyperframes-compose, hyperframes-captions |
HTML composition structure, class="clip" rules, data-* attributes, timeline registration, rendering constraints |
| GSAP | gsap-core, gsap-timeline, gsap-performance, gsap-plugins, gsap-scrolltrigger, gsap-utils, gsap-react, gsap-frameworks |
Core API, timeline sequencing, ScrollTrigger, plugin usage, performance best practices |
In Claude Code, invoke with /hyperframes-compose, /hyperframes-captions, /gsap-core, etc.
Contributing
See CONTRIBUTING.md for guidelines on how to contribute.
License
See LICENSE for details.