fix(preview): preserve recording retries

Author: Quicksaver

BRANCH_DETAILS.md

@@ -20,7 +20,7 @@ This branch does not add a second recording/PiP capture lifecycle or another hid
 Expected behavior:
 
 - Every Electron automation operation has a bounded control-session lifetime. The desktop manager reserves response grace inside the requested timeout without making the execution budget shrink when the caller increases a short timeout, always finalizes controller and action-timeline state, and detaches a timed-out debugger session while still holding an acquired control permit when a CDP command may be pending. Session removal and debugger teardown are atomic with respect to new session acquisition and bound to the exact acquired session, so late interruption or snapshot cleanup cannot detach a healthy replacement. Operations already queued on the retired semaphore detect that stale session and retry against its replacement. A request that times out while queued behind another action does not detach that action's shared debugger session.
-- Click, type, press, scroll, and wait operations clamp their caller-supplied timeout to the remaining renderer host budget before entering the desktop control-session boundary. Color-scheme changes and recording startup likewise receive the remaining deadline after overlay readiness; a timed-out color-scheme command does not persist a late preference, and timed-out recording startup tears down its frame-capture session and renderer recording state. Timed appearance persistence re-reads current tab state after CDP settles instead of relying on a pre-await snapshot. Recording stop bounds desktop capture shutdown, MediaRecorder settlement, blob conversion, and artifact persistence to the remaining deadline; a deadline failure retains captured chunks and the recording slot so finalization can be retried instead of silently losing the artifact. Operations without a caller timeout use the remaining bounded request budget rather than restarting the desktop default after renderer readiness work.
+- Click, type, press, scroll, and wait operations clamp their caller-supplied timeout to the remaining renderer host budget before entering the desktop control-session boundary. Color-scheme changes and recording startup likewise receive the remaining deadline after overlay readiness; a timed-out color-scheme command does not persist a late preference, and timed-out recording startup tears down its frame-capture session and renderer recording state. Timed appearance persistence re-reads current tab state after CDP settles and reapplies to the current guest if the webview was replaced instead of trusting a pre-await target snapshot. Recording stop bounds desktop capture shutdown, MediaRecorder settlement, blob conversion, and artifact persistence to the remaining deadline; renderer and desktop-originated deadline failures retain captured chunks and the recording slot so finalization can be retried instead of silently losing the artifact. An in-flight artifact-save promise is shared with that retry, preventing duplicate timestamped files when the renderer deadline wins before desktop IPC settles. Operations without a caller timeout use the remaining bounded request budget rather than restarting the desktop default after renderer readiness work.
 - Snapshot collection keeps active-tab capture on CDP `Page.captureScreenshot` from the compositor surface. For an unselected tab, the renderer stages the still-mounted guest at effectively transparent opacity for two compositor frames, but only for the snapshot itself. The desktop manager captures that compositor surface without focusing the guest or calling `Page.bringToFront`; either activation call can make Electron promote the native guest over the host window and keep the T3 interface covered after staging ends. A separately bounded `webContents.capturePage` attempt provides a fallback, using `stayHidden: true` for background guests and normal visible-page capture for the foreground. Primary and fallback screenshot waits are clamped to the remaining control-session deadline, with budget reserved for fallback and result settlement, so a tight caller deadline can still return semantic data instead of being preempted by the outer session timeout. Every returned PNG, including resized output, is validated and bounded. Final screenshot failure or timeout is logged, an actually timed-out CDP capture resets the session before releasing its control permit, queued work reattaches before issuing its first command, and a capture skipped before CDP runs leaves the healthy session attached. The semantic page state, interactive elements, accessibility tree, diagnostics, and action timeline still return with `screenshot: null` instead of failing the complete snapshot.
 - Desktop preview guests following the system color scheme create their CDP debugger session lazily, with initialization included in the automation operation deadline. This prevents an offscreen Chromium guest from leaving `Runtime.enable` pending while holding the synchronized session lock, which previously made every later evaluation or snapshot against that tab time out even after it became presentable. `apps/web/src/browser/desktopTabLifetime.ts` passes the upstream browser appearance default through `DesktopPreviewCreateTabInputSchema` in `packages/contracts/src/ipc.ts`; `apps/desktop/src/preview/Manager.ts` normalizes that value. A non-system color-scheme override is restored after webview registration or detached DevTools closes through a separately bounded recovery path, while tabs following the system scheme stay detached until the next automation operation.
 - Building on upstream's retained hidden guest, automation background snapshot presentation is reference-counted independently from the normal surface lease and composes with upstream's fitted-source content and corner-radius presentation. `PreviewAutomationHosts.tsx` passes the epoch-scoped runtime tab id into `previewAutomationPresentation.ts`; every surface lookup, staging marker, readiness check, diagnostic read, lease, and desktop capture targets that exact runtime guest, while selection and errors retain the stable server tab id. The presentation helper API has no state-derived or server-id compatibility fallback. Only a one-shot automation snapshot acquires this lease; upstream recording and picture-in-picture continue to use their shared frame-capture lifecycle, while navigation, color-scheme changes, evaluation, waits, and input operations do not acquire an automation presentation lease. Staging always restores the offscreen position and does not change the human-selected surface. The entire lease, including compositor-frame staging and desktop IPC, is bounded by the operation's remaining response budget and reports a typed timeout if it stalls. If the server epoch replaces the runtime guest while staging is pending, the snapshot fails immediately with `PreviewAutomationTargetUnavailableError` instead of waiting on the stale staging marker. If the user foregrounds the target in either surface while staging is pending, that visible presentation satisfies readiness. A never-presented tab does not depend on another browser surface having supplied a panel rectangle: automation staging falls back to a deterministic rectangle fitted inside the renderer viewport.
@@ -76,7 +76,7 @@ vp test run scripts/dev-runner.test.ts apps/desktop/src/app/DesktopAppIdentity.t
 
 Current verification:
 
-- The branch-focused suite passed 281 tests across 19 files on Windows, including bounded post-overlay and queued resize mutations, retryable recording finalization, recording-start cleanup, current-state appearance persistence, short-deadline viewport polling, post-read runtime-replacement, and background-guest accessibility regressions. The two unchanged desktop path-fixture files in the command above currently produce eight POSIX-versus-Windows path assertion failures; the affected runtime behavior passes in the remaining focused suite.
+- The branch-focused suite passed 284 tests across 19 files on Windows, including bounded post-overlay and queued resize mutations, retryable and deduplicated recording finalization across renderer and desktop timeouts, recording-start cleanup, replacement-guest appearance persistence, short-deadline viewport polling, post-read runtime-replacement, and background-guest accessibility regressions. The two unchanged desktop path-fixture files in the command above currently produce eight POSIX-versus-Windows path assertion failures; the affected runtime behavior passes in the remaining focused suite.
 - The incoming browser-default, provider-access, pull-request budget, tooltip, update-copy, and settings coverage passed 552 tests across 26 files. The focused open-policy and open-session subset passes 18 tests, including a shared explicit-over-default presentation decision and a reused rendered tab that remains in the background without a visibility wait.
 - Desktop, server, contracts, and mobile typechecks pass. Web typecheck currently reports 16 existing errors in `BranchToolbarBranchSelector.tsx`, `ModelPickerContent.tsx`, `PreviewAutomationHosts.tsx` at the pre-existing registry access, `FontFamilyPicker.tsx`, `use-atom-command.ts`, and `use-atom-query-runner.ts`; none are in the browser-default integration changed here.
 - An isolated web client on ports `5744`/`13784` paired and loaded successfully. Settings → Integrations exposed the browser defaults and agent-access setting; agent browser access could be disabled and restored. The non-Electron client correctly disabled desktop-only viewport, zoom, and appearance controls.

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

@@ -1861,6 +1861,89 @@ describe("PreviewManager", () => {
     ),
   );
 
+  effectIt.effect("reapplies a bounded color scheme after the webview is replaced", () =>
+    withManager((manager) =>
+      Effect.gen(function* () {
+        let finishFirstGuest: (() => void) | undefined;
+        const firstSendCommand = vi.fn(
+          async (method: string, parameters?: { features?: ReadonlyArray<{ value: string }> }) => {
+            if (
+              method === "Emulation.setEmulatedMedia" &&
+              parameters?.features?.[0]?.value === "dark"
+            ) {
+              await new Promise<void>((resolve) => {
+                finishFirstGuest = resolve;
+              });
+            }
+            return undefined;
+          },
+        );
+        const replacementSendCommand = vi.fn(async () => undefined);
+        const makeWebContents = (
+          id: number,
+          sendCommand: typeof firstSendCommand | typeof replacementSendCommand,
+        ) => {
+          let attached = false;
+          return {
+            id,
+            isDestroyed: () => false,
+            isDevToolsOpened: () => false,
+            getType: () => "webview",
+            getURL: () => "https://example.com",
+            getTitle: () => "Example",
+            isLoading: () => false,
+            getZoomFactor: () => 1,
+            setZoomFactor: vi.fn(),
+            on: vi.fn(),
+            off: vi.fn(),
+            ipc: { on: vi.fn(), off: vi.fn() },
+            send: webviewSend,
+            navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+            setWindowOpenHandler: vi.fn(),
+            debugger: {
+              isAttached: () => attached,
+              attach: vi.fn(() => {
+                attached = true;
+              }),
+              detach: vi.fn(() => {
+                attached = false;
+              }),
+              sendCommand,
+              on: vi.fn(),
+              off: vi.fn(),
+            },
+          } as never;
+        };
+        const first = makeWebContents(42, firstSendCommand);
+        const replacement = makeWebContents(43, replacementSendCommand);
+        fromId.mockImplementation((id) => (id === 42 ? first : id === 43 ? replacement : null));
+        const states: PreviewManager.PreviewTabState[] = [];
+        yield* manager.subscribeStateChanges((_tabId, state) =>
+          Effect.sync(() => {
+            states.push(state);
+          }),
+        );
+        yield* manager.createTab("tab_scheme_replacement");
+        yield* manager.registerWebview("tab_scheme_replacement", 42);
+        yield* Effect.yieldNow;
+
+        const mutation = yield* manager
+          .setColorScheme("tab_scheme_replacement", "dark", 1_000)
+          .pipe(Effect.forkChild({ startImmediately: true }));
+        yield* Effect.yieldNow;
+        yield* manager.registerWebview("tab_scheme_replacement", 43);
+        yield* Effect.yieldNow;
+        finishFirstGuest?.();
+        yield* Fiber.join(mutation);
+
+        expect(replacementSendCommand).toHaveBeenCalledWith("Emulation.setEmulatedMedia", {
+          features: [{ name: "prefers-color-scheme", value: "dark" }],
+        });
+        expect(states.at(-1)?.colorScheme).toBe("dark");
+      }),
+    ),
+  );
+
   effectIt.effect("blocks late webview and capture starts during tab close", () =>
     withManager((manager) =>
       Effect.gen(function* () {

apps/desktop/src/preview/Manager.ts

@@ -2338,30 +2338,46 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
       return yield* new PreviewTabNotFoundError({ tabId });
     }
     if (timeoutMs !== undefined) {
-      const wc = yield* requireWebContents(tabId);
-      yield* withControlSession(
-        tabId,
-        wc,
-        "set-color-scheme",
-        (send) =>
-          send("Emulation.setEmulatedMedia", {
-            features: [
-              {
-                name: "prefers-color-scheme",
-                value: colorScheme === "system" ? "" : colorScheme,
-              },
-            ],
-          }),
-        timeoutMs,
-      );
-      const currentTab = (yield* SynchronizedRef.get(tabsRef)).get(tabId);
-      if (!currentTab) {
-        return yield* new PreviewTabNotFoundError({ tabId });
-      }
-      if (currentTab.colorScheme !== colorScheme) {
-        yield* update(tabId, { colorScheme });
+      const deadline = (yield* currentMillis) + timeoutMs;
+      let target = yield* requireWebContents(tabId);
+      while (true) {
+        const remainingTimeoutMs = deadline - (yield* currentMillis);
+        if (remainingTimeoutMs <= 0) {
+          return yield* new PreviewAutomationTimeoutError({ tabId, timeoutMs });
+        }
+        yield* withControlSession(
+          tabId,
+          target,
+          "set-color-scheme",
+          (send) =>
+            send("Emulation.setEmulatedMedia", {
+              features: [
+                {
+                  name: "prefers-color-scheme",
+                  value: colorScheme === "system" ? "" : colorScheme,
+                },
+              ],
+            }),
+          remainingTimeoutMs,
+        );
+        const currentTab = (yield* SynchronizedRef.get(tabsRef)).get(tabId);
+        if (!currentTab) {
+          return yield* new PreviewTabNotFoundError({ tabId });
+        }
+        if (currentTab.webContentsId !== target.id) {
+          target = yield* requireWebContents(tabId);
+          continue;
+        }
+        if (currentTab.colorScheme !== colorScheme) {
+          yield* update(tabId, { colorScheme });
+        }
+        const appliedTab = (yield* SynchronizedRef.get(tabsRef)).get(tabId);
+        if (!appliedTab) {
+          return yield* new PreviewTabNotFoundError({ tabId });
+        }
+        if (appliedTab.webContentsId === target.id) return;
+        target = yield* requireWebContents(tabId);
       }
-      return;
     }
     if (tab.colorScheme !== colorScheme) {
       // Record the choice even when the CDP call below can't run yet (no

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

@@ -526,6 +526,58 @@ describe("browser recording", () => {
     expect(readActiveBrowserRecordingTabIds()).toEqual(new Set());
   });
 
+  it("shares an in-flight artifact save with a retry after the renderer deadline", async () => {
+    vi.useFakeTimers();
+    let finishSaving: ((artifact: Awaited<ReturnType<typeof save>>) => void) | undefined;
+    save.mockImplementationOnce(
+      async () =>
+        await new Promise<Awaited<ReturnType<typeof save>>>((resolve) => {
+          finishSaving = resolve;
+        }),
+    );
+    await startBrowserRecording("recording-tab");
+
+    const firstStop = stopBrowserRecording("recording-tab", 40);
+    const rejection = expect(firstStop).rejects.toMatchObject({ operation: "stop-deadline" });
+    await vi.advanceTimersByTimeAsync(40);
+    await rejection;
+
+    const retry = stopBrowserRecording("recording-tab");
+    expect(save).toHaveBeenCalledOnce();
+    finishSaving?.({
+      id: "recording-test",
+      tabId: "recording-tab",
+      path: "/tmp/recording-test.webm",
+      mimeType: "video/webm",
+      sizeBytes: 0,
+      createdAt: "2026-06-26T00:00:00.000Z",
+    });
+
+    await expect(retry).resolves.toMatchObject({ id: "recording-test" });
+    expect(save).toHaveBeenCalledOnce();
+    expect(readActiveBrowserRecordingTabIds()).toEqual(new Set());
+  });
+
+  it("keeps recording state retryable when the desktop stop deadline rejects first", async () => {
+    stopScreencast.mockRejectedValueOnce({
+      _tag: "PreviewAutomationTimeoutError",
+      tabId: "recording-tab",
+      timeoutMs: 40,
+    });
+    await startBrowserRecording("recording-tab");
+
+    await expect(stopBrowserRecording("recording-tab", 40)).rejects.toMatchObject({
+      operation: "stop-deadline",
+      tabId: "recording-tab",
+    });
+    expect(readActiveBrowserRecordingTabIds()).toEqual(new Set(["recording-tab"]));
+
+    await expect(stopBrowserRecording("recording-tab")).resolves.toMatchObject({
+      tabId: "recording-tab",
+    });
+    expect(readActiveBrowserRecordingTabIds()).toEqual(new Set());
+  });
+
   it("finishes startup before stopping so an active recording yields an artifact", async () => {
     let finishStartingScreencast: (() => void) | undefined;
     startScreencast.mockImplementationOnce(async () => {