fix(desktop): throttle hidden preview rendering

[t3-code]

problem

the desktop window disabled electron background throttling for its entire lifetime. electron keeps that window and every hosted preview renderer drawing even when t3 code is hidden or occluded, which can leave preview tabs consuming substantial cpu and energy.

fix

• restore electron's default background throttling for the desktop window
• temporarily disable throttling only while preview frame capture is active for recording or picture-in-picture
• make throttle and session transitions interruption-safe
• restore throttling after the final frame-capture consumer stops
• release recording and picture-in-picture captures when the main window closes

runtime probe

on linux with electron 41.5.0, a hidden-window animation ran 240 frames over four seconds with the current global override, versus 0 frames with default throttling restored.

testing

• vp test run apps/desktop/src/preview apps/desktop/src/window (204 passed)
• vp run --filter @t3tools/desktop typecheck
• vp check apps/desktop/src/preview/Manager.ts apps/desktop/src/preview/Manager.test.ts apps/desktop/src/window/DesktopWindow.ts apps/desktop/src/window/DesktopWindow.test.ts

implemented with gpt-5.6-sol through hermes agent.

request provenance

• requested by: @maria-rcks

---

Note

Medium Risk
Changes preview frame-capture and main-window lifecycle timing; incorrect throttling could affect recording quality or background CPU, though behavior is heavily covered by new tests.

Overview
Stops forcing backgroundThrottling: false on the desktop main window at creation so hidden/occluded windows can idle normally again. PreviewManager now calls setBackgroundThrottling(false) when the first frame-capture consumer starts (recording or picture-in-picture) and true when the last one stops, with retries and warnings if restore fails.

Session start/stop and setMainWindow reconciliation are made interruption-safe (uninterruptible paths). Replacing the main window re-applies unthrottled mode if captures are already running; stale closed handlers from old windows are ignored. On close, active recordings and PiP are torn down via stopAllRecordings.

Starting capture after the main window has closed fails with PreviewMainWindowClosedError instead of continuing in a bad state. Tests cover multi-tab refcounting, failed throttle updates, window swap races, and shared capture between recording and PiP.

^{Reviewed by Cursor Bugbot for commit 7281787. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Throttle main window background rendering only during active frame capture

• Removes the static backgroundThrottling: false from DesktopWindow creation; throttling is now managed dynamically by PreviewManager based on capture state.
• Disables background throttling on the main window when the first frame capture session starts, and restores it (with up to 2 retries) when the last session stops.
• When the main window is replaced via setMainWindow, throttling is disabled on the new window if captures are active; close events from the replaced window are ignored.
• Adds PreviewMainWindowClosedError so callers get a typed failure when attempting to start capture while the main window is closed.
• When the main window closes, all picture-in-picture sessions and recordings are stopped concurrently.
• Behavioral Change: new main windows no longer have backgroundThrottling forced to false at creation time; the setting defaults to undefined and is toggled only during active capture.

^{Macroscope summarized 7281787.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	12.6 KiB	12.6 KiB	−4 B (−0.0%)	15.1 KiB	✅
Codex	Thread snapshot wire	6.3 KiB	6.3 KiB	+5 B (+0.1%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	6.3 KiB	6.3 KiB	−9 B (−0.1%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	51.8 KiB	51.8 KiB	0 B (0.0%)	66.4 KiB	✅
Codex	Live turn messages	16	16	0 (0.0%)	21	✅
Claude	Total thread wire	12.6 KiB	12.6 KiB	+3 B (+0.0%)	15.1 KiB	✅
Claude	Thread snapshot wire	6.3 KiB	6.3 KiB	0 B (0.0%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	6.3 KiB	6.3 KiB	+3 B (+0.0%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	52.7 KiB	52.7 KiB	0 B (0.0%)	66.4 KiB	✅
Claude	Live turn messages	16	16	0 (0.0%)	21	✅

Baseline: 3a02c9c · PR result: 7281787 · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 99.9 KiB
• Claude decoded thread snapshot: 100.6 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR changes runtime behavior by dynamically managing background throttling for preview rendering rather than having it always disabled. The state management added is non-trivial and affects core desktop app functionality, warranting human review.

^{You can add or adjust custom eligibility rules. Learn more.}

[macroscopeapp]

Effect service conventions review: one finding on error modeling in apps/desktop/src/preview/Manager.ts. Everything else (namespace subpath imports, Effect.fn/Effect.fnUntraced usage, ref-based state handling, and the tests) matches the conventions.

^{Posted via Macroscope — Effect Service Conventions}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 08bcce8. Configure here.}