@omega.js/desktop 0.1.0

package/dist/test/suites/build/renderer-auth-bridge.test.js

@@ -0,0 +1,158 @@
+// Build-layer tests for renderer.js's auth bridge (_wireAuthBridge).
+//
+// The bridge is pure JS — ipc in, ipc out, no DOM — so it runs in plain Node here
+// against the REAL @omega.js/client Auth class (a renderer-layer suite can't: those
+// bodies run inside a BrowserWindow with no require).
+//
+// What's pinned: the sync-request payload carries the signed-in UID. The renderer
+// reads it from the client's auth handle, whose accessor is `getUser()` — an
+// accessor-name drift here is silent (optional chain → undefined → contextUid null),
+// which is exactly how #103 shipped: every renderer boot claimed "signed out" and
+// forced main into a full custom-token round-trip it could have skipped.
+
+const path = require('path');
+
+const { WAKEUP_ROUTE } = require('@omega.js/client/modules/request.js');
+const defineCases = require('../../../vendor/devkit/test/define-cases.js');
+
+const RENDERER_PATH = path.join(__dirname, '..', '..', '..', 'renderer.js');
+const CLIENT_BRIDGE_PATH = path.join(__dirname, '..', '..', '..', 'lib', 'client-bridge.js');
+
+// The real client Auth, wired to a manager stub whose firebaseAuth reports `user`.
+// `_resolveFirebaseConfig` returns an apiKey-less blob so listen() settles immediately
+// with a null user instead of hanging on a Firebase that isn't there.
+async function makeClientAuth(user) {
+  const { default: Auth } = await import('@omega.js/client/modules/auth.js');
+  return new Auth({
+    firebaseAuth: { currentUser: user },
+    _resolveFirebaseConfig: () => ({}),
+  });
+}
+
+// A renderer Manager with the client already booted and an ipc stub whose invoke
+// answers are supplied by `handle`. Returns the manager, the recorded invokes,
+// the recorded backend requests, and the `timeline` of both in the order the
+// bridge produced them — the wakeup ping's whole point is that it is FIRST.
+function makeRenderer(auth, handle) {
+  const Manager = require(RENDERER_PATH);
+  const manager = new Manager();
+  const invokes = [];
+  const requests = [];
+  const timeline = [];
+
+  manager.ipc = {
+    on: () => {},
+    invoke: async (channel, payload) => {
+      invokes.push({ channel, payload });
+      timeline.push(channel);
+      return handle(channel, payload);
+    },
+  };
+  manager.omega = {
+    auth: () => auth,
+    request: async (url, options = {}) => {
+      requests.push({ url, options });
+      timeline.push(options.wakeup ? 'wakeup' : url);
+    },
+  };
+
+  return { manager, invokes, requests, timeline };
+}
+
+module.exports = defineCases({
+  type: 'suite',
+  layer: 'build',
+  description: 'renderer auth bridge — sync-request context UID',
+  tests: [
+    {
+      name: 'the client auth handle exposes getUser() (and no user() accessor)',
+      run: async (ctx) => {
+        const auth = await makeClientAuth({ uid: 'uid-abc', email: 'a@b.co' });
+        ctx.expect(typeof auth.getUser).toBe('function');
+        ctx.expect(auth.getUser().uid).toBe('uid-abc');
+        ctx.expect(auth.user).toBeUndefined();
+      },
+    },
+    {
+      // #644: main answers a sync-request that needs a token by POSTing
+      // /omega/user/token — the app's first backend call, on a function that is
+      // cold at every launch. The ping goes out before the bridge waits on
+      // anything, so the cold start burns down while auth settles.
+      name: 'the bridge warms the backend first, then syncs',
+      run: async (ctx) => {
+        const auth = await makeClientAuth({ uid: 'uid-abc', email: 'a@b.co' });
+        const { manager, requests, timeline } = makeRenderer(auth, () => ({ needsSync: false }));
+
+        await manager._wireAuthBridge();
+
+        ctx.expect(requests.length).toBe(1);
+        ctx.expect(requests[0].url).toBe(WAKEUP_ROUTE);
+        ctx.expect(requests[0].options.wakeup).toBe(true);
+        ctx.expect(timeline[0]).toBe('wakeup');
+        ctx.expect(timeline[1]).toBe('desktop:auth:sync-request');
+      },
+    },
+    {
+      name: 'sync-request carries the signed-in UID as contextUid',
+      run: async (ctx) => {
+        const auth = await makeClientAuth({ uid: 'uid-abc', email: 'a@b.co' });
+        const { manager, invokes } = makeRenderer(auth, () => ({ needsSync: false }));
+
+        await manager._wireAuthBridge();
+
+        const sync = invokes.find((i) => i.channel === 'desktop:auth:sync-request');
+        ctx.expect(sync).toBeDefined();
+        ctx.expect(sync.payload.contextUid).toBe('uid-abc');
+      },
+    },
+    {
+      name: 'sync-request carries null when nobody is signed in',
+      run: async (ctx) => {
+        const auth = await makeClientAuth(null);
+        const { manager, invokes } = makeRenderer(auth, () => ({ needsSync: false }));
+
+        await manager._wireAuthBridge();
+
+        const sync = invokes.find((i) => i.channel === 'desktop:auth:sync-request');
+        ctx.expect(sync.payload.contextUid).toBeNull();
+      },
+    },
+    {
+      name: 'matching UIDs short-circuit against the real main-side handler — no token round-trip',
+      run: async (ctx) => {
+        // Main's side is the REAL client-bridge handler with its auth stubbed to the
+        // same user; the only thing under test is whether the renderer's claim matches.
+        const bridge = require(CLIENT_BRIDGE_PATH);
+        const origAuth = bridge._firebaseAuth;
+        bridge._firebaseAuth = { currentUser: { uid: 'uid-abc' } };
+
+        try {
+          const auth = await makeClientAuth({ uid: 'uid-abc', email: 'a@b.co' });
+          let signIns = 0;
+          let signOuts = 0;
+          auth.signInWithCustomToken = async () => { signIns++; };
+          auth.signOut = async () => { signOuts++; };
+
+          let result = null;
+          const { manager } = makeRenderer(auth, async (channel, payload) => {
+            if (channel !== 'desktop:auth:sync-request') return null;
+            result = await bridge._handleSyncRequest(payload.contextUid);
+            return result;
+          });
+
+          await manager._wireAuthBridge();
+
+          ctx.expect(result.needsSync).toBe(false);
+          // The handler's catch ALSO returns needsSync:false (with an error field), so a
+          // null contextUid falling through to the token fetch would pass the line above —
+          // the absent error is what proves the uid match short-circuited.
+          ctx.expect(result.error).toBeUndefined();
+          ctx.expect(signIns).toBe(0);
+          ctx.expect(signOuts).toBe(0);
+        } finally {
+          bridge._firebaseAuth = origAuth;
+        }
+      },
+    },
+  ],
+});

package/dist/test/suites/build/renderer-entry-key.test.js

@@ -0,0 +1,37 @@
+// The renderer bundle's output key
+// ([#806](https://github.com/Omega-JS-Stack/omega/issues/806)).
+//
+// esbuild writes one `[name].bundle.js` per entry KEY, and the key comes from
+// the path glob hands back for `src/assets/js/components/<name>/index.js`. On
+// Windows glob returns `settings\index.js`, so a derivation that strips a
+// forward-slash `/index.js` leaves EVERY key spelled `index.js`: about, main
+// and settings then all claim `index.js.bundle.js` and the package run dies on
+// "Two output files share the same path but have different contents". The
+// derivation therefore accepts either separator, and the same entry, spelled
+// either way, names the same bundle.
+
+const path = require('path');
+const defineCases = require('../../../vendor/devkit/test/define-cases.js');
+
+const FRAMEWORK_ROOT = path.join(__dirname, '..', '..', '..', '..');
+const { rendererEntryKey } = require(path.join(FRAMEWORK_ROOT, 'src', 'gulp', 'tasks', 'bundle.js'));
+
+module.exports = defineCases({
+  type: 'suite',
+  layer: 'build',
+  description: 'renderer entry keys (#806): one bundle name per component, on every platform',
+  tests: [
+    {
+      name: 'a posix relative path names the component directory',
+      run: (ctx) => {
+        ctx.expect(rendererEntryKey('settings/index.js')).toBe('settings');
+      },
+    },
+    {
+      name: 'the Windows spelling of the same entry names the same bundle',
+      run: (ctx) => {
+        ctx.expect(rendererEntryKey('settings\\index.js')).toBe('settings');
+      },
+    },
+  ],
+});

package/dist/test/suites/build/renderer-node-shims.test.js

@@ -0,0 +1,125 @@
+// The renderer's Node-builtin shim ([#737](https://github.com/Omega-JS-Stack/omega/issues/737)).
+//
+// The renderer runs with contextIsolation on — a browser-like environment with
+// no Node globals — but libraries bundled through @omega.js/client IMPORT `fs`,
+// `path`, `crypto` and friends on code paths their browser builds never take.
+// webpack answered `resolve.fallback: { fs: false, … }`; esbuild has no such
+// option, so the same list goes to @omega.js/devkit's `emptyModulesPlugin`.
+// Without it a renderer build FAILS ("Could not resolve"), which is one half of
+// what this pins. The other half is `electron`: it RESOLVES fine from a desktop
+// project, so a hook that resolved before substituting would inline the real
+// package — the binary launcher, `spawnSync` and all — into the one process
+// that must never reach it.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const FRAMEWORK_ROOT = path.join(__dirname, '..', '..', '..', '..');
+const { bundle } = require('../../../vendor/devkit/bundle.js');
+const { emptyModulesPlugin } = require('../../../vendor/devkit/empty-modules-plugin.js');
+const task = require(path.join(FRAMEWORK_ROOT, 'src', 'gulp', 'tasks', 'bundle.js'));
+const defineCases = require('../../../vendor/devkit/test/define-cases.js');
+
+// A browser bundle of an entry that imports built-ins the way a real library
+// spells them, built with the renderer lane's platform and its shim list.
+async function buildRenderer(source) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'omega-desktop-shims-'));
+  fs.writeFileSync(path.join(dir, 'entry.js'), source);
+  const outfile = path.join(dir, 'dist', 'entry.bundle.js');
+
+  try {
+    await bundle({
+      frameworkRoot: FRAMEWORK_ROOT,
+      entries: [path.join(dir, 'entry.js')],
+      outfile,
+      platform: 'browser',
+      format: 'iife',
+      dev: true,
+      plugins: [emptyModulesPlugin(task.RENDERER_EMPTY_MODULES)],
+    });
+    return fs.readFileSync(outfile, 'utf8');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+module.exports = defineCases({
+  type: 'suite',
+  layer: 'build',
+  description: 'renderer Node-builtin shims — a browser bundle answers the imports webpack fallbacks used to',
+  timeout: 60000,
+  tests: [
+    {
+      name: 'every shimmed name resolves to an empty module instead of failing the build',
+      run: async (ctx) => {
+        const source = task.RENDERER_EMPTY_MODULES
+          .map((name, index) => `import m${index} from '${name}';\nglobalThis.probe${index} = m${index};`)
+          .join('\n');
+        const built = await buildRenderer(source);
+
+        ctx.expect(/require\(["'](node:)?(fs|path|crypto|child_process|electron)["']\)/.test(built)).toBe(false);
+      },
+    },
+
+    {
+      name: 'the `node:` spelling of the same built-in is shimmed too',
+      run: async (ctx) => {
+        const built = await buildRenderer("import fsp from 'node:fs';\nglobalThis.probe = fsp;\n");
+        ctx.expect(/require\(["']node:fs["']\)/.test(built)).toBe(false);
+      },
+    },
+
+    {
+      // The absence of a `require("electron")` call proves nothing on its own —
+      // a hook that RESOLVED electron first would inline its source and leave no
+      // require behind either. These are strings out of electron's own
+      // index.js: the binary launcher, its download shell-out, and the path file
+      // it reads. None of them may appear in a renderer bundle.
+      name: 'electron is SUBSTITUTED, not resolved — none of its launcher source reaches the bundle',
+      run: async (ctx) => {
+        const built = await buildRenderer("import electron from 'electron';\nglobalThis.probe = electron;\n");
+
+        ctx.expect(built.includes('spawnSync')).toBe(false);
+        ctx.expect(built.includes('path.txt')).toBe(false);
+        ctx.expect(built.includes('Downloading Electron binary')).toBe(false);
+        ctx.expect(built.includes('ELECTRON_OVERRIDE_DIST_PATH')).toBe(false);
+      },
+    },
+
+    {
+      name: 'electron is on the list — a renderer reaching the real module is a hole, not a polyfill',
+      run: (ctx) => {
+        ctx.expect(task.RENDERER_EMPTY_MODULES.includes('electron')).toBe(true);
+      },
+    },
+
+    {
+      name: 'a name NOT on the list still fails with the bundler\'s own resolution error',
+      run: async (ctx) => {
+        let error = null;
+        try {
+          await buildRenderer("import 'totally-not-a-node-builtin';\n");
+        } catch (e) {
+          error = e;
+        }
+        ctx.expect(Boolean(error)).toBe(true);
+        ctx.expect(error.message).toContain('totally-not-a-node-builtin');
+      },
+    },
+
+    {
+      name: 'registering the hook with no names throws — a shim that shims nothing is the bug it prevents',
+      run: (ctx) => {
+        let error = null;
+        try {
+          emptyModulesPlugin([]);
+        } catch (e) {
+          error = e;
+        }
+        ctx.expect(Boolean(error)).toBe(true);
+        ctx.expect(error.message).toContain('non-empty array');
+      },
+    },
+  ],
+});

package/dist/test/suites/build/resolve-icons.test.js

@@ -0,0 +1,296 @@
+// Build-layer tests for lib/sign-helpers/resolve-icons.js — convention waterfall
+// (platform > global > linux-via-windows > bundled) + retina derivation.
+
+const path    = require('path');
+const fs      = require('fs');
+const os      = require('os');
+const jetpack = require('fs-jetpack');
+const sharp   = require('sharp');
+const defineCases = require('../../../vendor/devkit/test/define-cases.js');
+
+function stage() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'desktop-icons-'));
+  const projectRoot    = path.join(root, 'project');
+  const distRoot       = path.join(root, 'project', 'dist');
+  const emDefaultsRoot = path.join(root, 'desktop-defaults');
+  jetpack.dir(projectRoot);
+  jetpack.dir(distRoot);
+  jetpack.dir(emDefaultsRoot);
+  return { root, projectRoot, distRoot, emDefaultsRoot };
+}
+
+// Emit a real PNG so sharp can read metadata (used for retina slots).
+async function realPng(p, width, height) {
+  jetpack.dir(path.dirname(p));
+  await sharp({
+    create: { width, height, channels: 4, background: { r: 0, g: 0, b: 0, alpha: 1 } },
+  }).png().toFile(p);
+}
+
+// Minimal PNG signature for slots that don't need sharp metadata (non-retina).
+function fakePng(p) {
+  jetpack.dir(path.dirname(p));
+  fs.writeFileSync(p, Buffer.from([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A]));
+}
+
+module.exports = defineCases({
+  type: 'suite',
+  layer: 'build',
+  description: 'resolve-icons — convention waterfall + retina derivation',
+  tests: [
+    {
+      name: 'falls back to @omega.js/desktop bundled defaults when consumer has nothing',
+      run: async (ctx) => {
+        const { root, projectRoot, distRoot, emDefaultsRoot } = stage();
+        try {
+          fakePng(path.join(emDefaultsRoot, 'icons', 'macos', 'icon.png'));
+          fakePng(path.join(emDefaultsRoot, 'icons', 'windows', 'icon.png'));
+
+          const { resolveAndCopy } = require(path.join(__dirname, '..', '..', '..', 'lib', 'sign-helpers', 'resolve-icons.js'));
+          const out = await resolveAndCopy({ config: {}, projectRoot, distRoot, emDefaultsRoot });
+
+          ctx.expect(out.macos.app).toBe(path.join(distRoot, 'config', 'icons', 'macos', 'icon.png'));
+          ctx.expect(out.windows.app).toBe(path.join(distRoot, 'config', 'icons', 'windows', 'icon.png'));
+          ctx.expect(jetpack.exists(out.macos.app)).toBeTruthy();
+          ctx.expect(jetpack.exists(out.windows.app)).toBeTruthy();
+        } finally {
+          fs.rmSync(root, { recursive: true, force: true });
+        }
+      },
+    },
+    {
+      name: 'platform-specific override beats bundled default',
+      run: async (ctx) => {
+        const { root, projectRoot, distRoot, emDefaultsRoot } = stage();
+        try {
+          fakePng(path.join(emDefaultsRoot, 'icons', 'macos', 'icon.png'));
+          const consumerIcon = path.join(projectRoot, 'config', 'icons', 'macos', 'icon.png');
+          fakePng(consumerIcon);
+          fs.writeFileSync(consumerIcon, Buffer.from('consumer-bytes'));
+
+          const { resolveAndCopy } = require(path.join(__dirname, '..', '..', '..', 'lib', 'sign-helpers', 'resolve-icons.js'));
+          const out = await resolveAndCopy({ config: {}, projectRoot, distRoot, emDefaultsRoot });
+
+          const bytes = fs.readFileSync(out.macos.app);
+          ctx.expect(bytes.toString()).toBe('consumer-bytes');
+        } finally {
+          fs.rmSync(root, { recursive: true, force: true });
+        }
+      },
+    },
+    {
+      name: 'global/ fallback covers all platforms when no platform-specific override exists',
+      run: async (ctx) => {
+        const { root, projectRoot, distRoot, emDefaultsRoot } = stage();
+        try {
+          // Bundled defaults exist for all three platforms — but consumer-global wins.
+          fakePng(path.join(emDefaultsRoot, 'icons', 'macos', 'icon.png'));
+          fakePng(path.join(emDefaultsRoot, 'icons', 'windows', 'icon.png'));
+
+          // Consumer ships ONE file at the global path. All three platforms pick it up.
+          const globalIcon = path.join(projectRoot, 'config', 'icons', 'global', 'icon.png');
+          fakePng(globalIcon);
+          fs.writeFileSync(globalIcon, Buffer.from('global-bytes'));
+
+          const { resolveAndCopy } = require(path.join(__dirname, '..', '..', '..', 'lib', 'sign-helpers', 'resolve-icons.js'));
+          const out = await resolveAndCopy({ config: {}, projectRoot, distRoot, emDefaultsRoot });
+
+          for (const platform of ['macos', 'windows', 'linux']) {
+            ctx.expect(out[platform].app).toBeDefined();
+            const bytes = fs.readFileSync(out[platform].app);
+            ctx.expect(bytes.toString()).toBe('global-bytes');
+          }
+        } finally {
+          fs.rmSync(root, { recursive: true, force: true });
+        }
+      },
+    },
+    {
+      name: 'platform-specific override beats global fallback',
+      run: async (ctx) => {
+        const { root, projectRoot, distRoot, emDefaultsRoot } = stage();
+        try {
+          fakePng(path.join(emDefaultsRoot, 'icons', 'windows', 'icon.png'));
+
+          // Global file exists.
+          const globalIcon = path.join(projectRoot, 'config', 'icons', 'global', 'icon.png');
+          fakePng(globalIcon);
+          fs.writeFileSync(globalIcon, Buffer.from('global-bytes'));
+
+          // Mac-specific override exists — should win for macOS.
+          const macIcon = path.join(projectRoot, 'config', 'icons', 'macos', 'icon.png');
+          fakePng(macIcon);
+          fs.writeFileSync(macIcon, Buffer.from('mac-specific-bytes'));
+
+          const { resolveAndCopy } = require(path.join(__dirname, '..', '..', '..', 'lib', 'sign-helpers', 'resolve-icons.js'));
+          const out = await resolveAndCopy({ config: {}, projectRoot, distRoot, emDefaultsRoot });
+
+          ctx.expect(fs.readFileSync(out.macos.app).toString()).toBe('mac-specific-bytes');
+          ctx.expect(fs.readFileSync(out.windows.app).toString()).toBe('global-bytes');
+          ctx.expect(fs.readFileSync(out.linux.app).toString()).toBe('global-bytes');
+        } finally {
+          fs.rmSync(root, { recursive: true, force: true });
+        }
+      },
+    },
+    {
+      name: 'Windows tray falls back to Windows app icon when no tray.png exists',
+      run: async (ctx) => {
+        const { root, projectRoot, distRoot, emDefaultsRoot } = stage();
+        try {
+          fakePng(path.join(emDefaultsRoot, 'icons', 'windows', 'icon.png'));
+          // No windows/tray.png anywhere.
+
+          const { resolveAndCopy } = require(path.join(__dirname, '..', '..', '..', 'lib', 'sign-helpers', 'resolve-icons.js'));
+          const out = await resolveAndCopy({ config: {}, projectRoot, distRoot, emDefaultsRoot });
+
+          ctx.expect(out.windows.tray).toBeDefined();
+          ctx.expect(out.windows.tray).toBe(out.windows.app);
+        } finally {
+          fs.rmSync(root, { recursive: true, force: true });
+        }
+      },
+    },
+    {
+      name: 'Linux resolves through Windows bundled defaults when no Linux source exists',
+      run: async (ctx) => {
+        const { root, projectRoot, distRoot, emDefaultsRoot } = stage();
+        try {
+          fakePng(path.join(emDefaultsRoot, 'icons', 'windows', 'icon.png'));
+          // No Linux bundled dir anywhere — Linux must walk the chain through Windows bundled.
+
+          const { resolveAndCopy } = require(path.join(__dirname, '..', '..', '..', 'lib', 'sign-helpers', 'resolve-icons.js'));
+          const out = await resolveAndCopy({ config: {}, projectRoot, distRoot, emDefaultsRoot });
+
+          // Linux gets its own dist path (icon copied INTO linux/), populated from the
+          // Windows bundled source.
+          ctx.expect(out.linux.app).toBe(path.join(distRoot, 'config', 'icons', 'linux', 'icon.png'));
+          ctx.expect(jetpack.exists(out.linux.app)).toBeTruthy();
+          // Tray: no tray source anywhere → linux.tray falls back to windows.tray, which
+          // itself fell back to windows.app (the Windows-tray-to-Windows-app special case).
+          ctx.expect(out.linux.tray).toBe(out.windows.app);
+        } finally {
+          fs.rmSync(root, { recursive: true, force: true });
+        }
+      },
+    },
+    {
+      name: 'Linux: consumer windows/ override beats bundled (legacy linux→windows fallback)',
+      run: async (ctx) => {
+        const { root, projectRoot, distRoot, emDefaultsRoot } = stage();
+        try {
+          fakePng(path.join(emDefaultsRoot, 'icons', 'linux', 'icon.png'));
+          // No bundled linux defaults; consumer ships a windows/ override.
+          const winIcon = path.join(projectRoot, 'config', 'icons', 'windows', 'icon.png');
+          fakePng(winIcon);
+          fs.writeFileSync(winIcon, Buffer.from('win-consumer-bytes'));
+
+          const { resolveAndCopy } = require(path.join(__dirname, '..', '..', '..', 'lib', 'sign-helpers', 'resolve-icons.js'));
+          const out = await resolveAndCopy({ config: {}, projectRoot, distRoot, emDefaultsRoot });
+
+          // Linux pulled from the consumer's windows/ dir (legacy fallback), not bundled linux/.
+          ctx.expect(fs.readFileSync(out.linux.app).toString()).toBe('win-consumer-bytes');
+        } finally {
+          fs.rmSync(root, { recursive: true, force: true });
+        }
+      },
+    },
+    {
+      name: 'retina slots: source treated as @2x, @1x derived at half size',
+      run: async (ctx) => {
+        const { root, projectRoot, distRoot, emDefaultsRoot } = stage();
+        try {
+          fakePng(path.join(emDefaultsRoot, 'icons', 'macos', 'icon.png'));
+          // Input source files at retina (native) size. @omega.js/desktop should emit both @1x + @2x in dist.
+          // Tray input is `tray.png`; @omega.js/desktop renames the dist output to `trayTemplate.png` (macOS magic).
+          await realPng(path.join(emDefaultsRoot, 'icons', 'macos', 'tray.png'), 32, 32);
+          await realPng(path.join(emDefaultsRoot, 'icons', 'macos', 'dmg.png'), 1080, 760);
+
+          const { resolveAndCopy } = require(path.join(__dirname, '..', '..', '..', 'lib', 'sign-helpers', 'resolve-icons.js'));
+          const out = await resolveAndCopy({ config: {}, projectRoot, distRoot, emDefaultsRoot });
+
+          // Both @1x and @2x slots populated.
+          ctx.expect(out.macos.tray).toBeDefined();
+          ctx.expect(out.macos.tray2x).toBeDefined();
+          ctx.expect(out.macos.dmg).toBeDefined();
+          ctx.expect(out.macos.dmg2x).toBeDefined();
+          // app slot has no retina flag.
+          ctx.expect(out.macos.app2x).toBeUndefined();
+
+          // Tray output filename is trayTemplate.png (renamed for macOS auto-inversion magic).
+          ctx.expect(path.basename(out.macos.tray)).toBe('trayTemplate.png');
+          ctx.expect(path.basename(out.macos.tray2x)).toBe('trayTemplate@2x.png');
+
+          // @1x derived at half the @2x dimensions.
+          const tray1xMeta = await sharp(out.macos.tray).metadata();
+          const tray2xMeta = await sharp(out.macos.tray2x).metadata();
+          ctx.expect(tray1xMeta.width).toBe(16);
+          ctx.expect(tray1xMeta.height).toBe(16);
+          ctx.expect(tray2xMeta.width).toBe(32);
+          ctx.expect(tray2xMeta.height).toBe(32);
+
+          const dmg1xMeta = await sharp(out.macos.dmg).metadata();
+          const dmg2xMeta = await sharp(out.macos.dmg2x).metadata();
+          ctx.expect(dmg1xMeta.width).toBe(540);
+          ctx.expect(dmg1xMeta.height).toBe(380);
+          ctx.expect(dmg2xMeta.width).toBe(1080);
+          ctx.expect(dmg2xMeta.height).toBe(760);
+        } finally {
+          fs.rmSync(root, { recursive: true, force: true });
+        }
+      },
+    },
+    {
+      name: 'consumer single-file retina source overrides bundled default',
+      run: async (ctx) => {
+        const { root, projectRoot, distRoot, emDefaultsRoot } = stage();
+        try {
+          fakePng(path.join(emDefaultsRoot, 'icons', 'macos', 'icon.png'));
+          await realPng(path.join(emDefaultsRoot, 'icons', 'macos', 'tray.png'), 32, 32);
+          // Consumer ships ONE file as `tray.png` (at @2x native size).
+          const consumerTray = path.join(projectRoot, 'config', 'icons', 'macos', 'tray.png');
+          await realPng(consumerTray, 32, 32);
+
+          const { resolveAndCopy } = require(path.join(__dirname, '..', '..', '..', 'lib', 'sign-helpers', 'resolve-icons.js'));
+          const out = await resolveAndCopy({ config: {}, projectRoot, distRoot, emDefaultsRoot });
+
+          ctx.expect(out.macos.tray).toBeDefined();
+          ctx.expect(out.macos.tray2x).toBeDefined();
+          // Output is still trayTemplate.png regardless of input name.
+          ctx.expect(path.basename(out.macos.tray)).toBe('trayTemplate.png');
+          const tray1xMeta = await sharp(out.macos.tray).metadata();
+          ctx.expect(tray1xMeta.width).toBe(16);
+        } finally {
+          fs.rmSync(root, { recursive: true, force: true });
+        }
+      },
+    },
+    {
+      name: 'global/ retina source covers all platforms (tray)',
+      run: async (ctx) => {
+        const { root, projectRoot, distRoot, emDefaultsRoot } = stage();
+        try {
+          fakePng(path.join(emDefaultsRoot, 'icons', 'macos', 'icon.png'));
+          fakePng(path.join(emDefaultsRoot, 'icons', 'windows', 'icon.png'));
+
+          // Consumer ships ONE tray file under global/.
+          await realPng(path.join(projectRoot, 'config', 'icons', 'global', 'tray.png'), 32, 32);
+
+          const { resolveAndCopy } = require(path.join(__dirname, '..', '..', '..', 'lib', 'sign-helpers', 'resolve-icons.js'));
+          const out = await resolveAndCopy({ config: {}, projectRoot, distRoot, emDefaultsRoot });
+
+          ctx.expect(out.macos.tray).toBeDefined();
+          ctx.expect(out.macos.tray2x).toBeDefined();
+          ctx.expect(out.windows.tray).toBeDefined();
+          ctx.expect(out.linux.tray).toBeDefined();
+
+          // macOS @1x derived at half size from the global @2x source.
+          const macTrayMeta = await sharp(out.macos.tray).metadata();
+          ctx.expect(macTrayMeta.width).toBe(16);
+        } finally {
+          fs.rmSync(root, { recursive: true, force: true });
+        }
+      },
+    },
+  ],
+});