@omega.js/desktop 0.51.0 → 0.53.0

package/docs/test-framework.md

@@ -4,16 +4,16 @@ Built-in test framework for both @omega.js/desktop itself and consumer projects.
 
 ## 🚫 NEVER mock — test against the real harness (HARD RULE)
 
-**Do NOT hand-roll fake/stub/mock objects** — no `mockManager`, fake `ipc`/`storage`/`window`/`tray`, stubbed `app`/`BrowserWindow`, or fake IPC channels. Every test gets the **real** framework context:
+**Do NOT hand-roll fake/stub/mock objects**: no mock `omega`, fake `ipc`/`storage`/`window`/`tray`, stubbed `app`/`BrowserWindow`, or fake IPC channels. Every test gets the **real** framework context:
 
 - `build` runs real @omega.js/desktop helper code in plain Node.
-- `main` / `renderer` / `boot` run inside a **real spawned Electron process**, where `ctx.manager` (and boot's `inspect({ manager })`) is the **real booted Manager** — real `manager.storage`, `manager.ipc`, `manager.tray`, `manager.windows`, etc. Use them; exercise the code the way production does.
+- `main` / `renderer` / `boot` run inside a **real spawned Electron process**, where `ctx.omega` (and boot's `inspect({ omega })`) is the **real booted main-process instance**: real `omega.storage`, `omega.ipc`, `omega.tray`, `omega.windows`, etc. Use them; exercise the code the way production does.
 
 **Pure functions are the ONLY exception.** A function with zero I/O (config-defaults merge, icon-path resolver, schema validator, CLI alias resolver, a string/number transform) can be `require()`d and called directly with plain inputs — that's not mocking, there's nothing to mock. The moment a function touches `app.*` / `BrowserWindow` / `ipcMain` / `Tray` / the real bundle / an external service, it MUST run against the real harness in the appropriate layer (`main` / `renderer` / `boot`), not a stub.
 
 **Real external APIs are gated behind extended mode (`TEST_EXTENDED_MODE`), NOT mocked** (see [Extended vs normal mode](#extended-vs-normal-mode) below). Normal mode skips them *in the source*; extended mode runs them for real. The test never fakes them. **Anything an extended test creates in a real external system MUST be cleaned up** by the test (via the suite's `cleanup(ctx)` hook) — external systems are not reset between runs.
 
-If you find yourself writing `const mockX = {...}` to satisfy code under test, STOP — pass the real `ctx.manager` (or its real sub-object), or, if the function is genuinely pure, call it directly with plain data.
+If you find yourself writing `const mockX = {...}` to satisfy code under test, STOP: pass the real `ctx.omega` (or its real sub-object), or, if the function is genuinely pure, call it directly with plain data.
 
 ### The ONLY two exceptions where a narrow stub is allowed
 
@@ -30,7 +30,7 @@ A feature is not done when it works — it's done when every surface it exposes
 
 | Coverage | Layer | Proves |
 |---|---|---|
-| **Logic** | `build` / `main` | The feature's functions do the right thing when called directly (real Manager, real storage, real IPC) |
+| **Logic** | `build` / `main` | The feature's functions do the right thing when called directly (the real booted `omega`, real storage, real IPC) |
 | **UI** | `renderer` | The feature's interface is WIRED — a real event on the real DOM triggers the behavior and the visible result appears |
 | **End-to-end** | `boot` | The feature survives in the consumer's actual built bundle (extend the boot suite's `inspect` assertions) |
 
@@ -85,7 +85,7 @@ TEST_EXTENDED_MODE=true npx omega test build/config
 
 The target matches against the test file path. The source prefix scopes selection to framework-only or project-only tests — a prefixed target excludes the other source entirely:
 
-- `mgr:` — the **universal cross-framework alias** for "the manager's own tests" (framework-only). Works identically in @omega.js/desktop, BXM, UJM, and @omega.js/backend.
+- `mgr:`: the **universal cross-framework alias** for "the framework's own tests" (framework-only). Works identically in @omega.js/desktop, @omega.js/extension, @omega.js/web, and @omega.js/backend.
 - `desktop:` / `framework:` — desktop-specific aliases for framework-only tests, equivalent to `mgr:`.
 - `project:` — consumer project tests only.
 
@@ -111,20 +111,20 @@ Anything an extended suite creates externally must be torn down in its `cleanup(
 
 ### `OMEGA_ENVIRONMENT=testing`, the one input a test run names
 
-Both @omega.js/desktop test runners (`runners/electron.js`, `runners/boot.js`) spawn their child with `OMEGA_ENVIRONMENT=testing`, the ONE environment input ([#817](https://github.com/Omega-JS-Stack/omega/issues/817)), and nothing writes over an explicit one: the word a build baked into the artifact is the fallback for a packaged app, never an override ([#925](https://github.com/Omega-JS-Stack/omega/issues/925)). That powers `manager.isTesting()` (and the `Manager.isTesting()` static), the cross-context helper everything in @omega.js/desktop checks when it needs to behave differently in tests:
+Both @omega.js/desktop test runners (`runners/electron.js`, `runners/boot.js`) spawn their child with `OMEGA_ENVIRONMENT=testing`, the ONE environment input ([#817](https://github.com/Omega-JS-Stack/omega/issues/817)), and nothing writes over an explicit one: the word a build baked into the artifact is the fallback for a packaged app, never an override ([#925](https://github.com/Omega-JS-Stack/omega/issues/925)). That powers `omega.isTesting()` (and the build module's `isTesting()`), the cross-context helper everything in @omega.js/desktop checks when it needs to behave differently in tests:
 
 - `auto-updater` flips its idle threshold from 15min → 3s and its periodic tick from 60s → 500ms, AND short-circuits the native install-prompt dialog (so tests don't pop modal windows).
 - **Every BrowserWindow surfaces stealth** — named windows via `window-manager._surface()` AND raw `new BrowserWindow()` ones (e.g. a consumer's automation popup) via a global `browser-window-created` hook registered in `main.js` step 1a-ii. The shared recipe lives in `src/utils/stealth-window.js`: shown INACTIVE (keyboard focus never leaves your editor), opacity 0, click-through (`setIgnoreMouseEvents`), and raw windows get `show()` rerouted to `showInactive()` + `focus()` no-op'd — a test run never interrupts you, and a stray real click physically can't land in the app, while synthetic test input (`executeJavaScript`, `sendInputEvent`, CDP) is unaffected. **`webContents.focus()` is suppressed separately** (a global `web-contents-created` hook in the same main.js block): it bypasses the window-level patches — it's a different object whose `focus()` reaches the native window directly and makes the invisible window KEY, grabbing the keyboard mid-typing even under the accessory policy (which only prevents *launch* activation, not key-window steals). Consumers call it legitimately (e.g. address-bar focus on tab select), so it's no-op'd per-contents under the same predicate. Set **`OMEGA_TEST_SHOW=1`** to surface windows normally and watch a run live (the predicate is evaluated per window, so flipping it mid-run works). Deliberately NOT `hide()`/`minimize()`: occluded windows get throttled by Chromium (`requestAnimationFrame` pauses, `document.visibilityState` flips to `hidden`) — tests would exercise a DIFFERENT runtime, whereas an opacity-0 shown-inactive window renders and behaves identically to a visible one. See [windows.md](windows.md).
 - **App-level activation is suppressed too (macOS).** Launching a regular-policy app activates it — the menu bar and keyboard focus switch to the test process at launch even though every window surfaces inactive. Under the same stealth predicate (`src/utils/test-stealth.js` — Testing mode + `OMEGA_TEST_SHOW` unset), `main.js` (step 1a, before app ready) and the spawned test harness flip the app to the **accessory activation policy** (`app.dock.hide()` — the same switch `LSUIElement` bakes for packaged hidden-mode apps): the process never activates, never shows a dock icon, and never steals focus, while windows still render identically. `OMEGA_TEST_SHOW=1` restores normal activation along with visible windows. Verified by frontmost-app sampling across a full run: zero focus changes (previously four steals per run).
 - `main.js#initialize` isolates userData per environment: testing runs get `<userData> (Testing)` — **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). Dev runs get ` (Development)`; production is untouched. See [boot-sequence.md](boot-sequence.md).
 - **The main-layer harness exposes a CDP endpoint.** `test/harness/main-entry.js` appends `--remote-debugging-port=0` at require time (loopback-only, OS-assigned port) and publishes the resolved port as **`process.env.OMEGA_CDP_PORT`** before suites run (read from Chromium's `DevToolsActivePort` file; any value inherited from your shell is overwritten — that one points at your dev app, not the harness). Consumer suites can drive real browser automation against the harness Electron itself, e.g. `playwright-core`'s `connectOverCDP('http://127.0.0.1:' + process.env.OMEGA_CDP_PORT)`. Covered by `suites/main/harness-cdp.test.js`.
-- Other lib code can branch on `manager.isTesting()` to suppress dock bounce, login-item changes, OS protocol-handler registration, etc.
+- Other lib code can branch on `omega.isTesting()` to suppress dock bounce, login-item changes, OS protocol-handler registration, etc.
 
 Consumers writing their own tests name the same input in their own runner, for example in `package.json`:
 ```json
 "test": "OMEGA_ENVIRONMENT=testing vitest"
 ```
-Then in your code, gate test-only behavior on `manager.isTesting()` instead of inventing yet another env var.
+Then in your code, gate test-only behavior on `omega.isTesting()` instead of inventing yet another env var.
 
 ## Test discovery
 
@@ -170,14 +170,14 @@ module.exports = {
   layer: 'main',                    // 'build' | 'main' | 'renderer'
   description: 'storage (main)',
   cleanup: async (ctx) => {         // runs after the last test
-    ctx.manager.storage.clear();
+    ctx.omega.storage.clear();
   },
   tests: [
     {
       name: 'set + get round-trip',
       run: (ctx) => {
-        ctx.manager.storage.set('hello', 'world');
-        ctx.expect(ctx.manager.storage.get('hello')).toBe('world');
+        ctx.omega.storage.set('hello', 'world');
+        ctx.expect(ctx.omega.storage.get('hello')).toBe('world');
       },
     },
     {
@@ -232,7 +232,7 @@ module.exports = [
 | Layer | Where it runs | Use for |
 |---|---|---|
 | `build` | Plain Node | CLI, package.json, config schema, gulp tasks |
-| `main` | Spawned Electron main process | Manager init, lib modules, IPC, windows |
+| `main` | Spawned Electron main process | `omega.initialize()`, lib modules, IPC, windows |
 | `renderer` | Hidden BrowserWindow: the framework's harness page by default, one of the project's own `src/views/` when the suite declares `view: '<name>'` | `window.desktop.*`, preload bridge, UI logic, your own views |
 
 The runner partitions test files by layer at discovery time. The build layer runs inline; the main layer spawns Electron once with all main suites and parses JSON-line stdout.
@@ -246,7 +246,7 @@ ctx.expect(actual)          // Jest-compatible expect()
 ctx.state                   // shared object across tests in a suite/group
 ctx.layer                   // 'build' | 'main' | 'renderer'
 ctx.skip(reason)            // skip from inside the test
-ctx.manager                 // (main layer only) the booted @omega.js/desktop Manager
+ctx.omega                 // (main layer only) the booted @omega.js/desktop main-process instance
 ```
 
 ## expect() matchers
@@ -290,15 +290,15 @@ All test output is also teed (ANSI-stripped) to `<projectRoot>/logs/test.log`, t
 ## Test harness internals (main layer)
 
 - `runners/electron.js` spawns Electron with `harness/main-entry.js` as the app.
-- `harness/main-entry.js` boots Manager with `skipWindowCreation: true`, runs the suites, emits results via `__EM_TEST__{json}\n` lines on stdout.
+- `harness/main-entry.js` boots `omega` with `skipWindowCreation: true`, runs the suites, emits results via `__OMEGA_TEST__{json}\n` lines on stdout (`TEST_EVENT_PREFIX`, [src/utils/test-events.js](../src/utils/test-events.js), the one prefix every harness writes and every runner reads).
 - The runner parses those lines and renders @omega.js/backend-style output.
 - stderr is always drained (otherwise the pipe fills and the harness blocks); printed only when `OMEGA_TEST_DEBUG=1`.
 - `ELECTRON_RUN_AS_NODE` is stripped from the spawn env (would otherwise make Electron behave as Node and break the harness).
-- **Consumer-scheme containment.** The consumer's `main.js` — where the real `protocol.handle('<brand.id>', …)` lives — never runs in this harness, so `brand://` URLs loaded by main-layer suites would be UNHANDLED. Chromium treats a load on an unhandled scheme as an *external protocol* and hands it to the OS — and if an installed copy of the app owns the scheme (e.g. `/Applications/Brand.app` on macOS, registered via its `Info.plist`), Launch Services launches the installed production app mid-test-run. The harness contains this two ways after Manager boots: (1) it registers a stub handler for the consumer's brand scheme (read from `<cwd>/config/omega.json5`) on the default session, so `brand://` loads commit in-process as a blank page; (2) it denies the `openExternal` permission on the default session and every session created after it (partitions included), so no navigation can hand ANY scheme to the OS during a test run. Suites that need real page content for `brand://` URLs belong in the boot layer, where the real app (and its real protocol handler) runs. A main-layer suite that genuinely needs its OWN handler for the brand scheme must call `protocol.unhandle(brand.id)` first — the harness stub holds the scheme on the default session.
+- **Consumer-scheme containment.** The consumer's `main.js` (where the real `protocol.handle('<brand.id>', …)` lives) never runs in this harness, so `brand://` URLs loaded by main-layer suites would be UNHANDLED. Chromium treats a load on an unhandled scheme as an *external protocol* and hands it to the OS: and if an installed copy of the app owns the scheme (e.g. `/Applications/Brand.app` on macOS, registered via its `Info.plist`), Launch Services launches the installed production app mid-test-run. The harness contains this two ways after `omega` boots: (1) it registers a stub handler for the consumer's brand scheme (read from `<cwd>/config/omega.json5`) on the default session, so `brand://` loads commit in-process as a blank page; (2) it denies the `openExternal` permission on the default session and every session created after it (partitions included), so no navigation can hand ANY scheme to the OS during a test run. Suites that need real page content for `brand://` URLs belong in the boot layer, where the real app (and its real protocol handler) runs. A main-layer suite that genuinely needs its OWN handler for the brand scheme must call `protocol.unhandle(brand.id)` first: the harness stub holds the scheme on the default session.
 
 ## A test run never touches the OS keychain, and a blocked boot reports
 
-The harness resolves auth persistence to the **`none`** strategy on every layer, main and boot alike, before any config is read: a brand that declares `omega.authPersistence: 'safeStorage'` still runs its tests with Firebase auth in memory, because the lanes never sign a real user in. That is a hard rule, not a nicety. The boot lane spawns the raw, unsigned `Electron` binary, which carries no keychain ACL, so one `safeStorage` read parks the entire run behind a macOS SecurityAgent prompt ([#907](https://github.com/Omega-JS-Stack/omega/issues/907)). ONE signal answers "is this a test run" on both layers, `manager.isTesting()`: the boot lane boots the consumer's PRODUCTION artifact, and the word baked into it no longer writes over the `OMEGA_ENVIRONMENT=testing` the runner spawned it with ([#925](https://github.com/Omega-JS-Stack/omega/issues/925)), so the booted app reports the lane it is running in. And since a boot can block long before `main.js` requires the harness (where the per-test timeout lives), the boot runner carries its own budget, measured as SILENCE: every harness line rearms it, so a suite that legitimately runs longer keeps going, and a boot that produces no harness output for 60s (`OMEGA_TEST_BOOT_TIMEOUT_MS` overrides) counts its tests failed, prints `✗ boot: no harness output after 60s; last runtime.log line: "<line>"` from the booted app's `logs/runtime.log`, and ends the child instead of hanging `npx omega test`.
+The harness resolves auth persistence to the **`none`** strategy on every layer, main and boot alike, before any config is read: a brand that declares `omega.authPersistence: 'safeStorage'` still runs its tests with Firebase auth in memory, because the lanes never sign a real user in. That is a hard rule, not a nicety. The boot lane spawns the raw, unsigned `Electron` binary, which carries no keychain ACL, so one `safeStorage` read parks the entire run behind a macOS SecurityAgent prompt ([#907](https://github.com/Omega-JS-Stack/omega/issues/907)). ONE signal answers "is this a test run" on both layers, `omega.isTesting()`: the boot lane boots the consumer's PRODUCTION artifact, and the word baked into it no longer writes over the `OMEGA_ENVIRONMENT=testing` the runner spawned it with ([#925](https://github.com/Omega-JS-Stack/omega/issues/925)), so the booted app reports the lane it is running in. And since a boot can block long before `main.js` requires the harness (where the per-test timeout lives), the boot runner carries its own budget, measured as SILENCE: every harness line rearms it, so a suite that legitimately runs longer keeps going, and a boot that produces no harness output for 60s (`OMEGA_TEST_BOOT_TIMEOUT_MS` overrides) counts its tests failed, prints `✗ boot: no harness output after 60s; last runtime.log line: "<line>"` from the booted app's `logs/runtime.log`, and ends the child instead of hanging `npx omega test`.
 
 ## Writing consumer tests
 
@@ -314,7 +314,7 @@ module.exports = {
     {
       name: 'storage starts empty',
       run: (ctx) => {
-        ctx.expect(ctx.manager.storage.get('user')).toBeUndefined();
+        ctx.expect(ctx.omega.storage.get('user')).toBeUndefined();
       },
     },
   ],

package/docs/themes.md

@@ -87,13 +87,13 @@ theme: {
 }
 ```
 
-## Appearance (light / dark / system) — `manager.theme`
+## Appearance (light / dark / system): `omega.theme`
 
 @omega.js/desktop owns appearance at runtime. `config.theme.appearance` is only the **app default**; the resolved appearance is applied and kept live by the theme lib:
 
 - **`'system'` (default)** follows the OS preference **live** — when the OS flips, every page updates without a reload or restart.
 - **`'light'` / `'dark'`** are explicit overrides.
-- A user's runtime choice (`manager.theme.set(...)`) is **persisted in `manager.storage`** (`theme.appearance`) and wins over the config default on every boot.
+- A user's runtime choice (`omega.theme.set(...)`) is **persisted in `omega.storage`** (`theme.appearance`) and wins over the config default on every boot.
 
 ### How it propagates
 
@@ -105,10 +105,10 @@ The applier is **opt-in by presence**: it only manages pages whose `<html>` alre
 
 ```js
 // Main
-manager.theme.get();          // 'system' | 'light' | 'dark'  (the chosen source)
-manager.theme.resolved();     // 'light' | 'dark'             (what's showing)
-manager.theme.set('dark');    // apply + persist (throws on invalid values)
-const unsub = manager.theme.onChange(({ source, resolved }) => { ... });
+omega.theme.get();          // 'system' | 'light' | 'dark'  (the chosen source)
+omega.theme.resolved();     // 'light' | 'dark'             (what's showing)
+omega.theme.set('dark');    // apply + persist (throws on invalid values)
+const unsub = omega.theme.onChange(({ source, resolved }) => { ... });
 
 // Renderer (any page with the @omega.js/desktop preload)
 await window.desktop.theme.get();        // { source, resolved }
@@ -120,7 +120,7 @@ Main also broadcasts `desktop:theme:changed { source, resolved }` to BrowserWind
 
 ### Declarative controls
 
-Any element with `data-omega-theme-set` becomes a theme switch (wired by the renderer Manager's initialize — event-delegated, so late-rendered controls work):
+Any element with `data-omega-theme-set` becomes a theme switch (wired by the renderer's `omega.initialize()`, event-delegated, so late-rendered controls work):
 
 ```html
 <button data-omega-theme-set="light">Day</button>

package/docs/tooltips.md

@@ -52,7 +52,7 @@ control and put the tooltip on the wrapper:
 ## The rest of Bootstrap's JS
 
 The full namespace is exposed at **`window.bootstrap`** (and
-`manager.bootstrap`) — `Tooltip`, `Popover`, `Collapse`, `Dropdown`, `Modal`,
+`omega.bootstrap`): `Tooltip`, `Popover`, `Collapse`, `Dropdown`, `Modal`,
 `Offcanvas`, `Tab`, `Toast`, `Alert`, `Button`, `Carousel`, `ScrollSpy`. Only
 tooltips are auto-initialized; the other components' standard **data-api**
 works out of the box on plain Bootstrap markup (e.g.
@@ -94,6 +94,6 @@ runs from a preload, e.g. the test harness).
 
 - `src/test/suites/renderer/tooltips.test.js` — bundle loads, auto-init on
   insertion, live retitle, dispose-on-removal, tip cleanup. (The harness wires
-  the renderer Manager in the preload world — see the suite header for the
+  the renderer instance in the preload world: see the suite header for the
   world-split notes; single-world hover behavior is covered by consumer boot
   suites.)

package/docs/tray.md

@@ -4,19 +4,19 @@ File-based tray/menubar. @omega.js/desktop looks for `src/integrations/tray/inde
 
 ## Config
 
-No config block. Path is conventional: `src/integrations/tray/index.js`. To opt out, call `manager.tray.disable()` from your main entry — idempotent, tears down any existing Tray.
+No config block. Path is conventional: `src/integrations/tray/index.js`. To opt out, call `omega.tray.disable()` from your main entry: idempotent, tears down any existing Tray.
 
 ## Definition file
 
 ```js
 // src/integrations/tray/index.js
-module.exports = ({ manager, tray }) => {
+module.exports = ({ omega, tray }) => {
   // @omega.js/desktop auto-resolves the tray icon from config/icons/<platform>/tray.png at build
   // time, so explicit tray.icon() is OPTIONAL. Call it only to override.
   // Note: on macOS, if you pass your own path, the filename MUST end in
   // `Template.png` for the OS to auto-invert it in dark mode.
   // tray.icon('src/assets/icons/my-trayTemplate.png');
-  tray.tooltip(manager.config?.app?.productName);
+  tray.tooltip(omega.config?.app?.productName);
 
   // Easiest: start from @omega.js/desktop's default template.
   tray.useDefaults();
@@ -25,7 +25,7 @@ module.exports = ({ manager, tray }) => {
   tray.insertAfter('open', {
     id: 'dashboard',
     label: 'Open Dashboard',
-    click: () => manager.windows.show('dashboard'),
+    click: () => omega.windows.show('dashboard'),
   });
   tray.update('open', { label: 'Show Window' });
   tray.remove('website');
@@ -47,7 +47,7 @@ tray.clear()                   // start over
 
 ## Id-path API
 
-Same shape across menu / tray / context-menu. Available **during definition** (on the `tray` builder arg) AND **at runtime** on `manager.tray`:
+Same shape across menu / tray / context-menu. Available **during definition** (on the `tray` builder arg) AND **at runtime** on `omega.tray`:
 
 ```js
 .find(idPath)                  // live descriptor or null
@@ -69,8 +69,8 @@ Tray ids are **flat** — no `tray/` prefix (the lib namespace is implicit). For
 | ID | Item |
 |---|---|
 | `title` | Disabled label showing the app name |
-| `open` | "Open `<app>`" — calls `manager.windows.show('main')` |
-| `check-for-updates` | Wired to `manager.autoUpdater` (label updates dynamically) |
+| `open` | "Open `<app>`": calls `omega.windows.show('main')` |
+| `check-for-updates` | Wired to `omega.autoUpdater` (label updates dynamically) |
 | `website` | Visit `brand.url` (only present if configured) |
 | `quit` | Quit the app |
 
@@ -84,9 +84,9 @@ tray.item({ id: 'account', label: 'Account', submenu: [
   { id: 'sign-out', label: 'Sign out', click: () => {} },
 ]});
 
-manager.tray.find('account/sign-out');
-manager.tray.update('account/sign-out', { enabled: false });
-manager.tray.appendTo('account', { id: 'profile', label: 'Profile' });
+omega.tray.find('account/sign-out');
+omega.tray.update('account/sign-out', { enabled: false });
+omega.tray.appendTo('account', { id: 'profile', label: 'Profile' });
 ```
 
 ## Item descriptors
@@ -103,30 +103,30 @@ Mirror Electron's [`MenuItemConstructorOptions`](https://www.electronjs.org/docs
 | `click` | function | Wrapped to swallow errors so a bad handler can't kill the menu |
 | `submenu` | array | Recursively resolved with the same conveniences |
 
-## Runtime API on `manager.tray`
+## Runtime API on `omega.tray`
 
 ```js
-manager.tray.refresh()                   // re-evaluate dynamic state and re-render
-manager.tray.define(fn)                  // replace the whole definition at runtime
-manager.tray.disable()                   // tear down + stop responding (idempotent)
-manager.tray.setIcon(path)
-manager.tray.setTooltip(text)
-manager.tray.addItem(descriptor)         // append (preserves existing items)
-manager.tray.clearItems()
-manager.tray.destroy()                   // tear down (mostly for tests)
+omega.tray.refresh()                   // re-evaluate dynamic state and re-render
+omega.tray.define(fn)                  // replace the whole definition at runtime
+omega.tray.disable()                   // tear down + stop responding (idempotent)
+omega.tray.setIcon(path)
+omega.tray.setTooltip(text)
+omega.tray.addItem(descriptor)         // append (preserves existing items)
+omega.tray.clearItems()
+omega.tray.destroy()                   // tear down (mostly for tests)
 
 // Id-path API — same as listed above.
-manager.tray.find('quit')
-manager.tray.update('quit', { label: 'Goodbye' })
-manager.tray.remove('website')
-manager.tray.insertAfter('open', { id: 'preferences', label: 'Preferences...', click: ... })
-manager.tray.hide('check-for-updates')
+omega.tray.find('quit')
+omega.tray.update('quit', { label: 'Goodbye' })
+omega.tray.remove('website')
+omega.tray.insertAfter('open', { id: 'preferences', label: 'Preferences...', click: ... })
+omega.tray.hide('check-for-updates')
 
 // Inspection
-manager.tray.getItems()                  // shallow copy of raw descriptors
-manager.tray.getIcon()
-manager.tray.getTooltip()
-manager.tray.isRendered()
+omega.tray.getItems()                  // shallow copy of raw descriptors
+omega.tray.getIcon()
+omega.tray.getTooltip()
+omega.tray.isRendered()
 ```
 
 ## Common patterns
@@ -135,8 +135,8 @@ manager.tray.isRendered()
 
 ```js
 // in your renderer/main code, after sign-in:
-manager.storage.set('user', { ... });
-manager.tray.refresh();    // dynamic-label functions re-evaluate
+omega.storage.set('user', { ... });
+omega.tray.refresh();    // dynamic-label functions re-evaluate
 ```
 
 ### Hide updater item if you ship without auto-update
@@ -153,7 +153,7 @@ module.exports = ({ tray }) => {
 ### Replace the entire tray at runtime
 
 ```js
-manager.tray.define(({ manager, tray }) => {
+omega.tray.define(({ omega, tray }) => {
   tray.icon('icons/dark-mode.png');
   tray.item({ id: 'x', label: 'New layout', click: ... });
 });

package/docs/usage.md

@@ -1,15 +1,15 @@
 # Usage
 
-Tracks app-launch + hours-of-use stats. Sister of legacy @omega.js/desktop's Usage library, but uses `manager.storage` instead of a separate electron-store.
+Tracks app-launch + hours-of-use stats. Sister of legacy @omega.js/desktop's Usage library, but uses `omega.storage` instead of a separate electron-store.
 
 ## What's tracked
 
 ```js
-manager.usage.opens()              // total app launches
-manager.usage.hoursTotal()         // cumulative hours-of-use across clean exits
-manager.usage.hoursThisSession()   // live, computed from session start
-manager.usage.installedAt()        // ISO timestamp of first launch
-manager.usage.toJSON()             // all of the above as a structured-cloneable object
+omega.usage.opens()              // total app launches
+omega.usage.hoursTotal()         // cumulative hours-of-use across clean exits
+omega.usage.hoursThisSession()   // live, computed from session start
+omega.usage.installedAt()        // ISO timestamp of first launch
+omega.usage.toJSON()             // all of the above as a structured-cloneable object
 ```
 
 ## How it accumulates
@@ -51,7 +51,7 @@ const snap = await window.desktop.usage.get();
 
 ## Why not just use app-state?
 
-`app-state.js` already tracks `launchCount` (= opens). We could fold these in. But `app-state` is concerned with first-launch / crash-sentinel / version-change semantics — `usage` is concerned with telemetry. Keeping them separate keeps each module focused. Both write to disjoint keys in `manager.storage`.
+`app-state.js` already tracks `launchCount` (= opens). We could fold these in. But `app-state` is concerned with first-launch / crash-sentinel / version-change semantics: `usage` is concerned with telemetry. Keeping them separate keeps each module focused. Both write to disjoint keys in `omega.storage`.
 
 ## Tests
 

package/docs/verts.md

@@ -12,7 +12,7 @@ zero consumer JS, same element vocabulary as the web `verts/unit` section and
 
 ## What the wiring does
 
-`renderer.js _wireAds` (runs inside `manager.initialize()`, same liveness
+`renderer.js _wireAds` (runs inside `omega.initialize()`, same liveness
 model as the FontAwesome/tooltip wiring) binds every `[data-omega-vert]`
 element present at init AND inserted later (MutationObserver), marking bound
 hosts `data-omega-vert-bound="house"`. Everything after the bind lives in the

package/docs/windows.md

@@ -1,6 +1,6 @@
 # Windows
 
-**Lazy named-window registry.** @omega.js/desktop does NOT auto-create any window. Your `main.js` calls `manager.windows.create('main', { show: !startup.isLaunchHidden() })` from inside `manager.initialize().then(() => { ... })`. Always create `main` — its presence in the registry is what lets @omega.js/desktop's `app.on('activate')` (macOS dock click) and `app.on('second-instance')` (win/linux re-launch) handlers surface UI when the user double-clicks the running app. In hidden launches, pass `show: false` to keep the window invisible until something explicitly calls `windows.show('main')`. Use the registry for the common case (named, persistent, integrated windows). For one-off windows (a toast, a print preview), use `new BrowserWindow()` directly — `window-manager` doesn't get in the way.
+**Lazy named-window registry.** @omega.js/desktop does NOT auto-create any window. Your `main.js` calls `omega.windows.create('main', { show: !startup.isLaunchHidden() })` from inside `omega.initialize().then(() => { ... })`. Always create `main`: its presence in the registry is what lets @omega.js/desktop's `app.on('activate')` (macOS dock click) and `app.on('second-instance')` (win/linux re-launch) handlers surface UI when the user double-clicks the running app. In hidden launches, pass `show: false` to keep the window invisible until something explicitly calls `windows.show('main')`. Use the registry for the common case (named, persistent, integrated windows). For one-off windows (a toast, a print preview), use `new BrowserWindow()` directly, `window-manager` doesn't get in the way.
 
 ## Re-surface on user re-launch
 
@@ -14,20 +14,20 @@ Both handlers are no-ops if `main` isn't in the registry. So consumers who genui
 ## API
 
 ```js
-await manager.windows.create('main', overrides?)        // canonical entry point
-await manager.windows.createNamed('main', mgr, opts?)   // identical; .create() is sugar
-manager.windows.get('main')                              // BrowserWindow | null
-manager.windows.show('main')                             // show + focus + auto app.dock.show()
-manager.windows.hide('main')
-manager.windows.close('main')                            // force-close (bypasses hideOnClose)
-manager.windows.list()                                   // string[] of currently-open names
+await omega.windows.create('main', overrides?)        // canonical entry point
+await omega.windows.createNamed('main', mgr, opts?)   // identical; .create() is sugar
+omega.windows.get('main')                              // BrowserWindow | null
+omega.windows.show('main')                             // show + focus + auto app.dock.show()
+omega.windows.hide('main')
+omega.windows.close('main')                            // force-close (bypasses hideOnClose)
+omega.windows.list()                                   // string[] of currently-open names
 ```
 
 `create()` is single-instance: a second call with the same name returns the existing window and focuses it (no double-create).
 
 ## Defaults
 
-No JSON config required. @omega.js/desktop bakes in sensible defaults so `manager.windows.create('main')` "just works":
+No JSON config required. @omega.js/desktop bakes in sensible defaults so `omega.windows.create('main')` "just works":
 
 | Window | Defaults |
 |---|---|
@@ -37,8 +37,8 @@ No JSON config required. @omega.js/desktop bakes in sensible defaults so `manage
 Override at the call site:
 
 ```js
-manager.windows.create('main',     { width: 1280, height: 800 });
-manager.windows.create('settings', { width: 600,  height: 480 });
+omega.windows.create('main',     { width: 1280, height: 800 });
+omega.windows.create('settings', { width: 600,  height: 480 });
 ```
 
 ## Config (optional)
@@ -60,7 +60,7 @@ Per-window keys:
 | `view` | `main` | `<name>` | Folder under `src/views/`. Loads `dist/views/<view>/index.html`. |
 | `width` / `height` | 1024 / 720 | 800 / 600 | Initial size (overridden by saved bounds if `persistBounds: true`). |
 | `minWidth` / `minHeight` | 400 / 300 | 400 / 300 | |
-| `show` | `true` | `true` | Auto-show on `ready-to-show`. `false` keeps the window hidden until `manager.windows.show()`. |
+| `show` | `true` | `true` | Auto-show on `ready-to-show`. `false` keeps the window hidden until `omega.windows.show()`. |
 | `hideOnClose` | `true` | `false` | Discord-style: X click hides instead of closes. See "Hide-on-close" below. |
 | `title` | `app.productName` | `app.productName` | Window title. |
 | `backgroundColor` | `#ffffff` | `#ffffff` | Background color before the page loads. |
@@ -96,15 +96,15 @@ The `main` window's X button **hides instead of closes** by default. Real quit o
 - Menu Quit (`main/quit` on mac, `file/quit` on win/linux)
 - Tray Quit (`quit` item)
 - Auto-updater install (`autoUpdater.installNow()`)
-- Programmatic `manager.quit({ force: true })`
+- Programmatic `omega.quit({ force: true })`
 
 The window-manager close handler checks three flags before deciding to swallow vs let through:
 
 | Flag | Set by | Means |
 |---|---|---|
-| `manager._allowQuit` | `manager.quit({ force: true })`, `autoUpdater.installNow()` | Programmatic force — let the close go through. |
-| `manager._isQuitting` | `app.on('before-quit')` (every quit path Electron knows about) | App is quitting — let close events flow naturally. |
-| `win._emForceClose` | `manager.windows.close(name)` | Per-window override. |
+| `omega._allowQuit` | `omega.quit({ force: true })`, `autoUpdater.installNow()` | Programmatic force: let the close go through. |
+| `omega._isQuitting` | `app.on('before-quit')` (every quit path Electron knows about) | App is quitting: let close events flow naturally. |
+| `win._emForceClose` | `omega.windows.close(name)` | Per-window override. |
 
 Other named windows default to `hideOnClose: false` (X actually closes). Override per window via config or call-site overrides.
 
@@ -121,27 +121,27 @@ Every named window's position and size persist to storage on resize / move / max
 
 ## macOS dock auto-show
 
-When `LSUIElement: true` is baked at build time (`startup.mode: 'hidden'`), the app launches with **no dock icon, no Cmd+Tab, no taskbar**. The first time `manager.windows.create()` or `manager.windows.show()` runs, @omega.js/desktop calls `app.dock.show()` automatically — the dock icon appears alongside the window.
+When `LSUIElement: true` is baked at build time (`startup.mode: 'hidden'`), the app launches with **no dock icon, no Cmd+Tab, no taskbar**. The first time `omega.windows.create()` or `omega.windows.show()` runs, @omega.js/desktop calls `app.dock.show()` automatically: the dock icon appears alongside the window.
 
-**And the inverse**: for `startup.mode: 'hidden'` apps, when the LAST visible named window hides (hide-on-close X, `windows.hide()`, any consumer `win.hide()`), @omega.js/desktop calls `app.dock.hide()` again — the app returns to its fully-invisible posture, dock and UI appearing and vanishing together. Normal-mode apps keep their dock icon for life; quit paths are untouched (`manager._isQuitting` guard).
+**And the inverse**: for `startup.mode: 'hidden'` apps, when the LAST visible named window hides (hide-on-close X, `windows.hide()`, any consumer `win.hide()`), @omega.js/desktop calls `app.dock.hide()` again: the app returns to its fully-invisible posture, dock and UI appearing and vanishing together. Normal-mode apps keep their dock icon for life; quit paths are untouched (`omega._isQuitting` guard).
 
 This means agent / menubar apps can stay completely invisible until the user explicitly asks for UI:
 
 ```js
-manager.initialize().then(() => {
+omega.initialize().then(() => {
   // Don't call windows.create() here — app stays invisible.
   // Surface UI later when something warrants it:
-  manager.tray.update('open', { click: () => manager.windows.create('main') });
+  omega.tray.update('open', { click: () => omega.windows.create('main') });
 });
 ```
 
 ## Auto-attach context-menu
 
-Every window created via `manager.windows.create()` is automatically wired up with the consumer's `src/integrations/context-menu/index.js` (see [context-menu.md](context-menu.md)). Idempotent per webContents (uses a WeakSet). For windows you create directly with `new BrowserWindow()`, call `manager.contextMenu.attach(win.webContents)` manually.
+Every window created via `omega.windows.create()` is automatically wired up with the consumer's `src/integrations/context-menu/index.js` (see [context-menu.md](context-menu.md)). Idempotent per webContents (uses a WeakSet). For windows you create directly with `new BrowserWindow()`, call `omega.contextMenu.attach(win.webContents)` manually.
 
 ## Testing mode: stealth surfacing
 
-When `manager.isTesting()` (i.e. under `npx omega test`), every surfacing path in this lib — `ready-to-show`, `windows.show()`, the create-dedup focus — goes **stealth** instead of `win.show()`: `_surface()` applies the shared recipe from `src/utils/stealth-window.js` and surfaces via `showInactive()`, with no `win.focus()`/dock surfacing. **The full stealth story lives in [test-framework.md](test-framework.md) (SSOT)** — the recipe and why it's not `hide()`/`minimize()`, the raw-window `browser-window-created` hook, `webContents.focus()` suppression, macOS app-level activation suppression, and the **`OMEGA_TEST_SHOW=1`** opt-out. Covered by `suites/main/stealth-window.test.js`.
+When `omega.isTesting()` (i.e. under `npx omega test`), every surfacing path in this lib (`ready-to-show`, `windows.show()`, the create-dedup focus) goes **stealth** instead of `win.show()`: `_surface()` applies the shared recipe from `src/utils/stealth-window.js` and surfaces via `showInactive()`, with no `win.focus()`/dock surfacing. **The full stealth story lives in [test-framework.md](test-framework.md) (SSOT)**: the recipe and why it's not `hide()`/`minimize()`, the raw-window `browser-window-created` hook, `webContents.focus()` suppression, macOS app-level activation suppression, and the **`OMEGA_TEST_SHOW=1`** opt-out. Covered by `suites/main/stealth-window.test.js`.
 
 ## Platform behavior
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omega.js/desktop",
-  "version": "0.51.0",
+  "version": "0.53.0",
   "description": "OMEGA desktop framework — build, test, and package Electron apps for macOS, Windows, and Linux",
   "private": false,
   "publishConfig": {
@@ -23,7 +23,6 @@
     "./lib/context-menu": "./dist/lib/context-menu.js",
     "./lib/deep-link": "./dist/lib/deep-link.js",
     "./lib/ipc": "./dist/lib/ipc.js",
-    "./lib/logger": "./dist/lib/logger.js",
     "./lib/logger-lite": "./dist/lib/logger-lite.js",
     "./lib/menu": "./dist/lib/menu.js",
     "./lib/protocol": "./dist/lib/protocol.js",
@@ -33,7 +32,7 @@
     "./lib/storage": "./dist/lib/storage.js",
     "./lib/templating": "./dist/lib/templating.js",
     "./lib/tray": "./dist/lib/tray.js",
-    "./lib/client-bridge": "./dist/lib/client-bridge.js",
+    "./lib/auth": "./dist/lib/auth.js",
     "./lib/window-manager": "./dist/lib/window-manager.js",
     "./cli": "./dist/cli-run.js",
     "./ensure-target": "./dist/commands/lib/ensure-target.js",
@@ -155,7 +154,7 @@
     "@fortawesome/fontawesome-free": "^7.3.0",
     "@inquirer/prompts": "^8.5.2",
     "@octokit/rest": "^22.0.1",
-    "@omega.js/client": "0.51.0",
+    "@omega.js/client": "0.53.0",
     "@popperjs/core": "^2.11.8",
     "@sentry/electron": "^7.13.0",
     "chalk": "^5.6.2",