browser-extension-manager 1.6.1 → 1.7.0

package/docs/build-system.md

@@ -0,0 +1,131 @@
+# Build System
+
+BXM uses **gulp + webpack + sass + custom HTML templating + an electron-builder-style packaging step** to compile extension source into a Chrome-loadable, multi-browser-ready build.
+
+## Pipeline overview
+
+`src/` (consumer authored) → `dist/` (intermediate) → `packaged/<browser>/raw/` (Chrome-loadable) → `packaged/<browser>/<name>.zip` (store upload).
+
+```
+src/
+├── manifest.json                            # JSON5 source — comments, single quotes OK
+├── views/<component>/index.html             # HTML templates
+├── _locales/en/messages.json                # i18n catalog source
+├── assets/
+│   ├── js/components/<component>/index.js   # entry points (webpack bundles these)
+│   ├── css/main.scss + components/          # SCSS
+│   └── images/icon.png                      # source icon (1024×1024)
+└── ...
+        ↓ gulp build (BXM_BUILD_MODE=true)
+dist/
+├── manifest.json                            # still JSON5 — used by serve, not Chrome
+├── views/<component>/index.html             # templated
+├── assets/
+│   ├── js/components/<component>.bundle.js  # webpack output
+│   ├── css/components/<component>.bundle.css # sass output
+│   └── images/                              # icons (multiple sizes)
+└── _locales/<lang>/messages.json            # auto-translated (see docs/translations.md)
+        ↓ packaging step
+packaged/
+├── chromium/
+│   ├── raw/                                 # strict-JSON manifest, Chrome-loadable
+│   │   ├── manifest.json                    # comments stripped, valid JSON
+│   │   └── ...                              # everything from dist/
+│   └── <ExtensionName>.zip                  # store upload
+├── firefox/raw/ + .zip
+└── opera/raw/ + .zip
+```
+
+## Gulp tasks
+
+Auto-loaded from [src/gulp/tasks/](../src/gulp/tasks/) via [src/gulp/main.js](../src/gulp/main.js).
+
+| Task | Source | Purpose |
+|---|---|---|
+| `defaults` | [tasks/defaults.js](../src/gulp/tasks/defaults.js) | Copy framework defaults from `dist/defaults/` to consumer project on first run / setup. See [defaults.md](defaults.md). |
+| `distribute` | [tasks/distribute.js](../src/gulp/tasks/distribute.js) | Copy consumer's `src/` files (HTML, manifest, locales, etc.) to `dist/` |
+| `sass` | [tasks/sass.js](../src/gulp/tasks/sass.js) | Compile SCSS → CSS bundles with the load-path system (see [css.md](css.md)) |
+| `webpack` | [tasks/webpack.js](../src/gulp/tasks/webpack.js) | Bundle JS per component entry point with Babel transpilation |
+| `html` | [tasks/html.js](../src/gulp/tasks/html.js) | Run views through the two-step templating system (see [templating.md](templating.md)) |
+| `icons` | [tasks/icons.js](../src/gulp/tasks/icons.js) | Generate icon variants from `src/assets/images/icon.png` |
+| `translate` | [tasks/translate.js](../src/gulp/tasks/translate.js) | Auto-translate `_locales/en/messages.json` to 16 languages via Claude CLI (see [translations.md](translations.md)) |
+| `package` | [tasks/package.js](../src/gulp/tasks/package.js) | Bundle dist/ into packaged/<browser>/raw + zip; runs `build:pre` / `build:post` hooks ([hooks.md](hooks.md)) |
+| `serve` | [tasks/serve.js](../src/gulp/tasks/serve.js) | Dev server: WebSocket-based live reload, watches `src/` |
+| `audit` | [tasks/audit.js](../src/gulp/tasks/audit.js) | Build-pipeline-specific checks (icons exist, manifest is valid, etc.) |
+
+## Webpack
+
+[src/gulp/tasks/webpack.js](../src/gulp/tasks/webpack.js) discovers component entry points (`src/assets/js/components/<name>/index.js`) and bundles each to `dist/assets/js/components/<name>.bundle.js`.
+
+**Babel transpilation** — `@babel/preset-env` so the bundles work in older browsers. SW + content scripts have stricter constraints (no `eval`, no ES module syntax at top level in some configs).
+
+**Template replacement** — a webpack plugin replaces these markers in bundles at build time:
+- `%%% version %%%` → `package.json#version`
+- `%%% brand.name %%%` → config brand name
+- `%%% brand.url %%%` → config brand URL
+- `%%% environment %%%` → `'production'` or `'development'`
+- `%%% liveReloadPort %%%` → WebSocket port (35729 default)
+- `%%% webManagerConfiguration %%%` → JSON config blob
+
+**Strip-dev-blocks** — [src/gulp/plugins/webpack/strip-dev-blocks.js](../src/gulp/plugins/webpack/strip-dev-blocks.js) removes `/* dev */ ... /* /dev */` blocks from production bundles.
+
+**Custom aliases** — set via `resolve.alias` in webpack.js:
+```js
+resolve: {
+  alias: {
+    '__theme__': path.resolve(paths.root, 'assets/themes/<active-theme>'),
+  }
+}
+```
+
+## Sass
+
+[src/gulp/tasks/sass.js](../src/gulp/tasks/sass.js) compiles per-component SCSS bundles. Load-path resolution lets consumer SCSS `@use 'browser-extension-manager'`, `@use 'theme'`, and `@use 'components/popup'` resolve through a search chain. Full details in [css.md](css.md).
+
+## HTML templating
+
+Views in `src/views/<component>/index.html` go through two passes of `{{ }}` token replacement. See [templating.md](templating.md).
+
+## Packaging
+
+[tasks/package.js](../src/gulp/tasks/package.js):
+
+1. **Pre-hook** — runs `hooks/build:pre.js` if present
+2. **Per-browser manifest normalization** — converts JSON5 → strict JSON for Chrome/Edge/Opera (Firefox tolerates JSON5 but normalized anyway)
+3. **Per-browser asset copy** to `packaged/<browser>/raw/`
+4. **Zip** to `packaged/<browser>/<name>.zip`
+5. **Post-hook** — runs `hooks/build:post.js`
+6. **Auto-publish** (if `BXM_IS_PUBLISH=true`) — uploads to Chrome Web Store / Firefox Add-ons / Edge Add-ons stores. See [publishing.md](publishing.md).
+
+## Build modes
+
+Env vars that drive the pipeline:
+
+- `BXM_BUILD_MODE=true` — production build (minified, no sourcemaps, dev-blocks stripped)
+- `BXM_IS_PUBLISH=true` — also publish to extension stores after packaging
+- `BXM_LIVERELOAD_PORT=35729` — WebSocket port for `serve` task (override if 35729 collides)
+- `BXM_TEST_MODE=true` — running in BXM's test framework. Powers `Manager.isTesting()` (see [test-framework.md](test-framework.md)).
+- `BXM_LOG_FILE` — override the stdout/stderr tee path, or set to `false` to disable it (see [Log files](#log-files)).
+
+## Live reload
+
+`npm start` (= `gulp` with no args, by default invokes `serve`) watches `src/` and recompiles on change. A WebSocket server on `BXM_LIVERELOAD_PORT` (35729) notifies the extension's contexts. Background SW reloads itself via `chrome.runtime.reload()`; other contexts reload via `window.location.reload()`.
+
+## Log files
+
+The gulp pipeline tees all output to `logs/dev.log` (`npm start`) / `logs/build.log` (`npm run build`), and `npx mgr test` tees to `logs/test.log`. Full reference — file table, capture behavior, `BXM_LOG_FILE` controls: [logging.md](logging.md).
+
+## Output for Chrome's "Load unpacked"
+
+Point Chrome at `packaged/chromium/raw/` — that's the strict-JSON, fully-assembled Chrome-loadable build. NOT `dist/` (which has JSON5 manifest mid-pipeline). The test framework's boot layer auto-targets `packaged/chromium/raw/` for the same reason — see [test-boot-layer.md](test-boot-layer.md).
+
+## See also
+
+- [components.md](components.md) — the seven component contexts
+- [templating.md](templating.md) — `{{ }}` token replacement
+- [css.md](css.md) — SCSS load paths
+- [defaults.md](defaults.md) — `src/defaults/` template system
+- [hooks.md](hooks.md) — `build:pre` / `build:post`
+- [translations.md](translations.md) — auto-translate `_locales/`
+- [publishing.md](publishing.md) — store auto-publishing
+- [test-boot-layer.md](test-boot-layer.md) — verify the packaged extension actually boots in Chromium

package/docs/cdp-debugging.md

@@ -0,0 +1,45 @@
+# CDP Debugging (driving a live browser)
+
+How to launch a browser you can CONTROL — see the extension live, screenshot it, click, type, read console logs, inspect network requests — for agents (Claude via MCP/CDP) and humans. For BXM this is THE dev surface: the extension only exists inside a running Chrome.
+
+> Mirrored across the four sister frameworks (UJM / BEM / BXM / EM) — same core section, framework-flavored. Edit all four together.
+
+## Launching a controllable Chrome (the canonical command)
+
+```bash
+open -gna "Google Chrome" --args \
+  --remote-debugging-port=9223 \
+  --user-data-dir="$HOME/Library/Application Support/chrome-profiles/agent" \
+  --no-first-run --no-default-browser-check \
+  --disable-background-timer-throttling \
+  --disable-backgrounding-occluded-windows \
+  --disable-renderer-backgrounding
+```
+
+Verify it's up: `curl -s http://127.0.0.1:9223/json/version`
+
+The rules that make this work (each one learned the hard way):
+
+- **`open -gna` launches WITHOUT stealing focus.** `-g` = don't bring to foreground, `-n` = new instance (required — without it `open` just activates the already-running daily Chrome and the `--args` are ignored). Launching the Chrome binary directly ALWAYS activates the app and steals focus. Do NOT use `-j`/`--hide` — animations need a visible window; instead the three `--disable-*` flags keep timers/rAF/rendering at FULL speed while the window sits behind your work (verified: rAF at the display's native 120fps while backgrounded, focus never moved).
+- **`--user-data-dir` is REQUIRED, not optional.** Chrome 136+ **silently ignores** `--remote-debugging-port` on the default profile — no error, no port, nothing (verified on Chrome 149). This is the #1 "why isn't CDP up" trap.
+- **The profile dir IS the persistent state** — logins AND installed extensions. Cookies + localStorage survive relaunches (verified by round-trip), and so does an unpacked extension you've loaded (see below). Ecosystem convention: ONE shared profile at `~/Library/Application Support/chrome-profiles/agent` across all four frameworks, so setup is one-time.
+- **One Chrome instance per profile dir — but MANY agents per instance.** CDP is multi-client (verified: two concurrent clients driving different tabs of one instance): agents and sessions attach to the SAME port, each drives its own tab, and all share the profile's logins and extensions. One agent per tab is the only rule. A second launch with the same dir just opens a window in the existing instance and **ignores the new debug port** — attach to the running one instead. Reach for a second profile + port (`…/b` on 9224) only for a different IDENTITY (a different account = a different cookie jar) or hard isolation.
+- It runs **side-by-side with the daily Chrome** — a different `--user-data-dir` is a fully separate instance.
+- **Quit by profile match, never by app name**: `pkill -f "chrome-profiles/agent"`. (`osascript 'tell app "Google Chrome" to quit'` hits the daily browser too — same app name.)
+
+## Loading the extension (BXM specifics)
+
+- **`--load-extension` does NOT work on stable Chrome** — silently ignored (verified on Chrome 149; support was removed from branded Chrome around v137). Do not build tooling on it.
+- Instead, load it ONCE through the UI: in the agent-profile Chrome, open `chrome://extensions` → enable **Developer mode** → **Load unpacked** → select the build output. **The persistent profile keeps it installed across every relaunch** — reload it from `chrome://extensions` (or the ⟳ button) after rebuilds.
+- The extension's surfaces appear as CDP targets: the background service worker (`type: "service_worker"`, `chrome-extension://<id>/…`), the popup while it's open, and content scripts inside the page targets they're injected into.
+
+## Driving it
+
+| Client | Good for | Port handoff |
+|---|---|---|
+| `chrome-devtools` MCP | rich interaction — click, fill, type, screenshots, network requests, console messages, performance traces | `CHROME_CDP_PORT` env var, **expanded ONCE when the Claude session spawns its MCP — set it BEFORE launching `claude`** (mid-session changes do nothing) |
+| Any CDP client — including EM's `npx mgr cdp` run from any EM project | quick JS eval, per-renderer screenshots | per invocation: `EM_CDP_PORT=9223 npx mgr cdp eval "<url-substring>" 'document.title'` |
+
+Port conventions: **9222** = Electron apps (EM), **9223+** = Chrome instances.
+
+Navigating to a brand's UJM dev site? BrowserSync serves over HTTPS (self-signed cert). Prefer `https://localhost:4000`; fall back to the machine's local network IP (e.g. `https://192.168.x.x:4000`) if localhost doesn't connect. Port 4000 by default, increments to 4001+ when multiple sites run. Read the exact URL from `.temp/_config_browsersync.yml` at the root of the WEBSITE project (the UJM consumer — e.g. `<brand>-website/.temp/_config_browsersync.yml`, NOT this extension repo).

package/docs/cli.md

@@ -0,0 +1,70 @@
+# CLI
+
+`npx bxm <command>` — aliases `xm`, `ext`, `mgr`, `browser-extension-manager`.
+
+## Commands
+
+| Command | Aliases | Purpose |
+|---|---|---|
+| `setup` | `-s`, `--setup` | Scaffold a consumer project (copy `src/defaults/`, install peer deps, write projectScripts). Default when no command given. |
+| `clean` | `-c`, `--clean` | Remove `dist/`, `packaged/`, `.cache/`, `.temp/` |
+| `install` | `-i`, `i`, `--install` | Install peer deps (gulp, etc.) |
+| `test` | `-t`, `--test` | Run framework + project test suites. Positional target scopes by source + path (`project:` / `mgr:` / bare path); `--filter` matches test names; `--extended` enables real-external-API tests. See [test-framework.md](test-framework.md). |
+| `version` | `-v`, `--version` | Print BXM, Node, peer-dep versions |
+
+## Entry point
+
+[bin/browser-extension-manager](../bin/browser-extension-manager) — yargs-based shim that loads [src/cli.js](../src/cli.js).
+
+[src/cli.js](../src/cli.js) is the alias resolver: it maps short flags and positional args to a command module under [src/commands/](../src/commands/), then invokes it with the parsed options.
+
+## Adding a new command
+
+1. Create `src/commands/<name>.js` exporting `async function (options) { /* ... */ }`
+2. Add to `ALIASES` in [src/cli.js](../src/cli.js):
+   ```js
+   const ALIASES = {
+     clean:   ['-c', '--clean'],
+     setup:   ['-s', '--setup'],
+     <name>:  ['-x', '--<name>'],
+   };
+   ```
+3. Optionally add to `projectScripts` in [package.json](../package.json) so consumers get a wrapper npm script on `npx bxm setup`.
+4. Document under this page.
+
+## Command options
+
+Yargs parses `--foo bar` and `--foo=bar` into `options.foo`. Positional args go into `options._[]`. Each command reads what it needs:
+
+```js
+// src/commands/test.js
+module.exports = async function (options) {
+  const layer    = options.layer    || 'all';
+  const target   = (options._ && options._[1]) || null; // positional: `npx bxm test <target>`
+  const filter   = options.filter   || null;
+  const reporter = options.reporter || 'pretty';
+  // ...
+};
+```
+
+## Env var conventions
+
+Commands read BXM-prefixed env vars for behavior switches (one exception: `TEST_EXTENDED_MODE` is deliberately unprefixed — the SAME name across BEM/BXM/UJM/EM):
+
+| Env | Used by | Purpose |
+|---|---|---|
+| `BXM_BUILD_MODE=true` | gulp tasks | Production build mode |
+| `BXM_IS_PUBLISH=true` | gulp/package | Also publish to extension stores after packaging |
+| `BXM_LOG_FILE` | gulp + test runners | Override the stdout/stderr tee path, or `false` to disable (see [logging.md](logging.md)) |
+| `BXM_TEST_MODE=true` | test runners | Powers `Manager.isTesting()` (auto-set by `npx bxm test`) |
+| `TEST_EXTENDED_MODE=true` | test runners | Run tests that hit REAL external services (`--extended` is the CLI shorthand; see [test-framework.md](test-framework.md)) |
+| `BXM_TEST_BOOT_PROJECT` | test/boot | Override project root for boot tests |
+| `BXM_TEST_BOOT_DIR` | test/boot | Override extension dir directly |
+| `BXM_TEST_DEBUG=1` | test runners | Pipe Chromium stderr to console |
+| `BXM_LIVERELOAD_PORT` | gulp/serve | WebSocket port (default 35729) |
+
+## See also
+
+- [build-system.md](build-system.md) — `gulp` is what most CLI commands ultimately invoke
+- [test-framework.md](test-framework.md) — `npx bxm test` command surface
+- [defaults.md](defaults.md) — `npx bxm setup` invokes the defaults task

package/docs/common-mistakes.md

@@ -0,0 +1,10 @@
+# Common Mistakes to Avoid
+
+1. **Defining a local `escapeHTML` / `sanitizeURL` helper** — Use the canonical inline form `webManager.utilities().escapeHTML(value)` / `.sanitizeURL(url)` at every call site. Do NOT alias / destructure / `.bind()`. This is the most common XSS-introduction vector in BXM extensions.
+2. **Using raw `chrome.*` instead of `extension.*`** — Use the extension API wrapper for cross-browser compat (Chrome / Firefox / Edge).
+3. **Putting service-worker-incompatible code in `background`** — Service workers can't hold WebSockets or long-running state. Use the `offscreen` component for persistent work.
+4. **Trying to share Manager state across components** — Each component has its own Manager singleton. Use `extension.runtime.sendMessage` / `extension.storage` to communicate.
+5. **Writing `<html>`/`<head>`/`<body>` in component views** — Views are HTML fragments; BXM wraps them with `page-template.html` at build time.
+6. **Hand-editing `dist/manifest.json` or `dist/*` files** — Edit `config/manifest.json` (or component sources); BXM regenerates dist on every build.
+7. **Installing BXM's dependencies as direct consumer deps** — Consumer projects must NOT `npm install firebase`, `web-manager`, or any other BXM/web-manager transitive dep. BXM's webpack config includes `resolve.modules` pointing at the framework's own `node_modules/`. If a dependency isn't resolving, the fix is in BXM's webpack config — not the consumer's `package.json`. Mirrors EM and UJM.
+8. **Touching Firebase directly in consumer code** — Firebase is owned by web-manager. Consumer code NEVER does `import firebase from 'firebase/app'` or `require('firebase')`. Instead: `import webManager from 'web-manager'` → `webManager.auth()`, `webManager.firestore()`. Same rule in EM and UJM.

package/docs/components.md

@@ -0,0 +1,87 @@
+# Component Architecture
+
+Extensions are organized around **components**, each representing a distinct browser-extension context. Each component bundles a view, styles, and script.
+
+## The seven component contexts
+
+| Component | Runs in | When |
+|---|---|---|
+| `background` | MV3 service worker | Always — extension's source of truth, handles auth, messaging, lifecycle |
+| `popup` | Browser-action popup tab | When the user clicks the extension's toolbar button |
+| `options` | Standalone tab (or embedded settings page) | When the user opens extension settings |
+| `sidepanel` | Chrome side panel (Chrome 114+) | When the user opens the side panel |
+| `content` | Each web page the user visits | Injected by manifest `content_scripts` (or programmatically) |
+| `pages` | A custom extension page (e.g. dashboard, welcome) | Routed via `chrome.tabs.create({ url: chrome.runtime.getURL('views/pages/index.html') })` |
+| `offscreen` | Offscreen document (Chrome 109+) | Persistent SW-adjacent context for WebSocket, DOM parsing, long-running tasks |
+
+## Each component has three parts
+
+For a component named `<component>`:
+
+| Part | Source file | Compiled output |
+|---|---|---|
+| **View** (HTML) | `src/views/<component>/index.html` | `dist/views/<component>/index.html` |
+| **Styles** (SCSS) | `src/assets/css/components/<component>/index.scss` | `dist/assets/css/components/<component>.bundle.css` |
+| **Script** (JS) | `src/assets/js/components/<component>/index.js` | `dist/assets/js/components/<component>.bundle.js` |
+
+The build pipeline wires these together — `views/<component>/index.html` automatically references its matching `.bundle.css` and `.bundle.js`.
+
+## Manifest wiring per component
+
+`src/manifest.json` (JSON5, merged with BXM's default manifest at build — see [build-system.md](build-system.md)) registers each component with the browser:
+
+| Component | Manifest field |
+|---|---|
+| `popup` | `action.default_popup: 'views/popup/index.html'` |
+| `options` | `options_ui.page: 'views/options/index.html'` |
+| `sidepanel` | `side_panel.default_path: 'views/sidepanel/index.html'` |
+| `background` | `background.service_worker: 'assets/js/components/background.bundle.js'` |
+| `content` | `content_scripts` (match patterns + the content bundle) |
+| `offscreen` | created programmatically — requires the `offscreen` permission (see [offscreen.md](offscreen.md)) |
+| `pages` | none — opened via `extension.tabs.create({ url: extension.runtime.getURL('views/pages/index.html') })` |
+
+## Manager-per-context
+
+Each component context gets its own Manager class with a one-line bootstrap. See [managers.md](managers.md) for the full list and import paths.
+
+## Boot order across contexts
+
+There is no global "boot order" — each context boots independently when the browser instantiates it. BUT they coordinate via messaging:
+
+1. **Background SW** boots first when the extension is installed/reloaded — it's the source of truth.
+2. **Popup / options / sidepanel / pages** boot lazily when the user opens them. On boot they `bxm:syncAuth` to background to align with the canonical auth state.
+3. **Content scripts** boot per-page-load (or per-tab navigation, depending on `run_at`).
+4. **Offscreen** is created on demand by background (e.g. when it needs DOM parsing or a long-lived WebSocket).
+
+See [auth.md](auth.md) for the detailed sign-in / sign-out / context-load flows.
+
+## Adding a new component type to the framework
+
+This is rare — only needed if you're adding a brand new context kind to BXM (e.g. devtools panel). For most consumer needs, "add a new page" means creating a new entry under `src/views/pages/<name>/` (one component, many pages).
+
+If you DO need to add a new top-level component type:
+
+1. **Framework styles** — `src/assets/css/components/<component>/index.scss`
+2. **Default template files** copied into consumer projects:
+   - `src/defaults/src/assets/css/components/<component>/index.scss`
+   - `src/defaults/src/assets/js/components/<component>/index.js`
+   - `src/defaults/src/views/<component>/index.html`
+3. **Manager class** if the new context needs its own bootstrap surface — `src/<component>.js` (mirror `src/popup.js` shape).
+4. **Export in package.json**:
+   ```json
+   {
+     "exports": {
+       "./<component>": "./dist/<component>.js"
+     }
+   }
+   ```
+5. **Mix in cross-context helpers** at the bottom of the new Manager file — see [environment-detection.md](environment-detection.md).
+
+## See also
+
+- [managers.md](managers.md) — Manager classes, one-line bootstrap per context
+- [build-system.md](build-system.md) — how components compile through webpack/sass/html
+- [defaults.md](defaults.md) — the `src/defaults/` template system
+- [css.md](css.md) — SCSS load paths for component styles
+- [offscreen.md](offscreen.md) — offscreen document lifecycle + messaging patterns
+- [xss-prevention.md](xss-prevention.md) — escaping/sanitizing the strings components render

package/docs/css.md

@@ -0,0 +1,91 @@
+# CSS Architecture
+
+SCSS-based, theme-pluggable, with a load-path system that lets consumer SCSS reference framework + theme styles via short names (`@use 'browser-extension-manager'`, `@use 'theme'`).
+
+## Main entry
+
+[src/assets/css/browser-extension-manager.scss](../src/assets/css/browser-extension-manager.scss) is the framework's CSS entry point. Consumers `@use` it to get framework defaults + utilities + theme.
+
+## Core modules
+
+| Module | Source |
+|---|---|
+| `core/_initialize.scss` | Base resets (box-sizing, body defaults) |
+| `core/_utilities.scss` | Utility classes (`.shadow-lg`, `.text-truncate`, spacing, color, etc.) |
+| `core/_animations.scss` | Keyframe animations + transition mixins |
+
+## Per-component styles
+
+Each component can have framework defaults in `src/assets/css/components/<name>/index.scss`. These define the FRAMEWORK'S default look — e.g. `src/assets/css/components/popup/index.scss` defines popup-specific layout that ALL BXM extensions inherit unless they override.
+
+Consumer extensions add their OWN per-component overrides in `src/assets/css/components/<name>/index.scss` (in the consumer project, not the framework).
+
+## Load-path resolution
+
+The SCSS load path is set up by [src/gulp/tasks/sass.js](../src/gulp/tasks/sass.js) with this search order:
+
+1. **Framework CSS** — `node_modules/browser-extension-manager/dist/assets/css`
+2. **Active theme** — `node_modules/browser-extension-manager/dist/assets/themes/<theme-id>`
+3. **Project dist** — `<consumer>/dist/assets/css`
+4. **node_modules** — for npm-installed SCSS packages
+
+So this just works in a consumer's `src/assets/css/main.scss`:
+
+```scss
+// 1. Resolves to BXM's main entry — sets up Bootstrap, utilities, etc.
+@use 'browser-extension-manager' as * with (
+  $primary: #5B47FB,
+);
+
+// 2. Resolves to the active theme's _theme.scss
+@use 'theme' as *;
+
+// 3. Resolves to BXM's bundled popup defaults
+@use 'components/popup' as *;
+
+// 4. Resolves to npm-installed CSS package
+@use 'pkg:bootstrap-icons' as *;
+
+// Consumer-authored overrides come last
+.my-custom-rule { color: $primary; }
+```
+
+## Component bundle output
+
+Each component context gets a CSS bundle:
+
+- `src/assets/css/components/<component>/index.scss` → `dist/assets/css/components/<component>.bundle.css`
+
+The HTML pipeline auto-injects `<link rel="stylesheet" href="../assets/css/components/<component>.bundle.css">` into each view via the page template.
+
+## Theme integration
+
+Themes vendor their own SCSS under `src/assets/themes/<theme-id>/`. The load path resolves `@use 'theme'` to the active theme — flip `config.theme.id` to switch themes without code changes. See [themes.md](themes.md).
+
+## Adding a utility class
+
+[src/assets/css/core/_utilities.scss](../src/assets/css/core/_utilities.scss):
+
+```scss
+.shadow-lg {
+  box-shadow: 0 10px 15px -3px rgba(0, 0, 0, 0.1);
+}
+```
+
+After adding, run `npm run prepare` in BXM (or `npm start` in the consumer) and the new utility is available framework-wide.
+
+## Why this load-path system
+
+Without it, every consumer SCSS file would need:
+
+```scss
+@use '../../../../node_modules/browser-extension-manager/dist/assets/css/browser-extension-manager' as *;
+```
+
+Brittle, ugly, breaks with hoisted/non-hoisted npm installs. The load-path lets `@use 'browser-extension-manager'` work regardless of where BXM is installed. Same pattern UJM uses for Jekyll themes.
+
+## See also
+
+- [themes.md](themes.md) — theme system that the load path resolves
+- [components.md](components.md) — three-part component structure (view + styles + script)
+- [build-system.md](build-system.md) — gulp/sass task details

package/docs/defaults.md

@@ -0,0 +1,54 @@
+# Defaults System
+
+`src/defaults/` is the starter template that BXM copies into consumer projects on first run (`npx bxm setup`). It mirrors a "fresh BXM project" — manifest, views, components, config, .nvmrc, .gitignore, .env, etc.
+
+## How it works
+
+1. During BXM's own build (`prepare-package`), files in `src/defaults/` are copied to `dist/defaults/`.
+2. When a consumer runs `npx bxm setup`, the `gulp defaults` task copies files from `dist/defaults/` into the consumer's project root.
+3. File behavior (overwrite, skip, template, rename) is controlled by `FILE_MAP` in [src/gulp/tasks/defaults.js](../src/gulp/tasks/defaults.js).
+
+## FILE_MAP rules
+
+```js
+const FILE_MAP = {
+  'src/**/*':       { overwrite: false },                  // never overwrite user code
+  'hooks/**/*':     { overwrite: false },                  // never overwrite hooks
+  '_.gitignore':    { name: () => '.gitignore' },          // rename on copy
+  '_.env':          { name: () => '.env', overwrite: false },
+  '.nvmrc':         { template: { node: '22' } },          // run templating against the source
+  'package.json':   { skip: (cwd) => /* dynamic skip */ },
+};
+```
+
+## Rule types
+
+| Rule | Behavior |
+|---|---|
+| `overwrite: false` | Never replace if the file exists in the project. Default for `src/**`. |
+| `overwrite: true` | Always overwrite — for files BXM owns (e.g. `.github/workflows/build.yml`). |
+| `skip: function` | Dynamic skip — `(cwd) => boolean`. Skip in monorepo subdirs, etc. |
+| `template: data` | Run the source through templating with `data` as the var bag, then write. |
+| `name: function` | Rename on copy — typically used to add a leading `.` (`_.gitignore` → `.gitignore`). |
+
+## Why the underscore prefix?
+
+Files like `_.gitignore`, `_.env` are stored with a `_` prefix in `src/defaults/` so they don't interfere with BXM's own development (the framework repo doesn't want its `.env` overwritten by the template). The `name` rule renames them to the real `.foo` filename on copy.
+
+## Adding a new default
+
+1. Drop the file under `src/defaults/<path-where-it-goes-in-the-consumer>`
+2. If it needs special handling, add an entry to `FILE_MAP` in [tasks/defaults.js](../src/gulp/tasks/defaults.js)
+3. Run `npm run prepare` to refresh BXM's `dist/`
+4. Verify in a fresh consumer project: `mkdir test-consumer && cd test-consumer && npm i ../browser-extension-manager && npx bxm setup`
+
+## Why this exists
+
+Consumers shouldn't have to hand-author boilerplate (manifest, sample views, sample SCSS, sample background.js, .nvmrc, .gitignore). The defaults system seeds a working extension in one command. Same idea as `create-react-app` or `vite create`, just integrated with BXM's CLI.
+
+When BXM ships a framework improvement (e.g. a better default popup template), bumping BXM in a consumer + running `npx bxm setup` again pulls the improvements WITHOUT overwriting user changes (because most `src/**` entries are `overwrite: false`).
+
+## See also
+
+- [cli.md](cli.md) — `npx bxm setup` invokes the defaults task
+- [build-system.md](build-system.md) — gulp tasks pipeline

package/docs/environment-detection.md

@@ -0,0 +1,79 @@
+# Environment Detection
+
+`getEnvironment()` returns exactly ONE of three mutually-exclusive, exhaustive values:
+
+```javascript
+Manager.getEnvironment()    // 'development' | 'testing' | 'production'
+
+Manager.isDevelopment()     // true ONLY in development
+Manager.isTesting()         // true ONLY in testing
+Manager.isProduction()      // true ONLY in production
+```
+
+**The Manager is the single source of truth.** `getEnvironment()` is the ONLY function that reads the raw signals (`BXM_TEST_MODE` / `chrome.runtime.getManifest().update_url` / `BXM_BUILD_MODE` / `NODE_ENV` / `config.bxm.environment`). The three `is*()` checks **derive** from it live on every call — they never read raw signals themselves, so they can never disagree with `getEnvironment()`.
+
+**One implementation, mixed into all eight Managers.** BXM has eight Manager entry points (build / background / popup / options / content / sidepanel / page / offscreen). The helpers are defined once in [src/utils/mode-helpers.js](../src/utils/mode-helpers.js) and mixed into each via `attachTo(Manager)`, available as both prototype methods (`manager.isTesting()`) and statics (`Manager.isTesting()`).
+
+```javascript
+manager.getEnvironment()    // same answer in every extension context
+Manager.isTesting()         // static form, for build-time scripts
+```
+
+**Resolution order:** testing wins first, then production, else development. The three checks are mutually exclusive — exactly one is true. `isDevelopment()` is **false** during testing, and `isProduction()` is a real positive check (it is NOT `!isDevelopment()`).
+
+## Available helpers
+
+| Helper | Returns |
+|---|---|
+| `getEnvironment()` | `'development' \| 'testing' \| 'production'` — the SSOT resolver; the only reader of raw signals. |
+| `isDevelopment()` | `true` ONLY in development (unpacked extension via chrome://extensions / dev build), and NOT testing. Derives from `getEnvironment()`. |
+| `isTesting()` | `true` ONLY in testing (`BXM_TEST_MODE === 'true'`). **Takes precedence** — a test run is not development. |
+| `isProduction()` | `true` ONLY in production (packed / store-installed extension, `manifest.update_url` present). A **real positive check** — NOT `!isDevelopment()`. |
+
+## Gating side effects — use the INTENTIONAL check
+
+Because there are three environments, never gate a side effect on a two-value assumption. State what you mean:
+
+```javascript
+// Production-only (skip real telemetry / production behavior in dev AND testing):
+if (isProduction())  { /* do the real thing */ }
+if (!isProduction()) { /* skip / use the safe local behavior */ }
+
+// Local-or-test (anything that should run in BOTH dev and testing):
+if (isDevelopment() || isTesting()) { /* DevTools menu items, verbose logging */ }
+```
+
+**Avoid** `if (!isDevelopment())` or `if (env !== 'development')` to gate production behavior — those wrongly include `testing` as production and leak real side effects during test runs. This is the bug class that motivated the 3-value model. (A genuinely dev-only feature like live-reload is the exception: `env !== 'development'` correctly skips it in both testing and production.)
+
+## URL helpers
+
+BXM does **not** own backend URL helpers (`getApiUrl` / `getFunctionsUrl` / `getWebsiteUrl`). Extension code that needs a backend URL reads it from the `web-manager` runtime singleton in the runtime contexts (popup / options / sidepanel / background), which follows the same local-in-dev/testing, production-otherwise convention. The rule "call the getter, never hardcode" still applies; the implementation lives in `web-manager`.
+
+## Where they live
+
+Source: [src/utils/mode-helpers.js](../src/utils/mode-helpers.js) for `getEnvironment()` + `is*()` + `getVersion()`. The module exposes the functions plus an `attachTo(Manager)` mixin. Attached at the bottom of all eight Manager files ([build.js](../src/build.js), [background.js](../src/background.js), [popup.js](../src/popup.js), [options.js](../src/options.js), [content.js](../src/content.js), [sidepanel.js](../src/sidepanel.js), [page.js](../src/page.js), [offscreen.js](../src/offscreen.js)), so every extension context resolves the environment identically.
+
+## How detection works
+
+`getEnvironment()` resolves in this precedence order:
+
+1. **Testing** — `process.env.BXM_TEST_MODE === 'true'`, `globalThis.BXM_TEST_MODE === true`, or a build baked with `config.bxm.environment === 'testing'` (set by the harness before any consumer JS runs). A test run is a test run regardless of any other signal.
+2. **Production / Development (runtime)** — `chrome.runtime.getManifest().update_url`: present → production (packed / store-installed), absent → development (unpacked). This is the authoritative runtime signal in an extension context. In build-time Node, `chrome` is undefined, so it falls through.
+3. **Build-time + config signals** — `BXM_BUILD_MODE === 'true'` → production; `NODE_ENV === 'development'` → development; `config.bxm.environment` (`'development'` / `'production'`) override.
+4. **Default** — development. BXM's deployed artifacts always carry their signal (a packed / store extension has `manifest.update_url`; build-time Node sets `BXM_BUILD_MODE`), so reaching here means a bare tooling / unpacked context where development is correct. (Contrast BEM/EM, whose deployed *runtime* can legitimately lack a signal, so they default to **production**.)
+
+## Adding a new helper
+
+Write the function in [src/utils/mode-helpers.js](../src/utils/mode-helpers.js) (or a new `src/utils/<topic>-helpers.js` module), expose it from `attachTo(Manager)`, then call `attachTo` at the bottom of all eight Manager files. Don't define helpers on individual Manager prototypes — that leads to duplicated semantics. For anything environment-derived, derive from `getEnvironment()` rather than reading `chrome.runtime` / `process.env` directly, so there is one source of truth and no chance of drift.
+
+## Why this matters
+
+**One signal, used everywhere.** The test runner sets `BXM_TEST_MODE=true`; every piece of code that calls `isTesting()` (framework or consumer) then sees `true` — no need to invent a per-module env var.
+
+**Sub-modules check the same signal.** When framework code (an auto-update probe, an analytics flush) needs to skip side effects in tests, it checks `isTesting()` — the same answer the consumer's own code gets. No drift.
+
+**`is*()` can never disagree with `getEnvironment()`.** Because the checks derive from the single resolver instead of reading raw signals (`manifest.update_url` vs `BXM_BUILD_MODE`), there is exactly one definition of "what environment is this," and a wrong-but-confident gate is structurally impossible.
+
+## See also
+
+- [test-framework.md](test-framework.md) — `BXM_TEST_MODE` is set automatically by the test runners; extended mode (`--extended` / `TEST_EXTENDED_MODE=true`) gates real external APIs.