@omega.js/desktop 0.52.0 → 0.54.0

package/dist/test/suites/renderer/tooltips.test.js

@@ -4,9 +4,9 @@
 // inserted after boot), title changes update the live instance, and removal
 // disposes it. Real DOM, real Bootstrap — the tip element actually renders.
 //
-// The harness wires the renderer Manager in the PRELOAD world (contextIsolation
+// The harness wires the renderer instance in the PRELOAD world (contextIsolation
 // — see harness/renderer-preload.js), so instance-level assertions and the
-// show trigger go through the `window.__emTestTooltip` probe (page-world
+// show trigger go through the `window.__omegaTestTooltip` probe (page-world
 // synthetic mouse events can't reach preload-world listeners). Real
 // hover-in-one-world behavior + `window.bootstrap` page exposure are covered
 // by consumer boot suites.
@@ -25,10 +25,10 @@ module.exports = defineCases({
     {
       name: 'the Bootstrap bundle loads — Tooltip is available',
       run: (ctx) => {
-        if (!window.__emTestTooltip.available()) {
-          throw new Error(`Bootstrap bundle failed to load: ${window.__emTestTooltip.error() || '(no require error — wiring bailed earlier)'}`);
+        if (!window.__omegaTestTooltip.available()) {
+          throw new Error(`Bootstrap bundle failed to load: ${window.__omegaTestTooltip.error() || '(no require error, wiring bailed earlier)'}`);
         }
-        ctx.expect(window.__emTestTooltip.available()).toBe(true);
+        ctx.expect(window.__omegaTestTooltip.available()).toBe(true);
       },
     },
     {
@@ -51,9 +51,9 @@ module.exports = defineCases({
         document.body.appendChild(el);
 
         // The auto-init observer creates the instance without any consumer code.
-        await until(() => window.__emTestTooltip.hasInstance('tt-show'));
+        await until(() => window.__omegaTestTooltip.hasInstance('tt-show'));
 
-        const shown = window.__emTestTooltip.showDirect('tt-show');
+        const shown = window.__omegaTestTooltip.showDirect('tt-show');
         ctx.expect(shown).toBe(true);
         await until(() => document.querySelector('.tooltip .tooltip-inner'));
         ctx.expect(document.querySelector('.tooltip .tooltip-inner').textContent).toBe('Hello from @omega.js/desktop');
@@ -80,13 +80,13 @@ module.exports = defineCases({
         el.setAttribute('data-bs-toggle', 'tooltip');
         el.setAttribute('data-bs-title', 'before');
         document.body.appendChild(el);
-        await until(() => window.__emTestTooltip.hasInstance('tt-retitle'));
+        await until(() => window.__omegaTestTooltip.hasInstance('tt-retitle'));
 
         el.setAttribute('data-bs-title', 'after');
         // The observer applies setContent asynchronously (mutation microtask) —
         // give it a beat, then show and assert the rendered text.
         await new Promise((r) => setTimeout(r, 100));
-        ctx.expect(window.__emTestTooltip.showDirect('tt-retitle')).toBe(true);
+        ctx.expect(window.__omegaTestTooltip.showDirect('tt-retitle')).toBe(true);
         await until(() => document.querySelector('.tooltip .tooltip-inner'));
         ctx.expect(document.querySelector('.tooltip .tooltip-inner').textContent).toBe('after');
 
@@ -118,7 +118,7 @@ module.exports = defineCases({
         el.setAttribute('title', 'plain title');
         document.body.appendChild(el);
 
-        await until(() => window.__emTestTooltip.hasInstance('tt-title-only'));
+        await until(() => window.__omegaTestTooltip.hasInstance('tt-title-only'));
 
         // The loop starved macrotasks — a timer firing IS the proof the
         // main thread survived the mutation settling.
@@ -129,8 +129,8 @@ module.exports = defineCases({
         // instance alive, and the tip renders the original text.
         ctx.expect(el.hasAttribute('title')).toBe(false);
         ctx.expect(el.getAttribute('data-bs-original-title')).toBe('plain title');
-        ctx.expect(window.__emTestTooltip.hasInstance('tt-title-only')).toBe(true);
-        ctx.expect(window.__emTestTooltip.showDirect('tt-title-only')).toBe(true);
+        ctx.expect(window.__omegaTestTooltip.hasInstance('tt-title-only')).toBe(true);
+        ctx.expect(window.__omegaTestTooltip.showDirect('tt-title-only')).toBe(true);
         await until(() => document.querySelector('.tooltip .tooltip-inner'));
         ctx.expect(document.querySelector('.tooltip .tooltip-inner').textContent).toBe('plain title');
 
@@ -155,11 +155,11 @@ module.exports = defineCases({
         el.setAttribute('data-bs-toggle', 'tooltip');
         el.setAttribute('data-bs-title', 'bye');
         document.body.appendChild(el);
-        await until(() => window.__emTestTooltip.hasInstance('tt-dispose'));
+        await until(() => window.__omegaTestTooltip.hasInstance('tt-dispose'));
 
         el.remove();
-        await until(() => !window.__emTestTooltip.hasInstance('tt-dispose'));
-        ctx.expect(window.__emTestTooltip.hasInstance('tt-dispose')).toBe(false);
+        await until(() => !window.__omegaTestTooltip.hasInstance('tt-dispose'));
+        ctx.expect(window.__omegaTestTooltip.hasInstance('tt-dispose')).toBe(false);
       },
     },
   ],

package/dist/test/suites/renderer/{window-em-surface.test.js → window-desktop-surface.test.js}

@@ -1,5 +1,6 @@
-// Renderer-layer suite — asserts the `window.desktop` surface exposed by preload is shaped
-// correctly and that the storage proxy round-trips through IPC into the main store.
+// Renderer-layer suite: asserts the `window.desktop` surface exposed by preload is shaped
+// correctly, that the renderer instance carries it as `omega.desktop`, and that the
+// storage proxy round-trips through IPC into the main store.
 //
 // Runs inside a hidden BrowserWindow spawned by the test harness. The renderer harness
 // reconstructs each `run` function via `new Function('ctx', body)` so the function bodies
@@ -10,7 +11,7 @@ const defineCases = require('../../../vendor/devkit/test/define-cases.js');
 module.exports = defineCases({
   type: 'suite',
   layer: 'renderer',
-  description: 'window.desktop surface + storage proxy roundtrip',
+  description: 'window.desktop surface + omega.desktop + storage proxy roundtrip',
   tests: [
     {
       name: 'window.desktop is exposed and is an object',
@@ -19,6 +20,25 @@ module.exports = defineCases({
         ctx.expect(window.desktop).toBeTruthy();
       },
     },
+    {
+      // The preload global keeps its name and its shape: everything that
+      // crosses to the main process, under main's names
+      name: 'window.desktop carries the bridge namespaces, unchanged',
+      run: (ctx) => {
+        ctx.expect(Object.keys(window.desktop).sort()).toEqual(['analytics', 'autoUpdater', 'context', 'fontawesome', 'ipc', 'logger', 'remoteConfig', 'storage', 'theme', 'usage']);
+      },
+    },
+    {
+      // The renderer instance puts the SAME object under `omega.desktop`;
+      // `omega.storage` stays the client's page store, the app store is
+      // `omega.desktop.storage`
+      name: 'the renderer instance\'s omega.desktop IS the preload bridge',
+      run: (ctx) => {
+        ctx.expect(window.__omegaTestInstance.desktopIsBridge()).toBe(true);
+        ctx.expect(window.__omegaTestInstance.desktopKeys()).toEqual(Object.keys(window.desktop).sort());
+        ctx.expect(window.__omegaTestInstance.storageIsPageStore()).toBe(true);
+      },
+    },
     {
       name: 'window.desktop.ipc has invoke / on / send',
       run: (ctx) => {
@@ -29,10 +49,10 @@ module.exports = defineCases({
     },
     {
       // wave-5 F4: ipc.on used to return ipcRenderer (stripped to a useless
-      // object across the contextBridge) — docs/ipc.md promises an unsubscribe fn.
+      // object across the contextBridge) — docs/desktop/ipc.md promises an unsubscribe fn.
       name: 'ipc.on returns an unsubscribe function (docs contract)',
       run: (ctx) => {
-        const off = window.desktop.ipc.on('em-test:noop-channel', () => {});
+        const off = window.desktop.ipc.on('omega-test:noop-channel', () => {});
         ctx.expect(typeof off).toBe('function');
         off(); // must not throw
       },
@@ -66,7 +86,7 @@ module.exports = defineCases({
     {
       name: 'storage.set + storage.get round-trips through IPC',
       run: async (ctx) => {
-        const key = '__em_renderer_test_value';
+        const key = '__omega_renderer_test_value';
         await window.desktop.storage.set(key, { hello: 'world', n: 42 });
         const value = await window.desktop.storage.get(key);
         ctx.expect(value).toEqual({ hello: 'world', n: 42 });
@@ -76,7 +96,7 @@ module.exports = defineCases({
     {
       name: 'storage.has reports correctly',
       run: async (ctx) => {
-        const key = '__em_renderer_has_test';
+        const key = '__omega_renderer_has_test';
         await window.desktop.storage.set(key, 'x');
         const yes = await window.desktop.storage.has(key);
         ctx.expect(yes).toBe(true);
@@ -88,7 +108,7 @@ module.exports = defineCases({
     {
       name: 'storage.delete removes the key',
       run: async (ctx) => {
-        const key = '__em_renderer_delete_test';
+        const key = '__omega_renderer_delete_test';
         await window.desktop.storage.set(key, 'gone');
         await window.desktop.storage.delete(key);
         const value = await window.desktop.storage.get(key, 'fallback');

package/dist/test/utils/extended-mode-warning.js

@@ -1,6 +1,6 @@
 // TEST_EXTENDED_MODE warning — SSOT for consistent messaging.
 //
-// The headline + shape live in @omega.js/devkit (mirrored across @omega.js/backend/BXM/UJM); these
+// The headline + shape live in @omega.js/devkit (shared by every framework); these
 // detail lines describe @omega.js/desktop's blast radius. Used by the test command (printed to
 // console + teed to logs/test.log).
 const { makeExtendedModeWarning } = require('../../vendor/devkit/test/extended-mode-warning.js');

package/dist/utils/boot-harness.js

@@ -0,0 +1,56 @@
+// boot-harness: hands the booted main-process instance to the boot test lane's
+// harness. The runner sets OMEGA_TEST_BOOT=1 + OMEGA_TEST_BOOT_HARNESS=<absolute path>
+// + OMEGA_TEST_BOOT_SPEC=<path> before spawning electron; the harness emits
+// __OMEGA_TEST__ JSON lines on stdout (parsed by test/runners/boot.js) then
+// app.exit()s.
+//
+// A runtime env-var path, never a static `require('./test/harness/...')`:
+// @omega.js/desktop is bundled into the consumer's bundle, and a static require would
+// either get inlined (bundling test code into production) or dead-code-eliminated.
+// An env-var path stays external and can only resolve when the runner sets it.
+
+const { TEST_EVENT_PREFIX } = require('./test-events.js');
+
+/**
+ * Start the boot harness against `omega` when this process is a boot test run.
+ * @param {object} omega - the initialized main-process instance.
+ */
+function startBootHarness(omega) {
+  // Only a boot test run carries the flag; every other boot returns here
+  if (process.env.OMEGA_TEST_BOOT !== '1') {
+    return;
+  }
+
+  global.__omega_instance = omega;
+  const harnessPath = process.env.OMEGA_TEST_BOOT_HARNESS;
+
+  if (!harnessPath) {
+    fail('OMEGA_TEST_BOOT=1 but OMEGA_TEST_BOOT_HARNESS not set');
+    return;
+  }
+
+  // Defer the harness so the consumer's `omega.initialize().then(() => { ... })`
+  // callback gets a chance to run first. @omega.js/desktop doesn't auto-create any
+  // windows; the consumer's main.js does it inside .then(). Run synchronously and
+  // that callback hasn't fired yet, so `omega.windows.get('main')` would be null.
+  // setImmediate flushes the microtask queue (where promise callbacks live)
+  // before the boot harness inspects state.
+  setImmediate(() => {
+    try {
+      // A variable specifier, so the bundler leaves the call alone and it
+      // resolves at RUNTIME against the path the runner set (see above).
+      const harness = require(harnessPath);
+      harness.run(omega);
+    } catch (e) {
+      fail(`boot harness failed to load: ${e.message}`);
+    }
+  });
+}
+
+// Report a fatal harness event on the runner's channel and end the run
+function fail(message) {
+  process.stdout.write(`${TEST_EVENT_PREFIX}${JSON.stringify({ event: 'fatal', message })}\n`);
+  require('electron').app.exit(1);
+}
+
+module.exports = startBootHarness;

package/dist/utils/build-pipeline.js

@@ -1,4 +1,4 @@
-// The build-mode pipeline shared by the `build`, `package`, and `publish` verbs.
+// The pipeline shared by the `build`, `package`, `publish` and `dev` verbs.
 //
 // The CLI verbs are canonical and the synced projectScripts are thin
 // `omega <verb>` aliases, so a verb must run the pipeline ITSELF and never
@@ -10,8 +10,8 @@
 // Libraries
 const { execute } = require('node-powertools');
 
-function gulpCommand(task) {
-  return `npm run gulp -- ${task}`;
+function gulpCommand(task, args = []) {
+  return `npm run gulp -- ${[task, ...args].join(' ')}`;
 }
 
 // Default step implementations — required lazily so requiring a plan never
@@ -30,7 +30,7 @@ const RUNNERS = {
   'ship-keys': () => require('./ship-keys.js').assertShipKeys(),
   // `strict` rides the STEP: publish declares it (#891), a bare verb does not.
   'validate-certs': (options, step) => require('../commands/validate-certs.js')({ ...options, strict: step.strict === true || options.strict === true }),
-  gulp: (options, step) => execute(gulpCommand(step.task), { log: true }),
+  gulp: (options, step) => execute(gulpCommand(step.task, step.args), { log: true }),
 };
 
 async function runPipeline(plan, options, runners) {

package/dist/utils/mode-helpers.js

@@ -1,5 +1,5 @@
-// Runtime mode helpers, shared across all three context Managers (main /
-// renderer / preload) and the build-time Manager.
+// Runtime mode helpers: plain functions the process `Omega` classes (src/main.js,
+// src/preload.js, src/renderer.js) and the build-time module (src/build.js) call.
 //
 // The environment half is NOT implemented here any more
 // ([#817](https://github.com/Omega-JS-Stack/omega/issues/817)). It is
@@ -57,20 +57,7 @@ function getVersion() {
   }
 }
 
-// Mix the helpers into a Manager constructor's prototype + the constructor itself
-// (so `Manager.isTesting()` works statically too). The environment four come from
-// the shared module's own attachTo(), so every desktop entry point and every
-// sibling framework hangs the identical functions; getVersion() is desktop's and
-// is attached beside them. The URL helpers in url-helpers.js depend on
-// this.getEnvironment() existing, so this attachTo() runs first.
-function attachTo(Manager) {
-  environment.attachTo(Manager);
-  Manager.prototype.getVersion = getVersion;
-  Manager.getVersion = getVersion;
-}
-
 module.exports = {
-  attachTo,
   isDevelopment: environment.isDevelopment,
   isProduction: environment.isProduction,
   isTesting: environment.isTesting,

package/dist/utils/runner-env.js

@@ -35,6 +35,8 @@
 const fs   = require('fs');
 const os   = require('os');
 const path = require('path');
+const { envLine, assertEnvReadsBack } = require('../vendor/config/index.js');
+const { setEnvLines } = require('../vendor/devkit/env-lines.js');
 
 // Runner files live under %LOCALAPPDATA%\omega-runner — a per-user path that
 // doesn't need admin to read/write. Set OMEGA_RUNNER_HOME to override.
@@ -308,37 +310,20 @@ function ensureRunnerEnvFile(home) {
   return true;
 }
 
-// Write values into the file IN PLACE: an existing `KEY=` line (commented or
-// not) is replaced, a key the file never had is appended. Comments and order
-// survive, so the file stays the one a person reads.
+// Write values into the file IN PLACE through devkit's setEnvLines: a key's
+// first line or `# KEY=""` placeholder takes the new line and later ones drop,
+// so dotenv reads the new value; a key the file never had is appended. Comments
+// and order survive, so the file stays the one a person reads.
 function writeRunnerEnvValues(home, values) {
-  // Every value double-quoted, the one .env quoting rule this repo writes
-  // everywhere. dotenv reads a double-quoted value back verbatim and has no
-  // escape for a `"` inside one, so a value carrying one cannot be written at
-  // all: refuse it — naming the key and the character — before the file is
-  // touched, rather than save a value that reads back wrong.
-  const serialize = (key, value) => `${key}="${value}"`;
-  for (const [key, value] of Object.entries(values)) {
-    if (String(value).includes('"')) {
-      throw new Error(`${key} contains a double quote (") — a .env value cannot carry one. Remove it, then set ${key} again.`);
-    }
-  }
+  // envLine is the one .env serializer; it refuses, naming the key, a value
+  // dotenv would read back changed, before the file is touched.
+  const lineFor = Object.fromEntries(Object.entries(values).map(([key, value]) => [key, envLine(key, value)]));
 
   ensureRunnerEnvFile(home);
-  const file  = runnerEnvFile(home);
-  const lines = fs.readFileSync(file, 'utf8').split(/\r?\n/);
-  const seen  = new Set();
-
-  const out = lines.map((line) => {
-    const m = /^\s*#?\s*([A-Z][A-Z0-9_]*)\s*=/.exec(line);
-    if (!m || !(m[1] in values) || seen.has(m[1])) return line;
-    seen.add(m[1]);
-    return serialize(m[1], String(values[m[1]]));
-  });
-  for (const [key, value] of Object.entries(values)) {
-    if (!seen.has(key)) out.push(serialize(key, String(value)));
-  }
-  fs.writeFileSync(file, out.join('\n').replace(/\n*$/, '\n'));
+  const file    = runnerEnvFile(home);
+  const content = setEnvLines(fs.readFileSync(file, 'utf8'), lineFor);
+  assertEnvReadsBack(content, values);
+  fs.writeFileSync(file, content);
   return file;
 }
 

package/dist/utils/ship-keys.js

@@ -21,8 +21,8 @@
 
 const { shipPlan, missingShipKeys, shipKeyRefusal } = require('../vendor/devkit/ship-plan.js');
 
-const Manager = new (require('../build.js'));
-const logger = Manager.logger('ship-keys');
+const build = require('../build.js');
+const logger = build.logger('ship-keys');
 
 /**
  * Refuse a publish whose declared formats have no credential to ship with.
@@ -36,7 +36,7 @@ const logger = Manager.logger('ship-keys');
 function assertShipKeys(options) {
   options = options || {};
 
-  const config = options.config || Manager.getConfig();
+  const config = options.config || build.getConfig();
   const plan = shipPlan(config, 'desktop');
   const missing = missingShipKeys(plan, options.env || process.env);
 

package/dist/utils/signing-status.js

@@ -0,0 +1,51 @@
+// signing-status: logs whether a PACKAGED app is code-signed, and by whom, so
+// runtime.log answers "did this build ship signed?" without a terminal. Fire and
+// forget: the checks run async and only ever log. An unpackaged (dev or test)
+// boot has nothing signed to report, so it skips.
+
+/**
+ * Log this app's signing status (packaged apps only).
+ * @param {object} logger - the main process's logger.
+ */
+function logSigningStatus(logger) {
+  try {
+    if (!require('electron').app.isPackaged) {
+      return;
+    }
+
+    const { execFile } = require('child_process');
+
+    if (process.platform === 'darwin') {
+      const appIndex = process.execPath.indexOf('.app');
+      if (appIndex === -1) throw new Error('no .app in execPath');
+      const appPath = process.execPath.substring(0, appIndex + 4);
+      execFile('codesign', ['--verify', '--deep', '--strict', appPath], (err) => {
+        if (err) {
+          logger.warn(`signing: NOT signed (${err.message.split('\n')[0]})`);
+          return;
+        }
+        execFile('codesign', ['-dv', appPath], { encoding: 'utf8' }, (e2, stdout, stderr) => {
+          const authority = (stderr || '').match(/Authority=(.+)/);
+          const adhoc = (stderr || '').includes('Signature=adhoc');
+          const label = adhoc ? 'ad-hoc' : (authority ? authority[1] : 'unknown');
+          logger.log(`signing: signed (${label})`);
+        });
+      });
+    } else if (process.platform === 'win32') {
+      execFile('powershell', ['-NoProfile', '-Command', `(Get-AuthenticodeSignature '${process.execPath}').Status`], { encoding: 'utf8' }, (err, stdout) => {
+        const status = (stdout || '').trim();
+        if (err || status === 'NotSigned') {
+          logger.warn('signing: NOT signed');
+        } else {
+          logger.log(`signing: signed (${status})`);
+        }
+      });
+    } else {
+      logger.log('signing: n/a (Linux has no OS-level code signing)');
+    }
+  } catch (e) {
+    logger.warn(`signing: check failed (${e.message})`);
+  }
+}
+
+module.exports = logSigningStatus;

package/dist/utils/test-events.js

@@ -0,0 +1,7 @@
+// The ONE prefix a desktop test harness writes before each JSON event line on
+// stdout (test/harness/main-entry.js, test/harness/boot-entry.js,
+// utils/boot-harness.js) and each runner reads back (test/runners/electron.js,
+// test/runners/boot.js).
+const TEST_EVENT_PREFIX = '__OMEGA_TEST__';
+
+module.exports = { TEST_EVENT_PREFIX };

package/dist/utils/test-stealth.js

@@ -8,23 +8,23 @@
 //   - main.js — app-level activation suppression on macOS (accessory policy via
 //     app.dock.hide(), so a launching test app never steals keyboard focus)
 //   - test/harness/main-entry.js — same suppression for the spawned harness app,
-//     which initializes its Manager only after app ready (too late to prevent
+//     which initializes its omega instance only after app ready (too late to prevent
 //     the launch activation)
 //
-// Pass the Manager when you have one: its isTesting() reads the environment the
-// Manager's own config was baked with. Without one (the harness, pre-Manager
+// Pass the omega instance when you have one: its isTesting() reads the environment
+// its own config was baked with. Without one (the harness, pre-initialize
 // code) the standalone check reads the process's OMEGA_ENVIRONMENT, the one
 // input every lane sets ([#817](https://github.com/Omega-JS-Stack/omega/issues/817));
 // the test runners spawn their children naming `testing`.
 //
 // Usage:
 //   const isTestStealth = require('./utils/test-stealth.js');
-//   if (isTestStealth(manager)) { ... }
+//   if (isTestStealth(omega)) { ... }
 
 const { isTesting } = require('./mode-helpers.js');
 
-function isTestStealth(manager) {
-  const testing = manager ? manager.isTesting() : isTesting();
+function isTestStealth(omega) {
+  const testing = omega ? omega.isTesting() : isTesting();
   return testing && process.env.OMEGA_TEST_SHOW !== '1';
 }
 

package/dist/utils/url-helpers.js

@@ -1,13 +1,14 @@
-// Backend URL helpers, shared across all Manager contexts (main / renderer / preload /
-// build). Mirror @omega.js/client's contract so @omega.js/desktop apps can hit the same dev/prod backends as
-// UJM and BXM consumers.
+// Backend URL helpers: plain functions the process `Omega` classes (main / renderer /
+// preload) call, each passing itself as `context`. Mirror
+// @omega.js/client's contract so @omega.js/desktop apps can hit the same dev/prod backends as
+// @omega.js/web and @omega.js/extension consumers.
 //
 // `getEnvironment()` is the SINGLE SOURCE OF TRUTH and lives in src/utils/mode-helpers.js
-// (alongside the is*() family; mirrors @omega.js/backend/UJM/BXM). It returns exactly ONE of
+// (alongside the is*() family, the same on every framework). It returns exactly ONE of
 // 'development' | 'testing' | 'production' (mutually exclusive; testing wins).
 //
-// `getFunctionsUrl()` / `getApiUrl()` / `getWebsiteUrl()` route through
-// `this.getEnvironment()` and resolve to LOCAL urls in BOTH development AND testing —
+// `getFunctionsUrl()` / `getApiUrl()` / `getWebsiteUrl()` route through the context's
+// `getEnvironment()` and resolve to LOCAL urls in BOTH development AND testing,
 // callers normally pass NO argument. An explicit `environment` arg is an override
 // (used mainly by tests to pin a specific environment's mapping).
 
@@ -54,9 +55,16 @@ function requiredPort(context, envName, name) {
   return port;
 }
 
-function getFunctionsUrl(environment) {
-  const env = environment || this.getEnvironment();
-  const projectId = this?.config?.cloud?.config?.projectId;
+/**
+ * The Cloud Functions base: the local emulator in development and testing, the
+ * project's cloudfunctions.net host in production.
+ * @param {object} context - the instance asking (its `config` and `getEnvironment()`).
+ * @param {string} [environment] - an override of the running environment.
+ * @returns {string} the functions base URL.
+ */
+function getFunctionsUrl(context, environment) {
+  const env = environment || context.getEnvironment();
+  const projectId = context.config?.cloud?.config?.projectId;
 
   if (!projectId) {
     throw new Error('cloud.config.projectId not set in config/omega.json5');
@@ -66,15 +74,22 @@ function getFunctionsUrl(environment) {
   // same three-step chain getApiUrl() walks: the OMEGA_*_PORT env channel (N7),
   // then the baked map, then the classic default.
   if (env === 'development' || env === 'testing') {
-    const port = requiredPort(this, 'OMEGA_FUNCTIONS_PORT', 'functions');
+    const port = requiredPort(context, 'OMEGA_FUNCTIONS_PORT', 'functions');
     return `http://localhost:${port}/${projectId}/us-central1`;
   }
 
   return `https://us-central1-${projectId}.cloudfunctions.net`;
 }
 
-function getApiUrl(environment) {
-  const env = environment || this.getEnvironment();
+/**
+ * The API base: the local stack in development and testing, the brand's api
+ * subdomain in production.
+ * @param {object} context - the instance asking (its `config` and `getEnvironment()`).
+ * @param {string} [environment] - an override of the running environment.
+ * @returns {string} the API base URL.
+ */
+function getApiUrl(context, environment) {
+  const env = environment || context.getEnvironment();
 
   // Local for development OR testing; production otherwise. Mirrors
   // @omega.js/backend's getApiUrl (N7): a resolved OMEGA_HTTPS_PORT means
@@ -82,16 +97,16 @@ function getApiUrl(environment) {
   // hosting emulator (env port, then baked port). Neither resolved is a broken
   // build, not a case to assume the classic 5002 through (#834).
   if (env === 'development' || env === 'testing') {
-    const httpsPort = localPort(this, 'OMEGA_HTTPS_PORT', 'https');
+    const httpsPort = localPort(context, 'OMEGA_HTTPS_PORT', 'https');
     return httpsPort
       ? `https://localhost:${httpsPort}`
-      : `http://localhost:${requiredPort(this, 'OMEGA_HOSTING_PORT', 'hosting')}`;
+      : `http://localhost:${requiredPort(context, 'OMEGA_HOSTING_PORT', 'hosting')}`;
   }
 
   // Prod: api.<brand host>. Mirrors @omega.js/client.getApiUrl. Never derive
   // from authDomain — it is an auth concern (the brand host, with /__/auth/*
   // self-hosted at build time) and must stay free to change independently.
-  const brandUrl = this?.config?.brand?.url;
+  const brandUrl = context.config?.brand?.url;
   if (!brandUrl) {
     throw new Error('brand.url not set in config/omega.json5');
   }
@@ -113,20 +128,25 @@ function getApiUrl(environment) {
 // Prod → `config.brand.url`. Use this whenever app code wants to link out to "the
 // website" (Help → Website tray/menu items, "Open in browser," billing portal
 // landings) so dev runs don't punch out to the real domain.
-function getWebsiteUrl(environment) {
-  const env = environment || this.getEnvironment();
+/**
+ * @param {object} context - the instance asking (its `config` and `getEnvironment()`).
+ * @param {string} [environment] - an override of the running environment.
+ * @returns {string} the website origin (dev) or brand.url (production).
+ */
+function getWebsiteUrl(context, environment) {
+  const env = environment || context.getEnvironment();
 
   // Local for development OR testing; production otherwise.
   if (env === 'development' || env === 'testing') {
-    const origin = this?.config?.dev?.origin;
+    const origin = context.config?.dev?.origin;
     if (origin) {
       return origin;
     }
 
-    return `https://localhost:${requiredPort(this, 'OMEGA_WEBSITE_PORT', 'website')}`;
+    return `https://localhost:${requiredPort(context, 'OMEGA_WEBSITE_PORT', 'website')}`;
   }
 
-  const url = this?.config?.brand?.url;
+  const url = context.config?.brand?.url;
   if (!url) {
     throw new Error('brand.url not set in config/omega.json5');
   }
@@ -134,19 +154,25 @@ function getWebsiteUrl(environment) {
 }
 
 // Sign-in URL that round-trips an auth token back to the app. Points at the brand
-// website's /signin page (UJM), chained through its /token page so a successful login
+// website's /signin page, chained through its /token page so a successful login
 // mints a Firebase custom token and redirects to `<brand.id>://auth/token` — the
-// deep-link built-in that hands the token to client-bridge (signInWithCustomToken).
+// deep-link built-in that hands the token to lib/auth.js (signInWithCustomToken).
 // Same env split as getWebsiteUrl: dev/test → the local website, prod → brand.url.
 // The token page redirects with ?authToken=<token> — the ONE modern shape the
-// auth/token route reads (legacy-app formats are UJM's concern, not @omega.js/desktop's).
+// auth/token route reads (older formats are not read).
 //
 // `returnUrl` overrides the final hop (default: `<brand.id>://auth/token`). Used by
 // lib/auth-flow.js in dev, where the custom scheme isn't OS-registered — the flow
 // returns to a loopback HTTP listener instead (RFC 8252 §7.3).
-function getAuthUrl(environment, returnUrl) {
-  const site = this.getWebsiteUrl(environment);
-  const brandId = this?.config?.brand?.id;
+/**
+ * @param {object} context - the instance asking (its `config` and `getEnvironment()`).
+ * @param {string} [environment] - an override of the running environment.
+ * @param {string} [returnUrl] - the final hop, `<brand.id>://auth/token` by default.
+ * @returns {string} the sign-in URL.
+ */
+function getAuthUrl(context, environment, returnUrl) {
+  const site = getWebsiteUrl(context, environment);
+  const brandId = context.config?.brand?.id;
   if (!brandId) {
     throw new Error('brand.id not set in config/omega.json5');
   }
@@ -159,23 +185,7 @@ function getAuthUrl(environment, returnUrl) {
   return signinUrl.toString();
 }
 
-// Mix the URL helpers into a Manager constructor's prototype + the constructor itself.
-// getEnvironment() is NOT attached here — it's the SSOT in src/utils/mode-helpers.js.
-// These helpers call `this.getEnvironment()`, so mode-helpers' attachTo() must run before
-// (or alongside) this one — every Manager entry point attaches mode-helpers first.
-function attachTo(Manager) {
-  Manager.prototype.getFunctionsUrl  = getFunctionsUrl;
-  Manager.prototype.getApiUrl        = getApiUrl;
-  Manager.prototype.getWebsiteUrl    = getWebsiteUrl;
-  Manager.prototype.getAuthUrl       = getAuthUrl;
-  Manager.getFunctionsUrl  = getFunctionsUrl;
-  Manager.getApiUrl        = getApiUrl;
-  Manager.getWebsiteUrl    = getWebsiteUrl;
-  Manager.getAuthUrl       = getAuthUrl;
-}
-
 module.exports = {
-  attachTo,
   localPort,
   requiredPort,
   getFunctionsUrl,