browser-extension-manager 1.6.0 → 1.7.0

package/docs/extension.md

@@ -0,0 +1,94 @@
+# Cross-Browser API Wrapper (`lib/extension.js`)
+
+A singleton that normalizes the `chrome.*` / `browser.*` / `window.*` extension API surface so consumers write their extension once and it works on Chrome, Firefox, Edge, and other Chromium-based browsers.
+
+## Import
+
+```js
+const ext = require('browser-extension-manager/lib/extension');
+
+// or as a Manager property:
+const Manager = new (require('browser-extension-manager/popup'));
+await Manager.initialize();
+const { extension } = Manager;     // same singleton
+```
+
+## How it works
+
+For each known extension API, the wrapper tries in order:
+1. `chrome.<api>` (Chrome, Edge, Opera, Brave)
+2. `window.<api>` (some content-script contexts where chrome is exposed under window)
+3. `browser.<api>` (Firefox)
+4. `browser.extension.<api>` (legacy fallback)
+
+The first one that resolves becomes the singleton's `<api>` property. Each lookup is wrapped in try/catch so unknown globals don't throw at module-load time — that's what makes the wrapper safe to import from Node contexts too (where none of these globals exist).
+
+## Supported APIs
+
+```
+action, alarms, bookmarks, browsingData, browserAction,
+certificateProvider, commands, contentSettings, contextMenus,
+cookies, debugger, declarativeContent, declarativeNetRequest,
+devtools, dns, documentScan, downloads, enterprise, events,
+extension, extensionTypes, fileBrowserHandler, fileSystemProvider,
+fontSettings, gcm, history, i18n, identity, idle, input, instanceID,
+management, notifications, offscreen, omnibox, pageAction,
+permissions, platformKeys, power, printerProvider, privacy, proxy,
+runtime, scripting, search, sessions, sidePanel, storage, tabGroups,
+tabs, topSites, tts, ttsEngine, userScripts, vpnProvider, wallpaper,
+webNavigation, webRequest, windows
+```
+
+If a browser doesn't expose a given API, the property is `null` (not undefined), so consumers can branch on `if (extension.sidePanel) { ... }`.
+
+## Usage
+
+```js
+const Manager = new (require('browser-extension-manager/popup'));
+await Manager.initialize();
+const { extension } = Manager;
+
+// Works on Chrome, Firefox, Edge — identical call sites
+extension.tabs.query({ active: true, currentWindow: true }, (tabs) => {
+  console.log('Active tab:', tabs[0]);
+});
+
+extension.storage.get('key', (result) => { /* ... */ });
+extension.runtime.sendMessage({ type: 'hello' });
+extension.notifications.create({ /* ... */ });
+```
+
+## Storage normalization
+
+The wrapper auto-resolves `storage` to `storage.sync` when available (preferred — synced across the user's Chrome sign-in), falling back to `storage.local` when sync isn't available (e.g. some Firefox MV2 contexts).
+
+```js
+extension.storage.set({ foo: 'bar' });
+extension.storage.get('foo', (result) => console.log(result.foo));
+```
+
+If you specifically need local-only storage (per-machine, larger quota), use `chrome.storage.local.*` directly — bypass the wrapper.
+
+## Node-safe by design
+
+The wrapper imports cleanly from Node (build-time scripts, tests, gulp tasks) — every property is `null` in that context because none of the browser globals exist. This is what makes BXM's build-layer tests possible:
+
+```js
+// build-layer test (Node)
+const ext = require('browser-extension-manager/lib/extension');
+ctx.expect(ext.runtime).toBeNull();   // no chrome global in Node
+```
+
+## Why not `webextension-polyfill`?
+
+`webextension-polyfill` shims Firefox's promise-returning APIs onto Chrome's callback-based APIs. Useful, but:
+- Adds an npm dep that has to be loaded as a content-script before user code
+- Doesn't address the case where APIs simply don't exist on a browser (e.g. `sidePanel` on Firefox)
+- Slow boot in SW context
+
+BXM's wrapper is simpler: detect what's there, expose null when it isn't, let user code branch. Combine with the promisification Chrome added in MV3 (callbacks return promises when omitted) for a polyfill-free async-friendly API.
+
+## See also
+
+- [managers.md](managers.md) — every Manager exposes `extension` after `initialize()`
+- [components.md](components.md) — which API surface is available in which context

package/docs/hooks.md

@@ -0,0 +1,101 @@
+# Build Hooks
+
+Two lifecycle hooks let consumers run custom logic during the build pipeline.
+
+## Hook files
+
+| Hook | Source | When |
+|---|---|---|
+| `build:pre` | `hooks/build:pre.js` (in consumer project) | Before packaging — after `dist/` is built but before `packaged/` is assembled |
+| `build:post` | `hooks/build:post.js` | After packaging — `packaged/<browser>/raw/` and `.zip` exist |
+
+Hooks are optional — `gulp/tasks/package.js` checks for the file's presence and runs it if present.
+
+## Hook shape
+
+```js
+// hooks/build:pre.js
+module.exports = async function (index) {
+  // index contains build info — package, manifest, config, paths
+  console.log('Pre-build hook running for', index.brand.name);
+
+  // Mutate files, generate assets, validate, anything you want.
+  // Return a Promise (or use async fn) to make the build wait.
+};
+```
+
+## The `index` argument
+
+The hook receives a build-info object with:
+
+- `index.package` — parsed `package.json`
+- `index.manifest` — parsed `src/manifest.json` (JSON5)
+- `index.config` — parsed `config/browser-extension-manager.json`
+- `index.brand` — shorthand for `index.config.brand`
+- `index.paths` — `{ root, src, dist, packaged }` absolute paths
+- `index.env` — `'production'` or `'development'`
+- `index.browsers` — array of browser targets being built (`['chromium', 'firefox', 'opera']`)
+
+## Common uses
+
+### Sync a CHANGELOG version into the manifest
+
+```js
+// hooks/build:pre.js
+const fs = require('fs');
+const path = require('path');
+
+module.exports = async function (index) {
+  const changelog = fs.readFileSync(path.join(index.paths.root, 'CHANGELOG.md'), 'utf8');
+  const latestVersion = changelog.match(/## \[([\d.]+)\]/)?.[1];
+  if (latestVersion && latestVersion !== index.manifest.version) {
+    console.warn(`Manifest version (${index.manifest.version}) doesn't match CHANGELOG latest (${latestVersion})`);
+  }
+};
+```
+
+### Inject a build timestamp
+
+```js
+// hooks/build:pre.js
+const fs = require('fs');
+const path = require('path');
+
+module.exports = async function (index) {
+  const buildInfo = {
+    builtAt: new Date().toISOString(),
+    gitSha: require('child_process').execSync('git rev-parse HEAD').toString().trim(),
+  };
+  fs.writeFileSync(path.join(index.paths.dist, 'build-info.json'), JSON.stringify(buildInfo, null, 2));
+};
+```
+
+### Trigger a post-publish webhook
+
+```js
+// hooks/build:post.js
+module.exports = async function (index) {
+  if (process.env.BXM_IS_PUBLISH !== 'true') return;   // only after real publish
+  await fetch('https://api.myservice.com/extension-released', {
+    method: 'POST',
+    body: JSON.stringify({ version: index.manifest.version }),
+  });
+};
+```
+
+## Async by default
+
+Hooks are awaited — the build waits for them to resolve before continuing. Throw or reject to fail the build (and abort packaging / publishing).
+
+## Where hooks are invoked
+
+[src/gulp/tasks/package.js](../src/gulp/tasks/package.js) loads and runs them. Search for `runHook` in that file to see the exact wiring.
+
+## Why not just edit gulp tasks?
+
+You COULD fork BXM's gulp tasks for any custom build behavior. Hooks exist so consumers don't need to. Hooks are stable contract (the `index` object shape doesn't change), survive BXM upgrades, and live in the consumer's repo (where build-specific concerns belong).
+
+## See also
+
+- [build-system.md](build-system.md) — gulp pipeline details
+- [publishing.md](publishing.md) — store auto-publishing happens AFTER `build:post`

package/docs/icons.md

@@ -0,0 +1,47 @@
+# Icons
+
+BXM generates every extension icon size from ONE consumer-supplied source image — drop a single file, the build derives the rest.
+
+## Layout
+
+```
+<consumer>/config/icon.png        ← your ONE source icon (png or svg)
+```
+
+That's it. The `icons` gulp task picks up `config/icon.{png,svg}` and generates:
+
+```
+dist/assets/images/icons/icon.png          (original, converted to png)
+dist/assets/images/icons/icon-1024x.png
+dist/assets/images/icons/icon-512x.png
+dist/assets/images/icons/icon-256x.png
+dist/assets/images/icons/icon-128x.png
+dist/assets/images/icons/icon-64x.png
+dist/assets/images/icons/icon-48x.png
+dist/assets/images/icons/icon-32x.png
+dist/assets/images/icons/icon-24x.png
+dist/assets/images/icons/icon-16x.png
+```
+
+## Where the sizes are used
+
+- **Manifest** — BXM's manifest template wires the `icons` map to the generated paths (`assets/images/icons/icon-<size>x.png`), covering Chrome's required 16/32/48/128 plus the larger store sizes.
+- **Store packaging** — the `package` task copies `icon-128x.png` into the store-assets directory for listing uploads.
+
+## Sizes — ship ONE large source
+
+Supply the source at the largest size you have (1024×1024 recommended) — generation resizes DOWN with quality 100 and strips metadata. Small sources are enlarged (`withoutEnlargement: false`), but upscaled icons look soft; start big.
+
+## Watch behavior
+
+In dev (`npm start`) the task watches `config/icon.*` and regenerates on change. In build mode the watcher is skipped — generation runs once in the pipeline.
+
+## Source files
+
+- [src/gulp/tasks/icons.js](../src/gulp/tasks/icons.js) — generation task (gulp-responsive-modern)
+- [src/config/manifest.json](../src/config/manifest.json) — framework manifest wiring the `icons` map
+
+## See also
+
+- [build-system.md](build-system.md) — where the icons task runs in the pipeline
+- [extension.md](extension.md) — cross-browser API + manifest reference

package/docs/logging.md

@@ -0,0 +1,33 @@
+# Logging
+
+BXM tees every line of CLI/pipeline output to log files in the consumer project root, so you can `tail -f` or `grep` a run instead of scrolling terminal scrollback. Runtime extension logs live in the browser's own consoles (service-worker console, popup/options DevTools) — this doc covers the file logs BXM itself writes.
+
+## Log files
+
+All in `<projectRoot>/logs/`:
+
+| File | Source | Lifetime |
+|---|---|---|
+| `dev.log` | Gulp pipeline output on `npm start` | Truncated each run |
+| `build.log` | Gulp pipeline output on `npm run build` (`BXM_BUILD_MODE=true`) | Truncated each run |
+| `test.log` | `npx mgr test` runner output (suite names, pass/fail states, timings) | Truncated each run |
+
+`dev.log` and `build.log` are the same gulp tee — which one it writes is chosen by `BXM_BUILD_MODE`, so they never both fill up in one run.
+
+## What gets captured
+
+Everything that flows through stdout/stderr: `Manager.logger(...)` output, raw `console.log` calls, gulp task names, webpack/sass output, the works. ANSI color codes are stripped from the file (grep-friendly); the terminal continues to receive colored output unchanged.
+
+## Controls
+
+| Var | Effect |
+|---|---|
+| `BXM_LOG_FILE=false` | Disable the tee entirely |
+| `BXM_LOG_FILE=<path>` | Override the log file path |
+
+Implementation: [src/utils/attach-log-file.js](../src/utils/attach-log-file.js), attached at the top of [src/gulp/main.js](../src/gulp/main.js) — same pattern as EM's `dev.log`/`build.log` and UJM's.
+
+## See also
+
+- [build-system.md](build-system.md) — the gulp pipeline that feeds `dev.log`/`build.log`
+- [test-framework.md](test-framework.md) — the test runner that feeds `test.log`

package/docs/managers.md

@@ -0,0 +1,100 @@
+# Manager Classes
+
+Each component context has its own Manager class — a one-line import + `initialize()` bootstrap that wires up `extension` (the cross-browser API wrapper), `logger`, `webManager` (Firebase auth), `messenger`, and cross-context helpers.
+
+## Import paths
+
+| Context | Import | Source |
+|---|---|---|
+| Build-time (Node) | `require('browser-extension-manager/build')` | [src/build.js](../src/build.js) |
+| Background SW | `require('browser-extension-manager/background')` | [src/background.js](../src/background.js) |
+| Popup | `require('browser-extension-manager/popup')` | [src/popup.js](../src/popup.js) |
+| Options | `require('browser-extension-manager/options')` | [src/options.js](../src/options.js) |
+| Sidepanel | `require('browser-extension-manager/sidepanel')` | [src/sidepanel.js](../src/sidepanel.js) |
+| Pages (custom) | `require('browser-extension-manager/page')` | [src/page.js](../src/page.js) |
+| Content script | `require('browser-extension-manager/content')` | [src/content.js](../src/content.js) |
+| Offscreen | `require('browser-extension-manager/offscreen')` | [src/offscreen.js](../src/offscreen.js) |
+
+## One-line bootstrap
+
+Every consumer-side context entry is the same shape:
+
+```js
+// src/assets/js/components/popup/index.js
+import Manager from 'browser-extension-manager/popup';
+
+const manager = new Manager();
+await manager.initialize();
+
+// Manager now exposes:
+//   manager.extension   — cross-browser chrome.*/browser.* API wrapper (see docs/extension.md)
+//   manager.logger      — LoggerLite('popup') with timestamped output
+//   manager.webManager  — Web Manager (Firebase, auth, analytics, bindings)
+//   manager.messenger   — wired automatically; chrome.runtime.onMessage listener installed
+//   manager.isDevelopment() / isProduction() / isTesting() / getVersion()  (cross-context helpers)
+```
+
+The contexts that include `web-manager` (popup / options / sidepanel / page) also run the auth sync handshake automatically — see [auth.md](auth.md).
+
+## Build-time Manager
+
+`browser-extension-manager/build` is the build-time Manager — used in gulp tasks, CLI commands, and tests. Different surface from the runtime Managers:
+
+```js
+const Manager = require('browser-extension-manager/build');
+
+Manager.getConfig();         // → parsed config/browser-extension-manager.json
+Manager.getManifest();       // → parsed src/manifest.json (JSON5)
+Manager.getPackage('project');   // → cwd's package.json
+Manager.getPackage('main');      // → BXM's own package.json
+Manager.getRootPath('project');  // → process.cwd()
+Manager.getRootPath('main');     // → path to BXM's dist
+Manager.getEnvironment();    // → 'production' if BXM_BUILD_MODE=true else 'development'
+Manager.getLiveReloadPort(); // → 35729 by default
+Manager.isBuildMode();       // → boolean
+Manager.actLikeProduction(); // → buildMode || UJ_AUDIT_FORCE
+Manager.require(name);       // → borrow any of BXM's bundled deps (json5, fs-jetpack, etc.)
+Manager.logger(name);        // → new logger('name') instance
+Manager.reportBuildError(e); // → notifly + log
+```
+
+Cross-context helpers (`isTesting/isDevelopment/isProduction/getVersion`) are available on `Manager` as static methods AND on instances. See [environment-detection.md](environment-detection.md).
+
+## Boot flow inside `initialize()`
+
+Each Manager's `initialize()`:
+
+1. **Read configuration** — from `window.BXM_BUILD_JSON?.config` (injected by webpack at build time)
+2. **Wire `extension`** — singleton from [src/lib/extension.js](../src/lib/extension.js), normalized chrome.*/browser.* API
+3. **Construct `logger`** — `new LoggerLite('<context>')` from [src/lib/logger-lite.js](../src/lib/logger-lite.js)
+4. **Initialize `webManager`** (popup/options/sidepanel/page only) — `webManager.initialize(config)`
+5. **Set up auth listener** — `webManager.auth().listen((state) => { /* ... */ })`
+6. **Sync with background** — call `syncWithBackground(this)` from [src/lib/auth-helpers.js](../src/lib/auth-helpers.js); see [auth.md](auth.md)
+7. **Install broadcast / sign-out / event listeners** — handles signin-from-other-context, signout propagation
+8. **Return the manager instance**
+
+Background.js is more involved — it owns the auth source of truth, listens for `bxm:syncAuth` from other contexts, handles the website token flow. See [auth.md](auth.md).
+
+## Auth-related shortcuts (popup / options / sidepanel / page)
+
+These Manager classes expose `manager.openAuthPage(options)` — opens the website's `/token` page (with `authSourceTabId` so tab restoration works after sign-in). See [auth.md](auth.md) for the full flow.
+
+## Mixin: cross-context helpers
+
+Every Manager file imports `attachTo` from [src/utils/mode-helpers.js](../src/utils/mode-helpers.js) and calls it at the bottom of the file:
+
+```js
+import { attachTo as attachModeHelpers } from './utils/mode-helpers.js';
+// ... class Manager { ... }
+attachModeHelpers(Manager);
+export default Manager;
+```
+
+That gives every Manager `isDevelopment` / `isProduction` / `isTesting` / `getVersion` on both the prototype and the constructor. See [environment-detection.md](environment-detection.md).
+
+## See also
+
+- [components.md](components.md) — the seven component contexts
+- [extension.md](extension.md) — the cross-browser chrome.* API wrapper
+- [auth.md](auth.md) — how background.js coordinates auth across contexts
+- [environment-detection.md](environment-detection.md) — `isTesting / isDevelopment / getVersion`

package/docs/offscreen.md

@@ -0,0 +1,57 @@
+# Offscreen Component
+
+Offscreen documents persist in the background (unlike service workers, they don't sleep). Use for WebSocket connections, long-running tasks, audio, clipboard — anything an MV3 service worker can't hold.
+
+**Key facts:**
+
+- Only one offscreen document can exist per extension.
+- Invisible — no UI, no styling needed.
+- Lightweight Manager (no WebManager, no auth, no theme) — see [managers.md](managers.md).
+- Must be created programmatically from the background service worker.
+- Requires the `offscreen` permission in the manifest (opt-in — see [components.md](components.md)).
+
+## Creating from Background
+
+```javascript
+const OFFSCREEN_PATH = 'views/offscreen/index.html';
+
+async function hasOffscreenDocument() {
+  const contexts = await chrome.runtime.getContexts({
+    contextTypes: ['OFFSCREEN_DOCUMENT'],
+    documentUrls: [chrome.runtime.getURL(OFFSCREEN_PATH)],
+  });
+  return contexts.length > 0;
+}
+
+async function setupOffscreenDocument() {
+  if (await hasOffscreenDocument()) return;
+  await chrome.offscreen.createDocument({
+    url: OFFSCREEN_PATH,
+    reasons: ['WEB_RTC'],
+    justification: 'Maintain persistent connection',
+  });
+}
+```
+
+## Offscreen ↔ Background Communication
+
+```javascript
+// From offscreen → background
+chrome.runtime.sendMessage({ action: 'myAction', data: {...} }, (response) => {
+  // handle response
+});
+
+// From background, listen for offscreen messages
+chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
+  if (message.action === 'myAction') {
+    doSomething(message.data).then(sendResponse);
+    return true; // keep channel open for async response
+  }
+});
+```
+
+## See also
+
+- [components.md](components.md) — the seven component contexts + manifest wiring
+- [managers.md](managers.md) — lightweight vs full Manager per context
+- [extension.md](extension.md) — cross-browser API wrapper

package/docs/publishing.md

@@ -0,0 +1,175 @@
+# Publishing
+
+`BXM_IS_PUBLISH=true npm run build` packages AND uploads to extension stores in one step.
+
+## Supported stores
+
+- **Chrome Web Store** (Chrome / Edge / Brave / Opera users)
+- **Firefox Add-ons** (AMO)
+- **Microsoft Edge Add-ons** (separate from Chrome Web Store — Edge Insiders + corporate environments)
+
+Only stores with configured credentials get published to. Unconfigured stores are silently skipped.
+
+## Setup — `.env`
+
+Add store credentials to your project's `.env` (gitignored):
+
+```bash
+# Chrome Web Store
+CHROME_EXTENSION_ID="..."
+CHROME_CLIENT_ID="..."
+CHROME_CLIENT_SECRET="..."
+CHROME_REFRESH_TOKEN="..."
+
+# Firefox Add-ons
+FIREFOX_EXTENSION_ID="..."
+FIREFOX_API_KEY="..."
+FIREFOX_API_SECRET="..."
+
+# Microsoft Edge Add-ons
+EDGE_PRODUCT_ID="..."
+EDGE_CLIENT_ID="..."
+EDGE_API_KEY="..."
+```
+
+## Getting credentials
+
+### Chrome Web Store
+
+1. Create an OAuth client via [Google Cloud Console](https://console.cloud.google.com/) (Web application type)
+2. Enable the [Chrome Web Store API](https://developer.chrome.com/docs/webstore/using_webstore_api/)
+3. Generate a refresh token via the OAuth flow (one-time)
+4. `CHROME_EXTENSION_ID` is in your Chrome Web Store Developer Dashboard URL: `chrome.google.com/webstore/devconsole/<id>`
+
+### Firefox Add-ons
+
+1. Sign in to [Add-on Developer Hub](https://addons.mozilla.org/developers/)
+2. Generate JWT credentials at "Manage API Keys"
+3. `FIREFOX_EXTENSION_ID` matches the `id` field in your manifest's `browser_specific_settings.gecko.id`
+
+### Microsoft Edge Add-ons
+
+1. Sign up for the [Microsoft Edge Add-ons Partner Center](https://partner.microsoft.com/dashboard/microsoftedge)
+2. Generate API credentials in the "API publishing" section
+3. `EDGE_PRODUCT_ID` is the GUID assigned to your extension by Microsoft
+
+## Publish flow
+
+```bash
+BXM_IS_PUBLISH=true npm run build
+```
+
+What happens:
+
+1. `npm run build` runs the full gulp pipeline (build → package → packaged/<browser>/raw + zip)
+2. `gulp/tasks/package.js` detects `BXM_IS_PUBLISH=true`
+3. For each browser, reads the store credentials from `.env`
+4. If credentials are present, uploads the `.zip` via the store's API
+5. Logs success / failure per store; exits non-zero if any upload fails
+
+## Manual upload
+
+Run `npm run build` without `BXM_IS_PUBLISH=true` — you get unsigned `.zip` files per browser under `packaged/`:
+
+```
+packaged/
+├── chromium/<ExtensionName>.zip
+├── firefox/<ExtensionName>.zip
+└── opera/<ExtensionName>.zip
+```
+
+Upload these manually via each store's web dashboard.
+
+## CI / GitHub Actions
+
+For automated releases, store credentials as encrypted GitHub Actions secrets. A typical workflow:
+
+```yaml
+- name: Build + publish
+  env:
+    BXM_IS_PUBLISH:        true
+    CHROME_EXTENSION_ID:   ${{ secrets.CHROME_EXTENSION_ID }}
+    CHROME_CLIENT_ID:      ${{ secrets.CHROME_CLIENT_ID }}
+    CHROME_CLIENT_SECRET:  ${{ secrets.CHROME_CLIENT_SECRET }}
+    CHROME_REFRESH_TOKEN:  ${{ secrets.CHROME_REFRESH_TOKEN }}
+    # ...same for FIREFOX_*, EDGE_*
+  run: npm run build
+```
+
+Same pattern EM uses for its desktop apps. Each store does its own review afterward (Chrome / Firefox: hours to a few days; Edge: typically same day).
+
+## What about Safari?
+
+Safari (Apple) uses a different extension model and requires Xcode-based packaging via `safari-web-extension-converter`. Not currently in scope for BXM's auto-publish. Manual conversion + App Store Connect upload is the route.
+
+## Store listing description (`config/description.md`)
+
+`config/description.md` is the Chrome Web Store listing description. When writing or rewriting it, first read `config/browser-extension-manager.json` (brand), `config/messages.json` (extension name + short description), `src/manifest.json` (permissions/features), and the component JS under `src/assets/js/components/` to understand what the extension actually does — be specific about real features, not generic copy.
+
+**Format:**
+
+```
+[emoji] [Key Feature Headline 1]
+[emoji] [Key Feature Headline 2]
+[emoji] [Key Feature Headline 3]
+[emoji] [Key Feature Headline 4]
+[emoji] [Key Feature Headline 5]
+
+[Extension Name] is [compelling one-sentence pitch]. [Pain point 1]. [Pain point 2]. [Pain point 3].
+If you [target audience description] — [Extension Name] was made for you.
+
+[emoji] How it works
+[Extension Name] [brief mechanism description].
+
+[emoji] [Feature 1]: [One-line description]
+[emoji] [Feature 2]: [One-line description]
+[emoji] [Feature 3]: [One-line description]
+[emoji] [Feature 4]: [One-line description]
+
+[Brief usage instructions — 2-3 sentences].
+No complicated setup. No learning curve. Just [core value proposition].
+
+[emoji] Why [Extension Name] is a game changer
+
+[Benefit 1 title]: [Description].
+[Benefit 2 title]: [Description].
+[Benefit 3 title]: [Description].
+[Benefit 4 title]: [Description].
+[Benefit 5 title]: [Description].
+
+[emoji] The [Extension Name] Difference
+Most people either:
+
+[Alternative 1 that's worse]
+[Alternative 2 that's worse]
+
+[Extension Name] gives you a [better option description].
+[Catchy metaphor with emoji]
+[Closing sentence about who benefits].
+
+[emoji] Install [Extension Name] now and [call to action].
+[Short imperative sentence].
+
+:money_with_wings: Bonus:
+While you're browsing, the extension also finds and applies shopping deals from top partners like Amazon, Capital One, and NordVPN. Get discounts and bonuses without lifting a finger. When you buy through links on our extension, we may earn an affiliate commission.
+
+:locked_with_key: Your privacy is respected — we do not sell or misuse your data. By using our extension, you agree to our terms of service and privacy policy.
+When you buy through links on our extension, we may earn an affiliate commission.
+```
+
+**Rules:**
+
+- **Keep the Bonus section and Privacy section EXACTLY as shown** — do not modify these
+- Use the extension's actual name from `config/messages.json` — do NOT use `{{ brand.name }}` template variables
+- Be specific about features — reference what the code actually does
+- Tone: enthusiastic, conversational, persuasive; emojis for section headers and feature bullets
+- Feature headlines short and punchy (under 50 characters)
+- 300-500 words (excluding the Bonus and Privacy sections)
+
+**After rewriting**, clear stale cached translations — delete `.cache/translations/description/` and the `description` key from `.cache/translate.json` — then have the user run `npm run build` to regenerate translations (see [translations.md](translations.md)).
+
+## See also
+
+- [build-system.md](build-system.md) — packaging pipeline that produces the per-browser zips
+- [hooks.md](hooks.md) — `build:pre` and `build:post` hooks run before/after publish
+- [cli.md](cli.md) — env var conventions

package/docs/templating.md

@@ -0,0 +1,66 @@
+# Templating
+
+HTML views go through a two-step `{{ }}` token replacement during the `gulp/html` task. Same convention as EM and UJM.
+
+## How it works
+
+1. Your view file (`src/views/<component>/index.html`) is templated first — `{{ brand.name }}` etc. resolve against the page-vars object.
+2. The result is injected into [src/config/page-template.html](../src/config/page-template.html) (the framework's outer HTML shell).
+3. The outer template is processed again with the same vars.
+4. Output written to `dist/views/<component>/index.html`.
+
+## Available variables
+
+| Token | Source | Example |
+|---|---|---|
+| `{{ brand.name }}` | `config/browser-extension-manager.json` → `brand.name` | `Tabblar` |
+| `{{ brand.url }}` | `config/browser-extension-manager.json` → `brand.url` | `https://tabblar.com` |
+| `{{ brand.id }}` | `config/browser-extension-manager.json` → `brand.id` | `tabblar` |
+| `{{ page.name }}` | Component name (e.g. `popup`, `pages/dashboard`) | `popup` |
+| `{{ page.path }}` | Full view path | `views/popup/index.html` |
+| `{{ page.title }}` | Page title — defaults to brand name | `Tabblar` |
+| `{{ theme.appearance }}` | Theme appearance: `dark` or `light` | `dark` |
+| `{{ cacheBust }}` | Cache-busting timestamp (build time) | `1715568000` |
+| `{{ version }}` | `package.json#version` | `1.1.10` |
+| `{{ environment }}` | `'production'` or `'development'` | `production` |
+
+## Example usage
+
+```html
+<!-- src/views/popup/index.html -->
+<!doctype html>
+<html>
+<head><title>{{ page.title }}</title></head>
+<body>
+  <h1>Welcome to {{ brand.name }}</h1>
+  <a href="{{ brand.url }}/pricing?ref=ext">Upgrade to Premium</a>
+  <p>Version {{ version }}</p>
+</body>
+</html>
+```
+
+## Page template
+
+[src/config/page-template.html](../src/config/page-template.html) is the outer shell that wraps every view. It contains:
+- `<!doctype html>` + `<html>` boilerplate
+- `<meta>` tags (viewport, charset)
+- A `{{ content }}` slot where the per-component HTML is injected
+- `<link rel="stylesheet">` for the component's `.bundle.css`
+- `<script>` for the component's `.bundle.js`
+- Cache-busting query params via `{{ cacheBust }}`
+
+Consumers don't author this — BXM owns it. If you need to customize per-view, override directly in `src/views/<component>/index.html` (BXM detects when a view provides its own full `<html>` and skips wrapping).
+
+## Customizing page vars
+
+The page-vars object is built by [src/gulp/tasks/html.js](../src/gulp/tasks/html.js). To add a new variable for consumer templates, edit the `buildPageVars()` helper there. Vars added are available in BOTH the view file AND the outer page-template.html.
+
+## Why two passes?
+
+Pass 1 lets a view interpolate something into the outer template. For example, a view can do `<!-- bxm:page-title --> Custom Title <!-- /bxm:page-title -->` (a future feature) and have the value flow into `{{ page.title }}` for the outer template's `<title>`. The pattern keeps simple cases simple (`{{ brand.name }}` Just Works) while leaving room for view → shell metadata flow.
+
+## See also
+
+- [build-system.md](build-system.md) — gulp pipeline including the html task
+- [css.md](css.md) — how the page template references compiled CSS bundles
+- [themes.md](themes.md) — `{{ theme.appearance }}` derivation