The best way to control Claude Code, Codex and more from any computer or phone
fix(desktop): capture fresh pixels from background previews (#19931)
Co-authored-by: Julius Marminge <julius0216@outlook.com>
Luís Miguel committed
Oct 20, 2026 at 06:31 UTC
3c188189cf7464ab5f3cf4007d94b9c7675b8328
2 files changed
+492
-5
apps/desktop/src/preview/Manager.test.ts
+391
-3
@@ -1,3 +1,4 @@
1
+import * as NodeVM from "node:vm";
2
import { it as effectIt } from "@effect/vitest";
3
import * as NodeCrypto from "@effect/platform-node/NodeCrypto";
4
import { DESKTOP_PREVIEW_RECORDING_CAPTURE_TRIGGER } from "@t3tools/contracts";
@@ -411,6 +412,44 @@ const makeTestPreviewWebContents = (
412
} as unknown as TestPreviewWebContents;
413
};
414
415
+const makeStillImage = (pixels = "fresh-png") => ({
416
+ toPNG: () => Buffer.from(pixels),
417
+ toJPEG: () => Buffer.from(pixels),
418
+ getSize: () => ({ width: 100, height: 80 }),
419
+});
420
+
421
+const makeTestStillImageWebContents = (...args: Parameters<typeof makeTestPreviewWebContents>) => {
422
+ const wc = makeTestPreviewWebContents(...args);
423
+ Object.assign(wc, { isDevToolsOpened: () => false });
424
+ holdStillImagePaint(wc, Promise.resolve());
425
+ return wc;
426
+};
427
+
428
+const holdStillImagePaint = (wc: TestPreviewWebContents, paint: Promise<void>) => {
429
+ vi.mocked(wc.debugger.sendCommand).mockImplementation(async (method) => {
430
+ if (method === "Page.getFrameTree") return { frameTree: { frame: { id: "main" } } };
431
+ if (method === "Page.createIsolatedWorld") return { executionContextId: 7 };
432
+ if (method === "Runtime.evaluate") {
433
+ await paint;
434
+ return { result: { value: true } };
435
+ }
436
+ return undefined;
437
+ });
438
+};
439
+
440
+const setupStill = (manager: PreviewManager.PreviewManager["Service"], paint = Promise.resolve()) =>
441
+ Effect.gen(function* () {
442
+ const image = makeStillImage();
443
+ const capturePage = vi.fn<() => Promise<typeof image>>().mockResolvedValue(image);
444
+ const wc = makeTestStillImageWebContents(capturePage);
445
+ holdStillImagePaint(wc, paint);
446
+ fromId.mockReturnValue(wc);
447
+ yield* manager.createTab("tab_still");
448
+ yield* manager.registerWebview("tab_still", wc.id);
449
+ yield* manager.setColorScheme("tab_still", "system");
450
+ return { image, capturePage, wc, capture: manager.captureScreenshot("tab_still") };
451
+ });
452
+
453
const setupRecordingRaceTabs = (manager: PreviewManager.PreviewManager["Service"]) =>
454
Effect.gen(function* () {
455
const capturePage = vi.fn(async () => ({
@@ -2501,6 +2540,7 @@ describe("PreviewManager", () => {
2540
isDestroyed: () => false,
2541
getType: () => "webview",
2542
getURL: () => "https://example.com:8443/path?query=value",
2543
+ setBackgroundThrottling: vi.fn(),
2544
getTitle: () => "Example",
2545
isLoadingMainFrame: () => false,
2546
getZoomFactor: () => 1,
@@ -2539,7 +2579,7 @@ describe("PreviewManager", () => {
2579
2580
const artifact = yield* manager.captureScreenshot("tab_1");
2581
2542
- expect(capturePage).toHaveBeenCalledOnce();
2582
+ expect(capturePage).toHaveBeenCalledTimes(2);
2583
expect(mkdir).toHaveBeenCalledWith("/tmp/t3/dev/browser-artifacts");
2584
expect(writeFile).toHaveBeenCalledWith(artifact.path, png);
2585
expect(artifact).toMatchObject({
@@ -2562,18 +2602,21 @@ describe("PreviewManager", () => {
2602
yield* TestClock.adjust(1_000);
2603
const retriedExit = yield* Fiber.join(retriedFiber);
2604
expect(Exit.isSuccess(retriedExit)).toBe(true);
2565
- expect(capturePage).toHaveBeenCalledTimes(3);
2605
+ expect(capturePage).toHaveBeenCalledTimes(4);
2606
2607
capturePage.mockClear();
2608
const captureCause = new Error("capture failed");
2609
capturePage.mockRejectedValue(captureCause);
2610
+ const writesBeforeFailure = writeFile.mock.calls.length;
2611
const failingFiber = yield* Effect.exit(manager.captureScreenshot("tab_1")).pipe(
2612
Effect.forkChild({ startImmediately: true }),
2613
);
2614
yield* TestClock.adjust(1_000);
2615
const exit = yield* Fiber.join(failingFiber);
2616
expect(Exit.isFailure(exit)).toBe(true);
2576
- expect(capturePage).toHaveBeenCalledTimes(3);
2617
+ expect(capturePage).toHaveBeenCalledTimes(6);
2618
+ expect(writeFile).toHaveBeenCalledTimes(writesBeforeFailure);
2619
+ expect(fromId(42)?.setBackgroundThrottling).toHaveBeenLastCalledWith(true);
2620
if (Exit.isSuccess(exit)) return;
2621
const error = Option.getOrThrow(Cause.findErrorOption(exit.cause));
2622
expect(error).toMatchObject({
@@ -2587,6 +2630,30 @@ describe("PreviewManager", () => {
2630
),
2631
);
2632
2633
+ effectIt.effect("captures final pixels after warmup fails and paint readiness settles", () =>
2634
+ withManager((manager) =>
2635
+ Effect.gen(function* () {
2636
+ const paint = Promise.withResolvers<void>();
2637
+ const { capturePage, wc, capture } = yield* setupStill(manager, paint.promise);
2638
+ capturePage
2639
+ .mockRejectedValueOnce(new Error("UnknownVizError"))
2640
+ .mockRejectedValueOnce(new Error("UnknownVizError"))
2641
+ .mockRejectedValueOnce(new Error("UnknownVizError"))
2642
+ .mockResolvedValue(makeStillImage("final-png"));
2643
+ const fiber = yield* capture.pipe(Effect.forkChild({ startImmediately: true }));
2644
+ yield* TestClock.adjust(300);
2645
+ expect(capturePage).toHaveBeenCalledTimes(3);
2646
+ expect(writeFile).not.toHaveBeenCalled();
2647
+ expect(wc.setBackgroundThrottling.mock.calls).toEqual([[false]]);
2648
+ paint.resolve();
2649
+ const artifact = yield* Fiber.join(fiber);
2650
+ expect(capturePage).toHaveBeenCalledTimes(4);
2651
+ expect(writeFile.mock.calls).toEqual([[artifact.path, Buffer.from("final-png")]]);
2652
+ expect(wc.setBackgroundThrottling.mock.calls).toEqual([[false], [true]]);
2653
+ }),
2654
+ ),
2655
+ );
2656
+
2657
effectIt.effect("preserves both screenshots of the same site in the same millisecond", () =>
2658
withManager((manager) =>
2659
Effect.gen(function* () {
@@ -2600,6 +2667,8 @@ describe("PreviewManager", () => {
2667
const capturePage = vi
2668
.fn<() => Promise<ReturnType<typeof pngImage>>>()
2669
.mockResolvedValueOnce(pngImage(firstPng))
2670
+ .mockResolvedValueOnce(pngImage(firstPng))
2671
+ .mockResolvedValueOnce(pngImage(secondPng))
2672
.mockResolvedValueOnce(pngImage(secondPng));
2673
fromId.mockReturnValue(makeTestPreviewWebContents(capturePage));
2674
yield* manager.createTab("tab_1");
@@ -2621,6 +2690,325 @@ describe("PreviewManager", () => {
2690
),
2691
);
2692
2693
+ effectIt.effect(
2694
+ "waits for paint before capturing and restores rendering after overlapping requests",
2695
+ () =>
2696
+ withManager((manager) =>
2697
+ Effect.gen(function* () {
2698
+ const paint = Promise.withResolvers<void>();
2699
+ const { image, capturePage, wc, capture } = yield* setupStill(manager, paint.promise);
2700
+ const first = Promise.withResolvers<typeof image>();
2701
+ const second = Promise.withResolvers<typeof image>();
2702
+ capturePage
2703
+ .mockResolvedValueOnce(makeStillImage("discarded-warmup"))
2704
+ .mockResolvedValueOnce(makeStillImage("discarded-warmup"))
2705
+ .mockReturnValueOnce(first.promise)
2706
+ .mockReturnValueOnce(second.promise);
2707
+ const hostThrottling = vi.fn();
2708
+ yield* manager.setMainWindow({
2709
+ isDestroyed: () => false,
2710
+ once: vi.fn(),
2711
+ webContents: { setBackgroundThrottling: hostThrottling },
2712
+ } as never);
2713
+ const one = yield* capture.pipe(Effect.forkChild({ startImmediately: true }));
2714
+ const two = yield* capture.pipe(Effect.forkChild({ startImmediately: true }));
2715
+ yield* TestClock.adjust(0);
2716
+ expect(capturePage).toHaveBeenCalledTimes(2);
2717
+ expect(writeFile).not.toHaveBeenCalled();
2718
+ expect(hostThrottling.mock.calls).toEqual([[false]]);
2719
+ expect(wc.setBackgroundThrottling.mock.calls).toEqual([[false]]);
2720
+ paint.resolve();
2721
+ yield* TestClock.adjust(0);
2722
+ expect(capturePage).toHaveBeenCalledTimes(4);
2723
+ first.resolve(image);
2724
+ yield* Fiber.join(one);
2725
+ expect(wc.setBackgroundThrottling.mock.calls).toEqual([[false]]);
2726
+ second.resolve(image);
2727
+ yield* Fiber.join(two);
2728
+ expect(writeFile.mock.calls.map((call) => call[1])).toEqual([
2729
+ Buffer.from("fresh-png"),
2730
+ Buffer.from("fresh-png"),
2731
+ ]);
2732
+ expect(hostThrottling.mock.calls).toEqual([[false], [true]]);
2733
+ expect(wc.setBackgroundThrottling.mock.calls).toEqual([[false], [true]]);
2734
+ }),
2735
+ ),
2736
+ );
2737
+
2738
+ effectIt.effect("keeps picture-in-picture rendering after a still image completes", () =>
2739
+ withManager((manager) =>
2740
+ Effect.gen(function* () {
2741
+ const { image, capturePage, wc, capture } = yield* setupStill(manager);
2742
+ const pending = Promise.withResolvers<typeof image>();
2743
+ capturePage
2744
+ .mockResolvedValueOnce(image)
2745
+ .mockResolvedValueOnce(makeStillImage("discarded-warmup"))
2746
+ .mockReturnValueOnce(pending.promise);
2747
+ const { pictureInPictureWindow } = makeTestPictureInPictureWindow();
2748
+ browserWindowConstructor.mockImplementation(function () {
2749
+ return pictureInPictureWindow;
2750
+ });
2751
+ yield* manager.openPictureInPicture("tab_still");
2752
+ const still = yield* capture.pipe(Effect.forkChild({ startImmediately: true }));
2753
+ yield* TestClock.adjust(0);
2754
+ expect(capturePage).toHaveBeenCalledTimes(3);
2755
+ expect(writeFile).not.toHaveBeenCalled();
2756
+ pending.resolve(image);
2757
+ yield* Fiber.join(still);
2758
+ expect(writeFile.mock.calls.map((call) => call[1])).toEqual([Buffer.from("fresh-png")]);
2759
+ expect(wc.setBackgroundThrottling.mock.calls).toEqual([[false]]);
2760
+ yield* manager.closePictureInPicture("tab_still");
2761
+ expect(wc.setBackgroundThrottling.mock.calls).toEqual([[false], [true]]);
2762
+ }),
2763
+ ),
2764
+ );
2765
+
2766
+ effectIt.effect("keeps a pending still image rendering when recording ends", () =>
2767
+ withManager((manager) =>
2768
+ Effect.gen(function* () {
2769
+ const { image, capturePage, wc, capture } = yield* setupStill(manager);
2770
+ const pending = Promise.withResolvers<typeof image>();
2771
+ capturePage.mockResolvedValueOnce(image).mockReturnValue(pending.promise);
2772
+ yield* manager.startRecording("tab_still");
2773
+ const fiber = yield* capture.pipe(Effect.forkChild({ startImmediately: true }));
2774
+ yield* TestClock.adjust(0);
2775
+ yield* manager.stopRecording("tab_still");
2776
+ expect(wc.setBackgroundThrottling.mock.calls).toEqual([[false]]);
2777
+ pending.resolve(image);
2778
+ yield* Fiber.join(fiber);
2779
+ expect(wc.setBackgroundThrottling.mock.calls).toEqual([[false], [true]]);
2780
+ }),
2781
+ ),
2782
+ );
2783
+
2784
+ effectIt.effect(
2785
+ "ignores late native warmup completion after interruption while recording owns rendering",
2786
+ () =>
2787
+ withManager((manager) =>
2788
+ Effect.gen(function* () {
2789
+ const { image, capturePage, wc, capture } = yield* setupStill(manager);
2790
+ const warmup = Promise.withResolvers<typeof image>();
2791
+ let nativeCompleted = false;
2792
+ const nativePromise = warmup.promise.then((result) => {
2793
+ nativeCompleted = true;
2794
+ return result;
2795
+ });
2796
+ capturePage.mockReturnValueOnce(nativePromise);
2797
+ const fiber = yield* capture.pipe(Effect.forkChild({ startImmediately: true }));
2798
+ yield* TestClock.adjust(0);
2799
+ yield* manager.startRecording("tab_still");
2800
+ yield* Fiber.interrupt(fiber);
2801
+ expect(nativeCompleted).toBe(false);
2802
+ expect(wc.setBackgroundThrottling.mock.calls).toEqual([[false]]);
2803
+ warmup.resolve(image);
2804
+ yield* TestClock.adjust(0);
2805
+ expect(nativeCompleted).toBe(true);
2806
+ expect(capturePage).toHaveBeenCalledTimes(2);
2807
+ expect(writeFile).not.toHaveBeenCalled();
2808
+ expect(wc.setBackgroundThrottling.mock.calls).toEqual([[false]]);
2809
+ yield* manager.stopRecording("tab_still");
2810
+ expect(wc.setBackgroundThrottling.mock.calls).toEqual([[false], [true]]);
2811
+ }),
2812
+ ),
2813
+ );
2814
+
2815
+ effectIt.effect(
2816
+ "ignores an interrupted warmup that resolves while the replacement guest is capturing",
2817
+ () =>
2818
+ withManager((manager) =>
2819
+ Effect.gen(function* () {
2820
+ const fresh = makeStillImage("replacement-png");
2821
+ const late = Promise.withResolvers<typeof fresh>();
2822
+ const finalCapture = Promise.withResolvers<typeof fresh>();
2823
+ const oldCapture = vi.fn(() => late.promise);
2824
+ const replacementCapture = vi
2825
+ .fn()
2826
+ .mockResolvedValueOnce(fresh)
2827
+ .mockReturnValue(finalCapture.promise);
2828
+ const hostThrottling = vi.fn();
2829
+ const host = Object.assign(makeTestHostWebContents(), {
2830
+ setBackgroundThrottling: hostThrottling,
2831
+ });
2832
+ const original = makeTestStillImageWebContents(oldCapture, 42, host);
2833
+ const replacement = makeTestStillImageWebContents(replacementCapture, 43, host);
2834
+ holdStillImagePaint(original, new Promise(() => {}));
2835
+ fromId.mockImplementation((id) => (id === 42 ? original : replacement));
2836
+ yield* manager.createTab("tab_still");
2837
+ yield* manager.registerWebview("tab_still", 42);
2838
+ yield* manager.setColorScheme("tab_still", "system");
2839
+ yield* manager.setMainWindow({
2840
+ isDestroyed: () => false,
2841
+ once: vi.fn(),
2842
+ webContents: host,
2843
+ } as never);
2844
+ const failed = yield* Effect.exit(manager.captureScreenshot("tab_still")).pipe(
2845
+ Effect.forkChild({ startImmediately: true }),
2846
+ );
2847
+ yield* TestClock.adjust(0);
2848
+ yield* Fiber.interrupt(failed);
2849
+ yield* manager.registerWebview("tab_still", 43);
2850
+ yield* manager.setColorScheme("tab_still", "system");
2851
+ const healthy = yield* manager
2852
+ .captureScreenshot("tab_still")
2853
+ .pipe(Effect.forkChild({ startImmediately: true }));
2854
+ yield* TestClock.adjust(0);
2855
+ late.resolve({ ...fresh, toPNG: () => Buffer.from("late-old-warmup") });
2856
+ yield* TestClock.adjust(0);
2857
+ expect(writeFile).not.toHaveBeenCalled();
2858
+ expect(oldCapture).toHaveBeenCalledOnce();
2859
+ expect(replacementCapture).toHaveBeenCalledTimes(2);
2860
+ expect(hostThrottling.mock.calls).toEqual([[false], [true], [false]]);
2861
+ expect(replacement.setBackgroundThrottling.mock.calls).toEqual([[false]]);
2862
+ finalCapture.resolve(fresh);
2863
+ yield* Fiber.join(healthy);
2864
+ expect(writeFile.mock.calls.map((call) => call[1])).toEqual([
2865
+ Buffer.from("replacement-png"),
2866
+ ]);
2867
+ expect(hostThrottling.mock.calls).toEqual([[false], [true], [false], [true]]);
2868
+ expect(replacement.setBackgroundThrottling.mock.calls).toEqual([[false], [true]]);
2869
+ }),
2870
+ ),
2871
+ );
2872
+
2873
+ effectIt.effect("paints a loading document with isolated scheduling despite page overrides", () =>
2874
+ withManager((manager) =>
2875
+ Effect.gen(function* () {
2876
+ for (const mode of ["suppressed", "synchronous", "timeout-before", "timeout-after"]) {
2877
+ writeFile.mockClear();
2878
+ let pixels = "old-pixels";
2879
+ const frames: Array<() => void> = [];
2880
+ let expire = () => {};
2881
+ let paintConfirmed: unknown;
2882
+ const clearTimeout = vi.fn();
2883
+ const probeStarted = Promise.withResolvers<void>();
2884
+ const pageFrame = vi.fn((callback: () => void) => {
2885
+ if (mode === "synchronous") callback();
2886
+ });
2887
+ const page = NodeVM.createContext({
2888
+ Promise: undefined,
2889
+ requestAnimationFrame: pageFrame,
2890
+ });
2891
+ const isolated = NodeVM.createContext({
2892
+ requestAnimationFrame: (callback: () => void) => frames.push(callback),
2893
+ cancelAnimationFrame: (id: number) => {
2894
+ frames.splice(id - 1, 1);
2895
+ },
2896
+ setTimeout: (callback: () => void, delay: number) => {
2897
+ expect(delay).toBe(1_000);
2898
+ expire = callback;
2899
+ return 1;
2900
+ },
2901
+ clearTimeout,
2902
+ });
2903
+ const capturePage = vi.fn(async () => makeStillImage(pixels));
2904
+ const wc = makeTestStillImageWebContents(capturePage);
2905
+ Object.assign(wc, { isLoading: () => true });
2906
+ vi.mocked(wc.executeJavaScript).mockImplementation(async (expression) =>
2907
+ NodeVM.runInContext(expression, page),
2908
+ );
2909
+ vi.mocked(wc.debugger.sendCommand).mockImplementation(async (method, params) => {
2910
+ if (method === "Page.getFrameTree") return { frameTree: { frame: { id: "main" } } };
2911
+ if (method === "Page.createIsolatedWorld") return { executionContextId: 7 };
2912
+ if (method === "Runtime.evaluate") {
2913
+ const pending = NodeVM.runInContext(params?.["expression"] as string, isolated);
2914
+ probeStarted.resolve();
2915
+ paintConfirmed = await pending;
2916
+ return { result: { value: paintConfirmed } };
2917
+ }
2918
+ return undefined;
2919
+ });
2920
+ fromId.mockReturnValue(wc);
2921
+ const tabId = `tab_loading_${mode}`;
2922
+ yield* manager.createTab(tabId);
2923
+ yield* manager.registerWebview(tabId, wc.id);
2924
+ yield* manager.setColorScheme(tabId, "system");
2925
+ const still = yield* manager
2926
+ .captureScreenshot(tabId)
2927
+ .pipe(Effect.forkChild({ startImmediately: true }));
2928
+ yield* Effect.promise(() => probeStarted.promise);
2929
+ yield* TestClock.adjust(0);
2930
+ expect(capturePage).toHaveBeenCalledOnce();
2931
+ expect(writeFile).not.toHaveBeenCalled();
2932
+ if (mode !== "timeout-before") frames.shift()?.();
2933
+ pixels = "new-pixels";
2934
+ yield* TestClock.adjust(0);
2935
+ expect(writeFile).not.toHaveBeenCalled();
2936
+ if (mode.startsWith("timeout")) expire();
2937
+ else frames.shift()?.();
2938
+ yield* Fiber.join(still);
2939
+ expect(paintConfirmed).toBe(!mode.startsWith("timeout"));
2940
+ expect(frames).toHaveLength(0);
2941
+ expect(clearTimeout.mock.calls).toEqual(mode.startsWith("timeout") ? [] : [[1]]);
2942
+ expect(writeFile.mock.calls.map((call) => call[1])).toEqual([Buffer.from("new-pixels")]);
2943
+ expect(pageFrame).not.toHaveBeenCalled();
2944
+ expect(wc.setBackgroundThrottling.mock.calls).toEqual([[false], [true]]);
2945
+ yield* manager.closeTab(tabId);
2946
+ }
2947
+ }),
2948
+ ),
2949
+ );
2950
+
2951
+ effectIt.effect("captures available pixels without taking another debugger's ownership", () =>
2952
+ withManager((manager) =>
2953
+ Effect.gen(function* () {
2954
+ for (const devToolsOpen of [true, false]) {
2955
+ const capturePage = vi.fn(async () => makeStillImage("available-pixels"));
2956
+ const wc = makeTestStillImageWebContents(capturePage);
2957
+ Object.assign(wc, { isDevToolsOpened: () => devToolsOpen });
2958
+ vi.spyOn(wc.debugger, "isAttached").mockReturnValue(true);
2959
+ fromId.mockReturnValue(wc);
2960
+ const tabId = `tab_foreign_debugger_${devToolsOpen}`;
2961
+ yield* manager.createTab(tabId);
2962
+ yield* manager.registerWebview(tabId, wc.id);
2963
+ yield* manager.captureScreenshot(tabId);
2964
+ expect(capturePage).toHaveBeenCalledTimes(2);
2965
+ expect(wc.debugger.attach).not.toHaveBeenCalled();
2966
+ expect(wc.debugger.sendCommand).not.toHaveBeenCalled();
2967
+ expect(writeFile).toHaveBeenLastCalledWith(
2968
+ expect.any(String),
2969
+ Buffer.from("available-pixels"),
2970
+ );
2971
+ expect(wc.setBackgroundThrottling.mock.calls).toEqual([[false], [true]]);
2972
+ yield* manager.closeTab(tabId);
2973
+ }
2974
+ }),
2975
+ ),
2976
+ );
2977
+
2978
+ effectIt.effect(
2979
+ "bounds paint readiness and ignores its late completion during another capture",
2980
+ () =>
2981
+ withManager((manager) =>
2982
+ Effect.gen(function* () {
2983
+ const paint = Promise.withResolvers<void>();
2984
+ const { image, capturePage, wc, capture } = yield* setupStill(manager, paint.promise);
2985
+ const first = yield* Effect.exit(capture).pipe(
2986
+ Effect.forkChild({ startImmediately: true }),
2987
+ );
2988
+ yield* TestClock.adjust(1_001);
2989
+ expect(Exit.isSuccess(yield* Fiber.join(first))).toBe(true);
2990
+ expect(capturePage).toHaveBeenCalledTimes(2);
2991
+ expect(writeFile.mock.calls.map((call) => call[1])).toEqual([Buffer.from("fresh-png")]);
2992
+ expect(wc.setBackgroundThrottling.mock.calls).toEqual([[false], [true]]);
2993
+
2994
+ holdStillImagePaint(wc, Promise.resolve());
2995
+ const finalCapture = Promise.withResolvers<typeof image>();
2996
+ capturePage.mockResolvedValueOnce(image).mockReturnValueOnce(finalCapture.promise);
2997
+ const second = yield* capture.pipe(Effect.forkChild({ startImmediately: true }));
2998
+ yield* TestClock.adjust(0);
2999
+ paint.resolve();
3000
+ yield* TestClock.adjust(0);
3001
+ expect(writeFile).toHaveBeenCalledOnce();
3002
+ expect(capturePage).toHaveBeenCalledTimes(4);
3003
+ expect(wc.setBackgroundThrottling.mock.calls).toEqual([[false], [true], [false]]);
3004
+ finalCapture.resolve(image);
3005
+ yield* Fiber.join(second);
3006
+ expect(writeFile).toHaveBeenCalledTimes(2);
3007
+ expect(wc.setBackgroundThrottling.mock.calls).toEqual([[false], [true], [false], [true]]);
3008
+ }),
3009
+ ),
3010
+ );
3011
+
3012
effectIt.effect("keeps every recorded guest unthrottled until its frame capture stops", () =>
3013
withManager((manager) =>
3014
Effect.gen(function* () {
apps/desktop/src/preview/Manager.ts
+101
-2
@@ -391,7 +391,8 @@ interface ManagedListeners {
391
readonly webContents: Electron.WebContents;
392
}
393
394
-type FrameCaptureConsumer = "picture-in-picture" | "recording";
394
+// Each still-image request owns a separate, short-lived rendering lease.
395
+type FrameCaptureConsumer = "picture-in-picture" | "recording" | symbol;
396
397
interface FrameCaptureSession {
398
readonly recordingInputOptions?: RecordingInputOptions;
@@ -2487,7 +2488,7 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
2488
const [createdAt, millis, image] = yield* Effect.all([
2489
currentIso,
2490
currentMillis,
2490
- capturePageWithRetry(
2491
+ captureStillImage(
2492
{
2493
operation: "captureScreenshot.capturePage",
2494
tabId,
@@ -2535,6 +2536,104 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
2536
};
2537
});
2538
2539
+ const captureStillImage = Effect.fn("PreviewManager.captureStillImage")(function* (
2540
+ errorContext: PreviewOperationContext,
2541
+ tabId: string,
2542
+ wc: Electron.WebContents,
2543
+ ) {
2544
+ const consumer = Symbol("still-image");
2545
+ return yield* Effect.acquireUseRelease(
2546
+ startFrameCapture(tabId, consumer),
2547
+ () =>
2548
+ Effect.gen(function* () {
2549
+ // A DOM mutation can precede its compositor frame even in a shown
2550
+ // window. Keep the original guest rendering through the next paint;
2551
+ // a hidden guest otherwise returns old pixels or never completes.
2552
+ const probe = Effect.fn("PreviewManager.probeStillImagePaint")(function* (
2553
+ send: (
2554
+ method: string,
2555
+ params?: Record<string, unknown>,
2556
+ ) => Effect.Effect<unknown, PreviewOperationError>,
2557
+ ) {
2558
+ // CDP executes against the current document without Electron's
2559
+ // did-stop-loading gate. Isolate scheduling globals from page code.
2560
+ const tree = (yield* send("Page.getFrameTree")) as
2561
+ | { frameTree?: { frame?: { id?: string } } }
2562
+ | undefined;
2563
+ const frameId = tree?.frameTree?.frame?.id;
2564
+ if (typeof frameId !== "string")
2565
+ return yield* new PreviewOperationError({
2566
+ ...errorContext,
2567
+ cause: new Error("The preview paint frame is unavailable."),
2568
+ });
2569
+ const world = (yield* send("Page.createIsolatedWorld", {
2570
+ frameId,
2571
+ worldName: "t3-preview-still-image",
2572
+ })) as { executionContextId?: number } | undefined;
2573
+ if (typeof world?.executionContextId !== "number")
2574
+ return yield* new PreviewOperationError({
2575
+ ...errorContext,
2576
+ cause: new Error("The preview paint context is unavailable."),
2577
+ });
2578
+ const response = (yield* send("Runtime.evaluate", {
2579
+ // Settle and release scheduled work when only timers keep running.
2580
+ // The outer deadline still bounds a frozen renderer.
2581
+ expression: `new Promise(resolve => { let frame; const timer = setTimeout(() => { cancelAnimationFrame(frame); resolve(false); }, ${CAPTURE_PAGE_ATTEMPT_TIMEOUT_MS}); frame = requestAnimationFrame(() => { frame = requestAnimationFrame(() => { clearTimeout(timer); resolve(true); }); }); })`,
2582
+ contextId: world.executionContextId,
2583
+ awaitPromise: true,
2584
+ returnByValue: true,
2585
+ })) as { result?: { value?: unknown }; exceptionDetails?: unknown } | undefined;
2586
+ if (response?.exceptionDetails || response?.result?.value !== true)
2587
+ return yield* new PreviewOperationError({
2588
+ ...errorContext,
2589
+ cause: new Error("The preview paint boundary was not confirmed."),
2590
+ });
2591
+ });
2592
+ const paintReady = Effect.gen(function* () {
2593
+ // Only use an existing owned session; never attach or displace
2594
+ // another debugger to obtain a screenshot.
2595
+ const control = (yield* SynchronizedRef.get(controlSessionsRef)).get(wc.id);
2596
+ if (!control)
2597
+ return yield* new PreviewOperationError({
2598
+ ...errorContext,
2599
+ cause: new Error("The preview paint session is unavailable."),
2600
+ });
2601
+ return yield* control.semaphore.withPermit(
2602
+ probe((method, params) =>
2603
+ attemptPromise(errorContext, () => control.debugger.sendCommand(method, params)),
2604
+ ),
2605
+ );
2606
+ }).pipe(
2607
+ Effect.timeout(CAPTURE_PAGE_ATTEMPT_TIMEOUT_MS),
2608
+ Effect.catch((error) =>
2609
+ Effect.logWarning(
2610
+ "Preview paint readiness was not confirmed; capturing available pixels with mutation freshness unconfirmed.",
2611
+ { tabId, webContentsId: wc.id, error },
2612
+ ),
2613
+ ),
2614
+ );
2615
+ // capturePage temporarily marks the original guest as captured. A
2616
+ // minimized page can otherwise keep animation frames suspended even
2617
+ // with scheduler throttling disabled. Discard this warmup image and
2618
+ // accept its output only after readiness settles. If the bounded
2619
+ // probe cannot confirm paint, retain the native capture fallback.
2620
+ const warmup = capturePageWithRetry(errorContext, tabId, wc).pipe(
2621
+ Effect.catchTags({
2622
+ PreviewOperationError: (error) =>
2623
+ Effect.logWarning("Preview warmup capture failed; continuing with final capture.", {
2624
+ tabId,
2625
+ webContentsId: wc.id,
2626
+ error,
2627
+ }),
2628
+ }),
2629
+ );
2630
+ yield* Effect.all([paintReady, warmup], { concurrency: 2, discard: true });
2631
+ return yield* capturePageWithRetry(errorContext, tabId, wc);
2632
+ }),
2633
+ () => stopFrameCapture(tabId, consumer),
2634
+ );
2635
+ });
2636
+
2637
const capturePreviewFrame = Effect.fn("PreviewManager.capturePreviewFrame")(function* (
2638
tabId: string,
2639
) {