@omega.js/desktop 0.53.0 → 0.54.1

package/docs/common-mistakes.md

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

package/docs/config-schema.md

@@ -1,120 +0,0 @@
-# Config schema
-
-@omega.js/desktop validates `config/omega.json5` against the canonical OMEGA schema in **`@omega.js/config`** (vendored into `dist/vendor/config/` at prepare time; also exposed to consumers as `require('@omega.js/desktop/config')`). The shared schema covers the cross-framework sections (brand, cloud, analytics, payment, monitoring, connections, theme, targets); the desktop-specific refinements (app.category, the `platforms` shipping declaration, platforms.windows.signing.strategy, startup.mode, restartManager.*, …) live in the same package's `TARGET_SCHEMAS.desktop` and apply when validating with `{ target: 'desktop' }`. Validation always runs against the RESOLVED config: `targets.desktop` contents land at the top level (see the monorepo's `docs/shared/config.md` for the format).
-
-Validation runs in two places:
-
-1. **`omega.initialize()` (boot, main)**: hard-fails the app at boot if any required field is missing or any present field is invalid. So a misconfigured app never reaches the "white window of confusion" phase: it tells you exactly which field is broken.
-2. **`gulp audit` (build)**: same schema, plus build-pipeline-specific extras (file-existence for icons, an addressable releases repo in publish mode, etc.).
-
-## Schema entry shape
-
-```js
-{
-  path:        'brand.id',                     // dot-path into the config
-  type:        'string' | 'boolean' | 'number' | 'array' | 'object',
-  required:    true | false | (config) => bool,
-  match:       /^[a-z][a-z0-9+\-.]*$/,         // string-value regex
-  enum:        ['normal', 'hidden'],           // value-must-be-in-this-list
-  description: 'Used for the deep-link scheme + default appId.',
-}
-```
-
-## The `required` flag
-
-@omega.js/desktop keeps validation simple: **`required` is either `true`, `false`, or a function**.
-
-```js
-required: true                    // hard-fail if missing
-required: false                   // OK to omit (but if present, match/enum/type still run)
-required: (cfg) => bool           // conditional — predicate gets the full config
-```
-
-The function form is for "this field is mandatory only when another part of config is set." Illustrative shape (no current entry uses it — every present-day field is `true` or `false`):
-
-```js
-{
-  path:     'analytics.providers.google.id',
-  required: (cfg) => Boolean(cfg?.analytics?.providers?.google?.secret),  // id mandatory only when a secret is configured
-  match:    /^G-[A-Z0-9]+$/,
-}
-```
-
-This is identical strictness in dev and production. There's no separate `'publish-only'` tier — if a field truly matters only for builds, validate it inside `gulp/audit.js` (next to `fileMustExist` calls for icons, etc.) rather than the schema.
-
-## How `match` / `enum` / `type` interact with absence
-
-They **only run when the value is present**. A missing field with `required: false` is silent. A missing field with `required: true` fires the "missing" error and nothing else — so consumers don't see a confusing flood of "missing AND wrong type AND doesn't match" for the same field.
-
-## Presence-driven feature flags (@omega.js/backend convention)
-
-A non-empty credential value enables a feature — there is no separate `enabled: true/false` flag for credential-gated features:
-
-| Feature | Enable signal | Disable signal |
-|---|---|---|
-| Sentry | `monitoring.providers.sentry.dsn = 'https://...'` | `monitoring.providers.sentry.dsn = ''` |
-| GA4 analytics | `analytics.providers.google.id = 'G-XXXXX'` | `analytics.providers.google.id = ''` |
-| Firebase Auth (renderer) | `cloud.config.projectId = '...'` (etc.) | empty `cloud.config` |
-
-**Exceptions where an explicit `enabled` flag exists:** `remoteConfig.enabled`, `autoUpdate.enabled`, `releases.enabled`, `restartManager.enabled`, `startup.openAtLogin.enabled`. (`platforms.linux.snap.enabled` was one until [#867](https://github.com/Omega-JS-Stack/omega/issues/867): the snap is a declared FORMAT now, so its presence is the switch and `platforms.linux.formats.snap: false` is the off.) These toggle BEHAVIOR, not credentials: a fork can keep the brand's `repo.org` and still want releases off, for example.
-
-## Adding a new field
-
-When you add a new config knob anywhere in @omega.js/desktop:
-
-1. Add an entry to `TARGET_SCHEMAS.desktop` in `@omega.js/config` (`packages/config/src/schema.js` in the Omega monorepo) — or to `SHARED_SCHEMA` if the field is genuinely cross-framework.
-2. If it has a default, set it in [`src/defaults/config/omega.json5`](../src/defaults/config/omega.json5) (under `targets.desktop` for desktop-scoped fields).
-3. That's it. No separate validation logic to add elsewhere — the schema entry is the validation.
-
-## What's NOT in the schema
-
-These checks live in [`gulp/tasks/audit.js`](../src/gulp/tasks/audit.js) instead, because they depend on build-pipeline state rather than the config shape:
-
-- **`src/main.js` / `src/preload.js` existence** — the bundle task skips them with a warning but the schema doesn't know about consumer entry points.
-- **`brand.images.icon` file existence** — only enforced when packaging (`isBuildMode()` / `isPublishMode()`); dev runs with the default Electron icon.
-- **An addressable releases repo** (`repo.org` + `brand.id`), only enforced in publish mode.
-
-These are kept in `audit.js` so the schema stays a pure description of the config shape, callable from any context without dragging in build state.
-
-## Examples
-
-Required field missing:
-
-```
-@omega.js/desktop: config validation failed — fix the following in config/omega.json5:
-  1. config.brand.id is required — URL-scheme-safe slug. Used as deep-link scheme + default appId. Must be lowercase, start with a letter, alnum/+/-/.
-```
-
-Field present but invalid:
-
-```
-  1. config.startup.mode "tray-only" is not allowed — must be one of [normal, hidden]
-  2. config.brand.id "My App!" does not match expected pattern /^[a-z][a-z0-9+\-.]*$/ — URL-scheme-safe slug. Used as deep-link scheme + default appId. Must be lowercase, start with a letter, alnum/+/-/.
-```
-
-Errors are numbered so you can fix everything in one pass instead of fix-rebuild-fix-rebuild.
-
-## Adding payment fields (@omega.js/backend-shaped)
-
-@omega.js/desktop's schema mirrors [@omega.js/backend's `manager-config.example.json`](https://github.com/itw-creative-works/backend-manager) shape for payment so the same product catalog reads identically on backend, web, and desktop:
-
-```js
-{
-  payment: {
-    providers: {
-      stripe: { publishableKey: 'pk_live_...' },     // schema: match /^pk_(test|live)_/
-      paypal: { clientId: '...' },
-    },
-    products: [
-      { id: 'basic', name: 'Basic', type: 'subscription', limits: { credits: 100 } },
-    ],
-  },
-}
-```
-
-The schema only enforces shape for the few well-defined publishable keys — the product catalog itself is freeform so @omega.js/backend can extend it without @omega.js/desktop caring.
-
-## Source
-
-- Schema definitions + validator engine: `@omega.js/config` (`packages/config/src/{schema,validate}.js` in the Omega monorepo; vendored copy at `dist/vendor/config/`)
-- @omega.js/desktop integration tests: [`src/test/suites/build/validate-config.test.js`](../src/test/suites/build/validate-config.test.js)

package/docs/context-menu.md

@@ -1,112 +0,0 @@
-# Context Menu (Right-Click)
-
-File-based context menu. Unlike tray and application menu (called once at boot), the context-menu definition is called **every time the user right-clicks** — so it gets fresh `params` each time and can vary the menu by selection.
-
-## Config
-
-No config block. Path is conventional: `src/integrations/context-menu/index.js`. To opt out, call `omega.contextMenu.disable()` from your main entry: after that, right-click events are silently swallowed.
-
-## Definition file
-
-```js
-// src/integrations/context-menu/index.js
-module.exports = ({ omega, menu, params, webContents }) => {
-  // Easiest: start from @omega.js/desktop's defaults, then customize per event.
-  menu.useDefaults();
-
-  // Add a "Search Google" entry when text is selected:
-  if (params.selectionText) {
-    menu.insertAfter('copy', {
-      id: 'search-google',
-      label: `Search "${params.selectionText.slice(0, 20)}"`,
-      click: () => require('electron').shell.openExternal(
-        `https://google.com/search?q=${encodeURIComponent(params.selectionText)}`,
-      ),
-    });
-  }
-
-  // Hide the dev-tools entries even in development:
-  menu.remove('toggle-devtools');
-};
-```
-
-Calling no `menu.*` methods (or `menu.clear()` after `useDefaults()` with nothing added) **suppresses the popup** entirely.
-
-## Builder API (per event)
-
-```js
-menu.item(descriptor)
-menu.separator()
-menu.submenu(label, items)
-menu.useDefaults()             // populate with @omega.js/desktop's defaults based on params
-menu.clear()                   // wipe items added so far this event
-```
-
-## Id-path API (per event)
-
-Same shape across menu / tray / context-menu. Available **inside the definition fn** on the `menu` builder. Operates on the items being built for the current right-click event:
-
-```js
-.find(idPath)
-.has(idPath)
-.update(idPath, patch)
-.remove(idPath)
-.enable(idPath, bool = true)
-.show(idPath, bool = true)
-.hide(idPath)
-.insertBefore(idPath, item)
-.insertAfter(idPath, item)
-.appendTo(idPath, item)
-```
-
-Context-menu ids are **flat** — no `context/` prefix needed (the lib namespace is implicit). Submenus you build with `menu.submenu(...)` are addressable as `parent/child` paths via the resolver.
-
-(Runtime-on-`omega.contextMenu` mutators don't apply here: items are rebuilt every event. Mutate inside the definition fn instead.)
-
-## Default template ids
-
-@omega.js/desktop's `useDefaults()` populates items based on `params`. Every default item carries an id you can target:
-
-| ID | When it appears |
-|---|---|
-| `undo`, `redo` | `params.editFlags.canUndo` / `canRedo` |
-| `cut`, `copy`, `paste`, `paste-and-match-style`, `select-all` | `params.isEditable` |
-| `copy` | `params.selectionText` (read-only) |
-| `open-link`, `copy-link` | `params.linkURL` |
-| `reload` | always |
-| `inspect`, `toggle-devtools` | `omega.isDevelopment()` only |
-
-## Definition fn arguments
-
-| Arg | Description |
-|---|---|
-| `omega` | The running @omega.js/desktop main-process instance |
-| `menu` | Per-event builder + id-path API |
-| `params` | Electron's [`ContextMenuParams`](https://www.electronjs.org/docs/latest/api/web-contents#event-context-menu) — `selectionText`, `isEditable`, `linkURL`, `srcURL`, `mediaType`, `editFlags`, `x`, `y`, etc. |
-| `webContents` | The `webContents` that fired the event |
-
-## Auto-attach
-
-Every window created via `omega.windows.createNamed()` is automatically wired up with the context-menu listener. Idempotent per `webContents` (uses a `WeakSet`). For windows you create directly with `new BrowserWindow()`, call:
-
-```js
-omega.contextMenu.attach(win.webContents);
-```
-
-## Runtime API on `omega.contextMenu`
-
-```js
-omega.contextMenu.define(fn)              // replace the definition at runtime
-omega.contextMenu.disable()               // ignore future right-click events (idempotent)
-omega.contextMenu.attach(webContents)     // manual attach
-omega.contextMenu.buildItems(params, wc)  // run the definition without popping a menu (useful for tests)
-omega.contextMenu.hasCustomDefinition()   // false → using the built-in default fn
-```
-
-## Default fn
-
-Without a consumer file, @omega.js/desktop uses a built-in fallback that just calls `useDefaults()` — sensible undo/redo/cut/copy/paste/link/reload/inspect baseline. Same behavior as the default scaffold.
-
-## Default scaffold
-
-The scaffold every verb runs ships `src/integrations/context-menu/index.js` calling `menu.useDefaults()` plus commented-out examples covering insertAfter, remove, hide, enable, and building from scratch.

package/docs/context.md

@@ -1,81 +0,0 @@
-# Context
-
-Runtime info block. Mirrors @omega.js/backend's `assistant.request.{geolocation,client}` shape so @omega.js/desktop apps + sister projects (@omega.js/backend, UJM, @omega.js/client) all reference the same property paths when reading user info.
-
-Populated asynchronously during `omega.initialize()`.
-
-## Shape
-
-```js
-omega.context.geolocation = {
-  ip:      '203.0.113.42',     // async-fetched via ipify
-  country: null,               // future enhancement
-  region:  null,
-  city:    null,
-};
-
-omega.context.client = {
-  userAgent: 'Mozilla/5.0 ...',  // app.userAgentFallback
-  locale:    'en-US',            // app.getLocale()
-  platform:  'darwin',           // os.platform()
-  arch:      'arm64',            // os.arch()
-  mobile:    false,              // always false on @omega.js/desktop (desktop framework)
-};
-
-omega.context.session = {
-  id:        '<uuid>',           // fresh per launch (crypto.randomUUID)
-  startTime: '2026-05-08T...',   // ISO at boot
-  deviceId:  '<uuid or MAC>',    // stable per-machine
-};
-
-omega.context.app = {
-  version:     '1.2.3',          // omega.getVersion()
-  environment: 'production',     // omega.getEnvironment()
-  isPackaged:  true,             // app.isPackaged
-};
-```
-
-## Device ID resolution
-
-The walk itself is the shared one — `@omega.js/analytics`' `deriveDeviceId({ get, set, seed })`, the same call `@omega.js/client` makes on a page ([#396](https://github.com/Omega-JS-Stack/omega/issues/396)). What this module supplies is desktop's own world: electron-store, and the MAC as the seed. Order:
-
-1. **Storage** — already persisted from a prior boot. Wins so we're stable across NIC swaps / VPN changes.
-2. **First non-internal MAC** from `os.networkInterfaces()`, the injected seed. Stable on a stable rig, and it hands a reinstalled app the id it had before its storage was wiped.
-3. **A generated UUID** — the shared derivation's floor. Persisted on first launch.
-
-Once resolved on first launch it never changes. This is the input to `analytics._clientId = uuidv5(deviceId, projectIdNamespace)`, and it is desktop's alone: a browser on the same machine derives its own id from its own localStorage.
-
-## Geolocation
-
-`geolocation.ip` is fetched in the background via `https://api.ipify.org?format=json`. Cached to `storage.context.geolocation` so the next launch has last-known-good values even if offline. The `country/region/city` fields are reserved for a future enrichment provider.
-
-Failure mode: a failed ipify fetch leaves the previous cached value untouched. The app keeps working with last-known-good.
-
-## API
-
-```js
-omega.context.geolocation.ip            // direct read
-omega.context.session.deviceId          // direct read
-const snap = omega.context.toJSON();    // structured-cloneable snapshot
-```
-
-Renderer:
-
-```js
-const snap = await window.desktop.context.get();
-console.log(snap.session.deviceId);
-```
-
-## Why the @omega.js/backend shape
-
-Sister projects (@omega.js/backend, @omega.js/client, UJM) all reference paths like `assistant.request.geolocation.country` and `assistant.request.client.userAgent`. @omega.js/desktop matches the leaf names so consumer code can write logic that works across all four runtimes:
-
-```js
-const country = omega.context.geolocation.country
-             || assistant.request.geolocation.country  // @omega.js/backend
-             || omega.context.geolocation.country;
-```
-
-## Tests
-
-- `src/test/suites/main/context.test.js` — session shape, deviceId stability across re-init, the injected seed + persistence of the shared derivation, client info, IPC handler, JSON-roundtrippability.

package/docs/css.md

@@ -1,84 +0,0 @@
-# CSS Architecture
-
-@omega.js/desktop styles are SCSS, compiled by the pipeline's `sass` task into per-window bundles on top of a shared base. Bootstrap 5 (via @omega.js/desktop's classy theme) is the foundation — consumers restyle Bootstrap, they don't replace it.
-
-## Main entry
-
-`<consumer>/src/assets/scss/main.scss` — loaded by EVERY window. It configures the theme via `@use ... with (...)`:
-
-```scss
-// Generated from `brand.color` by the sass task (#912).
-@use 'brand';
-
-@use 'omega-desktop' as * with (
-  $primary: brand.$primary,
-  $dark: #1a1a2e,
-  $classy-bg-dark: #0f0f1a,
-  $classy-bg-dark-secondary: #161628,
-  $classy-bg-dark-tertiary: #1e1e38,
-);
-
-// The runtime --omega-accent ramp, after the framework import.
-@include brand.ramp;
-
-// Custom global styles below
-```
-
-Compiles to `dist/assets/css/main.bundle.css` (Bootstrap + classy theme + your globals).
-
-## Per-window styles
-
-`src/assets/scss/pages/<window>.scss` → `dist/assets/css/components/<window>.bundle.css`, loaded ONLY on that window's page. One file per window (`main.scss`, `settings.scss`, …) — page-specific chrome lives here, shared styles live in the main entry.
-
-## Theme integration
-
-The `@use 'omega-desktop'` entry pulls in Bootstrap 5 + @omega.js/desktop's classy theme. Appearance (`system`/`light`/`dark`) defaults from `config.theme.appearance` and is applied + kept live on `<html data-bs-theme>` by `omega.theme` (OS-following, runtime-switchable, persisted override, see [themes.md](themes.md)). Theme variables (`$primary`, `$dark`, `$classy-bg-*`, typography, borders) are overridable via the `with (...)` block, and `$primary` arrives from `brand.color` through the generated `dist/assets/scss/_brand.scss` unless a literal replaces `brand.$primary` ([#912](https://github.com/Omega-JS-Stack/omega/issues/912)). See [themes.md](themes.md) for the full variable reference.
-
-## Icon presentation
-
-Icon CSS is ONE sheet for every omega target, vendored from @omega.js/web at prepare (package.json `omega.vendorAssets` → `dist/assets/css/core/_fontawesome.scss`) and loaded by the `omega-desktop` entry. It ships the square glyph-centered box every rendered `<i>` gets, the `fa-2xs`…`fa-6xl` size scale, and the `fa-spin` / `fa-bounce` / `fa-beat` utilities (each parked under `prefers-reduced-motion`). Nothing to import and nothing to hand-fix. See [shared/icons.md](shared/icons.md).
-
-## App shell
-
-Dashboard/admin windows use the `.omega-shell` layout — a sidebar + topbar + main grid with a collapsible desktop rail and a mobile drawer. Two layers ship, both vendored from @omega.js/web at prepare: the MECHANICS (`dist/assets/css/shell/_index.scss` — the grid, region geometry, states, and the `--omega-shell-*` tokens, loaded by the `omega-desktop` entry before the theme) and the theme's SKIN (`dist/assets/themes/<theme-id>/css/layout/_shell.scss`, layered over it). Nothing to import — `@use 'omega-desktop'` gets both.
-
-Emit this markup in the window's HTML:
-
-```html
-<div class="omega-shell" data-omega-shell>
-  <aside class="omega-shell__sidebar" id="app-sidebar">
-    <!-- pinned head (brand, selector) sits here, outside the scroll region -->
-    <div class="omega-shell__sidebar-scroll">
-      <!-- nav scrolls HERE (the rail itself clips nothing, so popovers can
-           escape); text that should hide in the collapsed rail wears
-           .omega-shell__label -->
-    </div>
-  </aside>
-
-  <header class="omega-shell__topbar">
-    <div class="omega-shell__topbar-start">
-      <button data-shell-toggle="drawer" aria-expanded="false" aria-controls="app-sidebar">☰</button>
-      <button data-shell-toggle="collapse" aria-expanded="true" aria-controls="app-sidebar">⇤</button>
-    </div>
-    <div class="omega-shell__topbar-end"><!-- account menu, actions --></div>
-  </header>
-
-  <main class="omega-shell__main"><!-- page content --></main>
-
-  <div class="omega-shell__scrim" data-shell-dismiss></div>
-</div>
-```
-
-The renderer instance wires the behavior during `omega.initialize()` (the vendored `__main_assets__/js/core/app-shell.js`, the same module @omega.js/web runs), so a view that renders the markup needs no script of its own. The API is `omega.shell` (`isCollapsed`, `isOpen`, `setCollapsed`, `setOpen`, `toggleCollapsed`, `toggleOpen`).
-
-The module is delegated and declarative: `[data-shell-toggle="collapse"]` toggles the rail, `[data-shell-toggle="drawer"]` toggles the mobile drawer, `[data-shell-dismiss]` (and Escape) closes it. It stamps the state on the container: `data-shell-collapsed="true"` (persisted under the `shell.collapsed` storage key) and `data-shell-open="true"`, which is what the CSS keys off. Add `.omega-shell--locked` when `main` should never scroll (the page manages its own interior scroll).
-
-## Bootstrap-first convention
-
-NEVER create custom classes for things Bootstrap already provides — use `btn`, `card`, `form-*`, `d-flex`, `gap-*`, `rounded-*`, `bg-body-*`, `text-*` natively, and use `bg-body` variants (not `bg-light`/`bg-dark`) so dark mode adapts. Theme SCSS overrides how Bootstrap components LOOK; custom CSS is only for genuinely novel components with no Bootstrap equivalent. Same rule in BXM and UJM.
-
-## See also
-
-- [themes.md](themes.md) — theme variables, appearance modes
-- [build-system.md](build-system.md) — where the `sass` task runs in the pipeline
-- [templating.md](templating.md) — the page template that loads the bundles

package/docs/deep-link.md

@@ -1,186 +0,0 @@
-# Deep Links
-
-Cross-platform deep-link handling that's simple to use and hard to get wrong. @omega.js/desktop owns all the OS plumbing (single-instance lock, scheme registration, argv parsing, second-instance routing, focus-on-warm-start) and gives you one unified event API regardless of how the link arrived.
-
-## Config
-
-```jsonc
-"deepLinks": {
-  "schemes": ["myapp"]      // urls like myapp://...
-}
-```
-
-@omega.js/desktop registers each scheme with the OS via `app.setAsDefaultProtocolClient` so the system routes matching URLs to your app. Registration is **production-only**: dev/test runs never claim OS-wide protocol handlers for unpackaged Electron binaries. In dev, exercise your handlers with `omega.deepLink.dispatch(url)` instead.
-
-## How it works (so you don't have to think about it)
-
-| Platform | Cold-start (app not running) | Warm-start (app already running) |
-|---|---|---|
-| **macOS** | `app.on('open-url')` — queued before `whenReady`, drained after | `app.on('open-url')` |
-| **Windows** | URL appended to `process.argv`; @omega.js/desktop extracts it | OS forwards argv to the existing instance via `app.on('second-instance')`; @omega.js/desktop reads the duplicate's real argv from that event's `additionalData` |
-| **Linux** | Same as Windows | Same as Windows |
-
-@omega.js/desktop handles all of these and dispatches them through the same `omega.deepLink.on()` event registry. Your code looks identical regardless of platform or cold/warm start. Single-instance lock is acquired automatically (via `lib/protocol.js`); duplicate launches exit cleanly and forward their argv to the original instance.
-
-## Public API
-
-```js
-omega.deepLink.on(pattern, handler)    // register a handler. Returns unsubscribe fn.
-omega.deepLink.off(pattern, handler)
-omega.deepLink.dispatch(url)           // manually fire (testing, custom triggers)
-omega.deepLink.getColdStartUrl()       // the URL the app was launched with, or null
-```
-
-## Patterns
-
-```
-'auth/token'             // exact match
-'user/profile/:id'       // named param → ctx.params.id
-'org/:slug/repo/:repo'   // multiple params
-'*'                      // wildcard catch-all (only fires when no concrete handler matched)
-```
-
-## Handler signature
-
-```js
-omega.deepLink.on('user/profile/:id', (ctx) => {
-  ctx.url       // 'myapp://user/profile/42?ref=tray'
-  ctx.scheme    // 'myapp'
-  ctx.route     // 'user/profile/42'
-  ctx.pattern   // 'user/profile/:id'
-  ctx.params    // { id: '42' }
-  ctx.query     // { ref: 'tray' }
-  ctx.source    // 'cold-start' | 'warm-start' | 'manual'
-  ctx.argv      // process.argv (cold) or the duplicate's real argv (warm, from additionalData)
-  ctx.cwd       // working directory (the duplicate's on warm-start)
-  ctx.handled   // mutable: set true to suppress remaining handlers (including built-ins)
-});
-```
-
-## Built-in routes
-
-@omega.js/desktop ships with handlers for common patterns. They run AFTER consumer handlers, so you can shadow any of them by registering your own handler at the same pattern.
-
-| Route | Default behavior |
-|---|---|
-| `auth/token` | Calls `omega.auth.handleToken(query.authToken)`: the receiving end of the `omega.openAuthFlow()` sign-in round-trip. MODERN shape only (`?authToken=`, what the website's token page sends); other formats (`?token=`, `?payload=`) are ignored. In production the URL arrives via the OS scheme; in dev/test `lib/auth-flow.js`'s loopback listener dispatches the same URL manually (the scheme isn't OS-registered in dev: protocol.js registers only in production, and macOS can't runtime-register unlisted schemes at all) |
-| `app/show` | `omega.windows.show(query.window || 'main')` |
-| `app/quit` | `app.quit()` |
-
-### Overriding a built-in
-
-```js
-// Replace the built-in app/show with custom logic.
-omega.deepLink.on('app/show', (ctx) => {
-  if (ctx.query.window === 'admin' && !omega.appState.isAdminUser()) {
-    showError('not authorized');
-    ctx.handled = true;       // suppress built-in
-    return;
-  }
-  // Otherwise let the built-in run normally.
-});
-```
-
-## Resolution order
-
-For each incoming URL, @omega.js/desktop walks handlers in this order:
-
-1. **Consumer concrete handlers** (any non-wildcard pattern you registered with `.on()`)
-2. **Built-in concrete handlers** (`auth/token`, `app/show`, `app/quit`)
-3. **Wildcard handlers** (`'*'`) — only if NO concrete handler matched
-
-Setting `ctx.handled = true` in any handler stops the cascade. Within a single tier, handlers fire in registration order. Errors in a handler are caught and logged — they don't stop subsequent handlers.
-
-## Common patterns
-
-### Route to a window + send IPC
-
-```js
-omega.deepLink.on('user/profile/:id', (ctx) => {
-  omega.windows.show('main');
-  omega.windows.get('main').webContents.send('navigate', {
-    to: `/profile/${ctx.params.id}`,
-  });
-});
-```
-
-### Catch-all logger
-
-```js
-omega.deepLink.on('*', (ctx) => {
-  omega.logger.warn(`Unrouted deep link: ${ctx.url}`);
-});
-```
-
-### Cold-start branching
-
-```js
-const coldUrl = omega.deepLink.getColdStartUrl();
-if (coldUrl) {
-  omega.logger.log(`Launched from deep link: ${coldUrl}`);
-  // appState.launchedFromDeepLink() is also set automatically
-}
-```
-
-### Manually dispatching (e.g. from a tray click)
-
-```js
-tray.item({
-  label: 'Open Profile',
-  click: () => omega.deepLink.dispatch('myapp://user/profile/me'),
-});
-```
-
-## Boot queueing
-
-Every dispatch is held until `omega.initialize()` completes (main.js calls `deepLink.markOmegaReady()` as its last step). A cold-start `auth/token` link (the OS launching the app from the sign-in round trip) therefore never fires before `omega.auth` has Firebase up; it queues and drains the moment the instance is ready. Warm-start dispatches on a running app pass straight through.
-
-## Single-instance behavior
-
-@omega.js/desktop acquires the OS-level single-instance lock during `protocol.initialize()` (boot step 5, before deep-link inits). If another copy of the app is already running:
-
-1. The new instance loses the lock.
-2. The OS forwards its argv to the original instance.
-3. The new instance's `omega.initialize()` halts (after `protocol.hasSingleInstanceLock() === false`): the duplicate quits and its promise never settles.
-4. The original instance's `app.on('second-instance')` fires with the Chromium-processed argv as its second argument AND the duplicate's real argv as its fourth, `additionalData` (@omega.js/desktop passes `{ argv, cwd }` to `app.requestSingleInstanceLock()` for you).
-5. @omega.js/desktop extracts the deep-link URL from that argv and dispatches normally — but as `source: 'warm-start'`.
-6. @omega.js/desktop also focuses the existing main window automatically (consumer can override by registering a route handler that does its own thing).
-
-Reading the duplicate's own flags (a CLI-shaped app, a `--open <file>` handler) means reading that fourth argument:
-
-```js
-app.on('second-instance', (event, argv, cwd, additionalData) => additionalData.argv);
-```
-
-Never parse the event's own `argv` for flags: Chromium re-serializes it (switches first, Chromium's own switches spliced in, the values detached at the end), so a `--message two` launch arrives with the value detached from the flag.
-
-## Linking with `appState`
-
-When a deep link is detected at cold-start, @omega.js/desktop calls `omega.appState.setLaunchedFromDeepLink(true)`. This means:
-
-```js
-if (omega.appState.launchedFromDeepLink()) {
-  // user clicked a link to launch the app — handle differently than a tray click or login launch
-}
-```
-
-Combine with `appState.isFirstLaunch()` to detect "first launch via deep link" (e.g. from an onboarding flow on your website).
-
-## Testing
-
-The dispatch pipeline is unit-testable without actually triggering an OS event:
-
-```js
-omega.deepLink.dispatch('myapp://auth/token?token=test');
-// Fires source='manual'. Handlers run synchronously.
-```
-
-See `src/test/suites/main/deep-link.test.js` for the full coverage.
-
-## Implementation notes
-
-- `lib/protocol.js` owns the single-instance lock + scheme registration; `lib/deep-link.js` owns the dispatch pipeline. They're separate modules but tightly coupled.
-- OS scheme registration is gated on `omega.isProduction()` (in `lib/protocol.js`): unpackaged dev/test binaries are never registered as system protocol handlers (unconditional registration also intermittently triggered macOS Launch Services `-600` dialogs during test runs).
-- On Windows/Linux, scheme registration uses `app.setAsDefaultProtocolClient(scheme, process.execPath, [process.cwd()])` so `app.exe scheme://...` style invocations route argv correctly.
-- macOS open-url events that arrive before `whenReady` are queued internally and drained on `deepLink.initialize()`.
-- Argv extraction walks backward from the end of argv (where the URL typically sits) and matches against registered schemes.