fix(studio): boost quiet clips and persist agent previews

[miguel-heygen]

What

Fixes both issue families reported in the six screenshots:

1. Studio can now raise a quiet clip above unity gain. The shared fader uses dB, places 0 dB / linear gain 1 at its midpoint, and supports up to +12 dB consistently in browser preview and FFmpeg render.
2. Agent-launched Studio previews no longer depend on the lifetime of the invoking shell. In non-interactive sessions, bare npx hyperframes preview now starts or reuses a managed persistent preview; human TTY sessions keep the familiar foreground/Ctrl+C behavior.

Managed previews expose exact Studio deep links and structured start/status/list/stop/kill-all state. --background and --foreground remain explicit overrides.

Why

The audio control previously treated unity as the maximum, so an agent could attenuate a loud clip but could not boost a quiet one. Matching control values, peaks, or cached metadata also do not prove equal perceived loudness.

The localhost timeout was not caused by browser refresh or by the shared project. Reproduction through the real npx hyperframes preview path showed that the foreground listener could disappear when the agent/tool-owned launcher session ended; the already-open page then failed on its next request. The same exact user-shared project survived repeated hard reloads while its listener remained alive.

Agents need a lifecycle that survives launcher exit, is safely discoverable and reusable, and cannot kill an unrelated process from a stale PID record.

How

• Added shared audio gain/dB conversion helpers and one +12 dB ceiling across Studio, Web Audio, runtime media, the engine mixer, and FFmpeg render.
• Converted both Studio media property panels to a nonlinear −∞ / −60 dB … 0 dB … +12 dB fader with unity at the center.
• Kept native HTMLMediaElement.volume clamped while applying above-unity gain through Web Audio.
• Added a detached preview lifecycle with readiness probing, per-project state/logs, custom-port discovery and reuse, stale-record cleanup, and ownership-checked stop.
• Made bare preview select managed mode only for non-TTY/agent sessions. Added --foreground for an explicitly attached process and retained --background as an explicit managed override.
• Added one-line JSON contracts for start/status/list/stop/kill-all, including validation and failure paths. --foreground --json emits readiness once and then remains attached.
• Emit the exact URL-encoded Studio project route on start/reuse/status; agents no longer construct project URLs themselves.
• Validate ports before detaching, reject launch-only overrides on lifecycle actions, and keep occupied-port fallback silent in JSON mode.
• Replace an owned managed preview before --force-new records its successor, including custom-port and GPU-policy changes, so the prior listener cannot become orphaned.
• Kill process trees on POSIX and Windows (taskkill /T /F). A saved wrapper is terminated only when both its persisted process-birth identity and the live server's ancestry prove ownership; otherwise stop targets only the live server PID.
• Close embedded project watchers on reuse, startup errors, and normal shutdown; throwing preflight completes before watcher acquisition.
• Updated CLI and installed-skill guidance for TTY/non-TTY behavior, persistence, reuse, status, logs, and cleanup.
• Updated loudness guidance to resolve the exact served asset bytes and compare integrated LUFS before and after gain changes.

Compatibility is preserved: existing data-volume="1" clips remain at unity, and interactive human preview remains foreground by default.

Test plan

• Unit tests added/updated
  • Full CLI Vitest: 186 files passed, 1 skipped; 2,675 tests passed, 3 skipped.
  • Preview lifecycle/command focused suite: 78/78 passed after the final hardening changes.
  • Skills suite: 466/466 passed.
  • Audio conversion, Web Audio, runtime media, Studio controls, engine mixer, FFmpeg, lifecycle ownership, Windows tree-kill arguments, custom-port replacement/reuse, JSON failures, and URL encoding have targeted coverage.
• Manual testing performed
  • Reproduced the localhost timeout through the packed real npx hyperframes preview path when its foreground owner disappeared.
  • Ran the exact user-shared project privately: it survived 8/8 hard reloads while foreground stayed alive and another 8/8 after a managed launcher exited; no project-content refresh crash reproduced.
  • Packed-CLI non-TTY acceptance: one-line JSON start, same-PID custom-port reuse without passing the port again, list/status discovery, exact Studio URL, 8/8 hard reloads, stop/kill-all cleanup, and no remaining listener/process/state.
  • Packed-CLI TTY acceptance: bare preview stayed attached and Ctrl+C reaped the listener and descendants.
  • Packed-CLI --foreground --json: emitted one readiness document, stayed attached, served HTTP 200, and cleaned up on interruption. Occupied-port fallback also emitted only that JSON document.
  • Invalid ports (banana, 0, 70000) fail before detach with one validation document and no process/listener/session leak; lifecycle actions combined with --force-new fail without performing the action.
  • Replaced a managed hardware-GPU preview on one custom port with a software-GPU --force-new preview on another: the old process/port closed and exactly one replacement record/listener remained.
  • Ran a three-listener ownership adversary: an explicit policy change stopped only the saved managed preview, preserved an unmanaged same-project sibling, attributed readiness to a newly started replacement, and later stopped only that replacement.
  • Multiple independent clean-room agent runs used only the installed skill and public CLI help and exercised start/reuse/status/list/stop, exact PID reporting, custom ports, JSON purity, wrapper ownership, and cleanup.
  • Verified special project names containing spaces, #, ?, and % produce the correct encoded Studio route.
  • Authored and rendered above-unity gain; measured render loudness increased by the authored dB amount.
• Documentation updated (if applicable)
  • CLI README and hyperframes-cli preview reference cover managed agent defaults, foreground human behavior, JSON contracts, exact deep links, reuse, status, logs, and cleanup.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
hyperframes	🟢 Ready	View Preview	Aug 15, 2026, 2:18 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.