@omega.js/desktop 0.1.0

package/docs/test-framework.md

@@ -0,0 +1,357 @@
+# Test Framework
+
+Built-in test framework for both @omega.js/desktop itself and consumer projects. Jest-like assertion syntax (`expect(actual).toBe(expected)`), layered runners, @omega.js/backend-style output.
+
+## 🚫 NEVER mock — test against the real harness (HARD RULE)
+
+**Do NOT hand-roll fake/stub/mock objects** — no `mockManager`, fake `ipc`/`storage`/`window`/`tray`, stubbed `app`/`BrowserWindow`, or fake IPC channels. Every test gets the **real** framework context:
+
+- `build` runs real @omega.js/desktop helper code in plain Node.
+- `main` / `renderer` / `boot` run inside a **real spawned Electron process**, where `ctx.manager` (and boot's `inspect({ manager })`) is the **real booted Manager** — real `manager.storage`, `manager.ipc`, `manager.tray`, `manager.windows`, etc. Use them; exercise the code the way production does.
+
+**Pure functions are the ONLY exception.** A function with zero I/O (config-defaults merge, icon-path resolver, schema validator, CLI alias resolver, a string/number transform) can be `require()`d and called directly with plain inputs — that's not mocking, there's nothing to mock. The moment a function touches `app.*` / `BrowserWindow` / `ipcMain` / `Tray` / the real bundle / an external service, it MUST run against the real harness in the appropriate layer (`main` / `renderer` / `boot`), not a stub.
+
+**Real external APIs are gated behind extended mode (`TEST_EXTENDED_MODE`), NOT mocked** (see [Extended vs normal mode](#extended-vs-normal-mode) below). Normal mode skips them *in the source*; extended mode runs them for real. The test never fakes them. **Anything an extended test creates in a real external system MUST be cleaned up** by the test (via the suite's `cleanup(ctx)` hook) — external systems are not reset between runs.
+
+If you find yourself writing `const mockX = {...}` to satisfy code under test, STOP — pass the real `ctx.manager` (or its real sub-object), or, if the function is genuinely pure, call it directly with plain data.
+
+### The ONLY two exceptions where a narrow stub is allowed
+
+Mock **nothing** by default. There are exactly two cases where the real dependency genuinely cannot run in the test environment — and even then, stub the *smallest possible seam* (one method / one object), restore it immediately, and comment *why*:
+
+1. **A side effect that would destroy the test run itself.** If the real call would kill or corrupt the harness — `app.quit()`, a process-exit, `autoUpdater.quitAndInstall()`, a destructive wipe — stub *that one call* to a no-op, assert the surrounding decision logic (e.g. that `_allowQuit` was set first), then restore. You are preventing the harness from terminating mid-assertion, not faking behavior. (Examples: `window-manager.test.js` stubs `app.quit`; `auto-updater.test.js` stubs `installNow`/`_promptToInstall`.)
+2. **A real dependency the test environment can't provide.** When the real object only exists from infra you can't stand up in a unit test (e.g. a live `webContents` from a not-yet-created window, a second running app instance), a unit test may hand a minimal stub to verify a *narrow side effect* (e.g. that `attach()` registers the right listener). Prefer obtaining the real object from the harness if you can; only stub when you genuinely can't.
+
+If you can run it for real, you must. These exceptions are not a license to unit-test in isolation when a real-harness layer (`main`/`renderer`/`boot`) would work.
+
+## Test coverage — every surface gets a test (HARD RULE)
+
+A feature is not done when it works — it's done when every surface it exposes is covered in the layer that owns that surface:
+
+| Coverage | Layer | Proves |
+|---|---|---|
+| **Logic** | `build` / `main` | The feature's functions do the right thing when called directly (real Manager, real storage, real IPC) |
+| **UI** | `renderer` | The feature's interface is WIRED — a real event on the real DOM triggers the behavior and the visible result appears |
+| **End-to-end** | `boot` | The feature survives in the consumer's actual built bundle (extend the boot suite's `inspect` assertions) |
+
+**Skipping a layer is the exception, not the default.** A layer may be skipped ONLY when the feature genuinely has no surface there — a pure build-time utility has no UI; a CSS-only tweak has no logic to call. Convenience is never a reason: "the logic test already covers it" does NOT excuse the UI test — logic tests prove the logic, UI tests prove the wiring (a button can come unhooked while every logic test stays green), boot tests prove the packaging. When in doubt, write the test.
+
+## Running tests
+
+```bash
+npx omega test                          # consumer: runs YOUR project suites (bare runs never include the framework corpus)
+npx omega test --layer=main             # only main-process suites (also: build, renderer, all)
+npx omega test --filter="storage"       # only suites/tests whose name contains "storage"
+npx omega test --extended               # opt into extended mode — real external APIs (also: TEST_EXTENDED_MODE=true)
+npx omega test --reporter=json          # pretty output + machine-readable {"event":"summary",...} line
+OMEGA_TEST_DEBUG=1 npx omega test          # see Electron stderr (otherwise drained silently)
+```
+
+In @omega.js/desktop itself, `npm test` runs the framework's own suite — the self-test context flips the no-target default.
+
+### Filtering tests
+
+Pass a path (relative to `test/`) as a positional **target** to select which test FILES run:
+
+```bash
+# Run project test files under a path (a bare path binds to the PROJECT source)
+npx omega test build/config
+
+# Run BOTH sources — reaching the framework suite is always an explicit choice
+npx omega test full:
+npx omega test full:build/config
+
+# Run ONLY consumer project tests (no framework suites at all)
+npx omega test project:
+
+# Run a single project test file
+npx omega test project:main/tab-manager
+
+# Run ONLY framework tests (universal cross-framework alias)
+npx omega test mgr:
+
+# Run ONLY @omega.js/desktop framework tests (desktop-specific aliases, equivalent to mgr:)
+npx omega test desktop:
+npx omega test framework:
+
+# Run framework tests matching a path
+npx omega test mgr:build/config
+npx omega test desktop:build/config
+
+# Combine with extended mode
+TEST_EXTENDED_MODE=true npx omega test build/config
+```
+
+The target matches against the test file path. The source prefix scopes selection to framework-only or project-only tests — a prefixed target excludes the other source entirely:
+
+- `mgr:` — the **universal cross-framework alias** for "the manager's own tests" (framework-only). Works identically in @omega.js/desktop, BXM, UJM, and @omega.js/backend.
+- `desktop:` / `framework:` — desktop-specific aliases for framework-only tests, equivalent to `mgr:`.
+- `project:` — consumer project tests only.
+
+A bare prefix (`mgr:` / `desktop:` / `project:` with no path) runs every test in that source. A bare path (no prefix) binds to the PROJECT source; `full:<path>` searches both sources by path.
+
+A target that names a path and matches NO file is a hard error: the run prints `No test file matches "<target>"` and exits 1, so a typo'd path, or a suite renamed out from under a target, can never run silently green ([#814](https://github.com/Omega-JS-Stack/omega/issues/814)). A run that named no file (bare, or a bare source prefix) still exits 0 when there is nothing to run. Inside a brand-root fan-out the manager sets `OMEGA_TEST_FANOUT=1` on every forwarded run, and the same miss answers with exit 3 instead: a path another target carries is a no-op here, and the brand run fails only when EVERY target missed ([docs/shared/testing.md](../../../docs/shared/testing.md#brand-root-cp94b)).
+
+> **Target vs `--filter`.** The positional target selects test FILES (by path + source). The `--filter=<substring>` flag is orthogonal: it matches test NAMES/descriptions within the selected files. Use them together, e.g. `npx omega test project: --filter="reorder"`.
+
+### Layers
+
+- **build** — runs in plain Node. Fast.
+- **main**  — spawns Electron and runs inside the main process. Required for anything touching `app`/`ipcMain`/`BrowserWindow`.
+- **renderer** — runs inside a hidden `BrowserWindow` spawned by the main harness. Test functions are serialized + reconstructed via `new Function('ctx', body)`, so they only have access to `ctx` and the page's globals (`window`, `document`, `window.desktop.*`). No closures over module scope.
+- **boot** — rebuilds the project and spawns Electron against the real bundle. The build goes to a staged app root of its own (`<project>/.omega/test-app/`, via `OMEGA_BUILD_OUTPUT`), never the project's `dist/` — so a boot-test run and a live `npm start` watcher never write the same tree. See [test-boot-layer.md](test-boot-layer.md).
+- **all** (default) — build, then main, then renderer in a single Electron boot.
+
+### Extended vs normal mode
+
+Suites that hit a live backend (Firebase Auth admin SDK, real GitHub API, etc.) are gated behind **extended mode** — `npx omega test --extended` or `TEST_EXTENDED_MODE=true`. `TEST_EXTENDED_MODE` is the **shared, unprefixed env var across @omega.js/backend, @omega.js/extension, UJM, and @omega.js/desktop** (cross-framework parity) — once set on `process.env` it propagates to every spawned test environment (the Electron main/renderer/boot children, the gulp boot build) automatically via `{ ...process.env }`. These external calls are **skipped in-source, NOT mocked** — the suite short-circuits / `ctx.skip()`s when `TEST_EXTENDED_MODE` is unset; with it set, it calls the real service. Default is to skip them so `npx omega test` is fast + green offline, and a warning prints when extended mode is on. The CI workflow runs normal mode by default; add a separate workflow that sets `TEST_EXTENDED_MODE: 'true'` for extended coverage.
+
+Anything an extended suite creates externally must be torn down in its `cleanup(ctx)` — the harness only resets local Electron state between runs, never external systems.
+
+### `OMEGA_TEST_MODE=true` — the canonical "we're in tests" signal
+
+Both @omega.js/desktop test runners (`runners/electron.js`, `runners/boot.js`) set `OMEGA_TEST_MODE=true` in the spawned child env. That powers `manager.isTesting()` (and `Manager.isTesting()` static) — the cross-context helper everything in @omega.js/desktop checks when it needs to behave differently in tests:
+
+- `auto-updater` flips its idle threshold from 15min → 3s and its periodic tick from 60s → 500ms, AND short-circuits the native install-prompt dialog (so tests don't pop modal windows).
+- **Every BrowserWindow surfaces stealth** — named windows via `window-manager._surface()` AND raw `new BrowserWindow()` ones (e.g. a consumer's automation popup) via a global `browser-window-created` hook registered in `main.js` step 1a-ii. The shared recipe lives in `src/utils/stealth-window.js`: shown INACTIVE (keyboard focus never leaves your editor), opacity 0, click-through (`setIgnoreMouseEvents`), and raw windows get `show()` rerouted to `showInactive()` + `focus()` no-op'd — a test run never interrupts you, and a stray real click physically can't land in the app, while synthetic test input (`executeJavaScript`, `sendInputEvent`, CDP) is unaffected. **`webContents.focus()` is suppressed separately** (a global `web-contents-created` hook in the same main.js block): it bypasses the window-level patches — it's a different object whose `focus()` reaches the native window directly and makes the invisible window KEY, grabbing the keyboard mid-typing even under the accessory policy (which only prevents *launch* activation, not key-window steals). Consumers call it legitimately (e.g. address-bar focus on tab select), so it's no-op'd per-contents under the same predicate. Set **`OMEGA_TEST_SHOW=1`** to surface windows normally and watch a run live (the predicate is evaluated per window, so flipping it mid-run works). Deliberately NOT `hide()`/`minimize()`: occluded windows get throttled by Chromium (`requestAnimationFrame` pauses, `document.visibilityState` flips to `hidden`) — tests would exercise a DIFFERENT runtime, whereas an opacity-0 shown-inactive window renders and behaves identically to a visible one. See [windows.md](windows.md).
+- **App-level activation is suppressed too (macOS).** Launching a regular-policy app activates it — the menu bar and keyboard focus switch to the test process at launch even though every window surfaces inactive. Under the same stealth predicate (`src/utils/test-stealth.js` — Testing mode + `OMEGA_TEST_SHOW` unset), `main.js` (step 1a, before app ready) and the spawned test harness flip the app to the **accessory activation policy** (`app.dock.hide()` — the same switch `LSUIElement` bakes for packaged hidden-mode apps): the process never activates, never shows a dock icon, and never steals focus, while windows still render identically. `OMEGA_TEST_SHOW=1` restores normal activation along with visible windows. Verified by frontmost-app sampling across a full run: zero focus changes (previously four steals per run).
+- `main.js#initialize` isolates userData per environment: testing runs get `<userData> (Testing)` — **wiped at boot**, so every test run starts from a clean slate (post-run state stays on disk for inspection until the next run; set `OMEGA_TEST_KEEP_USERDATA=1` to skip the wipe). Dev runs get ` (Development)`; production is untouched. See [boot-sequence.md](boot-sequence.md).
+- **The main-layer harness exposes a CDP endpoint.** `test/harness/main-entry.js` appends `--remote-debugging-port=0` at require time (loopback-only, OS-assigned port) and publishes the resolved port as **`process.env.OMEGA_CDP_PORT`** before suites run (read from Chromium's `DevToolsActivePort` file; any value inherited from your shell is overwritten — that one points at your dev app, not the harness). Consumer suites can drive real browser automation against the harness Electron itself, e.g. `playwright-core`'s `connectOverCDP('http://127.0.0.1:' + process.env.OMEGA_CDP_PORT)`. Covered by `suites/main/harness-cdp.test.js`.
+- Other lib code can branch on `manager.isTesting()` to suppress dock bounce, login-item changes, OS protocol-handler registration, etc.
+
+Consumers writing their own tests should set `OMEGA_TEST_MODE=true` in their test runner so the same signal applies — for example, in `package.json`:
+```json
+"test": "OMEGA_TEST_MODE=true vitest"
+```
+Then in your code, gate test-only behavior on `manager.isTesting()` instead of inventing yet another env var.
+
+## Test discovery
+
+- **Framework defaults**: `<@omega.js/desktop>/dist/test/suites/**/*.js`
+- **Consumer suites**: `<cwd>/test/**/*.js`
+
+**The underscore convention** (`DISCOVERY_IGNORE` in `src/test/runner.js`): `_`-prefixed FILES (`test/_init.js`, `test/main/_helper.js`) and everything under a `_`-prefixed DIRECTORY at **any depth** (`test/_fixtures/**`, `test/boot/_private/**`) are excluded from suite discovery. Put shared helpers, fixture data, and non-test support files in `_`-prefixed paths — e.g. `test/_fixtures/`, `test/_helpers/`. The runner still specifically loads `test/_init.js` as the lifecycle hook. Matches the same convention in @omega.js/backend/BXM/UJM. Files load alphabetically (sorted globally per source).
+
+**Framework boot suites are scoped to @omega.js/desktop self-test runs only.** When a consumer runs `npx omega test`, the framework's `dist/test/suites/boot/**` is excluded from discovery — those tests are meant to assert on @omega.js/desktop's own internal fixtures and would fail noisily against a real consumer app. Detection: the runner checks `cwd`'s `package.json#name === '@omega.js/desktop'`. Consumers write their own boot tests under `<cwd>/test/boot/`. Matches the same exclusion pattern in BXM and UJM. See [test-boot-layer.md](test-boot-layer.md).
+
+## `test/_init.js` — pre-test lifecycle hook
+
+The runner loads an optional `test/_init.js` from **both** test roots — the framework (`<@omega.js/desktop>/test/_init.js`) and the consumer project (`<cwd>/test/_init.js`) — and runs it **once, before any suite** (it is NOT itself run as a test; the `_`-prefix keeps it out of discovery). Mirrors the same hook in @omega.js/backend/UJM/BXM so all four frameworks share one shape.
+
+The module **must export a function** — `module.exports = (ctx) => ({ ... })` — called with `{ projectRoot }` and returning the hook object. It may declare:
+
+- `async setup({ projectRoot })` — runs once before the suites, e.g. to scaffold a fixture file the boot layer needs.
+
+There is **no `cleanup` hook** and **no `accounts` field** (unlike @omega.js/backend — these frameworks have no auth/user system): tests clean up after themselves, so there is nothing project-level to tear down.
+
+```javascript
+// <cwd>/test/_init.js
+const fs = require('fs');
+const path = require('path');
+
+module.exports = ({ projectRoot }) => ({
+  async setup() {
+    // Seed any fixture a suite needs before it runs.
+    fs.mkdirSync(path.join(projectRoot, '.temp'), { recursive: true });
+  },
+});
+```
+
+## Test file shapes
+
+Three forms — pick whichever fits.
+
+### Suite (sequential, share state, stop on first failure)
+
+```js
+module.exports = {
+  type: 'suite',
+  layer: 'main',                    // 'build' | 'main' | 'renderer'
+  description: 'storage (main)',
+  cleanup: async (ctx) => {         // runs after the last test
+    ctx.manager.storage.clear();
+  },
+  tests: [
+    {
+      name: 'set + get round-trip',
+      run: (ctx) => {
+        ctx.manager.storage.set('hello', 'world');
+        ctx.expect(ctx.manager.storage.get('hello')).toBe('world');
+      },
+    },
+    {
+      name: 'has reflects presence',
+      run: (ctx) => { /* ... */ },
+      cleanup: (ctx) => { /* ... */ },     // per-test cleanup
+      skip: 'reason',                       // skip this test
+    },
+  ],
+};
+```
+
+Tests share `ctx.state` across the suite. If one fails, remaining tests are skipped (`stopOnFailure: false` to disable).
+
+### Group (parallel-ish, share state, run all regardless of failures)
+
+```js
+module.exports = {
+  type: 'group',
+  layer: 'main',
+  description: 'boot sequence (main)',
+  tests: [ /* same shape as suite */ ],
+};
+```
+
+Same shape as suite, but all tests run even if some fail.
+
+### Standalone (single test per file)
+
+```js
+module.exports = {
+  layer: 'build',
+  description: 'CLI alias resolves to a command file',
+  run: (ctx) => { /* ... */ },
+  cleanup: (ctx) => { /* ... */ },
+  timeout: 10000,
+  skip: false,
+};
+```
+
+### Array shorthand (group of tests, no metadata)
+
+```js
+module.exports = [
+  { name: 'A', run: (ctx) => { /* ... */ } },
+  { name: 'B', run: (ctx) => { /* ... */ } },
+];
+```
+
+## Layers
+
+| Layer | Where it runs | Use for |
+|---|---|---|
+| `build` | Plain Node | CLI, package.json, config schema, gulp tasks |
+| `main` | Spawned Electron main process | Manager init, lib modules, IPC, windows |
+| `renderer` | Hidden BrowserWindow: the framework's harness page by default, one of the project's own `src/views/` when the suite declares `view: '<name>'` | `window.desktop.*`, preload bridge, UI logic, your own views |
+
+The runner partitions test files by layer at discovery time. The build layer runs inline; the main layer spawns Electron once with all main suites and parses JSON-line stdout.
+
+## ctx (context object)
+
+Every test fn receives a `ctx`:
+
+```js
+ctx.expect(actual)          // Jest-compatible expect()
+ctx.state                   // shared object across tests in a suite/group
+ctx.layer                   // 'build' | 'main' | 'renderer'
+ctx.skip(reason)            // skip from inside the test
+ctx.manager                 // (main layer only) the booted @omega.js/desktop Manager
+```
+
+## expect() matchers
+
+Jest-compatible subset:
+
+```js
+.toBe(expected)              // ===
+.toEqual(expected)           // deep equal
+.toBeTruthy() / .toBeFalsy()
+.toBeDefined() / .toBeUndefined() / .toBeNull()
+.toContain(item)             // array.includes / string.includes
+.toHaveProperty(key)
+.toMatch(regex)
+.toBeInstanceOf(class)
+.toBeGreaterThan(n) / .toBeLessThan(n)
+.toThrow(regex|string)       // also accepts async fns
+
+.not.<anything>              // negate any matcher
+```
+
+## Output
+
+```
+  OMEGA Desktop Tests
+
+  Framework Tests
+    ⤷ storage (main)
+      ✓ set + get round-trip (7ms)
+      ✓ has reflects presence (8ms)
+      ...
+
+  Results
+    149 passing
+
+    Total: 149 tests in 1850ms
+```
+
+All test output is also teed (ANSI-stripped) to `<projectRoot>/logs/test.log`, truncated fresh on each run — same pattern as `dev.log` (and @omega.js/backend's `test.log`). Grep it after a run instead of scrolling terminal output.
+
+## Test harness internals (main layer)
+
+- `runners/electron.js` spawns Electron with `harness/main-entry.js` as the app.
+- `harness/main-entry.js` boots Manager with `skipWindowCreation: true`, runs the suites, emits results via `__EM_TEST__{json}\n` lines on stdout.
+- The runner parses those lines and renders @omega.js/backend-style output.
+- stderr is always drained (otherwise the pipe fills and the harness blocks); printed only when `OMEGA_TEST_DEBUG=1`.
+- `ELECTRON_RUN_AS_NODE` is stripped from the spawn env (would otherwise make Electron behave as Node and break the harness).
+- **Consumer-scheme containment.** The consumer's `main.js` — where the real `protocol.handle('<brand.id>', …)` lives — never runs in this harness, so `brand://` URLs loaded by main-layer suites would be UNHANDLED. Chromium treats a load on an unhandled scheme as an *external protocol* and hands it to the OS — and if an installed copy of the app owns the scheme (e.g. `/Applications/Brand.app` on macOS, registered via its `Info.plist`), Launch Services launches the installed production app mid-test-run. The harness contains this two ways after Manager boots: (1) it registers a stub handler for the consumer's brand scheme (read from `<cwd>/config/omega.json5`) on the default session, so `brand://` loads commit in-process as a blank page; (2) it denies the `openExternal` permission on the default session and every session created after it (partitions included), so no navigation can hand ANY scheme to the OS during a test run. Suites that need real page content for `brand://` URLs belong in the boot layer, where the real app (and its real protocol handler) runs. A main-layer suite that genuinely needs its OWN handler for the brand scheme must call `protocol.unhandle(brand.id)` first — the harness stub holds the scheme on the default session.
+
+## Writing consumer tests
+
+In a consumer project, drop files in `test/` (or `test/**`):
+
+```js
+// test/login-flow.test.js
+module.exports = {
+  type: 'suite',
+  layer: 'main',
+  description: 'login flow',
+  tests: [
+    {
+      name: 'storage starts empty',
+      run: (ctx) => {
+        ctx.expect(ctx.manager.storage.get('user')).toBeUndefined();
+      },
+    },
+  ],
+};
+```
+
+`npx omega test` runs your project suites; scope `framework:` or `full:` to reach the framework's own.
+
+### Testing your own views
+
+A `renderer` suite that declares **`view: '<name>'`** runs against `src/views/<name>/` of YOUR app instead of the framework's harness page:
+
+```js
+// test/renderer/main-view.test.js
+module.exports = {
+  type: 'group',
+  layer: 'renderer',
+  view: 'main',                       // <- src/views/main/, as built
+  description: 'the main view',
+  tests: [
+    {
+      name: 'the heading renders the product name',
+      run: (ctx) => {
+        ctx.expect(document.querySelector('h1').textContent.trim()).toBe('My App');
+      },
+    },
+    {
+      name: 'the preload reached the page',
+      run: (ctx) => {
+        ctx.expect(typeof window.desktop).toBe('object');
+      },
+    },
+  ],
+};
+```
+
+Such a suite rides the **boot lane**, because only that lane stages and builds the real app (`<project>/.omega/test-app/`) before running: the page gets the project's real `dist/preload.bundle.js`, the real IPC handlers of the booted main process, and the real config. The window is created through the app's own window manager (hidden, no bounds persistence) and destroyed when the suite ends. Cost is the boot lane's: one build (~10-30s) shared with your boot tests.
+
+Consequences worth knowing:
+
+- **`--layer=renderer` does NOT run a view suite** (it needs the boot). `--layer=boot` and the default `--layer=all` do.
+- The test bodies still run as `new Function` inside the page: no closures over module scope, only `ctx` (`expect`, `state`, `layer`, `skip`) and the page globals (`window`, `document`, `window.desktop.*`).
+- Without `view`, nothing changes: the suite runs on the harness page in the main test Electron, as it always has.
+- A view that fails to load fails every test of the suite with `view "<name>" did not load`, rather than reporting an empty page.
+- Each view suite has a hard 60 s ceiling for the whole suite (the same ceiling the harness page uses); a suite's own `timeout` applies per test underneath it.

package/docs/themes.md

@@ -0,0 +1,135 @@
+# Themes
+
+@omega.js/desktop ships the **classy** theme (built on Bootstrap 5) so consumer apps look polished out of the box. Variables are fully customizable via `@use 'omega-desktop' as * with (...)` — same pattern as UJM and BXM.
+
+## How it works
+
+@omega.js/desktop carries @omega.js/web's FULL theme tree in `<em>/dist/assets/themes/` — vendored from the resolved `@omega.js/web` devDependency at every prepare via the declared-assets channel (C4 cp104/cp109), never hand-copied:
+
+| Theme | Base | Use case |
+|---|---|---|
+| `classy` (default) | Bootstrap 5.3 + OMEGA design system | Polished, modern app shell |
+| `bootstrap` | Plain Bootstrap 5.3 | Minimal, vanilla Bootstrap |
+| `neobrutalism` / `newsflash` | Bootstrap 5.3 | Alternate skins (universal `theme.id`) |
+
+The active theme is selected via `config.theme.id` (default `'classy'`). The `gulp/sass` task adds `<em>/dist/assets/themes/<theme>` to its sass `loadPaths` so the bare `@use 'theme'` import inside `@omega.js/desktop.scss` resolves to the active theme.
+
+## Consumer setup
+
+Your `src/assets/scss/main.scss` becomes:
+
+```scss
+@use 'omega-desktop' as * with (
+  $primary: #2563EB,
+  // $secondary: #6C757D,
+  // $border-radius: 0.5rem,
+);
+
+// Custom global styles below...
+main {
+  padding: 2rem;
+}
+```
+
+That single import gives you:
+- Full Bootstrap 5 (utilities, components, grid, etc.)
+- Classy theme overlays (typography, animations, refined spacing)
+- @omega.js/desktop's `_initialize.scss` (desktop-specific defaults — full-window body, app-region drag classes)
+
+## Per-page CSS
+
+@omega.js/desktop compiles per-page bundles in addition to the shared `main.bundle.css`:
+
+```
+src/assets/scss/main.scss          → dist/assets/css/main.bundle.css            (every page)
+src/assets/scss/pages/main.scss    → dist/assets/css/components/main.bundle.css       (main window only)
+src/assets/scss/pages/settings.scss → dist/assets/css/components/settings.bundle.css   (settings window only)
+src/assets/scss/pages/about.scss   → dist/assets/css/components/about.bundle.css      (about window only)
+```
+
+The page template auto-loads both: `main.bundle.css` is on every HTML page, and `components/<page.name>.bundle.css` is loaded only on its specific page. To add styles for a new page, drop a new file at `src/assets/scss/pages/<view>.scss` — it'll auto-compile and auto-inject.
+
+Per-page bundles can themselves `@use 'omega-desktop' as *;` if they need access to theme variables. Just be aware this means re-emitting some shared CSS — for very small per-page tweaks, prefer plain selectors that ride on the shared `main.bundle.css`.
+
+## Customizable variables
+
+The full classy variable list lives at `<em>/dist/assets/themes/classy/_config.scss`. ~60 variables you can override via the `@use ... with ()` form:
+
+**Colors:** `$primary`, `$secondary`, `$success`, `$info`, `$warning`, `$danger`, `$light`, `$dark`
+**Backgrounds (light mode):** `$classy-bg-light`, `$classy-bg-light-secondary`, `$classy-bg-light-tertiary`
+**Backgrounds (dark mode):** `$classy-bg-dark`, `$classy-bg-dark-secondary`, `$classy-bg-dark-tertiary`
+**Typography:** `$font-family-sans-serif`, `$font-family-base`, `$headings-font-weight`, `$classy-font-mono`, `$classy-font-accent`
+**Border radius:** `$border-radius`, `$border-radius-sm/lg/xl/2xl/pill`
+**Spacing, transitions, shadows** — see `_config.scss`
+
+## Switching themes
+
+Set `config.theme.id` in `config/omega.json5`:
+
+```jsonc
+theme: {
+  id:         'bootstrap',     // 'classy' (default) | 'bootstrap'
+  appearance: 'system',        // 'system' (default) | 'light' | 'dark'
+}
+```
+
+## Appearance (light / dark / system) — `manager.theme`
+
+@omega.js/desktop owns appearance at runtime. `config.theme.appearance` is only the **app default**; the resolved appearance is applied and kept live by the theme lib:
+
+- **`'system'` (default)** follows the OS preference **live** — when the OS flips, every page updates without a reload or restart.
+- **`'light'` / `'dark'`** are explicit overrides.
+- A user's runtime choice (`manager.theme.set(...)`) is **persisted in `manager.storage`** (`theme.appearance`) and wins over the config default on every boot.
+
+### How it propagates
+
+Everything rides on Electron's `nativeTheme.themeSource` (same three values). Setting it flips `prefers-color-scheme` in **every renderer of the app — BrowserWindows AND embedded WebContentsViews** — and @omega.js/desktop's preload applier listens via `matchMedia` and rewrites `<html data-bs-theme>` to the **resolved** value (`'light'`/`'dark'`) live. No IPC fan-out, no per-window wiring; native UI (menus, dialogs) follows too.
+
+The applier is **opt-in by presence**: it only manages pages whose `<html>` already carries `data-bs-theme` (stamped by the page template at build). External sites loaded in a consumer's embedded web views get the same preload but are never touched.
+
+### API
+
+```js
+// Main
+manager.theme.get();          // 'system' | 'light' | 'dark'  (the chosen source)
+manager.theme.resolved();     // 'light' | 'dark'             (what's showing)
+manager.theme.set('dark');    // apply + persist (throws on invalid values)
+const unsub = manager.theme.onChange(({ source, resolved }) => { ... });
+
+// Renderer (any page with the @omega.js/desktop preload)
+await window.desktop.theme.get();        // { source, resolved }
+await window.desktop.theme.set('dark');  // → { source, resolved }
+const unsub = window.desktop.theme.onChange(({ resolved }) => { ... }); // matchMedia-powered
+```
+
+Main also broadcasts `desktop:theme:changed { source, resolved }` to BrowserWindows as a courtesy — but renderers should rely on `onChange`/matchMedia, which works in every context.
+
+### Declarative controls
+
+Any element with `data-omega-theme-set` becomes a theme switch (wired by the renderer Manager's initialize — event-delegated, so late-rendered controls work):
+
+```html
+<button data-omega-theme-set="light">Day</button>
+<button data-omega-theme-set="dark">Dusk</button>
+<button data-omega-theme-set="system">Auto</button>
+```
+
+### Build-time stamp
+
+`data-bs-theme="{{ theme.appearance }}"` is still stamped into every page at build. For `'light'`/`'dark'` the stamp is already correct; `'system'` stamps an inert value that the preload applier replaces with the resolved appearance at `DOMContentLoaded` (Bootstrap treats unknown values as light for the instant before that).
+
+## Where the themes live
+
+The SSOT is **`@omega.js/web/themes/`** — one theme tree for web, desktop, and extension (C4 cp109: the classy triplication is dead). @omega.js/desktop declares `omega.vendorAssets` in its package.json, and every `prepare-package` run copies the resolved web package's `themes/` into `<em>/dist/assets/themes/`. Consumers import via the sass `loadPaths` mechanism — **nothing is ever copied into the consumer's tree**. Desktop-specific theme bits (the `.omega-titlebar` component, the `$min-contrast-ratio` knob) were upstreamed INTO the shared classy rather than kept as a fork.
+
+## Updating themes
+
+A theme change lands once in `packages/web/themes/` and rides into desktop + extension on their next prepare. There is no sync step and no version skew — dist is rebuilt from the resolved web package every time. (A standalone `@omega.js/themes` package was considered and rejected for now: the vendor channel gives one-source semantics without another publishable surface.)
+
+## Gotchas
+
+### Sass `@import` deprecation warnings
+Classy's `_theme.scss` uses `@import` (Sass's legacy module system) for its own internal layout. You'll see a deprecation warning during compile. UJM has the same warning. Functional today; will be migrated when classy upgrades to fully-modular `@use`/`@forward`.
+
+### Per-page CSS bundles are 0 bytes by default
+Empty `pages/<name>.scss` produces empty bundles. That's fine — the page template still loads them, the browser just gets a 200 with no rules. Adding any selector populates it.

package/docs/tooltips.md

@@ -0,0 +1,99 @@
+# Bootstrap JS & Tooltips
+
+@omega.js/desktop ships **Bootstrap's JavaScript** (v5.3, Popper inlined) as a prebuilt bundle
+— `assets/js/bootstrap.bundle.js` — loaded by the renderer
+bootstrap. Consumers add **zero setup** and never vendor Bootstrap JS
+themselves.
+
+## Tooltips (auto-initialized)
+
+Bootstrap makes tooltips opt-in (they need a JS instance per element); @omega.js/desktop does
+the opt-in for you. Any element carrying the standard Bootstrap markup gets a
+live tooltip:
+
+```html
+<button class="btn btn-primary" data-bs-toggle="tooltip" data-bs-title="Saves and continues">
+  Save
+</button>
+```
+
+The renderer bootstrap (`renderer.js _wireTooltips`) initializes every
+`[data-bs-toggle="tooltip"]` present at init and watches the DOM:
+
+- elements **inserted later** get their tooltip on arrival,
+- **`data-bs-title` / `title` changes** update the live instance in place
+  (emptying the title disposes it — no tooltip is a valid state),
+- **removed elements** have their instance disposed — no orphaned tips.
+
+Plain-`title` hosts work: Bootstrap's constructor MOVES `title` into
+`data-bs-original-title`, and the observer reads that bookkeeping as a live
+title source. (It must — reading only `title`/`data-bs-title` made the
+observer dispose the instance, dispose restored `title`, re-init removed it
+again: an infinite MutationObserver microtask loop that froze the whole
+renderer. Found by Somiibo's session-limits boot suite; regression-tested in
+the tooltips suite.) One knock-on: a title-only host can't be disposed by
+emptying its title — remove `data-bs-toggle` instead (prefer `data-bs-title`
+for dynamic tooltips).
+
+All the standard Bootstrap `data-bs-*` options work (`data-bs-placement`,
+`data-bs-delay`, …).
+
+### Disabled controls
+
+Bootstrap's own caveat: disabled elements don't fire hover events. Wrap the
+control and put the tooltip on the wrapper:
+
+```html
+<span data-bs-toggle="tooltip" data-bs-title="Requires the Pro plan">
+  <button class="btn btn-primary" disabled>Bulk import</button>
+</span>
+```
+
+## The rest of Bootstrap's JS
+
+The full namespace is exposed at **`window.bootstrap`** (and
+`manager.bootstrap`) — `Tooltip`, `Popover`, `Collapse`, `Dropdown`, `Modal`,
+`Offcanvas`, `Tab`, `Toast`, `Alert`, `Button`, `Carousel`, `ScrollSpy`. Only
+tooltips are auto-initialized; the other components' standard **data-api**
+works out of the box on plain Bootstrap markup (e.g.
+`data-bs-toggle="collapse"`), and everything is available for manual control:
+
+```js
+const collapse = window.bootstrap.Collapse.getOrCreateInstance(el);
+collapse.show();
+```
+
+## Rebuilding the bundle
+
+`assets/js/bootstrap.bundle.js` is a COMMITTED prebuilt artifact — no gulp task
+rebuilds it, so a normal build never regenerates it. The checked-in bytes are a
+legacy webpack UMD build, from before [#737](https://github.com/Omega-JS-Stack/omega/issues/737)
+took webpack out of desktop.
+
+Rebuild only when the vendored Bootstrap source is upgraded, with esbuild — the
+one bundler desktop still has. The input is @omega.js/desktop's vendored
+Bootstrap 5.3 source (the vendored themes tree) plus `@popperjs/core` (an
+@omega.js/desktop dependency), and the output has to keep the contract its two
+consumers rely on: `require()` hands back the Bootstrap namespace
+(`renderer.js` reads `.Tooltip` off it and assigns `window.bootstrap` itself),
+so the format is CommonJS:
+
+```bash
+esbuild bootstrap.js --bundle --minify --format=cjs \
+  --outfile=src/assets/js/bootstrap.bundle.js
+```
+
+Use `--format=iife --global-name=bootstrap` only if the bundle is ever loaded by
+a plain `<script>` tag instead — nothing does that today.
+
+Note: the bundle reads `document.documentElement` at import time — the renderer
+bootstrap defers loading it until the document exists (relevant when wiring
+runs from a preload, e.g. the test harness).
+
+## Testing
+
+- `src/test/suites/renderer/tooltips.test.js` — bundle loads, auto-init on
+  insertion, live retitle, dispose-on-removal, tip cleanup. (The harness wires
+  the renderer Manager in the preload world — see the suite header for the
+  world-split notes; single-world hover behavior is covered by consumer boot
+  suites.)