Skip to content

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

195 KB
Raw Blame
import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process";
import { EventEmitter } from "node:events";
import { constants as fsConstants } from "node:fs";
import fs from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import { fileURLToPath, pathToFileURL } from "node:url";
import type { DesktopCapturerSource, Rectangle, WebContents } from "electron";
import {
	app,
	BrowserWindow,
	clipboard,
	desktopCapturer,
	dialog,
	ipcMain,
	safeStorage,
	screen,
	shell,
	systemPreferences,
} from "electron";
import { DEFAULT_WEBCAM_QUALITY, type WebcamQualityId } from "../../src/hooks/webcamCaptureTarget";
import {
	type AxcutDocument,
	isAxcutDocumentFile,
	parseDocumentFile,
} from "../../src/lib/ai-edition/schema";
import type { CliSourcesResult } from "../../src/lib/cliContracts";
import { pickRecordingSource } from "../../src/lib/cliSourcePick";
import {
	type NativeLinuxRecordingRequest,
	portalCursorMode,
} from "../../src/lib/nativeLinuxRecording";
import {
	collectMacCaptureExcludedWindowIds,
	type NativeMacRecordingRequest,
} from "../../src/lib/nativeMacRecording";
import type { NativeWindowsRecordingRequest } from "../../src/lib/nativeWindowsRecording";
import {
	type CursorCaptureMode,
	normalizeCursorCaptureMode,
	normalizeProjectMedia,
	normalizeRecordingSession,
	type ProjectMedia,
	type RecordedVideoAssetInput,
	type RecordingSession,
	type StoreRecordedSessionInput,
} from "../../src/lib/recordingSession";
import {
	AI_EDITION_OPEN_PROJECT_CHANNEL,
	type CursorRecordingData,
	type ProjectFileResult,
	type ProjectPathResult,
} from "../../src/native/contracts";
import { PRODUCT_NAME } from "../about";
import {
	compactSessionNow,
	configureChatPersistence,
	createSession,
	deleteSession,
	getSessionContextUsage,
	listSessions,
	renameSession,
	rewindToMessage,
	runChat,
	selectSession,
} from "../ai-edition/chat-service";
import type { CursorTelemetryReader } from "../ai-edition/deep-agent/service";
import { DocumentService } from "../ai-edition/document-service";
import { LlmConfigStore } from "../ai-edition/llm-config-store";
import { StylePresetService } from "../ai-edition/style-preset-service";
import { AppSettingsStore } from "../app-settings";
import { createRunnerHost } from "../cli/runnerHost";
import { hideCountdownOverlay } from "../countdownOverlay";
import { isDiagnosticModeEnabled, mainLogFile } from "../diagnostics/main-log-file";
import { createZip } from "../diagnostics/zip";
import { mainT } from "../i18n";
import { getInstallChannel } from "../install-channel";
import {
	DEFAULT_RECORDINGS_DIR,
	getRecordingsDirInfo,
	RECORDINGS_DIR,
	setRecordingsDir,
} from "../main";
import { createAppRecorder, pickTakePrefs, takePrefs } from "../mcp/app-recorder";
import { EditorDocumentHost } from "../mcp/editor-document-host";
import { openVideoInHiddenWindow } from "../mcp/hidden-video";
import { NAMED_TAKE_NEEDS_SCREEN_ACCESS, namedTakeMayEnumerate } from "../mcp/macNamedTake";
import { McpController } from "../mcp/mcp-controller";
import { McpSettingsStore } from "../mcp/mcp-settings-store";
import { createMediaTools, type MediaToolDeps, type RecordRequest } from "../mcp/media-tools";
import { createToolRunner, type McpToolDeps } from "../mcp/openscreen-mcp-server";
import { type AudioPeaksResult, getAudioPeaks } from "../media/audioPeaks";
import {
	readCursorRecordingFile as readCursorRecordingFileFrom,
	readCursorSidecar,
	readCursorTelemetryFile as readCursorTelemetryFileFrom,
} from "../media/cursorSidecar";
import { findMediaLinksByFingerprint, registerMediaLinks } from "../media/mediaLinksRegistry";
import { relinkProjectMedia } from "../media/projectMediaRelinker";
import { showOpenDialogOver, showSaveDialogOver } from "../messageBox";
import {
	type LinuxCaptureSourceKind,
	LinuxNativeCaptureSession,
} from "../native-bridge/capture/linuxNativeCaptureSession";
import { compactCursorTelemetryPauseRanges } from "../native-bridge/cursor/recording/cursorPauseRanges";
import { createCursorRecordingSession } from "../native-bridge/cursor/recording/factory";
import {
	isMacCursorHelperUnavailable,
	requestMacCursorAccessibilityAccess,
} from "../native-bridge/cursor/recording/macNativeCursorRecordingSession";
import { findPipeWireCursorHelperPath } from "../native-bridge/cursor/recording/pipeWireCursorRecordingSession";
import type { CursorRecordingSession } from "../native-bridge/cursor/recording/session";
import { toHelperRect } from "../native-bridge/helperCoordinates";
import {
	isMacPickerSourceId,
	MAC_PICKER_SOURCE_PREFIX,
	type MacPickerSelection,
	MacPickerSession,
	macSystemPickerEnabled,
	markMacSystemPickerUnavailable,
} from "../native-bridge/screen/macPickerSession";
import { readMacScreenCaptureAccess } from "../native-bridge/screen/macScreenAccess";
import { CompositorViewService } from "../native-bridge/services/compositorViewService";
import { getMacPermissions, showPermissionsWindow } from "../permissions";
import { scoreDeviceNameMatch } from "../recording/deviceNameMatching";
import { recordingStorageProblem } from "../recording/diskSpaceCheck";
import {
	describeSalvagedTake,
	nativeMacSalvageTarget,
	salvageNativeMacCapture,
} from "../recording/nativeMacCaptureSalvage";
import {
	type NativeMacCaptureExit,
	nativeMacDiscardTargets,
	sendNativeMacStopCommand,
	waitForNativeMacCaptureStop,
} from "../recording/nativeMacCaptureStop";
import {
	isSalvageableFragmentedCapture,
	NATIVE_WINDOWS_SALVAGEABLE_OUTPUT_BYTES,
	readMicrophoneDefaulted,
	readMicrophoneNotFound,
	readMicrophoneUnavailable,
	readSecondaryWindowsApplied,
	readWebcamFormat,
	readWebcamUnavailable,
	terminateNativeWindowsCapture,
	waitForNativeWindowsCaptureStop,
} from "../recording/nativeWindowsCaptureStop";
import { removeEmptyCaptureOutput } from "../recording/removeEmptyCaptureOutput";
import { patchWebmDurationOnDisk } from "../recording/webm-duration";
import { reindexRecordingOnDisk } from "../recording/webm-seek-index";
import {
	describeMacPickerSource,
	describeRecordingSource,
	enumerationIncludesSourceKind,
	mergeEnumeratedSources,
	rememberedPickerSourceName,
	resolveRecordingSource,
	restoreRecordingSourceAfterEnumeration,
	shouldEnumerateRecordingSources,
	shouldPersistSelectedSource,
} from "../recording-source-settings";
import { getSttManager } from "../stt";
import { createRunnerWindow } from "../windows";
import {
	assertWindowsUpdateIdle,
	isWindowsUpdatePending,
	WINDOWS_UPDATE_PENDING_MESSAGE,
} from "../windows-update";
import { getSourcesByType, shouldEnumerateSourceTypesSeparately } from "./desktopSourceTypes";
import { registerNativeBridgeHandlers } from "./nativeBridge";
import { createNativeMacMidCaptureErrorWatch } from "./nativeMacMidCaptureErrorWatch";
import { registerRecordingPrefsHandlers } from "./recordingPrefs";
import { RecordingStreamRegistry, registerRecordingStreamHandlers } from "./recordingStream";
import { type SelectSourceContext, selectSourceWithOwnership } from "./selectSourceOwnership";

const PROJECT_FILE_EXTENSION = "openscreen";
export const SHORTCUTS_FILE = path.join(app.getPath("userData"), "shortcuts.json");
const RECORDING_FILE_PREFIX = "recording-";
const RECORDING_SESSION_SUFFIX = ".session.json";
const ALLOWED_IMPORT_VIDEO_EXTENSIONS = new Set([
	".webm",
	".mp4",
	".mov",
	".avi",
	".mkv",
	".m4v",
	".wmv",
	".flv",
	".ts",
]);
const PREVIEW_AUDIO_DIR = path.join(app.getPath("userData"), "preview-audio");
// See the save-recorded-voiceover handler: an upper bound on renderer-supplied
// bytes written to disk, well past any plausible take.
const MAX_RECORDED_VOICEOVER_BYTES = 512 * 1024 * 1024;
// The bundled click-sound samples, staged for the compositor, which reads audio by path and not
// by renderer URL. These are the only names the staging handler accepts, and they match
// HIT_FILES in src/lib/ai-edition/clickSound.ts.
const CLICK_SOUND_DIR = path.join(app.getPath("userData"), "click-sfx");
const CLICK_SOUND_HIT_FILES: string[] = ["click-down.wav", "click-up.wav"];
const MAX_CLICK_HIT_BYTES = 4 * 1024 * 1024;
const nativeMacCaptureEvents = new EventEmitter();

// Enumeration walks every display and window and grabs a thumbnail of each, so it
// is allowed to be slow on a loaded machine. It is not allowed to be unbounded.
// Deliberately above the CLI runner's own 20s bound, so the more specific message
// there still wins for `openscreen sources`; this is the backstop for everything
// else that calls get-sources.
const GET_SOURCES_TIMEOUT_MS = 30_000;

/**
 * Reject if `work` has not settled within `ms`.
 *
 * The abandoned promise keeps running — there is no way to cancel a
 * desktopCapturer call — so this bounds the *wait*, not the work. That is the
 * whole available remedy: an unbounded await leaves a caller with no error and no
 * way out, which is strictly worse than a late failure it can report.
 */
function withDeadline<T>(work: Promise<T>, ms: number, message: string): Promise<T> {
	let timer: ReturnType<typeof setTimeout> | undefined;
	return Promise.race([
		work,
		new Promise<never>((_resolve, reject) => {
			timer = setTimeout(() => reject(new Error(message)), ms);
		}),
	]).finally(() => clearTimeout(timer)) as Promise<T>;
}

// Paths the user approved via file picker or project load (i.e. outside the default dirs).
const approvedPaths = new Set<string>();

function approveFilePath(filePath: string): void {
	approvedPaths.add(path.resolve(filePath));
}

// The default folder stays readable after the user picks another one: every take made
// before the change, and the projects that use them, are still there.
// ponytail: a custom folder left for another custom folder is not remembered. The editor's
// own projects still open (they grant what they declare); a v2 project file outside it
// does not. Keep a list of past folders if that ever matters.
function getAllowedReadDirs(): string[] {
	return [RECORDINGS_DIR, DEFAULT_RECORDINGS_DIR];
}

function isPathWithinDir(filePath: string, dirPath: string): boolean {
	const resolved = path.resolve(filePath);
	const resolvedDir = path.resolve(dirPath);
	return resolved === resolvedDir || resolved.startsWith(resolvedDir + path.sep);
}

function isPathAllowed(filePath: string): boolean {
	const resolved = path.resolve(filePath);
	if (approvedPaths.has(resolved)) return true;
	return getAllowedReadDirs().some((dir) => isPathWithinDir(resolved, dir));
}

function resolveApprovedVideoPath(videoPath?: string | null): string | null {
	const normalizedPath = normalizeVideoSourcePath(videoPath);
	if (!normalizedPath) {
		return null;
	}

	if (!hasAllowedImportVideoExtension(normalizedPath) || !isPathAllowed(normalizedPath)) {
		return null;
	}

	return normalizedPath;
}

// Attach the parent window only when valid, to avoid passing a destroyed BrowserWindow to dialogs.
function hasAllowedImportVideoExtension(filePath: string): boolean {
	return ALLOWED_IMPORT_VIDEO_EXTENSIONS.has(path.extname(filePath).toLowerCase());
}

// Imported audio (issue #350). Kept separate from the video set so the two
// pickers stay honest — an audio picker must not approve a video path and vice
// versa. A SUBSET of SUPPORTED_AUDIO_EXTENSIONS in the document service, which
// also accepts `.webm`: that gate is told the kind by its caller, while this one
// only has the extension to go on and `.webm` is far more often a video.
const ALLOWED_IMPORT_AUDIO_EXTENSIONS = new Set([
	".mp3",
	".wav",
	".m4a",
	".aac",
	".flac",
	".ogg",
	".oga",
	".opus",
]);

function hasAllowedImportAudioExtension(filePath: string): boolean {
	return ALLOWED_IMPORT_AUDIO_EXTENSIONS.has(path.extname(filePath).toLowerCase());
}

// Video OR audio. The type-specific pickers stay honest (see the audio set's
// comment), but the generic media READS — peaks, binary, file-info, chunk — serve
// whichever kind the document points at, so they must accept both. Gating them on
// video alone dropped every imported audio path once `approvedPaths` was empty
// (a project reopen), and the waveform was lost for good (issue #350).
function hasAllowedImportMediaExtension(filePath: string): boolean {
	return hasAllowedImportVideoExtension(filePath) || hasAllowedImportAudioExtension(filePath);
}

function runProcess(
	command: string,
	args: string[],
): Promise<{ code: number | null; stdout: string; stderr: string }> {
	return new Promise((resolve, reject) => {
		const child = spawn(command, args, { stdio: ["ignore", "pipe", "pipe"] });
		let stdout = "";
		let stderr = "";
		child.stdout.on("data", (chunk) => {
			stdout += chunk.toString();
		});
		child.stderr.on("data", (chunk) => {
			stderr += chunk.toString();
		});
		child.on("error", reject);
		child.on("close", (code) => resolve({ code, stdout, stderr }));
	});
}

function parseAfinfoAudioTrackBitrates(output: string): number[] {
	const bitrates: number[] = [];
	const trackSections = output.split(/\n----\n/g).slice(1);
	for (const section of trackSections) {
		const match = section.match(/\bbit rate:\s*([0-9]+)\s*bits per second/i);
		bitrates.push(match ? Number(match[1]) : 0);
	}
	return bitrates;
}

async function prepareSupplementalPreviewAudioTrack(videoPath: string) {
	const normalizedPath = await approveReadableVideoPath(videoPath);
	if (!normalizedPath) {
		return {
			success: false,
			message: "File path is not approved or is not a supported video file",
		};
	}

	if (process.platform !== "darwin" || path.extname(normalizedPath).toLowerCase() !== ".mp4") {
		return { success: true, path: null };
	}

	const afinfo = await runProcess("/usr/bin/afinfo", [normalizedPath]);
	if (afinfo.code !== 0) {
		return { success: true, path: null };
	}

	const bitrates = parseAfinfoAudioTrackBitrates(`${afinfo.stdout}\n${afinfo.stderr}`);
	if (bitrates.length <= 1) {
		return { success: true, path: null };
	}

	let supplementalTrackIndex = 1;
	for (let index = 2; index < bitrates.length; index += 1) {
		if (bitrates[index] > bitrates[supplementalTrackIndex]) {
			supplementalTrackIndex = index;
		}
	}

	await fs.mkdir(PREVIEW_AUDIO_DIR, { recursive: true });
	const sourceStat = await fs.stat(normalizedPath);
	const parsedPath = path.parse(normalizedPath);
	const outputPath = path.join(
		PREVIEW_AUDIO_DIR,
		`${parsedPath.name}.track-${supplementalTrackIndex}.${Math.round(sourceStat.mtimeMs)}.m4a`,
	);

	try {
		const outputStat = await fs.stat(outputPath);
		if (outputStat.mtimeMs >= sourceStat.mtimeMs) {
			return { success: true, path: pathToFileURL(outputPath).toString() };
		}
	} catch {
		// Generate below.
	}

	const conversion = await runProcess("/usr/bin/afconvert", [
		"--read-track",
		String(supplementalTrackIndex),
		"-f",
		"m4af",
		"-d",
		"aac",
		normalizedPath,
		outputPath,
	]);
	if (conversion.code !== 0) {
		return {
			success: false,
			message: conversion.stderr || conversion.stdout || "Failed to prepare preview audio",
		};
	}

	return { success: true, path: pathToFileURL(outputPath).toString() };
}

// Shared core behind the media path approvers. `hasAllowedExtension` is the ONLY
// thing that differs between video and audio imports, so it is the single knob:
// an already-approved path passes regardless, otherwise the extension gate,
// optional trusted-dir confinement, and a stat check decide whether to approve.
async function approveReadableMediaPath(
	filePath: string | null | undefined,
	hasAllowedExtension: (p: string) => boolean,
	trustedDirs?: string[],
): Promise<string | null> {
	const normalizedPath = normalizeVideoSourcePath(filePath);
	if (!normalizedPath) {
		return null;
	}

	if (isPathAllowed(normalizedPath)) {
		return normalizedPath;
	}

	if (!hasAllowedExtension(normalizedPath)) {
		return null;
	}

	// With trustedDirs (e.g. project load), only auto-approve paths inside them so a
	// malicious project file can't approve reads to arbitrary locations.
	if (trustedDirs) {
		const resolved = path.resolve(normalizedPath);
		const withinTrusted = trustedDirs.some((dir) => isPathWithinDir(resolved, dir));
		if (!withinTrusted) {
			return null;
		}
	}

	try {
		const stats = await fs.stat(normalizedPath);
		if (!stats.isFile()) {
			return null;
		}
	} catch {
		return null;
	}

	approveFilePath(normalizedPath);
	return normalizedPath;
}

function approveReadableVideoPath(
	filePath?: string | null,
	trustedDirs?: string[],
): Promise<string | null> {
	return approveReadableMediaPath(filePath, hasAllowedImportVideoExtension, trustedDirs);
}

function approveReadableAudioPath(
	filePath?: string | null,
	trustedDirs?: string[],
): Promise<string | null> {
	return approveReadableMediaPath(filePath, hasAllowedImportAudioExtension, trustedDirs);
}

/**
 * A path a generic read may use — and NOT a way to obtain one.
 *
 * `approveReadableMediaPath` grants approval to any existing file with a media extension.
 * Behind a picker or a document load that is the point; behind `read-binary-file` it meant
 * the renderer could name any media file on the machine and have its bytes handed back,
 * which is a capability no generic handler should carry (CWE-200).
 *
 * Approval is granted in exactly three places now: the recordings directory, a file the user
 * picked, and the assets a loaded project declares (`approveDocumentMedia`). Everything else
 * spends one.
 */
function readableApprovedPath(filePath?: string | null): string | null {
	const normalizedPath = normalizeVideoSourcePath(filePath);
	if (!normalizedPath) return null;
	if (!isPathAllowed(normalizedPath)) return null;
	// The extension check stays: an approval granted for a recording must not become a way
	// to read the project file, the log, or anything else sitting beside it.
	if (!hasAllowedImportMediaExtension(normalizedPath)) return null;
	return normalizedPath;
}

/** Grant the media a loaded project declares. The document is the app's own file, and this
 *  is what the picker's approval decays into once the app restarts. */
/**
 * `trustedDirs`, when given, confines the grant to media inside them: a project file read from
 * an arbitrary path gets the same rule as a v2 project (`getApprovedProjectSession`). Without
 * it, as for the editor's own projects, every declared path is granted.
 */
function approveDocumentMedia(document: AxcutDocument, trustedDirs?: string[]): void {
	const trusted = (filePath: string) =>
		!trustedDirs || trustedDirs.some((dir) => isPathWithinDir(filePath, dir));
	for (const asset of document.assets ?? []) {
		const media = normalizeVideoSourcePath(asset.originalPath);
		if (media && hasAllowedImportMediaExtension(media) && trusted(media)) approveFilePath(media);
		const camera = normalizeVideoSourcePath(asset.cameraTrack?.sourcePath);
		if (camera && hasAllowedImportMediaExtension(camera) && trusted(camera)) {
			approveFilePath(camera);
		}
	}
}

function resolveRecordingOutputPath(fileName: string): string {
	const trimmed = fileName.trim();
	if (!trimmed) {
		throw new Error("Invalid recording file name");
	}

	const parsedPath = path.parse(trimmed);
	const hasTraversalSegments = trimmed.split(/[\\/]+/).some((segment) => segment === "..");
	const isNestedPath =
		parsedPath.dir !== "" ||
		path.isAbsolute(trimmed) ||
		trimmed.includes("/") ||
		trimmed.includes("\\");
	if (hasTraversalSegments || isNestedPath || parsedPath.base !== trimmed) {
		throw new Error("Recording file name must not contain path segments");
	}

	return path.join(RECORDINGS_DIR, parsedPath.base);
}

function isValidDurationMs(value: number | undefined): value is number {
	return typeof value === "number" && Number.isFinite(value) && value > 0;
}

/**
 * Finalize one recording file: flush/close the stream if it was streamed, else write
 * the buffered bytes (short recording or stream failed to open). Returns whether it was
 * streamed, so the caller knows if the WebM duration needs patching on disk.
 */
async function finalizeRecordingFile(
	registry: RecordingStreamRegistry,
	fileName: string,
	filePath: string,
	videoData?: ArrayBuffer,
): Promise<boolean> {
	const streamed = await registry.finalize(fileName);
	if (!streamed && videoData && videoData.byteLength > 0) {
		await fs.writeFile(filePath, Buffer.from(videoData));
	}
	return streamed;
}

/**
 * Give a finalized recording a usable container, by whichever route works.
 *
 * MediaRecorder omits the `Duration` header, so without repair the editor sees
 * `duration = Infinity` and cannot scale its timeline.
 *
 * Two routes, in order of quality:
 *   1. A full container remux through libavformat's matroska muxer (Linux, where
 *      capture goes through MediaRecorder). The muxer derives `Duration` from
 *      the real packet timestamps rather than from the renderer's wall-clock
 *      measurement, and writes `Cues`/`SeekHead` on the way past.
 *   2. The EBML header patch, which splices the caller's `durationMs` into the
 *      Info section. Used on Windows/macOS, and on Linux whenever the remux is
 *      unavailable (no addon, or a `.node` predating it) or fails.
 *
 * Both rewrite the file exactly once, so route 1 is not the more expensive one —
 * it is the same I/O for a strictly better result. Either way a failure leaves
 * the original file intact; a recording is never lost to a failed repair.
 */
async function repairRecordingContainer(filePath: string, durationMs: number): Promise<void> {
	const reindexed = await reindexRecordingOnDisk(filePath);
	if (reindexed.reindexed) {
		console.info(
			`[recording] re-muxed ${path.basename(filePath)}: ${reindexed.packets} packets, ` +
				`${reindexed.streams} streams, ${reindexed.wallS.toFixed(3)}s`,
		);
		return;
	}
	await patchWebmDurationOnDisk(filePath, durationMs);
}

async function getApprovedProjectSession(
	project: unknown,
	projectFilePath?: string,
): Promise<RecordingSession | null> {
	if (!project || typeof project !== "object") {
		return null;
	}

	const rawProject = project as { media?: unknown; videoPath?: unknown };
	const media: ProjectMedia | null =
		normalizeProjectMedia(rawProject.media) ??
		(typeof rawProject.videoPath === "string"
			? {
					screenVideoPath: normalizeVideoSourcePath(rawProject.videoPath) ?? rawProject.videoPath,
				}
			: null);

	if (!media) {
		return null;
	}

	// Only auto-approve media within the project's dir or the recordings folders, so a crafted
	// project file can't approve reads to arbitrary locations.
	const trustedDirs = getAllowedReadDirs();
	if (projectFilePath) {
		trustedDirs.push(path.dirname(path.resolve(projectFilePath)));
	}

	// Packed/portable projects: when the stored absolute path no longer exists
	// (project moved to another machine or directory), fall back to a file with
	// the same basename next to the project file (see `openscreen pack`).
	const resolveWithSiblingFallback = async (mediaPath: string): Promise<string> => {
		if (!projectFilePath) return mediaPath;
		const exists = await fs
			.stat(mediaPath)
			.then((stats) => stats.isFile())
			.catch(() => false);
		if (exists) return mediaPath;
		const sibling = path.join(
			path.dirname(path.resolve(projectFilePath)),
			path.basename(mediaPath),
		);
		const siblingExists = await fs
			.stat(sibling)
			.then((stats) => stats.isFile())
			.catch(() => false);
		return siblingExists ? sibling : mediaPath;
	};

	const screenVideoPath = await approveReadableVideoPath(
		await resolveWithSiblingFallback(media.screenVideoPath),
		trustedDirs,
	);
	if (!screenVideoPath) {
		throw new Error("Project references an invalid or unsupported screen video path");
	}

	const webcamVideoPath = media.webcamVideoPath
		? await approveReadableVideoPath(
				await resolveWithSiblingFallback(media.webcamVideoPath),
				trustedDirs,
			)
		: undefined;
	if (media.webcamVideoPath && !webcamVideoPath) {
		throw new Error("Project references an invalid or unsupported webcam video path");
	}

	return webcamVideoPath
		? { screenVideoPath, webcamVideoPath, createdAt: Date.now() }
		: { screenVideoPath, createdAt: Date.now() };
}

type SelectedSource = {
	name: string;
	id?: string;
	display_id?: string;
	[key: string]: unknown;
};

type AttachNativeMacWebcamRecordingInput = {
	screenVideoPath?: string;
	recordingId?: number;
	webcam?: RecordedVideoAssetInput;
	cursorCaptureMode?: CursorCaptureMode;
	/**
	 * Webcam clip duration (ms), head start included. A streamed webcam file carries
	 * no Duration header and the renderer no longer holds the blob to patch, so the
	 * main process repairs the container on disk with this value.
	 */
	durationMs?: number;
	/** See {@link ProjectMedia.webcamOffsetMs}. */
	webcamOffsetMs?: number;
};

let selectedSource: SelectedSource | null = null;
let selectedDesktopSource: DesktopCapturerSource | null = null;
let lastEnumeratedSources = new Map<string, DesktopCapturerSource>();
const selectSourceGeneration = { value: 0 };
let currentProjectPath: string | null = null;
let currentRecordingSession: RecordingSession | null = null;

// Durable source of truth for the mic/camera/system-audio/cursor/source
// choices a user makes in the editor's Rec-mode stage, so the HUD window's
// useScreenRecorder (a separate renderer, own process, own React tree) picks
// up those choices instead of silently reverting to its own defaults when
// startNewRecording() switches windows. Persisted in AppSettingsStore and
// broadcast on change; not project content.
export interface RecordingPrefs {
	micEnabled: boolean;
	micDeviceId: string | null;
	/**
	 * The microphone's LABEL, carried beside its id because the native Windows
	 * helper selects by name and Chromium selects by id.
	 *
	 * Without it, a HUD rebuilt for a new recording restored the id and had to
	 * re-derive the name from its own `enumerateDevices()` — which needs a full
	 * getUserMedia permission round-trip first, and an auto-started recording
	 * beat it. The request then went out with no name at all, and the helper
	 * answers that by recording the Windows default endpoint instead of the
	 * microphone the user picked (getopenscreen/openscreen#404).
	 */
	micDeviceName: string | null;
	camEnabled: boolean;
	camDeviceId: string | null;
	/** Camera label paired with the preferred id for restart-safe resolution. */
	camDeviceName: string | null;
	/** Capture resolution for the camera. See WEBCAM_QUALITY_PRESETS. */
	camQuality: WebcamQualityId;
	systemAudioEnabled: boolean;
	cursorCaptureMode: CursorCaptureMode;
	hideDesktopIcons: boolean;
	/** Whether a fresh take gets automatic zooms on import. Persisted; defaults on. */
	autoZoomEnabled: boolean;
}
const defaultRecordingPrefs: RecordingPrefs = {
	micEnabled: false,
	micDeviceId: null,
	micDeviceName: null,
	camEnabled: false,
	camDeviceId: null,
	camDeviceName: null,
	camQuality: DEFAULT_WEBCAM_QUALITY,
	systemAudioEnabled: false,
	cursorCaptureMode: "editable-overlay",
	hideDesktopIcons: false,
	autoZoomEnabled: true,
};

// Cached source from the user's pick. Used by setDisplayMediaRequestHandler in main.ts for cursor-free capture.
export function getSelectedDesktopSource(): DesktopCapturerSource | null {
	return selectedDesktopSource;
}
let currentVideoPath: string | null = null;

function normalizePath(filePath: string) {
	return path.resolve(filePath);
}

function normalizeVideoSourcePath(videoPath?: string | null): string | null {
	if (typeof videoPath !== "string") {
		return null;
	}

	const trimmed = videoPath.trim();
	if (!trimmed) {
		return null;
	}

	if (/^file:\/\//i.test(trimmed)) {
		try {
			return fileURLToPath(trimmed);
		} catch {
			// Fall through and keep best-effort string path below.
		}
	}

	return trimmed;
}

function isTrustedProjectPath(filePath?: string | null) {
	if (!filePath || !currentProjectPath) {
		return false;
	}
	return normalizePath(filePath) === normalizePath(currentProjectPath);
}

const CURSOR_SAMPLE_INTERVAL_MS = 33;
const MAX_CURSOR_SAMPLES = 60 * 60 * 30; // 1 hour @ 30Hz

let cursorRecordingSession: CursorRecordingSession | null = null;
let pendingCursorRecordingData: CursorRecordingData | null = null;
let nativeWindowsCaptureProcess: ChildProcessWithoutNullStreams | null = null;
let nativeWindowsCaptureOutput = "";
let nativeWindowsCaptureTargetPath: string | null = null;
let nativeWindowsCaptureWebcamTargetPath: string | null = null;
let nativeWindowsCaptureRecordingId: number | null = null;
let nativeWindowsCursorOffsetMs = 0;
let nativeWindowsCursorCaptureMode: CursorCaptureMode = "editable-overlay";
let nativeWindowsCursorRecordingStartMs = 0;
let nativeWindowsPauseStartedAtMs: number | null = null;
let nativeWindowsPauseRanges: Array<{ startMs: number; endMs: number }> = [];
let nativeWindowsIsPaused = false;
/**
 * The MP4 flavour the helper reported for THIS run, or null if it never said.
 * Read at stop, not for reporting: it is what decides whether a capture that
 * failed to finalize still left a playable file behind.
 */
let nativeWindowsCaptureContainer: string | null = null;
/** Cuts a surviving helper's output loose so it cannot pollute the next recording. */
let nativeWindowsCaptureDrainCleanup: (() => void) | null = null;

function detachNativeWindowsCaptureOutputDrain() {
	nativeWindowsCaptureDrainCleanup?.();
	nativeWindowsCaptureDrainCleanup = null;
}

function resetNativeWindowsCaptureState() {
	nativeWindowsCaptureDrainCleanup = null;
	nativeWindowsCaptureProcess = null;
	nativeWindowsCaptureTargetPath = null;
	nativeWindowsCaptureWebcamTargetPath = null;
	nativeWindowsCaptureRecordingId = null;
	nativeWindowsCursorOffsetMs = 0;
	nativeWindowsCursorCaptureMode = "editable-overlay";
	nativeWindowsCursorRecordingStartMs = 0;
	nativeWindowsPauseStartedAtMs = null;
	nativeWindowsPauseRanges = [];
	nativeWindowsIsPaused = false;
	nativeWindowsCaptureContainer = null;
}

/** Reads the file, then defers the judgement to the tested predicate. */
async function salvageNativeWindowsFragmentedCapture(screenVideoPath: string | null) {
	if (!screenVideoPath) {
		return false;
	}
	const stats = await fs.stat(screenVideoPath).catch(() => null);
	return isSalvageableFragmentedCapture(nativeWindowsCaptureContainer, stats?.size ?? null);
}

/**
 * Best-effort removal of the files a failed or discarded native Windows capture
 * left behind. Each removal is isolated: a helper that outlived its kill still
 * holds the MP4 open on Windows, and an EBUSY there must not mask why we were
 * cleaning up in the first place.
 */
async function removeNativeWindowsCaptureOutputs(
	screenVideoPath: string | null,
	webcamVideoPath: string | null,
	options: { onlyIfUnusable?: boolean } = {},
) {
	const targets = [
		screenVideoPath,
		webcamVideoPath,
		screenVideoPath ? `${screenVideoPath}.cursor.json` : null,
	];

	for (const target of targets) {
		if (!target || !isPathWithinDir(target, RECORDINGS_DIR)) {
			continue;
		}
		try {
			if (options.onlyIfUnusable && target !== `${screenVideoPath}.cursor.json`) {
				const stats = await fs.stat(target).catch(() => null);
				if (stats && stats.size >= NATIVE_WINDOWS_SALVAGEABLE_OUTPUT_BYTES) {
					console.warn(
						"[native-wgc] keeping a capture output that may still be playable:",
						target,
						stats.size,
					);
					continue;
				}
			}
			await fs.rm(target, { force: true });
		} catch (error) {
			console.warn("[native-wgc] could not remove leftover capture output:", target, error);
		}
	}
}
let nativeMacCaptureProcess: ChildProcessWithoutNullStreams | null = null;
/**
 * Apple's system picker session (macOS 15.2+), started on first use and kept for the app's
 * life: the pick it holds cannot leave that process. See macPickerSession.ts.
 */
let macPickerSession: MacPickerSession | null = null;
let nativeMacCaptureOutput = "";
let nativeMacCaptureTargetPath: string | null = null;
let nativeMacCaptureRecordingId: number | null = null;
let nativeMacCursorOffsetMs = 0;
let nativeMacCursorCaptureMode: CursorCaptureMode = "editable-overlay";
let nativeMacCursorRecordingStartMs = 0;
let nativeMacPauseStartedAtMs: number | null = null;
let nativeMacPauseRanges: Array<{ startMs: number; endMs: number }> = [];
let nativeMacIsPaused = false;
/**
 * How each macOS helper exited, recorded by its output drain on `close` — the
 * point at which its output has been read in full.
 */
const nativeMacCaptureExits = new WeakMap<ChildProcessWithoutNullStreams, NativeMacCaptureExit>();
/**
 * Each macOS helper's own output. The shared `nativeMacCaptureOutput` belongs to
 * the current take; a helper whose stop timed out keeps talking after the next
 * take has started, and its late `recording-stopped` must not settle that take.
 */
const nativeMacCaptureOutputs = new WeakMap<ChildProcessWithoutNullStreams, string>();
/**
 * Why the last macOS take ended before it was stopped, keyed by the file it was
 * kept in. Handed to whatever opens that recording next — the editor or the CLI —
 * because the HUD that ran the stop closes as the editor opens.
 */
let nativeMacRecordingWarning: { screenVideoPath: string; message: string } | null = null;
/** True while stop-native-mac-recording runs: the take is ending on purpose. */
let nativeMacStopInFlight = false;
// Global frame the macOS cursor is normalised against (see getSelectedSourceBounds).
// Seeded from the source frame before the first sample, then replaced by the
// helper's `recording-started.captureBounds` for a window take.
let activeMacCaptureBounds: Rectangle | null = null;
let linuxNativeCaptureSession: LinuxNativeCaptureSession | null = null;
/**
 * The Linux capture helper spawned last, kept after its take ends for Save Diagnostics'
 * `helperOutput.linux`: the same "until the next take starts" lifetime as
 * `nativeWindowsCaptureOutput`. A prepare that was cancelled counts, since its picker
 * answer is what a report about it needs.
 */
let lastLinuxCaptureSession: LinuxNativeCaptureSession | null = null;
let linuxNativeCaptureRecordingId: number | null = null;
let linuxNativeCaptureCursorMode: CursorCaptureMode = "editable-overlay";
/** What the portal granted for the running capture, for the tray's label. */
let linuxNativeCaptureSourceLabel: string | null = null;
/**
 * A portal session negotiated ahead of the countdown, waiting to be armed.
 *
 * Held here rather than in the renderer because the helper is a child process of
 * THIS process: a renderer that reloads, or a countdown abandoned without a
 * cancel, would otherwise leak a live ScreenCast session — the compositor's
 * "screen is being shared" indicator with nothing recording behind it.
 */
let preparedLinuxCapture: {
	session: LinuxNativeCaptureSession;
	outputPath: string;
	/** What the helper was actually spawned with. See [`captureSettingsOf`]. */
	request: NativeLinuxRecordingRequest;
} | null = null;
/**
 * Identifies the prepare that is still waiting on the picker.
 *
 * The slot above is only filled AFTER an await with no upper bound — a human is
 * reading a dialog. For that whole window it is null, so without this token a
 * cancel would find nothing to cancel and a second prepare would find nothing to
 * supersede: the first session would then assign itself afterwards and stay
 * alive, holding a ScreenCast grant and the compositor's sharing indicator with
 * nothing recording behind it.
 */
let preparingLinuxCaptureToken: symbol | null = null;

/**
 * Claims the prepared session when it matches the recording about to start.
 *
 * A mismatch means the prepare was for a recording that never happened, so it is
 * discarded rather than reused: arming it would record against the wrong output
 * path, and leaving it would strand a portal session.
 */
function takePreparedLinuxSession(
	outputPath: string,
	request: NativeLinuxRecordingRequest,
): LinuxNativeCaptureSession | null {
	const prepared = preparedLinuxCapture;
	if (!prepared) {
		return null;
	}
	preparedLinuxCapture = null;
	if (prepared.outputPath !== outputPath) {
		console.warn("[native-linux] discarding a prepared session for a different recording");
		prepared.session.discard();
		return null;
	}
	// EVERY CAPTURE SETTING IS FIXED AT SPAWN. `arm()` only writes `record`, so a
	// prepared helper is already running with the audio and cursor settings it
	// was created with — and the HUD does not lock its controls during the
	// countdown, so the user really can change them in between. Reusing the
	// session would record one thing while the app believed another, including
	// the cursor mode that decides whether the editor draws its own pointer.
	if (captureSettingsOf(prepared.request) !== captureSettingsOf(request)) {
		console.info("[native-linux] settings changed during the countdown; renegotiating");
		prepared.session.discard();
		return null;
	}
	return prepared.session;
}

/** The request fields baked into the helper's spawn arguments, canonicalised. */
function captureSettingsOf(request: NativeLinuxRecordingRequest): string {
	return JSON.stringify({
		fps: request.video?.fps ?? null,
		bitrate: request.video?.bitrate ?? null,
		system: request.audio?.system?.enabled ?? false,
		microphone: request.audio?.microphone?.enabled ?? false,
		deviceName: request.audio?.microphone?.deviceName ?? null,
		gain: request.audio?.microphone?.gain ?? null,
		cursor: normalizeCursorCaptureMode(request?.cursor?.mode) ?? "editable-overlay",
	});
}

/** Tears down a prepared-but-unarmed session, e.g. an abandoned countdown. */
function discardPreparedLinuxCapture(reason: string) {
	// Invalidate any negotiation still in flight, so the session it is about to
	// produce is discarded on arrival instead of stranded.
	preparingLinuxCaptureToken = null;
	if (!preparedLinuxCapture) {
		return;
	}
	console.info(`[native-linux] discarding the prepared capture: ${reason}`);
	preparedLinuxCapture.session.discard();
	preparedLinuxCapture = null;
}

/**
 * Names what the portal handed over, for the tray tooltip.
 *
 * There is no window title to show: the ScreenCast portal reports a kind and a
 * PipeWire node id, never a name. Reporting the kind is the most that can be
 * said honestly, and an unknown kind stays unknown — calling it "Screen" would
 * be the same guess that put a window's name on a full-screen recording.
 */
function linuxSourceLabel(kind?: LinuxCaptureSourceKind): string {
	switch (kind) {
		case "window":
			return mainT("common", "recordingSource.window");
		case "monitor":
			return mainT("common", "recordingSource.screen");
		case "virtual":
			return mainT("common", "recordingSource.virtual");
		default:
			return mainT("common", "recordingSource.unknown");
	}
}
/**
 * NO PORTAL RESTORE TOKEN IS KEPT, AND THAT IS DELIBERATE.
 *
 * A token used to be persisted here so the compositor's picker would not appear
 * on every recording. It is gone because it made "record this window" record the
 * whole screen instead. A restore token is bound to the source it was minted
 * for, so once any monitor had been approved the portal restored that monitor on
 * every later run and stopped raising the picker at all — and `SelectSources`
 * has no parameter naming a source, so the app could not ask for anything else.
 * On Wayland the picker IS the source chooser; suppressing it left the user with
 * no way to change what they were recording.
 *
 * Answering the picker each time is the cost of being able to choose at all.
 */

// ponytail: the sidecar readers used to live here, ~150 lines of parsing wedged
// between the capture state machine and the asset-path helpers, reachable only
// through IPC. They now live in `electron/media/cursorSidecar.ts` — Node-pure,
// injectable, testable — because the agent needed to read the same file and
// could not import an IPC handler. What is left here is the binding of
// `RECORDINGS_DIR` (an `app.getPath` at main-module scope) to those readers.
//
// ponytail: a FUNCTION, not a captured object. `main.ts` imports this module and
// this module imports `RECORDINGS_DIR` back from it, so at the moment this file
// is evaluated that binding is still in its temporal dead zone — reading it here
// threw `Cannot access 'RECORDINGS_DIR' before initialization` and the app died
// before its first window. Every call site is already inside a handler, i.e.
// long after both modules finished loading.
//
// The media-links registry stays in the DEFAULT folder whichever folder takes are written
// to, here and at every other registry call: the links registered before the user picked
// another folder must still be found after it.
const cursorSidecarOptions = () => ({ recordingsDir: DEFAULT_RECORDINGS_DIR });

const readCursorRecordingFile = (targetVideoPath: string) =>
	readCursorRecordingFileFrom(targetVideoPath, cursorSidecarOptions());

const readCursorTelemetryFile = (targetVideoPath: string) =>
	readCursorTelemetryFileFrom(targetVideoPath, cursorSidecarOptions());

/**
 * The agent's door onto cursor telemetry — the last mile of D-TELEM.
 *
 * ponytail: `resolveApprovedVideoPath` is not ceremony. The asset path comes
 * from the DOCUMENT rather than from the model, but the document is a file on
 * disk that the user (or a future import path) can put anything in, and the
 * sidecar path is DERIVED from it. Reusing the same allow-list the video loaders
 * use means a crafted `originalPath` cannot walk this into reading an arbitrary
 * JSON file. A refused path yields "unavailable", not "no-sidecar": we did not
 * look, and the model must not report otherwise.
 */
const agentCursorTelemetryReader: CursorTelemetryReader = {
	probe: async ({ originalPath }) => {
		const approved = resolveApprovedVideoPath(originalPath);
		if (!approved) return false;
		return (await readCursorSidecar(approved, cursorSidecarOptions())).found;
	},
	read: async ({ assetId, originalPath }) => {
		const approved = resolveApprovedVideoPath(originalPath);
		if (!approved) {
			return {
				status: "unavailable",
				assetId,
				note: "The asset's file is outside the folders this app may read, so its cursor sidecar was not opened.",
			};
		}
		const sidecar = await readCursorSidecar(approved, cursorSidecarOptions());
		if (!sidecar.found) return { status: "no-sidecar", assetId };
		return { status: "ok", assetId, samples: sidecar.data.samples };
	},
};

function resolveAssetBasePath() {
	try {
		if (app.isPackaged) {
			const assetPath = path.join(process.resourcesPath, "assets");
			return pathToFileURL(`${assetPath}${path.sep}`).toString();
		}
		const assetPath = path.join(app.getAppPath(), "public", "assets");
		return pathToFileURL(`${assetPath}${path.sep}`).toString();
	} catch (err) {
		console.error("Failed to resolve asset base path:", err);
		return null;
	}
}

/** Whether sources come from Apple's picker in this run. */
function macPickerOwnsSources() {
	return macSystemPickerEnabled();
}

async function getMacPickerSession(): Promise<MacPickerSession | null> {
	if (!macPickerOwnsSources()) {
		return null;
	}
	if (macPickerSession) {
		return macPickerSession;
	}
	const helperPath = await findNativeMacCaptureHelperPath();
	const session = helperPath ? new MacPickerSession(helperPath) : null;
	if (!session || !(await session.start())) {
		// A helper that predates `--picker-session`, or none at all: the app's own picker
		// and the Screen Recording grant, for the rest of this run.
		console.warn("[mac-picker] falling back to the app's own source picker");
		markMacSystemPickerUnavailable();
		return null;
	}
	macPickerSession = session;
	return session;
}

function selectedSourceFromPick(
	pick: MacPickerSelection,
): SelectedSource & { id: string; display_id: string } {
	const display =
		pick.displayId !== null
			? screen.getAllDisplays().find((candidate) => candidate.id === pick.displayId)
			: undefined;
	const name =
		pick.kind === "window" ? pick.title || pick.appName || "Window" : display?.label || "Screen";
	return {
		id: `${MAC_PICKER_SOURCE_PREFIX}${pick.kind}:${pick.windowId ?? pick.displayId ?? 0}`,
		name,
		display_id: pick.displayId !== null ? String(pick.displayId) : "",
	};
}

/** Legacy `window:` ids and a window chosen in Apple's picker. Display picks are not. */
function isMacWindowCaptureSourceId(sourceId: string | null | undefined) {
	return (
		typeof sourceId === "string" &&
		(sourceId.startsWith("window:") || sourceId.startsWith(`${MAC_PICKER_SOURCE_PREFIX}window:`))
	);
}

function getSelectedSourceBounds() {
	// A window take is normalised against the rect the helper is recording. That
	// rect is seeded from the source frame before the first cursor sample and
	// replaced by `recording-started.captureBounds`, the ScreenCaptureKit content
	// rect. The picker's frame and the display bounds must not stay in charge for
	// the take: either one leaves the pointer above the click (#1130).
	if (isMacWindowCaptureSourceId(selectedSource?.id) && activeMacCaptureBounds) {
		return activeMacCaptureBounds;
	}

	// A pick from Apple's picker carries its own frame; there is no desktopCapturer
	// display to look up for it. Display picks keep this frame for the whole take.
	if (isMacPickerSourceId(selectedSource?.id)) {
		const pick = macPickerSession?.getSelection();
		if (pick) {
			return pick.bounds;
		}
	}

	const cursor = screen.getCursorScreenPoint();
	const sourceDisplayId = Number(selectedSource?.display_id);
	const sourceDisplay = Number.isFinite(sourceDisplayId)
		? (screen.getAllDisplays().find((display) => display.id === sourceDisplayId) ?? null)
		: null;
	return (sourceDisplay ?? screen.getDisplayNearestPoint(cursor)).bounds;
}

function getSelectedSourceId() {
	return typeof selectedSource?.id === "string" ? selectedSource.id : null;
}

function getSelectedDisplay() {
	const sourceDisplayId = Number(selectedSource?.display_id);
	if (!Number.isFinite(sourceDisplayId)) {
		return null;
	}

	return screen.getAllDisplays().find((display) => display.id === sourceDisplayId) ?? null;
}

function resolveUnpackedAppPath(...segments: string[]) {
	const resolved = path.join(app.getAppPath(), ...segments);
	if (app.isPackaged) {
		return resolved.replace(/\.asar([/\\])/, ".asar.unpacked$1");
	}

	return resolved;
}

function resolvePackagedResourcePath(...segments: string[]) {
	if (!app.isPackaged) {
		return null;
	}

	return path.join(process.resourcesPath, ...segments);
}

function getNativeWindowsCaptureHelperCandidates() {
	const envPath = process.env.OPENSCREEN_WGC_CAPTURE_EXE?.trim();
	const archTag = process.arch === "arm64" ? "win32-arm64" : "win32-x64";
	return [
		envPath,
		resolveUnpackedAppPath(
			"electron",
			"native",
			"wgc-capture",
			"build",
			"Release",
			"wgc-capture.exe",
		),
		resolveUnpackedAppPath("electron", "native", "wgc-capture", "build", "wgc-capture.exe"),
		resolveUnpackedAppPath("electron", "native", "bin", archTag, "wgc-capture.exe"),
		resolvePackagedResourcePath("electron", "native", "bin", archTag, "wgc-capture.exe"),
	].filter((candidate): candidate is string => Boolean(candidate));
}

async function findNativeWindowsCaptureHelperPath() {
	if (process.platform !== "win32") {
		return null;
	}

	for (const candidate of getNativeWindowsCaptureHelperCandidates()) {
		try {
			await fs.access(candidate, fsConstants.X_OK);
			return candidate;
		} catch {
			// Try the next configured helper location.
		}
	}

	return null;
}

function getNativeMacCaptureHelperCandidates() {
	const envPath = process.env.OPENSCREEN_SCK_CAPTURE_EXE?.trim();
	const archTag = process.arch === "arm64" ? "darwin-arm64" : "darwin-x64";
	const helperName = "openscreen-screencapturekit-helper";
	return [
		envPath,
		resolveUnpackedAppPath("electron", "native", "screencapturekit", "build", helperName),
		resolveUnpackedAppPath("electron", "native", "bin", archTag, helperName),
		resolvePackagedResourcePath("electron", "native", "bin", archTag, helperName),
	].filter((candidate): candidate is string => Boolean(candidate));
}

async function findNativeMacCaptureHelperPath() {
	if (process.platform !== "darwin") {
		return null;
	}

	for (const candidate of getNativeMacCaptureHelperCandidates()) {
		try {
			await fs.access(candidate, fsConstants.X_OK);
			return candidate;
		} catch {
			// Try the next configured helper location.
		}
	}

	return null;
}

function isWindowsGraphicsCaptureOsSupported() {
	if (process.platform !== "win32") {
		return false;
	}

	const [, , build] = process.getSystemVersion().split(".").map(Number);
	return Number.isFinite(build) && build >= 19041;
}

function queryDirectShowVideoInputRegistry() {
	return new Promise<string>((resolve) => {
		const proc = spawn(
			"reg.exe",
			["query", "HKCR\\CLSID\\{860BB310-5D01-11D0-BD3B-00A0C911CE86}\\Instance", "/s"],
			{ windowsHide: true },
		);
		let stdout = "";
		proc.stdout.on("data", (chunk: Buffer) => {
			stdout += chunk.toString("utf16le").includes("\u0000")
				? chunk.toString("utf16le")
				: chunk.toString();
		});
		proc.on("close", () => resolve(stdout));
		proc.on("error", () => resolve(""));
	});
}

async function resolveDirectShowWebcamClsid(deviceName?: string) {
	if (process.platform !== "win32" || !deviceName?.trim()) {
		return null;
	}

	const output = await queryDirectShowVideoInputRegistry();
	let current: { friendlyName?: string; clsid?: string } = {};
	const entries: Array<{ friendlyName?: string; clsid?: string }> = [];
	for (const rawLine of output.split(/\r?\n/)) {
		const line = rawLine.trim();
		if (!line) continue;
		if (/^HKEY_/i.test(line)) {
			if (current.friendlyName || current.clsid) entries.push(current);
			current = {};
			continue;
		}
		const match = line.match(/^(\S+)\s+REG_SZ\s+(.+)$/);
		if (!match) continue;
		if (match[1] === "FriendlyName") current.friendlyName = match[2].trim();
		if (match[1] === "CLSID") current.clsid = match[2].trim();
	}
	if (current.friendlyName || current.clsid) entries.push(current);

	let best: { clsid: string; friendlyName?: string; score: number } | null = null;
	for (const entry of entries) {
		if (!entry.clsid) continue;
		const score = scoreDeviceNameMatch(entry.friendlyName ?? "", entry.clsid, deviceName);
		if (!best || score > best.score) {
			best = { clsid: entry.clsid, friendlyName: entry.friendlyName, score };
		}
	}

	if (!best || best.score <= 0) {
		return null;
	}

	console.info("[native-wgc] resolved DirectShow webcam filter", {
		requestedName: deviceName,
		filterName: best.friendlyName,
		clsid: best.clsid,
		score: best.score,
	});
	return best.clsid;
}

async function startCursorRecording(recordingId?: number) {
	// On Linux the native capture helper already produces cursor samples, from
	// the SAME portal session that produces the pixels. Spawning the cursor-only
	// helper alongside it would open a SECOND portal session — and since
	// SelectSources may be called once per session, that means a second picker
	// in front of the user, for a stream nothing consumes. The double prompt is
	// precisely what the native path exists to remove.
	if (linuxNativeCaptureSession) {
		return;
	}

	if (cursorRecordingSession) {
		pendingCursorRecordingData = await cursorRecordingSession.stop();
		cursorRecordingSession = null;
	}

	pendingCursorRecordingData = null;
	cursorRecordingSession = createCursorRecordingSession({
		getDisplayBounds: getSelectedSourceBounds,
		maxSamples: MAX_CURSOR_SAMPLES,
		platform: process.platform,
		sampleIntervalMs: CURSOR_SAMPLE_INTERVAL_MS,
		sourceId: getSelectedSourceId(),
		startTimeMs:
			typeof recordingId === "number" && Number.isFinite(recordingId) ? recordingId : undefined,
	});

	try {
		await cursorRecordingSession.start();
	} catch (error) {
		console.error("Failed to start cursor recording session:", error);
		cursorRecordingSession = null;
	}
}

async function stopCursorRecording() {
	if (!cursorRecordingSession) {
		return;
	}

	try {
		pendingCursorRecordingData = await cursorRecordingSession.stop();
	} catch (error) {
		console.error("Failed to stop cursor recording session:", error);
		pendingCursorRecordingData = null;
	} finally {
		cursorRecordingSession = null;
	}
}

async function writePendingCursorTelemetry(videoPath: string) {
	const telemetryPath = `${videoPath}.cursor.json`;
	if (pendingCursorRecordingData && pendingCursorRecordingData.samples.length > 0) {
		await fs.writeFile(telemetryPath, JSON.stringify(pendingCursorRecordingData, null, 2), "utf-8");
	}
	pendingCursorRecordingData = null;
}

// P4 — proactively seeds the media-links registry for a fresh recording so
// its camera/cursor-telemetry links can still be found later even if the
// screen video is moved, renamed, or imported into a different project.
// Best-effort: a registry write hiccup must never fail the recording flow.
async function registerRecordingMediaLinks(
	screenVideoPath: string,
	options: {
		webcamVideoPath?: string;
		webcamOffsetMs?: number;
		cursorCaptureMode?: CursorCaptureMode;
	},
) {
	try {
		const cursorTelemetryPath = `${screenVideoPath}.cursor.json`;
		const hasCursorTelemetry = await fs
			.access(cursorTelemetryPath, fsConstants.F_OK)
			.then(() => true)
			.catch(() => false);
		await registerMediaLinks(DEFAULT_RECORDINGS_DIR, screenVideoPath, {
			...(options.webcamVideoPath ? { webcamVideoPath: options.webcamVideoPath } : {}),
			...(options.webcamVideoPath && Number.isFinite(options.webcamOffsetMs)
				? { webcamOffsetMs: options.webcamOffsetMs }
				: {}),
			...(hasCursorTelemetry ? { cursorTelemetryPath } : {}),
			...(options.cursorCaptureMode ? { cursorCaptureMode: options.cursorCaptureMode } : {}),
		});
	} catch (error) {
		console.warn("[media-links] failed to register recording links:", error);
	}
}

function shiftPendingCursorTelemetry(offsetMs: number) {
	if (!pendingCursorRecordingData || !Number.isFinite(offsetMs) || offsetMs <= 0) {
		return;
	}

	pendingCursorRecordingData = {
		...pendingCursorRecordingData,
		samples: pendingCursorRecordingData.samples
			.map((sample) => ({
				...sample,
				timeMs: Math.max(0, sample.timeMs - offsetMs),
			}))
			.sort((a, b) => a.timeMs - b.timeMs),
	};
}

function compactPendingCursorTelemetryPauseRanges(
	ranges: Array<{ startMs: number; endMs: number }>,
) {
	if (!pendingCursorRecordingData) return;
	pendingCursorRecordingData = compactCursorTelemetryPauseRanges(
		pendingCursorRecordingData,
		ranges,
	);
}

function completeNativeMacCursorPauseRange(endMs = Date.now()) {
	if (nativeMacPauseStartedAtMs === null || nativeMacCursorRecordingStartMs <= 0) {
		return;
	}

	nativeMacPauseRanges.push({
		startMs: Math.max(0, nativeMacPauseStartedAtMs - nativeMacCursorRecordingStartMs),
		endMs: Math.max(0, endMs - nativeMacCursorRecordingStartMs),
	});
	nativeMacPauseStartedAtMs = null;
}

function completeNativeWindowsCursorPauseRange(endMs = Date.now()) {
	if (nativeWindowsPauseStartedAtMs === null || nativeWindowsCursorRecordingStartMs <= 0) {
		return;
	}

	nativeWindowsPauseRanges.push({
		startMs: Math.max(0, nativeWindowsPauseStartedAtMs - nativeWindowsCursorRecordingStartMs),
		endMs: Math.max(0, endMs - nativeWindowsCursorRecordingStartMs),
	});
	nativeWindowsPauseStartedAtMs = null;
}

function waitForNativeWindowsCaptureStart(proc: ChildProcessWithoutNullStreams) {
	return new Promise<void>((resolve, reject) => {
		const timer = setTimeout(() => {
			cleanup();
			reject(new Error("Timed out waiting for native Windows capture to start"));
		}, 12000);

		// Observes only. `attachNativeWindowsCaptureOutputDrain` is the single
		// writer of `nativeWindowsCaptureOutput` and is registered first, so the
		// chunk that triggers this call is already in the buffer.
		const onOutput = () => {
			if (nativeWindowsCaptureOutput.includes("Recording started")) {
				cleanup();
				resolve();
			}
		};
		const onError = (error: Error) => {
			cleanup();
			reject(error);
		};
		const onExit = (code: number | null) => {
			cleanup();
			reject(
				new Error(
					nativeWindowsCaptureOutput.trim() ||
						`Native Windows capture exited before recording started (code=${code ?? "unknown"})`,
				),
			);
		};
		const cleanup = () => {
			clearTimeout(timer);
			proc.stdout.off("data", onOutput);
			proc.stderr.off("data", onOutput);
			proc.off("error", onError);
			proc.off("exit", onExit);
		};

		proc.stdout.on("data", onOutput);
		proc.stderr.on("data", onOutput);
		proc.once("error", onError);
		proc.once("exit", onExit);
	});
}

/**
 * Keeps reading the helper for as long as it lives.
 *
 * `waitForNativeWindowsCaptureStart` drops every listener the moment it sees
 * "Recording started", so until this existed the whole recording ran unobserved:
 * helper warnings and `[stop-timing]` diagnostics were discarded, which is why
 * issue #252 had no helper-side evidence from a real app run and had to be
 * reproduced by driving the .exe by hand. macOS has had this since it shipped
 * (`attachNativeMacCaptureOutputDrain`); Windows never did.
 */
function attachNativeWindowsCaptureOutputDrain(proc: ChildProcessWithoutNullStreams) {
	const drain = (chunk: Buffer) => {
		nativeWindowsCaptureOutput += chunk.toString();
	};
	const cleanup = () => {
		proc.stdout.off("data", drain);
		proc.stderr.off("data", drain);
	};

	proc.stdout.on("data", drain);
	proc.stderr.on("data", drain);
	proc.once("close", cleanup);
	// An 'error' event with no listener throws, and in the main process that is
	// an uncaught exception rather than a rejected promise. Both streams need a
	// sink for the whole life of the helper: stdin raises EPIPE when the helper
	// died before we wrote to it, and `kill()` on a wedged process re-emits its
	// failure on the ChildProcess itself.
	// All four emitters, not just stdin: `cleanup` only drops 'data', so an
	// abandoned-but-still-alive helper leaves these pipes open with no consumer,
	// and an ECONNRESET when the OS finally reaps it would take down the main
	// process.
	proc.stdin.on("error", (error) => {
		console.warn("[native-wgc] helper stdin error:", error);
	});
	proc.stdout.on("error", (error) => {
		console.warn("[native-wgc] helper stdout error:", error);
	});
	proc.stderr.on("error", (error) => {
		console.warn("[native-wgc] helper stderr error:", error);
	});
	proc.on("error", (error) => {
		console.warn("[native-wgc] helper process error:", error);
	});

	// Returned so an abandoned helper can be cut loose. A process that survived
	// both kill attempts keeps writing, and `nativeWindowsCaptureOutput` is
	// shared with whatever recording starts next.
	return cleanup;
}

/**
 * Sends `stop` and closes the command channel behind it.
 *
 * The helper treats stdin EOF as a stop too, so ending the stream is a free
 * second signal if the write itself is lost.
 */
function sendNativeWindowsStopCommand(proc: ChildProcessWithoutNullStreams) {
	if (!proc.stdin.writable) {
		return false;
	}

	proc.stdin.write("stop\n");
	proc.stdin.end();
	return true;
}

function readNativeWindowsEncoderSelection(output: string) {
	const lines = output
		.split(/\r?\n/)
		.filter((line) => line.includes('"event":"encoder-selection"'));
	const lastLine = lines.at(-1);
	if (!lastLine) {
		return null;
	}

	try {
		return JSON.parse(lastLine) as {
			video?: string;
			// Which MP4 flavour the helper actually wrote, `fragmented-mp4` or
			// `mp4`. It reports this because the fragmented sink degrades to the
			// plain one rather than failing a recording, so the flavour is a
			// per-run outcome and not a property of the version. This is the only
			// thing that can answer "was this file supposed to survive a kill?",
			// which is what `salvageNativeWindowsFragmentedCapture` asks.
			container?: string;
			preferSoftwareEncoder?: boolean;
			// Whether BeginWriting() actually landed on a hardware H.264 MFT, as
			// opposed to `video` above, which only says which configuration path
			// was tried. "default" plus a software runtime means the machine never
			// got hardware acceleration in the first place -- see
			// kVideoEncoderRuntime* in mf_encoder.h.
			videoEncoderRuntime?: string;
		};
	} catch {
		return null;
	}
}

function tryParseNativeHelperEvent(line: string) {
	try {
		const parsed = JSON.parse(line);
		return parsed && typeof parsed === "object" ? parsed : null;
	} catch {
		return null;
	}
}

function dispatchNativeMacHelperEvent(event: Record<string, unknown>) {
	const bounds = event.captureBounds as Rectangle | undefined;
	// Display takes never adopt this rect: their cursor stays on the display bounds.
	// Adopting it there would move a capture whose alignment is already right.
	if (
		isMacWindowCaptureSourceId(selectedSource?.id) &&
		bounds &&
		bounds.width > 0 &&
		bounds.height > 0
	) {
		activeMacCaptureBounds = bounds;
		cursorRecordingSession?.updateCaptureBounds?.(bounds);
	}
	nativeMacCaptureEvents.emit("helper-event", event);
}

function inspectNativeMacCaptureOutput() {
	for (const line of nativeMacCaptureOutput.split(/\r?\n/)) {
		const event = tryParseNativeHelperEvent(line.trim());
		if (event) {
			dispatchNativeMacHelperEvent(event);
		}
	}
}

function attachNativeMacCaptureOutputDrain(
	proc: ChildProcessWithoutNullStreams,
	onTakeEnded: () => void,
	onSystemAudioUnavailable: () => void,
) {
	let lineBuffer = "";
	// Hooked here rather than on `nativeMacCaptureEvents`, which the start wait
	// replays from the buffer: the drain sees each line once, live.
	const watchLiveTake = createNativeMacMidCaptureErrorWatch(
		() => nativeMacCaptureProcess === proc && !nativeMacStopInFlight,
		onTakeEnded,
		onSystemAudioUnavailable,
	);
	const drain = (chunk: Buffer) => {
		const text = chunk.toString();
		nativeMacCaptureOutputs.set(proc, (nativeMacCaptureOutputs.get(proc) ?? "") + text);
		// Only the current take's helper feeds the shared buffer and event bus that the
		// start wait, the microphone check and the diagnostics bundle read.
		const isCurrent = nativeMacCaptureProcess === proc;
		if (isCurrent) {
			nativeMacCaptureOutput += text;
		}
		lineBuffer += text;
		const lines = lineBuffer.split(/\r?\n/);
		lineBuffer = lines.pop() ?? "";
		for (const line of lines) {
			const event = tryParseNativeHelperEvent(line.trim());
			if (event) {
				if (isCurrent) {
					dispatchNativeMacHelperEvent(event);
				}
				watchLiveTake(event);
			}
		}
	};
	// Registered right after spawn, before the stop wait can listen for `close`, so
	// the wait always finds the exit recorded when its own listener runs.
	const onClose = (code: number | null, signal: NodeJS.Signals | null) => {
		nativeMacCaptureExits.set(proc, { code, signal });
		proc.stdout.off("data", drain);
		proc.stderr.off("data", drain);
		watchLiveTake.exited();
	};

	proc.stdout.on("data", drain);
	proc.stderr.on("data", drain);
	proc.once("close", onClose);
	// A ChildProcess `error` with no listener throws in the main process.
	proc.on("error", (error) => {
		console.warn("[native-sck] helper process error:", error);
	});
	// `sendNativeMacStopCommand` checks the pipe first, but the helper can still die
	// between that check and the write. The main-process guard would swallow the
	// EPIPE; a listener here keeps it from being raised as uncaught at all.
	proc.stdin.on("error", (error) => {
		console.warn("[native-sck] helper command pipe error:", error);
	});
	// The output pipes too, as the Windows drain does: the guard only swallows a few
	// codes, and any other stream error would take the main process down.
	proc.stdout.on("error", (error) => {
		console.warn("[native-sck] helper stdout error:", error);
	});
	proc.stderr.on("error", (error) => {
		console.warn("[native-sck] helper stderr error:", error);
	});
}

/**
 * Resolves with the helper's own stamp of its first appended frame: the file's t=0, and
 * so the instant the HUD timer counts from (#901). Null from a helper that sends none.
 */
function waitForNativeMacCaptureStart(proc: ChildProcessWithoutNullStreams) {
	return new Promise<number | null>((resolve, reject) => {
		const timer = setTimeout(() => {
			cleanup();
			reject(new Error("Timed out waiting for native macOS capture to start"));
		}, 10_000);

		const inspect = (event: Record<string, unknown>) => {
			if (event.event === "recording-started") {
				cleanup();
				resolve(
					typeof event.timestampMs === "number" && Number.isFinite(event.timestampMs)
						? event.timestampMs
						: null,
				);
				return;
			}
			if (event.event === "error") {
				cleanup();
				reject(new Error(String(event.message ?? event.code ?? "Native macOS capture failed")));
			}
		};

		const onOutput = (event: Record<string, unknown>) => inspect(event);
		const onClose = (code: number | null) => {
			cleanup();
			reject(
				new Error(
					nativeMacCaptureOutput.trim() ||
						`Native macOS capture exited before recording started (code=${code ?? "unknown"})`,
				),
			);
		};
		const onError = (error: Error) => {
			cleanup();
			reject(error);
		};
		const cleanup = () => {
			clearTimeout(timer);
			nativeMacCaptureEvents.off("helper-event", onOutput);
			proc.off("close", onClose);
			proc.off("error", onError);
		};

		nativeMacCaptureEvents.on("helper-event", onOutput);
		proc.once("close", onClose);
		proc.once("error", onError);
		inspectNativeMacCaptureOutput();
	});
}

function setCurrentRecordingSessionState(session: RecordingSession | null) {
	currentRecordingSession = session;
	currentVideoPath = session?.screenVideoPath ?? null;
}

function getSessionManifestPathForVideo(videoPath: string) {
	const parsedPath = path.parse(videoPath);
	const baseName = parsedPath.name.endsWith("-webcam")
		? parsedPath.name.slice(0, -"-webcam".length)
		: parsedPath.name;
	return path.join(parsedPath.dir, `${baseName}${RECORDING_SESSION_SUFFIX}`);
}

async function loadRecordedSessionForVideoPath(
	videoPath: string,
): Promise<RecordingSession | null> {
	try {
		const manifestPath = getSessionManifestPathForVideo(videoPath);
		if (!isPathAllowed(manifestPath)) {
			const parsedVideoPath = path.parse(videoPath);
			if (!isPathWithinDir(path.resolve(manifestPath), parsedVideoPath.dir)) {
				return null;
			}
		}

		const content = await fs.readFile(manifestPath, "utf-8");
		const session = normalizeRecordingSession(JSON.parse(content));
		if (!session) {
			return null;
		}

		const normalizedVideoPath = normalizePath(videoPath);
		const matchesScreen = normalizePath(session.screenVideoPath) === normalizedVideoPath;
		const matchesWebcam =
			typeof session.webcamVideoPath === "string" &&
			normalizePath(session.webcamVideoPath) === normalizedVideoPath;
		if (!matchesScreen && !matchesWebcam) {
			return null;
		}

		if (!isPathAllowed(session.screenVideoPath)) {
			const approvedScreen = await approveReadableVideoPath(session.screenVideoPath, [
				path.dirname(manifestPath),
				RECORDINGS_DIR,
			]);
			if (!approvedScreen) {
				return null;
			}
			session.screenVideoPath = approvedScreen;
		}

		if (session.webcamVideoPath && !isPathAllowed(session.webcamVideoPath)) {
			const approvedWebcam = await approveReadableVideoPath(session.webcamVideoPath, [
				path.dirname(manifestPath),
				RECORDINGS_DIR,
			]);
			if (!approvedWebcam) {
				session.webcamVideoPath = undefined;
			} else {
				session.webcamVideoPath = approvedWebcam;
			}
		}

		approveFilePath(session.screenVideoPath);
		if (session.webcamVideoPath) {
			approveFilePath(session.webcamVideoPath);
		}
		return session;
	} catch (error) {
		const nodeError = error as NodeJS.ErrnoException;
		if (nodeError.code !== "ENOENT") {
			console.error("Failed to restore recording session manifest:", error);
		}
		return null;
	}
}

// P4 — resolves the camera (and cursor-telemetry path, though callers that
// only care about the camera can ignore it) for a screen-recording video,
// trying the cheap path-adjacency sidecar first (handles "just recorded" and
// pre-existing recordings) and falling back to the fingerprint registry
// (handles the file having been moved/renamed/imported from elsewhere).
// `videoPath` must already be normalized + approved by the caller.
async function resolveMediaLinksForVideo(videoPath: string): Promise<{
	webcamVideoPath?: string;
	webcamOffsetMs?: number;
	cursorTelemetryPath?: string;
	resolvedVia: "sidecar" | "fingerprint" | "none";
}> {
	const session = await loadRecordedSessionForVideoPath(videoPath);
	const cursorTelemetryPath = `${videoPath}.cursor.json`;
	const hasCursorTelemetry = await fs
		.access(cursorTelemetryPath, fsConstants.F_OK)
		.then(() => true)
		.catch(() => false);

	if (session?.webcamVideoPath || hasCursorTelemetry) {
		// Opportunistic backfill so the link survives a later move even if this
		// recording predates the registry, or if its sidecar doesn't travel with it.
		await registerMediaLinks(DEFAULT_RECORDINGS_DIR, videoPath, {
			...(session?.webcamVideoPath ? { webcamVideoPath: session.webcamVideoPath } : {}),
			...(session?.webcamVideoPath && Number.isFinite(session.webcamOffsetMs)
				? { webcamOffsetMs: session.webcamOffsetMs }
				: {}),
			...(hasCursorTelemetry ? { cursorTelemetryPath } : {}),
		}).catch((error) => console.warn("[media-links] backfill failed:", error));

		return {
			...(session?.webcamVideoPath
				? {
						webcamVideoPath: session.webcamVideoPath,
						webcamOffsetMs: session.webcamOffsetMs ?? 0,
					}
				: {}),
			...(hasCursorTelemetry ? { cursorTelemetryPath } : {}),
			resolvedVia: "sidecar",
		};
	}

	try {
		const links = await findMediaLinksByFingerprint(DEFAULT_RECORDINGS_DIR, videoPath);
		if (links?.webcamVideoPath || links?.cursorTelemetryPath) {
			let webcamVideoPath = links.webcamVideoPath;
			if (webcamVideoPath && !isPathAllowed(webcamVideoPath)) {
				webcamVideoPath =
					(await approveReadableVideoPath(webcamVideoPath, getAllowedReadDirs())) ?? undefined;
			}
			return {
				...(webcamVideoPath ? { webcamVideoPath, webcamOffsetMs: links.webcamOffsetMs ?? 0 } : {}),
				...(links.cursorTelemetryPath ? { cursorTelemetryPath: links.cursorTelemetryPath } : {}),
				resolvedVia: "fingerprint",
			};
		}
	} catch (error) {
		console.warn("[media-links] fingerprint lookup failed:", error);
	}

	return { resolvedVia: "none" };
}

/**
 * Writes the diagnostic bundle a bug report needs, as a `.zip`: `diagnostic.json` with
 * app/OS facts, the native helpers' raw stdout/stderr (which is where `[stop-timing]` and
 * `encoder-selection` land — see nativeWindowsCaptureStop.ts) and the tail of the main
 * process's log, next to that log's files whole (`main.log`, and `main.old.log` once it
 * has rotated), which reach back into earlier launches. Shared by the renderer's IPC call and
 * the menu/tray "Save Diagnostics" entry point in main.ts, which has no
 * renderer-side `projectState`/`logs` to offer and does not need to.
 */
export async function exportDiagnosticFile(payload: {
	error: string;
	stack?: string;
	projectState: unknown;
	logs: string[];
}) {
	const { filePath, canceled } = await dialog.showSaveDialog({
		title: "Save Diagnostic File",
		defaultPath: `openscreen-diagnostic-${Date.now()}.zip`,
		filters: [{ name: "ZIP", extensions: ["zip"] }],
	});

	if (canceled || !filePath) return { success: false, canceled: true };

	const HELPER_OUTPUT_MAX_BYTES = 64 * 1024;
	const MAIN_PROCESS_LOGS_MAX_BYTES = 256 * 1024;
	const tail = (s: string, max: number) => (s.length <= max ? s : s.slice(s.length - max));
	// Read before `logFileError` below, so a failed read is reported in the same bundle.
	const logFiles = mainLogFile.readFiles();

	const diagnostic = {
		timestamp: new Date().toISOString(),
		appVersion: app.getVersion(),
		platform: process.platform,
		arch: process.arch,
		// The same fact the About box leads with, and for the same reason: it is what
		// explains why a copy does or does not offer an update check. This file is the
		// artifact users actually attach, so it must not be the one that omits it.
		channel: getInstallChannel(),
		osRelease: os.release(),
		osVersion: os.version(),
		totalMemoryMB: Math.round(os.totalmem() / 1024 / 1024),
		nodeVersion: process.versions.node,
		electronVersion: process.versions.electron,
		chromeVersion: process.versions.chrome,
		error: payload.error,
		stack: payload.stack,
		projectState: payload.projectState,
		recentLogs: payload.logs,
		helperOutput: {
			windows: tail(nativeWindowsCaptureOutput, HELPER_OUTPUT_MAX_BYTES),
			mac: tail(nativeMacCaptureOutput, HELPER_OUTPUT_MAX_BYTES),
			linux: tail(lastLinuxCaptureSession?.helperOutput ?? "", HELPER_OUTPUT_MAX_BYTES),
		},
		mainProcessLogs: mainLogFile.readTail(MAIN_PROCESS_LOGS_MAX_BYTES),
		logFile: mainLogFile.filePath,
		logFileError: mainLogFile.lastError,
	};

	try {
		const json = Buffer.from(JSON.stringify(diagnostic, null, 2), "utf-8");
		await fs.writeFile(filePath, createZip([{ name: "diagnostic.json", data: json }, ...logFiles]));
		return { success: true, path: filePath };
	} catch (error) {
		console.error("Failed to write diagnostic file:", error);
		return { success: false, error: String(error) };
	}
}

export function registerIpcHandlers(
	createEditorWindow: () => void,
	createSourceSelectorWindow: () => BrowserWindow,
	createCountdownOverlayWindow: () => BrowserWindow,
	createNotesWindowWrapper: () => BrowserWindow,
	getMainWindow: () => BrowserWindow | null,
	getSourceSelectorWindow: () => BrowserWindow | null,
	getNotesWindow: () => BrowserWindow | null,
	getCountdownOverlayWindow?: () => BrowserWindow | null,
	onRecordingStateChange?: (recording: boolean, sourceName: string, preparing?: boolean) => void,
	_switchToHud?: () => void,
	/** The editor holds changes it has not saved (main.ts): an MCP take would close it. */
	editorHasUnsavedChanges?: () => boolean,
) {
	/** The HUD is recording a take, the user's or an MCP client's. Set by `setAppRecording` only. */
	let appRecording = false;
	/**
	 * Every start and stop of a take goes through here: the browser path's `set-recording-state`
	 * and the native paths, which start and stop in this process. The MCP recorder waits on it
	 * for a client's take to start, and the tray shows it. A native path that called
	 * `onRecordingStateChange` itself left the MCP recorder waiting on a take already running.
	 */
	const setAppRecording = (recording: boolean, sourceName: string, preparing = false) => {
		appRecording = recording;
		if (!preparing) mcpAppRecorder.recordingChanged(recording);
		onRecordingStateChange?.(recording, sourceName, preparing);
	};
	const appSettings = new AppSettingsStore(app.getPath("userData"));
	const broadcastSelectedSource = (source: SelectedSource | null) => {
		for (const window of BrowserWindow.getAllWindows()) {
			if (!window.isDestroyed()) {
				window.webContents.send("selected-source-changed", source);
			}
		}
	};
	const sameSelectedSource = (left: SelectedSource | null, right: SelectedSource | null) =>
		left?.id === right?.id && left?.name === right?.name && left?.display_id === right?.display_id;

	// Issue #738: the renderer's `navigator.clipboard.writeText` is always denied
	// here (NotAllowedError: Write permission denied — Electron withholds the
	// clipboard-sanitized-write permission from the renderer), so chat's
	// "Copy message" fell to its error toast and the clipboard kept its old
	// content. Main's `clipboard` module has no such permission gate; the
	// preload exposes this as `copyToClipboard`.
	ipcMain.handle("clipboard:write-text", (_event, text: unknown) => {
		if (typeof text !== "string") {
			throw new TypeError("clipboard:write-text expects a string");
		}
		clipboard.writeText(text);
	});

	/** The sources the pickers list, in their order: the in-app MCP server's startRecording
	 *  picks from the same list its listSources shows. */
	async function getSourcesForPickers(opts: Electron.SourcesOptions) {
		// desktopCapturer.getSources can never settle where the GL stack cannot be
		// reached -- a container, a CI runner, a host whose ANGLE fails to
		// initialise. Bounded here rather than per-caller because every caller has
		// the same exposure and none of them can cancel this call: the CLI runners
		// (`sources`, `record`) and the GUI pickers (SourceSelector, RecStage) all
		// await it, and a renderer-side race would only stop *waiting* while this
		// keeps running and its reply goes to nobody. Rejecting is what turns an
		// indefinite spinner into the pickers' existing error branch.
		// How long it actually took, under the existing diagnostic flag. That
		// duration is what showed the headless hang (#462) to be bimodal -- ~17ms
		// or never -- and so not a threshold problem; see desktopSourceTypes.ts.
		const startedAt = Date.now();
		const diagnostic = isDiagnosticModeEnabled();
		let sources: Awaited<ReturnType<typeof desktopCapturer.getSources>>;
		try {
			sources = await withDeadline(
				getSourcesByType(
					opts,
					(typeOpts) => desktopCapturer.getSources(typeOpts),
					shouldEnumerateSourceTypesSeparately(process.platform, process.env),
				),
				GET_SOURCES_TIMEOUT_MS,
				`Desktop source enumeration did not return within ${GET_SOURCES_TIMEOUT_MS}ms. ` +
					"This usually means the display or GPU stack cannot be reached — check that a display server is available.",
			);
		} catch (error) {
			if (diagnostic) {
				// The reason, not an assumption about it: this catch also sees a
				// getSources that rejected on its own, well inside the deadline, and
				// calling that a timeout would point the next reader at the wrong thing.
				// The deadline error carries its own wording.
				const reason = error instanceof Error ? error.message : String(error);
				console.info(
					`[get-sources] failed after ${Date.now() - startedAt}ms (types=${(opts?.types ?? []).join(",")}): ${reason}`,
				);
			}
			throw error;
		}
		if (diagnostic) {
			console.info(
				`[get-sources] returned ${sources.length} source(s) in ${Date.now() - startedAt}ms (types=${(opts?.types ?? []).join(",")})`,
			);
		}
		lastEnumeratedSources = mergeEnumeratedSources(lastEnumeratedSources, sources, opts?.types);
		const previousSelectedSource = selectedSource;
		const currentLive = selectedSource?.id
			? sources.find((source) => source.id === selectedSource?.id)
			: null;
		if (currentLive) {
			selectedSource = {
				id: currentLive.id,
				name: currentLive.name,
				display_id: currentLive.display_id,
			};
			selectedDesktopSource = currentLive;
		} else if (enumerationIncludesSourceKind(opts?.types, selectedSource?.id)) {
			selectedSource = null;
			selectedDesktopSource = null;
			const restored = resolveRecordingSource(
				appSettings.getSnapshot().lastSource,
				process.platform,
				sources,
				{ waylandPortal: process.platform === "linux" && Boolean(findPipeWireCursorHelperPath()) },
			);
			if (restored) {
				selectedSource = {
					id: restored.id,
					name: restored.name,
					display_id: restored.display_id,
				};
				selectedDesktopSource = lastEnumeratedSources.get(restored.id) ?? null;
			}
		}
		if (!sameSelectedSource(previousSelectedSource, selectedSource)) {
			broadcastSelectedSource(selectedSource);
		}
		return sources.map((source) => ({
			id: source.id,
			name: source.name,
			display_id: source.display_id,
			thumbnail: source.thumbnail ? source.thumbnail.toDataURL() : null,
			appIcon: source.appIcon ? source.appIcon.toDataURL() : null,
		}));
	}
	ipcMain.handle("get-sources", (_, opts) => getSourcesForPickers(opts));

	const selectSourceContext: SelectSourceContext<DesktopCapturerSource> = {
		generation: selectSourceGeneration,
		getSelected: () => ({ source: selectedSource, live: selectedDesktopSource }),
		setSelected: (source, live) => {
			selectedSource = source;
			selectedDesktopSource = live;
		},
		getCached: (id) => lastEnumeratedSources.get(id) ?? null,
		replaceCache: (sources) => {
			lastEnumeratedSources = new Map(sources.map((candidate) => [candidate.id, candidate]));
		},
	};

	async function selectSource(source: SelectedSource, options?: { persist?: boolean }) {
		const next = await selectSourceWithOwnership(
			selectSourceContext,
			{ id: source.id, name: source.name, display_id: source.display_id },
			options,
			{
				getSources: () =>
					desktopCapturer.getSources({
						types: ["screen", "window"],
						thumbnailSize: { width: 0, height: 0 },
						fetchWindowIcons: true,
					}),
				persist: (live) => {
					appSettings.setLastSource(
						describeRecordingSource(process.platform, live as Required<SelectedSource>),
					);
				},
				broadcast: broadcastSelectedSource,
				shouldPersist: shouldPersistSelectedSource,
			},
		);
		if (next) {
			const sourceSelectorWin = getSourceSelectorWindow();
			if (sourceSelectorWin) {
				sourceSelectorWin.close();
			}
		}
		return next;
	}
	ipcMain.handle("select-source", (_, source: SelectedSource, options?: { persist?: boolean }) =>
		selectSource(source, options),
	);

	/**
	 * The HUD and the notes window belong to this process, not to the helper, so a display
	 * pick would record them unless the picker is told to leave them out.
	 */
	function macPickerExcludedWindowIds() {
		const appWindowSourceIds = [getMainWindow(), getNotesWindow()]
			.filter((window): window is BrowserWindow => !!window && !window.isDestroyed())
			.map((window) => window.getMediaSourceId());
		return collectMacCaptureExcludedWindowIds(appWindowSourceIds);
	}

	async function presentMacSystemPicker(session: MacPickerSession) {
		const excludedWindowIds = macPickerExcludedWindowIds();
		// Out of the way while the picker is up. The HUD window is far larger than the bar
		// it draws (a transparent reserve above it), and Apple's picker targets windows by
		// their frame, not by where clicks land -- so that invisible rectangle hid every
		// window behind it from the picker. Its exclusion from the capture is by window id,
		// so hiding it does not bring it back into a display pick.
		const hud = getMainWindow();
		const hideHud = !!hud && !hud.isDestroyed() && hud.isVisible();
		if (hideHud) {
			// Logged both ways: until the picker answers, this window (the HUD, or the editor in
			// Record mode) is off screen, and a report that stops at this line says the answer
			// never came (#1021).
			console.info("[mac-picker] hiding the main window until the picker answers");
			hud.hide();
		}
		let pick: MacPickerSelection | null;
		try {
			pick = await session.present(
				excludedWindowIds,
				appSettings.getSnapshot().recording.hideDesktopIcons,
			);
		} finally {
			if (hideHud && !hud.isDestroyed()) {
				hud.showInactive();
				console.info("[mac-picker] showing the main window again");
			}
		}
		if (!pick) {
			// Same signal our own picker window sends when it closes without a choice: the HUD
			// stops waiting to record after a selection.
			for (const window of BrowserWindow.getAllWindows()) {
				if (!window.isDestroyed()) {
					window.webContents.send("source-selector-closed");
				}
			}
			return;
		}
		const picked = selectedSourceFromPick(pick);
		selectedSource = picked;
		selectedDesktopSource = null;
		// Written only so the next launch can name it: the pick itself dies with the helper.
		try {
			appSettings.setLastSource(describeMacPickerSource(picked, pick.kind));
		} catch (error) {
			console.warn("Failed to persist the picked recording source:", error);
		}
		broadcastSelectedSource(selectedSource);
	}

	app.on("will-quit", () => {
		macPickerSession?.dispose();
	});

	// For the renderer's own source lists (the AI editor's recording stage): with Apple's
	// picker they must hand the choice to `open-source-selector` rather than enumerate.
	ipcMain.handle("uses-system-source-picker", () => macPickerOwnsSources());

	// Named in the HUD and Record mode after a relaunch, while `get-selected-source` still
	// answers null: the pick cannot be restored, so it is never reported as selected.
	ipcMain.handle("get-last-picked-source", () =>
		rememberedPickerSourceName(appSettings.getSnapshot().lastSource, macPickerOwnsSources()),
	);

	ipcMain.handle("get-selected-source", async () => {
		const previousSelectedSource = selectedSource;
		if (process.platform === "linux" && findPipeWireCursorHelperPath()) {
			selectedSource = null;
			selectedDesktopSource = null;
			if (!sameSelectedSource(previousSelectedSource, null)) {
				broadcastSelectedSource(null);
			}
			return null;
		}
		if (macPickerOwnsSources()) {
			// Apple's picker owns the choice. A pick lives only as long as the helper session
			// that holds it, so there is nothing to restore -- and enumerating here would ask
			// for the very Screen Recording grant the picker makes unnecessary. A source the
			// CLI selected by id in this run is still answered as it is: `record` picks by
			// name, headless, and keeps the per-take helper.
			if (!isMacPickerSourceId(selectedSource?.id)) {
				return selectedDesktopSource ? selectedSource : null;
			}
			// A screen pick that would record the current HUD or notes window is no pick at all:
			// answering null makes the next Record present the picker again (#965).
			macPickerSession?.forgetSelectionUnlessExcluding(macPickerExcludedWindowIds());
			if (!macPickerSession?.getSelection()) {
				selectedSource = null;
				selectedDesktopSource = null;
				broadcastSelectedSource(null);
			}
			return selectedSource;
		}
		const lastSource = appSettings.getSnapshot().lastSource;
		const liveSelected =
			selectedSource?.id != null
				? {
						id: selectedSource.id,
						name: selectedSource.name,
						display_id: selectedSource.display_id ?? "",
					}
				: null;
		if (!shouldEnumerateRecordingSources(liveSelected, lastSource)) {
			return selectedSource;
		}
		const sources = await withDeadline(
			desktopCapturer.getSources({
				types: ["screen", "window"],
				thumbnailSize: { width: 0, height: 0 },
				fetchWindowIcons: false,
			}),
			GET_SOURCES_TIMEOUT_MS,
			`Desktop source restoration did not return within ${GET_SOURCES_TIMEOUT_MS}ms.`,
		);
		const decision = restoreRecordingSourceAfterEnumeration({
			selectedBefore: liveSelected,
			selectedAfter:
				selectedSource?.id != null
					? {
							id: selectedSource.id,
							name: selectedSource.name,
							display_id: selectedSource.display_id ?? "",
						}
					: null,
			lastSourceBefore: lastSource,
			lastSourceAfter: appSettings.getSnapshot().lastSource,
			platform: process.platform,
			sources,
		});
		if (!decision.apply) {
			return selectedSource;
		}
		lastEnumeratedSources = new Map(sources.map((source) => [source.id, source]));
		const restored = decision.restored;
		selectedDesktopSource = restored ? (lastEnumeratedSources.get(restored.id) ?? null) : null;
		selectedSource = restored
			? { id: restored.id, name: restored.name, display_id: restored.display_id }
			: null;
		if (!sameSelectedSource(previousSelectedSource, selectedSource)) {
			broadcastSelectedSource(selectedSource);
		}
		return selectedSource;
	});

	const recordingPrefs = registerRecordingPrefsHandlers(
		defaultRecordingPrefs,
		getMainWindow,
		() => BrowserWindow.getAllWindows(),
		(previous, next) => {
			// Apple's picker bakes the exclusions into the filter it hands back, so a pick made
			// before "Hide desktop icons" changed would still record the desktop the old way.
			// Dropping it makes the HUD ask for a new pick instead of ignoring the toggle.
			if (
				previous.hideDesktopIcons !== next.hideDesktopIcons &&
				isMacPickerSourceId(selectedSource?.id)
			) {
				selectedSource = null;
				broadcastSelectedSource(null);
			}
			// Turning system audio on is when its grant becomes wanted: ask now, so the prompt
			// never lands on a take that is already counting down.
			if (!previous.systemAudioEnabled && next.systemAudioEnabled && macPickerOwnsSources()) {
				void getMacPermissions()
					.askForSystemAudioOnce()
					.catch((error) => console.warn("[permissions] system audio request failed:", error));
			}
		},
	);

	// Asked before every take starts. A disk that fills up mid-take used to be found only
	// when the take was saved, and the take was lost with it.
	ipcMain.handle("check-recording-storage", async () => {
		if (isWindowsUpdatePending()) {
			return { success: false, error: WINDOWS_UPDATE_PENDING_MESSAGE };
		}
		const problem = await recordingStorageProblem(RECORDINGS_DIR);
		if (!problem) return { success: true };
		if (problem.kind === "unavailable") {
			return {
				success: false,
				error: mainT("dialogs", "recording.folderUnavailable", { path: RECORDINGS_DIR }),
			};
		}
		const availableMb = Math.max(0, Math.floor(problem.availableBytes / (1024 * 1024)));
		return {
			success: false,
			error: mainT("dialogs", "recording.lowDiskSpace", { availableMb }),
		};
	});

	ipcMain.handle("get-recordings-dir", () => getRecordingsDirInfo());

	// The folder comes from the native picker, never from the renderer: everything in it
	// becomes readable through the media handlers.
	ipcMain.handle("choose-recordings-dir", async (event) => {
		const result = await showOpenDialogOver(BrowserWindow.fromWebContents(event.sender), {
			title: mainT("dialogs", "fileDialogs.selectRecordingsFolder"),
			defaultPath: RECORDINGS_DIR,
			properties: ["openDirectory", "createDirectory"],
		});
		if (result.canceled || result.filePaths.length === 0) {
			return { success: false, canceled: true };
		}
		try {
			return { success: true, path: await setRecordingsDir(result.filePaths[0]) };
		} catch (error) {
			console.error("Failed to switch recordings folder:", error);
			return { success: false, message: String(error) };
		}
	});

	ipcMain.handle("reset-recordings-dir", async () => {
		try {
			return { success: true, path: await setRecordingsDir(null) };
		} catch (error) {
			console.error("Failed to reset recordings folder:", error);
			return { success: false, message: String(error) };
		}
	});

	ipcMain.handle("request-camera-access", async () => {
		if (process.platform !== "darwin") {
			return { success: true, granted: true, status: "granted" };
		}

		try {
			const status = systemPreferences.getMediaAccessStatus("camera");
			if (status === "granted") {
				return { success: true, granted: true, status };
			}

			if (status === "not-determined") {
				const granted = await systemPreferences.askForMediaAccess("camera");
				return {
					success: true,
					granted,
					status: granted ? "granted" : systemPreferences.getMediaAccessStatus("camera"),
				};
			}

			return { success: true, granted: false, status };
		} catch (error) {
			console.error("Failed to request camera access:", error);
			return {
				success: false,
				granted: false,
				status: "unknown",
				error: String(error),
			};
		}
	});

	ipcMain.handle("request-native-mac-cursor-access", async () => {
		const access = await requestMacCursorAccessibilityAccess();

		// Pop the native Accessibility dialog ONLY for a genuine denial — the helper ran,
		// asked, and was told no. Every other !granted status means the helper never got
		// to ask (absent from the build, killed by the loader, crashed, hung), and telling
		// the user to grant a permission they may well already hold is what made #515
		// impossible to escape. Those degrade silently instead; the recorder falls back to
		// position-only cursor telemetry and the countdown still runs.
		if (process.platform === "darwin" && !access.granted) {
			if (isMacCursorHelperUnavailable(access.status)) {
				console.warn(
					`[cursor-macos] editable cursor unavailable (status=${access.status}${
						access.error ? `, error=${access.error}` : ""
					}); the app ${
						access.accessibilityTrusted ? "does" : "does not"
					} hold Accessibility trust. Recording continues with position-only cursor telemetry.`,
				);
				return access;
			}

			// Accessibility improves cursor shape hints but is not required to record.
			// Remember that the helper raised the system prompt so a later visit to the
			// permissions window can direct the user to Settings, but don't reopen that
			// window from every Record press.
			getMacPermissions().noteRequested("accessibility");
		}

		return access;
	});

	ipcMain.handle("open-source-selector", async () => {
		// Nothing to open on Linux WHEN THE NATIVE HELPER IS THERE. The selector's
		// own `desktopCapturer.getSources()` raises a portal dialog — a SECOND
		// one, for a session that is thrown away — and whatever it returns cannot
		// reach the helper, because `SelectSources` has no parameter naming a
		// source. Refusing keeps that dialog from appearing at all.
		//
		// Without the helper the recorder falls back to Chromium's capture, which
		// DOES consume a source id, so the picker has to stay reachable there or
		// that path could never start.
		if (process.platform === "linux" && findPipeWireCursorHelperPath()) {
			return { opened: false, reason: "portal-owns-selection" };
		}

		const pickerSession = await getMacPickerSession();
		if (pickerSession) {
			// Answered at once: the pick arrives later through `selected-source-changed`, which
			// is how the HUD already learns about a choice made in our own picker window.
			void presentMacSystemPicker(pickerSession);
			return { opened: true };
		}

		// Chromium's picker can only list sources once THIS process can capture, which on
		// macOS means granted, and granted before launch: the app's own read is cached for
		// the life of the process. Anything short of that belongs in the permissions
		// window, which says what is missing and offers the relaunch when that is all.
		if (process.platform === "darwin") {
			const permissions = await getMacPermissions().read();
			if (permissions.screen !== "granted" || permissions.screenRequiresRelaunch) {
				showPermissionsWindow();
				return { opened: false, reason: "screen-access-required" };
			}
		}

		const sourceSelectorWin = getSourceSelectorWindow();
		if (sourceSelectorWin) {
			sourceSelectorWin.focus();
			return { opened: true };
		}
		createSourceSelectorWindow();
		return { opened: true };
	});

	ipcMain.handle("open-notes", async () => {
		const notesSelectorWin = getNotesWindow();
		if (notesSelectorWin) {
			notesSelectorWin.focus();
			return { opened: true };
		}

		createNotesWindowWrapper();
		return { opened: true };
	});

	ipcMain.handle("switch-to-editor", () => {
		// createEditorWindow already closes the current mainWindow (the HUD) before
		// opening the editor. Closing it here too double-closes, leaving ghost
		// transparent windows and compounding the HUD shadow each cycle.
		createEditorWindow();
	});

	ipcMain.handle("switch-to-hud", () => {
		_switchToHud?.();
		return { success: true };
	});

	/** The editor's Record button: over to the HUD, which starts the take by itself. */
	function startNewRecording() {
		assertWindowsUpdateIdle();
		_switchToHud?.();
		const hudWindow = getMainWindow();
		if (hudWindow && !hudWindow.isDestroyed()) {
			const sendAutoStart = () => hudWindow.webContents.send("hud-auto-start-recording");
			if (hudWindow.webContents.isLoading()) {
				hudWindow.webContents.once("did-finish-load", sendAutoStart);
			} else {
				sendAutoStart();
			}
		}
	}
	ipcMain.handle("start-new-recording", () => {
		startNewRecording();
		return { success: true };
	});

	// Counts the countdowns that showed the overlay, so a Linux hide still waiting on its cleared
	// frame can tell that a newer countdown has taken the overlay over (`countdownOverlay.ts`).
	let countdownOverlayShows = 0;
	ipcMain.handle("countdown-overlay-show", async (_, value: number, runId: number) => {
		countdownOverlayShows += 1;
		const overlayWindow = getCountdownOverlayWindow?.() ?? createCountdownOverlayWindow();
		if (overlayWindow.isDestroyed()) {
			return;
		}

		// Wait for the first frame before showing, else Chromium flashes a black
		// rectangle because it hasn't rendered any pixels yet.
		if (overlayWindow.webContents.isLoading()) {
			await new Promise<void>((resolve) => {
				overlayWindow.once("ready-to-show", resolve);
			});
		}

		if (!overlayWindow.isVisible()) {
			overlayWindow.showInactive();
		}

		overlayWindow.webContents.send("countdown-overlay-value", value, runId);
	});

	ipcMain.handle("countdown-overlay-set-value", (_, value: number, runId: number) => {
		const overlayWindow = getCountdownOverlayWindow?.();
		if (!overlayWindow || overlayWindow.isDestroyed()) {
			return;
		}

		overlayWindow.webContents.send("countdown-overlay-value", value, runId);
	});

	// Resolves once the overlay is hidden, and the renderer starts the take only then: on Linux
	// that is after a frame without the digit has been painted, so the capture cannot record it.
	ipcMain.handle("countdown-overlay-hide", async (_, runId: number) => {
		const overlayWindow = getCountdownOverlayWindow?.();
		if (!overlayWindow || overlayWindow.isDestroyed()) {
			return;
		}

		const showsAtHide = countdownOverlayShows;
		await hideCountdownOverlay(overlayWindow, runId, {
			platform: process.platform,
			isSuperseded: () => countdownOverlayShows !== showsAtHide,
		});
	});

	ipcMain.handle("is-native-windows-capture-available", async () => {
		if (!isWindowsGraphicsCaptureOsSupported()) {
			return { success: true, available: false, reason: "unsupported-os" };
		}

		const helperPath = await findNativeWindowsCaptureHelperPath();
		return helperPath
			? { success: true, available: true, helperPath }
			: { success: true, available: false, reason: "missing-helper" };
	});

	ipcMain.handle("is-native-mac-capture-available", async () => {
		if (process.platform !== "darwin") {
			return { success: true, available: false, reason: "unsupported-platform" };
		}

		const helperPath = await findNativeMacCaptureHelperPath();
		return helperPath
			? { success: true, available: true, helperPath }
			: { success: true, available: false, reason: "missing-helper" };
	});

	ipcMain.handle("is-native-linux-capture-available", async () => {
		if (process.platform !== "linux") {
			return { success: true, available: false, reason: "unsupported-platform" };
		}

		const helperPath = findPipeWireCursorHelperPath();
		return helperPath
			? { success: true, available: true, helperPath }
			: { success: true, available: false, reason: "missing-helper" };
	});

	/**
	 * Raises the compositor's picker and stops there, holding the grant.
	 *
	 * Best-effort by contract: every failure returns `success: false` rather than
	 * throwing, because the caller's fallback is simply to start normally and get
	 * the picker after its countdown — the behaviour that shipped before this
	 * existed. Nothing downstream may depend on a prepare having succeeded.
	 */
	ipcMain.handle(
		"prepare-native-linux-recording",
		async (_, request: NativeLinuxRecordingRequest) => {
			if (process.platform !== "linux") {
				return { success: false, reason: "unsupported-platform" };
			}
			if (linuxNativeCaptureSession) {
				return { success: false, reason: "already-recording" };
			}
			discardPreparedLinuxCapture("superseded by a new prepare");
			const token = Symbol("prepare-native-linux-recording");
			preparingLinuxCaptureToken = token;

			try {
				if (!findPipeWireCursorHelperPath()) {
					return { success: false, reason: "missing-helper" };
				}
				const recordingId =
					typeof request?.recordingId === "number" && Number.isFinite(request.recordingId)
						? request.recordingId
						: Date.now();
				const outputPath = path.join(RECORDINGS_DIR, `${RECORDING_FILE_PREFIX}${recordingId}.mp4`);
				const cursorCaptureMode =
					normalizeCursorCaptureMode(request?.cursor?.mode) ?? "editable-overlay";

				await fs.mkdir(RECORDINGS_DIR, { recursive: true });

				const session = new LinuxNativeCaptureSession({
					outputPath,
					cursorMode: portalCursorMode(cursorCaptureMode),
					fps: request.video.fps,
					...(request.video.bitrate ? { bitrate: request.video.bitrate } : {}),
					audio: {
						system: { enabled: request.audio.system.enabled },
						microphone: {
							enabled: request.audio.microphone.enabled,
							...(request.audio.microphone.deviceName
								? { deviceName: request.audio.microphone.deviceName }
								: {}),
							gain: request.audio.microphone.gain,
						},
					},
					maxCursorSamples: MAX_CURSOR_SAMPLES,
					deferStart: true,
				});
				lastLinuxCaptureSession = session;

				await session.start();
				// The picker is up now. No timeout: a human is reading a dialog.
				await session.waitUntilSourceSelected();

				// Cancelled or superseded while the picker was up. Discard rather
				// than assign: this grant is for a recording nobody is waiting for
				// any more, and keeping it would leave the sharing indicator on.
				if (preparingLinuxCaptureToken !== token) {
					session.discard();
					return { success: false, reason: "cancelled" };
				}
				preparingLinuxCaptureToken = null;

				preparedLinuxCapture = { session, outputPath, request };
				return {
					success: true,
					recordingId,
					sourceKind: session.grantedSourceKind ?? null,
				};
			} catch (error) {
				console.warn("Could not prepare the native Linux capture:", error);
				discardPreparedLinuxCapture("prepare failed");
				return { success: false, error: String(error) };
			}
		},
	);

	/** Drops a prepared session, e.g. when the countdown was cancelled. */
	ipcMain.handle("cancel-native-linux-prepare", async () => {
		discardPreparedLinuxCapture("cancelled by the renderer");
		return { success: true };
	});

	ipcMain.handle(
		"start-native-linux-recording",
		async (_, request: NativeLinuxRecordingRequest) => {
			let outputPath: string | null = null;
			try {
				if (process.platform !== "linux") {
					return { success: false, error: "Native Linux capture requires Linux." };
				}
				if (linuxNativeCaptureSession) {
					return { success: false, error: "Native Linux capture is already running." };
				}
				if (!findPipeWireCursorHelperPath()) {
					return { success: false, error: "Native Linux capture helper is not available." };
				}

				const recordingId =
					typeof request?.recordingId === "number" && Number.isFinite(request.recordingId)
						? request.recordingId
						: Date.now();
				outputPath = path.join(RECORDINGS_DIR, `${RECORDING_FILE_PREFIX}${recordingId}.mp4`);
				const cursorCaptureMode =
					normalizeCursorCaptureMode(request?.cursor?.mode) ?? "editable-overlay";

				await fs.mkdir(RECORDINGS_DIR, { recursive: true });

				// A session prepared before the countdown, if there was one. Taking
				// it here rather than requiring it is what keeps every caller
				// working: a path that never prepared still gets a full start
				// below, just with the picker after its countdown instead of
				// before. Nothing has to know which path it is on.
				const prepared = takePreparedLinuxSession(outputPath, request);
				const session =
					prepared ??
					new LinuxNativeCaptureSession({
						outputPath,
						cursorMode: portalCursorMode(cursorCaptureMode),
						fps: request.video.fps,
						...(request.video.bitrate ? { bitrate: request.video.bitrate } : {}),
						audio: {
							system: { enabled: request.audio.system.enabled },
							microphone: {
								enabled: request.audio.microphone.enabled,
								...(request.audio.microphone.deviceName
									? { deviceName: request.audio.microphone.deviceName }
									: {}),
								gain: request.audio.microphone.gain,
							},
						},
						maxCursorSamples: MAX_CURSOR_SAMPLES,
					});
				lastLinuxCaptureSession = session;

				console.info("[native-linux] starting capture", {
					outputPath,
					prepared: Boolean(prepared),
					cursor: { mode: cursorCaptureMode },
					audio: request.audio,
					video: request.video,
				});

				if (!prepared) {
					await session.start();
					// Blocks until the user answers the portal picker, which has no
					// upper bound. On this path the countdown has already run.
					await session.waitUntilSourceSelected();
				}
				// Idempotent, and a no-op for a session that was not deferred.
				session.arm();
				await session.waitUntilCapturing();

				linuxNativeCaptureSession = session;
				linuxNativeCaptureRecordingId = recordingId;
				// The portal may lack EMBEDDED and get METADATA instead (#1357): the
				// pointer is then not in the pixels, so the editor has to draw it.
				linuxNativeCaptureCursorMode =
					session.cursorMode === "metadata" ? "editable-overlay" : cursorCaptureMode;

				// The portal's answer, not an in-app selection — on Wayland there
				// is none to have. This used to read `selectedSource || { name:
				// "Screen" }`, so the tray confidently displayed the name of a
				// window the capture had never been told about.
				linuxNativeCaptureSourceLabel = linuxSourceLabel(session.grantedSourceKind);
				setAppRecording(true, linuxNativeCaptureSourceLabel);

				return { success: true, recordingId, path: outputPath };
			} catch (error) {
				console.error("Failed to start native Linux recording:", error);
				linuxNativeCaptureSession = null;
				linuxNativeCaptureRecordingId = null;
				linuxNativeCaptureCursorMode = "editable-overlay";
				// The helper opens its mp4 on the first frame, before it reports capture
				// started, so an encoder that failed there leaves it empty.
				if (outputPath) {
					await removeEmptyCaptureOutput(outputPath);
				}
				return { success: false, error: String(error) };
			}
		},
	);

	ipcMain.handle("pause-native-linux-recording", async () => {
		if (!linuxNativeCaptureSession) {
			return { success: false, error: "Native Linux capture is not running." };
		}
		linuxNativeCaptureSession.pause();
		return { success: true };
	});

	ipcMain.handle("resume-native-linux-recording", async () => {
		if (!linuxNativeCaptureSession) {
			return { success: false, error: "Native Linux capture is not running." };
		}
		linuxNativeCaptureSession.resume();
		return { success: true };
	});

	ipcMain.handle("stop-native-linux-recording", async (_, discard?: boolean) => {
		const session = linuxNativeCaptureSession;
		const recordingId = linuxNativeCaptureRecordingId ?? Date.now();
		const cursorCaptureMode = linuxNativeCaptureCursorMode;

		if (!session) {
			return { success: false, error: "Native Linux capture is not running." };
		}

		try {
			if (discard) {
				session.discard();
				const discarded = path.join(RECORDINGS_DIR, `${RECORDING_FILE_PREFIX}${recordingId}.mp4`);
				await Promise.all([
					fs.rm(discarded, { force: true }),
					fs.rm(`${discarded}.cursor.json`, { force: true }),
				]);
				return { success: true, discarded: true };
			}

			const result = await session.stop();

			// The helper collects cursor samples itself, from the same portal
			// session that produced the pixels, so there is no separate sampler
			// to stop and no clock offset to correct — the two are one recording.
			if (cursorCaptureMode === "editable-overlay" && result.cursor.samples.length > 0) {
				await fs.writeFile(
					`${result.path}.cursor.json`,
					JSON.stringify(result.cursor, null, 2),
					"utf-8",
				);
			}

			const session_: RecordingSession = {
				screenVideoPath: result.path,
				createdAt: recordingId,
				cursorCaptureMode,
			};
			setCurrentRecordingSessionState(session_);
			currentProjectPath = null;

			const sessionManifestPath = path.join(
				RECORDINGS_DIR,
				`${path.parse(result.path).name}${RECORDING_SESSION_SUFFIX}`,
			);
			await fs.writeFile(sessionManifestPath, JSON.stringify(session_, null, 2), "utf-8");
			await registerRecordingMediaLinks(result.path, { cursorCaptureMode });

			console.info("[native-linux] capture stored", {
				path: result.path,
				frames: result.frames,
				droppedFrames: result.droppedFrames,
				durationMs: result.durationMs,
				videoEncoder: result.videoEncoder,
				cursorSamples: result.cursor.samples.length,
			});

			return {
				success: true,
				path: result.path,
				session: session_,
				message: "Native Linux recording session stored successfully",
			};
		} catch (error) {
			console.error("Failed to stop native Linux recording:", error);
			return { success: false, error: String(error) };
		} finally {
			linuxNativeCaptureSession = null;
			linuxNativeCaptureRecordingId = null;
			linuxNativeCaptureCursorMode = "editable-overlay";
			const stoppedLabel = linuxNativeCaptureSourceLabel ?? linuxSourceLabel();
			linuxNativeCaptureSourceLabel = null;
			setAppRecording(false, stoppedLabel);
		}
	});

	ipcMain.handle(
		"start-native-windows-recording",
		async (_, request: NativeWindowsRecordingRequest) => {
			if (isWindowsUpdatePending()) {
				return { success: false, error: WINDOWS_UPDATE_PENDING_MESSAGE };
			}
			let startReserved = false;
			try {
				if (!isWindowsGraphicsCaptureOsSupported()) {
					return {
						success: false,
						error: "Windows Graphics Capture requires Windows 10 build 19041 or newer.",
					};
				}
				if (nativeWindowsCaptureProcess) {
					return { success: false, error: "Native Windows capture is already running." };
				}

				const helperPath = await findNativeWindowsCaptureHelperPath();
				if (!helperPath) {
					return { success: false, error: "Native Windows capture helper is not available." };
				}

				if (!request?.source?.sourceId) {
					return {
						success: false,
						error: "Native Windows capture request is missing a source.",
					};
				}

				const recordingId =
					typeof request.recordingId === "number" && Number.isFinite(request.recordingId)
						? request.recordingId
						: Date.now();
				const outputPath = path.join(RECORDINGS_DIR, `${RECORDING_FILE_PREFIX}${recordingId}.mp4`);
				const webcamOutputPath = path.join(
					RECORDINGS_DIR,
					`${RECORDING_FILE_PREFIX}${recordingId}-webcam.mp4`,
				);
				const sourceDisplay =
					request.source.type === "display" && typeof request.source.displayId === "number"
						? (screen.getAllDisplays().find((display) => display.id === request.source.displayId) ??
							null)
						: getSelectedDisplay();
				const bounds = sourceDisplay?.bounds ?? getSelectedSourceBounds();
				// `bounds` is DIPs; the helper matches it against physical monitor rects
				// (getopenscreen/openscreen#346). Converted here, at the wire, and not in
				// `getSelectedSourceBounds` — the cursor session shares that getter and
				// converts on its own side.
				const helperBounds = toHelperRect(bounds);
				const displayId =
					typeof request.source.displayId === "number" && Number.isFinite(request.source.displayId)
						? request.source.displayId
						: Number(selectedSource?.display_id);
				const webcamDirectShowClsid = request.webcam.enabled
					? await resolveDirectShowWebcamClsid(request.webcam.deviceName)
					: null;
				const cursorCaptureMode =
					normalizeCursorCaptureMode(request.cursor?.mode) ?? "editable-overlay";
				const envPreferSoftwareEncoder = (process.env.OPENSCREEN_WGC_PREFER_SOFTWARE_ENCODER ?? "")
					.trim()
					.toLowerCase();
				const preferSoftwareEncoder =
					request.preferSoftwareEncoder === true ||
					envPreferSoftwareEncoder === "true" ||
					envPreferSoftwareEncoder === "1";
				const config = {
					schemaVersion: 2,
					recordingId,
					preferSoftwareEncoder,
					outputPath,
					sourceType: request.source.type,
					sourceId: request.source.sourceId,
					displayId: Number.isFinite(displayId) ? displayId : 0,
					windowHandle: request.source.windowHandle ?? null,
					fps: request.video.fps,
					videoWidth: request.video.width,
					videoHeight: request.video.height,
					displayX: helperBounds.x,
					displayY: helperBounds.y,
					displayW: helperBounds.width,
					displayH: helperBounds.height,
					hasDisplayBounds: true,
					captureSystemAudio: request.audio.system.enabled,
					captureMic: request.audio.microphone.enabled,
					microphoneDeviceId: request.audio.microphone.deviceId ?? null,
					microphoneDeviceName: request.audio.microphone.deviceName ?? null,
					microphoneGain: request.audio.microphone.gain,
					webcamEnabled: request.webcam.enabled,
					webcamDeviceId: request.webcam.deviceId ?? null,
					webcamDeviceName: request.webcam.deviceName ?? null,
					webcamDirectShowClsid,
					webcamWidth: request.webcam.width,
					webcamHeight: request.webcam.height,
					webcamFps: request.webcam.fps,
					captureCursor: cursorCaptureMode === "system",
					cursorCaptureMode,
					hideDesktopIcons:
						request.source.type === "display" &&
						appSettings.getSnapshot().recording.hideDesktopIcons,
					outputs: {
						screenPath: outputPath,
						webcamPath: webcamOutputPath,
					},
					source: {
						type: request.source.type,
						sourceId: request.source.sourceId,
						displayId: Number.isFinite(displayId) ? displayId : null,
						windowHandle: request.source.windowHandle ?? null,
						bounds: helperBounds,
					},
					video: request.video,
					audio: request.audio,
					webcam: request.webcam,
					cursor: {
						mode: cursorCaptureMode,
					},
				};

				console.info("[native-wgc] starting Windows capture", {
					helperPath,
					source: request.source,
					audio: request.audio,
					webcam: request.webcam,
					encoder: { preferSoftwareEncoder },
					cursor: { mode: cursorCaptureMode },
					// Both spaces, deliberately: the helper's own errors quote the physical
					// rect, and a report that only carried the DIP one would be read against
					// numbers it never saw (getopenscreen/openscreen#346).
					bounds: { dip: bounds, helper: helperBounds },
					sourceId: selectedSource?.id ?? null,
					usedDisplayMatch: Boolean(sourceDisplay),
					outputPath,
				});

				assertWindowsUpdateIdle();
				if (appRecording || nativeWindowsCaptureProcess) {
					return { success: false, error: "Native Windows capture is already running." };
				}
				// Reserve startup before cursor/helper awaits without reporting a started take.
				startReserved = true;
				setAppRecording(true, selectedSource?.name ?? "Screen", true);
				await fs.mkdir(RECORDINGS_DIR, { recursive: true });
				nativeWindowsCaptureOutput = "";
				nativeWindowsCaptureTargetPath = outputPath;
				nativeWindowsCaptureWebcamTargetPath = request.webcam.enabled ? webcamOutputPath : null;
				nativeWindowsCaptureRecordingId = recordingId;
				nativeWindowsCursorOffsetMs = 0;
				nativeWindowsCursorCaptureMode = cursorCaptureMode;
				nativeWindowsCursorRecordingStartMs = 0;
				nativeWindowsPauseStartedAtMs = null;
				nativeWindowsPauseRanges = [];
				nativeWindowsIsPaused = false;

				const cursorStartTimeMs = Date.now();
				if (cursorCaptureMode === "editable-overlay") {
					nativeWindowsCursorRecordingStartMs = cursorStartTimeMs;
					await startCursorRecording(cursorStartTimeMs);
					console.info("[native-wgc] cursor sampler ready", {
						cursorStartTimeMs,
						warmupMs: Date.now() - cursorStartTimeMs,
					});
				} else {
					pendingCursorRecordingData = null;
				}

				assertWindowsUpdateIdle();
				const proc = spawn(helperPath, [JSON.stringify(config)], {
					cwd: RECORDINGS_DIR,
					stdio: ["pipe", "pipe", "pipe"],
					windowsHide: true,
				});
				nativeWindowsCaptureProcess = proc;
				nativeWindowsCaptureDrainCleanup = attachNativeWindowsCaptureOutputDrain(proc);
				console.info("[native-wgc] helper spawned", { pid: proc.pid });

				await waitForNativeWindowsCaptureStart(proc);
				const captureStartedAtMs = Date.now();
				nativeWindowsCursorOffsetMs =
					cursorCaptureMode === "editable-overlay"
						? Math.max(0, captureStartedAtMs - cursorStartTimeMs)
						: 0;
				const webcamFormat = readWebcamFormat(nativeWindowsCaptureOutput);
				const encoderSelection = readNativeWindowsEncoderSelection(nativeWindowsCaptureOutput);
				// Captured now because stop may have no helper left to ask. A helper
				// killed mid-recording is exactly the case where this matters most.
				nativeWindowsCaptureContainer = encoderSelection?.container ?? null;
				console.info("[native-wgc] capture started", {
					captureStartedAtMs,
					cursorOffsetMs: nativeWindowsCursorOffsetMs,
					webcamFormat,
					encoderSelection,
					// Logged only: menus missing from a window take on Windows before 11
					// 24H2 are a platform limit, not something to put in front of the user.
					secondaryWindowsApplied: readSecondaryWindowsApplied(nativeWindowsCaptureOutput),
				});

				const source = selectedSource || { name: "Screen" };
				setAppRecording(true, source.name);

				// Reported at start, not at stop: the helper decides the camera is a
				// lost cause during its own init — before it announces "Recording
				// started", so the warning is already in the buffer here — and telling
				// the user now, while the take is still worth restarting, beats telling
				// them at the end. Keyed on the helper's own event rather than on a
				// missing `webcamFormat`: absence of the format line also means "the
				// line could not be parsed", which would put a red toast on a recording
				// whose camera is working perfectly.
				const webcamUnavailable =
					request.webcam.enabled && readWebcamUnavailable(nativeWindowsCaptureOutput);
				// Same shape as the camera notice: the helper records the Windows
				// default input rather than failing, so this take is usable but is
				// almost certainly the wrong microphone.
				const microphoneDefaulted =
					request.audio.microphone.enabled && readMicrophoneDefaulted(nativeWindowsCaptureOutput);
				if (microphoneDefaulted) {
					console.warn("[native-wgc] recording the default input; the microphone was not named", {
						deviceId: request.audio.microphone.deviceId,
						deviceName: request.audio.microphone.deviceName,
					});
				}
				if (webcamUnavailable) {
					console.warn("[native-wgc] recording without a camera; the helper could not open it", {
						deviceId: request.webcam.deviceId,
						deviceName: request.webcam.deviceName,
					});
				}

				return {
					success: true,
					recordingId,
					path: outputPath,
					helperPath,
					videoEncoderSelection: encoderSelection?.video ?? null,
					videoEncoderRuntime: encoderSelection?.videoEncoderRuntime ?? null,
					webcamUnavailable,
					microphoneDefaulted,
				};
			} catch (error) {
				console.error("Failed to start native Windows recording:", error);
				if (!startReserved) return { success: false, error: String(error) };
				const failedProc = nativeWindowsCaptureProcess;
				const failedOutputPaths = [
					nativeWindowsCaptureTargetPath,
					nativeWindowsCaptureWebcamTargetPath,
				];
				detachNativeWindowsCaptureOutputDrain();
				resetNativeWindowsCaptureState();
				// Awaited, not just killed: a helper still alive holds its mp4 open, and
				// the empty one it created could not be removed below.
				if (failedProc) {
					await terminateNativeWindowsCapture(failedProc).catch(() => false);
				}
				for (const outputPath of failedOutputPaths) {
					if (outputPath) {
						await removeEmptyCaptureOutput(outputPath);
					}
				}
				await stopCursorRecording();
				setAppRecording(false, selectedSource?.name ?? "Screen");
				return { success: false, error: String(error) };
			}
		},
	);

	ipcMain.handle("start-native-mac-recording", async (_, request: NativeMacRecordingRequest) => {
		try {
			if (process.platform !== "darwin") {
				return { success: false, error: "Native macOS capture requires macOS." };
			}
			if (nativeMacCaptureProcess) {
				return { success: false, error: "Native macOS capture is already running." };
			}

			const helperPath = await findNativeMacCaptureHelperPath();
			if (!helperPath) {
				return { success: false, error: "Native macOS capture helper is not available." };
			}

			if (!request?.source?.sourceId) {
				return { success: false, error: "Native macOS capture request is missing a source." };
			}

			const recordingId =
				typeof request.recordingId === "number" && Number.isFinite(request.recordingId)
					? request.recordingId
					: Date.now();
			const outputPath = path.join(RECORDINGS_DIR, `${RECORDING_FILE_PREFIX}${recordingId}.mp4`);
			const cursorCaptureMode =
				normalizeCursorCaptureMode(request.cursor?.mode) ?? "editable-overlay";
			// A source from Apple's picker records through the session that holds the pick,
			// and needs no Screen Recording grant -- so nothing here may go near one.
			const pickerSession = isMacPickerSourceId(request.source.sourceId) ? macPickerSession : null;
			// Normally caught by `get-selected-source` first; this is the last word (#965).
			pickerSession?.forgetSelectionUnlessExcluding(macPickerExcludedWindowIds());
			const pick = pickerSession?.getSelection() ?? null;
			if (isMacPickerSourceId(request.source.sourceId) && !pick) {
				selectedSource = null;
				broadcastSelectedSource(null);
				return {
					success: false,
					error: "The screen or window you picked is no longer available. Pick it again.",
				};
			}
			if (!pickerSession) {
				try {
					await desktopCapturer.getSources({
						types: ["screen"],
						thumbnailSize: { width: 1, height: 1 },
					});
				} catch {
					// The helper reports the final ScreenCaptureKit permission status.
				}
			}
			// A picked take records system audio from a Core Audio tap, under its own "System
			// Audio Recording Only" grant (see SystemAudioTap.swift). The helper raises that
			// prompt itself if it was never answered, so note it: the permissions window then
			// offers System Settings rather than a prompt macOS will not show again.
			if (pickerSession && request.audio?.system?.enabled) {
				getMacPermissions().noteRequested("systemAudio");
			}
			if (request.audio?.microphone?.enabled) {
				const micStatus = systemPreferences.getMediaAccessStatus("microphone");
				if (micStatus !== "granted") {
					await systemPreferences.askForMediaAccess("microphone");
				}
			}
			const sourceDisplay =
				request.source.type === "display" && typeof request.source.displayId === "number"
					? (screen.getAllDisplays().find((display) => display.id === request.source.displayId) ??
						null)
					: getSelectedDisplay();
			// Drop the previous take before this lookup. A window with no frame of its
			// own would otherwise seed the cursor from that take's capture rect.
			activeMacCaptureBounds = null;
			const bounds =
				pick?.bounds ?? request.source.bounds ?? sourceDisplay?.bounds ?? getSelectedSourceBounds();
			const captureExcludedWindowSourceIds: string[] = [];
			if (request.source.type === "display") {
				for (const window of [getMainWindow(), getNotesWindow()]) {
					if (window && !window.isDestroyed()) {
						captureExcludedWindowSourceIds.push(window.getMediaSourceId());
					}
				}
			}
			const config: NativeMacRecordingRequest = {
				...request,
				schemaVersion: 1,
				recordingId,
				excludedWindowIds: collectMacCaptureExcludedWindowIds(captureExcludedWindowSourceIds),
				hideDesktopIcons:
					request.source.type === "display" && appSettings.getSnapshot().recording.hideDesktopIcons,
				source: {
					...request.source,
					bounds,
				},
				video: {
					...request.video,
					hideSystemCursor: cursorCaptureMode === "editable-overlay",
				},
				webcam: {
					...request.webcam,
					enabled: false,
				},
				cursor: {
					mode: cursorCaptureMode,
				},
				outputs: {
					screenPath: outputPath,
					manifestPath: path.join(
						RECORDINGS_DIR,
						`${RECORDING_FILE_PREFIX}${recordingId}${RECORDING_SESSION_SUFFIX}`,
					),
				},
			};

			console.info("[native-sck] starting macOS capture", {
				helperPath,
				source: config.source,
				excludedWindowIds: config.excludedWindowIds,
				audio: config.audio,
				webcam: config.webcam,
				cursor: config.cursor,
				outputPath,
			});

			await fs.mkdir(RECORDINGS_DIR, { recursive: true });
			nativeMacCaptureOutput = "";
			nativeMacCaptureTargetPath = outputPath;
			nativeMacCaptureRecordingId = recordingId;
			nativeMacCursorOffsetMs = 0;
			nativeMacCursorCaptureMode = cursorCaptureMode;
			nativeMacCursorRecordingStartMs = 0;
			nativeMacPauseStartedAtMs = null;
			nativeMacPauseRanges = [];
			nativeMacIsPaused = false;
			nativeMacStopInFlight = false;
			nativeMacRecordingWarning = null;
			// Before the cursor session samples. A legacy window otherwise normalises
			// its opening samples against the display, and a picker window would keep
			// the picker's frame after the helper has reported the content rect it is
			// actually recording (#1130). Display takes stay unset, so the display
			// bounds remain authoritative.
			if (isMacWindowCaptureSourceId(selectedSource?.id) && bounds.width > 0 && bounds.height > 0) {
				activeMacCaptureBounds = bounds;
			}

			const cursorStartTimeMs = Date.now();
			if (cursorCaptureMode === "editable-overlay") {
				nativeMacCursorRecordingStartMs = cursorStartTimeMs;
				await startCursorRecording(cursorStartTimeMs);
			} else {
				pendingCursorRecordingData = null;
			}

			const proc = pickerSession
				? pickerSession.startTake(config)
				: spawn(helperPath, [JSON.stringify(config)], {
						cwd: RECORDINGS_DIR,
						stdio: ["pipe", "pipe", "pipe"],
					});
			nativeMacCaptureProcess = proc;
			// When the take ends without the user — the helper reported an error or
			// exited — this drives the renderer's own stop, the same one the tray's Stop
			// Recording sends: it clears the HUD and surfaces the result.
			attachNativeMacCaptureOutputDrain(
				proc,
				() => {
					const hudWindow = getMainWindow();
					if (hudWindow && !hudWindow.isDestroyed()) {
						hudWindow.webContents.send("stop-recording-from-tray");
					}
				},
				() => {
					const hudWindow = getMainWindow();
					if (hudWindow && !hudWindow.isDestroyed()) {
						hudWindow.webContents.send("native-mac-system-audio-unavailable");
					}
				},
			);

			const captureStartedAtMs = (await waitForNativeMacCaptureStart(proc)) ?? Date.now();
			const microphoneDefaulted =
				request.audio.microphone.enabled && readMicrophoneDefaulted(nativeMacCaptureOutput);
			if (microphoneDefaulted) {
				console.warn("[native-sck] recording the default input; microphone was not resolved", {
					deviceId: request.audio.microphone.deviceId,
					deviceName: request.audio.microphone.deviceName,
				});
			}
			// Where this happens the app offers no microphone (#700). A take that asks for one
			// anyway (`openscreen record --mic`) records without it, and this line is what the
			// CLI prints about it.
			const microphoneUnavailable =
				request.audio.microphone.enabled && readMicrophoneUnavailable(nativeMacCaptureOutput);
			if (microphoneUnavailable) {
				console.warn(
					"[native-sck] recording without the microphone; ScreenCaptureKit captures it from macOS 15",
					{ macOS: process.getSystemVersion() },
				);
			}
			const microphoneNotFound =
				request.audio.microphone.enabled && readMicrophoneNotFound(nativeMacCaptureOutput);
			if (microphoneNotFound) {
				console.warn("[native-sck] recording without the microphone; macOS lists no audio input");
			}
			nativeMacCursorOffsetMs =
				cursorCaptureMode === "editable-overlay"
					? Math.max(0, captureStartedAtMs - cursorStartTimeMs)
					: 0;

			const source = selectedSource || { name: "Screen" };
			setAppRecording(true, source.name);

			return {
				success: true,
				recordingId,
				path: outputPath,
				helperPath,
				startedAtMs: captureStartedAtMs,
				microphoneDefaulted,
				microphoneUnavailable,
				microphoneNotFound,
			};
		} catch (error) {
			console.error("Failed to start native macOS recording:", error);
			const failedOutputPath = nativeMacCaptureTargetPath;
			nativeMacCaptureProcess?.kill();
			nativeMacCaptureProcess = null;
			nativeMacCaptureTargetPath = null;
			nativeMacCaptureRecordingId = null;
			nativeMacCursorOffsetMs = 0;
			nativeMacCursorCaptureMode = "editable-overlay";
			nativeMacCursorRecordingStartMs = 0;
			nativeMacPauseStartedAtMs = null;
			nativeMacPauseRanges = [];
			nativeMacIsPaused = false;
			if (failedOutputPath) {
				await removeEmptyCaptureOutput(failedOutputPath);
			}
			await stopCursorRecording();
			return { success: false, error: error instanceof Error ? error.message : String(error) };
		}
	});

	ipcMain.handle("pause-native-mac-recording", async () => {
		if (process.platform !== "darwin") {
			return { success: false, error: "Native macOS capture requires macOS." };
		}

		const proc = nativeMacCaptureProcess;
		if (!proc) {
			return { success: false, error: "Native macOS capture is not running." };
		}
		if (nativeMacIsPaused) {
			return { success: true };
		}
		if (!proc.stdin.writable) {
			return { success: false, error: "Native macOS capture command channel is closed." };
		}

		try {
			proc.stdin.write("pause\n");
			nativeMacIsPaused = true;
			nativeMacPauseStartedAtMs = Date.now();
			return { success: true };
		} catch (error) {
			return { success: false, error: error instanceof Error ? error.message : String(error) };
		}
	});

	ipcMain.handle("resume-native-mac-recording", async () => {
		if (process.platform !== "darwin") {
			return { success: false, error: "Native macOS capture requires macOS." };
		}

		const proc = nativeMacCaptureProcess;
		if (!proc) {
			return { success: false, error: "Native macOS capture is not running." };
		}
		if (!nativeMacIsPaused) {
			return { success: true };
		}
		if (!proc.stdin.writable) {
			return { success: false, error: "Native macOS capture command channel is closed." };
		}

		try {
			proc.stdin.write("resume\n");
			completeNativeMacCursorPauseRange();
			nativeMacIsPaused = false;
			return { success: true };
		} catch (error) {
			return { success: false, error: error instanceof Error ? error.message : String(error) };
		}
	});

	ipcMain.handle("pause-native-windows-recording", async () => {
		const proc = nativeWindowsCaptureProcess;
		if (!proc) {
			return { success: false, error: "Native Windows capture is not running." };
		}
		if (nativeWindowsIsPaused) {
			return { success: true };
		}
		if (!proc.stdin.writable) {
			return { success: false, error: "Native Windows capture command channel is closed." };
		}

		try {
			proc.stdin.write("pause\n");
			nativeWindowsIsPaused = true;
			nativeWindowsPauseStartedAtMs = Date.now();
			return { success: true };
		} catch (error) {
			return { success: false, error: error instanceof Error ? error.message : String(error) };
		}
	});

	ipcMain.handle("resume-native-windows-recording", async () => {
		const proc = nativeWindowsCaptureProcess;
		if (!proc) {
			return { success: false, error: "Native Windows capture is not running." };
		}
		if (!nativeWindowsIsPaused) {
			return { success: true };
		}
		if (!proc.stdin.writable) {
			return { success: false, error: "Native Windows capture command channel is closed." };
		}

		try {
			proc.stdin.write("resume\n");
			completeNativeWindowsCursorPauseRange();
			nativeWindowsIsPaused = false;
			return { success: true };
		} catch (error) {
			return { success: false, error: error instanceof Error ? error.message : String(error) };
		}
	});

	ipcMain.handle("stop-native-windows-recording", async (_, discard?: boolean) => {
		const proc = nativeWindowsCaptureProcess;
		const preferredPath = nativeWindowsCaptureTargetPath;
		const preferredWebcamPath = nativeWindowsCaptureWebcamTargetPath;
		const recordingId = nativeWindowsCaptureRecordingId ?? Date.now();
		const cursorCaptureMode = nativeWindowsCursorCaptureMode;

		if (!proc) {
			return { success: false, error: "Native Windows capture is not running." };
		}

		// Discarding does not need a finalized file, so it must not wait for one.
		// Cancel and Restart both route here, and making them sit through the
		// full stop handshake meant a wedged helper could not be escaped from at
		// all -- the user waited out the timeout only to be told the recording
		// failed, then waited it out again to cancel. Linux has always done this;
		// Windows never did.
		if (discard) {
			try {
				completeNativeWindowsCursorPauseRange();
				await stopCursorRecording();
				pendingCursorRecordingData = null;
				const exited = await terminateNativeWindowsCapture(proc);
				if (!exited) {
					detachNativeWindowsCaptureOutputDrain();
				}
				await removeNativeWindowsCaptureOutputs(preferredPath, preferredWebcamPath);
				return { success: true, discarded: true };
			} finally {
				// Unconditional. Killing a wedged helper can itself throw, and
				// leaving the handle set would make every later recording fail
				// with "already running" against a process nobody can stop.
				resetNativeWindowsCaptureState();
				setAppRecording(false, (selectedSource || { name: "Screen" }).name);
			}
		}

		// Set when the helper failed its stop handshake but left a playable
		// fragmented file. Reported so a bug report can tell a clean stop from a
		// recovered one; the user-facing path is deliberately identical.
		let recovered = false;

		try {
			completeNativeWindowsCursorPauseRange();
			const stopPromise = waitForNativeWindowsCaptureStop({
				proc,
				targetPath: preferredPath,
				readOutput: () => nativeWindowsCaptureOutput,
			});
			if (!sendNativeWindowsStopCommand(proc)) {
				console.warn("[native-wgc] stop command channel was already closed");
			}
			const stopResult = await stopPromise;
			if (!stopResult.ok) {
				console.error("[native-wgc] stop failed", {
					reason: stopResult.reason,
					exited: stopResult.exited,
					pid: proc.pid,
					output: stopResult.message,
				});
				if (!stopResult.exited) {
					detachNativeWindowsCaptureOutputDrain();
				}

				// A failed stop stopped meaning a lost take when the helper started
				// writing fragmented MP4. The file on disk is already playable, so
				// the only thing standing between the user and their recording is
				// this function deciding to throw it away and say so. Fall through
				// into the normal save path instead: same manifest, same media
				// links, same editor. From the user's side it simply worked, minus
				// at most the last incomplete fragment.
				//
				// Only once the helper is actually dead. `exited: false` means it
				// survived even the forced kill -- stuck somewhere `TerminateProcess`
				// could not reach -- and on Windows such a process still holds the
				// MP4 open and may still be appending to it. Handing that file to
				// the editor trades an honest failure for a sharing violation on a
				// file that is still moving, so a wedged helper keeps the old answer.
				if (stopResult.exited && (await salvageNativeWindowsFragmentedCapture(preferredPath))) {
					console.warn("[native-wgc] stop failed but the fragmented output is playable", {
						reason: stopResult.reason,
						path: preferredPath,
					});
					recovered = true;
				} else {
					await stopCursorRecording();
					// Same as the discard path. `startCursorRecording` clears this on
					// the next recording anyway, so this is not what keeps the samples
					// from being written next to someone else's video -- it just stops
					// a lost take's telemetry from sitting in memory until then.
					pendingCursorRecordingData = null;
					// Reaching here means the container was the plain one, whose only
					// index is written by the `Finalize()` this stop never reached, so
					// what is on disk really is an unindexed stub and leaving those
					// behind just accumulates unplayable recordings the user cannot
					// explain. Size-gate it anyway: throwing away a recording to tidy
					// up after a failed stop is the worse mistake of the two, and the
					// gate is the same one the salvage check above uses.
					await removeNativeWindowsCaptureOutputs(preferredPath, preferredWebcamPath, {
						onlyIfUnusable: true,
					});
					// The helper log goes to console/diagnostics above, not into this
					// string: it ends up in a toast, and pasting an entire capture log
					// into the HUD tells the user nothing they can act on.
					return {
						success: false,
						reason: stopResult.reason,
						error:
							stopResult.reason === "stop-timeout"
								? "Timed out waiting for native Windows capture to stop. The recording could not be saved."
								: stopResult.message.split(/\r?\n/).filter(Boolean).at(-1) ||
									"Native Windows capture failed.",
					};
				}
			}

			// Only a successful stop names the file; the salvage path above falls
			// through with `ok: false` and nothing but the path we asked for.
			const screenVideoPath = (stopResult.ok ? stopResult.screenVideoPath : null) || preferredPath;
			if (!screenVideoPath) {
				throw new Error("Native Windows capture did not return an output path.");
			}

			if (cursorCaptureMode === "editable-overlay") {
				await stopCursorRecording();
			} else {
				pendingCursorRecordingData = null;
			}

			if (cursorCaptureMode === "editable-overlay") {
				compactPendingCursorTelemetryPauseRanges(nativeWindowsPauseRanges);
				shiftPendingCursorTelemetry(nativeWindowsCursorOffsetMs);
				await writePendingCursorTelemetry(screenVideoPath);
			}
			let webcamVideoPath: string | undefined;
			if (preferredWebcamPath) {
				try {
					// Size, not just existence. A camera that opened but delivered no
					// frame still gets a file created for it, and its `Finalize()` then
					// fails, leaving nought bytes on disk. Admitting that file put a
					// camera track in the document pointing at something no demuxer can
					// read, and the preview compositor answers an unreadable camera by
					// drawing the SCREEN recording inside the little camera rectangle —
					// which is how a webcam that never recorded showed up as the desktop
					// duplicated into its own corner (getopenscreen/openscreen#387).
					const webcamStat = await fs.stat(preferredWebcamPath);
					webcamVideoPath = webcamStat.size > 0 ? preferredWebcamPath : undefined;
					if (!webcamVideoPath) {
						console.warn("[native-wgc] the webcam file is empty; saving without a camera", {
							path: preferredWebcamPath,
						});
					}
				} catch {
					webcamVideoPath = undefined;
				}
			}
			const session: RecordingSession = webcamVideoPath
				? { screenVideoPath, webcamVideoPath, createdAt: recordingId, cursorCaptureMode }
				: { screenVideoPath, createdAt: recordingId, cursorCaptureMode };
			setCurrentRecordingSessionState(session);
			currentProjectPath = null;

			const sessionManifestPath = path.join(
				RECORDINGS_DIR,
				`${path.parse(screenVideoPath).name}${RECORDING_SESSION_SUFFIX}`,
			);
			await fs.writeFile(sessionManifestPath, JSON.stringify(session, null, 2), "utf-8");
			await registerRecordingMediaLinks(screenVideoPath, { webcamVideoPath, cursorCaptureMode });

			return {
				success: true,
				path: screenVideoPath,
				session,
				recovered,
				// `preferredWebcamPath` is non-null only for a take that asked for a
				// camera, so the pair means "a camera was requested and none survived".
				// This is the second, quieter way to lose one: the helper opened the
				// device happily and then never got a frame out of it, so it reports no
				// `webcam-unavailable` and the start-time notice stays silent. Left
				// unreported, the user would find out in the editor — which is exactly
				// the silence this change exists to end.
				webcamDropped: Boolean(preferredWebcamPath) && !webcamVideoPath,
				message: recovered
					? "Native Windows recording recovered from a failed stop"
					: "Native Windows recording session stored successfully",
			};
		} catch (error) {
			console.error("Failed to stop native Windows recording:", error);
			await stopCursorRecording();
			return { success: false, error: String(error) };
		} finally {
			resetNativeWindowsCaptureState();
			const source = selectedSource || { name: "Screen" };
			setAppRecording(false, source.name);
		}
	});

	ipcMain.handle("stop-native-mac-recording", async (_, discard?: boolean) => {
		if (process.platform !== "darwin") {
			return { success: false, error: "Native macOS capture requires macOS." };
		}

		const proc = nativeMacCaptureProcess;
		const preferredPath = nativeMacCaptureTargetPath;
		const recordingId = nativeMacCaptureRecordingId ?? Date.now();
		const cursorCaptureMode = nativeMacCursorCaptureMode;

		if (!proc) {
			return { success: false, error: "Native macOS capture is not running." };
		}

		nativeMacStopInFlight = true;
		try {
			completeNativeMacCursorPauseRange();
			// Listen before sending, so a helper that stops at once cannot slip past.
			const stopResultPromise = waitForNativeMacCaptureStop({
				proc,
				targetPath: preferredPath,
				readOutput: () => nativeMacCaptureOutputs.get(proc) ?? "",
				readExit: () => nativeMacCaptureExits.get(proc) ?? null,
			});
			sendNativeMacStopCommand(proc);
			const stopResult = await stopResultPromise;

			if (cursorCaptureMode === "editable-overlay") {
				await stopCursorRecording();
			} else {
				pendingCursorRecordingData = null;
			}
			if (discard) {
				pendingCursorRecordingData = null;
				await Promise.all(
					nativeMacDiscardTargets(stopResult, preferredPath).map((target) =>
						fs.rm(target, { force: true }),
					),
				);
				if (!stopResult.ok) {
					console.warn("[native-sck] discarded a take whose stop did not complete", {
						reason: stopResult.reason,
						message: stopResult.message,
					});
				}
				return { success: true, discarded: true };
			}
			let screenVideoPath: string;
			let warning: string | undefined;
			let recovered = false;
			if (stopResult.ok) {
				screenVideoPath = stopResult.screenVideoPath;
				warning = stopResult.warning;
				if (warning) {
					console.warn(
						"[native-sck] the take ended before it was stopped; its recording was kept",
						{
							warning,
							path: screenVideoPath,
						},
					);
				}
			} else {
				// A helper that exited left a file nothing writes to any more, and what its
				// writer finished before the failure is usually a playable fragmented take.
				// One still running may be mid-write, so it is left alone.
				const salvageTarget = nativeMacSalvageTarget(stopResult, preferredPath);
				const salvage = salvageTarget ? await salvageNativeMacCapture(salvageTarget) : null;
				if (!salvage || !salvage.ok) {
					pendingCursorRecordingData = null;
					console.error("Failed to stop native macOS recording:", {
						reason: stopResult.reason,
						message: stopResult.message,
						helperExited: stopResult.exited,
						salvage: salvage ? salvage.reason : "not attempted: the helper had not exited",
						output: (nativeMacCaptureOutputs.get(proc) ?? "").trim(),
					});
					return { success: false, error: stopResult.message };
				}
				screenVideoPath = salvage.screenVideoPath;
				warning = describeSalvagedTake(stopResult.message, salvage.durationSec);
				recovered = true;
				console.warn("[native-sck] recovered the part of the take written before its stop failed", {
					stopFailure: stopResult.message,
					path: screenVideoPath,
					videoSamples: salvage.videoSamples,
					durationSec: salvage.durationSec,
					truncatedBytes: salvage.truncatedBytes,
				});
			}
			nativeMacRecordingWarning = warning ? { screenVideoPath, message: warning } : null;

			// A recovered take most often follows a disk that filled up, and these writes
			// go to the same volume. The video is already safe on disk, so for a recovered
			// take a failed side write is logged, and its partial file removed, instead of
			// turning the recovery back into a lost take.
			const writeAlongside = async (label: string, target: string, write: () => Promise<void>) => {
				if (!recovered) {
					await write();
					return;
				}
				try {
					await write();
				} catch (error) {
					console.warn(`[native-sck] could not write the recovered take's ${label}:`, error);
					await fs.rm(target, { force: true }).catch(() => undefined);
				}
			};

			if (cursorCaptureMode === "editable-overlay") {
				compactPendingCursorTelemetryPauseRanges(nativeMacPauseRanges);
				shiftPendingCursorTelemetry(nativeMacCursorOffsetMs);
				await writeAlongside("cursor telemetry", `${screenVideoPath}.cursor.json`, () =>
					writePendingCursorTelemetry(screenVideoPath),
				);
			}

			const session: RecordingSession = {
				screenVideoPath,
				createdAt: recordingId,
				cursorCaptureMode,
			};
			setCurrentRecordingSessionState(session);
			currentProjectPath = null;

			const sessionManifestPath = path.join(
				RECORDINGS_DIR,
				`${path.parse(screenVideoPath).name}${RECORDING_SESSION_SUFFIX}`,
			);
			await writeAlongside("session manifest", sessionManifestPath, () =>
				fs.writeFile(sessionManifestPath, JSON.stringify(session, null, 2), "utf-8"),
			);
			await registerRecordingMediaLinks(screenVideoPath, { cursorCaptureMode });

			return {
				success: true,
				path: screenVideoPath,
				session,
				message: recovered
					? "Native macOS recording recovered from a failed stop"
					: "Native macOS recording session stored successfully",
				...(warning ? { warning } : {}),
				...(recovered ? { recovered: true } : {}),
			};
		} catch (error) {
			console.error("Failed to stop native macOS recording:", error);
			await stopCursorRecording();
			return { success: false, error: error instanceof Error ? error.message : String(error) };
		} finally {
			nativeMacStopInFlight = false;
			nativeMacCaptureProcess = null;
			nativeMacCaptureTargetPath = null;
			nativeMacCaptureRecordingId = null;
			nativeMacCursorOffsetMs = 0;
			nativeMacCursorCaptureMode = "editable-overlay";
			nativeMacCursorRecordingStartMs = 0;
			nativeMacPauseStartedAtMs = null;
			nativeMacPauseRanges = [];
			nativeMacIsPaused = false;
			activeMacCaptureBounds = null;
			const source = selectedSource || { name: "Screen" };
			setAppRecording(false, source.name);
		}
	});

	// On-disk write streams for in-progress recordings, keyed by output file name.
	// Chunks append as they arrive so the renderer never buffers the full video (#616).
	// Declared here because both the webcam attach below and store-recorded-session
	// finalize through the same registry.
	const recordingStreams = new RecordingStreamRegistry();
	registerRecordingStreamHandlers(ipcMain, recordingStreams, resolveRecordingOutputPath);

	/**
	 * Writes a browser-recorded webcam clip next to a natively-recorded screen
	 * video and rewrites the session manifest to include both.
	 *
	 * Shared by macOS and Linux, whose native helpers both leave the camera to
	 * the renderer's `MediaRecorder`: opening the device a second time from the
	 * helper would fight the preview for an exclusive claim, and buys nothing
	 * that the screen capture needs. (Windows is the exception — its helper takes
	 * the webcam through DirectShow so both streams share one start clock.)
	 *
	 * Nothing in here is platform-specific; the two `ipcMain.handle` calls below
	 * differ only in which platform they accept.
	 */
	const attachNativeWebcamRecording = async (
		platformLabel: string,
		payload: AttachNativeMacWebcamRecordingInput,
	) => {
		try {
			{
				const screenVideoPath = normalizeVideoSourcePath(payload.screenVideoPath);
				if (!screenVideoPath || !isPathWithinDir(screenVideoPath, RECORDINGS_DIR)) {
					return {
						success: false,
						error: `Native ${platformLabel} webcam attachment requires a recording output path.`,
					};
				}

				await fs.access(screenVideoPath, fsConstants.R_OK);

				if (!payload.webcam?.fileName) {
					return {
						success: false,
						error: `Native ${platformLabel} webcam attachment is missing video data.`,
					};
				}

				const webcamVideoPath = resolveRecordingOutputPath(payload.webcam.fileName);
				// A streamed webcam arrives with an empty buffer: its bytes are already on
				// disk, so close the stream and keep the file rather than writing it here.
				// Nothing multi-gigabyte crosses IPC or gets flattened into one Buffer (#253).
				const webcamStreamed = await finalizeRecordingFile(
					recordingStreams,
					payload.webcam.fileName,
					webcamVideoPath,
					payload.webcam.videoData,
				);
				// Mirrors finalizeRecordingFile's own condition, so this fires exactly when
				// it wrote nothing and the session would point at a file that isn't there.
				if (
					!webcamStreamed &&
					!(payload.webcam.videoData && payload.webcam.videoData.byteLength > 0)
				) {
					return {
						success: false,
						error: `Native ${platformLabel} webcam attachment is missing video data.`,
					};
				}
				// Streamed files lack the WebM Duration header, which the editor needs to
				// scale its timeline. Best-effort: a failed repair leaves the clip intact.
				if (webcamStreamed && isValidDurationMs(payload.durationMs)) {
					await repairRecordingContainer(webcamVideoPath, payload.durationMs);
				}

				const createdAt =
					typeof payload.recordingId === "number" && Number.isFinite(payload.recordingId)
						? payload.recordingId
						: Date.now();
				const cursorCaptureMode = normalizeCursorCaptureMode(payload.cursorCaptureMode);
				const webcamOffsetMs = Number.isFinite(payload.webcamOffsetMs)
					? payload.webcamOffsetMs
					: undefined;
				const session: RecordingSession = {
					screenVideoPath,
					webcamVideoPath,
					createdAt,
					...(webcamOffsetMs !== undefined ? { webcamOffsetMs } : {}),
					...(cursorCaptureMode ? { cursorCaptureMode } : {}),
				};
				setCurrentRecordingSessionState(session);
				currentProjectPath = null;

				const sessionManifestPath = path.join(
					RECORDINGS_DIR,
					`${path.parse(screenVideoPath).name}${RECORDING_SESSION_SUFFIX}`,
				);
				await fs.writeFile(sessionManifestPath, JSON.stringify(session, null, 2), "utf-8");
				await registerRecordingMediaLinks(screenVideoPath, {
					webcamVideoPath,
					webcamOffsetMs,
					cursorCaptureMode,
				});

				return {
					success: true,
					path: screenVideoPath,
					session,
					message: `Native ${platformLabel} webcam recording attached successfully`,
				};
			}
		} catch (error) {
			console.error(`Failed to attach native ${platformLabel} webcam recording:`, error);
			return {
				success: false,
				error: error instanceof Error ? error.message : String(error),
			};
		}
	};

	ipcMain.handle(
		"attach-native-mac-webcam-recording",
		async (_, payload: AttachNativeMacWebcamRecordingInput) => {
			if (process.platform !== "darwin") {
				return { success: false, error: "Native macOS webcam attachment requires macOS." };
			}
			return attachNativeWebcamRecording("macOS", payload);
		},
	);

	ipcMain.handle(
		"attach-native-linux-webcam-recording",
		async (_, payload: AttachNativeMacWebcamRecordingInput) => {
			if (process.platform !== "linux") {
				return { success: false, error: "Native Linux webcam attachment requires Linux." };
			}
			return attachNativeWebcamRecording("Linux", payload);
		},
	);

	ipcMain.handle("store-recorded-session", async (_, payload: StoreRecordedSessionInput) => {
		try {
			return await storeRecordedSessionFiles(payload);
		} catch (error) {
			console.error("Failed to store recording session:", error);
			return {
				success: false,
				message: "Failed to store recording session",
				error: String(error),
			};
		}
	});

	async function storeRecordedSessionFiles(payload: StoreRecordedSessionInput) {
		const createdAt =
			typeof payload.createdAt === "number" && Number.isFinite(payload.createdAt)
				? payload.createdAt
				: Date.now();
		const cursorCaptureMode = normalizeCursorCaptureMode(payload.cursorCaptureMode);
		const screenVideoPath = resolveRecordingOutputPath(payload.screen.fileName);
		const screenStreamed = await finalizeRecordingFile(
			recordingStreams,
			payload.screen.fileName,
			screenVideoPath,
			payload.screen.videoData,
		);

		let webcamVideoPath: string | undefined;
		let webcamStreamed = false;
		if (payload.webcam) {
			webcamVideoPath = resolveRecordingOutputPath(payload.webcam.fileName);
			webcamStreamed = await finalizeRecordingFile(
				recordingStreams,
				payload.webcam.fileName,
				webcamVideoPath,
				payload.webcam.videoData,
			);
		}

		// MediaRecorder occasionally produces a 0-byte file on Windows
		// when the display stream is captured but no frames are produced (the
		// streaming WriteStream was opened but never received any chunks). Detect
		// the bad file here so the recording fails loudly instead of opening the
		// editor on a file the <video> element can't decode. The WebM EBML header
		// alone is ~33 bytes; 1KB rules out a header-only file with no frames.
		const MIN_VALID_BYTES = 1024;
		try {
			const screenStat = await fs.stat(screenVideoPath);
			if (screenStat.size < MIN_VALID_BYTES) {
				await fs.unlink(screenVideoPath).catch(() => undefined);
				if (webcamVideoPath) {
					await fs.unlink(webcamVideoPath).catch(() => undefined);
				}
				return {
					success: false,
					message: `Screen recording is empty (${screenStat.size} bytes). The screen capture did not produce any frames — this can happen on Windows when the display source changes during recording. Try recording again.`,
				};
			}
		} catch (statError) {
			// file missing is fatal; any other stat error is non-fatal, the
			// editor will surface the load error on its own.
			if ((statError as NodeJS.ErrnoException).code === "ENOENT") {
				return {
					success: false,
					message: "Screen recording file is missing on disk.",
				};
			}
		}

		// Streamed files lack the WebM Duration header (renderer no longer holds the
		// blob), so repair the container on disk for the editor's seek bar and timeline.
		// Best-effort, independent per file, so they run together.
		if (isValidDurationMs(payload.durationMs)) {
			const patches: Promise<unknown>[] = [];
			if (screenStreamed) {
				patches.push(repairRecordingContainer(screenVideoPath, payload.durationMs));
			}
			if (webcamStreamed && webcamVideoPath) {
				patches.push(repairRecordingContainer(webcamVideoPath, payload.durationMs));
			}
			await Promise.all(patches);
		}

		const webcamOffsetMs =
			webcamVideoPath && Number.isFinite(payload.webcamOffsetMs)
				? payload.webcamOffsetMs
				: undefined;
		const session: RecordingSession = webcamVideoPath
			? {
					screenVideoPath,
					webcamVideoPath,
					createdAt,
					...(webcamOffsetMs !== undefined ? { webcamOffsetMs } : {}),
					...(cursorCaptureMode ? { cursorCaptureMode } : {}),
				}
			: { screenVideoPath, createdAt, ...(cursorCaptureMode ? { cursorCaptureMode } : {}) };
		// Sidecar BEFORE the session is published, as the three native stop paths already
		// do it. Publishing first opens a window where `getCurrentRecordingSession` hands
		// the editor a take whose `.cursor.json` is not on disk yet, and the editor's
		// fresh-take auto-zoom reads that file the moment it imports -- an empty read there
		// is indistinguishable from a take with no click, so the zooms are silently
		// skipped.
		await writePendingCursorTelemetry(screenVideoPath);
		setCurrentRecordingSessionState(session);
		currentProjectPath = null;

		const sessionManifestPath = path.join(
			RECORDINGS_DIR,
			`${path.parse(payload.screen.fileName).name}${RECORDING_SESSION_SUFFIX}`,
		);
		await fs.writeFile(sessionManifestPath, JSON.stringify(session, null, 2), "utf-8");
		await registerRecordingMediaLinks(screenVideoPath, {
			webcamVideoPath,
			webcamOffsetMs,
			cursorCaptureMode,
		});

		return {
			success: true,
			path: screenVideoPath,
			session,
			message: "Recording session stored successfully",
		};
	}

	ipcMain.handle("store-recorded-video", async (_, videoData: ArrayBuffer, fileName: string) => {
		try {
			return await storeRecordedSessionFiles({
				screen: { videoData, fileName },
				createdAt: Date.now(),
			});
		} catch (error) {
			console.error("Failed to store recorded video:", error);
			return {
				success: false,
				message: "Failed to store recorded video",
				error: String(error),
			};
		}
	});

	ipcMain.handle("get-recorded-video-path", async () => {
		try {
			if (currentRecordingSession?.screenVideoPath) {
				return { success: true, path: currentRecordingSession.screenVideoPath };
			}

			const files = await fs.readdir(RECORDINGS_DIR);
			const videoFiles = files.filter(
				(file) => file.endsWith(".webm") && !file.endsWith("-webcam.webm"),
			);

			if (videoFiles.length === 0) {
				return { success: false, message: "No recorded video found" };
			}

			const latestVideo = videoFiles.sort().reverse()[0];
			const videoPath = path.join(RECORDINGS_DIR, latestVideo);

			return { success: true, path: videoPath };
		} catch (error) {
			console.error("Failed to get video path:", error);
			return { success: false, message: "Failed to get video path", error: String(error) };
		}
	});

	ipcMain.handle(
		"set-recording-state",
		async (
			_,
			recording: boolean,
			recordingId?: number,
			cursorCaptureMode?: CursorCaptureMode,
			reserveOnly?: boolean,
		) => {
			if (recording && isWindowsUpdatePending()) {
				return { success: false, error: WINDOWS_UPDATE_PENDING_MESSAGE };
			}
			const source = selectedSource || { name: "Screen" };
			if (recording) {
				// Claim the take synchronously, before cursor setup yields to an updater.
				setAppRecording(recording, source.name, true);
				if (reserveOnly) return { success: true };
			}
			const normalizedCursorCaptureMode =
				normalizeCursorCaptureMode(cursorCaptureMode) ?? "editable-overlay";
			if (recording && normalizedCursorCaptureMode === "editable-overlay") {
				await startCursorRecording(recordingId);
			} else {
				await stopCursorRecording();
			}

			setAppRecording(recording, source.name);
			return { success: true };
		},
	);

	ipcMain.handle("get-cursor-telemetry", async (_, videoPath?: string) => {
		const targetVideoPath = resolveApprovedVideoPath(
			videoPath ?? currentRecordingSession?.screenVideoPath,
		);
		if (!targetVideoPath) {
			return { success: true, samples: [] };
		}

		return readCursorTelemetryFile(targetVideoPath);
	});

	// Protocol allowlist. `shell.openExternal` hands the string to the OS handler,
	// so `file:`, `ms-msdt:`, a UNC path, or any registered custom scheme is a
	// launch primitive — the renderer runs with webSecurity:false and now renders
	// model-generated content, so "the renderer is trusted" is not a strong enough
	// premise to skip this. http/https/mailto is everything the app actually opens.
	const EXTERNAL_URL_PROTOCOLS = new Set(["http:", "https:", "mailto:"]);

	ipcMain.handle("open-external-url", async (_, url: string) => {
		try {
			const parsed = new URL(url);
			if (!EXTERNAL_URL_PROTOCOLS.has(parsed.protocol)) {
				console.warn(`Refused to open external URL with protocol ${parsed.protocol}`);
				return { success: false, error: `Unsupported URL protocol: ${parsed.protocol}` };
			}
			await shell.openExternal(parsed.toString());
			return { success: true };
		} catch (error) {
			console.error("Failed to open URL:", error);
			return { success: false, error: String(error) };
		}
	});

	// Return base path for assets so renderer can resolve file:// paths in production
	ipcMain.handle("get-asset-base-path", () => {
		return resolveAssetBasePath();
	});

	ipcMain.handle(
		"pick-export-save-path",
		async (event, fileName: string, exportFolder?: string) => {
			try {
				const isGif = fileName.toLowerCase().endsWith(".gif");
				const filters = isGif
					? [{ name: mainT("dialogs", "fileDialogs.gifImage"), extensions: ["gif"] }]
					: [{ name: mainT("dialogs", "fileDialogs.mp4Video"), extensions: ["mp4"] }];

				// Prefer the user's last export folder if it still exists, else ~/Downloads.
				// Validate here because the renderer can't stat the filesystem.
				let defaultDir = app.getPath("downloads");
				if (exportFolder) {
					try {
						const stats = await fs.stat(exportFolder);
						if (stats.isDirectory()) {
							defaultDir = exportFolder;
						}
					} catch (err) {
						console.warn(
							`Could not access remembered export folder "${exportFolder}", falling back to Downloads:`,
							err,
						);
					}
				}
				const dialogOptions: Electron.SaveDialogOptions = {
					title: isGif
						? mainT("dialogs", "fileDialogs.saveGif")
						: mainT("dialogs", "fileDialogs.saveVideo"),
					defaultPath: path.join(defaultDir, fileName),
					filters,
					properties: ["createDirectory", "showOverwriteConfirmation"],
				};
				const result = await showSaveDialogOver(
					BrowserWindow.fromWebContents(event.sender),
					dialogOptions,
				);

				if (result.canceled || !result.filePath) {
					return { success: false, canceled: true, message: "Export canceled" };
				}

				return { success: true, path: path.normalize(result.filePath) };
			} catch (error) {
				console.error("Failed to show save dialog:", error);
				return {
					success: false,
					message: "Failed to show save dialog",
					error: String(error),
				};
			}
		},
	);

	ipcMain.handle("write-export-to-path", async (_, videoData: ArrayBuffer, filePath: string) => {
		try {
			// Sanity-check the path: the renderer is trusted (contextIsolation on), but a
			// stale-state bug shouldn't be able to clobber arbitrary files.
			if (typeof filePath !== "string" || !path.isAbsolute(filePath)) {
				return { success: false, message: "Invalid path" };
			}
			const lower = filePath.toLowerCase();
			if (![".mp4", ".gif", ".wav", ".m4a"].some((extension) => lower.endsWith(extension))) {
				return { success: false, message: "Invalid file type" };
			}

			const normalizedPath = path.normalize(filePath);
			await fs.mkdir(path.dirname(normalizedPath), { recursive: true });
			await fs.writeFile(normalizedPath, Buffer.from(videoData));

			return {
				success: true,
				path: normalizedPath,
				message: "Video exported successfully",
			};
		} catch (error) {
			console.error("Failed to write exported video:", error);
			return {
				success: false,
				message: "Failed to save exported video",
				error: String(error),
			};
		}
	});

	// The media tab imports VIDEO (it arranges clips). Audio is imported from the
	// timeline toolbar instead (issue #350) — see `open-audio-file-picker` below.
	ipcMain.handle("open-video-file-picker", async (event) => {
		try {
			const dialogOptions: Electron.OpenDialogOptions = {
				title: mainT("dialogs", "fileDialogs.selectVideo"),
				defaultPath: RECORDINGS_DIR,
				filters: [
					{
						name: mainT("dialogs", "fileDialogs.videoFiles"),
						extensions: ["webm", "mp4", "mov", "avi", "mkv", "m4v", "wmv", "flv", "ts"],
					},
					{ name: mainT("dialogs", "fileDialogs.allFiles"), extensions: ["*"] },
				],
				properties: ["openFile"],
			};
			const result = await showOpenDialogOver(
				BrowserWindow.fromWebContents(event.sender),
				dialogOptions,
			);

			if (result.canceled || result.filePaths.length === 0) {
				return { success: false, canceled: true };
			}

			const normalizedPath = await approveReadableVideoPath(result.filePaths[0]);
			if (!normalizedPath) {
				return {
					success: false,
					message: "Selected file is not a supported readable video file",
				};
			}

			currentProjectPath = null;
			return {
				success: true,
				path: normalizedPath,
			};
		} catch (error) {
			console.error("Failed to open file picker:", error);
			return {
				success: false,
				message: "Failed to open file picker",
				error: String(error),
			};
		}
	});

	// Import an external audio file (voiceover / BGM / SFX) — issue #350. Driven by
	// the timeline's "Add audio" tool: audio is a timeline overlay (like an
	// annotation), not a media-tab clip, so it has its own audio-only picker and the
	// renderer adds it as a kind:"audio" asset + track at the playhead.
	ipcMain.handle("open-audio-file-picker", async (event) => {
		try {
			const dialogOptions: Electron.OpenDialogOptions = {
				title: mainT("dialogs", "fileDialogs.selectAudio"),
				defaultPath: RECORDINGS_DIR,
				filters: [
					{
						name: mainT("dialogs", "fileDialogs.audioFiles"),
						extensions: ["mp3", "wav", "m4a", "aac", "flac", "ogg", "opus"],
					},
					{ name: mainT("dialogs", "fileDialogs.allFiles"), extensions: ["*"] },
				],
				properties: ["openFile"],
			};
			const result = await showOpenDialogOver(
				BrowserWindow.fromWebContents(event.sender),
				dialogOptions,
			);

			if (result.canceled || result.filePaths.length === 0) {
				return { success: false, canceled: true };
			}

			const normalizedPath = await approveReadableAudioPath(result.filePaths[0]);
			if (!normalizedPath) {
				return {
					success: false,
					message: "Selected file is not a supported readable audio file",
				};
			}

			return {
				success: true,
				path: normalizedPath,
			};
		} catch (error) {
			console.error("Failed to open audio file picker:", error);
			return {
				success: false,
				message: "Failed to open audio file picker",
				error: String(error),
			};
		}
	});

	// In-editor voiceover recording: the renderer hands over the raw MediaRecorder
	// blob (webm/opus) and gets back the path it landed at, under the recordings
	// dir so it lives with the project's other media and survives relaunches.
	ipcMain.handle("save-recorded-voiceover", async (_event, data: ArrayBuffer) => {
		try {
			if (!(data instanceof ArrayBuffer) || data.byteLength === 0) {
				return { success: false, message: "Empty recording" };
			}
			// A cap, because this writes renderer-supplied bytes straight to disk. An
			// hour of Opus is a few tens of MB, so 512 MB is far past any real take
			// and still refuses a runaway or malformed payload before it is buffered.
			if (data.byteLength > MAX_RECORDED_VOICEOVER_BYTES) {
				return { success: false, message: "Recording too large" };
			}
			await fs.mkdir(RECORDINGS_DIR, { recursive: true });
			const fileName = `voiceover-${new Date().toISOString().replace(/[:.]/g, "-")}.webm`;
			const target = path.join(RECORDINGS_DIR, fileName);
			await fs.writeFile(target, Buffer.from(data));
			return { success: true, path: target };
		} catch (error) {
			console.error("Failed to save recorded voiceover:", error);
			return {
				success: false,
				message: "Failed to save recorded voiceover",
				error: String(error),
			};
		}
	});

	// The two click-sound samples the editor ships (src/lib/ai-edition/clickSound.ts). The
	// compositor reads its audio from the filesystem, not from a renderer URL, so the bundled
	// bytes are staged here once and the absolute path handed back. Renderer bytes like the
	// recorded voiceover, but with nothing to sanitise: the name is checked against the two the
	// app knows, so the payload cannot steer where anything lands.
	ipcMain.handle("stage-click-sound-hit", async (_event, name: string, data: ArrayBuffer) => {
		try {
			if (!CLICK_SOUND_HIT_FILES.includes(name)) {
				return { success: false, message: `Unknown click hit ${name}` };
			}
			if (!(data instanceof ArrayBuffer) || data.byteLength === 0) {
				return { success: false, message: "Empty click hit" };
			}
			if (data.byteLength > MAX_CLICK_HIT_BYTES) {
				return { success: false, message: "Click hit too large" };
			}
			const target = path.join(CLICK_SOUND_DIR, name);
			await fs.mkdir(CLICK_SOUND_DIR, { recursive: true });
			// Written fresh each time rather than checked for existence: the file the app shipped
			// is the one the compositor must hear, and an update may have changed it.
			await fs.writeFile(target, Buffer.from(data));
			return { success: true, path: target };
		} catch (error) {
			console.error("Failed to stage click sound hit:", error);
			return { success: false, message: "Failed to stage click sound hit", error: String(error) };
		}
	});

	ipcMain.handle("reveal-in-folder", async (_, filePath: string) => {
		try {
			// showItemInFolder returns nothing, it throws on error
			shell.showItemInFolder(filePath);
			return { success: true };
		} catch (error) {
			console.error(`Error revealing item in folder: ${filePath}`, error);
			// Fall back to opening the directory if revealing fails (file moved/deleted
			// after export, or a path showItemInFolder rejects).
			try {
				const openPathResult = await shell.openPath(path.dirname(filePath));
				if (openPathResult) {
					// openPath returned an error message
					return { success: false, error: openPathResult };
				}
				return { success: true, message: "Could not reveal item, but opened directory." };
			} catch (openError) {
				console.error(`Error opening directory: ${path.dirname(filePath)}`, openError);
				return { success: false, error: String(error) };
			}
		}
	});

	ipcMain.handle("read-binary-file", async (_, filePath: string) => {
		try {
			const normalizedPath = readableApprovedPath(filePath);
			if (!normalizedPath) {
				return {
					success: false,
					message: "File path is not approved or is not a supported video file",
				};
			}

			const data = await fs.readFile(normalizedPath);
			return {
				success: true,
				data: data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength),
				path: normalizedPath,
			};
		} catch (error) {
			console.error("Failed to read binary file:", error);
			return {
				success: false,
				message: "Failed to read binary file",
				error: String(error),
			};
		}
	});

	// Stat an approved video file. Used to decide whether a recording is small
	// enough to slurp via read-binary-file, or large enough that it must be
	// streamed in chunks (Node's fs.readFile caps a single read at 2 GiB, so any
	// recording above that can never be loaded whole — see read-file-chunk).
	ipcMain.handle("get-readable-file-info", async (_, filePath: string) => {
		try {
			const normalizedPath = readableApprovedPath(filePath);
			if (!normalizedPath) {
				return {
					success: false,
					message: "File path is not approved or is not a supported video file",
				};
			}

			const stat = await fs.stat(normalizedPath);
			return {
				success: true,
				size: stat.size,
				mtimeMs: stat.mtimeMs,
				path: normalizedPath,
			};
		} catch (error) {
			console.error("Failed to stat file:", error);
			return {
				success: false,
				message: "Failed to stat file",
				error: String(error),
			};
		}
	});

	// Waveform peaks for a timeline clip, decoded natively (see media/audioPeaks).
	// The renderer's own pipelines take ~12s on a 32-minute recording because they
	// decode the whole track in Chromium; ffmpeg does the same work in ~2s off the
	// UI process, and the result is cached on disk so it is paid once per file.
	// `peaks: null` means "no native path available" — the caller falls back to
	// its own decoding rather than losing the waveform.
	ipcMain.handle(
		"get-audio-peaks",
		async (_, filePath: string, durationSec: number): Promise<AudioPeaksResult> => {
			try {
				// Same approval gate as every other read of a renderer-supplied path.
				const normalizedPath = readableApprovedPath(filePath);
				if (!normalizedPath) {
					return { success: false, message: "File path is not approved" };
				}
				const peaks = await getAudioPeaks(normalizedPath, durationSec);
				return { success: true, peaks };
			} catch (error) {
				// A clip with no audio track lands here. Degrade quietly: the renderer
				// draws no waveform, which is correct, and logs its own warning.
				return { success: false, message: String(error) };
			}
		},
	);

	// The loudness-normalisation gain the export applies to a voice file, measured by the
	// compositor over the whole file and cached there, so the preview plays the voice at the
	// level the export writes it. `gainDb: 0` whenever there is nothing to apply — no addon, a
	// file with no audio, a failed read — which is the preview as it played before.
	const loudnessService = new CompositorViewService();
	ipcMain.handle(
		"get-loudness-gain",
		async (
			_,
			filePath: string,
		): Promise<{ success: boolean; gainDb: number; message?: string }> => {
			try {
				// Same approval gate as every other read of a renderer-supplied path.
				const normalizedPath = readableApprovedPath(filePath);
				if (!normalizedPath) {
					return { success: false, gainDb: 0, message: "File path is not approved" };
				}
				return {
					success: true,
					gainDb: (await loudnessService.loudnessGainDb(normalizedPath)) ?? 0,
				};
			} catch (error) {
				return { success: false, gainDb: 0, message: String(error) };
			}
		},
	);

	// Cap renderer-requested chunk sizes so a buggy or compromised renderer
	// cannot make the main process allocate an arbitrarily large buffer.
	const MAX_IPC_CHUNK_BYTES = 64 * 1024 * 1024;

	// Read a byte range [offset, offset+length) from an approved video file.
	// Lets the renderer stream a >2 GiB recording into OPFS one chunk at a time
	// instead of materialising the whole file in memory, which fs.readFile cannot
	// do (2 GiB cap) and a 16 GB machine cannot hold for multi-GB recordings.
	ipcMain.handle("read-file-chunk", async (_, filePath: string, offset: number, length: number) => {
		try {
			const normalizedPath = readableApprovedPath(filePath);
			if (!normalizedPath) {
				return {
					success: false,
					message: "File path is not approved or is not a supported video file",
				};
			}
			if (!Number.isFinite(offset) || offset < 0 || !Number.isFinite(length) || length <= 0) {
				return { success: false, message: "Invalid chunk range" };
			}
			if (length > MAX_IPC_CHUNK_BYTES) {
				return { success: false, message: "Requested chunk size exceeds limit" };
			}

			const handle = await fs.open(normalizedPath, "r");
			try {
				const buffer = Buffer.allocUnsafe(length);
				const { bytesRead } = await handle.read(buffer, 0, length, offset);
				return {
					success: true,
					data: buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + bytesRead),
					bytesRead,
				};
			} finally {
				await handle.close();
			}
		} catch (error) {
			console.error("Failed to read file chunk:", error);
			return {
				success: false,
				message: "Failed to read file chunk",
				error: String(error),
			};
		}
	});

	ipcMain.handle("prepare-preview-audio-track", async (_, filePath: string) => {
		try {
			return await prepareSupplementalPreviewAudioTrack(filePath);
		} catch (error) {
			console.error("Failed to prepare preview audio track:", error);
			return {
				success: false,
				message: "Failed to prepare preview audio track",
				error: String(error),
			};
		}
	});

	ipcMain.handle(
		"save-project-file",
		async (event, projectData: unknown, suggestedName?: string, existingProjectPath?: string) => {
			return saveProjectFile(
				projectData,
				suggestedName,
				existingProjectPath,
				BrowserWindow.fromWebContents(event.sender),
			);
		},
	);

	async function saveProjectFile(
		projectData: unknown,
		suggestedName?: string,
		existingProjectPath?: string,
		parent?: BrowserWindow | null,
	): Promise<ProjectFileResult> {
		try {
			const trustedExistingProjectPath = isTrustedProjectPath(existingProjectPath)
				? existingProjectPath
				: null;

			if (trustedExistingProjectPath) {
				await fs.writeFile(
					trustedExistingProjectPath,
					JSON.stringify(projectData, null, 2),
					"utf-8",
				);
				currentProjectPath = trustedExistingProjectPath;
				return {
					success: true,
					path: trustedExistingProjectPath,
					message: "Project saved successfully",
				};
			}

			const safeName = (suggestedName || `project-${Date.now()}`).replace(/[^a-zA-Z0-9-_]/g, "_");
			const defaultName = safeName.endsWith(`.${PROJECT_FILE_EXTENSION}`)
				? safeName
				: `${safeName}.${PROJECT_FILE_EXTENSION}`;

			const dialogOptions: Electron.SaveDialogOptions = {
				title: mainT("dialogs", "fileDialogs.saveProject"),
				defaultPath: path.join(RECORDINGS_DIR, defaultName),
				filters: [
					{
						name: mainT("dialogs", "fileDialogs.openscreenProject"),
						extensions: [PROJECT_FILE_EXTENSION],
					},
					{ name: "JSON", extensions: ["json"] },
				],
				properties: ["createDirectory", "showOverwriteConfirmation"],
			};
			const result = await showSaveDialogOver(parent, dialogOptions);

			if (result.canceled || !result.filePath) {
				return {
					success: false,
					canceled: true,
					message: "Save project canceled",
				};
			}

			await fs.writeFile(result.filePath, JSON.stringify(projectData, null, 2), "utf-8");
			currentProjectPath = result.filePath;

			return {
				success: true,
				path: result.filePath,
				message: "Project saved successfully",
			};
		} catch (error) {
			console.error("Failed to save project file:", error);
			return {
				success: false,
				message: "Failed to save project file",
				error: String(error),
			};
		}
	}

	ipcMain.handle("load-project-file", async (event, projectFolder?: string) => {
		return loadProjectFile(projectFolder, BrowserWindow.fromWebContents(event.sender));
	});

	async function loadProjectFile(
		projectFolder?: string,
		parent?: BrowserWindow | null,
	): Promise<ProjectFileResult> {
		try {
			// Default to the projects directory, where the editor actually stores
			// openable project files (one `.openscreen` per project). Prefer the user's
			// last opened-project folder if given and still valid; only fall back to
			// RECORDINGS_DIR if the projects dir doesn't exist yet (fresh install).
			// Validate here because the renderer can't stat the filesystem.
			const projectsDir = path.join(app.getPath("userData"), "projects");
			let defaultDir = RECORDINGS_DIR;
			try {
				const stats = await fs.stat(projectsDir);
				if (stats.isDirectory()) defaultDir = projectsDir;
			} catch {
				// projects dir not created yet — keep RECORDINGS_DIR fallback.
			}
			if (projectFolder) {
				try {
					const stats = await fs.stat(projectFolder);
					if (stats.isDirectory()) {
						defaultDir = projectFolder;
					}
				} catch (err) {
					// Stat can fail if the folder was moved/deleted (expected) or on a
					// permission error (worth surfacing). We fall back either way, but log it.
					console.warn(
						`Could not access remembered project folder "${projectFolder}", falling back to default:`,
						err,
					);
				}
			}
			const dialogOptions: Electron.OpenDialogOptions = {
				title: mainT("dialogs", "fileDialogs.openProject"),
				defaultPath: defaultDir,
				filters: [
					{
						name: mainT("dialogs", "fileDialogs.openscreenProject"),
						// All projects are `.openscreen`; `.axcut` is kept only so files
						// written by older builds (pre-migration) still show up.
						extensions: [PROJECT_FILE_EXTENSION, "axcut"],
					},
					{ name: "JSON", extensions: ["json"] },
					{ name: mainT("dialogs", "fileDialogs.allFiles"), extensions: ["*"] },
				],
				properties: ["openFile"],
			};
			const result = await showOpenDialogOver(parent, dialogOptions);

			if (result.canceled || result.filePaths.length === 0) {
				return { success: false, canceled: true, message: "Open project canceled" };
			}

			const filePath = result.filePaths[0];
			const content = await fs.readFile(filePath, "utf-8");
			const project = await relinkProjectMedia(JSON.parse(content), DEFAULT_RECORDINGS_DIR);
			currentProjectPath = filePath;
			let session: RecordingSession | null = null;
			try {
				session = await getApprovedProjectSession(project, filePath);
			} catch (sessionError) {
				console.warn(
					"[loadProjectFile] Could not approve session paths, proceeding without session:",
					sessionError,
				);
			}
			setCurrentRecordingSessionState(session);

			return {
				success: true,
				path: filePath,
				project,
				storedProjectId: aiEditionDocuments.storedProjectId(filePath),
			};
		} catch (error) {
			console.error("Failed to load project file:", error);
			return {
				success: false,
				message: "Failed to load project file",
				error: String(error),
			};
		}
	}

	ipcMain.handle("load-project-file-from-path", async (_event, filePath: string) => {
		return loadProjectFileFromPath(filePath);
	});

	async function loadProjectFileFromPath(filePath: string): Promise<ProjectFileResult> {
		try {
			if (!filePath || typeof filePath !== "string") {
				return { success: false, message: "Invalid file path" };
			}
			// Validate extension and readability
			if (path.extname(filePath).toLowerCase() !== `.${PROJECT_FILE_EXTENSION}`) {
				return { success: false, message: "Not an Openscreen project file" };
			}
			const stats = await fs.stat(filePath).catch(() => null);
			if (!stats?.isFile()) {
				return { success: false, message: "File not found" };
			}
			const content = await fs.readFile(filePath, "utf-8");
			const project = await relinkProjectMedia(JSON.parse(content), DEFAULT_RECORDINGS_DIR);
			currentProjectPath = filePath;
			// A document the editor saved grants the media it declares, within the same trusted
			// dirs as a legacy v2 project below: the recordings dir and the project's own dir.
			// This file came from an arbitrary path, not from the editor's projects dir.
			if (isAxcutDocumentFile(project)) {
				try {
					approveDocumentMedia(parseDocumentFile(project), [
						...getAllowedReadDirs(),
						path.dirname(path.resolve(filePath)),
					]);
				} catch {
					// Not a valid document: nothing is granted, and the caller reports the parse error.
				}
			}

			// Approve session paths but tolerate failures (e.g. video moved outside trusted
			// dirs) so the project still loads and the renderer can show "video not found".
			let session: import("../../src/lib/recordingSession").RecordingSession | null = null;
			try {
				session = await getApprovedProjectSession(project, filePath);
			} catch (sessionError) {
				console.warn(
					"[loadProjectFileFromPath] Could not approve session paths, proceeding without session:",
					sessionError,
				);
			}
			setCurrentRecordingSessionState(session);
			return {
				success: true,
				path: filePath,
				project,
				storedProjectId: aiEditionDocuments.storedProjectId(filePath),
			};
		} catch (error) {
			console.error("Failed to load project file from path:", error);
			return {
				success: false,
				message: "Failed to load project file",
				error: String(error),
			};
		}
	}

	ipcMain.handle("load-current-project-file", async () => {
		return loadCurrentProjectFile();
	});

	async function loadCurrentProjectFile(): Promise<ProjectFileResult> {
		try {
			if (!currentProjectPath) {
				return { success: false, message: "No active project" };
			}

			const content = await fs.readFile(currentProjectPath, "utf-8");
			const project = JSON.parse(content);
			setCurrentRecordingSessionState(await getApprovedProjectSession(project, currentProjectPath));
			return {
				success: true,
				path: currentProjectPath,
				project,
			};
		} catch (error) {
			console.error("Failed to load current project file:", error);
			return {
				success: false,
				message: "Failed to load current project file",
				error: String(error),
			};
		}
	}

	ipcMain.handle("set-current-video-path", async (_, path: string) => {
		return setCurrentVideoPath(path);
	});

	ipcMain.handle("set-current-recording-session", (_, session: RecordingSession | null) => {
		const normalizedSession = normalizeRecordingSession(session);
		setCurrentRecordingSessionState(normalizedSession);
		currentVideoPath = normalizedSession?.screenVideoPath ?? null;
		currentProjectPath = null;
		if (normalizedSession) mcpAppRecorder.takeSaved(normalizedSession.screenVideoPath);
		return { success: true, session: currentRecordingSession };
	});

	ipcMain.handle("get-current-recording-session", () => {
		if (!currentRecordingSession) {
			return { success: false };
		}
		const warning =
			nativeMacRecordingWarning?.screenVideoPath === currentRecordingSession.screenVideoPath
				? nativeMacRecordingWarning.message
				: undefined;
		return { success: true, session: currentRecordingSession, ...(warning ? { warning } : {}) };
	});

	// returns the webcam path (if any) for a given screen video by
	// reading its sibling session.json — drives the cameraTrack auto-link on
	// `addAsset` in the new editor's project store.
	ipcMain.handle(
		"find-recording-camera",
		async (
			_event,
			videoPath: string,
		): Promise<{
			success: boolean;
			webcamVideoPath?: string;
			offsetMs?: number;
			error?: string;
		}> => {
			try {
				const normalized = normalizeVideoSourcePath(videoPath);
				if (!normalized || !isPathAllowed(normalized)) {
					return { success: false, error: "Video path has not been approved" };
				}
				const resolution = await resolveMediaLinksForVideo(normalized);
				if (!resolution.webcamVideoPath) {
					return { success: false, error: "No camera attached to this recording" };
				}
				return {
					success: true,
					webcamVideoPath: resolution.webcamVideoPath,
					offsetMs: resolution.webcamOffsetMs ?? 0,
				};
			} catch (err) {
				return {
					success: false,
					error: err instanceof Error ? err.message : String(err),
				};
			}
		},
	);

	async function setCurrentVideoPath(path: string): Promise<ProjectPathResult> {
		const normalizedPath = normalizeVideoSourcePath(path);
		if (!normalizedPath || !isPathAllowed(normalizedPath)) {
			return {
				success: false,
				message: "Video path has not been approved",
			};
		}

		const restoredSession = await loadRecordedSessionForVideoPath(normalizedPath);
		if (restoredSession) {
			setCurrentRecordingSessionState(restoredSession);
		} else {
			setCurrentRecordingSessionState({
				screenVideoPath: normalizedPath,
				createdAt: Date.now(),
			});
		}
		currentProjectPath = null;
		return { success: true, path: currentVideoPath ?? normalizedPath };
	}

	ipcMain.handle("get-current-video-path", () => {
		return getCurrentVideoPathResult();
	});

	function getCurrentVideoPathResult(): ProjectPathResult {
		return currentVideoPath ? { success: true, path: currentVideoPath } : { success: false };
	}

	ipcMain.handle("clear-current-video-path", () => {
		return clearCurrentVideoPath();
	});

	function clearCurrentVideoPath(): ProjectPathResult {
		currentVideoPath = null;
		currentProjectPath = null;
		setCurrentRecordingSessionState(null);
		return { success: true };
	}

	// Keep the native Windows/Linux window-control overlay in the app's theme
	// colours. The renderer sends the resolved CSS values so the palette stays in
	// one place. No-op on macOS (traffic lights aren't tintable) and on any window
	// that wasn't created with an overlay, which is what setTitleBarOverlay throws on.
	ipcMain.on("set-titlebar-overlay", (event, color: string, symbolColor: string) => {
		try {
			BrowserWindow.fromWebContents(event.sender)?.setTitleBarOverlay({ color, symbolColor });
		} catch {
			// Best-effort cosmetic.
		}
	});

	ipcMain.handle("get-shortcuts", async () => {
		try {
			const data = await fs.readFile(SHORTCUTS_FILE, "utf-8");
			return JSON.parse(data);
		} catch {
			return null;
		}
	});

	ipcMain.handle("save-shortcuts", async (_, shortcuts: unknown) => {
		try {
			await fs.writeFile(SHORTCUTS_FILE, JSON.stringify(shortcuts, null, 2), "utf-8");
			return { success: true };
		} catch (error) {
			console.error("Failed to save shortcuts:", error);
			return { success: false, error: String(error) };
		}
	});

	ipcMain.handle(
		"save-diagnostic",
		async (_, payload: { error: string; stack?: string; projectState: unknown; logs: string[] }) =>
			exportDiagnosticFile(payload),
	);

	// Same one-instance rule: the service serialises its writes per instance. The folder is
	// in Documents, not userData, because presets are files users are meant to find and share.
	const stylePresets = new StylePresetService(
		path.join(app.getPath("documents"), `${PRODUCT_NAME} Presets`),
	);

	// One instance each, not one per call. DocumentService serialises saves of a
	// project through a per-INSTANCE queue (see its writeProject comment — this
	// race destroyed two real project files), so a second instance means a second
	// queue racing for the same path: temp+rename still keeps the file valid, but
	// a save can land under a concurrent one and be silently lost.
	const chatProjectsRoot = path.join(app.getPath("userData"), "projects");
	configureChatPersistence(chatProjectsRoot);
	const aiEditionDocuments = new DocumentService(
		chatProjectsRoot,
		DEFAULT_RECORDINGS_DIR,
		approveDocumentMedia,
		() => stylePresets.newProjectAppearance(),
	);

	// LlmConfigStore is single-instance for a duller reason — its constructor does
	// two sync readFileSync plus a safeStorage decrypt, and it was running on every
	// chat message. But it must also stay UNBUILT until something actually needs it:
	// on macOS that decrypt is backed by a Keychain item, so constructing it at
	// startup made every launch prompt for Keychain access, including for users who
	// never open the AI layer at all. (The prompt repeats because an unsigned or
	// ad-hoc-signed build has no stable code identity for the item's ACL to trust —
	// signing is the other half of that fix, and is not this function's business.)
	// Memoised, so the "one instance" guarantee above still holds.
	let aiEditionLlmConfigInstance: LlmConfigStore | null = null;
	const getAiEditionLlmConfig = (): LlmConfigStore => {
		if (!aiEditionLlmConfigInstance) {
			aiEditionLlmConfigInstance = new LlmConfigStore(app.getPath("userData"));
		}
		return aiEditionLlmConfigInstance;
	};

	// The local MCP server offers the agent's tools to MCP clients the user runs
	// (Claude Code, Codex…), on any project: the open one through the editor, the
	// rest through the same DocumentService instance as every other save (see
	// above for why there is only one). Built here because this is where the agent's own
	// dependencies live, but NOT started here: the headless CLI shares this
	// function and must never bind the port a running app is listening on.
	// `main.ts` starts it. Its writes have their own switch, off by default and
	// read on every call: "MCP edits", separate from the in-app agent's "Agent edits",
	// so turning the server on grants a client read access and nothing more.
	const mcpSettings = new McpSettingsStore(app.getPath("userData"), safeStorage);
	const mcpToolDeps: McpToolDeps = {
		transport: "http",
		host: new EditorDocumentHost(ipcMain),
		projects: aiEditionDocuments,
		editsAllowed: () => mcpSettings.getSettings().allowEdits,
		cursor: agentCursorTelemetryReader,
		cameraSegmentation: () => loudnessService.probeSegmentation(),
		checkShaderEffect: (code, params) => loudnessService.checkShaderEffect(code, params),
		// The editor's own engine, in this process: `openscreen mcp` transcribes without the app.
		transcribe: (request) => getSttManager().transcribe(request),
		version: app.getVersion(),
		// importMedia: the editor's own probe, and the grant a picked file gets, so the editor
		// can play a file a client imported into the project it has open.
		openVideo: openVideoInHiddenWindow,
		approveMedia: (filePath) => {
			const media = normalizeVideoSourcePath(filePath);
			if (media && hasAllowedImportMediaExtension(media)) approveFilePath(media);
		},
	};
	// One runner, so one queue and one checkpoint store, for the in-app server and every
	// `openscreen mcp` the app answers through its channel (app-channel.ts, started by main.ts).
	const mcpRunTool = createToolRunner(mcpToolDeps);

	// The in-app server's media tools. listSources and exportVideo run the CLI's hidden
	// runners in this process, their IPC registered on first use: never in the headless
	// CLI, which registers its own and never starts this server.
	let mcpRunnerHost: ReturnType<typeof createRunnerHost<BrowserWindow>> | null = null;
	const mcpRunners: MediaToolDeps["runners"] = {
		start(request, handlers) {
			mcpRunnerHost ??= createRunnerHost(ipcMain, createRunnerWindow);
			return mcpRunnerHost.start(request, handlers);
		},
	};

	/**
	 * Points the HUD at a client's take, as Record mode does before it hands over, and
	 * returns what puts back what the user had. Restored once the take is captured, so the
	 * user's own source and settings are what their next take starts from.
	 */
	async function pointHudAtTake(request: RecordRequest): Promise<() => void> {
		// The devices first: finding them changes nothing, so a miss leaves all as it was.
		let listed: CliSourcesResult | null = null;
		if ((request.mic && request.micDevice) || (request.camera && request.cameraDevice)) {
			// Their ids as well as their names, both of which the HUD records with: a renderer's to read.
			const run = mcpRunners.start({ kind: "sources" });
			listed = (await run.done.finally(() => run.close())).sources ?? null;
		}
		const next = takePrefs(request, listed);

		const before = { source: selectedSource, live: selectedDesktopSource };
		const restoreSource = () => {
			selectedSource = before.source;
			selectedDesktopSource = before.live;
			broadcastSelectedSource(before.source);
		};
		if (process.platform === "linux" && findPipeWireCursorHelperPath()) {
			// The portal asks the user once the take starts: nothing here to select.
		} else {
			// Where Apple's picker owns the bar's sources, a named take still records what it
			// names: the picker would wait for a person (#1232, see macNamedTake.ts).
			if (macPickerOwnsSources()) {
				const access = await readMacScreenCaptureAccess();
				if (!namedTakeMayEnumerate(access.status)) {
					throw new Error(NAMED_TAKE_NEEDS_SCREEN_ACCESS);
				}
			}
			try {
				// The list listSources shows, in its order: its display indexes are this list's.
				const sources = await getSourcesForPickers({
					types: ["screen", "window"],
					thumbnailSize: { width: 0, height: 0 },
				});
				const picked = pickRecordingSource(sources, request);
				if (!(await selectSource(picked, { persist: false }))) {
					throw new Error(`"${picked.name}" can no longer be recorded. Call listSources again.`);
				}
			} catch (error) {
				// A failed pick may have cleared the selection: the user's comes back.
				restoreSource();
				throw error;
			}
		}

		const userPrefs = pickTakePrefs(recordingPrefs.get());
		recordingPrefs.set(next);
		// The prefs are saved to disk: a quit mid-take must not leave the client's for the next
		// launch. ponytail: a crash still does; keep them in memory only if that bites.
		const restore = () => {
			app.off("will-quit", restore);
			recordingPrefs.set(userPrefs);
			restoreSource();
		};
		app.once("will-quit", restore);
		return restore;
	}

	const mcpAppRecorder = createAppRecorder({
		isRecording: () => appRecording,
		editorHasUnsavedChanges: () => editorHasUnsavedChanges?.() ?? false,
		prepare: pointHudAtTake,
		startTake: startNewRecording,
		stopTake: () => {
			const hudWindow = getMainWindow();
			if (hudWindow && !hudWindow.isDestroyed()) {
				hudWindow.webContents.send("stop-recording-from-tray");
			}
		},
		host: mcpToolDeps.host,
	});
	const mcpMedia = createMediaTools({
		transport: "http",
		// Recording and exporting change things too: the same switch as edits.
		editsAllowed: mcpToolDeps.editsAllowed,
		recorder: mcpAppRecorder,
		runners: mcpRunners,
		documents: aiEditionDocuments,
		openVideo: openVideoInHiddenWindow,
		renderFrames: (...args) => loudnessService.renderFrames(...args),
		readCursor: async (videoPath) => (await readCursorTelemetryFile(videoPath)).samples,
		// Never overriding the switch: setPointerTrack is refused while MCP edits is off.
		runTool: mcpRunTool,
	});
	const mcpController = new McpController(mcpSettings, mcpToolDeps, mcpRunTool, mcpMedia);

	// The editor says which project it holds, so `openscreen mcp`, a process of its own
	// that cannot ask it, refuses to edit that project behind its back (#1138).
	// Only the window that set the marker clears it, so an older window going away
	// never unmarks the project a newer one holds.
	let markedBy: WebContents | null = null;
	const watchedEditors = new WeakSet<WebContents>();
	ipcMain.on(AI_EDITION_OPEN_PROJECT_CHANNEL, (event, projectId: unknown) => {
		const id = typeof projectId === "string" ? projectId : null;
		if (id === null && markedBy !== null && markedBy !== event.sender) return;
		markedBy = id === null ? null : event.sender;
		aiEditionDocuments.markOpenInEditor(id);
		if (watchedEditors.has(event.sender)) return;
		watchedEditors.add(event.sender);
		event.sender.once("destroyed", () => {
			if (markedBy !== event.sender) return;
			markedBy = null;
			aiEditionDocuments.markOpenInEditor(null);
		});
	});

	registerNativeBridgeHandlers({
		getPlatform: () => process.platform,
		getCurrentProjectPath: () => currentProjectPath,
		getCurrentVideoPath: () => currentVideoPath,
		saveProjectFile,
		loadProjectFile,
		loadCurrentProjectFile,
		loadProjectFileFromPath,
		setCurrentVideoPath,
		getCurrentVideoPathResult,
		clearCurrentVideoPath,
		resolveAssetBasePath,
		resolveVideoPath: (videoPath?: string | null) =>
			normalizeVideoSourcePath(videoPath ?? currentVideoPath),
		loadCursorRecordingData: readCursorRecordingFile,
		loadCursorTelemetry: readCursorTelemetryFile,
		// compositor view's createView needs the renderer-owning
		// BrowserWindow's native handle (HWND on Windows, NSView* on macOS).
		// Same ownership rules as desktopCapturer: `BrowserWindow.fromWebContents`
		// gives us the window that hosts this sender; `getNativeWindowHandle`
		// is the platform-native parent handle the D3D11 addon parents its
		// child window to.
		getNativeWindowHandle: (sender) => {
			const window = BrowserWindow.fromWebContents(sender);
			if (!window || window.isDestroyed()) {
				return null;
			}
			try {
				return window.getNativeWindowHandle();
			} catch {
				return null;
			}
		},
		getAiEditionDocuments: () => aiEditionDocuments,
		getRecordingsDirs: () => ({
			dirs: getAllowedReadDirs(),
			registryDir: DEFAULT_RECORDINGS_DIR,
		}),
		getStylePresets: () => stylePresets,
		getAiEditionLlmConfig,
		runAiEditionChat: (projectId, sessionId, message, document, sink, signal) =>
			runChat(projectId, sessionId, message, getAiEditionLlmConfig(), document, sink, {
				signal,
				cursor: agentCursorTelemetryReader,
				cameraSegmentation: () => loudnessService.probeSegmentation(),
				checkShaderEffect: (code, params) => loudnessService.checkShaderEffect(code, params),
			}),
		undoAiEditionToolBatch: (_projectId, _sessionId) => ({
			success: false,
			error: "Per-tool-batch undo retired in favor of per-message rewind.",
		}),
		rewindToMessage: (projectId, sessionId, messageId) =>
			rewindToMessage(projectId, sessionId, messageId),
		compactNow: (projectId, sessionId) =>
			compactSessionNow(projectId, sessionId, getAiEditionLlmConfig()),
		getContextUsage: getSessionContextUsage,
		listAiEditionChatSessions: (projectId) => listSessions(projectId),
		createAiEditionChatSession: (projectId, title) => createSession(projectId, title),
		selectAiEditionChatSession: (projectId, sessionId) => selectSession(projectId, sessionId),
		renameAiEditionChatSession: (projectId, sessionId, title) =>
			renameSession(projectId, sessionId, title),
		deleteAiEditionChatSession: (projectId, sessionId) => deleteSession(projectId, sessionId),
		getMcpController: () => mcpController,
	});

	// `openscreen mcp` serves the same tools on stdio, from the CLI process.
	return {
		mcpController,
		mcpAppChannel: { deps: mcpToolDeps, runTool: mcpRunTool },
		agentServices: {
			mcpToolDeps,
			documents: aiEditionDocuments,
			// getFrames without an export: this process's compositor renders them.
			renderFrames: loudnessService.renderFrames.bind(loudnessService),
			// The reader the export runner's auto zoom reads through.
			readCursorTelemetry: async (videoPath: string) =>
				(await readCursorTelemetryFile(videoPath)).samples,
		},
	};
}