@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,362 @@
1
+ /**
2
+ * @module for-os.tray
3
+ * @description Runtime-switchable system-tray icon and menu bridge.
4
+ * @summary `TrayIcon` owns one native tray host, a menu with JavaScript
5
+ * callbacks, and the cooperative native event pump. Icons can be replaced at
6
+ * runtime with {@link TrayIcon.setIcon} (path, bytes, base64, or RGBA), menu
7
+ * entries can be relabelled/enabled/checked, and unknown native failures
8
+ * degrade the tray without throwing into the host application.
9
+ */
10
+ import { TrayError } from "./../errors.js";
11
+ import { IconResolver } from "./../native/icons.js";
12
+ import { requireNativeModule } from "./../native/loader.js";
13
+ /** Interval of the cooperative native event pump while a tray exists. */
14
+ const DEFAULT_POLL_INTERVAL_MS = 100;
15
+ function defaultLog(message) {
16
+ console.warn(message);
17
+ }
18
+ /**
19
+ * @description A live system-tray icon with a JavaScript-driven menu.
20
+ * @summary Create one with {@link TrayIcon.create}. Call {@link close} when the
21
+ * host application shuts the tray down. `active` turns false after a native
22
+ * failure; every mutating method is a no-op after that.
23
+ * @class TrayIcon
24
+ * @example
25
+ * import { TrayIcon, TRAY_ICON_BASE64 } from "@decaf-ts/for-os";
26
+ * const tray = TrayIcon.create({
27
+ * icon: { base64: TRAY_ICON_BASE64.idle },
28
+ * tooltip: "Decaf",
29
+ * menu: [{ id: "quit", label: "Quit" }],
30
+ * });
31
+ * tray.on("quit", () => tray.close());
32
+ */
33
+ export class TrayIcon {
34
+ constructor(api, host, options, menu, resolver, handles) {
35
+ this.api = api;
36
+ this.host = host;
37
+ this.handlers = new Map();
38
+ this.itemHandlers = new Map();
39
+ this.menuHandles = new Map();
40
+ this.closed = false;
41
+ this.isActive = true;
42
+ this.menu = menu;
43
+ this.log = options.log ?? defaultLog;
44
+ this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
45
+ this.onEvent = options.onEvent;
46
+ this.resolver = resolver;
47
+ for (const { id, entry, handle } of handles) {
48
+ this.menuHandles.set(id, handle);
49
+ if (entry.onClick)
50
+ this.itemHandlers.set(id, entry.onClick);
51
+ }
52
+ this.startPump();
53
+ }
54
+ /**
55
+ * Creates a tray icon and its menu.
56
+ * @param {TrayIconOptions} options icon, tooltip, title, and menu entries
57
+ * @param {NativeModule} [api] native module override (tests/embedding)
58
+ * @return {TrayIcon} the live tray
59
+ * @throws {NativeModuleUnavailableError} when the native addon is unavailable
60
+ * @throws {TrayError} when the native tray host or menu cannot be created
61
+ */
62
+ static create(options, api = requireNativeModule()) {
63
+ if (!options?.icon)
64
+ throw new TrayError("TrayIcon requires an icon source.");
65
+ const resolver = new IconResolver(api.Icon);
66
+ let menu;
67
+ const handles = [];
68
+ try {
69
+ api.initialize();
70
+ const icon = resolver.resolve(options.icon);
71
+ if (options.menu?.length) {
72
+ menu = new api.Menu();
73
+ for (const entry of options.menu) {
74
+ if (entry.separator) {
75
+ const separator = api.PredefinedMenuItem?.separator();
76
+ if (separator)
77
+ menu.appendPredefinedMenuItem(separator);
78
+ continue;
79
+ }
80
+ if (entry.checkable && api.CheckMenuItemBuilder) {
81
+ const builder = new api.CheckMenuItemBuilder();
82
+ builder.withId(entry.id);
83
+ builder.withText(entry.label);
84
+ builder.withEnabled(entry.enabled ?? true);
85
+ builder.withChecked(entry.checked ?? false);
86
+ const handle = builder.build();
87
+ menu.appendCheckMenuItem(handle, entry.id);
88
+ handles.push({ id: entry.id, entry, handle });
89
+ continue;
90
+ }
91
+ const builder = new api.MenuItemBuilder();
92
+ builder.withId(entry.id);
93
+ builder.withText(entry.label);
94
+ builder.withEnabled(entry.enabled ?? true);
95
+ const handle = builder.build();
96
+ menu.appendMenuItem(handle, entry.id);
97
+ handles.push({ id: entry.id, entry, handle });
98
+ }
99
+ }
100
+ const builder = new api.TrayIconBuilder();
101
+ builder.withIcon(icon);
102
+ if (options.tooltip)
103
+ builder.withTooltip(options.tooltip);
104
+ if (options.title)
105
+ builder.withTitle(options.title);
106
+ if (menu)
107
+ builder.withMenu(menu);
108
+ const host = builder.build();
109
+ return new TrayIcon(api, host, options, menu, resolver, handles);
110
+ }
111
+ catch (error) {
112
+ resolver.dispose();
113
+ if (error instanceof TrayError)
114
+ throw error;
115
+ throw new TrayError(error);
116
+ }
117
+ }
118
+ /**
119
+ * Creates a tray icon, returning `undefined` instead of throwing.
120
+ * @param {TrayIconOptions} options tray construction options
121
+ * @param {NativeModule} [api] native module override
122
+ * @return {TrayIcon|undefined} the tray, or `undefined` when it cannot be created
123
+ */
124
+ static tryCreate(options, api) {
125
+ try {
126
+ return TrayIcon.create(options, api);
127
+ }
128
+ catch (error) {
129
+ (options.log ?? defaultLog)(`for-os: tray unavailable (${error instanceof Error ? error.message : String(error)}).`);
130
+ return undefined;
131
+ }
132
+ }
133
+ /** Whether the tray still exists and has not degraded. */
134
+ get active() {
135
+ return this.isActive && !this.closed;
136
+ }
137
+ /**
138
+ * Switches the tray icon at runtime.
139
+ * @param {IconSource} source the new icon
140
+ * @return {boolean} `true` when applied
141
+ */
142
+ setIcon(source) {
143
+ if (!this.active)
144
+ return false;
145
+ try {
146
+ this.host.setIcon(this.resolver.resolve(source));
147
+ this.pumpOnce();
148
+ return true;
149
+ }
150
+ catch (error) {
151
+ this.degrade(error);
152
+ return false;
153
+ }
154
+ }
155
+ /**
156
+ * Updates the hover tooltip.
157
+ * @param {string} tooltip new tooltip text
158
+ * @return {boolean} `true` when applied
159
+ */
160
+ setTooltip(tooltip) {
161
+ if (!this.active)
162
+ return false;
163
+ try {
164
+ this.host.setTooltip(tooltip);
165
+ return true;
166
+ }
167
+ catch (error) {
168
+ this.degrade(error);
169
+ return false;
170
+ }
171
+ }
172
+ /**
173
+ * Updates the macOS title text.
174
+ * @param {string} title new title
175
+ * @return {boolean} `true` when applied
176
+ */
177
+ setTitle(title) {
178
+ if (!this.active)
179
+ return false;
180
+ try {
181
+ this.host.setTitle(title);
182
+ return true;
183
+ }
184
+ catch (error) {
185
+ this.degrade(error);
186
+ return false;
187
+ }
188
+ }
189
+ /**
190
+ * Shows or hides the tray icon.
191
+ * @param {boolean} visible desired visibility
192
+ * @return {boolean} `true` when applied
193
+ */
194
+ setVisible(visible) {
195
+ if (!this.active)
196
+ return false;
197
+ try {
198
+ this.host.setVisible(visible);
199
+ return true;
200
+ }
201
+ catch (error) {
202
+ this.degrade(error);
203
+ return false;
204
+ }
205
+ }
206
+ /**
207
+ * Registers a global menu-action handler.
208
+ * @param {string} id menu action id
209
+ * @param {TrayActionHandler} handler callback
210
+ * @return {TrayIcon} this instance
211
+ */
212
+ on(id, handler) {
213
+ const handlers = this.handlers.get(id) ?? new Set();
214
+ handlers.add(handler);
215
+ this.handlers.set(id, handlers);
216
+ return this;
217
+ }
218
+ /**
219
+ * Removes a previously registered global handler.
220
+ * @param {string} id menu action id
221
+ * @param {TrayActionHandler} handler callback to remove
222
+ * @return {TrayIcon} this instance
223
+ */
224
+ off(id, handler) {
225
+ this.handlers.get(id)?.delete(handler);
226
+ return this;
227
+ }
228
+ /**
229
+ * Relabels, enables/disables, or checks a menu entry.
230
+ * @param {string} id menu entry id
231
+ * @param {TrayMenuItemPatch} patch fields to update
232
+ * @return {boolean} `true` when the entry exists and the change was applied
233
+ */
234
+ updateMenuItem(id, patch) {
235
+ if (!this.active)
236
+ return false;
237
+ const handle = this.menuHandles.get(id);
238
+ if (!handle)
239
+ return false;
240
+ try {
241
+ if (typeof patch.label === "string")
242
+ handle.setText(patch.label);
243
+ if (typeof patch.enabled === "boolean")
244
+ handle.setEnabled(patch.enabled);
245
+ if (typeof patch.checked === "boolean" && "setChecked" in handle) {
246
+ handle.setChecked(patch.checked);
247
+ }
248
+ return true;
249
+ }
250
+ catch (error) {
251
+ this.degrade(error);
252
+ return false;
253
+ }
254
+ }
255
+ /**
256
+ * Reads the checked state of a checkable menu entry.
257
+ * @param {string} id menu entry id
258
+ * @return {boolean} whether the entry is checked
259
+ */
260
+ isMenuItemChecked(id) {
261
+ if (!this.active || !this.menu)
262
+ return false;
263
+ try {
264
+ return this.menu.isChecked(id);
265
+ }
266
+ catch (error) {
267
+ this.degrade(error);
268
+ return false;
269
+ }
270
+ }
271
+ /**
272
+ * Toggles a checkable menu entry.
273
+ * @param {string} id menu entry id
274
+ * @return {boolean} the resulting checked state
275
+ */
276
+ toggleMenuItem(id) {
277
+ if (!this.active || !this.menu)
278
+ return false;
279
+ try {
280
+ this.menu.toggleCheck(id);
281
+ return this.menu.isChecked(id);
282
+ }
283
+ catch (error) {
284
+ this.degrade(error);
285
+ return false;
286
+ }
287
+ }
288
+ /**
289
+ * Processes pending native events immediately.
290
+ * @return {string[]} menu action ids dispatched in this drain
291
+ */
292
+ poll() {
293
+ return this.pumpOnce();
294
+ }
295
+ /** Releases the native tray, event pump, and materialized icon files; idempotent. */
296
+ close() {
297
+ if (this.closed)
298
+ return;
299
+ this.closed = true;
300
+ if (this.pump)
301
+ clearInterval(this.pump);
302
+ this.pump = undefined;
303
+ try {
304
+ this.host.setVisible(false);
305
+ }
306
+ catch {
307
+ // The desktop host may already have removed the tray; nothing to release.
308
+ }
309
+ this.resolver.dispose();
310
+ this.isActive = false;
311
+ }
312
+ startPump() {
313
+ this.pump = setInterval(() => this.pumpOnce(), this.pollIntervalMs);
314
+ this.pump.unref?.();
315
+ this.pumpOnce();
316
+ }
317
+ pumpOnce() {
318
+ if (!this.active)
319
+ return [];
320
+ const dispatched = [];
321
+ try {
322
+ this.api.update();
323
+ for (let event = this.api.pollMenuEvents(); event; event = this.api.pollMenuEvents()) {
324
+ this.dispatchMenuAction(event.id);
325
+ dispatched.push(event.id);
326
+ }
327
+ if (this.api.pollTrayEvents && this.onEvent) {
328
+ for (let event = this.api.pollTrayEvents(); event; event = this.api.pollTrayEvents()) {
329
+ this.onEvent(event);
330
+ }
331
+ }
332
+ return dispatched;
333
+ }
334
+ catch (error) {
335
+ this.degrade(error);
336
+ return dispatched;
337
+ }
338
+ }
339
+ dispatchMenuAction(id) {
340
+ const handlers = this.handlers.get(id);
341
+ if (handlers) {
342
+ for (const handler of handlers)
343
+ this.invoke(id, handler);
344
+ }
345
+ const item = this.itemHandlers.get(id);
346
+ if (item)
347
+ this.invoke(id, item);
348
+ }
349
+ invoke(id, handler) {
350
+ try {
351
+ handler(id);
352
+ }
353
+ catch (error) {
354
+ this.log(`for-os: tray action "${id}" handler failed (${error instanceof Error ? error.message : String(error)}).`);
355
+ }
356
+ }
357
+ degrade(error) {
358
+ this.log(`for-os: tray disabled after native failure (${error instanceof Error ? error.message : String(error)}).`);
359
+ this.close();
360
+ }
361
+ }
362
+ //# sourceMappingURL=TrayIcon.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"TrayIcon.js","sourceRoot":"","sources":["../../../src/tray/TrayIcon.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,26 @@
1
+ /**
2
+ * @module for-os.tray.assets
3
+ * @description Embedded 16x16 tray icons for runtime icon-switching examples.
4
+ * @summary Icons are base64 PNG strings so no binary asset has to be resolved
5
+ * at runtime. Pass them directly to {@link TrayIcon.setIcon} or decode them
6
+ * with {@link trayIconPng}.
7
+ */
8
+ /**
9
+ * Embedded base64 PNG icons keyed by tray state.
10
+ * @summary Values are 16x16 PNGs encoded as base64 strings. Decode them with
11
+ * {@link trayIconPng}, or pass `{ base64 }` directly to
12
+ * {@link TrayIcon.setIcon}.
13
+ * @constant
14
+ * @readonly
15
+ */
16
+ export const TRAY_ICON_BASE64 = {
17
+ /** Base64 PNG shown while the tray is idle. */
18
+ idle: "iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAaUlEQVR42q2TwQ3AIAhFvbof2zDC28IZvbdpIkljitHC4V0k/0UBC1AieIUKCKADGWdbgifQgWuij9pS0D6CM80T6EbY0FlQnWt7dOuJCeQgbMhboD8EmioIPyHcxPAYUxYpZZVTPtMRNxn8JW/L/TDsAAAAAElFTkSuQmCC",
19
+ /** Base64 PNG shown while the tray is active. */
20
+ active: "iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAbUlEQVR42mN46uHLQAnGJcH51MM35KmHbzUUh0DFiDIApOHLUw/f/2j4C1QOrwGLsGhEx4twGVBNhGYYrkY3gBOHs3HhL7AwgRkQQoJmGA5BNqCaDAOqqWoAxV6gOBApjkaqJCSqJGWqZCaSMABh2/5gh+Rb1AAAAABJRU5ErkJggg==",
21
+ };
22
+ /** Decodes an embedded tray icon back into PNG bytes. */
23
+ export function trayIconPng(name) {
24
+ return Buffer.from(TRAY_ICON_BASE64[name], "base64");
25
+ }
26
+ //# sourceMappingURL=assets.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"assets.js","sourceRoot":"","sources":["../../../src/tray/assets.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,+CAA+C;IAC/C,IAAI,EAAE,0NAA0N;IAChO,iDAAiD;IACjD,MAAM,EACJ,kOAAkO;CAC5N,CAAC;AAKX,yDAAyD;AACzD,MAAM,UAAU,WAAW,CAAC,IAAkB;IAC5C,OAAO,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,CAAC;AACvD,CAAC"}
@@ -0,0 +1,56 @@
1
+ /**
2
+ * @module for-os.errors
3
+ * @description Error hierarchy for the native operating-system bridges.
4
+ * @summary Every failure raised by `@decaf-ts/for-os` extends the Decaf
5
+ * `InternalError` hierarchy so callers get a stable `code` and `name`.
6
+ */
7
+ import { InternalError } from "@decaf-ts/db-decorators";
8
+ /**
9
+ * @description Raised when the native tray/notification addon cannot be located or loaded.
10
+ * @summary Use this when the vendored `tray-icon-node` addon has not been built
11
+ * or the host platform is unsupported.
12
+ * @param {string|Error|unknown} msg error message or originating error
13
+ * @class NativeModuleUnavailableError
14
+ * @extends InternalError
15
+ * @category Errors
16
+ */
17
+ export declare class NativeModuleUnavailableError extends InternalError {
18
+ constructor(msg: string | Error | unknown);
19
+ }
20
+ /**
21
+ * @description Raised when a system-tray host or menu operation fails.
22
+ * @summary Wraps native addon failures raised while creating or mutating a
23
+ * {@link TrayIcon} so callers can distinguish tray failures from other errors.
24
+ * @param {string|Error|unknown} msg error message or originating error
25
+ * @class TrayError
26
+ * @extends InternalError
27
+ * @category Errors
28
+ */
29
+ export declare class TrayError extends InternalError {
30
+ constructor(msg: string | Error | unknown);
31
+ }
32
+ /**
33
+ * @description Raised when a desktop notification cannot be dispatched.
34
+ * @summary Reserved for notification-specific failures; validation and missing
35
+ * native backends report {@link ValidationError} and
36
+ * {@link NativeModuleUnavailableError} respectively.
37
+ * @param {string|Error|unknown} msg error message or originating error
38
+ * @class NotificationError
39
+ * @extends InternalError
40
+ * @category Errors
41
+ */
42
+ export declare class NotificationError extends InternalError {
43
+ constructor(msg: string | Error | unknown);
44
+ }
45
+ /**
46
+ * @description Raised when an icon source cannot be materialized or decoded.
47
+ * @summary Covers empty paths, missing files, malformed base64, and RGBA buffers
48
+ * whose length does not match `width x height x 4`.
49
+ * @param {string|Error|unknown} msg error message or originating error
50
+ * @class IconError
51
+ * @extends InternalError
52
+ * @category Errors
53
+ */
54
+ export declare class IconError extends InternalError {
55
+ constructor(msg: string | Error | unknown);
56
+ }
@@ -0,0 +1,56 @@
1
+ /**
2
+ * @module for-os.errors
3
+ * @description Error hierarchy for the native operating-system bridges.
4
+ * @summary Every failure raised by `@decaf-ts/for-os` extends the Decaf
5
+ * `InternalError` hierarchy so callers get a stable `code` and `name`.
6
+ */
7
+ import { InternalError } from "@decaf-ts/db-decorators";
8
+ /**
9
+ * @description Raised when the native tray/notification addon cannot be located or loaded.
10
+ * @summary Use this when the vendored `tray-icon-node` addon has not been built
11
+ * or the host platform is unsupported.
12
+ * @param {string|Error|unknown} msg error message or originating error
13
+ * @class NativeModuleUnavailableError
14
+ * @extends InternalError
15
+ * @category Errors
16
+ */
17
+ export declare class NativeModuleUnavailableError extends InternalError {
18
+ constructor(msg: string | Error | unknown);
19
+ }
20
+ /**
21
+ * @description Raised when a system-tray host or menu operation fails.
22
+ * @summary Wraps native addon failures raised while creating or mutating a
23
+ * {@link TrayIcon} so callers can distinguish tray failures from other errors.
24
+ * @param {string|Error|unknown} msg error message or originating error
25
+ * @class TrayError
26
+ * @extends InternalError
27
+ * @category Errors
28
+ */
29
+ export declare class TrayError extends InternalError {
30
+ constructor(msg: string | Error | unknown);
31
+ }
32
+ /**
33
+ * @description Raised when a desktop notification cannot be dispatched.
34
+ * @summary Reserved for notification-specific failures; validation and missing
35
+ * native backends report {@link ValidationError} and
36
+ * {@link NativeModuleUnavailableError} respectively.
37
+ * @param {string|Error|unknown} msg error message or originating error
38
+ * @class NotificationError
39
+ * @extends InternalError
40
+ * @category Errors
41
+ */
42
+ export declare class NotificationError extends InternalError {
43
+ constructor(msg: string | Error | unknown);
44
+ }
45
+ /**
46
+ * @description Raised when an icon source cannot be materialized or decoded.
47
+ * @summary Covers empty paths, missing files, malformed base64, and RGBA buffers
48
+ * whose length does not match `width x height x 4`.
49
+ * @param {string|Error|unknown} msg error message or originating error
50
+ * @class IconError
51
+ * @extends InternalError
52
+ * @category Errors
53
+ */
54
+ export declare class IconError extends InternalError {
55
+ constructor(msg: string | Error | unknown);
56
+ }
@@ -0,0 +1,27 @@
1
+ /**
2
+ * @module for-os
3
+ * @description Native operating-system bridges for Decaf.ts: system tray and
4
+ * desktop notifications, built from Rust and exposed to TypeScript/JavaScript.
5
+ * @summary The package ships a vendored NAPI-RS crate
6
+ * (`native/tray-icon-node`) that is compiled at install time. The TypeScript
7
+ * layer adds runtime icon switching, menu callbacks, auto-dismiss notification
8
+ * timers, and JavaScript button mapping on top of the raw native API. The main
9
+ * entry points are {@link TrayIcon}, {@link NotificationCenter}, and the native
10
+ * loader helpers exposed by {@link loadNativeModule}.
11
+ */
12
+ export * from "./errors.d.cts";
13
+ export * from "./native/types.d.cts";
14
+ export * from "./native/icons.d.cts";
15
+ export * from "./native/loader.d.cts";
16
+ export * from "./tray/assets.d.cts";
17
+ export * from "./tray/TrayIcon.d.cts";
18
+ export * from "./notifications/NotificationCenter.d.cts";
19
+ /**
20
+ * @description The package version, replaced by the build pipeline.
21
+ * @summary Reports the released semantic version of `@decaf-ts/for-os`; the
22
+ * placeholder literal is substituted during the release build.
23
+ * @type {string}
24
+ * @constant
25
+ * @memberOf module:for-os
26
+ */
27
+ export declare const VERSION = "0.2.7";
@@ -0,0 +1,27 @@
1
+ /**
2
+ * @module for-os
3
+ * @description Native operating-system bridges for Decaf.ts: system tray and
4
+ * desktop notifications, built from Rust and exposed to TypeScript/JavaScript.
5
+ * @summary The package ships a vendored NAPI-RS crate
6
+ * (`native/tray-icon-node`) that is compiled at install time. The TypeScript
7
+ * layer adds runtime icon switching, menu callbacks, auto-dismiss notification
8
+ * timers, and JavaScript button mapping on top of the raw native API. The main
9
+ * entry points are {@link TrayIcon}, {@link NotificationCenter}, and the native
10
+ * loader helpers exposed by {@link loadNativeModule}.
11
+ */
12
+ export * from "./errors.d.mts";
13
+ export * from "./native/types.d.mts";
14
+ export * from "./native/icons.d.mts";
15
+ export * from "./native/loader.d.mts";
16
+ export * from "./tray/assets.d.mts";
17
+ export * from "./tray/TrayIcon.d.mts";
18
+ export * from "./notifications/NotificationCenter.d.mts";
19
+ /**
20
+ * @description The package version, replaced by the build pipeline.
21
+ * @summary Reports the released semantic version of `@decaf-ts/for-os`; the
22
+ * placeholder literal is substituted during the release build.
23
+ * @type {string}
24
+ * @constant
25
+ * @memberOf module:for-os
26
+ */
27
+ export declare const VERSION = "0.2.7";
@@ -0,0 +1,71 @@
1
+ /**
2
+ * @module for-os.native.icons
3
+ * @description Converts TypeScript icon sources into native tray icon handles.
4
+ * @summary The native addon loads icons from file paths (or raw RGBA), so
5
+ * base64 and byte-buffer sources are materialized into a private temporary
6
+ * directory that is removed when the owning tray closes.
7
+ */
8
+ import type { NativeIconFactory } from "./types.d.cts";
9
+ /** Raw RGBA pixels accepted by {@link IconSource}. */
10
+ export type RgbaIcon = {
11
+ rgba: Buffer | Uint8Array;
12
+ width: number;
13
+ height: number;
14
+ };
15
+ /**
16
+ * Any icon representation accepted by {@link IconResolver.resolve}.
17
+ * - `string`: absolute or relative image file path
18
+ * - `{ path }`: image file path
19
+ * - `{ base64 }`: base64-encoded image bytes (PNG/JPEG, decided by `extension`)
20
+ * - `{ png }` / `{ bytes }`: raw encoded image bytes
21
+ * - `{ rgba, width, height }`: uncompressed RGBA pixels
22
+ *
23
+ * Caller-supplied `extension` values are sanitized to a safe alphanumeric/dot
24
+ * file suffix (capped at 16 characters) and fall back to `.png`.
25
+ */
26
+ export type IconSource = string | {
27
+ path: string;
28
+ } | {
29
+ base64: string;
30
+ extension?: string;
31
+ } | {
32
+ png: Buffer | Uint8Array;
33
+ } | {
34
+ bytes: Buffer | Uint8Array;
35
+ extension?: string;
36
+ } | RgbaIcon;
37
+ /**
38
+ * @description Owns the temporary directory used to materialize file-backed icons.
39
+ * @summary One resolver is normally owned by a tray or notification host and
40
+ * disposed with it. Resolving an already-native handle is intentionally not
41
+ * supported; callers pass a source and the resolver keeps the native object.
42
+ * @param {NativeIconFactory} api native icon factory used to build handles
43
+ * @param {function(string): string} [createDirectory] creates the private
44
+ * temporary directory; defaults to `fs.mkdtempSync` under the OS temp dir
45
+ * @param {function(string): void} [removeDirectory] removes the private
46
+ * directory on {@link IconResolver.dispose}; defaults to a recursive `fs.rmSync`
47
+ * @class IconResolver
48
+ */
49
+ export declare class IconResolver {
50
+ private readonly api;
51
+ private readonly createDirectory;
52
+ private readonly removeDirectory;
53
+ private directory?;
54
+ constructor(api: NativeIconFactory, createDirectory?: (prefix: string) => string, removeDirectory?: (directory: string) => void);
55
+ private ensureDirectory;
56
+ /**
57
+ * Materializes `source` into a native icon handle.
58
+ * @param {IconSource} source the icon path, bytes, base64, or RGBA data
59
+ * @return {unknown} the native icon handle expected by the addon
60
+ * @throws {IconError} when the source is invalid or points to a missing file
61
+ */
62
+ resolve(source: IconSource): unknown;
63
+ private fromPath;
64
+ private fromBytes;
65
+ /** Removes every materialized icon file; idempotent. */
66
+ dispose(): void;
67
+ /** Directory holding materialized icons, when one has been created. */
68
+ get iconDirectory(): string | undefined;
69
+ }
70
+ /** Returns a stable file extension for a path, defaulting to `.png`. */
71
+ export declare function iconExtension(path: string): string;