opentray 0.7.0 → 0.8.1

package/README.md

@@ -2,7 +2,7 @@
 
 Developer-facing OpenTray package.
 
-This is the package users install directly:
+Install it directly in the application or service that owns the tray lifetime:
 
 ```bash
 pnpm add opentray
@@ -10,223 +10,96 @@ pnpm add opentray
 
 ## Role
 
-- Resolve or auto-start the OpenTray broker.
-- Expose `createSpace()`, default space resolution, and `createTray()`.
-- Route extension packages through public OpenTray contracts.
-- Resolve per-platform optional binary packages.
+- Expose `createTray()` as the public creation entrypoint.
+- Bind tray handles to the current runtime host context.
+- Route official extension packages through public OpenTray contracts.
+- Resolve platform runtime artifacts without exposing `Space`, `Surface`, or a public broker object.
 
 `packages/cli` is the only unscoped npm package in this monorepo.
 
-## Example
-
-Run a protocol-only example that creates a space, creates a tray, dispatches an extension command, and prints each client frame:
-
-```bash
-pnpm --filter opentray example:basic
-```
-
-The top-level SDK now exposes the mainline broker-backed path directly:
+## Tray-First API
 
 ```ts
-import { createSpace, createTray, resolveDefaultSpace } from "opentray";
-
-const space = await createSpace({ id: "com.example.status", default: true });
-const tray = await space.createTray({
-  trayId: "status",
-  title: "Status",
-  icon: { type: "file", path: "./assets/tray-icon.png" },
-  menu: { items: [{ type: "item", id: 1, title: "Open", primaryEvent: true }] },
+import { createTray } from "opentray";
+
+const tray = await createTray({
+  id: "com.example.status",
+  icon: {
+    type: "file",
+    path: "./assets/tray-icon.png",
+    text: "Status",
+    "text-only": "Status",
+  },
+  tooltip: {
+    title: "Status",
+    description: "Background service is running",
+  },
+  menu: {
+    items: [{ type: "item", id: 1, title: "Open", primaryEvent: true }],
+  },
 });
 
-await tray.setTitle("Status: ready");
 tray.onMenuClick(({ itemId }) => {
   if (itemId === 1) {
-    // Open a native menu action or a WebView surface.
+    // Open an app-owned window, command, or extension surface.
   }
 });
-
-const defaultSpace = await resolveDefaultSpace();
-await createTray(
-  {
-    trayId: "secondary",
-    title: "Secondary",
-    icon: { type: "file", path: "./assets/tray-icon.png" },
-  },
-  { space: defaultSpace.space }
-);
 ```
 
-`createTray()` resolves the broker default space when no explicit target is provided. If you already know the target, pass `space: defaultSpace.space` in the second argument instead of relying on default-space lookup.
+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()`.
 
-Run the human-visible daemon tray example:
+## Runtime Ownership
 
-```bash
-pnpm --filter opentray example:daemon-tray
-```
+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.
 
-Run the direct webview control demo:
+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.
 
-```bash
-pnpm --filter opentray example:webview-control
-pnpm --filter opentray example:webview-control -- --overlay
-pnpm --filter opentray example:webview-control -- --no-overlay
-```
+By default, `createTray()` routes through the visible Node runtime binding. The host main thread must run `runVisibleRuntimeHost()` while app logic runs in a worker or another app-owned execution source. This is a platform law, not a convenience wrapper: on macOS native tray creation must happen on the application main thread, and all native menu/tray events route back only to the live session that owns the tray.
 
-That demo opens a native WebView window immediately and puts the controls inside the page itself, so you can exercise frameless, background modes, keep-on-top, title, icon, screen, overlay, and navigation behavior without going through the tray menu first. The control demo enables the show-time `windowControlsOverlay` capability by default; use `-- --no-overlay` when you want to test the disabled path.
-Treat `example:webview-control` as the API exercise surface. It is useful for probing capabilities and events, but it is not the canonical recipe for a tray-anchored glass shell.
+For protocol/session diagnostics, `createTray(options, { runtime: "headless-binding" })` routes through the Node binding without visible native state. Source-tree diagnostics may use `{ runtime: "local-broker" }`, but that transport is not the default package runtime.
 
-Application code mounts WebView as a tray capability. The first WebView command loads the native extension automatically; ordinary code does not need to send `load-ext` manually:
+Runtime options may also carry app identity facts:
 
 ```ts
-import { WebviewExt } from "@opentray/ext-webview";
-import { createTray } from "opentray";
-
-const tray = (await createTray({
-  trayId: "status",
-  title: "Status",
-  icon: { type: "file", path: "./tray-icon.png" },
-})).extend(WebviewExt);
-
-const panel = tray.createWebviewWindow({
-  html: "<main>Status</main>",
-  width: 360,
-  height: 240,
+await createTray(options, {
+  appId: "com.example.status",
+  appName: "Status",
 });
-
-await panel.show();
 ```
 
-For tray-anchored or screen-aware surfaces, use `WebviewPlacementKit` from `@opentray/ext-webview` instead of hand-authoring raw broker frames or creating a one-off panel abstraction.
+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.
 
-Run the placement demo when you want to review tray, screen, and edge-aware placement:
-
-```bash
-cargo build -p opentray-bin -p opentray-ext-webview
-pnpm --filter opentray example:placement
-```
+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.
 
-This demo follows the `skills/opentray` placement law: extension-owned WebView mounting, continuous `WebviewPlacementKit.watch()`, `applyOnce()`, tray/screen/edge anchors, and a page-owned frameless drag region.
+## Examples
 
-Run the media query demo when you want to review responsive native window style and constraints:
+Run a protocol-only example that creates a tray, dispatches an extension command, and prints each client frame:
 
 ```bash
-cargo build -p opentray-bin -p opentray-ext-webview
-pnpm --filter opentray example:mediaQuery
-```
-
-This demo focuses on `styleKit.apply(...)` and `mediaQueryKit.match(...)`. Keep it separate from placement debugging so size/style callbacks do not obscure placement behavior.
-
-Run the dedicated tray-panel demo:
-
-```bash
-cargo build -p opentray-bin -p opentray-ext-webview
-pnpm --filter opentray example:tray-panel
-```
-
-This demo is the canonical custom TrayPanel case: one `primaryEvent` tray item, backend `tray.getBounds()`, page `navigator.opentray.tray.getBounds()`, screen-aware repositioning, and a frameless glass panel with `keepOnTop`.
-It also follows the native-glass rule strictly: material background through `style.background`, no root HTML shell styling, and content padding only inside the page.
-On macOS it requests `{ kind: "platformMaterial", material: "hudWindow", state: "active" }` so the tray-launched material surface does not immediately fall back to the inactive grey AppKit appearance. On Windows it uses `background: "mica"` and `cornerPreference: "round"` instead of sending macOS-only style.
-For a step-by-step walkthrough of the examples and expected behavior, read [examples/EXAMPLE.md](./examples/EXAMPLE.md).
-
-## Release Channels And Maturity
-
-OpenTray uses release channels and capability maturity together. Do not read a published platform package as proof that every visible runtime path is already stable.
-
-- `latest`: the stable package line
-- `alpha`: the prerelease/testing package line, installed as `npm i opentray@alpha`
-
-Current WebView truth:
-
-- macOS is the current `stable` human-visible acceptance path
-- Windows is the current `stable` WebView2-backed human-visible acceptance path for common bridge/window controls, background material/corner preferences, and native icon projection
-- Linux remains supported by the OpenTray core daemon/packages, but `@opentray/ext-webview` does not publish Linux native WebView packages
-- some requests are `unsupported by design`, such as asking the macOS runtime to apply a Windows-only style family
-- some results are `unavailable by context`, such as tray-bounds projection when the current session has no authoritative tray anchor
-
-When run from the repo worktree, the example automatically discovers `target/debug` or `target/release` `libopentray_ext_webview` and wires it through `OPENTRAY_EXT_PATH` before starting the daemon. The WebView mount still exercises the real generic extension loader, but example users do not author a manual `load-ext` request.
-
-The published CLI is intentionally small and only owns daemon lifecycle and health:
-
-```bash
-opentray daemon health
-opentray daemon start
-opentray daemon stop
-opentray daemon restart
-```
-
-Visual smoke is a real runtime activity, not a daemon CLI subcommand. It may auto-start or reuse the same-version daemon, write runtime coordination files under `$OPENTRAY_HOME/.opentray/<package-version>/runtime` or the user's home directory when `OPENTRAY_HOME` is unset, create a visible tray item, load native extension packages, and open real WebView/Lynx windows. Use the `opentray` skill or source-tree examples to orchestrate those checks, and run `opentray daemon stop` if you want immediate daemon cleanup or if a smoke process was interrupted.
-
-This example starts or reuses the same-version daemon automatically, creates a real tray through the public SDK, and prints broker-routed menu events. Use manual lifecycle commands only for operator/debug control:
-
-```bash
-pnpm --filter opentray cli -- daemon start
-pnpm --filter opentray cli -- daemon stop
-pnpm --filter opentray cli -- daemon restart
-```
-
-The menu intentionally declares only one plain item: `Open WebView` with `primaryEvent: true`. On macOS, that single primary item lets clicking the status item direct-trigger the normal `menuClick` event without opening a menu, so the example can behave like a one-action launcher for a WebView-built surface.
-
-On platforms that expose a direct tray activation gesture, the same item opens the WebView immediately while still remaining a normal native menu item on platforms or gestures that show a menu.
-
-The host side of that example can call `await tray.getBounds()` to read the current tray geometry before opening the window. The rendered page can also opt into `navigator.opentray.tray.getBounds()` when it needs the same tray anchor for layout.
-
-The opened WebView also enables the injected page bridge so the rendered page can call `navigator.window` / `navigator.opentrayWindow` and, for the demo only, opt into `window.close()` / `window.moveTo()` / `window.resizeTo()` overrides. Use the in-page buttons to verify `getCapabilities`, `getStyle`, `setStyle({ frameless })`, move, resize, close, and tray-bounds behavior visually instead of relying only on terminal logs.
-
-The Lynx example path uses the same generic extension loader but launches a real `OpenTrayLynxRuntime.app.zip` sidecar from `@opentray/ext-lynx-darwin-*`. It starts the requested `.lynx.bundle` in a fixed host shell, sets an initial title and icon, applies an explicit startup feature expression, and exposes `Show Window`, `Hide Window`, and `Quit Smoke` through tray-routed events. Inside the Lynx window, use the rendered controls to verify `getCapabilities`, `getStyle`, `getTitle`, `setTitle`, `getIcon`, `setIcon`, `navigator.screen.getScreenDetails()`, `resizeTo`, `moveTo`, frameless toggling, `window.resizeTo()`, `window.getScreenDetails()`, and close behavior visually. On macOS, the runtime Dock icon should no longer appear blank.
-
-For Lynx, `frameless` currently means borderless only. It does not imply a full-window drag region, because that would steal clicks from the page content. When isolating host-feature regressions, `--features "*,!frameless"` is the fastest way to keep the bridge on while removing the borderless shell from the test.
-
-When you need to validate a GitHub-built macOS artifact before publish, use the workspace launcher instead of hand-written `/tmp` scripts:
-
-```bash
-pnpm run smoke:lynx -- --run <github-actions-run-id> --bundle packages/cli/assets/lynx-review/main.lynx.bundle
-pnpm run smoke:lynx -- --run <github-actions-run-id> --bundle packages/cli/assets/lynx-review/main.lynx.bundle --features "nativeWindowApi,bindWindowGlobals,nativeScreenApi,bindScreenGlobals"
-pnpm run smoke:lynx -- --run <github-actions-run-id> --bundle packages/cli/assets/lynx-review/main.lynx.bundle --features "*,!nativeScreenApi"
-```
-
-The workspace review bundle is the full human acceptance surface. The separate `input-probe.lynx.bundle` is only a low-level diagnostic asset for isolating raw click/scroll/input delivery. The empty feature set is the baseline carrier check. Use it to validate the physical window baseline: click, scroll, input, red/yellow/green controls, and resize/move. Only after that baseline is healthy should you validate explicit startup feature sets on top of the same carrier.
-
-First-stage core daemon platform packages are published for macOS, Linux, and Windows. macOS and Windows are stable WebView human-visual acceptance paths for common window and bridge commands plus native material projection. Linux is not an official `@opentray/ext-webview` runtime target. Lynx is intentionally macOS-first for now and should fail honestly on other platforms instead of pretending the runtime exists.
-
-If you are validating the current prerelease branch before stable publication, install from the alpha channel and treat that as alpha evidence rather than stable evidence:
-
-```bash
-npm i opentray@alpha
+pnpm --filter opentray example:basic
 ```
 
-For local native smoke before npm publish, stage the current platform artifacts first and run source-tree examples:
+Run the finite source-tree smoke matrix instead of relying on shell expansion for `example:*`:
 
 ```bash
-cargo build -p opentray-bin -p opentray-ext-webview -p opentray-ext-lynx
-bun run scripts/binaries/stage-local.ts --kind daemon --source target/debug/opentray
-bun run scripts/binaries/stage-local.ts --kind webview --source target/debug/libopentray_ext_webview.dylib
-bun run scripts/binaries/stage-local.ts --kind lynx --source target/debug/libopentray_ext_lynx.dylib
-bash scripts/release/build-lynx-runtime.sh /tmp/OpenTrayLynxRuntime.app.zip
-bun run scripts/binaries/stage-local.ts --kind lynx-runtime --source /tmp/OpenTrayLynxRuntime.app.zip
-OPENTRAY_EXAMPLE_WEBVIEW_SMOKE=1 pnpm --filter opentray example:daemon-tray
-pnpm --filter opentray example:daemon-lynx -- --bundle packages/cli/assets/lynx-review/main.lynx.bundle
+pnpm --filter opentray example:matrix
+pnpm --filter opentray example:matrix -- --row visible-binding
 ```
 
-During source-level daemon work, restart the daemon with the freshly built broker binary before testing tray behavior. Otherwise the CLI may reuse the already staged same-version daemon:
+Run human-visible tray and extension examples from a source checkout:
 
 ```bash
-cargo build -p opentray-bin
-OPENTRAY_BROKER_BIN="$PWD/target/debug/opentray" pnpm --filter opentray cli -- daemon restart
-OPENTRAY_BROKER_BIN="$PWD/target/debug/opentray" OPENTRAY_EXAMPLE_WEBVIEW_SMOKE=1 pnpm --filter opentray example:daemon-tray
-```
-
-The daemon exits automatically after 30 seconds with no connected clients. Set `OPENTRAY_DAEMON_IDLE_TIMEOUT_MS=0` to keep it alive during debugging, or provide another millisecond value for a custom idle release window.
-
-`OPENTRAY_HOME` should point at a home root, not the `.opentray` state directory itself. OpenTray always stores versioned state under `"$OPENTRAY_HOME/.opentray/<package-version>"`.
+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
 
-To confirm the native runtime split on macOS after a release build:
-
-```bash
-cargo build -p opentray-bin -p opentray-ext-webview -p opentray-ext-lynx --release
-wc -c target/release/opentray target/release/libopentray_ext_webview.dylib target/release/libopentray_ext_lynx.dylib
-otool -L target/release/opentray
-otool -L target/release/libopentray_ext_webview.dylib
-otool -L target/release/libopentray_ext_lynx.dylib
+pnpm --filter opentray example:debug-runtime-tray
+pnpm --filter opentray example:webview-control
+pnpm --filter opentray example:tray-panel
+pnpm --filter opentray example:placement
+pnpm --filter opentray example:mediaQuery
+pnpm --filter opentray example:debug-runtime-lynx -- --bundle packages/cli/assets/lynx-review/main.lynx.bundle
 ```
 
-The native `tray-icon` backend now normalizes `encoded` and `file` icon inputs into RGBA before native tray materialization. `rgba` still works when you already have pixel data, but ordinary app code can point at a PNG file instead of hand-building pixels.
+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.

package/dist/cli.d.mts

@@ -1,16 +1,14 @@
-import { DaemonHealth } from "@opentray/spec";
-
 //#region src/cli.d.ts
 type CliCommand = {
-  type: "daemon";
-  action: "start" | "stop" | "restart" | "health";
-} | {
   type: "help";
+  exitCode: 0;
+} | {
+  type: "unsupported";
+  command: string | undefined;
 };
 declare const parseCliCommand: (argv: string[]) => CliCommand;
 declare const runCli: (argv: string[]) => Promise<number>;
-declare const formatDaemonHealthOutput: (health: DaemonHealth) => string;
 declare const isCliEntrypoint: (argvEntryPath: string | undefined, modulePath: string) => boolean;
 //#endregion
-export { formatDaemonHealthOutput, isCliEntrypoint, parseCliCommand, runCli };
+export { isCliEntrypoint, parseCliCommand, runCli };
 //# sourceMappingURL=cli.d.mts.map

package/dist/cli.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.mts","names":[],"sources":["../src/cli.ts"],"mappings":";;;KAqBK,UAAA;EACC,IAAA;EAAgB,MAAA;AAAA;EAChB,IAAA;AAAA;AAAA,cAEO,eAAA,GAAmB,IAAA,eAAiB,UAehD;AAAA,cAEY,MAAA,GAAgB,IAAA,eAAiB,OAAO;AAAA,cAiFxC,wBAAA,GAA4B,MAAoB,EAAZ,YAAY;AAAA,cAoBhD,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,cAuBxC,eAAA,GACX,aAAA,sBACA,UAAkB"}

package/dist/cli.mjs

@@ -1,102 +1,35 @@
 #!/usr/bin/env node
-import { a as inspectDaemon, c as stopDaemon, i as createNodeDaemonDriver, n as resolveDaemonPaths, o as restartDaemon, r as readPackageVersion, s as startDaemon, t as connectLocalBroker } from "./local-broker-DOIkewF4.mjs";
-import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { realpathSync } from "node:fs";
 //#region src/cli.ts
-const packageJsonUrl = new URL("../package.json", import.meta.url);
 const cliModulePath = fileURLToPath(import.meta.url);
 const parseCliCommand = (argv) => {
-	const [group, action] = argv;
-	if (group !== "daemon") return { type: "help" };
-	if (action === "start" || action === "stop" || action === "restart" || action === "health") return {
-		type: "daemon",
-		action
+	const [command] = argv;
+	if (command === void 0 || command === "--help" || command === "-h") return {
+		type: "help",
+		exitCode: 0
+	};
+	return {
+		type: "unsupported",
+		command
 	};
-	return { type: "help" };
 };
 const runCli = async (argv) => {
 	const command = parseCliCommand(argv);
-	const packageVersion = process.env.OPENTRAY_DAEMON_PACKAGE_VERSION ?? await readPackageVersion(packageJsonUrl);
-	const paths = resolveDaemonPaths({
-		homeDir: process.env.OPENTRAY_HOME ?? homedir(),
-		packageVersion
-	});
-	if (command.type === "help") {
-		printHelp();
-		return 1;
-	}
-	const driver = createNodeDaemonDriver(cliModulePath);
-	if (command.action === "start") {
-		const result = await startDaemon({
-			paths,
-			driver
-		});
-		console.log(`opentray daemon ${result.status}: pid=${result.pid} endpoint=${result.paths.endpoint}`);
-		return 0;
-	}
-	if (command.action === "stop") {
-		const result = await stopDaemon({
-			paths,
-			driver
-		});
-		console.log(result.status === "stopped" ? `opentray daemon stopped: pid=${result.pid}` : "opentray daemon not running");
-		return 0;
-	}
-	if (command.action === "restart") {
-		const result = await restartDaemon({
-			paths,
-			driver
-		});
-		console.log(`opentray daemon ${result.status}: pid=${result.pid} endpoint=${result.paths.endpoint}`);
-		return 0;
-	}
-	if (command.action === "health") {
-		if ((await inspectDaemon({
-			paths,
-			driver
-		})).status === "not-running") {
-			console.log("opentray daemon not running");
-			return 0;
-		}
-		const connection = await connectLocalBroker({
-			autoStart: false,
-			endpoint: paths.endpoint,
-			homeDir: paths.homeDir,
-			packageVersion
-		});
-		try {
-			const response = await connection.request({
-				type: "health",
-				requestId: "opentray-daemon-health"
-			});
-			if (response.type !== "daemon-health") throw new Error(`expected daemon-health response, received ${response.type}`);
-			console.log(formatDaemonHealthOutput(response.health));
-		} finally {
-			await connection.close();
-		}
-		return 0;
-	}
-	printHelp();
-	return 1;
+	printHelp(command.type === "unsupported" ? command.command : void 0);
+	return command.type === "help" ? command.exitCode : 1;
 };
-const printHelp = () => {
-	console.error("Usage: opentray daemon <start|stop|restart|health>");
-};
-const formatDaemonHealthOutput = (health) => {
-	const lines = [
-		"opentray daemon running",
-		`pid: ${health.pid}`,
-		`endpoint: ${health.endpoint}`,
-		`packageVersion: ${health.packageVersion}`,
-		`protocolVersion: ${health.protocolVersion}`,
-		`sessions: ${health.sessionCount}`
-	];
-	for (const session of health.sessions) {
-		const internalLease = session.internalLeaseId ?? "(pending)";
-		lines.push(`- sessionId=${session.sessionId} initialized=${session.initialized} internalLeaseId=${internalLease}`);
-	}
-	return lines.join("\n");
+const printHelp = (unsupportedCommand) => {
+	if (unsupportedCommand !== void 0) console.error(`Unsupported opentray command: ${unsupportedCommand}`);
+	console.error([
+		"OpenTray v0.9 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"));
 };
 const isCliEntrypoint = (argvEntryPath, modulePath) => {
 	if (argvEntryPath === void 0) return false;
@@ -110,6 +43,6 @@ if (isCliEntrypoint(process.argv[1], cliModulePath)) runCli(process.argv.slice(2
 	process.exitCode = code;
 });
 //#endregion
-export { formatDaemonHealthOutput, isCliEntrypoint, parseCliCommand, runCli };
+export { isCliEntrypoint, parseCliCommand, runCli };
 
 //# sourceMappingURL=cli.mjs.map

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 { homedir } from \"node:os\";\nimport { fileURLToPath } from \"node:url\";\n\nimport type { DaemonHealth } from \"@opentray/spec\";\n\nimport {\n  createNodeDaemonDriver,\n  inspectDaemon,\n  restartDaemon,\n  startDaemon,\n  stopDaemon,\n} from \"./daemon/lifecycle\";\nimport { readPackageVersion } from \"./daemon/package-version\";\nimport { resolveDaemonPaths } from \"./daemon/paths\";\nimport { connectLocalBroker } from \"./local-broker\";\n\nconst packageJsonUrl = new URL(\"../package.json\", import.meta.url);\nconst cliModulePath = fileURLToPath(import.meta.url);\n\ntype CliCommand =\n  | { type: \"daemon\"; action: \"start\" | \"stop\" | \"restart\" | \"health\" }\n  | { type: \"help\" };\n\nexport const parseCliCommand = (argv: string[]): CliCommand => {\n  const [group, action] = argv;\n  if (group !== \"daemon\") {\n    return { type: \"help\" };\n  }\n  if (\n    action === \"start\" ||\n    action === \"stop\" ||\n    action === \"restart\" ||\n    action === \"health\"\n  ) {\n    return { type: \"daemon\", action };\n  }\n\n  return { type: \"help\" };\n};\n\nexport const runCli = async (argv: string[]): Promise<number> => {\n  const command = parseCliCommand(argv);\n  const packageVersion =\n    process.env.OPENTRAY_DAEMON_PACKAGE_VERSION ??\n    (await readPackageVersion(packageJsonUrl));\n  const paths = resolveDaemonPaths({\n    homeDir: process.env.OPENTRAY_HOME ?? homedir(),\n    packageVersion,\n  });\n\n  if (command.type === \"help\") {\n    printHelp();\n    return 1;\n  }\n\n  const driver = createNodeDaemonDriver(cliModulePath);\n\n  if (command.action === \"start\") {\n    const result = await startDaemon({ paths, driver });\n    console.log(\n      `opentray daemon ${result.status}: pid=${result.pid} endpoint=${result.paths.endpoint}`\n    );\n    return 0;\n  }\n\n  if (command.action === \"stop\") {\n    const result = await stopDaemon({ paths, driver });\n    console.log(\n      result.status === \"stopped\"\n        ? `opentray daemon stopped: pid=${result.pid}`\n        : \"opentray daemon not running\"\n    );\n    return 0;\n  }\n\n  if (command.action === \"restart\") {\n    const result = await restartDaemon({ paths, driver });\n    console.log(\n      `opentray daemon ${result.status}: pid=${result.pid} endpoint=${result.paths.endpoint}`\n    );\n    return 0;\n  }\n\n  if (command.action === \"health\") {\n    const inspected = await inspectDaemon({ paths, driver });\n    if (inspected.status === \"not-running\") {\n      console.log(\"opentray daemon not running\");\n      return 0;\n    }\n\n    const connection = await connectLocalBroker({\n      autoStart: false,\n      endpoint: paths.endpoint,\n      homeDir: paths.homeDir,\n      packageVersion,\n    });\n    try {\n      const response = await connection.request({\n        type: \"health\",\n        requestId: \"opentray-daemon-health\",\n      });\n      if (response.type !== \"daemon-health\") {\n        throw new Error(\n          `expected daemon-health response, received ${response.type}`\n        );\n      }\n      console.log(formatDaemonHealthOutput(response.health));\n    } finally {\n      await connection.close();\n    }\n    return 0;\n  }\n\n  printHelp();\n  return 1;\n};\n\nconst printHelp = (): void => {\n  console.error(\"Usage: opentray daemon <start|stop|restart|health>\");\n};\n\nexport const formatDaemonHealthOutput = (health: DaemonHealth): string => {\n  const lines = [\n    \"opentray daemon running\",\n    `pid: ${health.pid}`,\n    `endpoint: ${health.endpoint}`,\n    `packageVersion: ${health.packageVersion}`,\n    `protocolVersion: ${health.protocolVersion}`,\n    `sessions: ${health.sessionCount}`,\n  ];\n\n  for (const session of health.sessions) {\n    const internalLease = session.internalLeaseId ?? \"(pending)\";\n    lines.push(\n      `- sessionId=${session.sessionId} initialized=${session.initialized} internalLeaseId=${internalLease}`\n    );\n  }\n\n  return lines.join(\"\\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":"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"}
+{"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"}

package/dist/index.d.mts

@@ -1,23 +1,21 @@
-import { C as createTrayHandle, S as createSurfaceHandle, _ as TrayExtensionMountSpec, a as ExtensionLoadOptions, b as createInitFrame, c as OpenTrayEventSource, d as SpaceHandle, f as SurfaceHandle, g as TrayExtensionContext, h as TrayExtension, i as EventfulTrayHandle, l as OpenTrayEventfulClient, m as TrayEventType, n as CreateClientOptions, o as OpenTrayClient, p as TrayEventByType, r as EventfulSpaceHandle, s as OpenTrayConnection, t as BrokerEventFrame, u as OpenTrayTransport, v as TrayHandle, x as createSpaceHandle, y as createClient } from "./client-C27qmRfr.mjs";
-import { BrokerEndpointIdentity, BrokerEndpointIdentityOptions, PROTOCOL_VERSION, SpaceOptions, SpaceRef, TrayOptions, createBrokerEndpointIdentity, formatBrokerEndpointName, formatBrokerStateRoot, formatUnixSocketPath, formatWindowsPipeName, isSupportedProtocolVersion } from "@opentray/spec";
+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";
 
 //#region src/sdk.d.ts
-interface BrokerConnectOptions {
+type OpenTrayRuntimeMode = "visible-binding" | "local-broker" | "headless-binding";
+interface OpenTrayRuntimeOptions {
+  runtime?: OpenTrayRuntimeMode;
   endpoint?: string;
   homeDir?: string;
   packageVersion?: string;
   protocolVersion?: number;
   clientVersion?: string;
+  appId?: string;
+  appName?: string;
   autoStart?: boolean;
+  binding?: OpenTrayRuntimeBinding;
 }
-interface CreateTrayOptions extends BrokerConnectOptions {
-  space?: SpaceRef;
-}
-declare const createSpace: (options: SpaceOptions, brokerOptions?: BrokerConnectOptions) => Promise<EventfulSpaceHandle>;
-/** @deprecated Use `createSpace`. */
-declare const createSurface: (options: SpaceOptions, brokerOptions?: BrokerConnectOptions) => Promise<SurfaceHandle>;
-declare const resolveDefaultSpace: (brokerOptions?: BrokerConnectOptions) => Promise<EventfulSpaceHandle>;
-declare const createTray: (options: TrayOptions, brokerOptions?: CreateTrayOptions) => Promise<EventfulTrayHandle>;
+declare const createTray: (options: TrayOptions, runtimeOptions?: OpenTrayRuntimeOptions) => Promise<EventfulTrayHandle>;
 //#endregion
-export { type BrokerConnectOptions, type BrokerEndpointIdentity, type BrokerEndpointIdentityOptions, type BrokerEventFrame, type CreateClientOptions, type CreateTrayOptions, type EventfulSpaceHandle, type EventfulTrayHandle, type ExtensionLoadOptions, type OpenTrayClient, type OpenTrayConnection, type OpenTrayEventSource, type OpenTrayEventfulClient, type OpenTrayTransport, PROTOCOL_VERSION, type SpaceHandle, type SurfaceHandle, type TrayEventByType, type TrayEventType, type TrayExtension, type TrayExtensionContext, type TrayExtensionMountSpec, type TrayHandle, createBrokerEndpointIdentity, createClient, createInitFrame, createSpace, createSpaceHandle, createSurface, createSurfaceHandle, createTray, createTrayHandle, formatBrokerEndpointName, formatBrokerStateRoot, formatUnixSocketPath, formatWindowsPipeName, isSupportedProtocolVersion, resolveDefaultSpace };
+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 };
 //# 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":";;;;UAWiB,oBAAA;EACf,QAAA;EACA,OAAA;EACA,cAAA;EACA,eAAA;EACA,aAAA;EACA,SAAA;AAAA;AAAA,UAGe,iBAAA,SAA0B,oBAAoB;EAC7D,KAAA,GAAQ,QAAA;AAAA;AAAA,cAGG,WAAA,GACX,OAAA,EAAS,YAAA,EACT,aAAA,GAAe,oBAAA,KACd,OAAA,CAAQ,mBAAA;;cAME,aAAA,GACX,OAAA,EAAS,YAAA,EACT,aAAA,GAAe,oBAAA,KACd,OAAA,CAAQ,aAAA;AAAA,cAEE,mBAAA,GACX,aAAA,GAAe,oBAAA,KACd,OAAA,CAAQ,mBAAA;AAAA,cAKE,UAAA,GACX,OAAA,EAAS,WAAA,EACT,aAAA,GAAe,iBAAA,KACd,OAAA,CAAQ,kBAAA"}
+{"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"}