@omega.js/desktop 0.53.0 → 0.54.1

package/docs/analytics.md

@@ -1,140 +0,0 @@
-# Analytics
-
-GA4 Measurement Protocol with cross-platform identity. The same human gets unified events across desktop (@omega.js/desktop), web (UJM/@omega.js/client), and backend (@omega.js/backend) — provided all four reference the same Firebase project ID.
-
-## How identity works
-
-Every event ships with two GA4 fields:
-
-- **`client_id`** — uniquely identifies a *desktop install*. Stable per-install, anonymous.
-- **`user_id`** — uniquely identifies a *human*. Set when the user is signed in via Firebase Auth. It rides **alongside** the `client_id`, never in place of it: GA stitches sessions by the client id.
-
-@omega.js/desktop derives both via `uuidv5(input, namespace)` where:
-
-- `namespace = uuidv5(cloud.config.projectId, uuidv5.URL)` — same projectId in @omega.js/backend/UJM/@omega.js/client → same namespace everywhere.
-- `client_id = uuidv5(deviceId, namespace)` — the `deviceId` comes from the ONE shared derivation, `@omega.js/analytics`' `deriveDeviceId` ([#396](https://github.com/Omega-JS-Stack/omega/issues/396)), with desktop injecting its storage and its MAC seed ([context.md](context.md)).
-- `user_id = uuidv5(firebaseUid, namespace)` — set automatically when `omega.onAuthChange` fires with a uid; cleared on logout.
-
-Why this matters: the same Firebase user signing into the desktop app, the web app, and triggering backend events produces **identical `user_id` values** in every Measurement Protocol call. GA4 stitches the events into one user journey across all surfaces.
-
-What does NOT cross surfaces is the machine. The desktop app's deviceId lives in electron-store and a browser's lives in that browser's localStorage, so one machine is two `client_id`s — the human is the link, and always was.
-
-## Config
-
-```jsonc
-analytics: {
-  enabled: true,                                      // default true
-  providers: {
-    google: {
-      id: 'G-XXXXXXXXXX',                             // Measurement ID — REQUIRED
-    },
-  },
-}
-```
-
-The API secret is read from `process.env.GOOGLE_ANALYTICS_SECRET` — never committed. Mirrors @omega.js/backend's convention.
-
-### Local dev
-
-Add to `.env`:
-
-```bash
-GOOGLE_ANALYTICS_SECRET=your_secret_here
-```
-
-Mint the secret in GA4 Admin → Data Streams → your stream → **Measurement Protocol API secrets**.
-
-### Production builds
-
-The `bundle` task's esbuild `define` bakes `process.env.GOOGLE_ANALYTICS_SECRET` into the bundled main process at build time, so packaged apps don't need `.env` at runtime. The build runs with the secret set (CI does this via the GitHub Actions secret `omega deploy`'s precheck pushes).
-
-## API
-
-```js
-omega.analytics.event('button_click', { button_id: 'cta' });
-omega.analytics.pageview('/settings');
-omega.analytics.screenview('SettingsScreen');
-omega.analytics.setUserProperties({ plan: 'premium', trial: false });
-omega.analytics.setUserId('firebase-uid-abc');   // usually wired automatically
-```
-
-Same surface in renderer:
-
-```js
-window.desktop.analytics.event('button_click', { button_id: 'cta' });
-window.desktop.analytics.pageview('/settings');
-window.desktop.analytics.setUserProperties({ plan: 'premium' });
-const status = await window.desktop.analytics.getStatus();   // { enabled, measurementId, clientId, userId, queueLength }
-```
-
-The renderer surface is fire-and-forget IPC (`ipcRenderer.send`) for events; only `getStatus` round-trips via `invoke`.
-
-## The renderer NEVER sends — it forwards ([#411](https://github.com/Omega-JS-Stack/omega/issues/411))
-
-A renderer's own `omega.analytics.event(...)` (the embedded @omega.js/client, the surface a vert click or a permission prompt fires through) routes to the bridge above and is delivered by the MAIN process's sender. There is exactly one sender per install:
-
-```
-renderer: omega.analytics.event('vert_click', { … })
-  → @omega.js/client reads config.analyticsBridge (src/renderer.js injects the
-    preload's window.desktop.analytics when it boots the client)
-  → ipcRenderer.send('desktop:analytics:event', { name, params })
-  → main: analytics.event(name, params) → catalog → Measurement Protocol
-```
-
-The bridge is **injected, never sniffed**: the client reads that one config key and no global, so a page that merely carries a `window.desktop` can never route a brand's analytics into a void.
-
-Main owns identity end to end: the device id from electron-store, the session id minted once per launch, the real engagement time, and the app's `page_location` / `page_title` (a renderer's `file://` href is not GA's business). Only the canonical name and the caller's params cross.
-
-What does NOT cross the bridge:
-
-- **The fire's `options`** (`{ eventId, providers }`) — they exist to deduplicate a browser pixel against its server-side half, and GA4 through main is the one lane a desktop window has.
-- **The page data** the web path merges in (`page_path` / `page_title` / `page_location`) — main supplies the app's own.
-
-What the bridged client does NOT do: mint a `client_id` of its own (no `localStorage._omega_device_id` in a desktop renderer), hold an api_secret, or fire `login` / `logout` — main's auth bridge already fires those off the same Firebase user, and a second pair would double-count every sign-in.
-
-An uncatalogued event name never leaves the renderer: the catalog check runs before the forward, so a typo throws at the call site in development (and is logged-and-skipped in a packaged app) instead of surfacing as an unattributable warning in main's `runtime.log`. A forward that IPC cannot carry (a non-cloneable param) is warned about, never thrown at the user mid-action.
-
-> 🚫 **Never inject `GOOGLE_ANALYTICS_SECRET` into a renderer's config.** Desktop's config carries the measurement id alone. A renderer with its own secret would become a second Measurement Protocol sender with its own device id and its own session id — one install counted as two GA clients ([#396](https://github.com/Omega-JS-Stack/omega/issues/396) class). The client backs the rule with a guard: a bridged renderer drops any secret handed to it.
-
-## Auto-fired events
-
-| Event | When | Notes |
-|---|---|---|
-| `app_launch` | At end of `analytics.initialize()` (main process) | Fires once per launch |
-| `login` | On `omega.onAuthChange({uid: ...})` transition from null → uid | `params.method = providerId` |
-| `logout` | On `omega.onAuthChange({uid: null})` after a previous uid | — |
-
-## Queueing
-
-Calls before init complete are queued (up to 200 events). On init, the queue is drained. After init, calls send immediately.
-
-## Disabled paths
-
-`analytics._enabled = false` whenever:
-
-- `config.analytics.enabled === false`
-- No measurement ID configured
-- No `GOOGLE_ANALYTICS_SECRET` env var
-
-In all three cases, `event()` is a silent no-op (no throws, no warns past init).
-
-## Event names come from the catalog
-
-`event(name, params)` takes a CANONICAL name from `@omega.js/analytics`' shared
-catalog — the same vocabulary the web pages, the extension and the Cloud
-Functions speak ([docs/shared/analytics.md](../../../docs/shared/analytics.md)).
-The catalog's GA4 mapping decides the native name and payload; this module keeps
-only what is desktop's: the Measurement Protocol transport, the pre-init queue,
-the session/engagement enrichment, and the IPC bridge (unchanged — the preload
-API is byte-compatible).
-
-A name no catalog entry declares is a programmer error: it throws in development
-and is logged-and-skipped in a packaged app, where a throw would take the user's
-action with it. Adding an event is one catalog entry plus its test, never a
-free-typed string here.
-
-## Tests
-
-- `src/test/suites/main/analytics.test.js` — disabled paths, uuidv5 stability, the catalog contract (canonical name in, GA4 descriptor out; unknown names never post), queueing, auth-bridge wiring, IPC handlers, secret-not-leaked guard.
-- `src/test/suites/renderer/analytics-bridge.test.js`: renderer-side surface shape, `getStatus` round-trip, and the #411 pin: a renderer-originated `omega.analytics.event(...)` reaches main's sender exactly once, and the payload GA would receive carries main's `client_id` and main's session id, while the bridged client holds no secret and no device id of its own (the harness hands it credentials on purpose). The harness taps main's transport (`harness/main-entry.js`) so a renderer suite can read back what the sender was handed: a test run never reaches a real GA property. Harness fidelity, stated plainly: it drives the real client and the real IPC channel into the real main-process sender, but the client runs in the preload world holding the bridge object directly, not the contextBridge proxy a page bundle gets, the proxy hop is the one link this pin does not exercise.
-- `packages/client/test/analytics.test.js` — the client half: the bridge is the injected config value alone (a planted `window.desktop` bridges nothing), a bridged client drops credentials and mints no device id, an uncatalogued name never leaves the renderer, and a forward that throws never reaches the caller.

package/docs/app-state.md

@@ -1,92 +0,0 @@
-# App State
-
-Storage-backed launch flags + crash sentinel. Tells you *whether* this is the first launch ever, *how many* times the app has launched, *whether* the previous run crashed, and *whether* the version changed.
-
-## Public API on `omega.appState`
-
-```js
-omega.appState.isFirstLaunch()         // boolean: true ONLY on the very first boot
-omega.appState.getLaunchCount()        // number: total successful launches (including this one)
-omega.appState.getInstalledAt()        // Date: first ever launch timestamp
-omega.appState.getLastLaunchAt()       // Date | null: previous launch (null on first)
-omega.appState.getLastQuitAt()         // Date | null: previous graceful quit; null if it crashed
-omega.appState.recoveredFromCrash()    // boolean: previous run did not exit cleanly
-
-omega.appState.getVersion()            // string | null: package version of this launch
-omega.appState.getPreviousVersion()    // string | null: version before this launch
-omega.appState.wasUpgraded()           // boolean: true if THIS launch's version differs from the prior
-
-omega.appState.launchedAtLogin()       // boolean: OS booted us via openAtLogin
-omega.appState.launchedFromDeepLink()  // boolean: argv had a deep-link payload (set by lib/deep-link)
-
-omega.appState.reset()                 // wipe persisted state (test helper / factory-reset command)
-```
-
-## Storage shape (key `appState`)
-
-```js
-{
-  installedAt:     1700000000000,    // first ever boot timestamp (ms epoch)
-  launchCount:     42,
-  lastLaunchAt:    1700000123456,    // THIS launch's timestamp; previous launch's value exposed via getLastLaunchAt()
-  lastQuitAt:      null,             // null while running; set on graceful quit
-  version:         '1.2.3',
-  previousVersion: '1.2.2',          // preserved across no-change launches (see "Upgrade detection")
-  sentinel:        true              // true while running, cleared on graceful quit
-}
-```
-
-## Crash detection
-
-- On every boot, `appState.initialize()` reads the previous `sentinel` and `lastQuitAt` values BEFORE overwriting them.
-- If `sentinel === true` AND `lastQuitAt === null`, the previous run never made it to `before-quit` / `will-quit` → it crashed. `recoveredFromCrash()` returns `true` for this launch only.
-- First launch is exempt (no prior state to compare).
-- Graceful-quit cleanup is wired up via `app.on('before-quit')` and `app.on('will-quit')`. Both fire under different shutdown paths; either one clears the sentinel and writes `lastQuitAt`.
-
-## Upgrade detection
-
-`wasUpgraded()` is true **only** if THIS launch's version differs from the prior launch's version. Subsequent launches at the same version return `false`, but `getPreviousVersion()` keeps returning the historical value so you can show a "what's new" UI on the second launch too.
-
-```js
-// install 1.0.0
-appState.wasUpgraded()        // false (first launch)
-appState.getPreviousVersion() // null
-
-// upgrade to 1.0.1, launch again
-appState.wasUpgraded()        // true
-appState.getPreviousVersion() // '1.0.0'
-
-// launch again at 1.0.1, no change
-appState.wasUpgraded()        // false
-appState.getPreviousVersion() // '1.0.0' (preserved — useful for "what's new" UIs)
-```
-
-## Common patterns
-
-### Show onboarding on first launch
-
-```js
-if (omega.appState.isFirstLaunch()) {
-  omega.windows.show('onboarding');
-}
-```
-
-### Crash report ping
-
-```js
-if (omega.appState.recoveredFromCrash()) {
-  omega.sentry.captureMessage('recovered from crash', 'warning');
-}
-```
-
-### What's new modal after upgrade
-
-```js
-if (omega.appState.wasUpgraded()) {
-  omega.windows.show('changelog');
-}
-```
-
-## Test helper
-
-`appState.reset()` wipes the persisted state and resets the in-memory snapshot. Useful in test suites and as a real `Settings → Reset to factory defaults` command.

package/docs/audit.md

@@ -1,69 +0,0 @@
-# Audit Workflow
-
-Full-project audit for @omega.js/desktop — runs against a CONSUMER project or the FRAMEWORK repo itself (scope auto-detected). Invoked via the `omega:desktop` skill (`/omega:desktop audit`) or any "audit this app/project" request.
-
-Every check has a stable ID, a severity, and a scope. Findings are reported as `ID @ file:line`, fixed one at a time, then re-verified. The tables below do NOT restate the rules — each check links to the doc that owns the rule and the fix.
-
-## Protocol
-
-1. **Detect scope** — read `package.json`: `name` is `@omega.js/desktop` → **framework audit** (U + @omega.js/desktop + F checks); `@omega.js/desktop` in (dev)dependencies → **consumer audit** (U + @omega.js/desktop checks).
-2. **Run the catalog** — every check matching the scope. Search with Grep/Glob/Read over `src/` (+ `test/`, `config/`, `hooks/`); ALWAYS exclude `dist/`, `release/`, `node_modules/`, `_legacy/`, `_backup/`, `.cache/`. Record each finding as `ID @ file:line` + a one-line description.
-3. **Persist the report** — write the findings list to `.temp/audit/claude-audit.md` (create the dir; add `.temp/` to `.gitignore` if missing) so a long fix loop survives session breaks. Summarize counts by severity in chat.
-4. **Fix loop** — TodoWrite per finding, highest severity first, ONE at a time: mark in-progress → root cause → fix → verify → complete. Ask before structural or destructive fixes (file deletions, lib restructures, config reshapes).
-5. **Re-verify** — re-run every check that produced findings until clean; finish with `npx omega test` (must be green).
-6. **Doc parity** — if fixes changed behavior, update README / the framework guide / `docs/<topic>.md` / CHANGELOG in the same change set.
-
-Severity: **CRIT** security or broken functionality · **HIGH** hard-rule violation · **MED** convention drift · **LOW** optional improvement.
-Scope: **C** consumer · **F** framework repo · **B** both.
-
-## Universal checks (U-xx)
-
-Mirrored across all four OMEGA frameworks (UJM / @omega.js/backend / BXM / @omega.js/desktop) — same ID means the same check everywhere.
-
-| ID | Sev | Scope | Check |
-|----|-----|-------|-------|
-| U-01 | HIGH | B | Every feature has tests at EVERY layer it surfaces (build / main / renderer / boot) — never mocked, real harness only ([test-framework.md](test-framework.md)) |
-| U-02 | HIGH | B | Test hygiene — real-external-API tests gated behind `TEST_EXTENDED_MODE` in-source (not mocked); no tests that assert nothing ([test-framework.md](test-framework.md)) |
-| U-03 | CRIT | B | XSS: renderer DOM sinks escape untrusted values inline via `omega.utilities.escapeHTML(value)` (+ `sanitizeURL` for URL sinks); zero local escape helpers (rules mirror @omega.js/web and @omega.js/extension `docs/xss-prevention.md`; see also DSK-01 for navigation sinks) |
-| U-04 | HIGH | B | @omega.js/client owns Firebase: never `require('firebase')`; renderers use `omega.auth` / `omega.firestore`, main uses `omega.auth` ([common-mistakes.md](common-mistakes.md), [auth.md](auth.md)) |
-| U-05 | HIGH | C | No @omega.js/desktop transitive deps installed in the consumer `package.json` (`firebase`, `@omega.js/client`, `fs-jetpack`, …) — the bundle task's framework-deps hook resolves them ([common-mistakes.md](common-mistakes.md)) |
-| U-06 | HIGH | B | Env behavior gated on the INTENTIONAL check: `isProduction()` or `isDevelopment() \|\| isTesting()`, never `!isDevelopment()`; no ad-hoc `process.env` reads where a helper exists ([environment-detection.md](environment-detection.md)) |
-| U-07 | HIGH | B | Config canon — `config/omega.json5` validates against the schema (boot validator green); canonical cross-framework blocks (`brand`, `app`, `cloud.{provider,config}`, `monitoring`, `analytics`, `payment`) not reinvented ([config-schema.md](config-schema.md)) |
-| U-08 | CRIT | B | No private credentials committed — signing certs (`config/certs/` gitignored), `.env` secrets, tokens, API secret keys ([signing.md](signing.md)). (The Firebase WEB `apiKey` is public by design — do NOT flag it.) |
-| U-09 | HIGH | B | Source discipline — nothing edited in `dist/` or generated files (`dist/electron-builder.yml`, entitlements plist); no live code referencing `_legacy/` / `_backup/` ([build-system.md](build-system.md), [common-mistakes.md](common-mistakes.md)) |
-| U-10 | MED | B | Doc parity — README / the framework guide / `docs/` / CHANGELOG match shipped behavior; the docs index lists every `docs/*.md`; no stale names for renamed commands/patterns |
-| U-11 | MED | B | SSOT/DRY — no duplicated constants/config/logic; one authoritative home per value, imported everywhere else |
-| U-12 | MED | B | JS conventions — file structure, JSDoc, short-circuit returns, leading logical operators, `fs-jetpack`, one `module.exports` per file (global `js:patterns` skill + [the framework guide](../../../docs/desktop/index.md) §File Conventions) |
-| U-13 | MED | B | Dead code & stale patterns — no orphaned `src/` files nothing imports; no unused views/components/integrations; inventory TODO/FIXME (report only) |
-| U-14 | LOW | B | Dependency health — review `npm outdated` / `npm audit`; apply fixes via the `general:update-packages` workflow (includes supply-chain checks) |
-
-## desktop-specific checks
-
-| ID | Sev | Scope | Check |
-|----|-----|-------|-------|
-| DSK-01 | CRIT | B | Zero-trust URLs — every DYNAMIC URL is gated through `sanitize-url.js` before `shell.openExternal` / `BrowserWindow.loadURL` / `window.location.href =` (hardcoded internal-scheme URLs bypass) ([the framework guide](../../../docs/desktop/index.md) §File Conventions, [common-mistakes.md](common-mistakes.md)) |
-| DSK-02 | HIGH | B | Path resolution — `app.getAppPath()` / `utils/app-root.js`, never `process.cwd()`, in runtime code (it's `/` in packaged apps) ([common-mistakes.md](common-mistakes.md)) |
-| DSK-03 | HIGH | C | Windows — every `windows.create()` is `await`ed; the `main` window is ALWAYS created (even hidden launches, with `show: false`) so activate/second-instance can surface UI ([windows.md](windows.md), [common-mistakes.md](common-mistakes.md)) |
-| DSK-04 | HIGH | B | Zero-trust IPC: all channels go through `omega.ipc` (never raw `ipcMain`); handlers validate payload content before acting, especially in apps embedding remote web content ([ipc.md](ipc.md#zero-trust-payloads)) |
-| DSK-05 | MED | C | Icons — one native-size PNG per slot (no `@2x` siblings), macOS tray source named `tray.png` (@omega.js/desktop owns the `Template` rename), no `app.icons` config block ([icons.md](icons.md)) |
-| DSK-06 | HIGH | C | File-based integrations — tray/menu/context-menu logic lives in `src/integrations/<name>/index.js`, never expressed in config JSON ([tray.md](tray.md), [menu.md](menu.md), [context-menu.md](context-menu.md)) |
-| DSK-07 | HIGH | B | Presence-driven feature flags — credentials enable features (`monitoring.providers.sentry.dsn`, `analytics.providers.google.id`, `cloud.config`); no invented `enabled:` toggles ([config-schema.md](config-schema.md)) |
-| DSK-08 | MED | B | Accessibility basics in renderer views — meaningful `alt` text, labeled form fields, real `<button>`/`<a>` elements (no clickable `div`s) |
-
-## Framework-repo checks (F-xx)
-
-Only when auditing the @omega.js/desktop repo itself. Mirrored across the four frameworks.
-
-| ID | Sev | Check |
-|----|-----|-------|
-| F-01 | MED | Sister parity — mirrored sections (config shapes, test contract, guide skeleton, shared env/test conventions) in sync with UJM / @omega.js/backend / BXM; deviations are deliberate and documented |
-| F-02 | HIGH | Consumer-shipped defaults in sync — what `ensureTarget()` scaffolds (`src/defaults/`, every verb) matches current conventions and docs |
-| F-03 | MED | Docs completeness — every `docs/*.md` indexed in the framework guide; every lib module has a doc; no "(planned)" links for things that have shipped |
-| F-04 | HIGH | `npx omega test mgr:` green before treating the audit as complete |
-
-## See also
-
-- [common-mistakes.md](common-mistakes.md) — the canonical anti-pattern list behind several checks
-- [ipc.md](ipc.md#zero-trust-payloads) — the payload rules behind DSK-04
-- [config-schema.md](config-schema.md) — the validator behind U-07 / DSK-07
-- [test-framework.md](test-framework.md) — the layers behind U-01 / U-02

package/docs/auth.md

@@ -1,284 +0,0 @@
-# Auth: `omega.auth` and the state sync
-
-@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
-
-In Electron, you can't just initialize Firebase in the renderer and forget about it:
-
-- Multiple renderer windows would each have their own Firebase instance with no coordination.
-- Main-process code (tray, menu, deep-link routes) needs to know who's signed in.
-- A deep-link auth-token (`myapp://auth/token?token=...`) arrives in main, but the user's UI lives in the renderer — somebody has to bridge them.
-
-The bridge handles all three.
-
-## How it works
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  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                 │
-│  - Broadcasts desktop:auth:* IPC to all renderers on changes     │
-└─────────────────────────────────────────────────────────────┘
-              ▲                     │ broadcasts
-              │ sync-request        ▼
-┌──────────────────────────┐  ┌──────────────────────────┐
-│  RENDERER (window 1)     │  │  RENDERER (window 2)     │
-│  @omega.js/client + Firebase  │  │  @omega.js/client + Firebase  │
-└──────────────────────────┘  └──────────────────────────┘
-```
-
-### Auth flow: deep-link → all processes signed in
-
-**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. 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.
-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
-
-When a renderer window opens (cold or warm), it asks main for the current state:
-
-1. Renderer sends `desktop:auth:sync-request` IPC with its current UID (or null).
-2. Main compares with its own UID:
-   - **Same UID** → no sync needed, returns `{ needsSync: false }`.
-   - **Main signed out, renderer signed in** → returns `{ needsSync: true, signOut: true }`. Renderer signs out.
-   - **Main signed in, renderer not (or different user)** → main fetches a fresh custom token from `POST ${apiUrl}/omega/user/token` (responds `{ token }`) and returns `{ needsSync: true, customToken, user }`. Renderer signs in with that token.
-
-### Sign-out flow
-
-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, on that broadcast alone (the clicked window included), so nothing signs out twice.
-
-## Public API
-
-### Main process (`omega.auth`)
-
-```js
-// 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
-
-// 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 omega.auth.getIdToken();
-
-// 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 main out and broadcast the sign-out to every renderer.
-await omega.auth.signOut();
-```
-
-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
-// 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 through main (broadcasts to every renderer). omega.auth.signOut()
-// signs out this renderer alone.
-await omega.signOut();
-```
-
-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).
-- 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.
-
-## Session persistence (main)
-
-Renderers persist their Firebase sessions in IndexedDB for free (browser contexts).
-Main is Node — Firebase defaults to in-memory there — so @omega.js/desktop plugs in its own vault:
-**`lib/auth-persistence.js`**, a PLUGGABLE strategy behind a custom Firebase
-`Persistence` (the `getReactNativePersistence()` shape).
-
-- **`safeStorage`** (default) — values encrypted via Electron `safeStorage` (macOS
-  Keychain / Windows DPAPI / kwallet-gnome) before touching disk
-  (`{userData}/omega-auth-session.json` holds base64 ciphertext only). This is the same
-  os_crypt machinery Chromium uses for its cookie jar — stronger than browser
-  IndexedDB/localStorage, which are plaintext LevelDB on disk.
-- **`none`** — explicit opt-out (in-memory, pre-1.12 behavior).
-- **Custom** — `require('@omega.js/desktop/lib/auth-persistence').register(name, { available, getItem, setItem, removeItem })` before `initialize()`, then select it via config.
-
-```jsonc
-{
-  "omega": {
-    "authPersistence": "safeStorage"   // 'safeStorage' (default) | 'none' | custom name
-  }
-}
-```
-
-A TEST RUN is always `none`, whatever this config says, on the main and boot layers
-alike: the harness never signs a real user in, so it never asks the OS keychain
-([#907](https://github.com/Omega-JS-Stack/omega/issues/907), the mechanics in
-[test-framework.md](test-framework.md)).
-
-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 it.
-
-## Config
-
-```jsonc
-{
-  "cloud": {
-    "provider": "firebase",
-    "config": {
-      "apiKey":            "...",
-      "authDomain":        "myapp.com",
-      "projectId":         "myapp",
-      // ... etc.
-    }
-  }
-}
-```
-
-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.
-
-If you're building a no-auth Electron app, just leave `cloud.config` empty — the bridge is a clean no-op.
-
-In a TESTING run (`OMEGA_ENVIRONMENT=testing`) the bridge connects its auth instance to the local auth emulator, on the port it reads in three steps: `OMEGA_AUTH_PORT` when the CLI that booted the stack published one, then the `dev.ports.auth` value the bundle baked into `OMEGA_BUILD_JSON` (a packaged main process has no parent env, [#745](https://github.com/Omega-JS-Stack/omega/issues/745)), then the classic `9099`. Same chain `getApiUrl()` walks ([environment-detection.md](environment-detection.md)) and the same move it makes when it maps testing to localhost, and the same one @omega.js/extension's background worker makes for its emulator runs; development and production are untouched.
-
-## Common patterns
-
-### Refresh tray when auth state changes
-
-```js
-// 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/integrations/tray/index.js:
-tray.item({
-  label: () => {
-    const { user } = omega.auth;
-    return user.authenticated ? `Signed in as ${user.email}` : 'Sign in';
-  },
-  click: () => {
-    if (omega.auth.user.authenticated) {
-      omega.auth.signOut();
-    } else {
-      omega.openAuthFlow();
-    }
-  },
-});
-```
-
-### Gate a deep-link route on auth
-
-```js
-omega.deepLink.on('user/profile/:id', (ctx) => {
-  if (!omega.auth.user.authenticated) {
-    omega.openAuthFlow();
-    ctx.handled = true;
-    return;
-  }
-  omega.windows.show('main');
-  omega.windows.get('main').webContents.send('navigate', { to: `/profile/${ctx.params.id}` });
-});
-```
-
-### Sign-out button in a renderer
-
-```html
-<button id="signout">Sign out</button>
-<script>
-  document.getElementById('signout').addEventListener('click', async () => {
-    await omega.signOut();   // goes through main, propagates everywhere
-  });
-</script>
-```
-
-## IPC channels
-
-| 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." 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). |
-
-## Testing
-
-### Unit tests (always run)
-
-`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)
-
-`npm run test:e2e-desktop` ([scripts/e2e-desktop-auth.js](../../../scripts/e2e-desktop-auth.js)) boots a real Electron app against the backend emulator and delivers `<brand.id>://auth/token` from a SECOND instance — the OS-forwarded argv path — then asserts main AND the renderer both land on the emulator user. Offline; it is the lane that proves this whole chain end to end.
-
-### Extended tests (skip without the opt-in)
-
-`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. 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: 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.