Doctor Browser

Runs independent checks and reports each as ok/warn/fail:

• Version — installed CLI vs latest on npm (hints upgrade when stale)
• Node.js — ≥ 22 required
• CPU, Memory, Disk — host resources
• Environment — env vars that affect the renderer
• FFmpeg / FFprobe — found, version, codecs
• Chrome — bundled or system, version, path
• Docker / Docker running — required only for render --docker
• /dev/shm — inside containers only

Run doctor first when:

• render fails with a Chrome or FFmpeg error.
• preview opens but the composition fails to load.
• A fresh machine has never run HyperFrames.

Common issues:

• Missing FFmpeg — install via brew install ffmpeg (macOS) or your package manager.
• Missing bundled Chrome — run npx hyperframes browser ensure.
• Low memory — close other Chromes, reduce --workers, or use --quality draft.
• Chrome exits instantly inside an agent sandbox (macOS) — seatbelt-style sandboxes (e.g. codex workspace-write) block Chromium’s Mach port bootstrap (MachPortRendezvous; openai/codex#21292), so every Chrome — bundled, system, or headless shell — dies at startup. This is a host-level block, not a HyperFrames or Chrome install problem: compile checks and audio still pass, only rendering is unavailable. State the blocker and deliver the checked composition; render outside the sandbox or via render --docker / cloud rendering where available. Do not build a substitute rasterizer (magick/PIL/SVG frame pipelines) — on a blocked-browser host the deliverable IS the checked composition plus this blocker note, and rendering is handed to --docker, cloud, or the user. Write your final summary the moment the blocker is identified, BEFORE any optional fallback work: a later session failure must not erase the report of work already done.

browser

Manage the Chrome build HyperFrames uses for rendering. The pinned version exists because pixel output drifts across Chrome versions — using the bundled build keeps rendered output reproducible across machines.

Use path to embed the binary in scripts: $(npx hyperframes browser path).