sailfork / t3code-github / apps/ desktop/ src/ preview/ Manager.ts

import * as NodeZlib from "node:zlib";
import {
  DesktopPreviewAnnotationVoiceEventSchema,
  DesktopPreviewRecordingInputSchema,
  DESKTOP_PREVIEW_RECORDING_CAPTURE_TRIGGER,
} from "@t3tools/contracts";
import type {
  DesktopPreviewAnnotationTheme,
  DesktopPreviewAnnotationVoiceConfig,
  DesktopPreviewAnnotationVoiceState,
  DesktopPreviewColorScheme,
  DesktopPreviewFavicon,
  DesktopPreviewOpenLinkEvent,
  DesktopPreviewPointerEvent,
  PreviewAnnotationPayload,
  PreviewAnnotationRect,
  PreviewAnnotationSubmissionResult,
  DesktopPreviewRecordingArtifact,
  DesktopPreviewRecordingFrame,
  DesktopPreviewRecordingInputEvent,
  DesktopPreviewScreenshotArtifact,
  DesktopPreviewTabDefaults,
  PreviewForwardedShortcut,
} from "@t3tools/contracts";
import * as HostProcess from "@t3tools/shared/HostProcess";
import { matchesKeybindingShortcut } from "@t3tools/shared/keybindings";
import { normalizePreviewUrl } from "@t3tools/shared/preview";
import {
  BrowserWindow,
  ClipboardItem,
  app,
  type Session,
  clipboard,
  nativeImage,
  shell,
  webContents,
} from "electron";
import * as Cause from "effect/Cause";
import * as Clock from "effect/Clock";
import * as Context from "effect/Context";
import * as SecureRandom from "effect/crypto/SecureRandom";
import * as DateTime from "effect/DateTime";
import * as Deferred from "effect/Deferred";
import * as Effect from "effect/Effect";
import * as Exit from "effect/Exit";
import * as FileSystem from "effect/FileSystem";
import * as Fiber from "effect/Fiber";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as Path from "effect/Path";
import * as Queue from "effect/Queue";
import * as Ref from "effect/Ref";
import * as Schema from "effect/Schema";
import * as Semaphore from "effect/Semaphore";
import * as Stream from "effect/Stream";
import * as Schedule from "effect/Schedule";
import * as Scope from "effect/Scope";
import * as SynchronizedRef from "effect/SynchronizedRef";

import * as DesktopEnvironment from "../app/DesktopEnvironment.ts";
import * as DesktopRendererHistory from "../telemetry/DesktopRendererHistory.ts";
import {
  MENU_ACTION_CHANNEL,
  PREVIEW_ANNOTATION_VOICE_EVENT_CHANNEL,
  PREVIEW_PICTURE_IN_PICTURE_FRAME_CHANNEL,
} from "../ipc/channels.ts";
import * as DesktopBrowserHost from "./DesktopBrowserHost.ts";
import * as PreviewPasskeys from "./Passkeys.ts";
import * as BrowserSession from "./BrowserSession.ts";
import {
  ANNOTATION_CAPTURED_CHANNEL,
  ANNOTATION_SEND_ENABLED_CHANNEL,
  ANNOTATION_VOICE_EVENT_CHANNEL,
  ANNOTATION_VOICE_STATE_CHANNEL,
  ANNOTATION_THEME_CHANNEL,
  CANCEL_PICK_CHANNEL,
  ELEMENT_PICKED_CHANNEL,
  HUMAN_INPUT_CHANNEL,
  MOUSE_NAVIGATE_CHANNEL,
  RECORDING_CURSOR_CHANNEL,
  RECORDING_INPUT_CHANNEL,
  RECORDING_CONTROLLER_CHANNEL,
  RECORDING_POINTER_CHANNEL,
  START_PICK_CHANNEL,
} from "./GuestProtocol.ts";
import { isPreviewAnnotationPayload } from "./PickedElementPayload.ts";
import { captureFavicon, safeHttpOrigin, selectFaviconCandidates } from "./FaviconCapture.ts";
import { DEFAULT_RECORDING_INPUT_OPTIONS, type RecordingInputOptions } from "./RecordingInput.ts";

export type PreviewNavStatus =
  | { kind: "Idle" }
  | { kind: "Loading"; url: string; title: string }
  | { kind: "Success"; url: string; title: string }
  | {
      kind: "LoadFailed";
      url: string;
      title: string;
      code: number;
      description: string;
    };

export interface PreviewTabState {
  tabId: string;
  webContentsId: number | null;
  navStatus: PreviewNavStatus;
  canGoBack: boolean;
  canGoForward: boolean;
  zoomFactor: number;
  pictureInPicture: boolean;
  colorScheme: DesktopPreviewColorScheme;
  audioMuted: boolean;
  audible: boolean;
  controller: "human" | "agent" | "none";
  capturing: boolean;
  favicon?: DesktopPreviewFavicon;
  serverTab?: { readonly threadId: string; readonly tabId: string };
  updatedAt: string;
}

const ZOOM_LEVELS: ReadonlyArray<number> = [
  0.25, 0.33, 0.5, 0.67, 0.75, 0.8, 0.9, 1.0, 1.1, 1.25, 1.5, 1.75, 2.0, 2.5, 3.0, 4.0, 5.0,
];

const DEFAULT_ZOOM_FACTOR = 1.0;
const ZOOM_EPSILON = 0.001;
const RECORDING_ARM_GRACE_MS = 10_000;
const PICTURE_IN_PICTURE_FRAME_INTERVAL_MS = Math.ceil(1_000 / 12);
const PICTURE_IN_PICTURE_JPEG_QUALITY = 80;
// Cold guests can reject capturePage with UnknownVizError or stall; bound each attempt.
const CAPTURE_PAGE_RETRY_ATTEMPTS = 3;
const CAPTURE_PAGE_RETRY_DELAY_MS = 120;
const CAPTURE_PAGE_ATTEMPT_TIMEOUT_MS = 1_000;
const PICTURE_IN_PICTURE_INITIAL_WIDTH = 480;
const PICTURE_IN_PICTURE_INITIAL_HEIGHT = 320;
const PICTURE_IN_PICTURE_MIN_WIDTH = 240;
const PICTURE_IN_PICTURE_MIN_HEIGHT = 160;
const PICTURE_IN_PICTURE_ASPECT_RATIO_EPSILON = 0.002;
const MAX_ARTIFACT_SITE_SLUG_LENGTH = 80;
const requestRecordingCaptureExpression = (tabId: string): string =>
  `globalThis[${JSON.stringify(DESKTOP_PREVIEW_RECORDING_CAPTURE_TRIGGER)}]?.(${JSON.stringify(tabId)}) === true`;
const DEFAULT_ANNOTATION_THEME: DesktopPreviewAnnotationTheme = {
  colorScheme: "light",
  radius: "0.625rem",
  background: "white",
  foreground: "oklch(0.269 0 0)",
  popover: "white",
  popoverForeground: "oklch(0.269 0 0)",
  primary: "oklch(0.488 0.217 264)",
  primaryForeground: "white",
  muted: "rgb(0 0 0 / 4%)",
  mutedForeground: "oklch(0.556 0 0)",
  accent: "rgb(0 0 0 / 4%)",
  accentForeground: "oklch(0.269 0 0)",
  border: "rgb(0 0 0 / 8%)",
  input: "rgb(0 0 0 / 10%)",
  ring: "oklch(0.488 0.217 264)",
  fontSans: "system-ui, sans-serif",
  fontMono: "ui-monospace, monospace",
};

const buildPreviewPictureInPictureDataUrl = (): string => {
  const html = `<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <meta
      http-equiv="Content-Security-Policy"
      content="default-src 'none'; img-src data:; style-src 'unsafe-inline'; script-src 'unsafe-inline'"
    >
    <meta name="color-scheme" content="dark">
    <style>
      html, body { width: 100%; height: 100%; margin: 0; overflow: hidden; background: #111; }
      body { display: grid; place-items: center; }
      img { width: 100%; height: 100%; object-fit: contain; user-select: none; -webkit-user-drag: none; }
    </style>
  </head>
  <body>
    <img id="preview-frame" alt="Live browser preview">
    <script>
      const frame = document.getElementById("preview-frame");
      window.previewPictureInPicture.onFrame((next) => {
        frame.src = "data:image/jpeg;base64," + next.data;
      });
    </script>
  </body>
</html>`;
  return `data:text/html;charset=utf-8,${encodeURIComponent(html)}`;
};

export const fitPictureInPictureContentSize = (
  current: ReadonlyArray<number>,
  aspectRatio: number,
): readonly [width: number, height: number] => {
  const currentWidth = Math.max(1, current[0] ?? PICTURE_IN_PICTURE_INITIAL_WIDTH);
  const currentHeight = Math.max(1, current[1] ?? PICTURE_IN_PICTURE_INITIAL_HEIGHT);
  const currentArea = currentWidth * currentHeight;
  let width = Math.sqrt(currentArea * aspectRatio);
  let height = width / aspectRatio;
  const minimumScale = Math.max(
    1,
    PICTURE_IN_PICTURE_MIN_WIDTH / width,
    PICTURE_IN_PICTURE_MIN_HEIGHT / height,
  );
  width *= minimumScale;
  height *= minimumScale;
  return [Math.round(width), Math.round(height)];
};

const recordingFileExtension = (mimeType: string): string => {
  const subtype = mimeType.split(";", 1)[0]?.trim().toLowerCase().split("/")[1] ?? "";
  const extension = subtype.replace(/^x-/, "").replace(/[^a-z0-9]/g, "");
  return extension || "video";
};

const artifactSiteSlug = (rawUrl: string): string => {
  try {
    const url = new URL(rawUrl);
    const slug = url.hostname
      .toLowerCase()
      .replace(/[^a-z0-9]+/g, "-")
      .replace(/^-+|-+$/g, "")
      .slice(0, MAX_ARTIFACT_SITE_SLUG_LENGTH)
      .replace(/-+$/g, "");
    return slug || "site";
  } catch {
    return "site";
  }
};

export const PreviewAutomationSelectorKind = Schema.Literals([
  "focused-element",
  "selector",
  "locator",
]);
export type PreviewAutomationSelectorKind = typeof PreviewAutomationSelectorKind.Type;

export const PreviewAutomationEvaluationDetailKind = Schema.Literals([
  "exception-description",
  "exception-text",
  "unknown",
]);
export type PreviewAutomationEvaluationDetailKind =
  typeof PreviewAutomationEvaluationDetailKind.Type;

interface PreviewOperationContext {
  readonly operation: string;
  readonly tabId?: string;
  readonly webContentsId?: number;
  readonly artifactPath?: string;
}

const normalizeCaptureRect = (value: unknown): PreviewAnnotationRect | null => {
  if (typeof value !== "object" || value === null) return null;
  const rect = value as Record<string, unknown>;
  const x = rect["x"];
  const y = rect["y"];
  const width = rect["width"];
  const height = rect["height"];
  if (
    typeof x !== "number" ||
    !Number.isFinite(x) ||
    typeof y !== "number" ||
    !Number.isFinite(y) ||
    typeof width !== "number" ||
    !Number.isFinite(width) ||
    typeof height !== "number" ||
    !Number.isFinite(height) ||
    width <= 0 ||
    height <= 0
  ) {
    return null;
  }
  return { x, y, width, height };
};

// capturePage returns a 1x NativeImage containing device pixels, so crop() uses
// CSS coordinates scaled by the guest's devicePixelRatio (including page zoom).
const cropAnnotationScreenshot = (
  image: Electron.NativeImage,
  cropRect: PreviewAnnotationRect | null,
  devicePixelRatio: number,
  targetRects: ReadonlyArray<PreviewAnnotationRect>,
): PreviewAnnotationPayload["screenshot"] => {
  const full = image.getSize();
  if (full.width <= 0 || full.height <= 0) return null;
  const scale = Number.isFinite(devicePixelRatio) && devicePixelRatio > 0 ? devicePixelRatio : 1;
  // Padding or a union of offscreen targets can overlap an empty viewport area.
  // A zero-width/height SVG line can still paint at the top or left edge.
  if (
    targetRects.length > 0 &&
    !targetRects.some(
      (rect) =>
        (rect.width > 0 || rect.height > 0) &&
        rect.x * scale < full.width &&
        rect.y * scale < full.height &&
        (rect.width === 0 ? rect.x >= 0 : rect.x + rect.width > 0) &&
        (rect.height === 0 ? rect.y >= 0 : rect.y + rect.height > 0),
    )
  ) {
    return null;
  }
  if (!cropRect) {
    return {
      dataUrl: image.toDataURL(),
      width: full.width,
      height: full.height,
      cropRect: { x: 0, y: 0, width: full.width, height: full.height },
    };
  }
  const x = Math.max(0, Math.floor(cropRect.x * scale));
  const y = Math.max(0, Math.floor(cropRect.y * scale));
  const right = Math.min(full.width, Math.ceil((cropRect.x + cropRect.width) * scale));
  const bottom = Math.min(full.height, Math.ceil((cropRect.y + cropRect.height) * scale));
  // A target scrolled out of view has no pixels in this capture. Clamping its
  // origin onto the edge would attach an unrelated strip as a successful crop.
  if (right <= x || bottom <= y) return null;
  const cropped = image.crop({
    x,
    y,
    width: right - x,
    height: bottom - y,
  });
  const size = cropped.getSize();
  if (size.width <= 0 || size.height <= 0) return null;
  return { dataUrl: cropped.toDataURL(), width: size.width, height: size.height, cropRect };
};

// An invalid color space skips costly P3-to-sRGB conversion; fingerprints need no color accuracy.
const FINGERPRINT_BITMAP_OPTIONS: Electron.ToBitmapOptions = {
  colorSpace: { primaries: "invalid", transfer: "invalid", matrix: "invalid", range: "invalid" },
};

/** Empty readPixels results have no fingerprint and must be treated as changed frames. */
const fingerprintCapturedFrame = (image: Electron.NativeImage, size: Electron.Size) => {
  let bitmap: Buffer;
  try {
    bitmap = image.toBitmap(FINGERPRINT_BITMAP_OPTIONS);
  } catch {
    return null;
  }
  if (bitmap.byteLength === 0) return null;
  return `${size.width}x${size.height}:${NodeZlib.crc32(bitmap)}`;
};

const findZoomStep = (current: number): number => {
  const index = ZOOM_LEVELS.findIndex(
    (level) => Math.abs(level - current) < ZOOM_EPSILON || level > current,
  );
  if (index < 0) return ZOOM_LEVELS.length - 1;
  return Math.abs(ZOOM_LEVELS[index]! - current) < ZOOM_EPSILON ? index : index - 1;
};

const normalizeZoomFactor = (value: number | undefined): number => {
  if (value === undefined || !Number.isFinite(value)) return DEFAULT_ZOOM_FACTOR;
  let closest = ZOOM_LEVELS[0]!;
  for (const level of ZOOM_LEVELS) {
    if (Math.abs(level - value) < Math.abs(closest - value)) closest = level;
  }
  return closest;
};

const nextZoomLevel = (current: number, direction: "in" | "out"): number => {
  const step = findZoomStep(current);
  if (direction === "in") {
    return ZOOM_LEVELS[Math.min(step + 1, ZOOM_LEVELS.length - 1)] ?? current;
  }
  return ZOOM_LEVELS[Math.max(step - 1, 0)] ?? current;
};

type Listener = (tabId: string, state: PreviewTabState) => Effect.Effect<void>;

type PreviewInputSignal =
  | { readonly kind: "pointer"; readonly x: number; readonly y: number; readonly button: number }
  | { readonly kind: "key"; readonly key: string; readonly code: string };

interface ManagedListeners {
  readonly attachmentId: symbol;
  readonly cancelFaviconCapture: () => void;
  readonly scope: Scope.Closeable;
  readonly webContents: Electron.WebContents;
}

type FrameCaptureConsumer = "picture-in-picture" | "recording";

interface FrameCaptureSession {
  readonly recordingInputOptions?: RecordingInputOptions;
  readonly scope: Scope.Closeable | null;
  readonly consumers: ReadonlySet<FrameCaptureConsumer>;
  readonly unthrottledWebContentsIds: ReadonlySet<number>;
  readonly lastPictureInPictureFingerprint: string | null;
}

interface PictureInPictureSession {
  readonly window: BrowserWindow;
  readonly webContentsId: number;
  readonly ready: Deferred.Deferred<void, PreviewManagerError>;
  readonly initializationScope: Scope.Closeable;
}

interface PendingRecording {
  readonly tabId: string;
  readonly webContents: Electron.WebContents;
  readonly requestingFrameTreeNodeId: number;
  readonly armedAtMillis: number;
}

interface PickSession {
  readonly voiceSessionId?: string | undefined;
  readonly cancel: Effect.Effect<void>;
}

const decodeAnnotationVoiceEvent = Schema.decodeUnknownOption(
  DesktopPreviewAnnotationVoiceEventSchema,
);

interface BrowserControlSession {
  readonly webContentsId: number;
  // Retain the attached Debugger to prevent GC crashes (electron/electron#53376); wc.debugger throws after destruction.
  readonly debugger: Electron.Debugger;
  readonly semaphore: Semaphore.Semaphore;
  readonly scope: Scope.Closeable;
  readonly onMessage: (
    event: Electron.Event,
    method: string,
    params: Record<string, unknown>,
  ) => void;
}

const isRecordingInput = Schema.is(DesktopPreviewRecordingInputSchema);

type RecordingInputListener = (event: DesktopPreviewRecordingInputEvent) => Effect.Effect<void>;

type PointerEventListener = (event: DesktopPreviewPointerEvent) => Effect.Effect<void>;

type OpenLinkListener = (event: DesktopPreviewOpenLinkEvent) => Effect.Effect<void>;

// about:blank inherits relaxed guest preferences; external editor schemes must reach the OS handler.
const POPUP_PROTOCOLS = new Set(["http:", "https:"]);

// Main-process loadURL bypasses Chromium's renderer-side restrictions on local and inline URLs.
const IN_PLACE_DENIED_PROTOCOLS = new Set([
  "about:",
  "chrome:",
  "data:",
  "devtools:",
  "file:",
  "filesystem:",
  "javascript:",
  "view-source:",
]);

/** Popups bypass will-attach-webview hardening and would inherit the picker's contextIsolation:false. */
const POPUP_WINDOW_OPTIONS = {
  webPreferences: {
    contextIsolation: true,
    nodeIntegration: false,
    sandbox: true,
  },
} satisfies Electron.BrowserWindowConstructorOptions;

/**
 * OAuth needs a surviving popup opener. `blob:`, app links (behind the session's `openExternal`
 * prompt) and form POSTs stay in place.
 */
export const previewWindowOpenAction = (details: {
  readonly url: string;
  readonly disposition: Electron.HandlerDetails["disposition"];
  readonly postBody?: Electron.PostBody;
}): "popup" | "new-tab" | "navigate" | "deny" => {
  const protocol = URL.parse(details.url)?.protocol;
  // MSAL redirects on a denied blank popup; navigating the tab would destroy that fallback.
  if (protocol === undefined || IN_PLACE_DENIED_PROTOCOLS.has(protocol)) return "deny";
  if (!POPUP_PROTOCOLS.has(protocol)) return "navigate";
  if (details.disposition === "new-window") return "popup";
  return !details.postBody &&
    (details.disposition === "foreground-tab" || details.disposition === "background-tab")
    ? "new-tab"
    : "navigate";
};

const isPreviewRefreshShortcut = (input: Electron.Input, platform: NodeJS.Platform): boolean =>
  input.type === "keyDown" &&
  input.key.toLowerCase() === "r" &&
  (platform === "darwin" ? input.meta && !input.control : input.control && !input.meta) &&
  !input.shift &&
  !input.alt;

export const isPreviewEditingShortcut = (
  input: Electron.Input,
  platform: NodeJS.Platform,
): boolean => {
  const isMac = platform === "darwin";
  if (isMac ? !input.meta || input.control : !input.control || input.meta) return false;

  const key = input.key.toLowerCase();
  // Option changes the DOM key for macOS Paste and Match Style (for example, to ◊).
  if (isMac && input.alt && input.shift && input.code === "KeyV") return true;
  if (key === "v" && input.shift) return input.alt === isMac;
  if (input.alt) return false;
  if (key === "z") return !input.shift || platform !== "win32";
  if (input.shift) return false;
  return (
    key === "a" ||
    key === "c" ||
    key === "v" ||
    key === "x" ||
    (key === "y" && platform === "win32")
  );
};

const isPreviewInputSignal = (value: unknown): value is PreviewInputSignal => {
  if (typeof value !== "object" || value === null || !("kind" in value)) return false;
  if (value.kind === "pointer") {
    return (
      "x" in value &&
      typeof value.x === "number" &&
      "y" in value &&
      typeof value.y === "number" &&
      "button" in value &&
      typeof value.button === "number"
    );
  }
  return (
    value.kind === "key" &&
    "key" in value &&
    typeof value.key === "string" &&
    "code" in value &&
    typeof value.code === "string"
  );
};

const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function* (
  artifactDirectory: string,
  pictureInPicturePreloadPath: string,
) {
  const fileSystem = yield* FileSystem.FileSystem;
  const rendererHistory = yield* DesktopRendererHistory.DesktopRendererHistory;
  const hostPlatform = yield* HostProcess.Platform;
  const path = yield* Path.Path;
  const random = yield* SecureRandom.SecureRandom;
  const parentScope = yield* Scope.Scope;
  const browserHost = yield* DesktopBrowserHost.DesktopBrowserHost;
  const passkeys = yield* PreviewPasskeys.PreviewPasskeys;
  const context = yield* Effect.context<never>();
  const runFork = Effect.runForkWith(context);
  const resolvedArtifactDirectory = path.resolve(artifactDirectory);

  let forwardedShortcuts: ReadonlyArray<PreviewForwardedShortcut> = [];
  const annotationThemeRef = yield* Ref.make(DEFAULT_ANNOTATION_THEME);
  const annotationSendEnabled = new Map<string, boolean>();
  const mainWindowRef = yield* Ref.make<Option.Option<BrowserWindow>>(Option.none());
  const tabsRef = yield* SynchronizedRef.make<ReadonlyMap<string, PreviewTabState>>(new Map());
  const attachedRef = yield* Ref.make<ReadonlyMap<number, ManagedListeners>>(new Map());
  const listenersRef = yield* Ref.make<ReadonlySet<Listener>>(new Set());
  const pointerEventListenersRef = yield* Ref.make<ReadonlySet<PointerEventListener>>(new Set());
  const openLinkListenersRef = yield* Ref.make<ReadonlySet<OpenLinkListener>>(new Set());
  const recordingInputListenersRef = yield* Ref.make<ReadonlySet<RecordingInputListener>>(
    new Set(),
  );
  const pickSessionsRef = yield* Ref.make<ReadonlyMap<string, PickSession>>(new Map());
  const controlSessionsRef = yield* SynchronizedRef.make<
    ReadonlyMap<number, BrowserControlSession>
  >(new Map());
  const frameCaptureSessionsRef = yield* SynchronizedRef.make<
    ReadonlyMap<string, FrameCaptureSession>
  >(new Map());
  const pictureInPictureSessionsRef = yield* SynchronizedRef.make<
    ReadonlyMap<string, PictureInPictureSession>
  >(new Map());
  const pictureInPictureAspectRatiosRef = yield* Ref.make<ReadonlyMap<string, number>>(new Map());
  const pictureInPictureMutationSemaphore = yield* Semaphore.make(1);
  const closingTabIdsRef = yield* Ref.make<ReadonlySet<string>>(new Set());
  // Legacy tab capture is unsupported (electron/electron#44618); recording uses setDisplayMediaRequestHandler.
  let pendingRecording: PendingRecording | null = null;
  const displayMediaHandlerSessions = new WeakSet<Session>();
  let frameCaptureWindowOpen = true;
  let currentMainWindow: BrowserWindow | undefined;
  let mainWindowCleanupFiber: Fiber.Fiber<void, never> | undefined;
  const tabLifecycleLocks = new Map<
    string,
    { readonly semaphore: Semaphore.Semaphore; users: number }
  >();
  const tabLifecycleGenerations = new Map<string, number>();

  const attempt = <A>(errorContext: PreviewOperationContext, evaluate: () => A) =>
    Effect.try({
      try: evaluate,
      catch: (cause) => new PreviewOperationError({ ...errorContext, cause }),
    });
  const attemptPromise = <A>(
    errorContext: PreviewOperationContext,
    evaluate: () => PromiseLike<A>,
  ) =>
    Effect.tryPromise({
      try: evaluate,
      catch: (cause) => new PreviewOperationError({ ...errorContext, cause }),
    });
  const capturePageWithRetry = Effect.fn("PreviewManager.capturePageWithRetry")(function* (
    errorContext: PreviewOperationContext,
    tabId: string,
    wc: Electron.WebContents,
  ) {
    const requireCurrentGuest = Effect.gen(function* () {
      const tabs = yield* SynchronizedRef.get(tabsRef);
      if (wc.isDestroyed() || tabs.get(tabId)?.webContentsId !== wc.id) {
        return yield* new PreviewWebContentsNotFoundError({ tabId, webContentsId: wc.id });
      }
    });
    const capture = Effect.gen(function* () {
      yield* requireCurrentGuest;
      const image = yield* Effect.tryPromise({
        try: (_signal) => wc.capturePage(),
        catch: (cause) => new PreviewOperationError({ ...errorContext, cause }),
      }).pipe(
        Effect.timeout(CAPTURE_PAGE_ATTEMPT_TIMEOUT_MS),
        Effect.catchTags({
          TimeoutError: (cause) =>
            Effect.fail(new PreviewOperationError({ ...errorContext, cause })),
        }),
      );
      yield* requireCurrentGuest;
      return image;
    });
    return yield* capture.pipe(
      Effect.retry({
        times: CAPTURE_PAGE_RETRY_ATTEMPTS - 1,
        schedule: Schedule.spaced(CAPTURE_PAGE_RETRY_DELAY_MS),
        while: isPreviewOperationError,
      }),
    );
  });
  const currentIso = DateTime.now.pipe(Effect.map(DateTime.formatIso));
  const currentMillis = Clock.currentTimeMillis;
  const replaceMap = <K, V>(
    source: ReadonlyMap<K, V>,
    update: (copy: Map<K, V>) => void,
  ): ReadonlyMap<K, V> => {
    const copy = new Map(source);
    update(copy);
    return copy;
  };
  const withTabLifecycleLock = <A, E, R>(
    tabId: string,
    effect: Effect.Effect<A, E, R>,
  ): Effect.Effect<A, E, R> =>
    Effect.suspend(() => {
      const lifecycle = tabLifecycleLocks.get(tabId) ?? {
        semaphore: Semaphore.makeUnsafe(1),
        users: 0,
      };
      lifecycle.users += 1;
      tabLifecycleLocks.set(tabId, lifecycle);
      return lifecycle.semaphore.withPermit(effect).pipe(
        Effect.ensuring(
          Effect.sync(() => {
            lifecycle.users -= 1;
            if (lifecycle.users === 0 && tabLifecycleLocks.get(tabId) === lifecycle) {
              tabLifecycleLocks.delete(tabId);
            }
          }),
        ),
      );
    });
  const setWindowBackgroundThrottling = Effect.fnUntraced(function* (
    window: BrowserWindow,
    enabled: boolean,
  ) {
    if (window.isDestroyed()) return;
    yield* attempt({ operation: "frameCapture.setBackgroundThrottling" }, () =>
      window.webContents.setBackgroundThrottling(enabled),
    );
  });
  const setFrameCaptureBackgroundThrottling = Effect.fnUntraced(function* (enabled: boolean) {
    const mainWindow = yield* Ref.get(mainWindowRef);
    if (Option.isNone(mainWindow)) return;
    yield* setWindowBackgroundThrottling(mainWindow.value, enabled);
  });
  const setFrameCaptureWebContentsBackgroundThrottling = Effect.fnUntraced(function* (
    wc: Electron.WebContents,
    enabled: boolean,
  ) {
    if (wc.isDestroyed()) return;
    yield* attempt(
      {
        operation: "frameCapture.setBackgroundThrottling",
        webContentsId: wc.id,
      },
      () => wc.setBackgroundThrottling(enabled),
    );
  });
  const restoreFrameCaptureWebContentsBackgroundThrottling = Effect.fnUntraced(function* (
    webContentsIds: ReadonlySet<number>,
  ) {
    yield* Effect.forEach(
      webContentsIds,
      (webContentsId) => {
        const wc = webContents.fromId(webContentsId);
        if (!wc || wc.isDestroyed()) return Effect.void;
        return setFrameCaptureWebContentsBackgroundThrottling(wc, true).pipe(
          Effect.retry({ times: 2 }),
          Effect.catch((error) =>
            Effect.logWarning("Failed to restore preview webview frame capture throttling.", {
              webContentsId,
              error,
            }),
          ),
        );
      },
      { concurrency: "unbounded", discard: true },
    );
  });
  const keepFrameCaptureWebContentsUnthrottled = Effect.fnUntraced(function* (
    tabId: string,
    wc: Electron.WebContents,
  ) {
    yield* SynchronizedRef.modifyEffect(frameCaptureSessionsRef, (sessions) => {
      const current = sessions.get(tabId);
      if (!current || current.unthrottledWebContentsIds.has(wc.id)) {
        return Effect.succeed([undefined, sessions] as const);
      }
      return setFrameCaptureWebContentsBackgroundThrottling(wc, false).pipe(
        Effect.tap(() =>
          Effect.gen(function* () {
            if (!current.consumers.has("recording")) return;
            const tab = (yield* SynchronizedRef.get(tabsRef)).get(tabId);
            yield* attempt({ operation: "recording.cursor", tabId, webContentsId: wc.id }, () =>
              wc.send(
                RECORDING_CURSOR_CHANNEL,
                true,
                current.recordingInputOptions,
                tab?.controller,
              ),
            );
          }),
        ),
        Effect.map(
          () =>
            [
              undefined,
              replaceMap(sessions, (copy) => {
                copy.set(tabId, {
                  ...current,
                  unthrottledWebContentsIds: new Set([...current.unthrottledWebContentsIds, wc.id]),
                });
              }),
            ] as const,
        ),
      );
    });
  });
  const stopFrameCapture = Effect.fn("PreviewManager.stopFrameCapture")(function* (
    tabId: string,
    consumer: FrameCaptureConsumer,
  ) {
    yield* SynchronizedRef.modifyEffect(frameCaptureSessionsRef, (sessions) =>
      Effect.gen(function* () {
        const current = sessions.get(tabId);
        if (!current || !current.consumers.has(consumer)) {
          return [undefined, sessions] as const;
        }
        if (consumer === "recording") {
          yield* Effect.forEach(current.unthrottledWebContentsIds, (id) =>
            attempt({ operation: "recording.cursor", tabId, webContentsId: id }, () => {
              const contents = webContents.fromId(id);
              if (contents && !contents.isDestroyed())
                contents.send(RECORDING_CURSOR_CHANNEL, false);
            }).pipe(Effect.ignore),
          );
        }
        const consumers = new Set(current.consumers);
        consumers.delete(consumer);
        if (consumers.size > 0) {
          return [
            consumer === "picture-in-picture" ? current.scope : undefined,
            replaceMap(sessions, (copy) => {
              copy.set(tabId, {
                ...current,
                scope: consumer === "picture-in-picture" ? null : current.scope,
                consumers,
                lastPictureInPictureFingerprint:
                  consumer === "picture-in-picture"
                    ? null
                    : current.lastPictureInPictureFingerprint,
              });
            }),
          ] as const;
        }
        const remainingSessions = replaceMap(sessions, (copy) => {
          copy.delete(tabId);
        });
        yield* restoreFrameCaptureWebContentsBackgroundThrottling(
          current.unthrottledWebContentsIds,
        );
        if (remainingSessions.size === 0) {
          yield* setFrameCaptureBackgroundThrottling(true).pipe(
            Effect.retry({ times: 2 }),
            Effect.catch((error) =>
              Effect.logWarning("Failed to restore preview frame capture throttling.", { error }),
            ),
          );
        }
        return [current.scope, remainingSessions] as const;
      }),
    ).pipe(
      Effect.flatMap((captureScope) =>
        captureScope ? Scope.close(captureScope, Exit.void).pipe(Effect.ignore) : Effect.void,
      ),
      Effect.uninterruptible,
    );
  });

  const stopAllRecordings = Effect.fn("PreviewManager.stopAllRecordings")(function* () {
    pendingRecording = null;
    const sessions = yield* SynchronizedRef.get(frameCaptureSessionsRef);
    yield* Effect.forEach(sessions.keys(), (tabId) => stopFrameCapture(tabId, "recording"), {
      concurrency: "unbounded",
      discard: true,
    });
  });

  const deliverEvent = (
    eventKind: "state-change" | "recording-input" | "pointer-event" | "open-link",
    tabId: string,
    delivery: () => Effect.Effect<void>,
  ) =>
    Effect.suspend(delivery).pipe(
      Effect.catchCauseIf(
        (cause) => !Cause.hasInterrupts(cause),
        (cause) =>
          Effect.logWarning("Desktop preview event listener failed.", {
            eventKind,
            tabId,
            cause,
          }),
      ),
    );

  const emit = Effect.fn("PreviewManager.emit")(function* (tabId: string, state: PreviewTabState) {
    const listeners = yield* Ref.get(listenersRef);
    yield* Effect.forEach(
      listeners,
      (listener) => deliverEvent("state-change", tabId, () => listener(tabId, state)),
      { discard: true },
    );
  });

  const emitIfCurrent = Effect.fn("PreviewManager.emitIfCurrent")(function* (
    tabId: string,
    state: PreviewTabState,
  ) {
    if ((yield* SynchronizedRef.get(tabsRef)).get(tabId) === state) {
      yield* emit(tabId, state);
    }
  });

  const update = Effect.fn("PreviewManager.update")(function* (
    tabId: string,
    patch: Partial<PreviewTabState>,
    humanPoint?: { readonly x: number; readonly y: number },
  ) {
    const updatedAt = yield* currentIso;
    const next = yield* SynchronizedRef.modify(tabsRef, (tabs) => {
      const current = tabs.get(tabId);
      if (!current) return [Option.none<PreviewTabState>(), tabs] as const;
      const state: PreviewTabState = { ...current, ...patch, updatedAt };
      return [
        Option.some(state),
        replaceMap(tabs, (copy) => {
          copy.set(tabId, state);
        }),
      ] as const;
    });
    // syncTabAudible can commit after this update; emitIfCurrent prevents publishing a stale snapshot.
    if (Option.isSome(next)) {
      if (patch.controller !== undefined && next.value.webContentsId != null) {
        const capture = (yield* SynchronizedRef.get(frameCaptureSessionsRef)).get(tabId);
        const webContentsId = next.value.webContentsId;
        if (capture?.consumers.has("recording")) {
          yield* attempt({ operation: "recording.controller", tabId }, () => {
            const contents = webContents.fromId(webContentsId);
            if (contents && !contents.isDestroyed())
              contents.send(RECORDING_CONTROLLER_CHANNEL, patch.controller, humanPoint);
          }).pipe(Effect.ignore);
        }
      }
      yield* emitIfCurrent(tabId, next.value);
    }
  });

  /** Read zoom after awaits so concurrent zoom actions cannot be rolled back by an older snapshot. */
  const assertTabZoom = Effect.fn("PreviewManager.assertTabZoom")(function* (tabId: string) {
    const tab = (yield* SynchronizedRef.get(tabsRef)).get(tabId);
    if (!tab || tab.webContentsId == null) return;
    const wc = webContents.fromId(tab.webContentsId);
    if (!wc || wc.isDestroyed()) return;
    yield* attempt({ operation: "assertTabZoom", tabId, webContentsId: wc.id }, () =>
      wc.setZoomFactor(tab.zoomFactor),
    ).pipe(Effect.ignore);
  });

  /** Read committed mute and current guest at call time so stale snapshots cannot roll back newer actions. */
  const assertTabAudioMuted = Effect.fn("PreviewManager.assertTabAudioMuted")(function* (
    tabId: string,
  ) {
    const tab = (yield* SynchronizedRef.get(tabsRef)).get(tabId);
    if (!tab || tab.webContentsId == null) return;
    const wc = webContents.fromId(tab.webContentsId);
    if (!wc || wc.isDestroyed()) return;
    yield* attempt({ operation: "assertTabAudioMuted", tabId, webContentsId: wc.id }, () =>
      wc.setAudioMuted(tab.audioMuted),
    );
  });

  const syncTabAudible = Effect.fn("PreviewManager.syncTabAudible")(function* (
    tabId: string,
    wc: Electron.WebContents,
    audible: boolean,
  ) {
    if (wc.isDestroyed()) return;
    const updatedAt = yield* currentIso;
    const next = yield* SynchronizedRef.modify(tabsRef, (tabs) => {
      const current = tabs.get(tabId);
      if (
        !current ||
        current.webContentsId !== wc.id ||
        webContents.fromId(wc.id) !== wc ||
        current.audible === audible
      ) {
        return [Option.none<PreviewTabState>(), tabs] as const;
      }
      const state: PreviewTabState = { ...current, audible, updatedAt };
      return [
        Option.some(state),
        replaceMap(tabs, (copy) => {
          copy.set(tabId, state);
        }),
      ] as const;
    });
    if (Option.isSome(next)) yield* emitIfCurrent(tabId, next.value);
  });

  const requireWebContents = Effect.fn("PreviewManager.requireWebContents")(function* (
    tabId: string,
  ) {
    const tabs = yield* SynchronizedRef.get(tabsRef);
    const tab = tabs.get(tabId);
    if (!tab) {
      return yield* new PreviewTabNotFoundError({ tabId });
    }
    if (tab.webContentsId == null) {
      return yield* new PreviewWebviewNotInitializedError({ tabId });
    }
    const wc = webContents.fromId(tab.webContentsId);
    if (!wc) {
      return yield* new PreviewWebContentsNotFoundError({
        tabId,
        webContentsId: tab.webContentsId,
      });
    }
    return wc;
  });

  const resolveArtifactPath = (artifactPath: string) =>
    attempt({ operation: "resolveArtifactPath", artifactPath }, () => {
      const resolvedPath = path.resolve(artifactPath);
      const relativePath = path.relative(resolvedArtifactDirectory, resolvedPath);
      if (
        relativePath.length === 0 ||
        relativePath === ".." ||
        relativePath.startsWith(`..${path.sep}`) ||
        path.isAbsolute(relativePath)
      ) {
        return null;
      }
      return resolvedPath;
    }).pipe(
      Effect.filterOrFail(
        (resolvedPath) => resolvedPath !== null,
        () =>
          new PreviewArtifactPathOutsideDirectoryError({
            artifactPath,
            artifactDirectory: resolvedArtifactDirectory,
          }),
      ),
    );

  const tabIdForWebContents = Effect.fnUntraced(function* (webContentsId: number) {
    const tabs = yield* SynchronizedRef.get(tabsRef);
    return (
      Array.from(tabs.entries()).find(([, tab]) => tab.webContentsId === webContentsId)?.[0] ?? null
    );
  });

  const detachControlSession = Effect.fn("PreviewManager.detachControlSession")(function* (
    webContentsId: number,
    closedServerTab?: PreviewTabState["serverTab"],
  ) {
    const control = yield* SynchronizedRef.modify(controlSessionsRef, (sessions) => [
      sessions.get(webContentsId),
      replaceMap(sessions, (copy) => {
        copy.delete(webContentsId);
      }),
    ]);
    if (control) yield* releaseControlSession(control, closedServerTab);
  });

  // Closes a session already removed from `controlSessionsRef`. The server can
  // only drive a tab while the desktop holds its debugger.
  const releaseControlSession = Effect.fnUntraced(function* (
    control: BrowserControlSession,
    closedServerTab?: PreviewTabState["serverTab"],
  ) {
    if (closedServerTab) browserHost.detach(closedServerTab);
    for (const tab of (yield* SynchronizedRef.get(tabsRef)).values()) {
      if (tab.webContentsId === control.webContentsId && tab.serverTab) {
        browserHost.detach(tab.serverTab);
      }
    }
    yield* Scope.close(control.scope, Exit.void).pipe(Effect.ignore);
  });

  const ensureControlSession = Effect.fn("PreviewManager.ensureControlSession")(function* (
    wc: Electron.WebContents,
  ) {
    return yield* SynchronizedRef.modifyEffect(
      controlSessionsRef,
      (
        sessions,
      ): Effect.Effect<
        readonly [BrowserControlSession, ReadonlyMap<number, BrowserControlSession>],
        PreviewManagerError
      > => {
        const existing = sessions.get(wc.id);
        if (existing) return Effect.succeed([existing, sessions] as const);
        if (wc.isDestroyed()) {
          return Effect.fail(
            new PreviewOperationError({
              operation: "ensureControlSession",
              webContentsId: wc.id,
              cause: new Error("WebContents was destroyed"),
            }),
          );
        }
        if (wc.isDevToolsOpened()) {
          return Effect.fail(
            new PreviewAutomationDevToolsOpenError({
              webContentsId: wc.id,
            }),
          );
        }
        if (wc.debugger.isAttached()) {
          return Effect.fail(
            new PreviewAutomationDebuggerAttachedError({
              webContentsId: wc.id,
            }),
          );
        }
        const createControlSession = Effect.fn("PreviewManager.createControlSession")(function* () {
          const semaphore = yield* Semaphore.make(1);
          const scope = yield* Scope.fork(parentScope, "sequential");
          const wcDebugger = wc.debugger;
          const consoleReleases = yield* Queue.sliding<void>(1);
          // Console eviction leaves strong debugger handles; release the group because we keep only text.
          yield* Effect.forkIn(
            Effect.forever(
              Queue.take(consoleReleases).pipe(
                Effect.andThen(
                  attemptPromise({ operation: "releaseConsoleObjects", webContentsId: wc.id }, () =>
                    wcDebugger.sendCommand("Runtime.releaseObjectGroup", {
                      objectGroup: "console",
                    }),
                  ).pipe(Effect.ignore),
                ),
              ),
            ),
            scope,
          );
          const handleDebuggerMessage = Effect.fnUntraced(function* (
            method: string,
            params: Record<string, unknown>,
          ) {
            if (method === "Page.screencastFrame") {
              const sessionId = params["sessionId"];
              if (typeof sessionId === "number") {
                yield* attemptPromise(
                  {
                    operation: "ackScreencastFrame",
                    webContentsId: wc.id,
                  },
                  () => wcDebugger.sendCommand("Page.screencastFrameAck", { sessionId }),
                ).pipe(Effect.ignore);
              }
            }
            if (method === "Runtime.consoleAPICalled" || method === "Runtime.exceptionThrown") {
              yield* Queue.offer(consoleReleases, undefined);
            }
          });
          const onMessage: BrowserControlSession["onMessage"] = (_event, method, params) => {
            runFork(handleDebuggerMessage(method, params));
          };
          const control: BrowserControlSession = {
            webContentsId: wc.id,
            debugger: wcDebugger,
            semaphore,
            scope,
            onMessage,
          };
          // Electron emits `detach` when Chromium closes the debugger session on its
          // own. The cached session would then fail every command until the webview
          // is replaced.
          let dropped = false;
          const onDetach = () => {
            dropped = true;
            runFork(recoverDetachedControlSession(wc, control));
          };
          // The listener comes off before detach() so a detach this manager requested
          // never looks like a dropped one. A dropped session has nothing left to
          // detach: `wc.debugger` is shared, so detaching here would hit a successor.
          yield* Scope.addFinalizer(
            scope,
            attempt({ operation: "detachControlSession", webContentsId: wc.id }, () => {
              wcDebugger.off("message", onMessage);
              wcDebugger.off("detach", onDetach);
              if (!dropped && wcDebugger.isAttached()) wcDebugger.detach();
            }).pipe(Effect.ignore),
          );
          const initialize = Effect.fn("PreviewManager.initializeControlSession")(function* () {
            yield* attempt({ operation: "attachDebuggerListeners", webContentsId: wc.id }, () => {
              wcDebugger.on("message", onMessage);
              wcDebugger.on("detach", onDetach);
              wcDebugger.attach("1.3");
            });
            // Set an opaque base before first paint or background-less dark pages retain white-on-white text.
            yield* attemptPromise(
              { operation: "initializeDebugger.defaultBackground", webContentsId: wc.id },
              () =>
                wcDebugger.sendCommand("Emulation.setDefaultBackgroundColorOverride", {
                  color: { r: 255, g: 255, b: 255, a: 1 },
                }),
            );
            return [
              control,
              replaceMap(sessions, (copy) => {
                copy.set(wc.id, control);
              }),
            ] as const;
          });
          return yield* initialize().pipe(
            Effect.onError(() => Scope.close(scope, Exit.void).pipe(Effect.ignore)),
          );
        });
        return createControlSession();
      },
    );
  });

  const cancelPickElement = Effect.fn("PreviewManager.cancelPickElement")(function* (
    tabId: string,
  ) {
    const session = (yield* Ref.get(pickSessionsRef)).get(tabId);
    if (session) yield* session.cancel;
  });

  const detachListeners = Effect.fn("PreviewManager.detachListeners")(function* (
    webContentsId: number,
  ) {
    const managed = yield* Ref.modify(attachedRef, (attached) => [
      attached.get(webContentsId),
      replaceMap(attached, (copy) => {
        copy.delete(webContentsId);
      }),
    ]);
    if (managed) {
      managed.cancelFaviconCapture();
      yield* Scope.close(managed.scope, Exit.void).pipe(Effect.ignore);
    }
  });

  const computeNavStatus = (wc: Electron.WebContents): PreviewNavStatus => {
    const url = wc.getURL();
    const title = wc.getTitle();
    if (url === "" || url === "about:blank") return { kind: "Idle" };
    // isLoading() includes late iframes whose completion may never clear the tab's loading bar.
    if (wc.isLoadingMainFrame()) return { kind: "Loading", url, title };
    return { kind: "Success", url, title };
  };

  const attachListeners = Effect.fn("PreviewManager.attachListeners")(function* (
    tabId: string,
    wc: Electron.WebContents,
  ) {
    const scope = yield* Scope.fork(parentScope, "sequential");
    const attachmentId = Symbol();
    let detachPasskeys = () => {};
    let documentId = 0;
    let nextRequestId = 0;
    let activeCapture: {
      readonly controller: AbortController;
      readonly documentId: number;
      readonly eventKey: string;
      readonly requestId: number;
    } | null = null;
    const cancelFaviconCapture = () => {
      documentId += 1;
      activeCapture?.controller.abort();
      activeCapture = null;
    };
    const syncState = Effect.fn("PreviewManager.syncWebContentsState")(function* (
      preserveLoadFailure: boolean,
      confirmedNavigation = false,
    ) {
      if (wc.isDestroyed()) return;
      const computedNavStatus = computeNavStatus(wc);
      const canGoBack = wc.navigationHistory.canGoBack();
      const canGoForward = wc.navigationHistory.canGoForward();
      const updatedAt = yield* currentIso;
      const next = yield* SynchronizedRef.modify(tabsRef, (tabs) => {
        const current = tabs.get(tabId);
        if (!current || current.webContentsId !== wc.id || webContents.fromId(wc.id) !== wc) {
          return [Option.none<PreviewTabState>(), tabs] as const;
        }
        // did-stop-loading follows did-fail-load without proving successful navigation.
        const navStatus =
          preserveLoadFailure &&
          current.navStatus.kind === "LoadFailed" &&
          computedNavStatus.kind === "Success"
            ? current.navStatus
            : computedNavStatus;
        const clearFavicon =
          confirmedNavigation &&
          current.favicon !== undefined &&
          safeHttpOrigin(current.favicon.pageUrl) !==
            safeHttpOrigin(navStatus.kind === "Idle" ? wc.getURL() : navStatus.url);
        const { favicon: _favicon, ...currentWithoutFavicon } = current;
        const state: PreviewTabState = {
          ...(clearFavicon ? currentWithoutFavicon : current),
          navStatus,
          canGoBack,
          canGoForward,
          // Guest zoom inherits app zoom; mirroring it would overwrite the tab's own setting.
          updatedAt,
        };
        return [
          Option.some(state),
          replaceMap(tabs, (copy) => {
            copy.set(tabId, state);
          }),
        ] as const;
      });
      if (Option.isSome(next)) yield* emitIfCurrent(tabId, next.value);
    });
    const sync = () => runFork(syncState(true));
    const syncNavigation = () => runFork(syncState(false, true));
    const syncInPageNavigation = () => runFork(syncState(false));
    const restoreRecordingCursor = () =>
      runFork(
        Effect.gen(function* () {
          const session = (yield* SynchronizedRef.get(frameCaptureSessionsRef)).get(tabId);
          if (!wc.isDestroyed()) {
            const tab = (yield* SynchronizedRef.get(tabsRef)).get(tabId);
            wc.send(
              RECORDING_CURSOR_CHANNEL,
              session?.consumers.has("recording") ?? false,
              session?.recordingInputOptions,
              tab?.controller,
            );
          }
        }),
      );
    const navigationStarted = (
      event: Electron.Event<Electron.WebContentsDidStartNavigationEventParams>,
    ) => {
      if (event.isMainFrame && !event.isSameDocument) cancelFaviconCapture();
    };
    const audioStateChanged = (
      event: Electron.Event<Electron.WebContentsAudioStateChangedEventParams>,
    ) => runFork(syncTabAudible(tabId, wc, event.audible));
    const publishFavicon = Effect.fn("PreviewManager.publishFavicon")(function* (input: {
      readonly captureDocumentId: number;
      readonly dataUrl: string;
      readonly pageUrl: string;
      readonly requestId: number;
    }) {
      const pageOrigin = safeHttpOrigin(input.pageUrl);
      const managed = (yield* Ref.get(attachedRef)).get(wc.id);
      if (
        !pageOrigin ||
        wc.isDestroyed() ||
        webContents.fromId(wc.id) !== wc ||
        managed?.attachmentId !== attachmentId ||
        activeCapture?.documentId !== input.captureDocumentId ||
        activeCapture.requestId !== input.requestId ||
        safeHttpOrigin(wc.getURL()) !== pageOrigin
      ) {
        return;
      }
      const capturedAt = yield* currentMillis;
      const updatedAt = yield* currentIso;
      const next = yield* SynchronizedRef.modify(tabsRef, (tabs) => {
        const current = tabs.get(tabId);
        if (
          !current ||
          current.webContentsId !== wc.id ||
          webContents.fromId(wc.id) !== wc ||
          activeCapture?.documentId !== input.captureDocumentId ||
          activeCapture.requestId !== input.requestId
        ) {
          return [Option.none<PreviewTabState>(), tabs] as const;
        }
        const state: PreviewTabState = {
          ...current,
          favicon: { dataUrl: input.dataUrl, pageUrl: pageOrigin, capturedAt },
          updatedAt,
        };
        return [
          Option.some(state),
          replaceMap(tabs, (copy) => {
            copy.set(tabId, state);
          }),
        ] as const;
      });
      if (Option.isSome(next)) yield* emitIfCurrent(tabId, next.value);
    });
    const faviconUpdated = (_event: Event, rawCandidates: ReadonlyArray<string>): void => {
      const pageUrl = wc.getURL();
      if (!safeHttpOrigin(pageUrl)) return;
      const candidates = selectFaviconCandidates(rawCandidates);
      if (candidates.length === 0) return;
      const eventKey = JSON.stringify([pageUrl, ...candidates]);
      if (activeCapture?.eventKey === eventKey) return;
      activeCapture?.controller.abort();
      const captureDocumentId = documentId;
      const requestId = ++nextRequestId;
      const controller = new AbortController();
      activeCapture = { controller, documentId: captureDocumentId, eventKey, requestId };
      runFork(
        Effect.tryPromise({
          try: () =>
            captureFavicon({ webContents: wc, pageUrl, candidates, signal: controller.signal }),
          catch: (cause) =>
            new PreviewOperationError({
              operation: "captureFavicon",
              tabId,
              webContentsId: wc.id,
              cause,
            }),
        }).pipe(
          Effect.flatMap((result) =>
            result.kind === "captured"
              ? publishFavicon({
                  captureDocumentId,
                  dataUrl: result.dataUrl,
                  pageUrl,
                  requestId,
                })
              : Effect.void,
          ),
          Effect.catch((error) =>
            controller.signal.aborted
              ? Effect.void
              : Effect.logDebug("Favicon capture failed.", { error, tabId, webContentsId: wc.id }),
          ),
          Effect.ensuring(
            Effect.sync(() => {
              if (activeCapture?.requestId === requestId) activeCapture = null;
            }),
          ),
        ),
      );
    };
    const failed = (
      _event: Event,
      code: number,
      description: string,
      validatedUrl: string,
      isMainFrame: boolean,
    ): void => {
      if (code === -3 || !isMainFrame) return;
      runFork(
        update(tabId, {
          navStatus: {
            kind: "LoadFailed",
            url: validatedUrl || wc.getURL(),
            title: wc.getTitle(),
            code,
            description,
          },
        }),
      );
    };
    const handleHumanInput = Effect.fn("PreviewManager.handleHumanInput")(function* (
      rawSignal?: unknown,
    ) {
      yield* update(
        tabId,
        { controller: "human" },
        isPreviewInputSignal(rawSignal) && rawSignal.kind === "pointer"
          ? { x: rawSignal.x, y: rawSignal.y }
          : undefined,
      );
      yield* Effect.sleep(750);
      const tabs = yield* SynchronizedRef.get(tabsRef);
      if (tabs.get(tabId)?.controller === "human") {
        yield* update(tabId, { controller: "none" });
      }
    });
    const recordingInput = (_event: unknown, input: unknown) => {
      if (!isRecordingInput(input)) return;
      return runFork(
        Effect.gen(function* () {
          const tab = (yield* SynchronizedRef.get(tabsRef)).get(tabId);
          const capture = (yield* SynchronizedRef.get(frameCaptureSessionsRef)).get(tabId);
          if (tab?.webContentsId !== wc.id || !capture?.consumers.has("recording")) return;
          if (input.type === "key" && !capture.recordingInputOptions?.showKeyPresses) return;
          if (input.type === "pointer" && !capture.recordingInputOptions?.showMousePresses) return;
          const listeners = yield* Ref.get(recordingInputListenersRef);
          yield* Effect.forEach(
            listeners,
            (listener) => deliverEvent("recording-input", tabId, () => listener({ tabId, input })),
            { discard: true },
          );
        }),
      );
    };
    const humanInput = (_event: unknown, rawSignal?: unknown): void => {
      runFork(handleHumanInput(rawSignal));
    };
    const mouseNavigate = (_event: unknown, payload?: unknown): void => {
      const direction =
        typeof payload === "object" && payload !== null && "direction" in payload
          ? (payload as { direction?: unknown }).direction
          : undefined;
      if (direction !== "back" && direction !== "forward") return;
      runFork(
        attempt({ operation: "mouseNavigate", tabId, webContentsId: wc.id }, () => {
          if (direction === "back") {
            if (wc.navigationHistory.canGoBack()) wc.navigationHistory.goBack();
          } else if (wc.navigationHistory.canGoForward()) {
            wc.navigationHistory.goForward();
          }
        }).pipe(Effect.ignore),
      );
    };
    // Every guest of a focused window reports focus; GuestInput handles guests without a focused frame.
    const holdsKeyboardFocus = (contents: Electron.WebContents) =>
      contents.isFocused() && contents.focusedFrame !== null;
    const syncMenuShortcuts = (contents: Electron.WebContents, input: Electron.Input): void => {
      if (input.type !== "keyDown") return;
      contents.setIgnoreMenuShortcuts(
        !isPreviewEditingShortcut(input, hostPlatform) || !holdsKeyboardFocus(contents),
      );
    };
    // Popups inherit Electron's unrestricted window handler; block nested popups to bound the chain.
    const windowCreated = (window: Electron.BrowserWindow): void => {
      window.webContents.setIgnoreMenuShortcuts(true);
      window.webContents.setWindowOpenHandler(() => ({ action: "deny" }));
      window.webContents.on("before-input-event", (_event, input) => {
        syncMenuShortcuts(window.webContents, input);
      });
    };
    const beforeInput = (event: Electron.Event, input: Electron.Input): void => {
      syncMenuShortcuts(wc, input);
      const host = wc.hostWebContents;
      const forwarded =
        input.type === "keyDown" &&
        !input.isComposing &&
        host &&
        !host.isDestroyed() &&
        holdsKeyboardFocus(wc) &&
        !(
          hostPlatform !== "darwin" &&
          input.control &&
          input.alt &&
          /^(?:[^a-zA-Z0-9]|Dead)$/u.test(input.key)
        ) &&
        forwardedShortcuts.find(({ shortcut }) =>
          matchesKeybindingShortcut(
            {
              key: input.key,
              code: input.code,
              metaKey: input.meta,
              ctrlKey: input.control,
              shiftKey: input.shift,
              altKey: input.alt,
            },
            shortcut,
            hostPlatform === "darwin" ? "MacIntel" : hostPlatform,
          ),
        );
      if (forwarded && host) {
        event.preventDefault();
        if (!input.isAutoRepeat) {
          if (
            forwarded.command === "workspace.focusNext" ||
            forwarded.command === "workspace.focusPrevious" ||
            forwarded.command === "preview.focusUrl"
          ) {
            // DOM focus in the renderer cannot by itself release the guest's native keyboard focus.
            host.focus();
          }
          host.send(MENU_ACTION_CHANNEL, forwarded.command);
        }
        return;
      }
      if (isPreviewRefreshShortcut(input, hostPlatform)) {
        event.preventDefault();
        runFork(
          attempt({ operation: "shortcut.refresh", tabId, webContentsId: wc.id }, () =>
            wc.reload(),
          ).pipe(Effect.ignore),
        );
        return;
      }
    };
    yield* Scope.addFinalizer(
      scope,
      attempt({ operation: "detachListeners", tabId, webContentsId: wc.id }, () => {
        cancelFaviconCapture();
        wc.off("did-start-navigation", navigationStarted);
        wc.off("did-navigate", syncNavigation);
        wc.off("did-navigate-in-page", syncInPageNavigation);
        wc.off("page-title-updated", sync);
        wc.off("page-favicon-updated", faviconUpdated as never);
        wc.off("did-start-loading", sync);
        wc.off("did-stop-loading", sync);
        wc.off("dom-ready", restoreRecordingCursor);
        wc.off("did-fail-load", failed as never);
        wc.off("audio-state-changed", audioStateChanged);
        wc.off("did-create-window", windowCreated);
        wc.off("before-input-event", beforeInput);
        wc.ipc.off(HUMAN_INPUT_CHANNEL, humanInput);
        wc.ipc.off(RECORDING_INPUT_CHANNEL, recordingInput);
        wc.ipc.off(MOUSE_NAVIGATE_CHANNEL, mouseNavigate);
        detachPasskeys();
      }).pipe(Effect.ignore),
    );
    const install = Effect.fn("PreviewManager.installWebContentsListeners")(function* () {
      yield* attempt({ operation: "attachListeners", tabId, webContentsId: wc.id }, () => {
        wc.setIgnoreMenuShortcuts(true);
        wc.on("did-start-navigation", navigationStarted);
        wc.on("did-navigate", syncNavigation);
        wc.on("did-navigate-in-page", syncInPageNavigation);
        wc.on("page-title-updated", sync);
        wc.on("page-favicon-updated", faviconUpdated as never);
        wc.on("did-start-loading", sync);
        wc.on("did-stop-loading", sync);
        wc.on("dom-ready", restoreRecordingCursor);
        wc.on("did-fail-load", failed as never);
        wc.on("audio-state-changed", audioStateChanged);
        wc.ipc.on(HUMAN_INPUT_CHANNEL, humanInput);
        wc.ipc.on(RECORDING_INPUT_CHANNEL, recordingInput);
        wc.ipc.on(MOUSE_NAVIGATE_CHANNEL, mouseNavigate);
        detachPasskeys = passkeys.attachGuest(wc);
        wc.setWindowOpenHandler((details) => {
          const action = previewWindowOpenAction(details);
          if (action === "popup") {
            return { action: "allow", overrideBrowserWindowOptions: POPUP_WINDOW_OPTIONS };
          }
          if (action === "deny") return { action: "deny" };
          if (action === "new-tab") {
            runFork(
              emitOpenLink({
                tabId,
                url: details.url,
                background: details.disposition === "background-tab",
              }),
            );
            return { action: "deny" };
          }
          runFork(
            attemptPromise({ operation: "openPreviewWindow", tabId, webContentsId: wc.id }, () =>
              wc.loadURL(details.url),
            ).pipe(Effect.ignore),
          );
          return { action: "deny" };
        });
        wc.on("did-create-window", windowCreated);
        wc.on("before-input-event", beforeInput);
      });
      yield* Ref.update(attachedRef, (attached) =>
        replaceMap(attached, (copy) => {
          copy.set(wc.id, { attachmentId, cancelFaviconCapture, scope, webContents: wc });
        }),
      );
    });
    yield* install().pipe(Effect.onError(() => Scope.close(scope, Exit.void).pipe(Effect.ignore)));
  });

  const setMainWindow = Effect.fn("PreviewManager.setMainWindow")(function* (
    window: BrowserWindow,
  ) {
    if (mainWindowCleanupFiber) {
      yield* Fiber.join(mainWindowCleanupFiber);
      mainWindowCleanupFiber = undefined;
    }
    yield* SynchronizedRef.modifyEffect(frameCaptureSessionsRef, (sessions) =>
      Effect.gen(function* () {
        // Cleanup or lock acquisition can outlive the replacement window.
        if (window.isDestroyed()) return [undefined, sessions] as const;
        if (sessions.size > 0) {
          yield* setWindowBackgroundThrottling(window, false);
        }
        yield* Ref.set(mainWindowRef, Option.some(window));
        currentMainWindow = window;
        frameCaptureWindowOpen = true;
        window.once("closed", () => {
          if (currentMainWindow !== window) return;
          currentMainWindow = undefined;
          frameCaptureWindowOpen = false;
          mainWindowCleanupFiber = runFork(
            Effect.all([closeAllPictureInPicture(), stopAllRecordings()], {
              concurrency: "unbounded",
              discard: true,
            }).pipe(Effect.ignore),
          );
        });
        return [undefined, sessions] as const;
      }),
    ).pipe(Effect.uninterruptible);
  });

  const createTabUnlocked = Effect.fn("PreviewManager.createTabUnlocked")(function* (
    tabId: string,
    defaults?: DesktopPreviewTabDefaults,
  ) {
    const updatedAt = yield* currentIso;
    const result = yield* SynchronizedRef.modify(
      tabsRef,
      (
        tabs,
      ): readonly [
        { readonly state: PreviewTabState; readonly created: boolean },
        ReadonlyMap<string, PreviewTabState>,
      ] => {
        const existing = tabs.get(tabId);
        if (existing) return [{ state: existing, created: false }, tabs] as const;
        const initial: PreviewTabState = {
          tabId,
          webContentsId: null,
          navStatus: { kind: "Idle" },
          canGoBack: false,
          canGoForward: false,
          zoomFactor: normalizeZoomFactor(defaults?.zoomFactor),
          pictureInPicture: false,
          colorScheme: defaults?.colorScheme ?? "system",
          ...(defaults?.serverTab === undefined ? {} : { serverTab: defaults.serverTab }),
          audioMuted: false,
          audible: false,
          controller: "none",
          capturing: false,
          updatedAt,
        };
        return [
          { state: initial, created: true },
          replaceMap(tabs, (copy) => {
            copy.set(tabId, initial);
          }),
        ] as const;
      },
    );
    if (result.created) {
      tabLifecycleGenerations.set(tabId, (tabLifecycleGenerations.get(tabId) ?? 0) + 1);
    }
    yield* emit(tabId, result.state);
    return result.state;
  });

  const createTab = Effect.fn("PreviewManager.createTab")(function* (
    tabId: string,
    defaults?: DesktopPreviewTabDefaults,
  ) {
    return yield* withTabLifecycleLock(tabId, createTabUnlocked(tabId, defaults));
  });

  const closeTabUnlocked = Effect.fn("PreviewManager.closeTabUnlocked")(function* (tabId: string) {
    if (!(yield* SynchronizedRef.get(tabsRef)).has(tabId)) return;
    clearPendingRecording(tabId);
    annotationSendEnabled.delete(tabId);
    yield* Effect.all(
      [
        cancelPickElement(tabId),
        closePictureInPicture(tabId),
        stopFrameCapture(tabId, "recording"),
      ],
      {
        concurrency: 3,
        discard: true,
      },
    );
    const tab = yield* SynchronizedRef.modify(tabsRef, (tabs) => {
      const current = tabs.get(tabId);
      if (!current) return [Option.none<PreviewTabState>(), tabs] as const;
      return [
        Option.some(current),
        replaceMap(tabs, (copy) => {
          copy.delete(tabId);
        }),
      ] as const;
    });
    if (Option.isNone(tab)) return;
    const closedTab = tab.value;
    if (closedTab.serverTab) browserHost.setShown(closedTab.serverTab, undefined);
    if (closedTab.webContentsId != null) {
      yield* Effect.all(
        [
          detachControlSession(closedTab.webContentsId, closedTab.serverTab),
          detachListeners(closedTab.webContentsId),
        ],
        { concurrency: 2, discard: true },
      );
    }
    const updatedAt = yield* currentIso;
    const closed: PreviewTabState = {
      ...closedTab,
      webContentsId: null,
      navStatus: { kind: "Idle" },
      canGoBack: false,
      canGoForward: false,
      zoomFactor: DEFAULT_ZOOM_FACTOR,
      pictureInPicture: false,
      colorScheme: "system",
      audioMuted: false,
      audible: false,
      controller: "none",
      capturing: false,
      updatedAt,
    };
    yield* emit(tabId, closed);
  });

  const closeTab = Effect.fn("PreviewManager.closeTab")(function* (tabId: string) {
    const claimed = yield* Ref.modify(closingTabIdsRef, (closingTabIds) => {
      if (closingTabIds.has(tabId)) return [false, closingTabIds] as const;
      return [true, new Set([...closingTabIds, tabId])] as const;
    });
    if (!claimed) return;
    return yield* withTabLifecycleLock(tabId, closeTabUnlocked(tabId)).pipe(
      Effect.ensuring(
        Ref.update(closingTabIdsRef, (closingTabIds) => {
          if (!closingTabIds.has(tabId)) return closingTabIds;
          const next = new Set(closingTabIds);
          next.delete(tabId);
          return next;
        }),
      ),
    );
  });

  const registerWebviewUnlocked = Effect.fn("PreviewManager.registerWebviewUnlocked")(function* (
    tabId: string,
    webContentsId: number,
    expectedGeneration: number | undefined,
  ) {
    const tab = (yield* SynchronizedRef.get(tabsRef)).get(tabId);
    if (
      !tab ||
      tabLifecycleGenerations.get(tabId) !== expectedGeneration ||
      (yield* Ref.get(closingTabIdsRef)).has(tabId)
    ) {
      return yield* new PreviewTabNotFoundError({ tabId });
    }
    const wc = webContents.fromId(webContentsId);
    const mainWindow = yield* Ref.get(mainWindowRef);
    if (
      !wc ||
      wc.isDestroyed() ||