@flighthq/tray 0.3.0-next.906.07cea63 → 0.3.0

package/dist/contract.d.ts

@@ -1,2 +1,3 @@
+export * from './enableTrayGuards';
 export * from './tray';
 //# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC"}
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,QAAQ,CAAC"}

package/dist/contract.js

@@ -1,2 +1,3 @@
+export * from './enableTrayGuards';
 export * from './tray';
 //# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -1 +1 @@
-{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC"}
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,QAAQ,CAAC"}

package/dist/enableTrayGuards.d.ts

@@ -0,0 +1,17 @@
+/** Uninstalls the guard installed by `enableTrayGuards`. */
+export declare function disableTrayGuards(): void;
+/**
+ * Installs the caller-facing tray guard (opt-in, dev-only). It warns once — through `@flighthq/log` —
+ * when `startTrayIconAnimation` is given a non-positive interval.
+ *
+ * A `setInterval` of zero or less does not fail; it schedules as fast as the host will run it, writing
+ * the tray icon every tick. The animation "works", the app burns a core and hammers the platform's tray
+ * API, and nothing points at the call that asked for it. That is caller misuse rather than an expected
+ * failure, so it warns rather than throwing or returning a sentinel — the animation still starts, and
+ * the developer gets told why their machine is busy.
+ *
+ * Not importing this module costs production nothing: the message and the `@flighthq/log` dependency
+ * live only here.
+ */
+export declare function enableTrayGuards(): void;
+//# sourceMappingURL=enableTrayGuards.d.ts.map

package/dist/enableTrayGuards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enableTrayGuards.d.ts","sourceRoot":"","sources":["../src/enableTrayGuards.ts"],"names":[],"mappings":"AAMA,4DAA4D;AAC5D,wBAAgB,iBAAiB,IAAI,IAAI,CAExC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC"}

package/dist/enableTrayGuards.js

@@ -0,0 +1,32 @@
+import { logOnce } from '@flighthq/log/contract';
+import { LogLevel } from '@flighthq/types/contract';
+import { setTrayAnimationGuard } from './tray';
+/** Uninstalls the guard installed by `enableTrayGuards`. */
+export function disableTrayGuards() {
+    setTrayAnimationGuard(null);
+}
+/**
+ * Installs the caller-facing tray guard (opt-in, dev-only). It warns once — through `@flighthq/log` —
+ * when `startTrayIconAnimation` is given a non-positive interval.
+ *
+ * A `setInterval` of zero or less does not fail; it schedules as fast as the host will run it, writing
+ * the tray icon every tick. The animation "works", the app burns a core and hammers the platform's tray
+ * API, and nothing points at the call that asked for it. That is caller misuse rather than an expected
+ * failure, so it warns rather than throwing or returning a sentinel — the animation still starts, and
+ * the developer gets told why their machine is busy.
+ *
+ * Not importing this module costs production nothing: the message and the `@flighthq/log` dependency
+ * live only here.
+ */
+export function enableTrayGuards() {
+    setTrayAnimationGuard(warnOnUnboundedTrayAnimation);
+}
+function warnOnUnboundedTrayAnimation(_tray, _frameCount, intervalMs) {
+    if (intervalMs > 0)
+        return;
+    logOnce('tray:non-positive-animation-interval', LogLevel.Warn, {
+        message: `startTrayIconAnimation: intervalMs is ${intervalMs}, so the icon will be rewritten as fast as the ` +
+            'host schedules timers rather than on a frame interval. Pass a positive millisecond interval.',
+    }, 'tray');
+}
+//# sourceMappingURL=enableTrayGuards.js.map

package/dist/enableTrayGuards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enableTrayGuards.js","sourceRoot":"","sources":["../src/enableTrayGuards.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAEjD,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,QAAQ,CAAC;AAE/C,4DAA4D;AAC5D,MAAM,UAAU,iBAAiB;IAC/B,qBAAqB,CAAC,IAAI,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,gBAAgB;IAC9B,qBAAqB,CAAC,4BAA4B,CAAC,CAAC;AACtD,CAAC;AAED,SAAS,4BAA4B,CAAC,KAAe,EAAE,WAAmB,EAAE,UAAkB;IAC5F,IAAI,UAAU,GAAG,CAAC;QAAE,OAAO;IAC3B,OAAO,CACL,sCAAsC,EACtC,QAAQ,CAAC,IAAI,EACb;QACE,OAAO,EACL,yCAAyC,UAAU,iDAAiD;YACpG,8FAA8F;KACjG,EACD,MAAM,CACP,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { createTrayIcon, destroyTrayIcon, displayTrayBalloon, getTrayCapabilities, getTrayIconBounds, getTrayIconTitle, getTrayIconTooltip, getTrayIcons, isTrayDestroyed, onTrayEvent, popupTrayContextMenu, removeTrayBalloon, setTrayIcon, setTrayIconContextMenu, setTrayIconTemplate, setTrayIconTitle, setTrayIconTooltip, setTrayIgnoreDoubleClickEvents, setTrayPressedIcon, startTrayIconAnimation, } from './contract';
+export { disableTrayGuards, enableTrayGuards, createTrayIcon, destroyTrayIcon, displayTrayBalloon, getTrayCapabilities, getTrayIconBounds, getTrayIconTitle, getTrayIconTooltip, getTrayIcons, isTrayDestroyed, isTrayIconAnimating, onTrayEvent, popupTrayContextMenu, removeTrayBalloon, setTrayIcon, setTrayIconContextMenu, setTrayIconTemplate, setTrayIconTitle, setTrayIconTooltip, setTrayIgnoreDoubleClickEvents, setTrayPressedIcon, startTrayIconAnimation, stopTrayIconAnimation, } from './contract';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,YAAY,EACZ,eAAe,EACf,WAAW,EACX,oBAAoB,EACpB,iBAAiB,EACjB,WAAW,EACX,sBAAsB,EACtB,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,8BAA8B,EAC9B,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,YAAY,EACZ,eAAe,EACf,mBAAmB,EACnB,WAAW,EACX,oBAAoB,EACpB,iBAAiB,EACjB,WAAW,EACX,sBAAsB,EACtB,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,8BAA8B,EAC9B,kBAAkB,EAClB,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,2 +1,2 @@
-export { createTrayIcon, destroyTrayIcon, displayTrayBalloon, getTrayCapabilities, getTrayIconBounds, getTrayIconTitle, getTrayIconTooltip, getTrayIcons, isTrayDestroyed, onTrayEvent, popupTrayContextMenu, removeTrayBalloon, setTrayIcon, setTrayIconContextMenu, setTrayIconTemplate, setTrayIconTitle, setTrayIconTooltip, setTrayIgnoreDoubleClickEvents, setTrayPressedIcon, startTrayIconAnimation, } from './contract';
+export { disableTrayGuards, enableTrayGuards, createTrayIcon, destroyTrayIcon, displayTrayBalloon, getTrayCapabilities, getTrayIconBounds, getTrayIconTitle, getTrayIconTooltip, getTrayIcons, isTrayDestroyed, isTrayIconAnimating, onTrayEvent, popupTrayContextMenu, removeTrayBalloon, setTrayIcon, setTrayIconContextMenu, setTrayIconTemplate, setTrayIconTitle, setTrayIconTooltip, setTrayIgnoreDoubleClickEvents, setTrayPressedIcon, startTrayIconAnimation, stopTrayIconAnimation, } from './contract';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,YAAY,EACZ,eAAe,EACf,WAAW,EACX,oBAAoB,EACpB,iBAAiB,EACjB,WAAW,EACX,sBAAsB,EACtB,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,8BAA8B,EAC9B,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,YAAY,EACZ,eAAe,EACf,mBAAmB,EACnB,WAAW,EACX,oBAAoB,EACpB,iBAAiB,EACjB,WAAW,EACX,sBAAsB,EACtB,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,8BAA8B,EAC9B,kBAAkB,EAClB,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,YAAY,CAAC"}

package/dist/tray.d.ts

@@ -11,9 +11,14 @@ export declare function getTrayIcons(): readonly TrayIcon[];
 export declare function getTrayIconTitle(tray: TrayIcon): string;
 export declare function getTrayIconTooltip(tray: TrayIcon): string;
 export declare function isTrayDestroyed(tray: TrayIcon): boolean;
+export declare function isTrayIconAnimating(tray: TrayIcon): boolean;
 export declare function onTrayEvent(listener: (event: Readonly<TrayEventData>) => void): () => void;
 export declare function popupTrayContextMenu(tray: TrayIcon, position?: Readonly<Vector2Like>): void;
 export declare function removeTrayBalloon(tray: TrayIcon): void;
+/** Installs the tray guard, or clears it with `null`. The seam exists so the messages and the
+ *  `@flighthq/log` dependency live in the separately-importable guard module rather than here; not
+ *  importing that module costs production nothing. Called by `enableTrayGuards`, not directly. */
+export declare function setTrayAnimationGuard(guard: ((tray: TrayIcon, frameCount: number, intervalMs: number) => void) | null): void;
 export declare function setTrayBackend(backend: TrayBackend | null): void;
 export declare function setTrayIcon(tray: TrayIcon, icon: string): void;
 export declare function setTrayIconContextMenu(tray: TrayIcon, items: readonly MenuItemTemplate[]): void;
@@ -23,4 +28,5 @@ export declare function setTrayIconTooltip(tray: TrayIcon, tooltip: string): voi
 export declare function setTrayIgnoreDoubleClickEvents(tray: TrayIcon, ignore: boolean): void;
 export declare function setTrayPressedIcon(tray: TrayIcon, icon: string): void;
 export declare function startTrayIconAnimation(tray: TrayIcon, frames: readonly string[], intervalMs: number): () => void;
+export declare function stopTrayIconAnimation(tray: TrayIcon): void;
 //# sourceMappingURL=tray.d.ts.map

package/dist/tray.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tray.d.ts","sourceRoot":"","sources":["../src/tray.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,aAAa,EACb,WAAW,EACX,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,QAAQ,EACR,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAc5D,wBAAgB,cAAc,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,eAAe,CAAC,GAAG,QAAQ,GAAG,IAAI,CAGnF;AAKD,wBAAgB,oBAAoB,IAAI,WAAW,CAmElD;AAGD,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAEpD;AAID,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,CAAC,kBAAkB,CAAC,GAAG,IAAI,CAE9F;AAGD,wBAAgB,cAAc,IAAI,WAAW,CAG5C;AAKD,wBAAgB,mBAAmB,IAAI,QAAQ,CAAC,gBAAgB,CAAC,CAEhE;AAID,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAAC,aAAa,CAAC,GAAG,IAAI,CAEhF;AAGD,wBAAgB,YAAY,IAAI,SAAS,QAAQ,EAAE,CAIlD;AAGD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAEvD;AAGD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAEzD;AAID,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAEvD;AAKD,wBAAgB,WAAW,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,aAAa,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI,CAE1F;AAKD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,QAAQ,CAAC,WAAW,CAAC,GAAG,IAAI,CAE3F;AAGD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAEtD;AAGD,wBAAgB,cAAc,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,GAAG,IAAI,CAEhE;AAID,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAE9D;AAID,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,gBAAgB,EAAE,GAAG,IAAI,CAE/F;AAKD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,OAAO,GAAG,IAAI,CAE7E;AAGD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAEpE;AAGD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAExE;AAID,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAEpF;AAID,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAErE;AAOD,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,IAAI,CAShH"}
+{"version":3,"file":"tray.d.ts","sourceRoot":"","sources":["../src/tray.ts"],"names":[],"mappings":"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"}

package/dist/tray.js

@@ -1,4 +1,6 @@
-// Web tray capability constants. Web has no system tray — all capabilities are false.
+// Web tray capability constants. Web has no system tray — all capabilities are false. Readonly and
+// shared: getCapabilities hands this same object to every caller, so a mutable one would let any of
+// them rewrite what the backend reports to all the others.
 const WEB_CAPABILITIES = {
     balloon: false,
     bounds: false,
@@ -85,7 +87,12 @@ export function createWebTrayBackend() {
     };
 }
 // Destroys a tray icon and frees its host resource. No-op when the host has no tray.
+// Any icon animation running on this tray is stopped first: the interval writes through setTrayIcon,
+// and left running it would keep calling into a resource the host has freed — forever, since the
+// timer holds its own closure alive. Destroying the thing being animated is the clearest possible
+// signal that the animation is over, so the caller does not have to have kept the stop function.
 export function destroyTrayIcon(tray) {
+    stopTrayIconAnimation(tray);
     getTrayBackend().destroy(tray.id);
 }
 // Displays a Windows balloon notification from the tray icon. No-op on macOS/Linux and on web.
@@ -129,6 +136,11 @@ export function getTrayIconTooltip(tray) {
 export function isTrayDestroyed(tray) {
     return getTrayBackend().isDestroyed(tray.id);
 }
+// True while an icon animation started by startTrayIconAnimation is running on this tray. False once
+// it is stopped, replaced by a later start, or the tray is destroyed.
+export function isTrayIconAnimating(tray) {
+    return _animations.has(tray.id);
+}
 // Subscribes to tray icon events, delivering a rich TrayEventData payload (id, type, bounds,
 // position, modifier keys, and drop payloads). Returns an unsubscribe function. On web this
 // never fires (no tray); a native host is required.
@@ -145,6 +157,12 @@ export function popupTrayContextMenu(tray, position) {
 export function removeTrayBalloon(tray) {
     getTrayBackend().removeBalloon(tray.id);
 }
+/** Installs the tray guard, or clears it with `null`. The seam exists so the messages and the
+ *  `@flighthq/log` dependency live in the separately-importable guard module rather than here; not
+ *  importing that module costs production nothing. Called by `enableTrayGuards`, not directly. */
+export function setTrayAnimationGuard(guard) {
+    _animationGuard = guard;
+}
 // Installs a native host tray backend; pass null to fall back to the web default.
 export function setTrayBackend(backend) {
     _backend = backend;
@@ -183,21 +201,53 @@ export function setTrayIgnoreDoubleClickEvents(tray, ignore) {
 export function setTrayPressedIcon(tray, icon) {
     getTrayBackend().setPressedIcon(tray.id, icon);
 }
-// Starts an animated icon sequence by cycling through the given frames at the specified interval.
-// The caller owns the timer — this function is a thin helper over setTrayIcon that starts an
-// interval and returns a stop function. Call the returned function (or stopTrayIconAnimation) to
-// cancel. The tray icon is not destroyed when the animation stops.
+// Starts an animated icon sequence by cycling through the given frames at the specified interval,
+// returning a stop function. An empty frame list is a no-op. The tray icon is not destroyed when the
+// animation stops, and the last frame shown stays.
+//
+// A tray icon has one image, so it has one animation: starting a second on the same tray replaces the
+// first rather than running both. Without that, a perfectly ordinary sequence — swap a "syncing"
+// animation for an "error" one — left two intervals writing to the same icon on the same tick, and
+// the only handle to the orphaned one was a stop function the caller had no reason to still be
+// holding. The returned function stops only the animation it started, so calling a stale one cannot
+// cancel a newer animation.
+//
 // Note: interval timing is best-effort; the actual frame rate depends on the host event loop.
 export function startTrayIconAnimation(tray, frames, intervalMs) {
     if (frames.length === 0)
-        return () => { };
+        return _noopStop;
+    _animationGuard?.(tray, frames.length, intervalMs);
+    stopTrayIconAnimation(tray);
     let index = 0;
     setTrayIcon(tray, frames[index]);
     const handle = setInterval(() => {
         index = (index + 1) % frames.length;
         setTrayIcon(tray, frames[index]);
     }, intervalMs);
-    return () => clearInterval(handle);
+    _animations.set(tray.id, handle);
+    return () => {
+        // Only clear if this animation is still the current one; a later start already replaced it.
+        if (_animations.get(tray.id) !== handle)
+            return;
+        clearInterval(handle);
+        _animations.delete(tray.id);
+    };
 }
 let _backend = null;
+// The interval per animating tray id. Module-scoped like the backend, and correct at that scope: an
+// id is the host's, so one id is one icon is one animation.
+const _animations = new Map();
+function _noopStop() { }
+// Stops the icon animation running on this tray, if any. Idempotent, and safe on a tray that never
+// animated. The named counterpart to startTrayIconAnimation for callers that hold the TrayIcon but
+// not the stop function it returned — which is most of them, since the handle is what gets passed
+// around and the closure is what gets dropped.
+export function stopTrayIconAnimation(tray) {
+    const handle = _animations.get(tray.id);
+    if (handle === undefined)
+        return;
+    clearInterval(handle);
+    _animations.delete(tray.id);
+}
+let _animationGuard = null;
 //# sourceMappingURL=tray.js.map

package/dist/tray.js.map

@@ -1 +1 @@
-{"version":3,"file":"tray.js","sourceRoot":"","sources":["../src/tray.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tray.js","sourceRoot":"","sources":["../src/tray.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,8 @@
 {
   "name": "@flighthq/tray",
-  "version": "0.3.0-next.906.07cea63",
+  "version": "0.3.0",
+  "author": "Joshua Granick and other contributors",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/flighthq/flight.git",
@@ -36,7 +38,8 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/types": "0.3.0-next.906.07cea63"
+    "@flighthq/log": "0.3.0",
+    "@flighthq/types": "0.3.0"
   },
   "devDependencies": {
     "typescript": "^5.3.0"

package/src/enableTrayGuards.test.ts

@@ -0,0 +1,79 @@
+import { setLogSink } from '@flighthq/log/contract';
+import type { LogEntry } from '@flighthq/types/contract';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { disableTrayGuards, enableTrayGuards } from './enableTrayGuards';
+import { createTrayIcon, setTrayBackend, startTrayIconAnimation, stopTrayIconAnimation } from './tray';
+
+let entries: LogEntry[];
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  entries = [];
+  setLogSink((entry) => entries.push(entry));
+  setTrayBackend({
+    create: () => 1,
+    destroy: () => {},
+    getBounds: () => null,
+    getCapabilities: () => ({ animation: true, badge: false, bounds: true, contextMenu: true, title: true }),
+    getTitle: () => '',
+    isDestroyed: () => false,
+    listIds: () => [1],
+    setContextMenu: () => {},
+    setIcon: () => {},
+    setPressedIcon: () => {},
+    setTitle: () => {},
+    setTooltip: () => {},
+    subscribe: () => () => {},
+  } as never);
+});
+
+afterEach(() => {
+  disableTrayGuards();
+  setTrayBackend(null);
+  setLogSink(null);
+  vi.useRealTimers();
+});
+
+function messages(): string {
+  return entries.map((e) => String((e.data as { message?: unknown } | undefined)?.message ?? '')).join('\n');
+}
+
+describe('disableTrayGuards', () => {
+  it('stops the guard inspecting later animations', () => {
+    enableTrayGuards();
+    disableTrayGuards();
+    const tray = createTrayIcon()!;
+    startTrayIconAnimation(tray, ['a', 'b'], 0);
+    stopTrayIconAnimation(tray);
+    expect(messages()).toBe('');
+  });
+});
+
+describe('enableTrayGuards', () => {
+  it('says nothing for a positive interval', () => {
+    enableTrayGuards();
+    const tray = createTrayIcon()!;
+    startTrayIconAnimation(tray, ['a', 'b'], 100);
+    stopTrayIconAnimation(tray);
+    expect(messages()).toBe('');
+  });
+
+  // A non-positive interval does not fail — setInterval simply schedules as fast as the host will run
+  // it, so the animation "works" while burning a core. Nothing points at the call that asked for it.
+  it('warns when the interval is zero, and still starts the animation', () => {
+    enableTrayGuards();
+    const tray = createTrayIcon()!;
+
+    const stop = startTrayIconAnimation(tray, ['a', 'b'], 0);
+
+    expect(messages()).toContain('intervalMs is 0');
+    // The wording that explains WHY is asserted here rather than in a separate negative-interval test:
+    // logOnce suppresses a key for the process, so a second test tripping this key would pass or fail
+    // on file order alone.
+    expect(messages()).toContain('as fast as the host schedules');
+    // Warned, not refused: this is misuse, not an expected failure.
+    expect(typeof stop).toBe('function');
+    stop();
+  });
+});

package/src/tray.test.ts

@@ -20,9 +20,11 @@ import {
   getTrayIconTitle,
   getTrayIconTooltip,
   isTrayDestroyed,
+  isTrayIconAnimating,
   onTrayEvent,
   popupTrayContextMenu,
   removeTrayBalloon,
+  setTrayAnimationGuard,
   setTrayBackend,
   setTrayIcon,
   setTrayIconContextMenu,
@@ -32,6 +34,7 @@ import {
   setTrayIgnoreDoubleClickEvents,
   setTrayPressedIcon,
   startTrayIconAnimation,
+  stopTrayIconAnimation,
 } from './tray';
 
 // Fake backend state per icon.
@@ -54,6 +57,9 @@ function fakeBackend(caps: Partial<TrayCapabilities> = {}): TrayBackend & {
   capabilities: TrayCapabilities;
   fireEvent(event: TrayEventData): void;
   lastPopupPosition: { x: number; y: number } | null;
+  // Every icon written, in order — the animation tests assert on the sequence of writes rather than
+  // the final image, because two competing animations can leave a correct-looking final frame.
+  setIconCalls: string[];
   trays: Map<number, FakeTray>;
 } {
   const capabilities: TrayCapabilities = {
@@ -68,9 +74,12 @@ function fakeBackend(caps: Partial<TrayCapabilities> = {}): TrayBackend & {
   let eventListener: ((event: Readonly<TrayEventData>) => void) | null = null;
   const trays = new Map<number, FakeTray>();
 
+  const setIconCalls: string[] = [];
+
   return {
     capabilities,
     trays,
+    setIconCalls,
     lastPopupPosition: null,
     create(options) {
       const id = nextId++;
@@ -129,6 +138,7 @@ function fakeBackend(caps: Partial<TrayCapabilities> = {}): TrayBackend & {
       if (tray) tray.contextMenu = items;
     },
     setIcon(id, icon) {
+      setIconCalls.push(icon);
       const tray = trays.get(id);
       if (tray) tray.icon = icon;
     },
@@ -396,6 +406,43 @@ describe('isTrayDestroyed', () => {
   });
 });
 
+describe('isTrayIconAnimating', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('is false before, true during, and false after an animation', () => {
+    setTrayBackend(fakeBackend());
+    const tray = createTrayIcon({ icon: 'a.png' })!;
+    expect(isTrayIconAnimating(tray)).toBe(false);
+    const stop = startTrayIconAnimation(tray, ['a.png', 'b.png'], 100);
+    expect(isTrayIconAnimating(tray)).toBe(true);
+    stop();
+    expect(isTrayIconAnimating(tray)).toBe(false);
+  });
+
+  it('is false for an empty frame list, which starts nothing', () => {
+    setTrayBackend(fakeBackend());
+    const tray = createTrayIcon({ icon: 'a.png' })!;
+    startTrayIconAnimation(tray, [], 100);
+    expect(isTrayIconAnimating(tray)).toBe(false);
+  });
+
+  it('tracks each tray independently', () => {
+    setTrayBackend(fakeBackend());
+    const first = createTrayIcon({ icon: 'a.png' })!;
+    const second = createTrayIcon({ icon: 'b.png' })!;
+    startTrayIconAnimation(first, ['a.png', 'b.png'], 100);
+    expect(isTrayIconAnimating(first)).toBe(true);
+    expect(isTrayIconAnimating(second)).toBe(false);
+    stopTrayIconAnimation(first);
+  });
+});
+
 describe('onTrayEvent', () => {
   it('delivers rich TrayEventData via the active backend', () => {
     const backend = fakeBackend();
@@ -494,6 +541,42 @@ describe('removeTrayBalloon', () => {
   });
 });
 
+describe('setTrayAnimationGuard', () => {
+  afterEach(() => {
+    setTrayAnimationGuard(null);
+    setTrayBackend(null);
+  });
+
+  // The seam keeps the message and the @flighthq/log dependency in the separately-importable guard
+  // module; startTrayIconAnimation only calls whatever is installed.
+  it('reports the frame count and interval for each animation start', () => {
+    setTrayBackend(fakeBackend());
+    const seen: Array<[number, number]> = [];
+    setTrayAnimationGuard((_tray, frameCount, intervalMs) => seen.push([frameCount, intervalMs]));
+    const tray = createTrayIcon()!;
+
+    stopTrayIconAnimation(tray);
+    startTrayIconAnimation(tray, ['a', 'b', 'c'], 0);
+    stopTrayIconAnimation(tray);
+
+    expect(seen).toEqual([[3, 0]]);
+  });
+
+  it('stops reporting once cleared with null', () => {
+    setTrayBackend(fakeBackend());
+    let calls = 0;
+    setTrayAnimationGuard(() => (calls += 1));
+    const tray = createTrayIcon()!;
+    startTrayIconAnimation(tray, ['a'], 5);
+    stopTrayIconAnimation(tray);
+    setTrayAnimationGuard(null);
+    startTrayIconAnimation(tray, ['a'], 5);
+    stopTrayIconAnimation(tray);
+
+    expect(calls).toBe(1);
+  });
+});
+
 describe('setTrayBackend', () => {
   it('clears back to the web fallback when passed null', () => {
     setTrayBackend(fakeBackend());
@@ -645,3 +728,104 @@ describe('startTrayIconAnimation', () => {
     expect(() => stop()).not.toThrow();
   });
 });
+
+describe('stopTrayIconAnimation', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('stops the interval so no further frames are written', () => {
+    const backend = fakeBackend();
+    setTrayBackend(backend);
+    const tray = createTrayIcon({ icon: 'frame0.png' })!;
+    startTrayIconAnimation(tray, ['frame0.png', 'frame1.png'], 100);
+    stopTrayIconAnimation(tray);
+    const iconAtStop = backend.trays.get(tray.id)!.icon;
+    vi.advanceTimersByTime(500);
+    expect(backend.trays.get(tray.id)!.icon).toBe(iconAtStop);
+  });
+
+  it('is idempotent and safe on a tray that never animated', () => {
+    setTrayBackend(fakeBackend());
+    const tray = createTrayIcon({ icon: 'a.png' })!;
+    expect(() => {
+      stopTrayIconAnimation(tray);
+      stopTrayIconAnimation(tray);
+    }).not.toThrow();
+  });
+});
+
+describe('tray icon animation lifecycle', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('replaces a running animation instead of running both', () => {
+    // The regression this pins: two starts on one tray left two intervals writing to the same icon on
+    // the same tick — the icon flickered between the two sequences, and the only handle to the first
+    // was a stop function the caller had no reason to still hold.
+    const backend = fakeBackend();
+    setTrayBackend(backend);
+    const tray = createTrayIcon({ icon: 'a0.png' })!;
+    startTrayIconAnimation(tray, ['a0.png', 'a1.png'], 100);
+    startTrayIconAnimation(tray, ['b0.png', 'b1.png'], 100);
+    backend.setIconCalls.length = 0;
+    vi.advanceTimersByTime(100);
+    expect(backend.setIconCalls).toEqual(['b1.png']);
+  });
+
+  it('stops animating a tray that has been destroyed', () => {
+    // The regression this pins: the interval outlived the icon, calling setIcon on a destroyed tray
+    // forever — and the timer kept its own closure alive, so nothing could collect it.
+    const backend = fakeBackend();
+    setTrayBackend(backend);
+    const tray = createTrayIcon({ icon: 'a0.png' })!;
+    startTrayIconAnimation(tray, ['a0.png', 'a1.png'], 100);
+    destroyTrayIcon(tray);
+    backend.setIconCalls.length = 0;
+    vi.advanceTimersByTime(500);
+    expect(backend.setIconCalls).toEqual([]);
+    expect(isTrayIconAnimating(tray)).toBe(false);
+  });
+
+  it('a stale stop function cannot cancel the animation that replaced it', () => {
+    const backend = fakeBackend();
+    setTrayBackend(backend);
+    const tray = createTrayIcon({ icon: 'a0.png' })!;
+    const staleStop = startTrayIconAnimation(tray, ['a0.png', 'a1.png'], 100);
+    startTrayIconAnimation(tray, ['b0.png', 'b1.png'], 100);
+    staleStop();
+    expect(isTrayIconAnimating(tray)).toBe(true);
+    backend.setIconCalls.length = 0;
+    vi.advanceTimersByTime(100);
+    expect(backend.setIconCalls).toEqual(['b1.png']);
+    stopTrayIconAnimation(tray);
+  });
+});
+
+describe('TrayIcon handle identity', () => {
+  afterEach(() => setTrayBackend(null));
+
+  // Documented contract: handles compare by id, never by identity. Pinned so the doc and the behaviour
+  // cannot drift apart, and so anyone who later interns handles has to change this deliberately rather
+  // than discover it. The working form is the id comparison, and it is asserted alongside the failing
+  // one so the test shows the remedy, not just the trap.
+  it('mints a distinct object per call, so handles compare by id rather than identity', () => {
+    const backend = fakeBackend();
+    setTrayBackend(backend);
+    const tray = createTrayIcon()!;
+
+    const listed = getTrayIcons();
+
+    expect(listed.includes(tray)).toBe(false);
+    expect(listed.some((candidate) => candidate.id === tray.id)).toBe(true);
+  });
+});