@omega.js/desktop 0.1.0

package/docs/context-menu.md

@@ -0,0 +1,112 @@
+# Context Menu (Right-Click)
+
+File-based context menu. Unlike tray and application menu (called once at boot), the context-menu definition is called **every time the user right-clicks** — so it gets fresh `params` each time and can vary the menu by selection.
+
+## Config
+
+No config block. Path is conventional: `src/integrations/context-menu/index.js`. To opt out, call `manager.contextMenu.disable()` from your main entry — after that, right-click events are silently swallowed.
+
+## Definition file
+
+```js
+// src/integrations/context-menu/index.js
+module.exports = ({ manager, menu, params, webContents }) => {
+  // Easiest: start from @omega.js/desktop's defaults, then customize per event.
+  menu.useDefaults();
+
+  // Add a "Search Google" entry when text is selected:
+  if (params.selectionText) {
+    menu.insertAfter('copy', {
+      id: 'search-google',
+      label: `Search "${params.selectionText.slice(0, 20)}"`,
+      click: () => require('electron').shell.openExternal(
+        `https://google.com/search?q=${encodeURIComponent(params.selectionText)}`,
+      ),
+    });
+  }
+
+  // Hide the dev-tools entries even in development:
+  menu.remove('toggle-devtools');
+};
+```
+
+Calling no `menu.*` methods (or `menu.clear()` after `useDefaults()` with nothing added) **suppresses the popup** entirely.
+
+## Builder API (per event)
+
+```js
+menu.item(descriptor)
+menu.separator()
+menu.submenu(label, items)
+menu.useDefaults()             // populate with @omega.js/desktop's defaults based on params
+menu.clear()                   // wipe items added so far this event
+```
+
+## Id-path API (per event)
+
+Same shape across menu / tray / context-menu. Available **inside the definition fn** on the `menu` builder. Operates on the items being built for the current right-click event:
+
+```js
+.find(idPath)
+.has(idPath)
+.update(idPath, patch)
+.remove(idPath)
+.enable(idPath, bool = true)
+.show(idPath, bool = true)
+.hide(idPath)
+.insertBefore(idPath, item)
+.insertAfter(idPath, item)
+.appendTo(idPath, item)
+```
+
+Context-menu ids are **flat** — no `context/` prefix needed (the lib namespace is implicit). Submenus you build with `menu.submenu(...)` are addressable as `parent/child` paths via the resolver.
+
+(Runtime-on-`manager.contextMenu` mutators don't apply here — items are rebuilt every event. Mutate inside the definition fn instead.)
+
+## Default template ids
+
+@omega.js/desktop's `useDefaults()` populates items based on `params`. Every default item carries an id you can target:
+
+| ID | When it appears |
+|---|---|
+| `undo`, `redo` | `params.editFlags.canUndo` / `canRedo` |
+| `cut`, `copy`, `paste`, `paste-and-match-style`, `select-all` | `params.isEditable` |
+| `copy` | `params.selectionText` (read-only) |
+| `open-link`, `copy-link` | `params.linkURL` |
+| `reload` | always |
+| `inspect`, `toggle-devtools` | `manager.isDevelopment()` only |
+
+## Definition fn arguments
+
+| Arg | Description |
+|---|---|
+| `manager` | The running @omega.js/desktop Manager |
+| `menu` | Per-event builder + id-path API |
+| `params` | Electron's [`ContextMenuParams`](https://www.electronjs.org/docs/latest/api/web-contents#event-context-menu) — `selectionText`, `isEditable`, `linkURL`, `srcURL`, `mediaType`, `editFlags`, `x`, `y`, etc. |
+| `webContents` | The `webContents` that fired the event |
+
+## Auto-attach
+
+Every window created via `manager.windows.createNamed()` is automatically wired up with the context-menu listener. Idempotent per `webContents` (uses a `WeakSet`). For windows you create directly with `new BrowserWindow()`, call:
+
+```js
+manager.contextMenu.attach(win.webContents);
+```
+
+## Runtime API on `manager.contextMenu`
+
+```js
+manager.contextMenu.define(fn)              // replace the definition at runtime
+manager.contextMenu.disable()               // ignore future right-click events (idempotent)
+manager.contextMenu.attach(webContents)     // manual attach
+manager.contextMenu.buildItems(params, wc)  // run the definition without popping a menu (useful for tests)
+manager.contextMenu.hasCustomDefinition()   // false → using the built-in default fn
+```
+
+## Default fn
+
+Without a consumer file, @omega.js/desktop uses a built-in fallback that just calls `useDefaults()` — sensible undo/redo/cut/copy/paste/link/reload/inspect baseline. Same behavior as the default scaffold.
+
+## Default scaffold
+
+The scaffold every verb runs ships `src/integrations/context-menu/index.js` calling `menu.useDefaults()` plus commented-out examples covering insertAfter, remove, hide, enable, and building from scratch.

package/docs/context.md

@@ -0,0 +1,81 @@
+# Context
+
+Runtime info block. Mirrors @omega.js/backend's `assistant.request.{geolocation,client}` shape so @omega.js/desktop apps + sister projects (@omega.js/backend, UJM, @omega.js/client) all reference the same property paths when reading user info.
+
+Populated asynchronously during `manager.initialize()`.
+
+## Shape
+
+```js
+manager.context.geolocation = {
+  ip:      '203.0.113.42',     // async-fetched via ipify
+  country: null,               // future enhancement
+  region:  null,
+  city:    null,
+};
+
+manager.context.client = {
+  userAgent: 'Mozilla/5.0 ...',  // app.userAgentFallback
+  locale:    'en-US',            // app.getLocale()
+  platform:  'darwin',           // os.platform()
+  arch:      'arm64',            // os.arch()
+  mobile:    false,              // always false on @omega.js/desktop (desktop framework)
+};
+
+manager.context.session = {
+  id:        '<uuid>',           // fresh per launch (crypto.randomUUID)
+  startTime: '2026-05-08T...',   // ISO at boot
+  deviceId:  '<uuid or MAC>',    // stable per-machine
+};
+
+manager.context.app = {
+  version:     '1.2.3',          // manager.getVersion()
+  environment: 'production',     // manager.getEnvironment()
+  isPackaged:  true,             // app.isPackaged
+};
+```
+
+## Device ID resolution
+
+The walk itself is the shared one — `@omega.js/analytics`' `deriveDeviceId({ get, set, seed })`, the same call `@omega.js/client` makes on a page ([#396](https://github.com/Omega-JS-Stack/omega/issues/396)). What this module supplies is desktop's own world: electron-store, and the MAC as the seed. Order:
+
+1. **Storage** — already persisted from a prior boot. Wins so we're stable across NIC swaps / VPN changes.
+2. **First non-internal MAC** from `os.networkInterfaces()`, the injected seed. Stable on a stable rig, and it hands a reinstalled app the id it had before its storage was wiped.
+3. **A generated UUID** — the shared derivation's floor. Persisted on first launch.
+
+Once resolved on first launch it never changes. This is the input to `analytics._clientId = uuidv5(deviceId, projectIdNamespace)`, and it is desktop's alone: a browser on the same machine derives its own id from its own localStorage.
+
+## Geolocation
+
+`geolocation.ip` is fetched in the background via `https://api.ipify.org?format=json`. Cached to `storage.context.geolocation` so the next launch has last-known-good values even if offline. The `country/region/city` fields are reserved for a future enrichment provider.
+
+Failure mode: a failed ipify fetch leaves the previous cached value untouched. The app keeps working with last-known-good.
+
+## API
+
+```js
+manager.context.geolocation.ip            // direct read
+manager.context.session.deviceId          // direct read
+const snap = manager.context.toJSON();    // structured-cloneable snapshot
+```
+
+Renderer:
+
+```js
+const snap = await window.desktop.context.get();
+console.log(snap.session.deviceId);
+```
+
+## Why the @omega.js/backend shape
+
+Sister projects (@omega.js/backend, @omega.js/client, UJM) all reference paths like `assistant.request.geolocation.country` and `assistant.request.client.userAgent`. @omega.js/desktop matches the leaf names so consumer code can write logic that works across all four runtimes:
+
+```js
+const country = manager.context.geolocation.country
+             || assistant.request.geolocation.country  // @omega.js/backend
+             || omega.context.geolocation.country;
+```
+
+## Tests
+
+- `src/test/suites/main/context.test.js` — session shape, deviceId stability across re-init, the injected seed + persistence of the shared derivation, client info, IPC handler, JSON-roundtrippability.

package/docs/css.md

@@ -0,0 +1,84 @@
+# CSS Architecture
+
+@omega.js/desktop styles are SCSS, compiled by the pipeline's `sass` task into per-window bundles on top of a shared base. Bootstrap 5 (via @omega.js/desktop's classy theme) is the foundation — consumers restyle Bootstrap, they don't replace it.
+
+## Main entry
+
+`<consumer>/src/assets/scss/main.scss` — loaded by EVERY window. It configures the theme via `@use ... with (...)`:
+
+```scss
+@use 'omega-desktop' as * with (
+  $primary: #2563EB,
+  $dark: #1a1a2e,
+  $classy-bg-dark: #0f0f1a,
+  $classy-bg-dark-secondary: #161628,
+  $classy-bg-dark-tertiary: #1e1e38,
+);
+
+// Custom global styles below
+```
+
+Compiles to `dist/assets/css/main.bundle.css` (Bootstrap + classy theme + your globals).
+
+## Per-window styles
+
+`src/assets/scss/pages/<window>.scss` → `dist/assets/css/components/<window>.bundle.css`, loaded ONLY on that window's page. One file per window (`main.scss`, `settings.scss`, …) — page-specific chrome lives here, shared styles live in the main entry.
+
+## Theme integration
+
+The `@use 'omega-desktop'` entry pulls in Bootstrap 5 + @omega.js/desktop's classy theme. Appearance (`system`/`light`/`dark`) defaults from `config.theme.appearance` and is applied + kept live on `<html data-bs-theme>` by `manager.theme` (OS-following, runtime-switchable, persisted override — see [themes.md](themes.md)). Theme variables (`$primary`, `$dark`, `$classy-bg-*`, typography, borders) are overridable via the `with (...)` block. See [themes.md](themes.md) for the full variable reference.
+
+## Icon presentation
+
+Icon CSS is ONE sheet for every omega target, vendored from @omega.js/web at prepare (package.json `omega.vendorAssets` → `dist/assets/css/core/_fontawesome.scss`) and loaded by the `omega-desktop` entry. It ships the square glyph-centered box every rendered `<i>` gets, the `fa-2xs`…`fa-6xl` size scale, and the `fa-spin` / `fa-bounce` / `fa-beat` utilities (each parked under `prefers-reduced-motion`). Nothing to import and nothing to hand-fix. See [shared/icons.md](shared/icons.md).
+
+## App shell
+
+Dashboard/admin windows use the `.omega-shell` layout — a sidebar + topbar + main grid with a collapsible desktop rail and a mobile drawer. Two layers ship, both vendored from @omega.js/web at prepare: the MECHANICS (`dist/assets/css/shell/_index.scss` — the grid, region geometry, states, and the `--omega-shell-*` tokens, loaded by the `omega-desktop` entry before the theme) and the theme's SKIN (`dist/assets/themes/<theme-id>/css/layout/_shell.scss`, layered over it). Nothing to import — `@use 'omega-desktop'` gets both.
+
+Emit this markup in the window's HTML:
+
+```html
+<div class="omega-shell" data-omega-shell>
+  <aside class="omega-shell__sidebar" id="app-sidebar">
+    <!-- pinned head (brand, selector) sits here, outside the scroll region -->
+    <div class="omega-shell__sidebar-scroll">
+      <!-- nav scrolls HERE (the rail itself clips nothing, so popovers can
+           escape); text that should hide in the collapsed rail wears
+           .omega-shell__label -->
+    </div>
+  </aside>
+
+  <header class="omega-shell__topbar">
+    <div class="omega-shell__topbar-start">
+      <button data-shell-toggle="drawer" aria-expanded="false" aria-controls="app-sidebar">☰</button>
+      <button data-shell-toggle="collapse" aria-expanded="true" aria-controls="app-sidebar">⇤</button>
+    </div>
+    <div class="omega-shell__topbar-end"><!-- account menu, actions --></div>
+  </header>
+
+  <main class="omega-shell__main"><!-- page content --></main>
+
+  <div class="omega-shell__scrim" data-shell-dismiss></div>
+</div>
+```
+
+Wire the behavior from a renderer component (`src/assets/js/components/<window>/index.js`) — `__main_assets__` is the build alias for @omega.js/desktop's vendored core assets:
+
+```js
+import appShell from '__main_assets__/js/core/app-shell.js';
+
+appShell();
+```
+
+The module is delegated and declarative: `[data-shell-toggle="collapse"]` toggles the rail, `[data-shell-toggle="drawer"]` toggles the mobile drawer, `[data-shell-dismiss]` (and Escape) closes it. It stamps the state on the container — `data-shell-collapsed="true"` (persisted under the `shell.collapsed` storage key) and `data-shell-open="true"` — which is what the CSS keys off; the API is also registered at `omega._library.appShell`. Add `.omega-shell--locked` when `main` should never scroll (the page manages its own interior scroll).
+
+## Bootstrap-first convention
+
+NEVER create custom classes for things Bootstrap already provides — use `btn`, `card`, `form-*`, `d-flex`, `gap-*`, `rounded-*`, `bg-body-*`, `text-*` natively, and use `bg-body` variants (not `bg-light`/`bg-dark`) so dark mode adapts. Theme SCSS overrides how Bootstrap components LOOK; custom CSS is only for genuinely novel components with no Bootstrap equivalent. Same rule in BXM and UJM.
+
+## See also
+
+- [themes.md](themes.md) — theme variables, appearance modes
+- [build-system.md](build-system.md) — where the `sass` task runs in the pipeline
+- [templating.md](templating.md) — the page template that loads the bundles

package/docs/deep-link.md

@@ -0,0 +1,178 @@
+# Deep Links
+
+Cross-platform deep-link handling that's simple to use and hard to get wrong. @omega.js/desktop owns all the OS plumbing (single-instance lock, scheme registration, argv parsing, second-instance routing, focus-on-warm-start) and gives you one unified event API regardless of how the link arrived.
+
+## Config
+
+```jsonc
+"deepLinks": {
+  "schemes": ["myapp"]      // urls like myapp://...
+}
+```
+
+@omega.js/desktop registers each scheme with the OS via `app.setAsDefaultProtocolClient` so the system routes matching URLs to your app. Registration is **production-only** — dev/test runs never claim OS-wide protocol handlers for unpackaged Electron binaries. In dev, exercise your handlers with `manager.deepLink.dispatch(url)` instead.
+
+## How it works (so you don't have to think about it)
+
+| Platform | Cold-start (app not running) | Warm-start (app already running) |
+|---|---|---|
+| **macOS** | `app.on('open-url')` — queued before `whenReady`, drained after | `app.on('open-url')` |
+| **Windows** | URL appended to `process.argv`; @omega.js/desktop extracts it | OS forwards argv to the existing instance via `app.on('second-instance')` |
+| **Linux** | Same as Windows | Same as Windows |
+
+@omega.js/desktop handles all of these and dispatches them through the same `manager.deepLink.on()` event registry. Your code looks identical regardless of platform or cold/warm start. Single-instance lock is acquired automatically (via `lib/protocol.js`); duplicate launches exit cleanly and forward their argv to the original instance.
+
+## Public API
+
+```js
+manager.deepLink.on(pattern, handler)    // register a handler. Returns unsubscribe fn.
+manager.deepLink.off(pattern, handler)
+manager.deepLink.dispatch(url)           // manually fire (testing, custom triggers)
+manager.deepLink.getColdStartUrl()       // the URL the app was launched with, or null
+```
+
+## Patterns
+
+```
+'auth/token'             // exact match
+'user/profile/:id'       // named param → ctx.params.id
+'org/:slug/repo/:repo'   // multiple params
+'*'                      // wildcard catch-all (only fires when no concrete handler matched)
+```
+
+## Handler signature
+
+```js
+manager.deepLink.on('user/profile/:id', (ctx) => {
+  ctx.url       // 'myapp://user/profile/42?ref=tray'
+  ctx.scheme    // 'myapp'
+  ctx.route     // 'user/profile/42'
+  ctx.pattern   // 'user/profile/:id'
+  ctx.params    // { id: '42' }
+  ctx.query     // { ref: 'tray' }
+  ctx.source    // 'cold-start' | 'warm-start' | 'manual'
+  ctx.argv      // process.argv (cold) or second-instance argv (warm)
+  ctx.cwd       // working directory
+  ctx.handled   // mutable: set true to suppress remaining handlers (including built-ins)
+});
+```
+
+## Built-in routes
+
+@omega.js/desktop ships with handlers for common patterns. They run AFTER consumer handlers, so you can shadow any of them by registering your own handler at the same pattern.
+
+| Route | Default behavior |
+|---|---|
+| `auth/token` | Calls `manager.omega.handleAuthToken(query.authToken)` — the receiving end of the `manager.openAuthFlow()` sign-in round-trip. MODERN shape only (`?authToken=`, what the website's token page sends); legacy-app formats (`?token=`, `?payload=`) are UJM's concern and are ignored. In production the URL arrives via the OS scheme; in dev/test `lib/auth-flow.js`'s loopback listener dispatches the same URL manually (the scheme isn't OS-registered in dev — protocol.js registers only in production, and macOS can't runtime-register unlisted schemes at all) |
+| `app/show` | `manager.windows.show(query.window || 'main')` |
+| `app/quit` | `app.quit()` |
+
+### Overriding a built-in
+
+```js
+// Replace the built-in app/show with custom logic.
+manager.deepLink.on('app/show', (ctx) => {
+  if (ctx.query.window === 'admin' && !manager.appState.isAdminUser()) {
+    showError('not authorized');
+    ctx.handled = true;       // suppress built-in
+    return;
+  }
+  // Otherwise let the built-in run normally.
+});
+```
+
+## Resolution order
+
+For each incoming URL, @omega.js/desktop walks handlers in this order:
+
+1. **Consumer concrete handlers** (any non-wildcard pattern you registered with `.on()`)
+2. **Built-in concrete handlers** (`auth/token`, `app/show`, `app/quit`)
+3. **Wildcard handlers** (`'*'`) — only if NO concrete handler matched
+
+Setting `ctx.handled = true` in any handler stops the cascade. Within a single tier, handlers fire in registration order. Errors in a handler are caught and logged — they don't stop subsequent handlers.
+
+## Common patterns
+
+### Route to a window + send IPC
+
+```js
+manager.deepLink.on('user/profile/:id', (ctx) => {
+  manager.windows.show('main');
+  manager.windows.get('main').webContents.send('navigate', {
+    to: `/profile/${ctx.params.id}`,
+  });
+});
+```
+
+### Catch-all logger
+
+```js
+manager.deepLink.on('*', (ctx) => {
+  manager.logger.warn(`Unrouted deep link: ${ctx.url}`);
+});
+```
+
+### Cold-start branching
+
+```js
+const coldUrl = manager.deepLink.getColdStartUrl();
+if (coldUrl) {
+  manager.logger.log(`Launched from deep link: ${coldUrl}`);
+  // appState.launchedFromDeepLink() is also set automatically
+}
+```
+
+### Manually dispatching (e.g. from a tray click)
+
+```js
+tray.item({
+  label: 'Open Profile',
+  click: () => manager.deepLink.dispatch('myapp://user/profile/me'),
+});
+```
+
+## Boot queueing
+
+Every dispatch is held until `manager.initialize()` completes (main.js calls `deepLink.markManagerReady()` as its last step). A cold-start `auth/token` link — the OS launching the app from the sign-in round trip — therefore never fires before client-bridge has Firebase up; it queues and drains the moment the manager is ready. Warm-start dispatches on a running app pass straight through.
+
+## Single-instance behavior
+
+@omega.js/desktop acquires the OS-level single-instance lock during `protocol.initialize()` (boot step 5, before deep-link inits). If another copy of the app is already running:
+
+1. The new instance loses the lock.
+2. The OS forwards its argv to the original instance.
+3. The new instance's `Manager.initialize()` returns early (after `protocol.hasSingleInstanceLock() === false`).
+4. The original instance's `app.on('second-instance')` fires with the new argv.
+5. @omega.js/desktop extracts the deep-link URL from that argv and dispatches normally — but as `source: 'warm-start'`.
+6. @omega.js/desktop also focuses the existing main window automatically (consumer can override by registering a route handler that does its own thing).
+
+## Linking with `appState`
+
+When a deep link is detected at cold-start, @omega.js/desktop calls `manager.appState.setLaunchedFromDeepLink(true)`. This means:
+
+```js
+if (manager.appState.launchedFromDeepLink()) {
+  // user clicked a link to launch the app — handle differently than a tray click or login launch
+}
+```
+
+Combine with `appState.isFirstLaunch()` to detect "first launch via deep link" (e.g. from an onboarding flow on your website).
+
+## Testing
+
+The dispatch pipeline is unit-testable without actually triggering an OS event:
+
+```js
+manager.deepLink.dispatch('myapp://auth/token?token=test');
+// Fires source='manual'. Handlers run synchronously.
+```
+
+See `src/test/suites/main/deep-link.test.js` for the full coverage.
+
+## Implementation notes
+
+- `lib/protocol.js` owns the single-instance lock + scheme registration; `lib/deep-link.js` owns the dispatch pipeline. They're separate modules but tightly coupled.
+- OS scheme registration is gated on `manager.isProduction()` (in `lib/protocol.js`) — unpackaged dev/test binaries are never registered as system protocol handlers (unconditional registration also intermittently triggered macOS Launch Services `-600` dialogs during test runs).
+- On Windows/Linux, scheme registration uses `app.setAsDefaultProtocolClient(scheme, process.execPath, [process.cwd()])` so `app.exe scheme://...` style invocations route argv correctly.
+- macOS open-url events that arrive before `whenReady` are queued internally and drained on `deepLink.initialize()`.
+- Argv extraction walks backward from the end of argv (where the URL typically sits) and matches against registered schemes.

package/docs/environment-detection.md

@@ -0,0 +1,104 @@
+# Environment Detection
+
+`getEnvironment()` returns exactly ONE of three mutually-exclusive, exhaustive values:
+
+```javascript
+Manager.getEnvironment()    // 'development' | 'testing' | 'production'
+
+Manager.isDevelopment()     // true ONLY in development
+Manager.isTesting()         // true ONLY in testing
+Manager.isProduction()      // true ONLY in production
+```
+
+**The Manager is the single source of truth.** `getEnvironment()` is the ONLY function that reads the raw signals (`OMEGA_TEST_MODE` / Electron `app.isPackaged` / `config.em.environment` / `OMEGA_BUILD_MODE` / `NODE_ENV`). The three `is*()` checks **derive** from it live on every call — they never read raw signals themselves, so they can never disagree with `getEnvironment()`.
+
+**One implementation, mixed into all four Managers.** @omega.js/desktop has four Manager entry points (main / renderer / preload / build). The helpers are defined once in [src/utils/mode-helpers.js](../src/utils/mode-helpers.js) and mixed into each via `attachTo(Manager)`, available as both prototype methods (`manager.isTesting()`) and statics (`Manager.isTesting()`).
+
+```javascript
+manager.getEnvironment()    // same answer in main / renderer / preload / build
+Manager.isTesting()         // static form, for build-time scripts
+```
+
+**Resolution order:** testing wins first, then production, else development. The three checks are mutually exclusive — exactly one is true. `isDevelopment()` is **false** during testing, and `isProduction()` is a real positive check (it is NOT `!isDevelopment()`).
+
+## Available helpers
+
+| Helper | Returns |
+|---|---|
+| `getEnvironment()` | `'development' \| 'testing' \| 'production'` — the SSOT resolver; the only reader of raw signals. |
+| `isDevelopment()` | `true` ONLY in development (running unpackaged / `electron .` / dev), and NOT testing. Derives from `getEnvironment()`. |
+| `isTesting()` | `true` ONLY in testing (`OMEGA_TEST_MODE === 'true'`). **Takes precedence** — a test run is unpackaged, but it's a test, not development. |
+| `isProduction()` | `true` ONLY in production (packaged & distributed, `app.isPackaged === true`). A **real positive check** — NOT `!isDevelopment()`. |
+
+## Gating side effects — use the INTENTIONAL check
+
+Because there are three environments, never gate a side effect on a two-value assumption. State what you mean:
+
+```javascript
+// Production-only (skip OS side effects / real telemetry in dev AND testing):
+if (isProduction())  { /* do the real thing */ }
+if (!isProduction()) { /* skip / use the safe local behavior */ }
+
+// Local-or-test (anything that should run in BOTH dev and testing):
+if (isDevelopment() || isTesting()) { /* localhost URL, isolate userData, suppress login items */ }
+```
+
+**Avoid** `if (!isDevelopment())` or `if (env !== 'development')` to gate production behavior — those wrongly include `testing` as production and leak real side effects (login items, telemetry, auto-update) during test runs. This is the bug class that motivated the 3-value model. (A genuinely dev-only feature like live-reload is the exception: `env !== 'development'` correctly skips it in both testing and production.)
+
+## URL helpers
+
+```javascript
+Manager.getApiUrl()  // the app's API URL — the SSOT for calling the backend
+```
+
+`getApiUrl()` / `getFunctionsUrl()` / `getWebsiteUrl()` resolve to **local** URLs (`http://localhost:5002` / `http://localhost:5001/<projectId>/us-central1` / `https://localhost:4000`) in development OR testing, and to production (`https://api.<brand.url host>` etc.) otherwise. They route through `this.getEnvironment()`, so they're correct everywhere without an argument — call them directly. Pass an explicit `env` arg (`getApiUrl('production')`) only to force a specific environment regardless of the current one — rarely needed, and mainly used by tests to pin a specific environment's mapping.
+
+`getAuthUrl()` builds the **sign-in URL that round-trips an auth token back to the app**: `<site>/signin?authReturnUrl=<site>/token?authReturnUrl=<brand.id>://auth/token`, where `<site>` is `getWebsiteUrl()` (same env split). The UJM website's `/signin` page logs the user in (or bounces straight through if already signed in), its `/token` page mints a Firebase custom token via the backend, and the final redirect (`?authToken=<token>` — the ONE shape; legacy-app formats live in UJM, not @omega.js/desktop) deep-links the token into the app's built-in `auth/token` route → `omega.handleAuthToken()` → `signInWithCustomToken`. Use it for EVERY "Sign in" affordance an app exposes — never link the bare `/signin` page, which strands the login in the browser. Requires `brand.id` (the deep-link scheme) in config; throws when missing. The optional second arg `getAuthUrl(env, returnUrl)` overrides the chain's final hop — that's how `lib/auth-flow.js` swaps in its dev loopback return.
+
+**Apps should launch the flow through `manager.openAuthFlow()` (main process), not by opening `getAuthUrl()` themselves**: production opens `getAuthUrl()` externally as-is (the OS routes the custom scheme back), while dev/test — where the scheme is NOT OS-registered (protocol.js registers only in production, and macOS can't runtime-register schemes missing from the bundle's Info.plist) — swap the final hop for a one-shot, nonce-checked loopback HTTP listener (RFC 8252 §7.3) that feeds the token into the SAME deep-link pipeline. Sign-in always happens in the user's REAL default browser (their existing session/SSO), never an embedded window. Requires @omega.js/client ≥ 4.3.4 on the website (`isValidRedirectUrl` accepts loopback hosts while the SITE runs in dev). See [src/lib/auth-flow.js](../src/lib/auth-flow.js).
+
+All three local helpers resolve from whichever channel the process has: the `OMEGA_*_PORT` env vars (the CLI that booted the stack publishes them), the `dev` map the bundle baked into `OMEGA_BUILD_JSON` (a packaged main process has no parent env, so a bumped emulator port reaches it only this way, [#745](https://github.com/Omega-JS-Stack/omega/issues/745)), and the classic default. `getApiUrl()` and `getFunctionsUrl()` read them in exactly that order; `getWebsiteUrl()` takes its baked cell first, for the reason under the table:
+
+| Helper | Env channel | Baked channel | Classic |
+|---|---|---|---|
+| `getApiUrl()` | `OMEGA_HTTPS_PORT`, else `OMEGA_HOSTING_PORT` | `dev.ports.https`, else `dev.ports.hosting` | 5002 |
+| `getFunctionsUrl()` | `OMEGA_FUNCTIONS_PORT` | `dev.ports.functions` | 5001 |
+| `getWebsiteUrl()` | `OMEGA_WEBSITE_PORT`, composed as `https://localhost:<port>` | `dev.origin` (the whole origin) first, else `dev.ports.website` | `https://localhost:4000` |
+
+The first two rows are port chains: each cell names a port, and the helper builds the URL around it. The website row is an ORIGIN chain ([#747](https://github.com/Omega-JS-Stack/omega/issues/747)): the baked `dev.origin` the live website published carries scheme, host AND port, so it is the complete fact and outranks both port cells; only when it is absent does a port compose an origin, over **https**, because `omega dev` fronts its public port with the mkcert proxy by default and a port number alone can never say the scheme. Whenever the website published an origin, that is the same answer `@omega.js/client`'s `getDevWebsiteOrigin()` gives every other surface ([#262](https://github.com/Omega-JS-Stack/omega/issues/262)), and `getAuthUrl()` inherits it by construction.
+
+A resolved `OMEGA_HTTPS_PORT` (or a baked `dev.ports.https`) means `omega serve`'s mkcert proxy is up, so the api URL is https. That is the same three-step chain @omega.js/extension's `getApiUrl()` walks, and the same one client-bridge uses for the auth emulator port (`OMEGA_AUTH_PORT` → `dev.ports.auth` → 9099, [client-bridge.md](client-bridge.md)).
+
+Resolving local in test mode is required because tests hit the local emulator — without it, the app (and tests calling `getApiUrl()`) would leak to the live production server.
+
+> The URL helpers live in [src/utils/url-helpers.js](../src/utils/url-helpers.js) and depend on `this.getEnvironment()` (from mode-helpers.js) being mixed in — both `attachTo` calls run at the bottom of every Manager entry point.
+
+## Where they live
+
+Source: [src/utils/mode-helpers.js](../src/utils/mode-helpers.js) for `getEnvironment()` + `is*()` + `getVersion()`; [src/utils/url-helpers.js](../src/utils/url-helpers.js) for the URL builders. Each module exposes the functions plus an `attachTo(Manager)` mixin. Attached at the bottom of all four Manager files: [main.js](../src/main.js), [renderer.js](../src/renderer.js), [preload.js](../src/preload.js), [build.js](../src/build.js) — mode-helpers first (so `getEnvironment` exists), then url-helpers.
+
+## How detection works
+
+`getEnvironment()` resolves in this precedence order:
+
+1. **Testing** — `process.env.OMEGA_TEST_MODE === 'true'` (set by @omega.js/desktop's test runners). A test run is a test run regardless of packaged state.
+2. **Config override** — `config.em.environment` (`'development'` / `'testing'` / `'production'`), the consumer's explicit choice. It beats the auto-detected `app.isPackaged` below.
+3. **Production / Development (runtime)** — Electron `app.isPackaged`: packaged → production, unpackaged → development. This is the authoritative runtime signal in the main process. In renderer / preload / plain Node, `app` is unavailable, so it falls through.
+4. **Build-time signals** — `OMEGA_BUILD_MODE === 'true'` → production; `NODE_ENV === 'development'` → development.
+5. **Default** — production. @omega.js/desktop's deployed *runtime* can reach here without a dev signal (a packaged binary whose `app.isPackaged` didn't resolve is still a shipped app), so production is the safe assumption. (Contrast UJM/BXM, whose deployed artifacts always carry their signal baked in, so they default to **development** — a bare context there is just build tooling. @omega.js/backend defaults to production for the same reason as @omega.js/desktop.)
+
+## Adding a new helper
+
+Write the function in a `src/utils/<topic>-helpers.js` module, expose `attachTo(Manager)`, then call `attachTo` at the bottom of all four Manager files. Don't define helpers on individual Manager prototypes — that path leads to duplicated semantics (the old `getEnvironment` collision between main.js and build.js). For anything environment-derived, derive from `getEnvironment()` rather than reading `process.env` / `app.*` directly, so there is one source of truth and no chance of drift.
+
+## Why this matters
+
+**One signal, used everywhere.** The test runner sets `OMEGA_TEST_MODE=true`; every piece of code that calls `isTesting()` (framework or consumer) then sees `true` — no need to invent a per-module env var.
+
+**Sub-modules check the same signal.** When framework code (an auto-update poll, a restart-manager registration) needs to skip side effects in tests, it checks `isTesting()` — the same answer the consumer's own code gets. No drift.
+
+**`is*()` can never disagree with `getEnvironment()`.** Because the checks derive from the single resolver instead of reading raw signals (`app.isPackaged` vs `OMEGA_BUILD_MODE`), there is exactly one definition of "what environment is this," and a wrong-but-confident gate is structurally impossible.
+
+## See also
+
+- [test-framework.md](test-framework.md) — `OMEGA_TEST_MODE` is set automatically by the test runners; extended mode (`--extended` / `TEST_EXTENDED_MODE`) gates real external APIs.