opentray 0.8.0 → 0.9.0

package/dist/index.mjs

@@ -1,5 +1,12 @@
-import { t as connectLocalBroker } from "./local-broker-BMxjb-eO.mjs";
-import { PROTOCOL_VERSION, PROTOCOL_VERSION as PROTOCOL_VERSION$1, createBrokerEndpointIdentity, formatBrokerEndpointName, formatBrokerStateRoot, formatUnixSocketPath, formatWindowsPipeName, isSupportedProtocolVersion } from "@opentray/spec";
+import { t as createRuntimeBindingTransport } from "./runtime-binding-transport-UPunusBT.mjs";
+import { PROTOCOL_VERSION, PROTOCOL_VERSION as PROTOCOL_VERSION$1, createBrokerEndpointIdentity, createBrokerEndpointIdentity as createBrokerEndpointIdentity$1, formatBrokerEndpointName, formatBrokerStateRoot, formatUnixSocketPath, formatUnixSocketPath as formatUnixSocketPath$1, formatWindowsPipeName, formatWindowsPipeName as formatWindowsPipeName$1, isSupportedProtocolVersion, parseServerFrame, sanitizeCallerLabel } from "@opentray/spec";
+import { createConnection } from "node:net";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { basename, dirname, join } from "node:path";
+import { constants } from "node:fs";
+import { access, mkdir, open, readFile, rm, unlink, writeFile } from "node:fs/promises";
+import { spawn } from "node:child_process";
 //#region src/client.ts
 const createInitFrame = (clientVersion) => ({
 	type: "init",
@@ -8,46 +15,19 @@ const createInitFrame = (clientVersion) => ({
 });
 function createClient(transport, options = {}) {
 	const nextRequestId = createRequestIdFactory(options.requestIdPrefix ?? "opentray");
-	return {
-		async createSpace(spaceOptions) {
-			const requestId = nextRequestId();
-			const space = expectResponse(await transport.request({
-				type: "create-space",
-				requestId,
-				...spaceOptions
-			}), requestId, "space-created").space;
-			return createSpaceHandle(transport, space, nextRequestId);
-		},
-		async resolveDefaultSpace() {
-			const requestId = nextRequestId();
-			const space = expectResponse(await transport.request({
-				type: "resolve-default-space",
-				requestId
-			}), requestId, "default-space").space;
-			return createSpaceHandle(transport, space, nextRequestId);
-		},
-		async createSurface(spaceOptions) {
-			return this.createSpace(spaceOptions);
-		}
-	};
+	return { async createTray(options) {
+		const app = await resolveDefaultAppRef(transport, nextRequestId);
+		const requestId = nextRequestId();
+		const frame = expectResponse(await transport.request({
+			type: "create-tray",
+			requestId,
+			app,
+			tray: options
+		}), requestId, "tray-created");
+		return createTrayHandle(transport, app.appId, frame.trayId ?? options.id, nextRequestId);
+	} };
 }
-function createSpaceHandle(transport, space, nextRequestId = createRequestIdFactory("opentray")) {
-	return {
-		space,
-		async createTray(options) {
-			const requestId = nextRequestId();
-			return createTrayHandle(transport, space, expectResponse(await transport.request({
-				type: "create-tray",
-				requestId,
-				space,
-				tray: options
-			}), requestId, "tray-created").trayId, nextRequestId);
-		}
-	};
-}
-/** @deprecated Use `createSpaceHandle`. */
-const createSurfaceHandle = createSpaceHandle;
-function createTrayHandle(transport, space, trayId, nextRequestId = createRequestIdFactory("opentray")) {
+function createTrayHandle(transport, appId, trayId, nextRequestId = createRequestIdFactory("opentray")) {
 	let nextMountOrdinal = 1;
 	const nextMountId = (extensionName) => {
 		const mountId = `${formatMountIdComponent(extensionName)}.${formatMountIdComponent(trayId)}.${nextMountOrdinal}`;
@@ -55,14 +35,13 @@ function createTrayHandle(transport, space, trayId, nextRequestId = createReques
 		return mountId;
 	};
 	const handle = {
-		space,
 		trayId,
 		async getBounds() {
 			const requestId = nextRequestId();
 			return expectResponse(await transport.request({
 				type: "get-tray-bounds",
 				requestId,
-				spaceId: space.spaceId,
+				appId,
 				trayId
 			}), requestId, "tray-bounds").bounds;
 		},
@@ -71,7 +50,7 @@ function createTrayHandle(transport, space, trayId, nextRequestId = createReques
 			expectResponse(await transport.request({
 				type: "set-tray-menu",
 				requestId,
-				spaceId: space.spaceId,
+				appId,
 				trayId,
 				menu
 			}), requestId, "ack");
@@ -81,7 +60,7 @@ function createTrayHandle(transport, space, trayId, nextRequestId = createReques
 			expectResponse(await transport.request({
 				type: "set-tray-tooltip",
 				requestId,
-				spaceId: space.spaceId,
+				appId,
 				trayId,
 				tooltip
 			}), requestId, "ack");
@@ -91,27 +70,17 @@ function createTrayHandle(transport, space, trayId, nextRequestId = createReques
 			expectResponse(await transport.request({
 				type: "set-tray-icon",
 				requestId,
-				spaceId: space.spaceId,
+				appId,
 				trayId,
 				icon
 			}), requestId, "ack");
 		},
-		async setTitle(title) {
-			const requestId = nextRequestId();
-			expectResponse(await transport.request({
-				type: "set-tray-title",
-				requestId,
-				spaceId: space.spaceId,
-				trayId,
-				title
-			}), requestId, "ack");
-		},
 		async loadExtension(options) {
 			const requestId = nextRequestId();
 			expectResponse(await transport.request({
 				type: "load-ext",
 				requestId,
-				spaceId: space.spaceId,
+				appId,
 				name: options.name,
 				path: options.path,
 				...options.mountId === void 0 ? {} : { mountId: options.mountId }
@@ -125,7 +94,7 @@ function createTrayHandle(transport, space, trayId, nextRequestId = createReques
 			const response = await transport.request({
 				type: "ext-command",
 				requestId,
-				spaceId: space.spaceId,
+				appId,
 				trayId,
 				ext,
 				data
@@ -146,18 +115,18 @@ function createTrayHandle(transport, space, trayId, nextRequestId = createReques
 			expectResponse(await transport.request({
 				type: "destroy-tray",
 				requestId,
-				spaceId: space.spaceId,
+				appId,
 				trayId
 			}), requestId, "ack");
 		}
 	};
 	if (!isOpenTrayEventSource(transport)) return handle;
-	return attachEventfulTrayHandle(handle, transport, nextMountId);
+	return attachEventfulTrayHandle(handle, transport, appId, nextMountId);
 }
-const attachEventfulTrayHandle = (handle, source, nextMountId) => {
+const attachEventfulTrayHandle = (handle, source, appId, nextMountId) => {
 	const listen = (event, handler) => source.onEvent((frame) => {
 		if (frame.type !== "event" || frame.event.type !== event) return;
-		if (!isOwnedTrayEvent(frame.event, handle.space.spaceId, handle.trayId)) return;
+		if (!isOwnedTrayEvent(frame.event, appId, handle.trayId)) return;
 		handler(frame.event);
 	});
 	const eventful = {
@@ -165,10 +134,10 @@ const attachEventfulTrayHandle = (handle, source, nextMountId) => {
 		listenExtension(ext, handler) {
 			return source.onEvent((frame) => {
 				if (frame.type !== "ext-event" || frame.ext !== ext) return;
-				if (frame.spaceId !== handle.space.spaceId || frame.trayId !== handle.trayId) return;
+				if (frame.appId !== appId || frame.trayId !== handle.trayId) return;
 				handler({
 					scope: {
-						spaceId: frame.spaceId,
+						appId: frame.appId,
 						trayId: frame.trayId,
 						ext: frame.ext
 					},
@@ -194,8 +163,15 @@ const attachEventfulTrayHandle = (handle, source, nextMountId) => {
 	};
 	return eventful;
 };
-const isOwnedTrayEvent = (event, spaceId, trayId) => event.type !== "ready" && event.spaceId === spaceId && event.trayId === trayId;
+const isOwnedTrayEvent = (event, appId, trayId) => event.type !== "ready" && event.appId === appId && event.trayId === trayId;
 const isOpenTrayEventSource = (transport) => "onEvent" in transport && typeof transport.onEvent === "function";
+const resolveDefaultAppRef = async (transport, nextRequestId) => {
+	const requestId = nextRequestId();
+	return expectResponse(await transport.request({
+		type: "resolve-default-app",
+		requestId
+	}), requestId, "default-app").app;
+};
 const createTrayExtensionContext = (tray, extension, options, nextMountId) => {
 	const mount = extension.resolveMount?.(options) ?? {};
 	const name = mount.name ?? extension.name;
@@ -248,13 +224,13 @@ const expectResponse = (frame, requestId, type) => {
 };
 const requestIdOf = (frame) => {
 	switch (frame.type) {
-		case "space-created":
-		case "default-space":
+		case "app-created":
+		case "default-app":
 		case "tray-created":
 		case "tray-bounds":
 		case "ack":
 		case "ext-command-result":
-		case "daemon-health": return frame.requestId;
+		case "runtime-host-health": return frame.requestId;
 		case "error": return frame.requestId;
 		case "ready":
 		case "event":
@@ -262,21 +238,543 @@ const requestIdOf = (frame) => {
 	}
 };
 //#endregion
-//#region src/sdk.ts
-const createSpace = async (options, brokerOptions = {}) => {
-	return createClient(await connectLocalBroker(brokerOptions)).createSpace(options);
+//#region src/daemon/caller-label.ts
+/**
+* Derives a caller label using the precedence: explicit > npm_package_name >
+* script basename > neutral default. The result is always sanitized to a
+* filesystem- and process-safe component, so callers can use it directly in
+* endpoint identity, runtime directories, and process titles.
+*/
+const resolveCallerLabel = (options = {}) => {
+	const env = options.env ?? process.env;
+	const argv = options.argv ?? process.argv;
+	const candidates = [];
+	if (options.explicit !== void 0 && options.explicit.length > 0) candidates.push(options.explicit);
+	const npmName = options.npmPackageName ?? env.npm_package_name;
+	if (typeof npmName === "string" && npmName.length > 0) candidates.push(npmName);
+	const scriptPath = options.scriptPath ?? argv[1];
+	if (typeof scriptPath === "string" && scriptPath.length > 0) candidates.push(basename(scriptPath));
+	for (const candidate of candidates) {
+		const sanitized = sanitizeCallerLabel(candidate);
+		if (sanitized.length > 0) return sanitized;
+	}
+	return sanitizeCallerLabel(void 0);
+};
+//#endregion
+//#region src/daemon/native-target.ts
+const resolveBrokerNativeTarget = (platform = process.platform, arch = process.arch) => {
+	const packageOs = platformToPackageOs(platform);
+	return {
+		packageName: `@opentray/${packageOs}-${normalizeArch(arch)}`,
+		binaryRelativePath: `bin/${packageOs === "windows" ? "opentray.exe" : "opentray"}`
+	};
+};
+const platformToPackageOs = (platform) => {
+	switch (platform) {
+		case "darwin":
+		case "linux": return platform;
+		case "win32": return "windows";
+		default: throw new MissingPlatformBrokerBinaryError(`unsupported OpenTray broker platform: ${platform}`, platform, process.arch);
+	}
+};
+const normalizeArch = (arch) => {
+	switch (arch) {
+		case "arm64":
+		case "x64": return arch;
+		default: throw new MissingPlatformBrokerBinaryError(`unsupported OpenTray broker architecture: ${arch}`, process.platform, arch);
+	}
+};
+var MissingPlatformBrokerBinaryError = class extends Error {
+	code = "OPENTRAY_MISSING_PLATFORM_BROKER_BINARY";
+	platform;
+	arch;
+	packageName;
+	binaryPath;
+	constructor(message, platform, arch, options = {}) {
+		super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
+		this.name = "MissingPlatformBrokerBinaryError";
+		this.platform = platform;
+		this.arch = arch;
+		this.packageName = options.packageName;
+		this.binaryPath = options.binaryPath;
+	}
+};
+//#endregion
+//#region src/daemon/broker-command.ts
+const sourceUrl = import.meta.url;
+const resolveBrokerCommand = async (paths, options = {}) => {
+	const explicit = (options.env ?? process.env).OPENTRAY_BROKER_BIN;
+	if (explicit !== void 0 && explicit.length > 0) return commandForBinary(explicit, 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, workspaceRoot);
+	const platform = options.platform ?? process.platform;
+	const arch = options.arch ?? process.arch;
+	const target = resolveBrokerNativeTarget(platform, arch);
+	throw new MissingPlatformBrokerBinaryError(`unable to resolve OpenTray debug broker binary for ${platform}/${arch}; run from the source workspace or set OPENTRAY_BROKER_BIN`, platform, arch, { packageName: target.packageName });
+};
+const commandForBinary = (binary, paths, cwd) => {
+	const command = {
+		command: binary,
+		args: [
+			"broker",
+			"--endpoint",
+			paths.endpoint,
+			"--ready-file",
+			paths.readyFile,
+			"--package-version",
+			paths.packageVersion,
+			"--protocol-version",
+			`${paths.protocolVersion}`,
+			"--app-id",
+			paths.appId,
+			"--app-name",
+			paths.appName,
+			"--caller-label",
+			paths.callerLabel
+		]
+	};
+	if (cwd !== void 0) command.cwd = cwd;
+	return command;
+};
+const findWorkspaceRoot = async (start) => {
+	let current = start;
+	while (true) {
+		if (await exists(join(current, "Cargo.toml"))) {
+			if (await exists(join(current, "crates", "opentray-bin", "Cargo.toml"))) return current;
+		}
+		const parent = dirname(current);
+		if (parent === current) return;
+		current = parent;
+	}
+};
+const resolveDevBrokerBinaryPath = (workspaceRoot, platform = process.platform) => join(workspaceRoot, "target", "debug", platform === "win32" ? "opentray.exe" : "opentray");
+const terminateWorkspaceDevBrokerProcess = async (workspaceRoot, platform = process.platform) => {
+	if (platform !== "win32") return;
+	await terminateWindowsProcessByExecutable(resolveDevBrokerBinaryPath(workspaceRoot, platform));
+};
+const ensureDevBrokerBinary = async (workspaceRoot) => {
+	const binary = resolveDevBrokerBinaryPath(workspaceRoot);
+	await terminateWorkspaceDevBrokerProcess(workspaceRoot);
+	await runCargoBuild(workspaceRoot);
+	return binary;
+};
+const runCargoBuild = (workspaceRoot) => new Promise((resolve, reject) => {
+	const child = spawn("cargo", [
+		"build",
+		"-p",
+		"opentray-bin"
+	], {
+		cwd: workspaceRoot,
+		stdio: process.env.OPENTRAY_BROKER_BUILD_LOGS === "1" ? "inherit" : "ignore"
+	});
+	child.once("error", reject);
+	child.once("exit", (code) => {
+		if (code === 0) {
+			resolve();
+			return;
+		}
+		reject(/* @__PURE__ */ new Error(`cargo build -p opentray-bin failed with code ${code ?? "unknown"}`));
+	});
+});
+const exists = async (path) => {
+	try {
+		await access(path, constants.F_OK);
+		return true;
+	} catch {
+		return false;
+	}
+};
+const terminateWindowsProcessByExecutable = (binary) => new Promise((resolve, reject) => {
+	const child = spawn("powershell.exe", [
+		"-NoProfile",
+		"-NonInteractive",
+		"-ExecutionPolicy",
+		"Bypass",
+		"-Command",
+		String.raw`
+$ErrorActionPreference = 'Stop'
+$target = [System.IO.Path]::GetFullPath(${powerShellString(binary)})
+$processes = @(Get-CimInstance Win32_Process -Filter "Name = 'opentray.exe'" | Where-Object {
+  $_.ExecutablePath -and ([System.IO.Path]::GetFullPath($_.ExecutablePath) -ieq $target)
+})
+foreach ($process in $processes) {
+  Stop-Process -Id $process.ProcessId -Force -ErrorAction Stop
+}
+foreach ($process in $processes) {
+  Wait-Process -Id $process.ProcessId -Timeout 5 -ErrorAction SilentlyContinue
+}
+`
+	], { stdio: [
+		"ignore",
+		"ignore",
+		"pipe"
+	] });
+	let stderr = "";
+	child.stderr?.on("data", (chunk) => {
+		stderr += String(chunk);
+	});
+	child.once("error", reject);
+	child.once("exit", (code) => {
+		if (code === 0) {
+			resolve();
+			return;
+		}
+		reject(/* @__PURE__ */ new Error(`failed to stop running dev broker before cargo build: ${stderr.trim() || code}`));
+	});
+});
+const powerShellString = (value) => `'${value.replace(/'/g, "''")}'`;
+//#endregion
+//#region src/daemon/lifecycle.ts
+const DAEMON_STDIO_ENV = "OPENTRAY_DAEMON_STDIO";
+const createNodeDaemonDriver = (cliEntrypoint) => ({
+	async isAlive(pid) {
+		return isProcessAlive(pid);
+	},
+	async spawnBroker(paths) {
+		const broker = await resolveBrokerCommand(paths);
+		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])
+		});
+		child.unref();
+		return child.pid ?? 0;
+	},
+	async stop(pid) {
+		process.kill(pid, "SIGTERM");
+	}
+});
+const resolveBrokerStdio = (value) => {
+	return value === "inherit" ? "inherit" : "ignore";
+};
+const startDaemon = async ({ paths, driver, lockTimeoutMs = 1e3 }) => {
+	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)) return {
+			status: "already-running",
+			pid: existingPid,
+			paths
+		};
+		await cleanupRuntimeFiles(paths);
+		const pid = await driver.spawnBroker(paths);
+		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");
+		await waitForReadyFile(paths.readyFile, driver, pid);
+		return {
+			status: "started",
+			pid,
+			paths
+		};
+	} finally {
+		await lock.release();
+	}
+};
+const readPid = async (pidFile) => {
+	try {
+		const content = await readFile(pidFile, "utf8");
+		const pid = Number.parseInt(content.trim(), 10);
+		return Number.isInteger(pid) && pid > 0 ? pid : void 0;
+	} catch (error) {
+		if (isNodeError(error) && error.code === "ENOENT") return;
+		throw error;
+	}
 };
-/** @deprecated Use `createSpace`. */
-const createSurface = async (options, brokerOptions = {}) => createSpace(options, brokerOptions);
-const resolveDefaultSpace = async (brokerOptions = {}) => {
-	return createClient(await connectLocalBroker(brokerOptions)).resolveDefaultSpace();
+const cleanupRuntimeFiles = async (paths) => {
+	await rm(paths.readyFile, { force: true });
+	await rm(paths.pidFile, { force: true });
+	if (process.platform !== "win32") await rm(paths.endpoint, { force: true });
 };
-const createTray = async (options, brokerOptions = {}) => {
-	const { space, ...connectOptions } = brokerOptions;
-	const connection = await connectLocalBroker(connectOptions);
-	return (space ? createSpaceHandle(connection, space) : await createClient(connection).resolveDefaultSpace()).createTray(options);
+const waitForReadyFile = async (readyFile, driver, pid) => {
+	for (let attempt = 0; attempt < 40; attempt += 1) try {
+		await readFile(readyFile, "utf8");
+		return;
+	} catch (error) {
+		if (!isNodeError(error) || error.code !== "ENOENT") throw error;
+		if (!await driver.isAlive(pid)) throw new Error(`daemon broker exited before readiness: pid=${pid}; readyFile=${readyFile}; set ${DAEMON_STDIO_ENV}=inherit to inspect broker stderr`);
+		await sleep(50);
+	}
+	throw new Error(`timed out waiting for daemon readiness: ${readyFile}`);
+};
+const acquireLock = async (lockFile, timeoutMs) => {
+	const deadline = Date.now() + timeoutMs;
+	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");
+		return { async release() {
+			await handle.close();
+			await unlink(lockFile).catch((error) => {
+				if (!isNodeError(error) || error.code !== "ENOENT") throw error;
+			});
+		} };
+	} catch (error) {
+		if (isNodeError(error) && error.code === "EEXIST") {
+			await sleep(25);
+			continue;
+		}
+		throw error;
+	}
+	throw new Error(`timed out acquiring daemon lock: ${lockFile}`);
+};
+const isProcessAlive = (pid) => {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch {
+		return false;
+	}
+};
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const isNodeError = (error) => error instanceof Error && "code" in error;
+//#endregion
+//#region src/daemon/package-version.ts
+const readPackageVersion = async (packageJsonUrl) => {
+	const value = JSON.parse(await readFile(packageJsonUrl, "utf8"));
+	if (!isPackageJsonWithVersion(value)) throw new Error(`package.json is missing a string version: ${packageJsonUrl.href}`);
+	return value.version;
+};
+const isPackageJsonWithVersion = (value) => typeof value === "object" && value !== null && !Array.isArray(value) && "version" in value && typeof value.version === "string";
+//#endregion
+//#region src/daemon/paths.ts
+const resolveDaemonPaths = ({ homeDir, packageVersion, callerLabel, appId, appName, platform = process.platform }) => {
+	const identity = createBrokerEndpointIdentity$1(callerLabel === void 0 ? { packageVersion } : {
+		packageVersion,
+		callerLabel
+	});
+	const resolvedAppId = normalizeAppIdentityField$1(appId, identity.callerLabel);
+	const resolvedAppName = normalizeAppIdentityField$1(appName, identity.callerLabel);
+	const normalizedHome = homeDir.replace(/[\\/]+$/u, "");
+	const stateRoot = `${normalizedHome}/.opentray/${identity.packageVersion}/${identity.callerLabel}`;
+	const runtimeDir = `${stateRoot}/runtime`;
+	const endpoint = platform === "win32" ? formatWindowsPipeName$1(identity) : formatUnixSocketPath$1(normalizedHome, identity);
+	return {
+		homeDir: normalizedHome,
+		packageVersion: identity.packageVersion,
+		callerLabel: identity.callerLabel,
+		appId: resolvedAppId,
+		appName: resolvedAppName,
+		protocolVersion: identity.protocolVersion,
+		stateRoot,
+		runtimeDir,
+		endpoint,
+		pidFile: `${runtimeDir}/broker.pid`,
+		lockFile: `${runtimeDir}/broker.lock`,
+		readyFile: `${runtimeDir}/ready.json`
+	};
+};
+const normalizeAppIdentityField$1 = (value, fallback) => {
+	const trimmed = value?.trim();
+	return trimmed === void 0 || trimmed.length === 0 ? fallback : trimmed;
+};
+//#endregion
+//#region src/local-broker.ts
+const packageJsonUrl = new URL("../package.json", import.meta.url);
+const connectLocalBroker = async (options = {}) => {
+	const packageVersion = options.packageVersion ?? await readPackageVersion(packageJsonUrl);
+	const clientVersion = options.clientVersion ?? packageVersion;
+	const appId = normalizeAppIdentityField(options.appId);
+	const appName = normalizeAppIdentityField(options.appName);
+	const callerLabel = options.callerLabel ?? appName ?? appId ?? resolveCallerLabel();
+	const paths = resolveDaemonPaths({
+		homeDir: options.homeDir ?? process.env.OPENTRAY_HOME ?? homedir(),
+		packageVersion,
+		callerLabel,
+		...appId === void 0 ? {} : { appId },
+		...appName === void 0 ? {} : { appName }
+	});
+	const endpoint = options.endpoint ?? paths.endpoint;
+	const autoStart = options.autoStart ?? endpoint === paths.endpoint;
+	if (autoStart && endpoint !== paths.endpoint) throw new Error("local broker autoStart requires the derived same-version endpoint");
+	if (autoStart) {
+		const cliEntrypoint = options.cliEntrypoint ?? resolveCliEntrypoint();
+		await startDaemon({
+			paths,
+			driver: options.daemonDriver ?? createNodeDaemonDriver(cliEntrypoint)
+		});
+	}
+	const connection = new LocalBrokerConnection(await connectSocket(endpoint), endpoint, callerLabel);
+	await connection.init(clientVersion, options.protocolVersion ?? PROTOCOL_VERSION$1);
+	return connection;
+};
+const normalizeAppIdentityField = (value) => {
+	const trimmed = value?.trim();
+	return trimmed === void 0 || trimmed.length === 0 ? void 0 : trimmed;
+};
+var LocalBrokerConnection = class {
+	socket;
+	endpoint;
+	callerLabel;
+	sessionId = "";
+	buffer = "";
+	listeners = /* @__PURE__ */ new Set();
+	pending = /* @__PURE__ */ new Map();
+	ready;
+	constructor(socket, endpoint, callerLabel) {
+		this.socket = socket;
+		this.endpoint = endpoint;
+		this.callerLabel = callerLabel;
+		socket.setEncoding("utf8");
+		socket.on("data", (chunk) => {
+			this.consume(String(chunk));
+		});
+		socket.on("error", (error) => {
+			this.rejectAll(error);
+		});
+		socket.on("close", () => {
+			this.rejectAll(/* @__PURE__ */ new Error("broker connection closed"));
+		});
+	}
+	async init(clientVersion, protocolVersion) {
+		const ready = new Promise((resolve, reject) => {
+			this.ready = {
+				resolve,
+				reject
+			};
+		});
+		this.write({
+			type: "init",
+			protocolVersion,
+			clientVersion
+		});
+		const frame = await ready;
+		this.sessionId = frame.sessionId;
+	}
+	async request(frame) {
+		if (this.pending.has(frame.requestId)) throw new Error(`duplicate requestId: ${frame.requestId}`);
+		const response = new Promise((resolve, reject) => {
+			this.pending.set(frame.requestId, {
+				resolve,
+				reject
+			});
+		});
+		this.write(frame);
+		return response;
+	}
+	onEvent(listener) {
+		this.listeners.add(listener);
+		return () => {
+			this.listeners.delete(listener);
+		};
+	}
+	async close() {
+		this.write({ type: "exit" });
+		await new Promise((resolve) => {
+			this.socket.end(resolve);
+		});
+	}
+	consume(chunk) {
+		this.buffer += chunk;
+		while (true) {
+			const newline = this.buffer.indexOf("\n");
+			if (newline < 0) return;
+			const line = this.buffer.slice(0, newline).trim();
+			this.buffer = this.buffer.slice(newline + 1);
+			if (line.length > 0) this.dispatchLine(line);
+		}
+	}
+	dispatchLine(line) {
+		const parsed = parseServerFrame(line);
+		if (!parsed.ok || parsed.frame === void 0) {
+			this.rejectAll(/* @__PURE__ */ new Error(`${parsed.error ?? "invalid server frame"}: ${line}`));
+			return;
+		}
+		this.dispatchFrame(parsed.frame);
+	}
+	dispatchFrame(frame) {
+		if (frame.type === "ready") {
+			this.ready?.resolve(frame);
+			this.ready = void 0;
+			return;
+		}
+		if (frame.type === "error") {
+			const error = /* @__PURE__ */ new Error(`${frame.code}: ${frame.message}`);
+			if (frame.requestId !== void 0) {
+				this.pending.get(frame.requestId)?.reject(error);
+				this.pending.delete(frame.requestId);
+				return;
+			}
+			if (this.ready) {
+				this.ready.reject(error);
+				this.ready = void 0;
+				return;
+			}
+			this.rejectAll(error);
+			return;
+		}
+		const requestId = responseRequestId(frame);
+		if (requestId !== void 0) {
+			this.pending.get(requestId)?.resolve(frame);
+			this.pending.delete(requestId);
+			return;
+		}
+		if (frame.type === "event" || frame.type === "ext-event") for (const listener of this.listeners) listener(frame);
+	}
+	write(frame) {
+		this.socket.write(`${JSON.stringify(frame)}\n`);
+	}
+	rejectAll(error) {
+		this.ready?.reject(error);
+		this.ready = void 0;
+		for (const pending of this.pending.values()) pending.reject(error);
+		this.pending.clear();
+	}
+};
+const connectSocket = (endpoint) => new Promise((resolve, reject) => {
+	const socket = createConnection(endpoint);
+	socket.once("connect", () => {
+		socket.off("error", reject);
+		resolve(socket);
+	});
+	socket.once("error", reject);
+});
+const responseRequestId = (frame) => {
+	switch (frame.type) {
+		case "app-created":
+		case "default-app":
+		case "tray-created":
+		case "tray-bounds":
+		case "ack":
+		case "ext-command-result":
+		case "runtime-host-health": return frame.requestId;
+		case "ready":
+		case "event":
+		case "ext-event":
+		case "error": return;
+	}
+};
+const resolveCliEntrypoint = () => {
+	const suffix = fileURLToPath(import.meta.url).endsWith(".ts") ? "cli.ts" : "cli.mjs";
+	return fileURLToPath(new URL(`./${suffix}`, import.meta.url));
+};
+//#endregion
+//#region src/sdk.ts
+const createTray = async (options, runtimeOptions = {}) => {
+	const bindingTransportOptions = {
+		...runtimeOptions.binding === void 0 ? {} : { binding: runtimeOptions.binding },
+		...runtimeOptions.packageVersion === void 0 ? {} : { packageVersion: runtimeOptions.packageVersion },
+		...runtimeOptions.clientVersion === void 0 ? {} : { clientVersion: runtimeOptions.clientVersion },
+		...runtimeOptions.protocolVersion === void 0 ? {} : { protocolVersion: runtimeOptions.protocolVersion },
+		...runtimeOptions.appId === void 0 ? {} : { appId: runtimeOptions.appId },
+		...runtimeOptions.appName === void 0 ? {} : { appName: runtimeOptions.appName }
+	};
+	const runtime = runtimeOptions.runtime ?? "visible-binding";
+	return createClient(runtime === "local-broker" ? await connectLocalBroker(runtimeOptions) : await createRuntimeBindingTransport({
+		...bindingTransportOptions,
+		kind: runtime === "headless-binding" ? "headless" : "visible"
+	})).createTray(options);
 };
 //#endregion
-export { PROTOCOL_VERSION, createBrokerEndpointIdentity, createClient, createInitFrame, createSpace, createSpaceHandle, createSurface, createSurfaceHandle, createTray, createTrayHandle, formatBrokerEndpointName, formatBrokerStateRoot, formatUnixSocketPath, formatWindowsPipeName, isSupportedProtocolVersion, resolveDefaultSpace };
+export { PROTOCOL_VERSION, createBrokerEndpointIdentity, createClient, createInitFrame, createTray, createTrayHandle, formatBrokerEndpointName, formatBrokerStateRoot, formatUnixSocketPath, formatWindowsPipeName, isSupportedProtocolVersion };
 
 //# sourceMappingURL=index.mjs.map