ravensight-playtest 0.3.2 → 0.5.0

package/src/run/drivers/godot.js

@@ -9,8 +9,8 @@
 //
 // Both of the differences ./driver.js names fall on this driver's side: a
 // string `click` target is a scene tree node path, not an accessibility ref,
-// and `stop()` answers `videoPath: null` with a `frames/` sequence beside it,
-// because stitching is ffmpeg's job and ffmpeg stays optional.
+// and recording uses the selected viewport, with optional local ffmpeg encoding.
+// Without an encoder or a rendered viewport it reports unsupported, never a video.
 //
 // What happens at launch, in order:
 //   1. find the developer's own Godot binary (spec 17 detection order),
@@ -34,6 +34,8 @@ import {
   prepareProjectCopy,
 } from './godot-project.js';
 import { DriverRpcError, GodotRpcClient } from './godot-rpc.js';
+import { detectFfmpeg } from '../../detect.js';
+import { recordingLimits, recordingViewport, recordingDirectory, recordingMetadata, saveRecording, encodeFrames } from './recording.js';
 
 export const DRIVER_NAME = 'godot_driver';
 export const BOOT_TIMEOUT_MS = 60000;
@@ -124,6 +126,9 @@ export class GodotDriver {
     prepare = prepareProjectCopy,
     choosePort = findFreePort,
     now = () => Date.now(),
+    recording = {},
+    detectEncoder = detectFfmpeg,
+    encode = encodeFrames,
   } = {}) {
     this.name = DRIVER_NAME;
     this.projectDir = projectDir;
@@ -148,6 +153,11 @@ export class GodotDriver {
     this._prepare = prepare;
     this._choosePort = choosePort;
     this._now = now;
+    this._recordingLimits = recordingLimits(recording);
+    this._detectEncoder = detectEncoder;
+    this._encode = encode;
+    this._frames = [];
+    this._frameBytes = 0;
 
     this.rpc = null;
     this.child = null;
@@ -178,8 +188,13 @@ export class GodotDriver {
     return !this._stopped && this.exitCode !== null && this.exitCode !== 0;
   }
 
-  async launch({ recordVideo = false, viewport } = {}) {
+  async launch({ recordVideo = false, viewport, signal } = {}) {
+    if (signal?.aborted) throw new Error('run canceled before game launch');
     if (viewport) this.viewport = viewport;
+    if (recordVideo) {
+      const size = recordingViewport(this.viewport, this._recordingLimits);
+      this.viewport = { w: size.width, h: size.height };
+    }
     if (!this.projectDir) throw new Error('godot driver needs a projectDir');
     this.godot = this.godotPath
       ? await this._detect({ explicitPath: this.godotPath, env: this.env, projectDir: this.projectDir })
@@ -198,6 +213,7 @@ export class GodotDriver {
       this.logPath = this.runDir ? path.join(this.runDir, 'godot.log') : null;
 
       const args = ['--path', this.projectCopy];
+      if (recordVideo) args.push('--audio-driver', 'Dummy');
       if (this.headless) args.push('--headless');
       else args.push('--resolution', `${this.viewport.w}x${this.viewport.h}`);
       args.push('--', '--ravensight-driver', `--ravensight-driver-port=${this.port}`);
@@ -226,6 +242,10 @@ export class GodotDriver {
       }
 
       if (recordVideo) await this._startFrameCapture();
+      this._signal = signal;
+      this._onAbort = () => { void this.stop({ reason: 'canceled' }).catch(() => {}); };
+      signal?.addEventListener('abort', this._onAbort, { once: true });
+      if (signal?.aborted) { await this.stop({ reason: 'canceled' }); throw new Error('run canceled during game launch'); }
       return {};
     } catch (error) {
       // Everything past this point has already spawned a game and copied a
@@ -289,6 +309,10 @@ export class GodotDriver {
       this.exitCode = code;
       this.exitSignal = signal;
       if (log) log.end();
+      if (!this._stopped && this._recordingStartedAt != null) {
+        this._endCapture(code === 0 ? 'game_exited' : 'game_crashed');
+        void this._finalizeRecording().catch(() => {});
+      }
     });
     this.child.on('error', (error) => {
       this._consoleQueue.push({ kind: 'driver', text: `failed to launch Godot: ${error.message}` });
@@ -501,43 +525,114 @@ export class GodotDriver {
     this.chapters.push({ title, at: this._startedAt === null ? 0 : this._now() - this._startedAt });
   }
 
-  /**
-   * Video on a local Godot run is a sequence of stills, not a container: the
-   * frames land in the run dir and whoever wants a webm stitches them with
-   * ffmpeg, which stays optional for the CLI.
-   */
-  async _startFrameCapture({ fps = 4 } = {}) {
-    if (this.headless || !this.runDir) return;
-    this._framesDir = path.join(this.runDir, 'frames');
-    await fs.mkdir(this._framesDir, { recursive: true });
-    this._videoTimer = setInterval(() => {
-      void this._captureFrame();
-    }, Math.round(1000 / fps));
-    if (typeof this._videoTimer.unref === 'function') this._videoTimer.unref();
+  // Capture only this project's viewport. No screen/audio device is opened.
+  async _startFrameCapture() {
+    this._recordingStartedAt = this._now();
+    if (this.runDir) this._framesDir = await recordingDirectory(this.runDir);
+    if (this.headless || !this.runDir) {
+      this._recordingUnsupported = this.headless ? 'headless_no_viewport' : 'run_directory_required';
+      return;
+    }
+    this._encoder = await this._detectEncoder();
+    if (!this._encoder?.path) {
+      this._recordingUnsupported = 'encoder_unavailable';
+      this._consoleQueue.push({ kind: 'driver', text: 'Video unavailable: install optional ffmpeg or set RAVENSIGHT_FFMPEG. No video was recorded.' });
+      return;
+    }
+    this._recordingStartedAt = this._now();
+    await this._captureFrame();
+    if (this._captureEndedAt != null) return;
+    this._videoTimer = setInterval(() => { void this._captureFrame(); }, Math.round(1000 / this._recordingLimits.fps));
+    this._videoTimer.unref?.();
+    this._videoDeadline = setTimeout(() => this._endCapture('duration_limit'), this._recordingLimits.durationMs);
+    this._videoDeadline.unref?.();
+  }
+
+  _endCapture(reason) {
+    if (this._captureEndedAt != null) return;
+    this._captureEndedAt = Math.min(this._now(), this._recordingStartedAt + this._recordingLimits.durationMs);
+    this._captureReason = reason;
+    clearInterval(this._videoTimer);
+    clearTimeout(this._videoDeadline);
+    this._videoTimer = null;
   }
 
   async _captureFrame() {
-    if (this._capturing || this._stopped) return;
-    this._capturing = true;
-    try {
-      const shot = await this._rawScreenshot();
-      if (!shot) return;
-      this._frameIndex += 1;
-      const file = path.join(this._framesDir, `${String(this._frameIndex).padStart(6, '0')}.png`);
-      await fs.writeFile(file, Buffer.from(shot.data, 'base64'));
-    } catch {
-      // A dropped frame is never worth interrupting a run for.
-    } finally {
-      this._capturing = false;
+    if (this._capturePromise || this._stopped || this._captureEndedAt != null) return;
+    if (this._now() - this._recordingStartedAt >= this._recordingLimits.durationMs) {
+      this._endCapture('duration_limit'); return;
     }
+    const at = this._now();
+    this._capturePromise = (async () => {
+      try {
+        const shot = await this._rawScreenshot();
+        if (!shot) return;
+        const max = this._recordingLimits.singleFrameBytes;
+        if (typeof shot.data !== 'string' || shot.data.length > Math.ceil(max / 3) * 4) {
+          this._endCapture('frame_size_limit'); return;
+        }
+        const bytes = Buffer.from(shot.data, 'base64');
+        if (bytes.length > max || this._frameBytes + bytes.length > this._recordingLimits.frameBytes) {
+          this._endCapture('frame_bytes_limit'); return;
+        }
+        const name = `${String(this._frameIndex + 1).padStart(6, '0')}.png`;
+        await fs.writeFile(path.join(this._framesDir, name), bytes, { flag: 'wx', mode: 0o600 });
+        this._frames.push({ name, at });
+        this._frameIndex += 1;
+        this._frameBytes += bytes.length;
+      } catch {
+        // A disconnected/crashed game can still leave a useful partial recording.
+        this._endCapture('capture_failed');
+      }
+    })();
+    try { await this._capturePromise; } finally { this._capturePromise = null; }
   }
 
-  async stop({ removeTemp = !this.keepTemp } = {}) {
+  _finalizeRecording() {
+    if (this._finalizePromise) return this._finalizePromise;
+    this._finalizePromise = (async () => {
+      if (this._recordingStartedAt == null) return {};
+      await this._capturePromise;
+      const endedAt = this._captureEndedAt ?? this._now();
+      let metadata = recordingMetadata({ driver: this.name, startedAt: this._recordingStartedAt, endedAt,
+        reason: this._recordingUnsupported ?? this._captureReason ?? 'stopped',
+        status: this._recordingUnsupported ? 'unsupported' : 'failed', frameCount: this._frameIndex,
+        captureFpsLimit: this._recordingLimits.fps, timeOrigin: 'first-viewport-frame',
+      });
+      let videoPath = null;
+      if (!this._recordingUnsupported && this._framesDir) {
+        try {
+          const encoded = await this._encode({ directory: this._framesDir, frames: this._frames, endedAt,
+            encoder: this._encoder, limits: this._recordingLimits });
+          videoPath = path.join(this.runDir, 'session.mp4');
+          await fs.rename(encoded.file, videoPath);
+          metadata = { ...metadata, status: ['stopped', 'completed', 'game_exited'].includes(metadata.reason) ? 'complete' : 'partial',
+            relativePath: 'session.mp4', mimeType: encoded.mimeType, bytes: encoded.bytes,
+            durationMs: encoded.durationMs, durationSource: encoded.durationSource ?? 'frame-timestamps',
+            firstFrameOffsetMs: this._frames[0].at - this._recordingStartedAt };
+          if (encoded.truncated) { metadata.status = 'partial'; metadata.reason = 'size_limit'; }
+        } catch (error) {
+          metadata.reason = ['no_frames', 'encoder_unavailable', 'encoding_timeout', 'encoding_failed'].includes(error.message) ? error.message : 'encoding_failed';
+        }
+      }
+      // Captured game frames are local temporary data, never upload artifacts.
+      if (this._framesDir) await fs.rm(this._framesDir, { recursive: true, force: true });
+      if (this.runDir) await saveRecording(this.runDir, metadata);
+      return { videoPath, recording: metadata };
+    })();
+    return this._finalizePromise;
+  }
+
+  stop(options = {}) {
+    if (!this._stopPromise) this._stopPromise = Promise.resolve().then(() => this._stop(options));
+    return this._stopPromise;
+  }
+
+  async _stop({ removeTemp = !this.keepTemp, reason = 'stopped' } = {}) {
     this._stopped = true;
-    if (this._videoTimer) {
-      clearInterval(this._videoTimer);
-      this._videoTimer = null;
-    }
+    this._signal?.removeEventListener('abort', this._onAbort);
+    if (this._recordingStartedAt != null) this._endCapture(reason);
+    await this._capturePromise;
     if (this.rpc && !this.rpc.closed) {
       await this.rpc.call('quit', { code: 0 }, { timeoutMs: 2000 }).catch(() => {});
     }
@@ -549,12 +644,9 @@ export class GodotDriver {
       this.projectCopy = null;
     }
     return {
-      videoPath: null,
-      framesDir: this._framesDir,
-      frameCount: this._frameIndex,
-      chapters: this.chapters,
-      logPath: this.logPath,
-      exitCode: this.exitCode,
+      videoPath: null, ...await this._finalizeRecording(),
+      frameCount: this._frameIndex, chapters: this.chapters,
+      logPath: this.logPath, exitCode: this.exitCode,
     };
   }
 

package/src/run/drivers/recording.js

@@ -0,0 +1,148 @@
+// Local recording only. This module never uploads, reads credentials, or captures
+// a display/audio device. Final files use the existing opt-in upload allowlist.
+import { execFile } from 'node:child_process';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { detectFfmpeg } from '../../detect.js';
+import { MAX_VIDEO_BYTES } from '../../upload/allowlist.js';
+
+const execute = promisify(execFile);
+export const RECORDING_LIMITS = Object.freeze({
+  durationMs: 15 * 60 * 1000,
+  videoBytes: MAX_VIDEO_BYTES,
+  frameBytes: 256 * 1024 * 1024,
+  singleFrameBytes: 4 * 1024 * 1024,
+  width: 1280,
+  height: 720,
+  fps: 10,
+  finalizeMs: 60000,
+});
+
+// Test seams may lower limits, never raise production ceilings.
+export function recordingLimits(overrides = {}) {
+  const out = { ...RECORDING_LIMITS };
+  for (const [key, value] of Object.entries(overrides)) {
+    if (!(key in out) || !Number.isSafeInteger(value) || value < 1 || value > out[key]) {
+      throw new Error(`invalid recording limit: ${key}`);
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+export function recordingViewport(viewport, limits = RECORDING_LIMITS) {
+  const width = Number(viewport?.width ?? viewport?.w ?? limits.width);
+  const height = Number(viewport?.height ?? viewport?.h ?? limits.height);
+  if (!Number.isSafeInteger(width) || !Number.isSafeInteger(height) || width < 1 || height < 1) {
+    throw new Error('recording viewport must have positive integer dimensions');
+  }
+  const scale = Math.min(1, limits.width / width, limits.height / height);
+  return { width: Math.max(1, Math.floor(width * scale)), height: Math.max(1, Math.floor(height * scale)) };
+}
+
+export async function recordingDirectory(runDir) {
+  await fs.mkdir(runDir, { recursive: true });
+  // Reusing an old playable recording after a failed capture is worse than
+  // reporting no recording. Do not silently replace it either.
+  for (const name of ['session.webm', 'session.mp4', 'recording.json']) {
+    if (await fs.lstat(path.join(runDir, name)).then(() => true, e => { if (e.code === 'ENOENT') return false; throw e; })) {
+      throw new Error(`recording output already exists: ${name}`);
+    }
+  }
+  const directory = await fs.mkdtemp(path.join(runDir, '.recording-'));
+  await fs.chmod(directory, 0o700);
+  return directory;
+}
+
+export function recordingMetadata({ driver, startedAt, endedAt, reason = 'stopped', ...details }) {
+  return {
+    schemaVersion: 1, driver, status: 'failed', audio: false,
+    startedAt: new Date(startedAt).toISOString(), endedAt: new Date(endedAt).toISOString(),
+    durationMs: Math.max(0, endedAt - startedAt), durationSource: 'capture-clock',
+    relativePath: null, mimeType: null, bytes: 0, reason, stopReason: reason, ...details,
+  };
+}
+
+export async function saveRecording(runDir, metadata) {
+  const pending = path.join(runDir, '.recording.json.tmp');
+  await fs.writeFile(pending, `${JSON.stringify(metadata, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
+  await fs.rename(pending, path.join(runDir, 'recording.json'));
+  return metadata;
+}
+
+export async function videoInfo(file, { limits = RECORDING_LIMITS } = {}) {
+  const stat = await fs.lstat(file);
+  if (!stat.isFile() || stat.size < 16 || stat.size > limits.videoBytes) throw new Error('invalid_video_size');
+  const handle = await fs.open(file, 'r');
+  const head = Buffer.alloc(16);
+  try { await handle.read(head, 0, head.length, 0); } finally { await handle.close(); }
+  const webm = head.subarray(0, 4).equals(Buffer.from([0x1a, 0x45, 0xdf, 0xa3]));
+  const mp4 = head.toString('ascii', 4, 8) === 'ftyp';
+  if (!webm && !mp4) throw new Error('invalid_video_container');
+  return { bytes: stat.size, mimeType: webm ? 'video/webm' : 'video/mp4' };
+}
+
+// ffprobe is optional for Playwright, whose successful close finalizes WebM.
+// When installed, verify the actual media timeline and absence of audio. A
+// present tool rejecting the media is a failure, never a fallback success.
+export async function probeVideo(file, { limits = RECORDING_LIMITS, run = execute } = {}) {
+  const info = await videoInfo(file, { limits });
+  const binary = process.env.RAVENSIGHT_FFPROBE || (process.env.RAVENSIGHT_FFMPEG
+    ? path.join(path.dirname(process.env.RAVENSIGHT_FFMPEG), process.platform === 'win32' ? 'ffprobe.exe' : 'ffprobe') : 'ffprobe');
+  let stdout;
+  try {
+    ({ stdout } = await run(binary, ['-v', 'error', '-show_entries', 'stream=codec_type,width,height:format=duration', '-of', 'json', file],
+      { timeout: 10000, killSignal: 'SIGKILL', maxBuffer: 64 * 1024, windowsHide: true }));
+  } catch (error) {
+    if (error.code === 'ENOENT') return info;
+    throw new Error('invalid_video_media');
+  }
+  try {
+    const media = JSON.parse(stdout);
+    const video = media.streams.filter(stream => stream.codec_type === 'video');
+    const durationMs = Math.round(Number(media.format.duration) * 1000);
+    if (video.length !== 1 || media.streams.some(stream => stream.codec_type === 'audio')
+      || !Number.isSafeInteger(durationMs) || durationMs <= 0 || durationMs > limits.durationMs
+      || video[0].width > limits.width || video[0].height > limits.height) throw new Error();
+    return { ...info, durationMs, durationSource: 'media', width: video[0].width, height: video[0].height };
+  } catch { throw new Error('invalid_video_media'); }
+}
+
+/** Encode only numbered PNGs we wrote, with their actual capture timestamps. */
+export async function encodeFrames({ directory, frames, endedAt, limits = RECORDING_LIMITS, encoder, run = execute, inspect = probeVideo }) {
+  if (!frames.length) throw new Error('no_frames');
+  const detected = encoder ?? await detectFfmpeg();
+  if (!detected.path) throw new Error('encoder_unavailable');
+  const first = frames[0].at;
+  const durationMs = Math.min(limits.durationMs, Math.max(1000 / limits.fps, endedAt - first));
+  const lines = ['ffconcat version 1.0'];
+  for (let i = 0; i < frames.length; i++) {
+    const frame = frames[i];
+    if (!/^\d{6}\.png$/.test(frame.name) || !Number.isFinite(frame.at) || (i && frame.at < frames[i - 1].at)) {
+      throw new Error('invalid_frame_timeline');
+    }
+    const end = Math.min(first + durationMs, frames[i + 1]?.at ?? first + durationMs);
+    lines.push(`file '${frame.name}'`, `duration ${Math.max(0.001, (end - frame.at) / 1000).toFixed(6)}`);
+  }
+  lines.push(`file '${frames.at(-1).name}'`);
+  const list = path.join(directory, 'frames.ffconcat');
+  await fs.writeFile(list, `${lines.join('\n')}\n`, { mode: 0o600, flag: 'wx' });
+  const output = path.join(directory, 'encoded.mp4');
+  try {
+    await run(detected.path, [
+      '-nostdin', '-hide_banner', '-loglevel', 'error', '-n',
+      '-protocol_whitelist', 'file', '-f', 'concat', '-safe', '1', '-i', list,
+      '-an', '-vf', `scale=${limits.width}:${limits.height}:force_original_aspect_ratio=decrease,pad=ceil(iw/2)*2:ceil(ih/2)*2,setsar=1`,
+      '-c:v', 'libx264', '-preset', 'veryfast', '-crf', '23', '-pix_fmt', 'yuv420p',
+      '-r', '30', '-t', (durationMs / 1000).toFixed(3), '-fs', String(limits.videoBytes - 4096),
+      '-movflags', '+faststart', output,
+    ], { cwd: directory, timeout: limits.finalizeMs, killSignal: 'SIGKILL', maxBuffer: 64 * 1024, windowsHide: true });
+    const info = await inspect(output, { limits });
+    return { file: output, durationMs, ...info, truncated: info.durationMs != null && info.durationMs + 150 < durationMs };
+  } catch (error) {
+    await fs.rm(output, { force: true });
+    // Never include process output, a game path, or inherited environment in a report.
+    throw new Error(error.killed ? 'encoding_timeout' : 'encoding_failed');
+  }
+}

package/src/run/drivers/web.js

@@ -1,4 +1,5 @@
-import { mkdir, rename, stat, readdir } from 'node:fs/promises';
+import { mkdir, rename, stat, readdir, rm, chmod } from 'node:fs/promises';
+import { recordingLimits, recordingViewport, recordingDirectory, recordingMetadata, saveRecording, probeVideo } from './recording.js';
 import path from 'node:path';
 import {
   DriverError,
@@ -1121,7 +1122,7 @@ export const CHECK_PLAYTEST_IDENTITY = Object.freeze({ token: 'check', runId: nu
  *   the one the platform implies
  * @returns {Object} a driver
  */
-export function createWebDriver({ importer, headless = true, playtest = null, platform = process.platform, modifier = null } = {}) {
+export function createWebDriver({ importer, headless = true, playtest = null, platform = process.platform, modifier = null, recording = {}, now = () => Date.now(), inspectVideo = probeVideo } = {}) {
   const editModifier = modifier === 'Meta' || modifier === 'Control' ? modifier : platformModifier(platform);
   let browser = null;
   let context = null;
@@ -1129,6 +1130,16 @@ export function createWebDriver({ importer, headless = true, playtest = null, pl
   let target = null;
   let runDirectory = null;
   let videoRequested = false;
+  const limits = recordingLimits(recording);
+  let captureDirectory = null;
+  let captureStartedAt = null;
+  let stopPromise = null;
+  let captureTimer = null;
+  let captureDeadline = null;
+  let runSignal = null;
+  let onAbort = null;
+  let inspecting = false;
+  let terminalReason = null;
   let step = 0;
   let shots = 0;
   let lastHash = null;
@@ -1344,6 +1355,77 @@ export function createWebDriver({ importer, headless = true, playtest = null, pl
     return observationHash(after);
   }
 
+  function stop({ reason = 'stopped' } = {}) {
+    if (stopPromise) return stopPromise;
+    terminalReason ??= reason;
+    stopPromise = Promise.resolve().then(finalize);
+    return stopPromise;
+  }
+
+  async function finalize() {
+    clearInterval(captureTimer);
+    clearTimeout(captureDeadline);
+    runSignal?.removeEventListener('abort', onAbort);
+    const endedAt = now();
+    let videoPath = null;
+    let promotedPath = null;
+    let finalized = true;
+    // Only the explicitly selected page's handle may become session.webm.
+    const video = videoRequested && page && typeof page.video === 'function' ? page.video() : null;
+    try { if (context) await withTimeout(context.close(), 15000); } catch { finalized = false; }
+    let metadata = null;
+    if (videoRequested && captureStartedAt != null) {
+      metadata = recordingMetadata({ driver: 'playwright_web', startedAt: captureStartedAt, endedAt,
+        reason: terminalReason, timeOrigin: 'page-creation-request' });
+      if (video) {
+        try {
+          let source;
+          if (typeof video.saveAs === 'function') {
+            source = path.join(captureDirectory, 'selected-final.webm');
+            await withTimeout(video.saveAs(source), 15000);
+          } else source = await withTimeout(video.path(), 15000);
+          // No arbitrary run-directory scan or old-file fallback on a crash.
+          if (path.dirname(path.resolve(source)) !== path.resolve(captureDirectory)) throw new Error('foreign_video_path');
+          const info = await inspectVideo(source, { limits });
+          if (info.mimeType !== 'video/webm') throw new Error('invalid_video_container');
+          const destination = path.join(runDirectory, 'session.webm');
+          await rename(source, destination);
+          promotedPath = destination;
+          await chmod(destination, 0o600);
+          videoPath = destination;
+          metadata = { ...metadata, ...info, relativePath: 'session.webm',
+            status: finalized && ['stopped', 'completed'].includes(terminalReason) ? 'complete' : 'partial' };
+        } catch (error) {
+          if (promotedPath) await rm(promotedPath, { force: true });
+          videoPath = null;
+          metadata.reason = 'video_finalization_failed';
+          metadata.failure = ['invalid_video_size', 'invalid_video_container', 'invalid_video_media', 'foreign_video_path'].includes(error.message) ? error.message : 'recorder_unavailable';
+        }
+      } else metadata.reason = 'video_unavailable';
+    }
+    try { if (browser) await withTimeout(browser.close(), 15000); } catch { /* already closed or unavailable */ }
+    if (captureDirectory) await rm(captureDirectory, { recursive: true, force: true });
+    if (metadata) await saveRecording(runDirectory, metadata);
+    page = null;
+    context = null;
+    browser = null;
+    return { videoPath, ...(metadata ? { recording: metadata } : {}) };
+  }
+
+  async function inspectCapture() {
+    if (inspecting || stopPromise || !captureDirectory) return;
+    inspecting = true;
+    try {
+      let bytes = 0;
+      for (const name of await readdir(captureDirectory)) {
+        bytes += (await stat(path.join(captureDirectory, name))).size;
+      }
+      // Leave room for WebM's final index; oversize output is never published.
+      if (bytes >= Math.max(1, limits.videoBytes - 8 * 1024 * 1024)) await stop({ reason: 'size_limit' });
+    } catch { await stop({ reason: 'capture_failed' }); }
+    finally { inspecting = false; }
+  }
+
   return {
     name: 'playwright_web',
     supportsRefs: true,
@@ -1357,20 +1439,26 @@ export function createWebDriver({ importer, headless = true, playtest = null, pl
      * @param {boolean} [opts.recordVideo]
      * @param {{width: number, height: number}} [opts.viewport]
      */
-    async launch({ target: url, runDir, recordVideo = false, viewport = DEFAULT_VIEWPORT }) {
+    async launch({ target: url, runDir, recordVideo = false, viewport = DEFAULT_VIEWPORT, signal }) {
       if (!url) throw new DriverError('playwright_web needs a target URL', { fatal: true });
+      if (signal?.aborted) throw new DriverError('run canceled before browser launch');
       target = url;
       viewportSize = viewport || DEFAULT_VIEWPORT;
       runDirectory = runDir;
       videoRequested = Boolean(recordVideo);
+      if (videoRequested) {
+        viewport = recordingViewport(viewport, limits);
+        viewportSize = viewport;
+        captureDirectory = await recordingDirectory(runDir);
+      }
 
+      try {
       const playwright = await loadPlaywright(importer);
       await mkdir(runDir, { recursive: true });
-
-      browser = await playwright.chromium.launch({ headless });
+      browser = await playwright.chromium.launch({ headless, ...(videoRequested ? { args: ['--mute-audio'] } : {}) });
       context = await browser.newContext({
         viewport,
-        ...(videoRequested ? { recordVideo: { dir: runDir, size: viewport } } : {})
+        ...(videoRequested ? { recordVideo: { dir: captureDirectory, size: viewport }, permissions: [] } : {})
       });
       // The playtest identity goes in as an init script, not as
       // `extraHTTPHeaders`: a context header rides on every request the page
@@ -1387,7 +1475,34 @@ export function createWebDriver({ importer, headless = true, playtest = null, pl
       // One token per document: set again by every new document, kept by
       // pushState and hash route changes, which do not run init scripts.
       if (typeof context.addInitScript === 'function') await context.addInitScript(markDocument);
+      if (videoRequested && typeof context.route === 'function') {
+        const origin = new URL(url).origin;
+        await context.route('**/*', route => {
+          const request = route.request();
+          if (request.isNavigationRequest() && !request.frame().parentFrame() && new URL(request.url()).origin !== origin) {
+            return route.abort('blockedbyclient');
+          }
+          return route.continue();
+        });
+      }
+      captureStartedAt = videoRequested ? now() : null;
       page = await context.newPage();
+      if (videoRequested) {
+        // Context video may briefly allocate a popup file; close it immediately
+        // and discard all non-selected files during finalization.
+        page.on('popup', popup => { void popup.close().catch(() => {}); });
+        page.on('crash', () => { void stop({ reason: 'game_crashed' }).catch(() => {}); });
+        page.on('close', () => { if (!stopPromise) void stop({ reason: 'page_closed' }).catch(() => {}); });
+        captureTimer = setInterval(() => { void inspectCapture(); }, 250);
+        captureTimer.unref?.();
+        captureDeadline = setTimeout(() => { void stop({ reason: 'duration_limit' }).catch(() => {}); }, limits.durationMs);
+        captureDeadline.unref?.();
+      }
+      runSignal = signal;
+      onAbort = () => { void stop({ reason: 'canceled' }).catch(() => {}); };
+      signal?.addEventListener('abort', onAbort, { once: true });
+      if (signal?.aborted) { await stop({ reason: 'canceled' }); throw new DriverError('run canceled during browser launch'); }
+
       page.on('console', message => {
         if (message.type() !== 'error') return;
         let location = null;
@@ -1426,6 +1541,11 @@ export function createWebDriver({ importer, headless = true, playtest = null, pl
       if (response && response.status() >= 400) {
         throw new DriverError(`${url} answered ${response.status()}`, { fatal: true });
       }
+      } catch (error) {
+        await stop({ reason: 'launch_failed' }).catch(() => {});
+        if (captureDirectory) await rm(captureDirectory, { recursive: true, force: true }).catch(() => {});
+        throw error;
+      }
     },
 
     /** @returns {Promise<import('./driver.js').Observation>} */
@@ -1598,33 +1718,8 @@ export function createWebDriver({ importer, headless = true, playtest = null, pl
       return attachNetworkFailures(consoleBuffer.splice(0, consoleBuffer.length), networkFailures);
     },
 
-    /** @returns {Promise<{videoPath: string|null}>} */
-    async stop() {
-      let videoPath = null;
-      const video = videoRequested && page && typeof page.video === 'function' ? page.video() : null;
-      try {
-        if (context) await context.close();
-      } catch {
-        // A context that is already gone is not an error worth failing the
-        // run over; the report is already written by the time we get here.
-      }
-      if (video) {
-        try {
-          videoPath = await renameVideo(await video.path(), runDirectory);
-        } catch {
-          videoPath = await findVideo(runDirectory);
-        }
-      }
-      try {
-        if (browser) await browser.close();
-      } catch {
-        // Same: a closed browser is the desired end state either way.
-      }
-      page = null;
-      context = null;
-      browser = null;
-      return { videoPath };
-    }
+    /** Idempotent: cancellation, crashes and finally share one finalization. */
+    stop
   };
 }
 
@@ -1694,37 +1789,4 @@ export function attachNetworkFailures(entries, failures) {
   });
 }
 
-/**
- * Playwright names its recording with a random id. The upload allowlist and
- * the server's 90 day lifecycle rule are written against `session.webm`, so
- * the file is renamed rather than uploaded under whatever name it got.
- *
- * @param {string} source
- * @param {string} runDir
- * @returns {Promise<string>}
- */
-async function renameVideo(source, runDir) {
-  const target = path.join(runDir, 'session.webm');
-  if (!source || path.resolve(source) === path.resolve(target)) return target;
-  await rename(source, target);
-  return target;
-}
-
-/**
- * @param {string} runDir
- * @returns {Promise<string|null>}
- */
-async function findVideo(runDir) {
-  try {
-    const entries = await readdir(runDir);
-    const webm = entries.find(entry => entry.endsWith('.webm'));
-    if (!webm) return null;
-    const source = path.join(runDir, webm);
-    await stat(source);
-    return await renameVideo(source, runDir);
-  } catch {
-    return null;
-  }
-}
-
 export default createWebDriver;