@devries-cameron20 / t3code Mirror · read-only / commits / 984df7f156
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 22, 22:00 UTC

fix(preview): preserve actionable native capture errors (#17244)

Co-authored-by: Julius Marminge <julius0216@outlook.com> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Luís Miguel committed Oct 20, 2026 at 06:08 UTC 984df7f1566e34359e4eca2396076941d5365684
12 files changed +376 -26
apps/desktop/src/ipc/DesktopIpcHandlers.ts
+5 -1
@@ -166,7 +166,11 @@ export const installDesktopIpcHandlers = Effect.fn("desktop.ipc.installHandlers"
166 yield* ipc.handle(installCliCommand);
167 yield* ipc.handle(uninstallCliCommand);
168 for (const previewMethod of PreviewIpc.methods) {
169 - yield* ipc.handle(previewMethod);
169 + // Explicit types preserve the error/service union of these heterogeneous preview methods.
170 + yield* ipc.handle<
171 + Effect.Error<ReturnType<(typeof PreviewIpc.methods)[number]["handler"]>>,
172 + Effect.Services<ReturnType<(typeof PreviewIpc.methods)[number]["handler"]>>
173 + >(previewMethod);
174 }
175 yield* ipc.handle(PreviewIpc.listBrowserImportSources);
176 yield* ipc.handle(PreviewIpc.importBrowserCookies);
apps/desktop/src/ipc/methods/preview.test.ts
+98
@@ -3,6 +3,7 @@ import {
3 DEFAULT_BROWSER_PROFILE_ID,
4 INCOGNITO_BROWSER_PROFILE_ID,
5 PreviewAutomationStatus,
6 + PreviewCaptureFailure,
7 } from "@t3tools/contracts";
8 import * as Cause from "effect/Cause";
9 import * as Effect from "effect/Effect";
@@ -14,6 +15,8 @@ import { beforeEach, describe, expect, it, vi } from "vite-plus/test";
15 import * as PreviewManager from "../../preview/Manager.ts";
16 import * as BrowserImport from "../../preview/BrowserImport/BrowserImport.ts";
17 import * as PreviewIpc from "./preview.ts";
18 +import * as DesktopIpc from "../DesktopIpc.ts";
19 +import * as DesktopClientSettings from "../../settings/DesktopClientSettings.ts";
20
21 const { fromPartition } = vi.hoisted(() => ({
22 fromPartition: vi.fn(() => {
@@ -33,7 +36,102 @@ vi.mock("electron", () => ({
36 },
37 }));
38
39 +const decodeCaptureFailure = Schema.decodeUnknownEffect(PreviewCaptureFailure);
40 +
41 describe("preview IPC methods", () => {
42 + const invokeCapture = (
43 + method: typeof PreviewIpc.startRecording | typeof PreviewIpc.captureScreenshot,
44 + manager: Partial<PreviewManager.PreviewManager["Service"]>,
45 + ) =>
46 + Effect.scoped(
47 + Effect.gen(function* () {
48 + let listener: DesktopIpc.DesktopIpcHandleListener | undefined;
49 + const ipc = DesktopIpc.make({
50 + removeHandler: vi.fn(),
51 + handle: (_channel, registered) => {
52 + listener = registered;
53 + },
54 + removeAllListeners: vi.fn(),
55 + on: vi.fn(),
56 + });
57 + yield* ipc.handle(method);
58 + return yield* Effect.promise(async () =>
59 + structuredClone(await listener!({ sender: { id: 7 } }, { tabId: "capture-tab" })),
60 + );
61 + }).pipe(
62 + Effect.provideService(
63 + PreviewManager.PreviewManager,
64 + manager as PreviewManager.PreviewManager["Service"],
65 + ),
66 + Effect.provideService(DesktopClientSettings.DesktopClientSettings, {
67 + get: Effect.succeedNone,
68 + set: () => Effect.void,
69 + }),
70 + ),
71 + );
72 +
73 + effectIt.effect.each([
74 + {
75 + cause: new Error("Current display surface not available for capture"),
76 + reason: "capture-unavailable",
77 + guidance: ["target tab", "unlocked", "display is on", "window is restored"],
78 + },
79 + {
80 + cause: new Cause.TimeoutError(),
81 + reason: "capture-timeout",
82 + guidance: ["timed out during capture-page"],
83 + },
84 + {
85 + cause: new Error("Current display surface not available for capture: private page data"),
86 + reason: "capture-failed",
87 + guidance: ["Preview capture failed during capture-page"],
88 + },
89 + ])(
90 + "transports a safe $reason screenshot diagnostic through registered IPC",
91 + ({ cause, reason, guidance }) =>
92 + Effect.gen(function* () {
93 + const result = yield* invokeCapture(PreviewIpc.captureScreenshot, {
94 + captureScreenshot: (tabId) =>
95 + Effect.fail(
96 + new PreviewManager.PreviewOperationError({
97 + operation: "captureScreenshot.capturePage",
98 + tabId,
99 + artifactPath: "/private/capture.png",
100 + cause,
101 + }),
102 + ),
103 + });
104 + expect(result).toEqual({
105 + _tag: "PreviewCaptureFailure",
106 + reason,
107 + stage: "capture-page",
108 + });
109 + const failure = yield* decodeCaptureFailure(result);
110 + for (const phrase of guidance) expect(failure.message).toContain(phrase);
111 + }),
112 + );
113 +
114 + effectIt.effect("preserves recording arm failures without erasing successful void results", () =>
115 + Effect.gen(function* () {
116 + const result = yield* invokeCapture(PreviewIpc.startRecording, {
117 + startRecording: (tabId) =>
118 + Effect.fail(new PreviewManager.PreviewTabNotFoundError({ tabId })),
119 + });
120 + expect(result).toEqual({
121 + _tag: "PreviewCaptureFailure",
122 + reason: "renderer-unavailable",
123 + stage: "recording-start",
124 + });
125 + const failure = yield* decodeCaptureFailure(result);
126 + expect(failure.message).toContain("Reopen the preview tab");
127 + expect(
128 + yield* invokeCapture(PreviewIpc.startRecording, {
129 + startRecording: () => Effect.void,
130 + }),
131 + ).toBeUndefined();
132 + }),
133 + );
134 +
135 beforeEach(() => {
136 fromPartition.mockClear();
137 });
apps/desktop/src/ipc/methods/preview.ts
+13 -4
@@ -19,6 +19,7 @@ import {
19 DesktopPreviewTabInputSchema,
20 DesktopPreviewWebviewConfigSchema,
21 PreviewAnnotationSubmissionResultSchema,
22 + PreviewCaptureFailure,
23 DEFAULT_BROWSER_PROFILE_ID,
24 INCOGNITO_BROWSER_PROFILE_ID,
25 PreviewForwardedShortcut,
@@ -32,6 +33,7 @@ import * as NodeURL from "node:url";
33 import * as ElectronWindow from "../../electron/ElectronWindow.ts";
34 import * as BrowserImport from "../../preview/BrowserImport/BrowserImport.ts";
35 import * as PreviewManager from "../../preview/Manager.ts";
36 +import { normalizeCaptureFailure } from "../../preview/captureErrors.ts";
37 import * as DesktopClientSettings from "../../settings/DesktopClientSettings.ts";
38 import { PREVIEW_WEBVIEW_PREFERENCES } from "../../preview/WebviewPreferences.ts";
39 import * as IpcChannels from "../channels.ts";
@@ -207,7 +209,8 @@ export const cancelPickElement = tabMethod(
209 export const startRecording = DesktopIpc.makeIpcMethod({
210 channel: IpcChannels.PREVIEW_RECORDING_START_CHANNEL,
211 payload: DesktopPreviewTabInputSchema,
210 - result: Schema.Void,
212 + // Void encodes any value as undefined, so the tagged failure must be tried first.
213 + result: Schema.Union([PreviewCaptureFailure, Schema.Void]),
214 handler: Effect.fn("desktop.ipc.preview.startRecording")(function* ({ tabId }) {
215 const manager = yield* PreviewManager.PreviewManager;
216 const store = yield* DesktopClientSettings.DesktopClientSettings;
@@ -216,7 +219,11 @@ export const startRecording = DesktopIpc.makeIpcMethod({
219 showKeyPresses: value.browserRecordingShowKeyPresses,
220 showMousePresses: value.browserRecordingShowMousePresses,
221 }));
219 - yield* manager.startRecording(tabId, Option.getOrUndefined(options));
222 + return yield* manager
223 + .startRecording(tabId, Option.getOrUndefined(options))
224 + .pipe(
225 + Effect.catch((error) => Effect.succeed(normalizeCaptureFailure(error, "recording-start"))),
226 + );
227 }),
228 });
229 export const stopRecording = tabMethod(
@@ -390,10 +397,12 @@ export const setAnnotationSendEnabled = DesktopIpc.makeIpcMethod({
397 export const captureScreenshot = DesktopIpc.makeIpcMethod({
398 channel: IpcChannels.PREVIEW_CAPTURE_SCREENSHOT_CHANNEL,
399 payload: DesktopPreviewTabInputSchema,
393 - result: DesktopPreviewScreenshotArtifactSchema,
400 + result: Schema.Union([DesktopPreviewScreenshotArtifactSchema, PreviewCaptureFailure]),
401 handler: Effect.fn("desktop.ipc.preview.captureScreenshot")(function* ({ tabId }) {
402 const manager = yield* PreviewManager.PreviewManager;
396 - return yield* manager.captureScreenshot(tabId);
403 + return yield* manager
404 + .captureScreenshot(tabId)
405 + .pipe(Effect.catch((error) => Effect.succeed(normalizeCaptureFailure(error, "screenshot"))));
406 }),
407 });
408
apps/desktop/src/preview/captureErrors.ts new
+38
@@ -0,0 +1,38 @@
1 +import { PreviewCaptureFailure } from "@t3tools/contracts";
2 +import * as Cause from "effect/Cause";
3 +import type { PreviewManagerError } from "./Manager.ts";
4 +
5 +/** Classify before Electron replaces a rejected IPC Error with its message. */
6 +export function normalizeCaptureFailure(
7 + error: PreviewManagerError,
8 + stage: PreviewCaptureFailure["stage"],
9 +): PreviewCaptureFailure {
10 + let reason: PreviewCaptureFailure["reason"] = "capture-failed";
11 + switch (error._tag) {
12 + case "PreviewTabNotFoundError":
13 + case "PreviewWebContentsNotFoundError":
14 + case "PreviewMainWindowClosedError":
15 + reason = "renderer-unavailable";
16 + break;
17 + case "PreviewWebviewNotInitializedError":
18 + case "PreviewRecordingCaptureUnavailableError":
19 + reason = "capture-unavailable";
20 + break;
21 + case "PreviewRecordingArmConflictError":
22 + reason = "recording-conflict";
23 + break;
24 + case "PreviewOperationError":
25 + if (error.operation === "captureScreenshot.capturePage") {
26 + stage = "capture-page";
27 + if (
28 + error.cause instanceof Error &&
29 + error.cause.message === "Current display surface not available for capture"
30 + ) {
31 + reason = "capture-unavailable";
32 + }
33 + }
34 + if (Cause.isTimeoutError(error.cause)) reason = "capture-timeout";
35 + break;
36 + }
37 + return new PreviewCaptureFailure({ reason, stage });
38 +}
apps/web/src/browser/ElectronBrowserHost.browser.test.tsx
+1 -1
@@ -43,7 +43,7 @@ vi.mock(import("~/components/preview/previewBridge"), async (original) => ({
43 closeTab: mocks.closeTab,
44 registerWebview: mocks.registerWebview,
45 getPreviewConfig: mocks.getPreviewConfig,
46 - } as unknown as DesktopPreviewBridge,
46 + } as never,
47 }));
48
49 vi.mock(import("~/components/preview/usePreviewBridge"), async (original) => ({
apps/web/src/browser/HostedBrowserWebview.browser.test.tsx
+2 -1
@@ -12,6 +12,7 @@ import { act } from "react";
12 import "~/index.css";
13 import { createRoot, type Root } from "react-dom/client";
14 import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
15 +import type { previewBridge } from "~/components/preview/previewBridge";
16
17 const mocks = vi.hoisted(() => ({
18 getClientSettings: vi.fn<() => Promise<ClientSettings | null>>(),
@@ -41,7 +42,7 @@ vi.mock(import("~/components/preview/previewBridge"), async (original) => ({
42 closeTab: mocks.closeTab,
43 registerWebview: mocks.registerWebview,
44 getPreviewConfig: mocks.getPreviewConfig,
44 - } as unknown as DesktopPreviewBridge,
45 + } as unknown as NonNullable<typeof previewBridge>,
46 }));
47
48 vi.mock(import("~/components/preview/usePreviewBridge"), async (original) => ({
apps/web/src/browser/browserRecording.test.ts
+131 -15
@@ -2,12 +2,17 @@ import {
2 DESKTOP_PREVIEW_RECORDING_CAPTURE_TRIGGER,
3 EnvironmentId,
4 ThreadId,
5 + PreviewCaptureFailure,
6 + type DesktopPreviewBridge,
7 + type DesktopPreviewScreenshotArtifact,
8 + type PreviewCaptureFailureEncoded,
9 } from "@t3tools/contracts";
6 -import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
10 +import { afterEach, beforeEach, describe, expect, expectTypeOf, it, vi } from "vite-plus/test";
11
12 import { ensureClientSettingsHydrated } from "~/hooks/useSettings";
13
14 const {
15 + captureScreenshot,
16 clientSettings,
17 events,
18 getDisplayMedia,
@@ -19,6 +24,7 @@ const {
24 } = vi.hoisted(() => {
25 const events: string[] = [];
26 return {
27 + captureScreenshot: vi.fn<DesktopPreviewBridge["captureScreenshot"]>(),
28 clientSettings: { browserRecordingFrameRate: 30 as 30 | 60 },
29 events,
30 getDisplayMedia: vi.fn(),
@@ -36,26 +42,37 @@ const {
42 sizeBytes: 0,
43 createdAt: "2026-06-26T00:00:00.000Z",
44 })),
39 - startScreencast: vi.fn(async (_tabId: string) => {
45 + startScreencast: vi.fn<DesktopPreviewBridge["recording"]["startScreencast"]>(async (_tabId) => {
46 events.push("start-screencast");
47 }),
48 stopScreencast: vi.fn(async () => undefined),
49 };
50 });
51
46 -vi.mock("~/components/preview/previewBridge", () => ({
47 - previewBridge: {
48 - recording: {
49 - onFrame: vi.fn(),
50 - save,
51 - startScreencast: async (tabId: string) => {
52 - await startScreencast(tabId);
53 - requestDisplayMediaCapture(tabId);
52 +vi.mock(import("~/components/preview/previewBridge"), async (original) => {
53 + vi.stubGlobal("window", {
54 + desktopBridge: {
55 + preview: {
56 + captureScreenshot,
57 + recording: {
58 + onFrame: vi.fn(),
59 + save,
60 + startScreencast: async (tabId: string) => {
61 + const result = await startScreencast(tabId);
62 + if (result === undefined) requestDisplayMediaCapture(tabId);
63 + return result;
64 + },
65 + stopScreencast,
66 + },
67 },
55 - stopScreencast,
68 },
57 - },
58 -}));
69 + });
70 + try {
71 + return await original();
72 + } finally {
73 + vi.unstubAllGlobals();
74 + }
75 +});
76
77 vi.mock("~/rpc/atomRegistry", () => ({
78 appAtomRegistry: { set: registrySet },
@@ -81,6 +98,7 @@ import {
98 stopBrowserRecordingForUpload,
99 } from "./browserRecording";
100 import { useBrowserSurfaceStore } from "./browserSurfaceStore";
101 +import { previewBridge } from "~/components/preview/previewBridge";
102 import { previewRuntimeTabId } from "./previewRuntimeTabId";
103
104 class FakeMediaRecorder {
@@ -165,6 +183,43 @@ describe("browser recording", () => {
183 vi.unstubAllGlobals();
184 });
185
186 + it("decodes screenshot failures and preserves successful capture types and artifacts", async () => {
187 + expectTypeOf<ReturnType<DesktopPreviewBridge["captureScreenshot"]>>().toEqualTypeOf<
188 + Promise<DesktopPreviewScreenshotArtifact | PreviewCaptureFailureEncoded>
189 + >();
190 + expectTypeOf<ReturnType<DesktopPreviewBridge["recording"]["startScreencast"]>>().toEqualTypeOf<
191 + Promise<void | PreviewCaptureFailureEncoded>
192 + >();
193 + expectTypeOf<
194 + ReturnType<NonNullable<typeof previewBridge>["captureScreenshot"]>
195 + >().toEqualTypeOf<Promise<DesktopPreviewScreenshotArtifact>>();
196 + expectTypeOf<
197 + ReturnType<NonNullable<typeof previewBridge>["recording"]["startScreencast"]>
198 + >().toEqualTypeOf<Promise<void>>();
199 + captureScreenshot.mockResolvedValueOnce({
200 + _tag: "PreviewCaptureFailure",
201 + reason: "capture-timeout",
202 + stage: "capture-page",
203 + });
204 + await expect(previewBridge!.captureScreenshot("capture-tab")).rejects.toMatchObject({
205 + reason: "capture-timeout",
206 + stage: "capture-page",
207 + message: expect.stringContaining("timed out during capture-page"),
208 + });
209 +
210 + const artifact: DesktopPreviewScreenshotArtifact = {
211 + id: "screenshot-test",
212 + tabId: "capture-tab",
213 + path: "/tmp/capture.png",
214 + mimeType: "image/png",
215 + sizeBytes: 100,
216 + createdAt: "2026-06-26T00:00:00.000Z",
217 + };
218 + captureScreenshot.mockResolvedValueOnce(artifact);
219 + expect(await previewBridge!.captureScreenshot("capture-tab")).toBe(artifact);
220 + expect(captureScreenshot).toHaveBeenNthCalledWith(2, "capture-tab");
221 + });
222 +
223 it("starts recording for a visible tab", async () => {
224 await startBrowserRecording("recording-tab");
225 const startupEvents = [...events];
@@ -334,11 +389,13 @@ describe("browser recording", () => {
389 });
390
391 await startBrowserRecording("recording-tab");
337 - FakeMediaRecorder.stopError = new Error("stop failed");
392 + const cleanupCause = new DOMException("Could not start video source", "NotReadableError");
393 + FakeMediaRecorder.stopError = cleanupCause;
394
395 await expect(stopBrowserRecording("recording-tab")).rejects.toMatchObject({
396 operation: "cleanup",
397 tabId: "recording-tab",
398 + message: "Browser recording operation cleanup failed for tab recording-tab.",
399 });
400 expect(stopTrack).toHaveBeenCalledOnce();
401 });
@@ -395,17 +452,76 @@ describe("browser recording", () => {
452 });
453
454 it("releases the native capture lease when stream acquisition fails", async () => {
398 - getDisplayMedia.mockRejectedValueOnce(new Error("capture failed"));
455 + const cause = new Error("capture failed");
456 + cause.name = "NotReadableError";
457 + getDisplayMedia.mockRejectedValueOnce(cause);
458
459 await expect(startBrowserRecording("recording-tab")).rejects.toMatchObject({
460 operation: "capture-media-stream",
461 tabId: "recording-tab",
462 + cause,
463 + message: "Browser recording operation capture-media-stream failed for tab recording-tab.",
464 });
465
466 expect(stopScreencast).toHaveBeenCalledWith("recording-tab");
467 expect(events.at(-1)).toBe("clear");
468 });
469
470 + it.each([false, true])(
471 + "explains real video-source rejection and permits retry when cleanup fails: %s",
472 + async (cleanupFails) => {
473 + const cause = new DOMException("Could not start video source", "NotReadableError");
474 + const cleanupCause = new Error("native stop failed");
475 + getDisplayMedia.mockRejectedValueOnce(cause);
476 + if (cleanupFails) stopScreencast.mockRejectedValueOnce(cleanupCause);
477 +
478 + const error = await startBrowserRecording("recording-tab").catch(
479 + (failure: unknown) => failure,
480 + );
481 + expect(error).toMatchObject({
482 + _tag: "BrowserRecordingOperationError",
483 + operation: "capture-media-stream",
484 + tabId: "recording-tab",
485 + message:
486 + "Unable to start the preview video source. Make sure the capture host is unlocked " +
487 + "and its display is on, then retry. NotReadableError: Could not start video source",
488 + cause: cleanupFails ? { cause, errors: [cause, cleanupCause] } : cause,
489 + });
490 + expect(stopScreencast).toHaveBeenCalledWith("recording-tab");
491 + expect(FakeMediaRecorder.instances).toHaveLength(0);
492 + expect(save).not.toHaveBeenCalled();
493 + expect(readActiveBrowserRecordingTabIds()).toEqual(new Set());
494 + expect(useBrowserSurfaceStore.getState().activityByTabId["recording-tab"]).toBeUndefined();
495 +
496 + await startBrowserRecording("recording-tab");
497 + await stopBrowserRecording("recording-tab");
498 + expect(getDisplayMedia).toHaveBeenCalledTimes(2);
499 + },
500 + );
501 +
502 + it("reports a native arm diagnostic immediately and frees the tab for a retry", async () => {
503 + startScreencast.mockResolvedValueOnce({
504 + _tag: "PreviewCaptureFailure",
505 + reason: "renderer-unavailable",
506 + stage: "recording-start",
507 + });
508 +
509 + await expect(startBrowserRecording("recording-tab")).rejects.toMatchObject({
510 + _tag: "BrowserRecordingOperationError",
511 + operation: "start-screencast",
512 + tabId: "recording-tab",
513 + cause: expect.any(PreviewCaptureFailure),
514 + message: "The preview renderer is unavailable. Reopen the preview tab before retrying.",
515 + });
516 + expect(getDisplayMedia).not.toHaveBeenCalled();
517 + expect(readActiveBrowserRecordingTabIds()).toEqual(new Set());
518 + expect(useBrowserSurfaceStore.getState().activityByTabId["recording-tab"]).toBeUndefined();
519 +
520 + await startBrowserRecording("recording-tab");
521 + await stopBrowserRecording("recording-tab");
522 + expect(getDisplayMedia).toHaveBeenCalledOnce();
523 + });
524 +
525 it("times out stalled stream acquisition and stops a late stream", async () => {
526 vi.useFakeTimers();
527 let finishCapture!: (stream: MediaStream) => void;
apps/web/src/browser/browserRecording.ts
+22 -1
@@ -1,4 +1,7 @@
1 -import { DESKTOP_PREVIEW_RECORDING_CAPTURE_TRIGGER } from "@t3tools/contracts";
1 +import {
2 + DESKTOP_PREVIEW_RECORDING_CAPTURE_TRIGGER,
3 + PreviewCaptureFailure,
4 +} from "@t3tools/contracts";
5 import type { DesktopPreviewRecordingArtifact, ScopedThreadRef } from "@t3tools/contracts";
6 import { useAtomValue } from "@effect/atom-react";
7 import * as Schema from "effect/Schema";
@@ -12,6 +15,8 @@ import { createRecordingCompositor } from "./recordingCompositor";
15
16 import { acquireBrowserSurfaceActivity } from "./browserSurfaceStore";
17
18 +const isPreviewCaptureFailure = Schema.is(PreviewCaptureFailure);
19 +
20 export class BrowserRecordingUnavailableError extends Schema.TaggedError<BrowserRecordingUnavailableError>()(
21 "BrowserRecordingUnavailableError",
22 {
@@ -86,6 +91,22 @@ export class BrowserRecordingOperationError extends Schema.TaggedError<BrowserRe
91 },
92 ) {
93 override get message(): string {
94 + if (isPreviewCaptureFailure(this.cause)) {
95 + return this.cause.message;
96 + }
97 + // Stream acquisition stores its primary failure on the aggregate when cleanup also fails.
98 + const captureCause = this.cause instanceof AggregateError ? this.cause.cause : this.cause;
99 + if (
100 + this.operation === "capture-media-stream" &&
101 + captureCause instanceof DOMException &&
102 + captureCause.name === "NotReadableError"
103 + ) {
104 + return (
105 + "Unable to start the preview video source. Make sure the capture host is unlocked " +
106 + "and its display is on, then retry. " +
107 + `${captureCause.name}: ${captureCause.message}`
108 + );
109 + }
110 return `Browser recording operation ${this.operation} failed for tab ${this.tabId}.`;
111 }
112 }
apps/web/src/components/preview/previewBridge.ts
+27 -1
@@ -1,2 +1,28 @@
1 -export const previewBridge =
1 +import { PreviewCaptureFailure, type PreviewCaptureFailureEncoded } from "@t3tools/contracts";
2 +import * as Option from "effect/Option";
3 +import * as Schema from "effect/Schema";
4 +
5 +const decodeCaptureFailure = Schema.decodeUnknownOption(PreviewCaptureFailure);
6 +
7 +// Decode here because contextBridge strips custom properties from rejected Errors.
8 +function unwrapPreviewCaptureResult<A>(result: A | PreviewCaptureFailureEncoded): A {
9 + const failure = decodeCaptureFailure(result);
10 + if (Option.isSome(failure)) throw failure.value;
11 + return result as A;
12 +}
13 +
14 +const nativePreviewBridge =
15 typeof window === "undefined" ? null : (window.desktopBridge?.preview ?? null);
16 +
17 +export const previewBridge = nativePreviewBridge
18 + ? {
19 + ...nativePreviewBridge,
20 + captureScreenshot: async (tabId: string) =>
21 + unwrapPreviewCaptureResult(await nativePreviewBridge.captureScreenshot(tabId)),
22 + recording: {
23 + ...nativePreviewBridge.recording,
24 + startScreencast: async (tabId: string) =>
25 + unwrapPreviewCaptureResult(await nativePreviewBridge.recording.startScreencast(tabId)),
26 + },
27 + }
28 + : null;
packages/contracts/src/index.ts
+1
@@ -56,6 +56,7 @@ export * from "./browserProfile.ts";
56 export * from "./device.ts";
57 export * from "./preview.ts";
58 export * from "./previewAutomation.ts";
59 +export * from "./previewCapture.ts";
60 export * from "./resourceTelemetry.ts";
61 export * from "./usage.ts";
62 export * from "./scheduledTask.ts";
packages/contracts/src/ipc.ts
+5 -2
@@ -1,4 +1,5 @@
1 import * as Schema from "effect/Schema";
2 +import type { PreviewCaptureFailureEncoded } from "./previewCapture.ts";
3
4 import { SnapShotSource } from "./chatAttachment.ts";
5 import { EnvironmentId, TrimmedNonEmptyString } from "./baseSchemas.ts";
@@ -1196,7 +1197,9 @@ export interface DesktopPreviewBridge {
1197 */
1198 pickElement: (tabId: string) => Promise<PreviewAnnotationSubmissionResult | null>;
1199 cancelPickElement: (tabId: string) => Promise<void>;
1199 - captureScreenshot: (tabId: string) => Promise<DesktopPreviewScreenshotArtifact>;
1200 + captureScreenshot: (
1201 + tabId: string,
1202 + ) => Promise<DesktopPreviewScreenshotArtifact | PreviewCaptureFailureEncoded>;
1203 revealArtifact: (path: string) => Promise<void>;
1204 copyArtifactToClipboard: (path: string) => Promise<void>;
1205 pictureInPicture: {
@@ -1205,7 +1208,7 @@ export interface DesktopPreviewBridge {
1208 };
1209 recording: {
1210 onInput: (listener: (event: DesktopPreviewRecordingInputEvent) => void) => () => void;
1208 - startScreencast: (tabId: string) => Promise<void>;
1211 + startScreencast: (tabId: string) => Promise<void | PreviewCaptureFailureEncoded>;
1212 stopScreencast: (tabId: string) => Promise<void>;
1213 save: (
1214 tabId: string,
packages/contracts/src/previewCapture.ts new
+33
@@ -0,0 +1,33 @@
1 +import * as Schema from "effect/Schema";
2 +
3 +/** A plain encoded failure crosses IPC and contextBridge without an arbitrary Error or stack. */
4 +export class PreviewCaptureFailure extends Schema.TaggedError<PreviewCaptureFailure>()(
5 + "PreviewCaptureFailure",
6 + {
7 + reason: Schema.Literals([
8 + "renderer-unavailable",
9 + "capture-unavailable",
10 + "capture-timeout",
11 + "recording-conflict",
12 + "capture-failed",
13 + ]),
14 + stage: Schema.Literals(["screenshot", "capture-page", "recording-start"]),
15 + },
16 +) {
17 + override get message(): string {
18 + switch (this.reason) {
19 + case "renderer-unavailable":
20 + return "The preview renderer is unavailable. Reopen the preview tab before retrying.";
21 + case "capture-unavailable":
22 + return "The preview capture surface is unavailable. Present the target tab and check that the preview host is unlocked, its display is on and its window is restored before retrying.";
23 + case "capture-timeout":
24 + return `Preview capture timed out during ${this.stage}. Check the preview host's lock, display and window state before retrying.`;
25 + case "recording-conflict":
26 + return "A recording capture is already starting, stopping or active. Wait for it to settle, or stop the active recording before retrying.";
27 + case "capture-failed":
28 + return `Preview capture failed during ${this.stage}. Check the preview host and target tab before retrying.`;
29 + }
30 + }
31 +}
32 +
33 +export type PreviewCaptureFailureEncoded = Schema.Codec.Encoded<typeof PreviewCaptureFailure>;