import { spawn, spawnSync, type ChildProcess } from "node:child_process"; import { createHash } from "node:crypto"; import { existsSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statfsSync, statSync, unlinkSync, writeFileSync, } from "node:fs"; import { cpus, getPriority, tmpdir } from "node:os"; import { basename, dirname, join, parse, resolve } from "node:path"; import { BUSY_PC_PERCENT, cpuBusyPercent, readinessTimeoutLine, retrySettleMs, shouldRetryCapture, type CpuSample } from "./capture-retry"; import { clearViteCaches, headRevision, revisionDrifted, shortRevision } from "./captureRevision"; import { brokerServer } from "./devBrokerClient"; import { checkMarkedServer, checkoutIdentity, devServerIdentity, isUp, listMarkers, markerPath, readMarker, readServerIdentity, writeMarker } from "./devServerMarker"; import { currentStep, describeHang, markStep, pausableDeadline, pausedTotal } from "./hangReport"; import { localGet } from "./localhostHttp"; import { currentPriority, lowerToBelowNormal, type PriorityLabel, priorityLabel, restoreNormalPriority } from "./machine-priority"; import { startOutsideCaller } from "./outsideCaller"; import { computeShotMetrics, deadViewport } from "./shot-metrics"; import { removeDirSync } from "./removeDir"; import { decodePng } from "../packages/assets/src/imageCodec"; import type { GraphicsTier } from "../packages/jgengine/src/templates/captureArgs"; import { detail } from "./verbosity"; import { takeRenderSlot } from "./renderSlots"; export { checkoutIdentity, devServerIdentity, isUp }; /** * Default port when no worktree key is needed — kept for docs/bench that still * want a predictable single-session port. Prefer {@link resolveDevPort}. */ export const DEV_PORT = 4517; /** @deprecated Prefer {@link resolveDevBase} — fixed URL collides across worktrees. */ export const DEV_BASE = `http://127.0.0.1:${DEV_PORT}`; /** * Default warm Chrome debug port. Prefer {@link resolveWarmChromePort} so * parallel worktrees do not share one CDP endpoint. */ export const WARM_CHROME_PORT = 9223; export type Device = "desktop" | "mobile" | "mobile-landscape"; export type DeviceProfile = { width: number; height: number; deviceScaleFactor: number; mobile: boolean }; export type SizeMode = "full" | "half"; export const DEVICES: Record = { desktop: { width: 1600, height: 900, deviceScaleFactor: 1, mobile: false }, mobile: { width: 390, height: 844, deviceScaleFactor: 2, mobile: true }, "mobile-landscape": { width: 844, height: 390, deviceScaleFactor: 2, mobile: true }, }; export const MOBILE_UA = "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1"; /** * Half-res mid-loop judge shots run ~1/4 the pixels of a full-res shot — cheaper to encode and * cheaper for a vision model to read back. The page keeps its full CSS viewport and only the device * pixel ratio halves, so the game lays out exactly as at full size: a smaller viewport would switch * the HUD into its compact layout and judge a screen the player never sees at that size. * Full-res stays the default for final/PR evidence. */ export function scaleProfile(profile: DeviceProfile, size: SizeMode): DeviceProfile { if (size === "full") return profile; return { ...profile, deviceScaleFactor: profile.deviceScaleFactor / 2 }; } /** Viewport overrides (`--width`/`--height`) in CSS pixels, kept as-is by `--size half`, which halves only the pixel ratio. */ export interface ViewportOverride { width?: number | undefined; height?: number | undefined; } /** The device profile a capture actually uses: device defaults, explicit overrides, then size. */ export function captureProfile(device: Device, size: SizeMode = "full", override: ViewportOverride = {}): DeviceProfile { const base = DEVICES[device]; return scaleProfile({ ...base, width: override.width ?? base.width, height: override.height ?? base.height }, size); } export async function applyDevice(session: CdpSession, device: Device, size: SizeMode = "full", override: ViewportOverride = {}): Promise { const profile = captureProfile(device, size, override); await session.send("Emulation.setDeviceMetricsOverride", { width: profile.width, height: profile.height, deviceScaleFactor: profile.deviceScaleFactor, mobile: profile.mobile, }); if (profile.mobile) { await session.send("Emulation.setTouchEmulationEnabled", { enabled: true, maxTouchPoints: 5 }); await session.send("Emulation.setUserAgentOverride", { userAgent: MOBILE_UA }); } else { await session.send("Emulation.setTouchEmulationEnabled", { enabled: false }); } } export function findChromeExecutable(): string { for (const candidate of [ process.env["CHROME_PATH"], process.env["JG_CHROME"], "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe", "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe", "C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe", "C:\\Program Files\\Microsoft\\Edge\\Application\\msedge.exe", "/usr/bin/google-chrome", "/usr/bin/google-chrome-stable", "/usr/bin/chromium", "/usr/bin/chromium-browser", "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome", "/Applications/Chromium.app/Contents/MacOS/Chromium", ]) { if (candidate !== undefined && existsSync(candidate)) return candidate; } const root = process.env["PLAYWRIGHT_BROWSERS_PATH"] ?? "/opt/pw-browsers"; if (existsSync(root)) { const direct = join(root, "chromium"); if (existsSync(direct) && statSync(direct).isFile()) return direct; for (const entry of readdirSync(root)) { if (!entry.startsWith("chromium")) continue; for (const candidate of [ join(root, entry, "chrome-linux", "chrome"), join(root, entry, "chrome-linux", "headless_shell"), ]) { if (existsSync(candidate)) return candidate; } } } throw new Error("No Chrome/Chromium found. Set CHROME_PATH or install Chrome."); } /** Build browser fixtures outside the test runner's module mocks and resolver cache. */ export function buildBrowserFixture(entry: string): string { const build = spawnSync(process.execPath, [join(import.meta.dir, "build-browser-fixture.ts"), entry], { encoding: "utf8", timeout: 25_000, maxBuffer: 16 * 1024 * 1024, }); if (build.error !== undefined) throw build.error; if (build.status !== 0) throw new Error(build.stderr.trim() || "Browser fixture build failed"); return build.stdout; } /** * A capture Chrome on the real GPU. WebGPU developer features keep GPU timestamps exact: Chrome * otherwise rounds them to 100 µs, which buries a 0.3 ms pass in rounding. */ const HARDWARE_GPU_ARGS = ["--ignore-gpu-blocklist", "--enable-webgpu-developer-features"]; /** * `performance.memory` reports the exact heap on every read instead of a bucketed, cached figure, * so the frame breakdown sees a collection in the frame it happened and its hitch reads "gc" * rather than "other". The desktop harness passes it to WebView2 too. */ export const PRECISE_HEAP_ARG = "--enable-precise-memory-info"; /** Native GPU locally; deterministic software GL only when explicitly requested or in CI. */ export function chromeGraphicsArgs( env: NodeJS.ProcessEnv = process.env, platform: NodeJS.Platform = process.platform, ): string[] { const software = env["JG_CAPTURE_SOFTWARE_GL"] === "1" || (env["JG_CAPTURE_SOFTWARE_GL"] !== "0" && (env["CI"] !== undefined || platform === "linux")); return software ? ["--use-angle=swiftshader", "--enable-unsafe-swiftshader", "--ignore-gpu-blocklist"] : [...HARDWARE_GPU_ARGS]; } /** Frame clock a capture browser runs requestAnimationFrame on. */ export type FrameClock = "capped" | "uncapped"; /** * Chrome flags that take rAF off the display's commit clock, so a sampled frame delta is what the * frame costs instead of the next 16.7 ms vsync tick. Empty for the default clock, which is what * every capture and the perf gate keep using: a player sees a vsynced frame, so only a run that * asks for the uncapped clock measures the headroom below it. * * The rate-limit and vsync flags alone leave rAF at 17.2 ms (measured on Chrome 143 here); the * compositor only stops waiting for the next vsync window once it also runs its stages before * drawing, which trades pipelining away for a frame delta that covers the whole frame. */ export function chromeFrameClockArgs(clock: FrameClock = "capped"): string[] { return clock === "uncapped" ? ["--disable-frame-rate-limit", "--disable-gpu-vsync", "--run-all-compositor-stages-before-draw"] : []; } /** Software rasterizer a capture Chrome renders WebGL with when no GPU is used. */ export type SoftwareGl = "llvmpipe" | "swiftshader"; /** * Which software rasterizer to use, or null for the native GPU. On Linux, Mesa llvmpipe (ANGLE on * desktop GL, through an Xvfb display) renders the same frames about 3-4x faster than SwiftShader * (measured on beacon-bastion: 2.4 s vs 9.0 s per frame at 1600x900; 0.85 s vs 2.8 s for a draft * shot). SwiftShader stays the fallback when Xvfb is missing, and `JG_CAPTURE_GL=swiftshader` * forces it. */ export function softwareGlBackend( env: NodeJS.ProcessEnv = process.env, platform: NodeJS.Platform = process.platform, hasXvfb: boolean = xvfbExecutable() !== null, ): SoftwareGl | null { if (!chromeGraphicsArgs(env, platform).includes("--use-angle=swiftshader")) return null; if (env["JG_CAPTURE_GL"] === "swiftshader") return "swiftshader"; return platform === "linux" && hasXvfb ? "llvmpipe" : "swiftshader"; } /** * Where a `--headed` capture window sits: far outside every monitor, so a real window can never * cover Jon's desktop. A headed run is a deliberate act for debugging, not a way to watch a shot. */ export const HEADED_WINDOW_POSITION = "-32000,-32000"; /** * Chrome flags for a rasterizer choice: llvmpipe runs headful on the Xvfb display, the rest headless. * `headed` asks for a real window, which lands off-screen — the default for every capture is headless. */ export function chromeRenderArgs(backend: SoftwareGl | null, headed = false): string[] { if (headed) { return ["--window-size=1280,720", `--window-position=${HEADED_WINDOW_POSITION}`, ...chromeGraphicsArgs()]; } if (backend === "llvmpipe") { return ["--ozone-platform=x11", "--use-angle=gl", "--ignore-gpu-blocklist", "--window-size=2560,2560"]; } return ["--headless=new", ...(backend === "swiftshader" ? chromeGraphicsArgs({ JG_CAPTURE_SOFTWARE_GL: "1" }) : [...HARDWARE_GPU_ARGS])]; } /** * Whether a capture opens a real window or runs headless. A headed request needs a display to * open on; a cloud container has none (and Chrome exits 1 without one), so it runs headless there * with `--no-sandbox` and the SwiftShader GL flags instead. */ export function chromeLaunchMode( headed: boolean, env: NodeJS.ProcessEnv = process.env, platform: NodeJS.Platform = process.platform, ): "headed" | "headless" { if (!headed) return "headless"; if (platform !== "linux") return "headed"; return (env["DISPLAY"] ?? "") !== "" || (env["WAYLAND_DISPLAY"] ?? "") !== "" ? "headed" : "headless"; } function xvfbExecutable(): string | null { for (const dir of (process.env["PATH"] ?? "/usr/bin").split(":")) { const candidate = join(dir, "Xvfb"); if (dir !== "" && existsSync(candidate)) return candidate; } return null; } /** * Start (or reuse) the shared capture X display and return its name, or null when it cannot run. * One display serves every capture on the machine; it costs a few MB idle, so it is left running. */ export function ensureXvfbDisplay(): string | null { const xvfb = xvfbExecutable(); if (xvfb === null) return null; const display = Number(process.env["JG_XVFB_DISPLAY"] ?? 93); const socket = `/tmp/.X11-unix/X${display}`; if (existsSync(socket)) return `:${display}`; const child = spawn(xvfb, [`:${display}`, "-screen", "0", "2560x2560x24", "-nolisten", "tcp"], { stdio: "ignore", detached: true, }); child.unref(); const deadline = Date.now() + 5_000; while (Date.now() < deadline) { if (existsSync(socket)) return `:${display}`; spawnSync("sleep", ["0.1"]); } return existsSync(socket) ? `:${display}` : null; } /** * Rewrite a `localhost` URL host to `127.0.0.1`. Node/Bun `fetch` (and the * capture allowlist) treat the two as distinct: `fetch` resolves `localhost` * to IPv6 `::1` first, so a dev server bound only to IPv4 `127.0.0.1` reads as * down even while it is serving, and the allowlist only accepts `127.0.0.1`. * Normalizing at the CLI entry point makes `--url http://localhost:…` behave * identically to `--url http://127.0.0.1:…`. Non-URL or non-localhost inputs * pass through untouched. */ export function normalizeLoopbackUrl(raw: string): string { try { const url = new URL(raw); if (url.hostname === "localhost") { url.hostname = "127.0.0.1"; return url.toString(); } } catch { /* not a parseable URL — leave it for downstream handling */ } return raw; } function hashPortOffset(identity: string, span: number): number { const digest = createHash("sha256").update(identity).digest(); return digest.readUInt32BE(0) % span; } /** * Per-checkout dev port so parallel worktrees do not share one Vite. * Override with `JG_DEV_PORT`. Range 4517–4999 (483 ports). */ export function resolveDevPort(cwd = process.cwd()): number { const override = process.env["JG_DEV_PORT"]; if (override !== undefined && override.length > 0) { const n = Number(override); if (Number.isFinite(n) && n > 0) return Math.floor(n); } return 4517 + hashPortOffset(devServerIdentity(cwd), 483); } export function resolveDevBase(cwd = process.cwd()): string { return `http://127.0.0.1:${resolveDevPort(cwd)}`; } /** Per-checkout website port used by managed `shoot --site` captures. */ export function resolveWebPort(cwd = process.cwd()): number { const override = process.env["JG_WEB_PORT"]; if (override !== undefined && override.length > 0) { const n = Number(override); if (Number.isFinite(n) && n > 0) return Math.floor(n); } // Stay clear of Chrome's blocked-port list (notably 5060/5061 SIP and 6000 X11). return 5517 + hashPortOffset(checkoutIdentity(cwd), 400); } export function resolveWebBase(cwd = process.cwd()): string { return `http://127.0.0.1:${resolveWebPort(cwd)}`; } /** * Per-checkout warm Chrome debug port (`--keep` / `--connect` loop). * Override with `JG_CHROME_PORT`. Range 9223–9322. */ export function resolveWarmChromePort(cwd = process.cwd()): number { const override = process.env["JG_CHROME_PORT"]; if (override !== undefined && override.length > 0) { const n = Number(override); if (Number.isFinite(n) && n > 0) return Math.floor(n); } return 9223 + hashPortOffset(checkoutIdentity(cwd), 100); } /** * True when the server on `port` itself reports `identity`. The marker only says where to look: * a stale marker over another checkout's Vite on a reused port used to read as ours. */ export async function isOurDevServer(port: number, identity: string): Promise { const marker = readMarker(port); if (marker === null) return false; return (await checkMarkedServer(marker, identity)).status === "ours"; } /** * Retire a warm server whose commit no longer matches the tree. Reusing it would * serve the previous commit's module graph — the "start menu still on screen" * / readiness-timeout failure that made every checkout-then-shoot loop flaky. * Killing it here means the caller's normal boot path starts a clean one. Only a * server that reports this checkout's identity is killed, by the pid it reports. */ export async function retireDriftedDevServer(port: number, cwd = process.cwd()): Promise { const marker = readMarker(port); if (marker === null) return false; const checked = await checkMarkedServer(marker, marker.identity); if (checked.status !== "ours" || checked.report.root !== checkoutIdentity(cwd)) return false; const servedHead = checked.report.head ?? marker.head; if (!revisionDrifted(servedHead, headRevision(cwd))) return false; killPid(checked.report.pid, true); const cleared = clearViteCaches(cwd); console.error( `capture: warm Vite on :${port} booted from ${shortRevision(servedHead)} but HEAD is ${shortRevision(headRevision(cwd))} — restarting it${cleared.length > 0 ? " and clearing the dep cache" : ""}`, ); for (let attempt = 0; attempt < 40; attempt += 1) { if (!(await isUp(checked.base))) return true; await new Promise((resolve) => setTimeout(resolve, 250)); } throw new Error( `capture: the Vite on :${port} from ${shortRevision(servedHead)} would not die — kill it by hand, then retry`, ); } /** * A live server this checkout already started on any port, current with HEAD. A * one-second `isUp` miss on a busy machine used to read as "port taken" and boot a * fresh server 17 ports along; twelve copies of one worktree's Vite piled up that way. * Each candidate must report this identity itself; drifted copies are retired and * markers the live server contradicts are deleted on the way. */ async function findOwnedServer(identity: string, kind: "runner" | "website", cwd: string): Promise { const head = headRevision(cwd); for (const marker of listMarkers()) { if (marker.identity !== identity || (marker.kind ?? "runner") !== kind) continue; const checked = await checkMarkedServer(marker, identity); if (checked.status !== "ours") continue; if (revisionDrifted(checked.report.head ?? marker.head, head)) { killPid(checked.report.pid, true); continue; } return marker.port; } return null; } /** * After a launch answers, confirm the server on the port is the one just started and record the pid * it reports (the launcher only knows the `bun run` wrapper's). Another checkout's Vite that won the * port race reports a different identity, and attaching to it would capture the wrong tree. */ async function confirmLaunchedServer( base: string, port: number, identity: string, kind: "runner" | "website", cwd: string, ): Promise<"ours" | "foreign" | "pending"> { const report = await readServerIdentity(base); if (report === null) return "pending"; if (report.identity !== identity) return "foreign"; const host = new URL(base).hostname; writeMarker({ identity, port, pid: report.pid, head: report.head ?? headRevision(cwd), kind, host }); return "ours"; } export interface EnsureDevServerResult { child: ChildProcess | null; /** PID only when this invocation launched and therefore owns the server. */ pid?: number; port: number; base: string; } /** A dev server that outlives this run, outside its process tree and Windows job (scripts/outsideCaller.ts). */ function launchPersistentCommand( file: string, args: readonly string[], cwd: string, env: Record, ): number { return startOutsideCaller(file, args, { cwd, env: { ...process.env, ...env } }); } /** * The machine broker's server for this checkout, or null when the broker is off, unreachable or the * caller pinned a port. A brokered server carries no pid: the broker owns it and stops it when idle, * so a run that ends (or is killed) never leaves it behind and never kills it under another run. */ async function serverFromBroker(cwd: string, kind: "runner" | "website", portEnv: string): Promise { const pinned = process.env[portEnv]; if (pinned !== undefined && pinned !== "") return null; const preferredPort = kind === "runner" ? resolveDevPort(cwd) : resolveWebPort(cwd); const server = await brokerServer(cwd, kind, preferredPort); return server === null ? null : { child: null, port: server.port, base: server.base }; } /** * Boot (or reuse) the apps/dev Vite server for **this** checkout only. * Port is derived from the worktree path; a live server on that port is * reused only when a marker file proves it belongs to this identity. */ const DEV_SERVER_BOOT_MS = 90_000; export async function ensureDevServer(cwd = process.cwd()): Promise { const brokered = await serverFromBroker(cwd, "runner", "JG_DEV_PORT"); if (brokered !== null) return brokered; const identity = devServerIdentity(cwd); let port = resolveDevPort(cwd); const base = `http://127.0.0.1:${port}`; await retireDriftedDevServer(port, cwd); if (await isOurDevServer(port, identity)) { return { child: null, port, base }; } const owned = await findOwnedServer(identity, "runner", cwd); if (owned !== null) return { child: null, port: owned, base: `http://127.0.0.1:${owned}` }; if (await isUp(base)) { // Something else owns this port — try a few offsets rather than attach wrong. for (let step = 1; step <= 20; step += 1) { const candidate = 4517 + ((port - 4517 + step * 17) % 483); if (await isOurDevServer(candidate, identity)) { return { child: null, port: candidate, base: `http://127.0.0.1:${candidate}` }; } if (!(await isUp(`http://127.0.0.1:${candidate}`))) { port = candidate; break; } } } const args = ["--cwd=apps/dev", "run", "dev", "--", "--host", "127.0.0.1", "--port", String(port), "--strictPort"]; // The child inherits this process, so the `--game-dir` env (`VITE_JG_GAME_DIR`) reaches Vite. const child = process.platform === "win32" ? null : spawn(process.execPath, args, { cwd, stdio: "ignore", detached: true, env: { ...process.env, JG_DEV_PORT: String(port) }, windowsHide: true, }); const pid = child?.pid ?? launchPersistentCommand(process.execPath, args, cwd, { JG_DEV_PORT: String(port) }); child?.unref(); writeMarker({ identity, port, pid, head: headRevision(cwd), kind: "runner" }); const finalBase = `http://127.0.0.1:${port}`; // 90 s: a cold boot with its dep cache cleared took past the old 30 s on a loaded PC, and the // drive failed before Vite answered. A Vite that exits early still fails at once, below. for (let attempt = 0; attempt < DEV_SERVER_BOOT_MS / 500; attempt += 1) { await new Promise((r) => setTimeout(r, 500)); if (await isUp(finalBase)) { const confirmed = await confirmLaunchedServer(finalBase, port, identity, "runner", cwd); if (confirmed === "ours") return { child, pid, port, base: finalBase }; if (confirmed === "foreign") { if (child !== null) child.kill(); else killPid(pid, true); throw new Error(`Dev server on :${port} answers for another checkout, not ${identity} — retry to pick a free port`); } } if (child?.exitCode !== null && child?.exitCode !== undefined) { throw new Error(`Dev server exited with code ${child.exitCode} before becoming reachable on :${port}`); } } if (child !== null) child.kill(); else killPid(pid, true); // The runner's Vite is apps/dev's own dependency; the root never had it, so checking only there // called every slow boot "vite is missing". const viteInstalled = existsSync(join(cwd, "apps", "dev", "node_modules", "vite")) || existsSync(join(cwd, "node_modules", ".bin", "vite")) || existsSync(join(cwd, "node_modules", "vite")); const hint = viteInstalled ? `the apps/dev Vite server never became reachable in ${DEV_SERVER_BOOT_MS / 1000} s — check for a port conflict or a Vite boot error` : "node_modules looks incomplete (vite is missing) — run `bun scripts/ensure-ready.ts` (or `bun install`) first"; throw new Error(`Dev server failed to start on :${port} for ${identity} — ${hint}`); } /** Boot or reuse this checkout's website Vite server for `shoot --site` captures. */ export async function ensureWebServer(cwd = process.cwd()): Promise { const brokered = await serverFromBroker(cwd, "website", "JG_WEB_PORT"); if (brokered !== null) return brokered; const identity = checkoutIdentity(cwd); let port = resolveWebPort(cwd); const base = `http://127.0.0.1:${port}`; await retireDriftedDevServer(port, cwd); if (await isOurDevServer(port, identity)) return { child: null, port, base }; const owned = await findOwnedServer(identity, "website", cwd); if (owned !== null) return { child: null, port: owned, base: `http://127.0.0.1:${owned}` }; if (await isUp(base)) { for (let step = 1; step <= 20; step += 1) { const candidate = 5517 + ((port - 5517 + step * 17) % 400); if (await isOurDevServer(candidate, identity)) { return { child: null, port: candidate, base: `http://127.0.0.1:${candidate}` }; } if (!(await isUp(`http://127.0.0.1:${candidate}`))) { port = candidate; break; } } } const args = ["--cwd=apps/web", "run", "dev", "--", "--host", "127.0.0.1", "--port", String(port), "--strictPort"]; const child = process.platform === "win32" ? null : spawn(process.execPath, args, { cwd, stdio: "ignore", detached: true, env: { ...process.env, JG_WEB_PORT: String(port), JG_CAPTURE_SITE: "1" }, windowsHide: true, }); const pid = child?.pid ?? launchPersistentCommand(process.execPath, args, cwd, { JG_WEB_PORT: String(port), JG_CAPTURE_SITE: "1", }); child?.unref(); writeMarker({ identity, port, pid, head: headRevision(cwd), kind: "website" }); const finalBase = `http://127.0.0.1:${port}`; for (let attempt = 0; attempt < 120; attempt += 1) { await new Promise((resolve) => setTimeout(resolve, 500)); if (await isUp(finalBase)) { const confirmed = await confirmLaunchedServer(finalBase, port, identity, "website", cwd); if (confirmed === "ours") return { child, pid, port, base: finalBase }; if (confirmed === "foreign") { if (child !== null) killProcessTree(child); else killPid(pid, true); throw new Error(`Website dev server on :${port} answers for another checkout, not ${identity} — retry to pick a free port`); } } if (child?.exitCode !== null && child?.exitCode !== undefined) { throw new Error(`Website dev server exited with code ${child.exitCode} before becoming reachable on :${port}`); } } if (child !== null) killProcessTree(child); else killPid(pid, true); throw new Error(`Website dev server failed to start on :${port} for ${identity}`); } /** * Force-kill a single pid across platforms. `tree` also reaps the process * group on posix (SIGKILL to `-pid`) before falling back to the bare pid — * used when we own a detached launcher whose children must die with it. */ /** * Kill `pid` (and its tree). True when it is gone or going; false when the kill was refused. On * Windows a process can be stuck past `taskkill` ("there is no running instance of the task", * exit 255) while `process.kill(pid, 0)` already calls it dead, so only this answer tells a caller * that its files stay locked. */ export function killPid(pid: number | undefined, tree = false): boolean { if (pid === undefined || !Number.isFinite(pid) || pid <= 0) return true; if (process.platform === "win32") { const status = spawnSync("taskkill", ["/pid", String(pid), "/T", "/F"], { stdio: "ignore", windowsHide: true, timeout: 15_000 }).status; // 128: no such process, already gone. return status === 0 || status === 128; } if (tree) { try { process.kill(-pid, "SIGKILL"); return true; } catch { /* group gone or ungrouped — fall through to the bare pid */ } } try { process.kill(pid, "SIGKILL"); return true; } catch (error) { return (error as NodeJS.ErrnoException).code === "ESRCH"; } } export function killProcessTree(child: ChildProcess | null): void { killPid(child?.pid, true); } /** Default wait for a launched browser to answer on its debugger endpoint. */ export const DEFAULT_CHROME_READY_MS = 30_000; /** * How long one launch attempt waits for the debugger endpoint: `JG_CHROME_READY_MS`, * else 30s. A cold CI runner spends most of that on the first browser start of the * day, and a busy runner overran the old hardcoded 30s (#2110). */ export function resolveChromeReadyMs(env: NodeJS.ProcessEnv = process.env): number { const configured = Number(env["JG_CHROME_READY_MS"]); return Number.isFinite(configured) && configured > 0 ? Math.floor(configured) : DEFAULT_CHROME_READY_MS; } /** Where a launch stopped: spawning, the debugger endpoint, or the first page target. */ export type BrowserLaunchStep = "launch" | "endpoint" | "page"; export interface BrowserLaunchFailure { step: BrowserLaunchStep; elapsedMs: number; profilePath: string | null; attempts: number; /** Wait the failing attempt was given, when the step waited at all. */ waitedMs?: number | undefined; reason: string; } /** A launch that failed, saying which step it reached, how long it took and which profile it was using. */ export class BrowserLaunchError extends Error { readonly step: BrowserLaunchStep; readonly elapsedMs: number; readonly profilePath: string | null; readonly attempts: number; /** The underlying failure, without this error's own step/elapsed/profile prefix. */ readonly reason: string; constructor(failure: BrowserLaunchFailure) { const profile = failure.profilePath === null ? "no profile" : `profile ${failure.profilePath}`; const attempts = `${failure.attempts} attempt${failure.attempts === 1 ? "" : "s"}`; const waited = failure.waitedMs === undefined ? "" : `, last wait ${failure.waitedMs}ms`; super(`browser: the ${failure.step} step failed after ${failure.elapsedMs}ms (${profile}, ${attempts}${waited}): ${failure.reason}`); this.name = "BrowserLaunchError"; this.step = failure.step; this.elapsedMs = failure.elapsedMs; this.profilePath = failure.profilePath; this.attempts = failure.attempts; this.reason = failure.reason; } } /** Profile of the browser this process launched on each debug port, for failure messages. */ const launchedProfiles = new Map(); /** Profile path behind a debug port this process launched, or null when attached. */ function profileForDebugPort(debugPort: number): string | null { return launchedProfiles.get(debugPort) ?? null; } export interface DebuggerWaitContext { /** The browser just launched, so a process that already died fails now instead of at the deadline. */ browser?: { pid?: number; exitCode?: number | null }; profilePath?: string; } /** Chrome answers `/json/version` with a JSON body; anything slower than this is still not a debugger. */ const DEBUGGER_PROBE_TIMEOUT_MS = 2_000; async function debuggerVersionUrl(port: number): Promise { try { const body = JSON.parse( await localGet(`http://127.0.0.1:${port}/json/version`, DEBUGGER_PROBE_TIMEOUT_MS), ) as { webSocketDebuggerUrl?: unknown }; return typeof body.webSocketDebuggerUrl === "string" ? body.webSocketDebuggerUrl : null; } catch { return null; } } /** * Wait until Chrome's debugger endpoint really answers — a listening socket that has * not finished booting HTTP is not ready, so each probe asks for a parsed `/json/version`. * Returns the elapsed wait. A browser that exited fails at once rather than after the * full deadline. */ export async function waitForDebugger( port: number, timeoutMs: number, context: DebuggerWaitContext = {}, ): Promise { const startedAt = Date.now(); const deadline = startedAt + timeoutMs; let pause = 100; while (Date.now() < deadline) { const exit = context.browser?.exitCode; if (typeof exit === "number") { throw new BrowserLaunchError({ step: "endpoint", elapsedMs: Date.now() - startedAt, profilePath: context.profilePath ?? null, attempts: 1, waitedMs: timeoutMs, reason: `the browser process exited (code ${exit}) before binding the debugger on :${port}`, }); } if ((await debuggerVersionUrl(port)) !== null) return Date.now() - startedAt; const remaining = deadline - Date.now(); if (remaining <= 0) break; await new Promise((resolve) => setTimeout(resolve, Math.min(pause, remaining))); pause = Math.min(250, Math.round(pause * 1.5)); } throw new BrowserLaunchError({ step: "endpoint", elapsedMs: Date.now() - startedAt, profilePath: context.profilePath ?? null, attempts: 1, waitedMs: timeoutMs, reason: `the debugger on :${port} did not answer /json/version within ${timeoutMs}ms`, }); } type CdpMessage = { id?: number; method?: string; params?: Record; result?: Record; error?: { message: string }; }; /** One field of a CDP answer, read without trusting its shape: `undefined` when it is not there. */ export function cdpField(value: unknown, key: string): unknown { return typeof value === "object" && value !== null && key in value ? Reflect.get(value, key) : undefined; } /** The `objectId` of a remote object in a CDP answer (`result` of `Runtime.evaluate`, `objects` of `Runtime.queryObjects`). */ export function remoteObjectId(remote: unknown): string | undefined { const id = cdpField(remote, "objectId"); return typeof id === "string" ? id : undefined; } export class CdpSession { private nextId = 0; private readonly pending = new Map< number, { resolve: (value: Record) => void; reject: (error: Error) => void } >(); private readonly ws: WebSocket; private readonly ownedTarget?: { debugPort: number; targetId: string } | undefined; private readonly eventHandlers = new Map) => void>>(); private constructor(ws: WebSocket, ownedTarget?: { debugPort: number; targetId: string }) { this.ws = ws; this.ownedTarget = ownedTarget; this.ws.addEventListener("message", (event) => { const data = typeof event.data === "string" ? event.data : undefined; if (data === undefined) return; let message: CdpMessage; try { message = JSON.parse(data) as CdpMessage; } catch { return; } if (message.id === undefined) { if (message.method !== undefined) { for (const handler of this.eventHandlers.get(message.method) ?? []) { handler(message.params ?? {}); } } return; } const waiter = this.pending.get(message.id); if (waiter === undefined) return; this.pending.delete(message.id); if (message.error !== undefined) waiter.reject(new Error(message.error.message)); else waiter.resolve(message.result ?? {}); }); } static connect( url: string, timeoutMs: number, ownedTarget?: { debugPort: number; targetId: string }, ): Promise { return new Promise((resolvePromise, reject) => { const ws = new WebSocket(url); const timer = setTimeout(() => { ws.close(); reject(new Error(`CDP WebSocket connect timeout: ${url}`)); }, timeoutMs); ws.addEventListener("open", () => { clearTimeout(timer); resolvePromise(new CdpSession(ws, ownedTarget)); }); ws.addEventListener("error", () => { clearTimeout(timer); reject(new Error(`CDP WebSocket error: ${url}`)); }); }); } /** Subscribe to a CDP event and return an unsubscribe callback. */ on(method: string, handler: (params: Record) => void): () => void { const handlers = this.eventHandlers.get(method) ?? []; handlers.push(handler); this.eventHandlers.set(method, handlers); return () => { const current = this.eventHandlers.get(method); if (current === undefined) return; const index = current.indexOf(handler); if (index >= 0) current.splice(index, 1); if (current.length === 0) this.eventHandlers.delete(method); }; } send(method: string, params?: Record): Promise> { const id = ++this.nextId; return new Promise((resolvePromise, reject) => { this.pending.set(id, { resolve: resolvePromise, reject }); this.ws.send(JSON.stringify({ id, method, params })); }); } /** * Runtime.evaluate an expression with `returnByValue`, unwrapping * `result.result.value` to the caller's `T`. Returns `undefined` when the * page yields no value. Pass `awaitPromise` for async expressions. */ async evaluate(expression: string, opts: { awaitPromise?: boolean } = {}): Promise { const result = await this.send("Runtime.evaluate", { expression, returnByValue: true, ...(opts.awaitPromise === true ? { awaitPromise: true } : {}), }); return (result["result"] as { value?: T } | undefined)?.value; } async close(): Promise { if (this.ownedTarget !== undefined) { const closed = await closePageTarget( this.ownedTarget.debugPort, this.ownedTarget.targetId, ); if (!closed) { console.error(`browser session: failed to close page target ${this.ownedTarget.targetId}`); } } for (const [, waiter] of this.pending) waiter.reject(new Error("CDP session closed")); this.pending.clear(); this.ws.close(); } } /** Close one Chrome page target through the debugger HTTP endpoint. */ export async function closePageTarget(debugPort: number, targetId: string): Promise { try { await localGet(`http://127.0.0.1:${debugPort}/json/close/${encodeURIComponent(targetId)}`, 2_000); return true; } catch { return false; } } export async function openPageSession( debugPort: number, options: { profilePath?: string } = {}, ): Promise { const startedAt = Date.now(); const profilePath = options.profilePath ?? profileForDebugPort(debugPort); for (let attempt = 1; ; attempt += 1) { try { return await connectPageTarget(debugPort); } catch (error) { const reason = error instanceof Error ? error.message : String(error); // A page target that closes under us is the browser restarting its own target, not a // capture assertion: one fresh attempt covers "Target page, context or browser has been // closed", and anything else surfaces immediately. if (attempt >= 2 || !isTransientPageFailure(reason)) { throw new BrowserLaunchError({ step: "page", elapsedMs: Date.now() - startedAt, profilePath, attempts: attempt, reason, }); } await new Promise((resolve) => setTimeout(resolve, 250)); } } } function isTransientPageFailure(message: string): boolean { const lower = message.toLowerCase(); return ( lower.includes("target page, context or browser has been closed") || lower.includes("browser has been closed") || lower.includes("cdp websocket error") || lower.includes("cdp websocket connect timeout") || lower.includes("no cdp page target available") ); } async function connectPageTarget(debugPort: number): Promise { let info: { id?: string; webSocketDebuggerUrl?: string } | undefined; for (const method of ["PUT", "GET"] as const) { try { info = JSON.parse( await localGet(`http://127.0.0.1:${debugPort}/json/new?about:blank`, 10_000, method), ) as { id?: string; webSocketDebuggerUrl?: string }; break; } catch { /* try next */ } } if (info?.webSocketDebuggerUrl === undefined) { const pages = JSON.parse( await localGet(`http://127.0.0.1:${debugPort}/json/list`, 5_000), ) as Array<{ type: string; webSocketDebuggerUrl?: string }>; const page = pages.find((entry) => entry.type === "page" && entry.webSocketDebuggerUrl !== undefined); if (page?.webSocketDebuggerUrl === undefined) throw new Error("No CDP page target available"); return CdpSession.connect(page.webSocketDebuggerUrl, 15_000); } return CdpSession.connect( info.webSocketDebuggerUrl, 15_000, info.id === undefined ? undefined : { debugPort, targetId: info.id }, ); } /** Every capture profile dir is `jg-*` under the temp dir. */ const PROFILE_PREFIX = "jg-"; /** * A profile is swept once its directory has gone untouched this long. A live browser writes its * profile continuously, so an untouched directory that old belongs to a run that died. Three * hours was longer than a busy session: hundreds of profiles were created inside one window and * filled the drive, so the ordinary floor stays under a session's length. */ const STALE_PROFILE_MS = 45 * 60 * 1000; /** Age that counts as leaked while the temp drive is short of space. */ const PRESSURE_PROFILE_MS = 5 * 60 * 1000; /** Free space on the temp drive below which every profile older than {@link PRESSURE_PROFILE_MS} goes. */ export const PRESSURE_FREE_BYTES = 15 * 1024 * 1024 * 1024; /** Holds the browser pid, so a sweep never deletes the profile of a live browser. */ export const PROFILE_OWNER_FILE = "jg-owner-pid"; /** * Holds the pid of the run that launched the browser. Unlike {@link PROFILE_OWNER_FILE} this is not * the browser: a browser outliving its run is exactly the stray window the sweep reaps. */ export const PROFILE_RUN_FILE = "jg-owner-run"; /** Age past which a visible browser with no recorded run counts as leaked. */ export const STRAY_BROWSER_MS = 20 * 60 * 1000; /** Free space a capture needs on the temp drive before it starts; one Chrome profile is ~150 MB. */ export const MIN_CAPTURE_FREE_BYTES = 2 * 1024 * 1024 * 1024; export type ChromeProcess = ChildProcess & { userDataDir: string }; export function pidAlive(pid: number | undefined): boolean { if (pid === undefined || !Number.isFinite(pid) || pid <= 0) return false; try { process.kill(pid, 0); return true; } catch (error) { return (error as NodeJS.ErrnoException).code === "EPERM"; } } type OwnedProfile = { dir: string; pid?: number | undefined }; /** Profiles this process created and still owes cleanup for. */ const ownedProfiles = new Map(); let profileCleanupHooks = false; /** * Kill the browsers this process still owns, then delete their profiles. Every exit path that * cannot return normally — a throw, a watchdog, SIGINT — ends here. */ function releaseOwnedProfiles(): void { for (const profile of ownedProfiles.values()) killPid(profile.pid, true); for (const dir of [...ownedProfiles.keys()]) { ownedProfiles.delete(dir); try { rmSync(dir, { recursive: true, force: true }); } catch { /* a browser still holding a file; the stale sweep reaches it */ } } } function ownProfileDir(dir: string): string { if (!profileCleanupHooks) { profileCleanupHooks = true; process.on("exit", releaseOwnedProfiles); for (const [signal, code] of [["SIGINT", 130], ["SIGTERM", 143], ["SIGHUP", 129]] as const) { process.on(signal, () => { const count = ownedProfiles.size; if (count > 0) console.error(`browser: ${signal} — closing Chrome and removing ${count} capture profile(s)`); releaseOwnedProfiles(); process.exit(code); }); } } ownedProfiles.set(dir, { dir }); return dir; } /** Record the browser that owns a profile, so an exit kills it before deleting its files. */ export function trackProfileBrowser(dir: string, pid: number | undefined): void { const owned = ownedProfiles.get(dir); if (owned !== undefined) owned.pid = pid; } /** Hand a profile to a longer-lived owner (a warm daemon): this process must not delete it. */ export function detachProfileDir(dir: string): void { ownedProfiles.delete(dir); } /** Bounded wait for a browser to exit; Chrome keeps writing its profile until it does. */ export async function waitForPidExit(pid: number | undefined, timeoutMs = 5_000): Promise { const deadline = Date.now() + timeoutMs; while (pidAlive(pid) && Date.now() < deadline) { await new Promise((resolve) => setTimeout(resolve, 100)); } } /** Block until `pid` has exited or `timeoutMs` has passed. */ function waitForExitSync(pid: number, timeoutMs: number): void { const deadline = Date.now() + timeoutMs; const pause = new Int32Array(new SharedArrayBuffer(4)); while (pidAlive(pid) && Date.now() < deadline) Atomics.wait(pause, 0, 0, 100); } /** * Chrome's renderers and crash handler release profile files a moment after the browser pid * exits (EBUSY on Windows), so the delete retries for a few seconds. A profile still locked after * that is left for the stale sweep. */ export function removeProfileDir(userDataDir: string): void { ownedProfiles.delete(userDataDir); try { removeDirSync(userDataDir); } catch (error) { console.error( `browser: could not remove profile ${userDataDir} (${error instanceof Error ? error.message : String(error)}); a later sweep removes it`, ); } } /** * A `jg-*` directory is a browser profile only if it holds what a capture or Chrome writes into * one, or nothing yet. The prefix alone also matched agents' own folders: `%TEMP%\jg-scratch` of * screenshots was deleted under sessions still using it (2026-11-03). Those are never swept. */ function isBrowserProfile(dir: string): boolean { const names = readdirSync(dir); // `EBWebView` is a WebView2 user data folder (perf desktop launches an app on its own one). return names.length === 0 || [PROFILE_OWNER_FILE, PROFILE_RUN_FILE, "Local State", "Default", "EBWebView"].some((name) => names.includes(name)); } function readOwnerPid(dir: string): number | undefined { try { return Number(readFileSync(join(dir, PROFILE_OWNER_FILE), "utf8")); } catch { return undefined; } } function readRunPid(dir: string): number | undefined { try { const pid = Number(readFileSync(join(dir, PROFILE_RUN_FILE), "utf8")); return Number.isFinite(pid) && pid > 0 ? pid : undefined; } catch { return undefined; } } /** One running process as the stray-browser sweep sees it. */ export interface BrowserProcess { pid: number; parentPid?: number; /** Epoch ms the process started, when the platform reports it. */ startedAt?: number; commandLine: string; } /** The `--user-data-dir` a command line carries, as written. */ export function profileDirFromCommandLine(commandLine: string): string | undefined { const match = /--user-data-dir=(?:"([^"]+)"|(\S+))/.exec(commandLine); return match?.[1] ?? match?.[2]; } function samePath(a: string, b: string): boolean { const left = resolve(a); const right = resolve(b); return process.platform === "win32" ? left.toLowerCase() === right.toLowerCase() : left === right; } /** The `jg-*` profile directory a process owns under `root`, if any. */ export function profileDirUnderRoot(commandLine: string, root: string): string | undefined { const dir = profileDirFromCommandLine(commandLine); if (dir === undefined) return undefined; const normalized = dir.replace(/[\\/]+$/, ""); if (!basename(normalized).startsWith(PROFILE_PREFIX)) return undefined; return samePath(dirname(normalized), root) ? normalized : undefined; } const WINDOWS_PROCESS_QUERY = [ "$rows = @(Get-CimInstance Win32_Process -Filter \"CommandLine like '%--user-data-dir=%'\" | ForEach-Object {", " $age = -1", " if ($_.CreationDate -ne $null) { $age = [long]((Get-Date) - [datetime]$_.CreationDate).TotalMilliseconds }", " [pscustomobject]@{ pid = [int]$_.ProcessId; ppid = [int]$_.ParentProcessId; age = $age; cmd = [string]$_.CommandLine }", "});", "if ($rows.Count -eq 0) { '[]' } else { ConvertTo-Json -InputObject $rows -Compress -Depth 4 }", ].join("\n"); /** * Every process that carries a `--user-data-dir`, which is what a browser command line does. Cheap * enough (about 200 ms) to run at a capture's start, and name-agnostic so Edge and Chromium count. */ export function listBrowserProcesses(): BrowserProcess[] { const parseRows = (text: string): BrowserProcess[] => { const trimmed = text.trim(); if (trimmed.length === 0) return []; let rows: unknown; try { rows = JSON.parse(trimmed.startsWith("[") ? trimmed : `[${trimmed}]`); } catch { return []; } if (!Array.isArray(rows)) return []; return rows.flatMap((row): BrowserProcess[] => { if (typeof row !== "object" || row === null) return []; const record = row as { pid?: unknown; ppid?: unknown; age?: unknown; cmd?: unknown }; const pid = Number(record.pid); if (!Number.isFinite(pid) || pid <= 0 || typeof record.cmd !== "string") return []; const parentPid = Number(record.ppid); const ageMs = Number(record.age); return [ { pid, commandLine: record.cmd, ...(Number.isFinite(parentPid) && parentPid > 0 ? { parentPid } : {}), ...(Number.isFinite(ageMs) && ageMs >= 0 ? { startedAt: Date.now() - ageMs } : {}), }, ]; }); }; if (process.platform === "win32") { // Encoded, because `-Command` through argv mangles the quotes inside a WQL filter. const encoded = Buffer.from(WINDOWS_PROCESS_QUERY, "utf16le").toString("base64"); const run = (shell: string) => spawnSync( shell, ["-NoProfile", "-NonInteractive", "-EncodedCommand", encoded], { encoding: "utf8", windowsHide: true, timeout: 20_000 }, ); // PowerShell 7 starts in about 0.4 s; Windows PowerShell 5 took 3.5 to 8 s on a busy PC, and // every capture start runs this query (2026-11-08). let query = run("pwsh"); if (query.error !== undefined) { console.error(`degraded: pwsh is not installed (${query.error.message}); listing browsers with Windows PowerShell, which starts seconds slower`); query = run("powershell.exe"); } if (query.status !== 0) { // Silent before: on a loaded PC the 20 s query timed out, the sweep saw no browsers, and a // test read that as "nothing stray" (2026-11-08). console.error(`degraded: could not list browser processes (${query.error?.message ?? `exit ${query.status}`}); no stray browser is swept this time`); return []; } return parseRows(query.stdout ?? ""); } const withElapsed = spawnSync("ps", ["-eo", "pid=,ppid=,etimes=,args="], { encoding: "utf8", timeout: 20_000 }); const ps = withElapsed.status === 0 ? withElapsed : spawnSync("ps", ["-axo", "pid=,ppid=,command="], { encoding: "utf8", timeout: 20_000 }); if (ps.status !== 0) return []; const processes: BrowserProcess[] = []; for (const line of (ps.stdout ?? "").split("\n")) { const match = /^\s*(\d+)\s+(\d+)\s+(\d+)?\s*(.*)$/.exec(line); if (match === null || !(match[4] ?? "").includes("--user-data-dir=")) continue; const pid = Number(match[1]); const parentPid = Number(match[2]); const elapsed = Number(match[3]); processes.push({ pid, commandLine: match[4] ?? "", ...(parentPid > 0 ? { parentPid } : {}), ...(Number.isFinite(elapsed) && elapsed > 0 ? { startedAt: Date.now() - elapsed * 1000 } : {}), }); } return processes; } /** What one stray-browser sweep did. */ export interface StrayBrowserSweepResult { /** Browsers killed because the run that owned them was gone. */ killed: number; /** Profile directories those browsers left behind and the sweep removed. */ profilesRemoved: number; } function profileMtimeMs(dir: string): number | undefined { try { return statSync(dir).mtimeMs; } catch { return undefined; } } /** Profile directories some warm shoot daemon's state file still records. */ export function daemonProfiles(root = tmpdir()): Set { const profiles = new Set(); let names: string[] = []; try { names = readdirSync(root); } catch { return profiles; } for (const name of names) { if (!name.startsWith("jgengine-shoot-daemon-") || !name.endsWith(".json")) continue; try { const state = JSON.parse(readFileSync(join(root, name), "utf8")) as { userDataDir?: unknown }; if (typeof state.userDataDir === "string") profiles.add(resolve(state.userDataDir)); } catch { /* unreadable record — it protects nothing */ } } return profiles; } /** * Kill `pid`'s tree and wait for it to exit; true once it has. The exit decides, not the kill * command's status: on a PC at 100% CPU taskkill outlived its own 15 s limit while the browser it * was ending died anyway, and the sweep then left that profile behind as a survivor (2026-11-08). * A killed Chrome also holds its profile's files until it has exited, and Windows keeps a folder * whose files are still open, so the wait comes before the profile is removed. */ export function killAndConfirmExit( pid: number, kill: (pid: number, tree: boolean) => unknown = killPid, alive: (pid: number) => boolean = pidAlive, waitForExit: (pid: number, timeoutMs: number) => void = waitForExitSync, ): boolean { kill(pid, true); waitForExit(pid, 10_000); return !alive(pid); } export interface StrayBrowserSweepOptions { now?: number; /** Age past which an unowned visible browser is leaked; defaults to {@link STRAY_BROWSER_MS}. */ maxAgeMs?: number; /** Replace the live process list (tests). */ processes?: readonly BrowserProcess[]; /** False when the kill was refused (see {@link killPid}); the profile is then left alone. */ kill?: (pid: number) => unknown; remove?: (dir: string) => void; isAlive?: (pid: number | undefined) => boolean; } /** * Kill browsers whose run died, before a capture starts another one. A visible Chrome left on the * desktop is the failure this catches: a lane's ad-hoc script launched it, the run crashed, and the * window sat there for an hour holding gigabytes. A browser is reaped only when its run is gone — * a recorded run pid that is dead, or (for a visible browser with no record) a dead parent and a * profile older than {@link STRAY_BROWSER_MS}. Headless browsers are never reaped here: a warm * daemon outlives its launcher by design, and an invisible browser is not the complaint. */ export function sweepStrayBrowsers(root = tmpdir(), options: StrayBrowserSweepOptions = {}): StrayBrowserSweepResult { const now = options.now ?? Date.now(); const maxAgeMs = options.maxAgeMs ?? STRAY_BROWSER_MS; const isAlive = options.isAlive ?? pidAlive; const kill = options.kill ?? ((pid: number) => killAndConfirmExit(pid)); const remove = options.remove ?? removeProfileDir; // A browser whose main process died leaves its helpers (GPU, renderers, utilities) as siblings // with no parent, so killing one helper's tree ends only that helper. Every process on a stray // profile is killed: two such profiles kept 9 helpers alive for days and stalled each capture // start for 20 s (2026-11-08). const byProfile = new Map(); for (const process of options.processes ?? listBrowserProcesses()) { const dir = profileDirUnderRoot(process.commandLine, root); if (dir === undefined) continue; const group = byProfile.get(dir); if (group === undefined) byProfile.set(dir, [process]); else group.push(process); } const result: StrayBrowserSweepResult = { killed: 0, profilesRemoved: 0 }; for (const [dir, group] of byProfile) { const process = group[0]!; if (ownedProfiles.has(dir)) continue; const headless = process.commandLine.includes("--headless"); const runPid = readRunPid(dir); let stray: boolean; if (runPid !== undefined) { stray = !isAlive(runPid); } else if (headless) { // A warm daemon's Chrome is recorded in its state file and retired by its idle sweep. // One no record names was orphaned by a crashed or cleared daemon: four sat for ten hours. if (!basename(dir).startsWith("jg-shoot-daemon-") || daemonProfiles(root).has(resolve(dir))) continue; const startedAt = process.startedAt ?? profileMtimeMs(dir); stray = !isAlive(process.parentPid) && startedAt !== undefined && now - startedAt >= maxAgeMs; } else { const startedAt = process.startedAt ?? profileMtimeMs(dir); stray = !isAlive(process.parentPid) && startedAt !== undefined && now - startedAt >= maxAgeMs; } if (!stray) continue; const refused = new Set(group.filter(({ pid }) => kill(pid) === false).map(({ pid }) => pid)); // A process the kill could not end still holds the profile: deleting it would only retry for // 10 s and fail. const survivors = group.filter(({ pid }) => refused.has(pid) || isAlive(pid)).map(({ pid }) => pid); if (survivors.length > 0) { console.error(`degraded: browser process(es) ${survivors.join(", ")} on ${dir} survived the kill; the profile stays until they exit`); continue; } result.killed += 1; remove(dir); if (!existsSync(dir)) result.profilesRemoved += 1; } return result; } /** * Removes profile dirs that killed runs leaked: untouched for `minAgeMs`, and no live browser owns * them. Dirs this process is still using are never touched, whatever their age. * Returns how many it removed. */ export function sweepStaleProfiles( root = tmpdir(), now = Date.now(), minAgeMs = STALE_PROFILE_MS, ): number { let removed = 0; for (const name of readdirSync(root)) { if (!name.startsWith(PROFILE_PREFIX)) continue; const dir = join(root, name); if (ownedProfiles.has(dir)) continue; try { const info = statSync(dir); if (!info.isDirectory() || now - info.mtimeMs < minAgeMs || !isBrowserProfile(dir)) continue; if (pidAlive(readOwnerPid(dir))) continue; rmSync(dir, { recursive: true, force: true }); removed += 1; } catch { /* still locked or already gone; the next launch's sweep retries it */ } } return removed; } /** * Remove `jg-*` profiles whose recorded browser is already dead, whatever their age, plus the * ordinary stale ones. Used by the capture guard right after it force-kills a run: the killed * browser cannot release its own profile, and no cleanup code in it ever runs. */ export function sweepOrphanProfiles(root = tmpdir(), now = Date.now()): number { let removed = 0; for (const name of readdirSync(root)) { if (!name.startsWith(PROFILE_PREFIX)) continue; const dir = join(root, name); if (ownedProfiles.has(dir)) continue; try { const info = statSync(dir); if (!info.isDirectory() || !isBrowserProfile(dir)) continue; const owner = readOwnerPid(dir); if (owner === undefined ? now - info.mtimeMs < STALE_PROFILE_MS : pidAlive(owner)) continue; rmSync(dir, { recursive: true, force: true }); removed += 1; } catch { /* still locked or already gone */ } } return removed; } function formatBytes(bytes: number): string { return bytes >= 1024 ** 3 ? `${(bytes / 1024 ** 3).toFixed(1)} GB` : `${Math.round(bytes / 1024 ** 2)} MB`; } /** Free bytes on the drive holding `root`, or null where the platform cannot report it. */ export function freeBytesAt(root: string = tmpdir()): number | null { try { const stats = statfsSync(root); return stats.bsize * stats.bavail; } catch { return null; } } /** * Fail before a capture instead of filling the disk. A full drive takes the whole machine with * it, and one leaked profile is ~150 MB; `JG_CAPTURE_MIN_FREE_MB` moves the floor. */ export function ensureCaptureFreeSpace(root: string = tmpdir(), env: NodeJS.ProcessEnv = process.env): void { const configured = Number(env["JG_CAPTURE_MIN_FREE_MB"]); const minimum = Number.isFinite(configured) && configured > 0 ? configured * 1024 * 1024 : MIN_CAPTURE_FREE_BYTES; const free = freeBytesAt(root); if (free === null || free >= minimum) return; throw new Error( `capture: ${parse(root).root} has ${formatBytes(free)} free, less than the ${formatBytes(minimum)} a capture needs — free space, or point TEMP at another drive (JG_CAPTURE_MIN_FREE_MB changes the floor)`, ); } /** * Sweep leaked capture profiles, tightening the age limit while the temp drive is short of space, * and say in one line what it removed. Free space is read here and injectable * (`freeBytes: null` means unreadable, which is treated as no pressure). */ export interface SweepOptions { /** Free bytes on the temp drive; defaults to the live reading. Null when it cannot be read. */ freeBytes?: number | null; /** Where the line goes; stderr by default. */ log?: (line: string) => void; /** Clock, for tests. */ now?: number; /** Replace the live process list the stray-browser sweep reads (tests). */ processes?: readonly BrowserProcess[]; /** Replace the kill and the liveness check the stray-browser sweep uses (tests: a listed pid may be a real process on the host). */ kill?: (pid: number) => unknown; isAlive?: (pid: number | undefined) => boolean; } function minutes(ms: number): string { return `${Math.round(ms / 60_000)} minutes`; } /** * One sweep at a capture tool's startup: {@link STALE_PROFILE_MS} normally, and * {@link PRESSURE_PROFILE_MS} under {@link PRESSURE_FREE_BYTES} of free space. Returns how many * profiles it removed, and logs one line whenever it ran under pressure or removed anything. */ export function sweepCaptureProfiles(root = tmpdir(), options: SweepOptions = {}): number { const now = options.now ?? Date.now(); const free = options.freeBytes === undefined ? freeBytesAt(root) : options.freeBytes; const pressure = free !== null && free < PRESSURE_FREE_BYTES; const ageMs = pressure ? PRESSURE_PROFILE_MS : STALE_PROFILE_MS; const strays = sweepStrayBrowsers(root, { now, ...(options.processes === undefined ? {} : { processes: options.processes }), ...(options.kill === undefined ? {} : { kill: options.kill }), ...(options.isAlive === undefined ? {} : { isAlive: options.isAlive }), }); const removed = sweepStaleProfiles(root, now, ageMs); if (pressure || removed > 0 || strays.killed > 0 || strays.profilesRemoved > 0) { // A short disk is a warning; a routine sweep is housekeeping, printed under --verbose. const log = options.log ?? (pressure ? (line: string) => console.error(line) : detail); const killed = strays.killed > 0 ? `killed ${strays.killed} stray browser(s) whose run had died, removed ${strays.profilesRemoved} profile(s); ` : ""; log( pressure ? `capture: ${formatBytes(free ?? 0)} free on ${parse(root).root}, under ${formatBytes(PRESSURE_FREE_BYTES)} — ${killed}swept ${removed} capture profile(s) older than ${minutes(ageMs)}` : `capture: ${killed}swept ${removed} leaked capture profile(s) older than ${minutes(ageMs)} from ${root}`, ); } return removed + strays.profilesRemoved; } function createProfileDir(prefix: string): string { ensureCaptureFreeSpace(); // Silent here: a busy lane creates hundreds of these, and the entry-point sweep logs. sweepCaptureProfiles(tmpdir(), { log: () => {} }); return ownProfileDir(mkdtempSync(join(tmpdir(), prefix))); } export function launchChrome( debugPort: number, prefix = "jg-drive-", options: ChromeLaunchOptions = {}, ): ChromeProcess { const chrome = findChromeExecutable(); const userDataDir = createProfileDir(prefix); const headed = chromeLaunchMode(options.headed === true) === "headed"; let backend = softwareGlBackend(); const display = headed || backend !== "llvmpipe" ? null : ensureXvfbDisplay(); if (backend === "llvmpipe" && display === null) backend = "swiftshader"; if (!options.persistent) writeFileSync(join(userDataDir, PROFILE_RUN_FILE), String(process.pid)); // The machine's limit on rendering browsers, taken by every launch, held while this Chrome lives. const slot = takeRenderSlot({ label: renderLabel(prefix) }); let child: ReturnType; try { child = spawn( chrome, [ `--remote-debugging-port=${debugPort}`, `--user-data-dir=${userDataDir}`, ...chromeRenderArgs(headed ? null : backend, headed), ...chromeFrameClockArgs(options.frameClock), "--no-first-run", "--no-default-browser-check", "--disable-background-networking", // Without these three, a long-lived headless Chrome can throttle rAF on // pages it considers occluded/backgrounded — frame times read as seconds // and perf evidence from the debug snapshot becomes garbage. "--disable-background-timer-throttling", "--disable-backgrounding-occluded-windows", "--disable-renderer-backgrounding", "--disable-component-update", "--disable-sync", "--disable-extensions", "--disable-default-apps", "--mute-audio", "--hide-scrollbars", PRECISE_HEAP_ARG, "--no-sandbox", "--disable-dev-shm-usage", "about:blank", ], { ...(display === null ? {} : { env: { ...process.env, DISPLAY: display } }), stdio: "ignore", windowsHide: true, // A daemon Chrome must outlive the Bun command that starts it. Chrome is a GUI-subsystem // executable on Windows, so detaching it does not create a console window. detached: options.persistent === true || process.platform !== "win32", }, ); } catch (error) { slot.release(); throw error; } slot.attach(child.pid); child.once("exit", () => slot.release()); child.once("error", () => slot.release()); if (child.pid !== undefined) writeFileSync(join(userDataDir, PROFILE_OWNER_FILE), String(child.pid)); trackProfileBrowser(userDataDir, child.pid); // Set before Chrome forks its GPU and renderer processes, which inherit the browser's class. const priority = options.priority === "normal" ? restoreNormalPriority(child.pid) : currentPriority(child.pid); if (child.pid !== undefined) launchedPriorities.set(child.pid, priority); if (!options.persistent && child.pid !== undefined) startChromeWatchdog(child.pid, userDataDir); return Object.assign(child, { userDataDir }); } /** Who a render slot is for, as a waiting run reads it: the script, its profile prefix and checkout. */ function renderLabel(prefix: string): string { const script = process.argv[1]?.replace(/^.*[\\/]/, "") ?? "bun"; return `${script} ${prefix.replace(/-$/, "")} in ${process.cwd()}`; } /** The priority a Chrome this process launched runs at, by browser pid. */ const launchedPriorities = new Map(); /** * Start the detached watchdog that ends this Chrome's tree and profile when this process dies * without running its exit handlers (`taskkill /F`, a stopped job): `scripts/chrome-watchdog.ts`. * Tests that fake the launch never reach here. */ export function startChromeWatchdog(chromePid: number, userDataDir: string, launcherPid = process.pid): number | undefined { try { const watchdog = spawn(process.execPath, [join(import.meta.dir, "chrome-watchdog.ts"), String(launcherPid), String(chromePid), userDataDir], { stdio: "ignore", windowsHide: true, detached: true, }); watchdog.unref(); return watchdog.pid; } catch (error) { console.error(`degraded: no watchdog for Chrome ${chromePid} (${error instanceof Error ? error.message : String(error)}); a killed launcher would leave it running`); return undefined; } } /** Launch persistent headless Chrome without retaining a Windows child-process handle in Bun. */ export function launchPersistentChrome( debugPort: number, prefix = "jg-shoot-daemon-", ): { pid: number; child: ChromeProcess | null; userDataDir: string } { if (process.platform !== "win32") { const child = launchChrome(debugPort, prefix, { persistent: true }); child.unref(); if (child.pid === undefined) throw new Error("Persistent Chrome launcher returned no pid"); // The daemon state file owns this profile from here; this process exiting must not delete it. detachProfileDir(child.userDataDir); return { pid: child.pid, child, userDataDir: child.userDataDir }; } const chrome = findChromeExecutable(); const userDataDir = createProfileDir(prefix); const args = [ `--remote-debugging-port=${debugPort}`, `--user-data-dir=${userDataDir}`, "--headless=new", "--no-first-run", "--no-default-browser-check", "--disable-background-networking", "--disable-background-timer-throttling", "--disable-backgrounding-occluded-windows", "--disable-renderer-backgrounding", "--disable-component-update", "--disable-sync", "--disable-extensions", "--disable-default-apps", "--mute-audio", "--hide-scrollbars", PRECISE_HEAP_ARG, ...chromeGraphicsArgs(), "--no-sandbox", "--disable-dev-shm-usage", "about:blank", ]; let pid: number; const slot = takeRenderSlot({ label: renderLabel(prefix) }); try { // Outside this run's tree and Windows job, so the job ending does not end the daemon. pid = startOutsideCaller(chrome, args, { cwd: userDataDir }); // The slot lives with this browser, not with the run that started it. slot.attach(pid); } catch (error) { slot.release(); removeProfileDir(userDataDir); throw new Error(`Persistent Chrome launch failed: ${error instanceof Error ? error.message : String(error)}`); } writeFileSync(join(userDataDir, PROFILE_OWNER_FILE), String(pid)); // Created by WMI, it inherits nothing from this process: put it below normal like every capture // browser, before it starts most of its GPU and renderer processes. lowerToBelowNormal(pid); detachProfileDir(userDataDir); return { pid, child: null, userDataDir }; } export interface LaunchableBrowser { pid?: number | undefined; userDataDir: string; } /** What one launch hands Chrome beyond its port and profile: daemon lifetime, and the frame clock. */ export interface ChromeLaunchOptions { /** Leave the browser running after the process that started it exits. */ persistent?: boolean; /** rAF clock; the display's 16.7 ms commit by default. */ frameClock?: FrameClock; /** * Show a real window instead of headless Chrome. Off by default and off-screen when set, so a * capture can never put a Chrome on Jon's desktop by accident; only `--headed` sets it. */ headed?: boolean; /** * `normal` puts the browser back to normal priority after launch, for a mode whose product is a * frame time (the launcher itself runs below normal, see `scripts/machine-priority.ts`). The * default inherits the launcher's priority, which is what a capture or a byte count wants. */ priority?: "normal" | "inherit"; } export interface StartBrowserOptions { /** The debugger port to bind, or 0 for a free one the browser picks and publishes in its profile. */ debugPort: number; /** user-data-dir prefix; every attempt gets a fresh profile under it. */ prefix?: string; /** Wait per attempt; defaults to {@link resolveChromeReadyMs}. The retry doubles it. */ readyMs?: number; env?: NodeJS.ProcessEnv; /** Replace the real launch (tests and the daemon own what they hand back). */ launch?: (debugPort: number, prefix?: string, options?: ChromeLaunchOptions) => L; /** rAF clock the launched Chrome runs on; test launchers receive it too. */ frameClock?: FrameClock; /** Launch a real (off-screen) window instead of headless Chrome. */ headed?: boolean; /** `normal` for a Chrome whose frame times are the product; see {@link ChromeLaunchOptions.priority}. */ priority?: "normal" | "inherit"; /** Prove the page layer answers; defaults to opening and closing a page target. */ pageProbe?: (debugPort: number, profilePath: string) => Promise; /** Read the port a browser launched on port 0 published; defaults to its profile's DevToolsActivePort. */ publishedPort?: (browser: L, timeoutMs: number) => Promise; log?: (line: string) => void; } export interface StartedBrowser { /** The port the browser answers on: the one asked for, or the one it picked for `debugPort: 0`. */ debugPort: number; browser: L; profilePath: string; /** 1 when the first handshake worked, 2 when the retry recovered it. */ attempts: number; } async function defaultPageProbe(debugPort: number, profilePath: string): Promise { const session = await openPageSession(debugPort, { profilePath }); await session.close(); } /** * The port a browser launched on port 0 bound, read from the DevToolsActivePort file in its * profile. A port picked before the launch, however it is picked, is one two runs can pick * together; the one the browser publishes is held by that browser alone. */ export async function publishedDebugPort(browser: LaunchableBrowser & { exitCode?: number | null }, timeoutMs: number): Promise { const startedAt = Date.now(); const portFile = join(browser.userDataDir, "DevToolsActivePort"); while (Date.now() - startedAt < timeoutMs) { const exit = browser.exitCode; if (typeof exit === "number") { throw new Error(`the browser process exited (code ${exit}) before publishing its debugger port`); } let port = 0; try { port = parseInt(readFileSync(portFile, "utf8"), 10) || 0; } catch { /* not written yet */ } if (port > 0) return port; await new Promise((resolve) => setTimeout(resolve, 50)); } throw new Error(`the browser did not publish its debugger port within ${timeoutMs}ms`); } /** * The one way a caller starts a browser: spawn it, wait for its debugger endpoint, then * prove a page target answers. `debugPort: 0` lets the browser pick a free port, read back * from its profile, so two runs on one machine never share one; the port used comes back as * `debugPort`. A transient failure before the page is live — a slow cold * start, a browser that exits before binding, a target that closed under us — gets exactly * one retry with a fresh profile and a doubled wait. A budget, assertion or capture failure * happens after this returns and is never retried here. */ export async function startBrowser( options: StartBrowserOptions, ): Promise> { const env = options.env ?? process.env; let readyMs = options.readyMs ?? resolveChromeReadyMs(env); const log = options.log ?? ((line: string) => console.error(line)); const launch = options.launch ?? ((port: number, prefix?: string, launchOptions?: ChromeLaunchOptions) => launchChrome(port, prefix, launchOptions ?? {}) as unknown as L); const publishedPort = options.publishedPort ?? publishedDebugPort; const pageProbe = options.pageProbe ?? defaultPageProbe; const launchOptions: ChromeLaunchOptions | undefined = options.frameClock === undefined && options.headed !== true && options.priority === undefined ? undefined : { ...(options.frameClock === undefined ? {} : { frameClock: options.frameClock }), ...(options.headed === true ? { headed: true } : {}), ...(options.priority === undefined ? {} : { priority: options.priority }), }; const attempts = 2; let last: BrowserLaunchError | null = null; for (let attempt = 1; attempt <= attempts; attempt += 1) { const startedAt = Date.now(); let browser: L | undefined; let step: BrowserLaunchStep = "launch"; try { browser = launch(options.debugPort, options.prefix, launchOptions); step = "endpoint"; // Reading a published port spends part of this attempt's wait; a fixed port keeps all of it. const debugPort = options.debugPort === 0 ? await publishedPort(browser, readyMs) : options.debugPort; const remainingMs = options.debugPort === 0 ? Math.max(1, readyMs - (Date.now() - startedAt)) : readyMs; await waitForDebugger(debugPort, remainingMs, { browser: browser as { pid?: number; exitCode?: number | null }, profilePath: browser.userDataDir, }); step = "page"; await pageProbe(debugPort, browser.userDataDir); launchedProfiles.set(debugPort, browser.userDataDir); if (attempt > 1) { log(`browser: launch recovered on attempt ${attempt} after ${Date.now() - startedAt}ms (profile ${browser.userDataDir})`); } return { debugPort, browser, profilePath: browser.userDataDir, attempts: attempt }; } catch (error) { const elapsedMs = Date.now() - startedAt; const profilePath = browser?.userDataDir ?? null; const reason = error instanceof Error ? error.message : String(error); last = new BrowserLaunchError({ step, elapsedMs, profilePath, attempts: attempt, waitedMs: step === "launch" ? undefined : readyMs, reason, }); // Discard this attempt's browser and profile before spending another wait on a new one. if (browser !== undefined) { killPid(browser.pid, true); await waitForPidExit(browser.pid); removeProfileDir(browser.userDataDir); } if (attempt >= attempts || !isRetryableLaunchFailure(step, reason)) throw last; const next = Math.round(readyMs * 2); const short = error instanceof BrowserLaunchError ? error.reason : reason; log( `browser: the ${step} step failed on attempt ${attempt} after ${elapsedMs}ms` + `${profilePath === null ? "" : ` (profile ${profilePath})`}: ${short} — retrying with a fresh profile and a ${next}ms wait`, ); readyMs = next; } } throw last ?? new Error("browser: launch failed without a reason"); } /** Which handshake failures are worth one fresh browser, and which are real configuration errors. */ export function isRetryableLaunchFailure(step: BrowserLaunchStep, message: string): boolean { if (/no chrome\/chromium found/i.test(message)) return false; if (step === "launch" || step === "endpoint") return true; return isTransientPageFailure(message); } export type CaptureVia = "screencast" | "screenshot"; export interface ViewportPng { bytes: Buffer; /** Which CDP path produced the pixels — recorded in the shot's timing line. */ via: CaptureVia; } /** Screencast wait before falling back; below the ~20s a software-GL captureScreenshot costs. */ export const SCREENCAST_CAPTURE_TIMEOUT_MS = 15_000; /** * Whether the screencast pump reproduces this profile's pixels exactly. It emits CSS-pixel * frames, so a `deviceScaleFactor` above 1 would silently halve a mobile shot's resolution. */ export function screencastCapturesFully(profile: DeviceProfile): boolean { return profile.deviceScaleFactor === 1; } /** * Flat screencast frames tolerated before the pump is written off for this shot. The pump * composites the page's *last committed* layers, and a WebGL canvas that has not committed * one since the screencast started is simply absent from them — so the frame arrives fast, * correctly sized, correctly timestamped, and carries a black hole where the 3D view is. * A few frames is enough to tell "the canvas has not committed yet" from "this page never * will"; past that, the forced re-raster is the only honest capture. */ export const MAX_FLAT_SCREENCAST_FRAMES = 4; /** Distinct sampled colours at or below which a region carries no picture. */ const FLAT_REGION_COLOURS = 2; /** * Whether `region` of a captured PNG holds a picture at all, sampled on a stride grid. * * This is the acceptance test the fast capture path lacked: size, timestamp, and encoding * all passed on a frame whose viewport was one flat colour, so a blank 3D view shipped as * a real shot. Scoped to the region because a busy HUD alone clears any whole-frame check. */ export function regionCarriesPicture( bytes: Uint8Array, region: { x: number; y: number; width: number; height: number }, ): boolean { let decoded: { width: number; height: number; data: Uint8Array }; try { decoded = decodePng(bytes); } catch { return true; // undecodable here is the size guard's or the scorer's call, not this one } const { width, height, data } = decoded; const x0 = Math.max(0, Math.floor(region.x)); const y0 = Math.max(0, Math.floor(region.y)); const x1 = Math.min(width, Math.ceil(region.x + region.width)); const y1 = Math.min(height, Math.ceil(region.y + region.height)); if (x1 - x0 < 2 || y1 - y0 < 2) return true; const stride = Math.max(1, Math.floor(Math.min(x1 - x0, y1 - y0) / 24)); const seen = new Set(); for (let y = y0; y < y1; y += stride) { for (let x = x0; x < x1; x += stride) { const i = (y * width + x) * 4; seen.add(((data[i] ?? 0) << 16) | ((data[i + 1] ?? 0) << 8) | (data[i + 2] ?? 0)); if (seen.size > FLAT_REGION_COLOURS) return true; } } return false; } /** IHDR width/height without inflating the image data. */ function pngSize(bytes: Uint8Array): { width: number; height: number } | null { if (bytes.length < 24 || bytes[0] !== 137 || bytes[1] !== 80) return null; const read = (offset: number): number => (((bytes[offset] ?? 0) << 24) | ((bytes[offset + 1] ?? 0) << 16) | ((bytes[offset + 2] ?? 0) << 8) | (bytes[offset + 3] ?? 0)) >>> 0; return { width: read(16), height: read(20) }; } /** * Take the next composited frame off the screencast pump that actually shows the page, or * null when none arrives in time. `notBefore` drops a frame the compositor presented before * this request, and `liveRegion` drops one whose 3D viewport is a flat colour — the pump can * hand back a well-formed frame the canvas has not committed into yet. */ async function nextScreencastPng( session: CdpSession, timeoutMs: number, expect?: { width: number; height: number }, liveRegion?: { x: number; y: number; width: number; height: number }, ): Promise { const notBefore = Date.now() / 1000; let flatFrames = 0; return await new Promise((resolvePromise) => { let settled = false; const finish = (value: Buffer | null): void => { if (settled) return; settled = true; clearTimeout(timer); off(); void session.send("Page.stopScreencast").catch(() => {}); resolvePromise(value); }; const timer = setTimeout(() => finish(null), timeoutMs); const off = session.on("Page.screencastFrame", (params) => { const sessionId = params["sessionId"]; if (typeof sessionId === "number" || typeof sessionId === "string") { void session.send("Page.screencastFrameAck", { sessionId }).catch(() => {}); } const data = params["data"]; if (typeof data !== "string" || data.length === 0) return; const timestamp = (params["metadata"] as { timestamp?: number } | undefined)?.timestamp; if (typeof timestamp === "number" && timestamp < notBefore) return; const bytes = Buffer.from(data, "base64"); const size = pngSize(bytes); // A downscaled or unreadable frame is not this shot — take the slow honest path. if (size === null || (expect !== undefined && (size.width !== expect.width || size.height !== expect.height))) { finish(null); return; } if (liveRegion !== undefined && !regionCarriesPicture(bytes, liveRegion)) { flatFrames += 1; if (flatFrames >= MAX_FLAT_SCREENCAST_FRAMES) finish(null); return; } finish(bytes); }); void session.send("Page.startScreencast", { format: "png", everyNthFrame: 1 }).catch(() => finish(null)); }); } /** * Pull the viewport as a lossless PNG. * * `Page.captureScreenshot` re-rasters and re-composites the whole frame synchronously; * on software GL that costs several frame times (measured ~22s against a 1600x900 WebGL * scene whose own cadence is ~4s/frame). The screencast pump hands over the next * composited frame instead — same compositor, same PNG encoder, same dimensions — for * roughly one frame time. Anything that does not deliver a fresh, correctly-sized frame * within `timeoutMs` falls back to `Page.captureScreenshot`, so a page that never * commits another frame still captures. `JG_CAPTURE_SCREENCAST=0` forces the old path. * * Pass `liveRegion` (the 3D viewport in captured pixels) whenever the caller knows it: the * pump composites the page's last committed layers, so a canvas that has not committed one * since the screencast started is missing from an otherwise valid frame. Without the region * that frame is indistinguishable from a good one, and a blank 3D view ships as a real shot. * * The pump emits CSS-pixel frames — it ignores `deviceScaleFactor` — so a shot under a * dsf>1 profile (mobile) must pass `screencast: false` and keep the full-resolution path. * {@link screencastCapturesFully} decides that from the device profile. */ export async function captureViewportPng( session: CdpSession, options: { timeoutMs?: number; expect?: { width: number; height: number }; screencast?: boolean; liveRegion?: { x: number; y: number; width: number; height: number }; } = {}, ): Promise { if (options.screencast !== false && process.env["JG_CAPTURE_SCREENCAST"] !== "0") { try { const bytes = await nextScreencastPng( session, options.timeoutMs ?? SCREENCAST_CAPTURE_TIMEOUT_MS, options.expect, options.liveRegion, ); if (bytes !== null) return { bytes, via: "screencast" }; } catch { /* fall back to the synchronous capture */ } } const shot = await session.send("Page.captureScreenshot", { format: "png", fromSurface: true, captureBeyondViewport: false, optimizeForSpeed: true, }); const data = shot["data"]; if (typeof data !== "string" || data.length === 0) { throw new Error("Page.captureScreenshot returned empty data"); } return { bytes: Buffer.from(data, "base64"), via: "screenshot" }; } /** * Poll `data-jg-capture` until the page reports an honest frame (`ready`) or * surfaces an error, shared by shoot and drive. Throws with the page-reported * detail on error, or on timeout. */ export async function waitCaptureReady(session: CdpSession, timeoutMs: number): Promise { const wait = readinessWait(timeoutMs); let last: { status: string | null; error: string | null; href: string | null; stage: string | null } | undefined; for (;;) { last = (await session.evaluate<{ status: string | null; error: string | null; href: string | null; stage: string | null }>(`({ status: document.documentElement.dataset.jgCapture ?? null, error: document.documentElement.dataset.jgCaptureError ?? null, href: location.href, stage: document.documentElement.dataset.jgCaptureStage ?? null })`)) ?? undefined; const status = last?.status; if (status === "ready") return; if (status === "error") throw new Error(`capture error: ${last?.error ?? "unknown"}`); if (typeof last?.href === "string" && last.href.startsWith("chrome-error://")) throw new Error(wait.failure(last.status, last.href, "")); if (!wait.goOn(last?.status ?? null)) throw new Error(wait.failure(last?.status ?? null, last?.href ?? null, "", last?.stage)); await new Promise((r) => setTimeout(r, 100)); } } function cpuSample(): CpuSample { let idle = 0; let total = 0; for (const cpu of cpus()) { idle += cpu.times.idle; total += cpu.times.idle + cpu.times.user + cpu.times.sys + cpu.times.irq + cpu.times.nice; } return { idle, total }; } /** * The deadline of one readiness wait. A PC busy past {@link BUSY_PC_PERCENT} for the whole window * gets one more window, said in a line: a fixed 60 s failed shots that only needed a quieter * moment. The failure line names what the page was doing and how busy the PC was. */ function readinessWait(timeoutMs: number): { goOn(status: string | null): boolean; /** `stage` is what the page's gate was still waiting on (`data-jg-capture-stage`), when it said. */ failure(status: string | null, href: string | null, url: string, stage?: string | null): string; } { const startedAt = Date.now(); const since = cpuSample(); let deadline = startedAt + timeoutMs; let extended = false; return { goOn(status) { if (Date.now() < deadline) return true; const busy = cpuBusyPercent(since, cpuSample()); if (extended || busy < BUSY_PC_PERCENT) return false; extended = true; deadline = Date.now() + timeoutMs; console.error(`capture: the PC's CPU is ${busy}% busy, so the page (${status === null ? "no capture status yet" : `still "${status}"`}) gets another ${Math.round(timeoutMs / 1000)}s`); return true; }, failure(status, href, url, stage) { return readinessTimeoutLine({ waitedMs: Date.now() - startedAt, status, href, url, cpuBusy: cpuBusyPercent(since, cpuSample()), stage: stage ?? null }); }, }; } /** * What the page still has over the canvas while a scene prepares, or null once it is gone. The dev * runner declares capture readiness only after this clears, so a shot that still sees it is * photographing a loading cover: the label names the work it was waiting on. */ export async function preparingCoverLabel(session: CdpSession): Promise { const label = await session.evaluate(`(() => { const cover = document.querySelector("[data-shell-warmup], [data-shell-code-loading]"); if (cover === null) return null; return (cover.textContent || "").trim().slice(0, 80) || "loading cover"; })()`); return typeof label === "string" && label.length > 0 ? label : null; } /** * The WebGL2 renderer the launched browser draws with, or null when it has no WebGL2 at all. A * capture browser without it photographs an empty canvas, so a shot fails on null here instead of * writing a frame the scene never reached. */ export async function webGlRenderer(session: CdpSession): Promise { const renderer = await session.evaluate(`(() => { const canvas = document.createElement("canvas"); const gl = canvas.getContext("webgl2"); if (gl === null) return null; const ext = gl.getExtension("WEBGL_debug_renderer_info"); return String(ext === null ? gl.getParameter(gl.RENDERER) : gl.getParameter(ext.UNMASKED_RENDERER_WEBGL)); })()`); return typeof renderer === "string" && renderer.length > 0 ? renderer : null; } function exceptionMessage(params: Record): string { const details = params["exceptionDetails"] as | { text?: unknown; exception?: { description?: unknown; value?: unknown }; url?: unknown; lineNumber?: unknown } | undefined; const description = details?.exception?.description; const value = details?.exception?.value; const text = details?.text; const message = typeof description === "string" ? description : typeof value === "string" ? value : typeof text === "string" ? text : "unknown exception"; const location = typeof details?.url === "string" && details.url.length > 0 ? ` (${details.url}${typeof details.lineNumber === "number" ? `:${details.lineNumber + 1}` : ""})` : ""; return `page exception: ${message}${location}`; } /** * Records every uncaught page exception from now until `stop()`. A page that throws after its * first frame is still broken, and a measurement of it is not evidence the game works: the * frame-budget gate runs one of these over its whole window so a thrown boot fails it. */ export function watchPageExceptions(session: CdpSession): { exceptions: string[]; stop: () => void } { const exceptions: string[] = []; const off = session.on("Runtime.exceptionThrown", (params) => { exceptions.push(exceptionMessage(params)); }); return { exceptions, stop: off }; } export interface CaptureRegions { /** The WebGL canvas in device pixels — the 3D viewport, not the whole frame. */ region?: { x: number; y: number; width: number; height: number }; /** HUD rectangles drawn over it, in the same space. */ masks: { x: number; y: number; width: number; height: number }[]; } /** Cap on returned mask rects; the largest are kept, so the tail costs nothing to drop. */ const MAX_CAPTURE_MASKS = 200; /** One model the page replaced with a placeholder box, as the shell's loader publishes it. */ export interface MissingModel { name: string; url: string; message: string; } /** * Every model the page could not load and drew as a placeholder box (`__jgengineMissingModels`, * published by the shell's model loader). A capture that rendered one is not evidence of the game. */ export async function readMissingModels(session: CdpSession): Promise { const raw = await session.evaluate(`(() => { const list = globalThis.__jgengineMissingModels; return Array.isArray(list) ? list.map((entry) => ({ name: String(entry.name), url: String(entry.url), message: String(entry.message) })) : []; })()`); return raw ?? []; } /** The line a capture prints when models are missing, or null when none are. */ export function missingModelsProblem(missing: readonly MissingModel[]): string | null { if (missing.length === 0) return null; const names = missing.slice(0, 8).map((entry) => `${entry.name} (${entry.url})`).join(", "); const more = missing.length > 8 ? ` and ${missing.length - 8} more` : ""; return `MISSING MODELS: ${missing.length} drawn as placeholder boxes - ${names}${more}. Run: bun run games:provision (links them from the shared asset store), or fix the path.`; } /** Layout status the shot is judged against, read in the same pass as the regions. */ export interface CapturePageState extends CaptureRegions { overflow: string | null; collision: string | null; } /** * Locate the 3D viewport, everything painted over it (in captured-image pixels), and the * HUD layout status — everything a shot needs off the page, in **one** `Runtime.evaluate`. * Scoring the whole frame lets a busy HUD carry a dead viewport past every threshold — a * buried camera still scored `nonblank` because the panels alone supplied the entropy. * * Masks are discovered by what an element *paints*, not by what it opts into: a game whose * HUD is raw divs is the common case, and an opt-in marker would have covered exactly the * games that already use the shipped panels. `data-jg-capture-mask` forces an element in. * Over-masking is safe — the viewport verdict is withheld once too little of the region * survives (see `MIN_SAMPLED_SHARE`). * * One evaluate, not two: each round trip queues behind the page's own rAF work, so a second * read cost another whole frame time (measured 14.2s for the pair on a scene rendering at * ~4s/frame). */ export async function readCapturePageState(session: CdpSession): Promise { const raw = await session.evaluate(`(() => { const dpr = window.devicePixelRatio || 1; const box = (el) => { const r = el.getBoundingClientRect(); return { x: r.x * dpr, y: r.y * dpr, width: r.width * dpr, height: r.height * dpr }; }; const canvas = document.querySelector("canvas"); const canvasRect = canvas === null ? null : canvas.getBoundingClientRect(); const paints = (style) => { if (style.backgroundImage !== "none") return true; const match = /rgba?\\(([^)]+)\\)/.exec(style.backgroundColor); if (match === null) return false; const parts = match[1].split(",").map((v) => Number.parseFloat(v)); return parts.length < 4 || parts[3] > 0.05; }; const masks = []; const accepted = []; // A rect wholly inside an accepted mask adds nothing to the union, so it never needs a // getComputedStyle — the per-element style resolution is what makes this pass expensive on // a deep HUD (measured ~10s on one game, most of it style work on nested panel children). const covered = (r) => { for (let i = 0; i < accepted.length; i += 1) { const m = accepted[i]; if (r.left >= m.left && r.right <= m.right && r.top >= m.top && r.bottom <= m.bottom) return true; } return false; }; for (const el of document.querySelectorAll("body *")) { if (el.tagName === "CANVAS") continue; const forced = el.hasAttribute("data-jg-capture-mask") || el.hasAttribute("data-hud-panel"); const r = el.getBoundingClientRect(); if (r.width < 6 || r.height < 6) continue; if (canvasRect !== null && (r.right < canvasRect.left || r.left > canvasRect.right || r.bottom < canvasRect.top || r.top > canvasRect.bottom)) continue; // An ancestor of the canvas is the page frame, not an overlay drawn on top of it. if (canvas !== null && el.contains(canvas)) continue; if (covered(r)) continue; const style = getComputedStyle(el); if (style.visibility === "hidden" || style.display === "none" || Number(style.opacity) <= 0.1) continue; if (!forced && !paints(style)) continue; accepted.push(r); masks.push(box(el)); } masks.sort((a, b) => b.width * b.height - a.width * a.height); const attr = (selector, name) => { const value = document.querySelector(selector)?.getAttribute(name) ?? null; return typeof value === "string" && value.length > 0 ? value : null; }; return { ...(canvasRect === null ? {} : { region: box(canvas) }), masks: masks.slice(0, ${MAX_CAPTURE_MASKS}), overflow: attr("[data-hud-overflow]", "data-hud-overflow"), collision: attr("[data-jg-layout-collision]", "data-jg-layout-collision"), }; })()`); return { masks: [], overflow: null, collision: null, ...(raw ?? {}) }; } /** * Echo the page's own `console.warn`/`console.error` to stderr for the life of a capture. * The engine already explains most bad frames in the page console — the camera far-plane * warning, asset diagnostics — and none of it reached the agent driving the capture. */ export function forwardPageConsole(session: CdpSession, prefix: string): () => void { return session.on("Runtime.consoleAPICalled", (params) => { const level = params["type"]; if (level !== "warning" && level !== "error") return; const args = Array.isArray(params["args"]) ? params["args"] : []; const text = args .map((arg: { value?: unknown; description?: unknown }) => typeof arg?.value === "string" || typeof arg?.value === "number" ? String(arg.value) : typeof arg?.description === "string" ? arg.description : "", ) .filter((part) => part.length > 0) .join(" "); if (text.length === 0) return; const line = `${prefix} page ${level}: ${text.slice(0, 500)}`; if (isShaderCompilerChatter(text)) detail(line); else console.error(line); }); } const SHADER_INFO_LOG = "THREE.WebGLProgram: Program Info Log:"; /** * A shader that compiled, with only the GPU driver's own warnings in its info log (on Windows, * Direct3D's `warning X4122: sum ... cannot be represented accurately`). It says nothing about the * game and arrived in screenfuls on every capture, so it is kept for `--verbose`. A log with any * error, and three.js's `Shader Error` report, still print. */ export function isShaderCompilerChatter(text: string): boolean { if (!text.startsWith(SHADER_INFO_LOG) || /\berror\b/i.test(text)) return false; const lines = text.slice(SHADER_INFO_LOG.length).split("\n").map((row) => row.trim()).filter((row) => row !== ""); return lines.length > 0 && lines.every((row) => /\bwarning X\d+:/.test(row)); } const CAPTURE_SIGNAL_BINDING = "__jgCaptureSignal"; /** Sessions whose readiness binding is already installed — re-registering duplicates it per navigation. */ const readinessInstalled = new WeakSet(); /** * Push readiness instead of polling for it. Every `Runtime.evaluate` poll queues behind the * page's own rAF work, so on a heavy WebGL page the flag is seen up to a frame time after it * is set; a MutationObserver reports it in the task that sets it. Installation is best-effort — * the poll below stays as the backstop, so an older page or a failed binding still works. */ /** * Runs at document start in every capture page: tells the engine's browser-suspension observer that a * capture host holds play, so a focus or visibility change on this shared machine never auto-pauses * the game mid-drive. Must name `CAPTURE_HOLD_KEY` from `@jgengine/ui`'s `browserLifecycle`. */ export const CAPTURE_HOLD_SOURCE = "globalThis.__jgengineCaptureHold = true;"; const playHeld = new WeakSet(); /** Keep a capture page focused and unpausable by window switches; best-effort on older Chrome. */ async function holdCapturePlay(session: CdpSession): Promise { if (playHeld.has(session)) return; playHeld.add(session); await session.send("Page.addScriptToEvaluateOnNewDocument", { source: CAPTURE_HOLD_SOURCE }); // Chrome then reports the page focused even while another window is in front, so no blur fires. await session.send("Emulation.setFocusEmulationEnabled", { enabled: true }).catch(() => {}); } async function installReadinessSignal(session: CdpSession): Promise { if (readinessInstalled.has(session)) return; readinessInstalled.add(session); // Runs at document start, before exists — hence the two-stage attach. const source = `(() => { const check = () => { const root = document.documentElement; if (root === null) return false; const status = root.dataset.jgCapture ?? null; if (status === null) return false; const state = { status, error: root.dataset.jgCaptureError ?? null }; try { window.${CAPTURE_SIGNAL_BINDING}(JSON.stringify(state)); } catch { /* binding gone */ } return true; }; const attach = () => { const root = document.documentElement; if (root === null) return false; check(); new MutationObserver(check).observe(root, { attributes: true, attributeFilter: ["data-jg-capture", "data-jg-capture-error"] }); return true; }; if (attach()) return; const pending = new MutationObserver(() => { if (attach()) pending.disconnect(); }); pending.observe(document, { childList: true }); })()`; await session.send("Runtime.addBinding", { name: CAPTURE_SIGNAL_BINDING }); await session.send("Page.addScriptToEvaluateOnNewDocument", { source }); } export interface CaptureReadinessOptions { /** Older native SDK pages without a handshake may prove readiness with settled canvas pixels. */ legacyCanvas?: boolean; } const CAPTURE_READINESS_EXPR = `(() => { const canvas = document.querySelector("canvas"); return { status: document.documentElement.dataset.jgCapture ?? null, error: document.documentElement.dataset.jgCaptureError ?? null, stage: document.documentElement.dataset.jgCaptureStage ?? null, sizedCanvas: canvas !== null && canvas.clientWidth > 10 && canvas.clientHeight > 10 && canvas.width > 10 && canvas.height > 10 && document.querySelector("[data-shell-code-loading]") === null }; })()`; /** Navigate and surface browser/page failures instead of waiting for the capture timeout. */ export async function navigateCapturePage( session: CdpSession, url: string, timeoutMs: number, options: CaptureReadinessOptions = {}, ): Promise { let handshakeSeen = false; let pageFailure: string | undefined; let frameId: string | undefined; let signalled: { status: string | null; error: string | null; stage?: string | null; sizedCanvas?: boolean } | undefined; const requestFrames = new Map(); const pendingDocumentFailures: Array<{ frameId?: string | undefined; message: string }> = []; const offSignal = session.on("Runtime.bindingCalled", (params) => { if (params["name"] !== CAPTURE_SIGNAL_BINDING || typeof params["payload"] !== "string") return; try { signalled = JSON.parse(params["payload"]) as { status: string | null; error: string | null }; if (signalled.status !== null) handshakeSeen = true; } catch { /* malformed payload — the poll below still reads the real flag */ } }); const offException = session.on("Runtime.exceptionThrown", (params) => { pageFailure ??= exceptionMessage(params); }); const offRequest = session.on("Network.requestWillBeSent", (params) => { if (params["type"] !== "Document") return; if (typeof params["requestId"] === "string" && typeof params["frameId"] === "string") { requestFrames.set(params["requestId"], params["frameId"]); } }); const offLoadingFailed = session.on("Network.loadingFailed", (params) => { if (params["type"] !== "Document") return; const errorText = typeof params["errorText"] === "string" ? params["errorText"] : "unknown error"; const failedFrameId = typeof params["requestId"] === "string" ? requestFrames.get(params["requestId"]) : undefined; const message = /ERR_CONNECTION_REFUSED|ERR_CONNECTION_RESET|ERR_EMPTY_RESPONSE/.test(errorText) ? `page load failed: nothing answered at ${new URL(url).origin} (${errorText}), so the dev server stopped before the page loaded` : `page load failed: ${errorText}`; if (frameId === undefined) pendingDocumentFailures.push({ frameId: failedFrameId, message }); else if (failedFrameId === undefined || failedFrameId === frameId) pageFailure ??= message; }); try { await session.send("Network.enable"); await installReadinessSignal(session).catch(() => {}); await holdCapturePlay(session).catch(() => {}); const navigation = await session.send("Page.navigate", { url }); if (typeof navigation["errorText"] === "string" && navigation["errorText"].length > 0) { throw new Error(`navigation failed for ${url}: ${navigation["errorText"]}`); } frameId = typeof navigation["frameId"] === "string" ? navigation["frameId"] : undefined; const matchingFailure = pendingDocumentFailures.find( (failure) => frameId === undefined || failure.frameId === undefined || failure.frameId === frameId, ); if (matchingFailure !== undefined) pageFailure ??= matchingFailure.message; const wait = readinessWait(timeoutMs); let lastStatus: string | null = null; let stage: string | null = null; // The pushed signal is the fast path; the evaluate below is the backstop, polled slowly // so it does not itself compete with the page for the main thread. let nextPollAt = Date.now(); while (wait.goOn(lastStatus)) { if (pageFailure !== undefined) throw new Error(pageFailure); const remote = (signalled?.status === "ready" || signalled?.status === "error" ? signalled : undefined) ?? (Date.now() >= nextPollAt ? ((nextPollAt = Date.now() + 500), await session.evaluate<{ status: string | null; error: string | null; stage?: string | null; sizedCanvas?: boolean }>(CAPTURE_READINESS_EXPR)) : undefined); stage = remote?.stage ?? stage; if (remote?.status === "ready") return; if (remote?.status === "error") throw new Error(`capture error: ${remote.error ?? "unknown"}`); if (remote?.status != null) { handshakeSeen = true; lastStatus = remote.status; } if (options.legacyCanvas && !handshakeSeen && remote?.sizedCanvas) { const settled = await session.evaluate<{ status: string | null; error: string | null; sizedCanvas?: boolean }>( `new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(() => resolve(${CAPTURE_READINESS_EXPR}))))`, { awaitPromise: true }, ); if (settled?.status != null) handshakeSeen = true; if (settled?.status === "error") throw new Error(`capture error: ${settled.error ?? "unknown"}`); if (!handshakeSeen && settled?.sizedCanvas) { const regions = await readCapturePageState(session); const { bytes } = await captureViewportPng(session, { screencast: false }); const decoded = decodePng(bytes); const frame = computeShotMetrics(decoded.width, decoded.height, decoded.data); const viewport = computeShotMetrics(decoded.width, decoded.height, decoded.data, regions); const fresh = await session.evaluate<{ status: string | null; error: string | null }>(CAPTURE_READINESS_EXPR); if (fresh?.status != null) handshakeSeen = true; if (fresh?.status === "error") throw new Error(`capture error: ${fresh.error ?? "unknown"}`); if (pageFailure !== undefined) throw new Error(pageFailure); if (signalled?.status === "error") throw new Error(`capture error: ${signalled.error ?? "unknown"}`); if (!handshakeSeen && regions.region !== undefined && frame.nonblank && deadViewport(viewport) === null) { console.error("capture: legacy native canvas settled with nonblank pixels; SDK exposes no asset-ready handshake"); return; } } } await new Promise((resolve) => setTimeout(resolve, 25)); } if (pageFailure !== undefined) throw new Error(pageFailure); const href: unknown = await session.evaluate("location.href").catch(() => null); throw new Error(wait.failure(lastStatus, typeof href === "string" ? href : null, url, stage)); } finally { offSignal(); offException(); offRequest(); offLoadingFailed(); } } /** Navigate with one cache-bypassed retry for a transient post-HMR stale page. */ export async function navigateCapturePageWithRetry( session: CdpSession, url: string, serverBase: string, timeoutMs: number, maxAttempts = 2, options: CaptureReadinessOptions = {}, ): Promise { for (let attempt = 1; ; attempt += 1) { try { await navigateCapturePage(session, url, timeoutMs, options); const note = await session.evaluate(`document.documentElement.dataset.jgCaptureNote ?? null`); if (typeof note === "string" && note.length > 0) console.error(`capture: ${note}`); return; } catch (error) { const message = error instanceof Error ? error.message : String(error); if (!shouldRetryCapture({ attempt, maxAttempts, message })) throw error; const settleMs = retrySettleMs(attempt); console.error( `capture attempt ${attempt} failed (${message}) - reloading fresh once in case Vite was mid-rebuild, after ${settleMs}ms`, ); await new Promise((resolve) => setTimeout(resolve, settleMs)); const deadline = Date.now() + 5_000; while (Date.now() < deadline && !(await isUp(serverBase))) { await new Promise((resolve) => setTimeout(resolve, 200)); } await session.send("Network.setCacheDisabled", { cacheDisabled: true }); } } } /** Write bytes to a temp path then atomically swap into place (never a torn PNG). */ export function writePngAtomic(outPath: string, bytes: Buffer): void { const tmpPath = `${outPath}.tmp`; writeFileSync(tmpPath, bytes); if (existsSync(outPath)) unlinkSync(outPath); renameSync(tmpPath, outPath); } /** Filename suffix marking a half-res judge shot. */ export function sizeSuffix(size: SizeMode): string { return size === "half" ? "-half" : ""; } /** Validate a raw `--size` argument, throwing the shared usage error. */ export function parseSizeArg(value: string | undefined): SizeMode { if (value !== "full" && value !== "half") { throw new Error(`--size must be full or half (got ${value ?? "nothing"})`); } return value; } /** * `draft` is the iteration profile: half-size viewport and the low graphics tier (`?quality=low`, * pinned for the page only, never persisted). The tier itself is `--quality ` * and is independent of the viewport, so a perf or capture run can pin a real tier. */ export type CaptureQuality = GraphicsTier; /** Add the shell's graphics-tier pin to a capture URL; no tier leaves the URL untouched. */ export function applyCaptureQuality(url: URL, tier: GraphicsTier | undefined): URL { if (tier !== undefined) url.searchParams.set("quality", tier); return url; } /** Size a capture runs at: an explicit `--size` wins, otherwise `--draft` halves the viewport. */ export function sizeForDraft(draft: boolean, explicit: SizeMode | undefined): SizeMode { return explicit ?? (draft ? "half" : "full"); } /** Filename suffix naming a non-default tier, so an ultra shot never overwrites the high one. */ export function qualitySuffix(tier: GraphicsTier | undefined): string { return tier === undefined || tier === "high" ? "" : `-${tier}`; } /** Filename suffix marking a draft shot, so it never overwrites or passes for a full one. */ export function draftSuffix(draft: boolean): string { return draft ? "-draft" : ""; } /** * Throw when the page's reported tier is not the one `--quality` asked for. A tier flag that * changes nothing is worse than no flag: the comparison would be two runs at the game's default * and nobody would know until the numbers came out identical. */ export function assertQualityApplied(requested: GraphicsTier, reported: string | null): void { if (reported === null || reported.length === 0) { throw new Error(`--quality ${requested} never reached the page — no graphics tier was reported (data-jg-quality). The run would prove the game's default tier.`); } if (reported !== requested) { throw new Error(`--quality ${requested} did not take — the page reports tier ${reported}, so this run would prove the wrong tier.`); } } /** The graphics tier the page reports it resolved (`data-jg-quality`), or null when it reports none. */ export async function readReportedQuality(session: CdpSession): Promise { const value = await session.evaluate(`document.documentElement.dataset.jgQuality ?? null`); return typeof value === "string" && value.length > 0 ? value : null; } export interface BrowserSession { /** CDP debug port the page target lives on. */ debugPort: number; /** The Chrome we launched, or null when attached to an existing/daemon one. */ chrome: ChromeProcess | null; } export interface WithBrowserSessionOptions { /** Leave the derived warm debug port instead of a random one. */ keep: boolean; /** Attach to an already-running Chrome on this port (skips launch/kill). */ connect?: number | undefined; /** Base per-shot timeout; the hard watchdog defaults to this + 120s. */ timeoutMs: number; /** Dev server to tear down alongside Chrome when not left warm. */ server?: ChildProcess | null; /** Native persistent server pid when no ChildProcess handle is retained on Windows. */ serverPid?: number | undefined; /** Pre-resolved debug port (daemon attach) — overrides keep/connect derivation. */ debugPort?: number | undefined; /** Attach without launching even without `--connect` (daemon). */ attach?: boolean; /** Leave Chrome + server running after `fn` resolves (warm loop / daemon). */ leaveWarm?: boolean; /** user-data-dir prefix passed to {@link launchChrome}. */ chromePrefix?: string; /** Override the hard watchdog budget (default `timeoutMs + 120_000`). */ hardDeadlineMs?: number; /** Override the derived warm debug port. */ warmPort?: number; /** Replace the real Chrome launch (tests own the profile dir they hand back). */ launch?: (debugPort: number, prefix?: string, options?: ChromeLaunchOptions) => ChromeProcess; /** Replace the page-target probe {@link startBrowser} uses (tests own the fake browser). */ pageProbe?: (debugPort: number, profilePath: string) => Promise; /** rAF clock the launched Chrome runs on. Default is the display's commit clock. */ frameClock?: FrameClock; /** Launch a real (off-screen) window instead of headless Chrome; only `--headed` sets it. */ headed?: boolean | undefined; /** * Wait for a turn in a shared browser before the session starts; resolves with its release. * The wait sits outside the hard deadline, which covers only this run's own work. */ turn?: (() => Promise<() => Promise>) | undefined; /** `normal` for a session whose product is a frame time; see {@link ChromeLaunchOptions.priority}. */ chromePriority?: "normal" | "inherit" | undefined; } /** What the current session's Chrome runs at, for the record a measurement writes. */ export type SessionChromePriority = PriorityLabel | "daemon"; let sessionPriority: SessionChromePriority | null = null; let sessionChromePid: number | null = null; /** * The priority of the Chrome the latest {@link withBrowserSession} launched, `daemon` when it * attached to a browser another process owns, or null before the first session. Read live while * that Chrome runs, because something outside the run (Owl's machine-wide sweep) may have changed * it since launch; after it exits, the last value read stays, so a mode's closing summary can say * what its browser ran at. */ export function sessionChromePriority(): SessionChromePriority | null { if (sessionChromePid !== null) { try { sessionPriority = priorityLabel(getPriority(sessionChromePid)); } catch { sessionChromePid = null; } } return sessionPriority; } /** * Own the browser-driver shell shared by shoot and drive: derive the debug * port, launch-or-attach Chrome through {@link startBrowser} (one retried * handshake with a fresh profile), arm the hard-deadline watchdog, run `fn`, * then force-kill Chrome + dev server unless left warm. `fn` returns the * process exit code (defaults to 0); a throw is reported and yields 1. */ export async function withBrowserSession( options: WithBrowserSessionOptions, fn: (session: BrowserSession) => Promise, ): Promise { const warmPort = options.warmPort ?? resolveWarmChromePort(); const attach = options.attach ?? false; // 0 asks the browser for a free port, so two captures on one machine never pick the same one. let debugPort = options.debugPort ?? options.connect ?? (options.keep ? warmPort : 0); const leaveWarm = options.leaveWarm ?? options.keep; const hardDeadlineMs = options.hardDeadlineMs ?? options.timeoutMs + 120_000; let chrome: ChromeProcess | null = null; let exitCode = 0; let releaseTurn: (() => Promise) | null = null; if (options.turn !== undefined) { markStep("wait for a turn in the shared browser"); try { releaseTurn = await options.turn(); } catch (error) { console.error(error instanceof Error ? error.message : error); return 1; } } // Time `fn` spends queued for the perf lock is given back: the deadline covers this run's own work. const cancelWatchdog = pausableDeadline(hardDeadlineMs, () => pausedTotal(currentStep()), () => { console.error( `browser session: still running after the ${Math.round(hardDeadlineMs / 1000)}s hard deadline, ${describeHang(currentStep())} — force-killing Chrome and dev server`, ); // Daemon-owned Chrome/server are never handed to us (both null here), so // these are no-ops when attached — safe to run unconditionally. killProcessTree(chrome); killProcessTree(options.server ?? null); killPid(options.serverPid, true); if (chrome !== null) removeProfileDir(chrome.userDataDir); process.exit(124); }, { unref: true }); try { markStep( options.connect !== undefined || attach ? `attach to Chrome :${debugPort}` : `launch Chrome${debugPort === 0 ? " on a free port" : ` :${debugPort}`}`, ); if (options.connect !== undefined || attach) { await waitForDebugger(debugPort, 5_000); sessionChromePid = null; sessionPriority = "daemon"; } else { const started = await startBrowser({ debugPort, ...(options.chromePrefix === undefined ? {} : { prefix: options.chromePrefix }), ...(options.launch === undefined ? {} : { launch: options.launch }), ...(options.pageProbe === undefined ? {} : { pageProbe: options.pageProbe }), ...(options.frameClock === undefined ? {} : { frameClock: options.frameClock }), ...(options.headed === true ? { headed: true } : {}), ...(options.chromePriority === undefined ? {} : { priority: options.chromePriority }), }); chrome = started.browser; debugPort = started.debugPort; // A test's fake launch records nothing; its session then reports the launcher's own priority. sessionChromePid = chrome.pid !== undefined && launchedPriorities.has(chrome.pid) ? chrome.pid : null; sessionPriority = (chrome.pid === undefined ? undefined : launchedPriorities.get(chrome.pid)) ?? currentPriority(); } markStep("run the capture"); const result = await fn({ debugPort, chrome }); if (typeof result === "number") exitCode = result; } catch (error) { exitCode = 1; console.error(error instanceof Error ? error.message : error); } finally { cancelWatchdog(); await releaseTurn?.().catch(() => {}); if (!leaveWarm) { launchedProfiles.delete(debugPort); killProcessTree(chrome); killProcessTree(options.server ?? null); killPid(options.serverPid, true); if (chrome !== null) { await waitForPidExit(chrome.pid); removeProfileDir(chrome.userDataDir); } } else if (chrome !== null) { // A warm browser and the daemon state file own this profile now, not this process. The run // record goes too: the next capture must not read this dead pid as an orphaned browser. detachProfileDir(chrome.userDataDir); try { unlinkSync(join(chrome.userDataDir, PROFILE_RUN_FILE)); } catch { /* no record to hand over */ } } } return exitCode; }