mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-03 12:54:29 +00:00
James RussoandClaude Opus 4.6
237847e5c6
* docs: add prompt cookbook + prompting guide for AI agents Addresses user feedback that there's no guidance on how to actually prompt Claude Code (or other agents) once the hyperframes skills are installed. Adds copy-pasteable example prompts in the README and quickstart, a new prompting guide page, and a starter-prompt nudge in the `hyperframes init` output. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs(prompting): add vocabulary tables, rules, and TTS voice guide Merges the best content from the internal prompt guide into prompting.mdx: easing vocabulary, caption tone table, transition energy matrix, audio-reactive frequency mapping, marker highlight modes, TTS voice recommendations, rendering quality presets, and framework rules (technical requirements vs best practices). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs(prompting): rename page title to "Prompt Guide" Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * chore: remove greensock/gsap-skills dependency, fix Math.random nuance The bundled skills/gsap/ already covers the GSAP surface needed for HyperFrames compositions. Installing greensock/gsap-skills on top adds a competing full-ecosystem skill that's mostly irrelevant (ScrollTrigger, Draggable, SplitText, etc.) and can confuse agents about which GSAP context to load. Also adds seeded-PRNG nuance to the Math.random() rule in the prompt guide (matching the skill's actual guidance). Removed from: skills.ts, README, AGENTS.md, shared AGENTS.md/CLAUDE.md, and prompting.mdx. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * chore: require minimal reproduction link in bug report template Adds a required "Link to reproduction" input field asking users to push a minimal repro to a public GitHub repo (scaffolded via `hyperframes init repro --non-interactive --example blank`). Also consolidates the OS/Node/FFmpeg/version fields into a single "Environment" field using `npx hyperframes info` output — fewer fields to fill, more consistent data. Follows the same pattern as Next.js and Gatsby issue templates. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix(issue-template): use hyperframes doctor for environment info `hyperframes info` only prints project metadata (resolution, duration, elements). `hyperframes doctor` prints the full environment: version, Node.js, FFmpeg, Chrome, memory, disk, Docker — everything needed to diagnose bugs. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs(prompting): mention validate alongside lint in anti-patterns Per Vance's review comment — validate catches runtime errors (JS exceptions, missing assets, contrast) that lint doesn't. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: replace libretto example URL with hyperframes repo Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
76 lines
2.9 KiB
Markdown
76 lines
2.9 KiB
Markdown
# 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
|
|
```
|
|
|
|
## 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
|