@omega.js/web 0.1.0

package/docs/libs.md

@@ -0,0 +1,298 @@
+# Web JS libraries (core/js/libs)
+
+The browser-side modules `@omega.js/web` ships for page code to import:
+`packages/web/core/js/libs/`. They are the framework's own runtime helpers,
+distinct from `@omega.js/client` (the singleton every page boots with) and from
+`core/js/pages/` (a page's own module). Page modules, theme modules, the boot
+runtime, and consumer page modules all reach them the same way.
+
+## The import idiom
+
+```js
+import { createLogger } from '__main_assets__/js/libs/logger.js';
+import { loadCharts, chartSlot, barChart } from '__main_assets__/js/libs/charts.js';
+```
+
+`__main_assets__/` is a build-time specifier resolved by the esbuild plugin in
+`packages/web/src/assets.js`: `__main_assets__/js/...` points at the CORE layer
+root (`packages/web/core/`), `__main_assets__/themes/...` at the packaged themes
+dir. It is layer-independent, so a consumer's own page module in
+`src/assets/js/pages/` writes exactly the specifier core's own pages write
+(`core/js/pages/admin/index.js`, `core/js/layouts/modules/utilities/redirect.js`,
+`themes/classy/_theme.js`, `runtime/boot.js`). There are no exceptions: every
+bundle the pipeline builds — main, page, layout — carries the alias plugin
+([#624](https://github.com/Omega-JS-Stack/omega/issues/624) deleted the
+standalone-IIFE `js/modules/` lane that did not).
+
+`js/modules/` is therefore not an asset lane in ANY layer. A directory that
+still exists builds nothing, and the build prints one warning naming it rather
+than ignoring it in silence ([#249](https://github.com/Omega-JS-Stack/omega/issues/249)).
+Shared code goes in `js/libs/`; a script that belongs to one layout goes in
+`js/layouts/<layout>.js`.
+
+## Premade consumer JS: `src/assets/js/libs/`
+
+The consumer twin of this directory. A brand's own shared browser modules live
+in `src/assets/js/libs/` and are imported **by path** from any page module or
+from `js/main.js`:
+
+```js
+// src/assets/js/pages/pricing/index.js
+import { trackPlanChoice } from '../../libs/pricing-telemetry.js';
+```
+
+Nothing declares them and nothing registers them: they are ordinary modules the
+bundler follows from whichever entry imports them, so they land in the importing
+bundle (or a shared chunk, when more than one entry uses them) and cost nothing
+on a page that does not. The framework's own `libs/` below are reached the same
+way, through the `__main_assets__` specifier instead of a relative path — one
+idiom, two layers.
+
+Two neighbours it is NOT: `js/pages/**` is keyed by URL and loads itself, and
+`js/layouts/**` is keyed by layout name and does the same — a lib is only ever
+loaded by something that imports it. A `js/pages/` file nothing imports and no
+URL claims is dead code, and the orphan guard says so
+([#469](https://github.com/Omega-JS-Stack/omega/issues/469)); a `js/libs/` file
+nothing imports is simply never built.
+
+## The consumer rule: import the helper, never the library
+
+charts.js and graph.js state it, and it holds for both: @tanstack/charts and
+mermaid are dependencies of `@omega.js/web`, never a CDN load at runtime, and a
+page reaches either one ONLY through its helper module. Consumers import the helpers and
+never name the underlying library, so its version and delivery stay the
+framework's to change. The helpers own three things a page would otherwise have
+to redo:
+
+- **Lazy loading.** The library import inside `loadCharts` / `loadGraph` is
+  dynamic, and the bundle is ESM with splitting, so each library lands in its
+  own chunk fetched only when a page asks for it. A page with no chart or
+  diagram pays nothing.
+- **Theming.** Colors are read off the `--omega-*` token sheet at draw time
+  ([docs/shared/theming.md](shared/theming.md)), so a chart or diagram follows
+  the brand ramp and dark mode without knowing either exists.
+- **Bundling.** The framework's own installed copy of the library resolves for
+  whoever imports it, so it ships once.
+
+The practical consequence for a consumer: do not hand-roll SVG for a chart or a
+diagram, and do not add @tanstack/charts or mermaid to a target's dependencies.
+
+## The modules
+
+| Module | What it is | Key exports |
+|---|---|---|
+| `admin-helpers.js` | Formatting and stat-cell helpers for the admin pages: relative timestamps, capitalization, and writing a settled Firestore count-aggregation result (or an inline error) into a stat element | `formatTimeAgo`, `capitalize`, `setStatValue`, `setStatSubValue` |
+| `alert-dismiss.js` | The site alerts' × ([#719](https://github.com/Omega-JS-Stack/omega/issues/719)): one delegated `document` click handler hiding the `.main-alert` a pressed `.main-alert-close` sits in. `core/js/main.js` calls it, so every banner `core/_includes/core/body.html` ships is dismissible on every page, an alert injected after boot included | `setupAlertDismiss` |
+| `analytics.js` | The web HOST of the analytics facade ([#328](https://github.com/Omega-JS-Stack/omega/issues/328)): it wires the page's three seams into `@omega.js/analytics` and is the ONE way core code counts anything. Detail below | `event`, `identify`, `reset`, `configureAnalytics`, `readPlatformCookies`, `PLATFORM_COOKIES` |
+| `charts.js` | TanStack Charts behind framework helpers: lazy load, token colors, a slot to draw into, four chart builders. Detail below | `loadCharts`, `chartsReady`, `chartColors`, `resolveColor`, `chartSlot`, `chartDefinition`, `barChart`, `stackedBarChart`, `doughnutChart`, `lineChart` |
+| `dev.js` | Development-only helpers, imported by `runtime/boot.js` only when `manager.isDevelopment()`: a click logger, a breakpoint logger on resize, and the palette's **Tools** section — "Log opening tags" and "Toggle theme", which were `window.logOpeningTags()` / `window.changeTheme()` until [#342](https://github.com/Omega-JS-Stack/omega/issues/342) made the palette the one home | default export: a function that installs all of it |
+| `graph.js` | mermaid behind framework helpers, on the charts contract: a definition in, an SVG out. Detail below | `loadGraph`, `graphReady`, `graphTheme`, `graphSlot`, `drawGraph` |
+| `initialize-tooltips.js` | Initializes every `[data-bs-toggle="tooltip"]` element as a Bootstrap tooltip, and exits early when the page has none. The ONE home for the behavior ([#99](https://github.com/Omega-JS-Stack/omega/issues/99)): each theme's `_theme.js` calls it from its DOM-ready handler instead of shipping its own copy | default export: `initializeTooltips()` |
+| `logger.js` | The web runtime's tagged console, `[@omega.js/web:<module>]` with no timestamp ([#12](https://github.com/Omega-JS-Stack/omega/issues/12)). The methods are getters returning a bound `console` method, so devtools attributes each line to the real call site and a swapped `console` method is still seen | `createLogger(module)`, also the default export |
+| `omega-copy.js` | Declarative copy-to-clipboard ([#709](https://github.com/Omega-JS-Stack/omega/issues/709)): one delegated `document` click handler making any `data-omega-copy` element a copy control, so a page writes no JS. The copied value resolves in order — the `omegaCopyValue` property or `data-omega-copy-value` (display and clipboard may differ: a masked row copies the real credential), a selector in `data-omega-copy` (an input's value, a `<pre>`'s text), then the sibling field in the same `.input-group`. Feedback is `showNotification` ('Copied!' / 'Failed to copy' / 'Nothing to copy'). `core/js/main.js` calls it | `setupCopy` |
+| `path-prefix.js` | The browser half of base-path support ([#355](https://github.com/Omega-JS-Stack/omega/issues/355)): reads the mount off `<html data-omega-path-prefix>` (the build's own stamp — never baked into the bundle) and mounts a root-relative site path under it. Every absence — no stamp, no document, a worker scope — means the domain root | `pathPrefix()`, `siteUrl(path)` |
+| `payment-config.js` | Reads the payment config (products, providers, prices, feature values, currency) off `omega.config.payment` and the FEATURES CATALOG off `omega.config.features`, both populated by the build, so no page fetches either at runtime. A feature is defined ONCE in the catalog and a product names only its value ([#647](https://github.com/Omega-JS-Stack/omega/issues/647)), so `getProductLimits` is the catalog-aware read: only the counted features a product gives a NUMBER | `getPaymentConfig`, `getProviders`, `getProducts`, `getProductById`, `getFeatureCatalog`, `getFeature`, `getProductFeatures`, `getProductLimits`, `getProductPrices`, `getCurrency` |
+| `recaptcha.js` | reCAPTCHA v3 for any public form posting to a recaptcha-gated backend route (checkout payment intent, newsletter capture): lazy script load through `omega.dom().loadScript()`, then a token per action. Site key: `omega.config.captcha.providers.recaptcha.siteKey` | `initializeRecaptcha(siteKey)`, `getRecaptchaToken(action)` |
+| `srcset.js` | The srcset candidate parser for the browser ([#367](https://github.com/Omega-JS-Stack/omega/issues/367)): rewrites every candidate URL through a caller's function, reading a comma inside a URL (a `data:` payload, a `?w=100,200` query) as part of the URL. The FORMAT TWIN of the build-time `packages/web/src/srcset.js` — a grammar change lands in both files, and each one says so. Used by the runtime lazy-loader for the `data-srcset` lane the build passes defer | `mapSrcset(value, mapUrl)` |
+| `sale-name.js` | Picks the promotion name for a date. Holidays (Black Friday, Cyber Monday, Christmas, Easter) run a window of 7 days before to 3 days after their core date, and a later holiday only takes over once the earlier one's core date has passed; with no holiday active it falls back to the season (`Spring Sale`, and `End of Summer Sale` past 70% of the season), then to a plain `Sale` | `getSaleName(date)`, `getUpcomingSales(startDate, endDate)`, default `{ getSaleName, getUpcomingSales }` |
+
+### analytics.js
+
+The ONE call, and nothing about a provider at the call site:
+
+```js
+import { event } from '__main_assets__/js/libs/analytics.js';
+
+event('user_refund_request', { action: 'submit' });
+```
+
+The name is a CANONICAL event from `@omega.js/analytics`' catalog, which decides
+which providers hear it, under which native name, in which dialect — the whole
+contract is [docs/shared/analytics.md](shared/analytics.md). This module is
+the web HOST of that facade: it injects the three seams only a page can supply,
+once, and exports the call sites' entry points.
+
+| Seam | What web supplies |
+|---|---|
+| `transport` | the package's guarded browser transport — `gtag` / `fbq` / `ttq`, each checked with `typeof` before it is called |
+| `consent` | a gate over `libs/tracking-consent.js`, read LIVE, so a visitor who accepts mid-session is counted from that moment ([#383](https://github.com/Omega-JS-Stack/omega/issues/383)) |
+| `context` | `runtime: 'web'` plus the captured attribution, flattened into what the adapters read ([#384](https://github.com/Omega-JS-Stack/omega/issues/384)) |
+
+`environment` is NOT web's: @omega.js/client injects it from the brand's own
+`config.environment`, which is what decides whether an unknown event name throws.
+
+The package is reached THROUGH @omega.js/client (`@omega.js/client/modules/analytics.js`),
+never as a bare `@omega.js/analytics`: the analytics package is private and never
+publishes, so in a consumer install it exists only as the copy vendored into the
+client's dist — and the client is a real runtime dependency of every framework.
+
+**Identity is not an event.** `identify(user)` and `reset()` set what the events
+after them inherit — GA4's user properties, the Meta Pixel's advanced-matching
+`init`, TikTok's `identify` — so they have no catalog entry, and they live here,
+guarded the same way. `core/js/core/auth.js` calls them off the auth state. GA4's
+`user_id` is deliberately NOT among them: @omega.js/client's `setUserId` owns
+that one key on every runtime and sends the derived `uuidv5(uid, namespace)`
+value, so a raw uid written here would only clobber it.
+
+**`readPlatformCookies()`** is exported for the same SSOT reason: the checkout's
+intent payload needs the `_fbc`/`_fbp`/`_ttp` read at conversion time
+(`pages/payment/checkout/modules/api.js`), and one reader means a separator quirk
+cannot be fixed on one path and left on the other.
+
+**Why guarded at all**: `gtag`, `fbq` and `ttq` are page-level snippets, and an
+ad blocker does not stub them — it keeps them from ever being defined, so a BARE
+call throws a ReferenceError. Every one of these calls sits in front of the thing
+the customer just pressed, so the throw takes the action with it. That was the
+billing card's dead "Undo cancellation" button
+([#283](https://github.com/Omega-JS-Stack/omega/issues/283)), found again in 19
+other files ([#306](https://github.com/Omega-JS-Stack/omega/issues/306)). Each
+provider is checked on its own, because blockers work per list: a page that lost
+Meta still counts Google. The same reasoning covers this module's own storage
+reads (consent, attribution): a read that fails is a denial or an absence, never
+a raise.
+
+`test/analytics-blocked.test.js` keeps it the SSOT with two static sweeps: no
+file under `core/js` or the theme layer calls a provider global bare, and none
+names a provider at all — the retired `trackGoogle` / `trackMeta` / `trackTikTok`
+wrappers cannot regrow one page module at a time. Two files may name the globals:
+this module (the guard itself, plus the identity calls) and
+`core/js/core/analytics-loader.js`, which DEFINES them.
+
+### charts.js
+
+The library is [TanStack Charts](https://tanstack.com/charts/latest) — a
+grammar (marks, scales, mappings) with a framework-neutral DOM host that
+renders SVG ([#772](https://github.com/Omega-JS-Stack/omega/issues/772)). It is
+**Alpha**, where 0.x minors move together and may break, so the version is an
+EXACT pin in `packages/web/package.json` (`"@tanstack/charts": "0.16.0"`, no
+range) and an update is a deliberate read of its release notes.
+
+The lifecycle is load, slot, draw:
+
+1. `await loadCharts()` loads the library once. It is idempotent and safe to
+   call on every poll (a failed load clears the cached promise so a later call
+   can retry), and it resolves a boolean. The grammar is per-capability, so the
+   one call fetches the root (Cartesian marks + the DOM host) alongside the
+   polar, tooltip and scale subpaths — several chunks, one lazy load.
+2. `chartSlot(id, height = 220, series = [])` returns the markup to render: a
+   height-bearing box around a `<div id="…">` host that fills it, because the
+   host follows its container's WIDTH on its own and is told its height. It
+   stamps `series` onto the box as `data-series` so `@omega.js/client`'s
+   write-on-change `swap` (`modules/live-page`) sees a data-only change and
+   redraws; a host carries no data of its own, so without the stamp the old
+   picture would stand.
+3. One of `barChart` (with `horizontal` for ranked rows), `stackedBarChart`,
+   `doughnutChart`, `lineChart` draws into that id and returns the chart host,
+   or `null` when nothing was drawn.
+
+`chartsReady()` is the synchronous check for a render path. Every draw destroys
+the host already mounted on that id first (the module keeps a Map of id → host),
+so repainting on each poll replaces rather than stacks, and `svgAnimation` is
+off for the same reason: a polled page would otherwise spend most of its life
+growing bars back out of the axis.
+
+A value axis is labelled in WHOLE numbers: these charts count things, and the
+library's own tick policy is a responsive count that lands on 0.5 on a small
+domain. The helper supplies integer candidates on the 1/2/5 ladder and a
+configured `[first tick, last tick]` domain, so the axis ends exactly on its
+ticks; zero always stays on the axis, and a negative reading widens the span downwards.
+
+A tooltip names the THING being read, never the channel it rode in on
+([#800](https://github.com/Omega-JS-Stack/omega/issues/800)): a bar says
+`label: value`, a stacked segment and a line reading say `series · label: value`,
+and a doughnut slice adds its share of the whole. The unit travels with the
+data — `format: { prefix?, suffix?, decimals? }` on any builder's data argument,
+plain JSON so a page carrying chart data alone can hold it — and it prints in
+the tooltip AND on the value axis, so a money chart says `$` in both places.
+Stated `decimals` are exact (`$7.00`); unstated, a count prints as itself and a
+fraction gets at most two places. A page with JS may pass
+`tooltip: (point) => string` to take the whole line over, where `point.datum` is
+the row the mark drew (`{label, value}`, plus `series` on a stacked or line
+chart, plus `fraction` on a doughnut).
+
+`chartDefinition(kind, data)` — `'bar'`, `'stacked'`, `'doughnut'`, `'line'` —
+returns the definition a builder would draw, without drawing it. A definition is
+renderer-neutral and DOM-free, which is what lets the package's own suite
+(`test/dataviz.test.js`) compile all four through `createChartScene` and assert
+real geometry in node. The PAINT still needs a browser: the sandbox e2e lane's
+chart step (`brands/sandbox-brand/test/e2e/run.js` → `window.__omega.drawCharts()`)
+fails a chart whose host holds no SVG mark with a non-zero box. An unknown kind
+is a programmer error and throws.
+
+Element ids are authored, so `chartSlot` throws on anything that is not a plain
+id. When the library did not load, `chartSlot` returns a line saying so in place
+of the host instead of leaving a hole, which is why a chart always sits beside
+the same figures in a table or statgrid.
+
+Theming: `chartColors()` reads `--omega-ink-muted`, `--omega-line`,
+`--omega-accent`, and the categorical ramp `--omega-chart-1` through
+`--omega-chart-6` off `:root`, falling back token, then Bootstrap variable, then
+a hardcoded color. Those values become the definition's `theme` (axis and
+legend ink, gridlines, the categorical palette) and its color scale's `range`.
+`resolveColor()` turns a `var(--token)` string into a real color, which is how a
+caller passes `colors: ['var(--omega-ok)', …]` to keep STATUS meaning where the
+categorical ramp would only say "different". Tokens are read at draw time and
+nothing listens for a theme flip, so a light/dark switch lands on the next
+redraw.
+
+### graph.js
+
+The same shape, for mermaid diagrams: `await loadGraph()`, then
+`graphSlot(id, height = 320, definition = '')`, then
+`await drawGraph(id, definition)`, with `graphReady()` as the synchronous check.
+`drawGraph` returns the SVG it rendered (also written into the host), or `null`.
+The module takes a DEFINITION in and puts an SVG out: composing the mermaid text
+is the page's business, because the shapes and words in a diagram are content,
+not framework.
+
+`graphSlot`'s height is a FLOOR (`min-height`): the host is empty until the
+render lands, so the box reserves the space rather than letting the page jump,
+and a taller diagram still grows past it. The definition is stamped as
+`data-series` for the same `swap` reason charts stamp their series, and ids are
+validated the same way.
+
+`graphTheme()` resolves the live tokens into mermaid `themeVariables` for the
+`base` theme: ink, both surfaces, `--omega-line` for edges, `--omega-accent` for
+the node outline, and the same `--omega-chart-1` through `--omega-chart-6` ramp
+charts read, mapped onto mermaid's `cScale0` through `cScale5` and `pie1` through
+`pie6` slots (an unset slot is left out so mermaid derives its own). Mermaid
+paints with literal colors, so nothing is ever handed a `var()`. `drawGraph`
+initializes per render (`startOnLoad: false`, `securityLevel: 'strict'`,
+`suppressErrorRendering: true`) because the tokens are read per render, and it
+throws on a definition that does not parse: diagram text is authored, so a syntax
+error in it is a programmer error and says so instead of drawing nothing.
+
+## The auth cluster (`libs/auth/`)
+
+The three auth pages (`/signin`, `/signup`, `/reset`) share nearly all of their
+logic, so the page modules import one orchestrator and the flows live in focused
+modules beside it. `auth/index.js` builds a shared context object
+(`{ formManager, useAuthPopup }`) and passes it explicitly to every flow that
+needs it.
+
+The boot order is the orchestrator's whole job, and it runs inside
+`omega.dom().ready()`: handle `?authSignout`, then `?authCustomToken`, then
+`?authPrivateKey` (return if either sign-in took over, the page is navigating),
+then build the page's form from the `data-page-path` suffix, disable the fields
+while checking for a returning OAuth redirect (return if one was handled), then
+check the subdomain policy, call
+`formManager.ready()`, and propagate `authReturnUrl` into the page's auth links.
+
+| Module | What it is | Key exports |
+|---|---|---|
+| `auth/index.js` | The orchestrator: owns the boot order above and picks the form by matching the final segment of `data-page-path`. Imported by the `/signin`, `/signup`, and `/reset` page modules | default export: a function |
+| `auth/forms.js` | FormManager wiring for the three forms (built with `autoReady: false`, since the boot sequence calls `ready()` itself), the shared validation that only checks email and password when the pressed button's `data-provider` is `email`, the provider-aware submit handler, and the signup consent UI: both checkboxes are outlined as one unit, and consent is stashed to `omega.storage()` BEFORE any Firebase call so it survives the post-signup redirect for the backend's signup route | `initializeSigninForm`, `initializeSignupForm`, `initializeResetForm` |
+| `auth/email.js` | Email and password flows. Signup falls back to signing the user in when the address is already in use; reset reports success even for an unknown address, to avoid email enumeration; and each error lands on the field it belongs to (Firebase collapses wrong-email and wrong-password into one code, so both fields get the shared message) | `handleEmailSignin`, `handleEmailSignup`, `handlePasswordReset` |
+| `auth/oauth.js` | Provider flows: redirect by default, popup only inside an iframe or with `?authPopup=true`, with a popup-to-redirect fallback on blockers. Also the returning-redirect provider (a one-shot sessionStorage marker makes a redirect that came home empty loud instead of silent) and the accidental-signup reversal: Google auto-creates an account during a signin attempt, so the reversal deletes it, signs out, and shows an inline error — and marks the uid for `auth/orphan.js` when that delete fails | `shouldUseAuthPopup`, `handleRedirectResult`, `signInWithProvider`, `reverseAccidentalSignup` |
+| `auth/orphan.js` | The failed-delete backstop ([#703](https://github.com/Omega-JS-Stack/omega/issues/703)): a reversal whose `.delete()` fails leaves a live account with no consent record, and nothing about the account says so afterwards (a self-read is always allowed, and every account is consent-less until the `/user/signup` post lands), so the browser that failed the delete marks the uid in `omega.storage()`. `core/js/core/auth.js` retries the delete at auth-ready for THAT uid and nothing else — an account with legal consent on record is never touched, and a deliberate signup clears the markers before Firebase is called. A second failure signs the user out, reports it, and keeps the marker for the next visit | `markOrphanedAccount`, `clearOrphanMarkers`, `retryOrphanCleanup` |
+| `auth/session-params.js` | The URL-parameter session behaviors: `?authSignout=true` (sign out, then strip the param so reloads do not loop), `?authCustomToken=…` (admin impersonation and custom-token sign-in, which owns its own post-signin navigation), `?authPrivateKey=…` (the durable-URL lane for an OBS dock, a kiosk, or a bookmark: a custom token expires in an hour, so the key buys a fresh one at `POST /omega/user/token` on every load, is stripped from the address bar BEFORE the page moves, and is never logged, notified, or captured), `authReturnUrl` propagation into every auth link on the page, and the apex-domain bounce when `auth.config.allowSubdomainAuth` is false | `handleAuthSignout`, `handleCustomTokenSignin`, `handlePrivateKeySignin`, `updateAuthReturnUrl`, `checkSubdomainAuth` |
+| `auth/errors.js` | Pure Firebase error translation, no DOM and no form state: which codes belong on the password field, the short message for each, which codes are user-caused and therefore never worth a Sentry capture, and pulling a `@omega.js/backend` blocking-function message (rate limit, disposable email) back out of the opaque `auth/internal-error` blob | `isPasswordError`, `passwordErrorMessage`, `isUserError`, `extractBlockingFunctionMessage` |
+| `auth/tracking.js` | GA4, Facebook Pixel, and TikTok Pixel events for the three auth outcomes | `trackLogin`, `trackSignup`, `trackPasswordReset` |
+| `auth/password-toggle.js` | The password eye, registered once as the `password-toggle` click trigger on `@omega.js/client`'s shared trigger registry ([#16](https://github.com/Omega-JS-Stack/omega/issues/16)). `core/js/main.js` calls it, so it is armed on every page before any page module runs, and delegation covers input groups rendered after boot | `setupPasswordToggle` |
+
+## See also
+
+- [docs/web/index.md](index.md) for the framework guide, including the bundler
+  aliases and the conventions charts, graphs, and the log tag are pinned by
+- [docs/shared/theming.md](shared/theming.md) for the `--omega-*` tokens the
+  chart and graph helpers read

package/docs/omega-sections-spec.md

@@ -0,0 +1,159 @@
+---
+status: ratified
+created: 2026-07-18
+---
+# OMEGA Sections & Components — Architecture Spec
+
+> **STATUS: RATIFIED (Ian, 2026-07-18 — same night as the design).** Extraction underway; durable parts migrate to `docs/web/sections.md` as pieces land.
+> Scope: ALL frameworks (web, desktop, extension, future) — this design is made once and never redesigned. No backwards compat anywhere (standing rule).
+
+## 0. Why (the ruling that produced this)
+
+The frontmatter-monolith model (theme layout = whole page, copy as frontmatter defaults) has one fatal flaw — the **fork cliff**: consumers can override words but never structure; the only escape is owning a 600-line layout forever. Ian + Claude independently converged on a **section/component library**: structure becomes data, sections stay framework-owned, updates keep flowing. Massive frontmatter is explicitly rejected ("we tried that and its ugly") — frontmatter shrinks to page meta only.
+
+## 1. The two-tier library
+
+- **Sections** — full-width page bands (hero, testimonials, bento, pricing table, article list…). Pages are compositions of sections.
+- **Components** — smaller reusable pieces (browser frame with mac buttons, terminal, marquee, stat card…). Used inside sections and directly in pages.
+
+Both tiers share the same anatomy, resolution, and asset rules.
+
+## 2. Anatomy — a section is a folder that owns everything about itself
+
+```
+themes/base/_sections/marketing/hero/
+  section.html    ← markup (Liquid). The args are the data contract.
+  section.scss    ← its styles (optional)
+  section.js      ← its behavior (optional — most sections have none)
+  section.json5   ← meta: arg schema + defaults + showcase demo data
+```
+
+(Naming amendment, cp204: the folder families are `_sections`/`_components` —
+the Jekyll-family underscore marks template machinery, matching
+`_layouts`/`_includes`, and keeps Eleventy from processing them as content.)
+
+Components identical with `component.*` filenames. Standard filenames (not `<name>.html`) so tooling/resolvers are predictable.
+
+**The context-free rule (load-bearing):** args in → HTML out. Section markup never reaches into page globals (`site.*`, nav state, collections). This single rule is what makes sections renderable on every framework surface and portable to any future engine.
+
+## 3. Organization — nested, dozens-scale
+
+- Section id = path under `sections/` (kebab-case): `marketing/hero`, `commerce/pricing-table`, `content/article-list`, `app/stat-cards`.
+- Arbitrary nesting allowed; the showcase groups by folder automatically.
+- Same for components: `frame/browser`, `frame/terminal`, `motion/marquee`.
+
+## 4. Resolution & layering (mirrors the theme layer chain)
+
+For `{% section "marketing/hero" %}`, first match wins:
+
+1. **Consumer-local**: `<src>/_sections/marketing/hero/` — consumers author their own sections here (their git holds ONLY their own work)
+2. **Active theme**: `themes/<active>/_sections/...`
+3. **Base layer**: `themes/base/_sections/...` — the floor, same as the theming two-lane model
+
+Theme sections live inside the installed package (never scaffolded into the consumer repo) — consumer git stays clean; framework updates flow.
+
+## 5. Authoring syntax
+
+**Frontmatter is minimal forever**: meta title/description, permalink, page-level config only. Content lives in the body as section calls.
+
+Inline form (simple args):
+```liquid
+{% section "marketing/hero", headline: "Ship every surface" %}
+```
+
+Block form (structured data — objects, arrays, N items):
+```liquid
+{% section "marketing/testimonials" %}
+headline: "What builders say"
+items:
+  - quote: "Shipped in a weekend."
+    name: "Avery Quinn"
+    role: "Founder, Loopwork"
+  - quote: "One config. Every surface."
+    name: "Sam Okafor"
+    role: "CTO, Fieldnote"
+{% endsection %}
+```
+
+- Block body = YAML (same dialect as frontmatter). One tag, two forms; using both inline args and a block body on the same call is an error (simplicity first).
+- **Amendment (Ian 2026-07-18, landed cp224) — slots**: the body may also carry named markup blocks (`{% slot demo_html %}<any html>{% endslot %}`), composing with inline args OR the YAML (the both-forms error applies to the YAML remainder). Slot content renders in the caller's scope and reaches the section as a finished-HTML string arg (schema type `html`), merged outermost and never re-rendered. Full contract: docs/web/sections.md.
+- No args → the theme's default copy renders (defaults from `section.json5`).
+- Components: `{% component "frame/browser", url: "app.example.com" %}` — same two forms.
+- Sections must be **N-item responsive by design** (auto-fit grids etc.) — item count is data, layout self-adjusts; showcase demo data exercises 1/3/many variants.
+
+## 6. Schemas & validation (`section.json5`)
+
+- Declares: args (name, type: string/number/bool/array/object/enum, default, description), demo data for the showcase (variants allowed).
+- Build-time validation: unknown arg → warning with did-you-mean (`hero.headlin` → `headline`); type mismatch → warning. This is the typed-props benefit without changing engines.
+- Schema names are **API** — renames are breaking and follow deprecation discipline (warn one minor, remove later).
+- **Defaults ownership (cp205 ruling)**: a section used by ONE page lifts that page's default copy into its json5 (hero precedent); a section SHARED by multiple pages (testimonials: index + pricing + alternatives) keeps json5 defaults NEUTRAL — mechanical knobs only (e.g. the avatar placeholder frame) — and every caller passes its own copy over the data bridge, so no page can ever inherit another page's words.
+
+## 7. Assets
+
+- **CSS**: every section's `section.scss` compiles into the theme sheet (stable order); **PurgeCSS (already in the pipeline) strips sections a site never renders** — shipped CSS self-trims, zero config.
+- **JS**: section JS bundles into the theme bundle behind DOM-presence auto-init (`data-omega-section="marketing/hero"` → init only when present) — same pattern as the motion library. Manifest-driven per-section splitting stays available later if bundles fatten.
+- **Page assets — `asset_path` is DEAD**, replaced by wildcard filenames (Next.js convention, Windows-safe):
+  - `js/pages/team/[id].js` / `css/pages/team/[id].scss` match any `/team/<segment>` page without an exact module; exact path beats wildcard.
+  - Internal uses convert too (`js/pages/blog/[slug].js`); zero frontmatter involved.
+
+## 8. Pages model — blueprints stay, absence is the spine
+
+- **No file → theme/blueprint default renders** (Ian's loved behavior, preserved verbatim). Default pages become section compositions internally; pricing/contact/TOS keep filling from config.
+- **`omega customize <url>`** (verb SETTLED, Ian 2026-07-18): materializes the page prefilled with the default composition as clean one-liners (no copy inlined) — consumer adds args only where they diverge. Nobody starts blank; nobody owns what they didn't change.
+- Deep escape hatch unchanged: consumer-local theme file override = own that file forever (documented cost: its updates freeze).
+
+### Sample content (Ian 2026-07-18)
+
+- Posts/teammates/updates-style filler stays **SHARED across themes** — never per-theme. Scope = that filler only; anything bigger goes back to Ian.
+- It becomes **auto-generated with rolling current dates** (a virgin blog always looks alive, never "6 months stale") and materializes only under a **gitignored test path** in the consumer tree — never committed, never mixed with real brand content.
+
+### Update semantics (the truth table)
+
+| Consumer state | Theme updates (html/css/js/copy) | What's preserved |
+|---|---|---|
+| No file | Everything flows | — (nothing to preserve) |
+| Composition + args | All section internals flow; their words/composition preserved; framework NEVER writes consumer files | Their args + composition |
+| Forked theme file | Nothing flows for that file | Everything (frozen at fork) |
+
+Only schema renames can bite the middle row — governed by §6 deprecation + warnings.
+
+## 9. Showcase & docs — auto-generated
+
+- The showcase iterates the section/component library and renders each entry with its `section.json5` demo data (all variants). New section → appears automatically. The showcase stops being a hand-built page.
+- Reference docs generate from the same schemas (args table per section).
+
+## 10. Multilanguage
+
+- **The existing post-build translation system stays THE mechanism** (`packages/web/src/translate/`): reads built HTML, translates text units via `@omega.js/devkit/translate` (default provider: Claude on the local install), per-string cache committed in the consumer repo (hand-fix any string, it sticks), emits static `/{lang}/…` copies with lang/dir, rewritten links, honest hreflang. SEO-correct, zero manual translation.
+- Raw-liquid translation rejected (MT mangles template syntax). Data-level translation rejected as the pipeline (would need a second pipeline for prose anyway).
+- Section contract additions: code-y components (terminal, code frames, commands) carry the standard `translate="no"` attribute; a future per-locale arg-override lane (hand-tuned marketing headlines) rides the same committed cache.
+
+## 11. Cross-framework standardization (Ian 2026-07-18: design once, never again)
+
+- **`@omega.js/web`'s engine is the single HTML factory for every framework's HTML surfaces.** Desktop windows/pages and extension popup/options pages are BUILT by it (target-scoped page sets via `targets.*` config); no framework ever reimplements templates, sections, theming, or translation.
+- **One design contract across surfaces**: the `--omega-*` token sheet + `.omega-shell` chrome (already shipped) — sections ride on it.
+- **One translator**: `@omega.js/devkit/translate` — the post-build pass runs over any built HTML dir regardless of target.
+- Realistic surface scope: desktop inherits full pages via the website; extension shares tokens + small components (buttons, cards, frames) — marketing bands in a popup are a non-goal.
+- Enabled entirely by the context-free rule (§2).
+
+## 12. Engine ruling — Liquid stays this generation
+
+- Market reality (2026): Liquid alive and huge (Shopify engine, Eleventy first-class); the modern paradigm is components-with-typed-props (Astro/JSX/Svelte; WebC is Eleventy's answer). Greenfield would evaluate Astro seriously.
+- We are not greenfield: the layered file-override model works BECAUSE Liquid templates are interpreted at build from whichever file wins the chain (compile-time imports would break it); two themes are finished; consumers never write Liquid — they write one-liner calls + YAML.
+- Sections + schemas capture the typed-props/scoped-assets benefit at ~10% of a rewrite's cost. **Sections are the migration unit** if omega v2 ever switches engines. Revisit at the next major, not before.
+
+## 13. Sequencing (the locked map, updated)
+
+1. ~~Ian ratifies this spec~~ **RATIFIED 2026-07-18**
+2. **Extraction refactor**: classy + newsflash layouts → section/component libraries. `packages/web` only (playground-freeze-safe); corpus/golden-master pins output identical
+3. **Content pass A — omega-ify the playground**: real framework pitch as compositions/args; playground = the living draft of the real site
+4. **Content pass B — genericize classy**: sweep omega dev-accents from theme defaults (theme speaks generic SaaS; promoting OMEGA is a brand's job); optional per-theme sample posts/team
+5. **Showcase**: auto-generated from the library (§9)
+6. ~~**Arc close — THE FORK**: real omegajs.dev sub-brand born fresh outside the monorepo on published omega (fresh repo, fresh production Firebase, omegajs.dev zone, CI deploys); playground's polished content copies over 1:1.~~ **AMENDED + LANDED 2026-07-18 (Ian, cp229): the fork went LOCAL-FIRST** — born EARLY at `../omegajs.dev` (sibling repo) on relative `file:` specs into the monorepo ("still use local … until we are fully locked on all decisions that may result in breaking changes"), versions pre-reset to 1.0.0 (cp228) so first publish flips the specs to `^1.0.0` seamlessly; content forked 1:1 as specced (stale es caches dropped + re-translated fresh); **"published omega, fresh production Firebase, omegajs.dev zone, CI deploys" are now LAUNCH GATES, not birth conditions.** **The playground stays in the monorepo forever as the dedicated live test brand** (real Firebase, zero customer risk, break it freely)
+7. Post-arc: company umbrella brand + sub-brand rebuilds (existing hard gates unchanged; the config `company` layer already models the umbrella)
+
+## 14. Open items — ALL RESOLVED (Ian, 2026-07-18)
+
+- Verb name → **`omega customize <url>`**
+- Per-theme sample content → **NO — shared filler stays shared**, but it becomes auto-generated + gitignored-test-path isolated (see §8)
+- Playground deploys after the fork → **BOTH lanes**: simple direct push is the normal lane (CI runs cost real money), and the full CI-dispatch path gets deliberately exercised every once in a while so it stays proven

package/docs/page-contract.md

@@ -0,0 +1,112 @@
+# The page paint contract
+
+What every page owes a visitor in its first frame, and what it may make them
+wait for. Ratified by Ian on 2026-08-27
+([#637](https://github.com/Omega-JS-Stack/omega/issues/637)) after the checkout
+page held its prices behind a cold backend.
+
+The rules are five. They apply to every page in `packages/web/core/js/pages/`
+and to every consumer page built on this framework.
+
+## 1. Static content paints immediately
+
+A page never hides its DOM waiting for auth. Everything the build already knows
+goes on screen in the first frame: copy, prices from the payment config, plan
+tiles, buttons, forms.
+
+Redirects are not the page's job. The global auth policy owns them
+(`packages/web/core/js/core/auth.js`): a visitor in the wrong state is sent
+elsewhere before the page code runs. A page that hides itself "in case" is
+hiding from a visitor who is allowed to be there.
+
+That listener also owns the MID-SESSION case: it redirects the moment
+@omega.js/client's session probe signs a dead session out, so a revoked,
+disabled or deleted account leaves an `authenticated` page for sign-in with no
+reload ([the session probe](../client/index.md#the-session-probe-omegaauthprobesession),
+[#798](https://github.com/Omega-JS-Stack/omega/issues/798)).
+
+## 2. User data arrives through bindings
+
+Anything that depends on the signed-in user renders through
+`data-omega-bind`, with a skeleton on the element until it fills. The client
+fills the `auth`, `usage`, `config` and `device` roots on every page when auth
+settles (`packages/client/src/modules/auth.js`). Page code does not repeat that
+work.
+
+Page code awaits auth for exactly one reason: to make a request that needs the
+user. Never to decide whether to draw something.
+
+## 3. An answer the visitor acts on resolves ONCE
+
+Trial eligibility, the current plan, the price actually being charged: the
+visitor decides with these, so they must never flip from one answer to another
+while being read.
+
+The spot holding such an answer keeps its skeleton until the answer lands, and
+then renders once. The rest of the page is already painted around it. Only the
+spot waits.
+
+The bindings root key is the unit of deferral. `bindings.update()` filters by
+the top-level keys it was handed, so a spot that must wait belongs to a root
+the early paint does not publish
+([packages/client/docs/bindings.md](../../packages/client/docs/bindings.md)).
+Checkout is the worked example: its build-config half publishes `checkout`, and
+the money line and trial spot live under `order`, written once when eligibility
+answers.
+
+## 4. Every wait has a deadline and a named fallback
+
+A network wait behind user-visible copy gets a timeout, a constant that names
+it, and a fallback state that is a decision rather than an accident. The
+fallback is logged as a warning when it fires.
+
+Pick the fallback that keeps the page's promises.
+
+Checkout's trial check has THREE answers, not two: yes, no, and unknown. A
+check that timed out or failed is unknown, and the page splits that answer in
+two (Ian 2026-08-27). What it SHOWS stays conservative: no trial quoted, the
+full amount due today, because rule 3 never shows a price the server has not
+confirmed. What it ASKS FOR in the intent payload is the trial anyway, because
+the intent route re-checks eligibility against the buyer's own order history and
+silently downgrades anyone who does not qualify. Asking costs a non-qualifying
+buyer nothing; not asking would cost a qualifying one their offer over a slow
+network. A visitor is never quoted a price they are not charged, and never
+loses an offer to a timeout.
+
+## 5. Forms gate their submit control
+
+Every form uses FormManager
+(`@omega.js/client/modules/form-manager.js`). When a form must not be submitted
+until an async answer is in, the page registers a gate per answer before it
+calls `ready()`:
+
+```javascript
+formManager.addGate('eligibility');
+formManager.addGate('recaptcha');
+formManager.ready();          // held: the form stays `initializing`
+...
+formManager.resolveGate('recaptcha');
+formManager.resolveGate('eligibility');   // the last one arms the form
+```
+
+The submit controls stay disabled while a gate is open. The rest of the form
+stays live, so the visitor can still read it and change their choices. Both
+calls fail loudly on a mistake: a gate added after the form armed throws, and so
+does resolving a name that opened no gate (a typo would otherwise leave the form
+gated forever).
+
+## Reading a page against the contract
+
+Four questions, in order:
+
+1. Does anything in the first frame wait on a promise? If yes, does it need the
+   user, or was the answer already in the build config?
+2. Is any element hidden pending auth that the auth policy already protects?
+3. Can any user-visible value be written twice with two different answers?
+4. Does every wait behind visible copy have a deadline and a named fallback?
+
+## Related
+
+- [docs/web/index.md](index.md) — the web framework guide
+- [docs/client/index.md](../client/index.md) — the runtime that fills the bindings
+- [packages/client/docs/bindings.md](../../packages/client/docs/bindings.md) — `data-omega-bind`, skeletons, root-key update filtering