@omega.js/desktop 0.52.0 → 0.53.0

package/docs/context.md

@@ -2,19 +2,19 @@
 
 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()`.
+Populated asynchronously during `omega.initialize()`.
 
 ## Shape
 
 ```js
-manager.context.geolocation = {
+omega.context.geolocation = {
   ip:      '203.0.113.42',     // async-fetched via ipify
   country: null,               // future enhancement
   region:  null,
   city:    null,
 };
 
-manager.context.client = {
+omega.context.client = {
   userAgent: 'Mozilla/5.0 ...',  // app.userAgentFallback
   locale:    'en-US',            // app.getLocale()
   platform:  'darwin',           // os.platform()
@@ -22,15 +22,15 @@ manager.context.client = {
   mobile:    false,              // always false on @omega.js/desktop (desktop framework)
 };
 
-manager.context.session = {
+omega.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()
+omega.context.app = {
+  version:     '1.2.3',          // omega.getVersion()
+  environment: 'production',     // omega.getEnvironment()
   isPackaged:  true,             // app.isPackaged
 };
 ```
@@ -54,9 +54,9 @@ Failure mode: a failed ipify fetch leaves the previous cached value untouched. T
 ## API
 
 ```js
-manager.context.geolocation.ip            // direct read
-manager.context.session.deviceId          // direct read
-const snap = manager.context.toJSON();    // structured-cloneable snapshot
+omega.context.geolocation.ip            // direct read
+omega.context.session.deviceId          // direct read
+const snap = omega.context.toJSON();    // structured-cloneable snapshot
 ```
 
 Renderer:
@@ -71,7 +71,7 @@ console.log(snap.session.deviceId);
 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
+const country = omega.context.geolocation.country
              || assistant.request.geolocation.country  // @omega.js/backend
              || omega.context.geolocation.country;
 ```

package/docs/css.md

@@ -32,7 +32,7 @@ Compiles to `dist/assets/css/main.bundle.css` (Bootstrap + classy theme + your g
 
 ## 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, and `$primary` arrives from `brand.color` through the generated `dist/assets/scss/_brand.scss` unless a literal replaces `brand.$primary` ([#912](https://github.com/Omega-JS-Stack/omega/issues/912)). See [themes.md](themes.md) for the full variable reference.
+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 `omega.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, and `$primary` arrives from `brand.color` through the generated `dist/assets/scss/_brand.scss` unless a literal replaces `brand.$primary` ([#912](https://github.com/Omega-JS-Stack/omega/issues/912)). See [themes.md](themes.md) for the full variable reference.
 
 ## Icon presentation
 
@@ -69,15 +69,9 @@ Emit this markup in the window's HTML:
 </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:
+The renderer instance wires the behavior during `omega.initialize()` (the vendored `__main_assets__/js/core/app-shell.js`, the same module @omega.js/web runs), so a view that renders the markup needs no script of its own. The API is `omega.shell` (`isCollapsed`, `isOpen`, `setCollapsed`, `setOpen`, `toggleCollapsed`, `toggleOpen`).
 
-```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).
+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. Add `.omega-shell--locked` when `main` should never scroll (the page manages its own interior scroll).
 
 ## Bootstrap-first convention
 

package/docs/deep-link.md

@@ -10,7 +10,7 @@ Cross-platform deep-link handling that's simple to use and hard to get wrong. @o
 }
 ```
 
-@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.
+@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 `omega.deepLink.dispatch(url)` instead.
 
 ## How it works (so you don't have to think about it)
 
@@ -20,15 +20,15 @@ Cross-platform deep-link handling that's simple to use and hard to get wrong. @o
 | **Windows** | URL appended to `process.argv`; @omega.js/desktop extracts it | OS forwards argv to the existing instance via `app.on('second-instance')`; @omega.js/desktop reads the duplicate's real argv from that event's `additionalData` |
 | **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.
+@omega.js/desktop handles all of these and dispatches them through the same `omega.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
+omega.deepLink.on(pattern, handler)    // register a handler. Returns unsubscribe fn.
+omega.deepLink.off(pattern, handler)
+omega.deepLink.dispatch(url)           // manually fire (testing, custom triggers)
+omega.deepLink.getColdStartUrl()       // the URL the app was launched with, or null
 ```
 
 ## Patterns
@@ -43,7 +43,7 @@ manager.deepLink.getColdStartUrl()       // the URL the app was launched with, o
 ## Handler signature
 
 ```js
-manager.deepLink.on('user/profile/:id', (ctx) => {
+omega.deepLink.on('user/profile/:id', (ctx) => {
   ctx.url       // 'myapp://user/profile/42?ref=tray'
   ctx.scheme    // 'myapp'
   ctx.route     // 'user/profile/42'
@@ -63,16 +63,16 @@ manager.deepLink.on('user/profile/:id', (ctx) => {
 
 | 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')` |
+| `auth/token` | Calls `omega.auth.handleToken(query.authToken)`: the receiving end of the `omega.openAuthFlow()` sign-in round-trip. MODERN shape only (`?authToken=`, what the website's token page sends); other formats (`?token=`, `?payload=`) 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` | `omega.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()) {
+omega.deepLink.on('app/show', (ctx) => {
+  if (ctx.query.window === 'admin' && !omega.appState.isAdminUser()) {
     showError('not authorized');
     ctx.handled = true;       // suppress built-in
     return;
@@ -96,9 +96,9 @@ Setting `ctx.handled = true` in any handler stops the cascade. Within a single t
 ### 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', {
+omega.deepLink.on('user/profile/:id', (ctx) => {
+  omega.windows.show('main');
+  omega.windows.get('main').webContents.send('navigate', {
     to: `/profile/${ctx.params.id}`,
   });
 });
@@ -107,17 +107,17 @@ manager.deepLink.on('user/profile/:id', (ctx) => {
 ### Catch-all logger
 
 ```js
-manager.deepLink.on('*', (ctx) => {
-  manager.logger.warn(`Unrouted deep link: ${ctx.url}`);
+omega.deepLink.on('*', (ctx) => {
+  omega.logger.warn(`Unrouted deep link: ${ctx.url}`);
 });
 ```
 
 ### Cold-start branching
 
 ```js
-const coldUrl = manager.deepLink.getColdStartUrl();
+const coldUrl = omega.deepLink.getColdStartUrl();
 if (coldUrl) {
-  manager.logger.log(`Launched from deep link: ${coldUrl}`);
+  omega.logger.log(`Launched from deep link: ${coldUrl}`);
   // appState.launchedFromDeepLink() is also set automatically
 }
 ```
@@ -127,13 +127,13 @@ if (coldUrl) {
 ```js
 tray.item({
   label: 'Open Profile',
-  click: () => manager.deepLink.dispatch('myapp://user/profile/me'),
+  click: () => omega.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.
+Every dispatch is held until `omega.initialize()` completes (main.js calls `deepLink.markOmegaReady()` 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 `omega.auth` has Firebase up; it queues and drains the moment the instance is ready. Warm-start dispatches on a running app pass straight through.
 
 ## Single-instance behavior
 
@@ -141,7 +141,7 @@ Every dispatch is held until `manager.initialize()` completes (main.js calls `de
 
 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`).
+3. The new instance's `omega.initialize()` halts (after `protocol.hasSingleInstanceLock() === false`): the duplicate quits and its promise never settles.
 4. The original instance's `app.on('second-instance')` fires with the Chromium-processed argv as its second argument AND the duplicate's real argv as its fourth, `additionalData` (@omega.js/desktop passes `{ argv, cwd }` to `app.requestSingleInstanceLock()` for you).
 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).
@@ -156,10 +156,10 @@ Never parse the event's own `argv` for flags: Chromium re-serializes it (switche
 
 ## Linking with `appState`
 
-When a deep link is detected at cold-start, @omega.js/desktop calls `manager.appState.setLaunchedFromDeepLink(true)`. This means:
+When a deep link is detected at cold-start, @omega.js/desktop calls `omega.appState.setLaunchedFromDeepLink(true)`. This means:
 
 ```js
-if (manager.appState.launchedFromDeepLink()) {
+if (omega.appState.launchedFromDeepLink()) {
   // user clicked a link to launch the app — handle differently than a tray click or login launch
 }
 ```
@@ -171,7 +171,7 @@ Combine with `appState.isFirstLaunch()` to detect "first launch via deep link" (
 The dispatch pipeline is unit-testable without actually triggering an OS event:
 
 ```js
-manager.deepLink.dispatch('myapp://auth/token?token=test');
+omega.deepLink.dispatch('myapp://auth/token?token=test');
 // Fires source='manual'. Handlers run synchronously.
 ```
 
@@ -180,7 +180,7 @@ 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).
+- OS scheme registration is gated on `omega.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

@@ -3,25 +3,25 @@
 `getEnvironment()` returns exactly ONE of three mutually-exclusive, exhaustive values:
 
 ```javascript
-Manager.getEnvironment()    // 'development' | 'testing' | 'production'
+omega.getEnvironment()    // 'development' | 'testing' | 'production'
 
-Manager.isDevelopment()     // true ONLY in development
-Manager.isTesting()         // true ONLY in testing
-Manager.isProduction()      // true ONLY in production
+omega.isDevelopment()     // true ONLY in development
+omega.isTesting()         // true ONLY in testing
+omega.isProduction()      // true ONLY in production
 ```
 
 **ONE input, and no default** ([#817](https://github.com/Omega-JS-Stack/omega/issues/817)). `getEnvironment()` reads the `OMEGA_ENVIRONMENT` variable in Node, and the baked `OMEGA_BUILD_JSON.config.environment` in a renderer (which has no `process.env`). Nothing else is consulted: the `app.isPackaged`, `config.em.environment`, `OMEGA_BUILD_MODE` and `NODE_ENV` sniffs are gone, and a context with neither input **throws**, naming the variable. The old default here was `production`, so a plain `npm start` bundled itself as a production artifact while @omega.js/extension's copy of the same function answered `development` from the same inputs.
 
-**One implementation, shared with every sibling framework.** The four calls are `@omega.js/config`'s [environment.js](../../config/src/environment.js), the module @omega.js/extension, @omega.js/web, @omega.js/backend and @omega.js/client all answer from. @omega.js/desktop has four Manager entry points (main / renderer / preload / build); [src/utils/mode-helpers.js](../src/utils/mode-helpers.js) re-exports the shared four beside desktop's own `getVersion()` and mixes them into each via `attachTo(Manager)`, available as both prototype methods (`manager.isTesting()`) and statics (`Manager.isTesting()`).
+**One implementation, shared with every sibling framework.** The four calls are `@omega.js/config`'s [environment.js](../../config/src/environment.js), the module @omega.js/extension, @omega.js/web, @omega.js/backend and @omega.js/client all answer from. @omega.js/desktop has four entry points (main / renderer / preload / build); [src/utils/mode-helpers.js](../src/utils/mode-helpers.js) re-exports the shared four beside desktop's own `getVersion()`. The build module exports them as plain functions, and every process's `omega` carries them as methods.
 
 ```javascript
-manager.getEnvironment()    // same answer in main / renderer / preload / build
-Manager.isTesting()         // static form, for build-time scripts
+omega.getEnvironment()                                // same answer in main / renderer / preload
+require('@omega.js/desktop/build').isTesting()        // the build module, for build-time scripts
 ```
 
 **Who sets the input.** [src/build.js](../src/build.js) names it at LOAD, from the lane: `OMEGA_BUILD_MODE` (which `omega build` / `package` / `publish` / `release` and the boot runner's staged build all set) is `production` and WINS over an inherited value, so a production build spawned from a test run still bakes production; otherwise a lane that already named one keeps it (the test runners spawn their children naming `testing`), and a bare dev boot is `development`. The electron app that lane spawns inherits the variable. A PACKAGED app has no parent lane, so [src/main.js](../src/main.js) names it from the word the build baked into the artifact: that is a FALLBACK for the context with no input, never an override ([#925](https://github.com/Omega-JS-Stack/omega/issues/925)). A process that already carries `OMEGA_ENVIRONMENT` keeps it, which is why a test lane that boots a production artifact still answers `testing` inside it.
 
-**The renderer gets the running word too.** A page has no `process`, so its Manager reads input 2, the baked `config.environment`, which is the word the BUILD was for. Those agree everywhere except a lane that boots a production artifact, so the preload (a Node context, it has the variable) exposes it on `window.desktop.environment` and [src/renderer.js](../src/renderer.js) applies it over the baked word at `initialize()`. Same precedence, one context removed: the running environment first, the bake second. No second signal exists.
+**The renderer gets the running word too.** A page has no `process`, so its `omega` reads input 2, the baked `config.environment`, which is the word the BUILD was for. Those agree everywhere except a lane that boots a production artifact, so the preload (a Node context, it has the variable) exposes it on `window.desktop.environment` and [src/renderer.js](../src/renderer.js) applies it over the baked word at `initialize()`. Same precedence, one context removed: the running environment first, the bake second. No second signal exists.
 
 **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()`).
 
@@ -52,14 +52,14 @@ if (isDevelopment() || isTesting()) { /* localhost URL, isolate userData, suppre
 ## URL helpers
 
 ```javascript
-Manager.getApiUrl()  // the app's API URL — the SSOT for calling the backend
+omega.getApiUrl()  // the app's API URL: the SSOT for calling the backend
 ```
 
 `getApiUrl()` / `getFunctionsUrl()` / `getWebsiteUrl()` resolve to **local** URLs (from the baked dev map, whose floor is the classic hosting / functions / website numbers) 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.
+`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 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) deep-links the token into the app's built-in `auth/token` route → `omega.auth.handleToken()` → `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).
+**Apps should launch the flow through `omega.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), then 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)). There is no third step: the classic numbers used to be hand-typed under them, and they are gone ([#834](https://github.com/Omega-JS-Stack/omega/issues/834)).
 
@@ -73,15 +73,15 @@ The classics still reach these helpers, from the ONE place they are defined: the
 
 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 the port cell; 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 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` → throw, [client-bridge.md](client-bridge.md)).
+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 chain @omega.js/extension's `getApiUrl()` walks, and the same one `omega.auth` uses for the auth emulator port (`OMEGA_AUTH_PORT` → `dev.ports.auth` → throw, [auth.md](auth.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.
+> The URL helpers live in [src/utils/url-helpers.js](../src/utils/url-helpers.js) as plain functions of the instance (`getApiUrl(omega, environment)`), reading its `getEnvironment()`; each process class calls them from its own methods.
 
 ## 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.
+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. Both modules export plain functions. [build.js](../src/build.js) exports the mode helpers as they are; the three process classes, [main.js](../src/main.js) (the methods mixed in from [lib/_environment-mixin.js](../src/lib/_environment-mixin.js)), [preload.js](../src/preload.js) and [renderer.js](../src/renderer.js), call them from their own methods (the renderer takes the environment four and `getApiUrl()` / `getFunctionsUrl()` from @omega.js/client's base class it extends).
 
 ## How detection works
 
@@ -89,7 +89,7 @@ Source: [src/utils/mode-helpers.js](../src/utils/mode-helpers.js) for `getEnviro
 ([#817](https://github.com/Omega-JS-Stack/omega/issues/817)):
 
 1. **`process.env.OMEGA_ENVIRONMENT`**, wherever this context has a `process` (main, preload, build-time Node).
-2. **The baked `config.environment`** off the Manager the call is made on, for a renderer, which has none. It is the build fact every OMEGA surface spells the same way ([#896](https://github.com/Omega-JS-Stack/omega/issues/896)). The preload hands the running word across to the renderer when the two differ, so this step answers the artifact's own build only when no lane named one ([#925](https://github.com/Omega-JS-Stack/omega/issues/925)).
+2. **The baked `config.environment`** off the `omega` the call is made on, for a renderer, which has none. It is the build fact every OMEGA surface spells the same way ([#896](https://github.com/Omega-JS-Stack/omega/issues/896)). The preload hands the running word across to the renderer when the two differ, so this step answers the artifact's own build only when no lane named one ([#925](https://github.com/Omega-JS-Stack/omega/issues/925)).
 3. **Neither** is a loud error naming `OMEGA_ENVIRONMENT`. There is no default, because the four framework copies this replaced each had one and they disagreed.
 
 The lanes above supply that input, and the whole table of who names what lives in
@@ -97,7 +97,7 @@ The lanes above supply that input, and the whole table of who names what lives i
 
 ## 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.
+Write the function in a `src/utils/<topic>-helpers.js` module, export it from [build.js](../src/build.js), and call it from a method on each process class that needs it. Don't define a helper's logic inside one process class: that path leads to duplicated semantics. 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
 

package/docs/fontawesome.md

@@ -35,7 +35,7 @@ drift on how an icon name resolves or what the served SVG looks like.
   `metadata/icon-families.json` for aliases (`search` → `magnifying-glass`).
   Declared dependencies ride into packaged apps automatically (fs reads
   through the asar transparently).
-- **Main lib** (`lib/fontawesome.js`) — `manager.fontawesome.get(name, style)`
+- **Main lib** (`lib/fontawesome.js`): `omega.fontawesome.get(name, style)`
   resolves an icon to its SVG string (`null` for unknown names — never
   throws). Lookups are slug-sanitized via icon-core (the IPC channel can
   never read outside the icon directories) and cached per app run. Serves
@@ -61,11 +61,13 @@ drift on how an icon name resolves or what the served SVG looks like.
 ## Minimal surfaces
 
 The auto-render is wired by `initialize()`. A renderer that deliberately skips
-the full init (no @omega.js/client / auth — e.g. a lightweight popover overlay) can
-enable JUST the icon pipeline:
+`initialize()` (e.g. a lightweight popover overlay with no auth) can enable JUST
+the icon pipeline on the same instance:
 
 ```js
-new (require('@omega.js/desktop/renderer'))().enableFontAwesome();
+import omega from '@omega.js/desktop/renderer';
+
+omega.enableFontAwesome();
 ```
 
 ## Supplying Font Awesome Pro (C4 cp111)
@@ -88,7 +90,7 @@ own **prod dependency** so the set ships inside the asar.
   `window.desktop.fontawesome.get()` and swap yourself.
 - **Free set = solid + regular + brands.** Pro styles (light/duotone/sharp)
   need a supplied Pro set (above); otherwise
-  `manager.fontawesome.get(name, 'duotone')` returns `null`.
+  `omega.fontawesome.get(name, 'duotone')` returns `null`.
 - **Updating the set** — bump the `@fortawesome/fontawesome-free` dependency
   (or reinstall/refresh the brand's Pro supply).
 

package/docs/hooks.md

@@ -6,7 +6,7 @@ Consumers can inject custom logic at well-defined points without forking @omega.
 
 1. @omega.js/desktop scaffolds empty hook files into `<consumer>/hooks/**/*.js` on every verb (`ensureTarget()`).
 2. At each lifecycle point, @omega.js/desktop checks for the file. If it exists, @omega.js/desktop loads + invokes it. If not, no-op.
-3. The hook signature is `async (ctx) => { ... }`. Whatever it returns is awaited but ignored.
+3. The hook signature is `async (ctx) => { ... }`, with `ctx` the ONE hook-argument shape every OMEGA framework passes, `{ build, projectRoot, mode }`: `build` is the build module (`require('@omega.js/desktop/build')`, one plain object of functions: `getConfig()`, `getPackage()`, `getRootPath()`, ...). Whatever it returns is awaited but ignored.
 4. **Failure semantics:**
    - File missing entirely → logged informationally (`hook "<name>" not present at ... — skipping.`), build continues.
    - File exists but fails to load (syntax error, etc.) → **throws**, build fails.
@@ -19,11 +19,11 @@ Consumers can inject custom logic at well-defined points without forking @omega.
 
 | Hook file | When it runs | `ctx` shape |
 |---|---|---|
-| `hooks/build/pre.js`     | Before the build pipeline runs (`defaults` → `distribute` → `bundle` ...) | `{ manager, projectRoot, mode }` |
-| `hooks/build/post.js`    | After the build pipeline finishes, before `electron-builder` packages anything | `{ manager, projectRoot, mode }` |
-| `hooks/release/pre.js`   | Before `electron-builder build --publish always` | `{ manager, projectRoot, mode }` |
-| `hooks/release/post.js`  | After the release publishes | `{ manager, projectRoot, mode }` |
-| `hooks/deploy/pre.js`    | Inside `omega deploy`, after the local scaffold and before the network precheck, on both lanes (the dispatch and `--direct`); a dry run skips it, because a hook may act on the world ([#900](https://github.com/Omega-JS-Stack/omega/issues/900): the playground's prunes its release family down to the newest, so two releases stay live; the VERSION comes from `omega bump` at the brand root, [#869](https://github.com/Omega-JS-Stack/omega/issues/869), never from a hook) | `{ manager, projectRoot, mode: 'production' }` |
+| `hooks/build/pre.js`     | Before the build pipeline runs (`defaults` → `distribute` → `bundle` ...) | `{ build, projectRoot, mode }` |
+| `hooks/build/post.js`    | After the build pipeline finishes, before `electron-builder` packages anything | `{ build, projectRoot, mode }` |
+| `hooks/release/pre.js`   | Before `electron-builder build --publish always` | `{ build, projectRoot, mode }` |
+| `hooks/release/post.js`  | After the release publishes | `{ build, projectRoot, mode }` |
+| `hooks/deploy/pre.js`    | Inside `omega deploy`, after the local scaffold and before the network precheck, on both lanes (the dispatch and `--direct`); a dry run skips it, because a hook may act on the world ([#900](https://github.com/Omega-JS-Stack/omega/issues/900): the playground's prunes its release family down to the newest, so two releases stay live; the VERSION comes from `omega bump` at the brand root, [#869](https://github.com/Omega-JS-Stack/omega/issues/869), never from a hook) | `{ build, projectRoot, mode: 'production' }` |
 | `hooks/notarize/post.js` | After @omega.js/desktop's built-in macOS notarization completes (extension only — @omega.js/desktop's notarize is the real entrypoint) | electron-builder afterSign context |
 
 `mode` is `'production'` when `OMEGA_BUILD_MODE=true`, else `'development'`. A deploy hook always reads `'production'`: the verb runs outside a build, and what it is about to publish is a release.
@@ -32,7 +32,7 @@ Consumers can inject custom logic at well-defined points without forking @omega.
 
 - **Notarize specifically:** the consumer's `hooks/notarize/post.js` is **never** the electron-builder afterSign entrypoint. @omega.js/desktop's `gulp/build-config` injects `afterSign:` pointing at @omega.js/desktop's real notarize implementation (resolved via `require.resolve('@omega.js/desktop/hooks/notarize')`). @omega.js/desktop's real notarize calls into the consumer's `hooks/notarize/post.js` as a final post-step. So the consumer can never accidentally break notarization by editing the file — the file can be empty, malformed, or missing entirely and the app still notarizes correctly.
 - **Why no `hooks/notarize/pre.js`?** electron-builder's `afterSign` hook is the only signing-related extension point we control. Anything that would belong in a "pre-notarize" step belongs either in `hooks/release/pre.js` (whole-release-level prep, runs before the gulp release task), or in electron-builder's own `afterPack` / `afterAllArtifactBuild` configuration (per-artifact mutation). If you have a real use case that doesn't fit either, file an issue.
-- **Build/release hooks:** standard before/after lifecycle pattern. Same shape as Ultimate Jekyll Manager's hook system.
+- **Build/release hooks:** standard before/after lifecycle pattern, the same `ctx` @omega.js/extension hands its hooks.
 
 ## Examples
 
@@ -40,7 +40,7 @@ Consumers can inject custom logic at well-defined points without forking @omega.
 
 ```js
 // hooks/release/post.js
-module.exports = async ({ manager, projectRoot }) => {
+module.exports = async ({ build, projectRoot }) => {
   const pkg = require(`${projectRoot}/package.json`);
   const url = process.env.SLACK_WEBHOOK_URL;
   if (!url) return;