Skip to content

Commit 6a3a2cd

Browse files
fix(desktop): agent preview tabs keep working while T3 is hidden
A <webview> guest that attaches while the app window is hidden or minimized never paints, and one parked off-screen stops painting, so agent snapshots waited on a frame that never came. Agent-opened tabs now live in a never-shown window of their own, which paints in every window state; the panel streams them like any other server tab. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent 6a6c84f commit 6a3a2cd

22 files changed

Lines changed: 627 additions & 62 deletions

‎.github/actions/ci-changes/action.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,8 @@ outputs:
1919
value: ${{ steps.detect.outputs.release_smoke }}
2020
mobile_native:
2121
value: ${{ steps.detect.outputs.mobile_native }}
22+
desktop_preview:
23+
value: ${{ steps.detect.outputs.desktop_preview }}
2224
runs:
2325
using: composite
2426
steps:

‎.github/scripts/ci-changes.cjs‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,11 @@ const BUILD_ONLY_DEPS = { t3: ["@t3tools/web"] };
6464
const MOBILE_NATIVE =
6565
/^apps\/mobile\/.*\.(swift|kt|kts)$|^apps\/mobile\/(\.swiftlint\.yml|detekt\.yml|\.editorconfig|Brewfile)$|^scripts\/mobile-native-static-check\.ts$|^package\.json$|^\.github\/workflows\/ci\.yml$|^\.github\/scripts\/ci-changes\.cjs$|^\.github\/actions\/ci-changes\//;
6666

67+
// Real-Electron check that agent preview tabs paint with the app window hidden.
68+
// Electron is pinned in the desktop manifest, so its upgrades rerun it too.
69+
const DESKTOP_PREVIEW =
70+
/^apps\/desktop\/src\/preview\/|^apps\/desktop\/scripts\/verify-background-preview|^apps\/desktop\/package\.json$|^\.github\/workflows\/ci\.yml$|^\.github\/scripts\/ci-changes\.cjs$|^\.github\/actions\/ci-changes\//;
71+
6772
// Jobs that test every package except these, which have jobs of their own.
6873
const OWN_TEST_JOB = new Set(["t3", "@t3tools/web", "@t3tools/monorepo"]);
6974

@@ -181,6 +186,7 @@ function decide(files, packages, full) {
181186
rust: everything || rust,
182187
release_smoke: scriptsChanged,
183188
mobile_native: files === null || files.some((file) => MOBILE_NATIVE.test(file)),
189+
desktop_preview: files === null || files.some((file) => DESKTOP_PREVIEW.test(file)),
184190
},
185191
};
186192
}

‎.github/workflows/ci.yml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@ jobs:
3434
rust: ${{ steps.detect.outputs.rust }}
3535
release_smoke: ${{ steps.detect.outputs.release_smoke }}
3636
mobile_native: ${{ steps.detect.outputs.mobile_native }}
37+
desktop_preview: ${{ steps.detect.outputs.desktop_preview }}
3738
steps:
3839
# Only the package manifests the script reads to build the dependency graph.
3940
# Depth 2 brings the base commit the change is diffed against.
@@ -470,6 +471,38 @@ jobs:
470471
- name: Lint mobile native sources
471472
run: vp run lint:mobile
472473

474+
# Unit tests mock Electron, so only a real one with a real window manager can
475+
# prove agent preview tabs still paint while the app window is hidden.
476+
desktop_preview:
477+
name: Desktop Background Preview
478+
needs: changes
479+
if: ${{ !cancelled() && needs.changes.outputs.desktop_preview != 'false' }}
480+
runs-on: blacksmith-6vcpu-macos-26
481+
timeout-minutes: 10
482+
steps:
483+
- name: Checkout
484+
uses: actions/checkout@v6
485+
with:
486+
sparse-checkout: |
487+
/*
488+
!/.repos/
489+
sparse-checkout-cone-mode: false
490+
491+
- name: Setup Vite+
492+
uses: voidzero-dev/setup-vp@v1
493+
with:
494+
node-version-file: package.json
495+
cache: true
496+
run-install: |
497+
args:
498+
- --filter=@t3tools/desktop
499+
500+
- name: Ensure Electron runtime is installed
501+
run: vp run --filter @t3tools/desktop ensure:electron
502+
503+
- name: Verify background preview tabs paint
504+
run: node apps/desktop/scripts/verify-background-preview.mjs
505+
473506
release_smoke:
474507
name: Release Smoke
475508
needs: changes
@@ -510,6 +543,7 @@ jobs:
510543
test_server,
511544
rust,
512545
mobile_native_static_analysis,
546+
desktop_preview,
513547
release_smoke,
514548
]
515549
runs-on: blacksmith-2vcpu-ubuntu-2404
Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
// Electron entry for verify-background-preview.mjs. CommonJS, because an ESM
2+
// entry delays `ready` until its top-level await settles.
3+
const NodeFS = require("node:fs");
4+
const NodeOS = require("node:os");
5+
const NodePath = require("node:path");
6+
const NodeURL = require("node:url");
7+
const { app, BrowserWindow, nativeImage } = require("electron");
8+
9+
const CAPTURE_TIMEOUT_MS = 5_000;
10+
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
11+
const withTimeout = (promise, ms) =>
12+
Promise.race([
13+
promise.then((value) => ({ ok: true, value })),
14+
sleep(ms).then(() => ({ ok: false })),
15+
]);
16+
const page = (html) => `data:text/html,${encodeURIComponent(html)}`;
17+
18+
async function captureColor(tab, rgb) {
19+
await tab.debugger.sendCommand("Runtime.evaluate", {
20+
expression: `document.body.style.background = 'rgb(${rgb.join(",")})'`,
21+
});
22+
const shot = await withTimeout(
23+
tab.debugger.sendCommand("Page.captureScreenshot", { format: "png" }),
24+
CAPTURE_TIMEOUT_MS,
25+
);
26+
if (!shot.ok) return "timed out";
27+
const pixels = nativeImage.createFromBuffer(Buffer.from(shot.value.data, "base64")).toBitmap();
28+
const got = [pixels[2], pixels[1], pixels[0]];
29+
// Color management can shift a channel by a few levels.
30+
return got.every((value, index) => Math.abs(value - rgb[index]) <= 6)
31+
? null
32+
: `stale: rgb(${got.join(",")})`;
33+
}
34+
35+
async function main() {
36+
const { backgroundTabWindowOptions } = await import(
37+
NodeURL.pathToFileURL(NodePath.join(__dirname, "../src/preview/BackgroundTabWindow.ts")).href
38+
);
39+
const preload = NodePath.join(
40+
NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-background-preview-")),
41+
"preload.cjs",
42+
);
43+
NodeFS.writeFileSync(preload, "");
44+
// Each state closes its windows, which would otherwise quit the app.
45+
app.on("window-all-closed", () => {});
46+
await app.whenReady();
47+
48+
const failures = [];
49+
for (const state of ["hidden", "minimized"]) {
50+
const appWindow = new BrowserWindow({ width: 480, height: 320, show: true });
51+
await appWindow.loadURL(page("<body>T3 Code</body>"));
52+
await sleep(500);
53+
if (state === "hidden") appWindow.hide();
54+
else appWindow.minimize();
55+
await sleep(1_500);
56+
57+
// Created only after the app window is gone, as an agent's tab would be.
58+
const tabWindow = new BrowserWindow(
59+
backgroundTabWindowOptions({
60+
partition: `t3-background-preview-${state}`,
61+
preload,
62+
passkeyBridgeArgument: undefined,
63+
}),
64+
);
65+
await tabWindow.loadURL(page("<body style='margin:0'></body>"));
66+
const tab = tabWindow.webContents;
67+
tab.debugger.attach("1.3");
68+
for (const [step, rgb] of [
69+
[1, [0, 200, 0]],
70+
[2, [200, 200, 0]],
71+
[3, [0, 200, 200]],
72+
]) {
73+
const failure = await captureColor(tab, rgb);
74+
if (failure) failures.push(`app window ${state}, capture ${step}: ${failure}`);
75+
await sleep(1_000);
76+
}
77+
tabWindow.destroy();
78+
appWindow.destroy();
79+
}
80+
81+
if (failures.length > 0) {
82+
console.error("Background preview tabs stopped painting:");
83+
for (const failure of failures) console.error(` - ${failure}`);
84+
app.exit(1);
85+
return;
86+
}
87+
console.log("Background preview tabs paint while the app window is hidden or minimized.");
88+
app.exit(0);
89+
}
90+
91+
main().catch((error) => {
92+
console.error(error);
93+
app.exit(1);
94+
});
Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
// Proves agent preview tabs still paint while the app window is hidden or
2+
// minimized, using the exact window options the preview manager ships.
3+
// Agents open tabs whenever they like; a tab that cannot paint makes every
4+
// screenshot of it time out. Unit tests mock Electron, so only a real one can
5+
// catch this.
6+
import * as NodeChildProcess from "node:child_process";
7+
import * as NodeModule from "node:module";
8+
import * as NodePath from "node:path";
9+
import * as NodeURL from "node:url";
10+
11+
const RUN_TIMEOUT_MS = 90_000;
12+
const entry = NodePath.join(
13+
NodePath.dirname(NodeURL.fileURLToPath(import.meta.url)),
14+
"verify-background-preview.electron.cjs",
15+
);
16+
// The plain binary: the development launcher's renamed app bundle refuses data: URLs.
17+
const electronPath = NodeModule.createRequire(import.meta.url)("electron");
18+
const { ELECTRON_RUN_AS_NODE: _ignored, ...env } = process.env;
19+
const child = NodeChildProcess.spawn(electronPath, [entry], { stdio: "inherit", env });
20+
const timer = setTimeout(() => {
21+
console.error(`Background preview check did not finish within ${RUN_TIMEOUT_MS}ms.`);
22+
child.kill("SIGKILL");
23+
}, RUN_TIMEOUT_MS);
24+
child.on("exit", (code, signal) => {
25+
clearTimeout(timer);
26+
process.exit(code ?? (signal ? 1 : 0));
27+
});

‎apps/desktop/src/ipc/methods/preview.ts‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -80,9 +80,25 @@ const createTab = DesktopIpc.makeIpcMethod({
8080
zoomFactor,
8181
colorScheme,
8282
serverTab,
83+
background,
8384
}) {
8485
const manager = yield* PreviewManager.PreviewManager;
85-
yield* manager.createTab(tabId, { zoomFactor, colorScheme, serverTab });
86+
if (background === undefined) {
87+
yield* manager.createTab(tabId, { zoomFactor, colorScheme, serverTab });
88+
return;
89+
}
90+
const { scope, persistent, namespace } = resolvePartitionScope(
91+
background.environmentId,
92+
background.profileId,
93+
);
94+
// Loading the session installs its UA rewrite and permission handlers.
95+
yield* manager.getBrowserSession(scope, persistent, namespace);
96+
const partition = yield* manager.getBrowserPartition(scope, persistent, namespace);
97+
yield* manager.createTab(
98+
tabId,
99+
{ zoomFactor, colorScheme, serverTab },
100+
{ partition, url: background.url },
101+
);
86102
}),
87103
});
88104

‎apps/desktop/src/preload.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -327,6 +327,7 @@ contextBridge.exposeInMainWorld("desktopBridge", {
327327
zoomFactor: defaults?.zoomFactor,
328328
serverTab: defaults?.serverTab,
329329
colorScheme: defaults?.colorScheme,
330+
background: defaults?.background,
330331
}),
331332
closeTab: (tabId) => ipcRenderer.invoke(IpcChannels.PREVIEW_CLOSE_TAB_CHANNEL, { tabId }),
332333
registerWebview: (tabId, webContentsId) =>
Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
import type { BrowserWindowConstructorOptions } from "electron";
2+
3+
// Kept free of runtime imports: scripts/verify-background-preview.mjs loads it
4+
// straight into Electron to prove these options still paint while the app
5+
// window is hidden.
6+
7+
// The server sizes the page through emulation; this only seeds the window.
8+
const BACKGROUND_TAB_WIDTH = 1280;
9+
const BACKGROUND_TAB_HEIGHT = 800;
10+
11+
/**
12+
* An agent tab's never-shown window. A panel `<webview>` that attaches while
13+
* the app window is hidden or minimized never paints, so its screenshots never
14+
* return; a window of its own paints in every app window state.
15+
*/
16+
export function backgroundTabWindowOptions(input: {
17+
readonly partition: string;
18+
readonly preload: string;
19+
readonly passkeyBridgeArgument: string | undefined;
20+
}): BrowserWindowConstructorOptions {
21+
return {
22+
width: BACKGROUND_TAB_WIDTH,
23+
height: BACKGROUND_TAB_HEIGHT,
24+
show: false,
25+
paintWhenInitiallyHidden: true,
26+
skipTaskbar: true,
27+
webPreferences: {
28+
partition: input.partition,
29+
preload: input.preload,
30+
// Mirrors `will-attach-webview` for panel guests.
31+
sandbox: true,
32+
nodeIntegration: false,
33+
nodeIntegrationInSubFrames: false,
34+
contextIsolation: false,
35+
disableHtmlFullscreenWindowResize: true,
36+
backgroundThrottling: false,
37+
...(input.passkeyBridgeArgument === undefined
38+
? {}
39+
: { additionalArguments: [input.passkeyBridgeArgument] }),
40+
},
41+
};
42+
}

‎apps/desktop/src/preview/DesktopBrowserHost.test.ts‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -55,18 +55,18 @@ describe("DesktopBrowserHost", () => {
5555
it.effect("announces tabs already attached to a backend that starts later", () =>
5656
Effect.gen(function* () {
5757
const host = yield* DesktopBrowserHost.make;
58-
host.attach(key, makeDebuggee().tab);
58+
host.attach(key, makeDebuggee().tab, false);
5959

60-
expect(yield* takeEvents(host, 1)).toEqual([{ type: "attached", ...key }]);
61-
expect(yield* takeEvents(host, 1)).toEqual([{ type: "attached", ...key }]);
60+
expect(yield* takeEvents(host, 1)).toEqual([{ type: "attached", ...key, background: false }]);
61+
expect(yield* takeEvents(host, 1)).toEqual([{ type: "attached", ...key, background: false }]);
6262
}),
6363
);
6464

6565
it.effect("drops replies from a relay the server released", () =>
6666
Effect.gen(function* () {
6767
const host = yield* DesktopBrowserHost.make;
6868
const debuggee = makeDebuggee();
69-
host.attach(key, debuggee.tab);
69+
host.attach(key, debuggee.tab, false);
7070
const reader = yield* takeEvents(host, 2).pipe(Effect.forkScoped);
7171

7272
yield* Effect.yieldNow;
@@ -93,7 +93,7 @@ describe("DesktopBrowserHost", () => {
9393
Effect.gen(function* () {
9494
const host = yield* DesktopBrowserHost.make;
9595
const debuggee = makeDebuggee();
96-
host.attach(key, debuggee.tab);
96+
host.attach(key, debuggee.tab, false);
9797
const paths: Array<string> = [];
9898
const item = {
9999
setSavePath: (path: string) => void paths.push(path),
@@ -121,7 +121,7 @@ describe("DesktopBrowserHost", () => {
121121
Effect.gen(function* () {
122122
const host = yield* DesktopBrowserHost.make;
123123
const debuggee = makeDebuggee();
124-
host.attach(key, debuggee.tab);
124+
host.attach(key, debuggee.tab, false);
125125

126126
yield* host.handleCommandLine(
127127
encodeJson({

‎apps/desktop/src/preview/DesktopBrowserHost.ts‎

Lines changed: 15 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@ const keyOf = ({ threadId, tabId }: DesktopBrowserTabKey) => `${threadId}\u0000$
4242
interface AttachedTab {
4343
readonly key: DesktopBrowserTabKey;
4444
readonly debuggee: DesktopBrowserTabDebugger;
45+
readonly background: boolean;
4546
relay: CdpRelayConnection | null;
4647
downloadDirectory: string | null;
4748
pendingDownloadGuid: string | null;
@@ -59,7 +60,12 @@ export class DesktopBrowserHost extends Context.Service<
5960
{
6061
readonly events: Stream.Stream<Uint8Array>;
6162
readonly handleCommandLine: (line: string) => Effect.Effect<void>;
62-
readonly attach: (key: DesktopBrowserTabKey, debuggee: DesktopBrowserTabDebugger) => void;
63+
/** `background` tabs live in a never-shown window that no panel sizes. */
64+
readonly attach: (
65+
key: DesktopBrowserTabKey,
66+
debuggee: DesktopBrowserTabDebugger,
67+
background: boolean,
68+
) => void;
6369
readonly detach: (key: DesktopBrowserTabKey) => void;
6470
readonly humanStartedDownload: (source: Electron.WebContents) => boolean;
6571
readonly placeDownload: (source: Electron.WebContents, item: Electron.DownloadItem) => boolean;
@@ -137,13 +143,18 @@ export const make = Effect.gen(function* () {
137143
emit({ type: "detached", ...key });
138144
};
139145

140-
const attach = (key: DesktopBrowserTabKey, debuggee: DesktopBrowserTabDebugger) => {
146+
const attach = (
147+
key: DesktopBrowserTabKey,
148+
debuggee: DesktopBrowserTabDebugger,
149+
background: boolean,
150+
) => {
141151
const id = keyOf(key);
142152
if (tabs.get(id)?.debuggee.webContents === debuggee.webContents) return;
143153
detach(key);
144154
const tab: AttachedTab = {
145155
key,
146156
debuggee,
157+
background,
147158
relay: null,
148159
downloadDirectory: null,
149160
pendingDownloadGuid: null,
@@ -158,7 +169,7 @@ export const make = Effect.gen(function* () {
158169
};
159170
tabs.set(id, tab);
160171
debuggee.debugger.on("message", tab.onMessage);
161-
emit({ type: "attached", ...key });
172+
emit({ type: "attached", ...key, background });
162173
};
163174

164175
const handleCommandLine = (line: string) =>
@@ -190,7 +201,7 @@ export const make = Effect.gen(function* () {
190201
[...tabs.values()],
191202
(tab) => {
192203
tab.relay = null;
193-
return PubSub.publish(outbox, { type: "attached", ...tab.key });
204+
return PubSub.publish(outbox, { type: "attached", ...tab.key, background: tab.background });
194205
},
195206
{ discard: true },
196207
),

0 commit comments

Comments
 (0)