@omega.js/desktop 0.52.0 → 0.53.0

package/docs/{client-bridge.md → auth.md}

@@ -1,6 +1,6 @@
-# Client Bridge — Auth State Sync
+# Auth: `omega.auth` and the state sync
 
-@omega.js/desktop keeps Firebase auth state in sync across all processes (main + every renderer window). The pattern mirrors BXM's background/foreground architecture: **main is the source of truth**, renderers reflect.
+@omega.js/desktop keeps Firebase auth state in sync across all processes (main + every renderer window). **Main is the source of truth**, renderers reflect: the same pattern as @omega.js/extension's background and page contexts. In main the lib is `omega.auth` ([src/lib/auth.js](../src/lib/auth.js)); in a renderer `omega.auth` is @omega.js/client's Auth module. Both sides hold the account as one `User` (`@omega.js/account`), never null.
 
 ## Why this exists
 
@@ -16,7 +16,7 @@ The bridge handles all three.
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│  MAIN (client-bridge.js)                               │
+│  MAIN (lib/auth.js, omega.auth)                         │
 │  - Owns Firebase Auth instance ("omega-auth" app)              │
 │  - Source of truth for auth state                           │
 │  - Listens for desktop:auth:* IPC from renderers                 │
@@ -32,13 +32,13 @@ The bridge handles all three.
 
 ### Auth flow: deep-link → all processes signed in
 
-**Consumers never collect credentials.** There is no login form to build — call `manager.openAuthFlow()` (documented in `lib/auth-flow.js`), which opens the brand website's sign-in page in the user's browser and receives the result through the deep link below.
+**Consumers never collect credentials.** There is no login form to build: call `omega.openAuthFlow()` (documented in `lib/auth-flow.js`), which opens the brand website's sign-in page in the user's browser and receives the result through the deep link below.
 
-1. User signs in on the website. Web-manager generates a custom token. Website opens `myapp://auth/token?token=XYZ` (deep link).
-2. @omega.js/desktop's deep-link `auth/token` built-in fires `manager.omega.handleAuthToken(token)`.
+1. User signs in on the website. The website's token page mints a custom token and opens `myapp://auth/token?authToken=XYZ` (deep link).
+2. @omega.js/desktop's deep-link `auth/token` built-in calls `omega.auth.handleToken(token)`.
 3. Main calls `signInWithCustomToken(auth, token)` against its own Firebase Auth → main is now signed in.
 4. Main broadcasts `desktop:auth:sign-in-with-token` IPC with the same token to all renderer windows.
-5. Each renderer receives the broadcast, calls `omega.auth().signInWithCustomToken(token)` against its own (@omega.js/client-managed) Firebase Auth → all renderers signed in with the same user.
+5. Each renderer receives the broadcast, calls `omega.auth.signInWithCustomToken(token)` against its own (@omega.js/client-managed) Firebase Auth → all renderers signed in with the same user.
 6. Tokens are NOT stored — they expire in 1 hour. Auth state persists via Firebase's built-in IndexedDB persistence.
 
 ### Auth flow: renderer load → sync with main
@@ -53,68 +53,79 @@ When a renderer window opens (cold or warm), it asks main for the current state:
 
 ### Sign-out flow
 
-Any renderer (or main code) calls `manager.omega.signOut()`:
+Main code calls `omega.auth.signOut()`; a renderer calls `omega.signOut()`, which a click on any `.omega-signout` element runs (@omega.js/client's trigger: confirm, then `desktop:auth:sign-out` to main). Either way:
 
 1. Main signs out its own Firebase.
 2. Main broadcasts `desktop:auth:sign-out` IPC to all renderers.
-3. Each renderer signs out its own Firebase.
+3. Each renderer signs out its own Firebase, on that broadcast alone (the clicked window included), so nothing signs out twice.
 
 ## Public API
 
-### Main process (`manager.omega`)
+### Main process (`omega.auth`)
 
 ```js
-// Sign in via a custom token (called automatically by the auth/token deep-link route).
-await manager.omega.handleAuthToken(token);
+// The account, always a `User`: signed out until a renderer pushes the account
+// document of the uid main's session holds, and signed out again the moment that
+// session ends.
+omega.auth.user;
+//   → User: .authenticated .uid .email .plan .active .trialing .cancelling .everPaid,
+//     .roles, .subscription, ..., .profile { displayName, photoURL, emailVerified }
+
+// Subscribe to state changes (e.g. to refresh tray/menu items). Called with
+// `{ user }`, plus a catch-up with the current state after listen() returns.
+const off = omega.auth.listen(({ user }) => {
+  omega.tray.refresh();
+  omega.menu.refresh();
+});
+off();   // unsubscribe
 
-// Read the currently signed-in user (snapshot, no sensitive fields).
-manager.omega.getCurrentUser();
-//   → { uid, email, displayName, photoURL, emailVerified } | null
+// Sign in via a custom token (called automatically by the auth/token deep-link route).
+await omega.auth.handleToken(token);
 
 // Fresh Firebase ID token for calling authenticated backend routes from main
 // (send as `Authorization: Bearer <token>`). null when signed out.
-await manager.omega.getIdToken();
+await omega.auth.getIdToken();
 
-// Subscribe to auth state changes (e.g. to refresh tray/menu items).
-const off = manager.omega.onAuthChange((user) => {
-  manager.tray.refresh();
-  manager.menu.refresh();
-});
-off();   // unsubscribe
+// Or let the instance fetch: @omega.js/client's request, built once on main,
+// attaches that token itself (the renderer's and the extension's shape).
+await omega.request('/notes', { method: 'POST', body: { text: 'hi' } });
 
-// Sign out from any process.
-await manager.omega.signOut();
-
-// The renderer-resolved subscription — THE main-side plan source. Renderers run
-// @omega.js/client's full auth cycle (Firestore account fetch → resolveSubscription)
-// and push the result to main (desktop:auth:account-resolved, uid-guarded); main can't
-// run Firestore itself. null until a renderer has resolved.
-manager.omega.getResolvedPlan();
-//   → { plan, active, trialing, cancelling } | null
-manager.omega.getResolvedRoles();
-//   → { admin, betaTester, ... } | null
+// Sign main out and broadcast the sign-out to every renderer.
+await omega.auth.signOut();
 ```
 
-### Renderer process (the @omega.js/desktop Manager you `initialize()`)
+Main can't run Firestore, so the account crosses from the renderers: each renderer runs @omega.js/client's full auth cycle and pushes the WHOLE stored document (`desktop:auth:account-resolved`, `{ uid, document, identity }`, uid-guarded), and main builds its `omega.auth.user` from it. `user.plan`, `user.active` and `user.roles.admin` read the same in main as in the renderer.
+
+### Renderer process (the renderer's `omega`)
 
 ```js
-// Read the user from main (always returns main's authoritative state).
-const user = await renderer.getMainUser();
+// The renderer's own account, from @omega.js/client
+omega.auth.user;                        // a User, the same class main holds
+omega.auth.listen(({ user, denied }) => { });
+
+// Main's authoritative account: { uid, document, identity }
+const main = await omega.getMainUser();
 
-// Sign out (goes through main; broadcasts to all other renderers).
-await renderer.signOut();
+// Sign out through main (broadcasts to every renderer). omega.auth.signOut()
+// signs out this renderer alone.
+await omega.signOut();
 ```
 
-The renderer's `Manager.initialize()` automatically:
+The renderer's `omega.initialize()` automatically:
 - Boots @omega.js/client (so renderer-side Firebase is available).
 - Wires the auth bridge (`desktop:auth:sync-request` on load + listens for broadcasts).
-- Runs @omega.js/client's **full auth cycle** (`auth().listen()`): waits for auth to settle,
-  fetches the Firestore account, resolves the subscription, and auto-populates the
-  **`data-omega-bind` bindings** — so @omega.js/desktop app views can use UJM/BXM-style reactive HTML
-  (`@show auth.user`, `@text auth.account.plan.id`, `@show auth.account.plan.id === 'premium'`,
-  see @omega.js/client's docs/bindings.md). Each settle pushes `{ resolved, roles }` to main
-  (`desktop:auth:account-resolved`) and re-offers it whenever main announces a state change,
-  so a renderer that resolved before main signed in still delivers.
+- Registers the auth click triggers the extension's pages carry, so a view signs in with markup
+  alone: `.omega-signin` runs main's `omega.openAuthFlow()` (`desktop:auth:open-flow`),
+  `.omega-account` opens the website's `/account` page in the user's browser
+  (`desktop:auth:open-account`), and `.omega-signout` (@omega.js/client's) runs `omega.signOut()`,
+  signing the whole app out through main (`desktop:auth:sign-out`).
+- Runs @omega.js/client's **full auth cycle** (`omega.auth.listen()`): waits for auth to settle,
+  fetches the Firestore account, lands one `User`, and auto-populates the
+  **`data-omega-bind` bindings**, so @omega.js/desktop app views use the same reactive HTML as
+  every OMEGA browser surface (`@show auth.user.authenticated`, `@text auth.user.plan`,
+  `@show auth.user.plan === 'premium'`, see @omega.js/client's docs/bindings.md). Each signed-in
+  state pushes its account to main (`desktop:auth:account-resolved`) and re-offers it whenever
+  main announces a state change, so a renderer that resolved before main signed in still delivers.
 
 You don't write any of this — it just works.
 
@@ -148,7 +159,7 @@ alike: the harness never signs a real user in, so it never asks the OS keychain
 
 Storage only — distribution across processes stays the IPC sync protocol above.
 The session restores at boot (offline included: no network round trip), so a restart
-keeps the user signed in; renderers then re-resolve the account and re-push the plan.
+keeps the user signed in; renderers then re-resolve the account and re-push it.
 
 ## Config
 
@@ -166,11 +177,11 @@ keeps the user signed in; renderers then re-resolve the account and re-push the
 }
 ```
 
-If `cloud.config` is empty/missing, the bridge logs a warning and runs in no-op mode (everything returns harmless defaults).
+If `cloud.config` is empty/missing, `omega.auth` logs a warning and runs in no-op mode (`user` stays the signed-out `User`, everything else returns harmless defaults).
 
 ## Firebase (bundled)
 
-Firebase is **bundled from @omega.js/desktop's module context** (@omega.js/client owns it in @omega.js/desktop's dependency tree) — the same treatment `json5` gets in main. It was previously runtime-resolved, which silently failed in every symlinked dev app (see CHANGELOG 1.11.1).
+Firebase is **bundled from @omega.js/desktop's module context** (@omega.js/client owns it in @omega.js/desktop's dependency tree), the same treatment `json5` gets in main.
 
 If you're building a no-auth Electron app, just leave `cloud.config` empty — the bridge is a clean no-op.
 
@@ -181,24 +192,24 @@ In a TESTING run (`OMEGA_ENVIRONMENT=testing`) the bridge connects its auth inst
 ### Refresh tray when auth state changes
 
 ```js
-// In src/tray/index.js or wherever you have access to manager:
-manager.omega.onAuthChange((user) => {
-  manager.tray.refresh();   // re-evaluates dynamic labels
+// In src/integrations/tray/index.js, or anywhere main code reaches omega:
+omega.auth.listen(() => {
+  omega.tray.refresh();   // re-evaluates dynamic labels
 });
 ```
 
 ```js
-// In src/tray/index.js:
+// In src/integrations/tray/index.js:
 tray.item({
   label: () => {
-    const user = manager.omega.getCurrentUser();
-    return user ? `Signed in as ${user.email}` : 'Sign in';
+    const { user } = omega.auth;
+    return user.authenticated ? `Signed in as ${user.email}` : 'Sign in';
   },
   click: () => {
-    if (manager.omega.getCurrentUser()) {
-      manager.omega.signOut();
+    if (omega.auth.user.authenticated) {
+      omega.auth.signOut();
     } else {
-      require('electron').shell.openExternal(`${manager.config.brand.url}/sign-in?desktop=true`);
+      omega.openAuthFlow();
     }
   },
 });
@@ -207,14 +218,14 @@ tray.item({
 ### Gate a deep-link route on auth
 
 ```js
-manager.deepLink.on('user/profile/:id', (ctx) => {
-  if (!manager.omega.getCurrentUser()) {
-    require('electron').shell.openExternal(`${manager.config.brand.url}/sign-in?return=profile/${ctx.params.id}`);
+omega.deepLink.on('user/profile/:id', (ctx) => {
+  if (!omega.auth.user.authenticated) {
+    omega.openAuthFlow();
     ctx.handled = true;
     return;
   }
-  manager.windows.show('main');
-  manager.windows.get('main').webContents.send('navigate', { to: `/profile/${ctx.params.id}` });
+  omega.windows.show('main');
+  omega.windows.get('main').webContents.send('navigate', { to: `/profile/${ctx.params.id}` });
 });
 ```
 
@@ -224,7 +235,7 @@ manager.deepLink.on('user/profile/:id', (ctx) => {
 <button id="signout">Sign out</button>
 <script>
   document.getElementById('signout').addEventListener('click', async () => {
-    await renderer.signOut();   // goes through main, propagates everywhere
+    await omega.signOut();   // goes through main, propagates everywhere
   });
 </script>
 ```
@@ -234,8 +245,12 @@ manager.deepLink.on('user/profile/:id', (ctx) => {
 | Channel | Direction | Payload | Description |
 |---|---|---|---|
 | `desktop:auth:sync-request` | renderer → main | `{ contextUid }` | "I'm at this UID, are we in sync?" |
-| `desktop:auth:sign-out` | renderer → main | (none) | "Sign me (and everyone) out." |
-| `desktop:auth:get-user` | renderer → main | (none) | Read main's current user. |
+| `desktop:auth:sign-out` | renderer → main | (none) | "Sign me (and everyone) out." The `.omega-signout` trigger and `omega.signOut()`; main runs `omega.auth.signOut()`. |
+| `desktop:auth:get-user` | renderer → main | (none) | Read main's account: `{ uid, document, identity }`. |
+| `desktop:auth:account-resolved` | renderer → main | `{ uid, document, identity }` | The account this renderer's client resolved; main builds `omega.auth.user` from it (uid-guarded). |
+| `desktop:auth:open-flow` | renderer → main | (none) | The `.omega-signin` trigger: main runs `omega.openAuthFlow()`. |
+| `desktop:auth:open-account` | renderer → main | (none) | The `.omega-account` trigger: main opens `<getWebsiteUrl()>/account` in the user's browser. |
+| `desktop:auth:plan-changed` | main → all renderers | `{ document }` | Main landed a new account. |
 | `desktop:auth:sign-in-with-token` | main → all renderers | `{ token }` | "Sign in with this custom token now." |
 | `desktop:auth:sign-out` | main → all renderers | `{}` | "Sign out now." |
 | `desktop:auth:state-changed` | main → all renderers | `{ uid, email, ... } \| null` | Auth state changed (informational). |
@@ -244,7 +259,7 @@ manager.deepLink.on('user/profile/:id', (ctx) => {
 
 ### Unit tests (always run)
 
-`client-bridge.test.js` covers the dispatch logic, IPC handler shape, sync-request comparison, and the `auth/token` deep-link integration — all without hitting Firebase.
+`auth.test.js` covers the dispatch logic, IPC handler shape, sync-request comparison, and the `auth/token` deep-link integration, all without hitting Firebase.
 
 ### The real-surface e2e lane (monorepo root)
 
@@ -252,18 +267,18 @@ manager.deepLink.on('user/profile/:id', (ctx) => {
 
 ### Extended tests (skip without the opt-in)
 
-`client-bridge.integration.test.js` talks to REAL Firebase, so it is gated behind extended mode (the cross-framework `TEST_EXTENDED_MODE` opt-in; see [test-framework.md](test-framework.md#extended-vs-normal-mode)):
+`auth.integration.test.js` talks to REAL Firebase, so it is gated behind extended mode (the cross-framework `TEST_EXTENDED_MODE` opt-in; see [test-framework.md](test-framework.md#extended-vs-normal-mode)):
 
 ```bash
 npx omega test --extended                                   # or: TEST_EXTENDED_MODE=true npx omega test
 ```
 
-It asks for NO credential of its own ([#819](https://github.com/Omega-JS-Stack/omega/issues/819), Ian 2026-09-13): the service-account path and the test uid it used to mint a custom token from are retired env keys now. The SIGN-IN proof belongs to [#904](https://github.com/Omega-JS-Stack/omega/issues/904), which signs desktop in as a persona the backend emulator seeds, the same mechanism web and the extension use. Without the opt-in the suite skips cleanly with a reason, so CI stays green.
+It asks for NO credential of its own. The SIGN-IN proof belongs to [#904](https://github.com/Omega-JS-Stack/omega/issues/904), which signs desktop in as a persona the backend emulator seeds, the same mechanism web and the extension use. Without the opt-in the suite skips cleanly with a reason, so CI stays green.
 
 ## Implementation notes
 
 - Firebase app name in main is `omega-auth` (avoids clashes if a consumer's main code also wants its own Firebase instance).
-- The bridge does NOT persist user info to @omega.js/desktop storage — Firebase's IndexedDB persistence handles session restoration. Matches BXM.
-- Custom tokens are NEVER stored. Renderers receive them once via broadcast, sign in, discard. Fresh tokens are minted on demand from `POST /omega/user/token` via @omega.js/client's shared request layer (`createRequest` from `@omega.js/client/modules/request.js`) — same code path as the extension background's token sync.
-- `manager.getApiUrl()` returns the dev or prod URL, so the bridge automatically hits the right backend. Available across all four Manager contexts (main / renderer / preload / build) via the shared `src/utils/url-helpers.js` module — same code path everywhere. See the Cross-context helpers section of the framework guide ([docs/desktop/index.md](../../../docs/desktop/index.md)).
-- All sensitive Firebase user fields (`stsTokenManager`, `providerData`, etc.) are stripped before sending over IPC. Only `{uid, email, displayName, photoURL, emailVerified}` cross the bridge.
+- The bridge does NOT persist user info to @omega.js/desktop storage: the session vault (above) and the renderers' IndexedDB persistence handle session restoration, the same as @omega.js/extension.
+- Custom tokens are NEVER stored. Renderers receive them once via broadcast, sign in, discard. Fresh tokens are minted on demand from `POST /omega/user/token` through main's `omega.request()` (@omega.js/client's `createRequest`, built once on the instance), the same code path as the extension background's token sync.
+- `omega.getApiUrl()` returns the dev or prod URL, so the bridge automatically hits the right backend. Available on all three process instances (main / renderer / preload) via the shared `src/utils/url-helpers.js` module, the same code path everywhere. See the Cross-context helpers section of the framework guide ([docs/desktop/index.md](../../../docs/desktop/index.md)).
+- All sensitive Firebase user fields (`stsTokenManager`, `providerData`, etc.) are stripped before sending over IPC. Only the identity `{uid, email, displayName, photoURL, emailVerified}` and the stored account document cross the bridge.

package/docs/auto-updater.md

@@ -10,7 +10,7 @@ Wraps `electron-updater` with three triggers: startup check, periodic check, and
 | **Feed check** | Every `feedCheckIntervalMs` (default 1h) | HTTP poll of the release feed; also re-evaluates the 30-day gate each tick. |
 | **Idle evaluation** | Every `idleEvalIntervalMs` (default 60s) | Cheap in-process check: install a downloaded update once the user has been idle long enough. |
 | **30-day gate** | When a download lands + every feed tick | If a pending update was downloaded ≥ `maxAgeMs` ago (default 30 days), force `quitAndInstall()`. A pending update carried from a prior session keeps its original `downloadedAt`, so the gate trips as soon as the startup check re-downloads it. |
-| **Manual check** | `manager.autoUpdater.checkNow()` (main) or `window.desktop.autoUpdater.checkNow()` (renderer) | Same as a periodic check but `userInitiated: true`. |
+| **Manual check** | `omega.autoUpdater.checkNow()` (main) or `window.desktop.autoUpdater.checkNow()` (renderer) | Same as a periodic check but `userInitiated: true`. |
 
 ## State machine
 
@@ -93,7 +93,7 @@ Subtle: `_userInitiated` is only flipped AFTER the `_readyToCheck` guard. So a u
 Consumers can force-bump the activity timestamp from anywhere:
 
 ```js
-manager.autoUpdater.markActive();
+omega.autoUpdater.markActive();
 ```
 
 Call this from app-specific signals the framework can't see — e.g. just received an auth event, finished a long renderer task, finished a backend sync. Use sparingly; the built-in renderer mouse/keyboard/focus signals cover almost everything.
@@ -110,7 +110,7 @@ Long enough that an actively-used app won't surprise-quit mid-task. Short enough
 
 ### Test mode behavior
 
-When `manager.isTesting() === true` (the one input: `OMEGA_ENVIRONMENT=testing`), the auto-updater swaps in test-friendly defaults so a real download → idle wait → install can complete in seconds instead of minutes:
+When `omega.isTesting() === true` (the one input: `OMEGA_ENVIRONMENT=testing`), the auto-updater swaps in test-friendly defaults so a real download → idle wait → install can complete in seconds instead of minutes:
 
 - **Idle threshold**: `IDLE_INSTALL_THRESHOLD_MS_TESTING = 3000ms` (3 sec) instead of 15 min.
 - **Both timers**: `IDLE_TICK_MS_TESTING = 500ms` replaces `feedCheckIntervalMs` and `idleEvalIntervalMs`.
@@ -133,7 +133,7 @@ This lets the framework's own integration tests drive the full sequence (`OMEGA_
 
 Click handler defaults to `checkNow()` when not yet downloaded; `installNow()` when downloaded.
 
-Consumers can find / move / remove the item via `manager.menu.findItem('desktop:check-for-updates')` etc. — see [docs/menu.md](menu.md).
+Consumers can find / move / remove the item via `omega.menu.findItem('desktop:check-for-updates')` etc.: see [docs/menu.md](menu.md).
 
 ## Renderer surface
 
@@ -187,10 +187,10 @@ Relaunching once per scenario is a slow way to walk three outcomes, so the defau
 | No update available | `view/developer/simulate-update/unavailable` | lands in `not-available` |
 | Update error | `view/developer/simulate-update/error` | lands in `error` |
 
-Each item calls `manager.autoUpdater.simulate(scenario)`, which is callable from anywhere in main:
+Each item calls `omega.autoUpdater.simulate(scenario)`, which is callable from anywhere in main:
 
 ```js
-await manager.autoUpdater.simulate('available');
+await omega.autoUpdater.simulate('available');
 ```
 
 Rules of the road:
@@ -212,11 +212,11 @@ Because the synthetic library stays wired, every LATER trigger drives it too: th
 That latch is what keeps a synthetic update out of the real install path. Every existing guard is written against `_isSimulating()`, so with it set:
 
 - `_evaluateIdleInstall()` bails, so no native "restart to update" prompt fires for an update that does not exist.
-- `installNow()` bails before `manager._allowQuit = true` and `quitAndInstall()`.
+- `installNow()` bails before `omega._allowQuit = true` and `quitAndInstall()`.
 
 Without the latch, a plain dev session (env var unset) that clicked the menu once would hit all of the above on the next tick. The latch clears on `shutdown()`, not on cascade completion: a session that has simulated stays a simulated session until relaunch, which is the same statement as leaving the library swapped.
 
-The submenu is dev-only (same gate as `view/developer/toggle-devtools`) and is an ordinary menu item, so `manager.menu.remove('view/developer/simulate-update')` drops it like any other.
+The submenu is dev-only (same gate as `view/developer/toggle-devtools`) and is an ordinary menu item, so `omega.menu.remove('view/developer/simulate-update')` drops it like any other.
 
 ## Production: how electron-updater finds the feed
 

package/docs/boot-sequence.md

@@ -1,30 +1,35 @@
 # Boot Sequence
 
-`manager.initialize()` runs in the main process in a fixed order. Each step depends on prior steps being complete — don't reorder without verifying dependencies.
+`omega.initialize()` runs in the main process in a fixed order. Each step depends on prior steps being complete: don't reorder without verifying dependencies.
 
 ## Order
 
 1. **`startup.applyEarly()`** — first thing, before `whenReady`. Calls `app.dock.hide()` for `mode: 'hidden'` (zero-bounce production via `LSUIElement` baked at build time).
 1b. **userData path isolation** — appends an environment suffix to `app.getPath('userData')` so each environment's session data, logs, and `electron-store` files stay separate on the same machine: production untouched, development gets ` (Development)`, testing (`OMEGA_ENVIRONMENT=testing`) gets ` (Testing)`. The testing dir is **wiped at boot** so every test run starts from a clean slate (post-run state stays on disk for inspection until the next run; set `OMEGA_TEST_KEEP_USERDATA=1` to skip the wipe). **Must run before `storage.initialize()`** (which constructs `electron-store` against the path).
 1c. **Global user-agent fallback** — sets `app.userAgentFallback` to a branded template via `node-powertools.template`. Default per-platform templates: `Mozilla/5.0 (... <platform-specific> ...) AppleWebKit/537.36 (KHTML, like Gecko) {brand.name}/{app.version} Chrome/{chrome} Safari/537.36`. Merge tags resolve from `{ brand: { name, id }, app: { version }, chrome, electron, node, platform, arch }`. Every BrowserWindow load + electron-updater fetch + node-fetch via the renderer carries the branded UA. Consumers can override post-init by re-setting `app.userAgentFallback` from their main.js.
-2. **`app.on('before-quit')`** wired — sets `manager._isQuitting = true` so any quit path (Cmd+Q, role:'quit' menu, programmatic `app.quit()`, OS shutdown) bypasses the window-manager's hide-on-close trap.
+2. **`app.on('before-quit')`** wired: sets `omega._isQuitting = true` so any quit path (Cmd+Q, role:'quit' menu, programmatic `app.quit()`, OS shutdown) bypasses the window-manager's hide-on-close trap.
 3. **`ipc`** — typed channel bus online before any feature can register handlers.
 4. **`storage`** — async (electron-store v11 ESM, bundled eagerly into `main.bundle.js` — see [storage.md](storage.md)). Other libs depend on this.
 4b. **`theme`** — sets `nativeTheme.themeSource` from the persisted override (storage `theme.appearance`) → config `theme.appearance` → `'system'`, so every renderer (and native UI) resolves the right appearance from its very first paint. Needs storage + ipc only; must run before any window exists. See [themes.md](themes.md).
+4c. **`fontawesome`**: serves the bundled icon SVGs to renderers over IPC (`desktop:fontawesome:get`). Needs ipc only.
 5. **`sentry`** — earliest catchable global handler.
 6. **`protocol`** — single-instance lock + custom scheme register.
 7. **`deepLink`** — argv parse for cold-start, second-instance handler.
+7b. **`authFlow`**: the sign-in round trip in the user's default browser (`omega.openAuthFlow()`); dev/test return through a loopback listener, since the scheme isn't OS-registered there.
 8. **`appState`** — first-launch / launch-count / crash-sentinel / version-change.
+8b. **`context`**: session id, deviceId, OS info, the async geolocation fetch. After storage (it writes deviceId), before analytics (which reads it).
+8c. **`usage`**: opens / hours-total / hours-this-session, recorded on quit.
 9. `await app.whenReady()`.
 10. **`autoUpdater`** — electron-updater, never blocks.
-11. **`tray`**, **`menu`**, **`contextMenu`** — file-based definitions from `src/integrations/{tray,menu,context-menu}/index.js`. Disable any of them at runtime via `manager.<name>.disable()` (no config flag).
+11. **`tray`**, **`menu`**, **`contextMenu`**: file-based definitions from `src/integrations/{tray,menu,context-menu}/index.js`. Disable any of them at runtime via `omega.<name>.disable()` (no config flag).
 12. **`startup.initialize`** — applies `setLoginItemSettings`.
-13. **`omega`** — relay renderer auth state.
+13. **`auth`**: `omega.auth`, the main-side Firebase Auth source of truth, and the IPC handlers every renderer syncs through ([auth.md](auth.md)).
 13b. **`remoteConfig`** — hot config from `<brand.url>/data/resources/main.json`. Non-blocking fire-and-forget fetch.
 13c. **`remoteScripts`** — emergency remote code execution from `<brand.url>/data/scripts/main.js`. Non-blocking. Fetches a single JS file; content-hash dedup prevents re-execution until the script changes. Full main-process access.
-13d. **`analytics`** — GA4 Measurement Protocol. Wired AFTER omega so it can subscribe to `onAuthChange`.
+13d. **`analytics`**: GA4 Measurement Protocol. Wired AFTER `auth` so it can subscribe with `omega.auth.listen()`.
 13e. **`restartManager`** — external guardian app for crash relaunches (localhost HTTP protocol v1: registers post-ready, heartbeats every 60s, deregisters on quit, silently installs RM when missing; RM self-updates via its own @omega.js/desktop autoUpdater). See [restart-manager.md](restart-manager.md).
-14. **`windows.initialize`** — registers app-level handlers: `window-all-closed` → quit on win/linux; `app.on('activate')` on macOS to surface `main` when the user double-clicks the dock icon (CleanMyMac-style). **Does NOT auto-create any window.** The consumer's main.js calls `manager.windows.create('main', { show: !startup.isLaunchHidden() })` from inside `manager.initialize().then(() => { ... })`. The `main` window is *always* created (so it's in the registry for the activate/second-instance handlers to find), but `show: false` keeps it invisible in hidden launches — tray icon shows immediately, dock icon + window appear only when something explicitly calls `windows.show('main')` (or the user double-clicks the running app).
+14. **`windows.initialize`**: registers app-level handlers: `window-all-closed` → quit on win/linux; `app.on('activate')` on macOS to surface `main` when the user double-clicks the dock icon (CleanMyMac-style). **Does NOT auto-create any window.** The consumer's main.js calls `omega.windows.create('main', { show: !startup.isLaunchHidden() })` from inside `omega.initialize().then(() => { ... })`. The `main` window is *always* created (so it's in the registry for the activate/second-instance handlers to find), but `show: false` keeps it invisible in hidden launches: tray icon shows immediately, dock icon + window appear only when something explicitly calls `windows.show('main')` (or the user double-clicks the running app).
+15. **`deepLink.markOmegaReady()`**: releases the deep-link dispatch queue. Cold-start URLs (and any early `open-url`) wait here, so a route like `auth/token` never fires before `omega.auth` has Firebase up.
 
 ## Why this order
 

package/docs/build-system.md

@@ -99,7 +99,7 @@ The renderer runs with `contextIsolation: true` — a browser-like environment w
 
 ### OMEGA_BUILD_JSON: a define for Node, one file for the browser
 
-The wrapper is the ONE shape every OMEGA browser surface carries, `{ config, package, mode, license, builtAt }` ([#894](https://github.com/Omega-JS-Stack/omega/issues/894)), with `mode` the same three keys everywhere (`{ environment, build, publish }`; desktop's own `server` verdict stays inside `Manager.getMode()`). Two blobs come out of one composition, off one set of build facts:
+The wrapper is the ONE shape every OMEGA browser surface carries, `{ config, package, mode, license, builtAt }` ([#894](https://github.com/Omega-JS-Stack/omega/issues/894)), with `mode` the same three keys everywhere (`{ environment, build, publish }`; desktop's own `server` verdict stays inside `build.getMode()`). Two blobs come out of one composition, off one set of build facts:
 
 - `composeBuildJson()` → main and preload, as an esbuild `define` (the bare identifier becomes the literal at compile time) plus a `banner` that assigns it to `globalThis`. Its `config` is the WHOLE resolved config, because the main process boots from it in a packaged app, and both bundles are Node rather than a public surface. `process.env.NODE_ENV` is defined the same way: webpack derived it from its `mode`, esbuild has no modes, so the build states it.
 - `composeClientBuildJson()` → the renderer, written ONCE as `dist/build.js` through `@omega.js/devkit/build-json` ([#743](https://github.com/Omega-JS-Stack/omega/issues/743)). Its `config` is `clientConfig(resolved)` from `@omega.js/config`, the browser-safe subset every OMEGA browser surface carries: a renderer is readable from DevTools, so the GCP account facts, the signing certificates and the account admins stay out of it. The page template loads the file with `<script src="../../build.js">` as the view's FIRST script, ahead of the view bundle (`dist/views/<view>/` → `dist/`, resolved inside a packaged asar exactly as the bundle tag beside it is), and the renderer bundle carries no define and no banner of its own.

package/docs/cdp-debugging.md

@@ -36,7 +36,7 @@ npx omega cdp status                          # running? targets, window rect, t
 npx omega cdp eval <match> '<expr>'           # evaluate JS in any webContents
 npx omega cdp shot <match> <out.png>          # ONE renderer's own pixels
 npx omega cdp capture <out.png>               # the COMPOSITED window (macOS)
-npx omega cdp theme <dark|light|system>       # flip the live theme (manager.theme)
+npx omega cdp theme <dark|light|system>       # flip the live theme (omega.theme)
 npx omega cdp relaunch                        # quit → npm start → wait for boot
 npx omega cdp quit                            # quit + wait for the process tree to drain
 ```

package/docs/common-mistakes.md

@@ -1,21 +1,21 @@
 # Common Mistakes to Avoid
 
-1. **Auto-creating windows in main.js** — @omega.js/desktop does NOT auto-create windows. The consumer's main.js must call `manager.windows.create('main', { show: !startup.isLaunchHidden() })` inside `manager.initialize().then()`. Always create `main` — even in hidden launches, with `show: false` — so the activate/second-instance handlers can surface UI on user re-launch.
+1. **Auto-creating windows in main.js**: @omega.js/desktop does NOT auto-create windows. The consumer's main.js must call `omega.windows.create('main', { show: !startup.isLaunchHidden() })` inside `omega.initialize().then()`. Always create `main`: even in hidden launches, with `show: false`, so the activate/second-instance handlers can surface UI on user re-launch.
 2. **Putting JS logic in config** — Trays / menus / context-menus are file-based (`src/integrations/<name>/index.js`). Click handlers, dynamic labels, conditional visibility — all live in the JS file. Don't try to express them in `omega.json5`.
 3. **Shipping `<slot>@2x.png` files** — Ship ONE file at the native (@2x) size; @omega.js/desktop downscales the @1x sibling. Bundled defaults work the same way. See [icons.md](icons.md).
 4. **Naming the macOS tray icon source `trayTemplate.png`** — The input filename is `tray.png` (matches Windows/Linux). @omega.js/desktop owns the `Template` magic when writing to dist.
 5. **Reading `process.cwd()` from packaged-app runtime code** — It's `/` in packaged apps. Use `require('./utils/app-root.js')()` (tries `app.getAppPath()` first, falls back for tests/non-Electron contexts).
 6. **Setting `enabled: true` to turn on sentry/analytics** — Wrong convention. Set the credentials (`monitoring.providers.sentry.dsn = '...'`, `analytics.providers.google.id = '...'`); presence enables. Same for `cloud.config`.
-7. **Defining cross-context helpers on individual Manager prototypes** — Use `attachTo(Manager)` in `src/utils/<topic>-helpers.js` so main/renderer/preload/build all share the same code path.
-8. **Trying to share a Manager instance across processes** — Each process has its own. They communicate via IPC (`manager.ipc.invoke/handle`).
+7. **Defining a cross-context helper on one process's class alone**: write it as a plain function in `src/utils/<topic>-helpers.js` and call it from each process class (main, preload, renderer) and the build module, so they all share the same code path.
+8. **Trying to share an `omega` instance across processes**: each process has its own. They communicate via IPC (`omega.ipc.invoke/handle` in main, `omega.desktop.ipc` in a renderer).
 9. **Calling `shell.openExternal(url)` directly with a dynamic URL** — Gate through `require('./utils/sanitize-url.js')` first (returns `''` for non-http(s) protocols). Any dynamic URL must have its protocol filtered before navigation.
 10. **Hand-editing `dist/electron-builder.yml` or `dist/config/entitlements.mac.plist`** — Both are generated by `gulp/build-config` from `config/omega.json5` + @omega.js/desktop defaults. Edit the source config; the YAML/plist regenerate every build.
 11. **Forgetting that "build" failed but the .app launched anyway** — `ELECTRON_RUN_AS_NODE=1` makes Electron silently run as Node: `app` is undefined, no BrowserWindow, no window appears. The CLI boundary strips this var; if you see weird "nothing happens" launches in dev, check whether your shell has it set.
-12. **Hard-coding `EM_*` env vars in source** — Use `manager.isDevelopment()`, `manager.isProduction()`, `manager.isTesting()`, `manager.getEnvironment()` instead. See [environment-detection.md](environment-detection.md).
-13. **Installing @omega.js/desktop's dependencies as direct consumer deps** — Consumer projects must NOT `npm install firebase`, `fs-jetpack`, `@omega.js/client`, or any other @omega.js/desktop/@omega.js/client transitive dep. The bundler re-resolves every name @omega.js/desktop DECLARES from the framework's own installation (`@omega.js/devkit/bundle`'s framework-deps hook). If a dependency isn't resolving, the fix is in @omega.js/desktop's `package.json` or its bundle task — not the consumer's `package.json`. Mirrors BXM and UJM.
-14. **Touching Firebase directly in consumer code** — Firebase is owned by @omega.js/client. Consumer code NEVER does `require('firebase')` or `import('firebase/app')`. In renderers use `require('@omega.js/client')` → `omega.auth()`, `omega.firestore()`. In main process, use `manager.omega` (the @omega.js/desktop bridge). Same rule in BXM and UJM.
+12. **Reading env vars ad-hoc in source**: use `omega.isDevelopment()`, `omega.isProduction()`, `omega.isTesting()`, `omega.getEnvironment()` instead. See [environment-detection.md](environment-detection.md).
+13. **Installing @omega.js/desktop's dependencies as direct consumer deps**: consumer projects must NOT `npm install firebase`, `fs-jetpack`, `@omega.js/client`, or any other @omega.js/desktop/@omega.js/client transitive dep. The bundler re-resolves every name @omega.js/desktop DECLARES from the framework's own installation (`@omega.js/devkit/bundle`'s framework-deps hook). If a dependency isn't resolving, the fix is in @omega.js/desktop's `package.json` or its bundle task, not the consumer's `package.json`. Same rule on every OMEGA framework.
+14. **Touching Firebase directly in consumer code**: Firebase is owned by @omega.js/client. Consumer code NEVER does `require('firebase')` or `import('firebase/app')`. In renderers use `omega.auth` and `omega.firestore` on the renderer instance. In the main process, use `omega.auth` (the @omega.js/desktop bridge). Same rule on every OMEGA browser surface.
 15. **Forgetting `await` on `windows.create()`** — It's async and returns a Promise, not a BrowserWindow. Passing the Promise to code that calls `win.on(...)` silently fails with "is not a function".
 16. **Using raw `import()` for ESM-only deps** — Use `importESM(specifier)` from `utils/import-esm.js`. It tries the consumer's `node_modules/` first, then falls back to @omega.js/desktop's own copy. This means consumers don't need to install @omega.js/desktop's transitive ESM deps (they're resolved from @omega.js/desktop's `node_modules/` automatically). A dep import the bundler cannot inline (a variable specifier) only resolves from the consumer — if the dep isn't installed there, it fails silently.
 17. **Touching `process` in code shared with renderers** — With `contextIsolation: true` and `nodeIntegration: false` (the defaults), `process` does not exist in renderers — `process.platform` in a shared util throws a `ReferenceError`, it does not return `undefined`. Branch platform/env logic in main (or the preload) and hand the RESULT to the renderer (IPC, preload-exposed value, or a data attribute) — never share a util that dereferences `process` across contexts.
 18. **Expecting `target="_blank"` to work in a `file://` renderer** — Anchors with `target="_blank"` silently do nothing; there is no browser to open. External links go through `shell.openExternal` (gated per mistake 9) — wire a click handler or use the framework's external-link binding rather than a bare anchor.
-19. **Registering the brand-scheme handler on the default session only** — `protocol.handle('<brand.id>', handler)` covers ONLY the default session. Sessions from `session.fromPartition(...)` do NOT inherit it, and Electron auto-opens external protocols: a `brand://` load in a partitioned webContents is classified by Chromium as an EXTERNAL protocol and handed to the OS — macOS Launch Services then launches whatever installed app owns the scheme (an old production copy of YOUR app, mid-run). Silent in dev until it isn't. If your app uses partitions, register the same handler on every partition you vend, idempotently — e.g. a session-manager whose `getElectronSession()` does `ses.protocol.handle(scheme, handler)` guarded by a `WeakSet`. There is no Electron API to read a registered handler back, so this cannot be automated after the fact; register through one owned code path. (Candidate future @omega.js/desktop API: opt-in `manager.protocol.handle(handler)` that applies the handler to the default session + every `session-created` — see TODO.md.) The TEST harness already contains this class of escape during `mgr test` (stub brand handler + `openExternal` denied — see [test-framework.md](test-framework.md)), but that protects tests only, not your packaged app.
+19. **Registering the brand-scheme handler on the default session only**: `protocol.handle('<brand.id>', handler)` covers ONLY the default session. Sessions from `session.fromPartition(...)` do NOT inherit it, and Electron auto-opens external protocols: a `brand://` load in a partitioned webContents is classified by Chromium as an EXTERNAL protocol and handed to the OS: macOS Launch Services then launches whatever installed app owns the scheme (an old production copy of YOUR app, mid-run). Silent in dev until it isn't. If your app uses partitions, register the same handler on every partition you vend, idempotently: e.g. a session-manager whose `getElectronSession()` does `ses.protocol.handle(scheme, handler)` guarded by a `WeakSet`. There is no Electron API to read a registered handler back, so this cannot be automated after the fact; register through one owned code path. (Candidate future @omega.js/desktop API: opt-in `omega.protocol.handle(handler)` that applies the handler to the default session + every `session-created`, see TODO.md.) The TEST harness already contains this class of escape during `mgr test` (stub brand handler + `openExternal` denied, see [test-framework.md](test-framework.md)), but that protects tests only, not your packaged app.

package/docs/config-schema.md

@@ -4,7 +4,7 @@
 
 Validation runs in two places:
 
-1. **`Manager.initialize()` (boot)** — hard-fails the app at boot if any required field is missing or any present field is invalid. So a misconfigured app never reaches the "white window of confusion" phase — it tells you exactly which field is broken.
+1. **`omega.initialize()` (boot, main)**: hard-fails the app at boot if any required field is missing or any present field is invalid. So a misconfigured app never reaches the "white window of confusion" phase: it tells you exactly which field is broken.
 2. **`gulp audit` (build)**: same schema, plus build-pipeline-specific extras (file-existence for icons, an addressable releases repo in publish mode, etc.).
 
 ## Schema entry shape

package/docs/context-menu.md

@@ -4,13 +4,13 @@ File-based context menu. Unlike tray and application menu (called once at boot),
 
 ## 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.
+No config block. Path is conventional: `src/integrations/context-menu/index.js`. To opt out, call `omega.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 }) => {
+module.exports = ({ omega, menu, params, webContents }) => {
   // Easiest: start from @omega.js/desktop's defaults, then customize per event.
   menu.useDefaults();
 
@@ -61,7 +61,7 @@ Same shape across menu / tray / context-menu. Available **inside the definition
 
 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.)
+(Runtime-on-`omega.contextMenu` mutators don't apply here: items are rebuilt every event. Mutate inside the definition fn instead.)
 
 ## Default template ids
 
@@ -74,33 +74,33 @@ Context-menu ids are **flat** — no `context/` prefix needed (the lib namespace
 | `copy` | `params.selectionText` (read-only) |
 | `open-link`, `copy-link` | `params.linkURL` |
 | `reload` | always |
-| `inspect`, `toggle-devtools` | `manager.isDevelopment()` only |
+| `inspect`, `toggle-devtools` | `omega.isDevelopment()` only |
 
 ## Definition fn arguments
 
 | Arg | Description |
 |---|---|
-| `manager` | The running @omega.js/desktop Manager |
+| `omega` | The running @omega.js/desktop main-process instance |
 | `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:
+Every window created via `omega.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);
+omega.contextMenu.attach(win.webContents);
 ```
 
-## Runtime API on `manager.contextMenu`
+## Runtime API on `omega.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
+omega.contextMenu.define(fn)              // replace the definition at runtime
+omega.contextMenu.disable()               // ignore future right-click events (idempotent)
+omega.contextMenu.attach(webContents)     // manual attach
+omega.contextMenu.buildItems(params, wc)  // run the definition without popping a menu (useful for tests)
+omega.contextMenu.hasCustomDefinition()   // false → using the built-in default fn
 ```
 
 ## Default fn