opentray 0.10.2 → 0.11.0

package/README.md

@@ -30,18 +30,33 @@ Use `alpha-A-B` for alpha packages on the same protocol line. Replace `A-B` with
 For the first app, call `createTray()` directly. The quickstart stays in one file and does not ask the user to wire a worker or a host loop first:
 
 ```ts
-import { createTray } from "opentray";
-
-const tray = await createTray({
+import {
+  createTray,
+  type CreateTrayHandle,
+  type CreateTrayOptions,
+  type TrayIcon,
+} from "opentray";
+
+const icon: TrayIcon = { "text-only": "OT" };
+let tray: CreateTrayHandle;
+const options: CreateTrayOptions = {
   id: "com.example.first-app",
-  icon: { "text-only": "OT" },
-  menu: { items: [{ type: "item", id: 1, title: "Quit", primaryEvent: true }] },
-}, {
+  icon,
+  menu: {
+    items: [
+      {
+        title: "Quit",
+        primaryEvent: true,
+        onMenuClick: () => void tray.destroy(),
+      },
+    ],
+  },
+};
+
+tray = await createTray(options, {
   appId: "com.example.first-app",
   appName: "First App",
 });
-
-tray.onMenuClick(({ itemId }) => void (itemId === 1 && tray.destroy()));
 ```
 
 `createTray()` remains the direct tray API when the caller already owns the runtime process shape.
@@ -62,28 +77,55 @@ const tray = await createTray({
     description: "Background service is running",
   },
   menu: {
-    items: [{ type: "item", id: 1, title: "Open", primaryEvent: true }],
+    items: [
+      {
+        title: "Open",
+        primaryEvent: true,
+        onMenuClick: () => {
+          // Open an app-owned window, command, or extension surface.
+        },
+      },
+      "-",
+      ["More", ["Settings", "Quit"]],
+    ],
   },
 });
-
-tray.onMenuClick(({ itemId }) => {
-  if (itemId === 1) {
-    // Open an app-owned window, command, or extension surface.
-  }
-});
 ```
 
-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()`.
+Visible tray text belongs to `icon.text`, `icon["text-only"]`, or `icon["icon-text"].text`. If no visible icon/text survives projection, native tray backends fall back to the runtime `appName`. The current tray-first API does not export `createSpace()`, `createSurface()`, `resolveDefaultSpace()`, or `TrayHandle.setTitle()`.
+
+The package re-exports common application-facing types including `CreateTrayOptions`, `TrayIcon`, `TrayMenu`, `TrayTooltip`, `TrayEvent`, and `TrayBoundsResult`. Use those public names instead of deriving SDK shapes with `typeof` in application code.
+
+Top-level `createTray(...)` and its returned `setMenu(...)` accept app-facing
+menu shorthand. Lower-level `createClient(...)` remains protocol-only for tools
+that need exact wire shapes.
+
+`primaryEvent` is a role on a normal menu item and emits the usual `menuClick`.
+Use `tray.onTrayClick(...)` when you want to listen to raw tray-icon clicks
+without making a menu item the primary route.
 
 ## Runtime Ownership
 
 OpenTray does not ask developers to create a public broker object. The application process or an application-owned background service imports `opentray`, calls `createTray()`, owns event handlers, and releases the tray when that process exits.
 
-Node platform packages carry the host-loadable runtime artifact at `runtime/opentray_runtime.node`. `opentray/node` exposes `runVisibleRuntimeHost()`, `loadOpenTrayRuntimeBinding()`, and `resolveInstalledRuntimeBindingPath()` for Node-specific host-loop ownership, runtime diagnostics, and packaging checks.
+Platform runtime packages carry the packaged runtime executable at `bin/opentray` or `bin/opentray.exe`.
+
+When a local consumer links this workspace, refresh native package artifacts explicitly instead of relying on `pnpm run build` alone:
+
+```bash
+pnpm run npm:cp-bin:runtime
+pnpm run npm:cp-bin:webview
+```
+
+Use `pnpm run npm:cp-bin` to refresh both the packaged runtime executable and the current platform WebView native library. Without `--target`, it compares existing `target/debug` and `target/release` artifacts and copies the newest binary for each kind. Pass `--target debug`, `-t debug`, or `--target release` to build and copy a specific target into the package projection:
 
-By default, `createTray()` routes through the local broker and starts it on first use when needed. `runVisibleRuntimeHost()` remains available from `opentray/node` as an explicit diagnostic path for the visible-binding smoke mode. That diagnostic path still follows the application main-thread law on macOS and the app-owned event-loop law on Windows.
+```bash
+pnpm run npm:cp-bin
+pnpm run npm:cp-bin -- --target debug
+pnpm run npm:cp-bin:webview -- -t debug
+```
 
-For protocol/session diagnostics, `createTray(options, { runtime: "headless-binding" })` routes through the Node binding without visible native state. Source-tree diagnostics may use `{ runtime: "visible-binding" }` or `{ runtime: "local-broker" }`, but those transports are not the default package runtime.
+By default, `createTray()` routes through the local runtime host and starts it on first use when needed. The executable host remains the source of truth for tray lifecycle, session cleanup, and native event routing on supported platforms.
 
 Runtime options may also carry app identity facts:
 
@@ -96,8 +138,6 @@ await createTray(options, {
 
 The runtime host reports those facts as `appId` and `appName` in `runtime-host-health`; tray icon text, menu labels, and tooltip text remain projection data.
 
-The `opentray/node` subpath exposes binding-resolution, visible host-loop, and binding-transport helpers. Source-tree diagnostics may still use the internal local broker transport, but that transport is not exported as a package contract.
-
 ## Examples
 
 Run the quickstart example and the protocol-only example:
@@ -111,17 +151,13 @@ Run the finite source-tree smoke matrix instead of relying on shell expansion fo
 
 ```bash
 pnpm --filter opentray example:matrix
-pnpm --filter opentray example:matrix -- --row visible-binding
+pnpm --filter opentray example:matrix -- --row webview-control
 ```
 
 Run human-visible tray and extension examples from a source checkout:
 
 ```bash
-cargo build -p opentray-runtime-node
-pnpm --filter opentray build
-bun run scripts/binaries/stage-local.ts --kind runtime --source target/debug/libopentray_runtime_node.dylib
-OPENTRAY_EXAMPLE_EXIT_AFTER_MS=1500 pnpm --filter opentray example:visible-binding
-
+cargo build -p opentray-bin
 pnpm --filter opentray example:debug-runtime-tray
 pnpm --filter opentray example:webview-control
 pnpm --filter opentray example:tray-panel
@@ -130,4 +166,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`, warms the broker binary before `first-app`, 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 example exercises the default package runtime. The visible-binding example is an explicit diagnostic row. 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 warms the runtime executable before `first-app`, 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 example exercises the default package runtime. 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/cli.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.mts","names":[],"sources":["../src/cli.ts"],"mappings":";KAMK,UAAA;EACC,IAAA;EAAc,QAAA;AAAA;EACd,IAAA;EAAqB,OAAA;AAAA;AAAA,cAEd,eAAA,GAAmB,IAAA,eAAiB,UAMhD;AAAA,cAEY,MAAA,GAAgB,IAAA,eAAiB,OAAO;AAAA,cAuBxC,eAAA,GACX,aAAA,sBACA,UAAkB"}
+{"version":3,"file":"cli.d.mts","names":[],"sources":["../src/cli.ts"],"mappings":";KAMK,UAAA;EACC,IAAA;EAAc,QAAA;AAAA;EACd,IAAA;EAAqB,OAAA;AAAA;AAAA,cAEd,eAAA,GAAmB,IAAA,eAAiB,UAMhD;AAAA,cAEY,MAAA,GAAgB,IAAA,eAAiB,OAAO;AAAA,cAsBxC,eAAA,GACX,aAAA,sBACA,UAAkB"}

package/dist/cli.mjs

@@ -22,12 +22,11 @@ const runCli = async (argv) => {
 const printHelp = (unsupportedCommand) => {
 	if (unsupportedCommand !== void 0) console.error(`Unsupported opentray command: ${unsupportedCommand}`);
 	console.error([
-		"OpenTray v0.9 does not expose daemon lifecycle commands.",
+		"OpenTray does not expose daemon lifecycle commands.",
 		"Create trays from an app-owned process with:",
 		"",
 		"  import { createTray } from \"opentray\";",
 		"",
-		"Node runtime diagnostics live under the opentray/node binding helpers.",
 		"Source-tree visual diagnostics live in packages/cli/examples."
 	].join("\n"));
 };

package/dist/cli.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"cli.mjs","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { realpathSync } from \"node:fs\";\nimport { fileURLToPath } from \"node:url\";\n\nconst cliModulePath = fileURLToPath(import.meta.url);\n\ntype CliCommand =\n  | { type: \"help\"; exitCode: 0 }\n  | { type: \"unsupported\"; command: string | undefined };\n\nexport const parseCliCommand = (argv: string[]): CliCommand => {\n  const [command] = argv;\n  if (command === undefined || command === \"--help\" || command === \"-h\") {\n    return { type: \"help\", exitCode: 0 };\n  }\n  return { type: \"unsupported\", command };\n};\n\nexport const runCli = async (argv: string[]): Promise<number> => {\n  const command = parseCliCommand(argv);\n  printHelp(command.type === \"unsupported\" ? command.command : undefined);\n  return command.type === \"help\" ? command.exitCode : 1;\n};\n\nconst printHelp = (unsupportedCommand?: string): void => {\n  if (unsupportedCommand !== undefined) {\n    console.error(`Unsupported opentray command: ${unsupportedCommand}`);\n  }\n  console.error(\n    [\n      \"OpenTray v0.9 does not expose daemon lifecycle commands.\",\n      \"Create trays from an app-owned process with:\",\n      \"\",\n      '  import { createTray } from \"opentray\";',\n      \"\",\n      \"Node runtime diagnostics live under the opentray/node binding helpers.\",\n      \"Source-tree visual diagnostics live in packages/cli/examples.\",\n    ].join(\"\\n\")\n  );\n};\n\nexport const isCliEntrypoint = (\n  argvEntryPath: string | undefined,\n  modulePath: string\n): boolean => {\n  if (argvEntryPath === undefined) return false;\n  try {\n    return realpathSync(argvEntryPath) === realpathSync(modulePath);\n  } catch {\n    return argvEntryPath === modulePath;\n  }\n};\n\nif (isCliEntrypoint(process.argv[1], cliModulePath)) {\n  runCli(process.argv.slice(2)).then((code) => {\n    process.exitCode = code;\n  });\n}\n"],"mappings":";;;;AAIA,MAAM,gBAAgB,cAAc,OAAO,KAAK,GAAG;AAMnD,MAAa,mBAAmB,SAA+B;CAC7D,MAAM,CAAC,WAAW;CAClB,IAAI,YAAY,KAAA,KAAa,YAAY,YAAY,YAAY,MAC/D,OAAO;EAAE,MAAM;EAAQ,UAAU;CAAE;CAErC,OAAO;EAAE,MAAM;EAAe;CAAQ;AACxC;AAEA,MAAa,SAAS,OAAO,SAAoC;CAC/D,MAAM,UAAU,gBAAgB,IAAI;CACpC,UAAU,QAAQ,SAAS,gBAAgB,QAAQ,UAAU,KAAA,CAAS;CACtE,OAAO,QAAQ,SAAS,SAAS,QAAQ,WAAW;AACtD;AAEA,MAAM,aAAa,uBAAsC;CACvD,IAAI,uBAAuB,KAAA,GACzB,QAAQ,MAAM,iCAAiC,oBAAoB;CAErE,QAAQ,MACN;EACE;EACA;EACA;EACA;EACA;EACA;EACA;CACF,EAAE,KAAK,IAAI,CACb;AACF;AAEA,MAAa,mBACX,eACA,eACY;CACZ,IAAI,kBAAkB,KAAA,GAAW,OAAO;CACxC,IAAI;EACF,OAAO,aAAa,aAAa,MAAM,aAAa,UAAU;CAChE,QAAQ;EACN,OAAO,kBAAkB;CAC3B;AACF;AAEA,IAAI,gBAAgB,QAAQ,KAAK,IAAI,aAAa,GAChD,OAAO,QAAQ,KAAK,MAAM,CAAC,CAAC,EAAE,MAAM,SAAS;CAC3C,QAAQ,WAAW;AACrB,CAAC"}
+{"version":3,"file":"cli.mjs","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { realpathSync } from \"node:fs\";\nimport { fileURLToPath } from \"node:url\";\n\nconst cliModulePath = fileURLToPath(import.meta.url);\n\ntype CliCommand =\n  | { type: \"help\"; exitCode: 0 }\n  | { type: \"unsupported\"; command: string | undefined };\n\nexport const parseCliCommand = (argv: string[]): CliCommand => {\n  const [command] = argv;\n  if (command === undefined || command === \"--help\" || command === \"-h\") {\n    return { type: \"help\", exitCode: 0 };\n  }\n  return { type: \"unsupported\", command };\n};\n\nexport const runCli = async (argv: string[]): Promise<number> => {\n  const command = parseCliCommand(argv);\n  printHelp(command.type === \"unsupported\" ? command.command : undefined);\n  return command.type === \"help\" ? command.exitCode : 1;\n};\n\nconst printHelp = (unsupportedCommand?: string): void => {\n  if (unsupportedCommand !== undefined) {\n    console.error(`Unsupported opentray command: ${unsupportedCommand}`);\n  }\n  console.error(\n    [\n      \"OpenTray does not expose daemon lifecycle commands.\",\n      \"Create trays from an app-owned process with:\",\n      \"\",\n      '  import { createTray } from \"opentray\";',\n      \"\",\n      \"Source-tree visual diagnostics live in packages/cli/examples.\",\n    ].join(\"\\n\")\n  );\n};\n\nexport const isCliEntrypoint = (\n  argvEntryPath: string | undefined,\n  modulePath: string\n): boolean => {\n  if (argvEntryPath === undefined) return false;\n  try {\n    return realpathSync(argvEntryPath) === realpathSync(modulePath);\n  } catch {\n    return argvEntryPath === modulePath;\n  }\n};\n\nif (isCliEntrypoint(process.argv[1], cliModulePath)) {\n  runCli(process.argv.slice(2)).then((code) => {\n    process.exitCode = code;\n  });\n}\n"],"mappings":";;;;AAIA,MAAM,gBAAgB,cAAc,OAAO,KAAK,GAAG;AAMnD,MAAa,mBAAmB,SAA+B;CAC7D,MAAM,CAAC,WAAW;CAClB,IAAI,YAAY,KAAA,KAAa,YAAY,YAAY,YAAY,MAC/D,OAAO;EAAE,MAAM;EAAQ,UAAU;CAAE;CAErC,OAAO;EAAE,MAAM;EAAe;CAAQ;AACxC;AAEA,MAAa,SAAS,OAAO,SAAoC;CAC/D,MAAM,UAAU,gBAAgB,IAAI;CACpC,UAAU,QAAQ,SAAS,gBAAgB,QAAQ,UAAU,KAAA,CAAS;CACtE,OAAO,QAAQ,SAAS,SAAS,QAAQ,WAAW;AACtD;AAEA,MAAM,aAAa,uBAAsC;CACvD,IAAI,uBAAuB,KAAA,GACzB,QAAQ,MAAM,iCAAiC,oBAAoB;CAErE,QAAQ,MACN;EACE;EACA;EACA;EACA;EACA;EACA;CACF,EAAE,KAAK,IAAI,CACb;AACF;AAEA,MAAa,mBACX,eACA,eACY;CACZ,IAAI,kBAAkB,KAAA,GAAW,OAAO;CACxC,IAAI;EACF,OAAO,aAAa,aAAa,MAAM,aAAa,UAAU;CAChE,QAAQ;EACN,OAAO,kBAAkB;CAC3B;AACF;AAEA,IAAI,gBAAgB,QAAQ,KAAK,IAAI,aAAa,GAChD,OAAO,QAAQ,KAAK,MAAM,CAAC,CAAC,EAAE,MAAM,SAAS;CAC3C,QAAQ,WAAW;AACrB,CAAC"}

package/dist/index.d.mts

@@ -1,10 +1,130 @@
-import { C as TrayHandle, E as createTrayHandle, S as TrayExtensionMountSpec, T as createInitFrame, _ as OpenTrayTransport, b as TrayExtension, d as EventfulTrayHandle, f as ExtensionLoadOptions, g as OpenTrayEventSource, h as OpenTrayEventFrame, m as OpenTrayConnection, n as OpenTrayRuntimeBinding, p as OpenTrayClient, u as CreateClientOptions, v as TrayEventByType, w as createClient, x as TrayExtensionContext, y as TrayEventType } from "./native-runtime-Cn8BaffH.mjs";
-import { BrokerEndpointIdentity, BrokerEndpointIdentityOptions, PROTOCOL_VERSION, TrayOptions, createBrokerEndpointIdentity, formatBrokerEndpointName, formatBrokerStateRoot, formatUnixSocketPath, formatWindowsPipeName, isSupportedProtocolVersion } from "@opentray/spec";
+import { AppId, AppIdentity, AppOptions, AppRef, BrokerEndpointIdentity, BrokerEndpointIdentityOptions, ClientFrame, ClientFrame as ClientFrame$1, ClientRequestFrame, ClientRequestFrame as ClientRequestFrame$1, DarwinIcon, DarwinIconText, ExtensionEnvelope, ExtensionEnvelope as ExtensionEnvelope$1, Icon, Icon as Icon$1, Icon as TrayIcon, IconCandidates, IconImage, IconText, LinuxIcon, Menu, Menu as Menu$1, MenuItem, MenuItemId, MenuItemId as MenuItemId$1, MouseButton, PROTOCOL_VERSION, Rect, RequestId, ServerFrame, ServerFrame as ServerFrame$1, SimpleIcon, Tooltip, Tooltip as Tooltip$1, Tooltip as TrayTooltip, TrayBoundsKind, TrayBoundsResult, TrayBoundsResult as TrayBoundsResult$1, TrayEvent, TrayEvent as TrayEvent$1, TrayId, TrayId as TrayId$1, TrayOptions, TrayOptions as TrayOptions$1, Win32Icon, createBrokerEndpointIdentity, formatBrokerEndpointName, formatBrokerStateRoot, formatUnixSocketPath, formatWindowsPipeName, isSupportedProtocolVersion } from "@opentray/spec";
 
+//#region src/client.d.ts
+interface OpenTrayTransport {
+  request(frame: ClientRequestFrame$1): Promise<ServerFrame$1>;
+}
+type OpenTrayEventFrame = Extract<ServerFrame$1, {
+  type: "event" | "ext-event";
+}>;
+interface OpenTrayEventSource {
+  onEvent(listener: (frame: OpenTrayEventFrame) => void): () => void;
+}
+interface OpenTrayConnection extends OpenTrayTransport, OpenTrayEventSource {}
+interface OpenTrayClient {
+  createTray(options: TrayOptions$1): Promise<TrayHandle>;
+}
+interface OpenTrayEventfulClient extends OpenTrayClient {
+  createTray(options: TrayOptions$1): Promise<EventfulTrayHandle>;
+}
+interface TrayHandle {
+  trayId: TrayId$1;
+  getBounds(): Promise<TrayBoundsResult$1>;
+  setMenu(menu: Menu$1): Promise<void>;
+  setTooltip(tooltip: Tooltip$1): Promise<void>;
+  setIcon(icon: Icon$1): Promise<void>;
+  loadExtension(options: ExtensionLoadOptions): Promise<void>;
+  commandExtension(ext: string, data: unknown): Promise<void>;
+  requestExtension(ext: string, data: unknown): Promise<ExtensionEnvelope$1[]>;
+  extend<TCapability extends object, TOptions = undefined>(extension: TrayExtension<TCapability, TOptions>, options?: TOptions): TrayHandle & TCapability;
+  destroy(): Promise<void>;
+}
+type TrayScopedEvent = Exclude<TrayEvent$1, {
+  type: "ready";
+}>;
+type TrayEventType = TrayScopedEvent["type"];
+type TrayEventByType<TEvent extends TrayEventType> = Extract<TrayScopedEvent, {
+  type: TEvent;
+}>;
+interface EventfulTrayHandle extends TrayHandle {
+  extend<TCapability extends object, TOptions = undefined>(extension: TrayExtension<TCapability, TOptions>, options?: TOptions): EventfulTrayHandle & TCapability;
+  listenExtension<TData = unknown>(ext: string, handler: (event: ExtensionEnvelope$1<TData>) => void): () => void;
+  listen<TEvent extends TrayEventType>(event: TEvent, handler: (event: TrayEventByType<TEvent>) => void): () => void;
+  onMenuClick(handler: (event: TrayEventByType<"menuClick">) => void): () => void;
+  onTrayClick(handler: (event: TrayEventByType<"trayClick">) => void): () => void;
+  onTrayDoubleClick(handler: (event: TrayEventByType<"trayDoubleClick">) => void): () => void;
+}
+interface ExtensionLoadOptions {
+  name: string;
+  path: string;
+  mountId?: string;
+}
+interface TrayExtensionMountSpec {
+  name?: string;
+  path?: string;
+  mountId?: string;
+}
+interface TrayExtensionContext {
+  readonly appId: string;
+  readonly trayId: TrayId$1;
+  readonly name: string;
+  readonly path: string;
+  readonly mountId: string;
+  ensureLoaded(): Promise<void>;
+  command(data: unknown): Promise<void>;
+  request(data: unknown): Promise<ExtensionEnvelope$1[]>;
+}
+interface TrayExtension<TCapability extends object, TOptions = undefined> {
+  readonly name: string;
+  readonly path: string;
+  resolveMount?(options: TOptions | undefined): TrayExtensionMountSpec;
+  extend(tray: TrayHandle, context: TrayExtensionContext, options: TOptions | undefined): TCapability;
+}
+declare const createInitFrame: (clientVersion: string) => ClientFrame$1;
+interface CreateClientOptions {
+  requestIdPrefix?: string;
+}
+declare function createClient(transport: OpenTrayConnection, options?: CreateClientOptions): OpenTrayEventfulClient;
+declare function createClient(transport: OpenTrayTransport, options?: CreateClientOptions): OpenTrayClient;
+declare function createTrayHandle(transport: OpenTrayConnection, appId: string, trayId: TrayId$1, nextRequestId?: () => RequestId): EventfulTrayHandle;
+declare function createTrayHandle(transport: OpenTrayTransport, appId: string, trayId: TrayId$1, nextRequestId?: () => RequestId): TrayHandle;
+//#endregion
+//#region src/menu-input.d.ts
+type CreateTrayMenuClickHandler = (event: TrayEventByType<"menuClick">) => void;
+/** App-facing menu input accepted by top-level createTray and setMenu. */
+type CreateTrayMenu = {
+  items: CreateTrayMenuItem[];
+};
+/** Menu item shorthand normalized to protocol MenuItem before runtime transport. */
+type CreateTrayMenuItem = string | readonly [title: string, items: readonly CreateTrayMenuItem[]] | CreateTrayItem | CreateTrayCheckItem | CreateTrayRadioItem | CreateTraySeparatorItem | CreateTraySubmenuItem;
+type CreateTrayItem = {
+  type?: "item";
+  id?: MenuItemId$1;
+  title: string;
+  primaryEvent?: boolean;
+  enabled?: boolean;
+  shortcut?: string;
+  onMenuClick?: CreateTrayMenuClickHandler;
+};
+type CreateTrayCheckItem = {
+  type: "check";
+  id?: MenuItemId$1;
+  title: string;
+  enabled?: boolean;
+  checked?: boolean;
+  onMenuClick?: CreateTrayMenuClickHandler;
+};
+type CreateTrayRadioItem = {
+  type: "radio";
+  id?: MenuItemId$1;
+  title: string;
+  enabled?: boolean;
+  checked?: boolean;
+  group: number;
+  onMenuClick?: CreateTrayMenuClickHandler;
+};
+type CreateTraySeparatorItem = {
+  type: "separator";
+};
+type CreateTraySubmenuItem = {
+  type: "submenu";
+  title: string;
+  enabled?: boolean;
+  items: readonly CreateTrayMenuItem[];
+};
+//#endregion
 //#region src/sdk.d.ts
-type OpenTrayRuntimeMode = "visible-binding" | "local-broker" | "headless-binding";
 interface OpenTrayRuntimeOptions {
-  runtime?: OpenTrayRuntimeMode;
   endpoint?: string;
   homeDir?: string;
   packageVersion?: string;
@@ -13,9 +133,21 @@ interface OpenTrayRuntimeOptions {
   appId?: string;
   appName?: string;
   autoStart?: boolean;
-  binding?: OpenTrayRuntimeBinding;
 }
-declare const createTray: (options: TrayOptions, runtimeOptions?: OpenTrayRuntimeOptions) => Promise<EventfulTrayHandle>;
+/** App-facing tray options accepted by top-level createTray. */
+interface CreateTrayOptions {
+  id: string;
+  tooltip?: Tooltip$1;
+  icon?: Icon$1;
+  menu?: CreateTrayMenu;
+}
+/** Tray handle returned by top-level createTray with ergonomic setMenu input. */
+interface CreateTrayHandle extends Omit<EventfulTrayHandle, "setMenu" | "extend" | "destroy"> {
+  setMenu(menu: CreateTrayMenu): Promise<void>;
+  extend<TCapability extends object, TOptions = undefined>(extension: TrayExtension<TCapability, TOptions>, options?: TOptions): CreateTrayHandle & TCapability;
+  destroy(): Promise<void>;
+}
+declare const createTray: (options: CreateTrayOptions, runtimeOptions?: OpenTrayRuntimeOptions) => Promise<CreateTrayHandle>;
 //#endregion
-export { type BrokerEndpointIdentity, type BrokerEndpointIdentityOptions, type CreateClientOptions, type EventfulTrayHandle, type ExtensionLoadOptions, type OpenTrayClient, type OpenTrayConnection, type OpenTrayEventFrame, type OpenTrayEventSource, type OpenTrayRuntimeOptions, type OpenTrayTransport, PROTOCOL_VERSION, type TrayEventByType, type TrayEventType, type TrayExtension, type TrayExtensionContext, type TrayExtensionMountSpec, type TrayHandle, createBrokerEndpointIdentity, createClient, createInitFrame, createTray, createTrayHandle, formatBrokerEndpointName, formatBrokerStateRoot, formatUnixSocketPath, formatWindowsPipeName, isSupportedProtocolVersion };
+export { type AppId, type AppIdentity, type AppOptions, type AppRef, type BrokerEndpointIdentity, type BrokerEndpointIdentityOptions, type ClientFrame, type ClientRequestFrame, type CreateClientOptions, type CreateTrayCheckItem, type CreateTrayHandle, type CreateTrayItem, type CreateTrayMenu, type CreateTrayMenu as TrayMenu, type CreateTrayMenuClickHandler, type CreateTrayMenuItem, type CreateTrayOptions, type CreateTrayRadioItem, type CreateTraySeparatorItem, type CreateTraySubmenuItem, type DarwinIcon, type DarwinIconText, type EventfulTrayHandle, type ExtensionEnvelope, type ExtensionLoadOptions, type Icon, type IconCandidates, type IconImage, type IconText, type LinuxIcon, type Menu, type MenuItem, type MenuItemId, type MouseButton, type OpenTrayClient, type OpenTrayConnection, type OpenTrayEventFrame, type OpenTrayEventSource, type OpenTrayRuntimeOptions, type OpenTrayTransport, PROTOCOL_VERSION, type Rect, type ServerFrame, type SimpleIcon, type Tooltip, type TrayBoundsKind, type TrayBoundsResult, type TrayEvent, type TrayEventByType, type TrayEventType, type TrayExtension, type TrayExtensionContext, type TrayExtensionMountSpec, type TrayHandle, type TrayIcon, type TrayId, type TrayOptions, type TrayTooltip, type Win32Icon, createBrokerEndpointIdentity, createClient, createInitFrame, createTray, createTrayHandle, formatBrokerEndpointName, formatBrokerStateRoot, formatUnixSocketPath, formatWindowsPipeName, isSupportedProtocolVersion };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/sdk.ts"],"mappings":";;;;KAOY,mBAAA;AAAA,UAKK,sBAAA;EACf,OAAA,GAAU,mBAAA;EACV,QAAA;EACA,OAAA;EACA,cAAA;EACA,eAAA;EACA,aAAA;EACA,KAAA;EACA,OAAA;EACA,SAAA;EACA,OAAA,GAAU,sBAAsB;AAAA;AAAA,cAGrB,UAAA,GACX,OAAA,EAAS,WAAA,EACT,cAAA,GAAgB,sBAAA,KACf,OAAA,CAAQ,kBAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/client.ts","../src/menu-input.ts","../src/sdk.ts"],"mappings":"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"}

package/dist/index.mjs

@@ -1,4 +1,3 @@
-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";
@@ -106,7 +105,7 @@ function createTrayHandle(transport, appId, trayId, nextRequestId = createReques
 			return expectResponse(response, requestId, "ext-command-result").events;
 		},
 		extend(extension, options) {
-			const context = createTrayExtensionContext(handle, extension, options, nextMountId);
+			const context = createTrayExtensionContext(handle, appId, extension, options, nextMountId);
 			const capability = extension.extend(handle, context, options);
 			return Object.assign({}, handle, capability);
 		},
@@ -156,7 +155,7 @@ const attachEventfulTrayHandle = (handle, source, appId, nextMountId) => {
 			return listen("trayDoubleClick", handler);
 		},
 		extend(extension, options) {
-			const context = createTrayExtensionContext(eventful, extension, options, nextMountId);
+			const context = createTrayExtensionContext(eventful, appId, extension, options, nextMountId);
 			const capability = extension.extend(eventful, context, options);
 			return Object.assign({}, eventful, capability);
 		}
@@ -172,7 +171,7 @@ const resolveDefaultAppRef = async (transport, nextRequestId) => {
 		requestId
 	}), requestId, "default-app").app;
 };
-const createTrayExtensionContext = (tray, extension, options, nextMountId) => {
+const createTrayExtensionContext = (tray, appId, extension, options, nextMountId) => {
 	const mount = extension.resolveMount?.(options) ?? {};
 	const name = mount.name ?? extension.name;
 	const path = mount.path ?? extension.path;
@@ -190,6 +189,8 @@ const createTrayExtensionContext = (tray, extension, options, nextMountId) => {
 		await loadPromise;
 	};
 	return {
+		appId,
+		trayId: tray.trayId,
 		name,
 		path,
 		mountId,
@@ -307,7 +308,7 @@ const resolveBrokerCommand = async (paths, options = {}) => {
 	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);
+	if (workspaceRoot !== void 0) return commandForBinary(await (options.ensureDevBrokerBinary ?? ensureDevBrokerBinary)(workspaceRoot), paths);
 	const platform = options.platform ?? process.platform;
 	const arch = options.arch ?? process.arch;
 	const target = resolveBrokerNativeTarget(platform, arch);
@@ -758,22 +759,176 @@ const resolveCliEntrypoint = () => {
 	return fileURLToPath(new URL(`./${suffix}`, import.meta.url));
 };
 //#endregion
+//#region src/menu-input.ts
+const normalizeCreateTrayMenu = (menu) => {
+	const state = {
+		usedIds: collectExplicitMenuIds(menu.items),
+		nextId: 1,
+		handlers: /* @__PURE__ */ new Map()
+	};
+	return {
+		menu: { items: menu.items.map((item) => normalizeCreateTrayMenuItem(item, state)) },
+		handlers: state.handlers
+	};
+};
+const normalizeCreateTrayMenuItem = (item, state) => {
+	if (typeof item === "string") {
+		if (isSeparatorShortcut(item)) return { type: "separator" };
+		return normalizePlainItem({ title: item }, state);
+	}
+	if (isSubmenuTuple(item)) {
+		const [title, items] = item;
+		return {
+			type: "submenu",
+			title,
+			items: items.map((child) => normalizeCreateTrayMenuItem(child, state))
+		};
+	}
+	switch (item.type) {
+		case void 0:
+		case "item": return normalizePlainItem(item, state);
+		case "check": return normalizeCheckItem(item, state);
+		case "radio": return normalizeRadioItem(item, state);
+		case "separator": return item;
+		case "submenu": return {
+			type: "submenu",
+			title: item.title,
+			...item.enabled === void 0 ? {} : { enabled: item.enabled },
+			items: item.items.map((child) => normalizeCreateTrayMenuItem(child, state))
+		};
+	}
+	throw new Error("unsupported menu item");
+};
+const normalizeClickableItem = (item, state) => {
+	const id = item.id ?? allocateMenuItemId(state);
+	registerClickId(state, id);
+	if (item.onMenuClick !== void 0) {
+		const handlers = state.handlers.get(id) ?? [];
+		handlers.push(item.onMenuClick);
+		state.handlers.set(id, handlers);
+	}
+	return id;
+};
+const normalizePlainItem = (item, state) => {
+	return {
+		type: "item",
+		id: normalizeClickableItem(item, state),
+		title: item.title,
+		...item.primaryEvent === void 0 ? {} : { primaryEvent: item.primaryEvent },
+		...item.enabled === void 0 ? {} : { enabled: item.enabled },
+		...item.shortcut === void 0 ? {} : { shortcut: item.shortcut }
+	};
+};
+const normalizeCheckItem = (item, state) => {
+	return {
+		type: "check",
+		id: normalizeClickableItem(item, state),
+		title: item.title,
+		...item.enabled === void 0 ? {} : { enabled: item.enabled },
+		...item.checked === void 0 ? {} : { checked: item.checked }
+	};
+};
+const normalizeRadioItem = (item, state) => {
+	return {
+		type: "radio",
+		id: normalizeClickableItem(item, state),
+		title: item.title,
+		...item.enabled === void 0 ? {} : { enabled: item.enabled },
+		...item.checked === void 0 ? {} : { checked: item.checked },
+		group: item.group
+	};
+};
+const allocateMenuItemId = (state) => {
+	while (state.usedIds.has(state.nextId)) state.nextId += 1;
+	const id = state.nextId;
+	state.usedIds.add(id);
+	state.nextId += 1;
+	return id;
+};
+const collectExplicitMenuIds = (items) => {
+	const ids = /* @__PURE__ */ new Set();
+	for (const item of items) {
+		if (typeof item === "string") continue;
+		if (isSubmenuTuple(item)) {
+			for (const id of collectExplicitMenuIds(item[1])) ids.add(id);
+			continue;
+		}
+		switch (item.type) {
+			case void 0:
+			case "item":
+			case "check":
+			case "radio":
+				if (item.id !== void 0) ids.add(item.id);
+				break;
+			case "submenu":
+				for (const id of collectExplicitMenuIds(item.items)) ids.add(id);
+				break;
+			case "separator": break;
+		}
+	}
+	return ids;
+};
+const isSeparatorShortcut = (value) => /^-+$/.test(value);
+const isSubmenuTuple = (item) => Array.isArray(item);
+const registerClickId = (state, id) => {
+	const seen = state.seenClickIds ?? /* @__PURE__ */ new Set();
+	if (seen.has(id)) throw new Error(`duplicate menu item id: ${id}`);
+	seen.add(id);
+	state.seenClickIds = seen;
+};
+//#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 connection = await connectLocalBroker(runtimeOptions);
+	const normalized = normalizeCreateTrayOptions(options);
+	const tray = await createClient(connection).createTray(normalized.options);
+	return wrapCreateTrayHandle(tray, { menuUnsubscribe: bindMenuClickHandlers(tray, normalized.menuHandlers) });
+};
+const normalizeCreateTrayOptions = (options) => {
+	const protocolOptions = {
+		id: options.id,
+		...options.tooltip === void 0 ? {} : { tooltip: options.tooltip },
+		...options.icon === void 0 ? {} : { icon: options.icon }
 	};
-	const runtime = runtimeOptions.runtime ?? "local-broker";
-	return createClient(runtime === "local-broker" ? await connectLocalBroker(runtimeOptions) : await createRuntimeBindingTransport({
-		...bindingTransportOptions,
-		kind: runtime === "headless-binding" ? "headless" : "visible"
-	})).createTray(options);
+	if (options.menu === void 0) return {
+		options: protocolOptions,
+		menuHandlers: /* @__PURE__ */ new Map()
+	};
+	const normalized = normalizeCreateTrayMenu(options.menu);
+	return {
+		options: {
+			...protocolOptions,
+			menu: normalized.menu
+		},
+		menuHandlers: normalized.handlers
+	};
+};
+const wrapCreateTrayHandle = (tray, state) => {
+	return {
+		...tray,
+		async setMenu(menu) {
+			const normalized = normalizeCreateTrayMenu(menu);
+			await tray.setMenu(normalized.menu);
+			state.menuUnsubscribe();
+			state.menuUnsubscribe = bindMenuClickHandlers(tray, normalized.handlers);
+		},
+		extend(extension, options) {
+			return wrapCreateTrayHandle(tray.extend(extension, options), state);
+		},
+		async destroy() {
+			state.menuUnsubscribe();
+			state.menuUnsubscribe = noop;
+			await tray.destroy();
+		}
+	};
+};
+const bindMenuClickHandlers = (tray, handlers) => {
+	if (handlers.size === 0) return noop;
+	return tray.onMenuClick((event) => {
+		for (const handler of handlers.get(event.itemId) ?? []) handler(event);
+	});
 };
+const noop = () => {};
 //#endregion
 export { PROTOCOL_VERSION, createBrokerEndpointIdentity, createClient, createInitFrame, createTray, createTrayHandle, formatBrokerEndpointName, formatBrokerStateRoot, formatUnixSocketPath, formatWindowsPipeName, isSupportedProtocolVersion };