@omega.js/desktop 0.52.0 → 0.53.0

package/dist/test/harness/renderer-preload.js

@@ -1,18 +1,18 @@
 // Renderer test-harness preload. Bridges between the harness BrowserWindow and the parent
-// main-process harness via two channels:
+// main-process harness via three channels:
 //
-//   __emTest:ready   — renderer signals it's ready to receive suites
-//   __emTest:result  — renderer emits per-test results / suite-start / fatal
-//   __emTest:suites  — main sends serialized renderer suites for execution
+//   __omegaTest:ready   : renderer signals it's ready to receive suites
+//   __omegaTest:result  : renderer emits per-test results / suite-start / fatal
+//   __omegaTest:suites  : main sends serialized renderer suites for execution
 //
 // Also exposes the production-style `window.desktop` surface (mirrors src/preload.js so renderer
-// test suites can assert on it).
+// test suites can assert on it), and builds the REAL renderer instance in this world.
 
 const { contextBridge, ipcRenderer } = require('electron');
 
 // Mirror the production preload's forwarding logger so renderer-layer tests can
 // verify that logger.log/warn/error actually emits 'desktop:log:forward' to main.
-// Kept minimal — same channel name as production (src/preload.js).
+// Kept minimal: same channel name as production (src/preload.js).
 function makeForwardingLogger() {
   const FORWARD_CHANNEL = 'desktop:log:forward';
   const methods = ['log', 'info', 'warn', 'error', 'debug'];
@@ -20,7 +20,7 @@ function makeForwardingLogger() {
   for (const m of methods) {
     const fileLevel = m === 'log' ? 'info' : m;
     out[m] = function () {
-      const args = ['[em]', ...Array.from(arguments)];
+      const args = ['[omega]', ...Array.from(arguments)];
       const fn = console[m] || console.log;
       try { fn.apply(console, args); } catch (_) { /* ignore */ }
       try {
@@ -38,74 +38,17 @@ function makeForwardingLogger() {
   return out;
 }
 
-contextBridge.exposeInMainWorld('__emTest', {
+contextBridge.exposeInMainWorld('__omegaTest', {
   // Signal main that the harness page is loaded and ready to accept suites.
-  ready: () => ipcRenderer.send('__emTest:ready'),
+  ready: () => { instanceBuilt.then(() => ipcRenderer.send('__omegaTest:ready')); },
   // Forward a result event up to main, which prints it.
-  emit:  (evt) => ipcRenderer.send('__emTest:result', evt),
+  emit:  (evt) => ipcRenderer.send('__omegaTest:result', evt),
   // Subscribe to incoming suite payloads.
   onSuites: (handler) => {
-    ipcRenderer.on('__emTest:suites', (_e, suites) => handler(suites));
+    ipcRenderer.on('__omegaTest:suites', (_e, suites) => handler(suites));
   },
 });
 
-// Expose a thin bridge to the actual renderer Manager so renderer-layer tests can
-// assert on its cross-context helpers (isDevelopment / isProduction / isTesting /
-// getVersion / getEnvironment / getApiUrl / getFunctionsUrl / getWebsiteUrl). We
-// instantiate the renderer Manager here in the preload (before contextIsolation
-// closes off `require`) and forward each helper as a sync contextBridge function.
-// We deliberately do NOT call `manager.initialize()` — that touches @omega.js/client /
-// firebase / IPC, which is heavy + flaky for a helper-shape assertion. Instead we
-// stub `manager.config` from a built-time-injected blob so config-dependent
-// helpers (getEnvironment fallback, getWebsiteUrl prod path) have something to read.
-let testManager;
-try {
-  // The renderer test harness loads the renderer Manager by absolute dist path
-  // injected by the boot harness. In its absence, fall back to require-by-name
-  // (works when the harness is run from a consumer with @omega.js/desktop in node_modules).
-  const RendererManager = process.env.OMEGA_TEST_RENDERER_MANAGER_PATH
-    ? require(process.env.OMEGA_TEST_RENDERER_MANAGER_PATH)
-    : require('@omega.js/desktop/renderer');
-  testManager = new RendererManager();
-  // Seed config the way a real BUILD bakes it, so the URL helpers have the same
-  // inputs here that they have in a shipped renderer. Tests can mutate this via
-  // __emTestManager.config.set().
-  //   `environment` is the build fact every OMEGA surface bakes
-  //   ([#817](https://github.com/Omega-JS-Stack/omega/issues/817)), which is
-  //   what a real renderer (no process.env) answers from.
-  //   `dev.ports` is the resolved local map, whose floor is @omega.js/config's
-  //   classic numbers ([#834](https://github.com/Omega-JS-Stack/omega/issues/834)):
-  //   nothing carries a browser-side copy of them any more, so an artifact
-  //   without the map cannot reach a localhost port at all.
-  testManager.config = {
-    environment: 'production',
-    dev:   { ports: { ...require('../../vendor/config/index.js').CLASSIC_PORTS } },
-    brand: { url: 'https://example.com' },
-    cloud: { provider: 'firebase', config: { projectId: 'demo-app', authDomain: 'demo-app.firebaseapp.com' } },
-  };
-} catch (e) {
-  console.warn('[renderer-preload] Could not instantiate renderer Manager for tests:', e.message);
-}
-
-// Wire the renderer Manager's DOM enhancements (FontAwesome auto-render +
-// Bootstrap tooltip auto-init) against THIS document. In production these run
-// in the page world (the consumer's esbuild bundle); here the preload world
-// stands in — the DOM is shared, so injected SVGs / tooltip tips are visible
-// to page-world test suites. The Manager reads `window.desktop.ipc` which only
-// exists in the page world, so hand it the preload's ipcRenderer directly.
-try {
-  if (testManager) {
-    testManager.ipc = {
-      invoke: (channel, payload) => ipcRenderer.invoke(channel, payload),
-    };
-    testManager._wireFontAwesome();
-    testManager._wireTooltips();
-  }
-} catch (e) {
-  console.warn('[renderer-preload] Could not wire DOM enhancements:', e.message);
-}
-
-
 // Mirror the production preload surface so renderer test suites can assert against it.
 const desktopSurface = {
   ipc: {
@@ -135,7 +78,7 @@ const desktopSurface = {
     },
   },
   // Mirror production preload's theme surface (get/set via IPC; onChange via
-  // matchMedia — the real mechanism, since themeSource flips prefers-color-scheme).
+  // matchMedia, the real mechanism, since themeSource flips prefers-color-scheme).
   theme: {
     get: ()       => ipcRenderer.invoke('desktop:theme:get'),
     set: (source) => ipcRenderer.invoke('desktop:theme:set', { source }),
@@ -189,65 +132,107 @@ const desktopSurface = {
 
 contextBridge.exposeInMainWorld('desktop', desktopSurface);
 
-// Defined ABOVE the client wiring below, which injects `desktopSurface.analytics`
-// as that client's analytics bridge ([#411](https://github.com/Omega-JS-Stack/omega/issues/411)):
-// the surface has to exist before the wiring reads it. Observed, not assumed —
-// with this block further down, the wiring resolved nothing.
+// The REAL renderer instance, built here in the preload world (before contextIsolation
+// closes off `require`): the same module a view's entry requires. Its constructor
+// reads `window.desktop`, which contextBridge exposes to the PAGE world only, so this
+// world gets the same surface first. Suites assert on it through the probes below.
+//
+// initialize() is deliberately NOT called: it boots Firebase and the auth bridge,
+// which is heavy + flaky for a helper-shape assertion. The config is seeded the way a
+// real BUILD bakes it instead:
+//   `environment` is the build fact every OMEGA surface bakes
+//   ([#817](https://github.com/Omega-JS-Stack/omega/issues/817)), which is
+//   what a real renderer (no process.env) answers from.
+//   `dev.ports` is the resolved local map, whose floor is @omega.js/config's
+//   classic numbers ([#834](https://github.com/Omega-JS-Stack/omega/issues/834)):
+//   nothing carries a browser-side copy of them any more, so an artifact
+//   without the map cannot reach a localhost port at all.
+//   `advertising` configures AdSense ON PURPOSE and no inhouse source: the
+//   house-lane pin is exactly what must keep the provider lane (remote script)
+//   from ever being attempted, and a source-less house render collapses
+//   deterministically with zero network.
+//   `analyticsBridge` is INJECTED exactly the way src/renderer.js injects it in
+//   production ([#411](https://github.com/Omega-JS-Stack/omega/issues/411)): the
+//   preload's own analytics surface, handed over as config.
+let testOmega;
+let buildError = null;
+
+// The ESM modules renderer.js requires. Electron's preload loader has no
+// require(esm) (a production renderer is esbuild-bundled, so it never needs one):
+// each is loaded through import() first and seated in require's cache, and
+// renderer.js's own require() then finds it there.
+const RENDERER_ESM = ['@omega.js/client', '@omega.js/client/modules/request.js', './assets/js/core/app-shell.js'];
+
+async function buildInstance() {
+  const Module = require('module');
+  const { pathToFileURL } = require('url');
 
-// Wire the verts auto-bind against THIS document. Production hands the client
-// singleton to _wireAds via manager.initialize(); here the preload requires
-// the REAL @omega.js/client (same resolution _wireFontAwesome uses) and seeds
-// its config directly — full initialize() is deliberately skipped (firebase,
-// heavy). AdSense is INTENTIONALLY configured and no inhouse source is: the
-// house-lane pin is exactly what must keep the provider lane (remote script)
-// from ever being attempted, and a source-less house render collapses
-// deterministically with zero network.
-(async () => {
-  try {
-    if (!testManager) return;
-    // The client is pure ESM — Electron's preload require() can't load it
-    // (unlike the CJS-compatible icon-renderer), so go through the Node ESM
-    // loader. Resolves well before suites arrive from main.
-    const wmMod = await import('@omega.js/client');
-    testManager.omega = wmMod.default || wmMod;
-    testManager.omega.config = Object.assign({}, testManager.omega.config, {
-      advertising: {
-        providers: { adsense: { client: 'ca-pub-test' } },
-      },
-      // The analytics bridge, INJECTED exactly the way src/renderer.js injects
-      // it in production ([#411](https://github.com/Omega-JS-Stack/omega/issues/411)):
-      // the preload's own analytics surface, handed over as config. The client
-      // reads this key and nothing else — no global is involved either side.
-      analyticsBridge: desktopSurface.analytics,
-    });
-    testManager._wireAds();
+  window.desktop = desktopSurface;
 
-    // Analytics, BRIDGED: the real client resolves the injected bridge and
-    // forwards every event over IPC to main's ONE sender. Same
-    // `analytics().init()` call `manager.initialize()` makes — the rest of
-    // initialize (firebase, auth) stays out, as everywhere else here.
-    //
-    // Credentials are handed in ON PURPOSE, the mistake desktop's build must
-    // never make: a bridged renderer has to DROP them (`analytics-bridge`
-    // renderer suite pins that it holds neither).
-    testManager.omega.analytics().init({
-      id:        'G-RENDERER1',
-      secret:    'harness-renderer-secret',
-      projectId: 'demo-app',
-      bridge:    testManager.omega._resolveAnalyticsBridge(),
-    });
-  } catch (e) {
-    console.warn('[renderer-preload] Could not wire verts auto-bind:', e.message);
+  // The main harness hands over the renderer's absolute dist path. In its absence,
+  // fall back to resolve-by-name (a consumer with @omega.js/desktop in node_modules).
+  const rendererPath = process.env.OMEGA_TEST_RENDERER_PATH || require.resolve('@omega.js/desktop/renderer');
+  const rendererRequire = Module.createRequire(rendererPath);
+
+  for (const specifier of RENDERER_ESM) {
+    const file = rendererRequire.resolve(specifier);
+    if (require.cache[file]) continue;
+    const seated = new Module(file);
+    seated.filename = file;
+    seated.exports = await import(pathToFileURL(file).href);
+    seated.loaded = true;
+    require.cache[file] = seated;
   }
-})();
+
+  testOmega = require(rendererPath);
+
+  testOmega.config = {
+    environment: 'production',
+    dev:   { ports: { ...require('../../vendor/config/index.js').CLASSIC_PORTS } },
+    brand: { url: 'https://example.com' },
+    cloud: { provider: 'firebase', config: { projectId: 'demo-app', authDomain: 'demo-app.firebaseapp.com' } },
+    advertising: {
+      providers: { adsense: { client: 'ca-pub-test' } },
+    },
+    analyticsBridge: desktopSurface.analytics,
+  };
+
+  // Wire the instance's DOM enhancements (FontAwesome auto-render, Bootstrap tooltip
+  // auto-init, the verts auto-bind) against THIS document. In production these run in
+  // the page world (the consumer's esbuild bundle); here the preload world stands in:
+  // the DOM is shared, so injected SVGs / tooltip tips / bound verts are visible to
+  // page-world test suites.
+  testOmega.enableFontAwesome();
+  testOmega._wireTooltips();
+  testOmega._wireAds();
+
+  // Analytics, BRIDGED: the real client resolves the injected bridge and forwards
+  // every event over IPC to main's ONE sender. Same `analytics.init()` call
+  // initialize() makes; the rest of initialize (firebase, auth) stays out.
+  // Credentials are handed in ON PURPOSE, the mistake desktop's build must never
+  // make: a bridged renderer has to DROP them (the `analytics-bridge` renderer suite
+  // pins that it holds neither).
+  testOmega.analytics.init({
+    id:        'G-RENDERER1',
+    secret:    'harness-renderer-secret',
+    projectId: 'demo-app',
+    bridge:    testOmega._resolveAnalyticsBridge(),
+  });
+}
+
+// Settled before the page tells main it is ready, so no suite runs ahead of the instance
+const instanceBuilt = buildInstance().catch((e) => {
+  buildError = e.stack || e.message;
+  console.warn('[renderer-preload] Could not build the renderer instance for tests:', e.message);
+});
 
 // Page-world probe for the bridged client analytics: `event()` is the call a
-// renderer's own code makes (`omega.analytics().event(...)`), `state()` reads
+// renderer's own code makes (`omega.analytics.event(...)`), `state()` reads
 // back what the module holds so a suite can pin that no second sender exists.
-contextBridge.exposeInMainWorld('__emTestClientAnalytics', {
-  event: (name, params) => testManager?.omega?.analytics().event(name, params),
+contextBridge.exposeInMainWorld('__omegaTestClientAnalytics', {
+  event: (name, params) => testOmega?.analytics.event(name, params),
   state: () => {
-    const a = testManager?.omega?.analytics();
+    const a = testOmega?.analytics;
     return {
       initialized: Boolean(a?.initialized),
       bridged:     Boolean(a?.bridge),
@@ -258,19 +243,19 @@ contextBridge.exposeInMainWorld('__emTestClientAnalytics', {
 });
 
 // Tooltip instances live in the preload world (page world can't reach the
-// bootstrap namespace across the contextIsolation boundary) — expose a probe so
+// bootstrap namespace across the contextIsolation boundary): expose a probe so
 // page-world suites can assert instance lifecycle by element id. `error()`
 // surfaces WHY the Bootstrap bundle failed to load (renderer.js swallows the
 // require error into a logger.warn that the harness can't see).
-contextBridge.exposeInMainWorld('__emTestTooltip', {
-  available: () => Boolean(testManager?.bootstrap?.Tooltip),
-  // Lazy — by call time the DOM exists, so a require failure here is the real
+contextBridge.exposeInMainWorld('__omegaTestTooltip', {
+  available: () => Boolean(testOmega?.bootstrap?.Tooltip),
+  // Lazy: by call time the DOM exists, so a require failure here is the real
   // reason the bundle can't load (not just "no documentElement yet").
   error: () => {
     try {
-      if (process.env.OMEGA_TEST_RENDERER_MANAGER_PATH) {
+      if (process.env.OMEGA_TEST_RENDERER_PATH) {
         const path = require('path');
-        require(path.join(path.dirname(process.env.OMEGA_TEST_RENDERER_MANAGER_PATH), 'assets', 'js', 'bootstrap.bundle.js'));
+        require(path.join(path.dirname(process.env.OMEGA_TEST_RENDERER_PATH), 'assets', 'js', 'bootstrap.bundle.js'));
       }
       return null;
     } catch (e) {
@@ -279,16 +264,16 @@ contextBridge.exposeInMainWorld('__emTestTooltip', {
   },
   hasInstance: (id) => {
     const el = document.getElementById(id);
-    return Boolean(el && testManager?.bootstrap?.Tooltip?.getInstance(el));
+    return Boolean(el && testOmega?.bootstrap?.Tooltip?.getInstance(el));
   },
   // Show the tooltip from the PRELOAD world. Synthetic mouse events dispatched
   // by page-world test code don't cross the contextIsolation boundary to the
   // preload world's Bootstrap listeners, so hover can't be simulated from a
-  // suite — real single-world hover behavior is covered by consumer boot
+  // suite; real single-world hover behavior is covered by consumer boot
   // suites. Returns true or the error message.
   showDirect: (id) => {
     try {
-      testManager.bootstrap.Tooltip.getOrCreateInstance(document.getElementById(id)).show();
+      testOmega.bootstrap.Tooltip.getOrCreateInstance(document.getElementById(id)).show();
       return true;
     } catch (e) {
       return e.message;
@@ -296,20 +281,31 @@ contextBridge.exposeInMainWorld('__emTestTooltip', {
   },
 });
 
-contextBridge.exposeInMainWorld('__emTestManager', {
-  isDevelopment:  () => testManager?.isDevelopment(),
-  isProduction:   () => testManager?.isProduction(),
-  isTesting:      () => testManager?.isTesting(),
-  getVersion:     () => testManager?.getVersion(),
-  getEnvironment: () => testManager?.getEnvironment(),
-  getApiUrl:      (env) => testManager?.getApiUrl(env),
-  getFunctionsUrl:(env) => testManager?.getFunctionsUrl(env),
-  getWebsiteUrl:  (env) => testManager?.getWebsiteUrl(env),
+// The instance's own surface, for the page world: the environment helpers, the URL
+// helpers, and what `omega.desktop` is. Each is forwarded as a sync contextBridge
+// function.
+contextBridge.exposeInMainWorld('__omegaTestInstance', {
+  built:          () => Boolean(testOmega),
+  // WHY the instance did not build (the console.warn above lands where the runner can't see it)
+  error:          () => buildError,
+  isDevelopment:  () => testOmega?.isDevelopment(),
+  isProduction:   () => testOmega?.isProduction(),
+  isTesting:      () => testOmega?.isTesting(),
+  getVersion:     () => testOmega?.getVersion(),
+  getEnvironment: () => testOmega?.getEnvironment(),
+  getApiUrl:      (env) => testOmega?.getApiUrl(env),
+  getFunctionsUrl:(env) => testOmega?.getFunctionsUrl(env),
+  getWebsiteUrl:  (env) => testOmega?.getWebsiteUrl(env),
+  // `omega.desktop` IS the preload's bridge object, under main's names
+  desktopIsBridge: () => Boolean(testOmega) && testOmega.desktop === window.desktop,
+  desktopKeys:     () => (testOmega ? Object.keys(testOmega.desktop).sort() : []),
+  // The client's page store stays `omega.storage`; the app store is `omega.desktop.storage`
+  storageIsPageStore: () => Boolean(testOmega) && testOmega.storage !== testOmega.desktop.storage,
   // Mutator used by tests to flip config flags between assertions.
   setConfig:      (path, value) => {
-    if (!testManager) return;
+    if (!testOmega) return;
     const parts = path.split('.');
-    let obj = testManager.config;
+    let obj = testOmega.config;
     for (let i = 0; i < parts.length - 1; i++) {
       obj[parts[i]] = obj[parts[i]] || {};
       obj = obj[parts[i]];

package/dist/test/index.js

@@ -8,14 +8,14 @@
 //     description: 'config has brand.id',
 //     timeout: 5000,
 //     run: async (ctx) => {
-//       const cfg = Manager.getConfig();
+//       const cfg = require('../build.js').getConfig();
 //       ctx.expect(cfg.brand.id).toBeTruthy();
 //     },
 //     cleanup: async (ctx) => { ... },
 //   };
 //
 // Boot layer — spawns the consumer's actual built main bundle (dist/main.bundle.js)
-// and runs `inspect` against the live manager. Replaces shell-level `npm start && sleep && kill`
+// and runs `inspect` against the live omega instance. Replaces shell-level `npm start && sleep && kill`
 // smoke tests with deterministic, signal-driven pass/fail. Use this to verify the WHOLE
 // integration: consumer scaffolds, brand config, custom integrations, real boot order.
 //
@@ -23,10 +23,10 @@
 //     layer: 'boot',
 //     description: 'tray boots with default items',
 //     timeout: 15000,
-//     inspect: async ({ manager, expect, projectRoot }) => {
-//       expect(manager.tray.has('open')).toBe(true);
-//       expect(manager.tray.has('check-for-updates')).toBe(true);
-//       expect(manager.menu.isRendered()).toBe(true);
+//     inspect: async ({ omega, expect, projectRoot }) => {
+//       expect(omega.tray.has('open')).toBe(true);
+//       expect(omega.tray.has('check-for-updates')).toBe(true);
+//       expect(omega.menu.isRendered()).toBe(true);
 //     },
 //   };
 //
@@ -36,9 +36,9 @@
 //     layer: 'main',
 //     description: 'storage round-trip',
 //     tests: [
-//       { name: 'set value', run: async (ctx) => { ctx.state.key = 'foo'; ctx.manager.storage.set('foo', 'bar'); } },
-//       { name: 'get value', run: async (ctx) => { ctx.expect(ctx.manager.storage.get('foo')).toBe('bar'); } },
-//       { name: 'delete',    run: async (ctx) => { ctx.manager.storage.delete('foo'); } },
+//       { name: 'set value', run: async (ctx) => { ctx.state.key = 'foo'; ctx.omega.storage.set('foo', 'bar'); } },
+//       { name: 'get value', run: async (ctx) => { ctx.expect(ctx.omega.storage.get('foo')).toBe('bar'); } },
+//       { name: 'delete',    run: async (ctx) => { ctx.omega.storage.delete('foo'); } },
 //     ],
 //   };
 //
@@ -57,7 +57,7 @@
 //   - ctx.state        — shared object across tests in a suite/group
 //   - ctx.skip(reason) — throw to skip the current test at runtime
 //   - ctx.layer        — current layer name
-//   - ctx.manager      — @omega.js/desktop Manager instance (main layer only — added in 2.3b)
+//   - ctx.omega        : the booted @omega.js/desktop main-process instance (main layer only)
 //   - ctx.page         — BrowserWindow page (renderer layer only — added in 2.3c)
 
 module.exports = {

package/dist/test/runner.js

@@ -9,7 +9,7 @@
 //   - 'build'    runs in plain Node (runner core).
 //   - 'main'     spawns Electron via runners/electron.js, runs in the main process.
 //   - 'renderer' runs in a hidden BrowserWindow in the same spawned Electron process.
-//   - 'boot'     spawns the consumer's actual built bundle and inspects the live manager.
+//   - 'boot'     spawns the consumer's actual built bundle and inspects the live omega instance.
 //
 // Electron / boot runners are lazy-loaded so a missing electron doesn't prevent build-layer
 // tests from running. The layer callbacks below require() them only when those layers exist.
@@ -68,7 +68,7 @@ const runner = createRunner({
   ],
 
   boot: {
-    // Spawn the consumer's actual built bundle and inspect the live manager (the core
+    // Spawn the consumer's actual built bundle and inspect the live omega instance (the core
     // aggregates boot tests into the flat `tests` list). `suites` are the boot-bound
     // renderer suites (`view: '<name>'`), which run in a real window of that same app.
     run: async ({ tests, suites, results, projectRoot }) => {

package/dist/test/runners/boot.js

@@ -1,5 +1,5 @@
 // Boot-runner — spawns electron with the consumer's actual built main bundle, runs
-// inspect functions against the live manager, then quits cleanly.
+// inspect functions against the live omega instance, then quits cleanly.
 //
 // Differences from runners/electron.js:
 //   - electron.js spawns electron with `harness/main-entry.js` and tests @omega.js/desktop lib code in isolation.
@@ -27,6 +27,7 @@ const { spawn, spawnSync } = require('child_process');
 const chalk = require('chalk').default;
 const distSnapshot = require('../utils/dist-snapshot.js');
 const { renderEvent } = require('./render-event.js');
+const { TEST_EVENT_PREFIX } = require('../../utils/test-events.js');
 
 // How long a booted app gets to say anything at all before the run is declared
 // failed. Generous: the app under test is the consumer's real one, cold.
@@ -44,8 +45,8 @@ async function runBootTests({ tests, suites, projectRoot, frameworkDistRoot }) {
 
   // OMEGA_TEST_BOOT_PROJECT — boot a different project root than the CWD. Auto-set to the
   // bundled fixture when @omega.js/desktop self-tests (see commands/test.js); set it explicitly to boot a
-  // real consumer (e.g. deployment-playground-desktop) without cd-ing into it. Mirrors
-  // BXM's OMEGA_TEST_BOOT_PROJECT / UJM's UJ_TEST_BOOT_PROJECT.
+  // real consumer (e.g. deployment-playground-desktop) without cd-ing into it. The
+  // same switch every framework's boot runner reads.
   const effectiveRoot = process.env.OMEGA_TEST_BOOT_PROJECT
     ? path.resolve(process.env.OMEGA_TEST_BOOT_PROJECT)
     : projectRoot;
@@ -147,7 +148,7 @@ async function bootProject({ tests, suites, effectiveRoot, frameworkDistRoot })
 
   const bootEntry = path.join(frameworkDistRoot, 'test', 'harness', 'boot-entry.js');
 
-  // Tell the consumer's main.js to publish the manager + run the boot harness.
+  // Tell the consumer's main.js to publish the instance + run the boot harness.
   // Three env vars are picked up by @omega.js/desktop's main.js after init completes:
   //   OMEGA_TEST_BOOT          — gate; "1" turns on harness loading
   //   OMEGA_TEST_BOOT_HARNESS  — absolute path to harness module (resolved here so it works
@@ -232,9 +233,9 @@ function runBootChild({ electronBin, args, childEnv, effectiveRoot, specFile, sk
       while ((nl = buffer.indexOf('\n')) >= 0) {
         const line = buffer.slice(0, nl);
         buffer = buffer.slice(nl + 1);
-        if (line.startsWith('__EM_TEST__')) {
+        if (line.startsWith(TEST_EVENT_PREFIX)) {
           armBudget();
-          renderEvent(JSON.parse(line.slice('__EM_TEST__'.length)), counts);
+          renderEvent(JSON.parse(line.slice(TEST_EVENT_PREFIX.length)), counts);
         } else if (process.env.OMEGA_TEST_DEBUG && line.trim().length > 0) {
           process.stdout.write(chalk.gray(`      ${line}\n`));
         }

package/dist/test/runners/electron.js

@@ -5,6 +5,7 @@ const path = require('path');
 const { spawn } = require('child_process');
 const chalk = require('chalk').default;
 const { renderEvent } = require('./render-event.js');
+const { TEST_EVENT_PREFIX } = require('../../utils/test-events.js');
 
 function runElectronTests({ harnessEntry, suiteFiles, rendererSuiteFiles, filter, projectRoot }) {
   rendererSuiteFiles = rendererSuiteFiles || [];
@@ -59,8 +60,8 @@ function runElectronTests({ harnessEntry, suiteFiles, rendererSuiteFiles, filter
       while ((nl = buffer.indexOf('\n')) >= 0) {
         const line = buffer.slice(0, nl);
         buffer = buffer.slice(nl + 1);
-        if (line.startsWith('__EM_TEST__')) {
-          renderEvent(JSON.parse(line.slice('__EM_TEST__'.length)), counts);
+        if (line.startsWith(TEST_EVENT_PREFIX)) {
+          renderEvent(JSON.parse(line.slice(TEST_EVENT_PREFIX.length)), counts);
         } else if (line.trim().length > 0) {
           // Pass-through other electron stdout (logger lines from @omega.js/desktop init, etc.)
           // Indent so they don't disrupt the layout.

package/dist/test/runners/render-event.js

@@ -1,4 +1,4 @@
-// Harness-event rendering: the ONE home of "what a `__EM_TEST__` envelope looks like on
+// Harness-event rendering: the ONE home of "what a `__OMEGA_TEST__` envelope looks like on
 // screen" and of the counts it folds into.
 //
 // Both runners parse the same JSON-line protocol (runners/electron.js from the spawned
@@ -10,7 +10,7 @@ const chalk = require('chalk').default;
 
 /**
  * Render one harness event and fold it into the run's counts.
- * @param {object} evt - A parsed `__EM_TEST__` envelope from a harness.
+ * @param {object} evt - A parsed `__OMEGA_TEST__` envelope from a harness.
  * @param {object} counts - `{ passed, failed, skipped }`, mutated in place.
  * @returns {void}
  */