Miguel Ángel
246a1911b1
* fix(studio): auto-reconnect when preview server is not running When the preview server is not reachable (tab reload after server died, or opening the URL before running npm run dev), the Studio was silently swallowing the fetch error and rendering an infinite pulsing dot with no recovery path. Users had no idea what happened. Instead of showing an error and asking the user to act, the Studio now polls /api/projects every 2 seconds and automatically transitions into the full editor the moment the server becomes available — no manual reload required. Also fixes how agents are instructed about the dev server: CLAUDE.md and AGENTS.md listed `npm run dev` as a one-liner comment identical to other commands, giving no indication it blocks until stopped. Agents (including Claude Code) were running it in foreground, timing out after ~2 minutes, and silently killing the server. Added an explicit note that it must be started as a background process. * fix(studio): auto-reconnect when preview server is not running Two issues combined to produce the "reloading the tab kills the whole" experience for users running with an AI agent: 1. Agents silently killed the server — CLAUDE.md/AGENTS.md listed npm run dev with no indication it blocks. Agents ran it in foreground, the Bash tool timed out, and the process died. Added an explicit run_in_background instruction. 2. Studio had no recovery path — fetch errors were swallowed, leaving a permanent pulsing dot with no way out. Now the Studio polls every 2s and auto-transitions the moment the server responds. Also fixes the bookmark-reload case: the hash path previously bailed out before pinging the server, so a dead server + saved URL produced a blank editor instead of the waiting state. The server is now always contacted first, regardless of whether a hash project ID is present. Timer cleanup (cancelled flag + clearTimeout) prevents setState on unmounted components under StrictMode dev re-mounts. Extracted into useServerConnection hook to keep App.tsx under the 500 LOC limit.
hyperframes
CLI for creating, previewing, and rendering HTML video compositions.
Install
npm install -g hyperframes
Or use directly with npx:
npx hyperframes <command>
Requirements: Node.js >= 22, FFmpeg
Commands
init
Scaffold a new Hyperframes project from a template:
npx hyperframes init my-video
cd my-video
preview
Start the live preview studio in your browser:
npx hyperframes preview
# Studio running at http://localhost:3002
npx hyperframes preview --port 4567
render
Render a composition to MP4:
npx hyperframes render ./my-composition.html -o output.mp4
lint
Validate your Hyperframes HTML:
npx hyperframes lint ./my-composition
npx hyperframes lint ./my-composition --json # JSON output for CI/tooling
npx hyperframes lint ./my-composition --verbose # Include info-level findings
By default only errors and warnings are shown. Use --verbose to also display informational findings (e.g., external script dependency notices). Use --json for machine-readable output with errorCount, warningCount, infoCount, and a findings array.
compositions
List compositions found in the current project:
npx hyperframes compositions
benchmark
Run rendering benchmarks:
npx hyperframes benchmark ./my-composition.html
doctor
Check your environment for required dependencies (Chrome, FFmpeg, Node.js):
npx hyperframes doctor
browser
Manage the bundled Chrome/Chromium installation:
npx hyperframes browser
info
Print version and environment info:
npx hyperframes info
docs
Open the documentation in your browser:
npx hyperframes docs
upgrade
Check for updates and show upgrade instructions:
npx hyperframes upgrade
npx hyperframes upgrade --check --json # machine-readable for agents
Documentation
Full documentation: hyperframes.heygen.com/packages/cli
Related packages
@hyperframes/core— types, parsers, frame adapters@hyperframes/engine— rendering engine@hyperframes/producer— render pipeline@hyperframes/studio— composition editor UI