opentray 0.5.1 → 0.6.0

package/README.md

@@ -34,7 +34,7 @@ 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 },
+  icon: { type: "file", path: "./assets/tray-icon.png" },
 });
 
 const defaultSpace = await resolveDefaultSpace();
@@ -42,7 +42,7 @@ await createTray(
   {
     trayId: "secondary",
     title: "Secondary",
-    icon: { type: "rgba", data: [0, 0, 0, 0], width: 1, height: 1 },
+    icon: { type: "file", path: "./assets/tray-icon.png" },
   },
   { space: defaultSpace.space }
 );
@@ -60,11 +60,34 @@ Run the direct webview control demo:
 
 ```bash
 pnpm --filter opentray example:webview-control
+pnpm --filter opentray example:webview-control -- --overlay
+pnpm --filter opentray example:webview-control -- --no-overlay
 ```
 
-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.
+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.
 
+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:
+
+```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 panel.show();
+```
+
 Run the dedicated tray-panel demo:
 
 ```bash
@@ -73,8 +96,8 @@ 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.
+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
@@ -87,20 +110,23 @@ OpenTray uses release channels and capability maturity together. Do not read a p
 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
+- 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. That keeps the example on the real `load-ext` path without requiring a manual staging step for routine source-level testing.
+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.
 
-After installing from npm, use the published CLI smoke path instead of workspace scripts:
+The published CLI is intentionally small and only owns daemon lifecycle and health:
 
 ```bash
-opentray smoke daemon-tray
-opentray smoke daemon-lynx
+opentray daemon health
+opentray daemon start
+opentray daemon stop
+opentray daemon restart
 ```
 
-`opentray smoke daemon-lynx` now uses the package-owned review bundle by default so a fresh npm install can perform the final visual audit without a workspace checkout. Keep `--bundle <path-to-main.lynx.bundle>` only when you want to override that official audit asset with a custom bundle.
+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:
 
@@ -118,7 +144,7 @@ The host side of that example can call `await tray.getBounds()` to read the curr
 
 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 `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.
+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.
 
@@ -130,9 +156,9 @@ pnpm run smoke:lynx -- --run <github-actions-run-id> --bundle packages/cli/asset
 pnpm run smoke:lynx -- --run <github-actions-run-id> --bundle packages/cli/assets/lynx-review/main.lynx.bundle --features "*,!nativeScreenApi"
 ```
 
-The package-owned 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.
+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 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.
+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:
 
@@ -140,7 +166,7 @@ If you are validating the current prerelease branch before stable publication, i
 npm i opentray@alpha
 ```
 
-For local native smoke before npm publish, stage the current platform artifacts first:
+For local native smoke before npm publish, stage the current platform artifacts first and run source-tree examples:
 
 ```bash
 cargo build -p opentray-bin -p opentray-ext-webview -p opentray-ext-lynx
@@ -149,8 +175,8 @@ bun run scripts/binaries/stage-local.ts --kind webview --source target/debug/lib
 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 cli -- smoke daemon-tray
-pnpm --filter opentray cli -- smoke daemon-lynx
+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
 ```
 
 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:
@@ -158,7 +184,7 @@ During source-level daemon work, restart the daemon with the freshly built broke
 ```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
+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.
@@ -175,4 +201,4 @@ 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.
+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.

package/dist/cli.d.mts

@@ -4,14 +4,6 @@ import { DaemonHealth } from "@opentray/spec";
 type CliCommand = {
   type: "daemon";
   action: "start" | "stop" | "restart" | "health";
-} | {
-  type: "smoke";
-  name: "daemon-tray";
-} | {
-  type: "smoke";
-  name: "daemon-lynx";
-  bundlePath?: string;
-  featureExpression?: string;
 } | {
   type: "help";
 };

package/dist/cli.d.mts.map

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