mirror of https://github.com/heygen-com/hyperframes.git synced 2026-09-03 04:38:33 +00:00

Files

T

James Russo 7b0c7e73b2 refactor: frame reorder buffer + port probe cleanup; add CREDITS.md and missing skill (#341 )

* refactor(engine): restructure frame reorder buffer with Map-keyed storage

Rewrites createFrameReorderBuffer to use a Map<number, Array<() => void>>
keyed by frame index instead of a flat Array<{frame, resolve}> scanned on
every advance. O(1) lookups in enqueue/flush, fast-paths for the matching-
cursor and overshoot cases, and a small fix: waitForAllDone now coexists
with the writer still waiting on the final frame instead of colliding on
the same waiter slot.

Also adds 5 unit tests (there were none before) covering the fast-path,
out-of-order gating, multi-waiter-per-frame semantics, waitForAllDone
normal path, and the overshoot case.

Comment tweaks on buildChromeArgs — the flag profile is the standard
headless-for-capture set (Puppeteer / Playwright / Chrome headless-shell
all converge on similar flags); rephrased for clarity.

* refactor(cli): simplify port availability probe with async/await

Rewrites isPortAvailableOnHost from a single new-Promise callback into an
async/await form with an intermediate `bindError: ErrnoException | null`
variable. Makes the bind-then-release flow explicit as two sequential
awaits, and broadens the non-EADDRINUSE errno commentary (EADDRNOTAVAIL
for disabled IPv6, EACCES for privileged ports, EAFNOSUPPORT for missing
address families — all treated as "this host doesn't apply", not "port
occupied").

No behavior change to existing callers; all four portUtils tests still
pass.

* docs: add CREDITS.md and surface website-to-hyperframes skill

- New CREDITS.md acknowledging prior art in the browser-based video
  rendering space (Remotion) and the ecosystem HyperFrames builds on
  (Puppeteer, FFmpeg, GSAP, Hono). Standard OSS practice.

- Adds the `website-to-hyperframes` skill to the skills tables in
  README.md, docs/guides/prompting.mdx, and the project template at
  packages/cli/src/templates/_shared/CLAUDE.md. The skill ships in
  skills/ but was missing from every table.

- Adds `/hyperframes-registry` to the prose mention in the repo
  CLAUDE.md.

2026-04-19 16:33:42 -07:00

2.5 KiB

Raw Blame History

Hyperframes

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

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)
  studio/    → Browser-based composition editor UI

Development

bun install     # Install dependencies
bun run build   # Build all packages
bun run test    # Run tests

This repo uses bun, not pnpm. Do NOT run pnpm install — it creates a pnpm-lock.yaml that should not exist. Workspace linking relies on bun's resolution from "workspaces" in root package.json.

Linting & Formatting

This project uses oxlint and oxfmt (not biome, not eslint, not prettier).

bunx oxlint <files>        # Lint
bunx oxfmt <files>         # Format (write)
bunx oxfmt --check <files> # Format (check only, used by pre-commit hook)

Always run both on changed files before committing. The lefthook pre-commit hook runs bunx oxlint and bunx oxfmt --check automatically.

Adding CLI Commands

When adding a new CLI command:

Define the command in packages/cli/src/commands/<name>.ts using defineCommand from citty
Export examples in the same file — export const examples: Example[] = [...] (import Example from ./_examples.js). These are displayed by --help.
Register it in packages/cli/src/cli.ts under subCommands (lazy-loaded)
Add to help groups in packages/cli/src/help.ts — add the command name and description to the appropriate GROUPS entry. Without this, the command won't appear in hyperframes --help even though it works.
Document it in docs/packages/cli.mdx — add a section with usage examples and flags.
Validate by running npx tsx packages/cli/src/cli.ts --help (command appears in the list) and npx tsx packages/cli/src/cli.ts <name> --help (examples appear).

Skills

Composition authoring (not repo development) is guided by skills installed via npx skills add heygen-com/hyperframes. See skills/ for source. Invoke /hyperframes, /hyperframes-cli, /hyperframes-registry, or /gsap when authoring compositions. When a user provides a website URL and wants a video, invoke /website-to-hyperframes — it runs the full 7-step capture-to-video pipeline.