feat(cli): preview lifecycle — idle timeout and owner-pid for background servers

Rework of the original `preview --detach` PR on top of the
`--background/--status/--stop` lifecycle that landed in #2384: instead
of a parallel detached-server implementation (state files, launch
nonces, a --detached-child internal mode), the two capabilities main
lacks become first-class preview flags that ride the existing argv
forwarding into the background child.

- `--idle-timeout <minutes>`: the server shuts itself down after this
  long with no requests. An open Studio tab counts as activity (it
  polls the project signature), so "idle" means nobody — human or
  agent — is looking. `--background` children default to 60 minutes
  (injected by buildBackgroundPreviewArgs unless the caller pinned a
  value; `--idle-timeout 0` opts out), so background servers no longer
  outlive their usefulness. Foreground default stays disabled.
- `--owner-pid <pid>`: the server exits when that process does — an
  agent session can tie the preview to its own lifetime instead of
  leaking servers when it is killed.

The watcher checks both conditions every 30s and SIGTERMs itself,
reusing the exact Ctrl+C shutdown path (browser-pool drain, ffmpeg
kill, hard deadline). Flags parse and fail loudly in the launching
process, not inside a detached child's log file. Vite dev/local-studio
modes warn that lifecycle flags apply to the embedded server only.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Miao Yang
2026-07-14 16:55:11 +08:00
co-authored by Claude Fable 5
parent 6933e8acda
commit 02166dad9f
5 changed files with 218 additions and 4 deletions
@@ -9,8 +9,13 @@ npx hyperframes preview # serve current directory
npx hyperframes preview --port 4567 # custom port (default 3002)
npx hyperframes preview --selection --json # print the current Studio selection and exit
npx hyperframes preview --context --json # print compact agent context from Studio
npx hyperframes preview --background # keep the server running after the command exits
npx hyperframes preview --status # show the background server for this project
npx hyperframes preview --stop # stop the background server for this project
```
Background servers shut themselves down after 60 minutes without a request — an open Studio tab counts as activity (it polls the project signature), so "idle" means nobody is looking. Tune with `--idle-timeout <minutes>` (`0` disables), or pass `--owner-pid <pid>` to tie the server to your session so it exits when your process does.
Hot-reloads on file changes. Opens Studio in the browser automatically — the full timeline editor, where the user can play the video and edit anything by hand before rendering. This is the review surface, not just a viewer.
When handing a project back to the user, use the Studio project URL, not the source `index.html` path: