@omega.js/client 0.1.0

package/docs/bindings.md

@@ -0,0 +1,235 @@
+# Bindings (`data-omega-bind`)
+
+The `data-omega-bind` attribute declaratively binds DOM elements to state data (auth, plan, roles, usage, custom state) managed by `omega.bindings()`. **Always prefer omega-bindings over manual JS class toggling** for anything based on user/auth state — if an element's visibility or content depends on the user object, use `data-omega-bind` in HTML, not `classList.toggle('d-none', ...)` or `.hidden` from JS.
+
+## HTML Syntax
+
+```html
+<element data-omega-bind="@action path.to.data"></element>
+```
+
+### Multiple Bindings: MUST Use Commas
+
+Multiple bindings are **comma-separated**. The parser splits by comma first, then parses each part as `@action expression`.
+
+```html
+<!-- CORRECT: comma-separated -->
+<element data-omega-bind="@show auth.user, @attr src auth.user.photoURL"></element>
+
+<!-- WRONG: space-separated — gets parsed as ONE binding with action=@show, expression="auth.user @attr src auth.user.photoURL" -->
+<element data-omega-bind="@show auth.user @attr src auth.user.photoURL"></element>
+```
+
+**Why this matters:** The parser splits on `,` then finds the first space within each part to separate `@action` from `expression`. Without commas, everything after the first `@action` is treated as a single expression string, producing broken behavior with no error.
+
+## Supported Actions
+
+| Action | Syntax | Description |
+|--------|--------|-------------|
+| `@text` | `@text path` | Set text content |
+| `@value` | `@value path` | Set input/textarea value |
+| `@show` | `@show condition` | Show element if truthy |
+| `@hide` | `@hide condition` | Hide element if truthy |
+| `@attr` | `@attr name path` | Set HTML attribute value |
+| `@style` | `@style property path` | Set CSS property or CSS variable |
+
+## Condition Operators
+
+```html
+<!-- Truthy check -->
+<div data-omega-bind="@show auth.user">Visible when logged in</div>
+
+<!-- Negation (!) -->
+<div data-omega-bind="@show !auth.user">Visible when NOT logged in</div>
+
+<!-- Comparisons (===, !==, ==, !=, >, <, >=, <=) -->
+<div data-omega-bind="@show auth.account.plan.id === 'premium'">Premium only</div>
+<div data-omega-bind="@show checkout.errorCount > 0">Has errors</div>
+```
+
+No logic operators (`&&`, `||`) in conditions — keep conditions simple. Right-side comparison values are auto-parsed: quoted strings, numbers, booleans, null.
+
+## Common Auth Patterns
+
+```html
+<!-- Show for anonymous users -->
+<div data-omega-bind="@show !auth.user">
+  <a href="/signup">Create free account</a>
+</div>
+
+<!-- Show for signed-in users -->
+<div data-omega-bind="@show auth.user">
+  <a href="/pricing">Upgrade your plan</a>
+</div>
+
+<!-- Admin-only elements -->
+<div data-omega-bind="@show auth.account.roles.admin">Admin panel</div>
+
+<!-- User data binding -->
+<img data-omega-bind="@show auth.user, @attr src auth.user.photoURL, @attr alt auth.user.displayName">
+<span data-omega-bind="@text auth.user.displayName">Loading...</span>
+<input data-omega-bind="@value auth.user.email">
+```
+
+## Available State Paths
+
+### Auth paths (automatically populated by @omega.js/client)
+
+```
+auth.user                        # Firebase user object (truthy = signed in)
+auth.user.uid                    # User ID
+auth.user.email                  # Email
+auth.user.displayName            # Display name
+auth.user.photoURL               # Avatar URL
+auth.user.emailVerified          # Boolean
+auth.account.plan.id             # Plan ID (e.g. 'basic', 'premium')
+auth.account.roles.admin         # Boolean
+auth.account.roles.betaTester    # Boolean
+```
+
+### Usage paths (server usage — auto-populated by @omega.js/client)
+
+```
+usage.{feature}.monthly              # Current monthly usage count
+usage.{feature}.daily                # Current daily usage count
+usage.{feature}.limit                # Plan limit for this feature
+```
+
+Example: `usage.credits.monthly`, `usage.credits.limit`
+
+Seeded on auth settle from `account.usage` + the site's payment plan config. Refreshed after every `omega.request()` call from the `omega-properties` response header — the backend attaches fresh usage counters to every response, so bound elements stay current automatically.
+
+### Device paths (local stats — auto-populated on initialize)
+
+```
+device.installed                     # First-seen timestamp (ms)
+device.session.count                 # Session count on this device
+device.version.current               # App version currently running
+device.version.isNew                 # True on the first run after an update
+device.duration.total.days           # Time since install (also: session.*, other units)
+```
+
+From the `device` module (localStorage / extension storage) — LOCAL device stats, deliberately a different key than the server-derived `usage` above.
+
+### Custom state (set via JS)
+
+Any custom paths set via `omega.bindings().update(stateObject)`.
+
+## JavaScript API
+
+```javascript
+// Update bindings with state data
+omega.bindings().update({
+  checkout: {
+    product: { name: 'Pro Plan' },
+    error: { show: false, message: '' },
+  },
+});
+
+// Get current binding context
+const context = omega.bindings().getContext();
+
+// Clear all bindings
+omega.bindings().clear();
+```
+
+## Skeleton Loaders
+
+### How Skeletons Work
+
+The `omega-binding-skeleton` class shows a shimmer animation until data loads. Skeletons resolve **only when at least one of the element's bindings is actually processed** — meaning the binding's root key must be in the `updatedKeys` for that `update()` call.
+
+When `_updateBindings` processes an element:
+
+1. Executes each binding action (`@text`, `@show`, `@attr`, etc.)
+2. Each action returns `true` (processed) or `false` (skipped because root key wasn't updated)
+3. **Only if at least one action was processed:** adds `omega-bound` class (triggers CSS fade-out transition)
+4. After 300ms, removes `omega-binding-skeleton` class (shimmer disappears)
+
+**Root key scoping matters for skeletons.** If an element is bound to `checkout.pricing.total` and `update({ auth: ... })` fires, that element's skeleton is NOT resolved — the binding is skipped entirely because `checkout` is not in `updatedKeys`.
+
+```html
+<!-- Skeleton resolves when 'auth' key is updated -->
+<span class="omega-binding-skeleton" data-omega-bind="@text auth.user.displayName">&nbsp;</span>
+
+<!-- Skeleton resolves when 'checkout' key is updated (NOT when 'auth' updates) -->
+<span class="omega-binding-skeleton" data-omega-bind="@text checkout.pricing.total">&nbsp;</span>
+```
+
+### Multi-phase binding example (e.g., checkout page)
+
+When bindings fire in phases, skeletons resolve independently per root key:
+
+```javascript
+// Phase 1: Global auth bindings fire
+omega.bindings().update({ auth: { user: {...} } });
+// → Only elements bound to 'auth.*' resolve their skeletons
+// → Elements bound to 'checkout.*' keep their skeletons
+
+// Phase 2: After API fetches complete
+omega.bindings().update({ checkout: { pricing: {...} } });
+// → Now elements bound to 'checkout.*' resolve their skeletons
+```
+
+This prevents checkout skeletons from disappearing prematurely when global auth bindings fire before checkout data is available.
+
+### Skeleton Pattern
+
+Use `&nbsp;` as placeholder content (prevents zero-width collapse so the shimmer is visible):
+
+```html
+<span class="omega-binding-skeleton" data-omega-bind="@text auth.user.displayName">&nbsp;</span>
+```
+
+**Do NOT use text like "Loading..." as placeholder** — it flashes visible text before the shimmer kicks in. Use `&nbsp;` for a clean shimmer-only experience.
+
+### Composite Text in Skeletons
+
+For composite text (e.g., "$0.00 due today"), do NOT mix static text with a binding span inside a skeleton div. Instead, create a dedicated pre-formatted value in the state and bind with a single `@text`:
+
+```javascript
+// CORRECT: compose the text in JS, bind as single value
+omega.bindings().update({
+  checkout: {
+    totalDueText: `${formatCurrency(prices.total)} due today`,
+  },
+});
+```
+
+```html
+<!-- CORRECT: single binding for composite text -->
+<span class="omega-binding-skeleton" data-omega-bind="@text checkout.totalDueText">&nbsp;</span>
+
+<!-- WRONG: mixing static text with binding inside skeleton -->
+<span class="omega-binding-skeleton">
+  <span data-omega-bind="@text checkout.pricing.total"></span> due today
+</span>
+```
+
+## Implementation Notes
+
+- Uses the `hidden` attribute for show/hide (`[hidden] { display: none !important; }`)
+- Queries `[data-omega-bind]` on each `update()` call — handles dynamic elements
+- Auth bindings are auto-populated when `omega.auth().listen()` fires
+- When `updatedKeys` is `null` (e.g., from `clear()`), ALL bindings fire
+
+### Root Key Update Filtering
+
+`_shouldUpdatePath` checks the **root key** (first segment before `.`) of each binding's expression path against the `updatedKeys` from the `update()` call. A binding only fires when its root key was updated.
+
+```javascript
+// This update ONLY triggers bindings whose expression starts with 'checkout'
+omega.bindings().update({
+  checkout: { pricing: { total: 9.99 } },
+});
+// Fires: @text checkout.pricing.total, @show checkout.active
+// Skips: @text auth.user.displayName (root key is 'auth', not updated)
+```
+
+Negation (`!`) is stripped before root-key checking, so `@show !auth.user` fires when `auth` is updated.
+
+## See also
+
+- [modules.md](modules.md) — quick reference for all nine modules
+- [architecture.md](architecture.md) — module dependency graph
+- `src/modules/bindings.js` — the implementation

package/docs/build-system.md

@@ -0,0 +1,32 @@
+# Build System
+
+## prepare-package
+
+The library uses `prepare-package` for ES5 transpilation:
+
+```json
+{
+  "preparePackage": {
+    "input": "./src",
+    "output": "./dist"
+  }
+}
+```
+
+**Commands**:
+- `npm run prepare` — Build once
+- `npm start` — Watch mode
+- `npm test` — Run Mocha tests
+
+## Package Exports
+
+```json
+{
+  "main": "dist/index.js",
+  "module": "src/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./modules/*": "./dist/modules/*"
+  }
+}
+```

package/docs/cdp-debugging.md

@@ -0,0 +1,29 @@
+# CDP Debugging (driving a live browser)
+
+How to drive a browser you can CONTROL — see a consuming site live, screenshot it, click, type, read console logs, inspect network requests — for agents (Claude via MCP/CDP) and humans. @omega.js/client has no dev server of its own; it runs INSIDE consumers (@omega.js/web sites, @omega.js/extension extensions, @omega.js/desktop renderers), so browser verification means driving a consumer.
+
+> Mirrored across the five sister frameworks (UJM / @omega.js/backend / @omega.js/extension / @omega.js/desktop / @omega.js/client) — same core section, framework-flavored. Edit all five together.
+
+## The browser: your Claude session owns one
+
+Browser work runs through the **`chrome-devtools` MCP** (via mcp-router). There is NO launch procedure anymore — no ports, no profile dirs, no curl checks:
+
+- **Just call the tools** — `new_page`, `navigate_page`, `take_screenshot`, `click`, `fill`, `evaluate_script`, `list_console_messages`, `list_network_requests`. The browser auto-launches on the first call.
+- **Each Claude session gets its OWN private Chrome** (`--isolated`): temp profile, CDP over an internal pipe. Parallel sessions cannot see or touch each other's pages — open and close pages freely, the whole browser is yours.
+- **It dies with the session.** No orphans, no cleanup, nothing to kill.
+- **Ephemeral profile** — cookies/logins do NOT persist between sessions. If a flow needs auth, log in during the task.
+- **Self-signed HTTPS is pre-accepted** (`--acceptInsecureCerts` in the upstream) — dev servers load without certificate interstitials.
+- **NEVER quit/kill Chrome by app name** (`killall "Google Chrome"`, osascript) — that's the user's personal browser, not yours.
+
+Humans: the agent's Chrome window is visible — you can watch it drive. Full reference: `~/.claude/mcp-server/servers/chrome-devtools/CLAUDE.md`.
+
+## Electron apps are the exception (attach, don't launch)
+
+An Electron dev app is a running singleton — you ATTACH to it instead of launching a browser: the `chrome-devtools-electron` MCP upstream (reads `OMEGA_CDP_PORT`, default 9222, expanded once at session start) or @omega.js/desktop's per-invocation `npx omega cdp`. See @omega.js/desktop's `docs/cdp-debugging.md`.
+
+## @omega.js/client specifics
+
+- **Verify @omega.js/client behavior through a consumer.** The usual host is a UJM site's dev server: **`https://localhost:4000` — NEVER the LAN IP** (`https://192.168.x.x:...`); port 4000 by default, increments (4001, …) when multiple sites run — exact port in the WEBSITE project's `.temp/_config_browsersync.yml`. To test uncommitted @omega.js/client changes, link the local @omega.js/client into the consumer first (see the consumer framework's dev-install flow), then drive the site.
+- What to exercise from the browser: auth flows (`omega.auth()` states, the Settler Pattern), `data-omega-bind` bindings reacting to state changes (`evaluate_script` to mutate state, `take_snapshot`/`take_screenshot` to verify DOM), Firestore reads/writes on the network tab, and console cleanliness (@omega.js/client logs its module lifecycle).
+- Ephemeral profile ⇒ auth'd testing means logging in through the consumer's real UI at the start of the session (test creds).
+- @omega.js/client inside a @omega.js/extension extension or @omega.js/desktop renderer: drive those through their own surfaces — @omega.js/extension's `chrome-devtools-extension` upstream, @omega.js/desktop's `chrome-devtools-electron`/`mgr cdp` (see those repos' `docs/cdp-debugging.md`).

package/docs/code-patterns.md

@@ -0,0 +1,96 @@
+# Key Patterns
+
+## 1. Early Return (Short-Circuit)
+
+Always use early returns instead of nested conditionals:
+
+```javascript
+// CORRECT
+function doSomething() {
+  if (!condition) {
+    return;
+  }
+  // Long code block...
+}
+
+// WRONG
+function doSomething() {
+  if (condition) {
+    // Long code block...
+  }
+}
+```
+
+## 2. DOM Element Naming
+
+Prefix DOM element variables with `$`:
+
+```javascript
+const $button = document.querySelector('.submit-btn');
+const $input = document.getElementById('email');
+```
+
+## 3. Logical Operator Formatting
+
+Place operators at the START of continuation lines:
+
+```javascript
+// CORRECT
+const result = conditionA
+  || conditionB
+  || conditionC;
+
+// WRONG
+const result = conditionA ||
+  conditionB ||
+  conditionC;
+```
+
+## 4. Firestore Path Syntax
+
+Prefer path syntax over collection/doc chaining:
+
+```javascript
+// PREFERRED
+db.doc('users/userId')
+
+// ALSO SUPPORTED
+db.doc('users', 'userId')
+```
+
+## 5. Dynamic Imports
+
+Firebase modules are dynamically imported to reduce bundle size:
+
+```javascript
+const { initializeApp } = await import('firebase/app');
+const { getAuth } = await import('firebase/auth');
+```
+
+## 6. Configuration Deep Merge
+
+User config is deep-merged with defaults in `_processConfiguration()`. Only override what you need:
+
+```javascript
+// Defaults defined in _processConfiguration()
+const defaults = {
+  environment: 'production',
+  firebase: { app: { enabled: true, config: {} } },
+  // ...
+};
+```
+
+## 7. Click Triggers
+
+Click-driven UI never hand-rolls a listener: it registers on the shared trigger
+registry (`modules/triggers.js`), which owns the ONE delegated `document` click
+listener. The class is always `omega-<name>` — callers never spell it:
+
+```javascript
+import { registerTrigger } from '@omega.js/client/modules/triggers.js';
+
+// A click on `.omega-signout` (or anything inside one) runs this
+registerTrigger('signout', async (event, element) => {
+  // Handle signout
+});
+```

package/docs/common-tasks.md

@@ -0,0 +1,36 @@
+# Common Tasks
+
+## Adding a New Utility Function
+
+1. Add function to `src/modules/utilities.js`
+2. Export it: `export function myFunction() { ... }`
+3. Update README.md with documentation
+4. Run `npm run prepare` to build
+
+## Adding a New Module
+
+1. Create `src/modules/my-module.js`
+2. Export class: `export default class MyModule { constructor(manager) { ... } }`
+3. Import in `src/index.js`: `import MyModule from './modules/my-module.js'`
+4. Add to Manager constructor: `this._myModule = new MyModule(this)`
+5. Add getter: `myModule() { return this._myModule; }`
+6. Update README.md
+7. Run `npm run prepare`
+
+## Modifying Configuration Defaults
+
+1. Edit `_processConfiguration()` in `src/index.js`
+2. Add to `defaults` object (e.g., `payment: { providers: {}, products: [] }`)
+3. Document in README.md Configuration section
+
+## Payment Configuration
+
+Payment config shape mirrors OMEGA (the SSOT) — same key names used in @omega.js/backend, UJM, and @omega.js/desktop:
+- `providers`: Stripe, PayPal, Chargebee, Coinbase (publishable keys / client IDs)
+- `products`: Array of `{ id, name, type, limits: { feature: N }, prices, trial, paypal, stripe, chargebee }` — used to resolve usage limits on the frontend AND drive checkout flows
+
+## Adding a Data Binding Action
+
+1. Edit `_executeAction()` in `src/modules/bindings.js`
+2. Add case for new action (e.g., `@class`)
+3. Document in README.md Data Binding section

package/docs/dependencies.md

@@ -0,0 +1,19 @@
+# Dependencies & Important Notes
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `firebase` (^12.x) | Auth, Firestore, Messaging |
+| `@sentry/browser` (^10.x) | Error tracking |
+| `lodash` (^4.x) | get/set for path-based access |
+| `itwcw-package-analytics` | Analytics (internal) |
+
+## Important Notes
+
+1. **DO NOT MODIFY `_legacy/`** — Reference only for historical context
+2. **Backwards compatibility is NOT required** — Just change to the new way
+3. **Prefer `fs-jetpack`** over `fs` for any file operations in tests/scripts
+4. **No TypeScript** — This is a pure JavaScript library
+5. **Template strings** — Use backticks for string interpolation
+6. **Modular design** — Keep modules focused and small

package/docs/index.md

@@ -0,0 +1,159 @@
+# OMEGA Client (@omega.js/client)
+
+> **Note for contributors and Claude:** This file is the guide for `@omega.js/client` — identity, top-level conventions, and a map to the deep references. It lives in the monorepo's `docs/` tree and is loaded on demand (the omega Claude plugin's hooks inject it by context; the repo-root AGENTS.md map is the one agent entry — packages carry no agent docs). The **meat** (module APIs, patterns, behavior tables) lives in the package's own [`docs/<topic>.md`](../docs) files. When extending or adding content, write it in the matching `docs/*.md` file and cross-link from here — do NOT inline it. If a topic doesn't have a doc yet, create one.
+
+## Identity
+
+OMEGA Client is a modern JavaScript utility library for web applications with Firebase integration. It runs in the browser, in Electron's renderer process, and inside browser extensions (content scripts, popups, background pages). Provides:
+
+- A singleton `Manager` instance exposing authentication, reactive DOM data binding, Firestore, storage, push notifications, error tracking (Sentry), service-worker helpers, DOM/utility functions, and `omega.request()` — the harmonized API-fetch layer (fresh Bearer token, automatic `omega-properties` processing with server usage synced into bindings)
+- Lazy Firebase imports to keep consumer bundles small
+- Reactive `data-omega-bind` DOM directives wired to auth + usage state
+- A `resolveSubscription()` helper unified with @omega.js/backend's `User.resolveSubscription()` so subscription-state logic is identical across frontend and backend
+
+### Consumed by the frontend Manager family
+
+OMEGA Client is the runtime singleton powering **@omega.js/web**, **@omega.js/extension**, and **@omega.js/desktop**. Each framework initializes the singleton once and exposes it as `manager.omega`. Any consumer of those frameworks gets a fully-wired @omega.js/client via `import omega from '@omega.js/client'`.
+
+## Recommended skills
+
+- **`omega:client`** — the router skill from the omega Claude plugin. The inject hook loads it automatically when the session works inside `packages/client` (own-name match only — a dependency on the runtime says nothing about the session); it points back to this guide + `docs/` (the SSOT).
+- **`js:patterns`** — JavaScript/Node.js conventions: file structure, JSDoc, defensive coding (`?.` usage), template literals, `package.json` conventions. Auto-loads when creating new `.js` files or touching JS module structure.
+
+## Quick Start
+
+### For Consuming Projects
+
+OMEGA Client is consumed indirectly through @omega.js/web, @omega.js/extension, or @omega.js/desktop — those frameworks initialize the singleton for you. Inside any consuming code:
+
+```javascript
+import omega from '@omega.js/client';
+
+omega.auth().listen({ once: true }, async () => { /* auth settled */ });
+omega.utilities().escapeHTML(untrustedText);
+omega.firestore().doc('users/abc').get();
+```
+
+### For Framework Development (This Repository)
+
+1. `npm install` — install OMEGA Client's own deps
+2. `npm run prepare` — build once: copies `src/` → `dist/` via prepare-package (ES5 transpile)
+3. `npm start` — watch mode (rebuild on change)
+4. `npm test` — run Mocha tests
+
+> **Important:** OMEGA Client is a library, not an app. There is no `npm run build` / `npm run serve` here. Consume it from inside an @omega.js/web / @omega.js/extension / @omega.js/desktop project for end-to-end behavior.
+
+## Architecture
+
+OMEGA Client exports a singleton `Manager` instance from `src/index.js`. Every `import omega from '@omega.js/client'` returns the same already-initialized object — do NOT call `new Manager()`, and do NOT pass `omega` through function params or module-level variables.
+
+The singleton owns thirteen feature modules under `src/modules/`: `storage`, `auth`, `bindings`, `firestore`, `notifications`, `service-worker`, `sentry`, `dom`, `utilities` (the untrusted-text surface — `escapeHTML`, `sanitizeURL`, and the escape-first `renderMarkdown` that composes them, plus clipboard/notification/platform helpers), `device` (local install/session stats — binds the `device` key), `request` (harmonized API fetch — `omega.request()`; also consumed standalone by desktop main + the extension service worker via `createRequest`), `verts` (the fallback-ladder ad engine, adblock-safe naming — AdSense provider lane + in-house/company units, shared by web/desktop/extension), and `analytics` (runtime event tracking on every runtime, built on the shared `@omega.js/analytics` core — the one home of GA4 event-name and Measurement Protocol semantics; the extension posts through the Measurement Protocol, web hands the event to the page's own `gtag` so the api_secret never reaches a page, and desktop's renderer forwards over the preload's IPC bridge so the main process is the one sender ([#411](https://github.com/Omega-JS-Stack/omega/issues/411))). Firebase modules are dynamically imported to keep the bundle small. Alongside them live the transport-free standalone modules (`icon-core`, `icon-renderer`, `motion`, `live-page`, `vert-document` — the ONE vert unit document renderer, consumed by the verts module's promo lane and by `@omega.js/backend`'s serve route ([docs/web/ads-system.md](../web/ads-system.md)), `triggers` — the click-trigger registry below, `form-manager` — lightweight form state: initializing → ready ⇄ submitting) that embedding frameworks import by subpath and boot themselves — `motion` is the shared animation engine behind the `data-omega-*` attributes (classy v2), and `live-page` is the self-refreshing-page kit (`swap` writes a section only when its markup changed, `loading` is the first-paint spinner, `createFeedPoller` owns the declared feed table with its in-flight count and keep-last-good-on-failure rule, taking an `omega.request`-shaped fetcher as an argument). See [docs/architecture.md](../docs/architecture.md) for the directory structure and module dependency graph, and [docs/modules.md](../docs/modules.md) for the API reference of each module.
+
+Pages built on this runtime follow the **page paint contract** ([docs/web/page-contract.md](../web/page-contract.md)): the client fills the `auth`, `usage`, `config` and `device` binding roots at auth settle so page code never hides its DOM waiting for a user, `bindings.update()` filters by root key so a spot that must wait for a server answer lives under a root the early paint does not publish, and `FormManager`'s `addGate()` / `resolveGate()` hold a form's submit controls disabled until every async answer it depends on has landed.
+
+### The wakeup ping (`omega.request(url, { wakeup: true })`)
+
+A fire-and-forget GET that warms a cold backend and nothing else. @omega.js/backend's middleware sees `wakeup` in the request data and answers it BEFORE it loads a route or authenticates ([docs/backend/index.md](../backend/index.md)), so any route warms the same function at the same cost and none of them runs. The call mints no ID token, reads no response body, and resolves rather than throwing when the network is down, so a caller can fire it and move on:
+
+```javascript
+import { WAKEUP_ROUTE } from '@omega.js/client/modules/request.js';
+
+omega.request(WAKEUP_ROUTE, { wakeup: true });
+```
+
+**One route, every surface.** `WAKEUP_ROUTE` (`/omega/health`) is exported by `modules/request.js` and named by every caller instead of "the route I am about to need": a wakeup never runs a route, so a per-caller route would be a dozen spellings of one warm function — and desktop main and the extension cannot reach a web-side constant anyway ([#644](https://github.com/Omega-JS-Stack/omega/issues/644)).
+
+**Where it fires.** Every entry point whose first user action is a backend call warms it on load, never awaited:
+
+| Surface | Site | The call it is warming for |
+|---|---|---|
+| @omega.js/web | `/pricing` | the checkout the plan buttons lead to |
+| @omega.js/web | `/payment/checkout` | `/omega/payments/intent` |
+| @omega.js/web | `/signup` | `/omega/user/signup` — the 14-second cold start measured live 2026-08-27 |
+| @omega.js/web | `/signin` | `/omega/user/signup` behind a first-time OAuth signin |
+| @omega.js/web | `/account` | the billing portal, plan switch, cancel, refund, API key, data request, delete |
+| @omega.js/web | `/token` | `/omega/user/token` (also where a desktop app and an extension sign in) |
+| @omega.js/web | `/connections/callback` | `/omega/user/connections` |
+| @omega.js/web | `/feedback` | `/omega/user/feedback` |
+| @omega.js/web | `/portal/email-preferences` | `/omega/marketing/email-preferences` |
+| @omega.js/web | `/download`, only where the notify-me form renders | `/omega/general/email` |
+| @omega.js/web | the `newsletter-cta` band — on first FOCUS, not on load | `/omega/marketing/contact` |
+| @omega.js/desktop | the renderer's auth bridge (`_wireAuthBridge`) | `/omega/user/token`, via main's sync-request |
+| @omega.js/extension | every surface's `syncWithBackground()` | `/omega/user/token`, via background's sync |
+
+The newsletter band is the one that waits for an interaction: it rides most pages, so a load-time ping would warm a function for every passive visitor scrolling past. A focus is the intent.
+
+Deliberately NOT pinging: the payment confirmation page (its check is a Firestore read, not a backend call), the contact form (it posts to Slapform, a third party), and the admin dashboard (internal tooling, whose seven load-time fetches are their own warm-up).
+
+### The session probe (`omega.auth().probeSession()`)
+
+One forced token refresh at a moment of doubt, and nothing else ([#798](https://github.com/Omega-JS-Stack/omega/issues/798)). Firebase asks the Auth server about a persisted session at page load and at the hourly refresh and at no other moment, so a revoked, disabled or deleted account keeps an open tab signed in until a reload, and a dev stack whose auth emulator restarted leaves the page holding a session the server no longer has. The probe never asks OUR backend, so dev and production run the same code.
+
+`probeSession()` exchanges the refresh token with the Auth server (`getIdToken(user, true)`) and classifies the answer:
+
+| Result | When | What the client does |
+|---|---|---|
+| `signed-out` | no `currentUser` | nothing; a probe on a signed-out client is a no-op |
+| `alive` | the refresh succeeded | nothing |
+| `gone` | a DEFINITE `auth/*` verdict, meaning any `auth/*` code that is not one of the three transient ones below (`auth/user-token-expired`, `auth/user-disabled`, `auth/user-not-found`, `auth/invalid-refresh-token`, …) | `signOut()`, whose `onAuthStateChanged` emission drives each surface's own policy listener |
+| `unknown` | the three TRANSIENT codes (`auth/network-request-failed`, `auth/too-many-requests`, `auth/internal-error`), or an error carrying no auth code | keeps the user: a bad connection, a throttle and a failing Auth server are no verdict on the session, and neither is the "Backend starting" window |
+
+**Three moments, no timer.** The tab coming back into view (`visibilitychange` to visible) and the network coming back (`online`) are wired once per manager instance beside the auth state listener, guarded for a host with no `document` (the extension's background service worker). The third is a 401 on an authenticated `omega.request()`: the request layer calls its optional `onUnauthorized` dep WITHOUT awaiting it and throws the caller's error unchanged, so nothing waits on a token refresh and a failed probe is never the request's failure. Probes coalesce, one in flight per Auth instance, because focus, online and a 401 arrive together all the time and are all asking the same question. A periodic ping would be a request per open tab for nothing; page load and the hourly refresh stay Firebase's own.
+
+Web, desktop and extension get every bit of this from the client, with no framework code of their own. Web's page auth policy is what redirects on the resulting signed-out state ([docs/web/page-contract.md](../web/page-contract.md)).
+
+### Click triggers (`modules/triggers.js`)
+
+The ONE click-trigger registry every surface shares ([#16](https://github.com/Omega-JS-Stack/omega/issues/16)). A trigger is markup wiring — a class means "clicking this runs that action", with no per-page JS — and the client owns the single delegated `document` click listener behind all of them.
+
+```javascript
+import { registerTrigger } from '@omega.js/client/modules/triggers.js';
+
+registerTrigger('signout', async (event, element) => { /* ... */ });
+```
+
+- **The class is always `omega-<name>`** — `registerTrigger('signout', …)` answers `.omega-signout`. Callers never spell the class, so the naming can never drift (this replaced three conventions: `.auth-signout-btn`, `.auth-signin-btn`, `.uj-password-toggle`, with no aliases kept).
+- **A click anywhere inside a trigger element counts** (`closest()`), which is what makes icon-only and label-wrapped buttons work. The INNERMOST trigger wins when triggers nest.
+- **A trigger class means the framework owns the click**: the registry calls `preventDefault()` + `stopPropagation()` before the handler, so no default navigation and no page-level handler fires behind it.
+- **Registration arms the listener**, so a surface may register before or after `omega.initialize()` — order never matters. Re-registering a name REPLACES the handler with a warning; it never stacks, so a double boot cannot double-fire.
+- **Who registers what**: the client registers the GENERIC actions (`omega-signout` — confirm, sign out, notify — from `auth.setupEventListeners()`), and each surface registers its own. Today: @omega.js/extension registers `omega-signin` (opens the website's `/token` page in a tab) and `omega-account` (opens the website's `/account` page in a tab) from `setupAuthEventListeners()`; @omega.js/web registers `omega-password-toggle` (the password eye) from its global module.
+- Transport-free and DOM-only like `motion` / `icon-renderer`: inert where there is no document (desktop main, the extension service worker).
+
+Web's `data-shell-toggle` / `data-shell-dismiss` are NOT triggers — they are @omega.js/web's attribute-driven app-shell contract and stay there.
+
+## File Conventions
+
+- **CommonJS-friendly ES6+** in `src/`. `prepare-package` transpiles to ES5 in `dist/`.
+- **`fs-jetpack`** over `fs` / `fs-extra` for any file operations in tests/scripts.
+- **No TypeScript** — pure JavaScript library.
+- **Template strings** — use backticks for string interpolation.
+- **DO NOT modify `_legacy/`** — reference only, frozen for historical context.
+- **No backwards compatibility** unless explicitly requested — just change to the new way.
+- **Early-return / short-circuit** style throughout — see [docs/code-patterns.md](../docs/code-patterns.md) for the full code-pattern checklist (`$`-prefixed DOM vars, operators at start of continuation lines, Firestore path syntax, dynamic imports, config deep-merge, event delegation).
+
+## Doc-update parity
+
+Whenever you make a behavioral change (new module, new method, new pattern, removed feature), update:
+
+1. **`README.md`** — user-facing summary
+2. **`docs/client/index.md`** (this file) — architecture overview, one paragraph or cross-link
+3. **`docs/<topic>.md`** — the meat. If a topic doesn't have a doc yet, create one.
+4. **`CHANGELOG.md`** — if the project keeps one
+
+Don't ship behavioral changes with stale docs. Validate first, then document — write docs that describe shipped reality, not intentions.
+
+**The four framework guides are structurally MIRRORED** — this guide follows the library subset of that skeleton (the scaffolding frameworks [web](../web/index.md), [backend](../backend/index.md), [desktop](../desktop/index.md), and [extension](../extension/index.md) carry the full skeleton + a consumer template). Never add, rename, or reorder a section here without checking the sibling guides.
+
+## Documentation
+
+Deep references live in `docs/`. Treat docs as a first-class deliverable. **Whenever you make a behavioral change, update both this overview AND the relevant `docs/*.md` deep reference.**
+
+- [docs/architecture.md](../docs/architecture.md) — singleton pattern, directory structure, module dependency graph
+- [docs/code-patterns.md](../docs/code-patterns.md) — early returns, `$`-prefixed DOM vars, logical operator placement, Firestore path syntax, dynamic imports, config deep-merge, event delegation
+- [docs/modules.md](../docs/modules.md) — full module quick reference (Storage, Auth + `resolveSubscription` + Settler Pattern, Bindings, Firestore, Notifications, ServiceWorker, Sentry, DOM, Utilities)
+- [docs/bindings.md](../docs/bindings.md) — `data-omega-bind` deep reference: actions, comma syntax, condition operators, state paths, skeleton loaders, root-key update filtering
+- [docs/build-system.md](../docs/build-system.md) — `prepare-package` ES5 transpile, build commands, package exports
+- [docs/testing.md](../docs/testing.md) — Mocha test setup
+- [docs/cdp-debugging.md](../docs/cdp-debugging.md) — driving a live browser (per-session isolated Chrome via the `chrome-devtools` MCP) to verify @omega.js/client inside a consuming site
+- [docs/common-tasks.md](../docs/common-tasks.md) — adding a utility, adding a module, modifying config defaults, payment config (OMEGA SSOT shape), adding a binding action
+- [docs/dependencies.md](../docs/dependencies.md) — dependencies table + important notes (no TypeScript, prefer fs-jetpack, no backwards-compat requirement, etc.)