@omega.js/desktop 0.1.0

package/dist/gulp/tasks/package.js

@@ -0,0 +1,53 @@
+// Package the app via electron-builder, using the materialized config at
+// `dist/electron-builder.yml` (produced by gulp/build-config from omega.json5).
+// Consumers never ship an electron-builder.yml — the dist version is the only source of truth.
+//
+// This task does NOT publish — it just produces local artifacts under `release/`.
+// For publishing, see gulp/release.js.
+//
+// Skip Windows code signing during this step on the windows runner if OMEGA_SKIP_WIN_SIGN=true
+// is set — the windows-sign job in CI signs separately.
+
+const path    = require('path');
+const jetpack = require('fs-jetpack');
+const Manager = new (require('../../build.js'));
+
+const logger = Manager.logger('package');
+
+module.exports = function packageApp(done) {
+  const projectRoot = process.cwd();
+  const config = path.join(require('../../utils/dist-root.js')(projectRoot), 'electron-builder.yml');
+
+  if (!jetpack.exists(config)) {
+    return done(new Error(`Missing ${config}. Run gulp/build-config first (it generates this file from omega.json5).`));
+  }
+
+  // Resolve electron-builder from the consumer's node_modules first, then @omega.js/desktop's bundled one.
+  let builder;
+  try {
+    builder = Manager.require('electron-builder');
+  } catch (e) {
+    return done(new Error(`Could not resolve electron-builder: ${e.message}. Run \`npm i -D electron-builder\` in the consumer.`));
+  }
+
+  const relConfig = path.relative(projectRoot, config);
+  logger.log(`Packaging via electron-builder (config=${relConfig})...`);
+
+  const opts = {
+    config,
+    publish: 'never',          // package only — release.js handles publishing
+  };
+
+  // electron-builder's programmatic API returns a Promise<string[]> of artifact paths.
+  builder.build(opts)
+    .then((artifacts) => {
+      const list = (artifacts || []).map((a) => path.relative(projectRoot, a));
+      logger.log(`Packaged ${list.length} artifact(s):`);
+      list.forEach((a) => logger.log(`  • ${a}`));
+      done();
+    })
+    .catch((e) => {
+      logger.error(`electron-builder failed: ${e.message}`);
+      done(e);
+    });
+};

package/dist/gulp/tasks/release.js

@@ -0,0 +1,57 @@
+// Release task — runs electron-builder with `--publish always`, which packages AND
+// uploads artifacts to the configured publish provider (GitHub Releases by default,
+// generated by gulp/build-config from omega.json5's `releases` block).
+//
+// Auth: the GH_TOKEN env var (loaded from .env or CI secrets) authorizes the upload.
+//
+// Cross-platform behavior:
+//   - macOS: signs + notarizes (via the afterSign hook) + uploads .dmg / .zip
+//   - Linux: builds + uploads .AppImage / .deb (no signing)
+//   - Windows: when OMEGA_SKIP_WIN_SIGN=true (CI macOS/linux runners), this never runs the
+//              Windows target. The dedicated windows-sign job in CI handles that path.
+//
+// For local single-platform release runs, electron-builder targets only the host OS by default.
+
+const path    = require('path');
+const jetpack = require('fs-jetpack');
+const Manager = new (require('../../build.js'));
+
+const logger = Manager.logger('release');
+
+module.exports = function release(done) {
+  const projectRoot = process.cwd();
+  const config = path.join(require('../../utils/dist-root.js')(projectRoot), 'electron-builder.yml');
+
+  if (!jetpack.exists(config)) {
+    return done(new Error(`Missing ${config}. Run gulp/build-config first (it generates this file from omega.json5).`));
+  }
+
+  if (!process.env.GH_TOKEN) {
+    logger.warn('GH_TOKEN not set — electron-builder will fail to publish to GitHub Releases.');
+  }
+
+  let builder;
+  try {
+    builder = Manager.require('electron-builder');
+  } catch (e) {
+    return done(new Error(`Could not resolve electron-builder: ${e.message}. Run \`npm i -D electron-builder\` in the consumer.`));
+  }
+
+  const relConfig = path.relative(projectRoot, config);
+  logger.log(`Releasing via electron-builder (config=${relConfig}, publish=always)...`);
+
+  builder.build({
+    config,
+    publish: 'always',
+  })
+    .then((artifacts) => {
+      const list = (artifacts || []).map((a) => path.relative(projectRoot, a));
+      logger.log(`Released ${list.length} artifact(s):`);
+      list.forEach((a) => logger.log(`  • ${a}`));
+      done();
+    })
+    .catch((e) => {
+      logger.error(`Release failed: ${e.message}`);
+      done(e);
+    });
+};

package/dist/gulp/tasks/sass.js

@@ -0,0 +1,82 @@
+// sass — compile consumer SCSS into dist/assets/css/.
+//
+//   src/assets/scss/main.scss          -> dist/assets/css/main.bundle.css      (one shared bundle, every page)
+//   src/assets/scss/pages/<name>.scss  -> dist/assets/css/components/<name>.bundle.css   (per-view bundle)
+//
+// loadPaths are configured so the consumer can write `@use 'omega-desktop' as *`:
+//   - <omega-package-root>/dist/assets/css      → resolves bare 'omega-desktop' to omega-desktop.scss
+//   - <omega-package-root>/dist/assets/themes/<active-theme>   → resolves bare 'theme' to <theme>/_theme.scss
+//   - <omega-package-root>/dist/assets/themes   → so themes can reference each other via '../<sibling>'
+//   - <consumer>/src/assets/scss             → consumer's own modules
+
+const Manager = new (require('../../build.js'));
+const logger = Manager.logger('sass');
+const path = require('path');
+const jetpack = require('fs-jetpack');
+const sass = require('sass');
+const { formatBytes } = require('../../vendor/devkit/bundle.js');
+
+const projectRoot = Manager.getRootPath('project');
+const packageRoot = Manager.getRootPath('main');
+const outputRoot  = require('../../utils/dist-root.js')(projectRoot);
+
+module.exports = function sassTask(done) {
+  const isProd = Manager.getMode().environment === 'production';
+  const config = Manager.getConfig() || {};
+  const themeId = config.theme?.id || 'classy';
+
+  const loadPaths = [
+    path.join(packageRoot, 'dist', 'assets', 'css'),                    // for `@use 'omega-desktop'`
+    path.join(packageRoot, 'dist', 'assets', 'themes', themeId),        // for `@use 'theme'`
+    path.join(packageRoot, 'dist', 'assets', 'themes'),                 // for sibling-theme references
+    path.join(projectRoot, 'src', 'assets', 'scss'),                    // consumer's own scss tree
+  ];
+
+  const compileOpts = {
+    style:     isProd ? 'compressed' : 'expanded',
+    sourceMap: !isProd,
+    loadPaths,
+    // Suppress noisy deprecation warnings inherited from the vendored classy + Bootstrap 5.3 source.
+    // These are functional today (Dart Sass 1.x) and will be fixed when classy migrates to the
+    // modern @use/@forward + sass:color module system upstream. Until then, drowning in warnings
+    // every build hides real errors.
+    silenceDeprecations: ['import', 'global-builtin', 'color-functions', 'if-function'],
+  };
+
+  // Compile main.scss → main.bundle.css
+  const mainEntry = path.join(projectRoot, 'src', 'assets', 'scss', 'main.scss');
+  const mainOut = path.join(outputRoot, 'assets', 'css', 'main.bundle.css');
+
+  try {
+    if (jetpack.exists(mainEntry)) {
+      const result = sass.compile(mainEntry, compileOpts);
+      jetpack.write(mainOut, result.css);
+      if (result.sourceMap) jetpack.write(`${mainOut}.map`, JSON.stringify(result.sourceMap));
+      logger.log(`built dist/assets/css/main.bundle.css (${formatBytes(result.css.length)})`);
+    } else {
+      logger.warn(`No main scss entry at ${mainEntry} — skipping main bundle.`);
+    }
+
+    // Compile per-page entries: src/assets/scss/pages/<name>.scss → dist/assets/css/components/<name>.bundle.css
+    const pagesDir = path.join(projectRoot, 'src', 'assets', 'scss', 'pages');
+    if (jetpack.exists(pagesDir)) {
+      const pageFiles = jetpack.find(pagesDir, { matching: '**/*.scss', recursive: true })
+        .filter((f) => !path.basename(f).startsWith('_'));   // skip partials
+
+      for (const src of pageFiles) {
+        const rel = path.relative(pagesDir, src);
+        const name = rel.replace(/\.scss$/, '').replace(/\\/g, '/');
+        const out = path.join(outputRoot, 'assets', 'css', 'components', `${name}.bundle.css`);
+        const result = sass.compile(src, compileOpts);
+        jetpack.write(out, result.css);
+        if (result.sourceMap) jetpack.write(`${out}.map`, JSON.stringify(result.sourceMap));
+        logger.log(`built dist/assets/css/components/${name}.bundle.css (${formatBytes(result.css.length)})`);
+      }
+    }
+
+    done();
+  } catch (e) {
+    logger.error('sass compile failed:', e.message || e);
+    done(e);
+  }
+};

package/dist/gulp/tasks/serve.js

@@ -0,0 +1,191 @@
+// serve — spawn `electron .` against the consumer project.
+//
+// Pass 2.0: minimum viable serve. Just launches Electron and pipes its stdio.
+// Future passes will add: livereload websocket, watch + rebuild, renderer reload via webContents.reload(),
+// main reload via app.relaunch().
+
+const Manager = new (require('../../build.js'));
+const logger = Manager.logger('serve');
+const { spawn } = require('child_process');
+const { watchEnvChain } = require('../../vendor/devkit/env-watch.js');
+
+const projectRoot = Manager.getRootPath('project');
+
+module.exports = function serve(done) {
+  // N7: resolve livereload (and CDP when requested) through the allocator —
+  // taken ports bump +1, so two targets of one brand (desktop + extension
+  // serve) land on distinct ports automatically. Config `ports.*` pins.
+  resolveServePorts()
+    .then((ports) => start(ports, done))
+    .catch(done);
+};
+
+async function resolveServePorts() {
+  const { resolvePorts, envPort, CLASSIC_PORTS } = require('../../vendor/config/index.js');
+  const configPins = Manager.getConfig()?.ports || {};
+
+  const wanted = { livereload: envPort('livereload') || CLASSIC_PORTS.livereload };
+  const pins = {};
+  if (typeof configPins.livereload === 'number') pins.livereload = configPins.livereload;
+
+  // CDP is opt-in (OMEGA_CDP_PORT set) — allocate it too instead of the old
+  // "try port+1 manually" advice when 9222 is taken.
+  const cdpRequested = !!process.env.OMEGA_CDP_PORT;
+  if (cdpRequested) {
+    wanted.cdp = envPort('cdp') || CLASSIC_PORTS.cdp;
+    if (typeof configPins.cdp === 'number') pins.cdp = configPins.cdp;
+  }
+
+  const { ports, bumped } = await resolvePorts({ wanted, pins });
+  process.env.OMEGA_LIVERELOAD_PORT = String(ports.livereload);
+  if (cdpRequested) {
+    process.env.OMEGA_CDP_PORT = String(ports.cdp);
+  }
+  if (bumped.length) {
+    logger.log(`Ports bumped (classic taken): ${bumped.map((name) => `${name}→${ports[name]}`).join(', ')}`);
+  }
+  return ports;
+}
+
+// Resolve the electron package from the consumer project — it exports the path to
+// the platform binary. Node resolution walks UP from projectRoot, so an npm-workspaces
+// brand that hoists electron to the monorepo root resolves just as well as a target
+// carrying its own copy.
+function resolveElectron(projectRoot) {
+  return require(require.resolve('electron', { paths: [projectRoot] }));
+}
+
+/**
+ * The ENV lane's watcher (#681): every layer of the `.env` chain — company,
+ * brand, this target — and each layer's `.env.<environment>` overlay. A change
+ * reloads the cascade into process.env, and the log line names the FILE, never
+ * a value. Resolution and watching live in @omega.js/devkit/env-watch, shared
+ * with the web and extension dev lanes; this binds desktop's own target name.
+ *
+ * PRE-WIRING on desktop — it has NO consumer yet, and saying otherwise would be
+ * a lie. Two reasons, both structural:
+ *   1. The dev pipeline is `series(build, serve)` (gulp/main.js) — a ONE-SHOT
+ *      build that has already finished before this arms. Desktop runs no
+ *      watch+rebuild lane, so there is no "next rebuild" to read a new value.
+ *   2. `start()` spawns electron with a `childEnv` SNAPSHOT of process.env, so
+ *      a later reload in this gulp process cannot reach the running app.
+ * It stays wired because it is the shared devkit bind and it costs one unref'd
+ * watch; it becomes real the day desktop grows a watch+rebuild lane. Until
+ * then, do not claim desktop in the reload-lane docs.
+ *
+ * Scope even once that lands (the shared contract): a NEW key AND an EDITED
+ * value both land on the next rebuild, and a key dropped from the file is
+ * dropped from the process — `reloadEnv` re-reads what a file layer owns
+ * ([#724](https://github.com/Omega-JS-Stack/omega/issues/724)). A SHELL-set
+ * value still wins over every file, whatever the file now says.
+ *
+ * `serve` is where it arms because it is the dev lane's only long-running task
+ * — the build/package/publish series never include it, so a one-shot build
+ * never opens a watch it would have to close.
+ * @param {string} root - the target root
+ * @param {object} [options]
+ * @param {string} [options.environment] - the environment whose overlay counts
+ * @returns {{ inputs: Array<{ layer: string, path: string }>, close: function }}
+ */
+function watchEnvSources(root, options) {
+  return watchEnvChain({
+    projectDir: root,
+    target: 'desktop',
+    environment: options && options.environment,
+    log: (line) => logger.log(line),
+  });
+}
+
+function start(ports, done) {
+  const port = ports.livereload;
+  logger.log(`serve — livereload port=${port}`);
+
+  // PRE-WIRING, no consumer yet: the build above already ran one-shot and the
+  // electron child below snapshots env at spawn. See watchEnvSources.
+  watchEnvSources(projectRoot);
+
+  // Resolve the electron binary from the consumer project (see resolveElectron).
+  let electronBin;
+  try {
+    electronBin = resolveElectron(projectRoot);
+  } catch (e) {
+    logger.error(`Could not resolve electron from ${projectRoot} — no copy in the target or any parent node_modules.`);
+    return done(e);
+  }
+
+  // Forward all --flags from process.argv to the Electron child. Chromium silently ignores
+  // flags it doesn't recognize, so gulp's own (--cwd, --gulpfile, etc.) are harmless noise.
+  // Usage: `npm start -- --remote-debugging-port=9222`
+  // Shorthand: `OMEGA_CDP_PORT=9222 npm start`
+  const extraArgs = process.argv.slice(2).filter(arg => arg.startsWith('--'));
+  if (process.env.OMEGA_CDP_PORT && !extraArgs.some(a => a.startsWith('--remote-debugging-port'))) {
+    extraArgs.push(`--remote-debugging-port=${process.env.OMEGA_CDP_PORT}`);
+  }
+  const electronArgs = ['.', ...extraArgs];
+
+  logger.log(`Spawning electron: ${electronBin} ${electronArgs.join(' ')} (cwd=${projectRoot})`);
+
+  const childEnv = Object.assign({}, process.env, {
+    OMEGA_LIVERELOAD_PORT: String(port),
+    // Force chalk to keep colors when stdout is a pipe; the tee strips them before writing
+    // to the log file but the terminal still gets colored output.
+    FORCE_COLOR: '1',
+  });
+  // Defensive scrub at the spawn (friction 17c): the gulp boundary strips it,
+  // but a path that bypasses the boundary would make require('electron')
+  // return the npm stub inside the target → crash at app.setName.
+  delete childEnv.ELECTRON_RUN_AS_NODE;
+
+  // Pipe stdio (instead of 'inherit') so our parent-process attach-log-file tee can capture
+  // electron's stdout/stderr too. We forward each chunk to process.stdout/stderr.write, which
+  // is the function the tee already wraps.
+  const child = spawn(electronBin, electronArgs, {
+    cwd:   projectRoot,
+    stdio: ['inherit', 'pipe', 'pipe'],
+    env:   childEnv,
+  });
+
+  child.stdout.on('data', (chunk) => process.stdout.write(chunk));
+  child.stderr.on('data', (chunk) => process.stderr.write(chunk));
+
+  // If CDP was requested, verify the port came up after Electron boots.
+  const cdpPort = (process.env.OMEGA_CDP_PORT || '').trim()
+    || (extraArgs.find(a => a.startsWith('--remote-debugging-port=')) || '').split('=')[1];
+  if (cdpPort) {
+    setTimeout(() => {
+      const http = require('http');
+      const req = http.get(`http://127.0.0.1:${cdpPort}/json/version`, (res) => {
+        let body = '';
+        res.on('data', (d) => body += d);
+        res.on('end', () => {
+          try {
+            const info = JSON.parse(body);
+            logger.log(`CDP active on port ${cdpPort} — ${info.Browser || 'unknown'}`);
+          } catch (_) {
+            logger.log(`CDP active on port ${cdpPort}`);
+          }
+        });
+      });
+      req.on('error', () => {
+        // The port was allocator-probed free before spawn, so a dead endpoint
+        // means Electron itself didn't bring CDP up — not a port clash.
+        logger.warn(`CDP port ${cdpPort} not responding — the app may not have remote debugging enabled`);
+      });
+      req.setTimeout(3000, () => { req.destroy(); });
+    }, 5000);
+  }
+
+  child.on('exit', (code) => {
+    logger.log(`electron exited with code ${code}`);
+    // When electron quits, end the gulp task. In dev with watch this would re-spawn instead.
+    done();
+  });
+
+  child.on('error', (err) => {
+    logger.error('electron spawn error:', err);
+    done(err);
+  });
+};
+
+module.exports.resolveElectron = resolveElectron;
+module.exports.watchEnvSources = watchEnvSources;

package/dist/hooks/notarize.js

@@ -0,0 +1,70 @@
+// Real macOS notarization implementation. Lives inside @omega.js/desktop — consumers can extend it via
+// hooks/notarize/post.js (called after this completes successfully).
+//
+// Uses Apple's notarytool with the App Store Connect API key. Legacy Apple ID + app-specific
+// password flow is deliberately NOT supported.
+//
+// Required env vars:
+//   APPLE_API_KEY     — path to AuthKey_XXXXXXXXXX.p8 (set by @omega.js/desktop CI workflow from base64-encoded secret)
+//   APPLE_API_KEY_ID  — 10-char Key ID (matches the XXXXXXXXXX in the filename)
+//   APPLE_API_ISSUER  — issuer UUID from App Store Connect → Users and Access → Keys
+//
+// Skipped automatically when:
+//   - building for a non-darwin platform
+//   - any of the env vars above is missing (warns, doesn't fail — useful for dev builds without certs)
+
+const path = require('path');
+const fs   = require('fs');
+const Logger = require('../lib/logger');
+
+const logger = new Logger('notarize');
+
+module.exports = async function notarize(context) {
+  const { electronPlatformName, appOutDir } = context;
+
+  if (electronPlatformName !== 'darwin') {
+    return;
+  }
+
+  const appleApiKey    = process.env.APPLE_API_KEY;
+  const appleApiKeyId  = process.env.APPLE_API_KEY_ID;
+  const appleApiIssuer = process.env.APPLE_API_ISSUER;
+
+  if (!appleApiKey || !appleApiKeyId || !appleApiIssuer) {
+    logger.warn('Skipping — set APPLE_API_KEY, APPLE_API_KEY_ID, APPLE_API_ISSUER to notarize.');
+    return;
+  }
+
+  const apiKeyPath = path.isAbsolute(appleApiKey)
+    ? appleApiKey
+    : path.resolve(process.cwd(), appleApiKey);
+
+  if (!fs.existsSync(apiKeyPath)) {
+    throw new Error(`[notarize] APPLE_API_KEY file not found at ${apiKeyPath}`);
+  }
+
+  const { notarize } = require('@electron/notarize');
+  const appName = context.packager.appInfo.productFilename;
+  const appPath = path.join(appOutDir, `${appName}.app`);
+
+  logger.log(`Notarizing ${appName} via App Store Connect API key (${appleApiKeyId})...`);
+  const start = Date.now();
+
+  await notarize({
+    tool:          'notarytool',
+    appPath,
+    appleApiKey:   apiKeyPath,
+    appleApiKeyId,
+    appleApiIssuer,
+  });
+
+  const duration = Math.round((Date.now() - start) / 1000);
+  logger.log(`Done in ${duration}s.`);
+
+  // After @omega.js/desktop's real notarization, optionally invoke the consumer's hooks/notarize/post.js as
+  // an extension point. The consumer hook can do post-notarize work (custom stapling,
+  // archiving, notifications, etc.). It is purely additive — @omega.js/desktop's real notarize always runs
+  // first.
+  const runConsumerHook = require('../utils/run-consumer-hook.js');
+  await runConsumerHook('notarize/post', context);
+};

package/dist/index.js

@@ -0,0 +1,14 @@
+// Default export — re-exports per-process Managers + version.
+// Most consumers should use the per-process subpath imports instead:
+//   require('@omega.js/desktop/main')
+//   require('@omega.js/desktop/renderer')
+//   require('@omega.js/desktop/preload')
+const package = require('../package.json');
+
+module.exports = {
+  version:  package.version,
+  Main:     require('./main.js'),
+  Renderer: require('./renderer.js'),
+  Preload:  require('./preload.js'),
+  Build:    require('./build.js'),
+};

package/dist/lib/_menu-mixin.js

@@ -0,0 +1,199 @@
+// Shared id-path helpers used by tray, menu, and context-menu. All three deal with the same
+// data shape — an array of MenuItemConstructorOptions descriptors with optional `submenu`
+// arrays — so the find/insert/update/remove logic lives here once.
+//
+// "Id paths" are slash-separated strings: `main/check-for-updates`, `view/developer/toggle-devtools`.
+// They map onto the descriptor tree by following each segment as a child id (via id field, NOT
+// label). Single-segment ids (`copy`, `tray-quit`) are also valid — they just match top-level.
+//
+// All functions are pure-ish: they mutate the items array (or a sub-array) in place and return
+// a boolean indicating whether anything was found/changed. Callers are expected to call their
+// own re-render after a mutation.
+
+// Find the descriptor at `idPath` within `items`. Returns the live descriptor or null.
+//
+// We match items by their **full id field**, not by walking segments. So an item with
+// `id: 'main/check-for-updates'` is found via lookup of 'main/check-for-updates' regardless
+// of whether the consumer thinks of it as a path. This keeps the API "id-as-path" without
+// forcing the data structure to have segmented ids at every nesting level.
+//
+// As a fallback, when a search by full-id misses, we walk the path segments treating
+// each segment as the item's **last** path component (so `main/check-for-updates` also
+// matches an item with id `'check-for-updates'` nested under one with id `'main'`). This
+// handles consumers who write short ids without baking the parent prefix in.
+function findItem(items, idPath) {
+  if (!Array.isArray(items) || !idPath) return null;
+
+  // Fast path: full-id match anywhere in the tree.
+  const direct = findById(items, idPath);
+  if (direct) return direct;
+
+  // Fallback: walk segments, matching each by id ===  segment OR id ending in `/${segment}`.
+  const segments = String(idPath).split('/').filter(Boolean);
+  if (segments.length <= 1) return null; // no useful fallback for single-segment
+
+  let current = items;
+  let match = null;
+  for (const seg of segments) {
+    match = (current || []).find((item) => item && idMatchesSegment(item.id, seg)) || null;
+    if (!match) return null;
+    current = match.submenu || [];
+  }
+  return match;
+}
+
+// Same as findItem, but also returns the parent array + index — used by remove + insert.
+function findItemWithLocation(items, idPath) {
+  if (!Array.isArray(items) || !idPath) return null;
+
+  // Fast path: full-id match anywhere in the tree.
+  const direct = findByIdWithLocation(items, idPath);
+  if (direct) return direct;
+
+  const segments = String(idPath).split('/').filter(Boolean);
+  if (segments.length <= 1) return null;
+
+  let parent = items;
+  let item = null;
+  let index = -1;
+  for (const seg of segments) {
+    index = (parent || []).findIndex((it) => it && idMatchesSegment(it.id, seg));
+    if (index < 0) return null;
+    item = parent[index];
+    if (seg === segments[segments.length - 1]) break;
+    parent = item.submenu || [];
+  }
+  return { parent, index, item };
+}
+
+// Treat `id` as matching `seg` when:
+//   - id === seg                                   (exact)
+//   - id ends with '/' + seg                       (id is a path, last component is seg)
+function idMatchesSegment(id, seg) {
+  if (!id) return false;
+  if (id === seg) return true;
+  return id.endsWith(`/${seg}`);
+}
+
+function findById(items, id) {
+  if (!Array.isArray(items)) return null;
+  for (const item of items) {
+    if (!item) continue;
+    if (item.id === id) return item;
+    if (Array.isArray(item.submenu)) {
+      const nested = findById(item.submenu, id);
+      if (nested) return nested;
+    }
+  }
+  return null;
+}
+
+function findByIdWithLocation(items, id) {
+  if (!Array.isArray(items)) return null;
+  for (let i = 0; i < items.length; i += 1) {
+    const item = items[i];
+    if (!item) continue;
+    if (item.id === id) return { parent: items, index: i, item };
+    if (Array.isArray(item.submenu)) {
+      const nested = findByIdWithLocation(item.submenu, id);
+      if (nested) return nested;
+    }
+  }
+  return null;
+}
+
+// Splice newItem into the parent array, before or after the item at idPath.
+// Returns true if the target was found and the splice happened, false otherwise.
+function insertRelative(items, idPath, newItem, position /* 'before' | 'after' */) {
+  const loc = findItemWithLocation(items, idPath);
+  if (!loc) return false;
+  const offset = position === 'before' ? 0 : 1;
+  loc.parent.splice(loc.index + offset, 0, newItem);
+  return true;
+}
+
+// Push newItem into the submenu of the descriptor at idPath. Creates submenu if absent.
+// Returns true if the parent was found, false otherwise.
+function appendInside(items, idPath, newItem) {
+  const target = findItem(items, idPath);
+  if (!target) return false;
+  if (!Array.isArray(target.submenu)) target.submenu = [];
+  target.submenu.push(newItem);
+  return true;
+}
+
+// Patch the descriptor at idPath in place. Returns true if found.
+function updateItem(items, idPath, patch) {
+  const item = findItem(items, idPath);
+  if (!item) return false;
+  Object.assign(item, patch || {});
+  return true;
+}
+
+// Remove the descriptor at idPath. Returns true if removed.
+function removeItem(items, idPath) {
+  const loc = findItemWithLocation(items, idPath);
+  if (!loc) return false;
+  loc.parent.splice(loc.index, 1);
+  return true;
+}
+
+// Build a unified id-path API for a host lib. The host provides:
+//   - getItems()       → returns the underlying items array (live reference)
+//   - render()         → re-renders the menu/tray after a mutation
+//   - logger           → for warnings on missing ids
+// Returns an object with find/has/update/remove/enable/show/hide/insertBefore/insertAfter/appendTo.
+function buildIdApi({ getItems, render, logger }) {
+  const warnMissing = (op, idPath) => {
+    logger.warn(`${op}: no item at id path "${idPath}"`);
+  };
+
+  return {
+    find(idPath)        { return findItem(getItems(), idPath); },
+    has(idPath)         { return Boolean(findItem(getItems(), idPath)); },
+    update(idPath, patch) {
+      const ok = updateItem(getItems(), idPath, patch);
+      if (ok) render(); else warnMissing('update', idPath);
+      return ok;
+    },
+    remove(idPath) {
+      const ok = removeItem(getItems(), idPath);
+      if (ok) render(); else warnMissing('remove', idPath);
+      return ok;
+    },
+    enable(idPath, value = true) {
+      return this.update(idPath, { enabled: Boolean(value) });
+    },
+    show(idPath, value = true) {
+      return this.update(idPath, { visible: Boolean(value) });
+    },
+    hide(idPath) {
+      return this.update(idPath, { visible: false });
+    },
+    insertBefore(idPath, item) {
+      const ok = insertRelative(getItems(), idPath, item, 'before');
+      if (ok) render(); else warnMissing('insertBefore', idPath);
+      return ok;
+    },
+    insertAfter(idPath, item) {
+      const ok = insertRelative(getItems(), idPath, item, 'after');
+      if (ok) render(); else warnMissing('insertAfter', idPath);
+      return ok;
+    },
+    appendTo(idPath, item) {
+      const ok = appendInside(getItems(), idPath, item);
+      if (ok) render(); else warnMissing('appendTo', idPath);
+      return ok;
+    },
+  };
+}
+
+module.exports = {
+  findItem,
+  findItemWithLocation,
+  insertRelative,
+  appendInside,
+  updateItem,
+  removeItem,
+  buildIdApi,
+};