The best way to control Claude Code, Codex and more from any computer or phone
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>;