@decaf-ts/for-os 0.0.0-stage → 0.2.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. package/LICENSE.md +21 -0
  2. package/README.md +380 -2
  3. package/lib/cjs/errors.cjs +73 -0
  4. package/lib/cjs/errors.cjs.map +1 -0
  5. package/lib/cjs/index.cjs +46 -0
  6. package/lib/cjs/index.cjs.map +1 -0
  7. package/lib/cjs/native/icons.cjs +123 -0
  8. package/lib/cjs/native/icons.cjs.map +1 -0
  9. package/lib/cjs/native/loader.cjs +123 -0
  10. package/lib/cjs/native/loader.cjs.map +1 -0
  11. package/lib/cjs/native/types.cjs +4 -0
  12. package/lib/cjs/native/types.cjs.map +1 -0
  13. package/lib/cjs/notifications/NotificationCenter.cjs +328 -0
  14. package/lib/cjs/notifications/NotificationCenter.cjs.map +1 -0
  15. package/lib/cjs/tray/TrayIcon.cjs +367 -0
  16. package/lib/cjs/tray/TrayIcon.cjs.map +1 -0
  17. package/lib/cjs/tray/assets.cjs +31 -0
  18. package/lib/cjs/tray/assets.cjs.map +1 -0
  19. package/lib/esm/errors.js +65 -0
  20. package/lib/esm/errors.js.map +1 -0
  21. package/lib/esm/index.js +28 -0
  22. package/lib/esm/index.js.map +1 -0
  23. package/lib/esm/native/icons.js +117 -0
  24. package/lib/esm/native/icons.js.map +1 -0
  25. package/lib/esm/native/loader.js +116 -0
  26. package/lib/esm/native/loader.js.map +1 -0
  27. package/lib/esm/native/types.js +8 -0
  28. package/lib/esm/native/types.js.map +1 -0
  29. package/lib/esm/notifications/NotificationCenter.js +322 -0
  30. package/lib/esm/notifications/NotificationCenter.js.map +1 -0
  31. package/lib/esm/tray/TrayIcon.js +362 -0
  32. package/lib/esm/tray/TrayIcon.js.map +1 -0
  33. package/lib/esm/tray/assets.js +26 -0
  34. package/lib/esm/tray/assets.js.map +1 -0
  35. package/lib/types/errors.d.cts +56 -0
  36. package/lib/types/errors.d.mts +56 -0
  37. package/lib/types/index.d.cts +27 -0
  38. package/lib/types/index.d.mts +27 -0
  39. package/lib/types/native/icons.d.cts +71 -0
  40. package/lib/types/native/icons.d.mts +71 -0
  41. package/lib/types/native/loader.d.cts +37 -0
  42. package/lib/types/native/loader.d.mts +37 -0
  43. package/lib/types/native/types.d.cts +104 -0
  44. package/lib/types/native/types.d.mts +104 -0
  45. package/lib/types/notifications/NotificationCenter.d.cts +163 -0
  46. package/lib/types/notifications/NotificationCenter.d.mts +163 -0
  47. package/lib/types/tray/TrayIcon.d.cts +174 -0
  48. package/lib/types/tray/TrayIcon.d.mts +174 -0
  49. package/lib/types/tray/assets.d.cts +25 -0
  50. package/lib/types/tray/assets.d.mts +25 -0
  51. package/native/tray-icon-node/Cargo.lock +1511 -0
  52. package/native/tray-icon-node/Cargo.toml +45 -0
  53. package/native/tray-icon-node/Cross.toml +10 -0
  54. package/native/tray-icon-node/LICENSE +21 -0
  55. package/native/tray-icon-node/UPSTREAM-README.md +281 -0
  56. package/native/tray-icon-node/UPSTREAM.md +213 -0
  57. package/native/tray-icon-node/build-manifest.json +16 -0
  58. package/native/tray-icon-node/build.rs +5 -0
  59. package/native/tray-icon-node/index.d.ts +368 -0
  60. package/native/tray-icon-node/index.js +609 -0
  61. package/native/tray-icon-node/package.json +55 -0
  62. package/native/tray-icon-node/rustfmt.toml +31 -0
  63. package/native/tray-icon-node/source-manifest.json +30 -0
  64. package/native/tray-icon-node/src/common.rs +101 -0
  65. package/native/tray-icon-node/src/icon.rs +255 -0
  66. package/native/tray-icon-node/src/lib.rs +449 -0
  67. package/native/tray-icon-node/src/menu.rs +849 -0
  68. package/native/tray-icon-node/src/tray.rs +251 -0
  69. package/native/tray-icon-node/tray-icon-node.linux-x64-gnu.node +0 -0
  70. package/package.json +131 -4
  71. package/scripts/for-os-build.mjs +60 -0
  72. package/scripts/for-os-init.mjs +327 -0
  73. package/scripts/for-os-install.mjs +47 -0
  74. package/scripts/for-os-integration.mjs +137 -0
  75. package/scripts/for-os-integrity.mjs +51 -0
  76. package/scripts/for-os-package.mjs +49 -0
  77. package/scripts/lib/native.mjs +591 -0
@@ -0,0 +1,45 @@
1
+ [package]
2
+ name = "tray-icon-node"
3
+ version = "0.1.2"
4
+ edition = "2021"
5
+
6
+ [lib]
7
+ crate-type = ["cdylib"]
8
+ name = "tray_icon_node"
9
+
10
+ [package.metadata.napi]
11
+ targets = [
12
+ "x86_64-pc-windows-msvc",
13
+ "i686-pc-windows-msvc",
14
+ "x86_64-apple-darwin",
15
+ "aarch64-apple-darwin",
16
+ "x86_64-unknown-linux-gnu",
17
+ "aarch64-unknown-linux-gnu",
18
+ ]
19
+
20
+ [dependencies]
21
+ napi = { version = "3.8.2", features = ["napi9", "async"] }
22
+ napi-derive = "3.5.1"
23
+ tray-icon = { version = "0.21.3" }
24
+ image = { version = "0.25", default-features = false, features = ["png", "jpeg"] }
25
+
26
+ [target.'cfg(target_os = "linux")'.dependencies]
27
+ gtk = "0.18"
28
+
29
+ [target.'cfg(target_os = "windows")'.dependencies]
30
+ windows-sys = { version = "0.52", features = [
31
+ "Win32_UI_WindowsAndMessaging",
32
+ "Win32_Foundation",
33
+ "Win32_System_Com",
34
+ "Win32_Graphics_Gdi"
35
+ ] }
36
+
37
+ [build-dependencies]
38
+ napi-build = "2"
39
+
40
+ [profile.release]
41
+ lto = true
42
+ codegen-units = 1
43
+ panic = "abort"
44
+ strip = true
45
+ opt-level = "z"
@@ -0,0 +1,10 @@
1
+ [target.aarch64-unknown-linux-gnu]
2
+ pre-build = [
3
+ "dpkg --add-architecture arm64",
4
+ "sed -i 's/deb http/deb [arch=amd64] http/g' /etc/apt/sources.list",
5
+ "echo \"deb [arch=arm64] http://ports.ubuntu.com/ubuntu-ports focal main restricted universe multiverse\" >> /etc/apt/sources.list",
6
+ "echo \"deb [arch=arm64] http://ports.ubuntu.com/ubuntu-ports focal-updates main restricted universe multiverse\" >> /etc/apt/sources.list",
7
+ "apt-get update",
8
+ "apt-get install --assume-yes qemu-user-static",
9
+ "apt-get install --assume-yes libgtk-3-dev:arm64 libayatana-appindicator3-dev:arm64 libxdo-dev:arm64"
10
+ ]
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 nglmercer
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,281 @@
1
+ # tray-icon-node
2
+
3
+ A cross-platform system tray icon library for Node.js with native Rust bindings.
4
+
5
+ ## Features
6
+
7
+ - **System Tray Icon** - Create and manage system tray icons on Windows, macOS, and Linux
8
+ - **Context Menus** - Build rich context menus with items, checkboxes, submenus, and separators
9
+ - **Icon Support** - Load icons from file paths or create from RGBA buffers
10
+ - **Event Handling** - Handle tray click events and menu interactions
11
+ - **Cross-platform** - Works on Windows, macOS, and Linux (GTK-based)
12
+ - **Native Performance** - Rust-based native modules using NAPI-RS
13
+ - **TypeScript** - Full TypeScript support with type definitions
14
+
15
+ ## Prerequisites
16
+
17
+ - Node.js >= 18.0.0
18
+ - Bun >= 1.0.0 (for development)
19
+ - Rust toolchain (stable)
20
+ - Linux: GTK development libraries (`libgtk-3-dev` on Debian/Ubuntu)
21
+
22
+ ## Installation
23
+
24
+ ```bash
25
+ bun install tray-icon-node
26
+ ```
27
+
28
+ Or with npm:
29
+ ```bash
30
+ npm install tray-icon-node
31
+ ```
32
+
33
+ ## Quick Start
34
+
35
+ ```typescript
36
+ import {
37
+ TrayIconBuilder,
38
+ Menu,
39
+ MenuItemBuilder,
40
+ Icon,
41
+ initialize,
42
+ update,
43
+ pollTrayEvents,
44
+ pollMenuEvents
45
+ } from 'tray-icon-node';
46
+
47
+ // Initialize platform-specific requirements
48
+ initialize();
49
+
50
+ // Create a menu
51
+ const menu = new Menu();
52
+ menu.appendMenuItem(
53
+ new MenuItemBuilder()
54
+ .withText("Hello")
55
+ .withId("hello")
56
+ .build()
57
+ );
58
+
59
+ // Create tray icon
60
+ const tray = new TrayIconBuilder()
61
+ .withIcon(Icon.fromPath("./icon.png"))
62
+ .withTooltip("My App")
63
+ .withMenu(menu)
64
+ .build();
65
+
66
+ // Event loop
67
+ setInterval(() => {
68
+ update();
69
+
70
+ const trayEvent = pollTrayEvents();
71
+ if (trayEvent) {
72
+ console.log('Tray clicked:', trayEvent);
73
+ }
74
+
75
+ const menuEvent = pollMenuEvents();
76
+ if (menuEvent) {
77
+ console.log('Menu clicked:', menuEvent.id);
78
+ }
79
+ }, 16);
80
+ ```
81
+
82
+ ## Building from Source
83
+
84
+ ### Release build
85
+ ```bash
86
+ bun run build
87
+ ```
88
+
89
+ ### Debug build
90
+ ```bash
91
+ bun run build:debug
92
+ ```
93
+
94
+ ## Development
95
+
96
+ Run the example development script:
97
+ ```bash
98
+ bun run dev
99
+ ```
100
+
101
+ ## Testing
102
+
103
+ ```bash
104
+ bun test
105
+ ```
106
+
107
+ ## API Reference
108
+
109
+ ### Classes
110
+
111
+ #### `TrayIconBuilder`
112
+ Builder for creating system tray icons.
113
+
114
+ ```typescript
115
+ const tray = new TrayIconBuilder()
116
+ .withIcon(icon: Icon)
117
+ .withTooltip(tooltip: string)
118
+ .withTitle(title: string)
119
+ .withMenu(menu: Menu)
120
+ .build();
121
+ ```
122
+
123
+ #### `TrayIcon`
124
+ Represents a system tray icon instance.
125
+
126
+ ```typescript
127
+ tray.setIcon(icon?: Icon | null): void
128
+ tray.setTooltip(tooltip?: string | null): void
129
+ tray.setTitle(title?: string | null): void
130
+ tray.setVisible(visible: boolean): void
131
+ ```
132
+
133
+ #### `Menu`
134
+ Context menu for tray icons.
135
+
136
+ ```typescript
137
+ const menu = new Menu();
138
+ menu.appendMenuItem(item: MenuItem, id?: string): void
139
+ menu.appendCheckMenuItem(item: CheckMenuItem, id: string): void
140
+ menu.appendIconMenuItem(item: IconMenuItem, id: string): void
141
+ menu.appendSubmenu(item: Submenu, id?: string): void
142
+ menu.appendPredefinedMenuItem(item: PredefinedMenuItem): void
143
+ menu.isChecked(id: string): boolean
144
+ menu.toggleCheck(id: string): boolean
145
+ menu.setText(id: string, text: string): void
146
+ ```
147
+
148
+ #### `MenuItemBuilder` / `MenuItem`
149
+ Standard menu items.
150
+
151
+ ```typescript
152
+ const item = new MenuItemBuilder()
153
+ .withText(text: string)
154
+ .withEnabled(enabled: boolean)
155
+ .withId(id: string)
156
+ .build();
157
+
158
+ item.setText(text: string): void
159
+ item.setEnabled(enabled: boolean): void
160
+ ```
161
+
162
+ #### `CheckMenuItemBuilder` / `CheckMenuItem`
163
+ Checkbox menu items.
164
+
165
+ ```typescript
166
+ const item = new CheckMenuItemBuilder()
167
+ .withText(text: string)
168
+ .withEnabled(enabled: boolean)
169
+ .withChecked(checked: boolean)
170
+ .withId(id: string)
171
+ .build();
172
+
173
+ item.isChecked(): boolean
174
+ item.setChecked(checked: boolean): void
175
+ ```
176
+
177
+ #### `SubmenuBuilder` / `Submenu`
178
+ Nested submenus.
179
+
180
+ ```typescript
181
+ const submenu = new SubmenuBuilder()
182
+ .withText(text: string)
183
+ .withEnabled(enabled: boolean)
184
+ .build();
185
+
186
+ submenu.appendMenuItem(item: MenuItem, id?: string): void
187
+ submenu.appendSubmenu(item: Submenu, id?: string): void
188
+ submenu.appendCheckMenuItem(item: CheckMenuItem, id: string): void
189
+ submenu.appendIconMenuItem(item: IconMenuItem, id?: string): void
190
+ submenu.appendPredefinedMenuItem(item: PredefinedMenuItem): void
191
+ submenu.isChecked(id: string): boolean
192
+ submenu.toggleCheck(id: string): boolean
193
+ ```
194
+
195
+ #### `Icon`
196
+ Icon creation utility.
197
+
198
+ ```typescript
199
+ const iconFromFile = Icon.fromPath(path: string);
200
+ const iconFromBuffer = Icon.fromRgba(rgba: Buffer, width: number, height: number);
201
+ ```
202
+
203
+ #### `PredefinedMenuItem`
204
+ Built-in menu items like separators.
205
+
206
+ ```typescript
207
+ const separator = PredefinedMenuItem.separator();
208
+ ```
209
+
210
+ ### Functions
211
+
212
+ #### `initialize()`
213
+ Initializes platform-specific requirements (GTK on Linux). Must be called before creating tray icons.
214
+
215
+ #### `update()`
216
+ Processes pending platform events. Should be called regularly in your event loop.
217
+
218
+ #### `pollTrayEvents()`
219
+ Returns pending tray events or `null` if none.
220
+
221
+ ```typescript
222
+ interface TrayIconEvent {
223
+ eventType: string;
224
+ id: string;
225
+ x: number;
226
+ y: number;
227
+ iconRect: Rect;
228
+ button: MouseButton;
229
+ buttonState: MouseButtonState;
230
+ }
231
+ ```
232
+
233
+ #### `pollMenuEvents()`
234
+ Returns pending menu click events or `null` if none.
235
+
236
+ ```typescript
237
+ interface MenuEvent {
238
+ id: string;
239
+ }
240
+ ```
241
+
242
+ ### Enums
243
+
244
+ ```typescript
245
+ enum MouseButton {
246
+ Left = 0,
247
+ Right = 1,
248
+ Middle = 2
249
+ }
250
+
251
+ enum MouseButtonState {
252
+ Up = 0,
253
+ Down = 1
254
+ }
255
+ ```
256
+
257
+ ## Project Structure
258
+
259
+ - `src/` - Rust source code
260
+ - `lib.rs` - Main library entry point
261
+ - `tray.rs` - Tray icon implementation
262
+ - `menu.rs` - Menu system implementation
263
+ - `icon.rs` - Icon handling
264
+ - `common.rs` - Shared types and utilities
265
+ - `examples/` - Usage examples
266
+ - `tests/` - Test suite
267
+
268
+ ## Supported Platforms
269
+
270
+ | Platform | Architecture | Status |
271
+ |----------|-------------|--------|
272
+ | Windows | x86_64 | ✅ Supported |
273
+ | Windows | i686 | ✅ Supported |
274
+ | macOS | x86_64 | ✅ Supported |
275
+ | macOS | aarch64 (Apple Silicon) | ✅ Supported |
276
+ | Linux | x86_64 | ✅ Supported |
277
+ | Linux | aarch64 | ✅ Supported |
278
+
279
+ ## License
280
+
281
+ MIT
@@ -0,0 +1,213 @@
1
+ # Vendored `tray-icon-node` — provenance and build notes
2
+
3
+ This directory is a source copy of [`nglmercer/tray-icon-node`](https://github.com/nglmercer/tray-icon-node),
4
+ vendored so the Rust implementation can be audited in this repository and the
5
+ native addon can be built from that audited source instead of consuming the
6
+ published npm tarball.
7
+
8
+ ## for-os adaptation
9
+
10
+ This copy is maintained by `@decaf-ts/for-os`. The system-tray runtime is
11
+ unchanged from the upstream implementation; the notification bridge was
12
+ located in with-ai at `with-ai/vendor/tray-icon-node/src/lib.rs` (the
13
+ `show_notification`, `show_appointment_notification`, and
14
+ `poll_notification_actions` functions) and is ported here with these additions:
15
+
16
+ - `NotificationAction` and `show_notification_with_actions(title, body,
17
+ actions, timeoutMs)` let JavaScript supply arbitrary notification buttons.
18
+ - `timeout_ms` is accepted by every notification entry point. Linux passes it
19
+ to `notify-send --expire-time`; Windows uses it as the balloon-tip timeout;
20
+ macOS uses the system dismissal policy.
21
+ - Linux notifications that have actions now pass `--wait`, so the activated
22
+ action id is actually captured and returned by
23
+ `poll_notification_actions()`. The with-ai version did not wait and therefore
24
+ could not observe button activations.
25
+ - `show_appointment_notification` normalizes the reserved `default` action to
26
+ `see` while keeping the `accept` and `see` ids.
27
+ - Rust tests cover the notification argument contract (timer, actions, wait)
28
+ in addition to the upstream conversion tests.
29
+
30
+ The TypeScript layer (`src/`) adds runtime icon switching (`TrayIcon.setIcon`
31
+ accepts paths, bytes, base64, and raw RGBA), typed menu callbacks, notification
32
+ timers, and JavaScript action mapping. The vendored package name and NAPI
33
+ surface stay compatible with the upstream loader.
34
+
35
+ ## Upstream pin
36
+
37
+ | Item | Value |
38
+ | --- | --- |
39
+ | Repository | `https://github.com/nglmercer/tray-icon-node` |
40
+ | Commit | `cb91e86184ed8612bcdee904277b4d5e78d966c3` |
41
+ | Commit date | 2026-07-22T10:03:08-05:00 |
42
+ | Commit subject | `Update Cross.toml` |
43
+ | Package version | `0.1.2` |
44
+ | License | MIT (see `LICENSE`) |
45
+
46
+ Copied from the upstream tree at that commit:
47
+
48
+ - `Cargo.toml`, `build.rs`, `rustfmt.toml`, `Cross.toml`
49
+ - `src/common.rs`, `src/icon.rs`, `src/lib.rs`, `src/menu.rs`, `src/tray.rs`
50
+ - `README.md` (preserved as `UPSTREAM-README.md` so the upstream usage/API text
51
+ stays available without making this directory look like the published package README)
52
+
53
+ Generated by upstream's build and published in the npm tarball (the upstream
54
+ git tree does not commit them):
55
+
56
+ - `index.js` (NAPI-RS CommonJS loader)
57
+ - `index.d.ts` (NAPI-RS generated declarations)
58
+
59
+ Both were extracted from the published `tray-icon-node@0.1.2` tarball and are
60
+ pinned byte-for-byte in `source-manifest.json`. The tarball itself is recorded
61
+ here for audit provenance:
62
+
63
+ - Tarball: `tray-icon-node-0.1.2.tgz`
64
+ - Tarball SHA-512: `03468f50a91c2394540dfa3ebdf384e85e088179d0569dc1e49f43bf9ca38562a8669c01cc0b35cbc2ef7a8cb16125b490ff0f8ce7f14072ac5260fe7827bfc5`
65
+ - `index.js` SHA-512: `d1ef7dc115a262266f1c62bd64cbc6239bcbacb53ec8016ffe4540730808cdeadd08543978a6ebd00931ca026ecdf0efb5345e046bd31b81f38f9208d310bc76`
66
+ - `index.d.ts` SHA-512: `1a3dfdc4a6792b6f0a3166ba6dd73133fb7356db5b77b0cab4b560748968121f25c706e4c40291fc921ac507cc297763a24432532beaadc0ff09dfd14a85c36f`
67
+
68
+ No published binary (`.node`) is used. The npm tarball's four prebuilt
69
+ binaries are deliberately not vendored.
70
+
71
+ ## Local deviations from upstream packaging
72
+
73
+ `package.json` differs from the published tarball in exactly these ways:
74
+
75
+ - `"type": "commonjs"` — the NAPI-RS loader in `index.js` is CommonJS. Upstream
76
+ publishes it inside an ESM package, which required a runtime post-install
77
+ patch in the previous dependency-based implementation. Because this copy is
78
+ under our control, the correct module type is declared directly and the patch
79
+ is gone.
80
+ - The unused `bun` peer dependency and `@napi-rs/cli`/`@types/bun`/`typescript`
81
+ dev dependencies are removed. The build uses `cargo` directly (see below) and
82
+ does not install a NAPI CLI from npm.
83
+ - The `build` script points at this repository's
84
+ `scripts/for-os-build.mjs`.
85
+
86
+ The Rust tray runtime and `Cargo.toml` retain the upstream implementation.
87
+ `src/common.rs` adds a `#[cfg(test)]` module that verifies mouse-button/state
88
+ and rectangle conversions. `src/lib.rs` adds the for-os desktop-notification
89
+ bridge: Linux `notify-send`, macOS `osascript`, and a Windows notification-area
90
+ balloon via PowerShell. This bridge adds no Cargo dependency. `Cargo.lock` is
91
+ new: upstream git-ignores it, but this repository commits it so the cargo
92
+ dependency closure is auditable and reproducible.
93
+
94
+ ## Build path: build at install from this source
95
+
96
+ Decision: **build the native addon at install time from this vendored source**.
97
+ No prebuilt binary is downloaded or trusted.
98
+
99
+ - `npm run for-os:init` installs `cactus-needle` and `uiohook-napi`, then runs
100
+ `scripts/for-os-install.mjs`, which verifies this tree against
101
+ `source-manifest.json`, builds `tray-icon-node.<platform>.node` with cargo when
102
+ needed, and materializes a verified copy under `node_modules/tray-icon-node`.
103
+ - `npm run for-os:build` builds explicitly and fails when the toolchain is
104
+ missing.
105
+ - `npm run for-os:install:required` requires the build to succeed and then
106
+ materializes the addon into `node_modules/tray-icon-node`.
107
+ - If the Rust/C toolchain or the platform GUI headers are unavailable,
108
+ `for-os:init` warns and installs the package without a binary; the tray then
109
+ degrades to the existing single-notice no-tray behavior while dictation keeps
110
+ working.
111
+ - `native supply-chain workflow` builds the vendored crate on Linux, macOS, and
112
+ Windows runners to prove the source compiles, and scans `Cargo.lock` for
113
+ known-vulnerable crates.
114
+
115
+ ### Prerequisites for a native build
116
+
117
+ Install Rust stable for the current user with rustup. This installs `rustup`,
118
+ `cargo`, and `rustc`; rustup selects the host target automatically:
119
+
120
+ ```bash
121
+ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
122
+ . "$HOME/.cargo/env"
123
+ rustup toolchain install stable
124
+ rustup default stable
125
+ rustc --version
126
+ cargo --version
127
+ ```
128
+
129
+ Platform build dependencies:
130
+
131
+ - Ubuntu/Debian Linux: `sudo apt update`, then
132
+ `sudo apt install build-essential pkg-config libgtk-3-dev
133
+ libayatana-appindicator3-dev libglib2.0-dev libxdo-dev libx11-dev
134
+ libnotify-bin`. `libnotify-bin` provides `notify-send` for for-os OS
135
+ notifications.
136
+ - macOS: `xcode-select --install` for the Xcode command-line tools, plus the
137
+ Rust stable toolchain above.
138
+ - Windows: Visual Studio Build Tools with the **Desktop development with C++**
139
+ workload, plus Rust stable installed with the MSVC host toolchain.
140
+
141
+ Build and install the compiled addon from this repository root:
142
+
143
+ ```bash
144
+ npm run for-os:install:required
145
+ ```
146
+
147
+ This verifies the vendored source pin, runs `cargo build --release --locked`,
148
+ records a hash and toolchain versions in `build-manifest.json`, and copies the
149
+ verified addon to `node_modules/tray-icon-node`. To compile without
150
+ materializing it, use `npm run for-os:build`.
151
+
152
+ Run the Rust crate test target and the real Rust-to-TypeScript desktop
153
+ integration check:
154
+
155
+ ```bash
156
+ npm run for-os:test:rust
157
+ npm run for-os:integration
158
+ ```
159
+
160
+ The interactive integration check requires an active desktop session with a
161
+ system-tray host. It asks the operator to click **Search now**, **Accept
162
+ appointment**, and **Quit**, then verifies that each native menu event reached
163
+ the TypeScript adapter. The per-action timeout defaults to 90 seconds and can
164
+ be changed with `VOICE_TRAY_TEST_TIMEOUT_MS`. For a non-interactive real
165
+ tray create/update/dispose check, run
166
+ `npm run for-os:integration -- --smoke`; this also sends a test OS
167
+ notification from Rust and requires a graphical
168
+ desktop session.
169
+
170
+ ## Why build at install (and the SAA-1290 disposition)
171
+
172
+ Building from the audited source on each platform removes the need for
173
+ per-platform prebuilt artifacts and therefore folds the previously separate
174
+ "darwin prebuild" follow-up (SAA-1290) into this rework: macOS is built from the
175
+ same vendored source as Linux and Windows, with no extra binary pin to obtain or
176
+ trust. The trade-off is a toolchain requirement on machines that want the tray
177
+ indicator; machines without it keep the graceful no-tray degradation.
178
+
179
+ ## Integrity manifest
180
+
181
+ `source-manifest.json` pins every vendored source/wrapper file by SHA-512 and
182
+ records the upstream pin and the source-tree digest. It is generated by
183
+ `npm run for-os:integrity:record`; the corresponding embedded pins live in
184
+ `scripts/for-os-integrity.mjs`.
185
+
186
+ A successful build writes `build-manifest.json` next to the binary with the
187
+ source-tree digest, target triple, cargo/rustc versions, and the built binary's
188
+ SHA-512. `verifyVendoredTrayIntegrity()` verifies the pinned source tree and then
189
+ requires the binary to match that build manifest before the module is imported.
190
+
191
+ ## Source and dependency audit notes (SAA-1292)
192
+
193
+ Reviewed the vendored Rust/Node source at the pinned commit:
194
+
195
+ - No network access (`reqwest`, sockets, HTTP clients), no subprocess spawning
196
+ (`std::process`, `Command`), no environment-variable reads, and no dynamic
197
+ code loading anywhere in `src/*.rs` or `build.rs`.
198
+ - Filesystem access is limited to `Icon::from_path`, which delegates decoding to
199
+ the `image` crate for the icon path supplied by the caller.
200
+ - `unsafe` appears in exactly two places: the Win32 `PeekMessageW` pump in
201
+ `src/lib.rs` (the documented message-loop handoff) and the `Send`/`Sync`
202
+ impls for `AnyMenuItem` in `src/menu.rs`. Both are confined to the platform
203
+ glue the tray library requires.
204
+ - Accepted residual (SAA-1297 F4, LOW, soundness): the `Send`/`Sync` impls rest
205
+ on a partially argued thread-safety claim about tray-icon/muda handles; this
206
+ integration is single-threaded (channel-polled events) and has no current
207
+ trigger, and the upstream thread-safety question is noted here rather than
208
+ blocking the vendored lane.
209
+ - Direct cargo dependencies: `napi` (resolves to 3.15.0), `napi-derive`
210
+ (3.6.13), `tray-icon` 0.21.3, `image` 0.25.10, Linux-only `gtk` 0.18.2,
211
+ Windows-only `windows-sys` 0.52, and build-dependency `napi-build` 2.6.0.
212
+ `Cargo.lock` pins the full closure (244 packages). `native supply-chain workflow`
213
+ scans that lockfile with osv-scanner every week and on changes.
@@ -0,0 +1,16 @@
1
+ {
2
+ "version": 1,
3
+ "package": "tray-icon-node",
4
+ "packageVersion": "0.1.2",
5
+ "sourceDigest": "c5c3009f9a93c9587bfd275994943dc0a9bb28e9847b0c55d887d52ea4e8a9c5f5e055766a5095888e1abac1993cd64bf9e1ecaef1b0fea29aa021237c5cdbcc",
6
+ "target": "x86_64-unknown-linux-gnu",
7
+ "platform": "linux",
8
+ "arch": "x64",
9
+ "binary": "tray-icon-node.linux-x64-gnu.node",
10
+ "sha512": "333e293b4a624d03ca5b4a3bc19eea5ec437b4ce45c5cf1398a8f9190520017f9d603b24611fe390b6aeee45cbcf0f3bab74bb8944029d458af1f803d6ac3c31",
11
+ "builtAt": "2026-11-16T19:35:34.461Z",
12
+ "toolchain": {
13
+ "cargo": "cargo 1.100.0 (3acc79c0c 2026-11-05)",
14
+ "rustc": "rustc 1.100.0 (0ef1bc386 2026-11-09)"
15
+ }
16
+ }
@@ -0,0 +1,5 @@
1
+ extern crate napi_build;
2
+
3
+ fn main() {
4
+ napi_build::setup();
5
+ }