opentray 0.9.0 → 0.10.0

package/README.md

@@ -8,6 +8,14 @@ Install it directly in the application or service that owns the tray lifetime:
 pnpm add opentray
 ```
 
+Use `latest` for the newest published package. When installing official extensions, use one protocol-line tag across the package set:
+
+```bash
+pnpm add opentray@stable-A-B @opentray/ext-webview@stable-A-B
+```
+
+Use `alpha-A-B` for alpha packages on the same protocol line. Replace `A-B` with the current OpenTray protocol-line tag from `@opentray/spec`; do not mix `latest` and protocol-line tags unless you are debugging install drift.
+
 ## Role
 
 - Expose `createTray()` as the public creation entrypoint.
@@ -19,6 +27,23 @@ pnpm add opentray
 
 ## Tray-First API
 
+For the first app, use `runTrayApp()` from `opentray/node` so the host/worker split stays out of the user's way:
+
+```ts
+import { runTrayApp } from "opentray/node";
+
+await runTrayApp(async ({ createTray }) => {
+  const tray = await createTray({
+    id: "com.example.first-app",
+    icon: { "text-only": "OT" },
+    menu: { items: [{ type: "item", id: 1, title: "Quit", primaryEvent: true }] },
+  });
+  tray.onMenuClick(({ itemId }) => void (itemId === 1 && tray.destroy()));
+}, { autoExitAfterMs: 1500 });
+```
+
+`createTray()` is still the direct tray API when the caller already owns the runtime process shape.
+
 ```ts
 import { createTray } from "opentray";
 
@@ -46,7 +71,7 @@ tray.onMenuClick(({ itemId }) => {
 });
 ```
 
-Visible tray text belongs to `icon.text`, `icon["text-only"]`, or `icon["icon-text"].text`. The v0.9 API does not export `createSpace()`, `createSurface()`, `resolveDefaultSpace()`, or `TrayHandle.setTitle()`.
+Visible tray text belongs to `icon.text`, `icon["text-only"]`, or `icon["icon-text"].text`. The current tray-first API does not export `createSpace()`, `createSurface()`, `resolveDefaultSpace()`, or `TrayHandle.setTitle()`.
 
 ## Runtime Ownership
 
@@ -73,9 +98,10 @@ The `opentray/node` subpath exposes binding-resolution, visible host-loop, and b
 
 ## Examples
 
-Run a protocol-only example that creates a tray, dispatches an extension command, and prints each client frame:
+Run the quickstart example and the protocol-only example:
 
 ```bash
+pnpm --filter opentray example:first-app
 pnpm --filter opentray example:basic
 ```
 
@@ -102,4 +128,4 @@ pnpm --filter opentray example:mediaQuery
 pnpm --filter opentray example:debug-runtime-lynx -- --bundle packages/cli/assets/lynx-review/main.lynx.bundle
 ```
 
-The example matrix stages the generated Node runtime artifact before `visible-binding`, skips unsupported or missing native extension carrier artifacts with an explicit reason, and labels contributor-only extension rows as `extension-debug-runtime` coverage. The visible-binding example exercises the default package runtime on macOS and Windows. The debug-runtime examples exercise the contributor-only source-tree transport for extension and panel iteration. The public API they demonstrate is tray-first: application code creates trays directly and treats background/service lifecycle as application-owned.
+The example matrix stages the generated Node runtime artifact before `first-app` and `visible-binding`, skips unsupported or missing native extension carrier artifacts with an explicit reason, and labels contributor-only extension rows as `extension-debug-runtime` coverage. The first-app and visible-binding examples exercise the default package runtime on macOS and Windows. The debug-runtime examples exercise the contributor-only source-tree transport for extension and panel iteration. The public API they demonstrate is tray-first: application code creates trays directly and treats background/service lifecycle as application-owned.

package/dist/node.d.mts

@@ -1,4 +1,5 @@
-import { a as ResolveRuntimeBindingOptions, c as resolveInstalledRuntimeBindingPath, i as OpenTrayVisibleRuntimeHostOptions, l as resolveRuntimeNativeTarget, m as OpenTrayConnection, n as OpenTrayRuntimeBinding, o as RuntimeNativeTarget, r as OpenTrayRuntimeBindingInfo, s as loadOpenTrayRuntimeBinding, t as MissingPlatformRuntimeBindingError } from "./native-runtime-Cn8BaffH.mjs";
+import { a as ResolveRuntimeBindingOptions, c as resolveInstalledRuntimeBindingPath, d as EventfulTrayHandle, i as OpenTrayVisibleRuntimeHostOptions, l as resolveRuntimeNativeTarget, m as OpenTrayConnection, n as OpenTrayRuntimeBinding, o as RuntimeNativeTarget, r as OpenTrayRuntimeBindingInfo, s as loadOpenTrayRuntimeBinding, t as MissingPlatformRuntimeBindingError } from "./native-runtime-Cn8BaffH.mjs";
+import { TrayOptions } from "@opentray/spec";
 
 //#region src/runtime-binding-transport.d.ts
 type RuntimeBindingTransportKind = "visible" | "headless";
@@ -21,8 +22,10 @@ declare const createRuntimeBindingTransport: ({
   kind
 }?: CreateRuntimeBindingTransportOptions) => Promise<OpenTrayConnection>;
 //#endregion
-//#region src/node.d.ts
+//#region src/node-host.d.ts
+/** Options for resolving the native binding and running the visible host loop. */
 interface RunVisibleRuntimeHostOptions extends ResolveRuntimeBindingOptions, OpenTrayVisibleRuntimeHostOptions {}
+/** Run the visible native host loop on the caller-owned Node main thread. */
 declare const runVisibleRuntimeHost: ({
   platform,
   arch,
@@ -31,5 +34,37 @@ declare const runVisibleRuntimeHost: ({
   ...hostOptions
 }?: RunVisibleRuntimeHostOptions) => Promise<void>;
 //#endregion
-export { type CreateRuntimeBindingTransportOptions, MissingPlatformRuntimeBindingError, type OpenTrayRuntimeBinding, type OpenTrayRuntimeBindingInfo, type OpenTrayVisibleRuntimeHostOptions, type ResolveRuntimeBindingOptions, RunVisibleRuntimeHostOptions, type RuntimeNativeTarget, createRuntimeBindingTransport, loadOpenTrayRuntimeBinding, resolveInstalledRuntimeBindingPath, resolveRuntimeNativeTarget, runVisibleRuntimeHost };
+//#region src/node-app.d.ts
+interface RunTrayAppOptions {
+  /** Runtime package version used for host state partitioning and diagnostics. */
+  readonly packageVersion?: string;
+  /** Client version reported to the runtime host handshake. */
+  readonly clientVersion?: string;
+  /** Protocol version reported to the runtime host handshake. */
+  readonly protocolVersion?: number;
+  /** App identity for diagnostics and runtime isolation. */
+  readonly appId?: string;
+  /** Human-readable app identity for diagnostics. */
+  readonly appName?: string;
+  /** Optional finite runtime window for examples and smoke tests. */
+  readonly autoExitAfterMs?: number;
+  /** Delay before the worker callback runs, giving the visible host time to boot. */
+  readonly startupDelayMs?: number;
+}
+interface TrayAppContext {
+  /** Create a tray in the app worker while the helper owns the visible host loop. */
+  createTray(options: TrayOptions): Promise<EventfulTrayHandle>;
+}
+/**
+ * First-app entrypoint executed inside the app worker.
+ *
+ * Keep the callback self-contained. Imports needed by the callback should be
+ * dynamic imports inside the callback because the helper runs it in a worker.
+ */
+type TrayAppMain = (context: TrayAppContext) => void | Promise<void>;
+/** Run a self-contained tray app without exposing host-thread choreography. */
+declare const runTrayApp: (main: TrayAppMain, options?: RunTrayAppOptions) => Promise<void>;
+declare const createTrayAppWorkerSource: () => string;
+//#endregion
+export { type CreateRuntimeBindingTransportOptions, MissingPlatformRuntimeBindingError, type OpenTrayRuntimeBinding, type OpenTrayRuntimeBindingInfo, type OpenTrayVisibleRuntimeHostOptions, type ResolveRuntimeBindingOptions, type RunTrayAppOptions, type RunVisibleRuntimeHostOptions, type RuntimeNativeTarget, type TrayAppContext, type TrayAppMain, createRuntimeBindingTransport, createTrayAppWorkerSource, loadOpenTrayRuntimeBinding, resolveInstalledRuntimeBindingPath, resolveRuntimeNativeTarget, runTrayApp, runVisibleRuntimeHost };
 //# sourceMappingURL=node.d.mts.map

package/dist/node.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"node.d.mts","names":[],"sources":["../src/runtime-binding-transport.ts","../src/node.ts"],"mappings":";;;KAgBY,2BAAA;AAAA,UAEK,oCAAA;EAAA,SACN,IAAA,GAAO,2BAAA;EAAA,SACP,OAAA,GAAU,sBAAsB;EAAA,SAChC,cAAA;EAAA,SACA,aAAA;EAAA,SACA,eAAA;EAAA,SACA,KAAA;EAAA,SACA,OAAA;AAAA;AAAA,cAGE,6BAAA;EAAuC,OAAA;EAAA,cAAA;EAAA,aAAA;EAAA,eAAA;EAAA,KAAA;EAAA,OAAA;EAAA;AAAA,IAQjD,oCAAA,KAA4C,OAAA,CAAQ,kBAAA;;;UC9BtC,4BAAA,SACP,4BAAA,EACN,iCAAiC;AAAA,cAExB,qBAAA;EAA+B,QAAA;EAAA,IAAA;EAAA,kBAAA;EAAA,YAAA;EAAA,GAAA;AAAA,IAMzC,4BAAA,KAAoC,OAAA"}
+{"version":3,"file":"node.d.mts","names":[],"sources":["../src/runtime-binding-transport.ts","../src/node-host.ts","../src/node-app.ts"],"mappings":";;;;KAgBY,2BAAA;AAAA,UAEK,oCAAA;EAAA,SACN,IAAA,GAAO,2BAAA;EAAA,SACP,OAAA,GAAU,sBAAsB;EAAA,SAChC,cAAA;EAAA,SACA,aAAA;EAAA,SACA,eAAA;EAAA,SACA,KAAA;EAAA,SACA,OAAA;AAAA;AAAA,cAGE,6BAAA;EAAuC,OAAA;EAAA,cAAA;EAAA,aAAA;EAAA,eAAA;EAAA,KAAA;EAAA,OAAA;EAAA;AAAA,IAQjD,oCAAA,KAA4C,OAAA,CAAQ,kBAAA;;;;UC7BtC,4BAAA,SACP,4BAAA,EACN,iCAAiC;ADOrC;AAAA,cCJa,qBAAA;EAA+B,QAAA;EAAA,IAAA;EAAA,kBAAA;EAAA,YAAA;EAAA,GAAA;AAAA,IAMzC,4BAAA,KAAoC,OAAA;;;UCZtB,iBAAA;;WAEN,cAAA;EFQ4B;EAAA,SEN5B,aAAA;EFM4B;EAAA,SEJ5B,eAAA;EFMM;EAAA,SEJN,KAAA;;WAEA,OAAA;EFGA;EAAA,SEDA,eAAA;EFEA;EAAA,SEAA,cAAA;AAAA;AAAA,UAGM,cAAA;EFAN;EEET,UAAA,CAAW,OAAA,EAAS,WAAA,GAAc,OAAA,CAAQ,kBAAA;AAAA;;AFA1B;AAGlB;;;;KEMY,WAAA,IAAe,OAAA,EAAS,cAAA,YAA0B,OAAO;;cAgBxD,UAAA,GACX,IAAA,EAAM,WAAA,EACN,OAAA,GAAS,iBAAA,KACR,OAAA;AAAA,cA8CU,yBAAA"}

package/dist/node.mjs

@@ -1,5 +1,7 @@
 import { a as resolveRuntimeNativeTarget, i as resolveInstalledRuntimeBindingPath, n as MissingPlatformRuntimeBindingError, r as loadOpenTrayRuntimeBinding, t as createRuntimeBindingTransport } from "./runtime-binding-transport-UPunusBT.mjs";
-//#region src/node.ts
+import { Worker } from "node:worker_threads";
+//#region src/node-host.ts
+/** Run the visible native host loop on the caller-owned Node main thread. */
 const runVisibleRuntimeHost = async ({ platform, arch, resolvePackageJson, nativeLoader, ...hostOptions } = {}) => {
 	const binding = await loadOpenTrayRuntimeBinding({
 		...platform === void 0 ? {} : { platform },
@@ -11,6 +13,104 @@ const runVisibleRuntimeHost = async ({ platform, arch, resolvePackageJson, nativ
 	binding.runVisibleRuntimeHost(hostOptions);
 };
 //#endregion
-export { MissingPlatformRuntimeBindingError, createRuntimeBindingTransport, loadOpenTrayRuntimeBinding, resolveInstalledRuntimeBindingPath, resolveRuntimeNativeTarget, runVisibleRuntimeHost };
+//#region src/node-app.ts
+/** Run a self-contained tray app without exposing host-thread choreography. */
+const runTrayApp = async (main, options = {}) => {
+	if (typeof main !== "function") throw new TypeError("main must be a function");
+	const worker = new Worker(createTrayAppWorkerSource(), {
+		eval: true,
+		workerData: {
+			mainSource: main.toString(),
+			sdkUrl: resolveWorkerSdkUrl(),
+			runtimeOptions: {
+				...options.packageVersion === void 0 ? {} : { packageVersion: options.packageVersion },
+				...options.clientVersion === void 0 ? {} : { clientVersion: options.clientVersion },
+				...options.protocolVersion === void 0 ? {} : { protocolVersion: options.protocolVersion },
+				...options.appId === void 0 ? {} : { appId: options.appId },
+				...options.appName === void 0 ? {} : { appName: options.appName }
+			},
+			startupDelayMs: normalizeDelay(options.startupDelayMs)
+		}
+	});
+	await waitForWorkerOnline(worker);
+	worker.postMessage("start");
+	try {
+		await runVisibleRuntimeHost({
+			...options.packageVersion === void 0 ? {} : { packageVersion: options.packageVersion },
+			...options.appId === void 0 ? {} : { appId: options.appId },
+			...options.appName === void 0 ? {} : { appName: options.appName },
+			...options.autoExitAfterMs === void 0 ? {} : { autoExitAfterMs: options.autoExitAfterMs }
+		});
+	} finally {
+		await worker.terminate();
+	}
+};
+const createTrayAppWorkerSource = () => `
+  const { parentPort, workerData } = require("node:worker_threads");
+
+  const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+  const isStartMessage = (value) => value === "start";
+
+  if (parentPort === null) {
+    throw new Error("OpenTray tray app worker requires a parent port");
+  }
+
+  import(workerData.sdkUrl)
+    .then(({ createTray: rawCreateTray }) => {
+      const createTray = (options) =>
+        rawCreateTray(options, workerData.runtimeOptions);
+      const main = eval("(" + workerData.mainSource + ")");
+
+      parentPort.postMessage("online");
+      parentPort.once("message", async (message) => {
+        if (!isStartMessage(message)) {
+          return;
+        }
+        if (workerData.startupDelayMs > 0) {
+          await delay(workerData.startupDelayMs);
+        }
+        await main({ createTray });
+        parentPort.postMessage("done");
+      });
+    })
+    .catch((error) => {
+      throw error;
+    });
+`;
+const normalizeDelay = (value) => {
+	if (value === void 0) return 250;
+	if (!Number.isFinite(value) || value < 0) throw new Error(`startupDelayMs must be a non-negative number: ${value}`);
+	return value;
+};
+const resolveWorkerSdkUrl = () => import.meta.url.endsWith(".mjs") ? new URL("./sdk.mjs", import.meta.url).href : new URL("./sdk.ts", import.meta.url).href;
+const waitForWorkerOnline = async (worker) => new Promise((resolve, reject) => {
+	const onMessage = (value) => {
+		if (value === "online") {
+			cleanup();
+			resolve();
+			return;
+		}
+	};
+	const onError = (error) => {
+		cleanup();
+		reject(error);
+	};
+	const onExit = (code) => {
+		if (code !== 0) {
+			cleanup();
+			reject(/* @__PURE__ */ new Error(`tray app worker exited with code ${code}`));
+		}
+	};
+	const cleanup = () => {
+		worker.off("message", onMessage);
+		worker.off("error", onError);
+		worker.off("exit", onExit);
+	};
+	worker.on("message", onMessage);
+	worker.on("error", onError);
+	worker.on("exit", onExit);
+});
+//#endregion
+export { MissingPlatformRuntimeBindingError, createRuntimeBindingTransport, createTrayAppWorkerSource, loadOpenTrayRuntimeBinding, resolveInstalledRuntimeBindingPath, resolveRuntimeNativeTarget, runTrayApp, runVisibleRuntimeHost };
 
 //# sourceMappingURL=node.mjs.map

package/dist/node.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"node.mjs","names":[],"sources":["../src/node.ts"],"sourcesContent":["import {\n  loadOpenTrayRuntimeBinding,\n  type OpenTrayVisibleRuntimeHostOptions,\n  type ResolveRuntimeBindingOptions,\n} from \"./native-runtime\";\n\nexport interface RunVisibleRuntimeHostOptions\n  extends ResolveRuntimeBindingOptions,\n    OpenTrayVisibleRuntimeHostOptions {}\n\nexport const runVisibleRuntimeHost = async ({\n  platform,\n  arch,\n  resolvePackageJson,\n  nativeLoader,\n  ...hostOptions\n}: RunVisibleRuntimeHostOptions = {}): Promise<void> => {\n  const binding = await loadOpenTrayRuntimeBinding({\n    ...(platform === undefined ? {} : { platform }),\n    ...(arch === undefined ? {} : { arch }),\n    ...(resolvePackageJson === undefined ? {} : { resolvePackageJson }),\n    ...(nativeLoader === undefined ? {} : { nativeLoader }),\n  });\n  if (binding.runVisibleRuntimeHost === undefined) {\n    throw new Error(\n      \"OpenTray runtime binding does not expose runVisibleRuntimeHost()\"\n    );\n  }\n  binding.runVisibleRuntimeHost(hostOptions);\n};\n\nexport {\n  MissingPlatformRuntimeBindingError,\n  resolveInstalledRuntimeBindingPath,\n  resolveRuntimeNativeTarget,\n  loadOpenTrayRuntimeBinding,\n  type OpenTrayRuntimeBinding,\n  type OpenTrayRuntimeBindingInfo,\n  type OpenTrayVisibleRuntimeHostOptions,\n  type ResolveRuntimeBindingOptions,\n  type RuntimeNativeTarget,\n} from \"./native-runtime\";\nexport {\n  createRuntimeBindingTransport,\n  type CreateRuntimeBindingTransportOptions,\n} from \"./runtime-binding-transport\";\n"],"mappings":";;AAUA,MAAa,wBAAwB,OAAO,EAC1C,UACA,MACA,oBACA,cACA,GAAG,gBAC6B,CAAC,MAAqB;CACtD,MAAM,UAAU,MAAM,2BAA2B;EAC/C,GAAI,aAAa,KAAA,IAAY,CAAC,IAAI,EAAE,SAAS;EAC7C,GAAI,SAAS,KAAA,IAAY,CAAC,IAAI,EAAE,KAAK;EACrC,GAAI,uBAAuB,KAAA,IAAY,CAAC,IAAI,EAAE,mBAAmB;EACjE,GAAI,iBAAiB,KAAA,IAAY,CAAC,IAAI,EAAE,aAAa;CACvD,CAAC;CACD,IAAI,QAAQ,0BAA0B,KAAA,GACpC,MAAM,IAAI,MACR,kEACF;CAEF,QAAQ,sBAAsB,WAAW;AAC3C"}
+{"version":3,"file":"node.mjs","names":[],"sources":["../src/node-host.ts","../src/node-app.ts"],"sourcesContent":["import {\n  loadOpenTrayRuntimeBinding,\n  type OpenTrayVisibleRuntimeHostOptions,\n  type ResolveRuntimeBindingOptions,\n} from \"./native-runtime\";\n\n/** Options for resolving the native binding and running the visible host loop. */\nexport interface RunVisibleRuntimeHostOptions\n  extends ResolveRuntimeBindingOptions,\n    OpenTrayVisibleRuntimeHostOptions {}\n\n/** Run the visible native host loop on the caller-owned Node main thread. */\nexport const runVisibleRuntimeHost = async ({\n  platform,\n  arch,\n  resolvePackageJson,\n  nativeLoader,\n  ...hostOptions\n}: RunVisibleRuntimeHostOptions = {}): Promise<void> => {\n  const binding = await loadOpenTrayRuntimeBinding({\n    ...(platform === undefined ? {} : { platform }),\n    ...(arch === undefined ? {} : { arch }),\n    ...(resolvePackageJson === undefined ? {} : { resolvePackageJson }),\n    ...(nativeLoader === undefined ? {} : { nativeLoader }),\n  });\n  if (binding.runVisibleRuntimeHost === undefined) {\n    throw new Error(\n      \"OpenTray runtime binding does not expose runVisibleRuntimeHost()\"\n    );\n  }\n  binding.runVisibleRuntimeHost(hostOptions);\n};\n\nexport {\n  MissingPlatformRuntimeBindingError,\n  resolveInstalledRuntimeBindingPath,\n  resolveRuntimeNativeTarget,\n  loadOpenTrayRuntimeBinding,\n  type OpenTrayRuntimeBinding,\n  type OpenTrayRuntimeBindingInfo,\n  type OpenTrayVisibleRuntimeHostOptions,\n  type ResolveRuntimeBindingOptions,\n  type RuntimeNativeTarget,\n} from \"./native-runtime\";\nexport {\n  createRuntimeBindingTransport,\n  type CreateRuntimeBindingTransportOptions,\n} from \"./runtime-binding-transport\";\n","import { Worker } from \"node:worker_threads\";\n\nimport type { EventfulTrayHandle } from \"./client\";\nimport type { TrayOptions } from \"@opentray/spec\";\nimport { runVisibleRuntimeHost } from \"./node-host\";\n\nexport interface RunTrayAppOptions {\n  /** Runtime package version used for host state partitioning and diagnostics. */\n  readonly packageVersion?: string;\n  /** Client version reported to the runtime host handshake. */\n  readonly clientVersion?: string;\n  /** Protocol version reported to the runtime host handshake. */\n  readonly protocolVersion?: number;\n  /** App identity for diagnostics and runtime isolation. */\n  readonly appId?: string;\n  /** Human-readable app identity for diagnostics. */\n  readonly appName?: string;\n  /** Optional finite runtime window for examples and smoke tests. */\n  readonly autoExitAfterMs?: number;\n  /** Delay before the worker callback runs, giving the visible host time to boot. */\n  readonly startupDelayMs?: number;\n}\n\nexport interface TrayAppContext {\n  /** Create a tray in the app worker while the helper owns the visible host loop. */\n  createTray(options: TrayOptions): Promise<EventfulTrayHandle>;\n}\n\n/**\n * First-app entrypoint executed inside the app worker.\n *\n * Keep the callback self-contained. Imports needed by the callback should be\n * dynamic imports inside the callback because the helper runs it in a worker.\n */\nexport type TrayAppMain = (context: TrayAppContext) => void | Promise<void>;\n\ninterface RunTrayAppWorkerData {\n  readonly mainSource: string;\n  readonly sdkUrl: string;\n  readonly runtimeOptions: {\n    readonly packageVersion?: string;\n    readonly clientVersion?: string;\n    readonly protocolVersion?: number;\n    readonly appId?: string;\n    readonly appName?: string;\n  };\n  readonly startupDelayMs: number;\n}\n\n/** Run a self-contained tray app without exposing host-thread choreography. */\nexport const runTrayApp = async (\n  main: TrayAppMain,\n  options: RunTrayAppOptions = {}\n): Promise<void> => {\n  if (typeof main !== \"function\") {\n    throw new TypeError(\"main must be a function\");\n  }\n\n  const worker = new Worker(createTrayAppWorkerSource(), {\n    eval: true,\n    workerData: {\n      mainSource: main.toString(),\n      sdkUrl: resolveWorkerSdkUrl(),\n      runtimeOptions: {\n        ...(options.packageVersion === undefined\n          ? {}\n          : { packageVersion: options.packageVersion }),\n        ...(options.clientVersion === undefined\n          ? {}\n          : { clientVersion: options.clientVersion }),\n        ...(options.protocolVersion === undefined\n          ? {}\n          : { protocolVersion: options.protocolVersion }),\n        ...(options.appId === undefined ? {} : { appId: options.appId }),\n        ...(options.appName === undefined ? {} : { appName: options.appName }),\n      },\n      startupDelayMs: normalizeDelay(options.startupDelayMs),\n    } satisfies RunTrayAppWorkerData,\n  });\n\n  await waitForWorkerOnline(worker);\n  worker.postMessage(\"start\");\n\n  try {\n    await runVisibleRuntimeHost({\n      ...(options.packageVersion === undefined\n        ? {}\n        : { packageVersion: options.packageVersion }),\n      ...(options.appId === undefined ? {} : { appId: options.appId }),\n      ...(options.appName === undefined ? {} : { appName: options.appName }),\n      ...(options.autoExitAfterMs === undefined\n        ? {}\n        : { autoExitAfterMs: options.autoExitAfterMs }),\n    });\n  } finally {\n    await worker.terminate();\n  }\n}\n\nexport const createTrayAppWorkerSource = (): string => `\n  const { parentPort, workerData } = require(\"node:worker_threads\");\n\n  const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));\n  const isStartMessage = (value) => value === \"start\";\n\n  if (parentPort === null) {\n    throw new Error(\"OpenTray tray app worker requires a parent port\");\n  }\n\n  import(workerData.sdkUrl)\n    .then(({ createTray: rawCreateTray }) => {\n      const createTray = (options) =>\n        rawCreateTray(options, workerData.runtimeOptions);\n      const main = eval(\"(\" + workerData.mainSource + \")\");\n\n      parentPort.postMessage(\"online\");\n      parentPort.once(\"message\", async (message) => {\n        if (!isStartMessage(message)) {\n          return;\n        }\n        if (workerData.startupDelayMs > 0) {\n          await delay(workerData.startupDelayMs);\n        }\n        await main({ createTray });\n        parentPort.postMessage(\"done\");\n      });\n    })\n    .catch((error) => {\n      throw error;\n    });\n`;\n\nconst normalizeDelay = (value: number | undefined): number => {\n  if (value === undefined) {\n    return 250;\n  }\n  if (!Number.isFinite(value) || value < 0) {\n    throw new Error(`startupDelayMs must be a non-negative number: ${value}`);\n  }\n  return value;\n};\n\nconst resolveWorkerSdkUrl = (): string =>\n  import.meta.url.endsWith(\".mjs\")\n    ? new URL(\"./sdk.mjs\", import.meta.url).href\n    : new URL(\"./sdk.ts\", import.meta.url).href;\n\nconst waitForWorkerOnline = async (worker: Worker): Promise<void> =>\n  new Promise((resolve, reject) => {\n    const onMessage = (value: unknown): void => {\n      if (value === \"online\") {\n        cleanup();\n        resolve();\n        return;\n      }\n    };\n    const onError = (error: Error): void => {\n      cleanup();\n      reject(error);\n    };\n    const onExit = (code: number): void => {\n      if (code !== 0) {\n        cleanup();\n        reject(new Error(`tray app worker exited with code ${code}`));\n      }\n    };\n    const cleanup = (): void => {\n      worker.off(\"message\", onMessage);\n      worker.off(\"error\", onError);\n      worker.off(\"exit\", onExit);\n    };\n\n    worker.on(\"message\", onMessage);\n    worker.on(\"error\", onError);\n    worker.on(\"exit\", onExit);\n  });\n"],"mappings":";;;;AAYA,MAAa,wBAAwB,OAAO,EAC1C,UACA,MACA,oBACA,cACA,GAAG,gBAC6B,CAAC,MAAqB;CACtD,MAAM,UAAU,MAAM,2BAA2B;EAC/C,GAAI,aAAa,KAAA,IAAY,CAAC,IAAI,EAAE,SAAS;EAC7C,GAAI,SAAS,KAAA,IAAY,CAAC,IAAI,EAAE,KAAK;EACrC,GAAI,uBAAuB,KAAA,IAAY,CAAC,IAAI,EAAE,mBAAmB;EACjE,GAAI,iBAAiB,KAAA,IAAY,CAAC,IAAI,EAAE,aAAa;CACvD,CAAC;CACD,IAAI,QAAQ,0BAA0B,KAAA,GACpC,MAAM,IAAI,MACR,kEACF;CAEF,QAAQ,sBAAsB,WAAW;AAC3C;;;;ACmBA,MAAa,aAAa,OACxB,MACA,UAA6B,CAAC,MACZ;CAClB,IAAI,OAAO,SAAS,YAClB,MAAM,IAAI,UAAU,yBAAyB;CAG/C,MAAM,SAAS,IAAI,OAAO,0BAA0B,GAAG;EACrD,MAAM;EACN,YAAY;GACV,YAAY,KAAK,SAAS;GAC1B,QAAQ,oBAAoB;GAC5B,gBAAgB;IACd,GAAI,QAAQ,mBAAmB,KAAA,IAC3B,CAAC,IACD,EAAE,gBAAgB,QAAQ,eAAe;IAC7C,GAAI,QAAQ,kBAAkB,KAAA,IAC1B,CAAC,IACD,EAAE,eAAe,QAAQ,cAAc;IAC3C,GAAI,QAAQ,oBAAoB,KAAA,IAC5B,CAAC,IACD,EAAE,iBAAiB,QAAQ,gBAAgB;IAC/C,GAAI,QAAQ,UAAU,KAAA,IAAY,CAAC,IAAI,EAAE,OAAO,QAAQ,MAAM;IAC9D,GAAI,QAAQ,YAAY,KAAA,IAAY,CAAC,IAAI,EAAE,SAAS,QAAQ,QAAQ;GACtE;GACA,gBAAgB,eAAe,QAAQ,cAAc;EACvD;CACF,CAAC;CAED,MAAM,oBAAoB,MAAM;CAChC,OAAO,YAAY,OAAO;CAE1B,IAAI;EACF,MAAM,sBAAsB;GAC1B,GAAI,QAAQ,mBAAmB,KAAA,IAC3B,CAAC,IACD,EAAE,gBAAgB,QAAQ,eAAe;GAC7C,GAAI,QAAQ,UAAU,KAAA,IAAY,CAAC,IAAI,EAAE,OAAO,QAAQ,MAAM;GAC9D,GAAI,QAAQ,YAAY,KAAA,IAAY,CAAC,IAAI,EAAE,SAAS,QAAQ,QAAQ;GACpE,GAAI,QAAQ,oBAAoB,KAAA,IAC5B,CAAC,IACD,EAAE,iBAAiB,QAAQ,gBAAgB;EACjD,CAAC;CACH,UAAU;EACR,MAAM,OAAO,UAAU;CACzB;AACF;AAEA,MAAa,kCAA0C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCvD,MAAM,kBAAkB,UAAsC;CAC5D,IAAI,UAAU,KAAA,GACZ,OAAO;CAET,IAAI,CAAC,OAAO,SAAS,KAAK,KAAK,QAAQ,GACrC,MAAM,IAAI,MAAM,iDAAiD,OAAO;CAE1E,OAAO;AACT;AAEA,MAAM,4BACJ,OAAO,KAAK,IAAI,SAAS,MAAM,IAC3B,IAAI,IAAI,aAAa,OAAO,KAAK,GAAG,EAAE,OACtC,IAAI,IAAI,YAAY,OAAO,KAAK,GAAG,EAAE;AAE3C,MAAM,sBAAsB,OAAO,WACjC,IAAI,SAAS,SAAS,WAAW;CAC/B,MAAM,aAAa,UAAyB;EAC1C,IAAI,UAAU,UAAU;GACtB,QAAQ;GACR,QAAQ;GACR;EACF;CACF;CACA,MAAM,WAAW,UAAuB;EACtC,QAAQ;EACR,OAAO,KAAK;CACd;CACA,MAAM,UAAU,SAAuB;EACrC,IAAI,SAAS,GAAG;GACd,QAAQ;GACR,uBAAO,IAAI,MAAM,oCAAoC,MAAM,CAAC;EAC9D;CACF;CACA,MAAM,gBAAsB;EAC1B,OAAO,IAAI,WAAW,SAAS;EAC/B,OAAO,IAAI,SAAS,OAAO;EAC3B,OAAO,IAAI,QAAQ,MAAM;CAC3B;CAEA,OAAO,GAAG,WAAW,SAAS;CAC9B,OAAO,GAAG,SAAS,OAAO;CAC1B,OAAO,GAAG,QAAQ,MAAM;AAC1B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opentray",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Developer-facing OpenTray SDK and CLI package.",
   "type": "module",
   "license": "MIT",
@@ -28,7 +28,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@opentray/spec": "0.7.0"
+    "@opentray/spec": "0.10.0"
   },
   "devDependencies": {
     "tsdown": "^0.22.1",
@@ -36,18 +36,19 @@
     "vitest": "^4.1.7"
   },
   "optionalDependencies": {
-    "@opentray/darwin-arm64": "0.9.0",
-    "@opentray/darwin-x64": "0.9.0",
-    "@opentray/linux-arm64": "0.9.0",
-    "@opentray/linux-x64": "0.9.0",
-    "@opentray/windows-arm64": "0.9.0",
-    "@opentray/windows-x64": "0.9.0"
+    "@opentray/darwin-arm64": "0.10.0",
+    "@opentray/darwin-x64": "0.10.0",
+    "@opentray/linux-arm64": "0.10.0",
+    "@opentray/linux-x64": "0.10.0",
+    "@opentray/windows-arm64": "0.10.0",
+    "@opentray/windows-x64": "0.10.0"
   },
   "scripts": {
     "build": "tsdown src/index.ts src/node.ts src/cli.ts --format esm --dts",
     "cli": "bun run src/cli.ts",
     "example:matrix": "bun run examples/example-matrix.ts",
     "example:basic": "bun run examples/basic-tray.ts",
+    "example:first-app": "bun run examples/first-app.ts",
     "example:debug-runtime-lynx": "bun run examples/debug-runtime-lynx.ts",
     "example:debug-runtime-tray": "bun run examples/debug-runtime-tray.ts",
     "example:visible-binding": "node examples/visible-binding-host.mjs",