Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
import { setCommandExitCode, requestCliExit } from "../utils/commandResult.js";
// fallow-ignore-file code-duplication
import { defineCommand } from "citty";
import type { Example } from "./_examples.js";
import { spawn, type ChildProcessByStdio } from "node:child_process";
import type { Readable } from "node:stream";
export const examples: Example[] = [
["Preview the current project", "hyperframes preview"],
["Print the current Studio selection as JSON", "hyperframes preview --selection --json"],
["Print current Studio context as JSON", "hyperframes preview --context --json"],
["Preview a specific project directory", "hyperframes preview ./my-video"],
["Use a custom port", "hyperframes preview --port 8080"],
["Force a new server even if one is already running", "hyperframes preview --force-new"],
["Keep preview running after this command exits", "hyperframes preview --background"],
["Force an attached preview in a non-interactive shell", "hyperframes preview --foreground"],
["Show the background preview for this project", "hyperframes preview --status"],
["Stop the background preview for this project", "hyperframes preview --stop"],
["Start without opening the browser", "hyperframes preview --no-open"],
["Open with a specific browser", "hyperframes preview --browser-path /usr/bin/chromium"],
[
"Open with CDP enabled (requires browser path + isolated profile)",
"hyperframes preview --browser-path /usr/bin/chromium --user-data-dir /tmp/hf-profile --remote-debugging-port 9222",
],
["List all active preview servers", "hyperframes preview --list"],
["Kill all active preview servers", "hyperframes preview --kill-all"],
[
"Disable auto-proxying of browser-hostile video codecs (HEVC, ProRes, AV1)",
"hyperframes preview --no-proxy",
],
[
"Show full lint findings on startup instead of the summary line",
"hyperframes preview --lint-verbose",
],
];
import { existsSync, lstatSync, mkdirSync, readlinkSync, symlinkSync, unlinkSync } from "node:fs";
import { resolve, dirname, basename, join } from "node:path";
import { fileURLToPath } from "node:url";
import { createRequire } from "node:module";
import * as clack from "@clack/prompts";
import { c } from "../ui/colors.js";
import { desktopHint, insideHostApp } from "../utils/desktopApp.js";
import { isDevMode } from "../utils/env.js";
import { normalizeErrorMessage as errorMessage } from "../utils/errorMessage.js";
import { buildNpxCommand } from "../utils/npxCommand.js";
import type { StudioSelectionSnapshot } from "@hyperframes/studio-server";
import {
openBrowser,
parseRemoteDebuggingPort,
validateRemoteDebuggingPortDeps,
} from "../utils/openBrowser.js";
import type { ProjectLintResult } from "../utils/lintProject.js";
import { runRenderSetupWorker } from "../utils/cancellableProcess.js";
import { formatLintStartupMessage } from "../utils/lintFormat.js";
import {
activeServerOnPort,
findPortAndServe,
scanActiveServers,
killActiveServers,
type FindPortResult,
} from "../server/portUtils.js";
import { killOrphanedProcesses, killProcessTree } from "../utils/orphanCleanup.js";
import { resolveProject, resolveProjectOrThrow } from "../utils/project.js";
import { resolveAutoProxy } from "../utils/projectConfig.js";
import { studioProxyEnv } from "../utils/studioProxyEnv.js";
import { PreviewServerPortMismatchError } from "../utils/studioSelectionClient.js";
import {
PreviewPortUnavailableError,
listBackgroundPreviewStatuses,
readBackgroundPreviewStatus,
startBackgroundPreview,
stopBackgroundPreview,
} from "./previewLifecycle.js";
import {
lifecycleFailurePayload,
lifecyclePayload,
writeLifecycleJson,
type PreviewLifecycleOperation,
type PreviewLifecyclePayload,
type PreviewLifecycleSession,
} from "./previewLifecycleOutput.js";
import { resolveLocalBrowserGpuMode, type BrowserGpuMode } from "../browser/gpuPolicy.js";
interface BrowserLaunchOptions {
noOpen?: boolean;
browserPath?: string;
userDataDir?: string;
remoteDebuggingPort?: number;
browserNoGpu?: boolean;
}
interface StudioLaunchOptions extends BrowserLaunchOptions {
projectName?: string;
autoProxy?: boolean;
browserGpuMode?: BrowserGpuMode;
port?: number;
json?: boolean;
}
interface EmbeddedStudioOptions extends StudioLaunchOptions {
forceNew?: boolean;
autoProxy?: boolean;
}
type StudioChildProcess = ChildProcessByStdio<null, Readable, Readable>;
const STUDIO_CHILD_SHUTDOWN_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"] as const;
type StudioShutdownSignal = (typeof STUDIO_CHILD_SHUTDOWN_SIGNALS)[number];
interface StudioSignalTarget {
once(event: StudioShutdownSignal, listener: () => void): unknown;
off(event: StudioShutdownSignal, listener: () => void): unknown;
}
type ContextField = "server" | "selection" | "lint" | "capabilities";
type CompactSelectionPayload = Pick<
StudioSelectionSnapshot,
| "schemaVersion"
| "projectId"
| "compositionPath"
| "sourceFile"
| "currentTime"
| "target"
| "label"
| "tagName"
| "boundingBox"
| "textContent"
| "thumbnailUrl"
>;
const DEFAULT_CONTEXT_FIELDS: ContextField[] = ["server", "selection", "lint", "capabilities"];
const PREVIEW_PORT_MISMATCH_CODE = "preview-port-mismatch";
export function backgroundStartFailureCode(error: unknown): string {
if (error instanceof PreviewServerPortMismatchError) return PREVIEW_PORT_MISMATCH_CODE;
if (error instanceof PreviewPortUnavailableError) return "preview-port-unavailable";
return "preview-start-failed";
}
export default defineCommand({
meta: {
name: "preview",
description: "Start the studio for previewing compositions",
},
args: {
dir: {
type: "positional",
description: "Project directory",
required: false,
},
port: {
type: "string",
description: "Port to run the preview server on",
default: "3002",
},
"force-new": {
type: "boolean",
description: "Start a new server even if one is already running for this project",
default: false,
},
background: {
type: "boolean",
description: "Start a preview that remains running after the command exits",
default: false,
},
foreground: {
type: "boolean",
description: "Keep preview attached even when the shell is non-interactive",
default: false,
},
status: {
type: "boolean",
description: "Show the background preview for this project and exit",
default: false,
},
stop: {
type: "boolean",
description: "Stop the background preview for this project and exit",
default: false,
},
list: {
type: "boolean",
description: "List all active preview servers and exit",
default: false,
},
"kill-all": {
type: "boolean",
description: "Kill all active preview servers and exit",
default: false,
},
"lint-verbose": {
type: "boolean",
description: "Show full lint findings on startup (default: a one-line summary)",
default: false,
},
open: {
type: "boolean",
default: true,
description: "Open browser automatically",
},
selection: {
type: "boolean",
description: "Print the current element selected in a running Studio preview and exit",
default: false,
},
json: {
type: "boolean",
description: "Output selection, context, or managed lifecycle state as JSON",
default: false,
},
context: {
type: "boolean",
description:
"Print the current agent-readable context from a running Studio preview and exit",
default: false,
},
"context-fields": {
type: "string",
description:
"Comma-separated context fields to include: server,selection,lint,capabilities (only with --context)",
},
"context-detail": {
type: "string",
description: "Context payload detail: compact or full (only with --context)",
default: "compact",
},
"browser-path": {
type: "string",
description: "Path to the browser executable to open",
},
"user-data-dir": {
type: "string",
description: "Chromium-compatible user data directory (requires --browser-path)",
},
"remote-debugging-port": {
type: "string",
description: "Chromium remote debugging port (requires --browser-path and --user-data-dir)",
},
"browser-no-gpu": {
type: "boolean",
default: false,
description:
"Launch the opened browser with --disable-gpu (requires --browser-path). For hosts where hardware acceleration crashes the graphics driver (e.g. NVIDIA Xid resets); with the system default browser use --no-open instead.",
},
"browser-gpu": {
type: "boolean",
description:
"Use hardware GPU for Studio thumbnails and frame capture; pass --no-browser-gpu for deterministic SwiftShader (default: auto-detect)",
default: undefined,
},
proxy: {
type: "boolean",
description:
"Auto-transcode browser-hostile video codecs (HEVC, ProRes, AV1) to a cached authoring proxy for preview (default: on; overrides hyperframes.json's media.autoProxy)",
negativeDescription: "Disable auto-proxying of browser-hostile video codecs",
},
},
async run({ args }) {
const launchModeError = previewLaunchModeError({
background: Boolean(args.background),
foreground: Boolean(args.foreground),
forceNew: Boolean(args["force-new"]),
status: Boolean(args.status),
stop: Boolean(args.stop),
list: Boolean(args.list),
killAll: Boolean(args["kill-all"]),
});
if (launchModeError) {
if (args.json) {
writeLifecycleJson(
lifecycleFailurePayload(
args.status
? "status"
: args.stop
? "stop"
: args.list
? "list"
: args["kill-all"]
? "kill-all"
: "start",
"conflicting-lifecycle-flags",
launchModeError,
),
);
} else {
clack.log.error(launchModeError);
}
setCommandExitCode(1);
return;
}
const portError = previewPortError(args.port);
if (portError) {
reportPreviewFailure(
Boolean(args.json),
args.status
? "status"
: args.stop
? "stop"
: args.list
? "list"
: args["kill-all"]
? "kill-all"
: "start",
"preview-validation-failed",
portError,
);
return;
}
const browserGpuMode = resolveLocalBrowserGpuMode(args["browser-gpu"] as boolean | undefined);
if (args["browser-gpu"] === true) process.env.PRODUCER_BROWSER_GPU_MODE = "hardware";
if (args["browser-gpu"] === false) process.env.PRODUCER_BROWSER_GPU_MODE = "software";
const startPort = parseInt(args.port ?? "3002", 10);
const explicitPort = hasExplicitPreviewPort(process.argv) ? startPort : undefined;
if (args.status || args.stop) {
try {
const project = args.json ? resolveProjectOrThrow(args.dir) : resolveProject(args.dir);
if (args.stop) {
const stopped = await stopBackgroundPreview(project.dir, startPort);
if (args.json) {
writeLifecycleJson(
lifecyclePayload(
"stop",
stopped
? { state: "stopped", projectDir: project.dir }
: { state: "not-running", projectDir: project.dir },
),
);
} else {
console.log(
stopped
? `\n ${c.success("Stopped background preview")} ${c.dim(project.dir)}\n`
: `\n ${c.dim("No background preview is running for")} ${project.dir}\n`,
);
}
return;
}
const status = await readBackgroundPreviewStatus(project.dir, startPort);
if (!status) {
if (args.json) {
writeLifecycleJson(
lifecyclePayload("status", {
state: "not-running",
projectDir: project.dir,
}),
);
} else {
console.log(`\n ${c.dim("No background preview is running for")} ${project.dir}\n`);
}
return;
}
if (args.json) {
writeLifecycleJson(
lifecyclePayload(
"status",
previewLifecycleSession({
state: "running",
mode: "background",
projectName: project.name,
projectDir: project.dir,
port: status.port,
pid: status.pid,
logPath: status.logPath,
}),
),
);
return;
}
printStudioSummary(project.name, previewBaseUrl(status.port), project.dir, {
details: [`Background preview running (PID ${status.pid}).`, `Log: ${status.logPath}`],
});
return;
} catch (error) {
reportPreviewFailure(
Boolean(args.json),
args.stop ? "stop" : "status",
args.stop ? "preview-stop-failed" : "preview-status-failed",
errorMessage(error),
);
return;
}
}
// --list: scan and display active servers
if (args.list) {
await handlePreviewList(startPort, Boolean(args.json));
return;
}
// --kill-all: kill all active servers
if (args["kill-all"]) {
await handlePreviewKillAll(startPort, Boolean(args.json));
return;
}
if (args.context) {
const project = resolveProject(args.dir);
return printCurrentContext(project.dir, startPort, {
json: Boolean(args.json),
fields: args["context-fields"] as string | undefined,
detail: args["context-detail"] as string | undefined,
preferredPort: explicitPort,
});
}
if (args.selection) {
const project = resolveProject(args.dir);
return printCurrentSelection(project.dir, startPort, Boolean(args.json), explicitPort);
}
const rawArg = args.dir;
const isImplicitCwd = !rawArg || rawArg === "." || rawArg === "./";
let project;
try {
project = args.json ? resolveProjectOrThrow(rawArg) : resolveProject(rawArg);
} catch (error) {
reportPreviewFailure(
Boolean(args.json),
"start",
"preview-start-failed",
errorMessage(error),
);
return;
}
const dir = project.dir;
const projectName = isImplicitCwd ? basename(process.env.PWD ?? dir) : project.name;
// Validation: --user-data-dir requires --browser-path
if (args["user-data-dir"] && !args["browser-path"]) {
reportPreviewFailure(
Boolean(args.json),
"start",
"preview-validation-failed",
"--user-data-dir requires --browser-path",
);
return;
}
// Validation: --remote-debugging-port deps
const depsError = validateRemoteDebuggingPortDeps({
browserPath: args["browser-path"] as string | undefined,
userDataDir: args["user-data-dir"] as string | undefined,
remoteDebuggingPort: args["remote-debugging-port"] as string | undefined,
});
if (depsError) {
reportPreviewFailure(Boolean(args.json), "start", "preview-validation-failed", depsError);
return;
}
const noOpen = !args.open;
const browserPath = args["browser-path"] as string | undefined;
const browserNoGpu = !!args["browser-no-gpu"];
if (browserNoGpu && !browserPath) {
reportPreviewFailure(
Boolean(args.json),
"start",
"preview-validation-failed",
"--browser-no-gpu requires --browser-path (the system default browser cannot receive Chromium flags — use --no-open on GPU-unstable hosts)",
);
return;
}
const userDataDir = args["user-data-dir"] as string | undefined;
let remoteDebuggingPort: number | undefined;
try {
remoteDebuggingPort = parseRemoteDebuggingPort(
args["remote-debugging-port"] as string | undefined,
);
} catch (err) {
reportPreviewFailure(
Boolean(args.json),
"start",
"preview-validation-failed",
(err as Error).message,
);
return;
}
// Resolve once so embedded, monorepo-dev, and locally installed Studio
// modes all receive identical --proxy/--no-proxy + config semantics.
const autoProxy = resolveAutoProxy(dir, args.proxy as boolean | undefined);
const launchMode = previewLaunchMode({
background: Boolean(args.background),
foreground: Boolean(args.foreground),
interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
devMode: isDevMode(),
localStudio: hasLocalStudio(dir),
});
const hostAppError = previewHostAppError(launchMode);
if (hostAppError) {
reportPreviewFailure(Boolean(args.json), "start", "host-app-owns-preview", hostAppError);
return;
}
// Kill orphaned chrome-headless-shell processes from previous crashed
// sessions. Deliberately last: this reaches outside the process and kills
// other people's PIDs, so it must not run for an invocation that turns out
// to be a validation error or a refusal and never starts anything.
const orphansKilled = killOrphanedProcesses();
if (orphansKilled > 0 && !args.json) {
console.log(
` ${c.dim(`Cleaned up ${orphansKilled} orphaned process${orphansKilled === 1 ? "" : "es"} from a previous session.`)}`,
);
}
// Runs in the CLI worker while Studio starts, so it never delays the opening; --json skips it.
const startupLint = args.json ? null : printStartupLint(dir, Boolean(args["lint-verbose"]));
if (launchMode === "background") {
let background;
try {
background = await startBackgroundPreview(dir, startPort, {
forceNew: Boolean(args["force-new"]),
// A bare launch promises same-project reuse, regardless of the mode
// the existing managed server resolved earlier. Only an explicit
// --browser-gpu/--no-browser-gpu request authorizes replacement.
browserGpuMode: args["browser-gpu"] === undefined ? undefined : browserGpuMode,
preferredPort: explicitPort,
});
} catch (error) {
const message = errorMessage(error);
if (args.json) {
writeLifecycleJson(
lifecycleFailurePayload("start", backgroundStartFailureCode(error), message),
);
} else {
clack.log.error(message);
}
setCommandExitCode(1);
return;
}
const url = `http://localhost:${background.port}`;
if (args.json) {
writeLifecycleJson(
lifecyclePayload(
"start",
previewLifecycleSession({
state: background.type,
mode: "background",
projectName,
projectDir: dir,
port: background.port,
pid: background.pid,
...(background.logPath ? { logPath: background.logPath } : {}),
}),
),
);
} else {
clack.intro(c.bold("hyperframes preview"));
printStudioSummary(projectName, url, dir, {
details: [
background.type === "reused"
? "Reusing the background server already running for this project."
: `Running in the background. Log: ${background.logPath}`,
"Changes reload automatically in the studio.",
],
footer: `Stop with: hyperframes preview ${JSON.stringify(dir)} --stop`,
});
}
openStudioBrowser(url, projectName, {
noOpen,
browserPath,
userDataDir,
remoteDebuggingPort,
browserNoGpu,
});
await startupLint;
return;
}
if (launchMode === "dev") {
return runDevMode(dir, {
projectName,
noOpen,
browserPath,
userDataDir,
remoteDebuggingPort,
browserNoGpu,
autoProxy,
browserGpuMode,
port: startPort,
json: Boolean(args.json),
});
}
// If @hyperframes/studio is installed locally, use Vite for full HMR
if (launchMode === "local") {
return runLocalStudioMode(dir, {
projectName,
noOpen,
browserPath,
userDataDir,
remoteDebuggingPort,
browserNoGpu,
autoProxy,
browserGpuMode,
port: startPort,
json: Boolean(args.json),
});
}
const forceNew = !!args["force-new"];
return runEmbeddedMode(dir, startPort, {
projectName,
forceNew,
autoProxy,
noOpen,
browserPath,
userDataDir,
remoteDebuggingPort,
browserNoGpu,
browserGpuMode,
json: Boolean(args.json),
});
},
});
async function printStartupLint(dir: string, verbose: boolean): Promise<void> {
try {
const lintResult = await runRenderSetupWorker<ProjectLintResult>(
"lint",
{ projectDir: dir },
{ maxBufferBytes: 8 * 1024 * 1024 },
);
if (lintResult.totalErrors === 0 && lintResult.totalWarnings === 0) return;
console.log();
for (const line of formatLintStartupMessage(
lintResult,
verbose ? { kind: "verbose" } : { kind: "summary", pointer: "studio" },
))
console.log(line);
console.log();
} catch (error) {
clack.log.warn(`Lint did not finish: ${errorMessage(error)}`);
}
}
export type PreviewLaunchMode = "background" | "dev" | "local" | "embedded";
export function previewLaunchMode(options: {
background: boolean;
foreground: boolean;
interactive: boolean;
devMode: boolean;
localStudio: boolean;
}): PreviewLaunchMode {
if (options.background) return "background";
if (!options.foreground && !options.interactive) return "background";
if (options.devMode) return "dev";
return options.localStudio ? "local" : "embedded";
}
export function previewHostAppError(
mode: PreviewLaunchMode,
env: NodeJS.ProcessEnv = process.env,
): string | null {
if (mode !== "background" || !insideHostApp(env)) return null;
return (
"A host app is running this project and owns its preview, so a background preview " +
"here would outlive this run and keep the project's history locked. Use the host " +
"app's preview, or run with --foreground to keep a preview attached to this run."
);
}
export function previewLaunchModeError(options: {
background: boolean;
foreground: boolean;
forceNew?: boolean;
status: boolean;
stop: boolean;
list: boolean;
killAll: boolean;
}): string | null {
if (options.background && options.foreground) {
return "--background and --foreground cannot be used together";
}
const actionCount = [options.status, options.stop, options.list, options.killAll].filter(
Boolean,
).length;
if (actionCount > 1) {
return "Only one of --status, --stop, --list, or --kill-all can be used at a time";
}
if (actionCount > 0 && (options.background || options.foreground || options.forceNew)) {
return "Preview launch overrides cannot be combined with lifecycle actions";
}
return null;
}
export function previewPortError(port: string | undefined): string | null {
const value = port ?? "3002";
if (!/^\d+$/.test(value)) return "--port must be an integer between 1 and 65535";
const parsed = Number(value);
return parsed >= 1 && parsed <= 65535 ? null : "--port must be an integer between 1 and 65535";
}
export function publicPreviewPid(
serverPid: string | null | undefined,
fallbackPid: number | null,
): number | null {
const parsed = Number(serverPid);
return Number.isInteger(parsed) && parsed > 0 ? parsed : fallbackPid;
}
function reportPreviewFailure(
json: boolean,
operation: PreviewLifecycleOperation,
code: string,
message: string,
): void {
if (json) writeLifecycleJson(lifecycleFailurePayload(operation, code, message));
else clack.log.error(message);
setCommandExitCode(1);
}
interface PreviewActionDependencies {
scan?: typeof scanActiveServers;
listManaged?: typeof listBackgroundPreviewStatuses;
stopManaged?: typeof stopBackgroundPreview;
killScanned?: typeof killActiveServers;
}
export async function handlePreviewList(
startPort: number,
json: boolean,
dependencies: PreviewActionDependencies = {},
): Promise<void> {
try {
const [scannedServers, managedSessions] = await Promise.all([
(dependencies.scan ?? scanActiveServers)(startPort),
(dependencies.listManaged ?? listBackgroundPreviewStatuses)(),
]);
const managedKeys = new Set(
managedSessions.map((session) => `${resolve(session.projectDir)}\0${session.port}`),
);
const servers = [
...managedSessions.map((session) => ({
port: session.port,
host: "127.0.0.1",
projectName: basename(session.projectDir),
projectDir: session.projectDir,
version: "managed",
pid: String(session.pid),
})),
...scannedServers.filter(
(server) => !managedKeys.has(`${resolve(server.projectDir)}\0${server.port}`),
),
];
if (json) {
writeLifecycleJson(
lifecyclePayload("list", {
state: "listed",
sessions: servers.map((server) =>
previewLifecycleSession({
state: "running",
mode: server.version === "managed" ? "background" : "unknown",
projectName: server.projectName,
projectDir: server.projectDir,
port: server.port,
pid: server.pid ? Number(server.pid) : null,
host: server.host,
}),
),
}),
);
return;
}
if (servers.length === 0) {
console.log("\n No active preview servers found.\n");
return;
}
console.log(`\n ${c.bold("Active preview servers:")}\n`);
for (const server of servers) {
const pid = server.pid ? c.dim(` (PID ${server.pid})`) : "";
console.log(
` ${c.accent(`Port ${server.port}`)} ${server.projectName} ${c.dim(server.projectDir)}${pid}`,
);
}
console.log(`\n ${servers.length} server${servers.length === 1 ? "" : "s"} running.\n`);
} catch (error) {
reportPreviewFailure(json, "list", "preview-list-failed", errorMessage(error));
}
}
export async function handlePreviewKillAll(
startPort: number,
json: boolean,
dependencies: PreviewActionDependencies = {},
): Promise<void> {
try {
const managedSessions = await (dependencies.listManaged ?? listBackgroundPreviewStatuses)();
let killed = 0;
// One unprovable record must not abandon the servers after it. A stop pass
// collects per-record failures and keeps going; propagating the first one
// left every later preview running AND unreported.
const failures: string[] = [];
for (const session of managedSessions) {
try {
if (
await (dependencies.stopManaged ?? stopBackgroundPreview)(
session.projectDir,
session.port,
)
) {
killed++;
}
} catch (error) {
failures.push(`${session.projectDir}: ${errorMessage(error)}`);
}
}
const swept = await (dependencies.killScanned ?? killActiveServers)(startPort);
killed += swept.killed;
// Ports whose owner the OS could not confirm are skipped rather than
// signalled; an agent reading this envelope needs to see that too, not just
// a lower count.
const unverified = swept.unverified;
if (json) {
writeLifecycleJson(
lifecyclePayload("kill-all", {
state: "killed-all",
stopped: killed,
...(failures.length > 0 ? { failed: failures } : {}),
...(unverified.length > 0 ? { unverifiedPorts: unverified } : {}),
}),
);
} else if (failures.length > 0 || unverified.length > 0) {
console.log(`\n Killed ${killed} preview server${killed === 1 ? "" : "s"}.`);
for (const failure of failures) clack.log.warn(`Could not stop ${failure}`);
if (unverified.length > 0) {
const plural = unverified.length === 1 ? "" : "s";
clack.log.warn(
`Left ${unverified.length} server${plural} alone (port${plural} ` +
`${unverified.join(", ")}): the OS could not confirm which process owns the ` +
`socket, and the server's own claim is not proof. Install lsof, or stop it ` +
`with its own preview --stop.`,
);
}
console.log();
} else if (killed === 0) {
console.log("\n No active preview servers to kill.\n");
} else {
console.log(`\n Killed ${killed} preview server${killed === 1 ? "" : "s"}.\n`);
}
} catch (error) {
reportPreviewFailure(json, "kill-all", "preview-kill-all-failed", errorMessage(error));
}
}
export function previewViteArgs(port: number | undefined): string[] {
return ["--host", "127.0.0.1", ...(port === undefined ? [] : ["--port", String(port)])];
}
// All preview modes bind the same IPv4 loopback so lifecycle probes and handed
// URLs agree on the reachable server.
function previewBaseUrl(port: number, host = "127.0.0.1"): string {
return `http://${host}:${port}`;
}
function absolutePreviewUrl(port: number, path: string, host = "127.0.0.1"): string {
if (/^https?:\/\//.test(path)) return path;
return `${previewBaseUrl(port, host)}${path.startsWith("/") ? path : `/${path}`}`;
}
function hasExplicitPreviewPort(argv: string[]): boolean {
return argv.some((arg) => arg === "--port" || arg.startsWith("--port="));
}
function printSelectionFailure(code: string, message: string, json: boolean): void {
if (json) {
console.log(JSON.stringify({ ok: false, error: { code, message } }, null, 2));
} else {
clack.log.error(message);
}
setCommandExitCode(1);
}
function previewServerPayload(server: {
port: number;
host?: string;
projectName: string;
projectDir: string;
}): {
port: number;
projectName: string;
projectDir: string;
url: string;
} {
return {
port: server.port,
projectName: server.projectName,
projectDir: server.projectDir,
url: previewBaseUrl(server.port, server.host),
};
}
function parseContextFields(value: string | undefined): ContextField[] {
if (value === undefined) return DEFAULT_CONTEXT_FIELDS;
if (!value.trim()) throw new Error("--context-fields cannot be empty");
const allowed = new Set<ContextField>(DEFAULT_CONTEXT_FIELDS);
const fields = value
.split(",")
.map((field) => field.trim())
.filter(Boolean);
const invalid = fields.filter((field) => !allowed.has(field as ContextField));
if (invalid.length > 0) {
throw new Error(
`Unknown context field${invalid.length === 1 ? "" : "s"}: ${invalid.join(", ")}`,
);
}
return [...new Set(fields)] as ContextField[];
}
function contextIncludes(fields: ContextField[], field: ContextField): boolean {
return fields.includes(field);
}
function addContextError(
payload: Record<string, unknown>,
field: ContextField,
error: { code: string; message: string },
): void {
payload.errors = {
...((payload.errors as Record<string, unknown> | undefined) ?? {}),
[field]: error,
};
}
async function printCurrentSelection(
projectDir: string,
startPort: number,
json: boolean,
preferredPort?: number,
): Promise<void> {
const {
AmbiguousPreviewServerError,
PreviewServerPortMismatchError,
fetchStudioSelection,
findPreviewServerForProject,
} = await import("../utils/studioSelectionClient.js");
let server: Awaited<ReturnType<typeof findPreviewServerForProject>>;
try {
server = await findPreviewServerForProject(
projectDir,
startPort,
undefined,
undefined,
preferredPort === undefined ? undefined : { preferredPort },
);
} catch (err) {
if (err instanceof AmbiguousPreviewServerError) {
printSelectionFailure("ambiguous-preview-server", err.message, json);
return;
}
if (err instanceof PreviewServerPortMismatchError) {
printSelectionFailure(PREVIEW_PORT_MISMATCH_CODE, err.message, json);
return;
}
throw err;
}
if (!server) {
printSelectionFailure(
"preview-not-running",
"No running Studio preview found for this project. Start one with: npx hyperframes preview",
json,
);
return;
}
let response: Awaited<ReturnType<typeof fetchStudioSelection>>;
try {
response = await fetchStudioSelection(server);
} catch (err) {
printSelectionFailure("selection-unavailable", errorMessage(err), json);
return;
}
if (!response.selection) {
printSelectionFailure(
"no-selection",
"Studio is running, but no element is selected. Select an element in Studio and rerun this command.",
json,
);
return;
}
const selection = {
...response.selection,
thumbnailUrl: absolutePreviewUrl(server.port, response.selection.thumbnailUrl, server.host),
};
if (json) {
console.log(
JSON.stringify(
{
ok: true,
server: previewServerPayload(server),
selection,
updatedAt: response.updatedAt,
},
null,
2,
),
);
return;
}
console.log(`${c.success("◇")} ${c.accent(selection.label)} selected in Studio`);
console.log(` ${c.dim("Source")} ${selection.sourceFile}`);
console.log(
` ${c.dim("Target")} ${selection.target.hfId ?? selection.target.id ?? selection.target.selector ?? "(none)"}`,
);
console.log(` ${c.dim("Time")} ${selection.currentTime.toFixed(3)}s`);
console.log(` ${c.dim("Thumbnail")} ${selection.thumbnailUrl}`);
console.log();
console.log(c.dim("Use --json for the full agent-readable selection payload."));
}
function countLintFindings(findings: Array<{ severity: string }>): {
errors: number;
warnings: number;
} {
return {
errors: findings.filter((finding) => finding.severity === "error").length,
warnings: findings.filter((finding) => finding.severity === "warning").length,
};
}
async function printCurrentContext(
projectDir: string,
startPort: number,
options: {
json: boolean;
fields?: string;
detail?: string;
preferredPort?: number;
},
): Promise<void> {
let fields: ContextField[];
try {
fields = parseContextFields(options.fields);
} catch (err) {
printSelectionFailure("invalid-context-fields", errorMessage(err), options.json);
return;
}
const fullDetail = options.detail === "full";
if (options.detail !== undefined && !["compact", "full"].includes(options.detail)) {
printSelectionFailure(
"invalid-context-detail",
"--context-detail must be compact or full",
options.json,
);
return;
}
const {
AmbiguousPreviewServerError,
PreviewServerPortMismatchError,
fetchStudioLint,
fetchStudioSelection,
findPreviewServerForProject,
} = await import("../utils/studioSelectionClient.js");
let server: Awaited<ReturnType<typeof findPreviewServerForProject>>;
try {
server = await findPreviewServerForProject(
projectDir,
startPort,
undefined,
undefined,
options.preferredPort === undefined ? undefined : { preferredPort: options.preferredPort },
);
} catch (err) {
if (err instanceof AmbiguousPreviewServerError) {
printSelectionFailure("ambiguous-preview-server", err.message, options.json);
return;
}
if (err instanceof PreviewServerPortMismatchError) {
printSelectionFailure(PREVIEW_PORT_MISMATCH_CODE, err.message, options.json);
return;
}
throw err;
}
if (!server) {
printSelectionFailure(
"preview-not-running",
"No running Studio preview found for this project. Start one with: npx hyperframes preview",
options.json,
);
return;
}
const wantsSelection = contextIncludes(fields, "selection");
const wantsLint = contextIncludes(fields, "lint");
const [selectionResult, lintResult] = await Promise.allSettled([
wantsSelection ? fetchStudioSelection(server) : Promise.resolve(null),
wantsLint ? fetchStudioLint(server) : Promise.resolve(null),
]);
const selection =
selectionResult.status === "fulfilled" && selectionResult.value?.selection
? {
ok: true as const,
value: fullDetail
? {
...selectionResult.value.selection,
thumbnailUrl: absolutePreviewUrl(
server.port,
selectionResult.value.selection.thumbnailUrl,
),
}
: compactSelectionPayload({
...selectionResult.value.selection,
thumbnailUrl: absolutePreviewUrl(
server.port,
selectionResult.value.selection.thumbnailUrl,
),
}),
updatedAt: selectionResult.value.updatedAt,
}
: {
ok: false as const,
error:
selectionResult.status === "rejected"
? {
code: "selection-unavailable",
message: errorMessage(selectionResult.reason),
}
: {
code: "no-selection",
message: "Studio is running, but no element is selected.",
},
};
const lint =
lintResult.status === "fulfilled" && lintResult.value
? {
ok: true as const,
summary: countLintFindings(lintResult.value.findings),
findings: lintResult.value.findings,
}
: {
ok: false as const,
error:
lintResult.status === "rejected"
? {
code: "lint-unavailable",
message: errorMessage(lintResult.reason),
}
: {
code: "lint-not-requested",
message: "Lint was not requested.",
},
};
const payload: Record<string, unknown> = { ok: true };
if (contextIncludes(fields, "server")) payload.server = previewServerPayload(server);
if (contextIncludes(fields, "selection")) {
payload.selection = selection.ok ? selection.value : null;
payload.selectionUpdatedAt = selection.ok ? selection.updatedAt : null;
if (!selection.ok) addContextError(payload, "selection", selection.error);
}
if (contextIncludes(fields, "lint")) payload.lint = lint;
if (contextIncludes(fields, "capabilities")) {
payload.capabilities = {
selection: true,
lint: true,
frame: false,
visibleElements: false,
lastAction: false,
};
}
if (options.json) {
console.log(JSON.stringify(payload, null, 2));
return;
}
console.log(`${c.success("◇")} Studio context`);
if (contextIncludes(fields, "server")) {
console.log(` ${c.dim("Project")} ${server.projectName}`);
console.log(` ${c.dim("Studio")} ${previewBaseUrl(server.port, server.host)}`);
}
if (contextIncludes(fields, "selection")) {
if (selection.ok) {
console.log(` ${c.dim("Selection")} ${selection.value.label}`);
} else {
console.log(` ${c.dim("Selection")} ${selection.error.message}`);
}
}
if (contextIncludes(fields, "lint")) {
if (lint.ok) {
console.log(
` ${c.dim("Lint")} ${lint.summary.errors} error(s), ${lint.summary.warnings} warning(s)`,
);
} else {
console.log(` ${c.dim("Lint")} ${lint.error.message}`);
}
}
console.log();
console.log(c.dim("Use --json for the full agent-readable context payload."));
}
function compactSelectionPayload(selection: StudioSelectionSnapshot): CompactSelectionPayload {
return {
schemaVersion: selection.schemaVersion,
projectId: selection.projectId,
compositionPath: selection.compositionPath,
sourceFile: selection.sourceFile,
currentTime: selection.currentTime,
target: selection.target,
label: selection.label,
tagName: selection.tagName,
boundingBox: selection.boundingBox,
textContent: selection.textContent,
thumbnailUrl: selection.thumbnailUrl,
};
}
// The full Studio URL to open or hand to the user. `url` never carries a
// trailing slash (both the embedded server and the Vite `Local:` match strip it).
export function studioDeepLink(url: string, projectName: string): string {
return `${url}/#project/${encodeURIComponent(projectName)}`;
}
export function studioSummaryUrls(
projectName: string,
serverUrl: string,
): { serverUrl: string; studioUrl: string } {
return {
serverUrl,
studioUrl: studioDeepLink(serverUrl, projectName),
};
}
/** Builds the preview while the browser starts; a failed build is retried by the player's own request. */
export function prebuildPreview(
fetchApp: (request: Request) => Response | Promise<Response>,
serverUrl: string,
projectName: string,
): Promise<unknown> {
const previewUrl = `${serverUrl}/api/projects/${encodeURIComponent(projectName)}/preview`;
return Promise.resolve()
.then(() => fetchApp(new Request(previewUrl)))
.catch(() => undefined);
}
export function foregroundPreviewReadyPayload(
projectName: string,
serverUrl: string,
projectDir: string,
pid: number | null,
): PreviewLifecyclePayload {
const port = Number(new URL(serverUrl).port);
return lifecyclePayload(
"start",
previewLifecycleSession({
state: "started",
mode: "foreground",
projectName,
projectDir,
port,
pid,
}),
);
}
function previewLifecycleSession(options: {
state: PreviewLifecycleSession["state"];
mode: PreviewLifecycleSession["mode"];
projectName: string;
projectDir: string;
port: number;
pid: number | null;
host?: string;
logPath?: string;
}): PreviewLifecycleSession {
const host = options.host ?? "127.0.0.1";
const serverUrl = previewBaseUrl(options.port, host);
return {
state: options.state,
mode: options.mode,
projectName: options.projectName,
projectDir: options.projectDir,
host,
port: options.port,
pid: options.pid,
serverUrl,
studioUrl: studioDeepLink(serverUrl, options.projectName),
ready: true,
...(options.logPath ? { logPath: options.logPath } : {}),
};
}
function openStudioBrowser(url: string, projectName: string, options?: BrowserLaunchOptions): void {
if (options?.noOpen) return;
openBrowser(studioDeepLink(url, projectName), {
browserPath: options?.browserPath,
userDataDir: options?.userDataDir,
remoteDebuggingPort: options?.remoteDebuggingPort,
disableGpu: options?.browserNoGpu,
});
}
function printStudioSummary(
projectName: string,
serverUrl: string,
projectDir: string,
opts: { details?: string[]; footer?: string } = {},
): void {
const urls = studioSummaryUrls(projectName, serverUrl);
console.log();
console.log(` ${c.dim("Project")} ${c.accent(projectName)}`);
console.log(` ${c.dim("Studio")} ${c.accent(urls.studioUrl)}`);
console.log(` ${c.dim("Server")} ${c.accent(urls.serverUrl)}`);
const hint = desktopHint(projectDir);
if (hint) console.log(` ${c.dim("Desktop")} ${hint}`);
console.log();
for (const detail of opts.details ?? []) {
console.log(` ${c.dim(detail)}`);
}
if (opts.details?.length && opts.footer) console.log();
if (opts.footer) console.log(` ${c.dim(opts.footer)}`);
console.log();
}
function linkProjectIntoStudioData(
dir: string,
projectsDir: string,
projectName: string,
): { symlinkPath: string; createdSymlink: boolean } {
const symlinkPath = join(projectsDir, projectName);
mkdirSync(projectsDir, { recursive: true });
let createdSymlink = false;
if (dir !== symlinkPath) {
if (existsSync(symlinkPath)) {
try {
const stat = lstatSync(symlinkPath);
if (stat.isSymbolicLink() && resolve(readlinkSync(symlinkPath)) !== resolve(dir)) {
unlinkSync(symlinkPath);
}
} catch {
// Real directories or unreadable paths are left untouched.
}
}
if (!existsSync(symlinkPath)) {
// Windows: "dir" symlinks need Developer Mode or elevation (EPERM otherwise);
// NTFS junctions are unprivileged and keep the live write-back the studio needs.
symlinkSync(dir, symlinkPath, process.platform === "win32" ? "junction" : "dir");
createdSymlink = true;
}
}
return { symlinkPath, createdSymlink };
}
function removeSymlinkOnExit(createdSymlink: boolean, symlinkPath: string): void {
if (!createdSymlink) return;
process.on("exit", () => {
try {
if (existsSync(symlinkPath)) unlinkSync(symlinkPath);
} catch {
/* ignore */
}
});
}
export function waitForStudioChildClose(
child: StudioChildProcess,
signalTarget: StudioSignalTarget = process,
): Promise<void> {
const shutdown = (): void => {
if (child.pid) killProcessTree(child.pid);
};
for (const signal of STUDIO_CHILD_SHUTDOWN_SIGNALS) signalTarget.once(signal, shutdown);
// A short-lived Vite child can exit before launch setup reaches this point.
// ChildProcess does not replay lifecycle events to listeners attached later,
// so waiting unconditionally would strand the preview wrapper forever.
const closed =
child.exitCode !== null || child.signalCode !== null
? Promise.resolve()
: new Promise<void>((resolveClose) => {
// `close` waits for stdio to close too. A Vite descendant can inherit
// those pipes, so the wrapper must key its lifetime to process exit.
child.once("exit", () => resolveClose());
});
return closed.finally(() => {
// Signal listeners keep Bun's event loop alive even after Vite exits. Leaving
// them registered makes `preview --stop` close the port but leak the wrapper.
for (const signal of STUDIO_CHILD_SHUTDOWN_SIGNALS) signalTarget.off(signal, shutdown);
});
}
function attachStudioReadyHandler(
child: StudioChildProcess,
spinner: ReturnType<typeof clack.spinner>,
projectName: string,
projectDir: string,
options?: StudioLaunchOptions,
): void {
let detected = false;
async function handleOutput(data: Buffer): Promise<void> {
const url = studioReadyUrl(data.toString());
if (!url || detected) return;
detected = true;
if (options?.json) {
const port = Number(new URL(url).port);
const server = await activeServerOnPort(port);
writeLifecycleJson(
foregroundPreviewReadyPayload(
projectName,
url,
projectDir,
publicPreviewPid(server?.pid, child.pid ?? null),
),
);
} else {
spinner.stop(c.success("Studio running"));
printStudioSummary(projectName, url, projectDir, {
footer: "Press Ctrl+C to stop",
});
}
openStudioBrowser(url, projectName, options);
child.stdout.removeListener("data", handleOutput);
child.stderr.removeListener("data", handleOutput);
}
child.stdout.on("data", (data) => void handleOutput(data));
child.stderr.on("data", (data) => void handleOutput(data));
child.on("error", (err) => {
if (options?.json) {
reportPreviewFailure(true, "start", "preview-start-failed", err.message);
} else {
spinner.stop(c.error("Failed to start studio"));
console.error(c.dim(err.message));
}
});
}
export function studioReadyUrl(output: string): string | null {
const localLine = output.split(/\r?\n/).find((line) => line.includes("Local:"));
return localLine?.match(/https?:\/\/(?:localhost|127\.0\.0\.1|\[::1\]):\d+/)?.[0] ?? null;
}
export function reportPreviewShutdown(json: boolean): void {
if (json) return;
console.log();
console.log(` ${c.dim("Shutting down studio...")}`);
}
/**
* Dev mode: spawn the studio dev server from the monorepo.
*/
export async function runDevMode(dir: string, options?: StudioLaunchOptions): Promise<void> {
// Find monorepo root by navigating from packages/cli/src/commands/
const thisFile = fileURLToPath(import.meta.url);
const repoRoot = resolve(dirname(thisFile), "..", "..", "..", "..");
// Symlink project into the studio's data directory
const projectsDir = join(repoRoot, "packages", "studio", "data", "projects");
const pName = options?.projectName ?? basename(dir);
const { symlinkPath, createdSymlink } = linkProjectIntoStudioData(dir, projectsDir, pName);
if (!options?.json) clack.intro(c.bold("hyperframes preview"));
const s = clack.spinner();
if (!options?.json) s.start("Starting studio...");
// Run the new consolidated studio (single Vite dev server with API plugin)
const studioPkgDir = join(repoRoot, "packages", "studio");
const child = spawn("bun", ["run", "dev", "--", ...previewViteArgs(options?.port)], {
cwd: studioPkgDir,
stdio: ["ignore", "pipe", "pipe"],
windowsHide: true,
env: studioProxyEnv(options?.autoProxy ?? true, process.env, {
projectDir: dir,
projectName: pName,
browserGpuMode: options?.browserGpuMode,
}),
});
attachStudioReadyHandler(child, s, pName, dir, options);
removeSymlinkOnExit(createdSymlink, symlinkPath);
// Kill the child's entire process tree on SIGTERM/SIGINT. Ctrl+C sends
// SIGINT to the foreground process group (covers the common case), but
// `kill <pid>` only targets this process — the child tree (Vite + Chrome)
// would survive without explicit cleanup.
// On Windows, killProcessTree delegates to taskkill /T so descendants are
// reaped even when the console signal reaches only this wrapper — and it
// always forces, so there is no grace period there, unlike the POSIX path.
return waitForStudioChildClose(child);
}
/**
* Whether the project's local @hyperframes/studio can actually be SERVED.
*
* Local mode runs `vite` with the studio package as its cwd, so it needs that
* package's own `vite.config.ts` — which the published tarball does not carry
* (`files: ["src", "dist"]`). Resolving the package alone therefore is not
* enough: an npm-installed studio would send `preview` down a path that can
* never come up, and since `--background` re-execs this same CLI, it would time
* out after ten seconds instead of falling back. Fall back to embedded mode,
* which serves the same studio and does work from a published install.
*/
function hasLocalStudio(dir: string): boolean {
try {
const req = createRequire(join(dir, "package.json"));
const studioPkgPath = dirname(req.resolve("@hyperframes/studio/package.json"));
return existsSync(join(studioPkgPath, "vite.config.ts"));
} catch {
return false;
}
}
/**
* Local studio mode: spawn Vite using a locally installed @hyperframes/studio.
* Provides full Vite HMR and the complete studio experience.
*/
export async function runLocalStudioMode(
dir: string,
options?: StudioLaunchOptions,
): Promise<void> {
const req = createRequire(join(dir, "package.json"));
const studioPkgPath = dirname(req.resolve("@hyperframes/studio/package.json"));
const pName = options?.projectName ?? basename(dir);
// Symlink project into studio's data directory
const projectsDir = join(studioPkgPath, "data", "projects");
const { symlinkPath, createdSymlink } = linkProjectIntoStudioData(dir, projectsDir, pName);
if (!options?.json) clack.intro(c.bold("hyperframes preview") + c.dim(" (local studio)"));
const s = clack.spinner();
if (!options?.json) s.start("Starting studio...");
const viteCommand = buildNpxCommand(["vite", ...previewViteArgs(options?.port)]);
const child = spawn(viteCommand.command, viteCommand.args, {
cwd: studioPkgPath,
stdio: ["ignore", "pipe", "pipe"],
windowsHide: true,
env: studioProxyEnv(options?.autoProxy ?? true, process.env, {
projectDir: dir,
projectName: pName,
browserGpuMode: options?.browserGpuMode,
}),
});
attachStudioReadyHandler(child, s, pName, dir, options);
removeSymlinkOnExit(createdSymlink, symlinkPath);
// Same cross-platform tree-kill handler as dev mode.
return waitForStudioChildClose(child);
}
/**
* Embedded mode: serve the pre-built studio SPA with a standalone Hono server.
* Works without any additional dependencies — the studio is bundled in dist/.
*
* If an existing HyperFrames server for the same project is detected,
* reuses it instead of starting a new one (unless --force-new is set).
*/
export async function runEmbeddedMode(
dir: string,
startPort: number,
options?: EmbeddedStudioOptions,
): Promise<void> {
const { createStudioServer, loadPreviewServerBuildSignature, resolveStudioBundle } =
await import("../server/studioServer.js");
const pName = options?.projectName ?? basename(dir);
const studioBundle = resolveStudioBundle();
if (!options?.json) clack.intro(c.bold("hyperframes preview"));
const s = clack.spinner();
if (!options?.json) s.start("Starting studio...");
if (!studioBundle.available) {
if (options?.json) {
reportPreviewFailure(true, "start", "preview-start-failed", "Studio build missing");
} else {
s.stop(c.error("Studio build missing"));
console.error();
console.error(` ${c.dim("Could not find")} ${c.accent("index.html")} ${c.dim("in:")}`);
for (const checkedPath of studioBundle.checkedPaths) {
console.error(` ${c.dim("-")} ${checkedPath}`);
}
console.error();
console.error(` ${c.dim("Rebuild the CLI package with")} ${c.accent("bun run build")}`);
console.error();
}
setCommandExitCode(1);
return;
}
// Compute everything that may throw before acquiring the fs.watch handle.
// Once createStudioServer returns, every subsequent exit path must close it.
const serverBuildSignature = await loadPreviewServerBuildSignature();
let listening: string | undefined;
const {
app,
watcher,
shutdown: shutdownStudio,
} = createStudioServer({
projectDir: dir,
projectName: pName,
autoProxy: options?.autoProxy,
browserGpuMode: options?.browserGpuMode,
origin: () => listening,
});
let result: FindPortResult;
try {
result = await findPortAndServe(
app.fetch,
startPort,
dir,
!!options?.forceNew,
serverBuildSignature,
undefined,
options?.browserGpuMode,
);
} catch (err: unknown) {
watcher.close();
if (!options?.json) s.stop(c.error("Could not start studio"));
reportPreviewFailure(
Boolean(options?.json),
"start",
"preview-start-failed",
(err as Error).message,
);
return;
}
if (result.type === "already-running") {
// createStudioServer acquires an fs.watch handle before port discovery.
// Reuse owns no local server, so release that handle before returning or
// the otherwise-finished CLI process remains alive indefinitely.
watcher.close();
const url = `http://localhost:${result.port}`;
if (options?.json) {
const server = await activeServerOnPort(result.port);
writeLifecycleJson(
lifecyclePayload(
"start",
previewLifecycleSession({
state: "reused",
mode: "foreground",
projectName: pName,
projectDir: dir,
port: result.port,
pid: publicPreviewPid(server?.pid, null),
}),
),
);
} else {
s.stop(c.success("Already running"));
printStudioSummary(pName, url, dir, {
details: ["Reusing existing server. Use --force-new to start a fresh instance."],
});
}
openStudioBrowser(url, pName, options);
return;
}
const url = `http://localhost:${result.port}`;
listening = `http://127.0.0.1:${result.port}`;
if (options?.json) {
writeLifecycleJson(foregroundPreviewReadyPayload(pName, url, dir, process.pid));
} else {
s.stop(c.success("Studio running"));
console.log();
if (result.port !== startPort) {
console.log(` ${c.warn(`Port ${startPort} is in use, using ${result.port} instead`)}`);
console.log();
}
printStudioSummary(pName, url, dir, {
details: [
"Edit with your AI agent — it has HyperFrames skills installed.",
"Changes reload automatically in the studio.",
],
footer: "Press Ctrl+C to stop",
});
}
openStudioBrowser(url, pName, options);
void prebuildPreview(app.fetch, url, pName);
// Block until Ctrl+C. Node would normally exit on SIGINT, but the listening
// HTTP server keeps handles open, so the event loop stays alive after the
// signal handler fires. Close the server explicitly and resolve the promise
// so `run()` returns cleanly instead of requiring a second Ctrl+C (or,
// worse, the user force-killing the terminal).
//
// Windows wrinkle: Ctrl+C in some terminals (Git Bash / MSYS) doesn't reach
// Node as a SIGINT at all — the process just sits there. Run a readline
// interface on stdin so the keystroke is observed at the TTY layer and
// re-emit it as SIGINT. No-op on platforms where the signal already arrives.
let rl: import("node:readline").Interface | undefined;
if (process.platform === "win32") {
const readline = await import("node:readline");
rl = readline.createInterface({
input: process.stdin,
output: process.stdout,
});
rl.on("SIGINT", () => {
process.emit("SIGINT", "SIGINT");
});
}
return new Promise<void>((resolveRun) => {
let shuttingDown = false;
const shutdown = (): void => {
if (shuttingDown) return;
shuttingDown = true;
rl?.close();
reportPreviewShutdown(Boolean(options?.json));
// Hard deadline: if cleanup hangs (e.g. dead Chrome never responds to
// browser.close()), force exit. Armed before awaiting cleanup so it
// can't be blocked by a stuck drainBrowserPool().
setTimeout(() => requestCliExit(0), 3000).unref();
shutdownStudio()
.catch(() => {})
.finally(() => {
watcher.close();
result.server.close(() => resolveRun());
});
};
// `on`, not `once`: a repeat Ctrl+C/SIGTERM while shutdown is running must
// stay caught and no-op via `shuttingDown`, not fall through to the OS
// default once a one-shot listener has self-removed after the first signal.
process.on("SIGINT", shutdown);
process.on("SIGTERM", shutdown);
// Last-resort cleanup for crash paths (unhandled exceptions/rejections)
// that bypass the signal handlers. Eagerly resolve the sync killer so
// the 'exit' handler (which is synchronous) can call it directly.
import("@hyperframes/engine")
.then(({ killTrackedProcesses }) => {
process.once("exit", () => {
if (!shuttingDown) killTrackedProcesses();
});
})
.catch(() => {});
});
}