browser-extension-manager 1.3.49 → 1.5.0

package/README.md

@@ -5,129 +5,171 @@
 </p>
 
 <p align="center">
-  <img src="https://img.shields.io/github/package-json/v/itw-creative-works/ultimate-browser-extension.svg">
+  <img src="https://img.shields.io/github/package-json/v/itw-creative-works/browser-extension-manager.svg">
   <br>
-  <img src="https://img.shields.io/librariesio/release/npm/ultimate-browser-extension.svg">
-  <img src="https://img.shields.io/bundlephobia/min/ultimate-browser-extension.svg">
-  <img src="https://img.shields.io/codeclimate/maintainability-percentage/itw-creative-works/ultimate-browser-extension.svg">
-  <img src="https://img.shields.io/npm/dm/ultimate-browser-extension.svg">
-  <img src="https://img.shields.io/node/v/ultimate-browser-extension.svg">
-  <img src="https://img.shields.io/website/https/itwcreativeworks.com.svg">
-  <img src="https://img.shields.io/github/license/itw-creative-works/ultimate-browser-extension.svg">
-  <img src="https://img.shields.io/github/contributors/itw-creative-works/ultimate-browser-extension.svg">
-  <img src="https://img.shields.io/github/last-commit/itw-creative-works/ultimate-browser-extension.svg">
+  <img src="https://img.shields.io/librariesio/release/npm/browser-extension-manager.svg">
+  <img src="https://img.shields.io/bundlephobia/min/browser-extension-manager.svg">
+  <img src="https://img.shields.io/npm/dm/browser-extension-manager.svg">
+  <img src="https://img.shields.io/node/v/browser-extension-manager.svg">
+  <img src="https://img.shields.io/github/license/itw-creative-works/browser-extension-manager.svg">
+  <img src="https://img.shields.io/github/contributors/itw-creative-works/browser-extension-manager.svg">
+  <img src="https://img.shields.io/github/last-commit/itw-creative-works/browser-extension-manager.svg">
   <br>
   <br>
-  <a href="https://itwcreativeworks.com">Site</a> | <a href="https://www.npmjs.com/package/ultimate-browser-extension">NPM Module</a> | <a href="https://github.com/itw-creative-works/ultimate-browser-extension">GitHub Repo</a>
+  <a href="https://itwcreativeworks.com">Site</a> | <a href="https://www.npmjs.com/package/browser-extension-manager">NPM Module</a> | <a href="https://github.com/itw-creative-works/browser-extension-manager">GitHub Repo</a>
   <br>
   <br>
-  <strong>Ultimate Browser Extension</strong> is a template that helps you jumpstart your Jekyll sites and is fueled by an intuitive incorporation of npm, gulp, and is fully SEO optimized and blazingly fast.
+  <strong>Browser Extension Manager</strong> is a framework for building modern cross-browser extensions. One-line bootstrap per context, component-based architecture, multi-browser build pipeline, cross-context auth, auto-translation across 16 languages, and a four-layer test framework.
 </p>
 
 ## 🦄 Features
-* **Build for Any Browser**: Export to Chrome, Firefox, Edge, and Opera.
-* **NPM & Gulp**: Fueled by an intuitive incorporation of npm and gulp.
+
+- **Build for any browser**: Chrome, Firefox, Edge, Opera, Brave
+- **Component architecture**: seven contexts (background / popup / options / sidepanel / content / pages / offscreen) each with view + styles + script
+- **One-line bootstrap per context** with cross-browser API wrapper
+- **Cross-context auth sync**: sign-in in one tab is reflected in all open contexts (no `chrome.storage` needed)
+- **Auto-translation** to 16 languages via Claude CLI on every build
+- **Four-layer test framework**: build / background / view / boot — real Chromium, real MV3 service worker, real consumer extensions
+- **Multi-browser packaging + auto-publish** to Chrome / Firefox / Edge stores from one command
+- **Theme system**: Bootstrap 5 + Classy (custom design system), or roll your own
+- **SCSS load paths**: `@use 'browser-extension-manager'` / `@use 'theme'` Just Work — no relative-path hell
 
 ## 🚀 Getting started
-1. [Create a repo](https://github.com/itw-creative-works/ultimate-browser-extension/generate) from the **Ultimate Browser Extension** template.
+
+1. [Create a repo](https://github.com/itw-creative-works/ultimate-browser-extension/generate) from the **Ultimate Browser Extension** template (or `npm i browser-extension-manager` in an existing project).
 2. Clone the repo to your local machine.
-3. Run these command to get everything setup and sync'd!
+3. Set up + run:
+   ```bash
+   npm install
+   npx bxm setup
+   npm start
+   ```
+4. Open Chrome and navigate to `chrome://extensions`.
+5. Enable **Developer mode**.
+6. Click **Load unpacked** and select the `packaged/chromium/raw` folder in your project.
+7. Your extension is loaded and live-reloads on source changes.
+
+## 📦 Sync with the template
+
+Run `npx bxm setup` again to pull the latest framework defaults. Files you've edited are preserved; only missing or framework-owned files update.
+
+## 🧪 Testing
+
+BXM ships a built-in four-layer test framework. Write tests under `test/<layer>/*.test.js` and run with:
+
 ```bash
-npm install
-npx bxm setup
-npm start
+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
+// test/build/manifest.test.js
+const Manager = require('browser-extension-manager/build');
+
+module.exports = {
+  layer: 'build',
+  description: 'manifest is valid MV3',
+  run: (ctx) => {
+    const m = Manager.getManifest();
+    ctx.expect(m.manifest_version).toBe(3);
+    ctx.expect(m.permissions).toContain('storage');
+  },
+};
 ```
-4. Open your browser and navigate to `chrome://extensions` (or the equivalent for your browser).
-5. Enable **Developer mode**.
-6. Click on **Load unpacked** and select the `dist` folder in your project directory.
-7. Your extension should now be loaded and ready to use!
 
-## 📦 How to sync with the template
-1. Simply run `npx bxm setup` in Terminal to get all the latest updates from the **Ultimate Browser Extension template**.
+Full guide: [docs/test-framework.md](docs/test-framework.md). End-to-end "did my packaged extension actually boot in Chrome?" tests: [docs/test-boot-layer.md](docs/test-boot-layer.md).
+
+## 🌐 Auto-translation
+
+When you run `npm run build`, BXM auto-translates `src/_locales/en/messages.json` to 16 languages via Claude CLI:
 
-## 🌐 Automatic Translation
-When you run `npm run build`, BXM automatically translates your `src/_locales/en/messages.json` to 16 languages using Claude CLI:
 `zh`, `es`, `hi`, `ar`, `pt`, `ru`, `ja`, `de`, `fr`, `ko`, `ur`, `id`, `bn`, `tl`, `vi`, `it`
 
-Only missing translations are generated - existing translations are preserved.
+Only missing translations are generated — existing translations are preserved. Full guide: [docs/translations.md](docs/translations.md).
 
 ## 🌎 Publishing your extension
 
-### Manual Upload
-1. Run `npm run build` in Terminal to build your extension for production.
-2. Upload the `.zip` file to the browser's extension store.
+### Manual upload
 
-### Automatic Publishing
-BXM can automatically publish to Chrome, Firefox, and Edge stores when `BXM_IS_PUBLISH=true`:
+```bash
+npm run build
+```
+
+Upload the `.zip` files under `packaged/<browser>/` to each browser's extension store.
+
+### Automatic publishing
 
 ```bash
 BXM_IS_PUBLISH=true npm run build
 ```
 
-**Setup:** Add store credentials to your `.env` file:
+Add store credentials to your `.env`:
 
 ```bash
 # Chrome Web Store
-CHROME_EXTENSION_ID="your-extension-id"
-CHROME_CLIENT_ID="your-client-id"
-CHROME_CLIENT_SECRET="your-client-secret"
-CHROME_REFRESH_TOKEN="your-refresh-token"
+CHROME_EXTENSION_ID="..."
+CHROME_CLIENT_ID="..."
+CHROME_CLIENT_SECRET="..."
+CHROME_REFRESH_TOKEN="..."
 
 # Firefox Add-ons
-FIREFOX_EXTENSION_ID="your-extension-id"
-FIREFOX_API_KEY="your-api-key"
-FIREFOX_API_SECRET="your-api-secret"
+FIREFOX_EXTENSION_ID="..."
+FIREFOX_API_KEY="..."
+FIREFOX_API_SECRET="..."
 
 # Microsoft Edge Add-ons
-EDGE_PRODUCT_ID="your-product-id"
-EDGE_CLIENT_ID="your-client-id"
-EDGE_API_KEY="your-api-key"
+EDGE_PRODUCT_ID="..."
+EDGE_CLIENT_ID="..."
+EDGE_API_KEY="..."
 ```
 
-Only stores with configured credentials will be published to.
+Only stores with configured credentials get published to. Full guide: [docs/publishing.md](docs/publishing.md).
 
 ## 🔐 Authentication
 
-BXM provides built-in authentication that syncs across all extension contexts (popup, options, pages, sidepanel, background).
-
-### How It Works
+BXM provides built-in cross-context authentication that syncs across all extension contexts (popup, options, sidepanel, pages, background) without using `chrome.storage`.
 
-**Background.js is the source of truth.** Auth syncs via messaging (no storage).
+**Background.js is the source of truth.** Auth syncs via messaging — sign-in / sign-out events propagate across all open contexts, and new contexts handshake with background on load.
 
-- **Sign-in**: User clicks `.auth-signin-btn` → opens `/token` page on website → website authenticates and redirects with token → background.js signs in and broadcasts to all open contexts
-- **Context load**: Each context compares its UID with background's UID on load; syncs if different
-- **Sign-out**: User clicks `.auth-signout-btn` → context signs out → notifies background → background broadcasts sign-out to all contexts
-
-### Required Setup
+### Setup
 
 1. Add `authDomain` to your Firebase config in `config/browser-extension-manager.json`
-2. Add `tabs` permission to `src/manifest.json` (for URL monitoring)
+2. Add `tabs` permission to `src/manifest.json`
+
+### Auth button classes
 
-### Auth Button Classes
+Add these CSS classes to HTML elements for declarative auth UI:
 
 | Class | Action |
-|-------|--------|
-| `.auth-signin-btn` | Opens `/token` page on website |
-| `.auth-signout-btn` | Signs out via Web Manager |
-| `.auth-account-btn` | Opens `/account` page on website |
+|---|---|
+| `.auth-signin-btn` | Opens `/token` page on your website |
+| `.auth-signout-btn` | Signs out via Web Manager (broadcasts to all contexts) |
+| `.auth-account-btn` | Opens `/account` page on your website |
 
-### Example
 ```html
 <button class="btn auth-signin-btn" data-wm-bind="@show !auth.user">Sign In</button>
 
 <div data-wm-bind="@show auth.user" hidden>
+  <img data-wm-bind="@attr src auth.user.photoURL">
   <span data-wm-bind="@text auth.user.displayName">User</span>
   <button class="auth-signout-btn">Sign Out</button>
 </div>
 ```
 
-### Reactive Bindings
-- `@show auth.user` / `@show !auth.user` - Show/hide based on auth state
-- `@text auth.user.displayName` / `@text auth.user.email` - Display user info
-- `@attr src auth.user.photoURL` - Set avatar image
+Full guide: [docs/auth.md](docs/auth.md).
 
-<!-- ## ⛳️ Flags
-* `--test=false` - Coming soon
-```bash
-npm start -- --test=false
-``` -->
+## 📚 Documentation
+
+In-depth docs for every subsystem live in [docs/](docs/). See [CLAUDE.md](CLAUDE.md) for the architecture overview + table of contents.
+
+## 🧰 Sister projects
+
+- [Electron Manager (EM)](https://github.com/itw-creative-works/electron-manager) — same patterns, but for Electron desktop apps
+- [Ultimate Jekyll Manager (UJM)](https://github.com/itw-creative-works/ultimate-jekyll-manager) — Jekyll static-site framework
+- [Backend Manager (BEM)](https://github.com/itw-creative-works/backend-manager) — Firebase Functions backend framework

package/dist/background.js

@@ -1,6 +1,7 @@
 // Libraries
 import extension from './lib/extension.js';
 import LoggerLite from './lib/logger-lite.js';
+import { attachTo as attachModeHelpers } from './utils/mode-helpers.js';
 
 // Firebase (static imports - dynamic import() doesn't work in service workers with webpack chunking)
 import { initializeApp, getApp } from 'firebase/app';
@@ -512,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
@@ -660,5 +662,8 @@ function setupGlobalHandlers() {
   });
 }
 
+// Cross-context helpers — Manager.isTesting() / isDevelopment() / etc.
+attachModeHelpers(Manager);
+
 // Export
 export default Manager;

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 () {
@@ -196,5 +191,8 @@ Manager.logMemory = function (logger, label) {
 };
 Manager.prototype.logMemory = Manager.logMemory;
 
+// Cross-context helpers — Manager.isTesting() / isDevelopment() / etc.
+require('./utils/mode-helpers.js').attachTo(Manager);
+
 // Export
 module.exports = Manager;

package/dist/cli.js

@@ -11,6 +11,7 @@ const ALIASES = {
   clean: ['-c', '--clean'],
   install: ['-i', 'i', '--install'],
   setup: ['-s', '--setup'],
+  test: ['-t', '--test'],
   version: ['-v', '--version'],
 };
 

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/commands/test.js

@@ -0,0 +1,55 @@
+// Libraries
+const path    = require('path');
+const fs      = require('fs');
+const Manager = new (require('../build.js'));
+const logger  = Manager.logger('test');
+const { run } = require('../test/runner.js');
+
+module.exports = async function (options) {
+  const layer       = options.layer    || 'all';
+  const filter      = options.filter   || null;
+  const reporter    = options.reporter || 'pretty';
+  const integration = options.integration === true || options.integration === 'true';
+
+  if (integration) {
+    process.env.BXM_TEST_INTEGRATION = '1';
+  }
+
+  // Canonical signal — every Manager picks this up via isTesting().
+  process.env.BXM_TEST_MODE = 'true';
+
+  // When BXM itself runs its own boot-layer tests (the cwd's package.json is
+  // BXM's package.json), there's no real consumer extension to target. Point
+  // the boot runner at the fixture under dist/test/fixtures/consumer-extension
+  // unless the caller has already set BXM_TEST_BOOT_PROJECT explicitly.
+  if (!process.env.BXM_TEST_BOOT_PROJECT) {
+    try {
+      const cwdPkg = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'package.json'), 'utf8'));
+      if (cwdPkg.name === 'browser-extension-manager') {
+        process.env.BXM_TEST_BOOT_PROJECT = path.join(__dirname, '..', 'test', 'fixtures', 'consumer-extension');
+      }
+    } catch (_) { /* no package.json — leave unset */ }
+  }
+
+  if (reporter !== 'json') {
+    logger.log(`Running tests (layer=${layer}${filter ? ` filter="${filter}"` : ''}${integration ? ' +integration' : ''})`);
+  }
+
+  const result = await run({ layer, filter, reporter });
+
+  if (reporter === 'json') {
+    // Final machine-readable summary.
+    process.stdout.write(JSON.stringify({
+      event:   'summary',
+      passed:  result.passed,
+      failed:  result.failed,
+      skipped: result.skipped,
+      total:   result.passed + result.failed + result.skipped,
+    }) + '\n');
+  }
+
+  if (result.failed > 0) {
+    process.exitCode = 1;
+    throw new Error(`${result.failed} test(s) failed`);
+  }
+};

package/dist/content.js

@@ -2,6 +2,7 @@
 import extension from './lib/extension.js';
 import LoggerLite from './lib/logger-lite.js';
 import Affiliatizer from './lib/affiliatizer.js';
+import { attachTo as attachModeHelpers } from './utils/mode-helpers.js';
 
 // Class
 class Manager {
@@ -28,5 +29,8 @@ class Manager {
   }
 }
 
+// Cross-context helpers — Manager.isTesting() / isDevelopment() / etc.
+attachModeHelpers(Manager);
+
 // Export
 export default Manager;

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,8 +1,84 @@
-# Identity
-This is a browser extension that is "consuming" a browser extension template project called Browser Extension Manager (BXM)--a collection of components that can be used to build a browser extension quickly and efficiently.
+# ========== Default Values ==========
+# Browser Extension Manager (BXM) — consumer project
 
-## BXM Documentation
-You should have a full understanding of Browser Extension Manager before editing this project, which can be found at: node_modules/browser-extension-manager/CLAUDE.md
+## Framework
 
-## Project-specific Notes
-Add any notes specific to this project here.
+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.
+
+## 🚨 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
+
+```bash
+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
+
+- `config/browser-extension-manager.json` — JSON5 config: brand, manifest overrides, build settings, theme. `Manager.getConfig()` reads this.
+- `config/messages.json` — i18n source. Auto-translated to 16 languages at build time via the Claude CLI (only missing keys regenerated).
+- `config/description.md` — store-listing description (used by the publish step).
+- `src/manifest.json` — extension manifest. BXM merges its defaults in at build time; you only need to declare what's specific to your extension.
+- `src/views/<context>/index.html` — per-context HTML (popup / options / sidepanel / pages).
+- `src/assets/js/components/<context>/index.js` — per-context script entry. One-line bootstrap of `browser-extension-manager/<context>`.
+- `src/assets/css/components/<context>/index.scss` — per-context styles.
+- `src/assets/js/components/background.js` — MV3 service worker entry. Source of truth for auth + messaging.
+- `src/_locales/en/messages.json` — Chrome `__MSG_*__` placeholders (auto-translated to 16 langs at build).
+- `hooks/build/{pre,post}.js` — optional lifecycle hooks.
+- `test/**/*.js` — your project test suites (framework auto-runs them alongside its own).
+
+## Per-context imports
+
+```js
+// src/assets/js/components/popup/index.js
+import Manager from 'browser-extension-manager/popup';
+await new Manager().initialize();
+
+// src/assets/js/components/background.js  (service worker)
+import Manager from 'browser-extension-manager/background';
+await new Manager().initialize();
+
+// Same shape for options / sidepanel / content / page / offscreen
+```
+
+## Available APIs at runtime
+
+After `initialize()`, every Manager exposes:
+- `manager.extension` — cross-browser `chrome.*` / `browser.*` / `window.*` wrapper
+- `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. `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
+
+Add anything specific to THIS project here. Edits below this line are preserved across `npx mgr setup` runs.

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/gulp/tasks/defaults.js

@@ -66,6 +66,15 @@ const FILE_MAP = {
     mergeLines: true,
   },
 
+  // Consumer CLAUDE.md uses the same marker-based merge as .env/.gitignore.
+  // Framework owns the Default section; consumer owns everything below the Custom marker.
+  // Must come AFTER `**/*.md` (which sets overwrite: false) — `getFileOptions` does
+  // last-match-wins, so this rule's `mergeLines: true` activates the merge path even though
+  // the catch-all would otherwise skip.
+  'CLAUDE.md': {
+    mergeLines: true,
+  },
+
   // Config files
   'config/browser-extension-manager.json': {
     overwrite: true,
@@ -270,8 +279,12 @@ function mergeLineBasedFiles(existingContent, newContent, fileName) {
   result.push(DEFAULT_SECTION_MARKER);
   result.push(...mergedDefaultSection);
 
-  // Add custom section
-  result.push('');
+  // Add custom section. Insert a single blank line before the marker, but only if the
+  // merged default doesn't already end with one — otherwise we'd accumulate an extra blank
+  // line on every merge, breaking idempotency after the first re-run.
+  if (mergedDefaultSection.length === 0 || mergedDefaultSection[mergedDefaultSection.length - 1].trim() !== '') {
+    result.push('');
+  }
   result.push(CUSTOM_SECTION_MARKER);
 
   // First add any user lines that were in default section (moved to custom)

package/dist/offscreen.js

@@ -1,6 +1,7 @@
 // Libraries
 import extension from './lib/extension.js';
 import LoggerLite from './lib/logger-lite.js';
+import { attachTo as attachModeHelpers } from './utils/mode-helpers.js';
 
 // Class
 class Manager {
@@ -23,5 +24,8 @@ class Manager {
   }
 }
 
+// Cross-context helpers — Manager.isTesting() / isDevelopment() / etc.
+attachModeHelpers(Manager);
+
 // Export
 export default Manager;

package/dist/options.js

@@ -3,6 +3,7 @@ import webManager from 'web-manager';
 import extension from './lib/extension.js';
 import LoggerLite from './lib/logger-lite.js';
 import { syncWithBackground, setupAuthBroadcastListener, setupSignOutListener, setupAuthEventListeners, openAuthPage as openAuthPageHelper } from './lib/auth-helpers.js';
+import { attachTo as attachModeHelpers } from './utils/mode-helpers.js';
 
 // Import theme (exposes Bootstrap to window.bootstrap)
 import '__theme__/_theme.js';
@@ -59,5 +60,8 @@ class Manager {
   }
 }
 
+// Cross-context helpers — Manager.isTesting() / isDevelopment() / etc.
+attachModeHelpers(Manager);
+
 // Export
 export default Manager;

package/dist/page.js

@@ -3,6 +3,7 @@ import webManager from 'web-manager';
 import extension from './lib/extension.js';
 import LoggerLite from './lib/logger-lite.js';
 import { syncWithBackground, setupAuthBroadcastListener, setupSignOutListener, setupAuthEventListeners, openAuthPage as openAuthPageHelper } from './lib/auth-helpers.js';
+import { attachTo as attachModeHelpers } from './utils/mode-helpers.js';
 
 // Import theme (exposes Bootstrap to window.bootstrap)
 import '__theme__/_theme.js';
@@ -59,5 +60,8 @@ class Manager {
   }
 }
 
+// Cross-context helpers — Manager.isTesting() / isDevelopment() / etc.
+attachModeHelpers(Manager);
+
 // Export
 export default Manager;