Skip to content

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

38.0 KB
Raw Blame
import fs from "node:fs";
import { createRequire } from "node:module";
import path from "node:path";
import { fileURLToPath } from "node:url";
import {
	app,
	BrowserWindow,
	screen,
	sharedTexture,
	type WebFrameMain,
	webContents,
} from "electron";
import type { ShaderEffectCheck } from "../../../src/lib/ai-edition/shaderEffects";
import {
	type CursorKind,
	readCursorAsArrow,
	resolveCursorSprites,
} from "../../../src/lib/cursor/cursorThemes";
import type {
	CompositorSharedFrameMeta,
	CompositorSharedFrameReceipt,
} from "../../../src/native/contracts";
import type { ExportJob } from "../../ipc/exportJobs";
import type {
	ClipInput,
	CompositorBackend,
	CompositorParamValue,
	CompositorViewAddon,
	CompositorViewRect,
	ExportParamsInput,
	ExportStats,
	GifExportStats,
	GifParamsInput,
	NativeFramePacket,
	NativeSharedFramePacket,
	RemuxStats,
	SegmentationSupport,
} from "../../native/compositor-view/addon";

/**
 * ESM-safe `require` for loading the native addon
 * (`compositor_view.node`). The electron main bundle is ESM at the source
 * level; `require()` isn't available at the top level. `createRequire` keeps
 * the addon require dynamic so vite/rollup never tries to bundle the native
 * binary.
 */
const localRequire: NodeRequire = createRequire(import.meta.url) as unknown as NodeRequire;

/**
 * `existsSync` that answers for the REAL filesystem, not Electron's asar-transparent view of it.
 *
 * Electron patches `fs` so JS can read `.../app.asar/dist/wallpapers/x.jpg` as if it were a plain
 * file — that's the entire point of asar. But `existsSync` inherits the same patch: called on an
 * asar-internal path it returns `true`, even though nothing outside Electron's own patched `fs`
 * can ever open that path — the Rust addon calls the raw OS `fopen`/`CreateFile`, which has no
 * concept of asar and gets ENOENT. A candidate-probe loop built on the patched `fs.existsSync`
 * therefore locks onto the WRONG candidate (VITE_PUBLIC, pointing into the asar) before ever
 * trying the right one (`resourcesPath`, real files on disk) — confirmed by running this exact
 * check inside the packaged binary: patched `existsSync` on the asar path answered `true`.
 *
 * `original-fs` is Electron's escape hatch for precisely this: the same API, unpatched. It only
 * exists inside Electron, so fall back to plain `node:fs` where it doesn't — under plain Node
 * (tests) there is no asar patch to route around in the first place, so plain `fs` already tells
 * the truth there.
 */
function realExistsSync(candidate: string): boolean {
	try {
		return (localRequire("original-fs") as typeof fs).existsSync(candidate);
	} catch {
		return fs.existsSync(candidate);
	}
}

/**
 * Bases holding the `wallpapers/` and `cursors/` trees, most specific first.
 *
 * `VITE_PUBLIC` is right in dev (`<root>/public`) and WRONG when packaged, where it points at
 * `<resources>/app.asar/dist`: vite copies `public/` into `dist`, so the files are there — but
 * inside the asar archive. Only Electron's patched `fs` can read through an asar, and the
 * compositor is a Rust addon calling `image::open` on a raw OS path, so every themed cursor
 * sprite and every bundled wallpaper silently failed to load in an installed build. The cursor
 * fell back to its default art (a theme pick looked like it did nothing) and the background fell
 * back to a flat colour. A CUSTOM uploaded image kept working throughout, because it travels as a
 * `data:` URL the addon decodes in memory rather than a path — which is exactly the asymmetry that
 * pinned this down.
 *
 * `extraResources` copies both trees to `<resources>/{wallpapers,cursors}` as real files (see
 * electron-builder.json5, whose own "Asset layout contract" comment names this), so
 * `process.resourcesPath` is the packaged answer. Probing for existence rather than branching on
 * `app.isPackaged` keeps `--dir` staging builds and tests working too, and mirrors the
 * candidate-list idiom `ffmpegSharedBinCandidates` already uses below. Same base dir as
 * `ASSET_BASE_DIR` in electron/windows.ts, which resolves these two trees for the renderer.
 */
function sceneAssetBaseDirs(): string[] {
	return [process.env.VITE_PUBLIC, process.resourcesPath].filter(
		(dir): dir is string => typeof dir === "string" && dir.length > 0,
	);
}

/** First base under which `relativePath` actually exists, joined; null when none does (leave the
 *  scene's own value alone rather than hand the addon a path we know is not there). */
export function resolveSceneAssetPath(relativePath: string): string | null {
	for (const base of sceneAssetBaseDirs()) {
		const candidate = path.join(base, relativePath);
		if (realExistsSync(candidate)) {
			return candidate;
		}
	}
	return null;
}

/** One cursor sprite as the compositor reads it (`SceneCursorSprite` in `scene.rs`). */
type SceneCursorSprite = {
	path: string;
	hotspotX: number;
	hotspotY: number;
	sculpt?: string;
	glass?: string;
};

/**
 * The theme's sprite set with every `assetPath` turned into an absolute on-disk path.
 *
 * Entries whose file doesn't resolve are dropped rather than passed through: the addon
 * would fail to decode them and fall back to its placeholder anyway, and a missing entry
 * lets it fall back to the arrow instead, which is closer to right.
 */
function resolveCursorSpritePaths(
	themeId: string,
	asArrow: readonly CursorKind[],
	model3d = false,
): Record<string, SceneCursorSprite> {
	const resolved: Record<string, SceneCursorSprite> = {};
	for (const [type, sprite] of Object.entries(resolveCursorSprites(themeId, asArrow, model3d))) {
		const absolute = resolveSceneAssetPath(sprite.assetPath);
		if (absolute) {
			resolved[type] = {
				path: absolute,
				hotspotX: sprite.hotspotX,
				hotspotY: sprite.hotspotY,
				...(sprite.sculpt ? { sculpt: sprite.sculpt } : {}),
				...(sprite.glass ? { glass: sprite.glass } : {}),
			};
		}
	}
	return resolved;
}

/** Where the segmentation model sits under `public/`, and therefore under `dist/` once Vite
 *  has copied it. Resolved here rather than in the renderer: the compositor runs in this
 *  process, and the renderer has no business knowing the on-disk layout. */
const SEGMENTATION_MODEL_ASSET = "mediapipe/selfie_segmentation/selfie_segmentation_landscape.onnx";

export function resolveSceneAssetPaths(sceneJson: string): string {
	try {
		const scene = JSON.parse(sceneJson) as {
			background?: { kind?: string; path?: string };
			cursor?: {
				theme?: string;
				asArrow?: unknown;
				model3d?: boolean;
				cursorSprites?: Record<string, SceneCursorSprite>;
			};
			webcamEffect?: {
				mode?: string;
				modelPath?: string;
				background?: { kind?: string; path?: string };
			};
		};
		let changed = false;
		// Both backgrounds go through this: the screen's, and the camera's under the "custom"
		// mode. The camera one was missed, and the failure is silent — the compositor gets
		// "/wallpapers/wallpaper1.jpg", `image::open` cannot find it, and the PiP falls back to
		// a flat colour with only a line on stderr to say so.
		const resolveBackgroundImage = (target?: { kind?: string; path?: string }): boolean => {
			if (
				target?.kind !== "image" ||
				typeof target.path !== "string" ||
				!target.path.startsWith("/")
			) {
				return false;
			}
			// strip the leading slash so path.join keeps it under the base dir
			const resolved = resolveSceneAssetPath(target.path.replace(/^\/+/, ""));
			if (!resolved) {
				return false;
			}
			target.path = resolved;
			return true;
		};
		changed = resolveBackgroundImage(scene.background) || changed;
		changed = resolveBackgroundImage(scene.webcamEffect?.background) || changed;
		if (scene.cursor && typeof scene.cursor.theme === "string") {
			scene.cursor.cursorSprites = resolveCursorSpritePaths(
				scene.cursor.theme,
				readCursorAsArrow(scene.cursor.asArrow, undefined, []),
				scene.cursor.model3d === true,
			);
			changed = true;
		}
		// The scene asks for an effect; this process says where the model is. A model that
		// does not resolve leaves `modelPath` unset, which turns the effect off in the
		// compositor rather than failing the scene — same contract as a missing cursor sprite.
		const effect = scene.webcamEffect;
		if (effect && typeof effect.mode === "string" && effect.mode !== "none") {
			const resolved = resolveSceneAssetPath(SEGMENTATION_MODEL_ASSET);
			if (resolved) {
				effect.modelPath = resolved;
				changed = true;
			}
		}
		return changed ? JSON.stringify(scene) : sceneJson;
	} catch {
		return sceneJson;
	}
}

export interface CompositorViewServiceOptions {
	/** Explicit in-process addon, used by tests of native job lifecycle. */
	addon?: CompositorViewAddon;
	/**
	 * Optional explicit override for the addon path. Has precedence over the
	 * `OPENSCREEN_COMPOSITOR_VIEW_NODE` env var and the candidate path list.
	 * Useful for poking at a locally-built `.node` without copying it into
	 * the standard search root.
	 */
	envOverride?: string | null;
	/**
	 * Directory to resolve candidate paths relative to. Defaults to
	 * `app.getAppPath()` so dev (unpackaged) and packaged setups resolve the
	 * same relative path. Tests can inject a temp directory here.
	 */
	appRoot?: string;
	isPackaged?: boolean;
	/** Electron's `sharedTexture` module, injectable for tests. `null` keeps every view on
	 *  read-back. */
	sharedTexture?: SharedTextureApi | null;
	/** Whether Chromium composites on the GPU, where a shared texture is imported. Injectable
	 *  for tests; defaults to `app.getGPUFeatureStatus()`. */
	gpuCompositing?: () => boolean;
	/** Refresh rate of the display the frame's window is on, `null` when unknown. Injectable for
	 *  tests; defaults to Electron's `screen`. */
	displayHz?: (target: WebFrameMain) => number | null;
}

/**
 * How long a shared frame's ring slot stays out of the render thread's reach after Chromium has
 * let go of it. Chromium lets go when the renderer drops its references, which is as soon as it
 * has issued the draw into the canvas, not once the GPU has run it: the copy runs when the frame
 * carrying it is drawn, up to a vsync later. A slot written again before that copy put a later
 * frame on the canvas, then the one in between, so the picture and the cursor stepped back a frame
 * (tens of times in 18 s at 60 Hz, a few at 280 Hz). 40 ms took the steps back to none at both
 * rates. On a slower display the copy can come later still: see `sharedSlotHoldMs`.
 */
export const SHARED_SLOT_RELEASE_DELAY_MS = 40;

/** How long to hold a released slot for a window on a `hz` display: two of its frames, never less
 *  than `SHARED_SLOT_RELEASE_DELAY_MS` (67 ms at 30 Hz, 40 ms from 50 Hz up). */
export function sharedSlotHoldMs(hz: number | null): number {
	if (!hz || !Number.isFinite(hz) || hz <= 0) return SHARED_SLOT_RELEASE_DELAY_MS;
	return Math.max(SHARED_SLOT_RELEASE_DELAY_MS, Math.ceil(2000 / hz));
}

function defaultDisplayHz(target: WebFrameMain): number | null {
	try {
		const contents = webContents.fromFrame(target);
		const win = contents && BrowserWindow.fromWebContents(contents);
		return win ? screen.getDisplayMatching(win.getBounds()).displayFrequency : null;
	} catch {
		return null;
	}
}

/** The two calls a shared preview frame needs from Electron's `sharedTexture` module. */
export type SharedTextureApi = Pick<
	Electron.SharedTexture,
	"importSharedTexture" | "sendSharedTexture"
>;

function defaultGpuCompositing(): boolean {
	try {
		return String(app.getGPUFeatureStatus().gpu_compositing).startsWith("enabled");
	} catch {
		return false;
	}
}

function defaultAppRoot(): string {
	try {
		return app.getAppPath();
	} catch {
		// bare-node test environment — fall back to the source tree root
		// via this file's location (service lives at
		// electron/native-bridge/services/, project root is four levels up).
		const here = path.dirname(fileURLToPath(import.meta.url));
		return path.resolve(here, "..", "..", "..", "..");
	}
}

function defaultIsPackaged(): boolean {
	try {
		return app.isPackaged;
	} catch {
		return false;
	}
}

function platformArchTag(): string {
	const platformPrefix =
		process.platform === "win32" ? "win32" : process.platform === "darwin" ? "darwin" : "linux";
	return process.arch === "arm64" ? `${platformPrefix}-arm64` : `${platformPrefix}-x64`;
}

/**
 * Bases that may hold `electron/native/…`, most specific first.
 *
 * `appRoot` alone is not enough, and was not enough on either side of the packaged
 * line:
 *
 *  - **Unpackaged.** `app.getAppPath()` resolves to the directory holding the entry
 *    script, i.e. `<repo>/dist-electron` — the entry every dev run uses, `npm run dev`
 *    included. Joining `electron/native/...` onto that gives
 *    `<repo>/dist-electron/electron/native/...`, which no build step ever writes, so
 *    the loader fell through to "addon not present; running as no-op" and the editor
 *    silently ran without a compositor. Walking up to the first ancestor that actually
 *    has an `electron/native` finds the checkout root.
 *  - **Packaged.** `electron/native/bin/<tag>/**` ships exclusively through
 *    `extraResources` (see electron-builder.json5's mac/win/linux blocks), so it lands
 *    at `<resources>/electron/native/bin/<tag>` and is never inside `app.asar` — the
 *    `.asar` → `.asar.unpacked` rewrite below cannot reach it either, since the file
 *    was never in the archive. `process.resourcesPath` is the base that holds it.
 *
 * Same pair of bases `ffmpegSharedBinCandidates` already walks for the ffmpeg dir; the
 * addon needs it for exactly the same reason.
 */
function nativeAssetBaseDirs(appRoot: string): string[] {
	const bases = [appRoot];
	// Bounded walk: dist-electron → repo root is one level, but a nested layout could
	// be deeper. Stop at the filesystem root rather than looping.
	let dir = appRoot;
	for (let i = 0; i < 4; i += 1) {
		const parent = path.dirname(dir);
		if (parent === dir) {
			break;
		}
		dir = parent;
		if (fs.existsSync(path.join(dir, "electron", "native"))) {
			bases.push(dir);
			break;
		}
	}
	if (typeof process.resourcesPath === "string" && process.resourcesPath.length > 0) {
		bases.push(process.resourcesPath);
	}
	return bases;
}

export function buildCandidatePaths(
	appRoot: string,
	isPackaged: boolean,
	envOverride: string | null | undefined,
): string[] {
	const tag = platformArchTag();
	const perBase = nativeAssetBaseDirs(appRoot).flatMap((base) => [
		path.join(base, "electron", "native", "bin", tag, "compositor_view.node"),
		path.join(base, "electron", "native", "compositor-view", "build", "compositor_view.node"),
	]);
	const ordered = [envOverride, ...perBase].filter(
		(value): value is string => typeof value === "string" && value.length > 0,
	);
	if (!isPackaged) {
		return ordered;
	}
	// in packaged builds, references inside `app.asar/...` must be
	// rewritten to `.asar.unpacked/...` so dynamic `require()` can load the
	// native binary (matches the capture-helper resolution policy).
	return ordered.map((candidate) => candidate.replace(/\.asar([/\\])/, ".asar.unpacked$1"));
}

/**
 * The dev-vendored ffmpeg tree, read from the pin that already exists rather
 * than named a second time here: `crates/.cargo/config.toml`'s `FFMPEG_DIR`.
 *
 * That pin is the one thing the addon is actually built against (see the
 * config's own comment), so the DLL basenames it imports — `avcodec-62.dll` and
 * friends — only match the tree it points at. Restating the folder name in this
 * file is precisely how the previous entry rotted: the pin moved off a floating
 * `master-latest` snapshot onto the fixed `n8.1.2` release and this list went on
 * probing a directory that no longer existed. Nothing broke, because the search
 * silently fell through to the vendored `electron/native/bin/<tag>` — which is
 * what makes the rot worth removing rather than tolerating.
 *
 * Returns null when there is no config to read: packaged builds ship no
 * `crates/` at all, and the candidate list simply starts one entry later.
 */
function pinnedFfmpegDir(appRoot: string): string | null {
	const crateDir = path.join(appRoot, "crates");
	let toml: string;
	try {
		toml = fs.readFileSync(path.join(crateDir, ".cargo", "config.toml"), "utf8");
	} catch {
		return null;
	}
	// Both spellings cargo accepts carry the path as the first quoted string on
	// the line: `FFMPEG_DIR = "…"` and `FFMPEG_DIR = { value = "…", relative = true }`.
	const value = /^\s*FFMPEG_DIR\s*=.*?"([^"]+)"/m.exec(toml)?.[1];
	if (!value) {
		return null;
	}
	// `relative = true` resolves against the directory the config governs (the
	// crate root), which is also what the pin's own comment documents.
	return path.isAbsolute(value) ? value : path.join(crateDir, value);
}

/**
 * Directories that may hold the ffmpeg shared DLLs (avcodec/avformat/avutil/…)
 * the addon dynamically links against. Node's `require()` of a native addon
 * does a Win32 `LoadLibrary` under the hood, which resolves dependent DLLs via
 * the standard search order — including `PATH` — so whichever of these exists
 * gets prepended to `process.env.PATH` before the `require()` in
 * `tryLoadAddon`.
 *
 * Order: the dev-only vendored location first (absent outside a source
 * checkout — see `pinnedFfmpegDir`), then the arch-tagged bin dir under
 * `appRoot` (dev / `electron-builder --dir` unpacked staging), then the *same*
 * dir under `process.resourcesPath` — required for real packaged installers,
 * since `electron/native/bin/**` ships exclusively via `extraResources` (see
 * `electron-builder.json5`'s `files` list, which only packs
 * `dist`/`dist-electron`) and is never inside `app.getAppPath()` there.
 * Mirrors the appPath/resourcePath pattern `stt/gpuDetector.ts` already uses
 * for the other native binaries in this same directory.
 */
export function ffmpegSharedBinCandidates(appRoot: string): string[] {
	const tag = platformArchTag();
	const resourcesPath =
		typeof process.resourcesPath === "string" && process.resourcesPath.length > 0
			? process.resourcesPath
			: null;
	const devDir = pinnedFfmpegDir(appRoot);
	return [
		...(devDir ? [path.join(devDir, "bin")] : []),
		path.join(appRoot, "electron", "native", "bin", tag),
		...(resourcesPath ? [path.join(resourcesPath, "electron", "native", "bin", tag)] : []),
	];
}

/** Prepends the first existing ffmpeg shared-DLL dir to `PATH` (no-op if already present or none found). */
function ensureFfmpegSharedDllsOnPath(appRoot: string): void {
	if (process.platform !== "win32") {
		return;
	}
	const dir = ffmpegSharedBinCandidates(appRoot).find((candidate) => fs.existsSync(candidate));
	if (!dir) {
		return;
	}
	const current = process.env.PATH ?? "";
	if (current.split(path.delimiter).includes(dir)) {
		return;
	}
	process.env.PATH = `${dir}${path.delimiter}${current}`;
}

/** The ONNX Runtime shared library's file name for this platform. */
function ortLibName(): string {
	if (process.platform === "win32") return "onnxruntime.dll";
	if (process.platform === "darwin") return "libonnxruntime.dylib";
	return "libonnxruntime.so";
}

/**
 * Points `ORT_DYLIB_PATH` at the staged ONNX Runtime, which the addon loads dynamically for
 * the webcam segmentation mask.
 *
 * It lives in the same arch-tagged `electron/native/bin/<tag>/` directory the addon itself
 * ships from, next to the ffmpeg DLLs — the convention `whisper-stt` already established for
 * native sidecars. The crate links `ort` with `load-dynamic`, so the library is resolved at
 * runtime rather than at build time: absent, `Segmenter::load` fails, the compositor logs one
 * line and draws the webcam unsegmented. That is why this is best-effort and never throws.
 */
function ensureOnnxRuntimeOnPath(appRoot: string): void {
	if (process.env.ORT_DYLIB_PATH) {
		return;
	}
	const lib = ortLibName();
	for (const dir of ffmpegSharedBinCandidates(appRoot)) {
		const candidate = path.join(dir, lib);
		if (fs.existsSync(candidate)) {
			process.env.ORT_DYLIB_PATH = candidate;
			return;
		}
	}
}

/**
 * Points `OPENSCREEN_FONTS_DIR` at the font files the compositor draws captions and annotations
 * with (`public/fonts`, shipped through `extraResources` like the wallpapers). The compositor
 * registers them privately when it builds its text rasterizer and never reads the machine's
 * installed fonts, so without this every family falls back to a system face. Best-effort like
 * `ensureOnnxRuntimeOnPath`: unresolved, text still draws, in system fonts.
 */
function ensureTextFontsDir(): void {
	if (process.env.OPENSCREEN_FONTS_DIR) {
		return;
	}
	const dir = resolveSceneAssetPath("fonts");
	if (dir) {
		process.env.OPENSCREEN_FONTS_DIR = dir;
	}
}

function tryLoadAddon(candidates: string[]): CompositorViewAddon | null {
	for (const candidate of candidates) {
		try {
			// only attempt the require when the file actually exists
			// — `require()` of a missing native module throws a noisy
			// MODULE_NOT_FOUND that pollutes the renderer console.
			if (!fs.existsSync(candidate)) {
				continue;
			}
			const loaded = localRequire(candidate) as unknown;
			if (loaded && typeof loaded === "object") {
				return loaded as CompositorViewAddon;
			}
		} catch (err) {
			// log and try the next candidate — a single broken build
			// shouldn't kill the addon entirely, but silently swallowing this
			// is exactly what made a missing-ffmpeg-DLL failure look like a
			// generic "addon not present" no-op.
			console.warn(`[compositor-view] failed to load addon candidate ${candidate}:`, err);
		}
	}
	return null;
}

export class CompositorViewService {
	private readonly options: CompositorViewServiceOptions;
	private readonly rects = new Map<number, CompositorViewRect>();
	/** Views whose frames go out as shared GPU textures rather than RAM pixels. */
	private readonly sharedViews = new Set<number>();
	private addon: CompositorViewAddon | null = null;
	private loadAttempted = false;
	private syntheticIdCounter = 0;

	constructor(options: CompositorViewServiceOptions = {}) {
		this.options = options;
	}

	private ensureAddon(): CompositorViewAddon | null {
		if (this.options.addon) return this.options.addon;
		if (this.loadAttempted) {
			return this.addon;
		}
		this.loadAttempted = true;

		const envOverride =
			this.options.envOverride ?? process.env.OPENSCREEN_COMPOSITOR_VIEW_NODE ?? null;
		const appRoot = this.options.appRoot ?? defaultAppRoot();
		const isPackaged = this.options.isPackaged ?? defaultIsPackaged();

		ensureFfmpegSharedDllsOnPath(appRoot);
		ensureOnnxRuntimeOnPath(appRoot);
		ensureTextFontsDir();
		const candidates = buildCandidatePaths(appRoot, isPackaged, envOverride);
		const loaded = tryLoadAddon(candidates);
		if (!loaded) {
			// single log line, exactly as specified — repeated
			// ensureAddon calls just return null without spamming the console.
			console.log("[compositor-view] native addon not present; running as no-op");
			return null;
		}
		this.addon = loaded;
		return this.addon;
	}

	/** True when the native `.node` addon was successfully loaded. */
	hasAddon(): boolean {
		return this.ensureAddon() !== null;
	}

	/** Which backend the compositor will use on this machine.
	 *
	 *  `"none"` when the addon is absent — no native path at all, so there is nothing to
	 *  warn about; that is the pure-web/dev case, not a degraded GPU. Callers must not
	 *  read `"none"` as "slow", only `"cpu"` means that. */
	probeBackend(): CompositorBackend {
		const addon = this.ensureAddon();
		if (!addon) {
			return "none";
		}
		try {
			return addon.probeBackend();
		} catch (err) {
			// An older `.node` predates probeBackend. Treat as unknown rather than
			// crashing the bridge: a stale addon should not take the editor down.
			console.warn("[compositor-view] probeBackend unavailable:", err);
			return "none";
		}
	}

	/** Whether this machine can actually segment the camera, and if not, what is missing.
	 *
	 *  Three things have to line up, and each of them has been silently absent at some point:
	 *  the addon, the ONNX Runtime library, and the model. The renderer used to guess from
	 *  `process.platform`, which was wrong in both directions — it hid the control on Linux
	 *  builds that could segment, and shows it on Intel Macs, for which upstream publishes no
	 *  ONNX binary at all. A dev checkout and a `--dir` build have none staged either.
	 *
	 *  Same shape as `probeBackend`: asked without allocating a view, because the panel needs
	 *  the answer before any preview exists. */
	probeSegmentation(): SegmentationSupport {
		const addon = this.ensureAddon();
		if (!addon) {
			return "none";
		}
		try {
			if (!addon.segmentationRuntimeAvailable()) {
				return "no-runtime";
			}
		} catch (err) {
			// An older `.node` predates this probe. Treat as unsupported rather than crashing
			// the bridge — same contract as `probeBackend`.
			console.warn("[compositor-view] segmentationRuntimeAvailable unavailable:", err);
			return "none";
		}
		// The model is resolved by this process, not the addon, so it is checked here — and it
		// is the same lookup `resolveSceneAssetPaths` performs, so the two cannot disagree.
		return resolveSceneAssetPath(SEGMENTATION_MODEL_ASSET) ? "ready" : "no-model";
	}

	/** Checks an agent-written effect's WGSL in the compositor (`docs/shader-effects.md`, E.3): the
	 *  compile error, or the cost tier. `null` when this addon cannot answer, which the agent tools
	 *  report as "not checked" rather than as a compile failure. */
	async checkShaderEffect(
		code: string,
		params: ReadonlyArray<{ name: string; type: string }>,
	): Promise<ShaderEffectCheck | null> {
		const addon = this.ensureAddon();
		if (!addon || typeof addon.checkShaderEffect !== "function") return null;
		try {
			// `await`, not a bare return: the check is a promise now, and a rejection must land in
			// this catch rather than escape it.
			return await addon.checkShaderEffect(
				code,
				JSON.stringify(params.map(({ name, type }) => ({ name, type }))),
			);
		} catch (err) {
			// A native throw is the addon failing, not the effect: "not checked", as documented.
			console.warn("[compositor-view] checkShaderEffect failed:", err);
			return null;
		}
	}

	/** Subject mask for one camera frame, no view needed — see `segmentFrame` in the addon.
	 *  `null` when the addon (or this version of it) or the model is missing. */
	async segmentFrame(rgba: Uint8Array): Promise<Uint8Array | null> {
		const addon = this.ensureAddon();
		const modelPath = resolveSceneAssetPath(SEGMENTATION_MODEL_ASSET);
		if (!addon?.segmentFrame || !modelPath) {
			return null;
		}
		return addon.segmentFrame(
			modelPath,
			Buffer.from(rgba.buffer, rgba.byteOffset, rgba.byteLength),
		);
	}

	/** Allocates an offscreen compositor view sized to `rect.width`x`rect.height`.
	 *  `rect.x` / `rect.y` are vestigial (ignored native-side) — the renderer
	 *  keeps them on the wire so the existing `CompositorViewRect` shape stays
	 *  source-compatible. No HWND/native-window-handle is passed: there's no
	 *  OS window to parent to. */
	createView(
		rect: CompositorViewRect,
		paths?: { screenPath?: string; webcamPath?: string; cursorPath?: string },
	): number {
		const addon = this.ensureAddon();
		if (!addon) {
			// synthetic negative ids let callers do bookkeeping
			// (cleanup in destroyView) without crashing when no native view
			// exists. Each call gets a fresh id so multiple no-op views
			// stay independent.
			this.syntheticIdCounter -= 1;
			const id = this.syntheticIdCounter;
			this.rects.set(id, rect);
			return id;
		}
		const id = addon.createView(rect, paths?.screenPath, paths?.webcamPath, paths?.cursorPath);
		this.rects.set(id, rect);
		this.shareFrames(addon, id);
		return id;
	}

	/** Hands the view's frames over as shared GPU textures when this host can, instead of
	 *  copying them through IPC: measured, that transport alone kept 37 to 55 % of the
	 *  renderer's main thread busy at 30 fps (rendering-performance.md). Anything missing —
	 *  the Electron API, GPU compositing, Windows' hardware backend native-side — leaves the
	 *  view on read-back. `OPENSCREEN_PREVIEW_READBACK=1` forces read-back, to compare. */
	private shareFrames(addon: CompositorViewAddon, id: number): void {
		if (process.env.OPENSCREEN_PREVIEW_READBACK === "1" || !this.sharedTextureApi()) {
			return;
		}
		if (!(this.options.gpuCompositing ?? defaultGpuCompositing)()) {
			return;
		}
		if (addon.setSharedFrames?.(id, true)) {
			this.sharedViews.add(id);
		}
	}

	private sharedTextureApi(): SharedTextureApi | null {
		const api =
			this.options.sharedTexture === undefined ? sharedTexture : this.options.sharedTexture;
		return typeof api?.importSharedTexture === "function" ? api : null;
	}

	/** Takes the view back to read-back frames: a delivery failed, or the renderer saw a shared
	 *  frame land as nothing (Chromium could not open the texture). The render thread
	 *  republishes the current frame, so the canvas is not left empty. */
	stopSharedFrames(id: number): void {
		this.sharedViews.delete(id);
		this.ensureAddon()?.setSharedFrames?.(id, false);
	}

	setRect(id: number, rect: CompositorViewRect): void {
		const addon = this.ensureAddon();
		this.rects.set(id, rect);
		if (!addon) {
			return;
		}
		addon.setRect(id, rect);
	}

	/** Reads the most recently rendered frame for `id`, but only if its generation is newer
	 *  than `sinceGen`. Returns `null` when the addon is absent, no frame is ready yet, OR the
	 *  caller already holds the current generation — the idle path, where nothing is copied.
	 *
	 *  A view on shared textures sends the frame to `target` as a GPU texture, and answers with
	 *  its receipt (`shared: true`, no pixels): the texture reaches the renderer before this
	 *  reply does. Any other view answers with the RGBA pixels themselves. */
	async readFrame(
		id: number,
		sinceGen: number,
		target?: WebFrameMain | null,
	): Promise<NativeFramePacket | CompositorSharedFrameReceipt | null> {
		const addon = this.ensureAddon();
		if (!addon) {
			return null;
		}
		if (target && this.sharedViews.has(id)) {
			const frame = addon.readSharedFrame?.(id, sinceGen);
			if (frame) {
				return this.sendSharedFrame(addon, id, frame, target);
			}
		}
		// Also the answer for a view whose render thread went back to read-back on its own.
		return addon.readFrame(id, sinceGen);
	}

	private async sendSharedFrame(
		addon: CompositorViewAddon,
		id: number,
		frame: NativeSharedFramePacket,
		target: WebFrameMain,
	): Promise<CompositorSharedFrameReceipt | null> {
		const meta: CompositorSharedFrameMeta = {
			viewId: id,
			gen: frame.gen,
			width: frame.width,
			height: frame.height,
			footage: frame.footage ?? null,
			footageProjective: frame.footageProjective ?? false,
			clipIndex: frame.clipIndex,
			sourceTimeSec: frame.sourceTimeSec,
		};
		const api = this.sharedTextureApi();
		const holdMs = sharedSlotHoldMs((this.options.displayHz ?? defaultDisplayHz)(target));
		let imported: Electron.SharedTextureImported | undefined;
		try {
			if (!api) {
				throw new Error("the sharedTexture API is gone");
			}
			imported = api.importSharedTexture({
				textureInfo: {
					pixelFormat: "rgba",
					codedSize: { width: frame.width, height: frame.height },
					handle: { ntHandle: frame.handle },
				},
				// Chromium is done with the texture in every process: after a grace period, the slot
				// may be written again (SHARED_SLOT_RELEASE_DELAY_MS says why it waits).
				allReferencesReleased: () => {
					setTimeout(() => addon.releaseSharedFrame?.(id, frame.slot, frame.gen), holdMs);
				},
			});
			await api.sendSharedTexture({ frame: target, importedSharedTexture: imported }, meta);
			return { ...meta, shared: true };
		} catch (error) {
			console.warn("[compositor-view] shared frame not delivered; reading frames back:", error);
			this.stopSharedFrames(id);
			if (!imported) {
				addon.releaseSharedFrame?.(id, frame.slot, frame.gen);
			}
			return null;
		} finally {
			// This process's reference only: the renderer holds its own until it has drawn.
			imported?.release();
		}
	}

	setParam(id: number, key: string, value: CompositorParamValue): void {
		const addon = this.ensureAddon();
		if (!addon) {
			return;
		}
		addon.setParam(id, key, value);
	}

	setPlaying(id: number, playing: boolean): void {
		const addon = this.ensureAddon();
		if (!addon) {
			return;
		}
		addon.setPlaying(id, playing);
	}

	presentTime(id: number, seconds: number): void {
		const addon = this.ensureAddon();
		if (!addon) {
			return;
		}
		addon.presentTime(id, seconds);
	}

	setScene(id: number, sceneJson: string): void {
		const addon = this.ensureAddon();
		if (!addon) {
			return;
		}
		addon.setScene(id, resolveSceneAssetPaths(sceneJson));
	}

	setActiveClip(
		id: number,
		screenPath: string,
		webcamPath: string,
		webcamOffsetSec: number,
		clipIndex: number,
		sourceTimeSec: number,
	): void {
		const addon = this.ensureAddon();
		if (!addon) {
			return;
		}
		addon.setActiveClip(id, screenPath, webcamPath, webcamOffsetSec, clipIndex, sourceTimeSec);
	}

	destroyView(id: number): void {
		const addon = this.ensureAddon();
		this.rects.delete(id);
		this.sharedViews.delete(id);
		if (!addon) {
			return;
		}
		addon.destroyView(id);
	}

	/** Native multiclip export (real timeline -> MP4). Auto-pauses previews via the addon.
	 *  `sceneJson` — same scene as the live preview (background/layout/webcam/cursor/effects);
	 *  goes through the same asset-path resolution as `setScene` (wallpaper image, cursor theme
	 *  sprite) since the native process can't resolve renderer-relative URLs either.
	 *  `onProgress` — see `export()` above.
	 *  Returns null when the addon is absent. */
	async exportMulti(
		clips: ClipInput[],
		outPath?: string,
		sceneJson?: string,
		params?: ExportParamsInput,
		onProgress?: (frames: number) => void,
		control?: object,
	): Promise<ExportStats | null> {
		const addon = this.ensureAddon();
		if (!addon) {
			return null;
		}
		const target = outPath ?? path.join(app.getPath("temp"), "openscreen-native-export.mp4");
		return addon.exportMulti(
			clips,
			target,
			sceneJson ? resolveSceneAssetPaths(sceneJson) : undefined,
			params,
			onProgress,
			control,
		);
	}

	/** Frames of a timeline as an export composes them, without the export: see `renderFrames`
	 *  in the addon. `null` when this addon cannot render them. */
	async renderFrames(
		clips: ClipInput[],
		sceneJson: string,
		fps: number,
		frames: number[],
		maxWidth: number,
	): Promise<Array<{ index: number; width: number; height: number; jpeg: Buffer }> | null> {
		const addon = this.ensureAddon();
		if (!addon || typeof addon.renderFrames !== "function") return null;
		return addon.renderFrames(clips, resolveSceneAssetPaths(sceneJson), fps, frames, maxWidth);
	}

	/** `startGifExport` for MP4, except that an addon built before MP4 cancellation still
	 *  exports: the main export must not fail over a missing Cancel. That job runs to the end
	 *  and refuses to cancel. */
	startExportMulti(
		clips: ClipInput[],
		outPath?: string,
		sceneJson?: string,
		params?: ExportParamsInput,
		onProgress?: (frames: number) => void,
	): ExportJob<ExportStats | null> {
		const addon = this.ensureAddon();
		if (!addon?.createMp4ExportControl || !addon.cancelMp4Export) {
			return {
				result: this.exportMulti(clips, outPath, sceneJson, params, onProgress),
				cancel: () => false,
			};
		}
		const control = addon.createMp4ExportControl();
		const cancel = addon.cancelMp4Export.bind(addon);
		return {
			result: this.exportMulti(clips, outPath, sceneJson, params, onProgress, control),
			cancel: () => cancel(control),
		};
	}

	/** Native GIF export. Same inputs as `exportMulti` — one clip list, one scene —
	 *  because it is the same render: both drive `walk_composited_timeline` in the
	 *  compositor crate and differ only in the encoder. The scene carries background,
	 *  layout, webcam and cursor, so there is no GIF-specific input.
	 *
	 *  Returns null when the addon is absent, which the renderer surfaces as a failed
	 *  export — there is no longer a renderer-side GIF path to fall back to. */
	async exportGif(
		clips: ClipInput[],
		outPath?: string,
		sceneJson?: string,
		params?: GifParamsInput,
		onProgress?: (frames: number) => void,
		control?: object,
	): Promise<GifExportStats | null> {
		const addon = this.ensureAddon();
		if (!addon) {
			return null;
		}
		const target = outPath ?? path.join(app.getPath("temp"), "openscreen-native-export.gif");
		return addon.exportGif(
			clips,
			target,
			sceneJson ? resolveSceneAssetPaths(sceneJson) : undefined,
			params,
			onProgress,
			control,
		);
	}

	startGifExport(
		clips: ClipInput[],
		outPath?: string,
		sceneJson?: string,
		params?: GifParamsInput,
		onProgress?: (frames: number) => void,
	): ExportJob<GifExportStats | null> {
		const addon = this.ensureAddon();
		if (!addon?.createGifExportControl || !addon.cancelGifExport) {
			throw new Error(
				"Native GIF cancellation is unavailable. Rebuild or update the compositor addon.",
			);
		}
		const control = addon.createGifExportControl();
		const cancel = addon.cancelGifExport.bind(addon);
		return {
			result: this.exportGif(clips, outPath, sceneJson, params, onProgress, control),
			cancel: () => cancel(control),
		};
	}

	/** Stream-copy `inputPath` to `outputPath` through libavformat's matroska muxer.
	 *  No re-encode: the packets are copied verbatim and only the container is rebuilt,
	 *  which is what gives the output a real `Duration`, `Cues` and `SeekHead`.
	 *
	 *  `outputPath` must be a TEMPORARY path — the caller renames it over the original
	 *  only once this resolves, so a failure leaves the recording untouched. See
	 *  `electron/recording/webm-seek-index.ts`, the only caller.
	 *
	 *  Returns null when the addon is absent, or when it predates this export (a stale
	 *  `.node` from an earlier build): the caller then keeps the file as it is rather
	 *  than treating a missing optimisation as a failed save. */
	async remuxSeekable(inputPath: string, outputPath: string): Promise<RemuxStats | null> {
		const addon = this.ensureAddon();
		if (!addon?.remuxSeekable) {
			return null;
		}
		return addon.remuxSeekable(inputPath, outputPath);
	}

	/** The loudness-normalisation gain (dB) the export applies to this voice file, so the
	 *  preview can play it at the same level. Null when the addon is absent or predates it:
	 *  the preview then plays the file as recorded, the export still normalises. */
	async loudnessGainDb(filePath: string): Promise<number | null> {
		const addon = this.ensureAddon();
		if (!addon?.loudnessGainDb) {
			return null;
		}
		return addon.loudnessGainDb(filePath);
	}
}