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() ||