@omega.js/desktop 0.53.0 → 0.54.1

package/docs/ipc.md

@@ -1,61 +0,0 @@
-# IPC
-
-Typed channel bus for main ↔ renderer communication. All @omega.js/desktop features register their channels through this single layer rather than calling `ipcMain.handle` directly, so you have one place to look and one place to instrument.
-
-## Main-process API
-
-```js
-omega.ipc.handle(channel, async (payload, evt) => result)   // request/response
-omega.ipc.unhandle(channel)
-omega.ipc.invoke(channel, payload)                          // call locally (also what renderer triggers)
-omega.ipc.on(channel, (payload, evt) => void)               // one-way subscribe (renderer → main)
-omega.ipc.off(channel, fn)
-omega.ipc.broadcast(channel, payload)                       // → all BrowserWindows
-omega.ipc.send(webContents, channel, payload)               // → one renderer
-omega.ipc.hasHandler(channel)
-omega.ipc.listenerCount(channel)
-```
-
-## Renderer-process API (via preload contextBridge)
-
-```js
-await window.desktop.ipc.invoke(channel, payload)   // → Promise<result>
-const off = window.desktop.ipc.on(channel, (payload) => { ... });
-window.desktop.ipc.send(channel, payload);          // fire-and-forget
-```
-
-## Channel naming
-
-framework-internal channels are prefixed `desktop:` (e.g. `desktop:storage:get`, `desktop:storage:change`). Consumers are free to use any namespace.
-
-## Validation
-
-- `handle()` throws if `channel` is empty/non-string or `handler` is non-function.
-- `handle()` throws on duplicate registration. Call `unhandle()` first if you need to swap.
-- `invoke()` rejects with a clear message if no handler is registered for the channel.
-- Handler errors propagate through `invoke()` (both main-local and renderer-side) — your renderer's `await window.desktop.ipc.invoke(...)` will reject with the original error message.
-
-## Zero-trust payloads
-
-Registration is validated for you (above) — payload CONTENT is not. Treat every payload reaching a `handle()` / `on()` callback as untrusted input: renderers can be compromised, and apps that embed remote web content (e.g. external pages in `WebContentsView`s) expose the IPC surface to code you don't control.
-
-- **Validate shape and values before acting** — types match, IDs are well-formed, enums are from the expected set, paths resolve inside the expected roots.
-- **Gate any URL arriving via IPC** through `sanitize-url.js` before `shell.openExternal` / `loadURL` (the zero-trust URL rule — see [common-mistakes.md](common-mistakes.md)).
-- **Never feed raw payload values** into filesystem paths, shell commands, or `webContents.executeJavaScript`.
-
-## Boot order
-
-`ipc` initializes **before** `storage` so that storage (and every other feature) can register handlers via `ipc.handle`. This is the canonical pattern: don't touch `ipcMain` directly.
-
-## Example
-
-```js
-// main
-omega.ipc.handle('user:get-token', async (payload) => {
-  const token = await fetchToken(payload.userId);
-  return { token };
-});
-
-// renderer
-const { token } = await window.desktop.ipc.invoke('user:get-token', { userId: 'abc' });
-```

package/docs/lib-modules.md

@@ -1,53 +0,0 @@
-# Lib Modules
-
-`src/lib/*.js`: every Electron concern is its own module. Each exports one object with `initialize(omega)`; the main-process instance hangs each on itself by name and initializes them in a fixed order at boot (see [boot-sequence.md](boot-sequence.md)). Each module's deep reference lives at `docs/<lib-name>.md`; the module list is in the framework guide's Architecture section ([docs/desktop/index.md](../../../docs/desktop/index.md)).
-
-## Lib initialization contract
-
-Each lib exposes the same skeleton:
-
-```js
-const myLib = {
-  _initialized: false,
-  _omega: null,
-
-  initialize(omega) {
-    myLib._omega = omega;
-    // wire IPC handlers, app event listeners, etc.
-    myLib._initialized = true;
-  },
-
-  // Public API
-  doThing() { ... },
-
-  // Disable at runtime (idempotent)
-  disable() {
-    // tear down listeners; safe to call multiple times
-  },
-};
-
-module.exports = myLib;
-```
-
-Don't use `EventEmitter` unless the lib genuinely emits multiple event types. For "fires once when ready" use a promise; for "broadcasts changes" use IPC with renderer subscriptions.
-
-## Adding a new lib
-
-1. Create `src/lib/<name>.js` exporting one object with `initialize(omega)`.
-2. Wire it into the boot order in `src/main.js` (or the renderer/preload class if it's a per-context lib): check [boot-sequence.md](boot-sequence.md) for where it belongs and what it may depend on.
-3. Set it on the instance in the `Omega` constructor as `this.<camelCaseName>`, so consumers reach it at runtime as `omega.<camelCaseName>`.
-4. Write tests at every layer the lib has a surface in (see [test-framework.md](test-framework.md)) — at minimum `src/test/suites/main/<name>.test.js`.
-5. Add a `docs/<name>.md` deep reference, add the module's row to the Lib modules table in the framework guide (`docs/desktop/index.md`), and link it from the Documentation index.
-
-## Flat file vs directory split
-
-- **Default to flat `src/lib/<name>.js`.**
-- **Split into a directory** (`src/lib/<name>/{index,core,main,renderer,preload}.js`) ONLY when each Electron context has materially different logic that would force ugly runtime branching inside one file. `index.js` becomes a thin context detector that delegates.
-- `lib/sentry/` was that split (the SDK has separate main/renderer/preload entry points) until it moved WHOLE into `@omega.js/monitoring` (#380) — the backend and the client needed the same policy, so the shape it proved now lives in the shared package. `lib/restart-manager/` is split for a different, also-valid reason — a **shared-SSOT split**: its `protocol.js` (the wire contract) must be importable by the Restart Manager app via the `exports` map with zero Electron/@omega.js/desktop baggage, so the contract lives in its own pure-Node file next to the main-only `index.js` + `install.js`. `sign-helpers/` is a helpers directory, not a lib.
-- Don't split prophylactically; convert when the branching gets ugly.
-
-## See also
-
-- [boot-sequence.md](boot-sequence.md): the fixed `omega.initialize()` order + rationale
-- [environment-detection.md](environment-detection.md): cross-context helpers shared by the three processes and the build module
-- [test-framework.md](test-framework.md) — the four-layer harness new libs must ship tests in

package/docs/logging.md

@@ -1,227 +0,0 @@
-# Logging
-
-@omega.js/desktop ships a runtime logger that writes to **both the console and a file on disk**, so production issues are inspectable without remoting into the user's machine.
-
-## What you get
-
-- **One log file**, `runtime.log`, populated by all three Electron processes (main / preload / renderer)
-- **Live console output** during development (DevTools console for renderer, terminal stdout for main)
-- **Kept across boots** — never truncated; it rotates by size instead (see the lifetime table below), unlike `dev.log`/`build.log`/`test.log`
-- **Cross-process timestamps** so log lines from main + preload + renderer interleave in arrival order
-
-## Where the file lives
-
-| Mode | Location |
-|---|---|
-| Dev (`npm start`, `app.isPackaged === false`) | `<projectRoot>/logs/runtime.log` |
-| Prod (installed `.dmg` / `.exe` / `.deb`, `app.isPackaged === true`) | OS log dir: `~/Library/Logs/<ProductName>/runtime.log` (macOS), `%APPDATA%\<ProductName>\logs\runtime.log` (Windows), `~/.config/<ProductName>/logs/runtime.log` (Linux) |
-
-`<ProductName>` = `config.app.productName` (falls back to `config.brand.name`). @omega.js/desktop calls `app.setName(productName)` at boot so `app.getPath('logs')` uses the human-readable brand name, not `package.json#name`.
-
-## How to write logs
-
-In **main process**:
-
-```js
-const omega = require('@omega.js/desktop/main');
-await omega.initialize();
-
-omega.logger.log('booted');
-omega.logger.warn('connection slow');
-omega.logger.error(new Error('boom'));
-```
-
-In **preload**:
-
-```js
-const omega = require('@omega.js/desktop/preload');
-await omega.initialize();
-omega.logger.log('preload ready');
-```
-
-In **renderer** (use the contextBridge surface, which forwards to main → file):
-
-```js
-window.desktop.logger.log('user clicked Save');
-window.desktop.logger.warn('IPC slow');
-window.desktop.logger.error(new Error('ui blew up'));
-```
-
-All three end up in the same `runtime.log`, prefixed with their scope (`main`, `preload`, `renderer`):
-
-```
-[2026-05-05 14:32:11.045] [info] main omega.initialize
-[2026-05-05 14:32:11.122] [info] main ipc ready
-[2026-05-05 14:32:11.187] [info] preload contextBridge exposed
-[2026-05-05 14:32:11.401] [info] renderer auth.listen attached
-[2026-05-05 14:32:12.998] [warn] main auto-updater check failed: network
-```
-
-Grep one context with:
-
-```bash
-grep ' main ' logs/runtime.log
-```
-
-## CLI: `npx omega logs`
-
-For dev-loop convenience. From the consumer project root:
-
-| Command | Effect |
-|---|---|
-| `npx omega logs` | Print path, then `tail -50` of the file |
-| `npx omega logs --tail` (or `-f`) | Follow mode (like `tail -f`). Ctrl+C to stop. Cross-platform. |
-| `npx omega logs --path` (or `-p`) | Print the resolved path only (pipe-friendly) |
-| `npx omega logs --open` | Open the log file in OS default editor |
-| `npx omega logs --lines=100` | Default mode with custom tail length |
-
-### The surface argument
-
-An optional positional names which of the project's logs to read — `npx omega logs [runtime|dev|build|test]`, resolving `<cwd>/logs/<surface>.log`. It defaults to `runtime`, and every flag above works the same on whichever surface was named:
-
-```bash
-npx omega logs dev --tail       # follow the gulp pipeline live
-npx omega logs test --lines=100 # last 100 lines of the previous test run
-npx omega logs build --path     # just the path, for piping
-```
-
-Anything else fails naming the four surfaces. (The four files themselves are described in the lifetime table below; `deploy.log` and `signing.log` are not tail targets.)
-
-`mgr logs` only resolves the dev path (`<cwd>/logs/<surface>.log`). To find the production runtime log on a user's machine, use the table above or call `getLogFilePath()` from app code.
-
-## How to find the file path from app code
-
-```js
-const LoggerLite = require('@omega.js/desktop/lib/logger-lite');
-const filePath = LoggerLite.getLogFilePath();
-// → '/Users/<user>/Library/Logs/MyApp/runtime.log' in production
-```
-
-Useful for:
-- "Send us your log" buttons in your settings UI
-- Programmatic log shipping (e.g. POSTing the file to your support backend)
-- Crash reporters that want to attach the runtime log
-
-## What @omega.js/desktop logs automatically
-
-Beyond what you write yourself, @omega.js/desktop emits a fixed set of high-signal lifecycle lines so post-mortem debugging works without redeploying:
-
-**At boot (`omega.initialize()`):**
-
-```
-(main)     Initializing @omega.js/desktop (main)... pid=12345 platform=darwin arch=arm64 packaged=true argv=["--omega-launched-at-login"]
-(startup)  startup boot summary — RAW inputs:
-(startup)    process.argv:            ["--omega-launched-at-login"]
-(startup)    process.platform:        darwin
-(startup)    process.arch:            arm64
-(startup)    app.isPackaged:          true
-(startup)    app.getLoginItemSettings(): {"status":"enabled","openAtLogin":true,"openAsHidden":false,"restoreState":false,"wasOpenedAtLogin":false,"wasOpenedAsHidden":false}
-(startup)    boot env:                {}
-(startup)  startup boot summary — RESOLVED values:
-(startup)    config.startup.mode:     normal
-(startup)    config.startup.openAtLogin: {enabled:true, mode:hidden}
-(startup)    isDev:                   false
-(startup)    hasLoginArg:             true
-(startup)    wasLaunchedAtLogin():    true (via argv-flag)
-(startup)    isLaunchHidden():        true
-```
-
-The boot summary has two parallel blocks: **RAW inputs** (what the OS / shell gave us) and **RESOLVED values** (what @omega.js/desktop decided to act on). Use it to debug both directions:
-- "Why is @omega.js/desktop behaving like X?" → check resolved values
-- "Why did @omega.js/desktop decide X?" → check raw inputs
-
-The `via:` annotation on `wasLaunchedAtLogin()` distinguishes a real login launch (`via:macos-wasOpenedAtLogin`) from a flag-based simulation (`via:argv-flag` — i.e. the user passed `--omega-launched-at-login`).
-
-**App lifecycle events** (logged from `main.js`):
-
-```
-app event: before-quit (entering quit sequence — close events bypass hide-on-close)
-app event: will-quit
-app event: quit code=0
-app event: window-all-closed
-app event: activate (macOS — dock click or app re-launch)
-app event: open-url url=myapp://auth/token?...
-app event: render-process-gone reason=crashed exitCode=139
-app event: child-process-gone type=GPU reason=killed exitCode=9
-process exit code=0
-uncaughtException: <stack>
-unhandledRejection: <stack>
-```
-
-**Window lifecycle events** (per named window, logged from `window-manager`):
-
-```
-createNamed: building "main" (show=false, hideOnClose=true)
-createNamed: loaded /path/to/app.asar/dist/views/main/index.html for "main"
-window "main": ready-to-show — staying invisible (show:false at create)
-window "main": ready-to-show — surfacing
-window "main": show event
-window "main": hide event
-window "main": focus event
-window "main": minimize event
-window "main": restore event
-window "main": close intercepted (hide-on-close) — hiding instead
-window "main": close allowed (hideOnClose=true, allowQuit=false, isQuitting=true, force=false)
-window "main": closed (destroyed)
-```
-
-**Re-surface handlers**:
-
-```
-activate (macOS) — surfacing main (visible=false, minimized=false)
-_ensureDockVisible — calling dock.show()
-_ensureDockVisible — dock already visible
-second-instance argv=["..."] eventArgv=["..."] cwd=/...
-second-instance — surfacing main (visible=false, minimized=false)
-```
-
-These cover everything you'd want when debugging "why did the app go invisible / crash / fail to surface" without needing to attach a debugger.
-
-## Log levels
-
-Standard: `log`, `info`, `warn`, `error`, `debug`. All levels are written to both transports by default.
-
-To dial down via env vars (useful in CI to silence verbose framework noise):
-
-| Var | Effect |
-|---|---|
-| `OMEGA_LOG_LEVEL_FILE=warn` | Only `warn` + `error` reach the file |
-| `OMEGA_LOG_LEVEL_CONSOLE=error` | Only `error` reaches stdout/stderr |
-
-Default is `silly` (everything) on both.
-
-## How it works under the hood
-
-@omega.js/desktop's runtime logger (`lib/logger-lite.js`) detects which process it's in:
-
-- **Main**: writes to `runtime.log` directly via [electron-log](https://github.com/megahertz/electron-log)'s file transport. Sets up an IPC listener on channel `desktop:log:forward` to receive forwarded calls from preload + renderer.
-- **Preload**: writes to console (DevTools) AND forwards each call via `ipcRenderer.send('desktop:log:forward', ...)` to main.
-- **Renderer**: same as preload via `window.desktop.logger` (contextBridge surface).
-- **Outside Electron** (build/CLI tools that happen to require this module): falls back to console-only.
-
-File path resolution in main:
-1. Read `app.isPackaged`.
-2. If packaged → `app.getPath('logs')`.
-3. If dev → `<cwd>/logs/`.
-4. `mkdirSync` the dir, point electron-log at `<dir>/runtime.log`.
-
-The transport is set up lazily on first `log()` call, so importing `LoggerLite` in build/CLI contexts that have no Electron is harmless.
-
-## Coexisting with `dev.log`, `build.log`, `test.log`, and `deploy.log`
-
-Five separate logs in `<projectRoot>/logs/`:
-
-| File | Source | Lifetime |
-|---|---|---|
-| `runtime.log` | Packaged-app runtime in dev mode | Persistent, rotates at 10 MB to `runtime.old.log` (one archive generation) |
-| `dev.log` | Gulp pipeline + spawned Electron child stdout (`npm start`) | Truncated each `npm start` |
-| `build.log` | Gulp pipeline output for production builds/packages (`npm run build` / `package` / `publish`, i.e. `OMEGA_BUILD_MODE=true`) | Truncated each build |
-| `test.log` | `npx omega test` runner output (suite names, pass/fail states, harness boot lines) | Truncated each test run |
-| `deploy.log` | GH Actions run output, streamed locally by the follower every target's deploy uses (`omega deploy`, `npm run release`) ([#873](https://github.com/Omega-JS-Stack/omega/issues/873); this was `ci.log`) | Truncated each deploy |
-| `signing.log` | JSONL signing events from Windows code-signing (local dev fallback; on CI this writes to the runner home as `omega-signing.log` instead) | Appended (not truncated) |
-
-`dev.log` and `build.log` are the same gulp tee — which one it writes is chosen by `OMEGA_BUILD_MODE`, so they never both fill up in one run. (Disable the tee with `OMEGA_LOG_FILE=false`; override its path with `OMEGA_LOG_FILE=<path>`.)
-
-They serve different purposes and don't overlap: `dev.log`/`build.log` show you "is the build still running?", `test.log` shows you "which test failed on the last run?", `deploy.log` shows you "did the release workflow pass?", `runtime.log` shows you "is my app's auto-updater finding the right release feed?". All useful.
-
-In production: only `runtime.log` exists (no project, no gulp, no GH Actions stream).

package/docs/menu.md

@@ -1,160 +0,0 @@
-# Application Menu
-
-File-based application menu (the macOS menu bar / Windows + Linux menu). Same builder + id-path API as [tray](tray.md) and [context-menu](context-menu.md).
-
-## Config
-
-No config block. Path is conventional: `src/integrations/menu/index.js`. To opt out, call `omega.menu.disable()` from your main entry.
-
-## Definition file
-
-```js
-// src/integrations/menu/index.js
-module.exports = ({ omega, menu, defaults }) => {
-  // Easiest: start from the platform-aware default template.
-  menu.useDefaults();
-
-  // Mutate by id-path:
-  menu.show('main/preferences');                // @omega.js/desktop ships this hidden by default
-  menu.update('main/check-for-updates', { label: 'Get Latest Version' });
-  menu.insertAfter('main/check-for-updates', {
-    id: 'main/account', label: 'Account...', click: () => omega.windows.show('account'),
-  });
-  menu.remove('view/reload');
-  menu.hide('main/services');
-
-  // Or add a whole new top-level menu:
-  menu.menu('Tools', [{ id: 'tools/sync', label: 'Sync Now', click: () => {} }]);
-};
-```
-
-## Builder API (during definition)
-
-```js
-menu.menu(label, items)        // add a top-level menu bar entry
-menu.useDefaults()             // populate with the platform-appropriate default template
-menu.append(item)              // append a top-level descriptor (rare; prefer menu())
-menu.clear()                   // start over
-```
-
-## Id-path API
-
-Same shape across menu / tray / context-menu. Available **during definition** (on the `menu` builder arg) AND **at runtime** on `omega.menu`:
-
-```js
-.find(idPath)                  // live descriptor or null
-.has(idPath)                   // bool
-.update(idPath, patch)         // Object.assign + re-render. returns true if found.
-.remove(idPath)                // splice + re-render. returns true if removed.
-.enable(idPath, bool = true)   // sugar over update({enabled})
-.show(idPath, bool = true)     // sugar over update({visible})
-.hide(idPath)                  // visible:false
-.insertBefore(idPath, item)    // splice in a sibling
-.insertAfter(idPath, item)     // splice in a sibling
-.appendTo(idPath, item)        // push into a submenu (creates submenu if absent)
-```
-
-Menu ids are **paths** because menus actually nest (`main/check-for-updates`, `view/developer/toggle-devtools`). @omega.js/desktop matches by full id field first; if that misses it walks the path treating each segment as the last component of an id.
-
-## Default template ids
-
-Every item in @omega.js/desktop's default template carries a stable id you can target.
-
-### macOS App menu (the one labeled with your app name)
-
-| ID | Item | Notes |
-|---|---|---|
-| `main/about` | About | |
-| `main/check-for-updates` | Check for Updates… | Auto-updater wired |
-| `main/preferences` | Preferences… | `visible:false` by default — use `menu.show('main/preferences')` |
-| `main/services` | Services submenu | |
-| `main/hide` | Hide | |
-| `main/hide-others` | Hide Others | |
-| `main/show-all` | Show All | |
-| `main/relaunch` | Relaunch | Restarts the app |
-| `main/quit` | Quit | |
-
-### File menu (win/linux equivalents of the App menu)
-
-| ID | Item | Notes |
-|---|---|---|
-| `file/close` | Close (mac only) | |
-| `file/preferences` | Preferences… (win/linux) | `visible:false` by default |
-| `file/relaunch` | Relaunch (win/linux) | |
-| `file/quit` | Exit | |
-
-### Cross-platform
-
-| ID | Item |
-|---|---|
-| `edit/undo`, `edit/redo`, `edit/cut`, `edit/copy`, `edit/paste`, `edit/select-all`, `edit/delete` | Edit submenu |
-| `edit/paste-and-match-style` | mac only |
-| `view/reload`, `view/reset-zoom`, `view/zoom-in`, `view/zoom-out`, `view/toggle-fullscreen` | View submenu |
-| `view/developer` | Submenu (dev mode only) |
-| `view/developer/toggle-devtools` | Toggle Developer Tools |
-| `view/developer/inspect-elements` | Inspect Element |
-| `view/developer/force-reload` | Force Reload |
-| `view/developer/simulate-update` | Simulate update submenu (see [docs/auto-updater.md](auto-updater.md)) |
-| `view/developer/simulate-update/available`, `.../unavailable`, `.../error` | Run the update simulator for one scenario |
-| `window/minimize`, `window/zoom`, `window/front` | Window submenu (mac) |
-| `window/minimize`, `window/close` | Window submenu (win/linux) |
-
-### Help menu
-
-| ID | Item | Notes |
-|---|---|---|
-| `help/check-for-updates` | Check for Updates… (win/linux only) | Auto-updater wired |
-| `help/website` | "`<brandName>` Home" | Only when `brand.url` configured |
-
-### Development menu (dev mode only)
-
-Top-level, only visible when `omega.isDevelopment()`. Mirrors legacy @omega.js/desktop's developer utilities.
-
-| ID | Item | Action |
-|---|---|---|
-| `development/open-exe-folder` | Open exe folder | Reveals `app.getPath('exe')` |
-| `development/open-user-data` | Open user data folder | Reveals `app.getPath('userData')` |
-| `development/open-logs` | Open logs folder | Reveals `app.getPath('logs')` |
-| `development/open-app-config` | Open app config folder | Reveals `app.getPath('appData')` |
-| `development/test-error` | Throw test error | Throws an uncaught error (verifies sentry / error handling) |
-
-## Built-in framework items
-
-`main/check-for-updates` (mac) and `help/check-for-updates` (win/linux) are **wired to `omega.autoUpdater`**:
-- Label updates dynamically: *Checking…*, *Downloading 42%*, *Restart to Update v1.2.3*, *You're up to date*.
-- Click triggers `autoUpdater.checkNow()` or `autoUpdater.installNow()` depending on state.
-
-The same hook also patches the tray's `check-for-updates` item if present, so both UIs stay in lockstep.
-
-Patch or remove either as needed — the auto-updater hook is a no-op when the item is missing.
-
-## Item descriptors
-
-Same dynamic conveniences as tray:
-- `label` / `enabled` / `visible` / `checked` may be functions, evaluated on every `refresh()`
-- `click` wrapped to catch errors
-- `submenu` recursively resolved
-
-## Runtime API on `omega.menu`
-
-```js
-omega.menu.refresh()                         // re-evaluate dynamic state
-omega.menu.define(fn)                        // replace the whole definition at runtime
-omega.menu.destroy()                         // tear down (mostly for tests)
-omega.menu.disable()                         // turn the menu off entirely (idempotent)
-
-// Id-path API — same as listed above.
-omega.menu.find('main/check-for-updates')
-omega.menu.update('main/check-for-updates', { label: 'Updates...' })
-omega.menu.remove('view/reload')
-omega.menu.insertAfter('main/check-for-updates', { id: 'main/account', label: 'Account...' })
-
-// Inspection
-omega.menu.getItems()                        // top-level descriptors (shallow copy)
-omega.menu.isRendered()                      // bool
-omega.menu.getMenu()                         // the underlying Electron Menu instance
-```
-
-## Default scaffold
-
-The scaffold every verb runs ships `src/integrations/menu/index.js` calling `menu.useDefaults()` plus commented-out examples (show preferences, insertAfter, update, remove, hide, add a Tools menu, appendTo).