mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-01 19:42:03 +00:00
Miguel Ángel
5388a48adf
## What Added three new lint rules to the Hyperframe HTML linter to catch common runtime errors and invalid script references. ## Why These lint rules prevent silent failures and runtime errors that can break Hyperframe compositions: 1. Timeline assignments without initialization guards cause silent failures when `window.__timelines` is undefined 2. Mismatched timeline IDs between `data-composition-id` attributes and `window.__timelines` keys prevent proper auto-nesting 3. Hallucinated script sources referencing non-existent `@hyperframe/` packages result in 404 errors ## How Implemented three new lint rules with corresponding error codes: - `timeline_registry_missing_init`: Detects timeline assignments without proper initialization guard using regex pattern matching - `timeline_id_mismatch`: Cross-references composition IDs from HTML attributes against timeline registry keys to identify mismatches - `hallucinated_script_src`: Checks script `src` attributes against known bad patterns for non-existent CDN packages Each rule provides specific error messages and fix hints to guide developers toward correct implementations. ## Test plan - [x] Unit tests added/updated - [x] Manual testing performed - [ ] Documentation updated (if applicable) Added comprehensive test coverage for all three new lint rules, including both positive and negative test cases to ensure proper detection and avoid false positives.
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
npx hyperframes dev # preview in browser
npx hyperframes render # render to MP4
Requirements: Node.js >= 22, FFmpeg
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 (compose-video, 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 | compose-video, 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 /compose-video, /captions, /gsap-core, etc.
Documentation
Full docs at hyperframes.heygen.com — includes guides, concepts, API reference, and package documentation.
Contributing
See CONTRIBUTING.md for guidelines on how to contribute.
License
See LICENSE for details.