@omega.js/extension 0.1.0

package/docs/audit.md

@@ -0,0 +1,67 @@
+# Audit Workflow
+
+Full-project audit for @omega.js/extension — runs against a CONSUMER extension or the FRAMEWORK repo itself (scope auto-detected). Invoked via the `omega:extension` skill (`/omega:extension audit`) or any "audit this extension/project" request.
+
+Every check has a stable ID, a severity, and a scope. Findings are reported as `ID @ file:line`, fixed one at a time, then re-verified. The tables below do NOT restate the rules — each check links to the doc that owns the rule and the fix.
+
+## Protocol
+
+1. **Detect scope** — read `package.json`: `name` is `@omega.js/extension` → **framework audit** (U + @omega.js/extension + F checks); `@omega.js/extension` in (dev)dependencies → **consumer audit** (U + @omega.js/extension checks).
+2. **Run the catalog** — every check matching the scope. Search with Grep/Glob/Read over `src/` (+ `test/`, `config/`, `hooks/`); ALWAYS exclude `dist/`, `packaged/`, `node_modules/`, `_legacy/`, `_backup/`, `.temp/`, `.cache/`. Record each finding as `ID @ file:line` + a one-line description.
+3. **Persist the report** — write the findings list to `.temp/audit/claude-audit.md` so a long fix loop survives session breaks. Summarize counts by severity in chat.
+4. **Fix loop** — TodoWrite per finding, highest severity first, ONE at a time: mark in-progress → root cause → fix → verify → complete. Ask before structural or destructive fixes (file deletions, component restructures, manifest permission changes).
+5. **Re-verify** — re-run every check that produced findings until clean; finish with `npx omega test` (must be green).
+6. **Doc parity** — if fixes changed behavior, update README / the framework guide / `docs/<topic>.md` / CHANGELOG in the same change set.
+
+Severity: **CRIT** security or broken functionality · **HIGH** hard-rule violation · **MED** convention drift · **LOW** optional improvement.
+Scope: **C** consumer · **F** framework repo · **B** both.
+
+## Universal checks (U-xx)
+
+Mirrored across all four OMEGA frameworks — same ID means the same check everywhere.
+
+| ID | Sev | Scope | Check |
+|----|-----|-------|-------|
+| U-01 | HIGH | B | Every feature has tests at EVERY layer it surfaces (build / background / view / boot) — never mocked, real harness only ([test-framework.md](test-framework.md)) |
+| U-02 | HIGH | B | Test hygiene — real-external-API tests gated behind `TEST_EXTENDED_MODE` in-source via `ctx.skip(...)` (not mocked); no tests that assert nothing ([test-framework.md](test-framework.md)) |
+| U-03 | CRIT | B | XSS — inline `omega.utilities().escapeHTML(value)` at EVERY DOM sink, `sanitizeURL(url)` at executable URL sinks, zero local escape helpers ([xss-prevention.md](xss-prevention.md)) |
+| U-04 | HIGH | B | @omega.js/client owns Firebase — no direct `firebase` imports anywhere; `omega.auth()` / `.firestore()` ([common-mistakes.md](common-mistakes.md)) |
+| U-05 | HIGH | C | No @omega.js/extension transitive deps installed in the consumer `package.json` (`firebase`, `@omega.js/client`, `json5`, …) — the bundler's framework-deps hook / `Manager.require()` resolve them ([common-mistakes.md](common-mistakes.md), [the framework guide](../../../docs/extension/index.md) §Dependency Resolution) |
+| U-06 | HIGH | B | Env behavior gated on the INTENTIONAL check — `isProduction()` or `isDevelopment() \|\| isTesting()`, never `!isDevelopment()`; no ad-hoc `process.env.BXM_*` reads where a helper exists ([environment-detection.md](environment-detection.md)) |
+| U-07 | HIGH | B | Config canon — `config/omega.json5` + `src/manifest.json` match the documented shapes; canonical cross-framework blocks (`brand`, `cloud.{provider,config}`, …) not reinvented ([defaults.md](defaults.md), [components.md](components.md)) |
+| U-08 | CRIT | B | No private credentials committed — store-publishing credentials, `.env`, tokens, secret keys; `.gitignore` covers them ([publishing.md](publishing.md)). (The Firebase WEB `apiKey` is public by design — do NOT flag it.) |
+| U-09 | HIGH | B | Source discipline — nothing edited in `dist/` or `packaged/` (including `dist/manifest.json`); no live code referencing `_legacy/` / `_backup/` ([build-system.md](build-system.md)) |
+| U-10 | MED | B | Doc parity — README / the framework guide / `docs/` / CHANGELOG match shipped behavior; the docs index lists every `docs/*.md`; no stale names for renamed commands/patterns |
+| U-11 | MED | B | SSOT/DRY — no duplicated constants/config/logic; one authoritative home per value, imported everywhere else |
+| U-12 | MED | B | JS conventions — file structure, JSDoc, short-circuit returns, leading logical operators, `fs-jetpack`, one `module.exports` per file (global `js:patterns` skill + [the framework guide](../../../docs/extension/index.md) §File Conventions) |
+| U-13 | MED | B | Dead code & stale patterns — no orphaned `src/` files nothing imports; no unused components/views; inventory TODO/FIXME (report only) |
+| U-14 | LOW | B | Dependency health — review `npm outdated` / `npm audit`; apply fixes via the `general:update-packages` workflow (includes supply-chain checks) |
+
+## extension-specific checks
+
+| ID | Sev | Scope | Check |
+|----|-----|-------|-------|
+| EXT-01 | HIGH | B | Cross-browser wrapper — `extension.*` everywhere; never raw `chrome.*` / `browser.*` in component code ([extension.md](extension.md)) |
+| EXT-02 | HIGH | B | Component structure — views are HTML FRAGMENTS (not full documents); three parts at conventional paths (view + styles + script) ([components.md](components.md)) |
+| EXT-03 | HIGH | B | Service-worker-safe background — no DOM/`window`/`document` APIs in `background`; DOM-needing work goes to an offscreen document ([components.md](components.md), [offscreen.md](offscreen.md), [common-mistakes.md](common-mistakes.md)) |
+| EXT-04 | MED | C | Permissions justified — every manifest permission maps to a feature actually used (`offscreen` ↔ offscreen component, `tabs` ↔ auth sync, …); remove unused ones ([components.md](components.md), [auth.md](auth.md), [offscreen.md](offscreen.md)) |
+| EXT-05 | MED | C | Store listing — `config/description.md` follows the listing format (Bonus/Privacy sections intact); stale translation caches cleared after description changes ([publishing.md](publishing.md), [translations.md](translations.md)) |
+| EXT-06 | MED | B | Accessibility basics in popup/options/sidepanel/pages views — meaningful `alt` text, labeled form fields, real `<button>`/`<a>` elements (no clickable `div`s) |
+
+## Framework-repo checks (F-xx)
+
+Only when auditing the @omega.js/extension repo itself. Mirrored across the four frameworks.
+
+| ID | Sev | Check |
+|----|-----|-------|
+| F-01 | MED | Sister parity — mirrored sections (config shapes, test contract, guide skeleton, shared env/test conventions) in sync with UJM / @omega.js/backend / EM; deviations are deliberate and documented |
+| F-02 | HIGH | Consumer-shipped defaults in sync — what `ensureTarget()` scaffolds (`src/defaults/` via `FILE_MAP`, every verb) matches current conventions and docs ([defaults.md](defaults.md)) |
+| F-03 | MED | Docs completeness — every `docs/*.md` indexed in the framework guide; every subsystem has a doc; no "(planned)" links for things that have shipped |
+| F-04 | HIGH | `npx omega test mgr:` green before treating the audit as complete |
+
+## See also
+
+- [xss-prevention.md](xss-prevention.md) — the escaping rules behind U-03
+- [extension.md](extension.md) — the wrapper rule behind EXT-01
+- [components.md](components.md) — the structure rules behind EXT-02 / EXT-03 / EXT-04
+- [test-framework.md](test-framework.md) — the layers behind U-01 / U-02

package/docs/auth.md

@@ -0,0 +1,149 @@
+# Cross-Context Auth
+
+Browser extensions have multiple isolated JavaScript contexts (background SW, popup, options, sidepanel, pages) — each runs its own Firebase instance. @omega.js/extension syncs them via messaging so a sign-in in one context is reflected in all of them without using `chrome.storage`.
+
+## The core idea
+
+**Background.js is the source of truth.** Other contexts compare their auth state with background's on load, and sync up if different. Sign-in/sign-out events are broadcast from background to everyone.
+
+This pattern avoids `chrome.storage` (no cross-context tokens on disk, no race conditions). Firebase persists session state in IndexedDB per-context.
+
+## Sign-in flow
+
+```
+User clicks .omega-signin (in popup/options/sidepanel/page)
+  ↓
+openAuthPage() opens https://<brand.url host>/token?authSourceTabId=<n>
+  ↓
+Website authenticates, redirects to /token?authToken=xxx
+  ↓
+background.js's tabs.onUpdated listener detects the brand-site URL + authToken param
+  ↓
+background.js calls signInWithCustomToken(authToken)
+  ↓
+background.js broadcasts the token to all open contexts via chrome.runtime.sendMessage
+  ↓
+background.js closes the /token tab, reactivates original tab (using authSourceTabId)
+  ↓
+Open contexts receive the broadcast, signInWithCustomToken() locally
+```
+
+## Context-load flow
+
+When a popup/options/sidepanel/page boots:
+
+```
+Context loads
+  ↓
+Web Manager initializes, waits for auth to settle (auth.listen({ once: true }))
+  ↓
+Sends `omega:syncAuth` message to background, including local UID
+  ↓
+Background compares UIDs:
+  - Same UID (including both null) → in sync, no action
+  - Different UID, background signed in   → background fetches fresh custom token from server,
+                                            sends to context, context signs in
+  - Background signed out, context signed in → tells context to sign out
+```
+
+## Sign-out flow
+
+```
+User clicks .omega-signout
+  ↓
+Web Manager signs out that context's Firebase
+  ↓
+setupSignOutListener() detects sign-out, sends `omega:signOut` to background
+  ↓
+background.js signs out its Firebase
+  ↓
+background.js broadcasts `omega:signOut` to all other contexts
+  ↓
+All contexts sign out
+```
+
+## Required setup
+
+1. **Set `brand.url`** in `config/omega.json5` — the sign-in round trip lands on the
+   brand website's `/token` page, and background.js watches for that host:
+   ```jsonc
+   {
+     brand: {
+       id: 'tabblar',
+       url: 'https://tabblar.com',   // ← required for the /token redirect flow
+     },
+   }
+   ```
+   (`cloud.config.authDomain` is the brand host too — the website build
+   self-hosts Firebase's `/__/auth/*` handler — but it plays no role in this
+   flow; the extension only watches `brand.url`.)
+2. **Add `tabs` permission** to `src/manifest.json` — needed for `chrome.tabs.onUpdated` listener that detects the `/token` redirect.
+
+## Functions in `lib/auth-helpers.js`
+
+[src/lib/auth-helpers.js](../src/lib/auth-helpers.js):
+
+| Function | Purpose |
+|---|---|
+| `syncWithBackground(context)` | Called on context boot. Compares context's UID with background's, syncs if different. |
+| `setupAuthBroadcastListener(context)` | Listens for sign-in / sign-out broadcasts from background. |
+| `setupSignOutListener(context)` | Notifies background when this context signs out. |
+| `setupAuthEventListeners(context)` | Registers the extension's `omega-signin` and `omega-account` click triggers on @omega.js/client's shared registry. |
+| `openAuthPage(context, options)` | Opens a page on the brand site (`options.path`, default `/token`) with `authSourceTabId` for tab restoration. |
+
+Every popup/options/sidepanel/page Manager calls these automatically in `initialize()`. See [managers.md](managers.md).
+
+## Auth button classes
+
+Add these classes to HTML elements to wire up auth UI without writing JS:
+
+| Class | Action |
+|---|---|
+| `.omega-signin` | Opens `/token` page on website. After authentication, signs in across all contexts. |
+| `.omega-signout` | Signs out via Web Manager. Notifies background, which broadcasts to other contexts. |
+| `.omega-account` | Opens `/account` page on website in a new tab. Same brand-URL resolution as `.omega-signin`. |
+
+## Reactive bindings
+
+Web Manager exposes `data-omega-bind` attributes for show/hide/text/attr based on auth state:
+
+```html
+<!-- Sign-in button shown when logged out -->
+<button class="btn omega-signin" data-omega-bind="@show !auth.user">
+  Sign In
+</button>
+
+<!-- Account UI shown when logged in -->
+<div data-omega-bind="@show auth.user" hidden>
+  <img data-omega-bind="@attr src auth.user.photoURL">
+  <span data-omega-bind="@text auth.user.displayName"></span>
+  <button class="omega-account">Account</button>
+  <button class="omega-signout">Sign Out</button>
+</div>
+```
+
+| Binding | Behavior |
+|---|---|
+| `@show auth.user` | Element visible only when signed in |
+| `@show !auth.user` | Element visible only when signed out |
+| `@text auth.user.displayName` | Element text content set from path |
+| `@text auth.user.email` | Same — any path under `auth.user.*` |
+| `@attr src auth.user.photoURL` | Set element attribute from path |
+
+These bindings live in Web Manager, not @omega.js/extension — but they're how every @omega.js/extension extension surfaces auth state in views.
+
+## Important implementation details
+
+1. **No storage.** Auth state is NOT in `chrome.storage`. Firebase persists sessions in IndexedDB per-context. Web Manager handles UI bindings off those persisted sessions.
+
+2. **Firebase in service workers requires static imports.** A service worker cannot fetch code at runtime under MV3, so dynamic `import()` is not an option there. @omega.js/extension's background.js uses static `import { initializeApp } from 'firebase/app'`.
+
+3. **Config path is fixed.** The watched host comes from omega.json5's `brand.url` (bridged into the packaged snapshot via the `OMEGA_BUILD_JSON` bake the bundle task puts in every bundle).
+
+4. **Tabs permission required.** Without it, background.js can't watch for `/token?authToken=…` redirects.
+
+## See also
+
+- [managers.md](managers.md) — each Manager's `initialize()` wires the auth helpers
+- [components.md](components.md) — which contexts participate in auth sync
+- [extension.md](extension.md) — `chrome.tabs.onUpdated` access via the extension wrapper

package/docs/build-system.md

@@ -0,0 +1,176 @@
+# Build System
+
+@omega.js/extension uses **gulp + esbuild + sass + custom HTML templating + an electron-builder-style packaging step** to compile extension source into a Chrome-loadable, multi-browser-ready build.
+
+## Pipeline overview
+
+`src/` (consumer authored) → `dist/` (intermediate) → `packaged/<browser>/raw/` (Chrome-loadable) → `packaged/<browser>/<name>.zip` (store upload).
+
+```
+src/
+├── manifest.json                            # JSON5 source — comments, single quotes OK
+├── views/<component>/index.html             # HTML templates
+├── _locales/en/messages.json                # i18n catalog source
+├── assets/
+│   ├── js/components/<component>/index.js   # entry points (esbuild bundles these)
+│   ├── css/main.scss + components/          # SCSS
+│   └── images/icon.png                      # source icon (1024×1024)
+└── ...
+        ↓ gulp build (OMEGA_BUILD_MODE=true)
+dist/
+├── manifest.json                            # still JSON5 — used by serve, not Chrome
+├── views/<component>/index.html             # templated
+├── assets/
+│   ├── js/components/<component>.bundle.js  # esbuild output
+│   ├── css/components/<component>.bundle.css # sass output
+│   └── images/                              # icons (multiple sizes)
+└── _locales/<lang>/messages.json            # auto-translated (see docs/translations.md)
+        ↓ packaging step
+packaged/
+├── chromium/
+│   ├── raw/                                 # strict-JSON manifest, Chrome-loadable
+│   │   ├── manifest.json                    # comments stripped, valid JSON
+│   │   └── ...                              # everything from dist/
+│   └── <ExtensionName>.zip                  # store upload
+├── firefox/raw/ + .zip
+└── opera/raw/ + .zip
+```
+
+## Gulp tasks
+
+Auto-loaded from [src/gulp/tasks/](../src/gulp/tasks/) via [src/gulp/main.js](../src/gulp/main.js).
+
+| Task | Source | Purpose |
+|---|---|---|
+| `defaults` | [tasks/defaults.js](../src/gulp/tasks/defaults.js) | Copy framework defaults from `dist/defaults/` to consumer project on first run / setup. See [defaults.md](defaults.md). |
+| `distribute` | [tasks/distribute.js](../src/gulp/tasks/distribute.js) | Copy consumer's `src/` files (HTML, manifest, locales, **static images**, etc.) to `dist/` |
+| `sass` | [tasks/sass.js](../src/gulp/tasks/sass.js) | Compile SCSS → CSS bundles with the load-path system (see [css.md](css.md)) |
+| `bundle` | [tasks/bundle.js](../src/gulp/tasks/bundle.js) | Bundle JS per component entry point with esbuild |
+| `html` | [tasks/html.js](../src/gulp/tasks/html.js) | Run views through the two-step templating system (see [templating.md](templating.md)) |
+| `icons` | [tasks/icons.js](../src/gulp/tasks/icons.js) | Generate icon variants from `src/assets/images/icon.png` |
+| `translate` | [tasks/translate.js](../src/gulp/tasks/translate.js) | Auto-translate `config/messages.json` to the configured `translation.languages` (see [translations.md](translations.md)) |
+| `package` | [tasks/package.js](../src/gulp/tasks/package.js) | Bundle dist/ into packaged/<browser>/raw + zip; runs `build:pre` / `build:post` hooks ([hooks.md](hooks.md)) |
+| `serve` | [tasks/serve.js](../src/gulp/tasks/serve.js) | Dev server: WebSocket-based live reload, watches `src/` |
+| `audit` | [tasks/audit.js](../src/gulp/tasks/audit.js) | Build-pipeline-specific checks (icons exist, manifest is valid, etc.) |
+
+### Static assets
+
+`distribute` copies everything under `src/` EXCEPT what another task owns: `.js` (bundle), `.css/.scss/.sass` (sass), and `src/views/**/*.html` (the html task). Static images (`.png`, `.jpg`, `.svg`, `.webp`, …) copy as-is, byte-for-byte — this framework ships no imagemin task, so nothing else would carry them to `dist/` ([#259](https://github.com/Omega-JS-Stack/omega/issues/259)). Consumers never need a `hooks/build/pre.js` copy step for images.
+
+## Bundling
+
+[src/gulp/tasks/bundle.js](../src/gulp/tasks/bundle.js) discovers component entry points (`src/assets/js/components/<name>/index.js`) and bundles each to `dist/assets/js/components/<name>.bundle.js`.
+
+The bundler is esbuild through @omega.js/devkit's ONE `bundle()` wrapper ([#738](https://github.com/Omega-JS-Stack/omega/issues/738) — webpack, `babel-loader` and `@babel/preset-env` left with it, and the gulp task, the file and the log tag were renamed off `webpack` at the same time). The wrapper supplies what every framework shares: the framework-deps resolve hook ([#87](https://github.com/Omega-JS-Stack/omega/issues/87)), the production `@dev-only` strip ([#18](https://github.com/Omega-JS-Stack/omega/issues/18)), the minify/sourcemap rules by mode, and one timing line per build.
+
+### One call, every lane
+
+Background service worker, content scripts, popup / options / sidepanel / pages all take the same options: `format: 'iife'`, `platform: 'browser'`, no code splitting. webpack needed three configs precisely to switch splitting OFF per lane (MV3's CSP lets neither a service worker nor a content script fetch a chunk); esbuild's iife format has no splitting at all, so each bundle is one self-contained file. Every bundle carries its own `OMEGA_BUILD_JSON` snapshot, content scripts included: in the default isolated world that is invisible to the host page, but a consumer that registers a content script with `world: 'MAIN'` publishes the whole config object onto the page's `window`, readable by any script there. Keep MAIN-world scripts free of anything you would not put in page source.
+
+### Syntax floor — the manifest answers it
+
+esbuild's `target` replaces preset-env's browserslist guess, and it is READ from the manifest rather than hardcoded: `minimum_chrome_version` and `browser_specific_settings.gecko.strict_min_version` are where a project already declares which browsers it supports, so raising either moves the bundler with it. Undeclared, each side falls back to its MV3 minimum — Chrome 88 (where MV3 shipped) and Firefox 91 (the `strict_min_version` the framework's default manifest ships) — which is the `chrome88, firefox91` a scaffolded project compiles to. esbuild compiles SYNTAX to that floor and never polyfills a runtime API.
+
+### Node built-ins
+
+Browser bundles answer `fs` / `path` / `crypto` / `os` / `util` / `assert` / `stream` / `buffer` / `process` with an empty module (@omega.js/devkit's `emptyModulesPlugin`, the esbuild answer to webpack's `resolve.fallback`): libraries bundled through @omega.js/client import them on code paths their browser builds never take.
+
+### The build snapshot — `OMEGA_BUILD_JSON`, baked into every bundle
+
+Every emitted bundle carries its own copy of the build snapshot. It is not a file: `bundle.js` composes it once per build (`composeBuildJson()`) and esbuild bakes it in two ways, which is the same shape @omega.js/desktop uses ([#743](https://github.com/Omega-JS-Stack/omega/issues/743)):
+
+- **`define`** replaces the bare identifier `OMEGA_BUILD_JSON` with the literal at compile time, so framework and consumer code can read the snapshot without reaching for a global.
+- **`banner`** prepends a one-line IIFE that assigns the same value onto `globalThis`, `self` and `window`. That is what `background.js` reads as `self.OMEGA_BUILD_JSON` and what every page context reads as `window.OMEGA_BUILD_JSON`, and it lands ahead of the bundle's own code so the snapshot is always already there.
+
+What it holds: `timestamp`, `repo`, `environment`, `license` (the build's verdict — a fact about the BUILD, never inside `config`), `packages`, and `config` — the blob the contexts hand @omega.js/client (brand, cloud, theme, analytics with the baked `GOOGLE_ANALYTICS_SECRET`, advertising, and in non-production builds the resolved `dev.ports` / `dev.origin` map, the only channel a browser context has to a bumped local stack).
+
+Before #743 the same blob was written as `packaged/<browser>/raw/build.js` — a JSONP file the service worker loaded with `importScripts('/build.js')` and every page loaded with its own `<script src="/build.js">` tag — plus a `build.json` sidecar nothing read. **Neither file is written any more.** Inspecting a built artifact means reading the bake back out of a bundle (`src/gulp/tasks/utils/build-json.js` `readBakedBuildJson()` runs the banner the way a browser would).
+
+### Template replacement
+
+A post-emit pass over the bundles replaces these markers at build time:
+- `%%% version %%%` → `package.json#version`
+- `%%% brand.name %%%` → config brand name
+- `%%% brand.url %%%` → config brand URL
+- `%%% environment %%%` → `'production'` or `'development'`
+- `%%% liveReloadPort %%%` → WebSocket port (35729 default)
+
+A key nothing answers is left INTACT rather than emptied, so unrelated `%%%` text in consumer code survives. The pass runs over the EMITTED files (not the sources) because the tokens reach the bundle from vendored and `@omega.js/client` code too, which a source-level hook would never see; the one cost is that in a DEV build a line carrying a replaced token has shifted source-map columns after the token — production builds ship no maps at all.
+
+### Dev-only blocks
+
+Production bundles drop everything between `/* @dev-only:start */` and `/* @dev-only:end */`. The markers and the cut live in ONE home (`@omega.js/devkit/strip-dev-blocks`) and the wrapper registers the esbuild plugin for production builds only; dev builds keep the blocks. "Production" here is `Manager.actLikeProduction()`, so an `OMEGA_AUDIT_FORCE=true` audit run strips too — it inspects the artifact a release would ship.
+
+### Aliases
+
+esbuild `alias` in bundle.js:
+```js
+alias: {
+  '__main_assets__':    '<framework>/dist/assets',
+  '__project_assets__': '<project>/src/assets',
+  '__theme__':          '<framework>/dist/assets/themes/<active-theme>',
+}
+```
+
+## Sass
+
+[src/gulp/tasks/sass.js](../src/gulp/tasks/sass.js) compiles per-component SCSS bundles. Load-path resolution lets consumer SCSS `@use 'omega-extension'`, `@use 'theme'`, and `@use 'components/popup'` resolve through a search chain. Full details in [css.md](css.md).
+
+## HTML templating
+
+Views in `src/views/<component>/index.html` go through two passes of `{{ }}` token replacement. See [templating.md](templating.md).
+
+## Packaging
+
+[tasks/package.js](../src/gulp/tasks/package.js):
+
+1. **Pre-hook** — runs `hooks/build/pre.js` if present (the flat `hooks/build:pre.js` still resolves as a transition fallback)
+2. **Per-browser manifest normalization** — converts JSON5 → strict JSON for Chrome/Edge/Opera (Firefox tolerates JSON5 but normalized anyway)
+3. **Per-browser asset copy** to `packaged/<browser>/raw/` — the bundles arrive with the snapshot already baked in, so the package lane writes no `build.js` / `build.json` of its own ([#743](https://github.com/Omega-JS-Stack/omega/issues/743))
+4. **Zip** to `packaged/<browser>/<name>.zip`
+5. **Post-hook** — runs `hooks/build/post.js`
+6. **Auto-publish** (if `OMEGA_IS_PUBLISH=true`) — uploads to Chrome Web Store / Firefox Add-ons / Edge Add-ons stores. See [publishing.md](publishing.md).
+
+### Manifest compilation rules
+
+The compiled manifest is the source manifest merged with the framework defaults ([src/config/manifest.json](../src/config/manifest.json)), then adjusted per target:
+
+- **Declared beats default.** The defaults only fill keys your `src/manifest.json` never wrote — including arrays. An array you declare REPLACES the default (an empty array ships nothing), which is the only way to drop a framework default such as `externally_connectable`'s dev origin from a production build ([#260](https://github.com/Omega-JS-Stack/omega/issues/260)).
+- **`externally_connectable` defaults to your BRAND origin.** The default `matches` is `<brand.url origin>/*`, plus the resolved dev-website origin in a dev build only. A packaged build used to ship the localhost dev origin alone, so the live brand site could not message the published extension ([#583](https://github.com/Omega-JS-Stack/omega/issues/583)). With no `brand.url`, a build-mode build declares no origin and says so. The scaffolded boot test `test/boot/externally-connectable.test.js` asserts the brand origin against the real packaged manifest.
+- **`homepage_url` is baked from `brand.url`** on every target — the store listing's developer-site link, which nothing emitted before ([#576](https://github.com/Omega-JS-Stack/omega/issues/576)). A value you declare wins; with no `brand.url` the key ships absent.
+- **Icons are pruned to what the build minted** — a manifest pointing at an icon that isn't there is an extension Chrome refuses to load.
+- **chromium / opera** — `background.scripts` dropped (MV3 service worker).
+- **firefox** — `background.service_worker` becomes `background.scripts`; `side_panel` becomes `sidebar_action` (Firefox has no side panel key) and the `sidePanel` permission is dropped; `browser_specific_settings.gecko.id` is DERIVED when you declare none — `extension@<brand.url host>`, or `extension@<brand.id>.extension` with no url, and packaging fails only when there are no brand facts at all to derive from ([#264](https://github.com/Omega-JS-Stack/omega/issues/264)). Firefox cannot identify, sign, or update an add-on without an id, so a fresh scaffold builds out of the box — but **declare your own id before the first publish** ([#574](https://github.com/Omega-JS-Stack/omega/issues/574)): it must stay stable across every release, and `brand.url` can change.
+
+## Build modes
+
+Env vars that drive the pipeline:
+
+- `OMEGA_BUILD_MODE=true` — production build (minified, no sourcemaps, dev-blocks stripped)
+- `OMEGA_IS_PUBLISH=true` — also publish to extension stores after packaging
+- `OMEGA_LIVERELOAD_PORT=35729` — WebSocket port for `serve` task (override if 35729 collides)
+- `OMEGA_TEST_MODE=true` — running in @omega.js/extension's test framework. Powers `Manager.isTesting()` (see [test-framework.md](test-framework.md)).
+- `OMEGA_LOG_FILE` — override the stdout/stderr tee path, or set to `false` to disable it (see [Log files](#log-files)).
+
+## Live reload
+
+`npm start` (= `gulp` with no args, by default invokes `serve`) watches `src/` and recompiles on change. A WebSocket server on `OMEGA_LIVERELOAD_PORT` (35729) notifies the extension's contexts. Background SW reloads itself via `chrome.runtime.reload()`; other contexts reload via `window.location.reload()`.
+
+## Log files
+
+The gulp pipeline tees all output to `logs/dev.log` (`npm start`) / `logs/build.log` (`npm run build`), and `npx omega test` tees to `logs/test.log`. Full reference — file table, capture behavior, `OMEGA_LOG_FILE` controls: [logging.md](logging.md).
+
+## Output for Chrome's "Load unpacked"
+
+Point Chrome at `packaged/chromium/raw/` — that's the strict-JSON, fully-assembled Chrome-loadable build. NOT `dist/` (which has JSON5 manifest mid-pipeline). The test framework's boot layer auto-targets `packaged/chromium/raw/` for the same reason — see [test-boot-layer.md](test-boot-layer.md).
+
+## See also
+
+- [components.md](components.md) — the seven component contexts
+- [templating.md](templating.md) — `{{ }}` token replacement
+- [css.md](css.md) — SCSS load paths
+- [defaults.md](defaults.md) — `src/defaults/` template system
+- [hooks.md](hooks.md) — `build:pre` / `build:post`
+- [translations.md](translations.md) — auto-translate `_locales/`
+- [publishing.md](publishing.md) — store auto-publishing
+- [test-boot-layer.md](test-boot-layer.md) — verify the packaged extension actually boots in Chromium

package/docs/cdp-debugging.md

@@ -0,0 +1,42 @@
+# CDP Debugging (driving a live browser)
+
+How to drive a browser you can CONTROL — see the extension live, screenshot it, click, type, read console logs, inspect network requests — for agents (Claude via MCP/CDP) and humans. For @omega.js/extension this is THE dev surface: the extension only exists inside a running browser.
+
+> Mirrored across the five sister frameworks (UJM / @omega.js/backend / @omega.js/extension / EM / @omega.js/client) — same core section, framework-flavored. Edit all five together.
+
+## The browser: your Claude session owns one
+
+Browser work runs through the **`chrome-devtools` MCP** (via mcp-router). There is NO launch procedure anymore — no ports, no profile dirs, no curl checks:
+
+- **Just call the tools** — `new_page`, `navigate_page`, `take_screenshot`, `click`, `fill`, `evaluate_script`, `list_console_messages`, `list_network_requests`. The browser auto-launches on the first call.
+- **Each Claude session gets its OWN private Chrome** (`--isolated`): temp profile, CDP over an internal pipe. Parallel sessions cannot see or touch each other's pages — open and close pages freely, the whole browser is yours.
+- **It dies with the session.** No orphans, no cleanup, nothing to kill.
+- **Ephemeral profile** — cookies/logins do NOT persist between sessions. If a flow needs auth, log in during the task.
+- **Self-signed HTTPS is pre-accepted** (`--acceptInsecureCerts` in the upstream) — dev servers load without certificate interstitials.
+- **NEVER quit/kill Chrome by app name** (`killall "Google Chrome"`, osascript) — that's the user's personal browser, not yours.
+
+Humans: the agent's Chrome window is visible — you can watch it drive. Full reference: `~/.claude/mcp-server/servers/chrome-devtools/CLAUDE.md`.
+
+## Electron apps are the exception (attach, don't launch)
+
+An Electron dev app is a running singleton — you ATTACH to it instead of launching a browser: the `chrome-devtools-electron` MCP upstream (reads `OMEGA_CDP_PORT`, default 9222, expanded once at session start) or EM's per-invocation `npx omega cdp`. See EM's `docs/cdp-debugging.md`.
+
+## @omega.js/extension specifics: testing the extension (`chrome-devtools-extension` upstream)
+
+The plain `chrome-devtools` browser has NO extension in it — and `--load-extension` is silently ignored by branded stable Chrome (removed ~v137; verified on 149). The fix is the dedicated **`chrome-devtools-extension` MCP upstream**: the same per-session isolated model, but it launches **Chrome for Testing** (which still honors `--load-extension` — verified on CfT 150) with your unpacked extension pre-loaded into the ephemeral profile.
+
+The recipe:
+
+1. **Build the loadable output**: `npm run build` → `packaged/chromium/raw/` (strict-JSON manifest; `dist/` is NOT Chrome-loadable — its manifest is JSON5).
+2. **Launch the session with the extension path** (env is expanded ONCE at session start — set it BEFORE `claude`):
+   ```bash
+   OMEGA_CDP_EXTENSION_PATH="$(pwd)/packaged/chromium/raw" claude
+   ```
+3. **In the session, enable the upstream** (it's on-demand): `router__enable_upstream { name: "chrome-devtools-extension" }`. The first tool call launches CfT with the extension loaded. Tools are namespaced `chrome-devtools-extension__*` (34 tools — the base set + extension tools).
+4. **Rebuild loop**: after `npm run build`, `router__disable_upstream` + `router__enable_upstream` → fresh browser with the rebuilt extension (the profile is ephemeral; the extension loads at launch).
+
+What you can reach: the popup and extension pages as page targets, content scripts inside the pages they're injected into, and the background service worker (`evaluate_script` takes a `serviceWorkerId`). Chrome for Testing binaries live in `~/.cache/puppeteer/chrome/` (the upstream auto-resolves the newest; update with `npu npx @puppeteer/browsers install chrome@stable`).
+
+Full recipe + gotchas: `~/.claude/mcp-server/servers/chrome-devtools-extension/CLAUDE.md`.
+
+Navigating to a brand's UJM dev site? **`https://localhost:4000` — NEVER the LAN IP** (`https://192.168.x.x:...`). Port 4000 by default, increments (4001, …) when multiple sites run; exact port in `.temp/_config_browsersync.yml` at the WEBSITE project root (the UJM consumer, NOT this extension repo).

package/docs/cli.md

@@ -0,0 +1,73 @@
+# CLI
+
+`npx omega <command>` — bins `omega`, `omg`, `mgr`, `omega-extension` (all the same context-aware dispatcher; `omega-extension` runs this framework's CLI directly).
+
+## Commands
+
+| Command | Aliases | Purpose |
+|---|---|---|
+| `build` | `-b`, `--build` | Production build: clean, then the gulp `build` task with `OMEGA_BUILD_MODE=true` set in-process. The verb OWNS the pipeline — the synced `build` project script is the thin `omega build` alias, so the verb never shells back to it ([#81](https://github.com/Omega-JS-Stack/omega/issues/81)) |
+| `clean` | `-c`, `--clean` | Remove `dist/`, `packaged/`, `.cache/`, `.temp/` |
+| `install` | `-i`, `i`, `--install` | Install peer deps (gulp, etc.) |
+| `deploy` | `-d`, `--deploy` | Dispatch the extension's CI publish workflow — `publish.yml` standalone, the composed `<target>-publish.yml` inside a brand monorepo ([defaults.md](defaults.md#brand-monorepos); see docs/shared/deploys.md in the Omega repo) |
+| `test` | `-t`, `--test` | Run the project's test suites (bare runs are project-only; `mgr:` / `framework:` / `full:` reach the framework suite). Positional target scopes by source + path; `--filter` matches test names; `--extended` enables real-external-API tests. See [test-framework.md](test-framework.md). |
+| `update` | `-u`, `--update`, `outdated`, `out` | Dependency freshness report (installed/wanted/latest + patch/minor/major, releases < 7 days old QUARANTINED). `--apply` installs the non-breaking non-quarantined set via `npu install` (plain npm + loud note without npu); `--major` opts into breaking; `--min-age N` / `--force-fresh` tune the quarantine. `file:` specs skipped. Shared devkit implementation — see docs/shared/updates.md in the Omega repo. |
+| `version` | `-v`, `--version` | Print @omega.js/extension, Node, peer-dep versions |
+| `help` | `-h`, `--help` | Command listing (router built-in, generated from this table's live aliases) |
+
+## Entry point
+
+[bin/omega-extension](../bin/omega-extension) — yargs-based shim that loads [src/cli.js](../src/cli.js).
+
+[src/cli.js](../src/cli.js) owns only the alias table and the commands directory — dispatch (positional/flag alias resolution, command loading, error surfacing) is the shared devkit router (`createCliRouter`, vendored into `dist/vendor/devkit/cli-router.js` at prepare time). The returned Main class exposes the resolved dispatch table as `Main.config` for structure tests.
+
+## Adding a new command
+
+1. Create `src/commands/<name>.js` exporting `async function (options) { /* ... */ }`
+2. Add to the `aliases` table in [src/cli.js](../src/cli.js):
+   ```js
+   aliases: {
+     clean:   ['-c', '--clean'],
+     deploy:  ['-d', '--deploy'],
+     <name>:  ['-x', '--<name>'],
+   },
+   ```
+3. Optionally add to `projectScripts` in [package.json](../package.json) so consumers get a wrapper npm script from the scaffold every verb runs.
+4. Document under this page.
+
+## Command options
+
+Yargs parses `--foo bar` and `--foo=bar` into `options.foo`. Positional args go into `options._[]`. Each command reads what it needs:
+
+```js
+// src/commands/test.js
+module.exports = async function (options) {
+  const layer    = options.layer    || 'all';
+  const target   = (options._ && options._[1]) || null; // positional: `npx omega test <target>`
+  const filter   = options.filter   || null;
+  const reporter = options.reporter || 'pretty';
+  // ...
+};
+```
+
+## Env var conventions
+
+Commands read BXM-prefixed env vars for behavior switches (one exception: `TEST_EXTENDED_MODE` is deliberately unprefixed — the SAME name across all OMEGA frameworks):
+
+| Env | Used by | Purpose |
+|---|---|---|
+| `OMEGA_BUILD_MODE=true` | gulp tasks | Production build mode |
+| `OMEGA_IS_PUBLISH=true` | gulp/package | Also publish to extension stores after packaging |
+| `OMEGA_LOG_FILE` | gulp + test runners | Override the stdout/stderr tee path, or `false` to disable (see [logging.md](logging.md)) |
+| `OMEGA_TEST_MODE=true` | test runners | Powers `Manager.isTesting()` (auto-set by `npx omega test`) |
+| `TEST_EXTENDED_MODE=true` | test runners | Run tests that hit REAL external services (`--extended` is the CLI shorthand; see [test-framework.md](test-framework.md)) |
+| `OMEGA_TEST_BOOT_PROJECT` | test/boot | Override project root for boot tests |
+| `OMEGA_TEST_BOOT_DIR` | test/boot | Override extension dir directly |
+| `OMEGA_TEST_DEBUG=1` | test runners | Pipe Chromium stderr to console |
+| `OMEGA_LIVERELOAD_PORT` | gulp/serve | WebSocket port (default 35729) |
+
+## See also
+
+- [build-system.md](build-system.md) — `gulp` is what most CLI commands ultimately invoke
+- [test-framework.md](test-framework.md) — `npx omega test` command surface
+- [defaults.md](defaults.md) — every verb's `ensureTarget()` invokes the defaults task

package/docs/common-mistakes.md

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

package/docs/components.md

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