feat(CDPBrowser): CDP screencast recording with APNG assembly

Adds startScreencast/stopScreencast to CDPBrowser via raw CDP
Page.startScreencast, buffering acknowledged Page.screencastFrame events
and muxing them into an APNG on stop. Verified format:'png' is honored by
both Chrome and Obscura v0.2.0 (magic bytes checked directly, not assumed)
before building the assembler; frames with a differing size than the first
are dropped with a debug note rather than guessed at, and a non-PNG frame
aborts assembly with a debug note instead of producing a broken file.

New lib/helper/extras/apngAssembler.js does pure container-level PNG chunk
muxing (IHDR/acTL/fcTL/IDAT/fdAT/IEND, CRC-32) with no new dependencies and
no pixel encoding.

The screencast plugin now supports this as a second path alongside its
existing Playwright page.screencast (webm) flow, chosen automatically per
active helper; captions/showActions stay Playwright-only, .srt subtitles
are unchanged since they're driven by step events either way. Also fixes
the plugin being unreachable for CDP-family helpers at all: getBrowserHelper
only recognizes the 4 standard acting helpers, so a local duck-typed
fallback (any helper exposing startScreencast) is used instead of widening
that shared list for every plugin that consumes it.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: DavertMik

docs/alternative-browsers.md

@@ -143,6 +143,7 @@ process — there is nothing to start by hand in the common case:
 | Layout / getBoundingClientRect | yes | yes (v0.2.0+ default builds); synthetic on `-no-render`/v0.1.x | yes |
 | Screenshots | yes | yes (v0.2.0+ default builds); no on `-no-render`/v0.1.x | yes |
 | Visibility assertions | yes | yes (v0.2.0+ default builds); no, DOM-presence only, on `-no-render`/v0.1.x | yes |
+| Screencast / video (`screencast` plugin) | yes — WebM via `page.screencast`, with caption burn-in | yes — APNG via CDP `Page.startScreencast`, assembled in-process (v0.2.0+ default builds; verified PNG frames on the live server); no caption burn-in | untested |
 | Startup cost | seconds + ~300 MB install | instant, 70 MB binary | ~1 s, zero local |
 | Parallel scale | machine-bound | machine-bound (light) | near-unlimited (cloud) |
 | Where it runs | local/grid | local | Cloudflare only |

docs/helpers/CDPBrowser.md

@@ -183,6 +183,18 @@ silently returning every candidate node instead of none or one. The result is ca
 
 Returns **[Promise][4]<[boolean][5]>** `true` if the polyfill should be injected.
 
+### _onScreencastFrame
+
+`Page.screencastFrame` handler: ignores frames from a session other than the currently active
+one (stale frames from a previous test, since the listener is never removed), acknowledges the
+frame so the browser keeps sending more, and buffers `{data, timestamp}` for `stopScreencast`
+to assemble.
+
+#### Parameters
+
+*   `params` &#x20;
+*   `sessionId` &#x20;
+
 ### _onTrafficLoadingFailed
 
 `Network.loadingFailed` handler, resolving a still-pending `response` promise to `null`
@@ -1591,6 +1603,26 @@ I.startRecordingTraffic();
 
 Returns **[Promise][4]<void>**&#x20;
 
+### startScreencast
+
+Starts recording a CDP `Page.startScreencast` session for the current test's target: frames
+arrive as `Page.screencastFrame` events, are acknowledged immediately (`Page.screencastFrameAck`,
+required or the browser stops sending more), and buffered in `this._screencastFrames`. The
+underlying `Page.screencastFrame` listener is installed once (lazily) and left in place, like
+`startRecordingTraffic`'s listeners, since `CDPConnection` has no listener-removal API; it
+filters by `this.sessionId` so only the currently active test's frames are buffered. Call
+`stopScreencast` to end the capture and assemble the buffered frames into an APNG.
+
+```js
+I.startScreencast();
+```
+
+#### Parameters
+
+*   `options` **[object][3]?** {maxWidth: number, maxHeight: number, quality: number, everyNthFrame: number} — CDP `Page.startScreencast` pass-throughs. `format` is always `'png'`. 
+
+Returns **[Promise][4]<void>**&#x20;
+
 ### stopRecordingTraffic
 
 Stops recording network traffic started by `startRecordingTraffic`. Already-recorded requests
@@ -1602,6 +1634,29 @@ I.stopRecordingTraffic();
 
 Returns **void**&#x20;
 
+### stopScreencast
+
+Stops the screencast started by `startScreencast` and assembles the buffered frames into a
+single APNG (Animated PNG) file, returned as a Buffer. Frame delays are derived from the CDP
+frame metadata's `timestamp` deltas (frame arrival is activity-driven — Obscura and Chrome both
+only emit a frame on damage — so this reproduces the actual pacing of what happened, not a
+fixed frame rate); the last frame is held for `options.lastFrameDelayMs` (default 1000ms) since
+it has no "next" frame to derive a delay from. Every frame is checked for the PNG signature
+before assembly — CDP's `format: 'png'` is honored by both Chrome and Obscura (verified
+directly), but if some other engine ever sends a different format regardless, this reports it
+via `debugSection` and returns `null` instead of muxing a broken file. Returns `null` if no
+frames were captured (screencast never started, or stopped immediately after starting).
+
+```js
+const apngBuffer = await I.stopScreencast();
+```
+
+#### Parameters
+
+*   `options` **[object][3]?** {lastFrameDelayMs: number} — hold time in milliseconds for the final frame (default 1000). 
+
+Returns **[Promise][4]<[object][3]>** a Buffer with the assembled APNG, or null if there was nothing to assemble.
+
 ### type
 
 Types characters into the currently focused element (as set by `click`, `focus`, etc), one at a

docs/plugins.md

@@ -71,7 +71,7 @@ Retries each failed step in a test.
 
 ## [screencast](/plugins/screencast)
 
-Records WebM video of tests using Playwright's screencast API.
+Records a video of tests. Uses Playwright's `page.screencast` API (WebM) when the active helper is Playwright, or raw CDP `Page.startScreencast` (APNG, assembled in-process) when the active helper is `CDPBrowser` or a subclass (`Obscura`, `Kitesurf`, ...). Which path is used is detected automatically per test run; nothing in the config changes between them.
 
 ## [screenshot](/plugins/screenshot)
 

docs/plugins/screencast.md

@@ -9,16 +9,21 @@ title: screencast
 
 ## screencast
 
-Records WebM video of tests using Playwright's screencast API.
-
-When `captions` is enabled, action annotations are burned into the video;
-when `subtitles` is enabled, a standalone `.srt` is also produced. Default
-`on=fail` keeps videos for failed tests only; `on=test` keeps every test's
-video.
-
-Note: enabling Playwright's helper-level `video: true` together with this
-plugin produces two independent recordings (`output/videos/*.webm` from the
-helper, `output/screencast/*.webm` from this plugin).
+Records a video of tests. Uses Playwright's `page.screencast` API (WebM) when the active
+helper is Playwright, or raw CDP `Page.startScreencast` (APNG, assembled in-process) when the
+active helper is `CDPBrowser` or a subclass (`Obscura`, `Kitesurf`, ...). Which path is used is
+detected automatically per test run; nothing in the config changes between them.
+
+When `captions` is enabled, action annotations are burned into the video — Playwright only,
+via `page.screencast.showActions()`/`showChapter()`; silently absent on the CDP path, since CDP
+screencast frames are raw, uncomposited page captures with no overlay mechanism. `subtitles`
+(a standalone `.srt`) works identically on both paths, since it's driven by step events, not by
+the video API. Default `on=fail` keeps videos for failed tests only; `on=test` keeps every
+test's video.
+
+Note: enabling Playwright's helper-level `video: true` together with this plugin produces two
+independent recordings (`output/videos/*.webm` from the helper, `output/screencast/*.webm` from
+this plugin).
 
 #### Configuration
 
@@ -38,11 +43,11 @@ plugins: {
 
 Other config options:
 
-*   `captions`: burn-in action overlays via `page.screencast.showActions()`. Default: true.
+*   `captions`: burn-in action overlays via `page.screencast.showActions()`. Playwright only. Default: true.
 *   `subtitles`: also write a standalone `.srt` file alongside the video. Default: false.
 *   `video`: record a video. With `video=false, subtitles=true`, only the `.srt` is produced. Default: true.
-*   `size`: pass-through `{ width, height }` for `screencast.start`.
-*   `quality`: pass-through 0–100 for `screencast.start`.
+*   `size`: pass-through `{ width, height }` — `screencast.start`'s `size` on Playwright, `maxWidth`/`maxHeight` on the CDP path.
+*   `quality`: pass-through 0–100 for `screencast.start` (Playwright) or CDP `Page.startScreencast` (CDPBrowser family).
 
 CLI examples:
 

lib/helper/CDPBrowser.js

@@ -19,6 +19,7 @@ import WebElement from '../element/WebElement.js'
 import CDPElementHandle from './extras/CDPElementHandle.js'
 import { checkFocusBeforeType, checkFocusBeforePressKey } from './extras/focusCheck.js'
 import { dontSeeTraffic, seeTraffic, grabRecordedNetworkTraffics, flushNetworkTraffics } from './network/actions.js'
+import { assembleApng, isPng } from './extras/apngAssembler.js'
 
 /**
  * ## Configuration
@@ -95,6 +96,9 @@ class CDPBrowser extends Helper {
     this.recordedAtLeastOnce = false
     this._pendingTrafficResponses = new Map()
     this._trafficListenersInstalled = false
+    this._screencastFrames = []
+    this._screencastActive = false
+    this._screencastListenerInstalled = false
   }
 
   /**
@@ -2436,6 +2440,97 @@ class CDPBrowser extends Helper {
   flushNetworkTraffics() {
     return flushNetworkTraffics.call(this)
   }
+
+  /**
+   * Starts recording a CDP `Page.startScreencast` session for the current test's target: frames
+   * arrive as `Page.screencastFrame` events, are acknowledged immediately (`Page.screencastFrameAck`,
+   * required or the browser stops sending more), and buffered in `this._screencastFrames`. The
+   * underlying `Page.screencastFrame` listener is installed once (lazily) and left in place, like
+   * `startRecordingTraffic`'s listeners, since `CDPConnection` has no listener-removal API; it
+   * filters by `this.sessionId` so only the currently active test's frames are buffered. Call
+   * `stopScreencast` to end the capture and assemble the buffered frames into an APNG.
+   *
+   * ```js
+   * I.startScreencast();
+   * ```
+   *
+   * @param {object} [options] {maxWidth: number, maxHeight: number, quality: number, everyNthFrame: number} — CDP `Page.startScreencast` pass-throughs. `format` is always `'png'`.
+   * @returns {Promise<void>}
+   */
+  async startScreencast(options = {}) {
+    if (!this._screencastListenerInstalled) {
+      this._screencastListenerInstalled = true
+      this.cdp.on('Page.screencastFrame', (params, sessionId) => this._onScreencastFrame(params, sessionId))
+    }
+    this._screencastFrames = []
+    this._screencastActive = true
+    const params = { format: 'png' }
+    if (options.maxWidth) params.maxWidth = options.maxWidth
+    if (options.maxHeight) params.maxHeight = options.maxHeight
+    if (options.quality != null) params.quality = options.quality
+    if (options.everyNthFrame) params.everyNthFrame = options.everyNthFrame
+    await this.cdp.send('Page.startScreencast', params, this.sessionId)
+  }
+
+  /**
+   * `Page.screencastFrame` handler: ignores frames from a session other than the currently active
+   * one (stale frames from a previous test, since the listener is never removed), acknowledges the
+   * frame so the browser keeps sending more, and buffers `{data, timestamp}` for `stopScreencast`
+   * to assemble.
+   *
+   * @protected
+   */
+  _onScreencastFrame(params, sessionId) {
+    if (!this._screencastActive || sessionId !== this.sessionId) return
+    this._screencastFrames.push({ data: params.data, timestamp: params.metadata && params.metadata.timestamp })
+    this.cdp.send('Page.screencastFrameAck', { sessionId: params.sessionId }, this.sessionId).catch(() => null)
+  }
+
+  /**
+   * Stops the screencast started by `startScreencast` and assembles the buffered frames into a
+   * single APNG (Animated PNG) file, returned as a Buffer. Frame delays are derived from the CDP
+   * frame metadata's `timestamp` deltas (frame arrival is activity-driven — Obscura and Chrome both
+   * only emit a frame on damage — so this reproduces the actual pacing of what happened, not a
+   * fixed frame rate); the last frame is held for `options.lastFrameDelayMs` (default 1000ms) since
+   * it has no "next" frame to derive a delay from. Every frame is checked for the PNG signature
+   * before assembly — CDP's `format: 'png'` is honored by both Chrome and Obscura (verified
+   * directly), but if some other engine ever sends a different format regardless, this reports it
+   * via `debugSection` and returns `null` instead of muxing a broken file. Returns `null` if no
+   * frames were captured (screencast never started, or stopped immediately after starting).
+   *
+   * ```js
+   * const apngBuffer = await I.stopScreencast();
+   * ```
+   *
+   * @param {object} [options] {lastFrameDelayMs: number} — hold time in milliseconds for the final frame (default 1000).
+   * @returns {Promise<object>} a Buffer with the assembled APNG, or null if there was nothing to assemble.
+   */
+  async stopScreencast(options = {}) {
+    this._screencastActive = false
+    if (this.cdp && this.cdp.isConnected && this.sessionId) {
+      await this.cdp.send('Page.stopScreencast', {}, this.sessionId).catch(() => null)
+    }
+    const frames = this._screencastFrames
+    this._screencastFrames = []
+    if (!frames.length) return null
+
+    const buffers = frames.map(f => Buffer.from(f.data, 'base64'))
+    const nonPngIndex = buffers.findIndex(b => !isPng(b))
+    if (nonPngIndex !== -1) {
+      this.debugSection('Screencast', `frame ${nonPngIndex} is not a PNG (first bytes: ${buffers[nonPngIndex].subarray(0, 8).toString('hex')}) — this engine isn't honoring format: 'png'; skipping APNG assembly`)
+      return null
+    }
+
+    const apngFrames = buffers.map((buffer, i) => {
+      const delayMs = i < frames.length - 1 && frames[i + 1].timestamp && frames[i].timestamp ? Math.max(1, Math.round((frames[i + 1].timestamp - frames[i].timestamp) * 1000)) : options.lastFrameDelayMs ?? 1000
+      return { buffer, delayMs }
+    })
+
+    return assembleApng(apngFrames, {
+      lastFrameDelayMs: options.lastFrameDelayMs ?? 1000,
+      onDropFrame: info => this.debugSection('Screencast', `dropped a frame with size ${info.width}x${info.height}, expected ${info.expectedWidth}x${info.expectedHeight}`),
+    })
+  }
 }
 
 export default CDPBrowser