browser-extension-manager 1.4.0 → 1.5.0

package/README.md

@@ -61,8 +61,11 @@ BXM ships a built-in four-layer test framework. Write tests under `test/<layer>/
 npx bxm test                   # all layers
 npx bxm test --layer build     # build layer only (plain Node, fast)
 npx bxm test --layer boot      # real-Chromium end-to-end test
+npx bxm test --integration     # also run integration suites against REAL external services (Firebase, etc.)
 ```
 
+Tests run against the **real** harness — a real MV3 service worker, a real Chromium tab, the real packaged extension. **Never mock** (`chrome`, the Manager, contexts are all real); only pure, I/O-free functions are called directly. Real external APIs are gated behind `--integration` (skipped in-source otherwise, never mocked).
+
 Test files use Jest-compatible matchers:
 
 ```js

package/dist/background.js

@@ -513,7 +513,8 @@ class Manager {
 
   // Setup livereload
   setupLiveReload() {
-    // Quit if not in dev mode
+    // Dev-only feature — skip in testing and production (environment is one of
+    // 'development' | 'testing' | 'production').
     if (this.environment !== 'development') return;
 
     // Get port from config or use default

package/dist/build.js

@@ -91,13 +91,8 @@ Manager.actLikeProduction = function () {
 }
 Manager.prototype.actLikeProduction = Manager.actLikeProduction;
 
-// getEnvironment: returns the environment based on the build mode
-Manager.getEnvironment = function () {
-  return Manager.isBuildMode()
-    ? 'production'
-    : 'development';
-}
-Manager.prototype.getEnvironment = Manager.getEnvironment;
+// getEnvironment() is the SSOT and lives in src/utils/mode-helpers.js (alongside the is*()
+// family). It's mixed onto the Manager via the attachTo() call below, same as in EM/UJM.
 
 // getManifest: requires and parses config.yml
 Manager.getManifest = function () {

package/dist/commands/install.js

@@ -17,7 +17,7 @@ module.exports = async function (options) {
 
   try {
     // Install production
-    if (['prod', 'p', 'production'].includes(type)) {
+    if (['live', 'prod', 'p', 'production'].includes(type)) {
       // Log
       logger.log('Installing production...');
 

package/dist/defaults/CHANGELOG.md

@@ -0,0 +1,15 @@
+# CHANGELOG
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## Changelog Categories
+
+- `BREAKING` for breaking changes.
+- `Added` for new features.
+- `Changed` for changes in existing functionality.
+- `Deprecated` for soon-to-be removed features.
+- `Removed` for now removed features.
+- `Fixed` for any bug fixes.
+- `Security` in case of vulnerabilities.

package/dist/defaults/CLAUDE.md

@@ -1,15 +1,25 @@
 # ========== Default Values ==========
 # Browser Extension Manager (BXM) — consumer project
 
-> **Auto-managed file.** Everything between `# ========== Default Values ==========` and `# ========== Custom Values ==========` is owned by `browser-extension-manager` and rewritten on every `npx mgr setup`. Put your own project-specific notes BELOW the `Custom Values` marker — that section is preserved verbatim across setups.
-
 ## Framework
 
 This project consumes **Browser Extension Manager** (BXM) — a comprehensive framework for building modern cross-browser extensions (Chrome, Firefox, Edge, Opera, Brave). BXM provides one-line bootstrap per extension context, a component-based architecture (view + styles + script per context), a multi-browser build/release pipeline that produces store-uploadable zips, cross-context auth synchronization, and a built-in four-layer test framework.
 
-**Framework's own docs** (read these for deep-dives; both paths point to the same files, the absolute path works regardless of working directory):
-- Top-level overview: `/Users/ian/Developer/Repositories/ITW-Creative-Works/browser-extension-manager/CLAUDE.md` (or `node_modules/browser-extension-manager/CLAUDE.md`)
-- Subsystem references: `/Users/ian/Developer/Repositories/ITW-Creative-Works/browser-extension-manager/docs/` (or `node_modules/browser-extension-manager/docs/`)
+## 🚨 READ THE FRAMEWORK DOCS FIRST
+
+**Before doing ANY work on this codebase, Claude MUST read the framework documentation — that is where the architecture, conventions, APIs, and gotchas live. Skipping these will result in solutions that conflict with framework patterns.**
+
+**Required reading:**
+- **`node_modules/browser-extension-manager/CLAUDE.md`** — top-level overview + index
+- **`node_modules/browser-extension-manager/docs/`** — subsystem deep references (read the relevant ones for the task at hand)
+
+## 🚨 READ WEB-MANAGER TOO
+
+**BXM ships `web-manager` as a runtime singleton across every extension context** (background service worker, popup, options, sidepanel, content scripts) — it powers auth, Firebase, reactive `data-wm-bind` directives, analytics, error tracking, and utilities (`escapeHTML`, etc.). Any task that touches auth flows, Firestore reads/writes, subscription resolution, push notifications, or DOM bindings means you are working with web-manager as much as with BXM.
+
+**Required reading:**
+- **`node_modules/web-manager/CLAUDE.md`** — top-level overview + index
+- **`node_modules/web-manager/docs/`** — module deep references (Auth, Bindings, Firestore, Notifications, etc.)
 
 ## Quick start
 
@@ -18,8 +28,12 @@ npm start                   # dev with live reload (gulp → webpack → serve)
 npm run build               # production build → dist/ + packaged/<browser>/raw/ + .zip per browser
 BXM_IS_PUBLISH=true npm run build   # build + auto-upload to Chrome / Firefox / Edge stores
 npx mgr test                # run framework + project test suites
+npx mgr install dev         # use LOCAL browser-extension-manager source (to test framework edits)
+npx mgr install live        # restore the published browser-extension-manager from npm
 ```
 
+> Editing the BXM framework source while working here? Run `npx mgr install dev` so this project picks up your uncommitted framework changes (it otherwise uses its installed `node_modules/browser-extension-manager`). Run `npx mgr install live` to switch back.
+
 Load the unpacked extension in Chrome: point chrome://extensions → "Load unpacked" at `packaged/chromium/raw/`.
 
 ## Where things live
@@ -57,10 +71,12 @@ After `initialize()`, every Manager exposes:
 - `manager.logger` — timestamped per-context logger
 - `manager.webManager` — Web Manager singleton (Firebase, auth, analytics, reactive `data-wm-bind` directives)
 - `manager.messenger` — `chrome.runtime.onMessage` listener wired automatically
-- `manager.isDevelopment()` / `isProduction()` / `isTesting()` / `getVersion()` — cross-context helpers
+- `manager.isDevelopment()` / `isProduction()` / `isTesting()` / `getVersion()` — cross-context helpers. `getEnvironment()` returns `'development' | 'testing' | 'production'` (mutually exclusive; testing wins). Gate side effects on the intentional check (`isProduction()` for prod-only; `isDevelopment() || isTesting()` for local-or-test) — never `!isDevelopment()`.
 
 Auth UI is declarative — add `.auth-signin-btn` / `.auth-signout-btn` / `.auth-account-btn` to buttons; BXM wires them. Show/hide based on auth state via `data-wm-bind="@show auth.user"`.
 
+<!-- Everything above this marker is owned by the framework and rewritten on every `npx mgr setup`. Add your project-specific notes below — they are preserved across setups. -->
+
 # ========== Custom Values ==========
 
 ## Project-specific notes

package/dist/defaults/docs/README.md

@@ -0,0 +1,17 @@
+# Project docs
+
+Per-subsystem deep references live here. Keep `CLAUDE.md` short — it should read as a **table of contents** that points at files in this directory.
+
+## Pattern
+
+When you find yourself adding more than a paragraph to `CLAUDE.md`, create a new `docs/<topic>.md` instead and link to it from `CLAUDE.md`. Goal: the project's `CLAUDE.md` stays under ~250 lines.
+
+Examples of good `docs/*.md` topics:
+- Subsystem deep-dives (one per area of the codebase)
+- Architectural decisions / "why we built it this way"
+- Defaults tables, behavior matrices, edge cases
+- Setup walkthroughs that don't belong in `README.md`
+
+## See also
+
+The framework's own docs follow this same pattern — browse `node_modules/browser-extension-manager/docs/` for the canonical examples.

package/dist/defaults/test/README.md

@@ -0,0 +1,32 @@
+# Project tests
+
+Drop your project test suites here. The framework auto-runs them alongside its own when you run `npx mgr test`.
+
+## Layers
+
+Match the framework's four layers — Browser Extension Manager's test runner discovers files by the directory they sit in:
+
+| Directory | Runtime | Use for |
+|---|---|---|
+| `test/build/` | Plain Node | Build-time logic, manifest validation, pure utilities |
+| `test/background/` | MV3 service worker context | Background messaging, auth source-of-truth, alarms |
+| `test/view/` | Popup / options / sidepanel page | DOM, view-side controllers, `data-wm-bind` directives |
+| `test/boot/` | Consumer's actual built extension | End-to-end smoke tests (does the extension load, does the background register, do views render) |
+
+## Quick example
+
+```js
+// test/build/my-feature.test.js
+const assert = require('browser-extension-manager/test/assert');
+
+module.exports = {
+  'my feature does the thing': async () => {
+    const result = await doTheThing();
+    assert.equal(result, 'expected');
+  },
+};
+```
+
+## See also
+
+`node_modules/browser-extension-manager/docs/test-framework.md` — full reference for the test framework (layers, assert API, fixtures, runner internals).

package/dist/defaults/test/_init.js

@@ -0,0 +1,10 @@
+/**
+ * Test lifecycle hook for this project. Runs once before any suite (not a test itself).
+ * See browser-extension-manager/docs/test-framework.md → "test/_init.js".
+ */
+
+module.exports = ({ projectRoot }) => ({
+  // Seed any fixture a suite needs before it runs.
+  async setup() {
+  },
+});

package/dist/test/runner.js

@@ -49,6 +49,10 @@ async function run(options = {}) {
   console.log('');
   console.log(chalk.bold('  Browser Extension Manager Tests'));
 
+  // Run the optional test/_init.js setup() hooks (framework + consumer) ONCE,
+  // before any suite. There is no cleanup hook — tests clean up after themselves.
+  await runInitSetups();
+
   const results = { passed: 0, failed: 0, skipped: 0, tests: [] };
 
   if (sources.framework.length > 0) {
@@ -404,4 +408,62 @@ function relativizePath(file, source) {
   return path.relative(path.join(process.cwd(), 'test'), file);
 }
 
+// ---------------------------------------------------------------------------
+// test/_init.js — pre-test lifecycle hook (setup only)
+//
+// Mirrors the backend framework's hook so all four frameworks share one shape.
+// A project may add `<cwd>/test/_init.js` exporting a FUNCTION —
+// `module.exports = (ctx) => ({ setup })` — called with `{ projectRoot }` and
+// returning an object with an async `setup({ projectRoot })` that runs ONCE
+// before any suite (e.g. to scaffold a fixture file the boot layer needs).
+// There is no `cleanup` hook: tests clean up after themselves. Unlike the
+// backend framework, there is no `accounts` field here — these frameworks have
+// no auth/user system.
+// ---------------------------------------------------------------------------
+
+function loadInit(testDir, label) {
+  const initPath = path.join(testDir, '_init.js');
+
+  if (!jetpack.exists(initPath)) {
+    return {};
+  }
+
+  try {
+    const fn = require(initPath);
+
+    if (typeof fn !== 'function') {
+      console.log(chalk.red(`  ✗ ${label} test/_init.js must export a function: module.exports = (ctx) => ({ ... })`));
+      return {};
+    }
+
+    const mod = fn({ projectRoot: process.cwd() });
+    return mod && typeof mod === 'object' ? mod : {};
+  } catch (e) {
+    console.log(chalk.red(`  ✗ Failed to load ${label} test/_init.js: ${e.message}`));
+    return {};
+  }
+}
+
+async function runInitSetups() {
+  const frameworkTestsDir = path.resolve(__dirname, '../../test');
+  const projectTestsDir = path.join(process.cwd(), 'test');
+
+  const hooks = [
+    loadInit(frameworkTestsDir, 'framework'),
+    loadInit(projectTestsDir, 'project'),
+  ];
+
+  const setups = hooks.filter((h) => typeof h.setup === 'function').map((h) => h.setup);
+
+  for (const setup of setups) {
+    process.stdout.write(chalk.gray('  Running test/_init.js setup... '));
+    try {
+      await setup({ projectRoot: process.cwd() });
+      console.log(chalk.green('✓'));
+    } catch (e) {
+      console.log(chalk.red(`✗ (${e.message})`));
+    }
+  }
+}
+
 module.exports = { run, SkipError };

package/dist/test/suites/build/manager.test.js

@@ -111,29 +111,51 @@ module.exports = {
       },
     },
     {
-      name: 'getEnvironment returns "development" when BXM_BUILD_MODE !== "true"',
+      name: 'getEnvironment returns "testing" when BXM_TEST_MODE === "true" (takes precedence)',
+      run: (ctx) => {
+        const Manager = require(path.join(__dirname, '..', '..', '..', 'build.js'));
+        const origTest = process.env.BXM_TEST_MODE;
+        const origBuild = process.env.BXM_BUILD_MODE;
+        process.env.BXM_TEST_MODE = 'true';
+        process.env.BXM_BUILD_MODE = 'true'; // even with build mode set, testing wins
+        try {
+          ctx.expect(Manager.getEnvironment()).toBe('testing');
+        } finally {
+          if (origTest === undefined) delete process.env.BXM_TEST_MODE; else process.env.BXM_TEST_MODE = origTest;
+          if (origBuild === undefined) delete process.env.BXM_BUILD_MODE; else process.env.BXM_BUILD_MODE = origBuild;
+        }
+      },
+    },
+    {
+      name: 'getEnvironment returns "development" when BXM_BUILD_MODE !== "true" (and not testing)',
       run: (ctx) => {
         const Manager = require(path.join(__dirname, '..', '..', '..', 'build.js'));
         const original = process.env.BXM_BUILD_MODE;
+        const origTest = process.env.BXM_TEST_MODE;
         delete process.env.BXM_BUILD_MODE;
+        delete process.env.BXM_TEST_MODE;
         try {
           ctx.expect(Manager.getEnvironment()).toBe('development');
         } finally {
           if (original !== undefined) process.env.BXM_BUILD_MODE = original;
+          if (origTest !== undefined) process.env.BXM_TEST_MODE = origTest;
         }
       },
     },
     {
-      name: 'getEnvironment returns "production" when BXM_BUILD_MODE === "true"',
+      name: 'getEnvironment returns "production" when BXM_BUILD_MODE === "true" (and not testing)',
       run: (ctx) => {
         const Manager = require(path.join(__dirname, '..', '..', '..', 'build.js'));
         const original = process.env.BXM_BUILD_MODE;
+        const origTest = process.env.BXM_TEST_MODE;
+        delete process.env.BXM_TEST_MODE;
         process.env.BXM_BUILD_MODE = 'true';
         try {
           ctx.expect(Manager.getEnvironment()).toBe('production');
         } finally {
           if (original === undefined) delete process.env.BXM_BUILD_MODE;
           else                        process.env.BXM_BUILD_MODE = original;
+          if (origTest !== undefined) process.env.BXM_TEST_MODE = origTest;
         }
       },
     },

package/dist/test/suites/build/mode-helpers.test.js

@@ -29,9 +29,10 @@ module.exports = {
   description: 'utils/mode-helpers — cross-context isDevelopment/isTesting/getVersion',
   tests: [
     {
-      name: 'exports { attachTo, isDevelopment, isProduction, isTesting, getVersion }',
+      name: 'exports { attachTo, getEnvironment, isDevelopment, isProduction, isTesting, getVersion }',
       run: (ctx) => {
         ctx.expect(typeof helpers.attachTo).toBe('function');
+        ctx.expect(typeof helpers.getEnvironment).toBe('function');
         ctx.expect(typeof helpers.isDevelopment).toBe('function');
         ctx.expect(typeof helpers.isProduction).toBe('function');
         ctx.expect(typeof helpers.isTesting).toBe('function');
@@ -50,18 +51,29 @@ module.exports = {
       },
     },
     {
-      name: 'isDevelopment() is true under NODE_ENV=development',
+      name: 'isDevelopment() is true under NODE_ENV=development (and not testing)',
       run: (ctx) => {
-        withEnv({ NODE_ENV: 'development', BXM_BUILD_MODE: null }, () => {
+        withEnv({ NODE_ENV: 'development', BXM_BUILD_MODE: null, BXM_TEST_MODE: null }, () => {
           ctx.expect(helpers.isDevelopment()).toBe(true);
         });
       },
     },
     {
-      name: 'isDevelopment() is false when BXM_BUILD_MODE=true',
+      name: 'isDevelopment() is false / isProduction() true when BXM_BUILD_MODE=true (and not testing)',
       run: (ctx) => {
-        withEnv({ NODE_ENV: null, BXM_BUILD_MODE: 'true' }, () => {
+        withEnv({ NODE_ENV: null, BXM_BUILD_MODE: 'true', BXM_TEST_MODE: null }, () => {
           ctx.expect(helpers.isDevelopment()).toBe(false);
+          ctx.expect(helpers.isProduction()).toBe(true);
+        });
+      },
+    },
+    {
+      name: 'testing takes precedence — is* are mutually exclusive (exactly one true)',
+      run: (ctx) => {
+        withEnv({ BXM_TEST_MODE: 'true', BXM_BUILD_MODE: 'true' }, () => {
+          ctx.expect(helpers.isTesting()).toBe(true);
+          ctx.expect(helpers.isDevelopment()).toBe(false);
+          ctx.expect(helpers.isProduction()).toBe(false);
         });
       },
     },
@@ -70,6 +82,8 @@ module.exports = {
       run: (ctx) => {
         function FakeManager() {}
         helpers.attachTo(FakeManager);
+        ctx.expect(typeof FakeManager.getEnvironment).toBe('function');
+        ctx.expect(typeof FakeManager.prototype.getEnvironment).toBe('function');
         ctx.expect(typeof FakeManager.isDevelopment).toBe('function');
         ctx.expect(typeof FakeManager.prototype.isDevelopment).toBe('function');
         ctx.expect(typeof FakeManager.isTesting).toBe('function');
@@ -77,6 +91,31 @@ module.exports = {
         ctx.expect(typeof FakeManager.getVersion).toBe('function');
       },
     },
+    {
+      // The core invariant of the SSOT refactor: is*() DERIVE from getEnvironment(), so they
+      // can NEVER disagree with it, and exactly one is always true. (In build-time Node `chrome`
+      // is undefined, so getEnvironment() resolves via the env-var fallback.)
+      name: 'invariant: is*() exactly matches getEnvironment() + mutually exclusive (every scenario)',
+      run: (ctx) => {
+        const scenarios = [
+          { env: { BXM_TEST_MODE: 'true', BXM_BUILD_MODE: 'true', NODE_ENV: null }, expect: 'testing' },
+          { env: { BXM_TEST_MODE: null, BXM_BUILD_MODE: 'true', NODE_ENV: null },    expect: 'production' },
+          { env: { BXM_TEST_MODE: null, BXM_BUILD_MODE: null, NODE_ENV: 'development' }, expect: 'development' },
+          { env: { BXM_TEST_MODE: null, BXM_BUILD_MODE: null, NODE_ENV: null },       expect: 'development' }, // BXM defaults dev (unpacked)
+        ];
+        for (const s of scenarios) {
+          withEnv(s.env, () => {
+            const e = helpers.getEnvironment();
+            ctx.expect(e).toBe(s.expect);
+            ctx.expect(helpers.isDevelopment()).toBe(e === 'development');
+            ctx.expect(helpers.isTesting()).toBe(e === 'testing');
+            ctx.expect(helpers.isProduction()).toBe(e === 'production');
+            const trueCount = [helpers.isDevelopment(), helpers.isTesting(), helpers.isProduction()].filter(Boolean).length;
+            ctx.expect(trueCount).toBe(1);
+          });
+        }
+      },
+    },
     {
       name: 'getVersion() reads cwd package.json#version in Node context',
       run: (ctx) => {

package/dist/utils/mode-helpers.js

@@ -1,54 +1,75 @@
-// Runtime mode helpers (BEM/EM-pattern), shared across BXM's eight context Managers
+// Runtime mode helpers (BEM/EM/UJM-pattern), shared across BXM's eight context Managers
 // (build / background / popup / options / content / sidepanel / page / offscreen).
 //
-// Three orthogonal concepts:
-//   isDevelopment() — true when running unpacked from disk (an unpacked extension
-//                     loaded via chrome://extensions or a dev build of the framework).
-//                     Browser detection uses `chrome.runtime.getManifest().update_url`
-//                     — packed extensions from the Web Store have one, unpacked ones
-//                     do not. Falls back to NODE_ENV in Node contexts.
-//   isProduction()  — inverse. Running from a packed .crx / store-installed extension.
-//   isTesting()     — true when BXM's test framework is running this process. Set by
-//                     BXM's test runners (BXM_TEST_MODE=true) and consumer test setups
-//                     that want the same signal.
+// `getEnvironment()` is the SINGLE SOURCE OF TRUTH: it is the ONLY function that reads the
+// raw signals (BXM_TEST_MODE / manifest.update_url / BXM_BUILD_MODE / NODE_ENV /
+// config.bxm.environment) and resolves them to exactly ONE of three mutually-exclusive
+// values. The three is*() checks DERIVE from it — they never read raw signals themselves,
+// so they can never disagree with getEnvironment().
 //
-// Use these whenever behavior should differ by *what kind of process* you're in —
-// shorter timeouts in tests, DevTools menu items only in dev, prompts suppressed in
-// tests. Don't use them for "should we hit dev or prod backends" — that's a config
-// concern; use `getEnvironment()` for that (in build.js).
+//   isDevelopment() — `getEnvironment() === 'development'`: running unpacked from disk (an
+//                     unpacked extension via chrome://extensions or a dev build), and NOT
+//                     testing.
+//   isTesting()     — `getEnvironment() === 'testing'`: BXM's test framework is running this
+//                     process (BXM_TEST_MODE=true). TAKES PRECEDENCE — a test run is not dev.
+//   isProduction()  — `getEnvironment() === 'production'`: running from a packed .crx /
+//                     store-installed extension, and NOT testing. A real positive check —
+//                     NOT `!isDevelopment()`.
 //
-// Context caveat: in build-time Node (gulp / CLI), `chrome` is undefined. We detect
-// via `typeof chrome` so the same code works in every context. In test mode the
-// browser-side check is short-circuited via BXM_TEST_MODE so `isDevelopment()`
-// returns a stable value regardless of which test layer is running.
+// To gate "anything non-production" use `!isProduction()` or `isDevelopment() ||
+// isTesting()` intentionally — never assume two values.
+//
+// Context caveat: in build-time Node (gulp / CLI), `chrome` is undefined. getEnvironment()
+// detects via `typeof chrome` so the same code works in every context. Browser detection
+// uses `chrome.runtime.getManifest().update_url` — packed store extensions have one,
+// unpacked ones do not.
 
-function isDevelopment() {
-  // Browser-side: rely on `update_url` being absent for unpacked extensions.
-  // (Store-installed extensions have `update_url` set to clients2.google.com / similar.)
+// getEnvironment() — the SINGLE SOURCE OF TRUTH. Reads every raw signal and resolves to
+// exactly ONE of 'development' | 'testing' | 'production' (mutually exclusive; testing wins).
+// Precedence: testing → production → development.
+function getEnvironment() {
+  // 1. Testing wins — set by BXM's test runners / harness, or a testing-baked build.
+  //    Works in Node (process.env), extension contexts (globalThis set before consumer JS),
+  //    and config-baked builds (config.bxm.environment === 'testing').
+  if (typeof process !== 'undefined' && process.env && process.env.BXM_TEST_MODE === 'true') return 'testing';
+  if (typeof globalThis !== 'undefined' && globalThis.BXM_TEST_MODE === true) return 'testing';
+  if (this && this.config && this.config.bxm && this.config.bxm.environment === 'testing') return 'testing';
+
+  // 2. Browser-side: packed/store extensions have `update_url`; unpacked ones do not.
+  //    This is the authoritative runtime signal in an extension context.
   if (typeof chrome !== 'undefined' && chrome.runtime && typeof chrome.runtime.getManifest === 'function') {
     try {
-      const manifest = chrome.runtime.getManifest();
-      return !manifest.update_url;
-    } catch (_) { /* fall through */ }
+      return chrome.runtime.getManifest().update_url ? 'production' : 'development';
+    } catch (_) { /* fall through to Node/config signals */ }
   }
-  // Node / build-time fallback.
-  if (process.env.NODE_ENV === 'development') return true;
-  if (process.env.BXM_BUILD_MODE === 'true') return false;
-  if (this && this.config && this.config.bxm && this.config.bxm.environment === 'development') return true;
-  return false;
+
+  // 3. Node / build-time + config signals.
+  if (process.env.BXM_BUILD_MODE === 'true') return 'production';
+  if (process.env.NODE_ENV === 'development') return 'development';
+  if (this && this.config && this.config.bxm && this.config.bxm.environment === 'development') return 'development';
+  if (this && this.config && this.config.bxm && this.config.bxm.environment === 'production') return 'production';
+
+  // 4. Default: development. BXM's deployed artifacts ALWAYS carry their signal — a packed /
+  //    store extension has `manifest.update_url`, and build-time Node sets BXM_BUILD_MODE. So
+  //    reaching here means a bare tooling / unpacked context, where development is the sensible
+  //    answer. (Contrast BEM/EM, whose deployed RUNTIME can legitimately lack a signal, so they
+  //    default to production.)
+  return 'development';
+}
+
+// The three checks DERIVE from getEnvironment() — they never read raw signals, so they can
+// never disagree with it. isDevelopment() is NOT true in testing; isProduction() is a real
+// positive check (never `!isDevelopment()`).
+function isDevelopment() {
+  return getEnvironment.call(this) === 'development';
 }
 
 function isProduction() {
-  return !this.isDevelopment();
+  return getEnvironment.call(this) === 'production';
 }
 
 function isTesting() {
-  // Canonical signal — set by BXM's test runners and consumer test setups alike.
-  // Works in Node (process.env) AND in extension contexts (the harness extension
-  // sets globalThis.BXM_TEST_MODE before any consumer code runs).
-  if (typeof process !== 'undefined' && process.env && process.env.BXM_TEST_MODE === 'true') return true;
-  if (typeof globalThis !== 'undefined' && globalThis.BXM_TEST_MODE === true) return true;
-  return false;
+  return getEnvironment.call(this) === 'testing';
 }
 
 // `getVersion()` — returns the extension's version string.
@@ -71,20 +92,24 @@ function getVersion() {
 }
 
 // Mix the helpers into a Manager constructor's prototype + the constructor itself
-// (so `Manager.isTesting()` works statically too, matching BEM/EM pattern).
+// (so `Manager.isTesting()` works statically too, matching BEM/EM/UJM pattern).
+// getEnvironment() is the SSOT and is attached here too — build.js no longer defines it.
 function attachTo(Manager) {
-  Manager.prototype.isDevelopment = isDevelopment;
-  Manager.prototype.isProduction  = isProduction;
-  Manager.prototype.isTesting     = isTesting;
-  Manager.prototype.getVersion    = getVersion;
-  Manager.isDevelopment = isDevelopment;
-  Manager.isProduction  = isProduction;
-  Manager.isTesting     = isTesting;
-  Manager.getVersion    = getVersion;
+  Manager.prototype.getEnvironment = getEnvironment;
+  Manager.prototype.isDevelopment  = isDevelopment;
+  Manager.prototype.isProduction   = isProduction;
+  Manager.prototype.isTesting      = isTesting;
+  Manager.prototype.getVersion     = getVersion;
+  Manager.getEnvironment = getEnvironment;
+  Manager.isDevelopment  = isDevelopment;
+  Manager.isProduction   = isProduction;
+  Manager.isTesting      = isTesting;
+  Manager.getVersion     = getVersion;
 }
 
 module.exports = {
   attachTo,
+  getEnvironment,
   isDevelopment,
   isProduction,
   isTesting,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-extension-manager",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Browser Extension Manager dependency manager",
   "main": "dist/index.js",
   "exports": {