Skip to content

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

58.1 KB
Raw Blame
// electron-builder beforePack hook: refuse to package a compositor addon that is older than its
// Rust sources.
//
// `compositor_view.node` is an untracked build artifact, and plain `npm run build` does NOT rebuild
// it (only `build:win` runs `build:native:compositor`). So a bare `npm run build` — or a fresh
// worktree that inherited a copy from the main checkout — happily ships a `.node` built from
// whatever the sources looked like days ago.
//
// That failure is silent, which is what makes it worth a hard error. Scene fields the app sends are
// `#[serde(default)]` on the Rust side, so an addon predating a contract change does not reject the
// payload: it ignores the unknown key, takes the default, and falls back to older art. The feature
// simply does nothing, with no error in any log — it reads exactly like a bug in the TypeScript, and
// it has already cost one full false-trail investigation (custom cursor themes, 2026-07-27, where
// the shipped addon was 3 days older than the commit adding `cursorSprites`).
//
// ponytail: mtime comparison, not content hashing. A `git checkout` restamps source mtimes, so this
// can fire when the addon is actually fine. That trade is deliberate — the false positive costs one
// rebuild, the false negative ships a broken installer. Switch to hashing the sources into a stamp
// file next to the `.node` if branch-switching makes the noise annoying.

const fs = require("node:fs");
const path = require("node:path");

const ROOT = path.join(__dirname, "..");
const ADDON = path.join(ROOT, "electron/native/compositor-view/build/compositor_view.node");

// Everything the addon is compiled from. shaders.hlsl lives under src/, so it is covered.
// crates/poc-d3d/ is deliberately absent: nothing links it, so editing the POC cannot
// invalidate the shipped addon.
const SOURCE_PATHS = [
	"crates/compositor/src",
	"crates/compositor-view-napi/src",
	"crates/Cargo.toml",
	"crates/compositor/Cargo.toml",
	"crates/compositor-view-napi/Cargo.toml",
].map((p) => path.join(ROOT, p));

const FIX =
	"Rebuild it with:\n\n    npm run build:native:compositor\n\nor use `npm run build:win`, which does that for you.";

const FIX_MAC =
	"Rebuild it with:\n\n    npm run build:native:compositor:mac\n\nor use `npm run build:mac`, which does that for you.";

const FIX_LINUX =
	"Rebuild it with:\n\n    npm run build:native:compositor:linux\n\nor use `npm run build:linux`, which does that for you.";

const FIX_LINUX_HELPER =
	"Rebuild it with:\n\n    npm run build:native:linux\n\nor use `npm run build:linux`, which does that for you.";

/** Everything the PipeWire capture helper is compiled from. */
const HELPER_SOURCE_PATHS = [
	"electron/native/pipewire-capture/src",
	"electron/native/pipewire-capture/csrc",
	"electron/native/pipewire-capture/build.rs",
	"electron/native/pipewire-capture/Cargo.toml",
].map((p) => path.join(ROOT, p));

/**
 * Everything that has to be inside `electron/native/bin/darwin-<arch>/` for the .app to
 * work, keyed by what breaks when it is absent.
 *
 * This list exists because the macOS deliverable had no guard at all: `beforePack`
 * returned early on any non-win32 platform, so a mac package built without the compositor
 * addon shipped silently — the preview and the export come up dead, with nothing in any
 * log to say why. That is precisely the failure mode the staleness check below was written
 * to prevent, and the platform guard was letting it through on the other OS.
 *
 * `mac.extraResources` ships this directory wholesale (`filter: ["darwin-*​/*"]`), so
 * "present here" is the same thing as "present in the installed app".
 */
/**
 * L'exigence ONNX Runtime de macOS, séparée parce qu'elle ne vaut QUE sur arm64.
 *
 * L'amont ne publie aucun binaire ONNX pour les Macs Intel : `fetch-onnxruntime.mjs` le constate
 * et sort en 0 sans rien poser. Un paquet x64 sans la bibliothèque est donc CORRECT, et l'exiger
 * là ferait échouer à l'empaquetage une build parfaitement saine — la garde se retournerait
 * contre ce qu'elle protège.
 *
 * Sur arm64 en revanche son absence ne casse rien de visible : `Segmenter::load` refuse, le
 * compositeur dessine la webcam telle quelle, et le contrôle disparaît de l'éditeur. Le paquet
 * est silencieusement amputé, ce qui est exactement la panne que cette garde existe pour
 * attraper et qu'aucun test ne peut voir puisque tout se dégrade proprement.
 */
const MAC_ONNX_REQUIRED = {
	match: (name) => name === "libonnxruntime.dylib",
	what: "the ONNX Runtime library the camera-background segmentation loads",
	breaks: "the camera-background control vanishes from the editor and every effect is a no-op",
	fix: "Stage it with:\n\n    npm run fetch:onnxruntime",
};

const MAC_REQUIRED = [
	{
		match: (name) => name === "compositor_view.node",
		what: "the Metal compositor addon",
		breaks: "the preview and every export render nothing",
		fix: FIX_MAC,
	},
	// One requirement per library, not `atLeast: N` over a combined regex — the
	// same trap LINUX_REQUIRED documents above. Several versioned copies of one
	// library would satisfy a combined count while another was missing entirely,
	// and the addon would still fail to load.
	...["avcodec", "avformat", "avutil", "swresample", "swscale", "avfilter"].map((library) => ({
		match: (name) => new RegExp(`^lib${library}\\.\\d+\\.dylib$`).test(name),
		what: `the LGPL lib${library} dylib the compositor links`,
		breaks: "the compositor addon cannot be loaded at all (dyld error at require())",
		fix: FIX_MAC,
	})),
	{
		match: (name) => /^libavdevice\.\d+\.dylib$/.test(name),
		what: "the LGPL libavdevice dylib the ffmpeg CLI links",
		breaks: "ffmpeg dies in dyld before main(), so waveform and STT extraction cannot start",
		fix: FIX_MAC,
	},
	{
		match: (name) => name === "whisper-stt-server",
		what: "the whisper.cpp STT helper",
		breaks: "transcription and captions fail with a developer error shown to end users",
		fix: "Build it with:\n\n    npm run build:whisper-binaries\n\nor stage CI's with `bash scripts/stage-whisper-stt.sh darwin-<arch>`.",
	},
	{
		match: (name) => /^libggml.*\.dylib$/.test(name),
		what: "the ggml backend dylibs the STT helper links",
		breaks: "whisper-stt-server dies in dyld before main(), so STT times out with no diagnostic",
		fix: "Build it with:\n\n    npm run build:whisper-binaries",
		atLeast: 1,
	},
	{
		match: (name) => name === "openscreen-screencapturekit-helper",
		what: "the ScreenCaptureKit capture helper",
		breaks: "native screen capture is unavailable",
		fix: "Build it with:\n\n    npm run build:native:mac",
	},
	{
		match: (name) => name === "ffmpeg",
		what: "the LGPL ffmpeg CLI (spawned for waveform peaks and STT audio extraction)",
		breaks:
			'transcription fails in the editor, over MCP and in the CLI with "ffmpeg is missing" (#616)',
		fix: "Build it with:\n\n    npm run build:native:compositor:mac\n\nwhich stages the SDK's ffmpeg beside the vendored dylibs.",
	},
];

/**
 * The Linux counterpart of MAC_REQUIRED. It exists for the same reason: until this
 * hook grew a Linux branch, `beforePack` asserted nothing at all on Linux — the
 * comment said "Linux ships no native addon of its own", which stopped being true
 * when the wgpu compositor addon and the PipeWire capture helper landed.
 *
 * `linux.extraResources` ships this directory wholesale (`filter: ["linux-*​/**"]`),
 * so "present here" is the same thing as "present in the installed app".
 *
 * Note the two ffmpeg sets, which is why `helper-ffmpeg/` is required separately below:
 * the `.so` files sitting directly in this directory are the compositor's copies,
 * with every symbol renamed to `osff_*` so the addon cannot bind to Chromium's
 * bundled ffmpeg. The helper needs the *unrenamed* originals, which is what the
 * `helper-ffmpeg/` subdirectory holds.
 */
const LINUX_REQUIRED = [
	// L'effet de fond de caméra est le seul dont la présence dépend d'un binaire optionnel, et
	// son absence ne casse RIEN de visible : `Segmenter::load` refuse, le compositeur dessine la
	// webcam telle quelle, et le contrôle disparaît de l'éditeur. Un paquet livré sans elle est
	// donc silencieusement amputé — la panne exacte que cette garde existe pour attraper, et
	// celle qu'aucun test ne peut voir puisque tout se dégrade proprement.
	{
		match: (name) => name === "libonnxruntime.so",
		what: "the ONNX Runtime library the camera-background segmentation loads",
		breaks: "the camera-background control vanishes from the editor and every effect is a no-op",
		fix: "Stage it with:\n\n    npm run fetch:onnxruntime",
	},
	{
		match: (name) => name === "compositor_view.node",
		what: "the wgpu/Vulkan compositor addon",
		breaks: "the preview renders nothing and every export falls back to the no-op compositor",
		fix: FIX_LINUX,
	},
	// Une exigence par famille, plutôt qu'`atLeast: 5` sur une regex combinée. Le
	// compte total était satisfait par cinq copies versionnées d'une même
	// bibliothèque — libavcodec.so.58 à .62 laissées par un build précédent —
	// pendant qu'une autre manquait. Le paquet passait alors la garde et le
	// compositeur ne chargeait pas : exactement le mode de panne que cette garde
	// existe pour attraper.
	...["avcodec", "avformat", "avutil", "swresample", "swscale", "avfilter"].map((library) => ({
		match: (name) => new RegExp(`^lib${library}\\.so\\.\\d+$`).test(name),
		what: `the symbol-renamed lib${library} shared object the compositor links`,
		breaks: "the compositor addon cannot be loaded at all (ld.so error at require())",
		fix: FIX_LINUX,
	})),
	{
		match: (name) => name === "openscreen-pipewire-helper",
		what: "the PipeWire screen-capture helper",
		breaks: "Wayland capture is unavailable and cursor recording throws",
		fix: FIX_LINUX_HELPER,
	},
	{
		match: (name) => name === "ffmpeg",
		what: "the LGPL ffmpeg CLI (spawned for waveform peaks and STT audio extraction)",
		breaks: 'transcription fails in the editor, over MCP and in the CLI with "ffmpeg is missing"',
		fix: `${FIX_LINUX_HELPER}\n\nwhich stages the SDK's shared ffmpeg beside helper-ffmpeg/.`,
	},
	{
		match: (name) => name === "whisper-stt-server",
		what: "the whisper.cpp STT helper",
		breaks: "transcription and captions fail with a developer error shown to end users",
		fix: "Build it with:\n\n    npm run build:whisper-binaries\n\nor stage CI's with `bash scripts/stage-whisper-stt.sh linux-x64`.",
	},
	{
		match: (name) => /^libggml.*\.so(\.\d+)*$/.test(name),
		what: "the ggml backend shared objects the STT helper links",
		breaks: "whisper-stt-server dies in ld.so before main(), so STT times out with no diagnostic",
		fix: "Build it with:\n\n    npm run build:whisper-binaries",
		atLeast: 1,
	},
];

/** electron-builder passes `context.arch` as a numeric enum; map it to our directory tag. */
function archTagFor(context) {
	const BY_INDEX = { 0: "ia32", 1: "x64", 2: "armv7l", 3: "arm64", 4: "universal" };
	const name = BY_INDEX[context?.arch];
	return name && name !== "universal" ? name : process.arch;
}

/**
 * Shared by the macOS and Linux payload checks — same contract on both: the arch-tagged
 * directory under electron/native/bin/ is what extraResources ships, so a missing entry
 * here is a missing entry in the installed app.
 */
function checkNativePayload({ dir, required, osLabel, bundleNoun, emptyDirFix }) {
	if (!fs.existsSync(dir)) {
		throw new Error(
			`Refusing to package: ${path.relative(ROOT, dir)} does not exist, so ${bundleNoun} would ` +
				"ship with no native modules at all.\n\n" +
				emptyDirFix,
		);
	}

	const present = fs.readdirSync(dir);
	const missing = required.filter(
		(req) => present.filter((name) => req.match(name)).length < (req.atLeast ?? 1),
	);
	if (missing.length === 0) {
		return;
	}

	const detail = missing
		.map(
			(req) =>
				`  - ${req.what}\n      without it: ${req.breaks}\n      ${req.fix.replace(/\n+/g, " ")}`,
		)
		.join("\n");
	throw new Error(
		`Refusing to package an incomplete ${osLabel} payload.\n\n` +
			`  looked in: ${path.relative(ROOT, dir)}\n\n` +
			`Missing:\n${detail}\n\n` +
			"Every one of these fails silently or as an unactionable timeout in the installed\n" +
			"app, which is why this is a hard error at pack time rather than a warning.",
	);
}

/**
 * The Windows addon must sit in the SAME directory as the ffmpeg DLLs it links
 * against, because that is the only arrangement that loads under MSIX.
 *
 * The addon dlopens avcodec/avformat/avutil at require() time. While it shipped from
 * app.asar.unpacked — one directory away from the DLLs — loading it depended on
 * `ensureFfmpegSharedDllsOnPath` prepending their directory to PATH. That works for
 * the NSIS installer and does not work under MSIX, which resolves dependent DLLs
 * through the package graph and ignores PATH. Measured inside a registered package,
 * with the directory correctly on PATH: `require` failed both before and after the
 * PATH was set; with the addon beside its DLLs it loaded with no PATH at all.
 *
 * That shipped as 1.9.0 on the Store: no compositor loaded, so the editor showed no
 * preview at all while audio kept playing — and it looked like an app bug, not a
 * packaging one, because every file was present and the NSIS build of the same commit
 * was fine.
 *
 * `win.extraResources` ships this directory wholesale (filter `win32-*​/*`), so
 * "together here" is the same thing as "together in the installed app".
 */
const WIN_REQUIRED = [
	// L'effet de fond de caméra est le seul dont la présence dépend d'un binaire optionnel, et
	// son absence ne casse RIEN de visible : `Segmenter::load` refuse, le compositeur dessine la
	// webcam telle quelle, et le contrôle disparaît de l'éditeur. Un paquet livré sans elle est
	// donc silencieusement amputé — la panne exacte que cette garde existe pour attraper, et
	// celle qu'aucun test ne peut voir puisque tout se dégrade proprement.
	{
		match: (name) => name === "onnxruntime.dll",
		what: "the ONNX Runtime library the camera-background segmentation loads",
		breaks: "the camera-background control vanishes from the editor and every effect is a no-op",
		fix: "Stage it with:\n\n    npm run fetch:onnxruntime",
	},
	{
		match: (name) => name === "compositor_view.node",
		what: "the D3D11 compositor addon",
		breaks: "the preview renders nothing and every export falls back to the no-op compositor",
		fix: FIX,
	},
	// One requirement per library, not `atLeast: 3` over a combined regex — the same
	// trap LINUX_REQUIRED documents above. Several versioned copies of one library
	// (avcodec-60/61/62.dll left by an earlier fetch) would satisfy a combined count
	// while another library was missing entirely, and the addon would still fail to
	// load.
	...["avcodec", "avformat", "avutil", "swresample", "swscale", "avfilter"].map((library) => ({
		match: (name) => new RegExp(`^${library}-\\d+\\.dll$`).test(name),
		what: `the ${library} DLL the compositor links`,
		breaks: "the addon cannot be loaded at all under MSIX, which ignores PATH",
		fix: "Fetch them with:\n\n    npm run fetch:ffmpeg",
	})),
];

/**
 * DLLs that come from the Visual C++ Redistributable rather than from Windows itself.
 *
 * The `api-ms-win-crt-*` api-sets are deliberately absent: that is the UCRT, which IS
 * part of Windows 10 and later. These are not, and no machine is obliged to have them.
 *
 * `vcomp` and `vcamp` were missing from the first version of this list, and the gap was
 * not academic: ggml-base.dll and ggml-cpu.dll are built with OpenMP and import
 * vcomp140.dll, so the shipped whisper payload still needed the redistributable after
 * 1.9.1 was supposed to have ended that. The guard reported the payload clean because
 * `vcomp` starts with none of msvcp/vcruntime/concrt. Enumerate the family, not the
 * members that happened to bite.
 */
const VC_REDIST_DLL = /^(msvcp|vcruntime|concrt|vcomp|vcamp|mfc)\d+/i;

/**
 * The DLL names a PE binary imports — just enough of the format to walk the import
 * directory, so this needs no dumpbin and therefore no Visual Studio on the runner.
 */
function importedDlls(file) {
	const b = fs.readFileSync(file);
	// Every read below is bounds-checked through this, so a truncated or non-PE file
	// arrives at the message this function means to give rather than at a RangeError
	// from readUInt32LE. The diagnostic is the whole product here: the caller's job is
	// to explain an absence, and "offset is out of bounds" explains nothing.
	const notPe = () => new Error(`${file} is not a PE binary, or is truncated`);
	const u32 = (at) => {
		if (at < 0 || at + 4 > b.length) throw notPe();
		return b.readUInt32LE(at);
	};
	const u16 = (at) => {
		if (at < 0 || at + 2 > b.length) throw notPe();
		return b.readUInt16LE(at);
	};

	if (u16(0) !== 0x5a4d) throw notPe(); // "MZ"
	const pe = u32(0x3c);
	if (u32(pe) !== 0x00004550) throw notPe(); // "PE\0\0"
	const opt = pe + 24;
	// The optional header's fixed part is 96 bytes for PE32 and 112 for PE32+ (five
	// fields widen to 8 bytes); the data directories follow it.
	const dirs = opt + (u16(opt) === 0x20b ? 112 : 96);
	// NumberOfRvaAndSizes is the last field before the directories, so it sits four
	// bytes back whichever the format. Without it, a binary declaring fewer entries
	// than we index would have unrelated header bytes read as an RVA.
	const dirCount = u32(dirs - 4);

	const sections = [];
	for (let i = 0; i < u16(pe + 6); i++) {
		const s = opt + u16(pe + 20) + i * 40;
		sections.push({ va: u32(s + 12), size: u32(s + 16), ptr: u32(s + 20) });
	}
	const fileOffset = (rva) => {
		const s = sections.find((s) => rva >= s.va && rva < s.va + s.size);
		if (!s) throw new Error(`${file}: RVA 0x${rva.toString(16)} is in no section`);
		return s.ptr + (rva - s.va);
	};

	const names = [];
	// Both directories are arrays of fixed-size descriptors ending in an all-zero one,
	// and both hold the DLL name as an RVA at a fixed offset. Reading only the first
	// would miss a delay-loaded dependency entirely — the loader resolves those on
	// first call rather than at load time, so the failure would arrive later and
	// nowhere near the cause, which is worse than the one this guard was written for.
	const walk = (index, stride, nameOffset) => {
		if (dirCount <= index) return;
		const rva = u32(dirs + index * 8);
		if (!rva) return;
		for (let entry = fileOffset(rva); ; entry += stride) {
			const nameRva = u32(entry + nameOffset);
			if (!nameRva) return;
			const at = fileOffset(nameRva);
			names.push(b.subarray(at, b.indexOf(0, at)).toString("latin1"));
		}
	};
	walk(1, 20, 12); // IMAGE_IMPORT_DESCRIPTOR.Name
	walk(13, 32, 4); // ImgDelayDescr.rvaDLLName
	return names;
}

/** IMAGE_FILE_HEADER.Machine, as the arch tag of the `win32-<arch>` directories. */
const PE_MACHINE = { 0x8664: "x64", 0xaa64: "arm64" };

/** The architecture a PE binary is built for, or undefined for a machine we do not ship. */
function peArch(file) {
	const b = fs.readFileSync(file);
	const notPe = () => new Error(`${file} is not a PE binary, or is truncated`);
	if (b.length < 0x40 || b.readUInt16LE(0) !== 0x5a4d) throw notPe();
	const pe = b.readUInt32LE(0x3c);
	if (pe + 6 > b.length || b.readUInt32LE(pe) !== 0x00004550) throw notPe();
	return PE_MACHINE[b.readUInt16LE(pe + 4)];
}

/**
 * Nothing we ship may depend on the Visual C++ Redistributable.
 *
 * This is the one failure this whole hook could not see. Every machine that builds this
 * repo, and most machines that have ever installed a desktop app, carry those DLLs in
 * System32 — so a binary that needs them works in local testing, in CI, and in every
 * package format, while being unloadable on a clean Windows image. There is no way to
 * reproduce it here; only the import table tells the truth.
 *
 * Store certification rejected 1.9.1 for exactly this: the WGC helper was built against
 * the dynamic CRT and died in the loader before main(), so the app reported
 * `Native Windows capture exited before recording started (code=3221225781)`
 * — 0xC0000135, STATUS_DLL_NOT_FOUND — and recording was impossible on the test device.
 * `compositor_view.node` had the same defect and would have failed certification a
 * second time, on the preview, right after the helper was fixed.
 *
 * The fix is per-toolchain, hence the two-part message: /MT for the CMake helpers
 * (electron/native/wgc-capture/CMakeLists.txt), `+crt-static` for the Rust addon
 * (crates/.cargo/config.toml).
 */
function checkWinNoRedistDependency(dir) {
	// Regular files only, and the same list serves both questions below. A directory
	// answers `readdirSync` by name exactly as a file does, and this directory really
	// does hold subdirectories (the vendored ffmpeg SDK), so the distinction is not
	// hypothetical. Without it one named `something.dll` is opened as a binary and the
	// hook dies on a raw `EISDIR` — the build stops, which is right, on a message that
	// names nothing, which is not.
	const files = fs
		.readdirSync(dir, { withFileTypes: true })
		.filter((entry) => entry.isFile())
		.map((entry) => entry.name);

	const scanned = files
		.filter((name) => /\.(exe|dll|node)$/i.test(name))
		.map((name) => ({ name, imports: importedDlls(path.join(dir, name)) }));

	// A guard that silently stops looking is worse than no guard: it reports "clean" for
	// the rest of the project's life. Every native binary imports something — kernel32 at
	// the very least — so an empty result means the parser broke, not that the file is
	// self-contained. Asserted here against the real payload rather than a synthetic PE
	// fixture, which would only ever prove this parser agrees with itself.
	const unread = scanned.filter((entry) => entry.imports.length === 0);
	if (unread.length > 0) {
		throw new Error(
			`Refusing to package: read no imports at all from ${unread.map((e) => e.name).join(", ")}.\n\n` +
				"Every native binary imports at least kernel32, so this is a bug in importedDlls()\n" +
				"(scripts/before-pack.cjs), not a self-contained binary. Fix the parser — leaving it\n" +
				"is how the Visual C++ Redistributable dependency gets back into a shipped build.",
		);
	}

	// The property that matters is not "imports a redistributable DLL", it is "imports a
	// redistributable DLL that will not be there". A copy sitting in this directory WILL
	// be there: it ships, and the loader searches an executable's own directory and, for
	// a .node, the module's — the same colocation that carries the ffmpeg DLLs. Shipping
	// vcomp140.dll beside the ggml libraries is therefore a fix, not an exception, and
	// the check has to be able to say so or it would forbid the remedy it asks for.
	const shipped = new Set(files.map((name) => name.toLowerCase()));
	const offenders = scanned
		.map((entry) => ({
			name: entry.name,
			bad: entry.imports.filter((d) => VC_REDIST_DLL.test(d) && !shipped.has(d.toLowerCase())),
		}))
		.filter((entry) => entry.bad.length > 0);
	if (offenders.length > 0) {
		throw new Error(
			"Refusing to package binaries that need the Visual C++ Redistributable.\n\n" +
				`  looked in: ${path.relative(ROOT, dir)}\n\n` +
				`${offenders.map((o) => `  - ${o.name} imports ${o.bad.join(", ")}`).join("\n")}\n\n` +
				"Those DLLs are not part of Windows. On a clean image the loader kills the process\n" +
				"before main() (0xC0000135) or fails require(), and the app can only report an exit\n" +
				"code. It works on every developer machine, which is why this is checked here.\n\n" +
				"Build against the static CRT instead:\n" +
				"  - CMake helpers: CMAKE_MSVC_RUNTIME_LIBRARY MultiThreaded (electron/native/wgc-capture)\n" +
				"  - Rust addon:    -C target-feature=+crt-static (crates/.cargo/config.toml)\n\n" +
				"For a prebuilt binary that is not ours to recompile, ship the DLL it needs into this\n" +
				"same directory and the check passes — that is what scripts/stage-vcomp-runtime.mjs\n" +
				"does for the OpenMP runtime the whisper/ggml libraries import.",
		);
	}

	// Every binary here must be built for this directory's architecture, and none of the
	// checks above can tell: the right name and clean imports say nothing about the
	// machine. An x64 compositor addon in win32-arm64 fails require() on every ARM64
	// device, and the Redist tree holds an x64 and an arm64 vcomp140.dll under the same
	// name, so either satisfies `shipped` while the loader refuses the wrong one with
	// the same 0xC0000135 as a missing file.
	//
	// The one exception is a runtime DLL that nothing here imports. The arm64 Redist
	// folder carries a vcruntime140_1.dll whose header says x64 — it is the ARM64EC build
	// Microsoft ships for emulated x64 code — and no ARM64 binary loads it.
	const dirArch = path.basename(dir).match(/^win32-(.+)$/)?.[1];
	if (!dirArch) {
		return;
	}
	const imported = new Set(scanned.flatMap((entry) => entry.imports.map((d) => d.toLowerCase())));
	const wrongArch = scanned
		.filter(({ name }) => !VC_REDIST_DLL.test(name) || imported.has(name.toLowerCase()))
		.map(({ name }) => ({ name, arch: peArch(path.join(dir, name)) }))
		.filter((entry) => entry.arch !== dirArch);
	if (wrongArch.length > 0) {
		throw new Error(
			"Refusing to package native binaries built for the wrong architecture.\n\n" +
				`${wrongArch.map((e) => `  - ${e.name} in ${path.basename(dir)} is built for ${e.arch ?? "an unknown machine"}`).join("\n")}\n\n` +
				`A ${dirArch} process cannot load them. Rebuild or re-fetch them for ${dirArch}; for the\n` +
				`Visual C++ runtime, stage the copy from VC\\Redist\\MSVC\\<version>\\${dirArch}\\ —\n` +
				"scripts/stage-vcomp-runtime.mjs does.",
		);
	}
}

/**
 * Every `win32-*` directory, because that is what ships: the extraResources filter is
 * `win32-*` / `*`, not the target's directory alone. The arm64 installer carries
 * win32-x64 for the whisper helper that runs under emulation, and checking only
 * win32-arm64 let that helper ship without the OpenMP runtime its ggml libraries import.
 */
function checkWinShippedRedist(binDir) {
	for (const entry of fs.readdirSync(binDir, { withFileTypes: true })) {
		if (entry.isDirectory() && /^win32-/.test(entry.name)) {
			checkWinNoRedistDependency(path.join(binDir, entry.name));
		}
	}
}

function checkWinNativePayload(context) {
	const dir = path.join(ROOT, "electron", "native", "bin", `win32-${archTagFor(context)}`);
	checkNativePayload({
		dir,
		required: WIN_REQUIRED,
		osLabel: "Windows",
		bundleNoun: "the installer",
		emptyDirFix: `${FIX}\n\nThe STT helper and the capture helper are separate builds — see\ntechnical-documentation/engineering/build-and-packaging.md.`,
	});
	checkWinShippedRedist(path.dirname(dir));
}

function checkMacNativePayload(context) {
	const arch = archTagFor(context);
	const dir = path.join(ROOT, "electron", "native", "bin", `darwin-${arch}`);
	checkNativePayload({
		dir,
		// Voir `MAC_ONNX_REQUIRED` : exiger la bibliothèque sur Intel ferait échouer une build
		// que l'amont rend impossible à satisfaire.
		required: arch === "arm64" ? [...MAC_REQUIRED, MAC_ONNX_REQUIRED] : MAC_REQUIRED,
		osLabel: "macOS",
		bundleNoun: "the .app",
		emptyDirFix: `${FIX_MAC}\n\nThe STT helper and the capture helper are separate builds — see\ntechnical-documentation/engineering/build-and-packaging.md.`,
	});

	// "Complete" is not the same property as "runnable on the macOS we claim". This file
	// exists because a payload can be whole and still broken; a floor above the supported
	// one is the second way that happens. See checkMacOsVersionFloor().
	checkMacOsVersionFloor(dir);
}

function checkLinuxNativePayload(context) {
	const dir = path.join(ROOT, "electron", "native", "bin", `linux-${archTagFor(context)}`);
	checkNativePayload({
		dir,
		required: LINUX_REQUIRED,
		osLabel: "Linux",
		bundleNoun: "the package",
		emptyDirFix: `${FIX_LINUX}\n\nThe capture helper and the STT helper are separate builds — see\ntechnical-documentation/engineering/build-and-packaging.md.`,
	});

	// Checked apart from LINUX_REQUIRED because "something named ffmpeg exists" is not the
	// property that matters — it has to be a directory holding the *unrenamed* libraries.
	// An empty one, or the wrong kind of entry, passes a name match and still ships a
	// helper that cannot start.
	const helperFfmpeg = path.join(dir, "helper-ffmpeg");
	const isDir = fs.existsSync(helperFfmpeg) && fs.statSync(helperFfmpeg).isDirectory();
	if (fs.existsSync(helperFfmpeg) && !isDir) {
		throw new Error(
			`Refusing to package: ${path.relative(ROOT, helperFfmpeg)} is a file, not a directory.\n\n` +
				"It should hold the PipeWire helper's unrenamed ffmpeg shared objects.\n" +
				"Delete it and re-run:\n\n    npm run build:native:linux",
		);
	}
	const libs = isDir
		? fs.readdirSync(helperFfmpeg).filter((name) => /^lib(av|sw)\w+\.so\.\d+$/.test(name))
		: [];
	if (libs.length === 0) {
		throw new Error(
			"Refusing to package an incomplete Linux payload.\n\n" +
				`  looked in: ${path.relative(ROOT, helperFfmpeg)}\n\n` +
				"Missing:\n  - the PipeWire helper's own ffmpeg shared objects\n" +
				"      without it: openscreen-pipewire-helper dies in ld.so, so capture never starts\n" +
				`      ${FIX_LINUX_HELPER.replace(/\n+/g, " ")}\n\n` +
				"These are deliberately not the copies one level up: those have every symbol\n" +
				"renamed to `osff_*` for the compositor addon, and the helper needs the originals.",
		);
	}

	checkLinuxSymbolVersionFloor(dir);
}

/**
 * The highest versioned symbol a shipped ELF may require, per version prefix.
 *
 * The Linux counterpart of the Windows import-table guard (checkWinNoRedistDependency
 * and importedDlls(), from #321 — this may land first, in which case they arrive with
 * it), and the same failure that hook could not see: the linker binds each symbol to
 * the newest version the BUILD machine
 * offers, so the runner image silently decides the oldest distro the packages run on.
 * It works on every developer machine and in CI by construction, and only the target
 * distro tells the truth.
 *
 * Nothing in the source asks for any of it. Built on ubuntu-latest (24.04) the payload
 * needed GLIBC_2.38 for four `__isoc23_strto*` — glibc 2.38's C23 redirect of `strtol`
 * — GLIBCXX_3.4.32 for `_ZSt21ios_base_library_initv`, which GCC 13.2+ emits into every
 * translation unit that includes <iostream>, and GLIBC_2.35 for one `hypotf`, a symbol
 * that has existed since 2.2.5 and whose newest version Rust's f32::hypot simply took.
 *
 * That shipped: on Ubuntu 22.04, Debian 12 and RHEL 9, whisper-stt-server and the ggml
 * backends died in ld.so before main() (transcription and captions fail with a developer
 * error), and on RHEL 9 compositor_view.node failed require() as well (no preview, and
 * every export falls back to the no-op compositor). The app still LAUNCHES on all of
 * them — Electron itself only needs 2.25 — so it reads as a broken app rather than a
 * broken package, and nothing in any log says otherwise. No package format catches it
 * either: the deb/rpm/pacman `depends` lists are hand-written in electron-builder.json5,
 * and electron-builder passes fpm none of --rpm-autoreq*, so not even dnf generates the
 * `libc.so.6(GLIBC_2.38)` requirement that would have refused the install.
 *
 * The ceiling is what the OLDEST distro the README claims actually provides. Ubuntu
 * 22.04 is the binding one — glibc 2.35, libstdc++6 from GCC 12 — against Debian 12's
 * 2.36 with the same libstdc++. Raising any of these is a decision to drop a distro
 * from the README, not a build detail; the runners are pinned to match (build.yml's
 * build-linux and build-whisper-stt.yml).
 */
const MAX_SYMBOL_VERSION = { GLIBC: "2.35", GLIBCXX: "3.4.30", CXXABI: "1.3.13" };

/**
 * The oldest macOS anything in the payload may demand — the macOS twin of
 * MAX_SYMBOL_VERSION above, and the same class of bug on a different libc.
 *
 * Must equal `mac.minimumSystemVersion` in electron-builder.json5, which is what the .app
 * tells LaunchServices; before-pack.test.mjs asserts exactly that, so the two cannot drift
 * apart quietly. Not read from the config at runtime because this hook must keep working
 * if that file is ever restructured — a guard that throws while parsing is a guard that
 * gets deleted.
 */
const MAC_MIN_OS_FLOOR = "13.0";

/**
 * The one supported way past the ceiling, for the one case it does not fit: a developer
 * on a distro newer than the floor, building a package for their own machine.
 *
 * Without it there is no way to get a .deb out of a working tree on, say, Ubuntu 24.04.
 * `npm run build:whisper-binaries` links whisper/ggml against the host's glibc, so the
 * guard refuses every local build and the only recourse is to push and wait for CI.
 * That is a real cost — it means nobody can test a packaging change without a round
 * trip — and it is what this exists to remove.
 *
 * `host` does NOT disable the check. It swaps the pinned ceiling for what this machine
 * actually provides, so a payload needing something even the host lacks still fails.
 * The guard keeps catching genuinely broken builds; it just stops pretending the
 * developer is on Ubuntu 22.04. What it gives up is the distro-floor promise, which is
 * exactly the promise a local build is not making.
 *
 * Refused outright under CI: an escape hatch that can reach a published artifact is not
 * an escape hatch, it is a hole. The runners are pinned to the floor, so they never
 * need it, and a release built with it set would be the bug this whole file prevents.
 */
const SYMBOL_FLOOR_MODE = process.env.OPENSCREEN_SYMBOL_FLOOR ?? "";

/** Dotted numeric compare, so 3.4.9 < 3.4.30 and 2.4 < 2.38 rather than by string. */
function compareVersions(a, b) {
	const left = a.split(".").map(Number);
	const right = b.split(".").map(Number);
	for (let i = 0; i < Math.max(left.length, right.length); i++) {
		if ((left[i] ?? 0) !== (right[i] ?? 0)) return (left[i] ?? 0) - (right[i] ?? 0);
	}
	return 0;
}

/**
 * The highest version an ELF needs per prefix, as `{ GLIBC: "2.38", GLIBCXX: "3.4.32" }`.
 *
 * Reads `.gnu.version_r` (the version NEEDS) and deliberately not `.gnu.version_d` (the
 * version DEFINITIONS): libc and libstdc++ define every version they ever shipped, so
 * reading definitions would report a bundled library as needing itself. Parsed here
 * rather than shelled out to readelf for the same reason importedDlls() does not use
 * dumpbin — binutils is not installed on every machine that packages this.
 *
 * 64-bit little-endian only, which is every arch this ships (x86_64, aarch64).
 */
function neededSymbolVersions(file) {
	const b = fs.readFileSync(file);
	if (b.readUInt32BE(0) !== 0x7f454c46) throw new Error(`${file} is not an ELF binary`);
	if (b[4] !== 2 || b[5] !== 1) throw new Error(`${file} is not 64-bit little-endian ELF`);

	const shoff = Number(b.readBigUInt64LE(0x28));
	const shentsize = b.readUInt16LE(0x3a);
	const SHT_GNU_VERNEED = 0x6ffffffe;

	let section;
	for (let i = 0; i < b.readUInt16LE(0x3c); i++) {
		const sh = shoff + i * shentsize;
		if (b.readUInt32LE(sh + 4) !== SHT_GNU_VERNEED) continue;
		// sh_info is the Verneed count; sh_link is the string table these names live in.
		const strtabHeader = shoff + b.readUInt32LE(sh + 0x28) * shentsize;
		section = {
			offset: Number(b.readBigUInt64LE(sh + 0x18)),
			count: b.readUInt32LE(sh + 0x2c),
			strtab: Number(b.readBigUInt64LE(strtabHeader + 0x18)),
		};
		break;
	}
	// No such section means the binary needs no versioned symbols at all — legitimate
	// for a fully static one, and nothing to check either way.
	if (!section) return {};

	const nameAt = (at) =>
		b.subarray(section.strtab + at, b.indexOf(0, section.strtab + at)).toString("latin1");

	const highest = {};
	let verneed = section.offset;
	for (let i = 0; i < section.count; i++) {
		let vernaux = verneed + b.readUInt32LE(verneed + 8);
		for (let j = 0; j < b.readUInt16LE(verneed + 2); j++) {
			// "GLIBC_2.38" -> prefix GLIBC, version 2.38. Anything not shaped like that
			// (there is none in practice) is skipped rather than guessed at.
			const [, prefix, version] =
				/^(.+)_(\d+(?:\.\d+)*)$/.exec(nameAt(b.readUInt32LE(vernaux + 8))) ?? [];
			if (prefix && (!highest[prefix] || compareVersions(version, highest[prefix]) > 0)) {
				highest[prefix] = version;
			}
			vernaux += b.readUInt32LE(vernaux + 12);
		}
		verneed += b.readUInt32LE(verneed + 12);
	}
	return highest;
}

/**
 * The mirror of neededSymbolVersions: what a library DEFINES (SHT_GNU_VERDEF) rather
 * than what it asks for. Only used to read the host's own ceiling — a payload binary
 * defines nothing interesting.
 *
 * Same hand-rolled parse as above, and for the same reason: this file already refuses
 * to shell out to readelf, so that a missing binutils cannot turn the guard off.
 */
function definedSymbolVersions(file) {
	const b = fs.readFileSync(file);
	if (b.readUInt32BE(0) !== 0x7f454c46) throw new Error(`${file} is not an ELF binary`);
	if (b[4] !== 2 || b[5] !== 1) throw new Error(`${file} is not 64-bit little-endian ELF`);

	const shoff = Number(b.readBigUInt64LE(0x28));
	const shentsize = b.readUInt16LE(0x3a);
	const SHT_GNU_VERDEF = 0x6ffffffd;

	let section;
	for (let i = 0; i < b.readUInt16LE(0x3c); i++) {
		const sh = shoff + i * shentsize;
		if (b.readUInt32LE(sh + 4) !== SHT_GNU_VERDEF) continue;
		// sh_info is the Verdef count; sh_link is the string table these names live in.
		const strtabHeader = shoff + b.readUInt32LE(sh + 0x28) * shentsize;
		section = {
			offset: Number(b.readBigUInt64LE(sh + 0x18)),
			count: b.readUInt32LE(sh + 0x2c),
			strtab: Number(b.readBigUInt64LE(strtabHeader + 0x18)),
		};
		break;
	}
	if (!section) return {};

	const nameAt = (at) =>
		b.subarray(section.strtab + at, b.indexOf(0, section.strtab + at)).toString("latin1");

	const highest = {};
	let verdef = section.offset;
	for (let i = 0; i < section.count; i++) {
		// Verdef: vd_version(2) vd_flags(2) vd_ndx(2) vd_cnt(2) vd_hash(4) vd_aux(4) vd_next(4)
		let verdaux = verdef + b.readUInt32LE(verdef + 12);
		for (let j = 0; j < b.readUInt16LE(verdef + 6); j++) {
			// Verdaux: vda_name(4) vda_next(4). The first entry of the first Verdef is the
			// soname rather than a version, and it simply does not match the pattern.
			const [, prefix, version] =
				/^(.+)_(\d+(?:\.\d+)*)$/.exec(nameAt(b.readUInt32LE(verdaux))) ?? [];
			if (prefix && (!highest[prefix] || compareVersions(version, highest[prefix]) > 0)) {
				highest[prefix] = version;
			}
			verdaux += b.readUInt32LE(verdaux + 4);
		}
		verdef += b.readUInt32LE(verdef + 16);
	}
	return highest;
}

/**
 * What THIS machine provides, read from the libraries node itself is running against —
 * `process.report` gives their absolute paths, so there is nothing to guess at and no
 * `ldconfig` to parse. node links both of the ones that matter.
 */
function hostSymbolCeiling() {
	const providers = process.report
		.getReport()
		.sharedObjects.filter((so) => /\/lib(?:c|stdc\+\+)\.so\.6(?:\.\d+)*$/.test(so));

	const ceiling = {};
	for (const lib of providers) {
		for (const [prefix, version] of Object.entries(definedSymbolVersions(lib))) {
			if (!(prefix in MAX_SYMBOL_VERSION)) continue;
			if (!ceiling[prefix] || compareVersions(version, ceiling[prefix]) > 0) {
				ceiling[prefix] = version;
			}
		}
	}

	// Every prefix the pinned ceiling names has to come back, or the comparison below
	// would quietly skip one and pass a payload nobody checked.
	const missing = Object.keys(MAX_SYMBOL_VERSION).filter((prefix) => !ceiling[prefix]);
	if (missing.length > 0) {
		throw new Error(
			`OPENSCREEN_SYMBOL_FLOOR=host could not read ${missing.join(", ")} from this machine.\n\n` +
				`  looked in: ${providers.join(", ") || "(node reported no libc/libstdc++)"}\n\n` +
				"Unset the variable to check against the pinned floor instead.",
		);
	}
	return ceiling;
}

/**
 * The ceiling this run compares against, plus whether it is the pinned one. Validates
 * OPENSCREEN_SYMBOL_FLOOR here rather than at module load, so a stray value cannot
 * break a Windows or macOS pack that never consults it.
 */
function resolveSymbolCeiling() {
	if (SYMBOL_FLOOR_MODE === "") {
		return { ceiling: MAX_SYMBOL_VERSION, pinned: true };
	}
	// An unrecognised value is an error, never a silent "enforce" or a silent "waive":
	// a typo in the one variable that relaxes this guard must not decide either way.
	if (SYMBOL_FLOOR_MODE !== "host") {
		throw new Error(
			`OPENSCREEN_SYMBOL_FLOOR=${SYMBOL_FLOOR_MODE} is not a value this guard knows.\n\n` +
				'The only accepted value is "host": compare against this machine rather than the\n' +
				"oldest supported distro, for a package you are building to run locally.\n" +
				"Unset it to check against the pinned floor.",
		);
	}
	if (process.env.CI) {
		throw new Error(
			"OPENSCREEN_SYMBOL_FLOOR=host is refused under CI.\n\n" +
				"It exists so a developer on a newer distro can build a package for their own\n" +
				"machine; a released artifact built with it would not start on the distros the\n" +
				"README claims. The runners are pinned to the floor (build.yml build-linux,\n" +
				"build-whisper-stt.yml), so nothing on CI needs it.",
		);
	}
	return { ceiling: hostSymbolCeiling(), pinned: false };
}

// Exported for scripts/before-pack.test.mjs and nothing else. The two refusals above
// are the only things standing between this escape hatch and a published package that
// starts on nobody's machine but the builder's, and they are reachable from a test
// without a payload to scan — so they are tested rather than trusted.
exports.__testing = {
	resolveSymbolCeiling,
	MAX_SYMBOL_VERSION,
	machoMinOs,
	checkMacOsVersionFloor,
	MAC_MIN_OS_FLOOR,
	MAC_REQUIRED,
	LINUX_REQUIRED,
	checkNativePayload,
	checkWinShippedRedist,
};

/** Every ELF under `dir`, recursively — the helper's ffmpeg sits in a subdirectory. */
function elfFilesUnder(dir) {
	const found = [];
	for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
		const full = path.join(dir, entry.name);
		if (entry.isDirectory()) {
			found.push(...elfFilesUnder(full));
			continue;
		}
		if (!entry.isFile()) continue;
		// By magic, not by extension: the helpers, whisper-stt-server and ffmpeg have none.
		const magic = Buffer.alloc(4);
		const fd = fs.openSync(full, "r");
		try {
			fs.readSync(fd, magic, 0, 4, 0);
		} finally {
			fs.closeSync(fd);
		}
		if (magic.readUInt32BE(0) === 0x7f454c46) found.push(full);
	}
	return found;
}

/** Nothing we ship may need a newer glibc or libstdc++ than MAX_SYMBOL_VERSION allows. */
function checkLinuxSymbolVersionFloor(dir) {
	const scanned = elfFilesUnder(dir).map((file) => ({
		name: path.relative(dir, file),
		needs: neededSymbolVersions(file),
	}));

	// The same assertion checkWinNoRedistDependency makes, for the same reason: a guard
	// that silently stops looking reports "clean" for the rest of the project's life.
	// Every dynamically linked binary in this payload needs versioned glibc symbols, so
	// finding none anywhere means the parser broke. Asserted across the scan rather than
	// per file, because a genuinely static binary legitimately has no .gnu.version_r.
	if (!scanned.some((entry) => entry.needs.GLIBC)) {
		throw new Error(
			`Refusing to package: read no glibc symbol versions from any of the ${scanned.length} ` +
				`ELF files in ${path.relative(ROOT, dir)}.\n\n` +
				"Every one of them links glibc, so this is a bug in neededSymbolVersions()\n" +
				"(scripts/before-pack.cjs), not a self-contained payload. Fix the parser — leaving\n" +
				"it is how packages that cannot start on the supported distros get shipped again.",
		);
	}

	// After the parser assertion on purpose: "does the pinned floor apply here" and "did
	// the scan work at all" are unrelated questions, and the second is how this guard
	// stays honest whichever ceiling it ends up using.
	const { ceiling, pinned } = resolveSymbolCeiling();
	if (!pinned) {
		// Loud, because a relaxed guard that says nothing is indistinguishable from a
		// guard that passed — and this one leaves a package that only runs here.
		console.log(
			`[before-pack] symbol-version ceiling taken from THIS MACHINE, not the pinned floor:\n` +
				`  ${Object.entries(ceiling)
					.map(([prefix, max]) => `${prefix}_${max}`)
					.join(", ")}  (pinned floor: ${Object.entries(MAX_SYMBOL_VERSION)
					.map(([prefix, max]) => `${prefix}_${max}`)
					.join(", ")})\n` +
				"  OPENSCREEN_SYMBOL_FLOOR=host is set. The package this produces may not start on\n" +
				"  the distros the README claims — do not publish it.",
		);
	}

	const offenders = scanned
		.map((entry) => ({
			name: entry.name,
			bad: Object.entries(ceiling)
				.filter(
					([prefix, max]) => entry.needs[prefix] && compareVersions(entry.needs[prefix], max) > 0,
				)
				.map(([prefix, max]) => `${prefix}_${entry.needs[prefix]} (max ${prefix}_${max})`),
		}))
		.filter((entry) => entry.bad.length > 0);
	if (offenders.length === 0) {
		return;
	}

	throw new Error(
		"Refusing to package binaries that need a newer glibc or libstdc++ than the oldest\n" +
			"supported distro provides.\n\n" +
			`  looked in: ${path.relative(ROOT, dir)}\n\n` +
			`${offenders.map((o) => `  - ${o.name} needs ${o.bad.join(", ")}`).join("\n")}\n\n` +
			"Almost certainly nothing asked for this: the linker binds each symbol to the newest\n" +
			"version the build machine offers, so this means something was built on a newer image\n" +
			"than the floor. On the target it dies in ld.so before main() or fails require(), while\n" +
			"the app still launches — so it reads as a broken app, and no package format catches it.\n\n" +
			"Build on the pinned runners: ubuntu-22.04 in .github/workflows/build.yml (build-linux)\n" +
			"and build-whisper-stt.yml. To see which symbols pulled a version in:\n\n" +
			"    readelf -V <file>\n" +
			"    readelf -W --dyn-syms <file> | grep @GLIBC_2.38\n\n" +
			(pinned
				? "Building a package to run on THIS machine rather than to release? Set\n" +
					"OPENSCREEN_SYMBOL_FLOOR=host, which compares against your own glibc instead of\n" +
					"the floor. It is refused under CI, so it cannot reach a published artifact.\n\n"
				: "") +
			"Raising MAX_SYMBOL_VERSION drops a distro the README claims to support.",
	);
}

/**
 * The macOS minimum-OS a Mach-O declares, as "12.0", or null if it declares none.
 *
 * Reads LC_BUILD_VERSION (and LC_VERSION_MIN_MACOSX, which is what anything built
 * against an older SDK carries) straight out of the file. Parsed here rather than
 * shelled out to `vtool -show-build` for the same reason neededSymbolVersions() does not
 * use readelf and importedDlls() does not use dumpbin — but with an extra one on top:
 * this hook runs for the Windows and Linux packs too, and vtool exists on neither, so a
 * subprocess would have to be skipped on exactly the hosts where skipping is silent.
 * Parsing makes the guard host-independent instead of conditionally absent.
 *
 * Universal binaries are walked slice by slice and the HIGHEST floor wins: an x86_64 half
 * built on a newer machine strands Intel users just as thoroughly as a thin binary would.
 */
function machoMinOs(file) {
	const b = fs.readFileSync(file);
	const FAT_MAGIC = 0xcafebabe;
	const FAT_MAGIC_64 = 0xcafebabf;
	const MH_MAGIC_64 = 0xfeedfacf;
	const MH_MAGIC_32 = 0xfeedface;
	const LC_VERSION_MIN_MACOSX = 0x24;
	const LC_BUILD_VERSION = 0x32;
	const PLATFORM_MACOS = 1;

	/** X.Y.Z packed as nibbles: 0x000c0000 is 12.0.0. */
	const decode = (packed) => `${packed >>> 16}.${(packed >> 8) & 0xff}.${packed & 0xff}`;

	const sliceMinOs = (start) => {
		const magic = b.readUInt32LE(start);
		if (magic !== MH_MAGIC_64 && magic !== MH_MAGIC_32) return null;
		const ncmds = b.readUInt32LE(start + 16);
		// 32 bytes of mach_header_64 (28 + 4 bytes of `reserved`); 28 for the 32-bit one.
		let off = start + (magic === MH_MAGIC_64 ? 32 : 28);
		for (let i = 0; i < ncmds; i++) {
			if (off + 8 > b.length) return null;
			const cmd = b.readUInt32LE(off);
			const cmdsize = b.readUInt32LE(off + 4);
			if (cmdsize < 8) return null;
			if (cmd === LC_BUILD_VERSION && b.readUInt32LE(off + 8) === PLATFORM_MACOS) {
				return decode(b.readUInt32LE(off + 12));
			}
			if (cmd === LC_VERSION_MIN_MACOSX) {
				return decode(b.readUInt32LE(off + 8));
			}
			off += cmdsize;
		}
		return null;
	};

	const fat = b.readUInt32BE(0);
	if (fat === FAT_MAGIC || fat === FAT_MAGIC_64) {
		const wide = fat === FAT_MAGIC_64;
		const nfat = b.readUInt32BE(4);
		let best = null;
		for (let i = 0; i < nfat; i++) {
			const entry = 8 + i * (wide ? 32 : 20);
			const offset = wide ? Number(b.readBigUInt64BE(entry + 8)) : b.readUInt32BE(entry + 8);
			const found = sliceMinOs(offset);
			if (found && (!best || compareVersions(found, best) > 0)) best = found;
		}
		return best;
	}

	return sliceMinOs(0);
}

/** Every Mach-O under `dir`, recursively. Symlinks are skipped — see elfFilesUnder(). */
function machoFilesUnder(dir) {
	const found = [];
	for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
		const full = path.join(dir, entry.name);
		if (entry.isDirectory()) {
			found.push(...machoFilesUnder(full));
			continue;
		}
		if (!entry.isFile()) continue;
		// By magic, not by extension: the helpers and whisper-stt-server have none, and
		// the ggml/whisper dylibs come as chains of symlinks onto one real file.
		const magic = Buffer.alloc(4);
		const fd = fs.openSync(full, "r");
		try {
			fs.readSync(fd, magic, 0, 4, 0);
		} finally {
			fs.closeSync(fd);
		}
		const le = magic.readUInt32LE(0);
		const be = magic.readUInt32BE(0);
		if (le === 0xfeedfacf || le === 0xfeedface || be === 0xcafebabe || be === 0xcafebabf) {
			found.push(full);
		}
	}
	return found;
}

/** Nothing we ship may demand a newer macOS than MAC_MIN_OS_FLOOR. */
function checkMacOsVersionFloor(dir) {
	const scanned = machoFilesUnder(dir).map((file) => ({
		name: path.relative(dir, file),
		minOs: machoMinOs(file),
	}));

	// Same assertion the Linux floor makes, for the same reason: a guard that quietly
	// stops looking reports "clean" for the rest of the project's life. Every binary we
	// ship is built with a deployment target, so reading none from any of them means the
	// parser broke rather than that the payload is unusually clean.
	if (scanned.length > 0 && !scanned.some((entry) => entry.minOs)) {
		throw new Error(
			`Refusing to package: read no macOS deployment target from any of the ${scanned.length} ` +
				`Mach-O files in ${path.relative(ROOT, dir)}.\n\n` +
				"Every one of them carries LC_BUILD_VERSION, so this is a bug in machoMinOs()\n" +
				"(scripts/before-pack.cjs), not an unusually clean payload. Fix the parser — leaving\n" +
				"it is how a build that cannot start on the supported macOS gets shipped again.",
		);
	}

	const offenders = scanned.filter(
		(entry) => entry.minOs && compareVersions(entry.minOs, MAC_MIN_OS_FLOOR) > 0,
	);
	if (offenders.length === 0) {
		return;
	}

	throw new Error(
		`Refusing to package binaries that demand a newer macOS than the ${MAC_MIN_OS_FLOOR} floor\n` +
			"the app claims to support.\n\n" +
			`  looked in: ${path.relative(ROOT, dir)}\n\n` +
			`${offenders.map((o) => `  - ${o.name} is built for macOS ${o.minOs} (floor ${MAC_MIN_OS_FLOOR})`).join("\n")}\n\n` +
			"Almost certainly nothing asked for this: clang and CMake default the deployment\n" +
			"target to the BUILD MACHINE's SDK, so this usually means a build script forgot to\n" +
			"pin one and the floor followed whatever image compiled it. CI's macos-latest moves\n" +
			"on its own, so the same source can ship a different floor month to month.\n\n" +
			"The number itself is not what breaks: dyld does NOT refuse a binary whose minos\n" +
			"exceeds the running OS. The damage is done at link time — the deployment target\n" +
			"decides which symbols the linker resolves against the OS instead of emitting\n" +
			"locally, so a too-high floor leaves strong references to symbols the target macOS\n" +
			"has never had, and the binary dies in dyld with 'Symbol not found'. That is issue\n" +
			"#515: a helper built for 13 stranded every macOS 12 user, and the app reported it\n" +
			"as a denied Accessibility permission.\n\n" +
			"Pin the deployment target in whichever script built the file:\n\n" +
			// Derived, not spelled out: this line said `.v12` for a while after the floor
			// moved to 13, i.e. the guard's own remediation advice contradicted the floor
			// it was enforcing.
			`    Swift    platforms: [.macOS(.v${MAC_MIN_OS_FLOOR.split(".")[0]})]      electron/native/screencapturekit/Package.swift\n` +
			"    CMake    -DCMAKE_OSX_DEPLOYMENT_TARGET  scripts/build-whisper-stt.sh\n" +
			"    clang    -mmacosx-version-min           scripts/fetch-ffmpeg-macos.mjs\n" +
			"    rustc    MACOSX_DEPLOYMENT_TARGET       scripts/build-macos-compositor-addon.mjs\n\n" +
			"To see it yourself:\n\n" +
			"    vtool -show-build <file>\n\n" +
			`Raising MAC_MIN_OS_FLOOR drops a macOS version the README claims to support.`,
	);
}

/** Newest mtime under `target` (file or directory), or 0 if it does not exist. */
function newestMtimeMs(target) {
	let stat;
	try {
		stat = fs.statSync(target);
	} catch {
		return 0;
	}
	if (!stat.isDirectory()) {
		return stat.mtimeMs;
	}
	let newest = 0;
	for (const entry of fs.readdirSync(target, { withFileTypes: true })) {
		newest = Math.max(newest, newestMtimeMs(path.join(target, entry.name)));
	}
	return newest;
}

// `label` is a full noun ("D3D11 compositor addon", "PipeWire capture helper"): this now
// guards artifacts that are not all compositor addons.
function checkCompositorAddonFreshness(
	addon = ADDON,
	fix = FIX,
	label = "D3D11 compositor addon",
	sources,
) {
	if (!fs.existsSync(addon)) {
		throw new Error(
			`Refusing to package: the ${label} is missing.\n\n  expected: ${addon}\n\n${fix}`,
		);
	}

	const addonMs = fs.statSync(addon).mtimeMs;
	const stale = (sources ?? SOURCE_PATHS)
		.map((source) => ({ source, ms: newestMtimeMs(source) }))
		.filter((entry) => entry.ms > addonMs);
	if (stale.length === 0) {
		return;
	}

	const newest = stale.reduce((a, b) => (a.ms > b.ms ? a : b));
	throw new Error(
		`Refusing to package a stale ${label}.\n\n` +
			`  addon: ${path.relative(ROOT, addon)}\n` +
			`  addon built: ${new Date(addonMs).toISOString()}\n` +
			`  newer source: ${path.relative(ROOT, newest.source)} (${new Date(newest.ms).toISOString()})\n\n` +
			"Packaging this would silently ship an addon that ignores newer scene fields\n" +
			"(they are #[serde(default)], so it falls back instead of erroring).\n\n" +
			fix,
	);
}

// electron-builder.json5 ships this as resources/THIRD-PARTY-LICENSES.txt, but for a missing
// extraResources source electron-builder only logs "file source doesn't exist" and packages
// without it. A packaging path that skipped `npm run licenses:generate` would ship an installer
// with no licence texts for the code it bundles, silently. The generator writes nothing when cargo
// cannot list the addon's crates, and never fails over a missing licence file, so only absence is
// refused here.
const THIRD_PARTY_LICENSES = path.join(ROOT, "build-licenses", "THIRD-PARTY-LICENSES.txt");

function checkThirdPartyLicenses() {
	if (!fs.existsSync(THIRD_PARTY_LICENSES)) {
		throw new Error(
			"Refusing to package without the third-party licence texts.\n\n" +
				`  expected: ${THIRD_PARTY_LICENSES}\n\n` +
				"Generate them with:\n\n    npm run licenses:generate\n\n" +
				"or use the build:<platform> script, which does that for you.",
		);
	}
}

exports.default = async function beforePack(context) {
	checkThirdPartyLicenses();
	const platform = context?.electronPlatformName ?? process.platform;
	if (platform === "win32") {
		// The copy that ships is the arch-tagged one under electron/native/bin/
		// (win.extraResources), beside its ffmpeg DLLs — not the dev copy this hook
		// used to be the sole guardian of. Same reasoning as the darwin branch below.
		const tag = `win32-${archTagFor(context)}`;
		const shipped = path.join(ROOT, "electron", "native", "bin", tag, "compositor_view.node");
		checkWinNativePayload(context);
		checkCompositorAddonFreshness(shipped, FIX, "D3D11");
		return;
	}
	if (platform === "darwin") {
		// The addon that actually ships is the arch-tagged copy under
		// electron/native/bin/ (mac.extraResources), not the dev copy this hook used to
		// be the sole guardian of — so that is the one whose freshness matters.
		const tag = `darwin-${archTagFor(context)}`;
		const shipped = path.join(ROOT, "electron", "native", "bin", tag, "compositor_view.node");
		checkMacNativePayload(context);
		checkCompositorAddonFreshness(shipped, FIX_MAC, "Metal compositor addon");
		return;
	}
	if (platform === "linux") {
		const tag = `linux-${archTagFor(context)}`;
		const dir = path.join(ROOT, "electron", "native", "bin", tag);
		checkLinuxNativePayload(context);
		checkCompositorAddonFreshness(
			path.join(dir, "compositor_view.node"),
			FIX_LINUX,
			"wgpu/Vulkan compositor addon",
		);
		checkCompositorAddonFreshness(
			path.join(dir, "openscreen-pipewire-helper"),
			FIX_LINUX_HELPER,
			"PipeWire capture helper",
			HELPER_SOURCE_PATHS,
		);
		return;
	}
};

// Runnable on its own for debugging: `node scripts/before-pack.cjs`
if (require.main === module) {
	try {
		checkThirdPartyLicenses();
		if (process.platform === "darwin") {
			checkMacNativePayload({ arch: undefined });
			const tag = `darwin-${process.arch}`;
			checkCompositorAddonFreshness(
				path.join(ROOT, "electron", "native", "bin", tag, "compositor_view.node"),
				FIX_MAC,
				"Metal compositor addon",
			);
			console.log(`macOS native payload complete in electron/native/bin/${tag}, addon up to date.`);
		} else if (process.platform === "linux") {
			// Was falling through to the Windows branch below, so running this on Linux
			// reported a missing D3D11 addon at a win32 path — noise, on the one platform
			// where the hook now has something to say.
			const tag = `linux-${process.arch}`;
			const dir = path.join(ROOT, "electron", "native", "bin", tag);
			checkLinuxNativePayload({ arch: undefined });
			checkCompositorAddonFreshness(
				path.join(dir, "compositor_view.node"),
				FIX_LINUX,
				"wgpu/Vulkan compositor addon",
			);
			checkCompositorAddonFreshness(
				path.join(dir, "openscreen-pipewire-helper"),
				FIX_LINUX_HELPER,
				"PipeWire capture helper",
				HELPER_SOURCE_PATHS,
			);
			console.log(`Linux native payload complete in electron/native/bin/${tag}, addon up to date.`);
		} else if (process.platform === "win32") {
			const shipped = path.join(
				ROOT,
				"electron",
				"native",
				"bin",
				"win32-x64",
				"compositor_view.node",
			);
			checkWinNativePayload();
			checkCompositorAddonFreshness(shipped, FIX, "D3D11");
			console.log(
				"Windows native payload complete in electron/native/bin/win32-x64 (addon beside its ffmpeg DLLs), addon up to date.",
			);
		} else {
			checkCompositorAddonFreshness();
			console.log("compositor addon is up to date with its Rust sources.");
		}
	} catch (err) {
		console.error(err.message);
		process.exit(1);
	}
}