Add preview color scheme controls and simplify project grouping

apps/desktop/src/ipc/channels.ts

@@ -50,6 +50,7 @@ export const PREVIEW_ZOOM_IN_CHANNEL = "desktop:preview-zoom-in";
 export const PREVIEW_ZOOM_OUT_CHANNEL = "desktop:preview-zoom-out";
 export const PREVIEW_RESET_ZOOM_CHANNEL = "desktop:preview-reset-zoom";
 export const PREVIEW_HARD_RELOAD_CHANNEL = "desktop:preview-hard-reload";
+export const PREVIEW_SET_COLOR_SCHEME_CHANNEL = "desktop:preview-set-color-scheme";
 export const PREVIEW_OPEN_DEVTOOLS_CHANNEL = "desktop:preview-open-devtools";
 export const PREVIEW_CLEAR_COOKIES_CHANNEL = "desktop:preview-clear-cookies";
 export const PREVIEW_CLEAR_CACHE_CHANNEL = "desktop:preview-clear-cache";

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

@@ -13,6 +13,7 @@ import {
   DesktopPreviewRecordingSaveInputSchema,
   DesktopPreviewRegisterWebviewInputSchema,
   DesktopPreviewScreenshotArtifactSchema,
+  DesktopPreviewSetColorSchemeInputSchema,
   DesktopPreviewTabInputSchema,
   DesktopPreviewWebviewConfigSchema,
   PreviewAnnotationPayloadSchema,
@@ -138,6 +139,15 @@ export const hardReload = tabMethod(
   "desktop.ipc.preview.hardReload",
   (manager, tabId) => manager.hardReload(tabId),
 );
+export const setColorScheme = DesktopIpc.makeIpcMethod({
+  channel: IpcChannels.PREVIEW_SET_COLOR_SCHEME_CHANNEL,
+  payload: DesktopPreviewSetColorSchemeInputSchema,
+  result: Schema.Void,
+  handler: Effect.fn("desktop.ipc.preview.setColorScheme")(function* ({ tabId, colorScheme }) {
+    const manager = yield* PreviewManager.PreviewManager;
+    yield* manager.setColorScheme(tabId, colorScheme);
+  }),
+});
 export const openDevTools = tabMethod(
   IpcChannels.PREVIEW_OPEN_DEVTOOLS_CHANNEL,
   "desktop.ipc.preview.openDevTools",
@@ -346,6 +356,7 @@ export const methods = [
   zoomOut,
   resetZoom,
   hardReload,
+  setColorScheme,
   openDevTools,
   clearCookies,
   clearCache,

apps/desktop/src/preload.ts

@@ -160,6 +160,8 @@ contextBridge.exposeInMainWorld("desktopBridge", {
     zoomOut: (tabId) => ipcRenderer.invoke(IpcChannels.PREVIEW_ZOOM_OUT_CHANNEL, { tabId }),
     resetZoom: (tabId) => ipcRenderer.invoke(IpcChannels.PREVIEW_RESET_ZOOM_CHANNEL, { tabId }),
     hardReload: (tabId) => ipcRenderer.invoke(IpcChannels.PREVIEW_HARD_RELOAD_CHANNEL, { tabId }),
+    setColorScheme: (tabId, colorScheme) =>
+      ipcRenderer.invoke(IpcChannels.PREVIEW_SET_COLOR_SCHEME_CHANNEL, { tabId, colorScheme }),
     openDevTools: (tabId) =>
       ipcRenderer.invoke(IpcChannels.PREVIEW_OPEN_DEVTOOLS_CHANNEL, { tabId }),
     clearCookies: () => ipcRenderer.invoke(IpcChannels.PREVIEW_CLEAR_COOKIES_CHANNEL),

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

@@ -365,6 +365,79 @@ describe("PreviewManager", () => {
     ),
   );
 
+  effectIt.effect("emulates prefers-color-scheme and re-applies it across webview swaps", () =>
+    withManager((manager) =>
+      Effect.gen(function* () {
+        const makeWebContents = (id: number) => {
+          const sendCommand = vi.fn(async () => undefined);
+          return {
+            sendCommand,
+            wc: {
+              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: () => false,
+                attach: vi.fn(),
+                sendCommand,
+                on: vi.fn(),
+                off: vi.fn(),
+              },
+            } as never,
+          };
+        };
+        const first = makeWebContents(42);
+        fromId.mockReturnValue(first.wc);
+        const states: PreviewManager.PreviewTabState[] = [];
+
+        yield* manager.subscribeStateChanges((_tabId, state) =>
+          Effect.sync(() => {
+            states.push(state);
+          }),
+        );
+        yield* manager.createTab("tab_scheme");
+        yield* manager.registerWebview("tab_scheme", 42);
+        yield* Effect.yieldNow;
+
+        yield* manager.setColorScheme("tab_scheme", "dark");
+
+        expect(first.sendCommand).toHaveBeenCalledWith("Emulation.setEmulatedMedia", {
+          features: [{ name: "prefers-color-scheme", value: "dark" }],
+        });
+        expect(states.at(-1)?.colorScheme).toBe("dark");
+
+        const replacement = makeWebContents(43);
+        fromId.mockReturnValue(replacement.wc);
+        yield* manager.registerWebview("tab_scheme", 43);
+        yield* Effect.yieldNow;
+
+        expect(replacement.sendCommand).toHaveBeenCalledWith("Emulation.setEmulatedMedia", {
+          features: [{ name: "prefers-color-scheme", value: "dark" }],
+        });
+        expect(states.at(-1)?.colorScheme).toBe("dark");
+
+        yield* manager.setColorScheme("tab_scheme", "system");
+
+        expect(replacement.sendCommand).toHaveBeenCalledWith("Emulation.setEmulatedMedia", {
+          features: [{ name: "prefers-color-scheme", value: "" }],
+        });
+        expect(states.at(-1)?.colorScheme).toBe("system");
+      }),
+    ),
+  );
+
   effectIt.effect("keeps a main-frame load failure visible until a retry starts", () =>
     withManager((manager) =>
       Effect.gen(function* () {

apps/desktop/src/preview/Manager.ts

@@ -7,6 +7,7 @@
  */
 import type {
   DesktopPreviewAnnotationTheme,
+  DesktopPreviewColorScheme,
   DesktopPreviewPointerEvent,
   PreviewAnnotationPayload,
   PreviewAnnotationRect,
@@ -84,6 +85,7 @@ export interface PreviewTabState {
   canGoBack: boolean;
   canGoForward: boolean;
   zoomFactor: number;
+  colorScheme: DesktopPreviewColorScheme;
   controller: "human" | "agent" | "none";
   updatedAt: string;
 }
@@ -1288,6 +1290,7 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
         canGoBack: false,
         canGoForward: false,
         zoomFactor: DEFAULT_ZOOM_FACTOR,
+        colorScheme: "system",
         controller: "none",
         updatedAt,
       };
@@ -1320,6 +1323,7 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
       canGoBack: false,
       canGoForward: false,
       zoomFactor: DEFAULT_ZOOM_FACTOR,
+      colorScheme: "system",
       controller: "none",
       updatedAt,
     };
@@ -1386,7 +1390,7 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
             wc.getZoomFactor(),
           );
     yield* attachListeners(tabId, wc);
-    runFork(ensureControlSession(wc).pipe(Effect.ignore));
+    runFork(restoreControlSession(tabId, wc));
     const registeredAt = yield* currentIso;
     const registration = yield* SynchronizedRef.modify(tabsRef, (tabs) => {
       const current = tabs.get(tabId);
@@ -1457,6 +1461,7 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
         canGoBack: current?.canGoBack ?? false,
         canGoForward: current?.canGoForward ?? false,
         zoomFactor: current?.zoomFactor ?? DEFAULT_ZOOM_FACTOR,
+        colorScheme: current?.colorScheme ?? "system",
         controller: current?.controller ?? "none",
         updatedAt,
       };
@@ -1525,7 +1530,7 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
     yield* detachControlSession(wc.id);
     yield* attempt({ operation: "openDevTools", tabId, webContentsId: wc.id }, () => {
       wc.once("devtools-closed", () => {
-        if (!wc.isDestroyed()) runFork(ensureControlSession(wc).pipe(Effect.ignore));
+        if (!wc.isDestroyed()) runFork(restoreControlSession(tabId, wc));
       });
       wc.openDevTools({ mode: "detach" });
     });
@@ -1684,6 +1689,65 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
     yield* update(tabId, { zoomFactor: next });
   });
 
+  // Emulated media lives on the CDP debugger session, not the WebContents, so
+  // it is lost whenever the session detaches (webview swap, DevTools
+  // open/close) and must be re-applied after every (re)attach.
+  const applyColorScheme = Effect.fn("PreviewManager.applyColorScheme")(function* (
+    tabId: string,
+    wc: Electron.WebContents,
+    colorScheme: DesktopPreviewColorScheme,
+  ) {
+    yield* ensureControlSession(wc);
+    yield* attemptPromise({ operation: "applyColorScheme", tabId, webContentsId: wc.id }, () =>
+      wc.debugger.sendCommand("Emulation.setEmulatedMedia", {
+        features: [
+          {
+            name: "prefers-color-scheme",
+            // An empty value clears the override so the page follows the OS.
+            value: colorScheme === "system" ? "" : colorScheme,
+          },
+        ],
+      }),
+    );
+  });
+
+  // Re-establish the control session after a detach, restoring any
+  // color-scheme override the tab carries. The scheme is read after the
+  // session attaches so a concurrent setColorScheme is not overwritten with
+  // a stale snapshot.
+  const restoreControlSession = (tabId: string, wc: Electron.WebContents) =>
+    ensureControlSession(wc).pipe(
+      Effect.andThen(SynchronizedRef.get(tabsRef)),
+      Effect.flatMap((tabs) => {
+        const colorScheme = tabs.get(tabId)?.colorScheme ?? "system";
+        return colorScheme === "system" ? Effect.void : applyColorScheme(tabId, wc, colorScheme);
+      }),
+      Effect.ignore,
+    );
+
+  const setColorScheme = Effect.fn("PreviewManager.setColorScheme")(function* (
+    tabId: string,
+    colorScheme: DesktopPreviewColorScheme,
+  ) {
+    const tab = (yield* SynchronizedRef.get(tabsRef)).get(tabId);
+    if (!tab) {
+      return yield* new PreviewTabNotFoundError({ tabId });
+    }
+    if (tab.colorScheme !== colorScheme) {
+      // Record the choice even when the CDP call below can't run yet (no
+      // webview, DevTools holding the debugger) — it is re-applied on the
+      // next control-session (re)attach.
+      yield* update(tabId, { colorScheme });
+    }
+    // Re-read after the update: registerWebview may have swapped the guest
+    // in the meantime and the override must land on the current one.
+    const webContentsId = (yield* SynchronizedRef.get(tabsRef)).get(tabId)?.webContentsId;
+    if (webContentsId == null) return;
+    const wc = webContents.fromId(webContentsId);
+    if (!wc || wc.isDestroyed()) return;
+    yield* applyColorScheme(tabId, wc, colorScheme);
+  });
+
   const captureScreenshot = Effect.fn("PreviewManager.captureScreenshot")(function* (
     tabId: string,
   ) {
@@ -2526,6 +2590,7 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
     revealArtifact,
     saveRecording,
     setAnnotationTheme,
+    setColorScheme,
     setMainWindow,
     startRecording,
     stopRecording,
@@ -2830,6 +2895,10 @@ export class PreviewManager extends Context.Service<
     readonly zoomOut: (tabId: string) => Effect.Effect<void, PreviewManagerError>;
     readonly resetZoom: (tabId: string) => Effect.Effect<void, PreviewManagerError>;
     readonly hardReload: (tabId: string) => Effect.Effect<void, PreviewManagerError>;
+    readonly setColorScheme: (
+      tabId: string,
+      colorScheme: DesktopPreviewColorScheme,
+    ) => Effect.Effect<void, PreviewManagerError>;
     readonly openDevTools: (tabId: string) => Effect.Effect<void, PreviewManagerError>;
     readonly clearCookies: () => Effect.Effect<void, PreviewManagerError>;
     readonly clearCache: () => Effect.Effect<void, PreviewManagerError>;
@@ -2921,6 +2990,7 @@ export const make = Effect.gen(function* PreviewManagerMake() {
     zoomOut: operations.zoomOut,
     resetZoom: operations.resetZoom,
     hardReload: operations.hardReload,
+    setColorScheme: operations.setColorScheme,
     openDevTools: operations.openDevTools,
     clearCookies: Effect.fn("PreviewManager.clearCookies")(function* () {
       yield* browserSession

apps/server/src/mcp/toolkits/preview/handlers.ts

@@ -4,6 +4,7 @@ import type {
   PreviewAutomationRecordingArtifact,
   PreviewAutomationRecordingStatus,
   PreviewAutomationResizeResult,
+  PreviewAutomationSetColorSchemeResult,
   PreviewAutomationSnapshot,
   PreviewAutomationStatus,
   PreviewTabId,
@@ -58,6 +59,8 @@ const handlers = {
     invokeTargeted<PreviewAutomationStatus>("navigate", input, input.timeoutMs),
   preview_resize: (input) =>
     invokeTargeted<PreviewAutomationResizeResult>("resize", input, input.timeoutMs),
+  preview_set_appearance: (input) =>
+    invokeTargeted<PreviewAutomationSetColorSchemeResult>("setColorScheme", input),
   preview_snapshot: (input) => invokeTargeted<PreviewAutomationSnapshot>("snapshot", input ?? {}),
   preview_click: (input) =>
     invokeTargeted<void>("click", input, input.timeoutMs).pipe(Effect.as(null)),

apps/server/src/mcp/toolkits/preview/tools.ts

@@ -10,6 +10,8 @@ import {
   PreviewAutomationResizeInput,
   PreviewAutomationResizeResult,
   PreviewAutomationScrollInput,
+  PreviewAutomationSetColorSchemeInput,
+  PreviewAutomationSetColorSchemeResult,
   PreviewAutomationSnapshot,
   PreviewAutomationStatus,
   PreviewAutomationTabTargetInput,
@@ -86,6 +88,19 @@ export const PreviewResizeTool = safeBrowserTool(
     .annotate(Tool.Idempotent, true),
 );
 
+export const PreviewSetAppearanceTool = safeBrowserTool(
+  Tool.make("preview_set_appearance", {
+    description:
+      "Emulate prefers-color-scheme in a collaborative browser tab, optionally selected by tabId. Use {colorScheme:'dark'} or {colorScheme:'light'} to preview the page in that appearance, and {colorScheme:'system'} to clear the override and follow the OS appearance.",
+    parameters: PreviewAutomationSetColorSchemeInput,
+    success: PreviewAutomationSetColorSchemeResult,
+    failure: PreviewAutomationError,
+    dependencies,
+  })
+    .annotate(Tool.Title, "Set preview appearance")
+    .annotate(Tool.Idempotent, true),
+);
+
 export const PreviewSnapshotTool = readonlyBrowserTool(
   Tool.make("preview_snapshot", {
     description:
@@ -189,6 +204,7 @@ export const PreviewToolkit = Toolkit.make(
   PreviewOpenTool,
   PreviewNavigateTool,
   PreviewResizeTool,
+  PreviewSetAppearanceTool,
   PreviewSnapshotTool,
   PreviewClickTool,
   PreviewTypeTool,
@@ -205,6 +221,7 @@ export const PreviewStandardToolkit = Toolkit.make(
   PreviewOpenTool,
   PreviewNavigateTool,
   PreviewResizeTool,
+  PreviewSetAppearanceTool,
   PreviewClickTool,
   PreviewTypeTool,
   PreviewPressTool,

apps/web/src/components/preview/PreviewAutomationHosts.tsx

@@ -10,6 +10,8 @@ import {
   type PreviewAutomationOpenInput,
   type PreviewAutomationResizeInput,
   type PreviewAutomationResizeResult,
+  type PreviewAutomationSetColorSchemeInput,
+  type PreviewAutomationSetColorSchemeResult,
   type PreviewAutomationHost as PreviewAutomationHostState,
   type PreviewAutomationRequest,
   type PreviewAutomationStatus,
@@ -451,6 +453,15 @@ function PreviewAutomationHost(props: { readonly environmentId: EnvironmentId })
               viewport,
             } satisfies PreviewAutomationResizeResult;
           }
+          case "setColorScheme": {
+            const ready = await requireReadyTab();
+            const input = request.input as PreviewAutomationSetColorSchemeInput;
+            await ready.bridge.setColorScheme(ready.tabId, input.colorScheme);
+            return {
+              tabId: ready.tabId,
+              colorScheme: input.colorScheme,
+            } satisfies PreviewAutomationSetColorSchemeResult;
+          }
           case "snapshot": {
             const ready = await requireReadyTab();
             return await ready.bridge.automation.snapshot(ready.tabId);