@omega.js/extension 0.1.0

package/docs/css.md

@@ -0,0 +1,133 @@
+# CSS Architecture
+
+SCSS-based, theme-pluggable, with a load-path system that lets consumer SCSS reference framework + theme styles via short names (`@use 'omega-extension'`, `@use 'theme'`).
+
+## Main entry
+
+[src/assets/css/@omega.js/extension.scss](../src/assets/css/@omega.js/extension.scss) is the framework's CSS entry point. Consumers `@use` it to get framework defaults + utilities + theme.
+
+## Core modules
+
+| Module | Source |
+|---|---|
+| `core/_initialize.scss` | Base resets (box-sizing, body defaults) |
+| `core/_utilities.scss` | Utility classes (`.shadow-lg`, `.text-truncate`, spacing, color, etc.) |
+| `core/_animations.scss` | Keyframe animations + transition mixins |
+| `core/_fontawesome.scss` | Icon presentation: the square glyph-centered box, the `fa-2xs`…`fa-6xl` size scale, `fa-spin`/`fa-bounce`/`fa-beat`. Vendored VERBATIM from @omega.js/web at prepare (package.json `omega.vendorAssets`), never hand-edited here. See [shared/icons.md](shared/icons.md) |
+
+## Per-component styles
+
+Each component can have framework defaults in `src/assets/css/components/<name>/index.scss`. These define the FRAMEWORK'S default look — e.g. `src/assets/css/components/popup/index.scss` defines popup-specific layout that ALL @omega.js/extension extensions inherit unless they override.
+
+Consumer extensions add their OWN per-component overrides in `src/assets/css/components/<name>/index.scss` (in the consumer project, not the framework).
+
+## Load-path resolution
+
+The SCSS load path is set up by [src/gulp/tasks/sass.js](../src/gulp/tasks/sass.js) with this search order:
+
+1. **Framework CSS** — `node_modules/@omega.js/extension/dist/assets/css`
+2. **Active theme** — `node_modules/@omega.js/extension/dist/assets/themes/<theme-id>`
+3. **Project dist** — `<consumer>/dist/assets/css`
+4. **node_modules** — for npm-installed SCSS packages
+
+So this just works in a consumer's `src/assets/css/main.scss`:
+
+```scss
+// 1. Resolves to @omega.js/extension's main entry — sets up Bootstrap, utilities, etc.
+@use 'omega-extension' as * with (
+  $primary: #2563EB,
+);
+
+// 2. Resolves to the active theme's _theme.scss
+@use 'theme' as *;
+
+// 3. Resolves to @omega.js/extension's bundled popup defaults
+@use 'components/popup' as *;
+
+// 4. Resolves to npm-installed CSS package
+@use 'pkg:bootstrap-icons' as *;
+
+// Consumer-authored overrides come last
+.my-custom-rule { color: $primary; }
+```
+
+## Component bundle output
+
+Each component context gets a CSS bundle:
+
+- `src/assets/css/components/<component>/index.scss` → `dist/assets/css/components/<component>.bundle.css`
+
+The HTML pipeline auto-injects `<link rel="stylesheet" href="../assets/css/components/<component>.bundle.css">` into each view via the page template.
+
+## Theme integration
+
+Theme SCSS is vendored from @omega.js/web's `themes/` tree into `dist/assets/themes/<theme-id>/` at prepare (C4 cp109 — one theme tree for web/desktop/extension). The load path resolves `@use 'theme'` to the active theme — flip `config.theme.id` to switch themes without code changes. See [themes.md](themes.md).
+
+## App shell
+
+Dashboard-style views (options, side panel, extension pages) use the `.omega-shell` layout — a sidebar + topbar + main grid with a collapsible desktop rail and a mobile drawer. Two layers ship, both vendored from @omega.js/web at prepare: the MECHANICS (`dist/assets/css/shell/_index.scss` — the grid, region geometry, states, and the `--omega-shell-*` tokens, loaded by the `omega-extension` entry before the theme) and the theme's SKIN (`dist/assets/themes/<theme-id>/css/layout/_shell.scss`, layered over it). Nothing to import — `@use 'omega-extension'` gets both.
+
+Emit this markup in the view's HTML:
+
+```html
+<div class="omega-shell" data-omega-shell>
+  <aside class="omega-shell__sidebar" id="app-sidebar">
+    <!-- pinned head (brand, selector) sits here, outside the scroll region -->
+    <div class="omega-shell__sidebar-scroll">
+      <!-- nav scrolls HERE (the rail itself clips nothing, so popovers can
+           escape); text that should hide in the collapsed rail wears
+           .omega-shell__label -->
+    </div>
+  </aside>
+
+  <header class="omega-shell__topbar">
+    <div class="omega-shell__topbar-start">
+      <button data-shell-toggle="drawer" aria-expanded="false" aria-controls="app-sidebar">☰</button>
+      <button data-shell-toggle="collapse" aria-expanded="true" aria-controls="app-sidebar">⇤</button>
+    </div>
+    <div class="omega-shell__topbar-end"><!-- account menu, actions --></div>
+  </header>
+
+  <main class="omega-shell__main"><!-- page content --></main>
+
+  <div class="omega-shell__scrim" data-shell-dismiss></div>
+</div>
+```
+
+Wire the behavior from the view's script (`src/assets/js/components/<component>/index.js`) — `__main_assets__` is the build alias for @omega.js/extension's vendored core assets:
+
+```js
+import appShell from '__main_assets__/js/core/app-shell.js';
+
+appShell();
+```
+
+The module is delegated and declarative: `[data-shell-toggle="collapse"]` toggles the rail, `[data-shell-toggle="drawer"]` toggles the mobile drawer, `[data-shell-dismiss]` (and Escape) closes it. It stamps the state on the container — `data-shell-collapsed="true"` (persisted under the `shell.collapsed` storage key) and `data-shell-open="true"` — which is what the CSS keys off; the API is also registered at `omega._library.appShell`. Add `.omega-shell--locked` when `main` should never scroll (the view manages its own interior scroll).
+
+## Adding a utility class
+
+[src/assets/css/core/_utilities.scss](../src/assets/css/core/_utilities.scss):
+
+```scss
+.shadow-lg {
+  box-shadow: 0 10px 15px -3px rgba(0, 0, 0, 0.1);
+}
+```
+
+After adding, run `npm run prepare` in @omega.js/extension (or `npm start` in the consumer) and the new utility is available framework-wide.
+
+## Why this load-path system
+
+Without it, every consumer SCSS file would need:
+
+```scss
+@use '../../../../node_modules/@omega.js/extension/dist/assets/css/@omega.js/extension' as *;
+```
+
+Brittle, ugly, breaks with hoisted/non-hoisted npm installs. The load-path lets `@use 'omega-extension'` work regardless of where @omega.js/extension is installed. Same pattern UJM uses for Jekyll themes.
+
+## See also
+
+- [themes.md](themes.md) — theme system that the load path resolves
+- [components.md](components.md) — three-part component structure (view + styles + script)
+- [build-system.md](build-system.md) — gulp/sass task details

package/docs/defaults.md

@@ -0,0 +1,72 @@
+# Defaults System
+
+`src/defaults/` is the starter template that @omega.js/extension copies into consumer projects on the first verb they run (`ensureTarget()`). It mirrors a "fresh @omega.js/extension project" — manifest, views, components, config, .nvmrc, .gitignore, .env, etc.
+
+## How it works
+
+1. During @omega.js/extension's own build (`prepare-package`), files in `src/defaults/` are copied to `dist/defaults/`.
+2. On every consumer verb, the `gulp defaults` task scaffolds files from `dist/defaults/` into the consumer's project root — dispatch runs through the shared devkit defaults engine (`applyDefaults`, vendored into `dist/vendor/devkit/`).
+3. File behavior (overwrite, skip, template, rename, merge) is controlled by `FILE_MAP` in [src/gulp/tasks/defaults.js](../src/gulp/tasks/defaults.js) — minimatch patterns, last-match-wins.
+
+## FILE_MAP rules
+
+```js
+const FILE_MAP = {
+  'src/**/*':            { overwrite: false },      // never overwrite user code
+  'hooks/**/*':          { overwrite: false },      // never overwrite hooks
+  '_.gitignore':         { mergeLines: true },      // marker-section merge (rename is an engine built-in)
+  'AGENTS.md':           { mergeLines: true },      // the agent-docs chain; CLAUDE.md is the one-line pointer
+  'config/omega.json5':  { overwrite: true, merge: true },  // JSON5 defaults merge
+  '.nvmrc':              { template: cleanVersions },       // `{{ versions.node }}` render
+};
+```
+
+## Rule types
+
+| Rule | Behavior |
+|---|---|
+| `overwrite: false` | Never replace if the file exists in the project. Default for `src/**`. |
+| `overwrite: true` | Always overwrite — for files @omega.js/extension owns (writes are skipped when byte-identical). |
+| `skip: bool\|function` | Never process — `(item) => boolean` for dynamic decisions. |
+| `template: data` | Render `{{ key.path }}` tokens with `data` (tolerant — unknown keys survive). |
+| `merge: true` | JSON5 defaults merge — consumer values and consumer-only keys survive, framework template provides shape. |
+| `mergeLines: true` | OMEGA marker-section merge (`Default Values` framework-owned / `Custom Values` consumer-owned). |
+| `name`/`path: function` | Rename / re-destination on copy. |
+
+Engine built-ins (no rule needed): `_.foo` → `.foo` renames, `.gitkeep` creates the directory without copying the file, `.DS_Store` never copies, archive dirs (non-final `_x` segments) never ship, and every write is skipped when the content is unchanged. On top of the per-rule handling, the task's site-token pass (`[ site.x ]` brackets) runs on `html/md/liquid/json/yml/yaml` files via the engine's `transform` hook.
+
+## Brand monorepos
+
+When the target sits inside a brand monorepo (`{brand}/targets/{target}` — the `@omega.js/config` seed mode), `scaffoldDefaults` adjusts the map: the local-layer `config/omega.json5` is skipped (the brand root's `targets.*` is the home), per-target docs retire to the brand root, and **`.github/**` never scaffolds**. GitHub executes workflows from the REPO ROOT's `.github/workflows/` only, so a per-target copy is dead on arrival — no CI build, no store publish, silently ([#265](https://github.com/Omega-JS-Stack/omega/issues/265)).
+
+Instead, setup composes the framework's workflow into the brand root as `.github/workflows/<target>-<workflow>.yml` (`extension-publish.yml`) via the shared devkit `ci-workflows` module:
+
+- every `run:` step that follows its job's `actions/checkout` is scoped to the target (a per-step `working-directory: targets/extension`), while `uses:` actions still run at the repo root, which is what checkout wants. Per step, not a workflow-level `defaults.run.working-directory`: that also scopes the steps running BEFORE the checkout (the git config step), where the target dir does not exist yet — the job dies on step 1;
+- an action's inputs ignore `working-directory:` entirely, so the path-bearing ones on post-checkout `uses:` steps are rewritten to the target dir from an explicit per-action table (`actions/cache`/`upload-artifact`/`download-artifact` `path`, `peaceiris/actions-gh-pages` `publish_dir`), as are `hashFiles()` patterns, which glob from the workspace root wherever they sit. The extension template uses none of them today — it carries only checkout and setup-node — so its composed file differs from the template by the `working-directory:` lines alone;
+- each target gets its own concurrency group, so one target's deploy never cancels another's;
+- the file is regenerated from the template on every setup — a rerun updates that one file and can never duplicate a job;
+- a target-level copy left by an older setup is deleted when it is still the untouched framework file, and KEPT with a warning when it differs from the current template (your edits, or an older framework version) — the warning names the composed file to compare it against.
+
+Scoping is by working directory, not a `paths:` trigger filter: OMEGA workflows carry no push triggers by design (deliberate deploys), and a path filter on a dispatch-only workflow filters nothing. `omega deploy` dispatches the composed name in a brand, the plain `publish.yml` standalone.
+
+## Why the underscore prefix?
+
+Files like `_.gitignore` are stored with a `_` prefix in `src/defaults/` so they don't interfere with @omega.js/extension's own development and so npm's tarball filter doesn't drop them. The engine strips the leading `_` on copy.
+
+## Adding a new default
+
+1. Drop the file under `src/defaults/<path-where-it-goes-in-the-consumer>`
+2. If it needs special handling, add an entry to `FILE_MAP` in [tasks/defaults.js](../src/gulp/tasks/defaults.js)
+3. Run `npm run prepare` to refresh @omega.js/extension's `dist/`
+4. Verify in a fresh consumer project: `mkdir test-consumer && cd test-consumer && npm i ../@omega.js/extension && npx omega build`
+
+## Why this exists
+
+Consumers shouldn't have to hand-author boilerplate (manifest, sample views, sample SCSS, sample background.js, .nvmrc, .gitignore). The defaults system seeds a working extension on the first verb. Same idea as `create-react-app` or `vite create`, just integrated with @omega.js/extension's CLI.
+
+When @omega.js/extension ships a framework improvement (e.g. a better default popup template), bumping @omega.js/extension in a consumer + running any verb again pulls the improvements WITHOUT overwriting user changes (because most `src/**` entries are `overwrite: false`).
+
+## See also
+
+- [cli.md](cli.md) — every verb's `ensureTarget()` invokes the defaults task
+- [build-system.md](build-system.md) — gulp tasks pipeline

package/docs/environment-detection.md

@@ -0,0 +1,79 @@
+# Environment Detection
+
+`getEnvironment()` returns exactly ONE of three mutually-exclusive, exhaustive values:
+
+```javascript
+Manager.getEnvironment()    // 'development' | 'testing' | 'production'
+
+Manager.isDevelopment()     // true ONLY in development
+Manager.isTesting()         // true ONLY in testing
+Manager.isProduction()      // true ONLY in production
+```
+
+**The Manager is the single source of truth.** `getEnvironment()` is the ONLY function that reads the raw signals (`OMEGA_TEST_MODE` / `chrome.runtime.getManifest().update_url` / `OMEGA_BUILD_MODE` / `NODE_ENV` / `config.bxm.environment`). The three `is*()` checks **derive** from it live on every call — they never read raw signals themselves, so they can never disagree with `getEnvironment()`.
+
+**One implementation, mixed into all eight Managers.** @omega.js/extension has eight Manager entry points (build / background / popup / options / content / sidepanel / page / offscreen). The helpers are defined once in [src/utils/mode-helpers.js](../src/utils/mode-helpers.js) and mixed into each via `attachTo(Manager)`, available as both prototype methods (`manager.isTesting()`) and statics (`Manager.isTesting()`).
+
+```javascript
+manager.getEnvironment()    // same answer in every extension context
+Manager.isTesting()         // static form, for build-time scripts
+```
+
+**Resolution order:** testing wins first, then production, else development. The three checks are mutually exclusive — exactly one is true. `isDevelopment()` is **false** during testing, and `isProduction()` is a real positive check (it is NOT `!isDevelopment()`).
+
+## Available helpers
+
+| Helper | Returns |
+|---|---|
+| `getEnvironment()` | `'development' \| 'testing' \| 'production'` — the SSOT resolver; the only reader of raw signals. |
+| `isDevelopment()` | `true` ONLY in development (unpacked extension via chrome://extensions / dev build), and NOT testing. Derives from `getEnvironment()`. |
+| `isTesting()` | `true` ONLY in testing (`OMEGA_TEST_MODE === 'true'`). **Takes precedence** — a test run is not development. |
+| `isProduction()` | `true` ONLY in production (packed / store-installed extension, `manifest.update_url` present). A **real positive check** — NOT `!isDevelopment()`. |
+
+## Gating side effects — use the INTENTIONAL check
+
+Because there are three environments, never gate a side effect on a two-value assumption. State what you mean:
+
+```javascript
+// Production-only (skip real telemetry / production behavior in dev AND testing):
+if (isProduction())  { /* do the real thing */ }
+if (!isProduction()) { /* skip / use the safe local behavior */ }
+
+// Local-or-test (anything that should run in BOTH dev and testing):
+if (isDevelopment() || isTesting()) { /* DevTools menu items, verbose logging */ }
+```
+
+**Avoid** `if (!isDevelopment())` or `if (env !== 'development')` to gate production behavior — those wrongly include `testing` as production and leak real side effects during test runs. This is the bug class that motivated the 3-value model. (A genuinely dev-only feature like live-reload is the exception: `env !== 'development'` correctly skips it in both testing and production.)
+
+## URL helpers
+
+@omega.js/extension owns ONE backend URL helper, `getApiUrl()` in [src/utils/url-helpers.js](../src/utils/url-helpers.js), mixed into every context Manager beside the mode helpers. It follows the same local-in-dev/testing, production-otherwise convention as @omega.js/client's `getApiUrl`. The local port comes from whichever channel the context has: the `OMEGA_HTTPS_PORT` / `OMEGA_HOSTING_PORT` env vars (build-time Node and the test harness), then the `dev.ports` map the build baked into `OMEGA_BUILD_JSON` (a browser context has no `process.env`, so a bumped emulator port reaches it this way, [#744](https://github.com/Omega-JS-Stack/omega/issues/744)), then the classic 5002. The rule "call the getter, never hardcode" applies everywhere; the runtime contexts' other backend URLs come from the `@omega.js/client` singleton.
+
+## Where they live
+
+Source: [src/utils/mode-helpers.js](../src/utils/mode-helpers.js) for `getEnvironment()` + `is*()` + `getVersion()`. The module exposes the functions plus an `attachTo(Manager)` mixin. Attached at the bottom of all eight Manager files ([build.js](../src/build.js), [background.js](../src/background.js), [popup.js](../src/popup.js), [options.js](../src/options.js), [content.js](../src/content.js), [sidepanel.js](../src/sidepanel.js), [page.js](../src/page.js), [offscreen.js](../src/offscreen.js)), so every extension context resolves the environment identically.
+
+## How detection works
+
+`getEnvironment()` resolves in this precedence order:
+
+1. **Testing** — `process.env.OMEGA_TEST_MODE === 'true'`, `globalThis.OMEGA_TEST_MODE === true`, or a build baked with `config.bxm.environment === 'testing'` (set by the harness before any consumer JS runs). A test run is a test run regardless of any other signal.
+2. **Production / Development (runtime)** — `chrome.runtime.getManifest().update_url`: present → production (packed / store-installed), absent → development (unpacked). This is the authoritative runtime signal in an extension context. In build-time Node, `chrome` is undefined, so it falls through.
+3. **Build-time + config signals** — `OMEGA_BUILD_MODE === 'true'` → production; `NODE_ENV === 'development'` → development; `config.bxm.environment` (`'development'` / `'production'`) override.
+4. **Default** — development. @omega.js/extension's deployed artifacts always carry their signal (a packed / store extension has `manifest.update_url`; build-time Node sets `OMEGA_BUILD_MODE`), so reaching here means a bare tooling / unpacked context where development is correct. (Contrast @omega.js/backend/EM, whose deployed *runtime* can legitimately lack a signal, so they default to **production**.)
+
+## Adding a new helper
+
+Write the function in [src/utils/mode-helpers.js](../src/utils/mode-helpers.js) (or a new `src/utils/<topic>-helpers.js` module), expose it from `attachTo(Manager)`, then call `attachTo` at the bottom of all eight Manager files. Don't define helpers on individual Manager prototypes — that leads to duplicated semantics. For anything environment-derived, derive from `getEnvironment()` rather than reading `chrome.runtime` / `process.env` directly, so there is one source of truth and no chance of drift.
+
+## Why this matters
+
+**One signal, used everywhere.** The test runner sets `OMEGA_TEST_MODE=true`; every piece of code that calls `isTesting()` (framework or consumer) then sees `true` — no need to invent a per-module env var.
+
+**Sub-modules check the same signal.** When framework code (an auto-update probe, an analytics flush) needs to skip side effects in tests, it checks `isTesting()` — the same answer the consumer's own code gets. No drift.
+
+**`is*()` can never disagree with `getEnvironment()`.** Because the checks derive from the single resolver instead of reading raw signals (`manifest.update_url` vs `OMEGA_BUILD_MODE`), there is exactly one definition of "what environment is this," and a wrong-but-confident gate is structurally impossible.
+
+## See also
+
+- [test-framework.md](test-framework.md) — `OMEGA_TEST_MODE` is set automatically by the test runners; extended mode (`--extended` / `TEST_EXTENDED_MODE=true`) gates real external APIs.

package/docs/extension.md

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

package/docs/hooks.md

@@ -0,0 +1,111 @@
+# Build Hooks
+
+Two lifecycle hooks let consumers run custom logic during the build pipeline.
+
+## Hook files
+
+| Hook | Source | When |
+|---|---|---|
+| `build:pre` | `hooks/build/pre.js` (in consumer project) | Before packaging — after `dist/` is built but before `packaged/` is assembled |
+| `build:post` | `hooks/build/post.js` | After packaging — `packaged/<browser>/raw/` and `.zip` exist |
+
+Hooks are optional — `gulp/tasks/package.js` checks for the file's presence and runs it if present.
+
+The NESTED path above is authoritative: it is what `src/defaults/hooks/build/` scaffolds and what setup's migration moves a flat `hooks/build:pre.js` to. The task resolves it first and falls back to the flat pre-migration path during the transition, so an unmigrated project keeps building ([#571](https://github.com/Omega-JS-Stack/omega/issues/571)).
+
+## Hook shape
+
+```js
+// hooks/build/pre.js
+module.exports = async function ({ manager, projectRoot, mode }) {
+  console.log('Pre-build hook running for', manager.getConfig().brand.name);
+
+  // Mutate files, generate assets, validate, anything you want.
+  // Return a Promise (or use async fn) to make the build wait.
+};
+```
+
+## The `ctx` argument
+
+Hooks take the ONE hook-argument shape every OMEGA framework passes — the same `ctx` @omega.js/desktop hands its lifecycle hooks:
+
+- `ctx.manager` — the build `Manager` instance (`@omega.js/extension/build`)
+- `ctx.projectRoot` — the consumer project root, absolute
+- `ctx.mode` — `'production'` when `OMEGA_BUILD_MODE=true`, else `'development'`
+
+Everything else a build hook needs comes off `ctx.manager`:
+
+| What you want | Where it is |
+|---|---|
+| Parsed `package.json` | `manager.getPackage('project')` |
+| Parsed `src/manifest.json` (JSON5) | `manager.getManifest()` |
+| Resolved `config/omega.json5` (targets.extension overlaid onto the top level) | `manager.getConfig()` |
+| The brand block | `manager.getConfig().brand` |
+| The project / framework roots | `manager.getRootPath('project')` / `manager.getRootPath('main')` |
+
+Until [#591](https://github.com/Omega-JS-Stack/omega/issues/591) this page described an `index` build-info object nothing ever built — the task passed its internal watch counter, so a hook written from these docs read `undefined` at its first property.
+
+## Common uses
+
+### Sync a CHANGELOG version into the manifest
+
+```js
+// hooks/build/pre.js
+const fs = require('fs');
+const path = require('path');
+
+module.exports = async function ({ manager, projectRoot }) {
+  const manifest = manager.getManifest();
+  const changelog = fs.readFileSync(path.join(projectRoot, 'CHANGELOG.md'), 'utf8');
+  const latestVersion = changelog.match(/## \[([\d.]+)\]/)?.[1];
+  if (latestVersion && latestVersion !== manifest.version) {
+    console.warn(`Manifest version (${manifest.version}) doesn't match CHANGELOG latest (${latestVersion})`);
+  }
+};
+```
+
+### Inject a build timestamp
+
+```js
+// hooks/build/pre.js
+const fs = require('fs');
+const path = require('path');
+
+module.exports = async function ({ projectRoot }) {
+  const buildInfo = {
+    builtAt: new Date().toISOString(),
+    gitSha: require('child_process').execSync('git rev-parse HEAD').toString().trim(),
+  };
+  fs.writeFileSync(path.join(projectRoot, 'dist', 'build-info.json'), JSON.stringify(buildInfo, null, 2));
+};
+```
+
+### Trigger a post-publish webhook
+
+```js
+// hooks/build/post.js
+module.exports = async function ({ manager }) {
+  if (process.env.OMEGA_IS_PUBLISH !== 'true') return;   // only after real publish
+  await fetch('https://api.myservice.com/extension-released', {
+    method: 'POST',
+    body: JSON.stringify({ version: manager.getManifest().version }),
+  });
+};
+```
+
+## Async by default
+
+Hooks are awaited — the build waits for them to resolve before continuing. Throw or reject to fail the build (and abort packaging / publishing).
+
+## Where hooks are invoked
+
+[src/gulp/tasks/package.js](../src/gulp/tasks/package.js) loads and runs them. Search for `hook(` in that file to see the exact wiring.
+
+## Why not just edit gulp tasks?
+
+You COULD fork @omega.js/extension's gulp tasks for any custom build behavior. Hooks exist so consumers don't need to. Hooks are stable contract (the `ctx` shape is the same one every OMEGA framework passes), survive @omega.js/extension upgrades, and live in the consumer's repo (where build-specific concerns belong).
+
+## See also
+
+- [build-system.md](build-system.md) — gulp pipeline details
+- [publishing.md](publishing.md) — store auto-publishing happens AFTER `build:post`

package/docs/icons.md

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