Skip to content

AGENTS.md

Latest commit

 

History

History
75 lines (55 loc) · 2.85 KB

AGENTS.md

File metadata and controls

75 lines (55 loc) · 2.85 KB

Hyperframes

Open-source video rendering framework: write HTML, render video.

Skills

This repo ships AI agent skills via vercel-labs/skills. Install them before writing compositions — they encode framework-specific patterns that generic docs don't cover.

npx skills add heygen-com/hyperframes

Build & Test

bun install     # Install dependencies (NOT pnpm — do not create pnpm-lock.yaml)
bun run build   # Build all packages
bun run test    # Run all tests

Linting & Formatting

Uses oxlint and oxfmt (not eslint, not prettier, not biome).

bunx oxlint <files>        # Lint
bunx oxfmt <files>         # Format
bunx oxfmt --check <files> # Check formatting (CI / pre-commit)

Always lint and format changed files before committing. Lefthook pre-commit hooks enforce this automatically.

Composition Validation

After creating or editing any .html composition:

npx hyperframes lint       # Static HTML structure check
npx hyperframes validate   # Runtime check (headless Chrome — catches JS errors, missing assets)

Both must pass before previewing or considering work complete.

Project Structure

packages/
  cli/                  → hyperframes CLI (create, preview, lint, render)
  core/                 → Types, parsers, generators, linter, runtime, frame adapters
  engine/               → Seekable page-to-video capture engine (Puppeteer + FFmpeg)
  player/               → Embeddable <hyperframes-player> web component
  producer/             → Full rendering pipeline (capture + encode + audio mix)
  shader-transitions/   → WebGL shader transitions for compositions
  studio/               → Browser-based composition editor UI
registry/
  blocks/               → Installable sub-composition scenes (50+)
  components/           → Installable effects and snippets
  examples/             → Starter project templates
docs/                   → Mintlify documentation site (hyperframes.heygen.com)
skills/                 → AI agent skill definitions

Key Conventions

  • Package manager: bun (not pnpm, not npm for workspace operations)
  • Commit format: Conventional commits (feat:, fix:, docs:, refactor:, test:)
  • TypeScript: Avoid any and as T assertions. Prefer type guards and narrowing.
  • Compositions: HTML files with data-* attributes. Clips need class="clip". GSAP timelines must be paused and registered on window.__timelines.
  • Frame Adapters: Animation runtimes plug in via the seek-by-frame adapter pattern. GSAP is the primary adapter.
  • Deterministic rendering: No Date.now(), no unseeded Math.random(), no render-time network fetches.

Documentation