@omega.js/desktop 0.1.0

package/dist/lib/startup.js

@@ -0,0 +1,214 @@
+// Startup — open-at-login + launch-mode management.
+//
+// Two independent things this lib controls:
+//
+// 1. `startup.mode` — how the app launches when the USER opens it directly:
+//      normal — default. Dock icon visible on macOS, taskbar entry on Windows.
+//      hidden — packaged builds get LSUIElement=true on macOS (zero dock bounce, no
+//               dock icon, not in Cmd+Tab). Tray/notifications/networking still work.
+//               Consumer surfaces UI later via `manager.windows.create('main')`, which
+//               calls app.dock.show() automatically so the icon appears alongside the
+//               window. Use this for menubar apps, agent apps, anything that should
+//               be invisible until the user explicitly asks for UI.
+//
+// 2. `startup.openAtLogin` — what the OS does at user login:
+//      enabled (default true)     — register the app to auto-launch at login.
+//      mode    (default 'hidden') — what mode the app launches in WHEN OS-launched.
+//                                   Independent from the user-launch mode above.
+//
+// @omega.js/desktop does NOT auto-create any windows anymore — the consumer's main.js drives that.
+// So "isLaunchHidden" no longer needs to gate window creation; we just expose the
+// raw mode and let the consumer decide whether to call `manager.windows.create()`.
+//
+// Detection: macOS sets `getLoginItemSettings().wasOpenedAtLogin = true`. On Windows we
+// register the login item with `--omega-launched-at-login` arg and check process.argv.
+// On Linux there's no standard signal, so we treat all launches as user-launches.
+
+const LoggerLite = require('./logger-lite.js');
+
+const logger = new LoggerLite('startup');
+
+// Valid startup modes. `tray-only` is now folded into `hidden` (they were always the
+// same idea — LSUIElement on macOS — so we collapse to a single name).
+const VALID_MODES = ['normal', 'hidden'];
+const LOGIN_ARG   = '--omega-launched-at-login';   // marker for Windows + Linux login-launch detection
+
+const startup = {
+  _initialized: false,
+  _manager:     null,
+  _electron:    null,
+
+  initialize(manager) {
+    if (startup._initialized) {
+      return;
+    }
+
+    startup._manager = manager;
+    startup._electron = require('electron');
+
+    const mode         = startup.getMode();
+    const loginEnabled = startup._loginEnabled();
+    const loginMode    = startup._loginMode();
+    const isDev        = startup._isDev();
+
+    // In dev, force open-at-login OFF regardless of config. And actively UNSET any prior
+    // registration so a dev run that previously ran with config:enabled=true doesn't leave
+    // electron.app (or worse, a stale dev binary path) trying to launch every login.
+    // Otherwise: sync the OS open-at-login flag with config. Pass --omega-launched-at-login
+    // in args so we can detect login launches reliably on Windows/Linux (macOS exposes
+    // wasOpenedAtLogin natively).
+    if (isDev) {
+      startup._electron.app.setLoginItemSettings({
+        openAtLogin:  false,
+        openAsHidden: false,
+        args:         [],
+      });
+    } else {
+      startup._electron.app.setLoginItemSettings({
+        openAtLogin:  loginEnabled,
+        openAsHidden: loginMode === 'hidden',
+        args:         loginEnabled ? [LOGIN_ARG] : [],
+      });
+    }
+
+    // Boot summary — RAW inputs (what the OS/shell gave us) + RESOLVED values (what @omega.js/desktop
+    // decided to act on). Two parallel blocks so you can debug in either direction:
+    //   "Why is @omega.js/desktop behaving like X?" → check resolved values
+    //   "Why did @omega.js/desktop decide X?" → check raw inputs
+    const macLogin = process.platform === 'darwin' ? startup._electron.app.getLoginItemSettings() : null;
+    const emEnv = Object.fromEntries(
+      Object.entries(process.env).filter(([k]) => k.startsWith('EM_') || k === 'ELECTRON_RUN_AS_NODE' || k === 'NODE_ENV')
+    );
+    const launchedAtLogin = startup.wasLaunchedAtLogin();
+    const launchedAtLoginVia = startup._launchedAtLoginVia();
+    const isHidden = startup.isLaunchHidden();
+
+    logger.log('startup boot summary — RAW inputs:');
+    logger.log(`  process.argv:            ${JSON.stringify(process.argv.slice(1))}`);
+    logger.log(`  process.platform:        ${process.platform}`);
+    logger.log(`  process.arch:            ${process.arch}`);
+    logger.log(`  app.isPackaged:          ${startup._electron.app.isPackaged}`);
+    logger.log(`  app.getLoginItemSettings(): ${macLogin ? JSON.stringify(macLogin) : '(not macOS)'}`);
+    logger.log(`  EM_/electron/node env:   ${JSON.stringify(emEnv)}`);
+
+    logger.log('startup boot summary — RESOLVED values:');
+    logger.log(`  config.startup.mode:     ${mode}`);
+    logger.log(`  config.startup.openAtLogin: ${isDev ? 'OFF (dev — config ignored)' : `{enabled:${loginEnabled}, mode:${loginMode}}`}`);
+    logger.log(`  isDev:                   ${isDev}`);
+    logger.log(`  hasLoginArg:             ${process.argv.includes(LOGIN_ARG)}`);
+    logger.log(`  wasLaunchedAtLogin():    ${launchedAtLogin}${launchedAtLogin ? ` (via ${launchedAtLoginVia})` : ''}`);
+    logger.log(`  isLaunchHidden():        ${isHidden}`);
+    startup._initialized = true;
+  },
+
+  // Internal: report HOW we determined this launch was at login. Used by initialize logging
+  // to distinguish "fake login via --omega-launched-at-login flag" from "real macOS at-login".
+  _launchedAtLoginVia() {
+    if (process.argv.includes(LOGIN_ARG)) return 'argv-flag';
+    if (process.platform === 'darwin' && startup._electron.app.getLoginItemSettings().wasOpenedAtLogin) {
+      return 'macos-wasOpenedAtLogin';
+    }
+    return 'none';
+  },
+
+  // Should we suppress login-item changes? Suppressed in any non-production run (dev OR
+  // testing) so we never touch the real user's OS login items outside a packaged build.
+  // OMEGA_FORCE_LOGIN_ITEM=1 bypasses the guard so you can intentionally exercise the flow.
+  _isDev() {
+    if (process.env.OMEGA_FORCE_LOGIN_ITEM === '1') return false;
+    return !startup._manager.isProduction();
+  },
+
+  // Returns the resolved user-launch mode, defaulting to 'normal' for unknown values.
+  getMode() {
+    const raw = startup._manager.config.startup?.mode || 'normal';
+    return VALID_MODES.includes(raw) ? raw : 'normal';
+  },
+
+  // openAtLogin block reads. `_loginEnabled` defaults to true; `_loginMode` defaults to 'hidden'.
+  _loginEnabled() {
+    const v = startup._manager.config.startup?.openAtLogin;
+    if (typeof v === 'boolean') return v;                          // back-compat for boolean form
+    if (v && typeof v === 'object') return v.enabled !== false;    // object form: default true
+    return true;                                                   // unset → true (apps open at login by default)
+  },
+
+  _loginMode() {
+    const v = startup._manager.config.startup?.openAtLogin;
+    if (v && typeof v === 'object' && VALID_MODES.includes(v.mode)) return v.mode;
+    return 'hidden';                                               // default: launch hidden at login
+  },
+
+  // True if this launch is hidden — combines user-launch mode (always honored) with
+  // login-launch mode (only honored when the app was launched at login). Consumers can
+  // read this to decide whether to call manager.windows.create() during boot.
+  isLaunchHidden() {
+    if (startup.getMode() === 'hidden') return true;
+    if (startup.wasLaunchedAtLogin() && startup._loginMode() === 'hidden') return true;
+    return false;
+  },
+
+  // Did the OS launch us at login (vs the user opening the app directly)?
+  // macOS: getLoginItemSettings().wasOpenedAtLogin.
+  // Windows/Linux: we registered with LOGIN_ARG, look for it in argv.
+  wasLaunchedAtLogin() {
+    if (process.argv.includes(LOGIN_ARG)) return true;
+    if (process.platform === 'darwin') {
+      return Boolean(startup._electron.app.getLoginItemSettings().wasOpenedAtLogin);
+    }
+    return false;
+  },
+
+  // Apply the runtime side of the mode (dock.hide for macOS). Called from main.js
+  // BEFORE whenReady so the dock animation is suppressed as early as JS allows.
+  // Note: in packaged tray-only builds the plist already prevents the dock entry,
+  // so this call is a no-op there. In dev or hidden mode it shaves the visible time.
+  applyEarly() {
+    if (!startup._electron) return;
+    if (process.platform !== 'darwin') return;
+    if (!startup.isLaunchHidden()) return;
+
+    startup._electron.app.dock.hide();
+  },
+
+  // Public mutators
+
+  // Toggle the OS open-at-login flag. Pass a boolean for back-compat, or an object
+  // { enabled, mode } to control both. Persists via setLoginItemSettings; does not mutate config.
+  // No-op in dev (no packaged build = no point registering electron.app for login-launch).
+  setOpenAtLogin(input) {
+    if (startup._isDev()) {
+      logger.log('setOpenAtLogin ignored — running in dev mode (set OMEGA_FORCE_LOGIN_ITEM=1 to override)');
+      return;
+    }
+
+    let enabled;
+    let openAsHidden;
+    if (typeof input === 'boolean') {
+      enabled      = input;
+      openAsHidden = startup._loginMode() !== 'normal';
+    } else if (input && typeof input === 'object') {
+      enabled      = input.enabled !== false;
+      const mode   = VALID_MODES.includes(input.mode) ? input.mode : startup._loginMode();
+      openAsHidden = mode === 'hidden';
+    } else {
+      enabled      = true;
+      openAsHidden = startup._loginMode() !== 'normal';
+    }
+
+    startup._electron.app.setLoginItemSettings({
+      openAtLogin:  enabled,
+      openAsHidden,
+      args:         enabled ? [LOGIN_ARG] : [],
+    });
+    logger.log(`setOpenAtLogin → enabled=${enabled} openAsHidden=${openAsHidden}`);
+  },
+
+  // Read the current OS open-at-login state (may differ from config if user changed it
+  // via System Settings; useful for keeping a settings UI in sync).
+  isOpenAtLogin() {
+    return Boolean(startup._electron.app.getLoginItemSettings().openAtLogin);
+  },
+};
+
+module.exports = startup;

package/dist/lib/storage.js

@@ -0,0 +1,193 @@
+// Storage — unified KV store for main + renderer.
+//
+// Main-side (sync, direct disk-backed via electron-store):
+//   manager.storage.get(key, default)
+//   manager.storage.set(key, value)
+//   manager.storage.delete(key)
+//   manager.storage.has(key)
+//   manager.storage.clear()
+//   manager.storage.onChange(key, fn)  // returns unsubscribe fn
+//
+// Renderer-side (async, proxied through preload contextBridge → IPC → main):
+//   window.desktop.storage.get(key, default)   → Promise
+//   window.desktop.storage.set(key, value)     → Promise
+//   etc.
+//
+// Key paths support dot-notation (e.g. 'window.main.bounds') natively via electron-store.
+//
+// Storage file lives at:
+//   macOS:   ~/Library/Application Support/<productName>/config.json
+//   Windows: %APPDATA%/<productName>/config.json
+//   Linux:   ~/.config/<productName>/config.json
+
+const LoggerLite = require('./logger-lite.js');
+const ipc = require('./ipc.js');
+
+const logger = new LoggerLite('storage');
+
+const storage = {
+  _initialized: false,
+  _manager:     null,
+  _store:       null,
+  _changeSubs:  {}, // key -> Set<fn>
+  _ipcRegistered: false,
+
+  async initialize(manager) {
+    if (storage._initialized) {
+      return;
+    }
+
+    storage._manager = manager;
+
+    let ElectronStore;
+    try {
+      // electron-store is ESM-only. The STATIC specifier is what matters: the
+      // bundler inlines it INTO main.bundle.js (no lazy chunk, no runtime
+      // resolution) — packaged consumers need nothing installed. Unbundled
+      // (@omega.js/desktop's own harness), Node resolves it from
+      // @omega.js/desktop's node_modules. Pinned by
+      // src/test/suites/boot/storage-bundled.test.js.
+      const mod = await import('electron-store');
+      ElectronStore = mod.default || mod;
+    } catch (e) {
+      logger.warn(`electron-store not available — storage running as no-op. (${e.message})`);
+      storage._initialized = true;
+      return;
+    }
+    const electron = require('electron');
+
+    // Build the store. Filename is `omega-storage.json` (electron-store appends .json).
+    // Production name is read from electron's app.name (set automatically from package.productName).
+    const projectName = manager.config.app?.productName || electron.app.getName();
+
+    storage._store = new ElectronStore({
+      name: 'omega-storage',
+      // electron-store handles the cwd; no need to override unless we want a custom path.
+    });
+
+    logger.log(`initialize — file=${storage._store.path} (project=${projectName})`);
+
+    // Register main-side IPC handlers so the renderer proxy works.
+    storage._registerIpc();
+
+    storage._initialized = true;
+  },
+
+  _registerIpc() {
+    if (storage._ipcRegistered) {
+      return;
+    }
+
+    if (!ipc._initialized) {
+      // ipc is initialized before storage in the boot sequence; if we're here, ipc is unavailable
+      // (e.g. running outside electron). Skip silently — main-side API still works.
+      return;
+    }
+
+    ipc.handle('desktop:storage:get',    ({ key, def }) => storage.get(key, def));
+    ipc.handle('desktop:storage:set',    ({ key, val }) => { storage.set(key, val); return true; });
+    ipc.handle('desktop:storage:delete', ({ key })      => { storage.delete(key); return true; });
+    ipc.handle('desktop:storage:has',    ({ key })      => storage.has(key));
+    ipc.handle('desktop:storage:clear',  ()             => { storage.clear(); return true; });
+
+    storage._ipcRegistered = true;
+  },
+
+  // Main-side public API
+  get(key, defaultValue) {
+    if (!storage._store) {
+      return defaultValue;
+    }
+    const value = storage._store.get(key);
+    return value === undefined ? defaultValue : value;
+  },
+
+  set(key, value) {
+    if (!storage._store) {
+      return;
+    }
+    const previous = storage._store.get(key);
+    storage._store.set(key, value);
+
+    // Notify subscribers
+    const subs = storage._changeSubs[key];
+    if (subs) {
+      subs.forEach((fn) => {
+        try {
+          fn(value, previous);
+        } catch (e) {
+          logger.error('onChange subscriber threw:', e);
+        }
+      });
+    }
+
+    // Broadcast change to all renderers so renderer caches can invalidate.
+    storage._broadcast(key, value, previous);
+  },
+
+  delete(key) {
+    if (!storage._store) {
+      return;
+    }
+    const previous = storage._store.get(key);
+    storage._store.delete(key);
+
+    const subs = storage._changeSubs[key];
+    if (subs) {
+      subs.forEach((fn) => {
+        try {
+          fn(undefined, previous);
+        } catch (e) {
+          logger.error('onChange subscriber threw:', e);
+        }
+      });
+    }
+
+    storage._broadcast(key, undefined, previous);
+  },
+
+  has(key) {
+    if (!storage._store) {
+      return false;
+    }
+    return storage._store.has(key);
+  },
+
+  clear() {
+    if (!storage._store) {
+      return;
+    }
+    storage._store.clear();
+    storage._broadcast('*', undefined, undefined);
+  },
+
+  // Subscribe to changes for a specific key. Returns an unsubscribe function.
+  onChange(key, fn) {
+    if (!storage._changeSubs[key]) {
+      storage._changeSubs[key] = new Set();
+    }
+    storage._changeSubs[key].add(fn);
+
+    return () => {
+      const set = storage._changeSubs[key];
+      if (set) {
+        set.delete(fn);
+        if (set.size === 0) {
+          delete storage._changeSubs[key];
+        }
+      }
+    };
+  },
+
+  _broadcast(key, value, previous) {
+    if (!ipc._initialized) return;
+    ipc.broadcast('desktop:storage:change', { key, value, previous });
+  },
+
+  // Expose the on-disk path (handy for debugging)
+  getPath() {
+    return storage._store?.path || null;
+  },
+};
+
+module.exports = storage;

package/dist/lib/templating.js

@@ -0,0 +1,85 @@
+// Templating — light token-replacement engine for HTML/CSS/JS at build time.
+//
+// Wraps node-powertools' template() with framework-friendly defaults:
+//   - Brackets are `{{ }}` (matches BXM/UJM convention).
+//   - Standard variable scope built from manager.config + page metadata.
+//
+// Public API:
+//   manager.templating.render(input, vars)               // arbitrary string + arbitrary vars
+//   manager.templating.buildPageVars(pageName, extras)   // produces { brand, app, page, theme, cacheBust }
+//   manager.templating.renderPage(pageTemplate, vars)    // shortcut that uses {{ }} brackets
+//
+// Manager.initialize calls .initialize(manager) but the lib is mostly used at build time
+// (gulp/html), not at runtime. The runtime surface is exposed for consumer hooks that want
+// to template their own strings.
+
+const LoggerLite = require('./logger-lite.js');
+const { template } = require('node-powertools');
+
+const logger = new LoggerLite('templating');
+
+const DEFAULT_BRACKETS = ['{{', '}}'];
+
+const templating = {
+  _initialized: false,
+  _manager:     null,
+
+  initialize(manager) {
+    templating._manager = manager;
+    templating._initialized = true;
+    logger.log('initialize');
+  },
+
+  // Render an arbitrary template string with the given vars. Brackets default to {{ }}.
+  render(input, vars, opts) {
+    opts = opts || {};
+    const brackets = opts.brackets || DEFAULT_BRACKETS;
+    return template(String(input || ''), vars || {}, { brackets });
+  },
+
+  // Build the standard variable scope for a page render. Combines manager.config with
+  // page-specific metadata + cache-buster for asset URLs.
+  // `manager` is optional — buildPageVars works at build time (where Manager singleton is built
+  // from build.js) without needing the runtime manager singleton.
+  buildPageVars(pageName, extras, manager) {
+    const m = manager || templating._manager;
+    const cfg = (m && m.config) || (m && typeof m.getConfig === 'function' ? m.getConfig() : {}) || {};
+    // Pull version from the consumer's package.json at build time. This baked-in
+    // string is used by templates that want to display the running version in the
+    // UI (e.g. "v1.0.5" in a footer). At runtime it always matches the version
+    // that was packaged + signed + uploaded, since both come from the same
+    // package.json read.
+    const pkg = (m && typeof m.getPackage === 'function' ? m.getPackage('project') : null) || {};
+    const appBlock = { ...(cfg.app || {}) };
+    if (pkg.version && !appBlock.version) appBlock.version = pkg.version;
+    const vars = {
+      brand: cfg.brand   || {},
+      app:   appBlock,
+      // 'system' is inert as a data-bs-theme value (Bootstrap knows light/dark only) —
+      // the preload's theme applier replaces it with the RESOLVED appearance at runtime.
+      theme: { appearance: cfg.theme?.appearance || 'system' },
+      page: {
+        name:  pageName,
+        title: (extras && extras.title) || cfg.app?.productName || cfg.brand?.name || 'App',
+      },
+      cacheBust: String((extras && extras.cacheBust) || Date.now()),
+      // Slot for the body content. gulp/html sets this after rendering the inner view.
+      content: (extras && extras.content) || '',
+    };
+    if (extras && typeof extras === 'object') {
+      // Merge any extra keys (e.g. content), but don't clobber the structured groups above
+      // unless explicitly provided.
+      for (const [k, v] of Object.entries(extras)) {
+        if (v !== undefined) vars[k] = v;
+      }
+    }
+    return vars;
+  },
+
+  // Convenience: render a page template (outer shell) with the given vars.
+  renderPage(pageTemplate, vars) {
+    return templating.render(pageTemplate, vars);
+  },
+};
+
+module.exports = templating;

package/dist/lib/theme.js

@@ -0,0 +1,173 @@
+// Theme — system-aware dynamic appearance (light / dark / follow-the-OS).
+//
+// Main-side API:
+//   manager.theme.get()        → 'system' | 'light' | 'dark'   (the SOURCE — what's chosen)
+//   manager.theme.resolved()   → 'light' | 'dark'              (what's actually showing)
+//   manager.theme.set(source)  → apply + persist a new source
+//   manager.theme.onChange(fn) → fn({ source, resolved }) on every effective change; returns unsubscribe
+//
+// Renderer-side (preload contextBridge):
+//   window.desktop.theme.get()      → Promise<{ source, resolved }>
+//   window.desktop.theme.set(s)     → Promise<{ source, resolved }>
+//   window.desktop.theme.onChange(fn) — matchMedia-powered (see below); returns unsubscribe
+//
+// How it works: everything rides on Electron's `nativeTheme.themeSource`, which accepts
+// exactly the same three values. Setting it (a) drives `shouldUseDarkColors`, (b) flips
+// `prefers-color-scheme` in EVERY renderer of the app — BrowserWindows AND
+// WebContentsViews — firing their matchMedia listeners, and (c) makes native UI (menus,
+// dialogs) follow. Renderers therefore SELF-RESOLVE via matchMedia instead of depending
+// on `ipc.broadcast` (which only reaches BrowserWindows — embedded WebContentsViews
+// would never hear it). The `desktop:theme:changed` broadcast below is a main-side courtesy
+// for windows that want the source+resolved pair pushed; it is not the sync mechanism.
+//
+// Source resolution at boot: storage override (the user's runtime choice) → config
+// `theme.appearance` (the app's default) → 'system'. Invalid values fall through.
+//
+// The `<html data-bs-theme>` attribute is applied/maintained by the preload's theme
+// applier on every framework-templated page (see src/preload.js) — pages that don't carry the
+// attribute (e.g. external sites loaded in an embedding consumer's web views) are left
+// untouched.
+
+const LoggerLite = require('./logger-lite.js');
+const ipc = require('./ipc.js');
+
+const logger = new LoggerLite('theme');
+
+const STORAGE_KEY = 'theme';
+const SOURCES = ['system', 'light', 'dark'];
+
+const theme = {
+  _initialized: false,
+  _manager: null,
+  _nativeTheme: null,
+  _listeners: new Set(),
+  _lastEmitted: null,
+  _onNativeUpdated: null,
+
+  initialize(manager) {
+    if (theme._initialized) {
+      return;
+    }
+
+    theme._manager = manager;
+
+    let nativeTheme;
+    try {
+      nativeTheme = require('electron').nativeTheme;
+    } catch (e) {
+      nativeTheme = null;
+    }
+    if (!nativeTheme) {
+      logger.warn('nativeTheme not available — theme running as no-op.');
+      theme._initialized = true;
+      return;
+    }
+    theme._nativeTheme = nativeTheme;
+
+    // Boot source: storage override → config default → 'system'.
+    const stored = manager.storage.get(`${STORAGE_KEY}.appearance`);
+    const configured = manager.config?.theme?.appearance;
+    const source = SOURCES.includes(stored) ? stored
+      : SOURCES.includes(configured) ? configured
+      : 'system';
+
+    nativeTheme.themeSource = source;
+    logger.log(`initialize — source=${source} (stored=${stored ?? '—'} config=${configured ?? '—'}) resolved=${theme.resolved()}`);
+
+    // OS preference changes (in 'system' mode) and themeSource flips both land here.
+    theme._onNativeUpdated = () => theme._emitChange();
+    nativeTheme.on('updated', theme._onNativeUpdated);
+
+    theme._registerIpc();
+
+    theme._lastEmitted = `${theme.get()}|${theme.resolved()}`;
+    theme._initialized = true;
+  },
+
+  _registerIpc() {
+    if (!ipc._initialized) {
+      return;
+    }
+
+    ipc.handle('desktop:theme:get', () => ({ source: theme.get(), resolved: theme.resolved() }));
+    ipc.handle('desktop:theme:set', ({ source }) => {
+      theme.set(source);
+      return { source: theme.get(), resolved: theme.resolved() };
+    });
+  },
+
+  // The chosen source ('system' tracks the OS; 'light'/'dark' are explicit overrides).
+  get() {
+    return theme._nativeTheme ? theme._nativeTheme.themeSource : 'system';
+  },
+
+  // What's actually showing right now.
+  resolved() {
+    return theme._nativeTheme?.shouldUseDarkColors ? 'dark' : 'light';
+  },
+
+  // Apply + persist a new source. Throws on anything outside the three valid values —
+  // a bad call is a programmer error, not a state to limp through.
+  set(source) {
+    if (!SOURCES.includes(source)) {
+      throw new Error(`theme.set: invalid source '${source}' — expected 'system' | 'light' | 'dark'.`);
+    }
+    if (!theme._nativeTheme) {
+      return;
+    }
+
+    theme._manager.storage.set(`${STORAGE_KEY}.appearance`, source);
+    theme._nativeTheme.themeSource = source;
+
+    // nativeTheme 'updated' only fires when the RESOLVED appearance changes — a
+    // source change with the same resolution (e.g. system-resolving-dark → dark)
+    // would otherwise go unannounced. _emitChange dedupes, so when 'updated' also
+    // fires this is still exactly one notification.
+    theme._emitChange();
+  },
+
+  // Subscribe to effective changes (source or resolution). Returns an unsubscribe fn.
+  onChange(fn) {
+    theme._listeners.add(fn);
+    return () => theme._listeners.delete(fn);
+  },
+
+  _emitChange() {
+    const payload = { source: theme.get(), resolved: theme.resolved() };
+    const stamp = `${payload.source}|${payload.resolved}`;
+    if (stamp === theme._lastEmitted) {
+      return;
+    }
+    theme._lastEmitted = stamp;
+
+    logger.log(`changed — source=${payload.source} resolved=${payload.resolved}`);
+
+    theme._listeners.forEach((fn) => {
+      try {
+        fn(payload);
+      } catch (e) {
+        logger.error('onChange subscriber threw:', e);
+      }
+    });
+
+    if (ipc._initialized) {
+      ipc.broadcast('desktop:theme:changed', payload);
+    }
+  },
+
+  // Tear down listeners + IPC (idempotent).
+  disable() {
+    if (theme._nativeTheme && theme._onNativeUpdated) {
+      theme._nativeTheme.removeListener('updated', theme._onNativeUpdated);
+      theme._onNativeUpdated = null;
+    }
+    theme._listeners.clear();
+    if (ipc._initialized) {
+      ipc.unhandle('desktop:theme:get');
+      ipc.unhandle('desktop:theme:set');
+    }
+    theme._initialized = false;
+  },
+};
+
+module.exports = theme;