@omega.js/desktop 0.1.0

package/dist/lib/client-bridge.js

@@ -0,0 +1,371 @@
+// Client bridge — main-process Firebase Auth, source of truth for renderers.
+//
+// This is @omega.js/desktop's analogue of BXM's background-service-worker auth role. The pattern:
+//
+//   1. Main runs its own Firebase Auth instance and is the source of truth.
+//   2. When a deep-link auth/token arrives, main calls signInWithCustomToken with that token,
+//      then BROADCASTS the token to all renderer windows so their @omega.js/client Firebase
+//      instances can sign in with the SAME token.
+//   3. On every renderer load, the renderer asks main "I'm at UID X (or null)" via the
+//      desktop:auth:sync-request IPC. Main compares with its own UID and either does nothing,
+//      tells the renderer to sign out, or fetches a fresh custom token from /omega
+//      and sends it to the renderer.
+//   4. Sign-out: any renderer can request sign-out via desktop:auth:sign-out. Main signs out
+//      its own Firebase + broadcasts desktop:auth:sign-out to all renderers.
+//
+// Firebase is BUNDLED by esbuild from @omega.js/desktop's module context (@omega.js/client owns it in @omega.js/desktop's
+// tree). If loading fails, the bridge stays in no-op mode and logs the reason.
+
+const LoggerLite = require('./logger-lite.js');
+const authPersistence = require('./auth-persistence.js');
+const { localPort } = require('../utils/url-helpers.js');
+
+const logger = new LoggerLite('client-bridge');
+
+const FIREBASE_APP_NAME = 'omega-auth';
+
+const bridge = {
+  _initialized:    false,
+  _manager:        null,
+  _firebase:       null,    // firebase/app
+  _firebaseAuth:   null,    // auth instance
+  _firebaseModule: null,    // firebase/auth namespace (signInWithCustomToken, signOut, ...)
+  _stateSubs:      new Set(), // main-side subscribers fn(user)
+  _ipcRegistered:  false,
+  _resolvedPlan:   null,    // renderer-resolved subscription { plan, active, trialing, cancelling }
+  _resolvedRoles:  null,    // renderer-resolved account roles { admin, betaTester, ... }
+
+  async initialize(manager) {
+    if (bridge._initialized) {
+      return;
+    }
+
+    bridge._manager = manager;
+
+    // Try to load firebase. If it's not installed, run in no-op mode.
+    const ok = await bridge._tryLoadFirebase();
+    if (!ok) {
+      logger.warn('firebase not installed — client-bridge running in no-op mode. `npm i firebase` to enable auth.');
+    }
+
+    bridge._registerIpc();
+
+    if (ok) {
+      // Boot Firebase Auth. With a persistence strategy active (lib/auth-persistence.js,
+      // default safeStorage), the session survives restarts — the restore lands async
+      // via onAuthStateChanged shortly after boot.
+      try {
+        const strategy = await authPersistence.resolve(manager);
+        bridge._firebaseAuth = bridge._getFirebaseAuth(strategy);
+        // onAuthStateChanged is the source of truth listener.
+        bridge._firebaseModule.onAuthStateChanged(bridge._firebaseAuth, (user) => {
+          bridge._handleAuthStateChange(user);
+        });
+        logger.log(`initialize — firebase loaded (persistence: ${strategy ? strategy.name : 'in-memory'})`);
+      } catch (e) {
+        logger.error('firebase init failed:', e.message);
+      }
+    }
+
+    bridge._initialized = true;
+  },
+
+  // Load firebase. Returns true on success. BUNDLED by esbuild from @omega.js/desktop's module context
+  // (@omega.js/client owns firebase in @omega.js/desktop's tree) — same treatment as json5 in main.js. In the
+  // webpack era it was a webpackIgnore'd runtime import(), which resolves relative to the CONSUMER's
+  // main.bundle.js: that walk never reaches @omega.js/desktop's node_modules when @omega.js/desktop is symlinked
+  // (`mgr install dev`) and depends on npm hoisting when installed — every dev app silently
+  // ran the bridge in no-op mode. Interop guards handle both namespace shapes (json5 precedent).
+  async _tryLoadFirebase() {
+    try {
+      const appMod  = require('firebase/app');
+      const authMod = require('firebase/auth');
+
+      bridge._firebase       = appMod.initializeApp ? appMod : (appMod.default || appMod);
+      bridge._firebaseModule = authMod.getAuth      ? authMod : (authMod.default || authMod);
+      return true;
+    } catch (e) {
+      logger.warn('firebase load failed:', e.message);
+      return false;
+    }
+  },
+
+  _getFirebaseAuth(strategy) {
+    if (bridge._firebaseAuth) return bridge._firebaseAuth;
+
+    const firebaseConfig = bridge._manager.config.cloud?.config;
+    if (!firebaseConfig || !Object.keys(firebaseConfig).length) {
+      throw new Error('cloud.config is empty — cannot initialize auth.');
+    }
+
+    const { initializeApp, getApp } = bridge._firebase;
+    const { getAuth, initializeAuth } = bridge._firebaseModule;
+
+    let app;
+    try { app = getApp(FIREBASE_APP_NAME); }
+    catch (e) { app = initializeApp(firebaseConfig, FIREBASE_APP_NAME); }
+
+    // With a storage strategy, boot auth on OUR persistence (session survives
+    // restarts); without one, firebase's Node default (in-memory) applies.
+    if (strategy && initializeAuth) {
+      bridge._firebaseAuth = initializeAuth(app, {
+        persistence: [authPersistence.buildFirebasePersistence(strategy)],
+      });
+    } else {
+      bridge._firebaseAuth = getAuth(app);
+    }
+
+    // A TESTING run talks to the LOCAL stack, never real auth — the same move
+    // getApiUrl() makes when it maps testing to localhost, and the same one
+    // @omega.js/extension's background SW makes for its emulator runs. Only
+    // OMEGA_TEST_MODE=true reaches here; dev and production are untouched.
+    if (bridge._manager.isTesting()) {
+      const { connectAuthEmulator } = bridge._firebaseModule;
+      const port = bridge._authEmulatorPort();
+      logger.log(`testing run — connecting auth to the emulator on :${port}`);
+      connectAuthEmulator(bridge._firebaseAuth, `http://localhost:${port}`, { disableWarnings: true });
+    }
+
+    return bridge._firebaseAuth;
+  },
+
+  // The auth emulator's port, on the same three-step chain getApiUrl() walks:
+  // the resolved-port env channel (N7), then the `dev.ports` map the bundle
+  // baked into OMEGA_BUILD_JSON, then the classic 9099
+  // ([#745](https://github.com/Omega-JS-Stack/omega/issues/745)).
+  _authEmulatorPort() {
+    return localPort(bridge._manager, 'OMEGA_AUTH_PORT', 'auth') || 9099;
+  },
+
+  _registerIpc() {
+    if (bridge._ipcRegistered) return;
+    const ipc = bridge._manager.ipc;
+
+    // Renderer asks main: "I'm at UID X (or null). Are we in sync?"
+    ipc.handle('desktop:auth:sync-request', async ({ contextUid }) => {
+      return bridge._handleSyncRequest(contextUid);
+    });
+
+    // Renderer asks main to sign out.
+    ipc.handle('desktop:auth:sign-out', async () => {
+      return bridge._handleSignOut();
+    });
+
+    // Renderer asks main for the current user (uid + email + displayName, no token).
+    ipc.handle('desktop:auth:get-user', () => {
+      const u = bridge._firebaseAuth?.currentUser;
+      return u ? bridge._snapshotUser(u) : null;
+    });
+
+    // Renderer pushes its @omega.js/client account resolution (auth().listen() settled:
+    // Firestore account fetched, subscription resolved). Main can't run Firestore,
+    // so this is how main-side plan gates learn the REAL plan — BXM's "browser
+    // contexts resolve, authority caches" split. UID-guarded: a stale push from a
+    // renderer that hasn't synced yet is dropped.
+    ipc.handle('desktop:auth:account-resolved', ({ uid, resolved, roles } = {}) => {
+      const mainUid = bridge._firebaseAuth?.currentUser?.uid || null;
+      if (!uid || uid !== mainUid) {
+        return { accepted: false };
+      }
+
+      const changed = JSON.stringify(resolved) !== JSON.stringify(bridge._resolvedPlan)
+        || JSON.stringify(roles || null) !== JSON.stringify(bridge._resolvedRoles);
+      bridge._resolvedPlan  = resolved || null;
+      bridge._resolvedRoles = roles || null;
+
+      if (changed) {
+        logger.log(`account resolved — plan=${resolved?.plan || '(none)'} active=${!!resolved?.active}`);
+        bridge._manager.ipc.broadcast('desktop:auth:plan-changed', { resolved: bridge._resolvedPlan, roles: bridge._resolvedRoles });
+        // Main-side subscribers see the same user snapshot again with plan now known.
+        const u = bridge._firebaseAuth?.currentUser;
+        bridge._stateSubs.forEach((fn) => {
+          try { fn(u ? bridge._snapshotUser(u) : null); } catch (e) { logger.error('onAuthChange subscriber threw:', e); }
+        });
+      }
+      return { accepted: true };
+    });
+
+    bridge._ipcRegistered = true;
+  },
+
+  _handleAuthStateChange(user) {
+    logger.log(`auth state → ${user ? user.email : 'signed out'}`);
+
+    // Sign-out (or a different user signing in) invalidates the cached resolution —
+    // renderers re-resolve and push fresh via desktop:auth:account-resolved.
+    if (!user) {
+      bridge._resolvedPlan = null;
+      bridge._resolvedRoles = null;
+    }
+
+    // Notify any main-side subscribers (consumer code that called manager.omega.onAuthChange).
+    const snap = user ? bridge._snapshotUser(user) : null;
+    bridge._stateSubs.forEach((fn) => {
+      try { fn(snap); } catch (e) { logger.error('onAuthChange subscriber threw:', e); }
+    });
+
+    // Tell renderers about the change so they can update UI / refresh menu items.
+    bridge._manager.ipc.broadcast('desktop:auth:state-changed', snap);
+
+    // Attribute Sentry events to the signed-in user (or clear on sign-out). When
+    // sentry is disabled (no DSN, dev mode, etc.) setUser is a documented no-op.
+    bridge._manager.sentry.setUser(snap);
+  },
+
+  // BXM's syncAuth pattern, ported to Electron.
+  async _handleSyncRequest(contextUid) {
+    if (!bridge._firebaseAuth) {
+      return { needsSync: false, reason: 'firebase-not-loaded' };
+    }
+
+    const bgUser = bridge._firebaseAuth.currentUser;
+    const bgUid = bgUser?.uid || null;
+
+    // Already in sync.
+    if (contextUid === bgUid) {
+      return { needsSync: false };
+    }
+
+    // Renderer signed in but main signed out → tell renderer to sign out.
+    if (!bgUser && contextUid) {
+      return { needsSync: true, signOut: true };
+    }
+
+    // Main signed in, renderer not (or different user) → fetch a fresh custom token + send.
+    try {
+      const token = await bridge._fetchCustomToken(bgUser);
+      return {
+        needsSync: true,
+        customToken: token,
+        user: bridge._snapshotUser(bgUser),
+      };
+    } catch (e) {
+      logger.error('sync-request: failed to fetch custom token:', e.message);
+      return { needsSync: false, error: e.message };
+    }
+  },
+
+  async _handleSignOut() {
+    try {
+      if (bridge._firebaseAuth?.currentUser) {
+        await bridge._firebaseModule.signOut(bridge._firebaseAuth);
+      }
+      bridge._manager.ipc.broadcast('desktop:auth:sign-out', {});
+      return { success: true };
+    } catch (e) {
+      logger.error('sign-out failed:', e.message);
+      return { success: false, error: e.message };
+    }
+  },
+
+  // Public API ──────────────────────────────────────────────────────────────────
+
+  // Called by lib/deep-link's auth/token built-in.
+  async handleAuthToken(token) {
+    if (!bridge._firebaseAuth) {
+      logger.warn('handleAuthToken called but firebase not loaded — ignoring.');
+      return { success: false, reason: 'firebase-not-loaded' };
+    }
+    if (!token) {
+      logger.warn('handleAuthToken called with no token — ignoring.');
+      return { success: false, reason: 'no-token' };
+    }
+
+    try {
+      const cred = await bridge._firebaseModule.signInWithCustomToken(bridge._firebaseAuth, token);
+      logger.log(`signed in: ${cred.user.email || cred.user.uid}`);
+
+      // Broadcast the token to renderers so they can sign in with the SAME token.
+      // Tokens expire in 1 hour and aren't stored.
+      bridge._manager.ipc.broadcast('desktop:auth:sign-in-with-token', { token });
+
+      return { success: true, user: bridge._snapshotUser(cred.user) };
+    } catch (e) {
+      logger.error('signInWithCustomToken failed:', e.message);
+      return { success: false, error: e.message };
+    }
+  },
+
+  // Subscribe to auth state changes on the main side (e.g. for menu/tray refresh).
+  onAuthChange(fn) {
+    bridge._stateSubs.add(fn);
+    return () => bridge._stateSubs.delete(fn);
+  },
+
+  // Snapshot of the current user (sync), or null.
+  getCurrentUser() {
+    const u = bridge._firebaseAuth?.currentUser;
+    return u ? bridge._snapshotUser(u) : null;
+  },
+
+  // The renderer-resolved subscription ({ plan, active, trialing, cancelling }) or null
+  // while no renderer has resolved yet. THE main-side plan source — consumer plan gates
+  // read this (@omega.js/client's resolveSubscription output, pushed via desktop:auth:account-resolved).
+  getResolvedPlan() {
+    return bridge._resolvedPlan;
+  },
+
+  // The renderer-resolved account roles ({ admin, betaTester, ... }) or null.
+  getResolvedRoles() {
+    return bridge._resolvedRoles;
+  },
+
+  // Fresh Firebase ID token for the signed-in user (async), or null when
+  // signed out / Firebase absent. For consumer main code calling
+  // authenticated backend routes (`Authorization: Bearer <token>`).
+  async getIdToken() {
+    const u = bridge._firebaseAuth?.currentUser;
+    return u ? u.getIdToken() : null;
+  },
+
+  // Force sign-out from main code.
+  async signOut() {
+    return bridge._handleSignOut();
+  },
+
+  // ─── Internals ────────────────────────────────────────────────────────────
+
+  _snapshotUser(user) {
+    return {
+      uid:           user.uid,
+      email:         user.email,
+      displayName:   user.displayName,
+      photoURL:      user.photoURL,
+      emailVerified: user.emailVerified,
+    };
+  },
+
+  // Fetch a fresh custom token for the currently-signed-in user via the shared
+  // @omega.js/client request layer. Mirrors BXM: POST <apiUrl>/omega/user/token —
+  // the route defaults uid to the authenticated caller and responds { token }
+  // at the top level.
+  async _fetchCustomToken(user) {
+    const { createRequest } = require('@omega.js/client/modules/request.js');
+
+    const request = createRequest({
+      getApiUrl: () => bridge._manager.getApiUrl(),
+      getIdToken: (force) => user.getIdToken(force),
+    });
+
+    const data = await request('/omega/user/token', { method: 'POST', body: {} });
+
+    const token = data?.token;
+    if (!token) {
+      throw new Error('@omega.js/backend response missing token.');
+    }
+    return token;
+  },
+
+  // Tear-down used by tests — wipes state but keeps registered IPC handlers
+  // (they're idempotent via `ipc.handle` duplicate-detection).
+  async _resetForTests() {
+    try {
+      if (bridge._firebaseAuth?.currentUser && bridge._firebaseModule?.signOut) {
+        await bridge._firebaseModule.signOut(bridge._firebaseAuth);
+      }
+    } catch (e) { /* ignore */ }
+    bridge._stateSubs.clear();
+  },
+};
+
+module.exports = bridge;

package/dist/lib/context-menu.js

@@ -0,0 +1,302 @@
+// Context Menu — file-based right-click menu definition.
+//
+// @omega.js/desktop looks for the consumer's `src/integrations/context-menu/index.js` and calls it FOR EACH
+// context-menu event with a builder API plus the event's `params`:
+//
+//   // src/integrations/context-menu/index.js
+//   module.exports = ({ manager, menu, params, webContents }) => {
+//     // Start from @omega.js/desktop's default template (undo/redo, cut/copy/paste, link items,
+//     // reload, dev-only inspect):
+//     menu.useDefaults();
+//
+//     // Mutate by id within this event's items:
+//     menu.remove('toggle-devtools');                        // hide dev tools
+//     menu.insertAfter('copy', { id: 'search-google',
+//       label: `Search "${params.selectionText.slice(0,20)}"`,
+//       click: () => require('electron').shell.openExternal(...) });
+//
+//     // Or build entirely from scratch — useDefaults() is optional:
+//     // menu.item({ id: 'copy', role: 'copy' });
+//     // menu.separator();
+//     // menu.item({ id: 'mine', label: 'Custom', click: ... });
+//   };
+//
+// Builder API (per event):
+//   menu.item(descriptor)
+//   menu.separator()
+//   menu.submenu(label, items)
+//   menu.useDefaults()           — populate with @omega.js/desktop's default template based on params
+//   menu.clear()                 — wipe items added so far this event
+//
+// Id-path API (per event, same shape as menu/tray):
+//   .find / .has / .update / .remove / .enable / .show / .hide /
+//   .insertBefore / .insertAfter / .appendTo
+//
+// Default template ids (flat — no `context/` prefix; the lib namespace is implicit):
+//   undo, redo                                   — when params.editFlags allow
+//   cut, copy, paste, paste-and-match-style,
+//   select-all                                   — when params.isEditable
+//   copy                                          — when params.selectionText (read-only)
+//   open-link, copy-link                          — when params.linkURL
+//   reload                                        — always (page reload)
+//   inspect, toggle-devtools                      — dev mode only
+//
+// Building no items (calling no menu.* methods) suppresses the popup entirely.
+//
+// @omega.js/desktop auto-attaches the handler to every BrowserWindow's webContents that
+// goes through `manager.windows.createNamed()`. To attach manually:
+//   manager.contextMenu.attach(webContents)
+//
+// Disabling at runtime: call `manager.contextMenu.disable()`. Idempotent. After
+// disable() the lib stops responding to context-menu events on already-attached
+// webContents — no new menus are shown. No config flag.
+
+const path = require('path');
+const fs   = require('fs');
+const LoggerLite = require('./logger-lite.js');
+const sanitizeURL = require('../utils/sanitize-url.js');
+const { buildIdApi } = require('./_menu-mixin.js');
+
+const logger = new LoggerLite('context-menu');
+
+const contextMenu = {
+  _initialized:  false,
+  _manager:      null,
+  _electron:     null,
+  _definitionFn: null,
+  _attached:     new WeakSet(), // webContents that already have the listener
+
+  initialize(manager) {
+    if (contextMenu._initialized) {
+      return;
+    }
+
+    contextMenu._manager = manager;
+
+    if (contextMenu._disabled) {
+      logger.log('initialize — disabled via manager.contextMenu.disable() called pre-init');
+      contextMenu._initialized = true;
+      return;
+    }
+
+    contextMenu._electron = require('electron');
+
+    // Conventional path. No config knob — disable() at runtime if you don't want a context menu.
+    // appRoot resolves to project dir in dev and asar mount in packaged apps — both contain
+    // src/integrations/* (electron-builder's `files: ['**/*']` packs the consumer's src/
+    // into the asar), so the existsSync + require below works in both modes.
+    const absPath = path.join(require('../utils/app-root.js')(), 'src', 'integrations', 'context-menu', 'index.js');
+
+    if (fs.existsSync(absPath)) {
+      const loadConsumerFile = require('../utils/load-consumer-file.js');
+      const loaded = loadConsumerFile(absPath, logger);
+      if (typeof loaded === 'function') {
+        contextMenu._definitionFn = loaded;
+      } else if (loaded != null) {
+        logger.warn(`context-menu definition at ${absPath} did not export a function — using default.`);
+        contextMenu._definitionFn = null;
+      }
+    } else {
+      logger.log(`no context-menu definition at ${absPath} — using default (copy/paste based on params).`);
+    }
+
+    logger.log(`initialize — definition=${contextMenu._definitionFn ? 'consumer' : 'default'}`);
+    contextMenu._initialized = true;
+  },
+
+  // Attach the context-menu listener to a webContents (idempotent per webContents).
+  attach(webContents) {
+    if (!webContents || contextMenu._attached.has(webContents)) {
+      return;
+    }
+    if (!contextMenu._electron) {
+      return;
+    }
+
+    contextMenu._attached.add(webContents);
+
+    webContents.on('context-menu', (event, params) => {
+      contextMenu._popup(webContents, params);
+    });
+  },
+
+  // Build the menu for the given (webContents, params) and pop it up.
+  _popup(webContents, params) {
+    if (contextMenu._disabled) return;             // disabled at runtime → no menu
+    const { Menu } = contextMenu._electron;
+
+    const items = contextMenu._buildItemsForEvent(params, webContents);
+    if (items.length === 0) return; // suppress popup
+
+    const template = items.map((item) => contextMenu._resolveItem(item));
+    const builtMenu = Menu.buildFromTemplate(template);
+    builtMenu.popup({ window: webContents.getOwnerBrowserWindow() || undefined });
+  },
+
+  // Construct the per-event builder + run the consumer's (or default) definition fn.
+  // Returns the items array (live — but per-event, so post-event mutations are pointless).
+  _buildItemsForEvent(params, webContents) {
+    const items = [];
+
+    const idApi = buildIdApi({
+      getItems: () => items,
+      // Per-event: nothing to re-render. The popup happens after definition returns.
+      render: () => {},
+      logger,
+    });
+
+    const builder = {
+      item:        (d)            => { items.push(d); },
+      separator:   ()             => { items.push({ type: 'separator' }); },
+      submenu:     (label, subs)  => { items.push({ label, submenu: subs }); },
+      useDefaults: ()             => { contextMenu._populateDefaults(items, params); },
+      clear:       ()             => { items.length = 0; },
+      ...idApi,
+    };
+
+    const fn = contextMenu._definitionFn || contextMenu._defaultFn;
+    try {
+      fn({ manager: contextMenu._manager, menu: builder, params, webContents });
+    } catch (e) {
+      logger.error('context-menu definition fn threw:', e);
+      return [];
+    }
+
+    return items;
+  },
+
+  // Populate `items` with @omega.js/desktop's default template based on context-menu params.
+  // Used by both `_defaultFn` (when no consumer file) and `menu.useDefaults()` (consumer opt-in).
+  // Item set + visibility gates mirror the legacy @omega.js/desktop context-menu behavior:
+  // undo/redo gated on canUndo/canRedo, edit ops gated on params.isEditable, etc.
+  _populateDefaults(items, params) {
+    const m = contextMenu._manager;
+    const flags = params.editFlags || {};
+
+    // Undo / redo — only when applicable. Hidden when canUndo/canRedo is false (matches legacy).
+    if (flags.canUndo) {
+      items.push({ id: 'undo', role: 'undo' });
+    }
+    if (flags.canRedo) {
+      items.push({ id: 'redo', role: 'redo' });
+    }
+    if (flags.canUndo || flags.canRedo) {
+      items.push({ type: 'separator' });
+    }
+
+    if (params.isEditable) {
+      items.push({ id: 'cut',                   role: 'cut',                enabled: flags.canCut   !== false });
+      items.push({ id: 'copy',                  role: 'copy',               enabled: flags.canCopy  !== false });
+      items.push({ id: 'paste',                 role: 'paste',              enabled: flags.canPaste !== false });
+      items.push({ id: 'paste-and-match-style', role: 'pasteAndMatchStyle', enabled: flags.canPaste !== false });
+      items.push({ id: 'select-all',            role: 'selectAll' });
+    } else if (params.selectionText) {
+      items.push({ id: 'copy', role: 'copy' });
+    }
+
+    if (params.linkURL) {
+      if (items.length > 0) items.push({ type: 'separator' });
+      items.push({
+        id: 'open-link',
+        label: 'Open Link in Browser',
+        click: () => {
+          const { shell } = require('electron');
+          const safe = sanitizeURL(params.linkURL);
+          if (safe) shell.openExternal(safe);
+        },
+      });
+      items.push({
+        id: 'copy-link',
+        label: 'Copy Link Address',
+        click: () => {
+          const { clipboard } = require('electron');
+          clipboard.writeText(params.linkURL);
+        },
+      });
+    }
+
+    // Reload — useful for both dev and prod. Separator only if there's already content above.
+    if (items.length > 0) items.push({ type: 'separator' });
+    items.push({ id: 'reload', role: 'reload' });
+
+    if (m.isDevelopment()) {
+      items.push({ type: 'separator' });
+      items.push({ id: 'inspect',         role: 'inspectElement' });
+      items.push({ id: 'toggle-devtools', role: 'toggleDevTools' });
+    }
+  },
+
+  // Default behavior when no consumer definition exists — sensible baseline.
+  _defaultFn({ menu, params }) {
+    menu.useDefaults();
+  },
+
+  // Same resolver pattern as tray/menu — supports dynamic label/enabled/etc.
+  _resolveItem(item) {
+    if (item.type === 'separator') {
+      return { type: 'separator' };
+    }
+
+    const out = { ...item };
+
+    if (typeof item.label === 'function') {
+      try { out.label = String(item.label()); }
+      catch (e) { logger.error('item.label() threw:', e); out.label = ''; }
+    }
+    if (typeof item.enabled === 'function') {
+      try { out.enabled = Boolean(item.enabled()); } catch (e) { out.enabled = true; }
+    }
+    if (typeof item.visible === 'function') {
+      try { out.visible = Boolean(item.visible()); } catch (e) { out.visible = true; }
+    }
+    if (typeof item.checked === 'function') {
+      try { out.checked = Boolean(item.checked()); } catch (e) { out.checked = false; }
+    }
+
+    if (Array.isArray(item.submenu)) {
+      out.submenu = item.submenu.map((sub) => contextMenu._resolveItem(sub));
+    }
+
+    if (typeof item.click === 'function') {
+      out.click = (menuItem, browserWindow, event) => {
+        try { item.click(menuItem, browserWindow, event); }
+        catch (e) { logger.error('item.click handler threw:', e); }
+      };
+    }
+
+    return out;
+  },
+
+  // Public runtime API — replace the definition fn at runtime.
+  define(fn) {
+    if (typeof fn !== 'function') {
+      throw new Error('contextMenu.define: fn must be a function');
+    }
+    contextMenu._definitionFn = fn;
+  },
+
+  // Test/inspection helpers — build the items list for given params without popping a menu.
+  buildItems(params, webContents) {
+    return contextMenu._buildItemsForEvent(params || {}, webContents);
+  },
+
+  hasCustomDefinition() {
+    return Boolean(contextMenu._definitionFn);
+  },
+
+  // Disable the context menu entirely. Idempotent. Safe pre- or post-init.
+  // After this, _popup() short-circuits — already-attached webContents stop
+  // showing menus on right-click. No way to re-enable; call manager.contextMenu.define()
+  // and clear _disabled if you really need to.
+  disable() {
+    contextMenu._disabled = true;
+    contextMenu._definitionFn = null;
+    if (contextMenu._initialized) {
+      logger.log('disabled at runtime — context-menu events will be ignored');
+    }
+  },
+
+  isDisabled() { return Boolean(contextMenu._disabled); },
+};
+
+module.exports = contextMenu;