@omega.js/desktop 0.52.0 → 0.53.0

package/docs/startup.md

@@ -24,7 +24,7 @@ The default behavior — `mode: 'normal'` + `openAtLogin: { enabled: true, mode:
 
 ### `normal` (default)
 
-Standard app behavior. Your `main.js` calls `windows.create('main', { show: !startup.isLaunchHidden() })` from inside `manager.initialize().then(...)`. In `normal` mode, `show` is `true` so the window appears immediately. Dock visible (macOS), taskbar entry (win/linux).
+Standard app behavior. Your `main.js` calls `windows.create('main', { show: !startup.isLaunchHidden() })` from inside `omega.initialize().then(...)`. In `normal` mode, `show` is `true` so the window appears immediately. Dock visible (macOS), taskbar entry (win/linux).
 
 ### `hidden`
 
@@ -38,31 +38,31 @@ Use this for: menubar apps, agent apps (clipboard managers, time trackers, syste
 
 > **Note:** the deprecated `'tray-only'` mode is no longer valid — its behavior was always identical to `'hidden'`, so they've been folded into one. Old `tray-only` configs fall back to `'normal'` per `getMode()` validation.
 
-## Public API on `manager.startup`
+## Public API on `omega.startup`
 
 ```js
-manager.startup.getMode()                  // user-launch mode: 'normal' | 'hidden'
-manager.startup.isLaunchHidden()           // true if THIS launch is hidden — combines
+omega.startup.getMode()                  // user-launch mode: 'normal' | 'hidden'
+omega.startup.isLaunchHidden()           // true if THIS launch is hidden: combines
                                            //   user-launch mode + login-launch detection.
                                            //   Use this in main.js to gate windows.create().
-manager.startup.wasLaunchedAtLogin()       // true if the OS auto-launched us at login
-manager.startup.applyEarly()               // calls app.dock.hide() if needed (called by main.js boot)
+omega.startup.wasLaunchedAtLogin()       // true if the OS auto-launched us at login
+omega.startup.applyEarly()               // calls app.dock.hide() if needed (called by main.js boot)
 
-manager.startup.setOpenAtLogin(true)                            // back-compat boolean form
-manager.startup.setOpenAtLogin({ enabled: true, mode: 'hidden' }) // object form
-manager.startup.isOpenAtLogin()            // read live OS state
+omega.startup.setOpenAtLogin(true)                            // back-compat boolean form
+omega.startup.setOpenAtLogin({ enabled: true, mode: 'hidden' }) // object form
+omega.startup.isOpenAtLogin()            // read live OS state
 ```
 
 ## Typical main.js pattern
 
 ```js
-manager.initialize().then(() => {
+omega.initialize().then(() => {
   // Always create the main window. In hidden launches, `show: false` keeps it
   // invisible until something explicitly calls windows.show('main') — but it's
   // in the registry, so @omega.js/desktop's activate/second-instance handlers can find and
   // surface it when the user double-clicks the running app.
-  manager.windows.create('main', {
-    show: !manager.startup.isLaunchHidden(),
+  omega.windows.create('main', {
+    show: !omega.startup.isLaunchHidden(),
   });
 });
 ```
@@ -71,9 +71,9 @@ Don't conditionally skip `create()` for hidden launches — without `main` in th
 
 ## Boot order
 
-`startup.applyEarly()` is the **first** call in `Manager.initialize()` — before `whenReady`, before any other lib. The goal: spend as little time as possible in the dock-bounce window.
+`startup.applyEarly()` is the **first** call in `omega.initialize()`: before `whenReady`, before any other lib. The goal: spend as little time as possible in the dock-bounce window.
 
-Sequence: applyEarly → before-quit hook → ipc → storage → sentry → protocol → deep-link → app-state → whenReady → updater → tray/menu/contextMenu → startup.initialize → @omega.js/client → windows.initialize. **@omega.js/desktop no longer auto-creates the main window** — your `main.js` does that inside the `.then()` callback after `initialize()` resolves.
+Sequence: applyEarly → before-quit hook → ipc → storage → theme → fontawesome → sentry → protocol → deep-link → auth-flow → app-state → context → usage → whenReady → updater → tray/menu/contextMenu → startup.initialize → auth → remote-config → remote-scripts → analytics → restart-manager → windows.initialize (full list: [boot-sequence.md](boot-sequence.md)). **@omega.js/desktop does not auto-create the main window**: your `main.js` does that inside the `.then()` callback after `initialize()` resolves.
 
 ## How zero-bounce works on macOS
 
@@ -86,7 +86,7 @@ Sequence: applyEarly → before-quit hook → ipc → storage → sentry → pro
 
 With the key baked, a MANUAL launch also starts dockless — the dock icon appears the moment the main window surfaces (every surface path runs `_ensureDockVisible()` → `app.dock.show()`), so the visible difference is only that the bounce animation is replaced by the icon appearing when the window is ready.
 
-At runtime, when the consumer first calls `manager.windows.show()` (or the `windows.create()` call resolves with `show: true`), @omega.js/desktop calls `app.dock.show()` so the dock icon appears alongside the window. Reverses cleanly via `app.dock.hide()` if you want to go back to invisible.
+At runtime, when the consumer first calls `omega.windows.show()` (or the `windows.create()` call resolves with `show: true`), @omega.js/desktop calls `app.dock.show()` so the dock icon appears alongside the window. Reverses cleanly via `app.dock.hide()` if you want to go back to invisible.
 
 The injection is YAML-text-level (preserves comments, idempotent, merges with existing `extendInfo`). See `src/gulp/tasks/build-config.js`.
 
@@ -136,7 +136,7 @@ Hidden / agent apps usually want:
 And in `src/integrations/tray/index.js`:
 
 ```js
-tray.update('open', { click: () => manager.windows.show('main') });
+tray.update('open', { click: () => omega.windows.show('main') });
 ```
 
 The window is created at boot but invisible. When the user clicks the tray's "Open" item (or double-clicks the app icon), `windows.show('main')` runs, @omega.js/desktop calls `app.dock.show()`, and the user sees both the dock icon and the window appear together.

package/docs/storage.md

@@ -13,13 +13,13 @@ Linux:   ~/.config/<productName>/omega-storage.json
 ## Main-process API (sync, direct disk-backed)
 
 ```js
-manager.storage.get(key, defaultValue)   // any
-manager.storage.set(key, value)
-manager.storage.delete(key)
-manager.storage.has(key)                 // boolean
-manager.storage.clear()
-manager.storage.onChange(key, fn)        // returns unsubscribe fn
-manager.storage.getPath()                // absolute path to omega-storage.json
+omega.storage.get(key, defaultValue)   // any
+omega.storage.set(key, value)
+omega.storage.delete(key)
+omega.storage.has(key)                 // boolean
+omega.storage.clear()
+omega.storage.onChange(key, fn)        // returns unsubscribe fn
+omega.storage.getPath()                // absolute path to omega-storage.json
 ```
 
 ## Renderer-process API (async, proxied through preload + IPC)
@@ -41,19 +41,19 @@ off();
 Keys support dot-notation for nested objects natively:
 
 ```js
-manager.storage.set('window.main.bounds', { x: 10, y: 20, w: 800, h: 600 });
-manager.storage.get('window.main.bounds.w');   // → 800
+omega.storage.set('window.main.bounds', { x: 10, y: 20, w: 800, h: 600 });
+omega.storage.get('window.main.bounds.w');   // → 800
 ```
 
 ## Change broadcasts
 
 Every `set` / `delete` / `clear` in main broadcasts an `desktop:storage:change` IPC event to all renderer windows. The renderer's `window.desktop.storage.onChange` filters by key locally.
 
-In main, `manager.storage.onChange(key, fn)` registers a callback fired with `(value, previous)`.
+In main, `omega.storage.onChange(key, fn)` registers a callback fired with `(value, previous)`.
 
 ## Implementation notes
 
-- Storage initialization is async — `Manager.initialize()` `await`s it before any other lib boots, since features like `app-state` and `windows` rely on it.
+- Storage initialization is async: `omega.initialize()` `await`s it before any other lib boots, since features like `app-state` and `windows` rely on it.
 - IPC handlers (`desktop:storage:get` etc.) are registered on the @omega.js/desktop `ipc` bus, not directly on `ipcMain`. See [ipc.md](ipc.md).
 - The store uses `name: 'omega-storage'` (filename `omega-storage.json`). Don't reuse this name in a separate `electron-store` instance.
 - `electron-store@11` is ESM-only. The bundler inlines it INTO `main.bundle.js` (the static-specifier `import()` in `lib/storage.js`) — consumers install NOTHING; packaged apps carry it inside the bundle with no runtime resolution. (It used to be a runtime import the bundler was told to ignore, which silently no-op'd storage in packaged consumers — @omega.js/desktop is a devDependency and never ships in the asar.)

package/docs/templating.md

@@ -77,13 +77,13 @@ Drop your own `config/page-template.html` in your project root. @omega.js/deskto
 
 ## Runtime API
 
-`manager.templating` is also available at runtime if you need to template a string yourself (e.g. dynamic deep-link routes):
+`omega.templating` is also available at runtime if you need to template a string yourself (e.g. dynamic deep-link routes):
 
 ```js
-manager.templating.render('Hello {{ user.name }}', { user: { name: 'Ian' } });
+omega.templating.render('Hello {{ user.name }}', { user: { name: 'Ian' } });
 // → 'Hello Ian'
 
-manager.templating.render('Custom [name]', { name: 'X' }, { brackets: ['[', ']'] });
+omega.templating.render('Custom [name]', { name: 'X' }, { brackets: ['[', ']'] });
 // → 'Custom X'
 ```
 

package/docs/test-boot-layer.md

@@ -11,12 +11,12 @@ The build and the boot happen in a **staged app root of their own**, `<project>/
 | `build` | Plain Node — config parsing, util fns, schema validation. | Fast (ms) |
 | `main` | @omega.js/desktop lib code in isolation (storage, ipc, tray, etc.) inside Electron. | Fast (~50ms each) |
 | `renderer` | Inside a hidden BrowserWindow. | Fast |
-| `boot` | The **whole boot integration** — consumer's main.js → manager.initialize → live state | ~1s startup, then fast |
+| `boot` | The **whole boot integration**: consumer's main.js → omega.initialize → live state | ~1s startup, then fast |
 
 Use `boot` for tests that need to verify **integration** rather than unit behavior:
 - "Does the consumer's `src/main.js` actually wire up correctly?"
 - "Did all 13 boot steps complete without throwing?"
-- "Did config flow from JSON5 → manager.config → tray titles?"
+- "Did config flow from JSON5 → omega.config → tray titles?"
 - "Did `src/integrations/{tray,menu,context-menu}/index.js` load?"
 - "Is the menu rendered with the expected default ids?"
 
@@ -31,17 +31,17 @@ module.exports = {
   timeout:     20000,
   tests: [
     {
-      description: 'manager initialized end-to-end',
-      inspect: async ({ manager, expect, projectRoot }) => {
-        expect(manager._initialized).toBe(true);
-        expect(manager.config).toBeTruthy();
+      description: 'omega initialized end-to-end',
+      inspect: async ({ omega, expect, projectRoot }) => {
+        expect(omega._initialized).toBe(true);
+        expect(omega.config).toBeTruthy();
       },
     },
     {
       description: 'tray + menu rendered',
-      inspect: async ({ manager, expect }) => {
-        expect(manager.tray.has('open')).toBe(true);
-        expect(manager.menu.isRendered()).toBe(true);
+      inspect: async ({ omega, expect }) => {
+        expect(omega.tray.has('open')).toBe(true);
+        expect(omega.menu.isRendered()).toBe(true);
       },
     },
   ],
@@ -51,7 +51,7 @@ module.exports = {
 The `inspect` function receives:
 | Arg | Description |
 |---|---|
-| `manager` | The fully-initialized live Manager instance — same one your consumer code uses. |
+| `omega` | The fully-initialized live main-process instance, the same one your consumer code uses. |
 | `expect` | @omega.js/desktop's [Jest-compatible assertion library](../src/test/assert.js). |
 | `projectRoot` | Absolute path to the consumer project root (its `src/`, `config/` — and the `dist/` a boot run must never write). |
 | `appRoot` | Absolute path to the staged app root Electron booted — `<projectRoot>/.omega/test-app`. Assert on built artifacts here (`<appRoot>/dist/main.bundle.js`), not under `projectRoot`. |
@@ -67,7 +67,7 @@ The `inspect` function receives:
    - `OMEGA_TEST_BOOT=1` — gate
    - `OMEGA_TEST_BOOT_HARNESS=<absolute path to dist/test/harness/boot-entry.js>`
    - `OMEGA_TEST_BOOT_SPEC=<temp file with test definitions>`
-5. @omega.js/desktop's `main.js` boots normally; after `manager.initialize()` resolves, detects `OMEGA_TEST_BOOT=1`, reconstitutes each `inspect` from its serialized body string, runs them sequentially, and emits `__EM_TEST__` JSON lines on stdout.
+5. @omega.js/desktop's `main.js` boots normally; after `omega.initialize()` resolves, detects `OMEGA_TEST_BOOT=1`, reconstitutes each `inspect` from its serialized body string, runs them sequentially, and emits `__OMEGA_TEST__` JSON lines on stdout (the ONE prefix, `TEST_EVENT_PREFIX` in [src/utils/test-events.js](../src/utils/test-events.js)).
 6. Test runner parses results, calls `app.exit()`. **No sleep, no kill.**
 
 ## View suites in this lane
@@ -152,6 +152,6 @@ The `build`/`main`/`renderer` layers cover @omega.js/desktop's lib code fast and
 
 ## Limitations
 
-- Tests run sequentially in a single Electron process to amortize startup cost (~1s). State doesn't carry across tests — they all share one `manager` instance.
+- Tests run sequentially in a single Electron process to amortize startup cost (~1s). State doesn't carry across tests: they all share one `omega` instance.
 - `inspect` function bodies are serialized via `Function.prototype.toString` and reconstituted with `new Function(...)`. Closures over the test file's outer scope **don't survive** — only the `inspect` argument bag is available inside.
 - We can't simulate user input (clicking the tray, right-clicking, typing). For that, you'd need `nut-js` or similar — out of scope.

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