@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.
- package/LICENSE.md +21 -0
- package/README.md +380 -2
- package/lib/cjs/errors.cjs +73 -0
- package/lib/cjs/errors.cjs.map +1 -0
- package/lib/cjs/index.cjs +46 -0
- package/lib/cjs/index.cjs.map +1 -0
- package/lib/cjs/native/icons.cjs +123 -0
- package/lib/cjs/native/icons.cjs.map +1 -0
- package/lib/cjs/native/loader.cjs +123 -0
- package/lib/cjs/native/loader.cjs.map +1 -0
- package/lib/cjs/native/types.cjs +4 -0
- package/lib/cjs/native/types.cjs.map +1 -0
- package/lib/cjs/notifications/NotificationCenter.cjs +328 -0
- package/lib/cjs/notifications/NotificationCenter.cjs.map +1 -0
- package/lib/cjs/tray/TrayIcon.cjs +367 -0
- package/lib/cjs/tray/TrayIcon.cjs.map +1 -0
- package/lib/cjs/tray/assets.cjs +31 -0
- package/lib/cjs/tray/assets.cjs.map +1 -0
- package/lib/esm/errors.js +65 -0
- package/lib/esm/errors.js.map +1 -0
- package/lib/esm/index.js +28 -0
- package/lib/esm/index.js.map +1 -0
- package/lib/esm/native/icons.js +117 -0
- package/lib/esm/native/icons.js.map +1 -0
- package/lib/esm/native/loader.js +116 -0
- package/lib/esm/native/loader.js.map +1 -0
- package/lib/esm/native/types.js +8 -0
- package/lib/esm/native/types.js.map +1 -0
- package/lib/esm/notifications/NotificationCenter.js +322 -0
- package/lib/esm/notifications/NotificationCenter.js.map +1 -0
- package/lib/esm/tray/TrayIcon.js +362 -0
- package/lib/esm/tray/TrayIcon.js.map +1 -0
- package/lib/esm/tray/assets.js +26 -0
- package/lib/esm/tray/assets.js.map +1 -0
- package/lib/types/errors.d.cts +56 -0
- package/lib/types/errors.d.mts +56 -0
- package/lib/types/index.d.cts +27 -0
- package/lib/types/index.d.mts +27 -0
- package/lib/types/native/icons.d.cts +71 -0
- package/lib/types/native/icons.d.mts +71 -0
- package/lib/types/native/loader.d.cts +37 -0
- package/lib/types/native/loader.d.mts +37 -0
- package/lib/types/native/types.d.cts +104 -0
- package/lib/types/native/types.d.mts +104 -0
- package/lib/types/notifications/NotificationCenter.d.cts +163 -0
- package/lib/types/notifications/NotificationCenter.d.mts +163 -0
- package/lib/types/tray/TrayIcon.d.cts +174 -0
- package/lib/types/tray/TrayIcon.d.mts +174 -0
- package/lib/types/tray/assets.d.cts +25 -0
- package/lib/types/tray/assets.d.mts +25 -0
- package/native/tray-icon-node/Cargo.lock +1511 -0
- package/native/tray-icon-node/Cargo.toml +45 -0
- package/native/tray-icon-node/Cross.toml +10 -0
- package/native/tray-icon-node/LICENSE +21 -0
- package/native/tray-icon-node/UPSTREAM-README.md +281 -0
- package/native/tray-icon-node/UPSTREAM.md +213 -0
- package/native/tray-icon-node/build-manifest.json +16 -0
- package/native/tray-icon-node/build.rs +5 -0
- package/native/tray-icon-node/index.d.ts +368 -0
- package/native/tray-icon-node/index.js +609 -0
- package/native/tray-icon-node/package.json +55 -0
- package/native/tray-icon-node/rustfmt.toml +31 -0
- package/native/tray-icon-node/source-manifest.json +30 -0
- package/native/tray-icon-node/src/common.rs +101 -0
- package/native/tray-icon-node/src/icon.rs +255 -0
- package/native/tray-icon-node/src/lib.rs +449 -0
- package/native/tray-icon-node/src/menu.rs +849 -0
- package/native/tray-icon-node/src/tray.rs +251 -0
- package/native/tray-icon-node/tray-icon-node.linux-x64-gnu.node +0 -0
- package/package.json +131 -4
- package/scripts/for-os-build.mjs +60 -0
- package/scripts/for-os-init.mjs +327 -0
- package/scripts/for-os-install.mjs +47 -0
- package/scripts/for-os-integration.mjs +137 -0
- package/scripts/for-os-integrity.mjs +51 -0
- package/scripts/for-os-package.mjs +49 -0
- 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
|
+
}
|