fix(preview): server recordings capture the tab instead of re-encoding the JPEG screencast#26684

Problem

Agent recordings of server-browser tabs go through the JPEG screencast: Chromium compresses each frame, CDP sends it as base64, and an encoder page decodes it again before MediaRecorder encodes the canvas. At the 60 fps setting and a 1600×900 viewport (3200×1800 frames), main records 17–19 fps here and keeps 3.5–3.7 cores busy. #26683 has the measurements on three machines, including with PR #25075's faster delivery (45 fps on a 32-thread host, 10 fps on an i7-4790S).

Change

Tabs in a persistent profile are recorded from the frames Chrome composites, through chrome.tabCapture, the way the desktop app records its tabs:

• ServerBrowserContexts writes a small recorder extension (MV3, tabCapture and debugger, the latter only for chrome.debugger.getTargets(), which maps the tab's CDP target to its tab ID) and loads it into persistent profiles. A fixed key gives it a fixed ID for --allowlisted-extension-id, without which getMediaStreamId fails. recorderPage() opens the extension's page beside the tab, or returns null where extensions do not run.
• startRecording uses that page as the encoder. recordingEncoderScript gets capture(): the tab's video track goes through MediaStreamTrackProcessor, and each VideoFrame is drawn by the existing paint, cursor and click ring included, into the same canvas and MediaRecorder.
• Tab capture records the window, into which Chrome scales an emulated viewport of another size, so the window's content area follows the recorded tab's viewport (Browser.setContentsSize) at the start and after every viewport change. Tab capture also keeps one frame size and letterboxes into it unless its size bounds exceed 1 px and differ in aspect ratio (SelectResolutionPolicyFromCandidates); with bounds of 3×2 to 7680×7680 the frames follow the window as screencast frames follow the viewport, and the encoder scales the cursor from the CSS width it is told.
• Incognito and isolated tabs (off-the-record contexts, where extensions do not run) and desktop tabs keep the screencast path unchanged.

Tab capture needs full Chrome, which chrome-headless-shell is not: it rejects getDisplayMedia and does not load an unpacked extension. So PreviewBrowser installs Chrome for Testing's chrome 156.0.8078.70 instead of the shell of the same version:

• The zips are about 200 MB instead of about 120 MB. HtmlRender launches the same executable with --headless=new, which full Chrome runs.
• The macOS zips hold five relative links inside the app bundle. The unpacker now creates links whose target is relative and has no .. segment, and still rejects everything else.
• After a successful install, the old tools/chrome-headless-shell directory is removed.
• chrome links four more libraries directly than the shell (libcairo, libcups, libpango, and NSS's libsmime3), so t3 browser setup installs libcairo2, libcups2t64/libcups2 and libpango-1.0-0 as well. Its AppArmor profile is renamed to t3-chrome-for-testing for the new path; setup checks only that the profile file exists, so a host set up for the shell gets the new one on the next t3 browser setup.

Limits:

• Tabs of one profile share a window. If two of them record at once with different viewports, the one that started first is scaled into the other's window, with its cursor off, until its own viewport changes again.
• Recordings of incognito, isolated and desktop tabs are as slow as before; PR #25075 still applies to them. It changes the same functions, so one of the two will need a rebase; I can rebase this one onto it.
• With PR #24959, a browser the host provides would have to be full Chrome for tab capture.

Scope and approval

#26683 reports the defect with measurements and has not been triaged yet. This is a substantial fix (it changes the browser T3 downloads), so it needs that triage; I am opening it next to the issue because a working change makes the tab-capture direction easier to judge.

Verification

• Recording, end to end. A script (not committed) drove this branch's ServerBrowserContexts and recordingEncoderScript with the real Chrome for Testing 156 on Linux x64, recording the issue's reproduction page (text plus a box moving every frame) at a 1600×900 viewport and the 60 fps setting, with the agent cursor moving ten times a second, each run 4 s after 0.5 s of warm-up. "Before" was main's screencast delivery into the same encoder with chrome-headless-shell 156. Runs alternated on a busy host (load average 5–14), so the cores are indicative:

  	Frames	fps	Cores (Chrome + Node)
  main (screencast)	3200×1800	17.1, 17.5, 18.6, 19.2	3.5–3.7
  This branch (tab capture)	3200×1800	52.8, 54.2, 55.4, 56.0	2.7–3.0

• Geometry. A red dot at CSS (100, 100) sits at frame pixel (200, 200) in the captured frames, as in Page.captureScreenshot, at the first capture, at a second capture in the already fitted window, and when another tab opens mid-capture. With the agent cursor held on the dot, the recorded cursor stays on it before and after the viewport changes from 1600×900 to 800×800 mid-recording. Frames follow 800×800, 390×844, 1920×1080 and 2160×3840 (1600×1600, 780×1688, 3840×2160, 4320×7680); for 1–6 frames during each change they have an intermediate size, as screencast frames do.

• The recorded tab stays visible with requestAnimationFrame at 61 per second while the recorder page is open, and the live view's screencast delivers 52 frames a second while it is captured, against 60–61 before and after.

• Tests:

  • ServerBrowser.test.ts: a tab the recorder page can capture records through capture() with the frame-size bounds and the 60 fps setting, fits the window, starts no screencast, and refits the window and tells the encoder the new width after a viewer resize (this part fails without the call in the resize handler). A tab the recorder cannot see fails the recording and closes the recorder page.
  • ServerBrowserContexts.test.ts: only persistent profiles load the extension, recorderPage() returns null for an isolated context, and a page that fails to load is closed.
  • PreviewBrowser.test.ts: links inside the browser's directory are installed, links to a parent directory, an absolute path or nothing reject the archive, and the old shell directory is removed after an install.
  • vp run check:changed: format, lint, knip, typecheck and the changed files' tests pass. vp test run on src/preview, src/cli and src/htmlRender passes except ServerBrowserStream.test.ts (6) and cli/pair.test.ts (1). The six stream tests fail the same way on main here, under Node 24 and 26 (WebSocket close 1006), and replace ServerBrowser with a mock. pair.test.ts is a Tailscale pairing test that this change does not touch.

• I checked the six zips' sizes and SHA-256, the macOS zips' links, and the Linux binary's NEEDED libraries against the Debian packages.

• Not checked: installing and recording on macOS, Windows and arm64, and t3 browser setup on Debian or Ubuntu.

Model and harness: Claude Opus 5.5, Claude Code in T3 Code