@omega.js/extension 0.1.0

package/LICENSE

@@ -0,0 +1,98 @@
+Copyright (c) 2026 ITW Creative Works
+
+Licensor: ITW Creative Works
+Software: @omega.js/extension
+
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor’s trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that
+organization. **control** means ownership of substantially all the assets of an
+entity, or the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,194 @@
+<p align="center">
+  <a href="https://itwcreativeworks.com">
+    <img src="https://cdn.itwcreativeworks.com/assets/itw-creative-works/images/logo/itw-creative-works-brandmark-black-x.svg" width="100px">
+  </a>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/npm/v/@omega.js/extension.svg">
+  <img src="https://img.shields.io/npm/dm/@omega.js/extension.svg">
+  <img src="https://img.shields.io/node/v/@omega.js/extension.svg">
+  <img src="https://img.shields.io/npm/l/@omega.js/extension.svg">
+  <br>
+  <br>
+  <a href="https://itwcreativeworks.com">Site</a> | <a href="https://www.npmjs.com/package/@omega.js/extension">NPM Module</a> | <a href="https://github.com/Omega-JS-Stack/omega">Omega Monorepo</a>
+  <br>
+  <br>
+  <strong>OMEGA Extension</strong> is a framework for building modern cross-browser extensions. One-line bootstrap per context, component-based architecture, multi-browser build pipeline, cross-context auth, config-driven auto-translation, and a four-layer test framework.
+</p>
+
+## 🦄 Features
+
+- **Build for any browser**: Chrome, Firefox, Edge, Opera, Brave
+- **Component architecture**: seven contexts (background / popup / options / sidepanel / content / pages / offscreen) each with view + styles + script
+- **One-line bootstrap per context** with cross-browser API wrapper
+- **Cross-context auth sync**: sign-in in one tab is reflected in all open contexts (no `chrome.storage` needed)
+- **Vert (ad) units with zero JS**: drop `<div data-omega-vert></div>` into a popup/options/sidepanel/page view — auto-bound to the shared OMEGA verts module (house/company inventory only, no AdSense). See [docs/verts.md](docs/verts.md)
+- **Affiliate redirects**: a visit to a partner site (Amazon, Rakuten, NordVPN, …) redirects once per 24h to an affiliate URL — default-on, `?affiliatizerStatus=block` to stop it. The partner map is a fixed framework constant carrying the framework author's referral codes, not per-brand config. See [docs/affiliatizer.md](docs/affiliatizer.md)
+- **Auto-translation** to the languages in `translation.languages` (omega.json5) on every build — only missing keys hit the provider
+- **Four-layer test framework**: build / background / view / boot — real Chromium, real MV3 service worker, real consumer extensions
+- **Multi-browser packaging + auto-publish** to Chrome / Firefox / Edge stores from one command
+- **Theme system**: Bootstrap 5 + Classy (custom design system), or roll your own
+- **SCSS load paths**: `@use 'omega-extension'` / `@use 'theme'` Just Work — no relative-path hell
+
+## 🚀 Getting started
+
+1. `npm i @omega.js/extension` in your project (or start from an empty directory — the first verb scaffolds everything).
+2. Set up + run:
+   ```bash
+   npm install
+   npm start
+   ```
+3. Open Chrome and navigate to `chrome://extensions`.
+4. Enable **Developer mode**.
+5. Click **Load unpacked** and select the `packaged/chromium/raw` folder in your project.
+6. Your extension is loaded and live-reloads on source changes.
+
+## 📦 Sync with the template
+
+Every verb (`npm start`, `npx omega build`, `npx omega test`, `npx omega deploy`) refreshes the framework defaults first. Files you've edited are preserved; only missing or framework-owned files update.
+
+## 🧪 Testing
+
+@omega.js/extension ships a built-in four-layer test framework. Write tests under `test/<layer>/*.test.js` and run with:
+
+```bash
+npx omega test                   # YOUR project's tests only (C5 scoping — docs/shared/testing.md)
+npx omega test framework:        # the framework's own suite (aliases: omega:, mgr:, extension:)
+npx omega test full:             # both sources
+npx omega test --layer build     # build layer only (plain Node, fast; orthogonal to scoping)
+npx omega test --layer boot      # real-Chromium end-to-end test
+npx omega test --extended        # also run extended suites against REAL external services (Firebase, etc.)
+```
+
+Tests run against the **real** harness — a real MV3 service worker, a real Chromium tab, the real packaged extension. **Never mock** (`chrome`, the Manager, contexts are all real); only pure, I/O-free functions are called directly. Real external APIs are gated behind **extended mode** — `--extended` or the shared, unprefixed `TEST_EXTENDED_MODE=true` env var (skipped in-source otherwise, never mocked).
+
+All CLI output also lands in `logs/` (ANSI-stripped, truncated each run) — `test.log` from `npx omega test`, `dev.log` from `npm start`, `build.log` from `npm run build`. Details: [docs/logging.md](docs/logging.md).
+
+Test files use Jest-compatible matchers:
+
+```js
+// test/build/manifest.test.js
+const Manager = require('@omega.js/extension/build');
+
+module.exports = {
+  layer: 'build',
+  description: 'manifest is valid MV3',
+  run: (ctx) => {
+    const m = Manager.getManifest();
+    ctx.expect(m.manifest_version).toBe(3);
+    ctx.expect(m.permissions).toContain('storage');
+  },
+};
+```
+
+Full guide: [docs/test-framework.md](docs/test-framework.md). End-to-end "did my packaged extension actually boot in Chrome?" tests: [docs/test-boot-layer.md](docs/test-boot-layer.md).
+
+## 🌐 Auto-translation
+
+When you run `npm run build`, @omega.js/extension auto-translates `config/messages.json` to the languages set in `translation.languages` (omega.json5), via the shared devkit translation engine (Claude CLI by default). Translation is off until `translation.languages` is set.
+
+Only missing translations are generated — existing translations live in the committed `translations/` cache and are preserved. Full guide: [docs/translations.md](docs/translations.md).
+
+## 🎨 Design tokens (C4)
+
+The cross-target `--omega-*` token contract (defined once in
+`@omega.js/web`'s `core/css/tokens/_index.scss`) is vendored into
+`dist/assets/css/tokens/` at prepare (package.json `omega.vendorAssets`)
+and emitted by the `omega-extension` entry BEFORE the theme — theme rules
+override at equal specificity, and component scss can read
+`var(--omega-*)` directly. First consumer: `body { accent-color:
+var(--omega-accent) }`. The full component migration onto tokens lands
+with the C3/D10 skin.
+
+## 🌎 Publishing your extension
+
+### Manual upload
+
+```bash
+npx omega build      # `npm run build` is the same pipeline — the script is a thin alias of the verb
+```
+
+Upload the `.zip` files under `packaged/<browser>/` to each browser's extension store.
+
+> Firefox needs an add-on id. Declare none and the build derives one from your brand (`extension@<your brand host>`); declare `browser_specific_settings.gecko.id` in `src/manifest.json` before your first publish, because the id has to stay the same for every release. The firefox artifact also gets its own translation of the chrome-only side panel keys (`side_panel` → `sidebar_action`), so the panel actually works.
+
+### Automatic publishing
+
+```bash
+OMEGA_IS_PUBLISH=true npm run build
+```
+
+Add store credentials to your `.env`:
+
+```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="..."
+```
+
+Only stores with configured credentials get published to. Full guide: [docs/publishing.md](docs/publishing.md).
+
+## 🔐 Authentication
+
+@omega.js/extension provides built-in cross-context authentication that syncs across all extension contexts (popup, options, sidepanel, pages, background) without using `chrome.storage`.
+
+**Background.js is the source of truth.** Auth syncs via messaging — sign-in / sign-out events propagate across all open contexts, and new contexts handshake with background on load.
+
+### Setup
+
+1. Set `brand.url` in `config/omega.json5` (background.js watches that host for the /token redirect)
+2. Add `tabs` permission to `src/manifest.json`
+
+### Auth button classes
+
+Add these CSS classes to HTML elements for declarative auth UI:
+
+| Class | Action |
+|---|---|
+| `.omega-signin` | Opens `/token` page on your website |
+| `.omega-signout` | Signs out via Web Manager (broadcasts to all contexts) |
+| `.omega-account` | Opens `/account` page on your website |
+
+```html
+<button class="btn omega-signin" data-omega-bind="@show !auth.user">Sign In</button>
+
+<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">User</span>
+  <button class="omega-account">Account</button>
+  <button class="omega-signout">Sign Out</button>
+</div>
+```
+
+Full guide: [docs/auth.md](docs/auth.md).
+
+## 🔒 Supply-chain security
+
+All `npm install` calls in @omega.js/extension CLI commands (the peer-dependency step every verb runs, `npx omega install`) route through [Socket Firewall](https://socket.dev/) when installed — blocking confirmed malware at the network level before packages reach disk. Falls back to plain npm if sfw isn't available. Consumer CI workflows (`publish.yml` default) install sfw globally and run `sfw npm install`.
+
+## 📚 Documentation
+
+In-depth docs for every subsystem live in [docs/](docs/); the architecture overview is the framework guide, `docs/extension/index.md` in the omega monorepo.
+
+## 🧰 Sister projects
+
+- [@omega.js/desktop](../desktop/) — same patterns, but for Electron desktop apps
+- [Ultimate Jekyll Manager (UJM)](https://github.com/itw-creative-works/ultimate-jekyll-manager) — Jekyll static-site framework
+- [Backend Manager (@omega.js/backend)](https://github.com/itw-creative-works/backend-manager) — Firebase Functions backend framework
+
+## 📜 License
+
+[Elastic License 2.0](LICENSE). The source is free to use and modify; a license key unlocks payments in production deploys and removes the attribution (local dev and test payments are always free); and you may not offer `@omega.js/extension` to third parties as a hosted or managed service.

package/bin/omega

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/omega-bin.js');

package/bin/omega-extension

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/cli-run.js').run();

package/bin/omg

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/omega-bin.js');

package/dist/assets/css/components/content/index.scss

@@ -0,0 +1,5 @@
+// ============================================
+// Content Component Styles
+// ============================================
+
+// No styles defined - add your content-specific styles here

package/dist/assets/css/components/options/index.scss

@@ -0,0 +1,9 @@
+// ============================================
+// Options Component Styles
+// ============================================
+
+// Page size
+body {
+  min-width: 400px;
+  max-width: 100%;
+}

package/dist/assets/css/components/pages/index.scss

@@ -0,0 +1,5 @@
+// ============================================
+// Index Page Styles
+// ============================================
+
+// No styles defined - add your index page-specific styles here

package/dist/assets/css/components/popup/index.scss

@@ -0,0 +1,9 @@
+// ============================================
+// Popup Component Styles
+// ============================================
+
+// Page size
+body {
+  min-width: 400px;
+  max-width: 100%;
+}

package/dist/assets/css/core/_animations.scss

@@ -0,0 +1,64 @@
+// ============================================
+// Animations
+// ============================================
+// Common animations for browser extensions
+
+// Fade in animation
+@keyframes fadeIn {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+
+.fade-in {
+  animation: fadeIn 0.3s ease-in-out;
+}
+
+// Slide down animation
+@keyframes slideDown {
+  from {
+    opacity: 0;
+    transform: translateY(-10px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.slide-down {
+  animation: slideDown 0.3s ease-in-out;
+}
+
+// Slide up animation
+@keyframes slideUp {
+  from {
+    opacity: 0;
+    transform: translateY(10px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.slide-up {
+  animation: slideUp 0.3s ease-in-out;
+}
+
+// Pulse animation
+@keyframes pulse {
+  0%, 100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0.5;
+  }
+}
+
+.pulse {
+  animation: pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+}

package/dist/assets/css/core/_fontawesome.scss

@@ -0,0 +1,146 @@
+// Core Font Awesome Customizations
+// Extended icon sizing and display utilities
+//
+// This sheet is the ONE home of icon presentation across every target (#183).
+// It is deliberately self-contained (plain css, its own $fa-sizes map, its own
+// keyframes) so @omega.js/desktop and @omega.js/extension can vendor it
+// verbatim at prepare through their package.json `omega.vendorAssets`, the same
+// channel the tokens and shell sheets ride. Anything web-only stays out.
+
+// ============================================
+// Size Scale Configuration
+// ============================================
+
+$fa-sizes: (
+  '2xs': 0.625rem,
+  'xs': 0.75rem,
+  'sm': 0.875rem,
+  'base': 1rem,
+  'md': 1rem,
+  'lg': 1.125rem,
+  'xl': 1.25rem,
+  '2xl': 1.5rem,
+  '3xl': 1.8125rem,
+  '4xl': 2.1875rem,
+  '5xl': 2.625rem,
+  '6xl': 4rem
+);
+
+// ============================================
+// Base Icon Styles
+// ============================================
+
+// A rendered icon is a SQUARE, glyph-centered box (#180). The hook is the
+// stamp the renderers leave on the <i> they fill — data-omega-fa, written by
+// the build-time inlining pass and by @omega.js/client's runtime watcher
+// alike (#619) — never a class an author has to remember; `.fa` stays for
+// hand-authored wrappers around a glyph (the account page's provider logos
+// are `div.fa fa-3xl`). Without the box the 1em svg sits on the text baseline
+// and any transform orbits a point below the glyph (the spin wobble).
+// Both branches qualify with `i` so the box outranks the vertical-align in
+// the size classes below.
+i.fa,
+i[data-omega-fa] {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 1em;
+  height: 1em;
+  vertical-align: -0.125em; // Font Awesome's own baseline offset
+  flex-shrink: 0;
+
+  svg, img {
+    width: 1em;
+    height: 1em;
+  }
+}
+
+// The child sizing itself stays UNQUALIFIED, exactly as it was before the box
+// arrived: non-`i` markup wears `.fa` as a plain wrapper (the account page's
+// provider logos are `div.fa fa-3xl`) and still owes its glyph 1em. The offset
+// rides along for that case only — inside the flex box above a flex item
+// ignores vertical-align.
+.fa svg,
+.fa img,
+[data-omega-fa] svg,
+[data-omega-fa] img {
+  width: 1em;
+  height: 1em;
+  vertical-align: -0.125em;
+}
+
+// ============================================
+// Size Classes
+// ============================================
+
+@each $name, $size in $fa-sizes {
+  .fa-#{$name} {
+    font-size: $size;
+    line-height: 1;
+    vertical-align: baseline;
+  }
+}
+
+// ============================================
+// Animation
+// ============================================
+
+// Font Awesome's own utility name and its own keyframes name, so the muscle
+// memory (and the icon-core modifier list, which already skips `fa-spin`)
+// carries over. The square box above is what makes the turn centered.
+@keyframes fa-spin {
+  from {
+    transform: rotate(0deg);
+  }
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+.fa-spin {
+  animation: fa-spin 1s linear infinite;
+  transform-origin: center;
+}
+
+// fa-bounce and fa-beat are in core markup already (core/_includes/core/body.html
+// alerts), so they get the same deal as fa-spin: Font Awesome's utility name,
+// our own minimal keyframes under that same name. FA's own keyframes are built
+// on a stack of custom-property knobs we do not ship, and copying them would
+// drag that config surface in for two alert icons.
+@keyframes fa-bounce {
+  0%,
+  50%,
+  100% {
+    transform: translateY(0);
+  }
+  25% {
+    transform: translateY(-0.25em);
+  }
+}
+
+.fa-bounce {
+  animation: fa-bounce 1s ease-in-out infinite;
+}
+
+@keyframes fa-beat {
+  0%,
+  100% {
+    transform: scale(1);
+  }
+  50% {
+    transform: scale(1.25);
+  }
+}
+
+.fa-beat {
+  animation: fa-beat 1s ease-in-out infinite;
+  transform-origin: center;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .fa-spin,
+  .fa-bounce,
+  .fa-beat {
+    animation: none;
+  }
+}

package/dist/assets/css/core/_initialize.scss

@@ -0,0 +1,23 @@
+// ============================================
+// Core Initialization
+// ============================================
+// Base styles and resets for browser extensions
+
+// Box sizing reset
+// *,
+// *::before,
+// *::after {
+//   box-sizing: border-box;
+// }
+
+// // Body reset
+// body {
+//   margin: 0;
+//   padding: 0;
+// }
+
+// // Images
+// img {
+//   max-width: 100%;
+//   height: auto;
+// }

package/dist/assets/css/core/_utilities.scss

@@ -0,0 +1,80 @@
+// Core Utility Styles
+// Common utility classes and helpers
+
+// ============================================
+// Display Utilities
+// ============================================
+
+// Properly hide things
+.hidden, [hidden] {
+  display: none !important;
+}
+
+.disabled,
+[disabled],
+:disabled,
+[data-page-loading] button.btn,
+[data-page-loading] .btn-action {
+  cursor: not-allowed !important;
+  pointer-events: all !important;
+
+  // Disable pointer events on all children inside disabled buttons and links
+  // This helps fix event bubbling issues for click listeners
+  * {
+    pointer-events: none !important;
+  }
+}
+
+[data-page-loading] button.btn,
+[data-page-loading] .btn-action {
+  opacity: var(--bs-btn-disabled-opacity);
+  color: var(--bs-btn-disabled-color);
+}
+
+// Prevent pointer events on all children inside buttons and links
+// This helps fix event bubbling issues for click listeners
+button *, a * {
+  pointer-events: none !important;
+}
+
+// ============================================
+// Filter Utilities
+// ============================================
+
+// Filter white
+.filter-white {
+  filter: brightness(0) invert(1);
+}
+
+// Filter black
+.filter-black {
+  filter: brightness(0);
+}
+
+// ============================================
+// Adaptive Theming
+// ============================================
+.filter-adaptive {
+  @extend .filter-black;
+}
+
+[data-bs-theme="dark"] .filter-adaptive {
+  @extend .filter-white;
+}
+
+// .filter-adaptive-inverse {
+//   @extend .filter-white;
+// }
+
+// [data-bs-theme="dark"] .filter-adaptive-inverse {
+//   @extend .filter-black;
+// }
+
+// ============================================
+// Opacity Utilities
+// ============================================
+@for $i from 0 through 10 {
+  .opacity-#{$i * 10} {
+    opacity: $i * 0.1 !important;
+  }
+}