@devries-cameron20 / t3code-1 / commits / 3c188189cf
Fork 0

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 ) {