mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 11:26:02 +00:00
docs: add AGENTS.md for universal AI assistant configuration (#278)
## What Adds `AGENTS.md` at two levels: 1. **Repo-level** (`/AGENTS.md`) — for contributors working on HyperFrames itself 2. **Project-level** (`packages/cli/src/templates/_shared/AGENTS.md`) — scaffolded into user projects by `hyperframes init` Also replaces the previous `AGENTS.md → CLAUDE.md` symlink with a standalone file. ## Why AGENTS.md is the emerging universal standard for AI coding tool configuration, supported by Claude Code, Cursor, GitHub Copilot, Gemini CLI, and Codex (60K+ repos). Remotion already has one. For a project that positions itself as AI-native, this is a gap. The project-level file (scaffolded by `init`) ensures every AI tool — not just Claude — gets framework context when working on a user's composition project. The symlink was replaced because symlinks are fragile on Windows and the content should differ (repo-level covers build/test, project-level covers composition rules). ## How - **Repo-level AGENTS.md**: Build/test/lint commands, project structure, key conventions, skills install, doc links - **Project-level AGENTS.md**: Composition-specific — skills, CLI commands, project structure, linting workflow, key rules, doc links - **CLAUDE.md** remains for Claude-specific skill invocation syntax (slash commands) ## Test plan - [ ] Verify AGENTS.md renders correctly on GitHub - [ ] Verify no duplication with CLAUDE.md (AGENTS.md = universal basics, CLAUDE.md = Claude-specific slash commands) - [ ] Manual testing performed - [x] Documentation updated (if applicable)
This commit is contained in:
@@ -0,0 +1,76 @@
|
||||
# Hyperframes
|
||||
|
||||
Open-source video rendering framework: write HTML, render video.
|
||||
|
||||
## Skills
|
||||
|
||||
This repo ships AI agent skills via [vercel-labs/skills](https://github.com/vercel-labs/skills). Install them before writing compositions — they encode framework-specific patterns that generic docs don't cover.
|
||||
|
||||
```bash
|
||||
npx skills add heygen-com/hyperframes # HyperFrames skills
|
||||
npx skills add greensock/gsap-skills # GSAP animation skills
|
||||
```
|
||||
|
||||
## Build & Test
|
||||
|
||||
```bash
|
||||
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).
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
- Docs: https://hyperframes.heygen.com/introduction
|
||||
- Catalog (50+ blocks): https://hyperframes.heygen.com/catalog/blocks/data-chart
|
||||
@@ -1 +0,0 @@
|
||||
CLAUDE.md
|
||||
@@ -0,0 +1,59 @@
|
||||
# HyperFrames Composition Project
|
||||
|
||||
## Skills
|
||||
|
||||
This project uses AI agent skills for framework-specific patterns. Install them if not already present:
|
||||
|
||||
```bash
|
||||
npx skills add heygen-com/hyperframes # HyperFrames composition skills
|
||||
npx skills add greensock/gsap-skills # GSAP animation skills
|
||||
```
|
||||
|
||||
Skills encode patterns like `class="clip"` on timed elements, `window.__timelines` registration, and `data-*` attribute semantics that are not in generic web docs. Using them produces correct compositions from the start.
|
||||
|
||||
## Commands
|
||||
|
||||
```bash
|
||||
npx hyperframes preview # preview in browser (studio editor)
|
||||
npx hyperframes render # render to MP4
|
||||
npx hyperframes lint # validate compositions (errors + warnings)
|
||||
npx hyperframes lint --json # machine-readable output for CI
|
||||
npx hyperframes docs <topic> # reference docs in terminal
|
||||
```
|
||||
|
||||
## Project Structure
|
||||
|
||||
- `index.html` — main composition (root timeline)
|
||||
- `compositions/` — sub-compositions referenced via `data-composition-src`
|
||||
- `assets/` — media files (video, audio, images)
|
||||
- `meta.json` — project metadata (id, name)
|
||||
- `transcript.json` — whisper word-level transcript (if generated)
|
||||
|
||||
## Linting — Always Run After Changes
|
||||
|
||||
After creating or editing any `.html` composition, run the linter before considering the task complete:
|
||||
|
||||
```bash
|
||||
npx hyperframes lint
|
||||
```
|
||||
|
||||
Fix all errors before presenting the result.
|
||||
|
||||
## Key Rules
|
||||
|
||||
1. Every timed element needs `data-start`, `data-duration`, and `data-track-index`
|
||||
2. Visible timed elements **must** have `class="clip"` — the framework uses this for visibility control
|
||||
3. GSAP timelines must be paused and registered on `window.__timelines`:
|
||||
```js
|
||||
window.__timelines = window.__timelines || {};
|
||||
window.__timelines["composition-id"] = gsap.timeline({ paused: true });
|
||||
```
|
||||
4. Videos use `muted` with a separate `<audio>` element for the audio track
|
||||
5. Sub-compositions use `data-composition-src="compositions/file.html"`
|
||||
6. Only deterministic logic — no `Date.now()`, no `Math.random()`, no network fetches
|
||||
|
||||
## Documentation
|
||||
|
||||
Full docs: https://hyperframes.heygen.com/introduction
|
||||
|
||||
Machine-readable index for AI tools: https://hyperframes.heygen.com/llms.txt
|
||||
Reference in New Issue
Block a user