@flighthq/tray 0.3.1-next.975.01aea94 → 0.4.0-edge.1908.751021c

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-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';
+export { disableTrayGuards, enableTrayGuards, createTrayIcon, destroyTrayIcon, displayTrayBalloon, explainTrayBackend, 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,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"}
+{"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,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 { 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';
+export { disableTrayGuards, enableTrayGuards, createTrayIcon, destroyTrayIcon, displayTrayBalloon, explainTrayBackend, 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,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"}
+{"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,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

@@ -1,20 +1,24 @@
+import type { BackendExplanation } from '@flighthq/types/contract';
 import type { MenuItemTemplate, RectangleLike, TrayBackend, TrayBalloonOptions, TrayCapabilities, TrayEventData, TrayIcon, TrayIconOptions } from '@flighthq/types/contract';
 import type { Vector2Like } from '@flighthq/types/contract';
 export declare function createTrayIcon(options?: Readonly<TrayIconOptions>): TrayIcon | null;
-export declare function createWebTrayBackend(): TrayBackend;
 export declare function destroyTrayIcon(tray: TrayIcon): void;
 export declare function displayTrayBalloon(tray: TrayIcon, options: Readonly<TrayBalloonOptions>): void;
+export declare function explainTrayBackend(): BackendExplanation;
 export declare function getTrayBackend(): TrayBackend;
 export declare function getTrayCapabilities(): Readonly<TrayCapabilities>;
 export declare function getTrayIconBounds(tray: TrayIcon): Readonly<RectangleLike> | null;
 export declare function getTrayIcons(): readonly TrayIcon[];
 export declare function getTrayIconTitle(tray: TrayIcon): string;
 export declare function getTrayIconTooltip(tray: TrayIcon): string;
+export declare function installTrayHostBackend(backend: TrayBackend): void;
 export declare function isTrayDestroyed(tray: TrayIcon): boolean;
 export declare function isTrayIconAnimating(tray: TrayIcon): boolean;
+export declare function observeTrayHostResult(operation: string, succeeded: boolean): void;
 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;
+export declare function resetTrayBackendForTest(): 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. */

package/dist/tray.d.ts.map

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

package/dist/tray.js

@@ -15,77 +15,6 @@ export function createTrayIcon(options) {
     const id = getTrayBackend().create(options ?? {});
     return id < 0 ? null : { id };
 }
-// Builds the default web backend. Web has no system tray, so create returns -1 and the tray mutators
-// are no-ops — a native host (Electron's Tray, Tauri) is required for the tray icon itself. (The
-// application/dock badge lives in @flighthq/app's setAppBadgeCount, not here.)
-export function createWebTrayBackend() {
-    return {
-        create() {
-            // No tray on web. -1 signals "unsupported"; createTrayIcon maps it to null.
-            return -1;
-        },
-        destroy() {
-            // No-op: web has no tray icon to destroy.
-        },
-        displayBalloon() {
-            // No-op: balloon notifications require a native host (Windows only).
-        },
-        getBounds() {
-            // No tray on web; null signals unavailable.
-            return null;
-        },
-        getCapabilities() {
-            return WEB_CAPABILITIES;
-        },
-        getTitle() {
-            // No tray on web.
-            return '';
-        },
-        getTooltip() {
-            // No tray on web.
-            return '';
-        },
-        isDestroyed() {
-            // No tray icons exist on web; treat every id as destroyed.
-            return true;
-        },
-        listIds() {
-            // No tray icons exist on web.
-            return [];
-        },
-        popUpContextMenu() {
-            // No-op: web has no context menu to pop up.
-        },
-        removeBalloon() {
-            // No-op: balloon notifications require a native host (Windows only).
-        },
-        setContextMenu() {
-            // No-op: web has no tray icon — a native host (Electron/Tauri) is required.
-        },
-        setIcon() {
-            // No-op: web has no tray icon to update.
-        },
-        setIgnoreDoubleClickEvents() {
-            // No-op: web has no tray icon double-click behavior to configure.
-        },
-        setPressedIcon() {
-            // No-op: web has no tray icon; pressed icon is macOS-specific.
-        },
-        setTemplate() {
-            // No-op: template images are a macOS menu-bar concept; irrelevant on web.
-        },
-        setTitle() {
-            // No-op: web has no tray icon to update.
-        },
-        setTooltip() {
-            // No-op: web has no tray icon to update.
-        },
-        subscribe() {
-            // No tray on web — a native host (Electron/Tauri) is required to emit tray events.
-            return () => { };
-        },
-    };
-}
 // 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
@@ -100,11 +29,23 @@ export function destroyTrayIcon(tray) {
 export function displayTrayBalloon(tray, options) {
     getTrayBackend().displayBalloon(tray.id, options);
 }
-// The active tray backend, or a lazily-created web default. There is always a backend.
+export function explainTrayBackend() {
+    if (_custom !== null) {
+        return { conflict: _hostConflict, layer: 'custom', operation: null, viability: 'unobserved' };
+    }
+    if (_host !== null) {
+        return {
+            conflict: _hostConflict,
+            layer: 'host',
+            operation: _hostObservation !== null ? _hostObservation.operation : null,
+            viability: _hostObservation !== null ? _hostObservation.viability : 'unobserved',
+        };
+    }
+    return { conflict: false, layer: 'host-not-enabled', operation: null, viability: 'unobserved' };
+}
+// The active tray backend. Precedence: custom > host > sentinel.
 export function getTrayBackend() {
-    if (_backend === null)
-        _backend = createWebTrayBackend();
-    return _backend;
+    return _custom ?? _host ?? _sentinel;
 }
 // Returns the capability flags for the active tray backend. Use before calling APIs that may
 // silently no-op — for example, check capabilities.balloon before displayTrayBalloon, or
@@ -131,6 +72,14 @@ export function getTrayIconTitle(tray) {
 export function getTrayIconTooltip(tray) {
     return getTrayBackend().getTooltip(tray.id);
 }
+export function installTrayHostBackend(backend) {
+    if (_host !== null) {
+        if (_host !== backend)
+            _hostConflict = true;
+        return;
+    }
+    _host = backend;
+}
 // Returns whether a tray icon has been destroyed. Returns true on web (no trays exist).
 // Use this to guard calls after destroyTrayIcon when the tray lifecycle is unclear.
 export function isTrayDestroyed(tray) {
@@ -141,6 +90,12 @@ export function isTrayDestroyed(tray) {
 export function isTrayIconAnimating(tray) {
     return _animations.has(tray.id);
 }
+export function observeTrayHostResult(operation, succeeded) {
+    _hostObservation = {
+        operation,
+        viability: succeeded ? 'available' : 'runtime-api-unavailable',
+    };
+}
 // 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.
@@ -157,15 +112,21 @@ export function popupTrayContextMenu(tray, position) {
 export function removeTrayBalloon(tray) {
     getTrayBackend().removeBalloon(tray.id);
 }
+export function resetTrayBackendForTest() {
+    _custom = null;
+    _host = null;
+    _hostConflict = false;
+    _hostObservation = null;
+}
 /** 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.
+// Installs a custom tray backend; pass null to clear the custom override.
 export function setTrayBackend(backend) {
-    _backend = backend;
+    _custom = backend;
 }
 // Sets the image for the tray icon. Accepts the same icon path/data-URI accepted by createTrayIcon.
 // Use this for runtime status updates (indicators, spinners, theme changes).
@@ -233,7 +194,6 @@ export function startTrayIconAnimation(tray, frames, intervalMs) {
         _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();
@@ -250,4 +210,74 @@ export function stopTrayIconAnimation(tray) {
     _animations.delete(tray.id);
 }
 let _animationGuard = null;
+let _custom = null;
+let _host = null;
+let _hostConflict = false;
+let _hostObservation = null;
+const _sentinel = {
+    create() {
+        // No tray on web. -1 signals "unsupported"; createTrayIcon maps it to null.
+        return -1;
+    },
+    destroy() {
+        // No-op: web has no tray icon to destroy.
+    },
+    displayBalloon() {
+        // No-op: balloon notifications require a native host (Windows only).
+    },
+    getBounds() {
+        // No tray on web; null signals unavailable.
+        return null;
+    },
+    getCapabilities() {
+        return WEB_CAPABILITIES;
+    },
+    getTitle() {
+        // No tray on web.
+        return '';
+    },
+    getTooltip() {
+        // No tray on web.
+        return '';
+    },
+    isDestroyed() {
+        // No tray icons exist on web; treat every id as destroyed.
+        return true;
+    },
+    listIds() {
+        // No tray icons exist on web.
+        return [];
+    },
+    popUpContextMenu() {
+        // No-op: web has no context menu to pop up.
+    },
+    removeBalloon() {
+        // No-op: balloon notifications require a native host (Windows only).
+    },
+    setContextMenu() {
+        // No-op: web has no tray icon — a native host (Electron/Tauri) is required.
+    },
+    setIcon() {
+        // No-op: web has no tray icon to update.
+    },
+    setIgnoreDoubleClickEvents() {
+        // No-op: web has no tray icon double-click behavior to configure.
+    },
+    setPressedIcon() {
+        // No-op: web has no tray icon; pressed icon is macOS-specific.
+    },
+    setTemplate() {
+        // No-op: template images are a macOS menu-bar concept; irrelevant on web.
+    },
+    setTitle() {
+        // No-op: web has no tray icon to update.
+    },
+    setTooltip() {
+        // No-op: web has no tray icon to update.
+    },
+    subscribe() {
+        // No tray on web — a native host (Electron/Tauri) is required to emit tray events.
+        return () => { };
+    },
+};
 //# 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,6 @@
 {
   "name": "@flighthq/tray",
-  "version": "0.3.1-next.975.01aea94",
+  "version": "0.4.0-edge.1908.751021c",
   "author": "Joshua Granick and other contributors",
   "license": "MIT",
   "repository": {
@@ -38,8 +38,8 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/log": "0.3.1-next.975.01aea94",
-    "@flighthq/types": "0.3.1-next.975.01aea94"
+    "@flighthq/log": "0.4.0-edge.1908.751021c",
+    "@flighthq/types": "0.4.0-edge.1908.751021c"
   },
   "devDependencies": {
     "typescript": "^5.3.0"

package/src/tray.test.ts

@@ -10,7 +10,6 @@ import type {
 
 import {
   createTrayIcon,
-  createWebTrayBackend,
   destroyTrayIcon,
   displayTrayBalloon,
   getTrayBackend,
@@ -35,6 +34,10 @@ import {
   setTrayPressedIcon,
   startTrayIconAnimation,
   stopTrayIconAnimation,
+  explainTrayBackend,
+  installTrayHostBackend,
+  observeTrayHostResult,
+  resetTrayBackendForTest,
 } from './tray';
 
 // Fake backend state per icon.
@@ -213,41 +216,6 @@ describe('createTrayIcon', () => {
   });
 });
 
-describe('createWebTrayBackend', () => {
-  it('returns sentinels without throwing (web has no tray)', () => {
-    const backend = createWebTrayBackend();
-    expect(backend.create({})).toBe(-1);
-    expect(() => backend.destroy(0)).not.toThrow();
-    expect(() => backend.setTooltip(0, 'x')).not.toThrow();
-    expect(() => backend.setTitle(0, 'x')).not.toThrow();
-    expect(() => backend.setContextMenu(0, [])).not.toThrow();
-    expect(() => backend.setIcon(0, 'icon.png')).not.toThrow();
-    expect(() => backend.setTemplate(0, true)).not.toThrow();
-    expect(() => backend.setPressedIcon(0, 'pressed.png')).not.toThrow();
-    expect(() => backend.setIgnoreDoubleClickEvents(0, true)).not.toThrow();
-    expect(() => backend.popUpContextMenu(0)).not.toThrow();
-    expect(() => backend.displayBalloon(0, { title: 'T', text: 'B' })).not.toThrow();
-    expect(() => backend.removeBalloon(0)).not.toThrow();
-    expect(backend.getBounds(0)).toBeNull();
-    expect(backend.getTitle(0)).toBe('');
-    expect(backend.getTooltip(0)).toBe('');
-    expect(backend.isDestroyed(0)).toBe(true);
-    expect(backend.listIds()).toEqual([]);
-    expect(typeof backend.subscribe(() => {})).toBe('function');
-  });
-
-  it('web capabilities are all false', () => {
-    const backend = createWebTrayBackend();
-    const caps = backend.getCapabilities();
-    expect(caps.balloon).toBe(false);
-    expect(caps.bounds).toBe(false);
-    expect(caps.clickEvents).toBe(false);
-    expect(caps.dropFiles).toBe(false);
-    expect(caps.pressedIcon).toBe(false);
-    expect(caps.title).toBe(false);
-  });
-});
-
 describe('destroyTrayIcon', () => {
   it('destroys the tray via the active backend', () => {
     const backend = fakeBackend();
@@ -289,6 +257,34 @@ describe('displayTrayBalloon', () => {
   });
 });
 
+describe('explainTrayBackend', () => {
+  afterEach(() => resetTrayBackendForTest());
+
+  it('reports host-not-enabled when no backend is installed', () => {
+    resetTrayBackendForTest();
+    const explanation = explainTrayBackend();
+    expect(explanation.layer).toBe('host-not-enabled');
+    expect(explanation.conflict).toBe(false);
+    expect(explanation.viability).toBe('unobserved');
+  });
+
+  it('reports custom layer when a custom backend is set', () => {
+    setTrayBackend(fakeBackend());
+    expect(explainTrayBackend().layer).toBe('custom');
+  });
+
+  it('reports host layer when a host backend is installed', () => {
+    installTrayHostBackend(fakeBackend());
+    expect(explainTrayBackend().layer).toBe('host');
+  });
+
+  it('reports conflict when two different host backends are installed', () => {
+    installTrayHostBackend(fakeBackend());
+    installTrayHostBackend(fakeBackend());
+    expect(explainTrayBackend().conflict).toBe(true);
+  });
+});
+
 describe('getTrayBackend', () => {
   it('falls back to a web backend', () => {
     expect(getTrayBackend()).not.toBeNull();
@@ -301,6 +297,41 @@ describe('getTrayBackend', () => {
   });
 });
 
+describe('getTrayBackend (sentinel)', () => {
+  it('returns sentinels without throwing (web has no tray)', () => {
+    const backend = getTrayBackend();
+    expect(backend.create({})).toBe(-1);
+    expect(() => backend.destroy(0)).not.toThrow();
+    expect(() => backend.setTooltip(0, 'x')).not.toThrow();
+    expect(() => backend.setTitle(0, 'x')).not.toThrow();
+    expect(() => backend.setContextMenu(0, [])).not.toThrow();
+    expect(() => backend.setIcon(0, 'icon.png')).not.toThrow();
+    expect(() => backend.setTemplate(0, true)).not.toThrow();
+    expect(() => backend.setPressedIcon(0, 'pressed.png')).not.toThrow();
+    expect(() => backend.setIgnoreDoubleClickEvents(0, true)).not.toThrow();
+    expect(() => backend.popUpContextMenu(0)).not.toThrow();
+    expect(() => backend.displayBalloon(0, { title: 'T', text: 'B' })).not.toThrow();
+    expect(() => backend.removeBalloon(0)).not.toThrow();
+    expect(backend.getBounds(0)).toBeNull();
+    expect(backend.getTitle(0)).toBe('');
+    expect(backend.getTooltip(0)).toBe('');
+    expect(backend.isDestroyed(0)).toBe(true);
+    expect(backend.listIds()).toEqual([]);
+    expect(typeof backend.subscribe(() => {})).toBe('function');
+  });
+
+  it('sentinel capabilities are all false', () => {
+    const backend = getTrayBackend();
+    const caps = backend.getCapabilities();
+    expect(caps.balloon).toBe(false);
+    expect(caps.bounds).toBe(false);
+    expect(caps.clickEvents).toBe(false);
+    expect(caps.dropFiles).toBe(false);
+    expect(caps.pressedIcon).toBe(false);
+    expect(caps.title).toBe(false);
+  });
+});
+
 describe('getTrayCapabilities', () => {
   it('returns capabilities from the active backend', () => {
     const backend = fakeBackend({ balloon: true, bounds: false });
@@ -385,6 +416,25 @@ describe('getTrayIconTooltip', () => {
   });
 });
 
+describe('installTrayHostBackend', () => {
+  afterEach(() => resetTrayBackendForTest());
+
+  it('installs a host backend that getTrayBackend returns', () => {
+    const backend = fakeBackend();
+    installTrayHostBackend(backend);
+    expect(getTrayBackend()).toBe(backend);
+  });
+
+  it('is first-host-wins: a second different backend sets conflict', () => {
+    const first = fakeBackend();
+    const second = fakeBackend();
+    installTrayHostBackend(first);
+    installTrayHostBackend(second);
+    expect(getTrayBackend()).toBe(first);
+    expect(explainTrayBackend().conflict).toBe(true);
+  });
+});
+
 describe('isTrayDestroyed', () => {
   it('returns false for a live tray', () => {
     const backend = fakeBackend();
@@ -443,6 +493,24 @@ describe('isTrayIconAnimating', () => {
   });
 });
 
+describe('observeTrayHostResult', () => {
+  afterEach(() => resetTrayBackendForTest());
+
+  it('records a successful observation', () => {
+    installTrayHostBackend(fakeBackend());
+    observeTrayHostResult('create', true);
+    const explanation = explainTrayBackend();
+    expect(explanation.operation).toBe('create');
+    expect(explanation.viability).toBe('available');
+  });
+
+  it('records a failed observation', () => {
+    installTrayHostBackend(fakeBackend());
+    observeTrayHostResult('create', false);
+    expect(explainTrayBackend().viability).toBe('runtime-api-unavailable');
+  });
+});
+
 describe('onTrayEvent', () => {
   it('delivers rich TrayEventData via the active backend', () => {
     const backend = fakeBackend();
@@ -541,6 +609,18 @@ describe('removeTrayBalloon', () => {
   });
 });
 
+describe('resetTrayBackendForTest', () => {
+  it('clears all backend slots', () => {
+    setTrayBackend(fakeBackend());
+    installTrayHostBackend(fakeBackend());
+    observeTrayHostResult('create', true);
+    resetTrayBackendForTest();
+    expect(explainTrayBackend().layer).toBe('host-not-enabled');
+    expect(explainTrayBackend().conflict).toBe(false);
+    expect(explainTrayBackend().viability).toBe('unobserved');
+  });
+});
+
 describe('setTrayAnimationGuard', () => {
   afterEach(() => {
     setTrayAnimationGuard(null);