@omega.js/desktop 0.52.0 → 0.54.0

package/docs/build-system.md

@@ -1,169 +0,0 @@
-# Build System
-
-@omega.js/desktop's pipeline: **prepare-package** (framework only) → **gulp** (consumer) → **esbuild** (3 bundles) → **electron-builder** (packaging) → **strategy-pluggable signing**.
-
-## prepare-package (framework-side)
-
-Copies @omega.js/desktop's `src/` → `dist/` so consumers `require('@omega.js/desktop/main')` from the built output. Configured in @omega.js/desktop's `package.json`:
-
-```jsonc
-"preparePackage": {
-  "input":  "./src",
-  "output": "./dist",
-  "type":   "copy",
-  "replace": {},
-  "hooks":   {}
-}
-```
-
-Run with `npm start` (watch) or `npm run prepare` (one-shot).
-
-## Gulp (consumer-side)
-
-Auto-loads tasks from `<@omega.js/desktop>/dist/gulp/tasks/*.js` via `<@omega.js/desktop>/dist/gulp/main.js`. Consumer's `package.json` points there:
-
-```jsonc
-"scripts": {
-  "gulp": "gulp --cwd ./ --gulpfile ./node_modules/@omega.js/desktop/dist/gulp/main.js"
-}
-```
-
-### Tasks
-
-| Task | Status | Description |
-|---|---|---|
-| `defaults` | real | Copy `<@omega.js/desktop>/dist/defaults/*` into the consumer (skips existing files) |
-| `distribute` | real | Stage consumer `src/` + @omega.js/desktop `dist/` into `.desktop-build/` |
-| `bundle` | real | Three parallel bundles — main / preload / renderer, through @omega.js/devkit's `bundle()` wrapper. Named `webpack` until [#737](https://github.com/Omega-JS-Stack/omega/issues/737) |
-| `sass` | real | SCSS → `dist/assets/css/*` |
-| `html` | real | `src/views/**/index.html` → `dist/views/*` |
-| `build-config` | real | Materialize `dist/electron-builder.yml` from source + mode-dependent injections (`LSUIElement` for hidden mode) |
-| `package` | real | Run `electron-builder build --config dist/electron-builder.yml` (full DMG/zip/universal-mac, NSIS-win, deb+AppImage-linux) |
-| `package-quick` | real | Quick-package for host platform/arch only — `--dir` mode, no DMG/zip/universal/notarize. ~30s vs ~3min for full `package`. Output: `release/<platform>-<arch>/<ProductName>.app` (or `.exe`-folder/linux-unpacked) — directly launchable. Used for smoke-testing packaged-mode behavior locally. `--quick` trims the electron-builder phase and NOTHING else: the build ahead of it is full and cold (#737). |
-| `release` | real | `electron-builder build --publish always` |
-| `audit` | real | Validate consumer config (required keys, valid enums, deep-link scheme format), ensure icon + entrypoints exist; in publish mode also requires an ADDRESSABLE releases repo (`repo.org` + `brand.id`) + `electron-builder.yml`. Throws with a numbered list of every problem found |
-| `serve` | real | Spawns `electron .` against the build output, websocket on `OMEGA_LIVERELOAD_PORT` |
-
-### Composition
-
-```js
-// `build` produces bundles only (dist/main.bundle.js, etc.) — no installer.
-exports.build = series(
-  exports['hook:build:pre'],
-  exports.defaults,
-  exports.distribute,
-  parallel(exports.sass, exports.bundle, exports.html),
-  exports.audit,
-  exports['build-config'],
-  exports['hook:build:post'],
-);
-
-// `packageBuild` = build + electron-builder (full DMG/zip/universal). Slow (~3min on mac).
-exports.packageBuild = series(exports.build, exports.package);
-
-// `packageQuick` = build + electron-builder --dir for host platform/arch only.
-// Fast (~20-30s) — smoke-testing only.
-exports.packageQuick = series(exports.build, exports['package-quick']);
-
-// `publish` = build + sign + notarize + GH Release upload (to the brand's ONE
-// public releases repo, under versionless names).
-exports.publish = series(
-  exports.build,
-  exports['hook:release:pre'],
-  exports.release,
-  exports['hook:release:post'],
-);
-
-exports.default = series(exports.build, exports.serve);
-```
-
-## esbuild — three bundles
-
-All bundled in production for source protection. `app.asar` alone is not obfuscation (anyone can `npx asar extract` it) — minification and name mangling are what protect framework + app source.
-
-Every bundle goes through @omega.js/devkit's ONE `bundle()` wrapper ([docs/devkit/index.md](../../../docs/devkit/index.md)), which composes the shared parts: the framework-deps resolve hook (#87), the production `@dev-only` strip (#18), the minify/sourcemap rules by mode, and one timing line per build. `src/gulp/tasks/bundle.js` holds only what is desktop's own.
-
-| Bundle | Entry | Output | Platform / format | Externals |
-|---|---|---|---|---|
-| `main` | `src/main.js` | `dist/main.bundle.js` | `node` / `cjs` | electron + node builtins + native modules from consumer's `package.json` |
-| `preload` | `src/preload.js` | `dist/preload.bundle.js` | `node` / `cjs` | electron — `platform: 'node'` already leaves every built-in external, same as main, so electron is the only name worth stating |
-| `renderer` | `src/assets/js/components/<view>/index.js` | `dist/assets/js/components/<view>.bundle.js` | `browser` / `iife` | none — Node built-ins resolve to an empty module (see below) |
-
-### Syntax floor — the pinned Electron answers it
-
-webpack encoded the runtime as `target: 'electron-main' | 'electron-preload' | 'web'`. esbuild splits it into `platform` (above) and `target` (the syntax floor), and the floor is READ from the Electron binary the consumer pinned: [src/utils/electron-targets.js](../src/utils/electron-targets.js) runs it once per build with `ELECTRON_RUN_AS_NODE` (no window, no focus) and takes `process.versions.node` → `node<version>` for main/preload and `process.versions.chrome` → `chrome<major>` for the renderer. The binary is resolved from the FRAMEWORK's module context — the same lookup `build-config` pins `electronVersion` with, so the bundles compile for the Electron that will actually run them. A binary that can't be run (a CI job with `ELECTRON_SKIP_BINARY_DOWNLOAD`) warns and drops the floor; it never invents a version.
-
-### Node built-ins in the renderer
-
-The renderer runs with `contextIsolation: true` — a browser-like environment with no Node globals — but libraries bundled through @omega.js/client still IMPORT `fs`, `path`, `crypto` and friends on code paths their browser builds never take. webpack answered with `resolve.fallback: { fs: false, … }`; esbuild has no such option, so the same list is a resolve hook onto one empty CommonJS module (`RENDERER_EMPTY_MODULES` in the task). `electron` is on the list too: a renderer that reached the real module would be a security hole, not a missing polyfill.
-
-### OMEGA_BUILD_JSON: a define for Node, one file for the browser
-
-The wrapper is the ONE shape every OMEGA browser surface carries, `{ config, package, mode, license, builtAt }` ([#894](https://github.com/Omega-JS-Stack/omega/issues/894)), with `mode` the same three keys everywhere (`{ environment, build, publish }`; desktop's own `server` verdict stays inside `Manager.getMode()`). Two blobs come out of one composition, off one set of build facts:
-
-- `composeBuildJson()` → main and preload, as an esbuild `define` (the bare identifier becomes the literal at compile time) plus a `banner` that assigns it to `globalThis`. Its `config` is the WHOLE resolved config, because the main process boots from it in a packaged app, and both bundles are Node rather than a public surface. `process.env.NODE_ENV` is defined the same way: webpack derived it from its `mode`, esbuild has no modes, so the build states it.
-- `composeClientBuildJson()` → the renderer, written ONCE as `dist/build.js` through `@omega.js/devkit/build-json` ([#743](https://github.com/Omega-JS-Stack/omega/issues/743)). Its `config` is `clientConfig(resolved)` from `@omega.js/config`, the browser-safe subset every OMEGA browser surface carries: a renderer is readable from DevTools, so the GCP account facts, the signing certificates and the account admins stay out of it. The page template loads the file with `<script src="../../build.js">` as the view's FIRST script, ahead of the view bundle (`dist/views/<view>/` → `dist/`, resolved inside a packaged asar exactly as the bundle tag beside it is), and the renderer bundle carries no define and no banner of its own.
-
-The build facts ride on both: `runtime: 'electron'` ([#896](https://github.com/Omega-JS-Stack/omega/issues/896), the fact @omega.js/client cannot sniff from inside a renderer), `environment`, `version`, `buildTime`, `target`, and the resolved `dev` map on non-production builds.
-
-Pinned by `src/test/suites/build/build-json-bake.test.js`.
-
-## electron-builder
-
-@omega.js/desktop **generates** `dist/electron-builder.yml` from `config/omega.json5` + @omega.js/desktop defaults — the consumer never ships an `electron-builder.yml`. `gulp/build-config` does the materialization, applying:
-
-- App metadata: `appId`, `productName`, `copyright` (with `{YEAR}` token expansion to the current year)
-- App-level cross-platform fields: `category` mapping, `languages`, `darkModeSupport`
-- Per-target (per-platform) installer config from `targets.{mac,win,linux}`:
-  - **mac**: arch (default `universal`), MAS stubs (not implemented)
-  - **win**: arch (default `x64`+`ia32`), NSIS oneClick + shortcuts
-  - **linux**: arch, optional snap publishing
-- Target lists derived from the `platforms` declaration and versionless `artifactName` templates from `@omega.js/config`'s `platforms.js`: the ONE format table the website's direct-download URLs read too, so `/releases/latest/download/<asset>` never changes. The asset table + the whole release contract: [releasing.md](releasing.md#versionless-assets-and-direct-download-links)
-- Mode-dependent injections like `mac.extendInfo.LSUIElement: true` when `startup.mode === 'hidden'` (zero-bounce production launches — see [startup.md](startup.md))
-- `electronVersion` pinned from the INSTALLED electron (resolved via the framework's module context — electron-builder refuses semver ranges and can't see a workspace-hoisted electron from the target dir)
-- Generated entitlements + resolved icons + materialized publish + afterSign hook. The publish block is CONFIG-ONLY and fully derived ([#883](https://github.com/Omega-JS-Stack/omega/issues/883)): `<brand.id>-releases` under `repo.org`, through @omega.js/config's `releasesRepo`. No git-remote discovery and no typed repo name (a brand-monorepo target's remote is the repo it is nested in; electron-builder's update-info step crashes on a null publish config, so this isn't cosmetic)
-- Optional passthrough: `fileAssociations`, `protocols`
-- The `files` list: everything under the target root except source maps, `.env` files, `logs/`, and the scratch and state dirs `.omega/`, `.claude/`, `.temp/`, `.cache/`, `.gh-runners/` and `test/` ([#866](https://github.com/Omega-JS-Stack/omega/issues/866): the boot runner stages `.omega/test-app` with symlinks into the target, and the packager followed them). `src/` ships, because the runtime reads `src/integrations/*` from the app root; `config/` (the build resources dir) and `release/` are excluded by electron-builder itself
-
-The full per-target reference (every config knob, default value, and what it produces in YAML) lives in **[installer-options.md](installer-options.md)**.
-
-`gulp/package` and `gulp/package-quick` both point electron-builder at the generated `dist/electron-builder.yml`. Consumer overrides via `config.electronBuilder.*` are merged on top of the generated config — see [installer-options.md § Raw `electronBuilder` overrides](installer-options.md#raw-electronbuilder-overrides-escape-hatch) for the escape hatch.
-
-## Build modes
-
-Environment variables (set in-process by the `omega build` / `omega package` / `omega publish` verbs — the consumer's npm scripts are thin `npx omega` aliases):
-
-| Var | Effect |
-|---|---|
-| `OMEGA_BUILD_MODE=true` | Production bundles (minified, name-mangled, no sourcemaps, `@dev-only` blocks stripped) |
-| `OMEGA_BUILD_OUTPUT=<path>` | The boot-test seam: redirect the gulp BUILD output away from `<project>/dist` (absolute, or relative to the project root). Resolved by [src/utils/dist-root.js](../src/utils/dist-root.js), which every build task's output path goes through — but `omega clean` and the generated `electron-builder.yml` stay project-relative, so this is NOT a general relocation switch; packaging under it is unsupported. Used by the boot-test runner so a test build never collides with the `npm start` watcher's `dist/` ([test-boot-layer.md](test-boot-layer.md#isolated-build-output)) |
-| `OMEGA_IS_PUBLISH=true` | electron-builder runs with `--publish always` |
-| `OMEGA_IS_SERVER=true` | Running in CI |
-
-## Windows code signing
-
-Strategy-pluggable via `platforms.windows.signing.strategy` in `config/omega.json5`:
-
-| Strategy | Where signing runs | When to use |
-|---|---|---|
-| `self-hosted` | Self-hosted GH Actions runner with USB EV token plugged in | Default for @omega.js/desktop v1 — physical EV token desktop |
-| `cloud` | `windows-latest` runner shells out to a cloud signing CLI (Azure Trusted Signing / SSL.com / DigiCert KeyLocker) | Future migration target |
-| `local` | Developer's Windows machine after CI uploads unsigned artifact | Fallback when no runner is available |
-
-The `gulp/build-config` task and `electron-builder.yml`'s `win.sign` hook both honor `platforms.windows.signing.strategy` so the same code path drives all three. Provider modules live in `src/lib/sign-providers/{ev,azure,sslcom,digicert}.js` (Pass 3).
-
-## GitHub Actions
-
-`.github/workflows/build.yml` (in `src/defaults/`) runs a 3-OS matrix: macOS / Linux / Windows. Windows job uploads unsigned; a separate `windows-sign` job runs on the strategy-appropriate runner and attaches signed artifacts to the release.
-
-Env vars set globally:
-
-```yaml
-NODE_VERSION:  '22'
-OMEGA_BUILD_MODE: 'true'
-OMEGA_IS_PUBLISH: 'true'
-OMEGA_IS_SERVER:  'true'
-GH_TOKEN:      ${{ secrets.GITHUB_TOKEN }}
-```
-
-Concurrency group: `${{ github.ref }}` with `cancel-in-progress`.

package/docs/cdp-debugging.md

@@ -1,169 +0,0 @@
-# CDP Debugging (Claude ↔ Electron)
-
-@omega.js/desktop's `serve` task forwards all `--` CLI flags to the Electron child process. This enables Chrome DevTools Protocol (CDP) debugging, which lets Claude (or any CDP client) interact with the running Electron app — take screenshots, click elements, type text, evaluate JS, read console logs, inspect network requests, etc.
-
-Two ways to use it: **the built-in `npx omega cdp` toolkit** (below — zero setup, multi-target, knows @omega.js/desktop's conventions) and the `chrome-devtools-electron` MCP (further down — richer single-page interaction: click/fill/network/traces).
-
-## Launching with CDP
-
-Two equivalent ways:
-
-```bash
-# Env var (recommended)
-OMEGA_CDP_PORT=9222 npm start
-
-# CLI flag
-npm start -- --remote-debugging-port=9222
-```
-
-Both add `--remote-debugging-port=9222` to the Electron spawn args. The env var takes precedence if both are set; a CLI flag already present won't be duplicated.
-
-Verify CDP is live:
-
-```bash
-curl -s http://localhost:9222/json
-# Returns JSON array of page targets (one per BrowserWindow)
-```
-
-## The `mgr cdp` toolkit
-
-Zero-dependency subcommands for driving the running dev app — see, act, and run the no-watch iterate loop. All read `OMEGA_CDP_PORT` (default 9222), or take `--port <n>` (which wins).
-
-**Pinning a port in an npm script? Use `--port`, never `cross-env`.** `npx cross-env OMEGA_CDP_PORT=… npx omega cdp eval … "window.desktop.ipc.invoke('my:channel')"` STRIPS the inner quotes from the expression before it reaches V8 (`invoke(my:channel)` → `SyntaxError: missing ) after argument list`). `npx omega cdp eval … "…" --port <n>` keeps the expression intact.
-
-```bash
-npx omega cdp status                          # running? targets, window rect, theme
-npx omega cdp eval <match> '<expr>'           # evaluate JS in any webContents
-npx omega cdp shot <match> <out.png>          # ONE renderer's own pixels
-npx omega cdp capture <out.png>               # the COMPOSITED window (macOS)
-npx omega cdp theme <dark|light|system>       # flip the live theme (manager.theme)
-npx omega cdp relaunch                        # quit → npm start → wait for boot
-npx omega cdp quit                            # quit + wait for the process tree to drain
-```
-
-### The multi-target model
-
-An @omega.js/desktop app is one window but potentially MANY webContents (every BrowserWindow + every `WebContentsView` is its own CDP page target). Every subcommand takes a **URL-substring matcher** instead of a "current page": the main window's document is always `/views/main/` (@omega.js/desktop's templating convention); other views match by their own URLs. `status` lists what's live.
-
-```bash
-npx omega cdp eval "/views/main/" 'document.title'
-npx omega cdp eval "example.com" 'getComputedStyle(document.body).backgroundColor'
-npx omega cdp eval "/views/main/" "window.desktop.ipc.invoke('my-app:some-channel')"   # the real IPC surface
-```
-
-Promises are awaited, results print as JSON, and expressions run with a user gesture (focus()/clipboard-ish APIs behave like real input).
-
-### shot vs capture — the compositing discriminator
-
-`shot` asks ONE renderer for its own surface; `capture` photographs the window the OS composited (the BrowserWindow document + every WebContentsView stacked). They answer different questions:
-
-- Styling wrong in one view? → `shot` that target.
-- Layering/transparency/z-order wrong? → `capture`; if `shot` looks right but `capture` doesn't, the bug is in compositing, not your CSS.
-
-Caveats:
-- `shot` needs a VISIBLE surface — a hidden view (`setVisible(false)`, a background view) produces no compositor frames and the capture times out. Show/select it first.
-- `capture` raises the app and region-captures its rect — anything overlaying that region still wins. For an occlusion-proof image: `--find-window-id` (slow Swift path; JXA's CoreGraphics bridge segfaults) → `capture <out.png> --window-id <id>` (the ID is stable per window lifetime — cache it).
-- **Color profiles:** macOS embeds the MONITOR's ICC profile in screenshot PNGs; many viewers (including image previews in tooling) misrender it dramatically — an opaque dark panel can read near-white. `capture` converts every file to sRGB via `sips`, so it's portable. Hand-rolled screencaptures should do the same: `sips -m "/System/Library/ColorSync/Profiles/sRGB Profile.icc" shot.png --out shot.png`.
-- `capture`, `relaunch`, and `quit` are macOS-only (screencapture / sips / osascript). `status`/`eval`/`shot`/`theme` are cross-platform.
-
-### relaunch / quit — the iterate loop
-
-@omega.js/desktop dev has **no watch** (`npm start` builds once, then runs) — every `src/` edit needs quit → rebuild → boot. `relaunch` is that loop in one command: it quits the app (real quit — `before-quit` handlers run), waits for the **full process tree to drain** (port-down alone is NOT that signal — the npm-start chain takes a few more seconds, and a test run started inside that window gets contaminated with flaky boot suites), spawns a detached `npm start` with `OMEGA_CDP_PORT`, and waits for the boot signal. `quit` is the first half alone — safe to run `npx omega test` the moment it returns. **Never run tests while the app is going down** (a test run started before the process tree drains gets contaminated) — boot tests build into their own `.omega/test-app/` output since #110, so `dist/` itself no longer collides.
-
-The boot signal defaults to the main window's document target. Apps whose boot completes later than first paint override it in `config/omega.json5`:
-
-```json5
-cdp: {
-  readySignal: 'my-app://overlay',   // URL substring of the target that appears LAST in boot
-}
-```
-
-The packaged-app process name (for quit/raise/window-id matching) comes from config too: `app.productName` (derived from `brand.name`); dev builds run under "Electron".
-
-## Driving a regular Chrome (not the app)
-
-Sometimes the thing to drive is a regular **Chrome** — the marketing site, a web flow, an OAuth page — not the Electron app.
-
-> Mirrored across the five sister frameworks (UJM / @omega.js/backend / BXM / @omega.js/desktop / @omega.js/client) — same core section, framework-flavored. Edit all five together.
-
-Browser work runs through the **`chrome-devtools` MCP** (via mcp-router). There is NO launch procedure anymore — no ports, no profile dirs, no curl checks:
-
-- **Just call the tools** — `new_page`, `navigate_page`, `take_screenshot`, `click`, `fill`, `evaluate_script`, `list_console_messages`, `list_network_requests`. The browser auto-launches on the first call.
-- **Each Claude session gets its OWN private Chrome** (`--isolated`): temp profile, CDP over an internal pipe. Parallel sessions cannot see or touch each other's pages — open and close pages freely, the whole browser is yours.
-- **It dies with the session.** No orphans, no cleanup, nothing to kill.
-- **Ephemeral profile** — cookies/logins do NOT persist between sessions. If a flow needs auth, log in during the task.
-- **Self-signed HTTPS is pre-accepted** (`--acceptInsecureCerts` in the upstream) — dev servers load without certificate interstitials.
-- **NEVER quit/kill Chrome by app name** (`killall "Google Chrome"`, osascript) — that's the user's personal browser, not yours.
-
-Humans: the agent's Chrome window is visible — you can watch it drive. Full reference: `~/.claude/mcp-server/servers/chrome-devtools/CLAUDE.md`.
-
-@omega.js/desktop specifics:
-
-- **The Electron app stays attach-by-port** — that's the whole rest of this doc (`mgr cdp` per invocation, or the `chrome-devtools-electron` MCP below). Port convention: **9222** = the Electron app. The isolated `chrome-devtools` browser has nothing to do with the app.
-- **Navigating to a brand's UJM dev site (the local marketing site)?** **`https://localhost:4000` — NEVER the LAN IP** (`https://192.168.x.x:...`). Port 4000 by default, increments to 4001+ when multiple sites run; exact port in `.temp/_config_browsersync.yml` at the root of the WEBSITE project (the UJM consumer — e.g. `<brand>-website/.temp/_config_browsersync.yml`, NOT this app repo).
-
-## What CDP exposes
-
-- **Renderer processes only** — one "page" target per BrowserWindow. Main process is NOT exposed (use `--inspect=9229` for that, which is a separate V8 inspector protocol).
-- Each BrowserWindow appears as a separate page target. MCP tools with `list_pages`/`select_page` can switch between them.
-- Chromium silently ignores flags it doesn't recognize, so gulp's own flags (`--cwd`, `--gulpfile`) pass through harmlessly.
-
-## MCP setup (Claude ↔ Electron)
-
-A `chrome-devtools-electron` MCP upstream is configured at `~/.claude/mcp-server/servers/chrome-devtools-electron/config.json`. It reads `OMEGA_CDP_PORT` from the environment at spawn time (defaults to 9222), so the same upstream works for any Electron app — just set the env var **BEFORE launching `claude`** (it's expanded once, when the session's router spawns the upstream; mid-session changes do nothing).
-
-```json
-{
-  "enabled": true,
-  "command": "sh",
-  "args": ["-c", "exec /Users/ian/.nvm/default-bin/npx -y chrome-devtools-mcp@latest --browserUrl=http://127.0.0.1:${OMEGA_CDP_PORT:-9222} --usage-statistics=false"]
-}
-```
-
-This runs alongside the regular `chrome-devtools` upstream (which launches its own per-session isolated browser — no env vars, no ports). Tools are namespaced:
-- `chrome-devtools__take_screenshot` → the session's own Chrome browser
-- `chrome-devtools-electron__take_screenshot` → the running Electron app
-
-Multiple Claude sessions can debug different apps simultaneously — each terminal sets its own `OMEGA_CDP_PORT`. See `~/.claude/mcp-server/README.md`.
-
-### Available MCP tools (29)
-
-Screenshots, click, fill, type, hover, drag, evaluate JS, list/read console messages, list/inspect network requests, navigate, resize, keyboard input, accessibility snapshots, Lighthouse audits, performance traces, heap snapshots, dialog handling.
-
-### Session setup
-
-If the upstream was added/enabled after a Claude session started, its tools won't appear until next session. To enable mid-session:
-
-```
-# From shell
-mcp enable chrome-devtools-electron
-
-# From inside Claude (if upstream is enabled on disk but not in session)
-router__enable_upstream { name: "chrome-devtools-electron" }
-```
-
-## Port conventions
-
-| Port | Protocol | Usage |
-|------|----------|-------|
-| 9222 | CDP (HTTP + WebSocket) | Electron renderer debugging (standard CDP port) |
-| 9229 | V8 Inspector | Node.js / Electron main process debugging (`--inspect`) |
-
-Use 9222 for `--remote-debugging-port` (industry standard). Avoid 9229 — that's the Node.js inspector port and a different protocol.
-
-## Security
-
-CDP gives full control of the renderer — any local process can connect and read/modify anything. **Never ship with `--remote-debugging-port` baked in.** It's dev-only, gated behind `OMEGA_CDP_PORT` which is never set in production.
-
-## How it works
-
-`src/gulp/tasks/serve.js` collects extra args in two ways:
-
-1. **CLI flags**: `process.argv.slice(2).filter(arg => arg.startsWith('--'))` — forwards all `--` flags from the gulp process to Electron
-2. **`OMEGA_CDP_PORT` env var**: if set and no `--remote-debugging-port` is already in the args, appends `--remote-debugging-port=${OMEGA_CDP_PORT}`
-
-The args are passed to `spawn(electronBin, ['.', ...extraArgs])`. The main process boot log shows the received argv:
-
-```
-[info] (main) Initializing @omega.js/desktop (main)... argv=[".","--remote-debugging-port=9222"]
-```

package/docs/client-bridge.md

@@ -1,269 +0,0 @@
-# Client Bridge — Auth State Sync
-
-@omega.js/desktop keeps Firebase auth state in sync across all processes (main + every renderer window). The pattern mirrors BXM's background/foreground architecture: **main is the source of truth**, renderers reflect.
-
-## Why this exists
-
-In Electron, you can't just initialize Firebase in the renderer and forget about it:
-
-- Multiple renderer windows would each have their own Firebase instance with no coordination.
-- Main-process code (tray, menu, deep-link routes) needs to know who's signed in.
-- A deep-link auth-token (`myapp://auth/token?token=...`) arrives in main, but the user's UI lives in the renderer — somebody has to bridge them.
-
-The bridge handles all three.
-
-## How it works
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  MAIN (client-bridge.js)                               │
-│  - Owns Firebase Auth instance ("omega-auth" app)              │
-│  - Source of truth for auth state                           │
-│  - Listens for desktop:auth:* IPC from renderers                 │
-│  - Broadcasts desktop:auth:* IPC to all renderers on changes     │
-└─────────────────────────────────────────────────────────────┘
-              ▲                     │ broadcasts
-              │ sync-request        ▼
-┌──────────────────────────┐  ┌──────────────────────────┐
-│  RENDERER (window 1)     │  │  RENDERER (window 2)     │
-│  @omega.js/client + Firebase  │  │  @omega.js/client + Firebase  │
-└──────────────────────────┘  └──────────────────────────┘
-```
-
-### Auth flow: deep-link → all processes signed in
-
-**Consumers never collect credentials.** There is no login form to build — call `manager.openAuthFlow()` (documented in `lib/auth-flow.js`), which opens the brand website's sign-in page in the user's browser and receives the result through the deep link below.
-
-1. User signs in on the website. Web-manager generates a custom token. Website opens `myapp://auth/token?token=XYZ` (deep link).
-2. @omega.js/desktop's deep-link `auth/token` built-in fires `manager.omega.handleAuthToken(token)`.
-3. Main calls `signInWithCustomToken(auth, token)` against its own Firebase Auth → main is now signed in.
-4. Main broadcasts `desktop:auth:sign-in-with-token` IPC with the same token to all renderer windows.
-5. Each renderer receives the broadcast, calls `omega.auth().signInWithCustomToken(token)` against its own (@omega.js/client-managed) Firebase Auth → all renderers signed in with the same user.
-6. Tokens are NOT stored — they expire in 1 hour. Auth state persists via Firebase's built-in IndexedDB persistence.
-
-### Auth flow: renderer load → sync with main
-
-When a renderer window opens (cold or warm), it asks main for the current state:
-
-1. Renderer sends `desktop:auth:sync-request` IPC with its current UID (or null).
-2. Main compares with its own UID:
-   - **Same UID** → no sync needed, returns `{ needsSync: false }`.
-   - **Main signed out, renderer signed in** → returns `{ needsSync: true, signOut: true }`. Renderer signs out.
-   - **Main signed in, renderer not (or different user)** → main fetches a fresh custom token from `POST ${apiUrl}/omega/user/token` (responds `{ token }`) and returns `{ needsSync: true, customToken, user }`. Renderer signs in with that token.
-
-### Sign-out flow
-
-Any renderer (or main code) calls `manager.omega.signOut()`:
-
-1. Main signs out its own Firebase.
-2. Main broadcasts `desktop:auth:sign-out` IPC to all renderers.
-3. Each renderer signs out its own Firebase.
-
-## Public API
-
-### Main process (`manager.omega`)
-
-```js
-// Sign in via a custom token (called automatically by the auth/token deep-link route).
-await manager.omega.handleAuthToken(token);
-
-// Read the currently signed-in user (snapshot, no sensitive fields).
-manager.omega.getCurrentUser();
-//   → { uid, email, displayName, photoURL, emailVerified } | null
-
-// Fresh Firebase ID token for calling authenticated backend routes from main
-// (send as `Authorization: Bearer <token>`). null when signed out.
-await manager.omega.getIdToken();
-
-// Subscribe to auth state changes (e.g. to refresh tray/menu items).
-const off = manager.omega.onAuthChange((user) => {
-  manager.tray.refresh();
-  manager.menu.refresh();
-});
-off();   // unsubscribe
-
-// Sign out from any process.
-await manager.omega.signOut();
-
-// The renderer-resolved subscription — THE main-side plan source. Renderers run
-// @omega.js/client's full auth cycle (Firestore account fetch → resolveSubscription)
-// and push the result to main (desktop:auth:account-resolved, uid-guarded); main can't
-// run Firestore itself. null until a renderer has resolved.
-manager.omega.getResolvedPlan();
-//   → { plan, active, trialing, cancelling } | null
-manager.omega.getResolvedRoles();
-//   → { admin, betaTester, ... } | null
-```
-
-### Renderer process (the @omega.js/desktop Manager you `initialize()`)
-
-```js
-// Read the user from main (always returns main's authoritative state).
-const user = await renderer.getMainUser();
-
-// Sign out (goes through main; broadcasts to all other renderers).
-await renderer.signOut();
-```
-
-The renderer's `Manager.initialize()` automatically:
-- Boots @omega.js/client (so renderer-side Firebase is available).
-- Wires the auth bridge (`desktop:auth:sync-request` on load + listens for broadcasts).
-- Runs @omega.js/client's **full auth cycle** (`auth().listen()`): waits for auth to settle,
-  fetches the Firestore account, resolves the subscription, and auto-populates the
-  **`data-omega-bind` bindings** — so @omega.js/desktop app views can use UJM/BXM-style reactive HTML
-  (`@show auth.user`, `@text auth.account.plan.id`, `@show auth.account.plan.id === 'premium'`,
-  see @omega.js/client's docs/bindings.md). Each settle pushes `{ resolved, roles }` to main
-  (`desktop:auth:account-resolved`) and re-offers it whenever main announces a state change,
-  so a renderer that resolved before main signed in still delivers.
-
-You don't write any of this — it just works.
-
-## Session persistence (main)
-
-Renderers persist their Firebase sessions in IndexedDB for free (browser contexts).
-Main is Node — Firebase defaults to in-memory there — so @omega.js/desktop plugs in its own vault:
-**`lib/auth-persistence.js`**, a PLUGGABLE strategy behind a custom Firebase
-`Persistence` (the `getReactNativePersistence()` shape).
-
-- **`safeStorage`** (default) — values encrypted via Electron `safeStorage` (macOS
-  Keychain / Windows DPAPI / kwallet-gnome) before touching disk
-  (`{userData}/omega-auth-session.json` holds base64 ciphertext only). This is the same
-  os_crypt machinery Chromium uses for its cookie jar — stronger than browser
-  IndexedDB/localStorage, which are plaintext LevelDB on disk.
-- **`none`** — explicit opt-out (in-memory, pre-1.12 behavior).
-- **Custom** — `require('@omega.js/desktop/lib/auth-persistence').register(name, { available, getItem, setItem, removeItem })` before `initialize()`, then select it via config.
-
-```jsonc
-{
-  "omega": {
-    "authPersistence": "safeStorage"   // 'safeStorage' (default) | 'none' | custom name
-  }
-}
-```
-
-A TEST RUN is always `none`, whatever this config says, on the main and boot layers
-alike: the harness never signs a real user in, so it never asks the OS keychain
-([#907](https://github.com/Omega-JS-Stack/omega/issues/907), the mechanics in
-[test-framework.md](test-framework.md)).
-
-Storage only — distribution across processes stays the IPC sync protocol above.
-The session restores at boot (offline included: no network round trip), so a restart
-keeps the user signed in; renderers then re-resolve the account and re-push the plan.
-
-## Config
-
-```jsonc
-{
-  "cloud": {
-    "provider": "firebase",
-    "config": {
-      "apiKey":            "...",
-      "authDomain":        "myapp.com",
-      "projectId":         "myapp",
-      // ... etc.
-    }
-  }
-}
-```
-
-If `cloud.config` is empty/missing, the bridge logs a warning and runs in no-op mode (everything returns harmless defaults).
-
-## Firebase (bundled)
-
-Firebase is **bundled from @omega.js/desktop's module context** (@omega.js/client owns it in @omega.js/desktop's dependency tree) — the same treatment `json5` gets in main. It was previously runtime-resolved, which silently failed in every symlinked dev app (see CHANGELOG 1.11.1).
-
-If you're building a no-auth Electron app, just leave `cloud.config` empty — the bridge is a clean no-op.
-
-In a TESTING run (`OMEGA_ENVIRONMENT=testing`) the bridge connects its auth instance to the local auth emulator, on the port it reads in three steps: `OMEGA_AUTH_PORT` when the CLI that booted the stack published one, then the `dev.ports.auth` value the bundle baked into `OMEGA_BUILD_JSON` (a packaged main process has no parent env, [#745](https://github.com/Omega-JS-Stack/omega/issues/745)), then the classic `9099`. Same chain `getApiUrl()` walks ([environment-detection.md](environment-detection.md)) and the same move it makes when it maps testing to localhost, and the same one @omega.js/extension's background worker makes for its emulator runs; development and production are untouched.
-
-## Common patterns
-
-### Refresh tray when auth state changes
-
-```js
-// In src/tray/index.js or wherever you have access to manager:
-manager.omega.onAuthChange((user) => {
-  manager.tray.refresh();   // re-evaluates dynamic labels
-});
-```
-
-```js
-// In src/tray/index.js:
-tray.item({
-  label: () => {
-    const user = manager.omega.getCurrentUser();
-    return user ? `Signed in as ${user.email}` : 'Sign in';
-  },
-  click: () => {
-    if (manager.omega.getCurrentUser()) {
-      manager.omega.signOut();
-    } else {
-      require('electron').shell.openExternal(`${manager.config.brand.url}/sign-in?desktop=true`);
-    }
-  },
-});
-```
-
-### Gate a deep-link route on auth
-
-```js
-manager.deepLink.on('user/profile/:id', (ctx) => {
-  if (!manager.omega.getCurrentUser()) {
-    require('electron').shell.openExternal(`${manager.config.brand.url}/sign-in?return=profile/${ctx.params.id}`);
-    ctx.handled = true;
-    return;
-  }
-  manager.windows.show('main');
-  manager.windows.get('main').webContents.send('navigate', { to: `/profile/${ctx.params.id}` });
-});
-```
-
-### Sign-out button in a renderer
-
-```html
-<button id="signout">Sign out</button>
-<script>
-  document.getElementById('signout').addEventListener('click', async () => {
-    await renderer.signOut();   // goes through main, propagates everywhere
-  });
-</script>
-```
-
-## IPC channels
-
-| Channel | Direction | Payload | Description |
-|---|---|---|---|
-| `desktop:auth:sync-request` | renderer → main | `{ contextUid }` | "I'm at this UID, are we in sync?" |
-| `desktop:auth:sign-out` | renderer → main | (none) | "Sign me (and everyone) out." |
-| `desktop:auth:get-user` | renderer → main | (none) | Read main's current user. |
-| `desktop:auth:sign-in-with-token` | main → all renderers | `{ token }` | "Sign in with this custom token now." |
-| `desktop:auth:sign-out` | main → all renderers | `{}` | "Sign out now." |
-| `desktop:auth:state-changed` | main → all renderers | `{ uid, email, ... } \| null` | Auth state changed (informational). |
-
-## Testing
-
-### Unit tests (always run)
-
-`client-bridge.test.js` covers the dispatch logic, IPC handler shape, sync-request comparison, and the `auth/token` deep-link integration — all without hitting Firebase.
-
-### The real-surface e2e lane (monorepo root)
-
-`npm run test:e2e-desktop` ([scripts/e2e-desktop-auth.js](../../../scripts/e2e-desktop-auth.js)) boots a real Electron app against the backend emulator and delivers `<brand.id>://auth/token` from a SECOND instance — the OS-forwarded argv path — then asserts main AND the renderer both land on the emulator user. Offline; it is the lane that proves this whole chain end to end.
-
-### Extended tests (skip without the opt-in)
-
-`client-bridge.integration.test.js` talks to REAL Firebase, so it is gated behind extended mode (the cross-framework `TEST_EXTENDED_MODE` opt-in; see [test-framework.md](test-framework.md#extended-vs-normal-mode)):
-
-```bash
-npx omega test --extended                                   # or: TEST_EXTENDED_MODE=true npx omega test
-```
-
-It asks for NO credential of its own ([#819](https://github.com/Omega-JS-Stack/omega/issues/819), Ian 2026-09-13): the service-account path and the test uid it used to mint a custom token from are retired env keys now. The SIGN-IN proof belongs to [#904](https://github.com/Omega-JS-Stack/omega/issues/904), which signs desktop in as a persona the backend emulator seeds, the same mechanism web and the extension use. Without the opt-in the suite skips cleanly with a reason, so CI stays green.
-
-## Implementation notes
-
-- Firebase app name in main is `omega-auth` (avoids clashes if a consumer's main code also wants its own Firebase instance).
-- The bridge does NOT persist user info to @omega.js/desktop storage — Firebase's IndexedDB persistence handles session restoration. Matches BXM.
-- Custom tokens are NEVER stored. Renderers receive them once via broadcast, sign in, discard. Fresh tokens are minted on demand from `POST /omega/user/token` via @omega.js/client's shared request layer (`createRequest` from `@omega.js/client/modules/request.js`) — same code path as the extension background's token sync.
-- `manager.getApiUrl()` returns the dev or prod URL, so the bridge automatically hits the right backend. Available across all four Manager contexts (main / renderer / preload / build) via the shared `src/utils/url-helpers.js` module — same code path everywhere. See the Cross-context helpers section of the framework guide ([docs/desktop/index.md](../../../docs/desktop/index.md)).
-- All sensitive Firebase user fields (`stsTokenManager`, `providerData`, etc.) are stripped before sending over IPC. Only `{uid, email, displayName, photoURL, emailVerified}` cross the bridge.

package/docs/common-mistakes.md

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