@milkstraw/traceframe 0.6.2 → 0.7.0

package/README.md

@@ -61,15 +61,19 @@ The cursor and click pulses are always drawn at the full frame rate. Chromium ma
 
 Use `--capture-diagnostics` (`captureDiagnostics: true` with `record` or `recordPage`) to include `captureStats` in the result. It reports received frames, their timestamp span and rate, the largest forward timestamp jumps and delivery gaps, and out-of-order timestamps. `lateFrames` counts frames older than the first received frame or the last written frame; `overflowFrames` counts frames dropped at the 64 MiB capture-buffer limit, and `maxBufferedBytes` reports its peak use. `writeWaitMs` and `maxWriteWaitMs` measure total and maximum time waiting for frame-write callbacks, including the final static frame; they do not measure durable disk writes. Slow writes can delay frame acknowledgments and reduce what Chromium sends, even when the writer drop counters stay at zero. These measurements describe frames delivered by Chromium. They do not count distinct pictures or prove smoothness; a static page legitimately delivers few frames, and a 30 FPS video cannot supply 60 distinct source frames per second.
 
-`--capture-quality <1–100>` (`captureQuality` in either API) controls the JPEG frames exported by Chromium; the default remains 95. A lower setting such as 80 can reduce frame-export and transfer cost, with a loss of image detail. This is separate from the final MP4 encoder. Check representative moving content and text at the intended resolution before choosing it.
+`--capture-quality <1–100>` (`captureQuality` in either API) controls the JPEG frames exported by Chromium; the default is 85. In 3024 × 1964 tests with software rendering, 85 made captured frames about a third smaller than 95, with slightly lower CPU use and no visible difference in the exported MP4, and quality did not change how many frames Chromium captured. In [GPU rendering](#gpu-rendering) tests on machines whose CPU was the limit, 85 worked best: higher quality captured fewer pictures, and lower quality stalled video playback. Otherwise, use 95 for maximum detail, or a lower setting such as 75 for smaller temporary captures with softer fine detail. This is separate from the final MP4 encoder. Check representative moving content and text at the intended resolution before choosing a non-default value.
 
 Since v0.6.0, the retained raw file is `capture.mkv` instead of `capture.webm`; update scripts that inspect it. Final output remains MP4.
 
-Traceframe saves Chromium's JPEG frames and presentation timestamps directly into a temporary `capture.mkv`, then encodes the final MP4 after the flow ends. This avoids a live intermediate video encode and works with CPU or GPU browser rendering. Chromium frame timestamps are retained with microsecond precision; a 150 ms buffer orders delayed arrivals. The first received frame establishes the audio clock, so subsequently delivered frames older than that origin are dropped. Slow storage applies backpressure. Moving content needs more temporary disk space than an inter-frame codec: at high resolution, allow hundreds of megabytes for short takes and potentially gigabytes for longer ones. Static pages need only a few stored frames. If your temporary directory is backed by RAM, choose a disk-backed `--run-dir` for large takes and remove it afterward. The final renderer supplies the requested frame rate while keeping cursor animations smooth.
+Traceframe saves Chromium's JPEG frames and presentation timestamps directly into a temporary `capture.mkv`, then encodes the final MP4 after the flow ends. This avoids a live intermediate video encode and works with CPU or GPU browser rendering. Chromium frame timestamps are retained with microsecond precision; a 150 ms buffer orders delayed arrivals. The first received frame establishes the audio clock, so subsequently delivered frames older than that origin are dropped. Slow storage applies backpressure. The final renderer supplies the requested frame rate while keeping cursor animations smooth.
 
-GPU rendering and hardware video decoding can help the browser, but frame export still costs CPU. The bundled headless browser used software rendering on the tested Linux setup; selecting an executable or adding a GPU flag does not guarantee acceleration. For a caller-owned browser, configure and verify its GPU use before `recordPage`; use full Chromium for extensions. A GPU capability flag alone does not establish that the active video is hardware-decoded. When measuring performance, keep the browser version, source codec, viewport and device scale fixed, and compare recorded image updates and audio timing as well as file metadata.
+Moving content needs more temporary space than an inter-frame codec: at high resolution, allow hundreds of megabytes for short takes and potentially gigabytes for longer ones. Full-screen video recorded at 3024 × 1964 with GPU rendering took about 20–35 MB per second, roughly 1–2 GB per minute. Static pages need only a few stored frames. Captures are written to the system temporary directory, or to `--run-dir` (`runDirectory` in the API) when supplied.
 
-Start performance comparisons with the Chromium build bundled with Playwright. A custom `--browser` executable can have different screencast performance even when recording succeeds. Traceframe preserves your requested resolution and quality. If the workload cannot sustain the desired cadence, increasing the encoded FPS repeats existing frames; choose a lower quality or smaller dimensions explicitly if that tradeoff suits your recording.
+SSD wear is usually a minor concern for occasional recordings; no special storage setup is needed. For frequent recording batches, you can optionally use an existing RAM-backed temporary directory to reduce SSD writes, provided it can hold the complete capture and leave ample memory for Chromium and export. If RAM-backed temporary storage is too small for a take, choose a disk-backed `--run-dir` and remove it afterward.
+
+When measuring performance, use an otherwise idle machine, keep the browser version, source codec, viewport and device scale fixed, and compare recorded image updates and audio timing as well as file metadata.
+
+Start performance comparisons with the Chromium build bundled with Playwright. A custom `--browser` executable can have different screencast performance even when recording succeeds. Traceframe preserves your requested resolution and quality. If the workload cannot sustain the desired cadence, increasing the encoded FPS repeats existing frames. On a slower machine, smaller dimensions help most, so choose them explicitly if that tradeoff suits your recording: `--scale 1` leaves Chromium a quarter of the pixels to capture. In full-screen 4K60 video tests on a 2017 4-core laptop with GPU rendering, it saved about 60 distinct pictures per second, against 24–30 at scale 2. A lower encoded FPS shortens export but does not reduce capture work, and on a machine that cannot keep up, 60 FPS saves more distinct pictures than 30.
 
 For video-heavy flows, see [checking video playback](docs/recording-flows.md#check-video-playback), including optional page effects and media sizing.
 
@@ -77,6 +81,22 @@ Use `--run-dir .traceframe/runs/name` (`runDirectory` in the API) to keep the ra
 
 When available, failure output includes the error code, flow-file locations, elapsed recording time, and paths to artifacts saved for that attempt. Without `--run-dir`, temporary captures are removed and no failure screenshot is saved. See [diagnosing a failed take](docs/recording-flows.md#diagnose-a-failed-take).
 
+### GPU rendering
+
+By default, Traceframe tries hardware rendering (`--gpu auto`, or `gpu: 'auto'` in the API). Before navigation, it checks Chromium's compositing status and renderer. If acceleration is unavailable or the GPU browser fails to start, it closes that attempt and uses software rendering instead. Navigation, `ready` and the flow run only on the selected browser; a later recording failure is not retried. Use `--gpu off` (`gpu: 'off'`) to render in software without trying the GPU.
+
+Auto mode uses ANGLE's EGL backend on Linux and Chromium's platform backend elsewhere (Metal on the tested Mac). GPU access and driver support depend on the environment. These launch configurations were tested on Linux Intel/Mesa, Linux NVIDIA and Apple M3 Pro; Windows hardware acceleration has not been validated.
+
+The JSON result includes `graphics`. When hardware rendering was verified, `hardwareAccelerated` is `true` and `renderer` names the GPU. Otherwise `hardwareAccelerated` is `false`; after a failed GPU attempt, `fallbackReason` is `software-rendering` (the GPU browser drew in software), `graphics-check-unavailable` (Chromium did not report its graphics status) or `gpu-launch-failed`. These describe the startup check, not GPU utilization or a guarantee of smooth playback or correct drawing. If a recording shows black or garbled areas, record again with `--gpu off`.
+
+Traceframe does not change GPU drivers or permissions. On Linux, Chromium usually needs to open the GPU device (`/dev/dri/renderD*`), which the `render` group allows. That access is often missing over SSH, in services and in containers, so auto mode falls back to software. An administrator can add the account to the group with `sudo usermod -aG render <user>`; this takes effect in new login sessions and restarted services. In Docker, pass the device with `--device` and, for a non-root user, its group ID with `--group-add`.
+
+On a Linux laptop with Intel and NVIDIA GPUs, auto mode can pick the Intel one; `graphics.renderer` names the GPU used. To use the faster NVIDIA GPU, install NVIDIA's EGL library for the installed driver if it is missing (on Ubuntu, `libnvidia-gl-<driver version>`) and run Traceframe with `__EGL_VENDOR_LIBRARY_FILENAMES=/usr/share/glvnd/egl_vendor.d/10_nvidia.json`.
+
+Video decoding stays in software, and JPEG capture and final MP4 encoding still use the CPU; GPU rendering is not hardware video encoding. Smoother capture can store more frames and increase temporary storage and export time. For `recordPage`, configure and check the caller's browser yourself; its result has no `graphics`.
+
+GPU rendering matters most for video-heavy pages. In full-screen 4K60 video tests at 3024 × 1964, it recorded several times more distinct pictures per second than software rendering. With spare CPU, a local 4K60 test video reached about 60 pictures per second, while YouTube's player settled at about 45; Chromium's screencast has no setting to raise that. On slower machines, video decoding and Chromium's JPEG capture compete for the CPU. Full Chromium, which extensions need, captured noticeably fewer pictures than the default headless shell on Linux, so use the default shell unless the flow needs extensions.
+
 ## Write a flow
 
 The flow module exports a default function. Timing values are seconds:
@@ -184,13 +204,15 @@ The callback receives the same `page`, `signal` and five helpers as a flow file.
 
 Use Playwright 1.64.1 with Chromium, a fixed viewport, 100% browser zoom and an unscaled page. Traceframe checks the page's inner dimensions and visual viewport before starting capture, rejecting unsupported geometry with `CAPTURE_SIZE_MISMATCH`. `recordPage` keeps the page, context and browser open on success, failure and cancellation. It does not navigate, resize, run a `ready` hook, or change page timeouts. Your script owns setup and shutdown. The CLI and `record` continue to create and close their own browser.
 
-`page` and a function `flow` are required. `output`, `audio`, `postRoll`, `flowTimeout`, `runDirectory` and `signal` have the same meaning as in `record`, and the return value is the same recording summary. Set `initialPointer: { x, y }` to choose the starting cursor position. The page's viewport determines the dimensions; `scale` defaults to 1 and accepts 1 or 2, and `fps` defaults to 30 and accepts 30 or 60. Use these explicit settings instead of a preset. Browser setup options such as `url`, `browser`, `storageState`, viewport dimensions and `readyTimeout` are rejected.
+`page` and a function `flow` are required. `output`, `audio`, `postRoll`, `flowTimeout`, `runDirectory` and `signal` have the same meaning as in `record`, and the return value is the same recording summary. Set `initialPointer: { x, y }` to choose the starting cursor position. The page's viewport determines the dimensions; `scale` defaults to 1 and accepts 1 or 2, and `fps` defaults to 30 and accepts 30 or 60. Use these explicit settings instead of a preset. Browser setup options such as `url`, `browser`, `gpu`, `storageState`, viewport dimensions and `readyTimeout` are rejected.
 
 Traceframe moves the caller's pointer only after validating the first frame. To show the starting hover state from frame 0, move the page's mouse to your chosen `initialPointer` before calling `recordPage`.
 
 For 2× frames, launch the caller's browser with `chromium.launch({ args: ['--force-device-scale-factor=2'] })`, create its context with `deviceScaleFactor: 2`, and pass `scale: 2` to `recordPage`. The same launch argument works with `launchPersistentContext`. Setting `deviceScaleFactor` alone does not ensure 2× screencast frames. Traceframe checks the first JPEG's actual dimensions before running the callback and rejects mismatches with `CAPTURE_SIZE_MISMATCH`.
 
-Keep the viewport, zoom and visual scale fixed and the page open until `recordPage` settles; geometry is checked only at startup. Only that page is recorded; a tab closed during a take may lose its capture. Use the page exclusively for recording: concurrent screencasts, context `recordVideo` and tracing with screenshots can change frame dimensions or supply stale frames. A size check cannot detect every conflict. Overlapping `recordPage` calls on the same page reject with `PAGE_RECORDING_ACTIVE`.
+If the page uses DOM fullscreen, such as a video player's fullscreen button, Chromium's default headless shell sizes it from the browser window, 800 × 600 pixels unless set. Launch that browser with the recording's pixel size too, for example `--window-size=3024,1964` for a 1512 × 982 viewport at scale 2. Browsers launched by `record` and the CLI already use the recording size.
+
+Keep the viewport, zoom and visual scale fixed and the page open until `recordPage` settles. Page geometry is checked at startup. During the take, a frame whose size differs from the first stops recording with `CAPTURE_SIZE_CHANGED`. Only that page is recorded; a tab closed during a take may lose its capture. Use the page exclusively for recording: concurrent screencasts, context `recordVideo` and tracing with screenshots can change frame dimensions or supply stale frames. A size check cannot detect every conflict. Overlapping `recordPage` calls on the same page reject with `PAGE_RECORDING_ACTIVE`.
 
 Await every helper. Helpers observe cancellation before further pointer or scroll actions, and release a mouse button that was already pressed; an already-issued action may still complete. Arbitrary callback code must cooperate with `signal`, including passing it to supported Playwright operations. A flow timeout does not forcibly terminate that code. Sequential takes are supported after a successful screencast stop, including ordinary flow failures and cooperative cancellation. Startup or stop failures may need a new page or context; Traceframe leaves that recovery to the caller and does not stop a pre-existing caller screencast.
 

package/docs/recording-flows.md

@@ -30,9 +30,17 @@ For a video-heavy journey, check playback in your first take at the final record
 
 On YouTube, the player's **Settings (gear) → Ambient mode → Off** can reduce expensive background drawing during CPU-only playback. Ambient mode is available only with YouTube's dark theme; check the setting under the theme you will record. Disable this decorative effect only when it is unnecessary for the demonstration, and verify the setting before the take. Use the site's setting in `ready`, or prepare the caller-owned page before `recordPage`; Traceframe does not change it automatically.
 
+If the journey enters fullscreen, wait for the fullscreen layout, not only for `document.fullscreenElement`. On a slower test machine, YouTube sometimes reported fullscreen while keeping its normal page layout. Check that the video's bounding box reaches the viewport's width or height; if it does not within a few seconds, exit fullscreen and enter it again. One retry fixed every such case in those tests.
+
 For video assets you control, matching the source dimensions to the displayed physical pixels can avoid costly browser resizing during CPU-only playback. Physical dimensions include device scale: a video displayed 1512 CSS pixels wide at scale 2 occupies 3024 physical pixels. Preparing another asset can change image quality, so compare it with the original and preserve the intended framing. Do not silently replace third-party media, crop content or lower the required output resolution to claim a performance improvement.
 
-If the video looks choppy, apply any preparation above that suits the demonstration and make one more take at the same recording settings. If it is still choppy, or nothing applies, keep the requested output dimensions, playback speed and source quality, finish the requested recording and report the limitation. For optional diagnosis of playback without recording, let buffering and any extension processing warm up, then read the video's `getVideoPlaybackQuality()` counters before and after a representative segment with recording off, for example in `ready` or before `recordPage`. Page preparation can improve playback while capture remains expensive.
+If the video looks choppy:
+
+1. Apply any preparation above that suits the demonstration and make one more take at the same recording settings.
+2. For a browser Traceframe launches, check `graphics.hardwareAccelerated` in the result. If it is `false`, or `graphics.renderer` names a slower GPU than the machine has, see [GPU rendering](../README.md#gpu-rendering) for fixes; most change system settings, so ask the machine's owner first.
+3. If the video is still choppy, or nothing applies, keep the requested output dimensions, playback speed and source quality, finish the requested recording and report the limitation. Mention that a smaller scale usually helps most on a slower machine: `--scale 1` (`scale: 1` in the API) leaves Chromium a quarter of the pixels to capture, while a lower FPS does not reduce capture work.
+
+For optional diagnosis of playback without recording, let buffering and any extension processing warm up, then read the video's `getVideoPlaybackQuality()` counters before and after a representative segment with recording off, for example in `ready` or before `recordPage`. Page preparation can improve playback while capture remains expensive.
 
 ## Save and switch login state
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milkstraw/traceframe",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "Record scripted browser flows and render smooth cursor overlays into video.",
   "keywords": [
     "playwright",
@@ -34,7 +34,7 @@
     "node": ">=22"
   },
   "scripts": {
-    "test": "node --test",
+    "test": "cd test && node --test",
     "test:smoke": "node scripts/smoke.mjs",
     "test:package": "node scripts/package-smoke.mjs",
     "build:assets": "node scripts/build-assets.mjs"

package/src/browser.mjs

@@ -0,0 +1,70 @@
+import { chromium } from 'playwright'
+
+import { TraceframeError } from './errors.mjs'
+import { withDeadline } from './deadline.mjs'
+
+const GRAPHICS_CHECK_TIMEOUT = 5_000
+const SOFTWARE_RENDERER = /swiftshader|llvmpipe|softpipe|lavapipe|software|basic render|\bwarp\b/i
+
+export async function launchBrowser(config, { handleSignals, signal }) {
+  const baseArgs = [
+    ...(config.scale === 2 ? ['--force-device-scale-factor=2'] : []),
+    // The headless shell sizes DOM fullscreen from its window (800×600 pixels by default).
+    // Match the recording's pixel size so a fullscreen page keeps the requested viewport.
+    `--window-size=${config.video.width},${config.video.height}`,
+    // Keep video decoding in software: hardware decoding fails in headless Linux and added no captured frames on macOS.
+    '--disable-accelerated-video-decode',
+  ]
+  async function launch(args) {
+    try {
+      return await chromium.launch({
+        executablePath: config.browser,
+        args: [...baseArgs, ...args],
+        handleSIGINT: handleSignals,
+        handleSIGTERM: handleSignals,
+        handleSIGHUP: handleSignals,
+      })
+    } catch (error) {
+      if (!/Executable doesn't exist/i.test(error.message)) throw error
+      const message = config.browser
+        ? `Configured browser executable is unavailable: ${config.browser}`
+        : 'Playwright Chromium is not installed. Run `npx playwright@1.64.1 install --only-shell chromium`, or pass --browser to a Chrome executable.'
+      throw new TraceframeError(message, { code: 'PLAYWRIGHT_RUNTIME_MISSING', cause: error })
+    }
+  }
+
+  const softwareArgs = ['--disable-gpu']
+  if (config.gpu === 'off') return { browser: await launch(softwareArgs), graphics: { hardwareAccelerated: false } }
+
+  // Decide before navigation or ready(): application preparation runs only once.
+  const candidate = await launch(['--enable-gpu', ...(process.platform === 'linux' ? ['--use-angle=gl-egl'] : [])])
+    .catch(error => { if (error.code === 'PLAYWRIGHT_RUNTIME_MISSING') throw error })
+  const { renderer, fallbackReason } = candidate ? await inspectGraphics(candidate, signal) : { fallbackReason: 'gpu-launch-failed' }
+  if (!fallbackReason) return { browser: candidate, graphics: { hardwareAccelerated: true, renderer } }
+  await candidate?.close()
+  // The launch or check may have stopped because the caller cancelled.
+  signal.throwIfAborted()
+  return { browser: await launch(softwareArgs), graphics: { hardwareAccelerated: false, fallbackReason } }
+}
+
+// Returns the GPU renderer when hardware rendering is verified, otherwise why it was not.
+async function inspectGraphics(browser, signal) {
+  try {
+    const { gpu } = await withDeadline(async () => {
+      const session = await browser.newBrowserCDPSession()
+      try {
+        return await session.send('SystemInfo.getInfo')
+      } finally {
+        // A rejected browser is closed next, so do not wait for the session.
+        session.detach().catch(() => {})
+      }
+    }, GRAPHICS_CHECK_TIMEOUT, new Error('Graphics check timed out.'), signal)
+    const compositing = gpu.featureStatus?.gpu_compositing
+    const renderer = gpu.auxAttributes?.glRenderer
+    if (!compositing || !renderer) return { fallbackReason: 'graphics-check-unavailable' }
+    if (!compositing.startsWith('enabled') || SOFTWARE_RENDERER.test(renderer)) return { fallbackReason: 'software-rendering' }
+    return { renderer }
+  } catch {
+    return { fallbackReason: 'graphics-check-unavailable' }
+  }
+}

package/src/capture.mjs

@@ -1,18 +1,22 @@
-import { addAbortListener } from 'node:events'
 import { writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { setTimeout as delay } from 'node:timers/promises'
-import { chromium } from 'playwright'
 
 import { TraceframeError } from './errors.mjs'
 import { addDiagnostics, retainedFile } from './diagnostics.mjs'
 import { createFlowApi } from './flow.mjs'
 import { createCaptureStats } from './capture-stats.mjs'
 import { createJpegCapture } from './jpeg-capture.mjs'
+import { launchBrowser } from './browser.mjs'
+import { raceAbort, withDeadline } from './deadline.mjs'
 
 const PLAYWRIGHT_DEFAULT_TIMEOUT = 30_000
 const FIRST_FRAME_TIMEOUT = 10_000
 const FAILURE_SCREENSHOT_TIMEOUT = 5_000
+// Playwright uses the screencast fps only to let Chromium have 10 frames in flight above 30,
+// otherwise 5. Export sets the output rate, so 30 FPS output keeps the larger allowance: with 5,
+// a busy machine captured fewer pictures without saving any work.
+const SCREENCAST_FPS = 60
 
 export async function captureFlow({ config, flow, directory, page, signal: callerSignal }) {
   const captureErrors = new AbortController()
@@ -22,7 +26,7 @@ export async function captureFlow({ config, flow, directory, page, signal: calle
   const stats = config.captureDiagnostics ? createCaptureStats() : undefined
 
   signal.throwIfAborted()
-  const browser = page ? undefined : await launchBrowser(config, { handleSignals: !callerSignal })
+  const { browser, graphics } = page ? {} : await launchBrowser(config, { handleSignals: !callerSignal, signal })
   let clock
   let recording = false
   let failed = false
@@ -33,7 +37,10 @@ export async function captureFlow({ config, flow, directory, page, signal: calle
   }
   try {
     if (browser) {
+      // A browser launch cannot be interrupted, so check before creating the page and again before navigation.
+      signal.throwIfAborted()
       page = await browser.newPage({ viewport: config.viewport, deviceScaleFactor: config.scale, storageState: config.storageState })
+      signal.throwIfAborted()
       await raceAbort(waitForReady(page, flow, config, signal), signal)
       signal.throwIfAborted()
       await page.mouse.move(trace.initialPointer.x, trace.initialPointer.y)
@@ -44,9 +51,18 @@ export async function captureFlow({ config, flow, directory, page, signal: calle
     const firstFrame = Promise.withResolvers()
     signal.throwIfAborted()
     capture = createJpegCapture(rawPath, { ...config.video, onError: cause => captureErrors.abort(new TraceframeError(`Could not save capture: ${cause.message}`, { code: 'CAPTURE_FAILED', cause })) })
-    await page.screencast.start({ size: { width: config.video.width, height: config.video.height }, fps: config.video.fps, quality: config.captureQuality, onFrame: (frame) => {
+    let firstSize
+    await page.screencast.start({ size: { width: config.video.width, height: config.video.height }, fps: SCREENCAST_FPS, quality: config.captureQuality, onFrame: (frame) => {
       stats?.observe(frame.timestamp, performance.now())
       firstFrame.resolve(frame)
+      // The first frame is checked against the request below. A later size change would
+      // otherwise surface only after export, as a truncated video.
+      const size = frameSize(frame)
+      firstSize ??= size
+      if (!sameSize(size, firstSize)) {
+        captureErrors.abort(new TraceframeError(`Screencast frames changed size during recording, from ${describeSize(firstSize)} to ${describeSize(size)}. Keep the page geometry fixed while recording.`, { code: 'CAPTURE_SIZE_CHANGED' }))
+        return
+      }
       return capture.append(frame)
     } })
     recording = true
@@ -79,7 +95,7 @@ export async function captureFlow({ config, flow, directory, page, signal: calle
     // Stop the page subscription only once, including when shutdown fails.
     recording = false
     await stopCapture()
-    return { rawPath, trace, startedAt: clock, ...(stats ? { captureStats: { ...stats.summary(), ...capture.stats } } : {}) }
+    return { rawPath, trace, startedAt: clock, graphics, ...(stats ? { captureStats: { ...stats.summary(), ...capture.stats } } : {}) }
   } catch (error) {
     failed = true
     // A writer failure during cleanup must not replace the initiating failure.
@@ -91,7 +107,8 @@ export async function captureFlow({ config, flow, directory, page, signal: calle
         .then(() => capture?.stop())
         .then(() => clock !== undefined && config.runDirectory ? retainedFile(rawPath) : undefined)
         .catch(() => undefined),
-      config.runDirectory && page && !signal.aborted ? saveFailureScreenshot(page, directory, signal) : undefined,
+      // A frame size change or a capture write error also aborts signal; only caller cancellation skips this.
+      config.runDirectory && page && !callerSignal?.aborted ? saveFailureScreenshot(page, directory, callerSignal) : undefined,
     ])
     if (callerSignal?.aborted) throw callerSignal.reason
     throw await addDiagnostics(failure, { flow: config.flow, recordingTime, capturePath, screenshotPath })
@@ -117,13 +134,27 @@ async function assertPageGeometry(page, config, signal) {
   }
 }
 
+// [JPEG width, JPEG height, viewport width, viewport height]; the JPEG values are undefined if unreadable.
+function frameSize(frame) {
+  const jpeg = jpegSize(frame.data)
+  return [jpeg?.width, jpeg?.height, frame.viewportWidth, frame.viewportHeight]
+}
+
+function sameSize(a, b) {
+  return a.every((value, index) => value === b[index])
+}
+
+function describeSize([width, height, viewportWidth, viewportHeight]) {
+  return `${width === undefined ? 'an unreadable JPEG' : `${width}×${height}`} for a ${viewportWidth}×${viewportHeight} viewport`
+}
+
 function assertFrameSize(frame, config) {
   // Check the exported JPEG dimensions; deviceScaleFactor alone is insufficient.
-  const size = jpegSize(frame.data)
-  if (size?.width !== config.video.width || size?.height !== config.video.height ||
-      frame.viewportWidth !== config.viewport.width || frame.viewportHeight !== config.viewport.height) {
+  const size = frameSize(frame)
+  const expected = [config.video.width, config.video.height, config.viewport.width, config.viewport.height]
+  if (!sameSize(size, expected)) {
     const scaleHint = config.scale === 2 ? ' For scale 2, launch Chromium with --force-device-scale-factor=2; deviceScaleFactor alone is insufficient.' : ''
-    throw new TraceframeError(`Screencast frames are ${size ? `${size.width}×${size.height}` : 'not a readable JPEG'} for a ${frame.viewportWidth}×${frame.viewportHeight} viewport; expected ${config.video.width}×${config.video.height} for a ${config.viewport.width}×${config.viewport.height} viewport. Keep the viewport fixed and use the page exclusively for this recording.${scaleHint}`, { code: 'CAPTURE_SIZE_MISMATCH' })
+    throw new TraceframeError(`Screencast frames are ${describeSize(size)}; expected ${describeSize(expected)}. Keep the viewport fixed and use the page exclusively for this recording.${scaleHint}`, { code: 'CAPTURE_SIZE_MISMATCH' })
   }
 }
 
@@ -155,24 +186,6 @@ async function saveFailureScreenshot(page, directory, signal) {
   }
 }
 
-async function launchBrowser(config, { handleSignals }) {
-  try {
-    return await chromium.launch({
-      executablePath: config.browser,
-      args: config.scale === 2 ? ['--force-device-scale-factor=2'] : [],
-      handleSIGINT: handleSignals,
-      handleSIGTERM: handleSignals,
-      handleSIGHUP: handleSignals,
-    })
-  } catch (error) {
-    if (!/Executable doesn't exist/i.test(error.message)) throw error
-    const message = config.browser
-      ? `Configured browser executable is unavailable: ${config.browser}`
-      : 'Playwright Chromium is not installed. Run `npx playwright@1.64.1 install --only-shell chromium`, or pass --browser to a Chrome executable.'
-    throw new TraceframeError(message, { code: 'PLAYWRIGHT_RUNTIME_MISSING', cause: error })
-  }
-}
-
 async function waitForReady(page, flow, config, signal) {
   try {
     page.setDefaultTimeout(config.readyTimeout * 1000)
@@ -184,26 +197,3 @@ async function waitForReady(page, flow, config, signal) {
     throw new TraceframeError(`Ready check failed: ${error instanceof Error ? error.message : error}`, { code: 'READY_FAILED', cause: error })
   }
 }
-
-// Settles with the task, or rejects at the deadline or on abort, even if the task ignores its signal.
-async function withDeadline(task, milliseconds, error, signal) {
-  const controller = new AbortController()
-  const timer = setTimeout(() => controller.abort(error), milliseconds)
-  const deadline = AbortSignal.any([signal, controller.signal])
-  try {
-    deadline.throwIfAborted()
-    return await raceAbort(task(deadline), deadline)
-  } finally {
-    clearTimeout(timer)
-  }
-}
-
-async function raceAbort(promise, signal) {
-  const aborted = Promise.withResolvers()
-  const listener = addAbortListener(signal, () => aborted.reject(signal.reason))
-  try {
-    return await Promise.race([promise, aborted.promise])
-  } finally {
-    listener[Symbol.dispose]()
-  }
-}

package/src/cli.mjs

@@ -15,6 +15,7 @@ const OPTION_KEYS = {
   out: 'output',
   preset: 'preset',
   browser: 'browser',
+  gpu: 'gpu',
   'storage-state': 'storageState',
   'viewport-width': 'viewportWidth',
   'viewport-height': 'viewportHeight',
@@ -41,12 +42,13 @@ Options:
   --preset <standard|draft>    standard: 1280x800 CSS viewport, 2560x1600 at 60 FPS (default)
                                draft: 1280x800 CSS viewport, 1280x800 at 30 FPS
   --browser <path>             Chromium executable (or set CHROME_PATH)
+  --gpu <auto|off>             Verified GPU with software fallback (default), or software only
   --storage-state <path>       Playwright storage state JSON
   --viewport-width <pixels>    CSS viewport width
   --viewport-height <pixels>   CSS viewport height
   --scale <1|2>                Device scale factor; the video is the viewport times this
   --fps <30|60>                Encoded frame rate
-  --capture-quality <1–100>    JPEG frame quality (default: 95); lower can reduce capture cost
+  --capture-quality <1–100>    JPEG frame quality (default: 85); higher keeps more detail
   --capture-diagnostics        Include frame delivery cadence and gaps in the JSON summary
   --post-roll <seconds>        Tail after the flow (default: 0.3)
   --ready-timeout <seconds>    Playwright default timeout during navigation and ready() (default: 30)

package/src/config.mjs

@@ -20,6 +20,8 @@ export function createConfig(options = {}) {
   check(options.url, 'A URL is required (the url option, or --url).')
   const readyTimeout = options.readyTimeout ?? 30
   check(Number.isFinite(readyTimeout) && readyTimeout > 0, 'Ready timeout must be more than 0 seconds.')
+  const gpu = options.gpu ?? 'auto'
+  check(['auto', 'off'].includes(gpu), 'GPU must be auto or off.')
 
   return {
     ...recordingConfig(options, viewport, preset),
@@ -27,6 +29,7 @@ export function createConfig(options = {}) {
     flow: resolve(options.flow),
     storageState: options.storageState,
     browser: options.browser ?? process.env.CHROME_PATH,
+    gpu,
     readyTimeout,
   }
 }
@@ -37,7 +40,7 @@ export function createPageConfig(options = {}) {
   check(!page.isClosed(), 'The supplied page is closed.')
   const viewport = page.viewportSize()
   check(viewport, 'recordPage requires a fixed viewport. Set it when creating the page or context; viewport: null is not supported.')
-  for (const key of ['url', 'browser', 'storageState', 'readyTimeout', 'viewportWidth', 'viewportHeight', 'preset']) {
+  for (const key of ['url', 'browser', 'gpu', 'storageState', 'readyTimeout', 'viewportWidth', 'viewportHeight', 'preset']) {
     check(options[key] === undefined, `recordPage does not accept ${key}; prepare the page before recording and use scale/fps for video settings.`)
   }
   return recordingConfig(options, viewport, { scale: 1, fps: 30 })
@@ -54,7 +57,7 @@ function recordingConfig(options, viewport, defaults) {
     fps: options.fps ?? defaults.fps,
   }
   check(video.fps === 30 || video.fps === 60, 'FPS must be 30 or 60.')
-  const captureQuality = options.captureQuality ?? 95
+  const captureQuality = options.captureQuality ?? 85
   check(Number.isInteger(captureQuality) && captureQuality >= 1 && captureQuality <= 100, 'Capture quality must be an integer from 1 to 100.')
   check(options.captureDiagnostics === undefined || typeof options.captureDiagnostics === 'boolean', 'Capture diagnostics must be a boolean.')
   check(video.width % 2 === 0 && video.height % 2 === 0, 'At scale 1, the viewport width and height must be even.')

package/src/deadline.mjs

@@ -0,0 +1,24 @@
+import { addAbortListener } from 'node:events'
+
+// Settles with the task, or rejects at the deadline or on abort, even if the task ignores its signal.
+export async function withDeadline(task, milliseconds, error, signal) {
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(error), milliseconds)
+  const deadline = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal
+  try {
+    deadline.throwIfAborted()
+    return await raceAbort(task(deadline), deadline)
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+export async function raceAbort(promise, signal) {
+  const aborted = Promise.withResolvers()
+  const listener = addAbortListener(signal, () => aborted.reject(signal.reason))
+  try {
+    return await Promise.race([promise, aborted.promise])
+  } finally {
+    listener[Symbol.dispose]()
+  }
+}

package/src/record.mjs

@@ -65,6 +65,7 @@ async function recordFlow({ config, flow, ffmpeg, signal, page }) {
       duration,
       moveCount: trace.moves.length,
       clickCount: trace.clicks.length,
+      ...(capture.graphics ? { graphics: capture.graphics } : {}),
       runDirectory: config.runDirectory,
       ...(audio ? { audio: true } : {}),
       ...(capture.captureStats ? { captureStats: capture.captureStats } : {}),