@omega.js/extension 0.1.0

package/docs/shared/translation.md

@@ -0,0 +1,291 @@
+# Translation
+
+AI translation for OMEGA consumers — one engine, config-driven, with a
+**committed** per-string cache. Shipped cp96 (Ian directive 2026-07-11),
+replacing both legacy systems: UJM's OpenAI-only gulp task with the
+`cache-uj-translation` GitHub-branch cache, and BXM's Claude-only task with a
+gitignored `.cache/` (which re-translated everything on any change and on
+every fresh clone).
+
+## Config (shared `translation` section of omega.json5)
+
+```json5
+translation: {
+  enabled: true,          // optional master switch (default true)
+  default: 'en',          // source language (default 'en')
+  languages: ['es', 'fr'],// target codes — EMPTY/ABSENT = translation off
+  providers: { claude: {} },// the engine is a KEY (#425): claude | chatgpt. Absent block = claude
+  model: null,            // optional override for the chosen engine (claude → 'sonnet' alias, chatgpt → 'gpt-5.4-nano')
+  exclude: [],            // web only: BRAND page routes/folders to skip (the framework's own default pages are already excluded — #605)
+}
+```
+
+Shared section (typically brand-level; `SHARED_SECTIONS` includes it, so
+every target inherits it through the merge chain). Language codes
+validate against the SSOT in `@omega.js/devkit/translate` (`LANGUAGE_NAMES`,
+~32 codes) — an unknown code is a hard config error naming the supported set.
+The same SSOT carries `LANGUAGE_LOCALES` + `ogLocale(code)`, the one code →
+Open Graph `language_TERRITORY` map (`es` → `es_ES`).
+
+## Providers
+
+| Provider | Rides | Credentials |
+|----------|-------|-------------|
+| `claude` (default) | the locally-installed Claude Code via `@anthropic-ai/claude-agent-sdk` | **none** — local auth |
+| `chatgpt` | OpenAI Responses API (native fetch) | `OPENAI_API_KEY` via the .env cascade |
+
+The claude provider runs **hermetic** sessions: `settingSources: []` (no user
+CLAUDE.md/hooks — they pollute mechanical output; a stop-hook reply actually
+leaked into a canary before this was locked down), a custom translator system
+prompt instead of the CLI persona, and NO `maxTurns` cap (a plain reply
+already counts as the final turn — `maxTurns: 1` reports `error_max_turns`
+even though the text arrived).
+
+**Enabling translation on web means installing the SDK (#37).** `@omega.js/web`
+does NOT ship `@anthropic-ai/claude-agent-sdk`: translation is opt-in and the
+SDK is heavy, so a web brand that turns it on installs it in the target itself
+(`npm install @anthropic-ai/claude-agent-sdk`); `@omega.js/extension` still
+declares it. The SDK is lazy-required at the first claude call, so a brand
+without translation never pays for it, and a brand that enabled translation
+without the SDK gets a hard error naming the package and that install command,
+never a silent skip. The `chatgpt` provider needs no SDK at all (native fetch
+plus `OPENAI_API_KEY`).
+
+**The manage cycle provisions it (#168).** Nobody types that install in a
+managed brand: the manager's workspace service reconciles it like every other
+brand file. A web app whose RESOLVED config translates with the `claude`
+provider gets `@anthropic-ai/claude-agent-sdk` written into its package.json
+`dependencies` (at the range `@omega.js/web` declares as its optional peer,
+read from the installed web package), followed by one `npm install` at the
+brand root. Converge-to-config, so: already declared (in `dependencies` or
+`devDependencies`) = zero-mutation no-op that never overwrites a
+consumer-chosen spec, `--dry-run` plans without writing, translation off or
+provider `chatgpt` leaves the target untouched, and turning translation back OFF
+never REMOVES the dep (uninstalling on a config flip is riskier than leaving
+it). Only web targets are provisioned, since backend and extension declare the
+SDK as a real dependency of the framework. The loud error above stays the backstop
+for hand-managed brands (`packages/manager/src/services/workspace/ensure/translation-sdk.js`,
+pinned by `packages/manager/test/workspace-translation-sdk.test.js`).
+
+## Engine protocol (`@omega.js/devkit/translate`)
+
+`translateStrings({ strings, language, languageName, brand, extraRules, send })`
+→ positionally-aligned translations:
+
+- **JSON array in → same-length JSON array out**, batches of 25.
+- **Batches fly concurrently**, `CONCURRENCY` wide (the constant at the top of
+  `packages/devkit/src/translate/engine.js`, currently 5 —
+  [#604](https://github.com/Omega-JS-Stack/omega/issues/604)). A batch is one
+  model call and the model's latency dominates it, so a serial pass paid that
+  latency once per 25 strings and one language took minutes it never needed.
+  Results are stitched back in BATCH order, never completion order, and
+  everything below still happens per batch, unchanged. Raise it only as far as
+  the providers' rate limits allow.
+- **Duplicates are deduped before batching** ([#529](https://github.com/Omega-JS-Stack/omega/issues/529)):
+  a page sends its title and description once per meta tag (`<title>`,
+  `og:title`, `twitter:title`), so the same string used to ride a batch three
+  times over — three times the AI spend, and adjacent twins are what a model
+  merges. Each unique string is translated ONCE and the translation is fanned
+  back to every occurrence. Occurrences key on the exact source string,
+  whitespace included, so a batch is 25 UNIQUE strings.
+- The `OMEGA-TRANSLATION-CONTROL` sentinel is appended to EVERY batch and must
+  return unchanged at its exact position — alignment proof per batch.
+- Validation failures (parse, length, sentinel) retry up to 2× then throw.
+- An ALIGNMENT failure (length or sentinel) that survives the retries splits the
+  batch in half and re-asks each half, down to one string
+  ([#523](https://github.com/Omega-JS-Stack/omega/issues/523)): a model that
+  merges a pair of strings does it every time, so retrying the same array can
+  only fail the same way — the playground's ship-the-docs page came back
+  25-for-26 on all six attempts, in both languages, and shipped untranslated.
+  A single string that still will not come back whole throws, and the caller
+  skips that page-language pair whole (never half-translated).
+- Original leading/trailing whitespace is re-applied to every translation.
+- Rules baked into the system prompt: preserve HTML/URLs/placeholders
+  (`$1`, `{name}`, `{{ value }}`), never translate the brand name.
+
+## The committed cache (`<app>/translations/`)
+
+`translations/{lang}/{namespace}.json` maps `sha256(source)[:12]` → translated
+string. Committed to git — that's the whole point:
+
+- **Incremental**: editing one source string changes one hash → exactly one
+  re-translation. Everything else is a cache hit (zero provider calls).
+- **Survives clones/CI**: a warm cache builds a fully-translated site with NO
+  AI credentials (kills the BXM parked finding where fresh clones burned live
+  Claude calls).
+- **Human-overridable**: hand-edit a translation VALUE in the cache file and
+  it sticks for as long as the source is unchanged (the value is the
+  translation; the key only changes when the SOURCE changes).
+- Maps are pruned to the current source set on save — no stale entries.
+
+`@omega.js/web` ships a second cache in exactly this shape for its OWN default
+pages, inside the package ([below](#framework-shipped-default-page-translations-621)).
+
+## Web (`@omega.js/web`)
+
+`omega build` translates everything by default (Ian's #24 final call): warm
+strings come from the committed cache instantly, cold strings translate live
+through the provider — a build ships the COMPLETE translated site whenever
+the provider delivers, and a warm cache means zero provider calls. A provider
+FAILURE skips that page-language pair whole, warning loudly with the page and
+the language (the build still exits 0): no half-translated copy ever ships
+behind full language chrome.
+`omega build --cached-only` skips cold page-language pairs WHOLE instead (no
+mixed-language copies, hreflang stays honest; the warning lists them) for
+provider-free builds.
+`omega translate` still runs the live pass standalone against an existing
+dist/ and exits 1 on failures. `OMEGA_TRANSLATE_ONLY=<route>` limits any of
+these to one page (canary/debug).
+
+Per page × language: text nodes/`<title>`/meta/attribute copy translate
+(cache-first), then the copy lands at `dist/{lang}/...` with `<html lang dir>`
+(RTL-aware), canonical + `og:url` + `og:locale` localized, internal links
+rewritten to `/{lang}/...`, and hreflang + `og:locale:alternate` tags
+stitched into BOTH the copy and the original — naming only the languages
+actually PRODUCED for that page (a pair skipped cold or failed is never
+advertised, on the copies as on the originals), so hreflang never lies.
+`og:locale` carries Open Graph's `language_TERRITORY` form (`en_US`,
+`es_ES`) from the devkit language SSOT's locale map — on translated copies
+and on the source pages the head include renders. Cache namespace:
+`pages/{route}` (`pages/home` for `/`).
+
+On a site served under a base path ([#355](https://github.com/Omega-JS-Stack/omega/issues/355)),
+link rewriting composes **prefix, then language**: the pass reads the mount
+point off the `<html data-omega-path-prefix>` stamp the build wrote (so
+`omega translate` standalone sees it too), takes the route from underneath it,
+and mounts the language segment after it — `/workkit/es/pricing`, never
+`/es/workkit/pricing` ([#359](https://github.com/Omega-JS-Stack/omega/issues/359)).
+Exclusions are matched on that same underneath-the-prefix route. ABSOLUTE URLs
+(canonical, `og:url`, hreflang alternates, the sitemap entries) are built from
+`brand.url`, which for a mounted site already carries the path — nothing
+prefixes them twice.
+
+Never sent to the PROVIDER, and the framework owns the list
+([#605](https://github.com/Omega-JS-Stack/omega/issues/605)): every one of its
+OWN default pages whose layout says it is plumbing rather than marketing copy —
+the auth flows, the `/app` shell, the account/payment/portal screens, the legal
+boilerplate, `404`, and the redirect stubs (`/login`, `/account`, `/cancel`, …).
+Those pages still get their `/{lang}/` copies — from the translations PACKAGED
+with `@omega.js/web`, at no cost to the brand (next section).
+The list is DERIVED from the packaged defaults tree
+(`packages/web/defaults/pages/**`, read by `src/translate/default-routes.js`),
+never typed out, so a default page that moves or arrives cannot drift out of it,
+and each excluded route guards its subtree too. On top of that: socials
+redirects (config `socials` keys), the `admin`/`test`/`team`/`updates` folders,
+every known language-code folder, plus config `translation.exclude` — which is
+for the BRAND's own pages, and only those. A brand that lists `signin` or
+`account` is listing something the framework already skips.
+Element opt-out: `data-omega-no-translate`. Collector fixes vs UJM:
+`aria-describedby`/`aria-labelledby` are NOT collected (ID refs), `value`
+only on button-type inputs (hidden-input tokens stay intact).
+
+### Framework-shipped default-page translations ([#621](https://github.com/Omega-JS-Stack/omega/issues/621))
+
+The default pages above render the SAME chrome on every brand, so the framework
+translates them ONCE and ships the result: `packages/web/translations/{lang}/pages/{route}.json`,
+the identical `{lang}/{namespace}.json` shape as a consumer's own cache (same
+loader, same `sha256(source)[:12]` keys, same prune-on-save, hand-fixable the
+same way), committed to the package and published under `files`.
+
+The keys are brand-NEUTRAL. The generator renders with a fixture brand and
+replaces every occurrence of it with the sentinel `__OMEGA_BRAND__` before
+hashing; the read-through replaces the CONSUMER's `brand.name` with the same
+token before the lookup and puts it back on the way out, so "Sign in to MiniCo"
+and "Sign in to Acme" are one packaged entry (`src/translate/packaged-defaults.js`).
+
+Consumer side, on every pass — `omega build`, `--cached-only`, `omega translate`
+alike, since it never touches a provider:
+
+- Each default route gets its `dist/{lang}/…` copy with the same localized
+  chrome, hreflang and sitemap entry as any other page. Link rewriting is the
+  same pass too, which means links OUT to brand pages gain the language segment
+  while links between two default routes (signin → signup) do not — those routes
+  are excluded from rewriting, and that is unchanged from #605.
+- A string the package does not carry (copy the brand overrode, a page the
+  framework has not regenerated for) stays in the source language and is
+  COUNTED — one log line per route names the miss count. Never guessed at.
+- A brand whose NAME is a word the chrome itself uses ("Sign") still gets every
+  string that does not interpolate the brand — the lookup falls back to the raw
+  key when the sentinel-normalized one misses. The strings that DO interpolate
+  it (`Sign in to Sign`) miss, and stay in the source language.
+- A route the package carries nothing for gets NO copy, so hreflang keeps
+  telling the truth. That is how the legal boilerplate stays one language:
+  `terms`/`privacy`/`cookies` are deliberately not generated.
+- A configured language the package does not ship is one log line for the whole
+  run, not an error — those routes stay in the source language.
+- A route the brand named in `translation.exclude` is left alone entirely.
+
+**Shipped set: `es`, `fa`.** Regenerating, or extending the set, is one command
+in `packages/web` (the ONLY place the framework's own pages ever reach a
+provider):
+
+```bash
+npm run translate:defaults                      # the shipped set
+npm run translate:defaults -- --languages es,fa,de   # …plus a new one
+```
+
+It renders the defaults tree through the real production build against a
+throwaway consumer (no brand repo involved), harvests with the same collector
+the pass uses, translates ONLY the strings the packaged cache is missing —
+across all routes at once, so the header/footer chrome every default page
+repeats is paid for exactly once — and writes the files back. Idempotent: a
+re-run costs nothing, adding a language costs only that language. A provider
+failure, or a translation that dropped the sentinel, STOPS the run and writes
+nothing.
+
+`dist/sitemap.xml` (emitted by the build in the source language only) is
+rewritten afterwards so it tells the same story: every PRODUCED copy joins it
+as its own `<url>`, and each entry of a translated set — source and copies
+alike — carries the full `xhtml:link rel="alternate"` list (`x-default` at the
+source language) plus the source entry's `lastmod`/`changefreq`/`priority`.
+Entries stay in loc byte order. The language-prefixed entries are owned by that
+pass: each run drops them all and re-emits only what it produced, so a skipped
+or failed pair is listed nowhere.
+
+The visitor-facing **language switcher** is the footer dropup in the shared
+base footer include (`_includes/frontend/sections/footer.html`, the base layer
+every theme inherits). It renders CLIENT-SIDE from the page's own
+`link[rel="alternate"][hreflang]` tags — the produced-only SSOT above — so the
+menu can never offer a copy that was not written: `core/js/core/language-switcher.js`
+drops `x-default`, labels each row with its native name (`Intl.DisplayNames` in
+that language's own locale, upper-cased code as the fallback), marks
+`documentElement.lang` as current, and leaves the mount empty and hidden when
+fewer than two languages exist. Selecting a language is a plain link to that
+alternate's href — never a redirect or a negotiation.
+
+Not here yet: no default homepage exists in the D8 set, so brand sites
+translate their own `index` when they add one.
+
+## Extension (`@omega.js/extension`)
+
+Build-mode gulp `translate` task (setup/dev builds only deploy):
+
+- **messages**: per-KEY incremental — unique `message` values without a cache
+  entry translate (CWS limits ride the prompt as extra rules; violations warn
+  with the file path to shorten). `dist/_locales/{lang}/messages.json` is
+  COMPOSED from the EN source + cache (English fallback per missing key, so
+  the file is always complete; developer `description` fields stay English).
+- **description**: whole-document per language →
+  `translations/{lang}/description.md`, first line
+  `<!-- omega:source <hash> -->` (stripped on read; source edit →
+  re-translate). The package task ships them as store assets
+  (`packaged/assets/description/{lang}.md`).
+
+Languages/provider come from resolved config — the old hardcoded 16-language
+list in `gulp/config/locales.js` is gone (only the CWS `limits` remain there).
+
+## Testing
+
+- devkit `test/translate.test.js` — engine protocol, providers, cache,
+  language SSOT, settings reader (fake `send`).
+- web `test/translate.test.js` — handcrafted dist through the real pipeline:
+  copies/chrome/links/exclusions/alternates/cache/override/only-filter, the
+  produced-languages-only alternates, and the loud failure skip.
+- web `test/language-switcher.test.js` — the switcher's DOM read (x-default
+  dropped, duplicates collapsed, current marked, escaping) and the built footer
+  mount in classy and newsflash.
+- extension `build/translate.test.js` — compose + description marker glue.
+- Live canary (cp96, local Claude): omega-brand `/about` → es (102 strings,
+  rerun 0 calls) and the extension's 4 messages (2 unique) + 2,703-char
+  description → es, both idempotent; artifacts committed under each target's
+  `translations/`.

package/docs/shared/updates.md

@@ -0,0 +1,61 @@
+# Dependency updates (`omega update`)
+
+One shared implementation (`@omega.js/devkit/update`) behind every framework's `omega update` verb (aliases: `outdated`, `out` — npu's muscle memory), thin wiring in web/desktop/extension (router commands), backend (colon-style command class), and the manager (brand-root fan-out). Semantics mirror Ian's `npu out` (node-power-user): report first, apply deliberately, and never trust a brand-new release.
+
+## The report (default — no flags)
+
+For each dependency of the target's `package.json` (prod + dev, grouped):
+
+| Column | Meaning |
+|---|---|
+| Current | the base version in `package.json` (`^1.2.3` → `1.2.3`) |
+| Installed | the physical `node_modules` copy (nearest, climbing — npm hoists in brand monorepos) |
+| Wanted | highest published version satisfying the range (npm-outdated semantics) |
+| Latest | the registry `dist-tags.latest` |
+| Bump | `patch` / `minor` / `major` — Current → Latest classification |
+| Released | Latest's publish date + age in days |
+| Status | `QUARANTINED` when Latest is younger than `--min-age` days (default **7**) and not already installed |
+
+Only rows needing attention print; a fully-current tree reports one line. Rows sort prod-first.
+
+**Quarantine (supply-chain caution, npu's `--min-age` semantics):** a release published < 7 days ago may be a compromised publish — it is flagged and **excluded from `--apply`**. `--min-age N` changes the window; `--min-age 0` or `--force-fresh` disables it. Unpublished packages (the pre-publish `@omega.js/*` set) report `not on the registry (unpublished?)` instead of a version row.
+
+**`file:`/`link:`/git specs are SKIPPED** with a dim note — they have no registry story. In the local era every brand's `@omega.js/*` dep is a `file:` spec, so the verb never touches the linked frameworks.
+
+## Applying (`--apply`)
+
+- Default tier is **non-breaking**: each dep rides to its highest same-major version (npu's minor tier) — quarantined targets are held and listed.
+- **Majors are never auto-applied**: breaking jumps are listed as held; `--apply --major` opts in explicitly.
+- Installs run through **`npu install`** when npu is on the machine (Socket supply-chain firewall); otherwise plain `npm install` with a loud warning. Dev deps install with `--save-dev` in their own pass.
+
+## The @omega.js family is pinned, and `omega update` is its ONE mover ([#794](https://github.com/Omega-JS-Stack/omega/issues/794))
+
+Every `@omega.js/*` spec the manager writes into a brand is an EXACT pin, never a
+caret: `"@omega.js/manager": "0.1.0"` at the brand root, `"@omega.js/<framework>":
+"0.1.0"` in each target, all at the manager's own version (the family ships
+lockstep — [publishing.md](publishing.md)). A caret would let one target float
+ahead alone on somebody's `npm update`, which is how a brand ends up serving two
+copies of `@omega.js/client` and validating one omega.json5 with two validators.
+
+Pinned, the only thing that moves a brand is `omega update --apply` at the brand
+ROOT (a bare run reports and installs nothing), and it moves every target — and
+the root's own manager pin — together. `--apply` installs an `@omega.js/*` dep with
+`--save-exact`, in its own command per dep group, so the mover never un-pins
+what it just moved (npm's default save-prefix would write `^<version>` back);
+every other dependency keeps npm's default prefix, because the pin is the
+FAMILY's rule and not a rule for the whole tree.
+
+The manager's boot check enforces the other half: a brand whose installed
+versions have drifted is refused before any service or dev leg runs
+([../manager/brand.md](../manager/brand.md)). The local era is untouched — a
+`file:` spec has no registry story, so the verb skips it and the boot check
+exempts it. `omega i live` (the publish-day flip back off `file:` specs) writes
+the same exact pin ([local-dev.md](local-dev.md) § API surface).
+
+## Brand root
+
+`omega update` at a brand root (manager) fans out over the brand's targets — cp251's deploy fan-out shape: same target discovery, same `--target=<target|dir>` picker ([#780](https://github.com/Omega-JS-Stack/omega/issues/780)), every other flag forwarded verbatim, each target answering through its own framework's `update` verb. Unlike deploy, targets are **independent**: one failing target never blocks the rest (any failure still exits 1). The brand-root shell `package.json` rides the walk as its LAST leg ([#794](https://github.com/Omega-JS-Stack/omega/issues/794)), scoped to the one `@omega.js/*` dependency it carries — `@omega.js/manager` — and run in-process through the same devkit implementation (there is no framework bin at the root to spawn; it would dispatch straight back into this command). A brand's own root tooling is never touched, and a picked run (`--target=`) skips the root, because the picker names targets. Without that leg a manager-behind brand could never heal itself: the boot check would refuse every verb, and the fix it names would move every target except the one that was wrong.
+
+## Testing
+
+Registry lookups, the clock, npu detection, and exec are all injectable — the devkit suite (`packages/devkit/test/update.test.js`) runs entirely offline against fixture packuments with a frozen clock; the manager fan-out test spawns fake framework bins; framework structure tests pin the wiring. The live path is the thin defaults (native `fetch` of the full packument — the abbreviated form carries no publish times).

package/docs/templating.md

@@ -0,0 +1,66 @@
+# Templating
+
+HTML views go through a two-step `{{ }}` token replacement during the `gulp/html` task. Same convention as EM and UJM.
+
+## How it works
+
+1. Your view file (`src/views/<component>/index.html`) is templated first — `{{ brand.name }}` etc. resolve against the page-vars object.
+2. The result is injected into [src/config/page-template.html](../src/config/page-template.html) (the framework's outer HTML shell).
+3. The outer template is processed again with the same vars.
+4. Output written to `dist/views/<component>/index.html`.
+
+## Available variables
+
+| Token | Source | Example |
+|---|---|---|
+| `{{ brand.name }}` | `config/omega.json5` → `brand.name` | `Tabblar` |
+| `{{ brand.url }}` | `config/omega.json5` → `brand.url` | `https://tabblar.com` |
+| `{{ brand.id }}` | `config/omega.json5` → `brand.id` | `tabblar` |
+| `{{ page.name }}` | Component name (e.g. `popup`, `pages/dashboard`) | `popup` |
+| `{{ page.path }}` | Full view path | `views/popup/index.html` |
+| `{{ page.title }}` | Page title — defaults to brand name | `Tabblar` |
+| `{{ theme.appearance }}` | Theme appearance: `dark` or `light` | `dark` |
+| `{{ cacheBust }}` | Cache-busting timestamp (build time) | `1715568000` |
+| `{{ version }}` | `package.json#version` | `1.1.10` |
+| `{{ environment }}` | `'production'` or `'development'` | `production` |
+
+## Example usage
+
+```html
+<!-- src/views/popup/index.html -->
+<!doctype html>
+<html>
+<head><title>{{ page.title }}</title></head>
+<body>
+  <h1>Welcome to {{ brand.name }}</h1>
+  <a href="{{ brand.url }}/pricing?ref=ext">Upgrade to Premium</a>
+  <p>Version {{ version }}</p>
+</body>
+</html>
+```
+
+## Page template
+
+[src/config/page-template.html](../src/config/page-template.html) is the outer shell that wraps every view. It contains:
+- `<!doctype html>` + `<html>` boilerplate
+- `<meta>` tags (viewport, charset)
+- A `{{ content }}` slot where the per-component HTML is injected
+- `<link rel="stylesheet">` for the component's `.bundle.css`
+- `<script>` for the component's `.bundle.js`
+- Cache-busting query params via `{{ cacheBust }}`
+
+Consumers don't author this — @omega.js/extension owns it. If you need to customize per-view, override directly in `src/views/<component>/index.html` (@omega.js/extension detects when a view provides its own full `<html>` and skips wrapping).
+
+## Customizing page vars
+
+The page-vars object is built by [src/gulp/tasks/html.js](../src/gulp/tasks/html.js). To add a new variable for consumer templates, edit the `buildPageVars()` helper there. Vars added are available in BOTH the view file AND the outer page-template.html.
+
+## Why two passes?
+
+Pass 1 lets a view interpolate something into the outer template. For example, a view can do `<!-- omega:page-title --> Custom Title <!-- /omega:page-title -->` (a future feature) and have the value flow into `{{ page.title }}` for the outer template's `<title>`. The pattern keeps simple cases simple (`{{ brand.name }}` Just Works) while leaving room for view → shell metadata flow.
+
+## See also
+
+- [build-system.md](build-system.md) — gulp pipeline including the html task
+- [css.md](css.md) — how the page template references compiled CSS bundles
+- [themes.md](themes.md) — `{{ theme.appearance }}` derivation

package/docs/test-boot-layer.md

@@ -0,0 +1,143 @@
+# Test Framework — Boot Layer
+
+The `boot` layer spawns headless Chromium with the **consumer's actual built extension** loaded as unpacked, then runs `inspect` callbacks against the live runtime. Replaces shell-level "did the extension load?" smoke tests with deterministic, signal-driven pass/fail.
+
+## What boot tests verify
+
+Things that ONLY break when the whole pipeline assembles correctly:
+- The packaged manifest is valid strict JSON (no JSON5 leakage)
+- All referenced files (background.service_worker, content scripts, popup HTML) exist on disk
+- The service worker boots without errors
+- `chrome.runtime.id` is assigned (extension successfully registered)
+- The popup page loads via `chrome-extension://<id>/<popup_path>`
+- Messages between popup and background round-trip
+
+If a boot test passes, the extension at minimum *loads* in a real Chrome — that alone catches a class of bugs unit tests can't (missing assets, manifest schema drift, file path typos).
+
+## Test file shape
+
+```js
+module.exports = {
+  layer: 'boot',
+  description: 'extension loads + popup renders',
+  timeout: 20000,
+  inspect: async ({ extension, page, expect, projectRoot }) => {
+    expect(extension.manifest.manifest_version).toBe(3);
+    await page.goto(extension.popupUrl, { waitUntil: 'domcontentloaded' });
+    const html = await page.content();
+    expect(html).toContain('<html');
+  },
+};
+```
+
+Or as a group:
+
+```js
+module.exports = {
+  type: 'group',
+  layer: 'boot',
+  description: 'extension boots end-to-end',
+  tests: [
+    {
+      description: 'extension has a valid ID',
+      inspect: async ({ extension, expect }) => {
+        expect(extension.id).toMatch(/^[a-z]{32}$/);
+      },
+    },
+    {
+      description: 'service worker came up',
+      inspect: async ({ extension, expect }) => {
+        expect(extension.swTarget).not.toBeNull();
+      },
+    },
+  ],
+};
+```
+
+## The `inspect` callback args
+
+```js
+inspect: async ({ extension, page, expect, projectRoot }) => { /* ... */ }
+```
+
+| Arg | Type | Description |
+|---|---|---|
+| `extension.id` | string | The extension's chrome-extension://`<id>` ID — random per launch, 32-char a-z |
+| `extension.manifest` | object | Parsed manifest.json |
+| `extension.popupUrl` | string\|null | `chrome-extension://<id>/<manifest.action.default_popup>` or null |
+| `extension.optionsUrl` | string\|null | `chrome-extension://<id>/<manifest.options_ui.page>` or null |
+| `extension.swTarget` | Puppeteer Target | The service worker target (may be null if extension has no SW) |
+| `page` | Puppeteer Page | A fresh tab — use `page.goto`, `page.evaluate`, `page.$eval`, etc. |
+| `expect` | function | Jest-compatible matcher (same surface as other layers) |
+| `projectRoot` | string | Absolute path to the consumer project |
+
+Each boot test gets a **fresh** `page` (closed at the end of the test). The browser + extension load are shared across all boot tests in a single `npx omega test` invocation (one Chromium boot per run, amortized across tests).
+
+## Extension-directory discovery
+
+The runner looks for the consumer's Chrome-loadable build in this order:
+
+1. `OMEGA_TEST_BOOT_DIR` env var (absolute path) — full override
+2. `<consumer>/packaged/chromium/raw/` — default. This is what @omega.js/extension's gulp pipeline produces. Strict JSON manifest, all bundles compiled, locale files in place. Same dir a developer points "Load unpacked" at.
+3. `<consumer>/dist/` — for non-standard pipelines (and the framework's own fixture extension, which is authored as strict JSON)
+
+**A directory qualifies only when its `manifest.json` is STRICT JSON** — what Chrome can actually parse. Existence alone used to qualify, and the intermediate `<consumer>/dist/` (JSON5, the framework-authored source style) exists after any dev run or `omega clean`, so an unbuilt project loaded that copy and hard-failed every boot test instead of skipping ([#575](https://github.com/Omega-JS-Stack/omega/issues/575)). A JSON5 `dist/` is passed over and named in the skip.
+
+An explicitly named `OMEGA_TEST_BOOT_DIR` is a decision, not a fallback, so a manifest Chrome can't parse THERE is still an actionable failure:
+
+```
+✗ boot tests aborted: dist/manifest.json is not strict JSON.
+  Chrome requires manifest.json to have no comments, no trailing commas, no single quotes.
+  Parser error: Expected property name or '}' in JSON at position 4
+  OMEGA_TEST_BOOT_DIR names this directory explicitly — point it at a
+  packaged/<browser>/raw/ output, or unset it and run `npm run build`.
+```
+
+Most consumers don't need to think about this — `npm run build && npx omega test` works.
+
+## OMEGA_TEST_BOOT_PROJECT vs OMEGA_TEST_BOOT_DIR
+
+| Env | Purpose |
+|---|---|
+| `OMEGA_TEST_BOOT_PROJECT` | Root of a different project to use instead of cwd. Auto-set when @omega.js/extension tests itself (points at the in-tree fixture under `src/test/fixtures/consumer-extension`). |
+| `OMEGA_TEST_BOOT_DIR` | Absolute path of the directory holding `manifest.json` — short-circuits the discovery order entirely. Use for monorepo layouts or custom output dirs. |
+
+## What happens when the extension can't load
+
+Chromium silently rejects extensions with malformed manifests (no chrome-extension:// target ever appears, no error in console). The runner detects this and surfaces likely causes:
+
+```
+✗ Boot aborted — Chromium loaded but no chrome-extension target appeared.
+  Likely cause: the extension failed to load. Common reasons:
+    - manifest.json missing required field (e.g. manifest_version: 3)
+    - default_locale is set but _locales/<locale>/messages.json is missing
+    - __MSG_*__ placeholders used without default_locale + _locales/
+    - referenced files (background.service_worker, content_scripts) don't exist on disk
+```
+
+This catches real ship-breakers (broken locale references, missing bundles) before users see them.
+
+## Skipping the build before boot tests
+
+Boot tests assume `packaged/chromium/raw/` exists. They don't auto-trigger `npm run build` (that would slow the test loop). If no candidate carries a strict-JSON manifest, you get:
+
+```
+○ boot tests skipped (no strict-JSON manifest.json found in any of:
+    /path/to/project/packaged/chromium/raw
+    /path/to/project/dist
+  /path/to/project/dist/manifest.json exists but is not strict JSON (the intermediate JSON5 source Chrome refuses)
+  — run `npm run build` first to produce packaged/chromium/raw/)
+```
+
+In CI, run build then test in separate steps so failures are isolated.
+
+## Why this exists
+
+Build-layer tests can verify "the manifest source is well-formed." Background-layer tests can verify "@omega.js/extension's framework code works inside a SW." But neither catches "the consumer's actual pipeline assembles into a Chrome-loadable extension." Boot tests do.
+
+In @omega.js/extension's own self-tests, the boot layer points at a hand-authored fixture extension (`src/test/fixtures/consumer-extension/`) — a known-good minimal MV3 extension. That validates the framework's boot runner is working; consumer projects then point it at their own packaged output to validate THEIR pipeline.
+
+## See also
+
+- [test-framework.md](test-framework.md) — overall harness, layers, ctx, expect API
+- [environment-detection.md](environment-detection.md) — `Manager.isTesting()` and friends