Files
hyperframes/CLAUDE.md
T
ukimsanov f4f6739510 docs: add HANDOFF.md, agent feedback, and CLAUDE.md session header
- HANDOFF.md: 747-line context doc for the May 15-16 pipeline quality session
  (git state, all skill changes, eval arena, video locations, key discoveries)
- AGENT-FEEDBACK-V2.md: 7-agent post-run friction report with priority action
  items (P0: HyperShader CSS crossfade bug, snapshot loading-screen blindspot)
- CLAUDE.md: add READ HANDOFF.md FIRST notice at top for new sessions
2026-05-16 00:55:09 -07:00

5.3 KiB
Raw Blame History

⚠️ READ HANDOFF.md FIRST

Before starting any work in this repo, read HANDOFF.md at the repo root. It's the full context document from the May 15–16 2026 pipeline quality session — 747 lines covering git state, all skill + code changes, eval arena, video locations, key discoveries, and pending work. Skipping it will cause you to miss critical context.


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

Local CLI

The published npx hyperframes is a released version and does not include local changes. Use the local CLI for commands where changes are in flight:

# Local CLI (use instead of `npx hyperframes` for capture and snapshot):
npx tsx packages/cli/src/cli.ts <command>

# Examples:
npx tsx packages/cli/src/cli.ts capture <URL> -o videos/<name>/capture
npx tsx packages/cli/src/cli.ts snapshot videos/<name> --frames <N>

Commands with local changes: capture (paginated contact sheets, fit:contain, SVG root scan), snapshot (3-col contact sheet). All other commands (lint, validate, preview, render) can use npx hyperframes as-is.

For shader transitions, copy the local build into the video project instead of using the CDN — the local build includes CSS crossfade mixing support and other fixes not yet published:

cp packages/shader-transitions/dist/index.global.js <project-dir>/hyper-shader-local.js

Then reference hyper-shader-local.js instead of the @hyperframes/shader-transitions CDN URL in index.html.

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:

  1. Define the command in packages/cli/src/commands/<name>.ts using defineCommand from citty
  2. Export examples in the same file — export const examples: Example[] = [...] (import Example from ./_examples.js). These are displayed by --help.
  3. Register it in packages/cli/src/cli.ts under subCommands (lazy-loaded)
  4. 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.
  5. Document it in docs/packages/cli.mdx — add a section with usage examples and flags.
  6. 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).

Regression Test Golden Baselines (producer)

packages/producer/tests/<name>/output/output.mp4 baselines MUST be generated inside Dockerfile.test, not on your host. CI renders inside that Docker image with a specific Chrome + ffmpeg build; pixel-level output drifts across different host Chrome/ffmpeg versions and will fail PSNR at dozens of checkpoints even when the code is correct.

# Build the test image once:
docker build -t hyperframes-producer:test -f Dockerfile.test .

# Generate or update a baseline (runs the harness with --update inside Docker):
bun run --cwd packages/producer docker:test:update <test-name>

Never run bun run --cwd packages/producer test:update directly from the host to capture a baseline that will be committed — the resulting output.mp4 will not match CI. Use it only for local-only experimentation.

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, /tailwind, or /gsap when authoring compositions. Use /tailwind for projects created with hyperframes init --tailwind so agents follow the pinned Tailwind v4 browser-runtime contract instead of Studio's Tailwind v3 setup. Use /animejs, /css-animations, /lottie, /three, or /waapi when a composition uses those first-party runtime adapters. Invoke /hyperframes-media for asset preprocessing (TTS narration, audio/video transcription, background removal for transparent overlays) — these commands have their own skill so the CLI skill stays focused on the dev loop. 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.