@omega.js/desktop 0.53.0 → 0.54.1

package/docs/environment-detection.md

@@ -1,112 +0,0 @@
-# Environment Detection
-
-`getEnvironment()` returns exactly ONE of three mutually-exclusive, exhaustive values:
-
-```javascript
-omega.getEnvironment()    // 'development' | 'testing' | 'production'
-
-omega.isDevelopment()     // true ONLY in development
-omega.isTesting()         // true ONLY in testing
-omega.isProduction()      // true ONLY in production
-```
-
-**ONE input, and no default** ([#817](https://github.com/Omega-JS-Stack/omega/issues/817)). `getEnvironment()` reads the `OMEGA_ENVIRONMENT` variable in Node, and the baked `OMEGA_BUILD_JSON.config.environment` in a renderer (which has no `process.env`). Nothing else is consulted: the `app.isPackaged`, `config.em.environment`, `OMEGA_BUILD_MODE` and `NODE_ENV` sniffs are gone, and a context with neither input **throws**, naming the variable. The old default here was `production`, so a plain `npm start` bundled itself as a production artifact while @omega.js/extension's copy of the same function answered `development` from the same inputs.
-
-**One implementation, shared with every sibling framework.** The four calls are `@omega.js/config`'s [environment.js](../../config/src/environment.js), the module @omega.js/extension, @omega.js/web, @omega.js/backend and @omega.js/client all answer from. @omega.js/desktop has four entry points (main / renderer / preload / build); [src/utils/mode-helpers.js](../src/utils/mode-helpers.js) re-exports the shared four beside desktop's own `getVersion()`. The build module exports them as plain functions, and every process's `omega` carries them as methods.
-
-```javascript
-omega.getEnvironment()                                // same answer in main / renderer / preload
-require('@omega.js/desktop/build').isTesting()        // the build module, for build-time scripts
-```
-
-**Who sets the input.** [src/build.js](../src/build.js) names it at LOAD, from the lane: `OMEGA_BUILD_MODE` (which `omega build` / `package` / `publish` / `release` and the boot runner's staged build all set) is `production` and WINS over an inherited value, so a production build spawned from a test run still bakes production; otherwise a lane that already named one keeps it (the test runners spawn their children naming `testing`), and a bare dev boot is `development`. The electron app that lane spawns inherits the variable. A PACKAGED app has no parent lane, so [src/main.js](../src/main.js) names it from the word the build baked into the artifact: that is a FALLBACK for the context with no input, never an override ([#925](https://github.com/Omega-JS-Stack/omega/issues/925)). A process that already carries `OMEGA_ENVIRONMENT` keeps it, which is why a test lane that boots a production artifact still answers `testing` inside it.
-
-**The renderer gets the running word too.** A page has no `process`, so its `omega` reads input 2, the baked `config.environment`, which is the word the BUILD was for. Those agree everywhere except a lane that boots a production artifact, so the preload (a Node context, it has the variable) exposes it on `window.desktop.environment` and [src/renderer.js](../src/renderer.js) applies it over the baked word at `initialize()`. Same precedence, one context removed: the running environment first, the bake second. No second signal exists.
-
-**The three checks are mutually exclusive**: exactly one is true. `isDevelopment()` is **false** during testing, and `isProduction()` is a real positive check (it is NOT `!isDevelopment()`).
-
-## Available helpers
-
-| Helper | Returns |
-|---|---|
-| `getEnvironment()` | `'development' \| 'testing' \| 'production'`: the one reader of the one input; throws when it is absent. |
-| `isDevelopment()` | `true` ONLY in development, and NOT testing. Derives from `getEnvironment()`. |
-| `isTesting()` | `true` ONLY in testing. Derives from `getEnvironment()`. |
-| `isProduction()` | `true` ONLY in production. A **real positive check**, NOT `!isDevelopment()`. |
-
-## Gating side effects — use the INTENTIONAL check
-
-Because there are three environments, never gate a side effect on a two-value assumption. State what you mean:
-
-```javascript
-// Production-only (skip OS side effects / real telemetry in dev AND testing):
-if (isProduction())  { /* do the real thing */ }
-if (!isProduction()) { /* skip / use the safe local behavior */ }
-
-// Local-or-test (anything that should run in BOTH dev and testing):
-if (isDevelopment() || isTesting()) { /* localhost URL, isolate userData, suppress login items */ }
-```
-
-**Avoid** `if (!isDevelopment())` or `if (env !== 'development')` to gate production behavior — those wrongly include `testing` as production and leak real side effects (login items, telemetry, auto-update) during test runs. This is the bug class that motivated the 3-value model. (A genuinely dev-only feature like live-reload is the exception: `env !== 'development'` correctly skips it in both testing and production.)
-
-## URL helpers
-
-```javascript
-omega.getApiUrl()  // the app's API URL: the SSOT for calling the backend
-```
-
-`getApiUrl()` / `getFunctionsUrl()` / `getWebsiteUrl()` resolve to **local** URLs (from the baked dev map, whose floor is the classic hosting / functions / website numbers) in development OR testing, and to production (`https://api.<brand.url host>` etc.) otherwise. They route through `this.getEnvironment()`, so they're correct everywhere without an argument: call them directly. Pass an explicit `env` arg (`getApiUrl('production')`) only to force a specific environment regardless of the current one, rarely needed, and mainly used by tests to pin a specific environment's mapping.
-
-`getAuthUrl()` builds the **sign-in URL that round-trips an auth token back to the app**: `<site>/signin?authReturnUrl=<site>/token?authReturnUrl=<brand.id>://auth/token`, where `<site>` is `getWebsiteUrl()` (same env split). The website's `/signin` page logs the user in (or bounces straight through if already signed in), its `/token` page mints a Firebase custom token via the backend, and the final redirect (`?authToken=<token>`, the ONE shape) deep-links the token into the app's built-in `auth/token` route → `omega.auth.handleToken()` → `signInWithCustomToken`. Use it for EVERY "Sign in" affordance an app exposes; never link the bare `/signin` page, which strands the login in the browser. Requires `brand.id` (the deep-link scheme) in config; throws when missing. The optional second arg `getAuthUrl(env, returnUrl)` overrides the chain's final hop: that's how `lib/auth-flow.js` swaps in its dev loopback return.
-
-**Apps should launch the flow through `omega.openAuthFlow()` (main process), not by opening `getAuthUrl()` themselves**: production opens `getAuthUrl()` externally as-is (the OS routes the custom scheme back), while dev/test, where the scheme is NOT OS-registered (protocol.js registers only in production, and macOS can't runtime-register schemes missing from the bundle's Info.plist), swap the final hop for a one-shot, nonce-checked loopback HTTP listener (RFC 8252 §7.3) that feeds the token into the SAME deep-link pipeline. Sign-in always happens in the user's REAL default browser (their existing session/SSO), never an embedded window. Requires @omega.js/client ≥ 4.3.4 on the website (`isValidRedirectUrl` accepts loopback hosts while the SITE runs in dev). See [src/lib/auth-flow.js](../src/lib/auth-flow.js).
-
-All three local helpers resolve from whichever channel the process has: the `OMEGA_*_PORT` env vars (the CLI that booted the stack publishes them), then the `dev` map the bundle baked into `OMEGA_BUILD_JSON` (a packaged main process has no parent env, so a bumped emulator port reaches it only this way, [#745](https://github.com/Omega-JS-Stack/omega/issues/745)). There is no third step: the classic numbers used to be hand-typed under them, and they are gone ([#834](https://github.com/Omega-JS-Stack/omega/issues/834)).
-
-| Helper | Env channel | Baked channel | Neither |
-|---|---|---|---|
-| `getApiUrl()` | `OMEGA_HTTPS_PORT`, else `OMEGA_HOSTING_PORT` | `dev.ports.https`, else `dev.ports.hosting` | throws |
-| `getFunctionsUrl()` | `OMEGA_FUNCTIONS_PORT` | `dev.ports.functions` | throws |
-| `getWebsiteUrl()` | `OMEGA_WEBSITE_PORT`, composed as `https://localhost:<port>` | `dev.origin` (the whole origin) first, else `dev.ports.website` | throws |
-
-The classics still reach these helpers, from the ONE place they are defined: the bundle task bakes `CLASSIC_PORTS` and `CLASSIC_DEV_ORIGIN` (`@omega.js/config`) as the FLOOR of the `dev` map, with the live stack's resolved numbers over them, so a dev artifact always carries a complete map. A read that finds none names the fact it wanted and the build step that writes it. A production build bakes no `dev` at all, which is correct: a packaged app has no local stack to reach.
-
-The first two rows are port chains: each cell names a port, and the helper builds the URL around it. The website row is an ORIGIN chain ([#747](https://github.com/Omega-JS-Stack/omega/issues/747)): the baked `dev.origin` the live website published carries scheme, host AND port, so it is the complete fact and outranks the port cell; only when it is absent does a port compose an origin, over **https**, because `omega dev` fronts its public port with the mkcert proxy by default and a port number alone can never say the scheme. Whenever the website published an origin, that is the same answer `@omega.js/client`'s `getDevWebsiteOrigin()` gives every other surface ([#262](https://github.com/Omega-JS-Stack/omega/issues/262)), and `getAuthUrl()` inherits it by construction.
-
-A resolved `OMEGA_HTTPS_PORT` (or a baked `dev.ports.https`) means `omega serve`'s mkcert proxy is up, so the api URL is https. That is the same chain @omega.js/extension's `getApiUrl()` walks, and the same one `omega.auth` uses for the auth emulator port (`OMEGA_AUTH_PORT` → `dev.ports.auth` → throw, [auth.md](auth.md)).
-
-Resolving local in test mode is required because tests hit the local emulator — without it, the app (and tests calling `getApiUrl()`) would leak to the live production server.
-
-> The URL helpers live in [src/utils/url-helpers.js](../src/utils/url-helpers.js) as plain functions of the instance (`getApiUrl(omega, environment)`), reading its `getEnvironment()`; each process class calls them from its own methods.
-
-## Where they live
-
-Source: [src/utils/mode-helpers.js](../src/utils/mode-helpers.js) for `getEnvironment()` + `is*()` + `getVersion()`; [src/utils/url-helpers.js](../src/utils/url-helpers.js) for the URL builders. Both modules export plain functions. [build.js](../src/build.js) exports the mode helpers as they are; the three process classes, [main.js](../src/main.js) (the methods mixed in from [lib/_environment-mixin.js](../src/lib/_environment-mixin.js)), [preload.js](../src/preload.js) and [renderer.js](../src/renderer.js), call them from their own methods (the renderer takes the environment four and `getApiUrl()` / `getFunctionsUrl()` from @omega.js/client's base class it extends).
-
-## How detection works
-
-`getEnvironment()` reads ONE input, and there is no precedence ladder under it
-([#817](https://github.com/Omega-JS-Stack/omega/issues/817)):
-
-1. **`process.env.OMEGA_ENVIRONMENT`**, wherever this context has a `process` (main, preload, build-time Node).
-2. **The baked `config.environment`** off the `omega` the call is made on, for a renderer, which has none. It is the build fact every OMEGA surface spells the same way ([#896](https://github.com/Omega-JS-Stack/omega/issues/896)). The preload hands the running word across to the renderer when the two differ, so this step answers the artifact's own build only when no lane named one ([#925](https://github.com/Omega-JS-Stack/omega/issues/925)).
-3. **Neither** is a loud error naming `OMEGA_ENVIRONMENT`. There is no default, because the four framework copies this replaced each had one and they disagreed.
-
-The lanes above supply that input, and the whole table of who names what lives in
-[docs/shared/config.md](../../../docs/shared/config.md).
-
-## Adding a new helper
-
-Write the function in a `src/utils/<topic>-helpers.js` module, export it from [build.js](../src/build.js), and call it from a method on each process class that needs it. Don't define a helper's logic inside one process class: that path leads to duplicated semantics. For anything environment-derived, derive from `getEnvironment()` rather than reading `process.env` / `app.*` directly, so there is one source of truth and no chance of drift.
-
-## Why this matters
-
-**One signal, used everywhere.** The test runners spawn their children naming `OMEGA_ENVIRONMENT=testing`; every piece of code that calls `isTesting()` (framework or consumer) then sees `true`, no need to invent a per-module env var.
-
-**Sub-modules check the same signal.** When framework code (an auto-update poll, a restart-manager registration) needs to skip side effects in tests, it checks `isTesting()` — the same answer the consumer's own code gets. No drift.
-
-**`is*()` can never disagree with `getEnvironment()`.** Because the checks derive from the single resolver instead of reading raw signals, there is exactly one definition of "what environment is this," and a wrong-but-confident gate is structurally impossible. Since #817 that holds ACROSS frameworks too: the resolver is one shared module, so @omega.js/desktop and @omega.js/extension can no longer answer differently from the same inputs.
-
-## See also
-
-- [test-framework.md](test-framework.md): `OMEGA_ENVIRONMENT=testing` is named automatically by the test runners; extended mode (`--extended` / `TEST_EXTENDED_MODE`) gates real external APIs.

package/docs/fontawesome.md

@@ -1,109 +0,0 @@
-# FontAwesome
-
-@omega.js/desktop serves the **brand's best available Font Awesome set** —
-Pro when the brand supplies one (see below), otherwise the **Free set**
-(solid + regular + brands, SVG) straight from its
-`@fortawesome/fontawesome-free` npm dependency — every consumer gets 2,600+
-icons with **zero setup**, fully offline, no icon font, no CDN, and nothing
-vendored inside the framework package.
-
-```html
-<button class="btn btn-primary">
-  <i class="fa-solid fa-rocket me-2"></i>Launch
-</button>
-```
-
-That's it. Any `<i>` element carrying `fa-*` classes — in static HTML or
-inserted dynamically at any time — gets the real SVG injected inline by the
-renderer bootstrap. No `initialize()` options, no imports.
-
-## One icon mechanism, every surface (C4 cp108)
-
-Icon SEMANTICS — valid names/styles, candidate lookup order (requested style,
-then the brands fallback), the injected root attributes, and alias mapping —
-live in **`@omega.js/client/modules/icon-core.js`**, the SAME module
-@omega.js/web's build-time inlining pass uses. Desktop and web can never
-drift on how an icon name resolves or what the served SVG looks like.
-
-## How it works
-
-- **Assets** — resolved through the root chain (cp111), best-first:
-  `OMEGA_FONTAWESOME_ROOT` download dir → `@fortawesome/fontawesome-pro`
-  when the brand installed it → `@fortawesome/fontawesome-free` (a declared
-  runtime dependency, always last so a partial brand set never loses icons
-  the free set has). Each root holds `svgs/<style>/*.svg` plus
-  `metadata/icon-families.json` for aliases (`search` → `magnifying-glass`).
-  Declared dependencies ride into packaged apps automatically (fs reads
-  through the asar transparently).
-- **Main lib** (`lib/fontawesome.js`): `omega.fontawesome.get(name, style)`
-  resolves an icon to its SVG string (`null` for unknown names — never
-  throws). Lookups are slug-sanitized via icon-core (the IPC channel can
-  never read outside the icon directories) and cached per app run. Serves
-  renderers over `desktop:fontawesome:get`.
-- **Preload bridge** — `window.desktop.fontawesome.get(name, style)` →
-  `Promise<svg | null>`.
-- **Renderer auto-render** (`renderer.js _wireFontAwesome`) — a thin
-  wrapper over **@omega.js/client's shared `icon-renderer`** (C4 cp112, the
-  same module web pages run): scan + MutationObserver for insertions AND
-  class changes (`el.className = 'fa-solid fa-stop'` re-renders in place;
-  dropping the classes clears the SVG), FA's family × weight class parsing
-  (`fa-sharp fa-light` → `sharp-light`; Pro markup without a Pro set stays
-  empty — never a wrong-style fallback), caching, and the
-  `data-omega-fa="<style>/<name>"` marker. Desktop supplies only the
-  transport: IPC to main's icon server.
-  The SVG is injected as a child of the `<i>`, sized `1em`/`currentColor` — it
-  inherits text color and scales with font-size (bump it via `font-size` or a
-  `fs-*` utility). Served SVGs also carry `overflow="visible"` (FA-kit parity:
-  `.svg-inline--fa { overflow: visible }`) — FA 7 glyphs may draw OUTSIDE
-  their viewBox (fa-lock's shackle peaks at y=-32 in a `0 0 384 512` box) and
-  the SVG-root default of `overflow: hidden` clips them flat.
-
-## Minimal surfaces
-
-The auto-render is wired by `initialize()`. A renderer that deliberately skips
-`initialize()` (e.g. a lightweight popover overlay with no auth) can enable JUST
-the icon pipeline on the same instance:
-
-```js
-import omega from '@omega.js/desktop/renderer';
-
-omega.enableFontAwesome();
-```
-
-## Supplying Font Awesome Pro (C4 cp111)
-
-Pro is brand-supplied, never redistributed by the framework. The two
-routes (FA npm token, or an `OMEGA_FONTAWESOME_ROOT` download dir), the
-chain semantics, and the style/family model are documented once at the
-repo hub: **[docs/shared/icons.md](../../../docs/shared/icons.md)**. Desktop-specific
-note: a packaged brand target declares `@fortawesome/fontawesome-pro` as its
-own **prod dependency** so the set ships inside the asar.
-
-## Notes
-
-- **The icon CSS is not desktop's.** The box, the size scale and the
-  `fa-spin`/`fa-bounce`/`fa-beat` utilities ride ONE sheet vendored from
-  @omega.js/web at prepare (see [css.md](css.md#icon-presentation)). Fix icon
-  presentation there, never here.
-- **Unknown names render nothing** — the `<i>` stays empty (marked
-  `data-omega-fa`). If you need a fallback, resolve through
-  `window.desktop.fontawesome.get()` and swap yourself.
-- **Free set = solid + regular + brands.** Pro styles (light/duotone/sharp)
-  need a supplied Pro set (above); otherwise
-  `omega.fontawesome.get(name, 'duotone')` returns `null`.
-- **Updating the set** — bump the `@fortawesome/fontawesome-free` dependency
-  (or reinstall/refresh the brand's Pro supply).
-
-## Testing
-
-- `src/test/suites/main/fontawesome.test.js` — resolution, aliases (via the
-  metadata map), sanitization (traversal attempts), caching, IPC round-trip,
-  the `overflow="visible"` serve attribute, and the cp111 root chain
-  (`OMEGA_FONTAWESOME_ROOT` wins, free set falls through for icons and
-  metadata the brand set lacks).
-- `src/test/suites/renderer/fontawesome.test.js` — the real-DOM proof of
-  the SHARED icon-renderer: inserted `<i>` elements get SVGs on the live
-  DOM, class changes re-render in place and class removal clears (cp112),
-  modifier classes are never mistaken for names, Pro family/weight classes
-  compose (Pro-adaptive assertions), unknown names stay empty, injected
-  SVGs compute `overflow: visible` (out-of-viewBox glyphs must not clip).

package/docs/hooks.md

@@ -1,89 +0,0 @@
-# Lifecycle Hooks
-
-Consumers can inject custom logic at well-defined points without forking @omega.js/desktop's gulp tasks. All hooks are **purely additive extension points** — @omega.js/desktop's core logic always runs first, the hook is called after (or before, depending on the lifecycle point), and a hook throwing only logs a warning, never breaks the build.
-
-## How hooks work
-
-1. @omega.js/desktop scaffolds empty hook files into `<consumer>/hooks/**/*.js` on every verb (`ensureTarget()`).
-2. At each lifecycle point, @omega.js/desktop checks for the file. If it exists, @omega.js/desktop loads + invokes it. If not, no-op.
-3. The hook signature is `async (ctx) => { ... }`, with `ctx` the ONE hook-argument shape every OMEGA framework passes, `{ build, projectRoot, mode }`: `build` is the build module (`require('@omega.js/desktop/build')`, one plain object of functions: `getConfig()`, `getPackage()`, `getRootPath()`, ...). Whatever it returns is awaited but ignored.
-4. **Failure semantics:**
-   - File missing entirely → logged informationally (`hook "<name>" not present at ... — skipping.`), build continues.
-   - File exists but fails to load (syntax error, etc.) → **throws**, build fails.
-   - File exists but doesn't export a function → **throws**, build fails.
-   - File loads + invokes the function and the function throws → **throws**, build fails.
-
-   In other words: a hook that doesn't exist is fine (you'll see one log line), but a hook that's broken in any way fails loudly. You should never silently ship a malformed hook to production.
-
-## Hooks reference
-
-| Hook file | When it runs | `ctx` shape |
-|---|---|---|
-| `hooks/build/pre.js`     | Before the build pipeline runs (`defaults` → `distribute` → `bundle` ...) | `{ build, projectRoot, mode }` |
-| `hooks/build/post.js`    | After the build pipeline finishes, before `electron-builder` packages anything | `{ build, projectRoot, mode }` |
-| `hooks/release/pre.js`   | Before `electron-builder build --publish always` | `{ build, projectRoot, mode }` |
-| `hooks/release/post.js`  | After the release publishes | `{ build, projectRoot, mode }` |
-| `hooks/deploy/pre.js`    | Inside `omega deploy`, after the local scaffold and before the network precheck, on both lanes (the dispatch and `--direct`); a dry run skips it, because a hook may act on the world ([#900](https://github.com/Omega-JS-Stack/omega/issues/900): the playground's prunes its release family down to the newest, so two releases stay live; the VERSION comes from `omega bump` at the brand root, [#869](https://github.com/Omega-JS-Stack/omega/issues/869), never from a hook) | `{ build, projectRoot, mode: 'production' }` |
-| `hooks/notarize/post.js` | After @omega.js/desktop's built-in macOS notarization completes (extension only — @omega.js/desktop's notarize is the real entrypoint) | electron-builder afterSign context |
-
-`mode` is `'production'` when `OMEGA_BUILD_MODE=true`, else `'development'`. A deploy hook always reads `'production'`: the verb runs outside a build, and what it is about to publish is a release.
-
-## Why this design
-
-- **Notarize specifically:** the consumer's `hooks/notarize/post.js` is **never** the electron-builder afterSign entrypoint. @omega.js/desktop's `gulp/build-config` injects `afterSign:` pointing at @omega.js/desktop's real notarize implementation (resolved via `require.resolve('@omega.js/desktop/hooks/notarize')`). @omega.js/desktop's real notarize calls into the consumer's `hooks/notarize/post.js` as a final post-step. So the consumer can never accidentally break notarization by editing the file — the file can be empty, malformed, or missing entirely and the app still notarizes correctly.
-- **Why no `hooks/notarize/pre.js`?** electron-builder's `afterSign` hook is the only signing-related extension point we control. Anything that would belong in a "pre-notarize" step belongs either in `hooks/release/pre.js` (whole-release-level prep, runs before the gulp release task), or in electron-builder's own `afterPack` / `afterAllArtifactBuild` configuration (per-artifact mutation). If you have a real use case that doesn't fit either, file an issue.
-- **Build/release hooks:** standard before/after lifecycle pattern, the same `ctx` @omega.js/extension hands its hooks.
-
-## Examples
-
-### Slack notification on release
-
-```js
-// hooks/release/post.js
-module.exports = async ({ build, projectRoot }) => {
-  const pkg = require(`${projectRoot}/package.json`);
-  const url = process.env.SLACK_WEBHOOK_URL;
-  if (!url) return;
-  await fetch(url, {
-    method: 'POST',
-    headers: { 'content-type': 'application/json' },
-    body: JSON.stringify({ text: `🚀 ${pkg.name} v${pkg.version} released` }),
-  });
-};
-```
-
-### Generate changelog before build
-
-```js
-// hooks/build/pre.js
-const { execSync } = require('child_process');
-const fs = require('fs');
-const path = require('path');
-
-module.exports = async ({ projectRoot }) => {
-  const log = execSync('git log --oneline -n 20', { cwd: projectRoot });
-  fs.writeFileSync(path.join(projectRoot, 'CHANGELOG_LATEST.txt'), log);
-};
-```
-
-### Custom post-notarize archive
-
-```js
-// hooks/notarize/post.js
-const fs = require('fs');
-const path = require('path');
-
-module.exports = async (context) => {
-  const { appOutDir, packager } = context;
-  const appName = packager.appInfo.productFilename;
-  const appPath = path.join(appOutDir, `${appName}.app`);
-  // e.g. archive a copy somewhere off the build path
-  fs.cpSync(appPath, `/tmp/omega-archive/${appName}-${Date.now()}.app`, { recursive: true });
-};
-```
-
-## Tests
-
-- `src/test/suites/build/run-consumer-hook.test.js` — silent skip, invocation with args, error swallowing.
-- `src/test/suites/build/deploy-hook.test.js`: `omega deploy` runs `hooks/deploy/pre.js` after the scaffold and before the precheck; a dry run skips it.
-- `src/test/suites/build/build-config.test.js` — `injectAfterSign` always points at @omega.js/desktop's notarize.

package/docs/icons.md

@@ -1,79 +0,0 @@
-# Icons
-
-Convention-only. No config block — drop PNGs at known paths and @omega.js/desktop finds them.
-
-## Layout
-
-```
-config/icons/
-  global/             ← used by any platform with no platform-specific override
-    icon.png
-    tray.png
-  mac/                ← macOS overrides (beats global)
-    icon.png
-    tray.png          ← 32×32 native; @omega.js/desktop renames to trayTemplate.png in dist
-    dmg.png           ← 1080×760 DMG installer background
-  windows/            ← Windows overrides
-    icon.png
-    tray.png          ← optional; falls back to icon.png
-  linux/              ← Linux overrides
-    icon.png
-    tray.png
-```
-
-## Resolution chain (per slot, per platform)
-
-Most specific wins:
-
-1. `<projectRoot>/config/icons/<platform>/<file>` — platform-specific override
-2. `<projectRoot>/config/icons/global/<file>` — universal fallback shared by all platforms
-3. `<projectRoot>/config/icons/windows/<file>` — Linux-only extra step (legacy compat — Linux apps historically reuse Windows assets)
-4. `<@omega.js/desktop>/dist/config/icons/<platform>/<file>` — @omega.js/desktop bundled default
-5. `<@omega.js/desktop>/dist/config/icons/windows/<file>` — Linux-only extra step at the bundled level
-
-Inside the runtime tray lookup (`lib/tray.js`), tray-slot misses fall back to the app icon (`icon.png`) instead of returning null.
-
-## Sizes — ship @2x native only
-
-Retina slots (macOS tray, macOS dmg) take ONE source file at the native (@2x) size. @omega.js/desktop downscales the @1x sibling at build time via `sharp` and writes both into `dist/`. Consumers never ship `<name>@2x.png` files.
-
-| Slot | Native size | @omega.js/desktop emits |
-|---|---|---|
-| `mac/tray.png` | 32×32 | `trayTemplate.png` (16×16) + `trayTemplate@2x.png` (32×32) |
-| `mac/dmg.png` | 1080×760 | `dmg.png` (540×380) + `dmg@2x.png` (1080×760) |
-| `mac/icon.png` | 1024×1024 | `icon.png` (unchanged; electron-builder converts to `.icns`) |
-| `windows/icon.png` | 1024×1024 | `icon.png` (unchanged; electron-builder converts to `.ico`) |
-| `linux/icon.png` | 1024×1024 | `icon.png` (unchanged) |
-
-## Why `trayTemplate.png` on disk
-
-macOS reads the literal filename of the tray icon and treats any `*Template.png` as a "template image" — pure-black with alpha, automatically inverted in dark mode. Consumers ship `tray.png` (clearer naming, matches Windows/Linux); @omega.js/desktop owns the `Template` suffix when writing to `dist/`.
-
-If you set a custom path via `tray.icon(path)` in your `src/integrations/tray/index.js`, YOU are responsible for the runtime filename containing `Template` — @omega.js/desktop only owns the convention path.
-
-## Two common scenarios
-
-**One icon for everything:**
-
-```
-config/icons/global/icon.png    # mac + win + linux
-config/icons/global/tray.png    # mac + win + linux
-```
-
-**Mac-specific + shared Win/Linux:**
-
-```
-config/icons/global/icon.png    # win + linux use this
-config/icons/mac/icon.png     # mac override
-config/icons/mac/tray.png     # mac-specific tray (will become trayTemplate.png in dist)
-config/icons/mac/dmg.png      # mac-only by definition
-```
-
-## Source files
-
-- `src/lib/sign-helpers/resolve-icons.js` — the resolver itself; called from `gulp/build-config.js`.
-- `src/lib/tray.js#_defaultIconPath` — runtime tray lookup (same convention waterfall, but checks `dist/` first since the build already resolved).
-
-## Bundled defaults
-
-@omega.js/desktop ships its own `icon.png`, `tray.png`, `dmg.png` for each platform in `<@omega.js/desktop>/src/defaults/config/icons/<platform>/`. These are the final fallback when neither the consumer nor a global file provides anything — so a freshly scaffolded project produces a buildable app with the generic @omega.js/desktop icon out of the box.