mirror of
https://github.com/hanzoai/frames.git
synced 2026-09-24 00:08:03 +00:00
docs: LLM.md is the guide; CLAUDE.md and AGENTS.md are symlinks to it
One file per repo, three names for it. The names exist because different tools look for different filenames; the CONTENT existing three times is how they drift, and a drifted agent guide is worse than none — it is confidently wrong. Where a name already held the only guide, that file BECAME LLM.md byte for byte rather than being replaced by a copy, so nothing was rewritten or lost. Repos where two names held genuinely DIFFERENT guides were skipped, not merged: symlinking there would delete one of them, and choosing which paragraphs survive is not a sweep's decision. Co-authored-by: Hanzo Dev <[email protected]>
This commit is contained in:
zooqueen
@@ -1,90 +0,0 @@
|
||||
# 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. **Default to the core set** — the `/frames` router installs each creation workflow on demand; install everything only when the user explicitly asks for the full set.
|
||||
|
||||
```bash
|
||||
npx frames skills update # default: installs/refreshes the core set — workflows install on demand
|
||||
npx skills add hanzoai/frames --full-depth # interactive picker (terminal only — non-interactive without --skill installs everything)
|
||||
```
|
||||
|
||||
**Creation workflows** route through one entry skill — read `/frames` first: it orients you to the whole surface, confirms the brief up front (the intent layer), and maps "make me a…" intent — usually a video, but also a navigable deck (`/slideshow`) or a composition port (`/remotion-to-frames`) — to a concrete workflow. Consult it before invoking a specific workflow:
|
||||
|
||||
- `/product-launch-video` — any **website** URL (or a pre-written script / text brief in no-capture mode) → a product launch / promo video, or a site tour / showcase featuring the site's own captured screens; up to ~3 min (sweet spot ~30-90s).
|
||||
- `/faceless-explainer` — arbitrary text, **no URL and no website capture** → faceless explainer, up to ~3 min (sweet spot ~30-90s); every visual is LLM-invented (typography / abstract graphics / diagram / data-viz).
|
||||
- `/embedded-captions` — an existing talking-head video (MP4) → the same footage with captions / subtitles added (verbatim rail + embedded climax, or pure-cinematic embed); the footage itself is untouched (no NLE-style editing).
|
||||
- `/talking-head-recut` — an existing talking-head / interview / podcast video (MP4) → the same footage packaged with designed **graphic overlays** (kinetic titles, lower-thirds, data callouts, pull-quotes, side panels, pip) synced to the transcript; the clip plays unchanged underneath, footage untouched. For plain captions/subtitles → `/embedded-captions`.
|
||||
- `/pr-to-video` — a GitHub PR (URL / `owner/repo#N` / "this PR") → code-change explainer, up to ~3 min (changelog / feature reveal / fix / refactor). A PR link, not a product website.
|
||||
- `/motion-graphics` — a short (typically under 10s) design-led **motion graphic**, motion-is-the-message, no narration: kinetic type, a stat / number count-up, a chart, a logo sting, a lower-third / overlay, or an animated tweet / headline / captured-page highlight; rendered to MP4 or a transparent overlay. Longer / narrated / custom → `/general-video`.
|
||||
- `/music-to-video` — a **music track** (audio file, or video to pull audio from) → beat-synced video (lyric / slideshow / kinetic promo). Music drives pacing; user-supplied images / videos are cut onto the same beat grid.
|
||||
- `/slideshow` — a **presentation / pitch deck / interactive deck** — discrete slides, fragment reveals, branching, hotspot navigation, presenter mode. Output is a navigable deck, not a rendered video.
|
||||
- `/general-video` — fallback for any other video creation (title card, longer brand / sizzle reel, multi-scene montage, static loop, custom composition) and the home of **companion mode** — co-create with the full Frames toolbox; the original frames flow — design → plan → layout → build → validate, any length.
|
||||
|
||||
**Porting an existing composition?** `/remotion-to-frames` translates a Remotion (React) video composition into Frames HTML — a source migration, separate from the creation workflows above.
|
||||
|
||||
## 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 frames lint # Static HTML structure check
|
||||
npx frames check # Browser gate (headless Chrome — runtime errors, layout, motion, WCAG contrast)
|
||||
```
|
||||
|
||||
Both must pass before previewing or considering work complete.
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
packages/
|
||||
cli/ → frames CLI (create, preview, lint, render)
|
||||
core/ → Types, parsers, generators, linter, runtime, frame adapters
|
||||
engine/ → Seekable page-to-video capture engine (Puppeteer + FFmpeg)
|
||||
player/ → Embeddable <frames-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 (frames.hanzo.ai)
|
||||
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://frames.hanzo.ai/introduction
|
||||
- Catalog (50+ blocks): https://frames.hanzo.ai/catalog/blocks/data-chart
|
||||
@@ -0,0 +1,90 @@
|
||||
# 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. **Default to the core set** — the `/frames` router installs each creation workflow on demand; install everything only when the user explicitly asks for the full set.
|
||||
|
||||
```bash
|
||||
npx frames skills update # default: installs/refreshes the core set — workflows install on demand
|
||||
npx skills add hanzoai/frames --full-depth # interactive picker (terminal only — non-interactive without --skill installs everything)
|
||||
```
|
||||
|
||||
**Creation workflows** route through one entry skill — read `/frames` first: it orients you to the whole surface, confirms the brief up front (the intent layer), and maps "make me a…" intent — usually a video, but also a navigable deck (`/slideshow`) or a composition port (`/remotion-to-frames`) — to a concrete workflow. Consult it before invoking a specific workflow:
|
||||
|
||||
- `/product-launch-video` — any **website** URL (or a pre-written script / text brief in no-capture mode) → a product launch / promo video, or a site tour / showcase featuring the site's own captured screens; up to ~3 min (sweet spot ~30-90s).
|
||||
- `/faceless-explainer` — arbitrary text, **no URL and no website capture** → faceless explainer, up to ~3 min (sweet spot ~30-90s); every visual is LLM-invented (typography / abstract graphics / diagram / data-viz).
|
||||
- `/embedded-captions` — an existing talking-head video (MP4) → the same footage with captions / subtitles added (verbatim rail + embedded climax, or pure-cinematic embed); the footage itself is untouched (no NLE-style editing).
|
||||
- `/talking-head-recut` — an existing talking-head / interview / podcast video (MP4) → the same footage packaged with designed **graphic overlays** (kinetic titles, lower-thirds, data callouts, pull-quotes, side panels, pip) synced to the transcript; the clip plays unchanged underneath, footage untouched. For plain captions/subtitles → `/embedded-captions`.
|
||||
- `/pr-to-video` — a GitHub PR (URL / `owner/repo#N` / "this PR") → code-change explainer, up to ~3 min (changelog / feature reveal / fix / refactor). A PR link, not a product website.
|
||||
- `/motion-graphics` — a short (typically under 10s) design-led **motion graphic**, motion-is-the-message, no narration: kinetic type, a stat / number count-up, a chart, a logo sting, a lower-third / overlay, or an animated tweet / headline / captured-page highlight; rendered to MP4 or a transparent overlay. Longer / narrated / custom → `/general-video`.
|
||||
- `/music-to-video` — a **music track** (audio file, or video to pull audio from) → beat-synced video (lyric / slideshow / kinetic promo). Music drives pacing; user-supplied images / videos are cut onto the same beat grid.
|
||||
- `/slideshow` — a **presentation / pitch deck / interactive deck** — discrete slides, fragment reveals, branching, hotspot navigation, presenter mode. Output is a navigable deck, not a rendered video.
|
||||
- `/general-video` — fallback for any other video creation (title card, longer brand / sizzle reel, multi-scene montage, static loop, custom composition) and the home of **companion mode** — co-create with the full Frames toolbox; the original frames flow — design → plan → layout → build → validate, any length.
|
||||
|
||||
**Porting an existing composition?** `/remotion-to-frames` translates a Remotion (React) video composition into Frames HTML — a source migration, separate from the creation workflows above.
|
||||
|
||||
## 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 frames lint # Static HTML structure check
|
||||
npx frames check # Browser gate (headless Chrome — runtime errors, layout, motion, WCAG contrast)
|
||||
```
|
||||
|
||||
Both must pass before previewing or considering work complete.
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
packages/
|
||||
cli/ → frames CLI (create, preview, lint, render)
|
||||
core/ → Types, parsers, generators, linter, runtime, frame adapters
|
||||
engine/ → Seekable page-to-video capture engine (Puppeteer + FFmpeg)
|
||||
player/ → Embeddable <frames-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 (frames.hanzo.ai)
|
||||
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://frames.hanzo.ai/introduction
|
||||
- Catalog (50+ blocks): https://frames.hanzo.ai/catalog/blocks/data-chart
|
||||
Reference in New Issue
Block a user