@omega.js/extension 0.1.0

package/docs/test-framework.md

@@ -0,0 +1,411 @@
+# Test Framework
+
+Built-in test framework for both @omega.js/extension itself and consumer projects. Jest-like assertion syntax (`expect(actual).toBe(expected)`), four layers, @omega.js/backend/EM-style output.
+
+## Running tests
+
+```bash
+npx omega test                          # consumer: runs YOUR project suites (bare runs never include the framework corpus)
+npx omega test --layer build            # only build-layer suites (plain Node, fast)
+npx omega test --layer background       # only background-layer suites (real MV3 SW)
+npx omega test --layer view             # only view-layer suites (popup/options/sidepanel)
+npx omega test --layer boot             # only boot-layer suites (real consumer extension)
+npx omega test --filter "messaging"     # only suites/tests whose name contains "messaging"
+npx omega test --extended               # run extended suites against REAL external services (Firebase, etc.) — normal mode skips them in-source, never mocks them
+TEST_EXTENDED_MODE=true npx omega test  # same as --extended (the shared, unprefixed env var across all OMEGA frameworks)
+npx omega test --reporter json          # pretty output + machine-readable {"event":"summary",...} line
+OMEGA_TEST_DEBUG=1 npx omega test         # see Chromium/SW stderr (otherwise drained silently)
+```
+
+In @omega.js/extension itself, `npm test` does the same.
+
+All test output is also teed (ANSI-stripped) to `<projectRoot>/logs/test.log`, truncated fresh on each run — same pattern as EM's `test.log` and @omega.js/backend's `test.log`. Grep it after a run instead of scrolling terminal output.
+
+### Selecting which tests run
+
+`npx omega test` takes two independent selectors that compose:
+
+1. **The positional target** selects which test **files** run, by source + path.
+2. **`--filter=<substring>`** matches test **names/descriptions** within the already-selected files.
+
+#### Positional target — select files by source + path
+
+```bash
+# Project suites only (the consumer default — the framework corpus needs an explicit prefix)
+npx omega test
+
+# ONLY project tests (all of them)
+npx omega test project:
+
+# Only project tests matching a path
+npx omega test project:custom-test
+
+# ONLY framework tests (mgr: is the universal cross-framework alias)
+npx omega test mgr:
+
+# ONLY framework tests (extension-specific aliases — equivalent to mgr:)
+npx omega test extension:
+npx omega test framework:
+
+# Framework tests matching a path
+npx omega test mgr:build/config
+npx omega test extension:build/config
+
+# Bare path (no prefix) — PROJECT tests matched by path
+npx omega test build/config
+
+# Both sources — always an explicit choice
+npx omega test full:
+npx omega test full:build/config
+```
+
+The source prefix is standardized across all four OMEGA frameworks:
+
+| Target | Selects |
+|---|---|
+| *(none)* | Project suites only (framework self-test context flips this to the framework suite) |
+| `project:` | ONLY project tests (all of them) |
+| `project:<path>` | Only project tests matching `<path>` |
+| `mgr:` | ONLY framework tests (`mgr:` is the universal alias for "the manager's own tests") |
+| `extension:` / `framework:` | ONLY framework tests (extension-specific aliases, equivalent to `mgr:`) |
+| `mgr:<path>` / `extension:<path>` | Framework tests matching `<path>` |
+| `<path>` (bare) | PROJECT tests matched by `<path>` |
+| `full:` / `full:<path>` | BOTH sources — the only way a consumer run includes the framework suite |
+
+A source-prefixed target excludes the other source entirely; the path part (if any) matches by relative path prefix (relative to each source's `test/` root).
+
+A target that names a path and matches NO file is a hard error: the run prints `No test file matches "<target>"` and exits 1, so a typo'd path, or a suite renamed out from under a target, can never run silently green ([#814](https://github.com/Omega-JS-Stack/omega/issues/814)). A run that named no file (bare, or a bare source prefix) still exits 0 when there is nothing to run. Inside a brand-root fan-out the manager sets `OMEGA_TEST_FANOUT=1` on every forwarded run, and the same miss answers with exit 3 instead: a path another target carries is a no-op here, and the brand run fails only when EVERY target missed ([docs/shared/testing.md](../../../docs/shared/testing.md#brand-root-cp94b)).
+
+#### `--filter` — match test names/descriptions
+
+`--filter` is **orthogonal** to the positional target: it matches a substring against test **names/descriptions** within the files the target already selected. They compose.
+
+```bash
+# All suites, but only tests whose name contains "messaging"
+npx omega test --filter "messaging"
+
+# Project files only, then only tests named "*storage*" within them
+npx omega test project: --filter "storage"
+
+# Combine the target with extended mode
+TEST_EXTENDED_MODE=true npx omega test build/config
+```
+
+## Layers
+
+| Layer | Runs in | Use for |
+|---|---|---|
+| `build` | Plain Node, fast (~ms) | `Manager.getConfig/getManifest/getPackage`, CLI alias resolution, schema/manifest validation, build helpers, `lib/*.js` regex maps + utilities |
+| `background` | Real MV3 service worker via Puppeteer + CDP | Background boot sequence, Firebase auth wiring, messaging listeners, `chrome.runtime.onMessage` handlers |
+| `view` | Chromium tab loading harness extension's popup.html / options.html / sidepanel.html | DOM bindings, Manager surface, @omega.js/client integration, popup ↔ background messaging |
+| `boot` | Real headless Chromium with the **consumer's** `packaged/<browser>/raw/` loaded as unpacked | End-to-end smoke: does the consumer's actual extension boot? Manifest validates? SW comes up? Popup renders? |
+
+`all` (default) runs build → background → view → boot.
+
+## NEVER mock — test against the real harness
+
+Every layer hands your test the **real** runtime, never a hand-rolled fake:
+
+- **No `mockManager`, no fake `chrome`/`browser` objects, no stubbed background/popup contexts.** `background`-layer tests run inside a real MV3 service worker with the real `chrome.*` API; `view`-layer tests run inside a real Chromium tab with the real DOM and real `chrome.runtime` messaging; `boot`-layer tests load the consumer's real packaged extension. Use what the harness gives you (`ctx`, `ctx.manager`, `ctx.page`, the `inspect` callback's `{ extension, page }`, and the browser globals `chrome` / `document` / `window`) — do not reconstruct any of it.
+- **Pure functions (zero I/O) are the only thing you call directly.** A regex map in `lib/*.js`, a string formatter, a config-shape validator — `require` it and assert on its output in a `build`-layer test. That is not mocking; it is calling a pure function. Anything that touches real I/O (storage, messaging, the SW lifecycle, the DOM, the network) runs against the real harness, not a substitute.
+
+### Real external APIs are GATED, NOT mocked
+
+Tests that hit a real external service (Firebase, push, any network call) live in **extended suites** and are gated behind extended mode (`npx omega test --extended` or `TEST_EXTENDED_MODE=true`):
+
+- **Normal mode** (`npx omega test`) **SKIPS** these calls **in-source** — guard them with `ctx.skip(reason)` (or an early return) so the test no-ops when extended mode is off. The external API is **skipped in-source, NOT mocked.** Never stand up a fake Firebase / fake fetch to make a normal-mode run go green.
+- **Extended mode** (`npx omega test --extended`) runs the same code against the **real** service.
+- **Anything an extended test creates externally MUST be cleaned up by the test** — delete the doc/user/record it created (use the suite/group `cleanup: async (ctx) => { ... }` hook, which runs after the last test). Leave no residue in the real backend.
+
+### Extended mode (`TEST_EXTENDED_MODE`)
+
+Extended mode is the opt-in for tests that hit REAL external services (Firebase via @omega.js/client, push, any network call from the background SW / popup / content scripts) instead of skipping them.
+
+- **Skipped by default.** `npx omega test` runs fast and offline-safe — external calls no-op in-source.
+- **Opt in** with `npx omega test --extended` (CLI shorthand) or `TEST_EXTENDED_MODE=true npx omega test` (env var). `TEST_EXTENDED_MODE=1` is also accepted.
+- **Shared, unprefixed name across all OMEGA frameworks.** All four OMEGA frameworks read the SAME `TEST_EXTENDED_MODE` env var (the canonical name is @omega.js/backend's) — no `BXM_`-prefixed variant.
+- **Propagates to every spawned test environment.** The command sets `process.env.TEST_EXTENDED_MODE = 'true'`, which is visible to the in-process Node runner and inherited by Puppeteer's Chromium (background / view / boot layers) since `puppeteer.launch()` inherits `process.env`.
+- **The warning prints.** When on, the command logs `Test mode: extended (real external APIs)` plus a `⚠️` banner (teed to `logs/test.log`); when off it logs `normal (external APIs skipped)`.
+- **Tests gate on `process.env.TEST_EXTENDED_MODE`.** Guard external-service tests with `if (process.env.TEST_EXTENDED_MODE !== 'true') ctx.skip('extended mode off');` (or an early return) so they no-op in normal mode.
+
+### The ONLY two exceptions where a narrow stub is allowed
+
+Mock **nothing** by default. There are exactly two cases where the real dependency genuinely cannot run in the test environment — and even then, stub the *smallest possible seam* (one method / one module), restore it immediately, and comment *why*:
+
+1. **A side effect that would destroy the test run itself.** If invoking the real thing would kill or corrupt the harness — a process-exit, a destructive clean/wipe, or a *recursive re-invocation of a CLI command* (running the real `test`/`clean`/`setup` command from inside a test re-enters the runner) — you may stub *that one module/call* to a no-op, assert the dispatch logic, then restore. (Example: `cli.test.js` stubs the real command modules so testing CLI dispatch doesn't actually run them.)
+2. **A real dependency the test environment can't provide.** When the real object only exists from infra you can't stand up in a `build`-layer unit test, a unit test may hand a minimal stub to verify a narrow side effect — but a real-harness layer (`background`/`view`/`boot`) MUST still cover the wired path where one exists.
+
+If you can run it for real, you must. These exceptions are not a license to unit-test in isolation when a real-harness layer would work.
+
+## Test coverage — every surface gets a test (HARD RULE)
+
+A feature is not done when it works — it's done when every surface it exposes is covered in the layer that owns that surface:
+
+| Coverage | Layer | Proves |
+|---|---|---|
+| **Logic** | `build` / `background` | The feature's functions do the right thing when called directly (real Manager, real `chrome.*`, real storage/messaging) |
+| **UI** | `view` | The feature's interface is WIRED — a real event on the real DOM triggers the behavior and the visible result appears |
+| **End-to-end** | `boot` | The feature survives in the consumer's actual packaged extension (extend the boot suite's `inspect` assertions) |
+
+**Skipping a layer is the exception, not the default.** A layer may be skipped ONLY when the feature genuinely has no surface there — a pure build-time utility has no UI; a CSS-only tweak has no logic to call. Convenience is never a reason: "the logic test already covers it" does NOT excuse the UI test — logic tests prove the logic, UI tests prove the wiring (a button can come unhooked while every logic test stays green), boot tests prove the packaging. When in doubt, write the test.
+
+## `OMEGA_TEST_MODE=true` — the canonical "we're in tests" signal
+
+Both @omega.js/extension test runners set `OMEGA_TEST_MODE=true` in spawned child envs. That powers `manager.isTesting()` (and `Manager.isTesting()` static) — the cross-context helper anything in @omega.js/extension/consumer code should check when behavior needs to differ in tests. See [environment-detection.md](environment-detection.md).
+
+Consumers writing their own tests get this automatically when running through `npx omega test`. To set it manually in another runner:
+
+```json
+"test": "OMEGA_TEST_MODE=true vitest"
+```
+
+## Test discovery
+
+- **Framework defaults**: `<@omega.js/extension>/dist/test/suites/**/*.js`
+- **Consumer suites**: `<cwd>/test/**/*.js`
+
+**The underscore convention** (`DISCOVERY_IGNORE` in `src/test/runner.js`): `_`-prefixed FILES (`test/_init.js`, `test/page/_helper.js`) and everything under a `_`-prefixed DIRECTORY at **any depth** (`test/_fixtures/**`, `test/boot/_private/**`) are excluded from suite discovery. Put shared helpers, fixture data, and non-test support files in `_`-prefixed paths — e.g. `test/_fixtures/`, `test/_helpers/`. The runner still specifically loads `test/_init.js` as the lifecycle hook. Matches the same convention in @omega.js/backend/EM/UJM. Files load alphabetically.
+
+**Framework's boot suites are scoped to @omega.js/extension self-test runs only.** When a consumer runs `npx omega test`, the framework's `dist/test/suites/boot/**` is excluded from discovery (those tests assert on @omega.js/extension's internal fixture extension). Consumers write their own boot tests under `<cwd>/test/boot/`. See [test-boot-layer.md](test-boot-layer.md).
+
+## `test/_init.js` — pre-test lifecycle hook
+
+The runner loads an optional `test/_init.js` from **both** test roots — the framework (`<@omega.js/extension>/test/_init.js`) and the consumer project (`<cwd>/test/_init.js`) — and runs it **once, before any suite** (it is NOT itself run as a test; the `_`-prefix keeps it out of discovery). Mirrors the same hook in @omega.js/backend/EM/UJM so all four frameworks share one shape.
+
+The module **must export a function** — `module.exports = (ctx) => ({ ... })` — called with `{ projectRoot }` and returning the hook object. It may declare:
+
+- `async setup({ projectRoot })` — runs once before the suites, e.g. to scaffold a fixture file the boot layer needs.
+
+There is **no `cleanup` hook** and **no `accounts` field** (unlike @omega.js/backend — these frameworks have no auth/user system): tests clean up after themselves, so there is nothing project-level to tear down.
+
+```javascript
+// <cwd>/test/_init.js
+const fs = require('fs');
+const path = require('path');
+
+module.exports = ({ projectRoot }) => ({
+  async setup() {
+    // Seed any fixture a suite needs before it runs.
+    fs.mkdirSync(path.join(projectRoot, '.temp'), { recursive: true });
+  },
+});
+```
+
+## Test file shapes
+
+Three forms — pick whichever fits.
+
+### Suite (sequential, share state, stop on first failure)
+
+```js
+module.exports = {
+  type: 'suite',
+  layer: 'background',
+  description: 'storage round-trip',
+  cleanup: async (ctx) => { /* runs after the last test */ },
+  tests: [
+    {
+      name: 'set returns without throwing',
+      run: async (ctx) => {
+        await chrome.storage.local.set({ k: 'v' });
+        ctx.expect(true).toBe(true);
+      },
+    },
+    {
+      name: 'get returns the just-set value',
+      run: async (ctx) => {
+        const out = await chrome.storage.local.get('k');
+        ctx.expect(out.k).toBe('v');
+      },
+    },
+  ],
+};
+```
+
+Tests share `ctx.state` across the suite. If one fails, remaining tests are skipped (`stopOnFailure: false` to disable).
+
+### Group (sequential, share state, run all regardless of failures)
+
+```js
+module.exports = {
+  type: 'group',
+  layer: 'build',
+  description: 'config defaults',
+  tests: [ /* same shape as suite */ ],
+};
+```
+
+### Standalone (single test per file)
+
+```js
+module.exports = {
+  layer: 'build',
+  description: 'manifest_version is 3',
+  run: (ctx) => {
+    const m = Manager.getManifest();
+    ctx.expect(m.manifest_version).toBe(3);
+  },
+};
+```
+
+### Array form (treated as a group)
+
+```js
+module.exports = [
+  { name: 'test 1', run: (ctx) => { /* ... */ } },
+  { name: 'test 2', run: (ctx) => { /* ... */ } },
+];
+```
+
+## The `ctx` object
+
+Every `run` / `cleanup` callback receives `ctx`:
+
+- `ctx.expect` — Jest-compatible assertion library
+- `ctx.state` — shared object across tests in a suite/group
+- `ctx.skip(reason)` — throw to skip the current test at runtime
+- `ctx.layer` — current layer name (`'build' | 'background' | 'view' | 'boot'`)
+- `ctx.manager` — present on background-layer tests (the framework Manager instance)
+- `ctx.page` — present on view-layer tests (the loaded tab's window)
+
+Boot-layer tests use `inspect: async ({ extension, page, expect, projectRoot }) => { ... }` instead of `run`. See [test-boot-layer.md](test-boot-layer.md).
+
+## `expect()` matchers
+
+Same Jest-compatible surface across all layers:
+
+```js
+ctx.expect(actual).toBe(expected);                     // strict ===
+ctx.expect(actual).toEqual(expected);                  // deep equality
+ctx.expect(actual).toBeTruthy() / .toBeFalsy()
+ctx.expect(actual).toBeDefined() / .toBeUndefined()
+ctx.expect(actual).toBeNull()
+ctx.expect(actual).toContain(item);                    // string or array
+ctx.expect(actual).toHaveProperty('key')
+ctx.expect(actual).toMatch(/regex/)
+ctx.expect(actual).toBeInstanceOf(Class)
+ctx.expect(actual).toBeGreaterThan(n) / .toBeLessThan(n)
+await ctx.expect(fn).toThrow(/regex/)                  // async — fn may be async
+ctx.expect(actual).not.toBe(expected)                  // negation: every matcher
+```
+
+## Consumer pattern — use the public Manager API
+
+Don't `require('json5')` or other transitive @omega.js/extension deps directly from consumer tests — they're not in your `package.json` and the resolution path is fragile. Instead use @omega.js/extension's public API:
+
+```js
+const Manager = require('@omega.js/extension/build');
+
+// Parsed JSON5 — same logic the framework uses internally
+const config   = Manager.getConfig();
+const manifest = Manager.getManifest();
+
+// Borrow any of @omega.js/extension's bundled deps without listing them yourself
+const JSON5 = Manager.require('json5');
+```
+
+This is the same pattern EM and @omega.js/backend consumers use — assert on framework API output rather than re-implementing parsing/loading in every test.
+
+## Build-layer example
+
+```js
+// test/build/config.test.js
+const Manager = require('@omega.js/extension/build');
+
+module.exports = {
+  type: 'suite',
+  layer: 'build',
+  description: 'config has required brand fields',
+  tests: [
+    {
+      name: 'brand.id is set',
+      run: (ctx) => {
+        ctx.expect(Manager.getConfig().brand.id).toBeTruthy();
+      },
+    },
+    {
+      name: 'cloud.config.projectId matches brand.id',
+      run: (ctx) => {
+        const cfg = Manager.getConfig();
+        ctx.expect(cfg.cloud.config.projectId).toBe(cfg.brand.id);
+      },
+    },
+  ],
+};
+```
+
+## Background-layer example
+
+```js
+// test/background/messaging.test.js
+module.exports = {
+  type: 'suite',
+  layer: 'background',
+  description: 'chrome.runtime.* surface in real SW',
+  tests: [
+    {
+      name: 'chrome.runtime.id is a non-empty string',
+      run: async (ctx) => {
+        ctx.expect(typeof chrome.runtime.id).toBe('string');
+        ctx.expect(chrome.runtime.id.length).toBeGreaterThan(0);
+      },
+    },
+    {
+      name: 'storage.local round-trip',
+      run: async (ctx) => {
+        await chrome.storage.local.set({ k: 'v' });
+        const out = await chrome.storage.local.get('k');
+        ctx.expect(out.k).toBe('v');
+      },
+    },
+  ],
+};
+```
+
+## View-layer example
+
+```js
+// test/view/popup.test.js
+module.exports = {
+  type: 'suite',
+  layer: 'view',
+  context: 'popup',     // popup | options | sidepanel — which HTML to open
+  description: 'popup DOM + chrome surface',
+  tests: [
+    {
+      name: 'document body has data-omega-context="popup"',
+      run: async (ctx) => {
+        ctx.expect(document.body.dataset.bxmContext).toBe('popup');
+      },
+    },
+    {
+      name: 'popup ↔ background messaging round-trip',
+      run: async (ctx) => {
+        const reply = await chrome.runtime.sendMessage({ type: 'extension:test:ping' });
+        ctx.expect(reply.pong).toBe(true);
+      },
+    },
+  ],
+};
+```
+
+For boot-layer (`inspect: async ({ extension, page, expect }) => { ... }`) tests, see [test-boot-layer.md](test-boot-layer.md).
+
+## How browser-layer tests are shipped to the SW/tab
+
+MV3 service workers have a strict CSP that forbids `eval` / `new Function` / `new AsyncFunction`. So we can't rebuild test functions from a string inside the SW.
+
+Instead: each test's source is **baked as a literal async-function expression** directly into the payload at runner build-time, then evaluated as top-level Runtime.evaluate (CDP-exempt from CSP). No inner `eval` happens inside the SW. Tests communicate results back via `console.log('__BXM_TEST__' + JSON.stringify(evt))`, which the Node-side runner parses via CDP `Runtime.consoleAPICalled`.
+
+You don't have to think about this — write tests in normal JS — but it's why test bodies must be **self-contained**: they can't close over their file's module scope. Use `ctx`, `expect`, `state`, and the browser globals (`chrome`, `document`, `window`) only.
+
+## Why a custom harness instead of Jest / Vitest?
+
+Browser-context code (background SW, popup DOM, content script) only runs inside Chromium. This is exactly why @omega.js/extension does not let you mock: a faked `chrome.runtime` (Jest's jsdom can't reproduce it faithfully) or a stubbed API (`webextension-polyfill` provides one, but it doesn't catch real SW lifecycle bugs) passes tests while shipping broken extensions. Puppeteer gives a real Chromium with real `chrome.*` APIs, so the harness is the real thing — not a substitute you assert against. See [NEVER mock](#never-mock--test-against-the-real-harness).
+
+Same trade-off EM ran into with Electron — tests must run inside the real runtime, so the framework owns the runner.
+
+## See also
+
+- [test-boot-layer.md](test-boot-layer.md) — boot layer deep-dive (loads consumer's actual packaged extension)
+- [environment-detection.md](environment-detection.md) — `Manager.isTesting()` / `isDevelopment()` / etc.

package/docs/themes.md

@@ -0,0 +1,89 @@
+# Themes
+
+@omega.js/extension ships two themes plus a template for new ones. Themes vendor their own SCSS + JS + Bootstrap-compatible variable system.
+
+## Available themes
+
+| Theme | Source | What it provides |
+|---|---|---|
+| `bootstrap` | `dist/assets/themes/bootstrap/` (vendored from @omega.js/web) | Pure Bootstrap 5.3+. Use when you want unopinionated Bootstrap. |
+| `classy` | `dist/assets/themes/classy/` (vendored from @omega.js/web) | Bootstrap 5 + custom design system (colors, typography, components). The "branded" theme. |
+| `_template` | `dist/assets/themes/_template/` (vendored from @omega.js/web) | Template for creating new themes. Underscore prefix excludes it from production builds. |
+
+## Activating a theme
+
+Set in `config/omega.json5`:
+
+```jsonc
+{
+  theme: {
+    id: 'classy',         // 'bootstrap' | 'classy' | '<your-theme>'
+    appearance: 'dark',   // 'dark' | 'light' (optional — drives {{ theme.appearance }})
+  },
+}
+```
+
+The bundler's `__theme__` alias resolves to the package's `dist/assets/themes/<id>/` so consumer JS can do `import '__theme__/_theme.js'` and get the right theme's entry point. SCSS gets the same via the `theme` load-path entry (see [css.md](css.md)).
+
+### theme.id is shared; the theme SET is per-framework
+
+`theme.id` is a shared omega.json5 key, but each framework ships its own themes — a brand whose WEBSITE theme is a consumer-local id has nothing under the extension's `dist/assets/themes/<id>/`. Both resolve sites (the sass load path and the bundler's `__theme__`) go through [src/lib/theme.js](../src/lib/theme.js): an id this framework doesn't ship falls back to `classy` with ONE warning naming `theme.id`, the unknown value, and the extension's valid themes — never a raw sass `Can't find stylesheet to import` ([#261](https://github.com/Omega-JS-Stack/omega/issues/261)). Give the extension its own theme without touching the brand's:
+
+```jsonc
+{
+  targets: {
+    extension: { theme: { id: 'classy' } },
+  },
+}
+```
+
+## Theme structure
+
+```
+dist/assets/themes/<theme-id>/   (vendored — the SSOT is @omega.js/web/themes/)
+├── _config.scss      # Theme variables (with !default so consumers can override)
+├── _theme.scss       # Theme entry — @forward + @use
+├── scss/             # Theme-specific SCSS (components, utilities)
+└── js/               # Theme-specific JS (e.g. Bootstrap's modal/popper init)
+└── _theme.js         # Theme JS entry (exposes Bootstrap globals to window.bootstrap)
+```
+
+## Creating a new theme
+
+1. Copy `_template/` into your CONSUMER project's theme dir (or add the theme to @omega.js/web's `themes/` — the one tree every target vendors)
+2. Rename the directory (remove the `_` prefix — that's only for the template).
+3. Customize `_config.scss` — variables like `$primary`, `$font-family-base`, etc.
+4. Add theme-specific styles under `scss/`.
+5. Update `_theme.scss` to forward your overrides.
+6. Activate via `config/omega.json5` → `theme.id: 'my-theme'`.
+
+## Overriding theme variables
+
+In a consumer's `src/assets/css/main.scss`:
+
+```scss
+// Override before @use to take effect
+@use 'omega-extension' as * with (
+  $primary: #2563EB,
+  $secondary: #FFA500,
+);
+@use 'theme' as *;
+```
+
+`!default` flags on theme variables let `with (...)` overrides win.
+
+## `{{ theme.appearance }}`
+
+If `config.theme.appearance === 'dark'`, the HTML page template adds `class="dark"` (or `data-bs-theme="dark"`, depending on theme) to `<html>`. Theme SCSS can then key off `:root.dark` / `[data-bs-theme="dark"]` for dark-mode variants.
+
+Consumer views can use `{{ theme.appearance }}` in their HTML to apply per-page tweaks. See [templating.md](templating.md).
+
+## Why not Tailwind?
+
+Themes are SCSS-first because @omega.js/extension's roots are Bootstrap-based and most @omega.js/extension consumers already use Bootstrap-style class names (`.btn`, `.card`, `.modal`). Tailwind requires a build step (PostCSS + content scanning) that would complicate the lean gulp pipeline. If a future theme wants Tailwind, add it to @omega.js/web's `themes/` and wire its own build hook.
+
+## See also
+
+- [css.md](css.md) — SCSS load paths and component overrides
+- [components.md](components.md) — component view + styles + script structure
+- [build-system.md](build-system.md) — sass/esbuild pipeline

package/docs/translations.md

@@ -0,0 +1,73 @@
+# Translations
+
+`npm run build` automatically translates `config/messages.json` (and `config/description.md`) to the languages set in `translation.languages` (omega.json5). Only missing translations are generated — existing translations live in the committed `translations/` cache and are preserved.
+
+## Languages produced
+
+Exactly the codes listed in `translation.languages` — there is no fixed set. Unset means translation is OFF (the build logs one skip line). The shared contract, including the supported-code list, is docs/shared/translation.md in the Omega repo.
+
+(Output written to `dist/_locales/<lang>/messages.json`, then packaged to `packaged/<browser>/raw/_locales/`.)
+
+## How it works
+
+[src/gulp/tasks/translate.js](../src/gulp/tasks/translate.js):
+
+1. Reads `config/messages.json` (source of truth — author all your strings here).
+2. For each configured language, loads the committed cache at `translations/<lang>/messages.json` (source-string hash → translated message).
+3. Sends ONLY the uncached strings to the translation provider (per-key incremental).
+4. Saves the results back into the cache, then composes `dist/_locales/<lang>/messages.json` from source + cache — a miss falls back to English so the file is always complete.
+
+`config/description.md` translates the same way, whole-document, cached as `translations/<lang>/description.md` with a source-hash marker — editing the source retranslates it.
+
+Existing translations are NEVER overwritten — once a string is translated, it stays until the source string changes. Edit the cache file directly if you want to change a translation.
+
+## What gets translated
+
+Keys with a `message` field:
+
+```jsonc
+{
+  appName: {
+    message: 'Tabblar — Workspace & Tab Manager',
+    description: 'The name of the extension.'
+  },
+  appDescription: {
+    message: 'Powerful tab and workspace manager...',
+    description: 'The description of the extension.'
+  }
+}
+```
+
+Only the `message` values are sent for translation; the `description` field stays English (it documents the key for maintainers and the store review).
+
+## What the scaffold seeds
+
+`config/messages.json` is scaffolded once (never overwritten) with the brand already rendered in: `appName`, `appNameShort` and `btnTooltip` from `brand.name`, and `appDescription` from `brand.description` when it fits the 200-character Chrome Web Store cap — a longer or absent description falls back to "The official &lt;brand&gt; browser extension." ([#573](https://github.com/Omega-JS-Stack/omega/issues/573)). Edit any of them afterward; setup will not touch them again.
+
+## Manifest `__MSG_*__` placeholders
+
+`src/manifest.json` references locale keys via `__MSG_<key>__`:
+
+```jsonc
+{
+  name: '__MSG_appName__',
+  description: '__MSG_appDescription__',
+}
+```
+
+Chrome resolves these at install time using the user's browser locale, falling back to `default_locale` (set in the manifest).
+
+The [test-framework.md](test-framework.md) ships a `locales.test.js` pattern that verifies every `__MSG_*__` placeholder in your manifest has a definition in `messages.json` — catches drift between manifest and i18n catalog before users see broken store listings.
+
+## Disabling translations
+
+Leave `translation.languages` unset (or empty) in omega.json5 — translation is opt-in and off by default.
+
+## Cost / API key
+
+The default provider is `claude`: it rides the locally-installed Claude Code via `@anthropic-ai/claude-agent-sdk` (declared by this framework), billed to your Claude subscription — no API key. `translation.provider: 'chatgpt'` uses the OpenAI API instead (needs `OPENAI_API_KEY`). Either way the cost is one-time per language per changed string — typically pennies.
+
+## See also
+
+- [build-system.md](build-system.md) — gulp pipeline including translate task
+- [publishing.md](publishing.md) — auto-publishing to Chrome / Firefox / Edge stores

package/docs/verts.md

@@ -0,0 +1,67 @@
+# Verts — the `data-omega-vert` auto-bind
+
+@omega.js/extension page surfaces auto-bind the OMEGA verts (ads) system (monorepo
+`docs/web/ads-system.md`, phase 4): drop a `[data-omega-vert]` element into a
+popup/options/sidepanel/page view and the surface Manager hands it to
+`@omega.js/client`'s verts module — zero consumer JS, same element vocabulary
+as the web `verts/unit` section and @omega.js/desktop.
+
+```html
+<div data-omega-vert data-omega-vert-size="banner"></div>
+```
+
+## What the wiring does
+
+`lib/verts.js wireAds()` (called by each page-surface Manager's `initialize()`
+after `omega.initialize()`) binds every `[data-omega-vert]` element present at
+boot AND inserted later (MutationObserver), marking bound hosts
+`data-omega-vert-bound="house"`. Everything after the bind lives in the client
+module (`@omega.js/client/modules/verts.js`): lazy arming near the viewport, a
+sandboxed iframe to the resolved in-house source's `/omega/verts/serve`,
+origin-validated postMessage, host-owned rotation + staleness recovery, and
+no-fill collapse (the host hides itself).
+
+**Content scripts, background, and offscreen do NOT auto-bind.** Content
+scripts follow the `lib/icons.js` rule — scanning a HOST page's DOM would
+mount verts into arbitrary websites; background/offscreen have no user-facing
+DOM.
+
+## House/company lane ONLY — no AdSense
+
+Extension surfaces never run the AdSense provider lane (store policy — and
+the scaffolded MV3 `extension_pages` CSP blocks the remote script anyway).
+The wiring pins `type: 'house'` on every mount — the pin wins over the
+element's `data-omega-vert` type, so even a shared omega.json5 that carries
+`advertising.providers.adsense` (the web target uses it) can only
+ever reach the house/company inventory here. Pinned by the build-layer
+`verts-binding` suite.
+
+## Config
+
+The `advertising` and `company` sections of `config/omega.json5` ride the
+build snapshot (`OMEGA_BUILD_JSON`, baked into every bundle) into every surface:
+
+```json5
+advertising: {
+  providers: {
+    inhouse: { source: 'company' },  // 'self' | 'company' | full URL
+  },
+  tags: ['music', 'audio-tools'],    // contextual targeting inputs
+}
+```
+
+No `advertising` key (or no resolvable inhouse source) → bound units collapse
+quietly. Nothing else to configure.
+
+## Element vocabulary
+
+| Attribute | Meaning |
+|---|---|
+| `data-omega-vert` | binds the element (type value is ignored in extensions — house pin) |
+| `data-omega-vert-size` | size preset (`banner`/`leaderboard`/`rectangle`/…) or raw px max-height |
+| `data-omega-vert-id` | pin a specific vert |
+| `data-omega-vert-tags` | comma-separated contextual tags for this unit |
+| `data-omega-vert-bound` | set by the wiring (`"house"`) once bound — observability/debugging |
+
+Units emit `omega-vert:fill` / `omega-vert:no-fill` / `omega-vert:click` /
+`omega-vert:reload` CustomEvents on the host (bubbling) for app-side hooks.