@omega.js/extension 0.1.0

package/dist/defaults/src/assets/js/components/offscreen/index.js

@@ -0,0 +1,25 @@
+// ============================================
+// Offscreen Component
+// ============================================
+// Persistent offscreen document for background operations
+// (WebSocket connections, long-running tasks, etc.)
+
+// Import OMEGA Extension
+import Manager from '@omega.js/extension/offscreen';
+
+// Create instance
+const manager = new Manager();
+
+// Initialize
+manager.initialize()
+.then(() => {
+  // Shortcuts
+  const { extension, logger } = manager;
+
+  // Add your project-specific offscreen logic here
+  // This document is invisible and persists in the background
+  // ...
+
+  // Log the initialization
+  logger.log('Offscreen initialized!');
+});

package/dist/defaults/src/assets/js/components/options/index.js

@@ -0,0 +1,22 @@
+// ============================================
+// Options Component
+// ============================================
+
+// Import OMEGA Extension
+import Manager from '@omega.js/extension/options';
+
+// Create instance
+const manager = new Manager();
+
+// Initialize
+manager.initialize()
+.then(() => {
+  // Shortcuts
+  const { extension, messenger, logger, omega } = manager;
+
+  // Add your project-specific options logic here
+  // ...
+
+  // Log the initialization
+  logger.log('Options initialized!');
+});

package/dist/defaults/src/assets/js/components/pages/index.js

@@ -0,0 +1,22 @@
+// ============================================
+// Index Page (Main Extension Page)
+// ============================================
+
+// Import OMEGA Extension
+import Manager from '@omega.js/extension/page';
+
+// Create instance
+const manager = new Manager();
+
+// Initialize
+manager.initialize()
+.then(() => {
+  // Shortcuts
+  const { extension, messenger, logger, omega } = manager;
+
+  // Add your project-specific page logic here
+  // ...
+
+  // Log the initialization
+  logger.log('Index page initialized!');
+});

package/dist/defaults/src/assets/js/components/popup/index.js

@@ -0,0 +1,22 @@
+// ============================================
+// Popup Component
+// ============================================
+
+// Import OMEGA Extension
+import Manager from '@omega.js/extension/popup';
+
+// Create instance
+const manager = new Manager();
+
+// Initialize
+manager.initialize()
+.then(() => {
+  // Shortcuts
+  const { extension, messenger, logger, omega } = manager;
+
+  // Add your project-specific popup logic here
+  // ...
+
+  // Log the initialization
+  logger.log('Popup initialized!');
+});

package/dist/defaults/src/assets/js/components/sidepanel/index.js

@@ -0,0 +1,20 @@
+// ============================================
+// Sidepanel Component
+// ============================================
+// Default functionality for the sidepanel view
+
+// Import OMEGA Extension
+import Manager from '@omega.js/extension/sidepanel';
+
+// Create instance
+const manager = new Manager();
+
+// Initialize
+manager.initialize()
+.then(() => {
+  // Shortcuts
+  const { extension, messenger, logger, omega } = manager;
+
+  // Add your sidepanel-specific JavaScript here
+  logger.log('Sidepanel initialized!');
+});

package/dist/defaults/src/manifest.json

@@ -0,0 +1,131 @@
+{
+  // Basic info
+  name: '__MSG_appName__',
+  short_name: '__MSG_appNameShort__',
+  description: '__MSG_appDescription__',
+
+  // Background script
+  background: {
+    service_worker: 'assets/js/components/background.bundle.js',
+  },
+
+  // Permissions
+  permissions: [
+    // 'activeTab',
+    // 'tabs',
+    // 'storage',
+    // 'scripting',
+  ],
+  host_permissions: [
+    // 'http://*/*',
+    // 'https://*/*',
+  ],
+
+  // Options page
+  options_ui: {
+    page: 'views/options/index.html',
+  },
+
+  // Content scripts
+  content_scripts: [
+    // {
+    //   matches: [
+    //     'http://*/*',
+    //     'https://*/*',
+    //   ],
+    //   js: [
+    //     'assets/js/components/content.bundle.js',
+    //   ],
+    //   css: [
+    //     'assets/css/components/content.bundle.css',
+    //   ],
+    //   run_at: 'document_end',
+    //   all_frames: false,
+    // },
+  ],
+
+  // Browser action
+  action: {
+    default_title: '__MSG_appName__',
+    default_popup: 'views/popup/index.html',
+  },
+
+  // Side panel
+  side_panel: {
+    default_path: 'views/sidepanel/index.html',
+  },
+
+  // Content security policy
+  content_security_policy: {
+    extension_pages: "script-src 'self'; object-src 'self'; worker-src 'self';",
+  },
+
+  // Origins allowed to message this extension. The framework default is your
+  // brand's own origin (from `brand.url`), plus the local dev website's origin
+  // in a dev build — so the live site can message the published extension.
+  // DECLARING the key is authoritative: it REPLACES that default outright, and
+  // an empty array ships NO origins at all. Leave it out to keep the default.
+  // externally_connectable: {
+  //   matches: [
+  //     'https://example.com/*',
+  //   ],
+  // },
+
+  // Web accessible resources
+  web_accessible_resources: [
+    // Icon set (C4 cp112): lets content-script-injected UI fetch icons via
+    // chrome.runtime.getURL('assets/icons/…'). Extension pages don't need this.
+    {
+      matches: [
+        '<all_urls>',
+      ],
+      resources: [
+        'assets/icons/*',
+      ],
+    },
+    // {
+    //   matches: [
+    //     '<all_urls>',
+    //   ],
+    //   resources: [
+    //     'assets/styles/content.bundle.css',
+    //   ],
+    // },
+  ],
+
+  // Commands
+  commands: {
+    // test: {
+    //   description: 'Test',
+    //   suggested_key: {
+    //     default: 'Alt+T',
+    //   },
+    // },
+  },
+
+  // Sandbox
+  sandbox: {
+    pages: [
+      // 'views/sandbox/index.html',
+    ],
+  },
+
+  // IDs
+  browser_specific_settings: {
+    gecko: {
+      // The firefox artifact needs an add-on id (Firefox cannot identify, sign,
+      // or update an add-on without one). Leave this commented out and the build
+      // DERIVES `extension@<your brand host>` from the brand config — only a
+      // project with no brand facts at all fails. Declare your own before the
+      // FIRST publish: the id must stay stable across releases, an id assigned
+      // at submission can never be changed from a self-hosted build, and
+      // `brand.url` can change.
+      // id: 'my-addon@example.com',
+      // strict_min_version: '91.0',
+      data_collection_permissions: {
+        required: ['authenticationInfo'],
+        optional: ['technicalAndInteraction'],
+      },
+    },
+  },
+}

package/dist/defaults/src/views/offscreen/index.html

@@ -0,0 +1,3 @@
+<!-- Offscreen Document -->
+<!-- This document is invisible and persists for background operations -->
+<div id="offscreen-root"></div>

package/dist/defaults/src/views/options/index.html

@@ -0,0 +1,8 @@
+<div class="options-container p-4">
+  <h1 class="h2 mb-4">Settings</h1>
+
+  <section class="settings-section mb-4">
+    <h2 class="h5 mb-3">General Settings</h2>
+    <p class="text-muted">Configure your extension settings here.</p>
+  </section>
+</div>

package/dist/defaults/src/views/pages/index.html

@@ -0,0 +1,10 @@
+<div class="page-container p-4">
+  <header class="page-header mb-4">
+    <h1 class="h2">Welcome</h1>
+    <p class="lead text-muted">Your extension page is ready.</p>
+  </header>
+
+  <main class="page-content">
+    <p>Add your page content here.</p>
+  </main>
+</div>

package/dist/defaults/src/views/popup/index.html

@@ -0,0 +1,4 @@
+<div class="popup-container p-3">
+  <h1 class="h4 mb-3">Popup</h1>
+  <p class="text-muted">Add your popup content here.</p>
+</div>

package/dist/defaults/src/views/sidepanel/index.html

@@ -0,0 +1,4 @@
+<div class="sidepanel-container p-3">
+  <h1 class="h4 mb-3">Side Panel</h1>
+  <p class="text-muted">Add your sidepanel content here.</p>
+</div>

package/dist/defaults/test/README.md

@@ -0,0 +1,41 @@
+# Project tests
+
+Drop your project test suites here. The framework auto-runs them alongside its own when you run `npx omega test`.
+
+## Layers
+
+Match the framework's four layers — OMEGA Extension's test runner discovers files by the directory they sit in:
+
+| Directory | Runtime | Use for |
+|---|---|---|
+| `test/build/` | Plain Node | Build-time logic, manifest validation, pure utilities |
+| `test/background/` | MV3 service worker context | Background messaging, auth source-of-truth, alarms |
+| `test/view/` | Popup / options / sidepanel page | DOM, view-side controllers, `data-omega-bind` directives |
+| `test/boot/` | Consumer's actual built extension | End-to-end smoke tests (does the extension load, does the background register, do views render) |
+
+## Coverage
+
+Every feature ships with tests at every layer it has a surface in — logic (`build`/`background`), UI (`view`), end-to-end (`boot`). Skip a layer only when the feature genuinely has no surface there; "the logic test covers it" does not excuse the UI test.
+
+Tests that hit REAL external services (Firebase, push, network) are skipped by default — gate them on `process.env.TEST_EXTENDED_MODE` (`if (process.env.TEST_EXTENDED_MODE !== 'true') ctx.skip('extended mode off');`) and run them with `npx omega test --extended` (or `TEST_EXTENDED_MODE=true`). `TEST_EXTENDED_MODE` is the shared, unprefixed name across every OMEGA framework (@omega.js/backend, @omega.js/extension, @omega.js/web, @omega.js/desktop). Never mock the external service — skip it in-source.
+
+## Quick example
+
+```js
+// test/build/my-feature.test.js
+const Manager = require('@omega.js/extension/build');
+
+module.exports = {
+  layer: 'build',
+  description: 'the project config carries a brand id',
+  run: (ctx) => {
+    ctx.expect(Manager.getConfig().brand.id).toBeTruthy();
+  },
+};
+```
+
+That is the standalone form: one test per file. Every `run` receives `ctx`, whose `ctx.expect` is the Jest-compatible assertion library (there is nothing to require). The `suite`, `group` and array forms, and the `inspect` form the `boot` layer takes, are all in the reference below.
+
+## See also
+
+`node_modules/@omega.js/extension/docs/test-framework.md` — full reference for the test framework (layers, assert API, fixtures, runner internals).

package/dist/defaults/test/_init.js

@@ -0,0 +1,10 @@
+/**
+ * Test lifecycle hook for this project. Runs once before any suite (not a test itself).
+ * See @omega.js/extension/docs/test-framework.md → "test/_init.js".
+ */
+
+module.exports = ({ projectRoot }) => ({
+  // Seed any fixture a suite needs before it runs.
+  async setup() {
+  },
+});

package/dist/defaults/test/boot/externally-connectable.test.js

@@ -0,0 +1,28 @@
+/**
+ * Boot-layer test — the packaged extension can be messaged by YOUR site.
+ *
+ * `externally_connectable.matches` is baked at package time from `brand.url`
+ * (plus the local dev origin in a dev build). A packaged build used to carry the
+ * localhost dev origin alone, so the live brand site could not message the
+ * published extension at all ([#583]). This asserts the real, built manifest of
+ * the extension Chromium just loaded.
+ *
+ * Declaring `externally_connectable` in `src/manifest.json` is authoritative and
+ * replaces the default outright — if you do that deliberately, edit this test to
+ * match the origins you declared.
+ */
+
+module.exports = {
+  layer: 'boot',
+  description: 'the packaged manifest lets the brand site message the extension',
+  inspect: async ({ extension, expect }) => {
+    const Manager = new (require('@omega.js/extension/build'));
+    const brandUrl = Manager.getConfig().brand?.url;
+
+    // Nothing to assert until the brand declares its own site
+    if (!brandUrl) return;
+
+    const matches = extension.manifest.externally_connectable?.matches || [];
+    expect(matches).toContain(`${new URL(brandUrl).origin}/*`);
+  },
+};

package/dist/gulp/config/locales.js

@@ -0,0 +1,12 @@
+// Locale field limits (Chrome Web Store requirements)
+// https://developer.chrome.com/docs/webstore/i18n
+// Target languages live in config/omega.json5 → translation.languages,
+// validated against @omega.js/devkit/translate's language SSOT.
+module.exports = {
+  // Field character limits
+  limits: {
+    appName: 50,
+    appNameShort: 25,
+    appDescription: 200,
+  },
+};

package/dist/gulp/main.js

@@ -0,0 +1,78 @@
+// Libraries
+const Manager = new (require('../build.js'));
+const logger = Manager.logger('main');
+const argv = Manager.getArguments();
+const { series, parallel } = require('gulp');
+const path = require('path');
+const glob = require('glob').globSync;
+
+// Load package
+const package = Manager.getPackage('main');
+const project = Manager.getPackage('project');
+const projectRoot = Manager.getRootPath('project');
+
+// Resolve the .env cascade from the project root (shell > app > brand > company).
+// `target` delivers the schema's `deliverAs` renames into process.env (#678);
+// gulp can be invoked outside the CLI (`npx gulp build`), so it asks here too.
+require('../vendor/config/index.js').loadEnv(projectRoot, { target: 'extension' });
+
+// Tee all stdout/stderr to <projectRoot>/logs/<dev|build>.log for easy `tail -f` / grep / Claude
+// inspection — captures gulp task output, bundle/serve output, console.log calls, the works.
+// build.log for production builds (OMEGA_BUILD_MODE=true), dev.log for `npm start`.
+// Disable via OMEGA_LOG_FILE=false. Override path via OMEGA_LOG_FILE=<path>.
+const attachLogFile = require('../utils/attach-log-file.js');
+const logFileEnv = process.env.OMEGA_LOG_FILE;
+if (logFileEnv !== 'false' && logFileEnv !== '0') {
+  const defaultName = Manager.isBuildMode() ? 'build.log' : 'dev.log';
+  const logPath = (logFileEnv && logFileEnv !== 'true') ? logFileEnv : path.join(projectRoot, 'logs', defaultName);
+  attachLogFile(logPath);
+  logger.log(`Logs tee'd to ${logPath}`);
+}
+
+// Log
+logger.log('Starting...', argv);
+
+// Load tasks
+const tasks = glob('*.js', { cwd: `${__dirname}/tasks` });
+
+// Init global
+global.tasks = {};
+global.websocket = null;
+
+// Load tasks
+tasks.forEach((file) => {
+  const name = file.replace('.js', '');
+
+  // Log
+  logger.log('Loading task:', name);
+
+  // Export task
+  exports[name] = require(path.join(__dirname, 'tasks', file));
+});
+
+// Set global variable to access tasks in other files
+global.tasks = exports;
+
+// Define build process
+exports.build = series(
+  // exports.setup,
+  // exports.clean,
+  // exports.themes,
+  exports.defaults,
+  exports.distribute,
+  exports.translate,
+  parallel(exports.sass, exports.bundle, exports.icons, exports.fontawesome, exports.html),
+  exports.package,
+  exports.audit,
+  exports.publish,
+);
+
+// Compose task scheduler
+exports.default = series(
+  // exports.setup,
+  // exports.clean,
+  exports.serve,
+  exports.build,
+  // exports.developmentRebuild,
+  // exports.watcher,
+);

package/dist/gulp/tasks/_.js

@@ -0,0 +1,18 @@
+// Libraries
+const Manager = new (require('../../build.js'));
+const logger = Manager.logger('XXX');
+
+// Load package
+const package = Manager.getPackage('main');
+const project = Manager.getPackage('project');
+const rootPathPackage = Manager.getRootPath('main');
+const rootPathProject = Manager.getRootPath('project');
+
+// Task
+module.exports = function XXX(complete) {
+  // Log
+  logger.log('Starting XXX...');
+
+  // Complete
+  return complete();
+}