opentray 0.16.0 → 0.18.0

package/dist/index.mjs

@@ -1,13 +1,240 @@
 import { createRequire } from "node:module";
 import { PROTOCOL_VERSION, PROTOCOL_VERSION as PROTOCOL_VERSION$1, brokerArtifactIdentityEquals, createBrokerEndpointIdentity, createBrokerEndpointIdentity as createBrokerEndpointIdentity$1, formatBrokerEndpointName, formatBrokerStateRoot, formatUnixSocketPath, formatUnixSocketPath as formatUnixSocketPath$1, formatWindowsPipeName, formatWindowsPipeName as formatWindowsPipeName$1, isBrokerArtifactIdentity, isSupportedProtocolVersion, parseServerFrame, sanitizeCallerLabel } from "@opentray/spec";
-import { access, mkdir, open, readFile, realpath, rm, unlink, writeFile } from "node:fs/promises";
-import { basename, dirname, join } from "node:path";
+import { access, appendFile, link, mkdir, open, readFile, realpath, rm, stat, unlink, writeFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { createConnection } from "node:net";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
+import { clearDarwinAppBundleOwner, convergeDarwinAppBundleIdentity, ensureDarwinAppBundle, resolveDefaultDarwinAppBundlePath, resolveOpenTrayPackageIdentity, updateDarwinAppLaunchDescriptor, writeDarwinAppBundleOwner } from "@opentray/packaging";
+import { createHash, randomUUID } from "node:crypto";
 import { constants } from "node:fs";
 import { spawn } from "node:child_process";
-import { createHash } from "node:crypto";
+//#region src/app-icon.ts
+const DEFAULT_APP_ICON_VARIANT = "default";
+const APP_ICON_VARIANT_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
+var InvalidAppIconError = class extends Error {
+	code = "OPENTRAY_INVALID_APP_ICON";
+	reason;
+	constructor(reason, platform = process.platform) {
+		super(`invalid appIcon for ${platform}: ${reason}`);
+		this.name = "InvalidAppIconError";
+		this.reason = reason;
+	}
+};
+var AppIconVariantNotFoundError = class extends Error {
+	code = "OPENTRAY_APP_ICON_VARIANT_NOT_FOUND";
+	variant;
+	constructor(variant, platform = process.platform) {
+		super(`appIcon variant ${variant} is unavailable for ${platform}`);
+		this.name = "AppIconVariantNotFoundError";
+		this.variant = variant;
+	}
+};
+/** Validate an explicit AppIcon, including native file signatures, before broker startup. */
+const validateAppIcon = async (icon, platform = process.platform) => {
+	if (!Array.isArray(icon) || icon.length === 0) throw new InvalidAppIconError("the asset array must not be empty", platform);
+	const variantPlatforms = /* @__PURE__ */ new Map();
+	const seenDarwin = /* @__PURE__ */ new Set();
+	const seenWindows = /* @__PURE__ */ new Set();
+	const seenLinuxPngSizes = /* @__PURE__ */ new Set();
+	const seenLinuxSvg = /* @__PURE__ */ new Set();
+	for (const asset of icon) {
+		if (!isRecord$1(asset)) throw new InvalidAppIconError("asset must be an object", platform);
+		const assetPlatform = asset.platform;
+		const format = asset.format;
+		const variants = validateVariantNames(asset.variant, platform);
+		if (assetPlatform === "darwin" && format === "icns") {
+			assertExactKeys(asset, [
+				"platform",
+				"format",
+				"source"
+			], platform, ["variant"]);
+			rejectDuplicateVariants(seenDarwin, variants, "darwin", platform);
+			await validateSource(asset.source, "icns", platform);
+			recordVariantPlatforms(variantPlatforms, variants, "darwin");
+			continue;
+		}
+		if (assetPlatform === "windows" && format === "ico") {
+			assertExactKeys(asset, [
+				"platform",
+				"format",
+				"source"
+			], platform, ["variant"]);
+			rejectDuplicateVariants(seenWindows, variants, "windows", platform);
+			await validateSource(asset.source, "ico", platform);
+			recordVariantPlatforms(variantPlatforms, variants, "windows");
+			continue;
+		}
+		if (assetPlatform === "linux" && format === "png") {
+			assertExactKeys(asset, [
+				"platform",
+				"format",
+				"size",
+				"source"
+			], platform, ["variant"]);
+			if (!Number.isInteger(asset.size) || typeof asset.size !== "number" || asset.size <= 0) throw new InvalidAppIconError("Linux PNG assets require a positive integer size", platform);
+			for (const variant of variants) {
+				const key = `${variant}\0${asset.size}`;
+				if (seenLinuxPngSizes.has(key)) throw new InvalidAppIconError(`duplicate Linux PNG size ${asset.size} for variant ${variant}`, platform);
+				seenLinuxPngSizes.add(key);
+			}
+			await validateSource(asset.source, "png", platform);
+			recordVariantPlatforms(variantPlatforms, variants, "linux");
+			continue;
+		}
+		if (assetPlatform === "linux" && format === "svg") {
+			assertExactKeys(asset, [
+				"platform",
+				"format",
+				"source"
+			], platform, ["variant"]);
+			rejectDuplicateVariants(seenLinuxSvg, variants, "Linux SVG", platform);
+			await validateSource(asset.source, "svg", platform);
+			recordVariantPlatforms(variantPlatforms, variants, "linux");
+			continue;
+		}
+		throw new InvalidAppIconError(`unsupported platform/format pair ${String(assetPlatform)}/${String(format)}`, platform);
+	}
+	const currentPlatform = normalizePlatform(platform);
+	if (currentPlatform !== void 0) {
+		if (!variantPlatforms.get("default")?.has(currentPlatform)) throw new InvalidAppIconError(`no ${currentPlatform} ${DEFAULT_APP_ICON_VARIANT} asset was provided`, platform);
+		for (const [variant, platforms] of variantPlatforms) if (!platforms.has(currentPlatform)) throw new InvalidAppIconError(`variant ${variant} has no ${currentPlatform} asset`, platform);
+	}
+};
+/** Normalize encoded sources into JSON array bytes for the Rust wire protocol. */
+const normalizeAppIcon = (icon) => icon.map((asset) => {
+	const source = normalizeSource(asset.source);
+	const variant = normalizeVariant(asset.variant);
+	if (asset.platform === "darwin") return {
+		...asset,
+		variant,
+		source
+	};
+	if (asset.platform === "windows") return {
+		...asset,
+		variant,
+		source
+	};
+	if (asset.format === "png") return {
+		...asset,
+		variant,
+		source
+	};
+	return {
+		...asset,
+		variant,
+		source
+	};
+});
+/** Select one semantic variant while retaining every platform's matching native asset. */
+const selectAppIconVariant = (icon, variant, platform = process.platform) => {
+	validateVariantName(variant, platform);
+	const selected = icon.filter((asset) => normalizedVariantNames(asset.variant).includes(variant));
+	const currentPlatform = normalizePlatform(platform);
+	if (selected.length === 0 || currentPlatform !== void 0 && !selected.some((asset) => asset.platform === currentPlatform)) throw new AppIconVariantNotFoundError(variant, platform);
+	return selected;
+};
+const normalizeSource = (source) => source.type === "encoded" ? {
+	type: "encoded",
+	data: Array.from(source.data)
+} : {
+	type: "file",
+	path: resolve(source.path)
+};
+const normalizeVariant = (variant) => variant === void 0 ? DEFAULT_APP_ICON_VARIANT : typeof variant === "string" ? variant : [...variant];
+const normalizedVariantNames = (variant) => variant === void 0 ? [DEFAULT_APP_ICON_VARIANT] : typeof variant === "string" ? [variant] : variant;
+const validateVariantNames = (variant, platform) => {
+	const names = variant === void 0 ? [DEFAULT_APP_ICON_VARIANT] : typeof variant === "string" ? [variant] : Array.isArray(variant) ? variant : [];
+	if (names.length === 0) throw new InvalidAppIconError("variant must be a name or non-empty name array", platform);
+	const seen = /* @__PURE__ */ new Set();
+	for (const name of names) {
+		validateVariantName(name, platform);
+		if (seen.has(name)) throw new InvalidAppIconError(`duplicate variant name ${name} on one asset`, platform);
+		seen.add(name);
+	}
+	return names;
+};
+function validateVariantName(variant, platform) {
+	if (typeof variant !== "string" || !APP_ICON_VARIANT_PATTERN.test(variant)) throw new InvalidAppIconError(`variant must match ${APP_ICON_VARIANT_PATTERN}`, platform);
+}
+const rejectDuplicateVariants = (seen, variants, label, hostPlatform) => {
+	for (const variant of variants) {
+		if (seen.has(variant)) throw new InvalidAppIconError(`duplicate ${label} asset for variant ${variant}`, hostPlatform);
+		seen.add(variant);
+	}
+};
+const recordVariantPlatforms = (variants, names, platform) => {
+	for (const name of names) {
+		const platforms = variants.get(name) ?? /* @__PURE__ */ new Set();
+		platforms.add(platform);
+		variants.set(name, platforms);
+	}
+};
+const validateSource = async (source, format, platform) => {
+	if (!isRecord$1(source)) throw new InvalidAppIconError("asset source must be a file or encoded payload", platform);
+	let bytes;
+	if (source.type === "file") {
+		assertExactKeys(source, ["type", "path"], platform);
+		if (typeof source.path !== "string" || source.path.trim().length === 0) throw new InvalidAppIconError("file source path must not be empty", platform);
+		try {
+			bytes = await readFile(source.path);
+		} catch (error) {
+			throw new InvalidAppIconError(`unable to read ${source.path}: ${errorMessage(error)}`, platform);
+		}
+	} else if (source.type === "encoded") {
+		assertExactKeys(source, ["type", "data"], platform);
+		bytes = encodedBytes(source.data, platform);
+	} else throw new InvalidAppIconError("unsupported app icon source type", platform);
+	if (!matchesFormat(bytes, format)) throw new InvalidAppIconError(`source bytes do not contain a valid ${format.toUpperCase()} asset`, platform);
+};
+const encodedBytes = (data, platform) => {
+	if (data instanceof Uint8Array && data.byteLength > 0) return data;
+	if (Array.isArray(data) && data.length > 0 && data.every((value) => Number.isInteger(value) && value >= 0 && value <= 255)) return Uint8Array.from(data);
+	throw new InvalidAppIconError("encoded source must contain one or more bytes in the range 0..255", platform);
+};
+const matchesFormat = (bytes, format) => {
+	if (format === "icns") return hasPrefix(bytes, [
+		105,
+		99,
+		110,
+		115
+	]);
+	if (format === "ico") return bytes.length >= 6 && hasPrefix(bytes, [
+		0,
+		0,
+		1,
+		0
+	]) && bytes[4] !== 0;
+	if (format === "png") return hasPrefix(bytes, [
+		137,
+		80,
+		78,
+		71,
+		13,
+		10,
+		26,
+		10
+	]);
+	const source = new TextDecoder().decode(bytes.subarray(0, 4096)).replace(/^\uFEFF/, "");
+	return /<(?:\?xml[^>]*>\s*)?(?:!--[\s\S]*?-->\s*)*svg(?:\s|>)/i.test(source.trimStart());
+};
+const hasPrefix = (bytes, prefix) => bytes.length >= prefix.length && prefix.every((byte, index) => bytes[index] === byte);
+const assertExactKeys = (record, expected, platform, optional = []) => {
+	const actual = Object.keys(record);
+	const allowed = new Set([...expected, ...optional]);
+	const unexpected = actual.find((key) => !allowed.has(key));
+	if (unexpected !== void 0) throw new InvalidAppIconError(`unexpected asset field ${unexpected}`, platform);
+	const missing = expected.find((key) => !(key in record));
+	if (missing !== void 0) throw new InvalidAppIconError(`missing asset field ${missing}`, platform);
+};
+const isRecord$1 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const errorMessage = (error) => error instanceof Error ? error.message : String(error);
+const normalizePlatform = (platform) => {
+	if (platform === "darwin") return "darwin";
+	if (platform === "win32") return "windows";
+	if (platform === "linux") return "linux";
+};
+//#endregion
 //#region src/native-extension-artifact.ts
 var NativeExtensionArtifactResolutionError = class extends Error {
 	target;
@@ -136,8 +363,7 @@ function createClient(transport, options = {}) {
 			const handle = createAppHandle(transport, app.appId, nextRequestId);
 			const configured = options.appOptions;
 			if (configured?.name !== void 0) await handle.setName(configured.name);
-			if (configured?.icon !== void 0) await handle.setIcon(configured.icon);
-			else if (trayOptions.icon !== void 0 && await handle.getIcon() === null) await handle.setIcon(trayOptions.icon);
+			if (configured?.appIcon !== void 0) await handle.setAppIcon(configured.appIcon);
 			return {
 				app,
 				handle
@@ -291,6 +517,11 @@ const attachEventfulTrayHandle = (handle, source, appId, nextMountId) => {
 		onTrayDoubleClick(handler) {
 			return listen("trayDoubleClick", handler);
 		},
+		onAppReopenRequested(handler) {
+			return source.onEvent((frame) => {
+				if (frame.type === "app-event" && frame.event.type === "reopenRequested" && frame.event.appId === appId) handler(frame.event);
+			});
+		},
 		extend(extension, options) {
 			const context = createTrayExtensionContext(eventful, appId, extension, options, nextMountId);
 			const capability = extension.extend(eventful, context, options);
@@ -332,18 +563,35 @@ const createAppHandle = (transport, appId, nextRequestId) => {
 			}), requestId, "ack");
 			return (await requestIdentity()).appName;
 		},
-		async getIcon() {
-			return (await requestIdentity()).icon ?? null;
+		async getAppIcon() {
+			return (await requestIdentity()).appIcon ?? null;
 		},
-		async setIcon(icon) {
+		async getAppIconVariant() {
+			return (await requestIdentity()).appIconVariant ?? null;
+		},
+		async setAppIcon(iconOrVariant) {
+			if (typeof iconOrVariant === "string") {
+				const identity = await requestIdentity();
+				if (identity.appIcon === void 0) selectAppIconVariant([], iconOrVariant);
+				else selectAppIconVariant(identity.appIcon, iconOrVariant);
+				const requestId = nextRequestId();
+				expectResponse(await transport.request({
+					type: "set-app-icon-variant",
+					requestId,
+					appId,
+					variant: iconOrVariant
+				}), requestId, "ack");
+				return;
+			}
+			if (iconOrVariant !== null) await validateAppIcon(iconOrVariant);
+			const appIcon = iconOrVariant === null ? null : normalizeAppIcon(iconOrVariant);
 			const requestId = nextRequestId();
 			expectResponse(await transport.request({
 				type: "set-app-icon",
 				requestId,
 				appId,
-				icon
+				appIcon
 			}), requestId, "ack");
-			return icon;
 		}
 	};
 };
@@ -412,6 +660,7 @@ const requestIdOf = (frame) => {
 		case "error": return frame.requestId;
 		case "ready":
 		case "event":
+		case "app-event":
 		case "ext-event": return;
 	}
 };
@@ -444,7 +693,8 @@ const resolveBrokerNativeTarget = (platform = process.platform, arch = process.a
 	const packageOs = platformToPackageOs(platform);
 	return {
 		packageName: `@opentray/${packageOs}-${normalizeArch(arch)}`,
-		binaryRelativePath: `bin/${packageOs === "windows" ? "opentray.exe" : "opentray"}`
+		binaryRelativePath: `bin/${packageOs === "windows" ? "opentray.exe" : "opentray"}`,
+		...packageOs === "darwin" ? { carrierTemplateRelativePath: "app/Info.plist" } : {}
 	};
 };
 const resolveBrokerArtifactTarget = (platform = process.platform, arch = process.arch) => {
@@ -520,10 +770,19 @@ const resolveBrokerCommand = async (paths, options = {}) => {
 	const arch = options.arch ?? process.arch;
 	const target = resolveBrokerNativeTarget(platform, arch);
 	const installed = await (options.resolveInstalledBrokerBinary ?? resolveInstalledBrokerBinary)(target, { platform });
-	if (installed.binary !== void 0) return commandForBinary(installed.binary, paths);
+	if (installed.binary !== void 0) {
+		if (platform !== "darwin") return commandForBinary(installed.binary, paths);
+		if (options.appBundle === void 0) return commandForBinary(installed.binary, paths);
+		if (installed.carrierTemplate === void 0) throw missingDarwinCarrierError(target, installed, arch);
+		return commandForBinary(await ensureDarwinBundle(options, paths, installed.binary, installed.carrierTemplate), paths);
+	}
 	const sourceDir = options.sourceDir ?? dirname(fileURLToPath(sourceUrl));
 	const workspaceRoot = await (options.findWorkspaceRoot ?? findWorkspaceRoot)(sourceDir);
-	if (workspaceRoot !== void 0) return commandForBinary(await (options.ensureDevBrokerBinary ?? ensureDevBrokerBinary)(workspaceRoot, paths, platform), paths);
+	if (workspaceRoot !== void 0) {
+		const binary = await (options.ensureDevBrokerBinary ?? ensureDevBrokerBinary)(workspaceRoot, paths, platform);
+		if (platform !== "darwin") return commandForBinary(binary, paths);
+		return commandForBinary(options.appBundle === void 0 ? binary : await ensureDarwinBundle(options, paths, binary, await (options.ensureDevDarwinCarrierTemplate ?? ensureDevDarwinCarrierTemplate)(workspaceRoot, paths)), paths);
+	}
 	throw new MissingPlatformBrokerBinaryError(installed.binaryPath === void 0 ? `unable to resolve OpenTray broker binary for ${platform}/${arch}; install "${target.packageName}" for this platform or set OPENTRAY_BROKER_BIN` : `unable to resolve OpenTray broker binary for ${platform}/${arch}; package "${target.packageName}" was found but binary "${installed.binaryPath}" is not accessible; restage the runtime package or set OPENTRAY_BROKER_BIN`, platform, arch, {
 		packageName: target.packageName,
 		...installed.binaryPath === void 0 ? {} : { binaryPath: installed.binaryPath }
@@ -539,14 +798,28 @@ const resolveInstalledBrokerBinary = async (target, options = {}) => {
 		throw error;
 	}
 	const binaryPath = join(dirname(packageJsonPath), target.binaryRelativePath);
+	const carrierTemplatePath = target.carrierTemplateRelativePath === void 0 ? void 0 : join(dirname(packageJsonPath), target.carrierTemplateRelativePath);
+	let carrierTemplate;
+	if (carrierTemplatePath !== void 0) try {
+		await (options.assertCarrierAccessible ?? assertInstalledCarrierAccessible)(carrierTemplatePath);
+		carrierTemplate = carrierTemplatePath;
+	} catch (error) {
+		if (!isNodeError$1(error) || error.code !== "ENOENT" && error.code !== "EACCES" && error.code !== "EPERM") throw error;
+	}
 	try {
 		await (options.assertBinaryAccessible ?? assertInstalledBrokerBinaryAccessible)(binaryPath, platform);
 		return {
 			binary: binaryPath,
-			binaryPath
+			binaryPath,
+			...carrierTemplatePath === void 0 ? {} : { carrierTemplatePath },
+			...carrierTemplate === void 0 ? {} : { carrierTemplate }
 		};
 	} catch (error) {
-		if (isNodeError$1(error) && (error.code === "ENOENT" || error.code === "EACCES" || error.code === "EPERM")) return { binaryPath };
+		if (isNodeError$1(error) && (error.code === "ENOENT" || error.code === "EACCES" || error.code === "EPERM")) return {
+			binaryPath,
+			...carrierTemplatePath === void 0 ? {} : { carrierTemplatePath },
+			...carrierTemplate === void 0 ? {} : { carrierTemplate }
+		};
 		throw error;
 	}
 };
@@ -593,15 +866,39 @@ const ensureDevBrokerBinary = async (workspaceRoot, paths, platform) => {
 	await runCargoBuild(workspaceRoot, platform === "win32" ? targetDir : void 0);
 	return binary;
 };
-const runCargoBuild = (workspaceRoot, targetDir) => new Promise((resolve, reject) => {
-	const child = spawn("cargo", [
-		"build",
-		"-p",
-		"opentray-bin",
-		...targetDir === void 0 ? [] : ["--target-dir", targetDir]
-	], {
-		cwd: workspaceRoot,
-		stdio: process.env.OPENTRAY_BROKER_BUILD_LOGS === "1" ? "inherit" : "ignore"
+const ensureDevDarwinCarrierTemplate = async (workspaceRoot, _paths) => {
+	return join(workspaceRoot, "packages/darwin-app-carrier/Info.plist");
+};
+const ensureDarwinBundle = async (options, paths, brokerPath, templatePath) => {
+	const appBundle = options.appBundle;
+	if (appBundle === void 0) return brokerPath;
+	const arch = options.arch ?? process.arch;
+	if (arch !== "arm64" && arch !== "x64") throw new Error(`unsupported Darwin app bundle architecture: ${arch}`);
+	return ensureDarwinAppBundle({
+		bundlePath: appBundle.path,
+		packageName: options.packageIdentity?.name ?? paths.callerLabel,
+		appId: paths.appId,
+		appName: paths.appName,
+		target: {
+			os: "darwin",
+			arch
+		},
+		brokerPath,
+		templatePath,
+		...options.appIcon === void 0 ? {} : { appIcon: options.appIcon },
+		...appBundle.reinitialize === void 0 ? {} : { reinitialize: appBundle.reinitialize }
+	});
+};
+const runCargoBuild = (workspaceRoot, targetDir) => runProcess("cargo", [
+	"build",
+	"-p",
+	"opentray-bin",
+	...targetDir === void 0 ? [] : ["--target-dir", targetDir]
+], workspaceRoot, process.env.OPENTRAY_BROKER_BUILD_LOGS === "1" ? "inherit" : "ignore");
+const runProcess = (command, args, cwd, stdio = "ignore") => new Promise((resolve, reject) => {
+	const child = spawn(command, [...args], {
+		cwd,
+		stdio
 	});
 	child.once("error", reject);
 	child.once("exit", (code) => {
@@ -609,7 +906,7 @@ const runCargoBuild = (workspaceRoot, targetDir) => new Promise((resolve, reject
 			resolve();
 			return;
 		}
-		reject(/* @__PURE__ */ new Error(`cargo build -p opentray-bin failed with code ${code ?? "unknown"}`));
+		reject(/* @__PURE__ */ new Error(`${command} ${args.join(" ")} failed with code ${code ?? "unknown"}`));
 	});
 });
 const exists = async (path) => {
@@ -624,52 +921,134 @@ const binaryAccessMode = (platform) => platform === "win32" ? constants.F_OK : c
 const assertInstalledBrokerBinaryAccessible = async (binaryPath, platform) => {
 	await access(binaryPath, binaryAccessMode(platform));
 };
+const assertInstalledCarrierAccessible = async (carrierPath) => {
+	await access(carrierPath, constants.F_OK);
+};
+const missingDarwinCarrierError = (target, resolution, arch) => new MissingPlatformBrokerBinaryError(`unable to resolve OpenTray Darwin app bundle template for ${target.packageName}; expected ${resolution.carrierTemplatePath ?? target.carrierTemplateRelativePath ?? "app/Info.plist"}`, "darwin", arch, {
+	packageName: target.packageName,
+	...resolution.carrierTemplatePath === void 0 ? {} : { binaryPath: resolution.carrierTemplatePath }
+});
 function isNodeError$1(error) {
 	return error instanceof Error && "code" in error;
 }
 //#endregion
 //#region src/daemon/lifecycle.ts
 const DAEMON_STDIO_ENV = "OPENTRAY_DAEMON_STDIO";
-const DEFAULT_DAEMON_LOCK_TIMEOUT_MS = 5e3;
-const createNodeDaemonDriver = (cliEntrypoint) => ({
+const DAEMON_POLL_INTERVAL_MS = 50;
+const DEFAULT_DAEMON_READY_TIMEOUT_MS = 1e4;
+const DEFAULT_DAEMON_LOCK_TIMEOUT_MS = 15e3;
+const ABANDONED_RECLAIM_CLAIM_MS = 1e3;
+const createNodeDaemonDriver = (cliEntrypoint, options = {}) => ({
 	async resolveBroker(paths) {
-		return resolveBrokerArtifact(paths);
+		return resolveBrokerArtifact(paths, {
+			...options.appBundle === void 0 ? {} : { appBundle: options.appBundle },
+			...options.appIcon === void 0 ? {} : { appIcon: options.appIcon },
+			...options.packageIdentity === void 0 ? {} : { packageIdentity: options.packageIdentity }
+		});
 	},
 	async isAlive(pid) {
 		return isProcessAlive(pid);
 	},
 	async spawnBroker(paths, broker) {
-		const child = spawn(broker.command, broker.args, {
-			cwd: broker.cwd,
-			detached: true,
-			env: {
-				...process.env,
-				OPENTRAY_DAEMON_HOME: paths.homeDir,
-				OPENTRAY_DAEMON_PACKAGE_VERSION: paths.packageVersion,
-				OPENTRAY_DAEMON_CLI_ENTRYPOINT: cliEntrypoint,
-				OPENTRAY_DAEMON_APP_ID: paths.appId,
-				OPENTRAY_DAEMON_APP_NAME: paths.appName,
-				OPENTRAY_DAEMON_CALLER_LABEL: paths.callerLabel
-			},
-			stdio: resolveBrokerStdio(process.env[DAEMON_STDIO_ENV])
+		const env = options.env ?? process.env;
+		const stdio = resolveBrokerStdio(env[DAEMON_STDIO_ENV]);
+		if (stdio === "log") await mkdir(paths.runtimeDir, { recursive: true });
+		const logHandle = stdio === "log" ? await open(paths.brokerLog, "a") : void 0;
+		if (logHandle !== void 0) await logHandle.appendFile(`${JSON.stringify({
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			event: "broker-spawn",
+			command: broker.command,
+			cwd: broker.cwd ?? process.cwd(),
+			appId: paths.appId,
+			appName: paths.appName
+		})}\n`, "utf8");
+		if (isAbsolute(broker.command)) try {
+			await access(broker.command, process.platform === "win32" ? constants.F_OK : constants.X_OK);
+		} catch (error) {
+			if (stdio === "log") await appendFile(paths.brokerLog, `${JSON.stringify({
+				timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+				event: "broker-spawn-error",
+				command: broker.command,
+				error: error instanceof Error ? error.message : String(error)
+			})}\n`, "utf8").catch(() => void 0);
+			await logHandle?.close();
+			return 0;
+		}
+		let child;
+		try {
+			child = spawn(broker.command, broker.args, {
+				cwd: broker.cwd,
+				detached: true,
+				env: {
+					...env,
+					OPENTRAY_DAEMON_HOME: paths.homeDir,
+					OPENTRAY_DAEMON_PACKAGE_VERSION: paths.packageVersion,
+					OPENTRAY_DAEMON_CLI_ENTRYPOINT: cliEntrypoint,
+					OPENTRAY_DAEMON_APP_ID: paths.appId,
+					OPENTRAY_DAEMON_APP_NAME: paths.appName,
+					OPENTRAY_DAEMON_CALLER_LABEL: paths.callerLabel
+				},
+				stdio: logHandle === void 0 ? stdio === "log" ? "ignore" : stdio : [
+					"ignore",
+					logHandle.fd,
+					logHandle.fd
+				]
+			});
+		} finally {
+			await logHandle?.close();
+		}
+		child.on("error", (error) => {
+			if (stdio !== "log") return;
+			appendFile(paths.brokerLog, `${JSON.stringify({
+				timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+				event: "broker-spawn-error",
+				command: broker.command,
+				error: error.message
+			})}\n`, "utf8").catch(() => void 0);
+		});
+		child.once("exit", (code, signal) => {
+			if (stdio !== "log") return;
+			appendFile(paths.brokerLog, `${JSON.stringify({
+				timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+				event: "broker-exit",
+				command: broker.command,
+				code,
+				signal
+			})}\n`, "utf8").catch(() => void 0);
 		});
 		child.unref();
-		return child.pid ?? 0;
+		const pid = child.pid ?? 0;
+		if (process.platform === "darwin" && options.appBundle !== void 0 && pid > 0) await writeDarwinAppBundleOwner(options.appBundle.path, pid, broker.artifactIdentity.executableHash);
+		return pid;
 	},
 	async stop(pid) {
 		process.kill(pid, "SIGTERM");
+		if (process.platform === "darwin" && options.appBundle !== void 0) await clearDarwinAppBundleOwner(options.appBundle.path, pid);
 	}
 });
 const resolveBrokerStdio = (value) => {
-	return value === "inherit" ? "inherit" : "ignore";
+	if (value === "inherit") return "inherit";
+	if (value === "ignore") return "ignore";
+	return "log";
 };
-const startDaemon = async ({ paths, driver, lockTimeoutMs = DEFAULT_DAEMON_LOCK_TIMEOUT_MS }) => {
-	const broker = await driver.resolveBroker(paths);
+const startDaemon = async ({ paths, driver, lockTimeoutMs = DEFAULT_DAEMON_LOCK_TIMEOUT_MS, readinessTimeoutMs = DEFAULT_DAEMON_READY_TIMEOUT_MS }) => {
 	await mkdir(paths.runtimeDir, { recursive: true });
-	const lock = await acquireLock(paths.lockFile, lockTimeoutMs);
+	const lock = await acquireDaemonLock(paths.lockFile, lockTimeoutMs);
 	try {
 		const existingPid = await readPid(paths.pidFile);
-		if (existingPid !== void 0 && await driver.isAlive(existingPid)) {
+		let existingAlive = existingPid !== void 0 && await driver.isAlive(existingPid);
+		let broker;
+		try {
+			broker = await driver.resolveBroker(paths);
+		} catch (error) {
+			if (existingAlive && isBundleInUseError(error) && existingPid !== void 0) {
+				await driver.stop(existingPid);
+				if (!await waitUntilStopped(driver, existingPid)) throw new Error(`incompatible daemon broker did not stop within the bounded shutdown window: pid=${existingPid}`);
+				existingAlive = false;
+				broker = await driver.resolveBroker(paths);
+			} else throw error;
+		}
+		if (existingPid !== void 0 && existingAlive) {
 			if (readyMatchesBroker(await readReadyMetadata(paths.readyFile), paths, existingPid, broker)) return {
 				status: "already-running",
 				pid: existingPid,
@@ -684,7 +1063,7 @@ const startDaemon = async ({ paths, driver, lockTimeoutMs = DEFAULT_DAEMON_LOCK_
 		if (!Number.isInteger(pid) || pid <= 0) throw new Error("daemon broker process did not expose a valid pid");
 		await writeFile(paths.pidFile, `${pid}\n`, "utf8");
 		try {
-			await waitForReadyFile(paths, driver, pid, broker);
+			await waitForReadyFile(paths, driver, pid, broker, readinessTimeoutMs);
 		} catch (error) {
 			if (await driver.isAlive(pid)) {
 				await driver.stop(pid);
@@ -721,19 +1100,22 @@ const cleanupRuntimeFiles = async (paths) => {
 const waitUntilStopped = async (driver, pid) => {
 	for (let attempt = 0; attempt < 20; attempt += 1) {
 		if (!await driver.isAlive(pid)) return true;
-		await sleep(50);
+		await sleep(DAEMON_POLL_INTERVAL_MS);
 	}
 	return false;
 };
-const waitForReadyFile = async (paths, driver, pid, broker) => {
-	for (let attempt = 0; attempt < 40; attempt += 1) {
+const waitForReadyFile = async (paths, driver, pid, broker, timeoutMs) => {
+	const deadline = Date.now() + timeoutMs;
+	while (true) {
 		const ready = await readReadyMetadata(paths.readyFile);
 		if (readyMatchesBroker(ready, paths, pid, broker)) return;
 		if (ready !== void 0) throw new Error(`daemon readiness artifact identity mismatch: expected=${JSON.stringify(broker.artifactIdentity)} actual=${JSON.stringify(ready.brokerArtifactIdentity)}`);
-		if (!await driver.isAlive(pid)) throw new Error(`daemon broker exited before readiness: pid=${pid}; readyFile=${paths.readyFile}; set ${DAEMON_STDIO_ENV}=inherit to inspect broker stderr`);
-		await sleep(50);
+		if (!await driver.isAlive(pid)) throw new Error(`daemon broker exited before readiness: pid=${pid}; readyFile=${paths.readyFile}; brokerLog=${paths.brokerLog}; set ${DAEMON_STDIO_ENV}=inherit to mirror broker stderr`);
+		const remainingMs = deadline - Date.now();
+		if (remainingMs <= 0) break;
+		await sleep(Math.min(DAEMON_POLL_INTERVAL_MS, remainingMs));
 	}
-	throw new Error(`timed out waiting for daemon readiness: ${paths.readyFile}`);
+	throw new Error(`timed out waiting for daemon readiness after ${timeoutMs}ms: pid=${pid}; readyFile=${paths.readyFile}; brokerLog=${paths.brokerLog}; set ${DAEMON_STDIO_ENV}=inherit to mirror broker stderr`);
 };
 const readReadyMetadata = async (readyFile) => {
 	let value;
@@ -758,24 +1140,31 @@ const readReadyMetadata = async (readyFile) => {
 	};
 };
 const readyMatchesBroker = (ready, paths, pid, broker) => ready !== void 0 && ready.pid === pid && ready.endpoint === paths.endpoint && ready.packageVersion === paths.packageVersion && ready.protocolVersion === paths.protocolVersion && ready.appId === paths.appId && ready.appName === paths.appName && ready.callerLabel === paths.callerLabel && executablePathsEqual(ready.executablePath, broker.executablePath) && brokerArtifactIdentityEquals(ready.brokerArtifactIdentity, broker.artifactIdentity);
+const isBundleInUseError = (error) => error instanceof Error && "code" in error && error.code === "bundle_in_use";
 const executablePathsEqual = (left, right, platform = process.platform) => {
 	if (platform !== "win32") return left === right;
 	const normalize = (value) => value.replaceAll("\\", "/").replace(/^\/\/?\?\//u, "").toLowerCase();
 	return normalize(left) === normalize(right);
 };
-const acquireLock = async (lockFile, timeoutMs) => {
+const acquireDaemonLock = async (lockFile, timeoutMs) => {
 	const deadline = Date.now() + timeoutMs;
+	const owner = `${JSON.stringify({
+		pid: process.pid,
+		token: randomUUID()
+	})}\n`;
 	while (Date.now() <= deadline) try {
 		const handle = await open(lockFile, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY);
-		await handle.writeFile(`${process.pid}\n`, "utf8");
+		await handle.writeFile(owner, "utf8");
 		return { async release() {
 			await handle.close();
+			if (await readLockSource(lockFile) !== owner) return;
 			await unlink(lockFile).catch((error) => {
 				if (!isNodeError(error) || error.code !== "ENOENT") throw error;
 			});
 		} };
 	} catch (error) {
 		if (isNodeError(error) && error.code === "EEXIST") {
+			if (await reclaimDeadLockOwner(lockFile)) continue;
 			await sleep(25);
 			continue;
 		}
@@ -783,12 +1172,72 @@ const acquireLock = async (lockFile, timeoutMs) => {
 	}
 	throw new Error(`timed out acquiring daemon lock: ${lockFile}`);
 };
+const reclaimDeadLockOwner = async (lockFile) => {
+	const observed = await readLockSource(lockFile);
+	if (observed === void 0) return true;
+	const owner = parseLockOwner(observed);
+	if (owner === void 0 || isProcessAlive(owner.pid)) return false;
+	const claimFile = `${lockFile}.reclaim-${createHash("sha256").update(observed).digest("hex").slice(0, 16)}`;
+	try {
+		await link(lockFile, claimFile);
+	} catch (error) {
+		if (isNodeError(error) && error.code === "ENOENT") return true;
+		if (isNodeError(error) && error.code === "EEXIST") {
+			await clearAbandonedReclaimClaim(claimFile);
+			return false;
+		}
+		throw error;
+	}
+	try {
+		if (await readLockSource(lockFile) !== observed || isProcessAlive(owner.pid)) return false;
+		try {
+			await unlink(lockFile);
+			return true;
+		} catch (error) {
+			if (isNodeError(error) && error.code === "ENOENT") return true;
+			throw error;
+		}
+	} finally {
+		await unlink(claimFile).catch((error) => {
+			if (!isNodeError(error) || error.code !== "ENOENT") throw error;
+		});
+	}
+};
+const clearAbandonedReclaimClaim = async (claimFile) => {
+	try {
+		const claim = await stat(claimFile);
+		if (Date.now() - claim.ctimeMs < ABANDONED_RECLAIM_CLAIM_MS) return;
+		await unlink(claimFile);
+	} catch (error) {
+		if (!isNodeError(error) || error.code !== "ENOENT") throw error;
+	}
+};
+const readLockSource = async (lockFile) => {
+	try {
+		return await readFile(lockFile, "utf8");
+	} catch (error) {
+		if (isNodeError(error) && error.code === "ENOENT") return void 0;
+		throw error;
+	}
+};
+const parseLockOwner = (source) => {
+	const legacyPid = Number(source.trim());
+	if (Number.isInteger(legacyPid) && legacyPid > 0) return { pid: legacyPid };
+	let value;
+	try {
+		value = JSON.parse(source);
+	} catch {
+		return;
+	}
+	if (!isRecord(value) || typeof value.pid !== "number" || !Number.isInteger(value.pid) || value.pid <= 0 || typeof value.token !== "string" || value.token.length === 0) return;
+	return { pid: value.pid };
+};
 const isProcessAlive = (pid) => {
 	try {
 		process.kill(pid, 0);
 		return true;
-	} catch {
-		return false;
+	} catch (error) {
+		return !(isNodeError(error) && error.code === "ESRCH");
 	}
 };
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
@@ -827,7 +1276,8 @@ const resolveDaemonPaths = ({ homeDir, packageVersion, callerLabel, appId, appNa
 		endpoint,
 		pidFile: `${runtimeDir}/broker.pid`,
 		lockFile: `${runtimeDir}/broker.lock`,
-		readyFile: `${runtimeDir}/ready.json`
+		readyFile: `${runtimeDir}/ready.json`,
+		brokerLog: `${runtimeDir}/broker.log`
 	};
 };
 const normalizeAppIdentityField$1 = (value, fallback) => {
@@ -854,7 +1304,16 @@ const connectLocalBroker = async (options = {}) => {
 	const autoStart = options.autoStart ?? endpoint === paths.endpoint;
 	if (autoStart && endpoint !== paths.endpoint) throw new Error("local broker autoStart requires the derived same-version endpoint");
 	const cliEntrypoint = options.cliEntrypoint ?? resolveCliEntrypoint();
-	const driver = options.daemonDriver ?? createNodeDaemonDriver(cliEntrypoint);
+	const packageIdentity = process.platform === "darwin" && autoStart ? await resolveOpenTrayPackageIdentity({
+		...options.packageName === void 0 ? {} : { packageName: options.packageName },
+		...options.packageRoot === void 0 ? {} : { packageRoot: options.packageRoot }
+	}) : void 0;
+	const appBundle = process.platform === "darwin" && autoStart ? resolveDarwinAppBundleOptions(options.appBundle, paths, packageIdentity) : void 0;
+	const driver = options.daemonDriver ?? createNodeDaemonDriver(cliEntrypoint, {
+		...appBundle === void 0 ? {} : { appBundle },
+		...options.appIcon === void 0 ? {} : { appIcon: options.appIcon },
+		...packageIdentity === void 0 ? {} : { packageIdentity }
+	});
 	const expectedBrokerArtifactIdentity = autoStart ? (await startDaemon({
 		paths,
 		driver
@@ -862,12 +1321,51 @@ const connectLocalBroker = async (options = {}) => {
 	const connection = new LocalBrokerConnection(await connectSocket(endpoint), endpoint, callerLabel);
 	try {
 		await connection.init(clientVersion, options.protocolVersion ?? PROTOCOL_VERSION$1, expectedBrokerArtifactIdentity);
+		if (appBundle !== void 0 && options.appLaunch !== void 0) {
+			await updateDarwinAppLaunchDescriptor(appBundle.path, options.appLaunch);
+			const convergence = await convergeDarwinAppBundleIdentity({
+				currentBundlePath: appBundle.path,
+				appId: paths.appId,
+				managedAppsRoot: resolve(paths.homeDir, ".opentray/apps"),
+				legacyRuntimeRoot: resolve(paths.homeDir, ".opentray"),
+				legacyBundlePaths: [resolve(paths.runtimeDir, "darwin-carrier/OpenTray.app")]
+			});
+			await appendBrokerDiagnostic(paths.brokerLog, {
+				event: "bundle-identity-convergence",
+				removed: convergence.removed,
+				skippedLiveOwner: convergence.skippedLiveOwner,
+				failedUnregister: convergence.failedUnregister
+			});
+		}
 	} catch (error) {
 		await connection.close();
 		throw error;
 	}
 	return connection;
 };
+const appendBrokerDiagnostic = async (path, value) => {
+	try {
+		await mkdir(dirname(path), { recursive: true });
+		await appendFile(path, `${JSON.stringify({
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			...value
+		})}\n`, "utf8");
+	} catch {}
+};
+const resolveDarwinAppBundleOptions = (configured, paths, packageIdentity) => {
+	if (packageIdentity === void 0) throw new Error("Darwin app bundle resolution requires the caller package identity");
+	const configuredPath = configured?.path;
+	return {
+		path: configuredPath === void 0 ? resolveDefaultDarwinAppBundlePath({
+			homeDir: paths.homeDir,
+			packageName: packageIdentity.name,
+			appName: paths.appName
+		}) : typeof configuredPath === "string" ? isAbsolute(configuredPath) ? configuredPath : resolve(packageIdentity.root, configuredPath) : configuredPath.protocol === "file:" ? fileURLToPath(configuredPath) : (() => {
+			throw new Error(`Darwin appBundle.path must be a file URL: ${configuredPath.href}`);
+		})(),
+		...configured?.reinitialize === void 0 ? {} : { reinitialize: configured.reinitialize }
+	};
+};
 const normalizeAppIdentityField = (value) => {
 	const trimmed = value?.trim();
 	return trimmed === void 0 || trimmed.length === 0 ? void 0 : trimmed;
@@ -980,7 +1478,7 @@ var LocalBrokerConnection = class {
 			this.pending.delete(requestId);
 			return;
 		}
-		if (frame.type === "event" || frame.type === "ext-event") for (const listener of this.listeners) listener(frame);
+		if (frame.type === "event" || frame.type === "app-event" || frame.type === "ext-event") for (const listener of this.listeners) listener(frame);
 	}
 	write(frame) {
 		this.socket.write(`${JSON.stringify(frame)}\n`);
@@ -1012,6 +1510,7 @@ const responseRequestId = (frame) => {
 		case "runtime-host-health": return frame.requestId;
 		case "ready":
 		case "event":
+		case "app-event":
 		case "ext-event":
 		case "error": return;
 	}
@@ -1139,14 +1638,53 @@ const registerClickId = (state, id) => {
 	state.seenClickIds = seen;
 };
 //#endregion
+//#region src/app-launch.ts
+const normalizeAppLaunch = (configured, context = {}) => {
+	const currentCwd = context.cwd ?? process.cwd();
+	if (configured === void 0 || configured === null) return {
+		schemaVersion: 1,
+		command: validateRequiredText(context.execPath ?? process.execPath, "process.execPath"),
+		args: [...(context.argv ?? process.argv).slice(1)].map((arg, index) => validateArg(arg, `process.argv[${index + 1}]`)),
+		cwd: validateRequiredText(currentCwd, "process.cwd()")
+	};
+	const command = validateRequiredText(configured.command, "appLaunch.command");
+	const cwd = resolve(currentCwd, configured.cwd === void 0 ? currentCwd : validateRequiredText(configured.cwd, "appLaunch.cwd"));
+	const args = [...configured.args ?? []].map((arg, index) => validateArg(arg, `appLaunch.args[${index}]`));
+	return {
+		schemaVersion: 1,
+		command: resolvePathLikeCommand(command, currentCwd),
+		args,
+		cwd
+	};
+};
+const resolvePathLikeCommand = (command, cwd) => {
+	if (isAbsolute(command) || command.includes("/") || command.includes("\\")) return resolve(cwd, command);
+	return command;
+};
+const validateRequiredText = (value, field) => {
+	if (value.trim().length === 0 || value.includes("\0")) throw new Error(`${field} must be a non-empty string without NUL`);
+	return value;
+};
+const validateArg = (value, field) => {
+	if (value.includes("\0")) throw new Error(`${field} must be a string without NUL`);
+	return value;
+};
+//#endregion
 //#region src/sdk.ts
 const createTray = async (options, runtimeOptions = {}) => {
+	if (runtimeOptions.appIcon !== void 0) await validateAppIcon(runtimeOptions.appIcon);
+	const appIcon = runtimeOptions.appIcon === void 0 ? void 0 : normalizeAppIcon(runtimeOptions.appIcon);
 	const normalized = normalizeCreateTrayOptions(options);
-	const connection = await connectLocalBroker(runtimeOptions);
+	const appLaunch = normalizeAppLaunch(runtimeOptions.appLaunch);
+	const connection = await connectLocalBroker({
+		...runtimeOptions,
+		...appIcon === void 0 ? {} : { appIcon },
+		appLaunch
+	});
 	try {
 		const tray = await createClient(connection, { appOptions: {
 			...runtimeOptions.appName === void 0 ? {} : { name: runtimeOptions.appName },
-			...runtimeOptions.appIcon === void 0 ? {} : { icon: runtimeOptions.appIcon }
+			...appIcon === void 0 ? {} : { appIcon }
 		} }).createTray(normalized.options);
 		return wrapCreateTrayHandle(tray, {
 			closeConnection: () => connection.close(),
@@ -1211,6 +1749,6 @@ const bindMenuClickHandlers = (tray, handlers) => {
 };
 const noop = () => {};
 //#endregion
-export { NativeExtensionArtifactResolutionError, PROTOCOL_VERSION, createBrokerEndpointIdentity, createClient, createInitFrame, createTray, createTrayHandle, formatBrokerEndpointName, formatBrokerStateRoot, formatUnixSocketPath, formatWindowsPipeName, isSupportedProtocolVersion, resolveNativeExtensionArtifact };
+export { AppIconVariantNotFoundError, DEFAULT_APP_ICON_VARIANT, InvalidAppIconError, NativeExtensionArtifactResolutionError, PROTOCOL_VERSION, createBrokerEndpointIdentity, createClient, createInitFrame, createTray, createTrayHandle, formatBrokerEndpointName, formatBrokerStateRoot, formatUnixSocketPath, formatWindowsPipeName, isSupportedProtocolVersion, resolveNativeExtensionArtifact, validateAppIcon };
 
 //# sourceMappingURL=index.mjs.map