@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,30 @@
1
+ {
2
+ "package": "tray-icon-node",
3
+ "version": "0.1.2",
4
+ "upstream": {
5
+ "repository": "https://github.com/nglmercer/tray-icon-node",
6
+ "commit": "cb91e86184ed8612bcdee904277b4d5e78d966c3",
7
+ "commitDate": "2026-07-22T10:03:08-05:00",
8
+ "packageTarball": "tray-icon-node-0.1.2.tgz sha512:03468f50a91c2394540dfa3ebdf384e85e088179d0569dc1e49f43bf9ca38562a8669c01cc0b35cbc2ef7a8cb16125b490ff0f8ce7f14072ac5260fe7827bfc5",
9
+ "generatedWrapper": "index.js/index.d.ts extracted from the published npm tarball 0.1.2"
10
+ },
11
+ "sourceDigest": "c1a0039645870517b7c1f7e6dbd93c21cc09d5e51ecefd34b15c18cfe79995bd677d0a991c0d7774873937aa8e279f1a7f2309991bf12730634439bf249bf9f1",
12
+ "files": {
13
+ "Cargo.lock": "cde78970234c6eb9406c792689ba189ed5fcf360264599328cc8e41fc509820ee920781efb68002a6491e1e14fa5358ab670ad16037792a1ab13f69c81edc206",
14
+ "Cargo.toml": "0ccef8719ad603532f722de1abaa0345210394d467ed7536aee48f62696d70f1654024072c6326183c61a3424850cae749707f2a4b97cedff95d22d7b3a41cee",
15
+ "Cross.toml": "b96ca269f19f06b5f20e4941acfed40a8e7a64f6701f6827ec719e2e70aeeba9e0bd28027716f4e174ecf534f6f2706b385e0657f21c73f9c45d8682719e00ef",
16
+ "LICENSE": "028df2dae60485df7aacb44afd6f139f3415468c51abb010033b813293520827ba024bb9acfcf11e4801fc90ab9812d2c0b9504c8e87b604ea942f36f53d5041",
17
+ "UPSTREAM-README.md": "585948668fcbff13edb452c9b2119a5c5778f69608896d7fbba5479e69c1552cd36d9c481f8f33fbd5943be2f9a936e36bc288fd24aeb1486aaa00f7416cb864",
18
+ "UPSTREAM.md": "f81ed193940d184a41dc2d80828885e1debe4813def3b32abe577141f3db0052a0801830cfac90d575ab221753880b32cb6dfdef44837f840fe392ca436054d0",
19
+ "build.rs": "d662aa9aebd0dabe6a1baa03493eb04ecc0f144e863212a3b66a7799591a7e831e84590fad3a14c9fecff46782f537ffeef188ddaa7ff07c81994607864f23ad",
20
+ "index.d.ts": "180b8ef1891f3f9aa82671c9235d4907778b844efa477ea619a6dff6b0fffdcd831e4644739dfcc0054010800693723ea9e7eaddd1de4dff3671c9c82e769ecd",
21
+ "index.js": "d1ef7dc115a262266f1c62bd64cbc6239bcbacb53ec8016ffe4540730808cdeadd08543978a6ebd00931ca026ecdf0efb5345e046bd31b81f38f9208d310bc76",
22
+ "package.json": "dbc5d90e9598aacdb7aaa0a51db5b0e839757b8e77dee42b50265913d66d326df12edb4b053552b14bc606ea0abbf3c9ffd53371f773c6754f0b2252ee9ef09f",
23
+ "rustfmt.toml": "301f9c51348d5e8c003ddb76356b30d84e006afde32c893419571c7399a6ae3ea1d30b7ad742ce82b8b3708001795687432854b24bda2d6f1b7a6b77bcfed268",
24
+ "src/common.rs": "b0b2c190afac55593122994bc9d67c1bb6ccb714e4646eb91b64a2ac4ddb578163bb9a1b533abf2e39173ca8a2e6362448dedd810ca33819605339ed60f2c4b5",
25
+ "src/icon.rs": "84475f78791e41a5c9b81af777d40bdccf63bf4565b7e45cd8271a89c8d8a19c6169d72d91d16589b4ec67d59d08ec140d8c71b6c9af867e554e8df04082f59e",
26
+ "src/lib.rs": "daebdcfa21e97af2042b84ba326597c0a3f1e302b6536992091012d8597f76febb2a3a779b264006d719957d7f8d811232405fb8815472598a788cbf9890ed0d",
27
+ "src/menu.rs": "32a9f43664514968517bc8e1b56ed63387e0261e7e59f64284bdd94f6901df51328f4299f0e4a9a90be45970758a0bc1460f14707e650cc4a3b691bf40a3c8ca",
28
+ "src/tray.rs": "9ca4161f452671a30ca679fa32576d8f4d1da3f56ac04e6a1589c116df8d9f7f235ace7dc8de03a6c59dbbada955edacf554d8cb5d4c8438aad5e5ec649a8f44"
29
+ }
30
+ }
@@ -0,0 +1,101 @@
1
+ use napi_derive::napi;
2
+
3
+ #[napi(object)]
4
+ #[derive(Debug, Clone, Copy)]
5
+ pub struct Rect {
6
+ pub x: f64,
7
+ pub y: f64,
8
+ pub width: f64,
9
+ pub height: f64,
10
+ }
11
+
12
+ impl From<tray_icon::Rect> for Rect {
13
+ fn from(rect: tray_icon::Rect) -> Self {
14
+ Self {
15
+ x: rect.position.x,
16
+ y: rect.position.y,
17
+ width: f64::from(rect.size.width),
18
+ height: f64::from(rect.size.height),
19
+ }
20
+ }
21
+ }
22
+
23
+ #[napi]
24
+ pub enum MouseButton {
25
+ Left,
26
+ Right,
27
+ Middle,
28
+ }
29
+
30
+ impl From<tray_icon::MouseButton> for MouseButton {
31
+ fn from(button: tray_icon::MouseButton) -> Self {
32
+ match button {
33
+ tray_icon::MouseButton::Left => Self::Left,
34
+ tray_icon::MouseButton::Right => Self::Right,
35
+ tray_icon::MouseButton::Middle => Self::Middle,
36
+ }
37
+ }
38
+ }
39
+
40
+ #[napi]
41
+ pub enum MouseButtonState {
42
+ Up,
43
+ Down,
44
+ }
45
+
46
+ impl From<tray_icon::MouseButtonState> for MouseButtonState {
47
+ fn from(state: tray_icon::MouseButtonState) -> Self {
48
+ match state {
49
+ tray_icon::MouseButtonState::Up => Self::Up,
50
+ tray_icon::MouseButtonState::Down => Self::Down,
51
+ }
52
+ }
53
+ }
54
+
55
+ #[cfg(test)]
56
+ mod tests {
57
+ use super::{MouseButton, MouseButtonState, Rect};
58
+
59
+ #[test]
60
+ fn converts_every_mouse_button() {
61
+ assert!(matches!(
62
+ MouseButton::from(tray_icon::MouseButton::Left),
63
+ MouseButton::Left
64
+ ));
65
+ assert!(matches!(
66
+ MouseButton::from(tray_icon::MouseButton::Right),
67
+ MouseButton::Right
68
+ ));
69
+ assert!(matches!(
70
+ MouseButton::from(tray_icon::MouseButton::Middle),
71
+ MouseButton::Middle
72
+ ));
73
+ }
74
+
75
+ #[test]
76
+ fn converts_mouse_button_states() {
77
+ assert!(matches!(
78
+ MouseButtonState::from(tray_icon::MouseButtonState::Up),
79
+ MouseButtonState::Up
80
+ ));
81
+ assert!(matches!(
82
+ MouseButtonState::from(tray_icon::MouseButtonState::Down),
83
+ MouseButtonState::Down
84
+ ));
85
+ }
86
+
87
+ #[test]
88
+ fn converts_physical_rect_fields() {
89
+ let mut source = tray_icon::Rect::default();
90
+ source.position.x = 12.5;
91
+ source.position.y = -4.0;
92
+ source.size.width = 120;
93
+ source.size.height = 48;
94
+ let rect = Rect::from(source);
95
+
96
+ assert_eq!(rect.x, 12.5);
97
+ assert_eq!(rect.y, -4.0);
98
+ assert_eq!(rect.width, 120.0);
99
+ assert_eq!(rect.height, 48.0);
100
+ }
101
+ }
@@ -0,0 +1,255 @@
1
+ use std::io::Cursor;
2
+
3
+ use napi::bindgen_prelude::*;
4
+ use napi_derive::napi;
5
+
6
+ const MAX_ICON_DIMENSION: u32 = 4096;
7
+
8
+ fn validate_dimensions(label: &str, width: u32, height: u32) -> Result<()> {
9
+ if width == 0 || height == 0 {
10
+ return Err(Error::from_reason(format!(
11
+ "{label} has invalid dimensions {width}x{height}"
12
+ )));
13
+ }
14
+ if width > MAX_ICON_DIMENSION || height > MAX_ICON_DIMENSION {
15
+ return Err(Error::from_reason(format!(
16
+ "{label} is {width}x{height}px; tray icons are limited to {MAX_ICON_DIMENSION}px per side"
17
+ )));
18
+ }
19
+ Ok(())
20
+ }
21
+
22
+ fn icon_limits() -> image::Limits {
23
+ let mut limits = image::Limits::default();
24
+ limits.max_image_width = Some(MAX_ICON_DIMENSION);
25
+ limits.max_image_height = Some(MAX_ICON_DIMENSION);
26
+ limits
27
+ }
28
+
29
+ fn decode_icon_rgba(path: &str) -> Result<image::RgbaImage> {
30
+ let bytes = std::fs::read(path)
31
+ .map_err(|e| Error::from_reason(format!("Failed to read image {path}: {e}")))?;
32
+ let probe = image::ImageReader::new(Cursor::new(&bytes))
33
+ .with_guessed_format()
34
+ .map_err(|e| Error::from_reason(format!("Failed to inspect image {path}: {e}")))?;
35
+ let format = probe.format().ok_or_else(|| {
36
+ Error::from_reason(format!(
37
+ "Unsupported or unrecognized image format for {path}"
38
+ ))
39
+ })?;
40
+ let (width, height) = probe
41
+ .into_dimensions()
42
+ .map_err(|e| Error::from_reason(format!("Failed to read dimensions of {path}: {e}")))?;
43
+ validate_dimensions(&format!("Image {path}"), width, height)?;
44
+
45
+ let mut decoder = image::ImageReader::with_format(Cursor::new(&bytes), format);
46
+ decoder.limits(icon_limits());
47
+ decoder
48
+ .decode()
49
+ .map(|image| image.to_rgba8())
50
+ .map_err(|e| Error::from_reason(format!("Failed to decode image {path}: {e}")))
51
+ }
52
+
53
+ #[napi]
54
+ #[derive(Clone)]
55
+ pub struct Icon {
56
+ pub(crate) inner: tray_icon::Icon,
57
+ pub(crate) rgba: Vec<u8>,
58
+ pub(crate) width: u32,
59
+ pub(crate) height: u32,
60
+ }
61
+
62
+ #[napi]
63
+ impl Icon {
64
+ /// Creates an icon from an image file at the given path.
65
+ ///
66
+ /// # Errors
67
+ ///
68
+ /// Returns an error if the file cannot be opened or decoded as an image.
69
+ #[napi(factory)]
70
+ pub fn from_path(path: String) -> Result<Self> {
71
+ let img = decode_icon_rgba(&path)?;
72
+ let (width, height) = img.dimensions();
73
+ let rgba = img.into_raw();
74
+ let icon = tray_icon::Icon::from_rgba(rgba.clone(), width, height)
75
+ .map_err(|e| Error::from_reason(format!("Failed to create icon: {e}")))?;
76
+ Ok(Self {
77
+ inner: icon,
78
+ rgba,
79
+ width,
80
+ height,
81
+ })
82
+ }
83
+
84
+ /// Creates an icon from raw RGBA pixel data.
85
+ ///
86
+ /// # Errors
87
+ ///
88
+ /// Returns an error if the RGBA data length does not match `width * height * 4`
89
+ /// or the OS fails to create the icon.
90
+ #[napi(factory)]
91
+ pub fn from_rgba(rgba: Buffer, width: u32, height: u32) -> Result<Self> {
92
+ validate_dimensions("RGBA icon", width, height)?;
93
+ let rgba_vec = rgba.to_vec();
94
+ let expected_len = width as usize * height as usize * 4;
95
+ if rgba_vec.len() != expected_len {
96
+ return Err(Error::from_reason(format!(
97
+ "RGBA buffer length {} does not match expected size {} ({}×{}×4)",
98
+ rgba_vec.len(),
99
+ expected_len,
100
+ width,
101
+ height
102
+ )));
103
+ }
104
+ let icon = tray_icon::Icon::from_rgba(rgba_vec.clone(), width, height)
105
+ .map_err(|e| Error::from_reason(format!("Failed to create icon from RGBA: {e}")))?;
106
+ Ok(Self {
107
+ inner: icon,
108
+ rgba: rgba_vec,
109
+ width,
110
+ height,
111
+ })
112
+ }
113
+ }
114
+
115
+ #[cfg(test)]
116
+ mod dimension_cap_tests {
117
+ use std::path::PathBuf;
118
+ use std::sync::atomic::{AtomicUsize, Ordering};
119
+
120
+ use napi::bindgen_prelude::Buffer;
121
+
122
+ use super::{decode_icon_rgba, icon_limits, validate_dimensions, Icon};
123
+
124
+ const DOCUMENTED_MAX: u32 = 4096;
125
+ const ONE_OVER: u32 = 4097;
126
+
127
+ struct TempPng(PathBuf);
128
+
129
+ impl TempPng {
130
+ fn from_image(image: &image::RgbaImage) -> Self {
131
+ static COUNTER: AtomicUsize = AtomicUsize::new(0);
132
+ let path = std::env::temp_dir().join(format!(
133
+ "tray-icon-node-dimension-cap-{}-{}.png",
134
+ std::process::id(),
135
+ COUNTER.fetch_add(1, Ordering::Relaxed)
136
+ ));
137
+ image
138
+ .save_with_format(&path, image::ImageFormat::Png)
139
+ .expect("test fixture must encode as PNG");
140
+ Self(path)
141
+ }
142
+
143
+ fn as_str(&self) -> &str {
144
+ self.0.to_str().expect("temporary path must be valid UTF-8")
145
+ }
146
+ }
147
+
148
+ impl Drop for TempPng {
149
+ fn drop(&mut self) {
150
+ let _ = std::fs::remove_file(&self.0);
151
+ }
152
+ }
153
+
154
+ #[test]
155
+ fn accepts_dimensions_at_or_below_the_cap() {
156
+ validate_dimensions("Icon", 16, 16).expect("16x16 is a valid tray icon size");
157
+ validate_dimensions("Icon", DOCUMENTED_MAX, DOCUMENTED_MAX)
158
+ .expect("4096x4096 is the maximum accepted tray icon size");
159
+ validate_dimensions("Icon", DOCUMENTED_MAX, 1).expect("a wide icon at the cap is accepted");
160
+ validate_dimensions("Icon", 1, DOCUMENTED_MAX).expect("a tall icon at the cap is accepted");
161
+ }
162
+
163
+ #[test]
164
+ fn decoder_limits_match_the_documented_cap() {
165
+ let limits = icon_limits();
166
+ assert_eq!(limits.max_image_width, Some(DOCUMENTED_MAX));
167
+ assert_eq!(limits.max_image_height, Some(DOCUMENTED_MAX));
168
+ }
169
+
170
+ #[test]
171
+ fn rejects_width_one_pixel_over_the_cap() {
172
+ let error =
173
+ validate_dimensions("Icon", ONE_OVER, 16).expect_err("4097px width must be rejected");
174
+ assert_eq!(
175
+ error.reason,
176
+ "Icon is 4097x16px; tray icons are limited to 4096px per side"
177
+ );
178
+ }
179
+
180
+ #[test]
181
+ fn rejects_height_one_pixel_over_the_cap() {
182
+ let error =
183
+ validate_dimensions("Icon", 16, ONE_OVER).expect_err("4097px height must be rejected");
184
+ assert_eq!(
185
+ error.reason,
186
+ "Icon is 16x4097px; tray icons are limited to 4096px per side"
187
+ );
188
+ }
189
+
190
+ #[test]
191
+ fn rejects_zero_width() {
192
+ let error = validate_dimensions("Icon", 0, 16).expect_err("zero width must be rejected");
193
+ assert_eq!(error.reason, "Icon has invalid dimensions 0x16");
194
+ }
195
+
196
+ #[test]
197
+ fn rejects_zero_height() {
198
+ let error = validate_dimensions("Icon", 16, 0).expect_err("zero height must be rejected");
199
+ assert_eq!(error.reason, "Icon has invalid dimensions 16x0");
200
+ }
201
+
202
+ #[test]
203
+ fn from_rgba_rejects_oversize_width_before_length_validation() {
204
+ let error = Icon::from_rgba(Buffer::from(vec![0u8; 4]), 5000, 1)
205
+ .err()
206
+ .expect("oversized RGBA width must be rejected");
207
+ let message = error.reason;
208
+ assert!(
209
+ message.contains("is 5000x1px; tray icons are limited to 4096px per side"),
210
+ "expected the dimension-cap message, got: {message}"
211
+ );
212
+ assert!(
213
+ !message.contains("does not match expected size"),
214
+ "dimension validation must run before buffer-length validation, got: {message}"
215
+ );
216
+ }
217
+
218
+ #[test]
219
+ fn from_rgba_rejects_oversize_height_before_length_validation() {
220
+ let error = Icon::from_rgba(Buffer::from(vec![0u8; 4]), 1, 5000)
221
+ .err()
222
+ .expect("oversized RGBA height must be rejected");
223
+ let message = error.reason;
224
+ assert!(
225
+ message.contains("is 1x5000px; tray icons are limited to 4096px per side"),
226
+ "expected the dimension-cap message, got: {message}"
227
+ );
228
+ assert!(
229
+ !message.contains("does not match expected size"),
230
+ "dimension validation must run before buffer-length validation, got: {message}"
231
+ );
232
+ }
233
+
234
+ #[test]
235
+ fn rejects_an_oversized_png_from_its_header_before_decoding() {
236
+ let oversized = image::RgbaImage::from_pixel(5000, 1, image::Rgba([9, 9, 9, 255]));
237
+ let fixture = TempPng::from_image(&oversized);
238
+ let error = decode_icon_rgba(fixture.as_str())
239
+ .expect_err("a PNG header reporting more than 4096px must be rejected");
240
+ let message = error.reason;
241
+ assert!(
242
+ message.contains("is 5000x1px; tray icons are limited to 4096px per side"),
243
+ "expected the pre-decode cap message, got: {message}"
244
+ );
245
+ }
246
+
247
+ #[test]
248
+ fn decodes_a_small_valid_png() {
249
+ let small = image::RgbaImage::from_pixel(16, 16, image::Rgba([1, 2, 3, 255]));
250
+ let fixture = TempPng::from_image(&small);
251
+ let decoded = decode_icon_rgba(fixture.as_str()).expect("16x16 PNG must decode");
252
+ assert_eq!(decoded.dimensions(), (16, 16));
253
+ assert_eq!(decoded.into_raw().len(), 16 * 16 * 4);
254
+ }
255
+ }