@omega.js/desktop 0.1.0

package/dist/renderer.js

@@ -0,0 +1,456 @@
+// Renderer-process Manager singleton.
+// Consumer entry (per view): `new (require('@omega.js/desktop/renderer'))().initialize()`.
+// Reads window.OMEGA_BUILD_JSON.config (injected by the bundle task's esbuild `define`), bootstraps @omega.js/client + auth.
+//
+// Auth bridge:
+//   - On init, asks main "I'm at UID X (or null), are we in sync?" via desktop:auth:sync-request.
+//     If main returns a custom token, this renderer calls omega.auth().signInWithCustomToken(token).
+//     If main says "sign out," this renderer signs out.
+//   - Listens for desktop:auth:sign-in-with-token broadcasts (fired when ANY renderer or main signs in)
+//     and signs in with the provided token.
+//   - Listens for desktop:auth:sign-out broadcasts and signs out.
+//
+// Pattern mirrors BXM: main is the source of truth, renderers reflect.
+
+const LoggerLite = require('./lib/logger-lite.js');
+
+function Manager() {
+  const self = this;
+
+  self.config = null;
+  self.logger = new LoggerLite('renderer');
+  self.omega = null;
+
+  // Bridges exposed by preload contextBridge (window.desktop.*)
+  self.ipc     = (typeof window !== 'undefined' && window.desktop?.ipc)     || null;
+  self.storage = (typeof window !== 'undefined' && window.desktop?.storage) || null;
+
+  return self;
+}
+
+Manager.prototype.initialize = async function (overrides) {
+  const self = this;
+
+  // Merge runtime overrides on top of build-time config.
+  // OMEGA_BUILD_JSON is injected by the bundle task's esbuild `define`; its `banner`
+  // also makes it available on globalThis.OMEGA_BUILD_JSON for DevTools introspection.
+  const buildJson = (typeof OMEGA_BUILD_JSON !== 'undefined' && OMEGA_BUILD_JSON) || {};
+  self.config = Object.assign({}, buildJson.config || {}, overrides || {});
+
+  self.logger.log('Initializing @omega.js/desktop (renderer)...');
+
+  // Boot @omega.js/client so Firebase Auth is available in this renderer.
+  //
+  // `analyticsBridge` is the preload's analytics surface, handed over as config:
+  // a renderer NEVER sends analytics itself — the client forwards every event
+  // through this bridge to main, whose sender owns the one device id
+  // (electron-store, MAC-seeded), the one session id minted per launch, and the
+  // real engagement time ([#411](https://github.com/Omega-JS-Stack/omega/issues/411)).
+  // The client reads this key alone, so nothing but THIS line can bridge it.
+  //
+  // 🚫 The GA Measurement Protocol secret must NEVER be injected into this
+  // config. A second sender in a renderer would split one install into two GA
+  // clients (the #396 class) — which is why desktop's config carries the
+  // measurement id alone, and why the client drops any secret handed to a
+  // bridged renderer.
+  try {
+    const wmMod = require('@omega.js/client');
+    self.omega = wmMod.default || wmMod;
+    if (self.omega?.initialize) {
+      await self.omega.initialize(Object.assign({}, self.config, {
+        analyticsBridge: (typeof window !== 'undefined' && window.desktop?.analytics) || null,
+      }));
+    }
+  } catch (e) {
+    self.logger.warn('@omega.js/client not available — auth bridge running in no-op mode.', e?.message);
+  }
+
+  // Wire the auth bridge: sync with main, listen for broadcasts.
+  await self._wireAuthBridge();
+
+  // Wire declarative theme controls ([data-omega-theme-set]).
+  self._wireThemeControls();
+
+  // Auto-render FontAwesome icons (<i class="fa-solid fa-*">) and Bootstrap
+  // tooltips ([data-bs-toggle="tooltip"]) — presence-driven, live via
+  // MutationObserver, zero consumer setup.
+  self._wireFontAwesome();
+  self._wireTooltips();
+
+  // Auto-bind [data-omega-vert] elements to the shared client verts module
+  // (house/company lane only — no AdSense in desktop surfaces).
+  self._wireAds();
+
+  self.logger.log('@omega.js/desktop (renderer) initialized.');
+
+  return self;
+};
+
+// Declarative theme switching — any element with `data-omega-theme-set="system|light|dark"`
+// becomes a theme control: clicking it calls main's theme setter (persisted, applied to
+// every renderer live). The `<html data-bs-theme>` attribute itself is maintained by the
+// preload's theme applier (src/preload.js) — consumers just drop plain buttons:
+//
+//   <button data-omega-theme-set="light">Day</button>
+//   <button data-omega-theme-set="dark">Dusk</button>
+//   <button data-omega-theme-set="system">Auto</button>
+//
+// Delegated on document so controls rendered after initialize still work.
+Manager.prototype._wireThemeControls = function () {
+  const self = this;
+
+  if (typeof document === 'undefined' || !window.desktop?.theme) {
+    return;
+  }
+
+  document.addEventListener('click', (event) => {
+    const control = event.target.closest('[data-omega-theme-set]');
+    if (!control) {
+      return;
+    }
+    const source = control.getAttribute('data-omega-theme-set');
+    window.desktop.theme.set(source).catch((e) => {
+      self.logger.warn(`theme set '${source}' failed:`, e?.message);
+    });
+  });
+};
+
+// FontAwesome auto-render — any `<i>` element carrying `fa-*` classes gets the
+// Font Awesome SVG injected inline, whether present at init, inserted later,
+// or re-classed via JS at any time (`el.className = 'fa-solid fa-stop'`
+// re-renders in place). The whole DOM mechanism — class parsing (FA's
+// family × weight model), MutationObserver, caching, re-render/clear — is
+// @omega.js/client's shared icon-renderer (C4 cp112), the SAME module web
+// pages run; desktop only supplies the transport (IPC to main's icon
+// server). Unknown names leave the element empty (marked data-omega-fa) —
+// consumers that want a fallback check `window.desktop.fontawesome.get()`.
+//
+//   <i class="fa-solid fa-rocket me-2"></i>   →   <i …><svg …>…</svg></i>
+Manager.prototype._wireFontAwesome = function () {
+  const self = this;
+
+  if (typeof document === 'undefined' || !self.ipc) {
+    return;
+  }
+
+  const { createIconRenderer } = require('@omega.js/client/modules/icon-renderer.js');
+  createIconRenderer({
+    resolve: (name, style) => self.ipc.invoke('desktop:fontawesome:get', { name, style })
+      .then((r) => r?.svg ?? null),
+  }).start(document);
+};
+
+// Public alias — minimal surfaces that skip the full initialize() (no
+// @omega.js/client / auth bridge) can still enable the FontAwesome auto-render:
+//   new (require('@omega.js/desktop/renderer'))().enableFontAwesome();
+Manager.prototype.enableFontAwesome = Manager.prototype._wireFontAwesome;
+
+// Bootstrap tooltips — auto-initialize every `[data-bs-toggle="tooltip"]`
+// element (Bootstrap's JS + Popper ship inside @omega.js/desktop as a prebuilt bundle —
+// assets/js/bootstrap.bundle.js; consumers add ZERO setup).
+// Live-managed via MutationObserver:
+//   - elements inserted later get their tooltip on arrival
+//   - `data-bs-title` / `title` changes update the live instance (emptying it
+//     disposes — no tooltip is a valid state)
+//   - removed elements have their instance disposed (no orphaned tips)
+// The full Bootstrap namespace is exposed at `window.bootstrap` (and
+// `manager.bootstrap`) for manual control — Tooltip, Collapse, Dropdown, etc.
+// Only tooltips are auto-initialized (Bootstrap 5 makes them opt-in); the other
+// components' standard data-api works out of the box on Bootstrap markup.
+//
+// Gotcha (Bootstrap's own): disabled elements don't fire hover events — wrap a
+// disabled control in a <span data-bs-toggle="tooltip"> to tooltip it.
+Manager.prototype._wireTooltips = function () {
+  const self = this;
+
+  if (typeof document === 'undefined') {
+    return;
+  }
+
+  // Everything — including the require — is deferred until the document
+  // exists: the Bootstrap bundle reads document.documentElement at import
+  // time, which is null when this runs from a preload (the @omega.js/desktop test harness
+  // does) before the DOM is built.
+  const start = () => {
+    let Tooltip;
+    try {
+      // Prebuilt UMD (Popper inlined) — loads through the bundle task AND plain require().
+      const bootstrap = require('./assets/js/bootstrap.bundle.js');
+      Tooltip = bootstrap.Tooltip;
+      window.bootstrap = Object.assign(window.bootstrap || {}, bootstrap);
+    } catch (e) {
+      self.logger.warn('bootstrap Tooltip unavailable — tooltips disabled.', e?.message);
+      return;
+    }
+
+    self.bootstrap = window.bootstrap;
+
+    const SELECTOR = '[data-bs-toggle="tooltip"]';
+
+    const init = (el) => {
+      Tooltip.getOrCreateInstance(el);
+    };
+
+    const scan = (root) => {
+      if (root.matches?.(SELECTOR)) {
+        init(root);
+      }
+      root.querySelectorAll?.(SELECTOR).forEach(init);
+    };
+
+    const dispose = (root) => {
+      if (root.nodeType !== 1) {
+        return;
+      }
+      const candidates = [root, ...(root.querySelectorAll?.(SELECTOR) || [])];
+      for (const el of candidates) {
+        Tooltip.getInstance(el)?.dispose();
+      }
+    };
+
+    new MutationObserver((mutations) => {
+      for (const mutation of mutations) {
+        if (mutation.type === 'childList') {
+          mutation.addedNodes.forEach((node) => {
+            if (node.nodeType === 1) {
+              scan(node);
+            }
+          });
+          mutation.removedNodes.forEach(dispose);
+          continue;
+        }
+
+        // Attribute change on a (potential) tooltip host.
+        const el = mutation.target;
+        const instance = Tooltip.getInstance(el);
+        if (!el.matches(SELECTOR)) {
+          instance?.dispose();
+          continue;
+        }
+        if (!instance) {
+          init(el);
+          continue;
+        }
+        if (mutation.attributeName !== 'data-bs-toggle') {
+          // data-bs-original-title is Bootstrap's OWN bookkeeping: the
+          // Tooltip constructor MOVES a plain `title` attribute there.
+          // Without reading it, a title-only host infinite-loops the
+          // renderer: init removes `title` → this handler sees no title →
+          // dispose → dispose RESTORES `title` → re-init → … — a pure
+          // MutationObserver microtask storm that starves the main thread
+          // (found by Somiibo's session-limits boot suite: the settings
+          // page froze solid on one badge).
+          const title = el.getAttribute('data-bs-title') || el.getAttribute('title') || el.getAttribute('data-bs-original-title');
+          if (title) {
+            instance.setContent({ '.tooltip-inner': title });
+          } else {
+            instance.dispose();
+          }
+        }
+      }
+    }).observe(document.documentElement, {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      attributeFilter: ['data-bs-toggle', 'data-bs-title', 'title'],
+    });
+
+    scan(document.documentElement);
+  };
+
+  if (document.documentElement && document.readyState !== 'loading') {
+    start();
+  } else {
+    document.addEventListener('DOMContentLoaded', start, { once: true });
+  }
+};
+
+// Vert auto-bind (ads-system phase 4) — every `[data-omega-vert]` element,
+// present at init or inserted later (MutationObserver, same liveness as the
+// FontAwesome/tooltip wiring), is handed to @omega.js/client's verts module,
+// which owns the WHOLE lifecycle: lazy arming near the viewport, sandboxed
+// iframe to the resolved in-house source's /omega/verts/serve, origin-validated
+// postMessage, host-owned rotation + staleness recovery, no-fill collapse.
+// The type is PINNED to 'house': desktop surfaces never run the AdSense
+// provider lane (policy: no web context), so even a shared omega.json5 that
+// carries `advertising.providers.adsense` can only ever take the
+// house/company inventory here. mount() merges passed options OVER the
+// element attributes, so the pin is absolute; bound hosts are marked
+// `data-omega-vert-bound="house"` for observability.
+//
+//   <div data-omega-vert data-omega-vert-size="banner"></div>
+Manager.prototype._wireAds = function () {
+  const self = this;
+
+  if (self._adsWired || typeof document === 'undefined' || typeof MutationObserver === 'undefined' || !self.omega?.verts) {
+    return;
+  }
+  self._adsWired = true;
+
+  const SELECTOR = '[data-omega-vert]';
+
+  const mount = (el) => {
+    self.omega.verts().mount(el, { type: 'house' });
+    el.setAttribute('data-omega-vert-bound', 'house');
+  };
+
+  const scan = (root) => {
+    if (root.matches?.(SELECTOR)) {
+      mount(root);
+    }
+    root.querySelectorAll?.(SELECTOR).forEach(mount);
+  };
+
+  const start = () => {
+    new MutationObserver((mutations) => {
+      for (const mutation of mutations) {
+        mutation.addedNodes.forEach((node) => {
+          if (node.nodeType === 1) {
+            scan(node);
+          }
+        });
+      }
+    }).observe(document.documentElement, { childList: true, subtree: true });
+
+    scan(document.documentElement);
+  };
+
+  if (document.documentElement && document.readyState !== 'loading') {
+    start();
+  } else {
+    document.addEventListener('DOMContentLoaded', start, { once: true });
+  }
+};
+
+// Bridge between renderer's @omega.js/client and main's client-bridge.
+// Mirrors BXM's foreground sync logic.
+Manager.prototype._wireAuthBridge = async function () {
+  const self = this;
+  if (!self.ipc) return;
+
+  // Warm the backend before any of the waits below. This bridge ends in a
+  // sync-request, and main answers it by POSTing `/omega/user/token` — the
+  // app's first backend call, on a function that is cold every time the app
+  // launches. Fire-and-forget and unauthenticated: the backend answers a wakeup
+  // before it loads a route or authenticates
+  // ([#644](https://github.com/Omega-JS-Stack/omega/issues/644)).
+  // The route is required where it is used, the way client-bridge requires the
+  // request layer it shares with this bridge.
+  try {
+    const { WAKEUP_ROUTE } = require('@omega.js/client/modules/request.js');
+    self.omega?.request?.(WAKEUP_ROUTE, { wakeup: true });
+  } catch (e) {
+    self.logger.warn('wakeup ping failed (non-fatal):', e?.message);
+  }
+
+  const auth = self.omega?.auth?.();
+  const getCurrentUid = () => {
+    try { return auth ? (auth.getUser()?.uid || null) : null; }
+    catch (e) { return null; }
+  };
+
+  // Listen for sign-in-with-token broadcasts (main signed in via deep link, or another renderer signed in).
+  self.ipc.on('desktop:auth:sign-in-with-token', async ({ token }) => {
+    if (!token || !auth?.signInWithCustomToken) return;
+    try {
+      await auth.signInWithCustomToken(token);
+      self.logger.log('signed in via broadcast token.');
+    } catch (e) {
+      self.logger.error('signInWithCustomToken (broadcast) failed:', e?.message);
+    }
+  });
+
+  // Listen for sign-out broadcasts.
+  self.ipc.on('desktop:auth:sign-out', async () => {
+    if (!auth?.signOut) return;
+    try {
+      await auth.signOut();
+      self.logger.log('signed out via broadcast.');
+    } catch (e) {
+      self.logger.error('signOut (broadcast) failed:', e?.message);
+    }
+  });
+
+  // Run @omega.js/client's FULL auth cycle (UJM/BXM parity): listen() waits for auth to
+  // settle, fetches the Firestore account, resolves the subscription, and auto-populates
+  // the data-omega-bind bindings — so any @omega.js/desktop app can write UJM-style reactive HTML
+  // (`@show auth.user`, `@text auth.account.plan.id`, ...). Persistent listener: fires
+  // again on every subsequent sign-in/out (broadcast tokens included).
+  //
+  // Each settle pushes the resolution to main (desktop:auth:account-resolved) — main can't
+  // run Firestore, so this is how main-side plan gates learn the REAL plan (BXM's
+  // "browser contexts resolve, the authority caches" split). Main uid-guards the push.
+  if (auth?.listen) {
+    let lastState = null;
+
+    const pushResolved = async (state) => {
+      const uid = state?.user?.uid || null;
+      if (!uid) return;
+      try {
+        await self.ipc.invoke('desktop:auth:account-resolved', {
+          uid,
+          resolved: state?.resolved || null,
+          roles:    state?.account?.roles || null,
+        });
+      } catch (e) {
+        self.logger.warn('account-resolved push failed (non-fatal):', e?.message);
+      }
+    };
+
+    try {
+      auth.listen({}, (state) => {
+        lastState = state;
+        pushResolved(state);
+      });
+    } catch (e) {
+      self.logger.warn('auth listen failed (non-fatal):', e?.message);
+    }
+
+    // Re-push when MAIN's auth state changes: a renderer that resolved BEFORE main
+    // signed in had its push uid-rejected (correctly — main was signed out). When
+    // main comes up on the same user, offer the resolution again.
+    self.ipc.on('desktop:auth:state-changed', (snap) => {
+      if (snap?.uid && lastState?.user?.uid === snap.uid) {
+        pushResolved(lastState);
+      }
+    });
+  }
+
+  // Sync with main on load. If main has a different state, it'll send back instructions.
+  try {
+    const result = await self.ipc.invoke('desktop:auth:sync-request', {
+      contextUid: getCurrentUid(),
+    });
+
+    if (!result?.needsSync) return;
+
+    if (result.signOut && auth?.signOut) {
+      await auth.signOut();
+      self.logger.log('synced: signed out (main was signed out).');
+    } else if (result.customToken && auth?.signInWithCustomToken) {
+      await auth.signInWithCustomToken(result.customToken);
+      self.logger.log(`synced: signed in as ${result.user?.email || result.user?.uid}.`);
+    }
+  } catch (e) {
+    self.logger.warn('auth sync failed (non-fatal):', e?.message);
+  }
+};
+
+// Sign-out helper for renderer code (UI button etc.). Goes through main so all
+// renderers + main stay in sync via the broadcast.
+Manager.prototype.signOut = async function () {
+  if (!this.ipc) return { success: false, error: 'no-ipc' };
+  return this.ipc.invoke('desktop:auth:sign-out');
+};
+
+// Read main's current user (sync answer from main, not the renderer's local Firebase).
+Manager.prototype.getMainUser = async function () {
+  if (!this.ipc) return null;
+  return this.ipc.invoke('desktop:auth:get-user');
+};
+
+// Mix in shared cross-context helpers — same code path used in main, preload, build.
+require('./utils/mode-helpers.js').attachTo(Manager);
+require('./utils/url-helpers.js').attachTo(Manager);
+
+module.exports = Manager;

package/dist/test/assert.js

@@ -0,0 +1,4 @@
+// Shared devkit module — vendored into dist/vendor/devkit at prepare time by the
+// preparePackage `after` hook. This shim keeps the framework's internal require
+// paths stable while the implementation lives in @omega.js/devkit.
+module.exports = require('../vendor/devkit/test/assert.js');

package/dist/test/fixtures/consumer-app/config/omega.json5

@@ -0,0 +1,39 @@
+{
+  // Minimal @omega.js/desktop consumer config used ONLY by @omega.js/desktop's own boot-layer self-test. The fixture
+  // is esbuild-built (dist/main.bundle.js) and booted by src/test/runners/boot.js when
+  // OMEGA_TEST_BOOT_PROJECT points here — auto-set when @omega.js/desktop tests itself (src/commands/test.js).
+  // Not a real app; never published.
+  brand: {
+    id: 'desktop-fixture',
+    name: 'Desktop Fixture Consumer',
+    images: {
+      // Empty → build-config falls back to @omega.js/desktop's bundled default icon (no icon file shipped).
+      icon: '',
+    },
+  },
+  monitoring: {
+    providers: {
+      sentry: {
+        dsn: '',
+      },
+    },
+  },
+  analytics: {
+    providers: {
+      google: { id: '' },
+    },
+  },
+  // Empty config → client-bridge skips Firebase init (no hang on a fake projectId).
+  cloud: { provider: 'firebase', config: {} },
+  targets: {
+    desktop: {
+      startup: {
+        mode: 'normal',
+      },
+      // Skip release/repo discovery during the fixture's production build (no GitHub repo behind it).
+      releases: {
+        enabled: false,
+      },
+    },
+  },
+}

package/dist/test/fixtures/consumer-app/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "desktop-fixture-consumer",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Minimal @omega.js/desktop consumer app — boot-layer self-test fixture (built + booted by src/test/runners/boot.js). The devDependencies mirror a CONVERGED consumer (the framework plus every peer it declares) so ensureTarget installs nothing and its locality check passes: see src/test/suites/build/boot-fixture.test.js.",
+  "main": "dist/main.bundle.js",
+  "devDependencies": {
+    "@omega.js/desktop": "^0.1.0",
+    "electron": ">=42",
+    "electron-builder": ">=26",
+    "gulp": "^5.0.1"
+  }
+}

package/dist/test/fixtures/consumer-app/src/assets/js/components/main/index.js

@@ -0,0 +1,11 @@
+// Minimal main-window renderer entry for the boot-layer self-test fixture.
+const Manager = require('@omega.js/desktop/renderer');
+
+new Manager().initialize();
+
+// #111 — pins that the vendored core module resolves through the renderer's
+// `__main_assets__` alias AND runs: with no .omega-shell in this window the
+// call registers the shell API on omega._library and returns early, so a
+// module that throws on a vendored surface breaks this fixture's boot.
+window.__omegaAppShell = require('__main_assets__/js/core/app-shell.js').default;
+window.__omegaAppShell();

package/dist/test/fixtures/consumer-app/src/assets/scss/main.scss

@@ -0,0 +1,3 @@
+// Minimal theme entry for the boot-layer self-test fixture — pulls in the @omega.js/desktop/classy
+// theme so the sass build path is exercised exactly like a real consumer's.
+@use 'omega-desktop' as *;

package/dist/test/fixtures/consumer-app/src/main.js

@@ -0,0 +1,17 @@
+// Minimal main entry for @omega.js/desktop's boot-layer self-test fixture. Mirrors a real consumer:
+// one-line bootstrap, then create the main window once initialize() resolves. The boot
+// harness (src/test/harness/boot-entry.js) inspects the live manager after this runs.
+const Manager = require('@omega.js/desktop/main');
+
+const manager = new Manager();
+
+manager.initialize()
+  .then(() => {
+    const { windows, logger } = manager;
+
+    // Force show:false — the boot harness runs headless and only asserts the window
+    // EXISTS + loaded the built view, never that it's visible on screen.
+    windows.create('main', { show: false });
+
+    logger.log('@omega.js/desktop fixture consumer main initialized!');
+  });

package/dist/test/fixtures/consumer-app/src/preload.js

@@ -0,0 +1,4 @@
+// Minimal preload for the boot-layer self-test fixture. Exposes window.desktop to the renderer.
+const Manager = require('@omega.js/desktop/preload');
+
+new Manager().initialize();

package/dist/test/fixtures/consumer-app/src/views/main/index.html

@@ -0,0 +1,4 @@
+<div id="fixture-root" class="container py-5 text-center">
+  <h1 class="display-5 fw-bold mb-2">{{ app.productName }}</h1>
+  <p class="text-muted mb-0">@omega.js/desktop boot-layer self-test fixture.</p>
+</div>