opentray 0.15.0 → 0.17.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 { 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, ensureDarwinAppBundle, resolveDefaultDarwinAppBundlePath, resolveOpenTrayPackageIdentity, writeDarwinAppBundleOwner } from "@opentray/packaging";
 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;
@@ -129,8 +356,26 @@ const createInitFrame = (clientVersion) => ({
 });
 function createClient(transport, options = {}) {
 	const nextRequestId = createRequestIdFactory(options.requestIdPrefix ?? "opentray");
+	let appPromise;
+	const ensureApp = async (trayOptions) => {
+		appPromise ??= (async () => {
+			const app = await resolveDefaultAppRef(transport, nextRequestId);
+			const handle = createAppHandle(transport, app.appId, nextRequestId);
+			const configured = options.appOptions;
+			if (configured?.name !== void 0) await handle.setName(configured.name);
+			if (configured?.appIcon !== void 0) await handle.setAppIcon(configured.appIcon);
+			return {
+				app,
+				handle
+			};
+		})().catch((error) => {
+			appPromise = void 0;
+			throw error;
+		});
+		return appPromise;
+	};
 	return { async createTray(options) {
-		const app = await resolveDefaultAppRef(transport, nextRequestId);
+		const { app } = await ensureApp(options);
 		const requestId = nextRequestId();
 		const frame = expectResponse(await transport.request({
 			type: "create-tray",
@@ -150,6 +395,7 @@ function createTrayHandle(transport, appId, trayId, nextRequestId = createReques
 	};
 	const handle = {
 		trayId,
+		app: createAppHandle(transport, appId, nextRequestId),
 		async getBounds() {
 			const requestId = nextRequestId();
 			return expectResponse(await transport.request({
@@ -288,6 +534,62 @@ const resolveDefaultAppRef = async (transport, nextRequestId) => {
 		requestId
 	}), requestId, "default-app").app;
 };
+const createAppHandle = (transport, appId, nextRequestId) => {
+	const requestIdentity = async () => {
+		const requestId = nextRequestId();
+		return expectResponse(await transport.request({
+			type: "get-app-identity",
+			requestId,
+			appId
+		}), requestId, "app-identity").identity;
+	};
+	return {
+		appId,
+		async getName() {
+			return (await requestIdentity()).appName;
+		},
+		async setName(name) {
+			const requestId = nextRequestId();
+			expectResponse(await transport.request({
+				type: "set-app-name",
+				requestId,
+				appId,
+				name
+			}), requestId, "ack");
+			return (await requestIdentity()).appName;
+		},
+		async getAppIcon() {
+			return (await requestIdentity()).appIcon ?? null;
+		},
+		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,
+				appIcon
+			}), requestId, "ack");
+		}
+	};
+};
 const createTrayExtensionContext = (tray, appId, extension, options, nextMountId) => {
 	const mount = extension.resolveMount?.(options) ?? {};
 	const name = mount.name ?? extension.name;
@@ -344,6 +646,7 @@ const requestIdOf = (frame) => {
 	switch (frame.type) {
 		case "app-created":
 		case "default-app":
+		case "app-identity":
 		case "tray-created":
 		case "tray-bounds":
 		case "ack":
@@ -384,7 +687,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) => {
@@ -460,10 +764,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 }
@@ -479,14 +792,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;
 	}
 };
@@ -533,15 +860,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) => {
@@ -549,7 +900,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) => {
@@ -564,6 +915,13 @@ 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;
 }
@@ -571,9 +929,13 @@ function isNodeError$1(error) {
 //#region src/daemon/lifecycle.ts
 const DAEMON_STDIO_ENV = "OPENTRAY_DAEMON_STDIO";
 const DEFAULT_DAEMON_LOCK_TIMEOUT_MS = 5e3;
-const createNodeDaemonDriver = (cliEntrypoint) => ({
+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);
@@ -594,22 +956,36 @@ const createNodeDaemonDriver = (cliEntrypoint) => ({
 			stdio: resolveBrokerStdio(process.env[DAEMON_STDIO_ENV])
 		});
 		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";
 };
 const startDaemon = async ({ paths, driver, lockTimeoutMs = DEFAULT_DAEMON_LOCK_TIMEOUT_MS }) => {
-	const broker = await driver.resolveBroker(paths);
 	await mkdir(paths.runtimeDir, { recursive: true });
 	const lock = await acquireLock(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,
@@ -698,6 +1074,7 @@ 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();
@@ -794,7 +1171,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
@@ -808,6 +1194,20 @@ const connectLocalBroker = async (options = {}) => {
 	}
 	return connection;
 };
+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;
@@ -944,6 +1344,7 @@ const responseRequestId = (frame) => {
 	switch (frame.type) {
 		case "app-created":
 		case "default-app":
+		case "app-identity":
 		case "tray-created":
 		case "tray-bounds":
 		case "ack":
@@ -1080,10 +1481,18 @@ const registerClickId = (state, id) => {
 //#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 connection = await connectLocalBroker({
+		...runtimeOptions,
+		...appIcon === void 0 ? {} : { appIcon }
+	});
 	try {
-		const tray = await createClient(connection).createTray(normalized.options);
+		const tray = await createClient(connection, { appOptions: {
+			...runtimeOptions.appName === void 0 ? {} : { name: runtimeOptions.appName },
+			...appIcon === void 0 ? {} : { appIcon }
+		} }).createTray(normalized.options);
 		return wrapCreateTrayHandle(tray, {
 			closeConnection: () => connection.close(),
 			destroyPromise: void 0,
@@ -1147,6 +1556,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