fix(preview): bound stalled screenshot captures#25862

Replaces #23487, which GitHub closed when its head fork was deleted and which can no longer be reopened. The same fix is ported onto current main.

Problem

Addresses #23015.

A desktop preview tab that is hidden, minimized or not composited can stop answering Page.captureScreenshot. captureViewport awaits that call with no deadline. The viewer's initial still (pushStill in attachViewer) holds the tab's capture lock while it waits, so the remote viewer stays on "Connecting to browser…". An agent snapshot then waits on that lock while holding the control queue, so evaluate, navigate and human takeover on the same tab block until the broker's 15-second deadline.

The comments on #23015 confirm this path. artjom-mashanin traced it on macOS with a T3 Connect client: the unbounded pushStill → captureViewport wait and the per-tab desktop screenshot slot. achose369 reported the same Connecting... state and 15-second snapshot/evaluate timeouts on Windows 0.1.2 on 2026-10-27.

Change

Bound the shared PNG/JPEG screenshot wait in captureViewport to three seconds. On expiry it rejects with an actionable execution error: "The browser is not producing screenshot frames. For a desktop tab, show or restore the T3 Code window and try again." The timer is cleared on completion and late results are ignored. This releases the existing capture and control queues without replaying browser actions or changing tab ownership. Recording startup uses the same helper for its first frame, so it now fails promptly and follows its existing cleanup path.

The existing snapshot retry is kept: two stalled attempts account for six seconds of screenshot waiting, inside the broker's 15-second budget. The execution-error classification preserves the diagnostic through the broker when this capture error reaches it first.

Changes from #23487: the port keeps main's native-size capture and separate PNG shrinking (captureViewport(cdp, options)), and applies the deadline only around the CDP screenshot wait. The tests are adapted to main's helpers, and the new tests sit alongside main's agent-turn and navigation-timeout tests.

What main already covers, and what it doesn't

• #25184 (fd71ddc2) holds focus/painting for pending screenshots, queued captures and live screencasts, so hidden desktop guests are more likely to produce frames. It does not put a deadline on the capture itself; when a capture still never answers (its native proof is Linux/X11), the server keeps waiting.
• #24056 (cccb78c4) serializes desktop screenshots per tab. The slot advances on completion or navigation, with no timeout.
• #20446 (8653c8f0) bounds the whole snapshot at 10 seconds, but not viewer stills or recording startup. The closing comment on #16567 notes that the underlying capture remained unbounded.
• #19919 made the desktop host tabs for unopened threads, which makes this path reachable whenever nobody is at the host.

Relationship to open PRs

• #23515 also adds a captureViewport deadline (5 seconds) and limits unanswered captures per session. This PR is the narrower variant: one bounded wait plus queue-recovery tests. Only one of the two should land.
• #24133 (now draft), #22877 and #22743 aim to keep hidden tabs rendering, which is the root cause. This PR doesn't conflict with them; it keeps a lost capture from wedging a tab when rendering still fails.
• #24130 improves timeout diagnostics and doesn't change capture deadlines.

Scope and approval

This is a small, focused correction to an indefinitely awaited browser read, submitted under CONTRIBUTING's exception for an obvious bug. #23015 records the expected clear-error fallback, and the diagnosis on #23015 asks for exactly this timeout. It adds no UI or control-policy changes and doesn't claim to restore mobile frames while the desktop is hidden.

On purpose, this doesn't touch the desktop screenshot slot or #25184's paint/focus holds. Releasing a hold at the server deadline while the stalled capture still owns its turn could stop the frames that capture needs to finish, which would block later screenshots of that tab. Bounding the desktop slot is a separate problem and belongs in its own PR.

Verification

On this branch (base 4cb29a56f6), from apps/server:

• 97 passed, 0 failed. These cover screenshot deadlines, late replies, timer cleanup, viewer-still lock recovery, same-tab snapshot/evaluate/navigate after a stall, human takeover, broker error preservation and retained tab ownership.
• Fail-before/pass-after: vp test run src/preview/ServerBrowserPage.test.ts -t 'server browser capture deadlines' gave 2 failed / 1 passed with main's ServerBrowserPage.ts, and 3 passed with the fix.
• Server vp run typecheck, plus vp lint and vp fmt --check on the three changed files, passed. git diff --check passed.

Native evidence from #23487, on Windows 11 Pro 10.0.26300 / Electron 44.9.3, using the checkout's actual capture and control functions with isolated Electron state on the earlier base:

Not verified:

• The native Electron check hasn't been repeated on the current base, which now includes #25184's paint holds.
• The complete Windows-to-mobile Entra sign-in sequence from #23015 wasn't reproduced.
• The native CDP capture itself isn't cancelled; its late result is ignored, and the desktop screenshot slot is still held until it settles or the page navigates.
• Several queued viewer stills can still together consume the broker deadline before an agent snapshot finishes, and a slow accessibility-tree read can let the inner snapshot deadline win. In those cases the generic timeout can still replace the actionable error.
• Missing mobile viewport/input data and absent compositor frames remain separate work.

Fixes pingdotgg/t3code#23514