@omega.js/desktop 0.51.0 → 0.53.0

package/dist/vendor/devkit/lockfile.js

@@ -0,0 +1,127 @@
+/**
+ * lockfile: regenerate an install root's OWN package-lock.json
+ * ([#938](https://github.com/Omega-JS-Stack/omega/issues/938)).
+ *
+ * ONE helper for its three callers: the pack step (`pack-local`, the staged
+ * shape), `omega i local` (`linkLocalPackages`) and `omega i live`
+ * (`restoreRegistrySpecs`).
+ *
+ * Two things a plain `npm install` gets wrong here, and this answers both:
+ *   - `--prefix` makes npm treat `root` as the install root. Without it, npm in
+ *     a directory that is itself a WORKSPACE of an outer root (every in-repo
+ *     brand, under the omega monorepo's `brands/*`) climbs to that outer root
+ *     and writes ITS lockfile, leaving the brand's own untouched.
+ *   - npm KEEPS a locked link whose target's version satisfies a registry spec,
+ *     so a lock from the local era (`link: true` into a checkout already at the
+ *     published number) would survive the flip. Every @omega.js entry the
+ *     deploy gate would refuse (`brandLockfileDrift`) is dropped first, with its
+ *     link target, so npm resolves those afresh and keeps every other pin.
+ *   - npm also honors a STALE path entry, a folder the lock names that is no
+ *     longer on disk (a renamed target), and re-creates whatever link its
+ *     dependencies declare. Those entries go first, with everything under them
+ *     and every `node_modules/` link pointing into them.
+ *
+ * Transactional: a failed npm run writes the lock back byte for byte.
+ */
+const fs = require('fs');
+const path = require('path');
+const jetpack = require('fs-jetpack');
+
+const { safeInstall } = require('./safe-install.js');
+const { brandLockfileDrift, staleLockPaths } = require('./brand-version.js');
+
+/** A path equal to base, or nested beneath it. */
+const under = (value, base) => value === base || value.startsWith(`${base}/`);
+
+/**
+ * Drop every stale path entry (`staleLockPaths`), everything nested under it,
+ * and every `node_modules/` entry whose `resolved` points into it.
+ *
+ * @param {object} lock - The parsed lock (mutated).
+ * @param {string} root - The install root the keys are relative to.
+ * @returns {string[]} The stale paths dropped (the outermost of each tree).
+ */
+function dropStalePaths(lock, root) {
+  const stale = staleLockPaths({ root, packages: lock.packages });
+  const outermost = stale.filter((key) => !stale.some((other) => other !== key && under(key, other)));
+
+  for (const [key, entry] of Object.entries(lock.packages)) {
+    const pointsInto = entry && typeof entry.resolved === 'string' && outermost.some((base) => under(entry.resolved, base));
+    if (outermost.some((base) => under(key, base)) || pointsInto) delete lock.packages[key];
+  }
+
+  return outermost;
+}
+
+/**
+ * Drop every lock entry `drift` names, plus a dropped link's target entry and
+ * everything nested under it (the checkout's own dependencies).
+ *
+ * @param {object} lock - The parsed lock (mutated).
+ * @param {Array<{ key: string|null, entry: object|undefined }>} drift - What the gate refused.
+ * @returns {string[]} The names whose entries were dropped.
+ */
+function dropDrift(lock, drift) {
+  const dropped = [];
+
+  for (const { name, key, entry } of drift) {
+    // An absent entry has nothing to drop (npm adds it from the manifest), and
+    // one inside a stale path is already gone with it.
+    if (!key || !lock.packages[key]) continue;
+
+    delete lock.packages[key];
+    dropped.push(name);
+
+    if (entry.link && entry.resolved) {
+      for (const other of Object.keys(lock.packages)) {
+        if (under(other, entry.resolved)) delete lock.packages[other];
+      }
+    }
+  }
+
+  return dropped;
+}
+
+/**
+ * Regenerate `root`'s package-lock.json from its manifests, lock-only: no
+ * scripts, no node_modules writes.
+ *
+ * @param {object} options
+ * @param {string} options.root - The install root whose lock is regenerated.
+ * @param {function} [options.log] - Line sink (silent when omitted).
+ * @returns {Promise<void>}
+ */
+async function regenerateLockfile({ root, log }) {
+  const { lockPath, lock, drift } = brandLockfileDrift({ root });
+  const original = lock ? jetpack.read(lockPath) : null;
+
+  if (lock && lock.packages) {
+    const pruned = dropStalePaths(lock, root);
+    const dropped = dropDrift(lock, drift);
+
+    if (pruned.length || dropped.length) {
+      jetpack.write(lockPath, `${JSON.stringify(lock, null, 2)}\n`);
+    }
+    if (log && pruned.length) log(`Pruned the lock entries of folders no longer on disk (${pruned.join(', ')}) so npm stops honoring what they declare`);
+    if (log && dropped.length) log(`Dropped the stale lock entries of ${dropped.join(', ')} so npm resolves them from the manifests`);
+  }
+
+  if (log) log(`Regenerating ${path.basename(root)}/package-lock.json...`);
+
+  // The REAL path: npm writes a link's `resolved` relative to the physical
+  // directory, so a prefix spelled through an alias (macOS /var for
+  // /private/var, a symlinked brand dir) reads those paths from the wrong place.
+  const prefix = fs.realpathSync(root);
+
+  try {
+    await safeInstall(
+      `npm install --package-lock-only --ignore-scripts --no-audit --no-fund --prefix "${prefix}"`,
+      { log: false, config: { cwd: prefix } },
+    );
+  } catch (error) {
+    if (original !== null) jetpack.write(lockPath, original);
+    throw error;
+  }
+}
+
+module.exports = { regenerateLockfile };

package/dist/vendor/devkit/merge-line-files.js

@@ -1,7 +1,6 @@
 // Merge line-based files (.env, .gitignore, AGENTS.md) during framework setup —
-// the OMEGA marker-section protocol. Canonical version is EM's (it added .env
-// double-quote normalization and order-safe key substitution over the older
-// BXM/UJM inline copies) plus @omega.js/backend's custom-key promotion (a key the framework
+// the OMEGA marker-section protocol: .env double-quote normalization,
+// order-safe key substitution, and custom-key promotion (a key the framework
 // newly adopts into its Default section is promoted UP from the user's Custom
 // section with their value, instead of appearing empty in Default and set in
 // Custom).

package/dist/vendor/devkit/pack-local.js

@@ -47,6 +47,7 @@ const path = require('path');
 const jetpack = require('fs-jetpack');
 const powertools = require('node-powertools');
 const chalk = require('chalk').default;
+const { regenerateLockfile } = require('./lockfile.js');
 
 // Constants
 const STAGING_DIR = 'omega_modules';
@@ -369,15 +370,11 @@ async function stageLocalPackages({ dir, log = () => {} }) {
     }
 
     // A remote install runs `npm ci`, so the uploaded lockfile must match the
-    // staged shape. `--prefix` is what makes npm treat THIS dir as the install
-    // root: run inside a workspace it would otherwise climb to the workspace
-    // root and write that one's lockfile instead.
+    // staged shape, regenerated from scratch (the one helper keeps it THIS
+    // dir's lock, never an enclosing workspace root's).
     log(`  ${chalk.dim('→')} Regenerating package-lock.json for the staged shape...`);
     jetpack.remove(lockPath);
-    await powertools.execute(
-      `npm install --package-lock-only --ignore-scripts --no-audit --no-fund --prefix "${root}"`,
-      { log: false, config: { cwd: root } },
-    );
+    await regenerateLockfile({ root });
   } catch (error) {
     // Loud and clean: the deploy stops here, and the tree goes back exactly as
     // it was rather than sitting half-staged.

package/dist/vendor/devkit/preludes/origin-heal.js

@@ -32,21 +32,22 @@
  *   - anything else: the remote is rewritten to the answered `full_name`,
  *     keeping its own url form, and the heal is stated in one line.
  *
- * Then DRIFT, on whatever the answer was: `repo.org` stays the one typed value
- * in `config/omega.json5`, and an owner GitHub reports that differs from it is
- * stated in one line and nothing more. The prelude never writes config: which
- * of the two is wrong (the config, or where the repo lives) is a human's call,
- * and the manager's repo service only ensures repos UNDER `repo.org`.
+ * Then DRIFT, on whatever the answer was: the WHOLE slug GitHub answers against
+ * the source repo the config derives (`@omega.js/config`'s `repoDrift`, so a
+ * rename drifts as surely as a transfer,
+ * [#934](https://github.com/Omega-JS-Stack/omega/issues/934)), stated in one
+ * line and nothing more. Never fatal: this runs before every verb, and a fatal
+ * boot would lock out the verbs that fix the mismatch. The verbs that ACT on
+ * the derived repo (the manage walk, the deploy) refuse on the same line
+ * instead. The prelude never writes config: which of the two is wrong (the
+ * config, or where the repo lives) is a human's call.
  *
  * The WRITE is the one thing that fails loudly: a `git remote set-url` refused
  * after a `get-url` just answered is not an external condition, it is a broken
  * invariant, and the runner stops the boot on it.
  */
 
-const path = require('node:path');
-const jetpack = require('fs-jetpack');
-
-const { parseRemoteUrl, retargetRemoteUrl, remoteUrl, setRemoteUrl } = require('../git-remote.js');
+const { readOrigin, retargetRemoteUrl, setRemoteUrl } = require('../git-remote.js');
 const github = require('../github-repo.js');
 
 // The one network read runs on EVERY verb boot, so a network that hangs (a
@@ -61,7 +62,7 @@ const GITHUB_READ_TIMEOUT_MS = 10000;
  * @param {function} [context.execFn] - Injectable git exec (tests).
  * @param {function} [context.resolveRepo] - Injectable `(owner, name) => repo|null` (tests).
  * @param {function} [context.log] - Injectable line printer (tests).
- * @returns {{ healed: boolean, reason?: string, from?: string, to?: string, drift?: { owner: string, org: string } }}
+ * @returns {{ healed: boolean, reason?: string, from?: string, to?: string, drift?: { origin: string, derived: string } }}
  */
 function run(context = {}) {
   const { brandRoot, execFn } = context;
@@ -72,21 +73,12 @@ function run(context = {}) {
 
   if (!brandRoot) return { healed: false, reason: 'no-brand' };
 
-  // One stat, before anything else: most boots in this monorepo's own trees and
-  // in every fixture brand end here.
-  if (!jetpack.exists(path.join(brandRoot, '.git'))) return { healed: false, reason: 'no-git' };
+  // One stat before anything else (most boots in this monorepo's own trees and
+  // in every fixture brand end there), then the remote itself.
+  const current = readOrigin({ dir: brandRoot, execFn });
+  if (!current.slug) return { healed: false, reason: current.reason };
 
-  let url;
-  try {
-    url = remoteUrl({ dir: brandRoot, execFn });
-  } catch (e) {
-    return { healed: false, reason: 'no-origin' };
-  }
-
-  const current = parseRemoteUrl(url);
-  if (!current) return { healed: false, reason: 'foreign-remote' };
-
-  const from = `${current.owner}/${current.repo}`;
+  const { url, slug: from } = current;
 
   // The ONE network read, on the slug the checkout carries: GitHub follows its
   // own redirect and names where that repo lives now.
@@ -109,44 +101,38 @@ function run(context = {}) {
     result = { healed: true, from, to };
   }
 
-  const drift = configDrift(brandRoot, context.config, to.split('/')[0]);
+  const config = composedConfig(brandRoot, context.config);
+  const { repoDrift, sourceRepo } = require('../../config/index.js');
+  const drift = config ? repoDrift(to, config) : null;
+
   if (drift) {
-    log(`omega: origin lives under ${drift.owner} but repo.org is ${drift.org}: fix repo.org in config/omega.json5 or move the repo`);
-    result.drift = drift;
+    log(`omega: ${drift}`);
+    result.drift = { origin: to, derived: sourceRepo(config).slug };
   }
 
   return result;
 }
 
 /**
- * The gap between where the repo LIVES and the org the config types, or null
- * when there is none to state. The config is loaded here when the caller has
- * none, and an unloadable one answers "no drift": a config the boot cannot read
- * is the VERB's failure to report, in its own words, never a prelude's. A brand
- * declaring no `repo` block types no org, so there is nothing to disagree with.
+ * The composed config the drift is read against: the caller's when it has one,
+ * else loaded here, and an unloadable one answers null ("no drift"): a config
+ * the boot cannot read is the VERB's failure to report, in its own words, never
+ * a prelude's.
  *
  * @param {string} brandRoot - The brand root.
  * @param {object} [config] - The composed config, when the caller has it.
- * @param {string} owner - The owner GitHub resolved the repo under.
- * @returns {{ owner: string, org: string }|null}
+ * @returns {object|null}
  */
-function configDrift(brandRoot, config, owner) {
-  const { loadConfig, repoBlock } = require('../../config/index.js');
+function composedConfig(brandRoot, config) {
+  if (config) return config;
 
-  let block;
-  if (config) {
-    block = repoBlock(config);
-  } else {
-    try {
-      block = repoBlock(loadConfig(brandRoot).config);
-    } catch (e) {
-      return null;
-    }
-  }
-
-  if (!block || block.org.toLowerCase() === owner.toLowerCase()) return null;
+  const { loadConfig } = require('../../config/index.js');
 
-  return { owner, org: block.org };
+  try {
+    return loadConfig(brandRoot).config;
+  } catch (e) {
+    return null;
+  }
 }
 
 module.exports = {

package/dist/vendor/devkit/target-secrets.js

@@ -31,7 +31,10 @@
  *      config (`repo.org`, the SOURCE repo). An inferred git remote is not proof: a
  *      target vendored into a framework/test monorepo, a cloned starter still
  *      pointing at the template author, or any fork would publish this brand's
- *      `.env` to a stranger's Actions.
+ *      `.env` to a stranger's Actions. A checkout that could be the brand's own
+ *      and whose origin names another repo REFUSES on `repoDrift`'s one line
+ *      ([#934](https://github.com/Omega-JS-Stack/omega/issues/934)), the
+ *      same refusal the deploy lane and the manage walk make.
  *   4. PUBLISH — each collected key becomes a repo Actions secret via devkit's
  *      `gh` boundary (values on stdin, never logged).
  *
@@ -70,11 +73,12 @@
  * sends nothing. The refusal still THROWS in a dry run: a plan that cannot be
  * made is loud.
  */
-const { composeTargetEnv, loadConfig } = require('../config/index.js');
+const { composeTargetEnv, loadConfig, sourceRepo } = require('../config/index.js');
 const { publishSecretKeys } = require('../config/env-delivery.js');
 const { checkEnvRules } = require('../config/env-rules.js');
 const { publishActionsSecrets } = require('./actions-secrets.js');
-const { resolveRepo, resolveDeployLane } = require('./deploy.js');
+const { assertOriginMatches } = require('./git-remote.js');
+const { findBrandRoot } = require('./local.js');
 const { targetSeams } = require('./target-seams.js');
 
 /**
@@ -200,26 +204,18 @@ function missingRequiredSecrets(options) {
 }
 
 /**
- * The brand's SOURCE repo as `owner/name`, from the target's resolved config:
- * the one the workflows and their secrets live on, derived as
- * `<brand.id>-omega` under `repo.org` (#883). Null when the config declares
- * nothing usable or doesn't load.
+ * The target's resolved PRODUCTION config, like every other read this publish
+ * makes (#895): the repo a release's secrets belong to is the one the
+ * production config names. Null when it doesn't load.
  *
  * @param {object} options
  * @param {string} options.targetDir - The target root.
  * @param {string} options.target - Target name ('web', 'extension', …).
- * @returns {string|null}
+ * @returns {object|null}
  */
-function declaredBrandRepo(options) {
+function productionConfig(options) {
   try {
-    const { loadConfig, sourceRepo } = require('../config/index.js');
-    // PRODUCTION, like every other read this publish makes (#895): the repo a
-    // release's secrets belong to is the one the production config names.
-    const { config } = loadConfig(options.targetDir, options.target, { environment: 'production' });
-    if (!config) return null;
-
-    const source = sourceRepo(config);
-    return source ? source.slug : null;
+    return loadConfig(options.targetDir, options.target, { environment: 'production' }).config || null;
   } catch (e) {
     return null;
   }
@@ -241,7 +237,6 @@ function declaredBrandRepo(options) {
  * @param {Object<string, string>} [options.extraSecrets] - Override for the
  *   target's already-valued keys, merged OVER the composed set (tests).
  * @param {function} [options.execFn] - Injectable `gh` exec (tests).
- * @param {function} [options.gitExecFn] - Injectable `git` exec for remote discovery (tests).
  * @returns {{ skipped: string }|{ planned: string[] }|{ published: string[], failed: Array<object> }}
  */
 function publishTargetSecrets(options) {
@@ -297,38 +292,32 @@ function publishTargetSecrets(options) {
     return { skipped: 'no-secrets' };
   }
 
-  const declared = declaredBrandRepo({ targetDir, target });
-  if (!declared) {
+  const config = productionConfig({ targetDir, target });
+  const source = config ? sourceRepo(config) : null;
+  if (!source) {
     logger.warn('Skipping secret publication: this brand names no GitHub repo in config (repo.org). Set it, then re-run `omega deploy`.');
     return { skipped: 'no-declared-repo' };
   }
 
-  // A NESTED brand (its root is not the toplevel of the git repo it sits in)
-  // has a remote that answers the ENCLOSING repo by construction, and its
-  // deploy pushes a snapshot to the DECLARED repo regardless
-  // ([#872](https://github.com/Omega-JS-Stack/omega/issues/872)), so the
-  // mismatch guard would only ever skip a publish that is correct. Every other
-  // guard stays: what the guard protects against is a checkout that COULD have
-  // been the brand's own and is not.
-  const { nested } = resolveDeployLane({ dir: targetDir, execFn: options.gitExecFn });
-  const repo = declared;
-
-  if (!nested) {
-    let remote;
-    try {
-      const { owner, repo: name } = resolveRepo({ cwd: targetDir, execFn: options.gitExecFn });
-      remote = `${owner}/${name}`;
-    } catch (e) {
-      logger.warn(`Skipping secret publication — no GitHub remote here (${e.message})`);
-      return { skipped: 'no-remote' };
-    }
-
-    if (declared.toLowerCase() !== remote.toLowerCase()) {
-      logger.warn(`Skipping secret publication — the git remote here is ${remote}, but this brand's repo is ${declared}. Run \`omega deploy\` from the brand's own checkout.`);
-      return { skipped: 'repo-mismatch' };
-    }
+  // The ONE origin gate the deploy lane and the manage walk use
+  // ([#934](https://github.com/Omega-JS-Stack/omega/issues/934)): the brand
+  // root's own origin (the local remote, which the boot prelude has already
+  // healed onto GitHub's redirect) must BE the derived source repo, or the
+  // publish REFUSES on the one drift line, because arming a repo that is not
+  // the derived one is the harm itself. No `.git` AT the brand root is nothing
+  // to compare: a NESTED brand's remote is the enclosing repo's by
+  // construction, and its deploy pushes to the derived repo regardless
+  // ([#872](https://github.com/Omega-JS-Stack/omega/issues/872)). A checkout
+  // with no GitHub origin (nobody pushed it yet, or it is hosted elsewhere) has
+  // no repo to arm, so it skips.
+  const origin = assertOriginMatches({ dir: findBrandRoot(targetDir), config });
+  if (origin.reason === 'no-origin' || origin.reason === 'foreign-remote') {
+    logger.warn(`Skipping secret publication: no GitHub remote here (${origin.reason})`);
+    return { skipped: 'no-remote' };
   }
 
+  const repo = source.slug;
+
   // The PLAN, and nothing else (#895): what the composition answered, by NAME.
   // It runs after the refusal and the two guards above on purpose, so a dry run
   // is a real preview of whether the deploy would publish at all: every one of
@@ -347,4 +336,4 @@ function publishTargetSecrets(options) {
   return result;
 }
 
-module.exports = { collectTargetSecrets, declaredBrandRepo, missingRequiredSecrets, publishTargetSecrets };
+module.exports = { collectTargetSecrets, missingRequiredSecrets, publishTargetSecrets };

package/dist/vendor/devkit/test/runner-core.js

@@ -1,7 +1,7 @@
 // Shared test-runner core for the OMEGA frameworks — discovery, suite/group/standalone
-// execution, filtering, skip semantics, init hooks, and reporting. Extracted from UJM's
-// runner (the canonical 3-layer build/page/boot model); BXM/EM/UJM differ only in title,
-// package name, CLI target alias, and their special layers — all injected via config.
+// execution, filtering, skip semantics, init hooks, and reporting, on the 3-layer
+// build/page/boot model. The frameworks differ only in title, package name, CLI
+// target alias, and their special layers — all injected via config.
 //
 // Test-definition forms supported (see each framework's test/index.js for docs):
 //   - Standalone:  module.exports = { layer, description, run, cleanup, timeout, skip };
@@ -12,7 +12,7 @@
 // Suites stop on first failure (sequential, share state). Groups run all tests regardless.
 //
 // createRunner(config) config surface:
-//   title              — heading printed at the top of a run ('Browser Extension Manager Tests')
+//   title              — heading printed at the top of a run ('OMEGA Extension Tests')
 //   packageName        — framework npm name; cwd package === this ⇒ framework self-test mode
 //                        (framework boot/ suites only run in self-test mode — they assert on
 //                        the framework's own fixture consumer)
@@ -28,7 +28,7 @@
 //                           options, results, projectRoot }) => void }]
 //                        The callback owns runner loading, skip messaging, and results
 //                        mutation — framework glue stays framework-side.
-//   bootDefaultTimeout — per-test default for boot-layer inspect() (UJM/BXM 20000, EM 15000)
+//   bootDefaultTimeout — per-test default for boot-layer inspect() (each framework's runner sets its own)
 //   boot:              { run: async ({ tests, suites, options, results, projectRoot }) => void }
 //                        Called with the aggregated flat boot test list plus the boot-BOUND
 //                        suites (at least one of the two is non-empty).
@@ -37,7 +37,7 @@
 //                        partitions that FILE into the boot layer whatever its `layer` says,
 //                        and hands it to boot.run WHOLE (`suites: [{ file, mod }]`) instead
 //                        of flattening it into the inspect list: for suites that need the
-//                        boot lane's built app but run their own way (EM's `view:` renderer
+//                        boot lane's built app but run their own way (desktop's `view:` renderer
 //                        suites). Default: () => false. An array-form file is never bound.
 
 const path = require('path');

package/dist/vendor/monitoring/env.js

@@ -21,7 +21,7 @@
  * signal with its own opinion: a build-mode run of a development artifact
  * reported as production, and a packaged production app whose lane did not
  * carry the flag reported as development. @omega.js/backend still passes its
- * own answer in (`Manager.isProduction()`), and a boolean a host supplies
+ * own answer in (`omega.isProduction()`), and a boolean a host supplies
  * always wins.
  */
 
@@ -30,7 +30,7 @@ const { isProduction } = require('../config/environment.js');
 /**
  * Read the environment gates for core.resolveConfig().
  * @param {object} [host] - the host's own signals, and the context the one
- *   environment is read off (a Manager carrying the baked `config`)
+ *   environment is read off (an Omega instance carrying the baked `config`)
  * @param {boolean} [host.isProduction] - overrides the one environment's answer
  * @param {boolean} [host.allowInDev] - the host's own dev opt-in (e.g. @omega.js/backend's `reportErrorsInDev`)
  * @returns {{ killed: boolean, killedReason: string|null, isProduction: boolean, allowInDev: boolean }}

package/dist/vendor/monitoring/index.js

@@ -1,6 +1,6 @@
 /**
  * The @omega.js/monitoring entry — the Electron context-aware delegator (#380).
- * Lifted from @omega.js/desktop's lib/sentry/index.js: a desktop Manager
+ * Lifted from @omega.js/desktop's lib/sentry/index.js: a desktop Omega instance
  * singleton requires this file from whichever process it is in, and every call
  * forwards to the right per-context module.
  *

package/dist/vendor/monitoring/main.js

@@ -25,7 +25,7 @@ const main = {
   _Sentry:      null,
 
   /**
-   * @param {object} host - the desktop Manager: { config, getVersion() }
+   * @param {object} host - the desktop Omega instance: { config, getVersion() }
    */
   initialize(host) {
     main._initialized = true;

package/dist/vendor/monitoring/preload.js

@@ -18,7 +18,7 @@ const preload = {
   _enabled: false,
 
   /**
-   * @param {object} host - the desktop Manager: { config }
+   * @param {object} host - the desktop Omega instance: { config }
    */
   initialize(host) {
     const { shouldEnable, reason } = resolveConfig(host && host.config && host.config.monitoring, readGates(host));

package/dist/vendor/monitoring/renderer.js

@@ -21,7 +21,7 @@ const renderer = {
   _Sentry:      null,
 
   /**
-   * @param {object} host - the desktop Manager: { config, getVersion() }
+   * @param {object} host - the desktop Omega instance: { config, getVersion() }
    */
   initialize(host) {
     renderer._initialized = true;

package/docs/analytics.md

@@ -51,11 +51,11 @@ The `bundle` task's esbuild `define` bakes `process.env.GOOGLE_ANALYTICS_SECRET`
 ## API
 
 ```js
-manager.analytics.event('button_click', { button_id: 'cta' });
-manager.analytics.pageview('/settings');
-manager.analytics.screenview('SettingsScreen');
-manager.analytics.setUserProperties({ plan: 'premium', trial: false });
-manager.analytics.setUserId('firebase-uid-abc');   // usually wired automatically
+omega.analytics.event('button_click', { button_id: 'cta' });
+omega.analytics.pageview('/settings');
+omega.analytics.screenview('SettingsScreen');
+omega.analytics.setUserProperties({ plan: 'premium', trial: false });
+omega.analytics.setUserId('firebase-uid-abc');   // usually wired automatically
 ```
 
 Same surface in renderer:
@@ -71,10 +71,10 @@ The renderer surface is fire-and-forget IPC (`ipcRenderer.send`) for events; onl
 
 ## The renderer NEVER sends — it forwards ([#411](https://github.com/Omega-JS-Stack/omega/issues/411))
 
-A renderer's own `omega.analytics().event(...)` — the embedded @omega.js/client, the surface a vert click or a permission prompt fires through — routes to the bridge above and is delivered by the MAIN process's sender. There is exactly one sender per install:
+A renderer's own `omega.analytics.event(...)` (the embedded @omega.js/client, the surface a vert click or a permission prompt fires through) routes to the bridge above and is delivered by the MAIN process's sender. There is exactly one sender per install:
 
 ```
-renderer: omega.analytics().event('vert_click', { … })
+renderer: omega.analytics.event('vert_click', { … })
   → @omega.js/client reads config.analyticsBridge (src/renderer.js injects the
     preload's window.desktop.analytics when it boots the client)
   → ipcRenderer.send('desktop:analytics:event', { name, params })
@@ -136,5 +136,5 @@ free-typed string here.
 ## Tests
 
 - `src/test/suites/main/analytics.test.js` — disabled paths, uuidv5 stability, the catalog contract (canonical name in, GA4 descriptor out; unknown names never post), queueing, auth-bridge wiring, IPC handlers, secret-not-leaked guard.
-- `src/test/suites/renderer/analytics-bridge.test.js` — renderer-side surface shape, `getStatus` round-trip, and the #411 pin: a renderer-originated `omega.analytics().event(...)` reaches main's sender exactly once, and the payload GA would receive carries main's `client_id` and main's session id, while the bridged client holds no secret and no device id of its own (the harness hands it credentials on purpose). The harness taps main's transport (`harness/main-entry.js`) so a renderer suite can read back what the sender was handed — a test run never reaches a real GA property. Harness fidelity, stated plainly: it drives the real client and the real IPC channel into the real main-process sender, but the client runs in the preload world holding the bridge object directly, not the contextBridge proxy a page bundle gets — the proxy hop is the one link this pin does not exercise.
+- `src/test/suites/renderer/analytics-bridge.test.js`: renderer-side surface shape, `getStatus` round-trip, and the #411 pin: a renderer-originated `omega.analytics.event(...)` reaches main's sender exactly once, and the payload GA would receive carries main's `client_id` and main's session id, while the bridged client holds no secret and no device id of its own (the harness hands it credentials on purpose). The harness taps main's transport (`harness/main-entry.js`) so a renderer suite can read back what the sender was handed: a test run never reaches a real GA property. Harness fidelity, stated plainly: it drives the real client and the real IPC channel into the real main-process sender, but the client runs in the preload world holding the bridge object directly, not the contextBridge proxy a page bundle gets, the proxy hop is the one link this pin does not exercise.
 - `packages/client/test/analytics.test.js` — the client half: the bridge is the injected config value alone (a planted `window.desktop` bridges nothing), a bridged client drops credentials and mints no device id, an uncatalogued name never leaves the renderer, and a forward that throws never reaches the caller.

package/docs/app-state.md

@@ -2,24 +2,24 @@
 
 Storage-backed launch flags + crash sentinel. Tells you *whether* this is the first launch ever, *how many* times the app has launched, *whether* the previous run crashed, and *whether* the version changed.
 
-## Public API on `manager.appState`
+## Public API on `omega.appState`
 
 ```js
-manager.appState.isFirstLaunch()         // boolean — true ONLY on the very first boot
-manager.appState.getLaunchCount()        // number — total successful launches (including this one)
-manager.appState.getInstalledAt()        // Date  — first ever launch timestamp
-manager.appState.getLastLaunchAt()       // Date | null — previous launch (null on first)
-manager.appState.getLastQuitAt()         // Date | null — previous graceful quit; null if it crashed
-manager.appState.recoveredFromCrash()    // boolean — previous run did not exit cleanly
+omega.appState.isFirstLaunch()         // boolean: true ONLY on the very first boot
+omega.appState.getLaunchCount()        // number: total successful launches (including this one)
+omega.appState.getInstalledAt()        // Date: first ever launch timestamp
+omega.appState.getLastLaunchAt()       // Date | null: previous launch (null on first)
+omega.appState.getLastQuitAt()         // Date | null: previous graceful quit; null if it crashed
+omega.appState.recoveredFromCrash()    // boolean: previous run did not exit cleanly
 
-manager.appState.getVersion()            // string | null — package version of this launch
-manager.appState.getPreviousVersion()    // string | null — version before this launch
-manager.appState.wasUpgraded()           // boolean — true if THIS launch's version differs from the prior
+omega.appState.getVersion()            // string | null: package version of this launch
+omega.appState.getPreviousVersion()    // string | null: version before this launch
+omega.appState.wasUpgraded()           // boolean: true if THIS launch's version differs from the prior
 
-manager.appState.launchedAtLogin()       // boolean — OS booted us via openAtLogin
-manager.appState.launchedFromDeepLink()  // boolean — argv had a deep-link payload (set by lib/deep-link)
+omega.appState.launchedAtLogin()       // boolean: OS booted us via openAtLogin
+omega.appState.launchedFromDeepLink()  // boolean: argv had a deep-link payload (set by lib/deep-link)
 
-manager.appState.reset()                 // wipe persisted state (test helper / factory-reset command)
+omega.appState.reset()                 // wipe persisted state (test helper / factory-reset command)
 ```
 
 ## Storage shape (key `appState`)
@@ -66,24 +66,24 @@ appState.getPreviousVersion() // '1.0.0' (preserved — useful for "what's new"
 ### Show onboarding on first launch
 
 ```js
-if (manager.appState.isFirstLaunch()) {
-  manager.windows.show('onboarding');
+if (omega.appState.isFirstLaunch()) {
+  omega.windows.show('onboarding');
 }
 ```
 
 ### Crash report ping
 
 ```js
-if (manager.appState.recoveredFromCrash()) {
-  manager.sentry.captureMessage('recovered from crash', 'warning');
+if (omega.appState.recoveredFromCrash()) {
+  omega.sentry.captureMessage('recovered from crash', 'warning');
 }
 ```
 
 ### What's new modal after upgrade
 
 ```js
-if (manager.appState.wasUpgraded()) {
-  manager.windows.show('changelog');
+if (omega.appState.wasUpgraded()) {
+  omega.windows.show('changelog');
 }
 ```