@omega.js/web 0.1.0

package/dist/vendor/template-kit/variable-resolver.js

@@ -0,0 +1,163 @@
+/**
+ * variable-resolver.js — argument parsing + variable resolution for omega_* tags.
+ *
+ * Ported from jekyll-uj-powertools lib/helpers/variable_resolver.rb (READ-ONLY
+ * reference repo). Engine-neutral: variable lookup goes through a `lookup(path)`
+ * function the engine adapter provides (register-liquid.js builds one from the
+ * LiquidJS render context).
+ */
+
+/**
+ * Resolve a variable or string literal.
+ * @param {function} lookup - (dotPath) => value from the render context
+ * @param {string} input - raw tag argument
+ * @param {boolean} [preferLiteral=false] - unquoted words stay literal text
+ *   unless they are typed literals, contain dots, or exist in context
+ * @returns {*}
+ */
+function resolveInput(lookup, input, preferLiteral = false) {
+  if (input === null || input === undefined || input === '') return null;
+
+  const quoted = input.match(/^["'](.*)["']$/);
+  if (quoted) return quoted[1];
+
+  if (preferLiteral) {
+    // A typed literal is typed in this lane too — max_width=640 is the number
+    // 640 and webp=false the boolean, matching the plain lane below. Quoting
+    // is the author's opt-out.
+    const typed = parseLiteral(input);
+    if (typed) return typed.value;
+    if (input.includes('.') || isTruthyLookup(lookup(input))) {
+      return resolveVariable(lookup, input);
+    }
+    return input;
+  }
+
+  return resolveVariable(lookup, input);
+}
+
+/**
+ * Read a bare typed literal (number, boolean, nil).
+ * @param {string} input
+ * @returns {{value: *}|null} null when the input is not a typed literal
+ */
+function parseLiteral(input) {
+  const trimmed = String(input).trim();
+
+  if (trimmed === 'nil' || trimmed === 'null') return { value: null };
+  if (trimmed === 'true') return { value: true };
+  if (trimmed === 'false') return { value: false };
+  if (/^-?\d+(\.\d+)?$/.test(trimmed)) return { value: Number(trimmed) };
+
+  return null;
+}
+
+// Ruby's `context[input]` guard is plain truthiness
+function isTruthyLookup(value) {
+  return value !== null && value !== undefined && value !== false;
+}
+
+/**
+ * Resolve a dot-path variable through the context.
+ * @param {function} lookup - (dotPath) => value
+ * @param {string} variableName
+ * @returns {*} null when unresolvable (Ruby parity: nil)
+ */
+function resolveVariable(lookup, variableName) {
+  if (!variableName) return null;
+
+  // Bare literals evaluate to their values before any scope lookup — a
+  // template writes max_width=640 / webp=false meaning the literal, not an
+  // (always-missing) scope path.
+  const literal = parseLiteral(variableName);
+  if (literal) return literal.value;
+
+  const value = lookup(variableName);
+  return value === undefined ? null : value;
+}
+
+/**
+ * Parse comma-separated tag arguments, preserving quotes.
+ * @param {string} markup
+ * @returns {string[]}
+ */
+function parseArguments(markup) {
+  const args = [];
+  let current = '';
+  let inQuotes = false;
+  let quoteChar = null;
+
+  for (const char of markup || '') {
+    if (!inQuotes && (char === '"' || char === "'")) {
+      inQuotes = true;
+      quoteChar = char;
+      current += char;
+    } else if (inQuotes && char === quoteChar) {
+      inQuotes = false;
+      quoteChar = null;
+      current += char;
+    } else if (!inQuotes && char === ',') {
+      args.push(current.trim());
+      current = '';
+    } else {
+      current += char;
+    }
+  }
+
+  if (current.trim().length > 0) args.push(current.trim());
+  return args;
+}
+
+/**
+ * Parse key=value options from parsed arguments.
+ * @param {string[]} args
+ * @param {function} [lookup] - when provided, unquoted values resolve as variables
+ * @returns {object}
+ */
+function parseOptions(args, lookup) {
+  const options = {};
+
+  for (const arg of args || []) {
+    if (!arg.includes('=')) continue;
+
+    const index = arg.indexOf('=');
+    const key = stripQuotes(arg.slice(0, index).trim());
+    let value = arg.slice(index + 1).trim();
+
+    if (lookup) {
+      // The ONE option parser (the image-tag lane in collections.js imports
+      // it too), on the preferLiteral rule: typed literals resolve typed
+      // (max_width=640 is the number), bare words keep their literal text
+      // unless they exist in context (class=hero works), dotted paths
+      // resolve — and a missing path yields null so a typo'd variable never
+      // renders its own name into the page.
+      value = resolveInput(lookup, value, true);
+    } else {
+      value = stripQuotes(value);
+    }
+
+    options[key] = value;
+  }
+
+  return options;
+}
+
+/**
+ * Check whether a raw argument was quoted.
+ * @param {string} input
+ * @returns {boolean}
+ */
+function isQuoted(input) {
+  return !!(input && /^["']/.test(input));
+}
+
+/**
+ * Strip surrounding quotes from a raw argument.
+ * @param {string} input
+ * @returns {string}
+ */
+function stripQuotes(input) {
+  return String(input).replace(/^['"]|['"]$/g, '');
+}
+
+module.exports = { resolveInput, resolveVariable, parseArguments, parseOptions, isQuoted, stripQuotes };

package/docs/ads-system.md

@@ -0,0 +1,109 @@
+---
+status: ratified
+created: 2026-07-20
+---
+# OMEGA Ads System — spec (RATIFIED with amendments, Ian 2026-07-20)
+
+> Queue item (b), Ian 2026-07-20: ads are "super important" — provider ads first (AdSense), in-house/fallback ads hostable on the parent company OR the brand itself. Grounded in the legacy survey (vert.js, promo-server-website/backend, UJM adunits, `ultimate-jekyll-manager/plans/unified-vert-ad-units.md`).
+>
+> **Ian's amendments (2026-07-20)**: (1) Detection is a FULL REWRITE — don't preserve the legacy poll mechanics, just the behavior: adblock detected OR no-fill for any reason → in-house fallback. (2) Serving is RUNTIME (function/Firestore read), not build-time — cost handled by an in-memory inventory cache in the function (TTL ~5 min → one Firestore read per instance per interval, not per impression). (3) `weight` required; RELEVANCE required: contextual targeting v1 (per-ad tags × the requesting brand/page's tags, match-score × weight) — no user tracking; viewer-level targeting is a later layer on the same scoring. (4) Company model confirmed: ITW Creative Works is the company; legacy brands (soundgrail, sweet-saucy, …) eventually migrate and look to the COMPANY for ads etc. promo-server.itwcreativeworks.com stays online untouched until that migration; its inventory imports into the company module then.
+
+## What the legacy system got right (preserved)
+
+- The **fallback ladder**: provider fills → shown; unfilled / timeout / script-load-failure → in-house unit → nothing. No adblock library, graceful always.
+- **Origin-validated postMessage** with a tiny fixed vocabulary (set-dimensions, click) + sandboxed iframe.
+- **Fail-closed redirect validation** (origin+pathname allowlist) and UTM-tagged click-throughs.
+- **Lazy rendering** — units cost nothing until near-viewport.
+- **One SSOT for the publisher ID** feeding both the ad tag and `ads.txt`.
+- Per-ad **whitelist/blacklist + enabled** flags; client-side shuffle rotation.
+
+## What it kills by design
+
+1. **The vert.js parked-build problem**: the legacy client was a standalone IIFE that can't `import @omega.js/client` without duplicating the singleton. The new client is an **`ads/unit` SECTION** — its `section.js` rides the §7 main-bundle lane (DOM-presence init), sharing the one client instance like every other section. `core/js/modules/vert.js` and the `adunits/*` includes die.
+2. **The self-refresh "chrome-error" bug**: rotation lived INSIDE the cross-origin iframe (a sleep/offline refresh strands `chrome-error://` with no JS left to recover). New rule: **the HOST owns all lifecycle** — rotation timer, staleness recovery (`visibilitychange`/`online` → reload iframe if stale), fill monitoring. The iframe only renders and reports.
+3. **Raw hardcoded consumer iframes** (the Tabblar antipattern): every surface gets the same first-class unit — web via the section, desktop/extension via the shared client's ads module bound to a `data-omega-ad` element (mirrored-implementation rule).
+4. Cargo-cult remnants: the dead `popupads.js` "detector" stub, duplicated AdSense in-feed layout keys (one JS-side table), allow-all Firebase rules.
+
+## Config (omega.json5 — provider-discriminated, D12 shape)
+
+```json5
+advertising: {
+  providers: {
+    adsense: {
+      client: 'ca-pub-XXXX',            // the ONE adsense switch: ad tag + ads.txt + the managed account (SSOT)
+      displaySlot: '…', inArticleSlot: '…', inFeedSlot: '…', multiplexSlot: '…',
+    },
+    inhouse: {
+      source: 'company',                 // 'self' (this brand's backend) | 'company' (parent's api) | full URL
+    },
+  },
+  fallback: 'inhouse',                   // provider role to fall through to; false = none
+  tags: ['music', 'audio-tools'],        // this brand's contextual tags (targeting match input)
+}
+```
+
+- Shared-section key, overridable per target. Key presence enables; no keys = no ads anywhere.
+- **One switch, one polarity** ([#527](https://github.com/Omega-JS-Stack/omega/issues/527)): `client` presence decides EVERYTHING adsense — the manager service reconciles the account it names, the ad units render off it, and `ads.txt` carries the record. No key set it out. There is no `units` gate and no provider `enabled` gate: a second switch is how one config told the manager "stop managing" while the site kept serving ads off the same id. The managed-but-ad-free brand is deliberately inexpressible — such a brand omits the block, and the account is managed by hand. This is case 1 of the gating doctrine in [docs/shared/config.md](shared/config.md#feature-gating-polarity-527).
+- The house/promo lanes are independent of adsense: a brand with no `client` still fills its slots from in-house inventory if it configures any, and the promo lane still terminates the ladder.
+- `source: 'company'` resolves through the config company layer to the parent's api URL — sub-brands inherit the parent inventory with one word. `'self'` serves the brand's own inventory. **No hard company requirement** (Ian): a brand alone is fully functional. In DEV mode every source resolves the local stack, `company.url` included — dev makes no live server hits (ratified, [#34](https://github.com/Omega-JS-Stack/omega/issues/34); the mechanism note lives in [docs/shared/config.md](shared/config.md)).
+- Legacy `advertising.<provider>` flat shape already converts via the existing migrate lane (`advertising.providers.*`).
+
+## House inventory — a backend module (modern replacement for the Jekyll-file verts)
+
+- **Firestore collection `ads`**: `{ enabled, title, description, button, link, image, footer, weight, targeting: { sites: [], categories: [], keywords: [] }, whitelist: [], blacklist: [], metadata }` — the legacy frontmatter shape, DB-backed + targeting. Public-read via routes only (no direct Firestore reads from foreign origins).
+- **Selection scoring**: eligibility (enabled + white/blacklist + never-advertise-self) → contextual match score (ad `targeting` tags vs the request's `tags` — brand-configured + page context) → weighted random among the top scorers (`weight`, default 1). No tags anywhere = pure weighted shuffle (legacy behavior).
+- **Inventory cache**: the serve route holds the ads collection in function memory (TTL ~5 min) — runtime serving at ~zero Firestore read cost per impression (Ian's ruling: runtime read is correct; this makes it cheap).
+- **Routes** (built-in, `/omega/ads/*`):
+  - `GET /omega/ads/serve?parent=<host>&…` — selection (filter enabled + white/blacklist + never-advertise-self, weighted shuffle) → the rendered unit page (self-contained HTML: card layout, dimension reporting, click postMessage). Serves from the backend's hosting surface, so 'self' needs only the backend target.
+- **One unit document, one renderer**: every vert unit document comes from `@omega.js/client`'s `modules/vert-document.js` — the serve route maps a stored vert onto it (the backend holds no template of its own; the CJS route pulls the ESM module in by dynamic import), and the client's terminal promo lane calls the same function with the house promo data. The look is one media row: thumbnail left, title with a clamped muted description, a hairline, then a muted label ('Sponsored', or the vert's own footer) on the left and the accent CTA button on the right. The card is content-sized — its natural height IS the card height, and the slot preset stays a ceiling the host clamps to, never a floor the card stretches into. A short or narrow slot tightens the row (smaller thumbnail, no description) on a spacing budget that keeps the compact card under the leaderboard ceiling — the shortest preset, the one a taller card would be cropped by; a skyscraper-shaped slot stacks. Colours are literal pairs per theme inside the document; the accent pair is an option, defaulting to neutral ink for served verts and passing the omega indigo for the promo. Every field from vert data is escaped; the single trusted-markup slot (the thumbnail) takes framework constants only. The document declares `color-scheme` (both modes when it follows the OS, the pinned one when a theme is passed) so the canvas the browser falls back to whenever it rasterizes the frame without the root's transparency — first paint, a re-raster on scroll or zoom — matches the card instead of defaulting to light-mode white, which is what showed as white corner notches around the card's radius and a sliver under its bottom edge. The card owns ALL the chrome (background, border, radius) and the host is invisible — the `.omega-vert-unit` element and any theme sheet carry no surface, no radius and no clipping, so the visible box IS the card. Sizing follows from the same rule: the document reports its CARD box (never `documentElement`, which can never measure shorter than the frame it fills), and the host shrinks the frame to it.
+  - `GET /omega/ads/redirect?id&url` — fail-closed allowlist validation (known ad links only) → UTM'd redirect. View/click events tracked server-side (Analytics lane) — no gtag dependency inside the frame.
+  - Admin CRUD rides the standard admin routes + an **admin dashboard card** (list/create/edit/toggle, image via the assets lane).
+- **Company mode**: the SAME module on the parent company's backend IS the ad network (promo-server successor). Sub-brands point `source: 'company'` at it. A parent can scope inventory per sub-brand via the white/blacklists.
+
+## Client unit — the `ads/unit` section (+ mirrored surfaces)
+
+- `{% section "ads/unit" %}` with args: `type` (`display`/`in-article`/`in-feed`/`multiplex`/`house`), `size` preset (banner/leaderboard/rectangle/…), optional `ad_id` pin. Neutral json5 defaults; markup is context-free per §sections doctrine.
+- `section.js` (§7 presence-init, shared client singleton):
+  1. Lazy: IntersectionObserver arms the unit near viewport.
+  2. Provider lane (FULL REWRITE — Ian: don't trust the legacy mechanics): adblock detection first (script-load failure of `adsbygoogle.js` IS the detector — no bait divs, no separate library); blocked → straight to fallback. Otherwise build the `<ins>` and await fill via a `data-ad-status` attribute observer (MutationObserver + timeout, not a 100ms poll) — `filled` → done; `unfilled`/timeout → fallback lane (if configured).
+  3. Fallback lane: sandboxed iframe → resolved inhouse source's `/omega/ads/serve`; origin-validated postMessage (set-dimensions/click); HOST-side rotation + staleness recovery.
+  4. Paying users: unit hides on `auth.resolved.active` via the standard bindings (legacy behavior kept).
+- Desktop/extension: no AdSense (policy/no-web-context) — the shared client ships the same fallback-lane logic as an `omega.ads()` module binding `data-omega-ad` elements straight to the house/company inventory. Web section uses the same module under the hood (one implementation, three surfaces).
+- `ads.txt`: web build emits it from `providers.adsense.client` when present (closes the parity-gap item) — the same presence that renders the units, because the file is the declaration that this domain sells inventory through that account.
+
+### Automatic placements (#44 items 24/25, 2026-07-31)
+
+- The AUTOMATIC placements — blog post in-article unit, blog index in-feed unit, mid-article insertion (`[slug].js`, every 4th paragraph), and the dashboard rail slot — are build-time gated on `site.advertising`: no advertising config, zero vert markup. Hand-authored `{% section "verts/unit" %}` calls stay ungated — an author who writes the tag asked for it.
+- A post opts out with `verts: false` frontmatter: suppresses the layout unit and stamps `data-omega-verts="false"` on the article, which the mid-article inserter honors.
+- The dashboard rail slot keys on the sidebar data's `bottom.vert.enabled` AND `site.advertising`; the admin sidebar carries no bottom block, so staff surfaces stay vert-free.
+- Visual QA: `/test/libraries/verts` shows every format and size preset with the literal producing tag and a config-state banner.
+- **A unit follows the PAGE's theme, not the OS**: mount reads `data-bs-theme` off the root element and passes it into both lanes — the house serve URL's `theme` param and the promo document's `data-theme` stamp — so a site toggled dark on a light machine renders dark cards. A host's own `data-omega-vert-theme` pins the frame and wins; nothing stamped anywhere leaves the frame on its own `prefers-color-scheme` branch. A flip AFTER render re-stamps every live promo frame from one `MutationObserver` on that attribute (a `srcdoc` assignment, zero network); a house frame keeps the theme it mounted with, because re-theming it would mean re-fetching it.
+
+- **The ladder ends in the promo, never in nothing** (Ian's QA ruling 2026-07-31): when every configured lane fails (provider no-fill/blocked AND the fallback source unresolvable or unreachable), the unit renders the built-in omegajs.dev promo at the slot's reserved size. The promo is a REAL unit, not a stub: the same sandboxed iframe (`title="Sponsored"`, the house sandbox set minus `allow-same-origin`, which a srcdoc frame cannot safely carry), the same `omega-vert:set-dimensions` / `omega-vert:click` postMessage vocabulary, the same host-owned sizing and max-height clamp, and the same `target="_blank" rel="noopener noreferrer sponsored"` link contract the backend-served unit uses. Its document comes from the SAME renderer a served vert's does (`@omega.js/client`'s `modules/vert-document.js`) — only the trusted inline-svg thumbnail and the indigo accent are promo-specific. The difference is delivery: the document arrives inline by `srcdoc`, so the lane makes ZERO network requests and carries literal colours per theme (css variables do not cross the frame boundary, so it holds in light, dark, and on an unthemed page). Because a sandboxed srcdoc frame posts with origin `null`, the host validates the promo frame by `contentWindow` identity; the house lane's origin check is untouched. `omega-vert:no-fill` still fires first (nothing was sold), then `omega-vert:promo`. A unit never renders empty.
+
+### Click tracking and UTM (#44, Ian's QA 2026-07-31)
+
+- **Every click destination is UTM-tagged automatically**, both lanes, through one tagger: `applyVertUtm` in `@omega.js/client`'s `modules/vert-document.js`. The promo lane tags its own `https://omegajs.dev` link in the browser (`utm_medium=omega-vert`, `utm_campaign=omega-promo`, `utm_content=<the slot's size preset>`); a served vert is tagged by the backend redirect route on the STORED link (`utm_medium=omega-vert`, `utm_campaign=<vert id>`), which is where the final destination is known.
+- **`utm_source` is the HOST brand's `brand.id`** (Ian's ruling 2026-07-31), with the parent host as the fallback when no id is available. The promo lane reads the id straight off the client's own config; the house lane sends it to the backend as the serve URL's `brand` param, the serve route stamps it on the redirect URL it builds, and the redirect route tags the stored link with it. Targeting is untouched: `?parent=<host>` still flows exactly as before (eligibility, postMessage origin, and the utm fallback), and only the tag's value changed. The backend accepts a `brand` value only when it matches `brand.id`'s own slug pattern, so nothing caller-supplied can write free text onto an advertiser's URL.
+- **Existing params win.** The tagger only fills keys the URL does not already carry, so an advertiser's own tagging survives verbatim and nothing double-appends. Non-http(s) or unparseable values come back untouched.
+- **Analytics fires HOST-side, on the click message.** Analytics cannot run inside a cross-origin frame, which is why the legacy stack bounced every click through a top-level forward page (`/verts/redirect`) that fired a `vert_redirect` gtag event, waited on the event callback, and only then navigated. The new unit already forwards clicks OUT of the frame, so the host handles it: on `omega-vert:click` the host fires `vert_click` through this brand's own `@omega.js/client` analytics with `vert_id`, `vert_lane` (`house`/`promo`), `vert_campaign`, `vert_slot`, and `vert_source`. **There is no forward page and there never will be one** — no interstitial, no navigation delay, and the server-side `verts/redirect` analytics event still records the same click from the other end.
+
+## Sequencing (proposed)
+
+1. Backend module (collection + serve/redirect routes + tests) — provable offline via emulator.
+2. Client ads module in `@omega.js/client` + the web `ads/unit` section (§7 lanes, goldens, showcase entry).
+3. Admin CRUD card.
+4. Desktop/extension `data-omega-ad` binding.
+5. Retire `core/js/modules/vert.js`, `adunits/*` includes, the assets.js skip-guard note; blog `[slug].js` flips to the section. (DONE)
+6. Company-mode proof on the playground (OMEGA Playground serves, a second in-repo brand consumes). (DONE — root `npm run test:verts` / scripts/e2e-verts-company.js; The Daily Build carries the standing `source: 'company'` + `company.url` config)
+- AdSense LIVE verification stays gated behind the real publish (Ian 2026-07-14: AdSense console needs the published site).
+
+## Resolved questions (Ian 2026-07-20)
+
+1. Serve surface: backend routes (`/omega/ads/serve`), runtime reads — ratified (with the in-memory cache).
+2. Weight: required, default 1, composed with contextual match scoring.
+3. Legacy promo-server: site stays online untouched until the ITW brands migrate to OMEGA; inventory imports into the ITW company module at that migration.
+
+## Naming: vert (cp258, Ian's ruling 2026-07-21)
+
+Adblock-safe naming — the ad system speaks **vert** EVERYWHERE at runtime (paths `/omega/verts/*`, DOM `data-omega-vert*`/`.omega-vert-unit`, Firestore collection `verts`, postMessage `omega-vert:*`, client `omega.verts()`/`Verts`/`VertUnit`, section `verts/unit`, admin `/admin/verts`). Only ads.txt, Google's own ad* tokens (adsbygoogle, `data-ad-*`), and the `advertising` config key say "ad". This plan file keeps its historical name.

package/docs/classy-v2/DIRECTION.md

@@ -0,0 +1,92 @@
+---
+status: ratified
+created: 2026-07-16
+---
+# classy v2 — Direction (LOCKED, build contract)
+
+**Status:** GO from Ian 2026-07-16 ("just go ahead and build classy"). Direction converged over two interactive comp rounds against Ian's theme notes (2026-07-15) + 14 Mobbin inspo screens + ElevenLabs/Manus references (his second-round attachments).
+
+**The visual spec is the comps** (self-contained HTML, open in any browser — the bottom dock switches view/theme/brand/type/density):
+
+- [draft-1.html](draft-1.html) — first round (violet/cyan gradients — REJECTED palette, kept for the record) · artifact: https://claude.ai/code/artifact/e26826cf-b6c2-4afb-9db7-d5bae486818a
+- [draft-2.html](draft-2.html) — **the approved direction** · artifact: https://claude.ai/code/artifact/f58ba1ef-4841-45f3-b046-77d7d75ef060
+
+Where this file and a comp disagree, this file wins (it encodes Ian's latest word). Comps are throwaway single-file mockups — the real theme ships proper SCSS partials + JS modules per repo conventions.
+
+## Identity decisions
+
+- **The name stays `classy`** — full gut renovation in place ("remake classy FROM SCRATCH"); D10's new-name lean is overridden. No meridian anything.
+- **Bootstrap 5 stays the base** — classy's existing `_config.scss → @forward '../bootstrap/scss/bootstrap.scss' with (…)` pattern is preserved architecture ("build upon Bootstrap's core, don't reinvent the wheel").
+- **Built ON the shared OMEGA theming system** (C3 systems slice): paints via the `--omega-*` token contract (`core/css/tokens/_index.scss`), rides `.omega-shell` mechanics (`core/css/shell/_index.scss`), brand accent flows from `brand.color` → `composeBrandTokens` inline ramp. C4 later hands the same token sheet to desktop/extension — this is what keeps every target harmonious.
+
+## Binding constraints (Ian, 2026-07-15 feedback round)
+
+1. **ZERO gradients** — chrome, buttons, borders, logos, text: none. The ONLY permitted fade is a monotone single-hue opacity gradient under chart lines/sparklines.
+2. **Dark mode is generic charcoal** — no blue/purple cast (ElevenLabs reference). Neutral grays only; color enters through the accent slot.
+3. **Search lives in the TOPBAR** (⌘K pill), never the sidebar.
+4. **Sidebar supports nested groups** (parent + chevron + tree-hairline children; open and closed states both first-class).
+5. **Active nav state must not shift geometry** — every item carries a transparent border at rest.
+6. **Consumers customize colors/vibe/typography EASILY in their main.scss** — this is the product; see Consumer contract below.
+
+## Token sheet (values from draft-2; token NAMES are the stable contract)
+
+Light (warm paper):
+`ground #f5f5f4 · surface #ffffff · surface-2 #f6f6f5 · ink #1a1a19 · muted #6d6d6c · faint #a1a19e · line #e8e8e6 · line-strong #d8d8d5`
+
+Dark (neutral charcoal, de-blued):
+`ground #0d0d0e · surface #151516 · surface-2 #1d1d1f · ink #ebebea · muted #9f9fa0 · faint #6c6c6e · line #262628 · line-strong #333336`
+
+Amendment (2026-07-31, [#152](https://github.com/Omega-JS-Stack/omega/issues/152)): light `surface-2` re-valued `#f6f6f5` to `#ececeb` — the draft value was one point off the ground and invisible when painted on it; light elevation recesses, so the second tier goes darker. Reasoning and the twins that move with it: `docs/shared/theming.md` "The three surface tiers".
+
+Accent (single hue, from `brand.color`; light/dark variants; derived hover/subtle/ring via color-mix in the comps — production derives via composeBrandTokens):
+default (playground) `#2563eb` light / `#5484ef` dark (draft-1 "ocean" — Ian retired the draft-2 purple 2026-07-16) · `accent-ink` = white on light, near-black on dark.
+
+Status (semantic, reserved): `ok #12925c/#3ecf8e · warn #c47206/#f5a524 · danger #d92d20/#f0574d` (light/dark).
+
+Charts: series-1 = accent; series-2 (comparison, dashed) = teal `#0f8fa9` light / `#1f9fb4` dark — **passed the dataviz CVD validator in both modes** (dark tritan 7.1 sits in the legal-with-secondary-encoding band; dashing + legend + direct labels satisfy it).
+
+Geometry: radii `6/8/10/14/20` · shell `sidebar 264 / rail 68 / topbar 60` · motion `160ms cubic-bezier(.25,.5,.35,1)` · density preset `compact` tightens `fs 13.5→12.5, control 34→29, card pad 20→14, nav item 34→29, topbar 60→52`.
+
+## Typography
+
+- **Default = the Manus split ("Mix")**: marketing display serif (`New York/ui-serif/Georgia` class), app + UI grotesk (system stack). Consumer presets: `sans` (grotesk everywhere — ElevenLabs mode), `editorial` (serif display everywhere), `terminal` (mono display).
+- **D5 (vendored webfonts) is OPEN** — comps deliberately use system stacks; Ian picks the real faces (Inter-class UI + a serif display) before or during the build; the token layer makes the swap trivial.
+- Manus-calibrated scale: page title 22/650/-0.02em; tile numbers 24/650 tabular; panel heads 14/650; uppercase 11px micro-labels (tables, stat labels, tp-heads).
+
+## Accent usage rules
+
+- **Primary buttons are INK** (black on light, white on dark) — Manus/ElevenLabs pattern.
+- Accent is for: links, active nav icon/state, focus rings, meters/progress, chart series-1, small signal chips, the brand dot. Never large surface fills; never text-gradient anything.
+- Status colors stay reserved for status (pills always dot+label, never color-alone).
+
+## App DNA (dashboard/backend/admin surfaces)
+
+Gray-canvas sidebar (on `ground`) + **content in ONE big rounded card** (`surface`, r-20, hairline) — the GitBook/Laravel-Cloud pattern. Sidebar top→bottom: ink Ω brandmark + wordmark (lockup) → project **selector module** (optional; solid accent tile + name/env) → nav sections with muted uppercase labels, count/`New` chips, **nested groups** → footer: optional **ad slot** (hairline card, SPONSORED tag, dismissable, "Pro removes ads") → user row. Collapse → 68px icon rail (brandmark only, nested groups hidden; drawer+scrim under 1200px). Topbar: drawer/collapse toggles, breadcrumb + env status pill, centered ⌘K search, docs/bell buttons, account selector dropdown (avatar = neutral chip). Content: merged stat card (hairline column dividers, sparklines, delta pills), chart card w/ legend + segmented metric tabs + crosshair tooltip + top-pages meters, usage meters (warn state at threshold), checklist card, activity feed, promo banner (plain hairline card), data table (uppercase heads, project dots = flat per-project colors, target chips, status pills, mono durations, pagination footer).
+
+## Marketing DNA (frontend surfaces)
+
+Ink on paper. Glassy nav (transparent until scroll → blur + hairline; ink CTA). Hero: subtle dotted grid (masked), serif display headline w/ **rotating italic second line** (motion = the life, not color), neutral badge pill w/ status dot, ink primary + mono-command ghost CTAs, **floating product frame** (gentle y-drift + perspective hover, real mini-dashboard inside). Word-logo marquee (masked edges, pause on hover). Hairline bento grid (neutral icon tiles; one 2×2 with omega.json5 codebox on ink panel; brand-dot demo tile; light/dark split tile; deploy terminal row w/ caret). Stats band: paper, hairline block borders, big serif ink numbers, count-up on reveal. Pricing: 3 cards, popular = ink border + inverted chip + ink button. Serif quote w/ italic emphasis. CTA band: neutral ink panel (`#161616`-class), serif white headline, paper button. Scroll-reveals via IntersectionObserver; `prefers-reduced-motion` kills all of it.
+
+## Consumer contract (THE product surface — every OMEGA consumer starts on classy)
+
+- **Tier 1 — customize classy from your target's `main.scss`** (most consumers stay here):
+  - `omega.json5 → brand.color` recolors every accent surface at build time (zero CSS).
+  - Sass knobs: `@use 'omega:theme' with ($primary: …, $font-family-sans-serif: …, $border-radius: …)` — every `_config.scss` var ships `!default`.
+  - Token overrides: redefine any `--omega-*` custom property in `:root` / `[data-bs-theme=dark]` for surgical re-vibing (grays, radii, speed, type presets, density).
+- **Tier 2 — build your own theme**: fork `themes/_template`, same layer chain; classy remains the fall-through reference.
+- **Stable API line (don't churn once consumers exist):** token NAMES, `_config.scss` variable names, shell markup contract, `_includes` section names. Everything behind that line (partial internals, exact values) stays freely iterable.
+
+## Iteration safety (Ian: "I don't want to get locked into a hole")
+
+- Comps in this folder are the frozen visual reference; the theme itself iterates by checkpoint commits — every step revertable, nothing sacred.
+- Until first publish, playground is the ONLY consumer → zero breakage risk while we iterate hard.
+- After publish, iteration discipline = respect the stable-API line above; values/partials/pages remain fair game forever.
+
+## Build order (the arc, per PROGRESS)
+
+1. **DRAFT 1 in-repo (next):** classy gut renovation sufficient for home/pricing/signin + chrome (nav/footer) + app-shell restyle on playground; light+dark; local screenshots; suites green; commit; ONE named playground deploy for Ian's reaction.
+2. Default pages + blueprints skinned.
+3. Auth/account/payment surfaces + dashboard/admin remake (this doc's App DNA).
+4. Showcase pass; FOUC critical-CSS/font QA rides this arc.
+5. C4 cross-target sharing (tokens → desktop/extension).
+6. Arc close: template repo cut OUTSIDE the monorepo; playground source → `Omega-JS-Stack/omega-playground` main + CI (`omega deploy` dispatch replaces direct gh-pages push); omegajs.dev wiring.