Skip to content

Commit 81f6305

Browse files
committed
fix(preview): preserve actionable native capture diagnostics
1 parent 348f217 commit 81f6305

13 files changed

Lines changed: 400 additions & 10 deletions

File tree

‎apps/desktop/src/ipc/DesktopIpcHandlers.ts‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -160,7 +160,11 @@ export const installDesktopIpcHandlers = Effect.fn("desktop.ipc.installHandlers"
160160
yield* ipc.handle(installCliCommand);
161161
yield* ipc.handle(uninstallCliCommand);
162162
for (const previewMethod of PreviewIpc.methods) {
163-
yield* ipc.handle(previewMethod);
163+
// Explicit types preserve the error/service union of these heterogeneous preview methods.
164+
yield* ipc.handle<
165+
Effect.Error<ReturnType<(typeof PreviewIpc.methods)[number]["handler"]>>,
166+
Effect.Services<ReturnType<(typeof PreviewIpc.methods)[number]["handler"]>>
167+
>(previewMethod);
164168
}
165169
yield* ipc.handle(PreviewIpc.listBrowserImportSources);
166170
yield* ipc.handle(PreviewIpc.importBrowserCookies);

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

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ import {
33
DEFAULT_BROWSER_PROFILE_ID,
44
INCOGNITO_BROWSER_PROFILE_ID,
55
PreviewAutomationStatus,
6+
PreviewCaptureFailure,
67
} from "@t3tools/contracts";
78
import * as Cause from "effect/Cause";
89
import * as Effect from "effect/Effect";
@@ -14,6 +15,8 @@ import { beforeEach, describe, expect, it, vi } from "vite-plus/test";
1415
import * as PreviewManager from "../../preview/Manager.ts";
1516
import * as BrowserImport from "../../preview/BrowserImport/BrowserImport.ts";
1617
import * as PreviewIpc from "./preview.ts";
18+
import * as DesktopIpc from "../DesktopIpc.ts";
19+
import * as DesktopClientSettings from "../../settings/DesktopClientSettings.ts";
1720

1821
const { fromPartition } = vi.hoisted(() => ({
1922
fromPartition: vi.fn(() => {
@@ -33,7 +36,59 @@ vi.mock("electron", () => ({
3336
},
3437
}));
3538

39+
const decodeCaptureFailure = Schema.decodeUnknownEffect(PreviewCaptureFailure);
40+
3641
describe("preview IPC methods", () => {
42+
const invokeRecording = (
43+
startRecording: PreviewManager.PreviewManager["Service"]["startRecording"],
44+
) =>
45+
Effect.scoped(
46+
Effect.gen(function* () {
47+
let listener: DesktopIpc.DesktopIpcHandleListener | undefined;
48+
const ipc = DesktopIpc.make({
49+
removeHandler: vi.fn(),
50+
handle: (_channel, registered) => {
51+
listener = registered;
52+
},
53+
removeAllListeners: vi.fn(),
54+
on: vi.fn(),
55+
});
56+
yield* ipc.handle(PreviewIpc.startRecording);
57+
return yield* Effect.promise(async () =>
58+
listener!({ sender: { id: 7 } }, { tabId: "closed-tab" }),
59+
);
60+
}).pipe(
61+
Effect.provideService(PreviewManager.PreviewManager, {
62+
startRecording,
63+
} as PreviewManager.PreviewManager["Service"]),
64+
Effect.provideService(DesktopClientSettings.DesktopClientSettings, {
65+
get: Effect.succeedNone,
66+
set: () => Effect.void,
67+
}),
68+
),
69+
);
70+
71+
effectIt.effect("encodes a native recording arm failure through the registered IPC handler", () =>
72+
Effect.gen(function* () {
73+
const result = yield* invokeRecording((tabId) =>
74+
Effect.fail(new PreviewManager.PreviewTabNotFoundError({ tabId })),
75+
);
76+
expect(result).toEqual({
77+
_tag: "PreviewCaptureFailure",
78+
reason: "renderer-unavailable",
79+
stage: "recording-start",
80+
});
81+
const failure = yield* decodeCaptureFailure(result);
82+
expect(failure.message).toContain("Reopen the preview tab");
83+
}),
84+
);
85+
86+
effectIt.effect("keeps a successful native recording arm encoded as undefined", () =>
87+
Effect.gen(function* () {
88+
expect(yield* invokeRecording(() => Effect.void)).toBeUndefined();
89+
}),
90+
);
91+
3792
beforeEach(() => {
3893
fromPartition.mockClear();
3994
});

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

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ import {
1919
DesktopPreviewTabInputSchema,
2020
DesktopPreviewWebviewConfigSchema,
2121
PreviewAnnotationSubmissionResultSchema,
22+
PreviewCaptureFailure,
2223
DEFAULT_BROWSER_PROFILE_ID,
2324
INCOGNITO_BROWSER_PROFILE_ID,
2425
PreviewForwardedShortcut,
@@ -32,6 +33,7 @@ import * as NodeURL from "node:url";
3233
import * as ElectronWindow from "../../electron/ElectronWindow.ts";
3334
import * as BrowserImport from "../../preview/BrowserImport/BrowserImport.ts";
3435
import * as PreviewManager from "../../preview/Manager.ts";
36+
import { normalizeCaptureFailure } from "../../preview/captureErrors.ts";
3537
import * as DesktopClientSettings from "../../settings/DesktopClientSettings.ts";
3638
import { PREVIEW_WEBVIEW_PREFERENCES } from "../../preview/WebviewPreferences.ts";
3739
import * as IpcChannels from "../channels.ts";
@@ -207,7 +209,8 @@ export const cancelPickElement = tabMethod(
207209
export const startRecording = DesktopIpc.makeIpcMethod({
208210
channel: IpcChannels.PREVIEW_RECORDING_START_CHANNEL,
209211
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]),
211214
handler: Effect.fn("desktop.ipc.preview.startRecording")(function* ({ tabId }) {
212215
const manager = yield* PreviewManager.PreviewManager;
213216
const store = yield* DesktopClientSettings.DesktopClientSettings;
@@ -216,7 +219,11 @@ export const startRecording = DesktopIpc.makeIpcMethod({
216219
showKeyPresses: value.browserRecordingShowKeyPresses,
217220
showMousePresses: value.browserRecordingShowMousePresses,
218221
}));
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+
);
220227
}),
221228
});
222229
export const stopRecording = tabMethod(
@@ -397,10 +404,12 @@ export const setAnnotationSendEnabled = DesktopIpc.makeIpcMethod({
397404
export const captureScreenshot = DesktopIpc.makeIpcMethod({
398405
channel: IpcChannels.PREVIEW_CAPTURE_SCREENSHOT_CHANNEL,
399406
payload: DesktopPreviewTabInputSchema,
400-
result: DesktopPreviewScreenshotArtifactSchema,
407+
result: Schema.Union([DesktopPreviewScreenshotArtifactSchema, PreviewCaptureFailure]),
401408
handler: Effect.fn("desktop.ipc.preview.captureScreenshot")(function* ({ tabId }) {
402409
const manager = yield* PreviewManager.PreviewManager;
403-
return yield* manager.captureScreenshot(tabId);
410+
return yield* manager
411+
.captureScreenshot(tabId)
412+
.pipe(Effect.catch((error) => Effect.succeed(normalizeCaptureFailure(error, "screenshot"))));
404413
}),
405414
});
406415

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
import { expect, it } from "vite-plus/test";
2+
import { PreviewCaptureFailure } from "@t3tools/contracts";
3+
import * as Cause from "effect/Cause";
4+
import * as Schema from "effect/Schema";
5+
import { normalizeCaptureFailure } from "./captureErrors.ts";
6+
const encodeCaptureFailure = Schema.encodeSync(PreviewCaptureFailure);
7+
const encodeJson = Schema.encodeSync(Schema.fromJsonString(Schema.Unknown));
8+
9+
it("preserves a native pixel capture timeout across the encoded IPC result", () => {
10+
const failure = normalizeCaptureFailure(
11+
{
12+
_tag: "PreviewOperationError",
13+
operation: "captureScreenshot.capturePage",
14+
cause: new Cause.TimeoutError(),
15+
},
16+
"screenshot",
17+
);
18+
const encoded = encodeCaptureFailure(failure);
19+
expect(encoded).toEqual({
20+
_tag: "PreviewCaptureFailure",
21+
reason: "capture-timeout",
22+
stage: "capture-page",
23+
});
24+
expect(encodeJson(encoded)).not.toContain("stack");
25+
});
26+
27+
it.each([
28+
["PreviewTabNotFoundError", "renderer-unavailable"],
29+
["PreviewWebContentsNotFoundError", "renderer-unavailable"],
30+
["PreviewMainWindowClosedError", "renderer-unavailable"],
31+
["PreviewWebviewNotInitializedError", "capture-unavailable"],
32+
["PreviewRecordingCaptureUnavailableError", "capture-unavailable"],
33+
["PreviewRecordingArmConflictError", "recording-conflict"],
34+
])("classifies %s without transporting its arbitrary fields", (tag, reason) => {
35+
const failure = normalizeCaptureFailure(
36+
{ _tag: tag, message: "secret page content", stack: "secret stack" },
37+
"recording-start",
38+
);
39+
expect(failure.reason).toBe(reason);
40+
expect(encodeJson(encodeCaptureFailure(failure))).not.toContain("secret");
41+
});
42+
43+
it.each(["captureScreenshot.capturePage"])(
44+
"classifies the exact Electron surface rejection for %s",
45+
(operation) => {
46+
const failure = normalizeCaptureFailure(
47+
{
48+
_tag: "PreviewOperationError",
49+
operation,
50+
cause: new Error("Current display surface not available for capture"),
51+
},
52+
"screenshot",
53+
);
54+
expect(encodeCaptureFailure(failure)).toEqual({
55+
_tag: "PreviewCaptureFailure",
56+
reason: "capture-unavailable",
57+
stage: "capture-page",
58+
});
59+
},
60+
);
61+
62+
it("keeps extended messages and unrelated operations generic with the screenshot stage", () => {
63+
for (const [operation, message] of [
64+
["captureScreenshot.capturePage", "Current display surface not available for capture secret"],
65+
["captureScreenshot.writeFile", "Current display surface not available for capture"],
66+
]) {
67+
const failure = normalizeCaptureFailure(
68+
{ _tag: "PreviewOperationError", operation, cause: new Error(message) },
69+
"screenshot",
70+
);
71+
expect(failure.reason).toBe("capture-failed");
72+
expect(failure.message).not.toContain("secret");
73+
if (operation === "captureScreenshot.writeFile") {
74+
expect(failure.stage).toBe("screenshot");
75+
expect(failure.message).toContain("during screenshot");
76+
}
77+
}
78+
});
79+
80+
it("does not classify an arbitrary message as a timeout", () => {
81+
const failure = normalizeCaptureFailure(
82+
new Error("TimeoutError secret page content"),
83+
"screenshot",
84+
);
85+
expect(failure.reason).toBe("capture-failed");
86+
expect(failure.message).not.toContain("secret");
87+
});
Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
import { PreviewCaptureFailure, type PreviewCaptureDiagnostic } from "@t3tools/contracts";
2+
import * as Cause from "effect/Cause";
3+
import * as Schema from "effect/Schema";
4+
5+
const isNativeFailure = Schema.is(
6+
Schema.Struct({
7+
_tag: Schema.String,
8+
operation: Schema.optional(Schema.String),
9+
cause: Schema.optional(Schema.Unknown),
10+
}),
11+
);
12+
13+
/** Classify before Electron replaces a rejected IPC Error with its message. */
14+
export function normalizeCaptureFailure(
15+
error: unknown,
16+
stage: PreviewCaptureDiagnostic["stage"],
17+
): PreviewCaptureFailure {
18+
let reason: PreviewCaptureDiagnostic["reason"] = "capture-failed";
19+
if (isNativeFailure(error)) {
20+
switch (error._tag) {
21+
case "PreviewTabNotFoundError":
22+
case "PreviewWebContentsNotFoundError":
23+
case "PreviewMainWindowClosedError":
24+
reason = "renderer-unavailable";
25+
break;
26+
case "PreviewWebviewNotInitializedError":
27+
case "PreviewRecordingCaptureUnavailableError":
28+
reason = "capture-unavailable";
29+
break;
30+
case "PreviewRecordingArmConflictError":
31+
reason = "recording-conflict";
32+
break;
33+
case "PreviewOperationError":
34+
if (error.operation === "captureScreenshot.capturePage") {
35+
stage = "capture-page";
36+
if (
37+
error.cause instanceof Error &&
38+
error.cause.message === "Current display surface not available for capture"
39+
) {
40+
reason = "capture-unavailable";
41+
}
42+
}
43+
if (Cause.isTimeoutError(error.cause)) reason = "capture-timeout";
44+
break;
45+
}
46+
}
47+
return new PreviewCaptureFailure({ reason, stage });
48+
}

‎apps/web/src/browser/browserRecording.test.ts‎

Lines changed: 71 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ import {
22
DESKTOP_PREVIEW_RECORDING_CAPTURE_TRIGGER,
33
EnvironmentId,
44
ThreadId,
5+
PreviewCaptureFailure,
56
} from "@t3tools/contracts";
67
import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
78

@@ -334,11 +335,13 @@ describe("browser recording", () => {
334335
});
335336

336337
await startBrowserRecording("recording-tab");
337-
FakeMediaRecorder.stopError = new Error("stop failed");
338+
const cleanupCause = new DOMException("Could not start video source", "NotReadableError");
339+
FakeMediaRecorder.stopError = cleanupCause;
338340

339341
await expect(stopBrowserRecording("recording-tab")).rejects.toMatchObject({
340342
operation: "cleanup",
341343
tabId: "recording-tab",
344+
message: "Browser recording operation cleanup failed for tab recording-tab.",
342345
});
343346
expect(stopTrack).toHaveBeenCalledOnce();
344347
});
@@ -406,6 +409,73 @@ describe("browser recording", () => {
406409
expect(events.at(-1)).toBe("clear");
407410
});
408411

412+
it.each([false, true])(
413+
"explains real video-source rejection and permits retry when cleanup fails: %s",
414+
async (cleanupFails) => {
415+
const cause = new DOMException("Could not start video source", "NotReadableError");
416+
const cleanupCause = new Error("native stop failed");
417+
getDisplayMedia.mockRejectedValueOnce(cause);
418+
if (cleanupFails) stopScreencast.mockRejectedValueOnce(cleanupCause);
419+
420+
const error = await startBrowserRecording("recording-tab").catch(
421+
(failure: unknown) => failure,
422+
);
423+
expect(error).toMatchObject({
424+
_tag: "BrowserRecordingOperationError",
425+
operation: "capture-media-stream",
426+
tabId: "recording-tab",
427+
message:
428+
"Unable to start the preview video source. Make sure the capture host is unlocked " +
429+
"and its display is on, then retry. NotReadableError: Could not start video source",
430+
cause: cleanupFails ? { cause, errors: [cause, cleanupCause] } : cause,
431+
});
432+
expect(stopScreencast).toHaveBeenCalledWith("recording-tab");
433+
expect(FakeMediaRecorder.instances).toHaveLength(0);
434+
expect(save).not.toHaveBeenCalled();
435+
expect(readActiveBrowserRecordingTabIds()).toEqual(new Set());
436+
expect(useBrowserSurfaceStore.getState().activityByTabId["recording-tab"]).toBeUndefined();
437+
438+
await startBrowserRecording("recording-tab");
439+
await stopBrowserRecording("recording-tab");
440+
expect(getDisplayMedia).toHaveBeenCalledTimes(2);
441+
},
442+
);
443+
444+
it("keeps unrecognized acquisition failures generic", async () => {
445+
const cause = new Error("capture failed");
446+
cause.name = "NotReadableError";
447+
getDisplayMedia.mockRejectedValueOnce(cause);
448+
449+
await expect(startBrowserRecording("recording-tab")).rejects.toMatchObject({
450+
operation: "capture-media-stream",
451+
cause,
452+
message: "Browser recording operation capture-media-stream failed for tab recording-tab.",
453+
});
454+
});
455+
456+
it("reports a native arm diagnostic immediately and frees the tab for a retry", async () => {
457+
const cause = new PreviewCaptureFailure({
458+
reason: "renderer-unavailable",
459+
stage: "recording-start",
460+
});
461+
startScreencast.mockRejectedValueOnce(cause);
462+
463+
await expect(startBrowserRecording("recording-tab")).rejects.toMatchObject({
464+
_tag: "BrowserRecordingOperationError",
465+
operation: "start-screencast",
466+
tabId: "recording-tab",
467+
cause,
468+
message: cause.message,
469+
});
470+
expect(getDisplayMedia).not.toHaveBeenCalled();
471+
expect(readActiveBrowserRecordingTabIds()).toEqual(new Set());
472+
expect(useBrowserSurfaceStore.getState().activityByTabId["recording-tab"]).toBeUndefined();
473+
474+
await startBrowserRecording("recording-tab");
475+
await stopBrowserRecording("recording-tab");
476+
expect(getDisplayMedia).toHaveBeenCalledOnce();
477+
});
478+
409479
it("times out stalled stream acquisition and stops a late stream", async () => {
410480
vi.useFakeTimers();
411481
let finishCapture!: (stream: MediaStream) => void;

0 commit comments

Comments
 (0)