Skip to content

Record your screen, ship a demo. Free and open-source, GPU-accelerated, no watermarks, no subscriptions. Windows, macOS, Linux. Actively maintained.

36.6 KB
Raw Blame
import path from "node:path";
import { fileURLToPath, pathToFileURL } from "node:url";
import { app, BrowserWindow, ipcMain, screen } from "electron";
import {
	fitEditorRect,
	loadEditorWindowState,
	resolveEditorCreation,
	saveEditorWindowState,
	shouldTrackEditorWindow,
	WAYLAND_MAXIMIZE_SETTLE_MS,
} from "./editorWindowState";
import {
	clampHudBoundsToWorkArea,
	HUD_WINDOW_MIN,
	type HudContentRect,
	hudBarAnchor,
	hudContentScreenRect,
	hudDragDestination,
	hudResizeBounds,
	parseHudContentRect,
	sameRect,
} from "./hudWindowBounds";
import { keepAlwaysOnTop, reassertAlwaysOnTop } from "./keepOnTop";
import { followAcrossSpaces } from "./macSpaces";
import { markSheetless } from "./messageBox";
import { usesWaylandBackend } from "./wayland";

const __dirname = path.dirname(fileURLToPath(import.meta.url));

const APP_ROOT = path.join(__dirname, "..");
const VITE_DEV_SERVER_URL = process.env["VITE_DEV_SERVER_URL"];
const RENDERER_DIST = path.join(APP_ROOT, "dist");
const HEADLESS = process.env["HEADLESS"] === "true";

// The HUD and Notes windows are excluded from every screen/window capture (WGC on Windows uses
// the same SetWindowDisplayAffinity this sets), so the recording controls never end up baked into
// the recorded video.
//
// The side effect is that they are equally invisible to an *agent's* screenshots, and the HUD is
// what opens the editor — which makes a whole slice of the app unreachable from automation. Hence
// this escape hatch, for testing only. It warns on every window it skips, because a recording made
// while it is set WILL contain the HUD.
const CONTENT_PROTECTION_DISABLED = process.env["OPENSCREEN_DISABLE_CONTENT_PROTECTION"] === "1";

// Forces protection back on where it is auto-disabled below, so the macOS and
// Windows regressions can be re-tested against a future Electron without editing code.
const CONTENT_PROTECTION_FORCED = process.env["OPENSCREEN_FORCE_CONTENT_PROTECTION"] === "1";

/**
 * macOS 26 (Darwin 25) never displays a window that has had
 * `setContentProtection(true)` applied to it.
 *
 * Not "excludes it from captures" — which is the documented behaviour and the
 * whole point — but never paints it for the user either. Confirmed on Darwin
 * 25.5 / Electron 41.2.1 with the HUD: tray icon present, renderer alive and
 * painting (React mounted, no console errors), `ready-to-show` fired, `show()`
 * called, window at valid on-screen coordinates on the main display — and
 * nothing on screen. `showMainWindow()` from the tray and the global shortcut
 * were equally inert, because the window was already "visible" as far as
 * Electron was concerned. Unsetting protection makes it appear instantly; the
 * ordering of protect-vs-show makes no difference, so it is the call itself.
 *
 * `setContentProtection` maps to `NSWindow.sharingType = NSWindowSharingNone`,
 * a path Electron has repeatedly churned on (electron/electron#45990, and
 * PR #46886 reverting a macOS content-protection refactor).
 *
 * Gated on the Darwin major version rather than `darwin` wholesale: the
 * breakage is only *confirmed* on 25.x, and silently dropping protection on
 * older macOS — where it may well work — would be a privacy regression made on
 * no evidence.
 *
 * ScreenCaptureKit ignores `sharingType`, so the native recorder independently
 * excludes the HUD and Notes windows by their native IDs. This call remains the
 * Windows protection and a second line of defence on older macOS releases.
 */
const CONTENT_PROTECTION_BREAKS_DISPLAY = (() => {
	if (process.platform !== "darwin") return false;
	// getSystemVersion() reports the *macOS* version on darwin, not the Darwin
	// kernel version: measured "26.5.0" here where `os.release()` is "25.5.0".
	// So the affected major is 26, and the check must not be fed os.release().
	const macOSMajor = Number.parseInt(process.getSystemVersion().split(".")[0] ?? "", 10);
	return Number.isFinite(macOSMajor) && macOSMajor >= 26;
})();

/**
 * Windows before 11 22H2 never lets the click-through HUD take a click again once
 * it is content-protected (#1105).
 *
 * On those builds Electron makes a protected window WS_EX_LAYERED before setting
 * its display affinity, because WDA_EXCLUDEFROMCAPTURE alone does not keep it out
 * of captures there (electron/electron#47834, worked around in #47856). The style
 * is latched: `UpdateAllowScreenshots` in electron_desktop_window_tree_host_win.cc
 * calls `SetLayered()`, and every later `setIgnoreMouseEvents(false)` puts
 * WS_EX_LAYERED back because `layered_` is set. The "hud-overlay-cursor" poll still
 * toggles input as it should, and Windows passes every click to the desktop
 * underneath. Confirmed on Windows 10 22H2 (19045) / Electron 41.2.1: clickable
 * with OPENSCREEN_DISABLE_CONTENT_PROTECTION=1, never without.
 *
 * Same threshold as Electron's `base::win::GetVersion() < WIN11_22H2`, read from the
 * same place: on Windows getSystemVersion() is Chromium's OSInfo version number
 * ("10.0.19045"), the one GetVersion() maps, and 22H2 starts at build 22621.
 *
 * Only for the HUD, the transparent click-through window. The Notes window is
 * opaque and never click-through, nothing says it is affected, and dropping its
 * protection would put the user's notes in recordings on no evidence.
 */
const CONTENT_PROTECTION_BREAKS_CLICK_THROUGH = (() => {
	if (process.platform !== "win32") return false;
	const build = Number.parseInt(process.getSystemVersion().split(".")[2] ?? "", 10);
	return Number.isFinite(build) && build < 22621;
})();

function applyContentProtection(win: BrowserWindow, label: string, { clickThrough = false } = {}) {
	if (CONTENT_PROTECTION_DISABLED) {
		console.warn(
			`[content-protection] OFF for the ${label} window ` +
				"(OPENSCREEN_DISABLE_CONTENT_PROTECTION=1) — it will appear in screen captures, " +
				"including recordings. Unset it for anything but automated testing.",
		);
		return;
	}
	if (CONTENT_PROTECTION_BREAKS_DISPLAY && !CONTENT_PROTECTION_FORCED) {
		console.warn(
			`[content-protection] OFF for the ${label} window — macOS ` +
				`${process.getSystemVersion()} never displays a content-protected window, so ` +
				"enabling it would make this window permanently invisible. It may therefore appear " +
				"in screen captures. Set OPENSCREEN_FORCE_CONTENT_PROTECTION=1 to re-test.",
		);
		return;
	}
	if (clickThrough && CONTENT_PROTECTION_BREAKS_CLICK_THROUGH && !CONTENT_PROTECTION_FORCED) {
		console.warn(
			`[content-protection] OFF for the ${label} window — Windows ` +
				`${process.getSystemVersion()} (before 11 22H2) never lets a content-protected ` +
				"click-through window take a click. It will therefore appear in screen captures, " +
				"including recordings. Set OPENSCREEN_FORCE_CONTENT_PROTECTION=1 to re-test.",
		);
		return;
	}
	win.setContentProtection(true);
}

// Asset base URL for renderer (wallpapers, etc.). Packaged: extraResources copies
// public/wallpapers to resources/wallpapers. Unpackaged: <appRoot>/public/.
const ASSET_BASE_DIR = process.defaultApp
	? path.join(__dirname, "..", "public")
	: process.resourcesPath;
export const ASSET_BASE_URL_ARG = `--asset-base-url=${pathToFileURL(`${ASSET_BASE_DIR}${path.sep}`).toString()}`;

let hudOverlayWindow: BrowserWindow | null = null;

// The HUD's size in DIP, as last given: at creation, then by "hud-overlay-set-size".
// Every move re-applies this size, never one read back from the window, because the
// read-back drifts: on Windows, getBounds() converts the physical rect to DIP by
// enclosing it (rounding outwards) and setBounds() converts back the same way, so under
// fractional scaling each read-modify-write grows the window by a pixel or two. At 125 %
// a drag grew it on every step, sliding the bar off the pointer and under the taskbar
// (#1004). setPosition() is no way out: Electron implements it as setBounds() with the
// size from getBounds().
let hudWindowSize = { width: 0, height: 0 };

/** The HUD's position, with its own size instead of the drifting read-back. */
function hudBounds(win: BrowserWindow): Electron.Rectangle {
	const [x, y] = win.getPosition();
	return { x, y, ...hudWindowSize };
}

// Origin the current drag gesture started from. The renderer sends the pointer's
// *total* travel since pointerdown rather than per-frame deltas, so every move is
// an absolute `origin + delta` — no rounding to accumulate, and a dropped message
// self-corrects on the next one instead of leaving the window permanently offset.
let hudDragOrigin: { x: number; y: number } | null = null;

// The visible stack's rect inside the window (the bar plus anything open above it), as
// last measured by the renderer. Everything that positions the HUD clamps this rect —
// not the window — into the work area, because the window around it is transparent
// reserve that may overhang any edge (see hudWindowBounds.ts). Null until the
// renderer's first measurement.
let hudContentRect: HudContentRect | null = null;

// Where the user left the bar: its bottom-centre on screen, set by a drag and by the first
// resize. A re-clamp places the bar from here, never from where the window was last pushed:
// a popover opening near the top of the screen pushes the window down so the popover fits,
// and starting from the pushed window left the bar there once the popover closed, a little
// further down with each popover (#1136). Null until the first resize.
let hudBarHome: { x: number; y: number } | null = null;

// Linux never makes the HUD click-through (setHudMouseEventsEnabled in LaunchWindow), so
// an overhanging reserve would swallow clicks on the panels and docks under it. There the
// content rect is ignored and the whole window stays inside the work area.
const HUD_CLAMPS_CONTENT = process.platform !== "linux";

/** Work area of the display the bar is on (or heading for), not the window. */
function hudWorkAreaFor(bounds: Electron.Rectangle): Electron.Rectangle {
	const reference = hudContentRect ? hudContentScreenRect(bounds, hudContentRect) : bounds;
	return screen.getDisplayMatching(reference).workArea;
}

// Re-clamps a HUD nobody is dragging: a drag owns the position frame by frame, and the
// renderer re-measures on release. Skipped while minimized, where moving the window is
// platform-defined; "restore" runs it instead.
function reclampHud() {
	const win = hudOverlayWindow;
	if (!win || win.isDestroyed() || win.isMinimized() || hudDragOrigin) return;

	const bounds = hudBounds(win);
	const workArea = hudWorkAreaFor(bounds);
	const next = hudBarHome
		? hudResizeBounds({
				bounds,
				previousContent: hudContentRect,
				anchor: hudBarHome,
				width: bounds.width,
				height: bounds.height,
				nextContent: hudContentRect,
				workArea,
			})
		: clampHudBoundsToWorkArea(bounds, hudContentRect, workArea);
	if (!sameRect(next, bounds)) {
		win.setBounds(next, false);
	}
}

// The work area can shrink under a HUD nobody is touching: the taskbar stops auto-hiding
// (or is revealed), the Dock moves, the resolution or the scale changes. A bar parked at
// the bottom edge would then be left sitting on the taskbar until the next drag — and the
// drag handle is under the taskbar. Re-clamp whenever the displays change, so the
// invariant the drag and resize paths both maintain holds without user input too.
let isWatchingHudWorkArea = false;
function watchHudWorkAreaChanges() {
	if (isWatchingHudWorkArea) return;
	isWatchingHudWorkArea = true;

	screen.on("display-metrics-changed", reclampHud);
	screen.on("display-added", reclampHud);
	screen.on("display-removed", reclampHud);
}

// Linux hides the bar instead of minimizing it, because a Wayland client cannot bring a
// minimized window back. xdg-shell has set_minimized and no request to undo it, and
// Chromium's Wayland Show() returns early on a toplevel that still exists, so the tray's
// restore() and show() did nothing; focus() then asked for activation without a fresh token,
// which GNOME turns into an "is ready" notification while the bar stays minimized. hide()
// destroys the toplevel and show() maps a new one, which every compositor displays. The cost
// is the position: the compositor places the new toplevel itself. X11 takes the same path:
// there `skipTaskbar` already left a minimized HUD no taskbar entry, so the tray was its only
// way back anyway.
const HUD_HIDES_INSTEAD_OF_MINIMIZING = process.platform === "linux";

ipcMain.on("hud-overlay-hide", () => {
	if (hudOverlayWindow && !hudOverlayWindow.isDestroyed()) {
		if (HUD_HIDES_INSTEAD_OF_MINIMIZING) {
			hudOverlayWindow.hide();
		} else {
			hudOverlayWindow.minimize();
		}
	}
});

// The cursor, sampled here and pushed to the renderer, because while the HUD is
// click-through nothing else can tell it where the pointer is.
//
// Chromium delivers no pointer event of any kind to a window it has made
// input-transparent — including the pointermove the renderer needs to ask for input
// back. Electron's `{ forward: true }` covered that with a global WH_MOUSE_LL hook
// that re-posts WM_MOUSEMOVE, and that hook was the ONLY route out: its install is
// unchecked (SetWindowsHookEx's return value is discarded), latched behind Electron's
// `forwarding_mouse_messages_` so it re-arms only after a setIgnoreMouseEvents(false)
// the renderer can no longer request, and Windows silently revokes any low-level hook
// whose callback overruns LowLevelHooksTimeout — "there is no way for the application
// to know whether the hook is removed". One hook that never installs or quietly dies
// and the HUD is painted, inert, forever, with the tray icon as the only way to quit
// the app. That is issue #266, and issue #385 after it: #266 was closed by moving
// *when* the hook is installed, which left the trapdoor exactly where it was.
//
// So the escape no longer runs on anything Windows can take away. getCursorScreenPoint
// is a plain positional read the main process can always make, the poll exists only
// while the window is click-through — the state it is there to escape — and the
// renderer re-derives the answer from scratch on every tick, so no dropped message,
// dead hook or stale flag can strand it.
const HUD_CURSOR_POLL_MS = 32;
let hudCursorPoll: ReturnType<typeof setInterval> | null = null;
let hudLastPoint: { x: number; y: number } | null = null;

function stopHudCursorPoll() {
	if (hudCursorPoll) clearInterval(hudCursorPoll);
	hudCursorPoll = null;
	hudLastPoint = null;
}

function pollHudCursor() {
	const win = hudOverlayWindow;
	if (!win || win.isDestroyed() || !win.isVisible() || win.isMinimized()) return;

	// getBounds() and getCursorScreenPoint() are both in DIP, and so is a renderer CSS
	// pixel (the HUD is frameless, so the client area is the whole window).
	const bounds = win.getBounds();
	const cursor = screen.getCursorScreenPoint();
	const x = cursor.x - bounds.x;
	const y = cursor.y - bounds.y;
	if (x < 0 || y < 0 || x >= bounds.width || y >= bounds.height) return;

	// Deduped on the WINDOW-RELATIVE point, not the cursor: "hud-overlay-set-size"
	// re-anchors the window on every content change, so the bar can arrive under a
	// cursor that never moved — and that changes the answer just as much.
	if (hudLastPoint && hudLastPoint.x === x && hudLastPoint.y === y) return;
	hudLastPoint = { x, y };

	win.webContents.send("hud-overlay-cursor", x, y);
}

ipcMain.on("hud-overlay-ignore-mouse-events", (_event, ignore: boolean) => {
	if (!hudOverlayWindow || hudOverlayWindow.isDestroyed()) {
		return;
	}

	// No `forward`: the poll above replaces it, and leaving it on would keep the app
	// depending on a hook it cannot check for a transition it no longer needs.
	hudOverlayWindow.setIgnoreMouseEvents(ignore);
	// The pointer crossing the bar is the one thing that follows every popover and dialog
	// closing, whatever took the HUD's topmost bit with it (see keepOnTop.ts).
	reassertAlwaysOnTop(hudOverlayWindow);

	if (!ignore) {
		// Input is live again; the document's own pointer events are cheaper and
		// finer-grained than anything sampled at 32 ms.
		stopHudCursorPoll();
		return;
	}
	if (!hudCursorPoll) {
		hudCursorPoll = setInterval(pollHudCursor, HUD_CURSOR_POLL_MS);
	}
});

ipcMain.on("hud-overlay-drag-start", () => {
	if (!hudOverlayWindow || hudOverlayWindow.isDestroyed()) {
		return;
	}

	// Under Wayland this origin is a lie: Electron documents getPosition() as returning
	// [0, 0] there, because the protocol prohibits a client from introspecting or
	// setting its own global coordinates. The origin+delta scheme below therefore
	// resolves against 0 rather than the window's real position, and the position
	// setBounds() asks for is ignored — so dragging cannot work on Wayland by this
	// route at all. The finiteness check only keeps a garbage origin from reaching a
	// native setter.
	const [x, y] = hudOverlayWindow.getPosition();
	hudDragOrigin = Number.isFinite(x) && Number.isFinite(y) ? { x, y } : null;
});

ipcMain.on("hud-overlay-drag-to", (_event, deltaX: number, deltaY: number) => {
	if (
		!hudOverlayWindow ||
		hudOverlayWindow.isDestroyed() ||
		!hudDragOrigin ||
		!Number.isFinite(deltaX) ||
		!Number.isFinite(deltaY)
	) {
		return;
	}

	// Clamp the *bar* into the work area of the display the drag is heading for —
	// resolved from the destination, not from where the window currently sits, so a
	// drag towards a second display follows the pointer instead of stopping at the
	// edge it started on. The window itself may overhang: everything in it except
	// the bar is transparent reserve (see hudWindowBounds.ts), and clamping the
	// window instead would hand the bar the reserve's width and ~600px of height as
	// a margin it can never cross — the "stuck at the bottom of the screen" trap.
	const bounds = hudBounds(hudOverlayWindow);
	const destination = hudDragDestination({ bounds, origin: hudDragOrigin, deltaX, deltaY });

	const next = clampHudBoundsToWorkArea(destination, hudContentRect, hudWorkAreaFor(destination));

	// setBounds with the HUD's own size, not setPosition, which re-applies the size read
	// back from the window and grows it every frame under fractional scaling.
	hudOverlayWindow.setBounds(next, false);
	hudBarHome = hudBarAnchor(next, hudContentRect);
});

ipcMain.on("hud-overlay-drag-end", () => {
	hudDragOrigin = null;
});

// Resize the HUD to fit its rendered content. The renderer also sends the bar's
// rect inside the requested size (the stack layout is deterministic: centred,
// pinned HUD_BAR_BOTTOM above the window's bottom edge), and every positioning
// decision below is made on that rect rather than on the window — anchored on
// the bar's bottom-centre so a horizontal↔vertical flip resizes the window
// around the bar instead of moving it, and clamped so the bar cannot end up off
// screen. The window around it may overhang; the reserve is invisible.
//
// Applied in one shot rather than tweened. The renderer now reserves space for
// everything that can float above the bar, so a resize only ever accompanies a
// discrete content change (orientation flip, recording controls appearing) that
// snaps anyway — tweening the window across 10 frames just meant 10 frames of the
// bar sitting at an offset that didn't match the content it was drawn with.
ipcMain.on("hud-overlay-set-size", (_event, width: number, height: number, content: unknown) => {
	// An empty size is refused too: it would be stored as the HUD's own size and re-applied by
	// every later move.
	if (
		!hudOverlayWindow ||
		hudOverlayWindow.isDestroyed() ||
		!Number.isFinite(width) ||
		!Number.isFinite(height) ||
		width <= 0 ||
		height <= 0
	) {
		return;
	}

	// A resize re-anchors from the window's current bounds, which would fight the
	// position an in-flight drag is applying. The renderer re-measures on release,
	// which re-sends the rect that matched the size actually in force.
	if (hudDragOrigin) {
		return;
	}

	const bounds = hudBounds(hudOverlayWindow);
	const nextContent = HUD_CLAMPS_CONTENT ? parseHudContentRect(content) : null;
	hudBarHome ??= hudBarAnchor(bounds, hudContentRect);
	const next = hudResizeBounds({
		bounds,
		previousContent: hudContentRect,
		anchor: hudBarHome,
		width,
		height,
		nextContent,
		workArea: hudWorkAreaFor(bounds),
	});
	// A malformed rect must not clobber the last good one: the stored rect is
	// what every later positioning decision clamps by.
	if (nextContent) {
		hudContentRect = nextContent;
	}
	hudWindowSize = { width: next.width, height: next.height };

	if (!sameRect(next, bounds)) {
		hudOverlayWindow.setBounds(next, false);
	}
	reassertAlwaysOnTop(hudOverlayWindow);
});

// The visible stack changed without a resize: the bar grew into its reserve, or a
// popover or notice opened above it. Re-clamp so none of it is left off screen.
ipcMain.on("hud-overlay-content", (_event, content: unknown) => {
	const nextContent = HUD_CLAMPS_CONTENT ? parseHudContentRect(content) : null;
	if (!nextContent) return;
	hudContentRect = nextContent;
	reclampHud();
	if (hudOverlayWindow) reassertAlwaysOnTop(hudOverlayWindow);
});

/**
 * Frameless transparent HUD overlay, always-on-top, centred at the bottom of the
 * primary display. Follows the user across macOS Spaces so it isn't lost on switch.
 */
export function createHudOverlayWindow(): BrowserWindow {
	const primaryDisplay = screen.getPrimaryDisplay();
	const { workArea } = primaryDisplay;

	// Close to what the renderer asks for on its very first measurement (bar plus
	// the reserved space above it), so the HUD doesn't visibly resize itself the
	// instant it becomes visible. See src/components/launch/hudGeometry.ts.
	const windowWidth = 820;
	const windowHeight = 560;

	const x = Math.floor(workArea.x + (workArea.width - windowWidth) / 2);
	const y = Math.floor(workArea.y + workArea.height - windowHeight - 5);

	const win = new BrowserWindow({
		width: windowWidth,
		height: windowHeight,
		// Min/max are intentionally loose: the renderer resizes to fit content via
		// "hud-overlay-set-size" (above), needed for the vertical tray to grow taller.
		minWidth: HUD_WINDOW_MIN.width,
		minHeight: HUD_WINDOW_MIN.height,
		// The reserve may overhang the screen (hudWindowBounds.ts). Without this, macOS
		// re-constrains the frame below the menu bar whenever the window is re-ordered,
		// pulling a stack parked at the top down by the whole reserve.
		enableLargerThanScreen: true,
		x: x,
		y: y,
		frame: false,
		transparent: true,
		// Fully-transparent ARGB backing. Without this macOS draws the window as a
		// rounded glass panel with a border around the HUD content.
		backgroundColor: "#00000000",
		// Don't let macOS mask the window into a rounded rect; the HUD bar provides
		// its own rounding and the window itself must be invisible.
		roundedCorners: false,
		resizable: false,
		alwaysOnTop: true,
		skipTaskbar: true,
		hasShadow: false,
		show: false, // shown via ready-to-show to avoid black rectangle flash
		webPreferences: {
			preload: path.join(__dirname, "preload.mjs"),
			additionalArguments: [ASSET_BASE_URL_ARG],
			nodeIntegration: false,
			contextIsolation: true,
			backgroundThrottling: false,
		},
	});

	// Deliberately NOT born click-through: the renderer asks for it on mount, over
	// "hud-overlay-ignore-mouse-events" (`show: false` holds this window back until
	// ready-to-show, so the two are ~85 ms apart — measured, not assumed). What that
	// leaves open is an invisible rectangle that can swallow one desktop click in
	// those 85 ms, right after the user launched the app — against what doing it here
	// cost them: the whole app (issue #266). A window nothing ever asks for — a
	// renderer that dies before mount — then stays clickable instead of becoming a
	// ghost. See the "hud-overlay-cursor" poll above for the way back out.

	// Keep the recording controls out of the recording (see applyContentProtection).
	applyContentProtection(win, "HUD", { clickThrough: true });

	// Follow the user across macOS Spaces, else the HUD stays pinned to the Space
	// it was first opened on.
	followAcrossSpaces(win);
	keepAlwaysOnTop(win);

	// Show only once painted to avoid the black rectangle flash when a transparent
	// window is shown before its first paint.
	win.once("ready-to-show", () => {
		applyContentProtection(win, "HUD", { clickThrough: true });
		if (!HEADLESS) win.show();
	});

	win.webContents.on("did-finish-load", () => {
		win?.webContents.send("main-process-message", new Date().toLocaleString());
	});

	hudOverlayWindow = win;
	hudWindowSize = { width: windowWidth, height: windowHeight };
	watchHudWorkAreaChanges();
	// Display changes while minimized were skipped; catch up on the way back.
	win.on("restore", reclampHud);

	win.on("closed", () => {
		if (hudOverlayWindow === win) {
			hudOverlayWindow = null;
			hudDragOrigin = null;
			// The next HUD is a new window: a rect measured in this one would misplace it.
			hudContentRect = null;
			hudBarHome = null;
			stopHudCursorPoll();
		}
	});

	if (VITE_DEV_SERVER_URL) {
		win.loadURL(VITE_DEV_SERVER_URL + "?windowType=hud-overlay");
	} else {
		win.loadFile(path.join(RENDERER_DIST, "index.html"), {
			query: { windowType: "hud-overlay" },
		});
	}

	markSheetless(win);
	return win;
}

/**
 * Main editor window. Starts maximised with a hidden title bar on macOS; not
 * always-on-top and appears in the taskbar/dock.
 *
 * `query` overrides the renderer's routing params. The export bench passes
 * windowType=bench so it runs under THIS window's webPreferences — same
 * preload, same sandbox, same backgroundThrottling:false — because a bench that
 * configures its own window measures a different app than the one we ship.
 */
export function createEditorWindow(query: Record<string, string> = {}): BrowserWindow {
	const isMac = process.platform === "darwin";
	const wayland = usesWaylandBackend(process.platform, app.commandLine, process.env);
	const persist = shouldTrackEditorWindow(query);
	const loaded = persist ? loadEditorWindowState(app.getPath("userData")) : null;
	const saved = loaded
		? {
				...fitEditorRect(loaded, screen.getDisplayMatching(loaded).workArea, wayland),
				maximized: loaded.maximized,
			}
		: null;
	const creation = resolveEditorCreation({
		isBench: query.windowType === "bench",
		saved,
		wayland,
	});

	const win = new BrowserWindow({
		...creation.bounds,
		minWidth: 800,
		minHeight: 600,
		// Seamless titlebar on every platform: the app's own topbar IS the titlebar
		// (it already carries the logo, the title and a drag region). macOS keeps its
		// traffic lights, Windows/Linux get the native Window Controls Overlay — which
		// preserves Snap Layouts and the system close/maximise semantics instead of
		// re-implementing them as HTML buttons. Its colours follow the app theme via
		// the "set-titlebar-overlay" IPC (see handlers.ts).
		titleBarStyle: "hidden",
		...(isMac
			? { trafficLightPosition: { x: 18, y: 21 } }
			: // Windows fixes the width of its caption buttons (46px) and leaves us the height: at
				// 46px each hover area is a square in the top-right corner, as in Chrome or Explorer,
				// instead of a 58px-tall slab, and the top bar's bottom rule runs on under it.
				// Native, so Snap Layouts stays on the maximise button.
				{ titleBarOverlay: { color: "#09090b", symbolColor: "#a1a1aa", height: 46 } }),
		transparent: false,
		resizable: true,
		alwaysOnTop: false,
		skipTaskbar: false,
		title: "OpenScreen",
		backgroundColor: "#09090b",
		show: false, // shown via ready-to-show to avoid white flash on first load
		webPreferences: {
			preload: path.join(__dirname, "preload.mjs"),
			additionalArguments: [ASSET_BASE_URL_ARG],
			nodeIntegration: false,
			contextIsolation: true,
			webSecurity: false,
			backgroundThrottling: false,
			// Media track lists: the preview's hidden <video> and <audio> deselect their video
			// track, so Chromium stops decoding pictures the native compositor already draws
			// (`dropVideoTrack` in VirtualPreview.tsx).
			enableBlinkFeatures: "AudioVideoTracks",
		},
	});

	const inNormalState = () => !win.isMaximized() && !win.isMinimized() && !win.isFullScreen();
	// Under Wayland, Electron 41's getNormalBounds() is wrong while the window is maximized: it
	// takes the restored widget bounds, which carry the client-side shadow, and subtracts the
	// *maximized* frame insets (none) instead of the restored ones. Each close while maximized
	// so wrote the normal rect back 30×41 px larger and 15×10 px up-left — on GNOME 46,
	// {271,0,1410,1080} came back as {256,-10,1440,1121}. getBounds() read in the normal state
	// is exact, so the last such reading is what gets saved there. The window is still in its
	// normal state here, before any maximize.
	let lastNormalBounds = win.getBounds();
	const trackNormalBounds = () => {
		if (!win.isDestroyed() && inNormalState()) lastNormalBounds = win.getBounds();
	};

	// Under Wayland the maximize waits until the compositor has mapped and focused the window,
	// or it sticks (WAYLAND_MAXIMIZE_SETTLE_MS). Until then the window still counts as
	// maximized for the saved state, so closing it early does not forget the choice.
	let maximizePending = creation.maximize && creation.deferMaximize;
	if (maximizePending) {
		win.once("maximize", () => {
			maximizePending = false;
		});
		win.once("focus", () => {
			setTimeout(() => {
				if (!maximizePending || win.isDestroyed()) return;
				maximizePending = false;
				if (inNormalState()) win.maximize();
			}, WAYLAND_MAXIMIZE_SETTLE_MS);
		});
	} else if (creation.maximize) {
		win.maximize();
	}

	if (creation.persist) {
		// `resized` and `moved` never fire on Linux; `resize` does, mid-drag included.
		if (wayland) win.on("resize", trackNormalBounds);
		const persistState = () => {
			if (win.isDestroyed()) return;
			if (wayland) trackNormalBounds();
			const rect = wayland ? lastNormalBounds : win.getNormalBounds();
			const bounds = fitEditorRect(rect, screen.getDisplayMatching(rect).workArea, wayland);
			saveEditorWindowState(app.getPath("userData"), {
				x: bounds.x,
				y: bounds.y,
				width: bounds.width,
				height: bounds.height,
				maximized: win.isMaximized() || maximizePending,
			});
		};
		win.on("moved", persistState);
		win.on("resized", persistState);
		win.on("close", persistState);
	}

	// The editor renders its own File/Edit/View menu bar in the custom titlebar,
	// so hide the native OS menu bar on Windows/Linux (it stays reachable via Alt).
	// macOS keeps its global menu bar.
	if (process.platform !== "darwin") {
		win.setAutoHideMenuBar(true);
	}

	// Show only once painted to avoid a white flash on cold Vite start.
	win.once("ready-to-show", () => {
		if (!HEADLESS) win.show();
	});

	// Inject dark background before any React paint so the sub-titlebar area never
	// flashes white on a cold Vite load.
	win.webContents.on("dom-ready", () => {
		// `--titlebar-inset-left` reserves room for the macOS traffic lights; on
		// Windows/Linux the topbar uses the `titlebar-area-*` env vars instead.
		win.webContents
			.insertCSS(
				`html, body, #root { background: #09090b !important; }
				 :root { --titlebar-inset-left: ${isMac ? "68px" : "0px"}; }`,
			)
			.catch(() => {
				// Best-effort cosmetic; ignore if the page is mid-teardown.
			});
	});

	win.webContents.on("did-finish-load", () => {
		win?.webContents.send("main-process-message", new Date().toLocaleString());
	});

	const routing = { windowType: "editor", ...query };
	if (VITE_DEV_SERVER_URL) {
		win.loadURL(`${VITE_DEV_SERVER_URL}?${new URLSearchParams(routing).toString()}`);
	} else {
		win.loadFile(path.join(RENDERER_DIST, "index.html"), { query: routing });
	}

	return win;
}

/**
 * Floating source-selector window for picking a screen or window to record.
 * Frameless, transparent, and follows the user across macOS Spaces.
 */
export function createSourceSelectorWindow(): BrowserWindow {
	const { width, height } = screen.getPrimaryDisplay().workAreaSize;

	const win = new BrowserWindow({
		width: 680,
		height: 580,
		minHeight: 420,
		maxHeight: 680,
		x: Math.round((width - 680) / 2),
		y: Math.round((height - 580) / 2),
		frame: false,
		resizable: false,
		alwaysOnTop: true,
		transparent: true,
		backgroundColor: "#00000000",
		webPreferences: {
			preload: path.join(__dirname, "preload.mjs"),
			additionalArguments: [ASSET_BASE_URL_ARG],
			nodeIntegration: false,
			contextIsolation: true,
		},
	});

	// Follow the user across macOS Spaces so the selector appears on the active
	// desktop regardless of where the HUD was opened.
	followAcrossSpaces(win);
	keepAlwaysOnTop(win);
	// The picker may close with another app in front, which gives the HUD no event of its own.
	win.on("closed", () => {
		if (hudOverlayWindow) reassertAlwaysOnTop(hudOverlayWindow);
	});

	if (VITE_DEV_SERVER_URL) {
		win.loadURL(VITE_DEV_SERVER_URL + "?windowType=source-selector");
	} else {
		win.loadFile(path.join(RENDERER_DIST, "index.html"), {
			query: { windowType: "source-selector" },
		});
	}

	markSheetless(win);
	return win;
}

/**
 * Centered transparent countdown overlay that sits above the HUD during
 * recording pre-roll.
 */
export function createCountdownOverlayWindow(): BrowserWindow {
	const { workArea } = screen.getPrimaryDisplay();
	const overlayWidth = 420;
	const overlayHeight = 260;

	const win = new BrowserWindow({
		width: overlayWidth,
		height: overlayHeight,
		minWidth: overlayWidth,
		maxWidth: overlayWidth,
		minHeight: overlayHeight,
		maxHeight: overlayHeight,
		x: Math.round(workArea.x + (workArea.width - overlayWidth) / 2),
		y: Math.round(workArea.y + (workArea.height - overlayHeight) / 2),
		frame: false,
		resizable: false,
		alwaysOnTop: true,
		skipTaskbar: true,
		focusable: false,
		transparent: true,
		backgroundColor: "#00000000",
		hasShadow: false,
		show: false,
		webPreferences: {
			preload: path.join(__dirname, "preload.mjs"),
			additionalArguments: [ASSET_BASE_URL_ARG],
			nodeIntegration: false,
			contextIsolation: true,
			backgroundThrottling: false,
		},
	});

	win.setIgnoreMouseEvents(true);

	followAcrossSpaces(win);
	keepAlwaysOnTop(win);

	if (VITE_DEV_SERVER_URL) {
		win.loadURL(VITE_DEV_SERVER_URL + "?windowType=countdown-overlay");
	} else {
		win.loadFile(path.join(RENDERER_DIST, "index.html"), {
			query: { windowType: "countdown-overlay" },
		});
	}

	markSheetless(win);
	return win;
}

/**
 * The macOS permissions window: first run, the app menu, and wherever a missing permission
 * would otherwise stop a recording. An ordinary opaque window on purpose -- it has to sit
 * beside System Settings and macOS' own prompts, not float above them like the HUD.
 */
export function createPermissionsWindow(): BrowserWindow {
	const win = new BrowserWindow({
		width: 520,
		height: 640,
		resizable: false,
		minimizable: false,
		maximizable: false,
		fullscreenable: false,
		title: "OpenScreen",
		backgroundColor: "#0b0c0f",
		show: false,
		webPreferences: {
			preload: path.join(__dirname, "preload.mjs"),
			additionalArguments: [ASSET_BASE_URL_ARG],
			nodeIntegration: false,
			contextIsolation: true,
		},
	});

	win.once("ready-to-show", () => {
		if (!HEADLESS) {
			win.show();
		}
	});

	if (VITE_DEV_SERVER_URL) {
		win.loadURL(VITE_DEV_SERVER_URL + "?windowType=permissions");
	} else {
		win.loadFile(path.join(RENDERER_DIST, "index.html"), {
			query: { windowType: "permissions" },
		});
	}

	return win;
}

// Frameless Notes Window for taking notes during a recording.
export function createNotesWindow(): BrowserWindow {
	const win = new BrowserWindow({
		width: 400,
		height: 540,
		minWidth: 360,
		minHeight: 400,
		maxWidth: 640,
		maxHeight: 720,
		title: "OpenScreen - Notes",
		backgroundColor: "#09090b",
		resizable: true,
		alwaysOnTop: true,
		skipTaskbar: false,
		show: false,
		webPreferences: {
			preload: path.join(__dirname, "preload.mjs"),
			additionalArguments: [ASSET_BASE_URL_ARG],
			nodeIntegration: false,
			contextIsolation: true,
			backgroundThrottling: false,
		},
	});

	// Match the editor: no native OS menu bar on Windows/Linux (reachable via Alt).
	if (process.platform !== "darwin") {
		win.setAutoHideMenuBar(true);
	}
	keepAlwaysOnTop(win);

	applyContentProtection(win, "Notes");
	win.once("ready-to-show", () => {
		applyContentProtection(win, "Notes");
		win.show();
	});

	if (VITE_DEV_SERVER_URL) {
		win.loadURL(VITE_DEV_SERVER_URL + "?showNotes=true");
	} else {
		win.loadFile(path.join(RENDERER_DIST, "index.html"), {
			query: { showNotes: "true" },
		});
	}

	return win;
}

/** A hidden window running one of the CLI runners (src/cli/): `openscreen <command>`, or a
 *  media tool of an MCP server. */
export function createRunnerWindow(windowType: string): BrowserWindow {
	const win = new BrowserWindow({
		width: 1280,
		height: 720,
		show: false,
		webPreferences: {
			preload: path.join(__dirname, "preload.mjs"),
			additionalArguments: [ASSET_BASE_URL_ARG],
			nodeIntegration: false,
			contextIsolation: true,
			// Same relaxation as the editor window: exporters load recording media
			// via file:// URLs.
			webSecurity: false,
			backgroundThrottling: false,
		},
	});

	if (VITE_DEV_SERVER_URL) {
		win.loadURL(`${VITE_DEV_SERVER_URL}?windowType=${windowType}`);
	} else {
		win.loadFile(path.join(RENDERER_DIST, "index.html"), { query: { windowType } });
	}
	return win;
}