opentray 0.0.0-alpha-20260605111358

package/README.md

@@ -0,0 +1,161 @@
+# opentray
+
+Developer-facing OpenTray package.
+
+This is the package users install directly:
+
+```bash
+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.
+
+`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:
+
+```ts
+import { createSpace, createTray, resolveDefaultSpace } from "opentray";
+
+const space = await createSpace({ id: "com.example.status", default: true });
+await space.createTray({
+  trayId: "status",
+  title: "Status",
+  icon: { type: "rgba", data: [0, 0, 0, 0], width: 1, height: 1 },
+});
+
+const defaultSpace = await resolveDefaultSpace();
+await createTray({
+  trayId: "secondary",
+  title: "Secondary",
+  icon: { type: "rgba", data: [0, 0, 0, 0], width: 1, height: 1 },
+}, { 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.
+
+Run the human-visible daemon tray example:
+
+```bash
+pnpm --filter opentray example:daemon-tray
+```
+
+Run the direct webview control demo:
+
+```bash
+pnpm --filter opentray example:webview-control
+```
+
+That demo opens a native WebView window immediately and puts the controls inside the page itself, so you can exercise frameless, transparent, keep-on-top, title, icon, screen, and navigation behavior without going through the tray menu first.
+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.
+
+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: transparent native window background, no root HTML shell styling, and content padding only inside the page.
+It now also pins `style.platform.macos.materialState: "active"` so the tray-launched material surface does not immediately fall back to the inactive grey AppKit appearance.
+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 and Linux are currently `alpha` for WebView runtime behavior, even though their platform packages are published
+- 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. That keeps the example on the real `load-ext` path without requiring a manual staging step for routine source-level testing.
+
+After installing from npm, use the published CLI smoke path instead of workspace scripts:
+
+```bash
+opentray smoke daemon-tray
+opentray smoke daemon-lynx --bundle ./research/lynx/app/dist/main.lynx.bundle
+```
+
+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 smoke path uses the same generic extension loader but launches a real `LynxExplorer.app.zip` runtime sidecar from `@opentray/ext-lynx-darwin-*`. It starts the requested `.lynx.bundle` immediately on run and exposes `Reload Bundle`, `Hide Window`, and `Quit Smoke` through tray-routed events.
+
+First-stage platform packages are published for macOS, Linux, and Windows. macOS is the current human-visual acceptance path. Linux and Windows artifacts are present for package topology validation, but unsupported broker/WebView capability must fail explicitly rather than pretending a visible UI exists. 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
+```
+
+For local native smoke before npm publish, stage the current platform artifacts first:
+
+```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/LynxExplorer.app.zip
+bun run scripts/binaries/stage-local.ts --kind lynx-runtime --source /tmp/LynxExplorer.app.zip
+OPENTRAY_EXAMPLE_WEBVIEW_SMOKE=1 pnpm --filter opentray cli -- smoke daemon-tray
+pnpm --filter opentray cli -- smoke daemon-lynx --bundle ./research/lynx/app/dist/main.lynx.bundle
+```
+
+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:
+
+```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" pnpm --filter opentray cli -- smoke 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>"`.
+
+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
+```
+
+Current native icon support is `rgba`. `encoded` and `file` are typed protocol shapes, but the native `tray-icon` backend reports them as unsupported until decoding and file loading policy are implemented.

package/dist/cli.d.mts

@@ -0,0 +1,23 @@
+import { DaemonHealth } from "@opentray/spec";
+
+//#region src/cli.d.ts
+type CliCommand = {
+  type: "daemon";
+  action: "start" | "stop" | "restart" | "health";
+} | {
+  type: "smoke";
+  name: "daemon-tray";
+} | {
+  type: "smoke";
+  name: "daemon-lynx";
+  bundlePath?: string;
+} | {
+  type: "help";
+};
+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 };
+//# sourceMappingURL=cli.d.mts.map

package/dist/cli.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.mts","names":[],"sources":["../src/cli.ts"],"mappings":";;;KAiBK,UAAA;EACC,IAAA;EAAgB,MAAA;AAAA;EAChB,IAAA;EAAe,IAAA;AAAA;EACf,IAAA;EAAe,IAAA;EAAqB,UAAA;AAAA;EACpC,IAAA;AAAA;AAAA,cAEO,eAAA,GAAmB,IAAA,eAAiB,UAmBhD;AAAA,cAEY,MAAA,GAAgB,IAAA,eAAiB,OAAO;AAAA,cAsFxC,wBAAA,GAA4B,MAAoB,EAAZ,YAAY;AAAA,cAoBhD,eAAA,GAAmB,aAAA,sBAAmC,UAAkB"}