@omega.js/desktop 0.1.0

package/docs/startup.md

@@ -0,0 +1,142 @@
+# Startup
+
+Controls how the app launches: full normal launch vs completely hidden background app. Also handles open-at-login.
+
+## Config
+
+```jsonc
+"startup": {
+  "mode": "normal",                // user-launch behavior: 'normal' | 'hidden'
+  "openAtLogin": {
+    "enabled": true,               // OS auto-launches the app at login
+    "mode":    "hidden"            // login-launch behavior (defaults to 'hidden')
+  }
+}
+```
+
+`mode` is what happens when **the user launches the app directly** (clicks the dock icon / Start menu / etc.).
+
+`openAtLogin.mode` is what happens when **the OS auto-launches the app at login**. It applies *only* when the launch is detected as a login-launch (macOS: `wasOpenedAtLogin` flag; Windows/Linux: presence of the `--omega-launched-at-login` arg @omega.js/desktop passes when registering the login item).
+
+The default behavior — `mode: 'normal'` + `openAtLogin: { enabled: true, mode: 'hidden' }` — means: the app auto-starts at login but stays out of the way until the user opens it themselves. User-direct launches show the main window like any normal app.
+
+## Modes
+
+### `normal` (default)
+
+Standard app behavior. Your `main.js` calls `windows.create('main', { show: !startup.isLaunchHidden() })` from inside `manager.initialize().then(...)`. In `normal` mode, `show` is `true` so the window appears immediately. Dock visible (macOS), taskbar entry (win/linux).
+
+### `hidden`
+
+App launches **completely invisible**: no dock icon, no Cmd+Tab presence, no taskbar entry. Tray + notifications + networking + IPC + auto-update all still work — only the visible UI is suppressed. Production builds inject `LSUIElement: true` into `Info.plist` (via `gulp/build-config`) so macOS treats the process as a background agent from launch — **zero dock bounce**.
+
+The `main` window is still created (just with `show: false`) so it sits in @omega.js/desktop's window registry. When the user double-clicks the running app's icon, @omega.js/desktop's `app.on('activate')` (macOS) / `app.on('second-instance')` (win/linux) handler finds `main` in the registry and calls `windows.show('main')` — which auto-runs `app.dock.show()` so the dock icon appears alongside the window. Same thing happens when the consumer manually surfaces UI from a tray click / deep-link / IPC event via `windows.show('main')`. The reverse is automatic too: hiding the last visible window (including the hide-on-close X) re-runs `app.dock.hide()`, so a hidden-mode app never strands a dock icon after its UI is dismissed.
+
+Use this for: menubar apps, agent apps (clipboard managers, time trackers, system monitors), apps that should be invisible at boot but available on demand.
+
+**Dev caveat**: in dev (`npm start` / `electron .`), the packaged `Info.plist` isn't in effect, so macOS will still briefly bounce. Production builds (`npm run build` / `npm run release`) get the real zero-bounce behavior.
+
+> **Note:** the deprecated `'tray-only'` mode is no longer valid — its behavior was always identical to `'hidden'`, so they've been folded into one. Old `tray-only` configs fall back to `'normal'` per `getMode()` validation.
+
+## Public API on `manager.startup`
+
+```js
+manager.startup.getMode()                  // user-launch mode: 'normal' | 'hidden'
+manager.startup.isLaunchHidden()           // true if THIS launch is hidden — combines
+                                           //   user-launch mode + login-launch detection.
+                                           //   Use this in main.js to gate windows.create().
+manager.startup.wasLaunchedAtLogin()       // true if the OS auto-launched us at login
+manager.startup.applyEarly()               // calls app.dock.hide() if needed (called by main.js boot)
+
+manager.startup.setOpenAtLogin(true)                            // back-compat boolean form
+manager.startup.setOpenAtLogin({ enabled: true, mode: 'hidden' }) // object form
+manager.startup.isOpenAtLogin()            // read live OS state
+```
+
+## Typical main.js pattern
+
+```js
+manager.initialize().then(() => {
+  // Always create the main window. In hidden launches, `show: false` keeps it
+  // invisible until something explicitly calls windows.show('main') — but it's
+  // in the registry, so @omega.js/desktop's activate/second-instance handlers can find and
+  // surface it when the user double-clicks the running app.
+  manager.windows.create('main', {
+    show: !manager.startup.isLaunchHidden(),
+  });
+});
+```
+
+Don't conditionally skip `create()` for hidden launches — without `main` in the registry, the dock-click / re-launch handlers have nothing to surface, and the user double-clicking the running app appears to do nothing.
+
+## Boot order
+
+`startup.applyEarly()` is the **first** call in `Manager.initialize()` — before `whenReady`, before any other lib. The goal: spend as little time as possible in the dock-bounce window.
+
+Sequence: applyEarly → before-quit hook → ipc → storage → sentry → protocol → deep-link → app-state → whenReady → updater → tray/menu/contextMenu → startup.initialize → @omega.js/client → windows.initialize. **@omega.js/desktop no longer auto-creates the main window** — your `main.js` does that inside the `.then()` callback after `initialize()` resolves.
+
+## How zero-bounce works on macOS
+
+`LSUIElement` is an `Info.plist` key that tells macOS *before launch* "this app is a background agent — don't put it in the dock or app switcher." Setting it at runtime (`app.dock.hide()`) is too late — by the time JS runs, the dock-bounce animation has already started.
+
+@omega.js/desktop handles this at build time:
+1. `gulp/build-config` reads `config/omega.json5`.
+2. If `startup.mode === 'hidden'` **or** `startup.openAtLogin.mode === 'hidden'`, it injects `mac.extendInfo.LSUIElement: true` into the materialized `dist/electron-builder.yml`. (The openAtLogin case matters for `mode: 'normal'` apps that launch hidden at login — without the plist key, the login launch flashes the dock before `applyEarly()`'s `dock.hide()` can run.)
+3. `electron-builder` packages the app with that key in the final `Info.plist`.
+
+With the key baked, a MANUAL launch also starts dockless — the dock icon appears the moment the main window surfaces (every surface path runs `_ensureDockVisible()` → `app.dock.show()`), so the visible difference is only that the bounce animation is replaced by the icon appearing when the window is ready.
+
+At runtime, when the consumer first calls `manager.windows.show()` (or the `windows.create()` call resolves with `show: true`), @omega.js/desktop calls `app.dock.show()` so the dock icon appears alongside the window. Reverses cleanly via `app.dock.hide()` if you want to go back to invisible.
+
+The injection is YAML-text-level (preserves comments, idempotent, merges with existing `extendInfo`). See `src/gulp/tasks/build-config.js`.
+
+## Re-surfacing on user re-launch
+
+When the user double-clicks a running hidden-mode app (or clicks its dock icon on macOS), @omega.js/desktop transparently surfaces the main window — no consumer wiring needed. Mechanisms:
+
+- **macOS**: `window-manager.initialize()` registers `app.on('activate')` which calls `windows.show('main')` if `main` is in the registry.
+- **Windows / Linux**: `deep-link.initialize()` registers `app.on('second-instance')` which does the same. (The OS spawns a duplicate process, the single-instance lock kills it, and forwards its argv to the original instance.)
+
+Both handlers are no-ops if `main` isn't in the registry, so consumers who genuinely never want a window can omit `windows.create('main', ...)` entirely. Otherwise, with the canonical pattern (`windows.create('main', { show: !isLaunchHidden() })`), hidden-mode apps come back to life on a second click — like CleanMyMac, Rectangle, etc.
+
+## Testing the login-launch path locally
+
+Pass `--omega-launched-at-login` as a command-line arg when launching the .app; @omega.js/desktop treats it identically to a real OS-driven login launch (`startup.wasLaunchedAtLogin()` returns `true`, with `via:argv-flag` in the boot summary log). Useful for testing hidden-mode behavior without configuring login items + rebooting.
+
+The easiest way is `mgr launch`, which auto-strips `ELECTRON_RUN_AS_NODE` and uses `open -n` under the hood:
+
+```bash
+# Auto-discover the most recent `mgr package:quick` build:
+npx omega launch --args="--omega-launched-at-login"
+
+# Or pass an explicit path:
+npx omega launch /Applications/MyApp.app --args="--omega-launched-at-login"
+```
+
+If you'd rather call `open` directly, remember to strip `ELECTRON_RUN_AS_NODE` first (the variable leaks into shells from common host processes like VS Code's Claude Code extension and silently breaks Electron):
+
+```bash
+unset ELECTRON_RUN_AS_NODE
+open -n /path/to/MyApp.app --args --omega-launched-at-login
+
+# Windows / Linux — direct binary launch
+"/path/to/MyApp.exe" --omega-launched-at-login
+```
+
+The boot summary log written by the `startup` lib distinguishes a real login launch (`via:macos-wasOpenedAtLogin`) from a flag-based simulation (`via:argv-flag`).
+
+## Pairing with tray/window patterns
+
+Hidden / agent apps usually want:
+
+```jsonc
+"startup": { "mode": "hidden" }
+```
+
+And in `src/integrations/tray/index.js`:
+
+```js
+tray.update('open', { click: () => manager.windows.show('main') });
+```
+
+The window is created at boot but invisible. When the user clicks the tray's "Open" item (or double-clicks the app icon), `windows.show('main')` runs, @omega.js/desktop calls `app.dock.show()`, and the user sees both the dock icon and the window appear together.

package/docs/storage.md

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

package/docs/templating.md

@@ -0,0 +1,101 @@
+# Templating
+
+Light token-replacement engine for HTML pages. Uses `{{ var }}` syntax, dot-notation paths, brand/app values from config.
+
+## How it works
+
+1. Consumer authors `src/views/<name>/index.html` as the **body** of the page (no `<html>`, `<head>`, `<body>` tags).
+2. @omega.js/desktop ships a default page template at `<em>/dist/config/page-template.html`. Consumers can override with their own at `<consumer>/config/page-template.html` if they want to.
+3. At build time, `gulp/html`:
+   - Reads each `src/views/<name>/index.html`
+   - Templates its body with the page vars (so the body can use `{{ brand.name }}` etc.)
+   - Injects the rendered body into the page template's `{{ content }}` slot
+   - Writes the final HTML to `dist/views/<name>/index.html`
+4. The page template auto-includes:
+   - `assets/css/main.bundle.css` (compiled from `src/assets/scss/main.scss` by gulp/sass) — present on every page
+   - `assets/js/components/<page.name>.bundle.js` (per-view renderer bundle) — only the JS for this page
+
+## Page name
+
+`page.name` is derived from the view's path under `src/views/`:
+- `src/views/main/index.html`        → `page.name = 'main'`
+- `src/views/settings/index.html`    → `page.name = 'settings'`
+- `src/views/blog/post.html`         → `page.name = 'blog/post'`
+
+This naming lines up with the renderer bundle's entry naming so the JS bundle path resolves correctly.
+
+## Page template variables
+
+| Var | Source | Example |
+|---|---|---|
+| `{{ brand.id }}`, `{{ brand.name }}`, `{{ brand.url }}` | `config.brand.*` | `myapp` / `MyApp` |
+| `{{ app.productName }}`, `{{ app.appId }}`, `{{ app.copyright }}` | `config.app.*` | `MyApp` / `com.itwcw.myapp` |
+| `{{ page.name }}` | derived from view path | `main` / `settings` |
+| `{{ page.title }}` | `extras.title` (in gulp/html) or `app.productName` | `MyApp` |
+| `{{ theme.appearance }}` | `config.theme.appearance` (default `'system'`) | `light` / `dark` / `system` — runtime applier replaces with the resolved value ([themes.md](themes.md)) |
+| `{{ cacheBust }}` | build timestamp | `1777515223640` |
+| `{{ content }}` | rendered body (set by gulp/html) | `<main>...</main>` |
+
+## Default page template
+
+```html
+<!doctype html>
+<html data-bs-theme="{{ theme.appearance }}">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <title>{{ page.title }}</title>
+    <link href="../../assets/css/main.bundle.css?cb={{ cacheBust }}" rel="stylesheet">
+  </head>
+  <body>
+    {{ content }}
+    <script src="../../assets/js/components/{{ page.name }}.bundle.js?cb={{ cacheBust }}"></script>
+  </body>
+</html>
+```
+
+## Overriding the page template
+
+Drop your own `config/page-template.html` in your project root. @omega.js/desktop picks it up before falling back to its own default.
+
+```html
+<!-- consumer/config/page-template.html -->
+<!doctype html>
+<html data-bs-theme="{{ theme.appearance }}" lang="en">
+  <head>
+    <meta charset="utf-8">
+    <title>{{ page.title }} | {{ brand.name }}</title>
+    <link href="../../assets/css/main.bundle.css?cb={{ cacheBust }}" rel="stylesheet">
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;700" rel="stylesheet">
+  </head>
+  <body class="custom-shell">
+    {{ content }}
+    <script src="../../assets/js/components/{{ page.name }}.bundle.js?cb={{ cacheBust }}"></script>
+  </body>
+</html>
+```
+
+## Runtime API
+
+`manager.templating` is also available at runtime if you need to template a string yourself (e.g. dynamic deep-link routes):
+
+```js
+manager.templating.render('Hello {{ user.name }}', { user: { name: 'Ian' } });
+// → 'Hello Ian'
+
+manager.templating.render('Custom [name]', { name: 'X' }, { brackets: ['[', ']'] });
+// → 'Custom X'
+```
+
+## Future
+
+The current page template hardcodes the asset paths. A future pass adds:
+- Per-page CSS bundles (currently only one shared `main.bundle.css`)
+- Source map references in dev mode
+- Inline critical CSS for fast first paint
+
+For theme-related styling (Bootstrap, classy theme), see [docs/themes.md](themes.md) when that pass lands.
+
+## Tests
+
+`src/test/suites/build/templating.test.js` — render, dot-notation, custom brackets, buildPageVars, renderPage end-to-end. 8 tests.

package/docs/test-boot-layer.md

@@ -0,0 +1,157 @@
+# Test Framework — Boot Layer
+
+The `boot` test layer runs against the consumer's **actual built `main.bundle.js`** — the real production main entry, loaded exactly as `electron .` loads one. Replaces shell-level `npm start && sleep 12 && kill` smoke tests with deterministic, signal-driven pass/fail.
+
+The build and the boot happen in a **staged app root of their own**, `<project>/.omega/test-app/` (gitignored) — never the project's `dist/`, which belongs to the `npm start` watcher. See [Isolated build output](#isolated-build-output).
+
+## When to use it
+
+| Layer | What it tests | Speed |
+|---|---|---|
+| `build` | Plain Node — config parsing, util fns, schema validation. | Fast (ms) |
+| `main` | @omega.js/desktop lib code in isolation (storage, ipc, tray, etc.) inside Electron. | Fast (~50ms each) |
+| `renderer` | Inside a hidden BrowserWindow. | Fast |
+| `boot` | The **whole boot integration** — consumer's main.js → manager.initialize → live state | ~1s startup, then fast |
+
+Use `boot` for tests that need to verify **integration** rather than unit behavior:
+- "Does the consumer's `src/main.js` actually wire up correctly?"
+- "Did all 13 boot steps complete without throwing?"
+- "Did config flow from JSON5 → manager.config → tray titles?"
+- "Did `src/integrations/{tray,menu,context-menu}/index.js` load?"
+- "Is the menu rendered with the expected default ids?"
+
+## Test shape
+
+```js
+// test/boot.test.js (consumer-side)
+module.exports = {
+  type:        'group',
+  layer:       'boot',
+  description: 'consumer boot smoke',
+  timeout:     20000,
+  tests: [
+    {
+      description: 'manager initialized end-to-end',
+      inspect: async ({ manager, expect, projectRoot }) => {
+        expect(manager._initialized).toBe(true);
+        expect(manager.config).toBeTruthy();
+      },
+    },
+    {
+      description: 'tray + menu rendered',
+      inspect: async ({ manager, expect }) => {
+        expect(manager.tray.has('open')).toBe(true);
+        expect(manager.menu.isRendered()).toBe(true);
+      },
+    },
+  ],
+};
+```
+
+The `inspect` function receives:
+| Arg | Description |
+|---|---|
+| `manager` | The fully-initialized live Manager instance — same one your consumer code uses. |
+| `expect` | @omega.js/desktop's [Jest-compatible assertion library](../src/test/assert.js). |
+| `projectRoot` | Absolute path to the consumer project root (its `src/`, `config/` — and the `dist/` a boot run must never write). |
+| `appRoot` | Absolute path to the staged app root Electron booted — `<projectRoot>/.omega/test-app`. Assert on built artifacts here (`<appRoot>/dist/main.bundle.js`), not under `projectRoot`. |
+| `frameworkDistRoot` | Absolute path to `<@omega.js/desktop>/dist` — where framework test utilities live. |
+| `distSnapshotBefore` | Fingerprint of `<projectRoot>/dist` taken before the test build, for the isolation assertion below. |
+
+## How it works
+
+1. Test runner discovers `test/**/*.js` files with `layer: 'boot'`.
+2. Stages `<projectRoot>/.omega/test-app`, builds into its `dist/`, and aggregates each test's `inspect` source body into a JSON spec file.
+3. Spawns a real Electron process: `electron <projectRoot>/.omega/test-app` — an app dir with a `package.json` whose `main` is the built bundle, same shape as `npm start`'s `electron .`.
+4. Sets three env vars before spawn:
+   - `OMEGA_TEST_BOOT=1` — gate
+   - `OMEGA_TEST_BOOT_HARNESS=<absolute path to dist/test/harness/boot-entry.js>`
+   - `OMEGA_TEST_BOOT_SPEC=<temp file with test definitions>`
+5. @omega.js/desktop's `main.js` boots normally; after `manager.initialize()` resolves, detects `OMEGA_TEST_BOOT=1`, reconstitutes each `inspect` from its serialized body string, runs them sequentially, and emits `__EM_TEST__` JSON lines on stdout.
+6. Test runner parses results, calls `app.exit()`. **No sleep, no kill.**
+
+## View suites in this lane
+
+The boot lane also carries the renderer suites that name a project view (`layer: 'renderer'` + `view: '<name>'`). They need exactly what this lane already produces: the staged, freshly built app. After the `inspect` tests finish, [harness/boot-entry.js](../src/test/harness/boot-entry.js) opens each such suite's view in a real window of the booted app (through the app's own window manager, hidden), evaluates `harness/renderer-entry.js` verbatim inside the page (one suite loop, one `expect`, no fork), runs the suite there, and destroys the window. So the page carries the project's real preload, the booted main process's real IPC handlers, and the real config. The knob and its rules are documented in [test-framework.md](test-framework.md#testing-your-own-views).
+
+## Running
+
+```bash
+# All layers including boot
+npx omega test
+
+# Boot only
+npx omega test --layer boot
+
+# With debug output (shows electron's stderr + harness internals)
+OMEGA_TEST_DEBUG=1 npx omega test --layer boot
+```
+
+## Isolated build output
+
+`npm start`'s watcher owns `<project>/dist/`. When the boot runner built there too, a dev app and a boot-test run interleaved writes on one tree and either side could load a half-written bundle — a race that presents as a code bug. So the boot build gets its own output (#110).
+
+**The seam** is [src/utils/dist-root.js](../src/utils/dist-root.js): every gulp task resolves its output through it instead of joining `dist/` by hand, and `OMEGA_BUILD_OUTPUT` (absolute, or relative to the project root) redirects the whole build. Nothing else in the build config is duplicated.
+
+**The staged app root** is `<project>/.omega/test-app/`, built by `stageTestApp()` in [src/test/runners/boot.js](../src/test/runners/boot.js):
+
+| Entry | What it is |
+|---|---|
+| `package.json` | The project's own, verbatim except `main`, pinned at the test build's bundle — so Electron derives the same app name, version and userData path a real boot does. |
+| `dist/` | The isolated build output. `<appRoot>/dist/views/*`, `<appRoot>/dist/preload.bundle.js` and the tray icon lookup resolve against it with **no runtime change** — the app root moved, the layout under it did not. |
+| `src`, `config` | Symlinks back to the project's. Runtime lookups against `app.getAppPath()` — `src/integrations/{tray,menu,context-menu}/index.js`, the unbundled config fallback — still find the consumer's real files. |
+
+`package.json` and the symlinks are restaged on every run, and the runner clears the staged `dist/` before each build (kept only under `OMEGA_TEST_SKIP_BUILD`). `node_modules` resolution still walks up into the project's. The isolation promise is about `dist/`: a boot run still appends to the project's gitignored `logs/` (the gulp build log and the booted app's runtime log), same as any run.
+
+The regression is covered end-to-end in the real run: the runner fingerprints `<project>/dist` before the build, and [src/test/suites/boot/build-isolation.test.js](../src/test/suites/boot/build-isolation.test.js) re-fingerprints it from inside the booted app and asserts nothing was touched.
+
+## Prerequisites
+
+**The runner always rebuilds the bundle first** (via the same gulp pipeline `npm run build` uses) so tests never see stale code. Adds ~10s to the boot-test run; correctness over speed.
+
+Opt out for CI scenarios where build already ran in a separate step:
+
+```bash
+OMEGA_TEST_SKIP_BUILD=1 npx omega test --layer boot
+```
+
+Boot then runs against whatever is already in `<project>/.omega/test-app/dist/`. If there is no bundle there, the run **fails loudly** rather than skipping or falling back to the project's `dist/` — an absent test build means the build step that was promised never ran, and booting some other bundle would silently test the wrong code.
+
+## Self-test from the framework repo (the bundled fixture)
+
+Everything above describes a **consumer** running boot tests against their own built bundle. @omega.js/desktop also boot-tests *itself* — the same way BXM verifies "does the extension load?" and UJM verifies "does the site boot?".
+
+When `npx omega test` runs from the @omega.js/desktop repo (the cwd's `package.json` name is `@omega.js/desktop`), two complementary mechanisms engage:
+
+- **`isFrameworkSelfTest`** (in [src/test/runner.js](../src/test/runner.js)) — test discovery includes the framework's own `boot/**` suites. For a real consumer this flag is false and framework `boot/**` suites are **excluded** (they target @omega.js/desktop's fixture, not the consumer's app), so they never run in a consumer's `npx omega test`.
+- **`OMEGA_TEST_BOOT_PROJECT`** — [src/commands/test.js](../src/commands/test.js) points the boot runner at the bundled fixture under `src/test/fixtures/consumer-app/` instead of the cwd.
+
+The gate decides *whether* the framework boot suite runs; the env var decides *which project* gets booted. (@omega.js/backend's `OMEGA_TEST_BOOT_PROJECT`, BXM's `OMEGA_TEST_BOOT_PROJECT`, and UJM's `UJ_TEST_BOOT_PROJECT` are the exact analogs.)
+
+### The bundled fixture
+
+`src/test/fixtures/consumer-app/` — a minimal, committed @omega.js/desktop consumer (source only):
+
+- `config/omega.json5` — fake brand (`desktop-fixture`), `releases.enabled: false` (no repo discovery during the build), empty `cloud.config` (no Firebase hang).
+- `src/main.js` / `src/preload.js` — the one-line bootstraps a real consumer ships; `main.js` creates the `main` window (`show: false`).
+- `src/views/main/index.html` + `src/assets/js/components/main/index.js` + `src/assets/scss/main.scss` — a real view/renderer/theme so the bundle + sass tasks run exactly as for a consumer.
+
+**Runtime-only, gitignored** (never committed): before the boot build, the runner symlinks `@omega.js/desktop` (→ the @omega.js/desktop repo root) and `electron` (→ @omega.js/desktop's own copy) into the fixture's `node_modules` — the only two deps resolved by *explicit path* (the gulpfile location, the bundle's `require('@omega.js/desktop/main')`, and the runner's electron-binary lookup). Everything else (gulp, esbuild, …) resolves via the upward `node_modules` walk because the fixture lives inside the @omega.js/desktop repo. The links are **removed again when the run finishes** — the `@omega.js/desktop` link points back at the repo root, which *contains* the fixture, so a leftover link forms an infinite directory cycle inside `dist/` that crashes the next prepare-package tree walk (`npm run prepare` / `npm publish` → `ENAMETOOLONG`). The fixture `.gitignore` is belt-and-suspenders for crashed runs. See `ensureFixtureDeps()` / `removeFixtureDeps()` in [src/test/runners/boot.js](../src/test/runners/boot.js).
+
+The fixture is then **built into a real `main.bundle.js`** (under its own `.omega/test-app/dist/`, like any other boot run) and booted — the same production path a consumer's boot test exercises (bundled, not the unbundled lib code the `main` layer covers). The boot smoke lives at [src/test/suites/boot/consumer-app-boots.test.js](../src/test/suites/boot/consumer-app-boots.test.js).
+
+### `OMEGA_TEST_BOOT_PROJECT`
+
+| Env | Purpose |
+|---|---|
+| `OMEGA_TEST_BOOT_PROJECT` | Root of a project to boot instead of the cwd. Auto-set to `src/test/fixtures/consumer-app` when @omega.js/desktop tests itself; set it explicitly to boot a **real consumer** (e.g. `deployment-playground-desktop`) without `cd`-ing into it. |
+
+### Why this exists
+
+The `build`/`main`/`renderer` layers cover @omega.js/desktop's lib code fast and in isolation. None of them prove the framework still assembles a consumer's `src/main.js` into a bundle that boots end-to-end. The fixture self-test fills that gap — @omega.js/desktop's analog of "does the extension load?" (BXM) / "does the site boot?" (UJM).
+
+## Limitations
+
+- Tests run sequentially in a single Electron process to amortize startup cost (~1s). State doesn't carry across tests — they all share one `manager` instance.
+- `inspect` function bodies are serialized via `Function.prototype.toString` and reconstituted with `new Function(...)`. Closures over the test file's outer scope **don't survive** — only the `inspect` argument bag is available inside.
+- We can't simulate user input (clicking the tray, right-clicking, typing). For that, you'd need `nut-js` or similar — out of scope.