@omega.js/desktop 0.1.0

package/LICENSE

@@ -0,0 +1,98 @@
+Copyright (c) 2026 ITW Creative Works
+
+Licensor: ITW Creative Works
+Software: @omega.js/desktop
+
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor’s trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that
+organization. **control** means ownership of substantially all the assets of an
+entity, or the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,166 @@
+<p align="center">
+  <a href="https://itwcreativeworks.com">
+    <img src="https://cdn.itwcreativeworks.com/assets/itw-creative-works/images/logo/itw-creative-works-brandmark-black-x.svg" width="100px">
+  </a>
+</p>
+
+<p align="center">
+  <strong>OMEGA Desktop</strong> — all-in-one development framework for Electron apps. Sister project to
+  <a href="../extension/">@omega.js/extension</a> and
+  <a href="https://github.com/itw-creative-works/ultimate-jekyll-manager">Ultimate Jekyll Manager</a>.
+</p>
+
+## What it does
+
+- **One-line bootstrap** per Electron process: `require('@omega.js/desktop/main')`, `/preload`, `/renderer`.
+- **Modular feature library** — storage, IPC, theme, tray, menu, context menu, window manager, startup, app-state, deep-link, auto-updater, @omega.js/client auth, Sentry, **analytics, context, usage, remote-config, restart-manager**. Each feature is its own module with documented API.
+- **System-aware dynamic theme.** `manager.theme` follows the OS light/dark preference **live** by default (`'system'`), with `'light'`/`'dark'` overrides persisted across boots. Every renderer — windows AND embedded views — keeps `<html data-bs-theme>` in sync automatically; consumers drop plain `<button data-omega-theme-set="dark">` controls and @omega.js/desktop wires them.
+- **Cross-platform analytics identity.** GA4 Measurement Protocol with `client_id = uuidv5(deviceId, projectIdNamespace)` and `user_id = uuidv5(firebaseUid, projectIdNamespace)`. Same Firebase project ID in @omega.js/backend, UJM, @omega.js/client, and @omega.js/desktop produces identical `user_id` outputs everywhere → unified events for one human across desktop + web + backend, no manual stitching.
+- **"Hot config"** fetched from your brand site (`<brand.url>/data/resources/main.json`) and polled hourly — flip a force-update version, default user-agent, ad rotation, etc. without re-releasing. `manager.remoteConfig.get('versionRequired')`. Cached to storage so offline boots still have last-known values.
+- **File-based feature definitions** — trays, menus, and context-menus are JS files (full power, no DSL): `src/integrations/{tray,menu,context-menu}/index.js`. All three ship sensible **id-tagged defaults** (legacy-framework-style: about, preferences, check-for-updates, dev menu w/ inspector + log folders, etc.) and share the same **id-path mutation API**: `find`, `update`, `remove`, `enable`, `show`, `hide`, `insertBefore`, `insertAfter`, `appendTo`. Any default item is one line away from removal, customization, or repositioning.
+- **Lazy windows + Discord-style hide-on-close.** @omega.js/desktop doesn't auto-create any windows — your `main.js` calls `windows.create('main', { show: !startup.isLaunchHidden() })`. The `main` window's X button hides instead of quitting on every platform; real quit only via Cmd+Q / menu Quit / tray Quit / auto-update install. Inset titlebar by default (mac `hiddenInset` traffic lights / win native overlay buttons / linux native frame) with a draggable topbar in the page template.
+- **Zero-bounce hidden-launch on macOS.** `startup.mode = 'hidden'` bakes `LSUIElement: true` into Info.plist at build time → app launches completely invisible (no dock icon, no Cmd+Tab, no taskbar). Tray + notifications + networking still work. When the user double-clicks the running app's icon, @omega.js/desktop's `app.on('activate')` (macOS) / `app.on('second-instance')` (win/linux) handler surfaces the `main` window and the dock icon appears alongside it. CleanMyMac-style "tray-only at login, full window when manually opened" is the default.
+- **Auto-update background install.** When a download finishes from a background poll (not user-initiated), @omega.js/desktop auto-relaunches into the new version after 5s — apps update overnight without bothering the user. User-initiated checks skip this so your UI can prompt instead.
+- **Vert (ad) units with zero JS.** Drop `<div data-omega-vert></div>` into any view — the renderer auto-binds it (live, MutationObserver) to the shared OMEGA verts module: house/company inventory only (no AdSense in desktop surfaces), lazy near-viewport loading, sandboxed iframe, no-fill collapse. See [verts](docs/verts.md).
+- **esbuild-bundled** main / preload / renderer for source protection.
+- **Built-in test framework** — Jest-like syntax, four layers: `build` (plain Node), `main` (spawned Electron), `renderer` (hidden BrowserWindow), and `boot` (spawns the consumer's actual built `dist/main.bundle.js` for end-to-end smoke tests against the live manager — no `npm start && sleep && kill` shell hacks). Boot layer always rebuilds the bundle first so tests never see stale code.
+- **Schema-validated config.** One `config/omega.json5` (the OMEGA-wide format: shared brand/analytics/payment/firebase sections + desktop settings under `targets.desktop`), validated against the canonical schema in the bundled `@omega.js/config`. Validation runs at app boot AND during `gulp audit` — a misconfigured app never reaches the "white window of confusion" stage; it tells you exactly which field is broken with a numbered list. Simple flag model — `required: true | false | (config) => bool` — and `match` / `enum` / `type` only fire on field presence so consumers never see a flood of redundant errors for the same field. Pure-JS validator, no Ajv/Joi/Zod dep. See [config-schema](docs/config-schema.md).
+- **Multi-platform build/release** via GitHub Actions — macOS sign + notarize, Linux (deb + AppImage + optional Snap), Windows EV-token signing (self-hosted runner now, cloud-signing pluggable). Sensible installer defaults out of the box: NSIS one-click install on Windows (desktop + start menu shortcut, launch on finish), universal mac binary (one .dmg for Intel + Apple Silicon), `app.category` automatically mapped to per-platform values, copyright `{YEAR}` token always current. Snap Store publishing is on by default in the scaffold and auto-skipped at build time when `SNAPCRAFT_STORE_CREDENTIALS` isn't set — drop the credential blob into `.env`, run `mgr push-secrets`, and the next release ships to the Snap Store. See [installer-options](docs/installer-options.md).
+
+## Quick start (consumer)
+
+@omega.js/desktop auto-syncs your system Node version to match whatever Node Electron's bundled runtime ships with. The postinstall `sync-nvmrc` step queries the official Electron releases feed using your installed Electron version, then writes the corresponding Node major to `.nvmrc`; every verb seeds a missing `.nvmrc` the same way. Run `nvm use` afterward to switch your shell.
+
+```bash
+npm install @omega.js/desktop --save-dev
+nvm use                  # switch to the Node version Electron uses (one-time per shell)
+npm start                # dev: gulp → esbuild → electron .
+OMEGA_CDP_PORT=9222 npm start  # dev + expose Chrome DevTools Protocol for Claude/MCP debugging
+npx omega cdp status       # drive the running dev app over CDP: status|eval|shot|capture|theme|relaunch|quit (docs/cdp-debugging.md)
+npm run build            # local production build (bundles only, no installer)
+npm run package:quick    # fast packaged build for host platform/arch (.app/.exe-folder/linux-unpacked, ~20-30s) — for smoke-testing packaged behavior
+npm run package          # full local production package (DMG/zip/universal-mac, NSIS-win, deb+AppImage-linux)
+npm run release          # signed + published release via GitHub Actions
+npx omega test             # YOUR project tests only (C5 scoping — docs/shared/testing.md)
+npx omega test framework:  # the framework's own suite (aliases: omega:, mgr:, desktop:, em:; add a path to narrow)
+npx omega test full:       # both sources
+npx omega test --extended  # opt into tests that hit real external services (or TEST_EXTENDED_MODE=true)
+```
+
+## Icons
+
+Convention-only. Drop PNGs at:
+
+```
+config/icons/
+  global/             ← used by any platform with no platform-specific override
+    icon.png
+    tray.png
+  macos/              ← macOS overrides (beats global)
+    icon.png
+    tray.png          ← 32×32 — @omega.js/desktop renames to trayTemplate.png in dist for OS dark-mode magic
+    dmg.png           ← 1080×760 DMG background
+  windows/            ← Windows overrides
+    icon.png
+    tray.png
+  linux/              ← Linux overrides (otherwise falls back to global → windows)
+    icon.png
+    tray.png
+```
+
+Resolution per slot/platform (most specific wins): `<platform>/<slot>` → `global/<slot>` → (Linux only) `windows/<slot>` → @omega.js/desktop bundled default. Tray missing falls back to app icon.
+
+**Ship native (@2x) size only — @omega.js/desktop downscales the @1x sibling automatically.** macOS tray must be 32×32; macOS DMG must be 1080×760. @omega.js/desktop emits both `<slot>.png` and `<slot>@2x.png` into `dist/config/icons/<platform>/`. No `app.icons` config block — files are the source of truth.
+
+## Logs
+
+Five logs in `<projectRoot>/logs/`, each with its own purpose:
+
+| File | What | Lifetime |
+|---|---|---|
+| `runtime.log` | Your packaged app's runtime — main + preload + renderer all converge here via electron-log | Persistent, rotates at 10 MB |
+| `dev.log` | Gulp pipeline output — sass, bundle, html, electron child stdout from `npm start` | Truncated each `npm start` |
+| `build.log` | Gulp pipeline output for production builds/packages (`npm run build` / `package` / `publish`, i.e. `OMEGA_BUILD_MODE=true`) | Truncated each build |
+| `test.log` | `npx omega test` runner output (suite names, pass/fail, harness boot lines) | Truncated each test run |
+| `ci.log` | `npm run release` — streamed GH Actions output during a CI release | Truncated each release |
+
+```bash
+npx omega logs                  # tail last 50 of runtime.log
+npx omega logs --tail           # follow runtime.log live
+npx omega logs dev --tail       # follow dev.log (runtime|dev|build|test)
+grep -i error logs/runtime.log
+```
+
+In production, `runtime.log` lives at `app.getPath('logs')`:
+- macOS: `~/Library/Logs/<AppName>/runtime.log`
+- Windows: `%APPDATA%\<AppName>\logs\runtime.log`
+- Linux: `~/.config/<AppName>/logs/runtime.log`
+
+See [docs/logging.md](docs/logging.md) for the full picture (renderer forwarding, log levels, programmatic path access).
+
+Override gulp's `dev.log` path via `OMEGA_LOG_FILE=<path>`; disable entirely via `OMEGA_LOG_FILE=false`. The default `.gitignore` includes `logs/`.
+
+## Design tokens (C4)
+
+The cross-target `--omega-*` token contract (defined once in
+`@omega.js/web`'s `core/css/tokens/_index.scss`) is vendored into
+`dist/assets/css/tokens/` at prepare (package.json `omega.vendorAssets`)
+and emitted by the `omega-desktop` entry BEFORE the theme — theme rules
+override at equal specificity, and consumer scss can read
+`var(--omega-*)` directly. First consumer: `body { accent-color:
+var(--omega-accent) }`. The full component migration onto tokens lands
+with the C3/D10 skin.
+
+## Per-process imports
+
+```js
+// src/main.js
+new (require('@omega.js/desktop/main'))().initialize();
+
+// src/preload.js
+new (require('@omega.js/desktop/preload'))().initialize();
+
+// src/assets/js/components/<view>/index.js
+new (require('@omega.js/desktop/renderer'))().initialize();
+```
+
+## Documentation
+
+Each subsystem has its own API reference under [`docs/`](docs/):
+
+- [storage](docs/storage.md) — KV store, sync in main, async (via IPC) in renderer, dot-notation paths, change broadcasts
+- [ipc](docs/ipc.md) — typed channel bus, `handle` / `invoke` / `broadcast`
+- [windows](docs/windows.md) — lazy named-window registry (no auto-create), bounds persistence, inset titlebar, hide-on-close
+- [tray](docs/tray.md) — file-based tray definition, dynamic items, runtime mutators
+- [menu](docs/menu.md) — file-based application menu, platform-aware default template
+- [context-menu](docs/context-menu.md) — file-based right-click menus, called per-event with `params`
+- [startup](docs/startup.md) — launch modes (`normal` / `hidden`), LSUIElement on macOS, login-item handling
+- [app-state](docs/app-state.md) — first-launch / launch-count / crash-sentinel flags
+- [deep-link](docs/deep-link.md) — cross-platform deep links, single-instance, pattern routing, built-in routes
+- [client-bridge](docs/client-bridge.md) — Firebase auth state synchronized across main + every renderer
+- [auto-updater](docs/auto-updater.md) — startup + periodic checks, 30-day max-age gate, dev simulation
+- [analytics](docs/analytics.md) — GA4 Measurement Protocol with cross-platform `uuidv5` identity (same human → same `user_id` across desktop/web/backend)
+- [context](docs/context.md) — runtime info block (geolocation, client, session, app) — @omega.js/backend-shaped
+- [usage](docs/usage.md) — opens / hoursTotal / hoursThisSession; clean-exit accumulation
+- [remote-config](docs/remote-config.md) — "hot config" fetched from brand site for runtime flag flips without re-releases
+- [restart-manager](docs/restart-manager.md) — auxiliary helper app for relaunches; auto-installs via signed mac.zip / NSIS exe / browser-opened .deb
+- [config-schema](docs/config-schema.md) — canonical schema + validator for `config/omega.json5`. Hard-fails boot AND `gulp audit` on missing required fields, regex mismatches, enum violations, type mismatches. Single source of truth in the bundled `@omega.js/config`
+- [templating](docs/templating.md) — `{{ var }}` token replacement, page template, body-only views
+- [themes](docs/themes.md) — classy + bootstrap themes, `@use 'omega-desktop' as * with (...)` overrides, per-page CSS bundles, system-aware appearance (`manager.theme`)
+- [sentry](docs/sentry.md) — error/crash reporting, dev-mode gating, auto auth attribution, release tagging
+- [hooks](docs/hooks.md) — lifecycle hooks (build/pre, build/post, release/pre, release/post, notarize)
+- [installer-options](docs/installer-options.md) — installer/distribution config: NSIS one-click defaults, ia32 inclusion, app.category mapping, `{YEAR}` copyright token, snap publishing (default-on with cred-gated auto-skip), MAS roadmap
+- [signing](docs/signing.md) — macOS + Windows code signing reference, cert files, env vars
+- [releasing](docs/releasing.md) — end-to-end release walkthrough (`.env` → GitHub Release)
+- [runner](docs/runner.md) — Windows EV-token signing runner — `npx omega runner install`, auto-onboards new GH orgs, `npx omega runner monitor` for a live signing event tail
+- [test-framework](docs/test-framework.md) — writing tests, running them, layers
+- [test-boot-layer](docs/test-boot-layer.md) — boot test layer (spawns the consumer's actual built bundle for end-to-end smoke tests)
+- [build-system](docs/build-system.md) — gulp, esbuild, electron-builder pipeline
+
+## Status
+
+Active development on `v1`. See [`PROGRESS.md`](PROGRESS.md) for pass-by-pass progress.
+
+## License
+
+[Elastic License 2.0](LICENSE). The source is free to use and modify; a license key unlocks payments in production deploys and removes the attribution (local dev and test payments are always free); and you may not offer `@omega.js/desktop` to third parties as a hosted or managed service.

package/bin/omega

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/omega-bin.js');

package/bin/omega-desktop

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/cli-run.js').run();

package/bin/omg

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/omega-bin.js');

package/dist/assets/css/core/_fontawesome.scss

@@ -0,0 +1,146 @@
+// Core Font Awesome Customizations
+// Extended icon sizing and display utilities
+//
+// This sheet is the ONE home of icon presentation across every target (#183).
+// It is deliberately self-contained (plain css, its own $fa-sizes map, its own
+// keyframes) so @omega.js/desktop and @omega.js/extension can vendor it
+// verbatim at prepare through their package.json `omega.vendorAssets`, the same
+// channel the tokens and shell sheets ride. Anything web-only stays out.
+
+// ============================================
+// Size Scale Configuration
+// ============================================
+
+$fa-sizes: (
+  '2xs': 0.625rem,
+  'xs': 0.75rem,
+  'sm': 0.875rem,
+  'base': 1rem,
+  'md': 1rem,
+  'lg': 1.125rem,
+  'xl': 1.25rem,
+  '2xl': 1.5rem,
+  '3xl': 1.8125rem,
+  '4xl': 2.1875rem,
+  '5xl': 2.625rem,
+  '6xl': 4rem
+);
+
+// ============================================
+// Base Icon Styles
+// ============================================
+
+// A rendered icon is a SQUARE, glyph-centered box (#180). The hook is the
+// stamp the renderers leave on the <i> they fill — data-omega-fa, written by
+// the build-time inlining pass and by @omega.js/client's runtime watcher
+// alike (#619) — never a class an author has to remember; `.fa` stays for
+// hand-authored wrappers around a glyph (the account page's provider logos
+// are `div.fa fa-3xl`). Without the box the 1em svg sits on the text baseline
+// and any transform orbits a point below the glyph (the spin wobble).
+// Both branches qualify with `i` so the box outranks the vertical-align in
+// the size classes below.
+i.fa,
+i[data-omega-fa] {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 1em;
+  height: 1em;
+  vertical-align: -0.125em; // Font Awesome's own baseline offset
+  flex-shrink: 0;
+
+  svg, img {
+    width: 1em;
+    height: 1em;
+  }
+}
+
+// The child sizing itself stays UNQUALIFIED, exactly as it was before the box
+// arrived: non-`i` markup wears `.fa` as a plain wrapper (the account page's
+// provider logos are `div.fa fa-3xl`) and still owes its glyph 1em. The offset
+// rides along for that case only — inside the flex box above a flex item
+// ignores vertical-align.
+.fa svg,
+.fa img,
+[data-omega-fa] svg,
+[data-omega-fa] img {
+  width: 1em;
+  height: 1em;
+  vertical-align: -0.125em;
+}
+
+// ============================================
+// Size Classes
+// ============================================
+
+@each $name, $size in $fa-sizes {
+  .fa-#{$name} {
+    font-size: $size;
+    line-height: 1;
+    vertical-align: baseline;
+  }
+}
+
+// ============================================
+// Animation
+// ============================================
+
+// Font Awesome's own utility name and its own keyframes name, so the muscle
+// memory (and the icon-core modifier list, which already skips `fa-spin`)
+// carries over. The square box above is what makes the turn centered.
+@keyframes fa-spin {
+  from {
+    transform: rotate(0deg);
+  }
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+.fa-spin {
+  animation: fa-spin 1s linear infinite;
+  transform-origin: center;
+}
+
+// fa-bounce and fa-beat are in core markup already (core/_includes/core/body.html
+// alerts), so they get the same deal as fa-spin: Font Awesome's utility name,
+// our own minimal keyframes under that same name. FA's own keyframes are built
+// on a stack of custom-property knobs we do not ship, and copying them would
+// drag that config surface in for two alert icons.
+@keyframes fa-bounce {
+  0%,
+  50%,
+  100% {
+    transform: translateY(0);
+  }
+  25% {
+    transform: translateY(-0.25em);
+  }
+}
+
+.fa-bounce {
+  animation: fa-bounce 1s ease-in-out infinite;
+}
+
+@keyframes fa-beat {
+  0%,
+  100% {
+    transform: scale(1);
+  }
+  50% {
+    transform: scale(1.25);
+  }
+}
+
+.fa-beat {
+  animation: fa-beat 1s ease-in-out infinite;
+  transform-origin: center;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .fa-spin,
+  .fa-bounce,
+  .fa-beat {
+    animation: none;
+  }
+}

package/dist/assets/css/core/_initialize.scss

@@ -0,0 +1,38 @@
+// @omega.js/desktop core init — desktop-targeted defaults that complement the active theme.
+// Web-specific bits (cookieconsent, exit-popup, social-sharing, lazy-loading, service-worker)
+// are intentionally not ported from UJM — they don't apply to a packaged Electron app.
+
+// Make sure the html / body fill the window with no scrollbars from layout glitches.
+html, body {
+  height: 100%;
+  margin: 0;
+  background: var(--bs-body-bg);
+  color: var(--bs-body-color);
+}
+
+// Prevent text selection in chrome / app frame; let consumers opt in for content areas.
+body {
+  user-select: none;
+  -webkit-user-select: none;
+}
+
+// Re-enable selection inside common content containers + form controls.
+main,
+.omega-selectable,
+input,
+textarea,
+[contenteditable="true"] {
+  user-select: text;
+  -webkit-user-select: text;
+}
+
+// macOS draggable title-bar surface — opt in by adding `.omega-drag` (e.g. on a header bar).
+.omega-drag {
+  -webkit-app-region: drag;
+}
+.omega-no-drag,
+.omega-drag button,
+.omega-drag input,
+.omega-drag a {
+  -webkit-app-region: no-drag;
+}

package/dist/assets/css/omega-desktop.scss

@@ -0,0 +1,39 @@
+// ============================================
+// OMEGA Desktop — Main SCSS Entry
+// ============================================
+// Consumer projects import via: `@use 'omega-desktop' as * with ($primary: #2563EB);`
+//
+// gulp/sass adds <omega-package-root>/dist/assets/css and <omega-package-root>/dist/assets/themes/<theme>
+// to the sass loadPaths so the bare 'omega-desktop' import resolves to this file.
+
+// App shell mechanics (#111) — the .omega-shell grid, region geometry and the
+// collapse/drawer states, vendored from @omega.js/web alongside the theme's
+// shell SKIN. Loaded BEFORE the theme (Sass emits a module's CSS at its first
+// load, @forward included) so the skin layers OVER the mechanics, exactly as
+// web's core/css/main.scss orders them.
+@use 'shell/index' as omega-shell;
+
+// Forward the active theme so consumers can override theme variables via @use ... with ()
+@forward 'theme';
+
+// Core design tokens (C4) — the cross-target `--omega-*` contract, vendored
+// from @omega.js/web at prepare (package.json `omega.vendorAssets`). Emitted
+// BEFORE the theme so theme rules can override at equal specificity.
+@use 'tokens/index' as omega-tokens;
+
+@use 'theme' as *;
+
+// desktop-specific core styles (desktop-targeted)
+@use 'core/_initialize' as *;
+
+// Icon presentation (#183): the square glyph-centered box, the size scale and
+// the spin/bounce/beat utilities, vendored VERBATIM from @omega.js/web's one
+// icon sheet at prepare (package.json `omega.vendorAssets`), same channel as
+// the tokens and shell sheets above. Never hand-written here.
+@use 'core/_fontawesome' as *;
+
+// First cross-target token consumer: native controls pick up the brand accent.
+// The full component migration onto tokens lands with the D10 skin (C4 cp109).
+body {
+  accent-color: var(--omega-accent);
+}