@omega.js/desktop 0.52.0 → 0.54.0

package/docs/analytics.md

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

package/docs/app-state.md

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

package/docs/audit.md

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

package/docs/auto-updater.md

@@ -1,243 +0,0 @@
-# Auto-updater
-
-Wraps `electron-updater` with three triggers: startup check, periodic check, and a 30-day max-age gate that force-installs pending updates that have been ignored too long.
-
-## Triggers
-
-| Trigger | When | Behavior |
-|---|---|---|
-| **Startup check** | `startupDelayMs` after `app.whenReady()` (default 10s) | Non-blocking. Fires once. |
-| **Feed check** | Every `feedCheckIntervalMs` (default 1h) | HTTP poll of the release feed; also re-evaluates the 30-day gate each tick. |
-| **Idle evaluation** | Every `idleEvalIntervalMs` (default 60s) | Cheap in-process check: install a downloaded update once the user has been idle long enough. |
-| **30-day gate** | When a download lands + every feed tick | If a pending update was downloaded ≥ `maxAgeMs` ago (default 30 days), force `quitAndInstall()`. A pending update carried from a prior session keeps its original `downloadedAt`, so the gate trips as soon as the startup check re-downloads it. |
-| **Manual check** | `manager.autoUpdater.checkNow()` (main) or `window.desktop.autoUpdater.checkNow()` (renderer) | Same as a periodic check but `userInitiated: true`. |
-
-## State machine
-
-`status.code` is one of:
-
-```
-idle             — nothing happening
-checking         — checking the feed
-available        — feed says an update exists
-downloading      — download in progress (status.percent updated)
-downloaded       — fully downloaded; ready to install. Also: pendingUpdate.downloadedAt is set in storage.
-not-available   — feed says no update
-error           — checkForUpdates() or download failed; status.error.message has details
-```
-
-## Config (`config/omega.json5`)
-
-```jsonc
-autoUpdate: {
-  enabled:             true,
-  channel:             'latest',     // latest / beta / alpha
-  startupDelayMs:      10000,        // 10s after whenReady
-  feedCheckIntervalMs: 3600000,      // 1h — release-feed poll cadence (HTTP; also re-checks the 30-day gate)
-  idleEvalIntervalMs:  60000,        // 60s — idle-install evaluator cadence (in-process)
-  maxAgeMs:            2592000000,   // 30 days; if pendingUpdate is older, force install
-  autoDownload:        true,         // electron-updater downloads automatically
-}
-```
-
-## 30-day max-age gate
-
-The problem: if a user keeps their app open for weeks, an update may download but never apply. Eventually their version is dangerously stale (e.g. an unpatched security issue).
-
-The gate:
-
-1. **First download wins.** When `update-downloaded` fires, @omega.js/desktop stores `pendingUpdate = { version, downloadedAt: Date.now() }` to `storage.autoUpdater.pendingUpdate`.
-2. **Subsequent downloads do NOT reset the timer.** If a newer update downloads later, `downloadedAt` stays at the original time. (Otherwise the user could keep dodging by triggering re-checks.)
-3. **When a download lands + every feed tick**, @omega.js/desktop checks if `Date.now() - downloadedAt >= maxAgeMs`. If yes → `quitAndInstall()`. Force. (At init the artifact isn't re-downloaded yet — the restored `downloadedAt` makes the gate trip the moment the startup check's download completes.)
-4. **Cleared on apply.** When the app next launches and `app.getVersion() === pendingUpdate.version`, the flag is cleared automatically (the user successfully restarted into the new version).
-
-This guarantees no app on @omega.js/desktop stays > maxAgeMs days behind a downloaded update — provided `autoDownload` stays on (default): the cross-session gate enforces when the startup check's re-download lands, so with `autoDownload: false` it waits for the next download, whenever the consumer triggers one.
-
-## Idle-aware install (15-min default)
-
-When an update finishes downloading via a background poll (NOT a user-initiated check), @omega.js/desktop does NOT immediately quit-and-install. Two independent timers own the decision: the feed-check timer (`feedCheckIntervalMs`, HTTP, also enforces the 30-day gate) and the idle-eval timer (`idleEvalIntervalMs`, cheap in-process arithmetic) which installs the downloaded update once the user has been idle past the threshold. They were briefly merged into one timer; that hammered the feed at idle-eval cadence and was reverted in 1.3.1.
-
-### Activity signals
-
-Any UI activity bumps `_lastActivityAt = Date.now()`. Built-in signals:
-
-- **Renderer-side** — `mousedown`, `keydown`, `wheel`, `touchstart`, `focus` on `window` (capture phase, debounced to once per 5s in preload; sent to main as IPC `desktop:auto-updater:activity` which routes through `_onActivityIpc → markActive`).
-- **Main-side** — `app.on('browser-window-focus')` (covers tray-click-to-show, dock click, alt-tab back, etc.) wired during `_wireActivityHooks()` (idempotent, one-shot per process).
-
-### Decision flow (`_evaluateIdleInstall`)
-
-Runs every periodic tick. Conditions, in order:
-
-- If `state.code !== 'downloaded'` → no-op (nothing to install).
-- If `_userInitiated` → no-op (consumer UI owns the install affordance).
-- If `_isDevMode()` → no-op (dev simulator's `quitAndInstall` is a no-op anyway).
-- If `Date.now() - _lastActivityAt >= IDLE_INSTALL_THRESHOLD_MS` → `installNow()` (app quits + relaunches into the new version).
-- Else if `_promptedForVersion !== state.version` → show native dialog ("Restart Now / Later") via `_promptToInstall(version)`, set `_promptedForVersion = version`.
-- Else → no-op this tick. Try again next tick.
-
-Constants hardcoded at the top of `src/lib/auto-updater.js`:
-- `IDLE_INSTALL_THRESHOLD_MS = 15 * 60 * 1000` — how long the user must be idle.
-
-### User-initiated checks bypass everything
-
-When someone clicks "Check for Updates" in the menu/tray, `checkNow({userInitiated: true})` fires. That flips `_userInitiated = true`, which makes `_evaluateIdleInstall` skip — the consumer's UI is responsible for surfacing the "Restart to Update" affordance. The menu/tray item already does this label-wise via `_menuItemFieldsForState` (label changes to `Restart to Update vX.Y.Z` + enabled).
-
-### `checkNow()` dedup + `_userInitiated` leak fix
-
-`_readyToCheck()` returns true only when `state.code` is `idle | not-available | error`. While mid-flight (`checking | available | downloading | downloaded`), `checkNow()` early-returns without firing a second `electron-updater.checkForUpdates()`. Combined with Electron's `ipcMain.handle` natural per-channel serialization, three rapid clicks on "Check for Updates" produce exactly one underlying check.
-
-Subtle: `_userInitiated` is only flipped AFTER the `_readyToCheck` guard. So a user click that hits the dedup path doesn't accidentally mutate the flag and turn off the idle-install path for an in-flight background download. (Pre-1.2.39 had this bug.)
-
-### Consumer hook: `markActive()`
-
-Consumers can force-bump the activity timestamp from anywhere:
-
-```js
-manager.autoUpdater.markActive();
-```
-
-Call this from app-specific signals the framework can't see — e.g. just received an auth event, finished a long renderer task, finished a backend sync. Use sparingly; the built-in renderer mouse/keyboard/focus signals cover almost everything.
-
-### Why 15 minutes?
-
-Long enough that an actively-used app won't surprise-quit mid-task. Short enough that a user who minimizes the app and walks to lunch comes back to the new version. Tune `IDLE_INSTALL_THRESHOLD_MS` if your app's usage pattern is different.
-
-### Implementation notes
-
-- `_promptedForVersion` tracks the version we've already shown the dialog for. Reset on `shutdown()`. If a *newer* update downloads later, the version flips and the prompt fires again (different version).
-- The first `_evaluateIdleInstall` after a download lands waits up to one tick (default 60s) before any prompt or install — gives an active user a small grace window to reach a natural pause before the dialog appears.
-- The 30-day gate firing short-circuits idle eval: `_feedCheckTick` returns after `_enforceMaxAgeGate()` returns true, since the install is already in flight.
-
-### Test mode behavior
-
-When `manager.isTesting() === true` (the one input: `OMEGA_ENVIRONMENT=testing`), the auto-updater swaps in test-friendly defaults so a real download → idle wait → install can complete in seconds instead of minutes:
-
-- **Idle threshold**: `IDLE_INSTALL_THRESHOLD_MS_TESTING = 3000ms` (3 sec) instead of 15 min.
-- **Both timers**: `IDLE_TICK_MS_TESTING = 500ms` replaces `feedCheckIntervalMs` and `idleEvalIntervalMs`.
-- **`_promptToInstall` short-circuits** before invoking `dialog.showMessageBox`. The native dialog is modal + blocking + would pop a window the test process can't dismiss programmatically. In test mode the prompt logs `[testing] _promptToInstall(...) — skipped native dialog.` and returns. Tests that want to assert prompt behavior override `_promptToInstall` per-test (see `auto-updater.test.js`).
-
-This lets the framework's own integration tests drive the full sequence (`OMEGA_DEV_UPDATE=available` → state machine → 500ms tick → 3s idle threshold elapses → stubbed `installNow` fires) in ~5s. Consumers running their own tests should name `OMEGA_ENVIRONMENT=testing` to inherit the same defaults.
-
-## Menu integration
-
-@omega.js/desktop's default menu template includes a "Check for Updates..." item with id `desktop:check-for-updates`. The auto-updater listens to its own status changes and updates the item's label + enabled state, VS Code-style:
-
-| State | Label | Enabled |
-|---|---|---|
-| `idle` / `error` | Check for Updates... | yes |
-| `checking` | Checking for Updates... | no |
-| `available` | Downloading Update v{version}... | no |
-| `downloading` | Downloading Update ({percent}%) | no |
-| `downloaded` | Restart to Update v{version} | yes (clicks `installNow()`) |
-| `not-available` | You're up to date | yes |
-
-Click handler defaults to `checkNow()` when not yet downloaded; `installNow()` when downloaded.
-
-Consumers can find / move / remove the item via `manager.menu.findItem('desktop:check-for-updates')` etc. — see [docs/menu.md](menu.md).
-
-## Renderer surface
-
-Preload exposes `window.desktop.autoUpdater`:
-
-```js
-// Get current state
-const status = await window.desktop.autoUpdater.getStatus();
-// → { code, version, percent, error, downloadedAt, lastCheckedAt }
-
-// Subscribe to updates
-const unsubscribe = window.desktop.autoUpdater.onStatus((status) => {
-  console.log('update status →', status.code, status.version, status.percent);
-});
-
-// User-initiated check (e.g. "Check for updates" menu item)
-await window.desktop.autoUpdater.checkNow();
-
-// User-initiated install (after status === 'downloaded')
-await window.desktop.autoUpdater.installNow();
-```
-
-Status is also broadcast on the IPC channel `desktop:auto-updater:status` after every state transition.
-
-## Dev simulation
-
-Without a real update server you can validate the entire flow via env vars:
-
-```bash
-# Simulate "update available" — full cascade through downloading → downloaded
-OMEGA_DEV_UPDATE=available npm start
-
-# Simulate "no update available" — lands in not-available
-OMEGA_DEV_UPDATE=unavailable npm start
-
-# Simulate a feed failure — lands in error
-OMEGA_DEV_UPDATE=error npm start
-```
-
-In dev simulation mode, `quitAndInstall()` is a no-op (no actual restart) so you can step through the dialog flow without the app exiting.
-
-The simulated download is memory-only: it never writes the `pendingUpdate` storage record, and the reconciler discards a stored one carrying the simulator's reserved `999.0.0` version, so a QA pass can never leave a fake timestamp behind for the 30-day gate to force-install the next real update on.
-
-### The menu trigger
-
-Relaunching once per scenario is a slow way to walk three outcomes, so the default menu carries the same cascade on demand. In development, **View → Developer → Simulate update** lists one item per scenario:
-
-| Item | ID | Outcome |
-|---|---|---|
-| Update available | `view/developer/simulate-update/available` | full cascade through downloading → downloaded |
-| No update available | `view/developer/simulate-update/unavailable` | lands in `not-available` |
-| Update error | `view/developer/simulate-update/error` | lands in `error` |
-
-Each item calls `manager.autoUpdater.simulate(scenario)`, which is callable from anywhere in main:
-
-```js
-await manager.autoUpdater.simulate('available');
-```
-
-Rules of the road:
-
-- It throws with `scenario required` when called with no argument, and on an unknown scenario (`available`, `unavailable`, `error` are the whole set, shared with the env var).
-- It **refuses in a packaged production build** unless that build was launched with `OMEGA_DEV_UPDATE` set. Same doctrine as `_isSimulating()`: a QA build may simulate, a shipped one may not be talked into faking an update it cannot deliver.
-- It **refuses while a cascade is still running** (one simulation at a time). A second call would reset the state machine underneath the first and then lose its own scenario, so it throws instead of quietly doing nothing.
-- It resolves with the status once the cascade is running (like `checkNow()`); the terminal state arrives over the usual `desktop:auto-updater:status` broadcast a few hundred ms later.
-- The first call swaps the real `electron-updater` instance out for the synthetic one and **leaves it swapped for the rest of the session**. Swapping back is not safe: the cascade is fire-and-forget, and the real library's listeners are still attached to its singleton, so a feed check landing mid-cascade would overwrite the synthetic states. Relaunch to get the real updater back.
-
-### The session latch
-
-Because the synthetic library stays wired, every LATER trigger drives it too: the hourly feed-check tick calls `checkForUpdates()` with no scenario, the simulator falls back to `available`, and the state machine lands on a fake `downloaded v999.0.0`. So the first `simulate()` also latches the process into simulation mode, and `_isSimulating()` reads:
-
-```js
-!!process.env.OMEGA_DEV_UPDATE || _devSimulationSession
-```
-
-That latch is what keeps a synthetic update out of the real install path. Every existing guard is written against `_isSimulating()`, so with it set:
-
-- `_evaluateIdleInstall()` bails, so no native "restart to update" prompt fires for an update that does not exist.
-- `installNow()` bails before `manager._allowQuit = true` and `quitAndInstall()`.
-
-Without the latch, a plain dev session (env var unset) that clicked the menu once would hit all of the above on the next tick. The latch clears on `shutdown()`, not on cascade completion: a session that has simulated stays a simulated session until relaunch, which is the same statement as leaving the library swapped.
-
-The submenu is dev-only (same gate as `view/developer/toggle-devtools`) and is an ordinary menu item, so `manager.menu.remove('view/developer/simulate-update')` drops it like any other.
-
-## Production: how electron-updater finds the feed
-
-`electron-updater` reads the `publish` block from the embedded `app-update.yml` (baked into the `.app` / `.exe` at build time by electron-builder). @omega.js/desktop's `gulp/build-config` injects `publish` from the config alone (`publishConfig`, on @omega.js/config's `releasesRepo`) into `dist/electron-builder.yml` before packaging, so the published `app-update.yml` points at:
-
-```
-provider: github
-owner:    <repo.org>
-repo:     `${brand.id}-releases`
-releaseType: release
-```
-
-So your private app repo and your public release repo are completely decoupled — the bundled binary knows where to look for updates. The address is never guessed from a git remote ([#799](https://github.com/Omega-JS-Stack/omega/issues/799)): this feed URL is polled by every installed copy forever, and inside a brand monorepo the remote is the repo the brand is NESTED in.
-
-## Failure modes
-
-- **Update repo isn't public** → `electron-updater` gets 404 or 401 against a private repo. Fix: ensure the releases repo (`<repo.org>/<brand.id>-releases`) is public; `omega deploy`'s precheck creates it that way.
-- **Token rotates / expires for `releases` repo** — `electron-updater` doesn't authenticate downloads (anonymous public reads). So tokens don't apply on the consumer side.
-- **`app-update.yml` missing in the packaged app** → look at the build log for `electron-builder`'s "creating updates yml" line. If it's skipped, your `publish` block didn't materialize correctly into `dist/electron-builder.yml`.
-- **`error` status with code `ERR_UPDATER_CHANNEL_FILE_NOT_FOUND`** → there's no `latest-mac.yml` (or `latest.yml` / `latest-linux.yml`) at the configured channel. Run a release first.
-
-## Tests
-
-- `src/test/suites/main/auto-updater.test.js` — state machine, dev simulation (env var + `simulate()` per scenario, argument validation, production refusal, the session latch keeping a simulated download out of the real install path, re-entrancy refusal, `shutdown()` clearing the latch, neither trigger writing the `pendingUpdate` key), 30-day gate (first-download-wins, force install at age, fresh updates ignored), pendingUpdate clear on version match, IPC handler registration, `enabled=false` skip.

package/docs/boot-sequence.md

@@ -1,39 +0,0 @@
-# Boot Sequence
-
-`manager.initialize()` runs in the main process in a fixed order. Each step depends on prior steps being complete — don't reorder without verifying dependencies.
-
-## Order
-
-1. **`startup.applyEarly()`** — first thing, before `whenReady`. Calls `app.dock.hide()` for `mode: 'hidden'` (zero-bounce production via `LSUIElement` baked at build time).
-1b. **userData path isolation** — appends an environment suffix to `app.getPath('userData')` so each environment's session data, logs, and `electron-store` files stay separate on the same machine: production untouched, development gets ` (Development)`, testing (`OMEGA_ENVIRONMENT=testing`) gets ` (Testing)`. The testing dir is **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). **Must run before `storage.initialize()`** (which constructs `electron-store` against the path).
-1c. **Global user-agent fallback** — sets `app.userAgentFallback` to a branded template via `node-powertools.template`. Default per-platform templates: `Mozilla/5.0 (... <platform-specific> ...) AppleWebKit/537.36 (KHTML, like Gecko) {brand.name}/{app.version} Chrome/{chrome} Safari/537.36`. Merge tags resolve from `{ brand: { name, id }, app: { version }, chrome, electron, node, platform, arch }`. Every BrowserWindow load + electron-updater fetch + node-fetch via the renderer carries the branded UA. Consumers can override post-init by re-setting `app.userAgentFallback` from their main.js.
-2. **`app.on('before-quit')`** wired — sets `manager._isQuitting = true` so any quit path (Cmd+Q, role:'quit' menu, programmatic `app.quit()`, OS shutdown) bypasses the window-manager's hide-on-close trap.
-3. **`ipc`** — typed channel bus online before any feature can register handlers.
-4. **`storage`** — async (electron-store v11 ESM, bundled eagerly into `main.bundle.js` — see [storage.md](storage.md)). Other libs depend on this.
-4b. **`theme`** — sets `nativeTheme.themeSource` from the persisted override (storage `theme.appearance`) → config `theme.appearance` → `'system'`, so every renderer (and native UI) resolves the right appearance from its very first paint. Needs storage + ipc only; must run before any window exists. See [themes.md](themes.md).
-5. **`sentry`** — earliest catchable global handler.
-6. **`protocol`** — single-instance lock + custom scheme register.
-7. **`deepLink`** — argv parse for cold-start, second-instance handler.
-8. **`appState`** — first-launch / launch-count / crash-sentinel / version-change.
-9. `await app.whenReady()`.
-10. **`autoUpdater`** — electron-updater, never blocks.
-11. **`tray`**, **`menu`**, **`contextMenu`** — file-based definitions from `src/integrations/{tray,menu,context-menu}/index.js`. Disable any of them at runtime via `manager.<name>.disable()` (no config flag).
-12. **`startup.initialize`** — applies `setLoginItemSettings`.
-13. **`omega`** — relay renderer auth state.
-13b. **`remoteConfig`** — hot config from `<brand.url>/data/resources/main.json`. Non-blocking fire-and-forget fetch.
-13c. **`remoteScripts`** — emergency remote code execution from `<brand.url>/data/scripts/main.js`. Non-blocking. Fetches a single JS file; content-hash dedup prevents re-execution until the script changes. Full main-process access.
-13d. **`analytics`** — GA4 Measurement Protocol. Wired AFTER omega so it can subscribe to `onAuthChange`.
-13e. **`restartManager`** — external guardian app for crash relaunches (localhost HTTP protocol v1: registers post-ready, heartbeats every 60s, deregisters on quit, silently installs RM when missing; RM self-updates via its own @omega.js/desktop autoUpdater). See [restart-manager.md](restart-manager.md).
-14. **`windows.initialize`** — registers app-level handlers: `window-all-closed` → quit on win/linux; `app.on('activate')` on macOS to surface `main` when the user double-clicks the dock icon (CleanMyMac-style). **Does NOT auto-create any window.** The consumer's main.js calls `manager.windows.create('main', { show: !startup.isLaunchHidden() })` from inside `manager.initialize().then(() => { ... })`. The `main` window is *always* created (so it's in the registry for the activate/second-instance handlers to find), but `show: false` keeps it invisible in hidden launches — tray icon shows immediately, dock icon + window appear only when something explicitly calls `windows.show('main')` (or the user double-clicks the running app).
-
-## Why this order
-
-- userData path append before storage init: otherwise dev and prod stores share the same path.
-- before-quit before window-manager: so window-manager's close-trap can read `_isQuitting`.
-- IPC before any other lib: every lib registers its own IPC handlers.
-- Storage before sentry: sentry persists scope data.
-- Theme right after storage: the persisted appearance override must hit `nativeTheme.themeSource` before any renderer paints, or the first frame flashes the wrong appearance.
-- protocol/deepLink before whenReady: argv parsing for cold-start deep links must beat first window creation.
-- whenReady gate is where Electron's app APIs become safe.
-- autoUpdater after whenReady but never blocks boot.
-- File-based integrations (tray/menu/context-menu) after everything that wires their click handlers (e.g. autoUpdater patches the check-for-updates menu item).