@omega.js/desktop 0.1.0

package/dist/vendor/monitoring/core.js

@@ -0,0 +1,180 @@
+/**
+ * core — the ONE place error-reporting policy lives (#380).
+ *
+ * Pure functions, zero runtime assumptions: no SDK, no `process`, no DOM. The
+ * browser bundle imports this file, so an env read here would be a
+ * ReferenceError on a web page (esbuild defines only the NODE_ENV key) — every
+ * environment signal is passed IN as a gate. `env.js` is the Node/Electron side
+ * of that seam.
+ *
+ * Policy it owns, once for every target:
+ *   - config resolution from omega.json5's `monitoring` role section — the
+ *     settings live under `monitoring.providers.sentry` (#425) and DSN presence
+ *     is the enable signal (no separate `enabled` flag — matches
+ *     @omega.js/backend convention: a config block's credentials are its switch)
+ *   - the release tag, from the host's own version identity
+ *   - user normalization with the email SCRUBBED BY DEFAULT (the uid stays —
+ *     it is the join key to the account, and it is not PII on its own)
+ *   - the client-side framework-bundle filter: browser events report ONLY when
+ *     they come from OUR bundles. User-land page scripts, browser extensions
+ *     injecting into the page, and cross-origin "Script error." noise never do.
+ *
+ * The SDK is never loaded from here. Nothing in this file can turn reporting
+ * ON either: it can only say whether a host SHOULD boot one.
+ */
+
+const DEFAULTS = {
+  dsn:              '',
+  environment:      null,   // null = the host's gate decides (production / development)
+  sampleRate:       1,      // error events kept, 0..1 — the sampling knob (Sentry-native)
+  tracesSampleRate: 0.1,
+  attachScreenshot: false,
+  scrubEmail:       true,   // PII off by default — set false to opt IN to emails
+  // Browser only: the URL fragments that identify OUR bundles. Both @omega.js/web
+  // and @omega.js/extension serve every framework bundle (the client runtime
+  // included) out of `/assets/js/`, so one default covers both surfaces.
+  bundlePatterns:   ['/assets/js/'],
+};
+
+// A resolved-but-off result. `options` still comes back so a caller can log what
+// it read.
+function disabled(options, reason) {
+  return { shouldEnable: false, options, reason };
+}
+
+/**
+ * The Sentry settings inside a `monitoring` role section (#425). The role level
+ * carries only `enabled`; every SDK-facing key hangs off the provider, so this
+ * is the one place that knows the nesting. `{ sentry: false }` (deliberately
+ * disabled) and a missing block both resolve to nothing — no dsn, no boot.
+ *
+ * @param {object} [section] - the `monitoring` config block (target-resolved)
+ * @returns {object} the provider's settings, or {} when there are none
+ */
+function providerOptions(section) {
+  const settings = section && section.providers && section.providers.sentry;
+  return settings && typeof settings === 'object' ? settings : {};
+}
+
+/**
+ * Resolve the runtime config and decide whether reporting should boot.
+ *
+ * Reads omega.json5's `monitoring` role section: the SDK-facing keys come from
+ * `monitoring.providers.sentry`, so the resolved options feed init directly.
+ *
+ * @param {object} section - the `monitoring` config block (target-resolved)
+ * @param {object} [gates] - the host's environment signals
+ * @param {boolean} [gates.killed] - a kill switch tripped (env var, test runner)
+ * @param {string} [gates.killedReason] - what tripped it, for the log line
+ * @param {boolean} [gates.isProduction] - this run ships telemetry
+ * @param {boolean} [gates.allowInDev] - report anyway outside production
+ * @returns {{ shouldEnable: boolean, options: object, reason: string|null }}
+ */
+function resolveConfig(section, gates) {
+  gates = gates || {};
+
+  const options = { ...DEFAULTS, ...providerOptions(section) };
+
+  if (gates.killed) {
+    return disabled(options, gates.killedReason || 'disabled by the host');
+  }
+  if (!options.dsn) {
+    return disabled(options, 'no dsn set');
+  }
+  if (!gates.isProduction && !gates.allowInDev) {
+    return disabled(options, 'not a production run (set OMEGA_SENTRY_FORCE=true to override)');
+  }
+
+  if (!options.environment) {
+    options.environment = gates.isProduction ? 'production' : 'development';
+  }
+
+  return { shouldEnable: true, options, reason: null };
+}
+
+/**
+ * Normalize a @omega.js/client / firebase / admin user into the minimal shape
+ * the SDK wants. The email is PII: it rides ONLY when the host explicitly opts
+ * in with `monitoring.providers.sentry.scrubEmail: false`.
+ *
+ * @param {object} user - a user-ish object carrying uid/id and maybe email
+ * @param {object} [options] - the resolved monitoring options
+ * @returns {object|null} { id, email? } — null when there is nothing safe to send
+ */
+function normalizeUser(user, options) {
+  if (!user) return null;
+
+  const scrubEmail = (options || {}).scrubEmail !== false;
+  const out = {};
+
+  if (user.uid)     out.id = user.uid;
+  else if (user.id) out.id = user.id;
+  if (user.email && !scrubEmail) out.email = user.email;
+
+  return Object.keys(out).length === 0 ? null : out;
+}
+
+/**
+ * Build the release tag from the host's own version identity. ONE format on
+ * every target (Ian, 2026-08-20): `<brand.id>@<version>` — a Sentry release is
+ * comparable across the backend, the desktop app and the browser bundles only
+ * when they spell it the same way. The brand id is required config, so a tag
+ * missing one is a config hole, not a second format: no id, no tag.
+ *
+ * The version is the host's own — @omega.js/backend's functions package
+ * version, @omega.js/desktop's app version, the browser blob's app version.
+ *
+ * @param {object} identity - { id, version }
+ * @returns {string|undefined} the tag, or undefined when either half is missing
+ */
+function releaseTag(identity) {
+  const { id, version } = identity || {};
+  if (!id || !version) return undefined;
+  return `${id}@${version}`;
+}
+
+/**
+ * Every stack-frame filename an event carries (exception frames first, then the
+ * threads a hung-renderer report uses).
+ */
+function eventFrameFilenames(event) {
+  const values = [
+    ...((event && event.exception && event.exception.values) || []),
+    ...((event && event.threads && event.threads.values) || []),
+  ];
+
+  return values.flatMap((value) => ((value.stacktrace && value.stacktrace.frames) || [])
+    .map((frame) => frame.filename || frame.abs_path || '')
+    .filter(Boolean));
+}
+
+/**
+ * The client-side doctrine gate (#380): a browser event reports ONLY when our
+ * own framework code is on its stack.
+ *
+ * An event with no matching frame is DROPPED, and that includes an event with no
+ * frames at all — a cross-origin `Script error.` is exactly the third-party noise
+ * this exists to kill. Deliberate `omega.sentry().captureException(...)` calls
+ * are unaffected: they are thrown from page bundles, which ARE our bundles.
+ *
+ * @param {string[]} [patterns] - URL fragments identifying our bundles
+ * @returns {(event: object) => boolean} true when the event may report
+ */
+function createBundleFilter(patterns) {
+  const fragments = (patterns || DEFAULTS.bundlePatterns).filter(Boolean);
+
+  return function isFrameworkEvent(event) {
+    const filenames = eventFrameFilenames(event);
+    return filenames.some((filename) => fragments.some((fragment) => filename.includes(fragment)));
+  };
+}
+
+module.exports = {
+  DEFAULTS,
+  providerOptions,
+  resolveConfig,
+  normalizeUser,
+  releaseTag,
+  eventFrameFilenames,
+  createBundleFilter,
+};

package/dist/vendor/monitoring/env.js

@@ -0,0 +1,49 @@
+/**
+ * env — the Node/Electron half of core's gate seam (#380).
+ *
+ * core.js is pure so the browser bundle can import it; every `process.env` read
+ * lives HERE, and only hosts with a real process require this file.
+ *
+ * The switches, in the order they win:
+ *   OMEGA_SENTRY_ENABLED=false  kill switch — nothing reports, ever
+ *   OMEGA_TEST_RUNNER           a test run never pollutes a live project
+ *   OMEGA_SENTRY_FORCE=true     report from a non-production run (local proving)
+ *   OMEGA_BUILD_MODE=true       the DEFAULT production signal, for hosts that
+ *                               have no runtime one
+ *
+ * The production signal is the host's to supply. @omega.js/desktop has no
+ * runtime answer — "should we ship telemetry" is a property of its BUILD, so it
+ * falls through to OMEGA_BUILD_MODE. @omega.js/backend does have one
+ * (`Manager.isProduction()`, env-derived and stable for the life of the
+ * process) and passes it in.
+ */
+
+/**
+ * Read the environment gates for core.resolveConfig().
+ * @param {object} [host] - the host's own signals
+ * @param {boolean} [host.isProduction] - overrides the OMEGA_BUILD_MODE default
+ * @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 }}
+ */
+function readGates(host) {
+  host = host || {};
+  const env = process.env;
+
+  let killedReason = null;
+  if (env.OMEGA_SENTRY_ENABLED === 'false') {
+    killedReason = 'OMEGA_SENTRY_ENABLED=false';
+  } else if (env.OMEGA_TEST_RUNNER) {
+    killedReason = 'test run (OMEGA_TEST_RUNNER)';
+  }
+
+  return {
+    killed:       !!killedReason,
+    killedReason,
+    isProduction: typeof host.isProduction === 'boolean'
+      ? host.isProduction
+      : env.OMEGA_BUILD_MODE === 'true',
+    allowInDev:   !!host.allowInDev || env.OMEGA_SENTRY_FORCE === 'true',
+  };
+}
+
+module.exports = { readGates };

package/dist/vendor/monitoring/index.js

@@ -0,0 +1,28 @@
+/**
+ * The @omega.js/monitoring entry — the Electron context-aware delegator (#380).
+ * Lifted from @omega.js/desktop's lib/sentry/index.js: a desktop Manager
+ * singleton requires this file from whichever process it is in, and every call
+ * forwards to the right per-context module.
+ *
+ * Detection:
+ *   - renderer: `process.type === 'renderer'` (electron's own signal)
+ *   - main:     anything else, including no `process.type` at all (running
+ *               outside electron, e.g. in tests)
+ *
+ * The preload module is a different lifecycle, so it is never auto-detected:
+ * reach it at `@omega.js/monitoring/preload`. The non-Electron entries are
+ * explicit too — `@omega.js/monitoring/node` for a server process,
+ * `@omega.js/monitoring/browser` for a web bundle (which must never `require`
+ * this file: it would pull the Electron SDK into a page bundle).
+ */
+
+function detectContext() {
+  if (typeof process !== 'undefined' && process.type === 'renderer') return 'renderer';
+  return 'main';
+}
+
+const impl = detectContext() === 'renderer'
+  ? require('./renderer.js')
+  : require('./main.js');
+
+module.exports = impl;

package/dist/vendor/monitoring/logger.js

@@ -0,0 +1,39 @@
+/**
+ * The monitoring package's log tag — the ONE identity tag every OMEGA surface
+ * prints: `[@omega.js/monitoring:<module>]` ([#12](https://github.com/Omega-JS-Stack/omega/issues/12)).
+ *
+ * The twin of @omega.js/analytics' createLogger, emitting this package's
+ * segment: no timestamp, because devtools, Cloud Logging and electron-log all
+ * stamp their own lines.
+ *
+ * CJS like the rest of the package: the backend and the electron main process
+ * require() it, the browser bundles import it with standard interop.
+ */
+
+// The package segment — this file IS @omega.js/monitoring, so it is a literal.
+const PACKAGE = '@omega.js/monitoring';
+
+/**
+ * Create a tagged console for one module, e.g. createLogger('core').
+ * @param {string} module - The module identity segment.
+ * @returns {object} A console-shaped logger whose calls carry the tag.
+ */
+function createLogger(module) {
+  const tag = `[${PACKAGE}:${module}]`;
+
+  // GETTERS returning a BOUND console method, not wrapper arrows: devtools
+  // attributes a line to the frame that called console, so a wrapper would make
+  // every line read as coming from this file. Resolution stays at ACCESS time,
+  // so a test (or a consumer) that swaps console[method] still sees its own stub.
+  const logger = { tag };
+  for (const method of ['log', 'info', 'warn', 'error', 'debug']) {
+    Object.defineProperty(logger, method, {
+      get: () => console[method].bind(console, tag),
+      enumerable: true,
+    });
+  }
+
+  return logger;
+}
+
+module.exports = { createLogger };

package/dist/vendor/monitoring/main.js

@@ -0,0 +1,99 @@
+/**
+ * main — the Electron main-process entry (#380). Lifted from
+ * @omega.js/desktop's lib/sentry/main.js, which proved the shape.
+ *
+ * Uncaught exceptions and unhandled rejections are captured BY THE SDK: an
+ * @sentry/electron/main init installs `onUncaughtExceptionIntegration` and
+ * node's `onUnhandledRejectionIntegration` by default. The host's own
+ * process handlers (@omega.js/desktop logs both to runtime.log) are additive —
+ * never a second capture.
+ *
+ * setUser / captureException / captureMessage exist for explicit reporting from
+ * seams the SDK can't see.
+ */
+
+const { resolveConfig, normalizeUser, releaseTag } = require('./core.js');
+const { readGates } = require('./env.js');
+const { createLogger } = require('./logger.js');
+
+const logger = createLogger('main');
+
+const main = {
+  _initialized: false,
+  _enabled:     false,
+  _options:     null,
+  _Sentry:      null,
+
+  /**
+   * @param {object} host - the desktop Manager: { config, getVersion() }
+   */
+  initialize(host) {
+    main._initialized = true;
+
+    const { shouldEnable, options, reason } = resolveConfig(host && host.config && host.config.monitoring, readGates());
+    main._options = options;
+
+    if (!shouldEnable) {
+      logger.log(`disabled — ${reason}`);
+      main._enabled = false;
+      return;
+    }
+
+    let Sentry;
+    try {
+      Sentry = require('@sentry/electron/main');
+    } catch (e) {
+      logger.warn(`@sentry/electron is not installed — reporting disabled. (${e.message})`);
+      main._enabled = false;
+      return;
+    }
+
+    // The one release format: the brand id from the resolved config, the app
+    // version from electron (main's `app.getVersion()` is authoritative).
+    const release = releaseTag({ id: host.config?.brand?.id, version: host.getVersion() });
+
+    Sentry.init({
+      dsn:              options.dsn,
+      environment:      options.environment,
+      release,
+      sampleRate:       options.sampleRate,
+      tracesSampleRate: options.tracesSampleRate,
+      attachScreenshot: options.attachScreenshot,
+    });
+
+    main._Sentry = Sentry;
+    main._enabled = true;
+    logger.log(`initialized — env=${options.environment} release=${release}`);
+  },
+
+  setUser(user) {
+    if (!main._enabled) return;
+    main._Sentry.setUser(normalizeUser(user, main._options));
+  },
+
+  captureException(error, extra) {
+    if (!main._enabled) {
+      logger.warn(`captureException (no-op, reporting disabled): ${error?.message || error}`);
+      return;
+    }
+    main._Sentry.captureException(error, extra ? { extra } : undefined);
+  },
+
+  captureMessage(message, level) {
+    if (!main._enabled) {
+      logger.log(`captureMessage (no-op, reporting disabled): ${message}`);
+      return;
+    }
+    main._Sentry.captureMessage(message, level);
+  },
+
+  // Used by tests to reset state between cases.
+  shutdown() {
+    main._initialized = false;
+    main._enabled     = false;
+    main._options     = null;
+    main._Sentry      = null;
+  },
+};
+
+module.exports = main;

package/dist/vendor/monitoring/preload.js

@@ -0,0 +1,45 @@
+/**
+ * preload — the Electron preload entry (#380). Lifted from
+ * @omega.js/desktop's lib/sentry/preload.js.
+ *
+ * Minimal on purpose: the renderer SDK takes over the moment the renderer
+ * initializes, and the preload scope is small and short-lived. No SDK boots
+ * here — this is only a surface the preload script can call to report a setup
+ * error thrown before the renderer loads.
+ */
+
+const { resolveConfig } = require('./core.js');
+const { readGates } = require('./env.js');
+const { createLogger } = require('./logger.js');
+
+const logger = createLogger('preload');
+
+const preload = {
+  _enabled: false,
+
+  /**
+   * @param {object} host - the desktop Manager: { config }
+   */
+  initialize(host) {
+    const { shouldEnable, reason } = resolveConfig(host && host.config && host.config.monitoring, readGates());
+    preload._enabled = shouldEnable;
+    if (!shouldEnable) logger.log(`disabled — ${reason}`);
+  },
+
+  // Forward to the renderer SDK when it exists in this context (it does, once
+  // the renderer module has initialized). Otherwise a no-op — preload is short-lived.
+  captureException(error) {
+    if (!preload._enabled) return;
+    try {
+      const Sentry = require('@sentry/electron/renderer');
+      Sentry.captureException(error);
+    } catch (e) { /* the SDK is not available in this context */ }
+  },
+
+  // Used by tests to reset state between cases.
+  shutdown() {
+    preload._enabled = false;
+  },
+};
+
+module.exports = preload;

package/dist/vendor/monitoring/renderer.js

@@ -0,0 +1,87 @@
+/**
+ * renderer — the Electron renderer entry (#380). Lifted from
+ * @omega.js/desktop's lib/sentry/renderer.js.
+ *
+ * Window `error` and `unhandledrejection` events are captured by the SDK
+ * itself. No bundle filter runs here: a desktop renderer loads OUR pages only,
+ * so every script in it is framework or brand code — the client-side filter is
+ * for the open web, where the page shares a global with anything.
+ */
+
+const { resolveConfig, normalizeUser, releaseTag } = require('./core.js');
+const { readGates } = require('./env.js');
+const { createLogger } = require('./logger.js');
+
+const logger = createLogger('renderer');
+
+const renderer = {
+  _initialized: false,
+  _enabled:     false,
+  _options:     null,
+  _Sentry:      null,
+
+  /**
+   * @param {object} host - the desktop Manager: { config, getVersion() }
+   */
+  initialize(host) {
+    renderer._initialized = true;
+
+    const { shouldEnable, options, reason } = resolveConfig(host && host.config && host.config.monitoring, readGates());
+    renderer._options = options;
+
+    if (!shouldEnable) {
+      logger.log(`disabled — ${reason}`);
+      renderer._enabled = false;
+      return;
+    }
+
+    let Sentry;
+    try {
+      Sentry = require('@sentry/electron/renderer');
+    } catch (e) {
+      logger.warn(`@sentry/electron is not installed — reporting disabled. (${e.message})`);
+      renderer._enabled = false;
+      return;
+    }
+
+    // Same tag main builds — one release, both processes.
+    const release = releaseTag({ id: host.config?.brand?.id, version: host.getVersion() });
+
+    Sentry.init({
+      dsn:              options.dsn,
+      environment:      options.environment,
+      release,
+      sampleRate:       options.sampleRate,
+      tracesSampleRate: options.tracesSampleRate,
+    });
+
+    renderer._Sentry = Sentry;
+    renderer._enabled = true;
+    logger.log(`initialized — env=${options.environment} release=${release}`);
+  },
+
+  setUser(user) {
+    if (!renderer._enabled) return;
+    renderer._Sentry.setUser(normalizeUser(user, renderer._options));
+  },
+
+  captureException(error, extra) {
+    if (!renderer._enabled) return;
+    renderer._Sentry.captureException(error, extra ? { extra } : undefined);
+  },
+
+  captureMessage(message, level) {
+    if (!renderer._enabled) return;
+    renderer._Sentry.captureMessage(message, level);
+  },
+
+  // Used by tests to reset state between cases.
+  shutdown() {
+    renderer._initialized = false;
+    renderer._enabled     = false;
+    renderer._options     = null;
+    renderer._Sentry      = null;
+  },
+};
+
+module.exports = renderer;

package/docs/analytics.md

@@ -0,0 +1,140 @@
+# Analytics
+
+GA4 Measurement Protocol with cross-platform identity. The same human gets unified events across desktop (@omega.js/desktop), web (UJM/@omega.js/client), and backend (@omega.js/backend) — provided all four reference the same Firebase project ID.
+
+## How identity works
+
+Every event ships with two GA4 fields:
+
+- **`client_id`** — uniquely identifies a *desktop install*. Stable per-install, anonymous.
+- **`user_id`** — uniquely identifies a *human*. Set when the user is signed in via Firebase Auth. It rides **alongside** the `client_id`, never in place of it: GA stitches sessions by the client id.
+
+@omega.js/desktop derives both via `uuidv5(input, namespace)` where:
+
+- `namespace = uuidv5(cloud.config.projectId, uuidv5.URL)` — same projectId in @omega.js/backend/UJM/@omega.js/client → same namespace everywhere.
+- `client_id = uuidv5(deviceId, namespace)` — the `deviceId` comes from the ONE shared derivation, `@omega.js/analytics`' `deriveDeviceId` ([#396](https://github.com/Omega-JS-Stack/omega/issues/396)), with desktop injecting its storage and its MAC seed ([context.md](context.md)).
+- `user_id = uuidv5(firebaseUid, namespace)` — set automatically when `omega.onAuthChange` fires with a uid; cleared on logout.
+
+Why this matters: the same Firebase user signing into the desktop app, the web app, and triggering backend events produces **identical `user_id` values** in every Measurement Protocol call. GA4 stitches the events into one user journey across all surfaces.
+
+What does NOT cross surfaces is the machine. The desktop app's deviceId lives in electron-store and a browser's lives in that browser's localStorage, so one machine is two `client_id`s — the human is the link, and always was.
+
+## Config
+
+```jsonc
+analytics: {
+  enabled: true,                                      // default true
+  providers: {
+    google: {
+      id: 'G-XXXXXXXXXX',                             // Measurement ID — REQUIRED
+    },
+  },
+}
+```
+
+The API secret is read from `process.env.GOOGLE_ANALYTICS_SECRET` — never committed. Mirrors @omega.js/backend's convention.
+
+### Local dev
+
+Add to `.env`:
+
+```bash
+GOOGLE_ANALYTICS_SECRET=your_secret_here
+```
+
+Mint the secret in GA4 Admin → Data Streams → your stream → **Measurement Protocol API secrets**.
+
+### Production builds
+
+The `bundle` task's esbuild `define` bakes `process.env.GOOGLE_ANALYTICS_SECRET` into the bundled main process at build time, so packaged apps don't need `.env` at runtime. The build runs with the secret set (CI does this via the GitHub Actions secret pushed by `mgr push-secrets`).
+
+## 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
+```
+
+Same surface in renderer:
+
+```js
+window.desktop.analytics.event('button_click', { button_id: 'cta' });
+window.desktop.analytics.pageview('/settings');
+window.desktop.analytics.setUserProperties({ plan: 'premium' });
+const status = await window.desktop.analytics.getStatus();   // { enabled, measurementId, clientId, userId, queueLength }
+```
+
+The renderer surface is fire-and-forget IPC (`ipcRenderer.send`) for events; only `getStatus` round-trips via `invoke`.
+
+## 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:
+
+```
+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 })
+  → main: analytics.event(name, params) → catalog → Measurement Protocol
+```
+
+The bridge is **injected, never sniffed**: the client reads that one config key and no global, so a page that merely carries a `window.desktop` can never route a brand's analytics into a void.
+
+Main owns identity end to end: the device id from electron-store, the session id minted once per launch, the real engagement time, and the app's `page_location` / `page_title` (a renderer's `file://` href is not GA's business). Only the canonical name and the caller's params cross.
+
+What does NOT cross the bridge:
+
+- **The fire's `options`** (`{ eventId, providers }`) — they exist to deduplicate a browser pixel against its server-side half, and GA4 through main is the one lane a desktop window has.
+- **The page data** the web path merges in (`page_path` / `page_title` / `page_location`) — main supplies the app's own.
+
+What the bridged client does NOT do: mint a `client_id` of its own (no `localStorage._omega_device_id` in a desktop renderer), hold an api_secret, or fire `login` / `logout` — main's auth bridge already fires those off the same Firebase user, and a second pair would double-count every sign-in.
+
+An uncatalogued event name never leaves the renderer: the catalog check runs before the forward, so a typo throws at the call site in development (and is logged-and-skipped in a packaged app) instead of surfacing as an unattributable warning in main's `runtime.log`. A forward that IPC cannot carry (a non-cloneable param) is warned about, never thrown at the user mid-action.
+
+> 🚫 **Never inject `GOOGLE_ANALYTICS_SECRET` into a renderer's config.** Desktop's config carries the measurement id alone. A renderer with its own secret would become a second Measurement Protocol sender with its own device id and its own session id — one install counted as two GA clients ([#396](https://github.com/Omega-JS-Stack/omega/issues/396) class). The client backs the rule with a guard: a bridged renderer drops any secret handed to it.
+
+## Auto-fired events
+
+| Event | When | Notes |
+|---|---|---|
+| `app_launch` | At end of `analytics.initialize()` (main process) | Fires once per launch |
+| `login` | On `omega.onAuthChange({uid: ...})` transition from null → uid | `params.method = providerId` |
+| `logout` | On `omega.onAuthChange({uid: null})` after a previous uid | — |
+
+## Queueing
+
+Calls before init complete are queued (up to 200 events). On init, the queue is drained. After init, calls send immediately.
+
+## Disabled paths
+
+`analytics._enabled = false` whenever:
+
+- `config.analytics.enabled === false`
+- No measurement ID configured
+- No `GOOGLE_ANALYTICS_SECRET` env var
+
+In all three cases, `event()` is a silent no-op (no throws, no warns past init).
+
+## Event names come from the catalog
+
+`event(name, params)` takes a CANONICAL name from `@omega.js/analytics`' shared
+catalog — the same vocabulary the web pages, the extension and the Cloud
+Functions speak ([docs/shared/analytics.md](../../../docs/shared/analytics.md)).
+The catalog's GA4 mapping decides the native name and payload; this module keeps
+only what is desktop's: the Measurement Protocol transport, the pre-init queue,
+the session/engagement enrichment, and the IPC bridge (unchanged — the preload
+API is byte-compatible).
+
+A name no catalog entry declares is a programmer error: it throws in development
+and is logged-and-skipped in a packaged app, where a throw would take the user's
+action with it. Adding an event is one catalog entry plus its test, never a
+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.
+- `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.