fix(preview): preserve actionable native capture diagnostics

Author: Quicksaver

FORK.md

@@ -884,7 +884,7 @@ The tracked accessory note is [PREVIEW_RECORDING_START.md](PREVIEW_RECORDING_STA
 
 **Worktree branch:** `fix/preview-capture-diagnostics`
 
-The standalone worktree is `E:/Projects/t3code.worktrees/preview-capture-diagnostics`, at final HEAD `14f3cbc4f53d4753f50393d5ec64dc6273e84b4c`. Its rebased baseline `64fe72af4faa77a76b73835c2acd16a2405522d3` is directly above fixed `base/main` `26285ab80513260d1ff29d2c3fbe18f21990cb62`. The clean source branch tracks `origin/fix/preview-capture-diagnostics`; `base/main` remains its comparison base. Its source commits are published.
+The standalone worktree is `E:/Projects/t3code.worktrees/preview-capture-diagnostics`, at HEAD `8d8196e4d2df519519e94ce1e01abba4dd77cd8d` directly above fixed `base/main` `48b71f0eb323d08c8fcadfe54adf34becb2984da`. The clean source branch tracks `origin/fix/preview-capture-diagnostics`; `base/main` remains its comparison base. Its source commit is published and retains all thirteen customization files unchanged. Historical locked-state proof below retains its original source attribution.
 
 Status is VALID ADAPTED with PASSING actual Windows locked/off acquisition-error diagnostics, cleanup and same-original-guest retry. Incoming agent browser automation moved to the environment server and supersedes old desktop agent/broker propagation. Surviving diagnostics preserve safe typed native screenshot/recording failures through IPC and the direct primary cause through the recording wrapper/UI. Capture, fallback, permissions, power behavior and server-browser CDP are outside this customization; no new CDP proof was produced.
 

apps/desktop/src/ipc/DesktopIpcHandlers.ts

@@ -158,7 +158,11 @@ export const installDesktopIpcHandlers = Effect.fn("desktop.ipc.installHandlers"
   yield* ipc.handle(installCliCommand);
   yield* ipc.handle(uninstallCliCommand);
   for (const previewMethod of PreviewIpc.methods) {
-    yield* ipc.handle(previewMethod);
+    // Explicit types preserve the error/service union of these heterogeneous preview methods.
+    yield* ipc.handle<
+      Effect.Error<ReturnType<(typeof PreviewIpc.methods)[number]["handler"]>>,
+      Effect.Services<ReturnType<(typeof PreviewIpc.methods)[number]["handler"]>>
+    >(previewMethod);
   }
   yield* ipc.handle(PreviewIpc.listBrowserImportSources);
   yield* ipc.handle(PreviewIpc.importBrowserCookies);

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

@@ -3,6 +3,7 @@ import {
   DEFAULT_BROWSER_PROFILE_ID,
   INCOGNITO_BROWSER_PROFILE_ID,
   PreviewAutomationStatus,
+  PreviewCaptureFailure,
 } from "@t3tools/contracts";
 import * as Cause from "effect/Cause";
 import * as Effect from "effect/Effect";
@@ -14,6 +15,8 @@ import { beforeEach, describe, expect, it, vi } from "vite-plus/test";
 import * as PreviewManager from "../../preview/Manager.ts";
 import * as BrowserImport from "../../preview/BrowserImport/BrowserImport.ts";
 import * as PreviewIpc from "./preview.ts";
+import * as DesktopIpc from "../DesktopIpc.ts";
+import * as DesktopClientSettings from "../../settings/DesktopClientSettings.ts";
 
 const { fromPartition } = vi.hoisted(() => ({
   fromPartition: vi.fn(() => {
@@ -33,7 +36,59 @@ vi.mock("electron", () => ({
   },
 }));
 
+const decodeCaptureFailure = Schema.decodeUnknownEffect(PreviewCaptureFailure);
+
 describe("preview IPC methods", () => {
+  const invokeRecording = (
+    startRecording: PreviewManager.PreviewManager["Service"]["startRecording"],
+  ) =>
+    Effect.scoped(
+      Effect.gen(function* () {
+        let listener: DesktopIpc.DesktopIpcHandleListener | undefined;
+        const ipc = DesktopIpc.make({
+          removeHandler: vi.fn(),
+          handle: (_channel, registered) => {
+            listener = registered;
+          },
+          removeAllListeners: vi.fn(),
+          on: vi.fn(),
+        });
+        yield* ipc.handle(PreviewIpc.startRecording);
+        return yield* Effect.promise(async () =>
+          listener!({ sender: { id: 7 } }, { tabId: "closed-tab" }),
+        );
+      }).pipe(
+        Effect.provideService(PreviewManager.PreviewManager, {
+          startRecording,
+        } as PreviewManager.PreviewManager["Service"]),
+        Effect.provideService(DesktopClientSettings.DesktopClientSettings, {
+          get: Effect.succeedNone,
+          set: () => Effect.void,
+        }),
+      ),
+    );
+
+  effectIt.effect("encodes a native recording arm failure through the registered IPC handler", () =>
+    Effect.gen(function* () {
+      const result = yield* invokeRecording((tabId) =>
+        Effect.fail(new PreviewManager.PreviewTabNotFoundError({ tabId })),
+      );
+      expect(result).toEqual({
+        _tag: "PreviewCaptureFailure",
+        reason: "renderer-unavailable",
+        stage: "recording-start",
+      });
+      const failure = yield* decodeCaptureFailure(result);
+      expect(failure.message).toContain("Reopen the preview tab");
+    }),
+  );
+
+  effectIt.effect("keeps a successful native recording arm encoded as undefined", () =>
+    Effect.gen(function* () {
+      expect(yield* invokeRecording(() => Effect.void)).toBeUndefined();
+    }),
+  );
+
   beforeEach(() => {
     fromPartition.mockClear();
   });

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

@@ -19,6 +19,7 @@ import {
   DesktopPreviewTabInputSchema,
   DesktopPreviewWebviewConfigSchema,
   PreviewAnnotationSubmissionResultSchema,
+  PreviewCaptureFailure,
   DEFAULT_BROWSER_PROFILE_ID,
   INCOGNITO_BROWSER_PROFILE_ID,
   PreviewForwardedShortcut,
@@ -32,6 +33,7 @@ import * as NodeURL from "node:url";
 import * as ElectronWindow from "../../electron/ElectronWindow.ts";
 import * as BrowserImport from "../../preview/BrowserImport/BrowserImport.ts";
 import * as PreviewManager from "../../preview/Manager.ts";
+import { normalizeCaptureFailure } from "../../preview/captureErrors.ts";
 import * as DesktopClientSettings from "../../settings/DesktopClientSettings.ts";
 import { PREVIEW_WEBVIEW_PREFERENCES } from "../../preview/WebviewPreferences.ts";
 import * as IpcChannels from "../channels.ts";
@@ -204,7 +206,8 @@ export const cancelPickElement = tabMethod(
 export const startRecording = DesktopIpc.makeIpcMethod({
   channel: IpcChannels.PREVIEW_RECORDING_START_CHANNEL,
   payload: DesktopPreviewTabInputSchema,
-  result: Schema.Void,
+  // Void encodes any value as undefined, so the tagged failure must be tried first.
+  result: Schema.Union([PreviewCaptureFailure, Schema.Void]),
   handler: Effect.fn("desktop.ipc.preview.startRecording")(function* ({ tabId }) {
     const manager = yield* PreviewManager.PreviewManager;
     const store = yield* DesktopClientSettings.DesktopClientSettings;
@@ -213,7 +216,11 @@ export const startRecording = DesktopIpc.makeIpcMethod({
       showKeyPresses: value.browserRecordingShowKeyPresses,
       showMousePresses: value.browserRecordingShowMousePresses,
     }));
-    yield* manager.startRecording(tabId, Option.getOrUndefined(options));
+    return yield* manager
+      .startRecording(tabId, Option.getOrUndefined(options))
+      .pipe(
+        Effect.catch((error) => Effect.succeed(normalizeCaptureFailure(error, "recording-start"))),
+      );
   }),
 });
 export const stopRecording = tabMethod(
@@ -394,10 +401,12 @@ export const setAnnotationSendEnabled = DesktopIpc.makeIpcMethod({
 export const captureScreenshot = DesktopIpc.makeIpcMethod({
   channel: IpcChannels.PREVIEW_CAPTURE_SCREENSHOT_CHANNEL,
   payload: DesktopPreviewTabInputSchema,
-  result: DesktopPreviewScreenshotArtifactSchema,
+  result: Schema.Union([DesktopPreviewScreenshotArtifactSchema, PreviewCaptureFailure]),
   handler: Effect.fn("desktop.ipc.preview.captureScreenshot")(function* ({ tabId }) {
     const manager = yield* PreviewManager.PreviewManager;
-    return yield* manager.captureScreenshot(tabId);
+    return yield* manager
+      .captureScreenshot(tabId)
+      .pipe(Effect.catch((error) => Effect.succeed(normalizeCaptureFailure(error, "screenshot"))));
   }),
 });
 

apps/desktop/src/preview/captureErrors.test.ts

@@ -0,0 +1,87 @@
+import { expect, it } from "vite-plus/test";
+import { PreviewCaptureFailure } from "@t3tools/contracts";
+import * as Cause from "effect/Cause";
+import * as Schema from "effect/Schema";
+import { normalizeCaptureFailure } from "./captureErrors.ts";
+const encodeCaptureFailure = Schema.encodeSync(PreviewCaptureFailure);
+const encodeJson = Schema.encodeSync(Schema.fromJsonString(Schema.Unknown));
+
+it("preserves a native pixel capture timeout across the encoded IPC result", () => {
+  const failure = normalizeCaptureFailure(
+    {
+      _tag: "PreviewOperationError",
+      operation: "captureScreenshot.capturePage",
+      cause: new Cause.TimeoutError(),
+    },
+    "screenshot",
+  );
+  const encoded = encodeCaptureFailure(failure);
+  expect(encoded).toEqual({
+    _tag: "PreviewCaptureFailure",
+    reason: "capture-timeout",
+    stage: "capture-page",
+  });
+  expect(encodeJson(encoded)).not.toContain("stack");
+});
+
+it.each([
+  ["PreviewTabNotFoundError", "renderer-unavailable"],
+  ["PreviewWebContentsNotFoundError", "renderer-unavailable"],
+  ["PreviewMainWindowClosedError", "renderer-unavailable"],
+  ["PreviewWebviewNotInitializedError", "capture-unavailable"],
+  ["PreviewRecordingCaptureUnavailableError", "capture-unavailable"],
+  ["PreviewRecordingArmConflictError", "recording-conflict"],
+])("classifies %s without transporting its arbitrary fields", (tag, reason) => {
+  const failure = normalizeCaptureFailure(
+    { _tag: tag, message: "secret page content", stack: "secret stack" },
+    "recording-start",
+  );
+  expect(failure.reason).toBe(reason);
+  expect(encodeJson(encodeCaptureFailure(failure))).not.toContain("secret");
+});
+
+it.each(["captureScreenshot.capturePage"])(
+  "classifies the exact Electron surface rejection for %s",
+  (operation) => {
+    const failure = normalizeCaptureFailure(
+      {
+        _tag: "PreviewOperationError",
+        operation,
+        cause: new Error("Current display surface not available for capture"),
+      },
+      "screenshot",
+    );
+    expect(encodeCaptureFailure(failure)).toEqual({
+      _tag: "PreviewCaptureFailure",
+      reason: "capture-unavailable",
+      stage: "capture-page",
+    });
+  },
+);
+
+it("keeps extended messages and unrelated operations generic with the screenshot stage", () => {
+  for (const [operation, message] of [
+    ["captureScreenshot.capturePage", "Current display surface not available for capture secret"],
+    ["captureScreenshot.writeFile", "Current display surface not available for capture"],
+  ]) {
+    const failure = normalizeCaptureFailure(
+      { _tag: "PreviewOperationError", operation, cause: new Error(message) },
+      "screenshot",
+    );
+    expect(failure.reason).toBe("capture-failed");
+    expect(failure.message).not.toContain("secret");
+    if (operation === "captureScreenshot.writeFile") {
+      expect(failure.stage).toBe("screenshot");
+      expect(failure.message).toContain("during screenshot");
+    }
+  }
+});
+
+it("does not classify an arbitrary message as a timeout", () => {
+  const failure = normalizeCaptureFailure(
+    new Error("TimeoutError secret page content"),
+    "screenshot",
+  );
+  expect(failure.reason).toBe("capture-failed");
+  expect(failure.message).not.toContain("secret");
+});

apps/desktop/src/preview/captureErrors.ts

@@ -0,0 +1,48 @@
+import { PreviewCaptureFailure, type PreviewCaptureDiagnostic } from "@t3tools/contracts";
+import * as Cause from "effect/Cause";
+import * as Schema from "effect/Schema";
+
+const isNativeFailure = Schema.is(
+  Schema.Struct({
+    _tag: Schema.String,
+    operation: Schema.optional(Schema.String),
+    cause: Schema.optional(Schema.Unknown),
+  }),
+);
+
+/** Classify before Electron replaces a rejected IPC Error with its message. */
+export function normalizeCaptureFailure(
+  error: unknown,
+  stage: PreviewCaptureDiagnostic["stage"],
+): PreviewCaptureFailure {
+  let reason: PreviewCaptureDiagnostic["reason"] = "capture-failed";
+  if (isNativeFailure(error)) {
+    switch (error._tag) {
+      case "PreviewTabNotFoundError":
+      case "PreviewWebContentsNotFoundError":
+      case "PreviewMainWindowClosedError":
+        reason = "renderer-unavailable";
+        break;
+      case "PreviewWebviewNotInitializedError":
+      case "PreviewRecordingCaptureUnavailableError":
+        reason = "capture-unavailable";
+        break;
+      case "PreviewRecordingArmConflictError":
+        reason = "recording-conflict";
+        break;
+      case "PreviewOperationError":
+        if (error.operation === "captureScreenshot.capturePage") {
+          stage = "capture-page";
+          if (
+            error.cause instanceof Error &&
+            error.cause.message === "Current display surface not available for capture"
+          ) {
+            reason = "capture-unavailable";
+          }
+        }
+        if (Cause.isTimeoutError(error.cause)) reason = "capture-timeout";
+        break;
+    }
+  }
+  return new PreviewCaptureFailure({ reason, stage });
+}

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

@@ -2,6 +2,7 @@ import {
   DESKTOP_PREVIEW_RECORDING_CAPTURE_TRIGGER,
   EnvironmentId,
   ThreadId,
+  PreviewCaptureFailure,
 } from "@t3tools/contracts";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
 
@@ -705,11 +706,13 @@ describe("browser recording", () => {
     });
 
     await startBrowserRecording("recording-tab");
-    FakeMediaRecorder.stopError = new Error("stop failed");
+    const cleanupCause = new DOMException("Could not start video source", "NotReadableError");
+    FakeMediaRecorder.stopError = cleanupCause;
 
     await expect(stopBrowserRecording("recording-tab")).rejects.toMatchObject({
       operation: "cleanup",
       tabId: "recording-tab",
+      message: "Browser recording operation cleanup failed for tab recording-tab.",
     });
     expect(stopTrack).toHaveBeenCalledOnce();
   });
@@ -777,6 +780,81 @@ describe("browser recording", () => {
     expect(events.at(-1)).toBe("clear");
   });
 
+  it.each([false, true])(
+    "explains fallback video-source rejection and permits retry when cleanup fails: %s",
+    async (cleanupFails) => {
+      const cause = new DOMException("Could not start video source", "NotReadableError");
+      const cleanupCause = new Error("native stop failed");
+      const frames = prepareFrameFallback();
+      frames.canvas.captureStream.mockImplementationOnce(() => {
+        throw cause;
+      });
+      if (cleanupFails) stopScreencast.mockRejectedValueOnce(cleanupCause);
+
+      const failed = startBrowserRecording("recording-tab").catch((failure: unknown) => failure);
+      await frames.ready;
+      await frames.receive();
+      const error = await failed;
+      expect(error).toMatchObject({
+        _tag: "BrowserRecordingOperationError",
+        operation: "capture-media-stream",
+        tabId: "recording-tab",
+        message:
+          "Unable to start the preview video source. Make sure the capture host is unlocked " +
+          "and its display is on, then retry. NotReadableError: Could not start video source",
+        cause: cleanupFails ? { cause, errors: [cause, cleanupCause] } : cause,
+      });
+      expect(stopScreencast).toHaveBeenCalledWith("recording-tab");
+      expect(FakeMediaRecorder.instances).toHaveLength(0);
+      expect(save).not.toHaveBeenCalled();
+      expect(readActiveBrowserRecordingTabIds()).toEqual(new Set());
+      expect(useBrowserSurfaceStore.getState().activityByTabId["recording-tab"]).toBeUndefined();
+
+      const recoveredFrames = prepareFrameFallback();
+      const restarted = startBrowserRecording("recording-tab");
+      await recoveredFrames.ready;
+      await recoveredFrames.receive();
+      await restarted;
+      await stopBrowserRecording("recording-tab");
+      expect(getUserMedia).toHaveBeenCalledTimes(2);
+    },
+  );
+
+  it("keeps unrecognized acquisition failures generic", async () => {
+    const cause = new Error("capture failed");
+    cause.name = "NotReadableError";
+    getUserMedia.mockRejectedValueOnce(cause);
+
+    await expect(startBrowserRecording("recording-tab")).rejects.toMatchObject({
+      operation: "capture-media-stream",
+      cause,
+      message: "Browser recording operation capture-media-stream failed for tab recording-tab.",
+    });
+  });
+
+  it("reports a native arm diagnostic immediately and frees the tab for a retry", async () => {
+    const cause = new PreviewCaptureFailure({
+      reason: "renderer-unavailable",
+      stage: "recording-start",
+    });
+    startScreencast.mockRejectedValueOnce(cause);
+
+    await expect(startBrowserRecording("recording-tab")).rejects.toMatchObject({
+      _tag: "BrowserRecordingOperationError",
+      operation: "start-screencast",
+      tabId: "recording-tab",
+      cause,
+      message: cause.message,
+    });
+    expect(getUserMedia).not.toHaveBeenCalled();
+    expect(readActiveBrowserRecordingTabIds()).toEqual(new Set());
+    expect(useBrowserSurfaceStore.getState().activityByTabId["recording-tab"]).toBeUndefined();
+
+    await startBrowserRecording("recording-tab");
+    await stopBrowserRecording("recording-tab");
+    expect(getUserMedia).toHaveBeenCalledOnce();
+  });
+
   it("times out stalled stream acquisition and stops a late stream", async () => {
     vi.useFakeTimers();
     let finishCapture!: (stream: MediaStream) => void;