web-manager 4.3.1 → 4.3.3

package/CLAUDE.md

@@ -69,6 +69,8 @@ Whenever you make a behavioral change (new module, new method, new pattern, remo
 
 Don't ship behavioral changes with stale docs. Validate first, then document — write docs that describe shipped reality, not intentions.
 
+**The OMEGA docs are structurally MIRRORED.** WM follows the library subset of the canonical OMEGA CLAUDE.md skeleton (the scaffolding frameworks UJM / BEM / BXM / EM / MAM carry the full skeleton + a consumer template). Never add, rename, or reorder a section here without checking the sister repos and the canonical skeletons + omission rules in the `omega:main` skill's `mirror-spec.md` resource.
+
 ## 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.**
@@ -76,7 +78,9 @@ Deep references live in `docs/`. Treat docs as a first-class deliverable. **When
 - [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-wm-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 WM 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.)

package/docs/bindings.md

@@ -0,0 +1,223 @@
+# Bindings (`data-wm-bind`)
+
+The `data-wm-bind` attribute declaratively binds DOM elements to state data (auth, plan, roles, usage, custom state) managed by `webManager.bindings()`. **Always prefer wm-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-wm-bind` in HTML, not `classList.toggle('d-none', ...)` or `.hidden` from JS.
+
+## HTML Syntax
+
+```html
+<element data-wm-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-wm-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-wm-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-wm-bind="@show auth.user">Visible when logged in</div>
+
+<!-- Negation (!) -->
+<div data-wm-bind="@show !auth.user">Visible when NOT logged in</div>
+
+<!-- Comparisons (===, !==, ==, !=, >, <, >=, <=) -->
+<div data-wm-bind="@show auth.account.plan.id === 'premium'">Premium only</div>
+<div data-wm-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-wm-bind="@show !auth.user">
+  <a href="/signup">Create free account</a>
+</div>
+
+<!-- Show for signed-in users -->
+<div data-wm-bind="@show auth.user">
+  <a href="/pricing">Upgrade your plan</a>
+</div>
+
+<!-- Admin-only elements -->
+<div data-wm-bind="@show auth.account.roles.admin">Admin panel</div>
+
+<!-- User data binding -->
+<img data-wm-bind="@show auth.user, @attr src auth.user.photoURL, @attr alt auth.user.displayName">
+<span data-wm-bind="@text auth.user.displayName">Loading...</span>
+<input data-wm-bind="@value auth.user.email">
+```
+
+## Available State Paths
+
+### Auth paths (automatically populated by web-manager)
+
+```
+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 (auto-populated by web-manager + authorized-fetch)
+
+```
+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 `authorizedFetch` call from `bm-properties` response headers.
+
+### Custom state (set via JS)
+
+Any custom paths set via `webManager.bindings().update(stateObject)`.
+
+## JavaScript API
+
+```javascript
+// Update bindings with state data
+webManager.bindings().update({
+  checkout: {
+    product: { name: 'Pro Plan' },
+    error: { show: false, message: '' },
+  },
+});
+
+// Get current binding context
+const context = webManager.bindings().getContext();
+
+// Clear all bindings
+webManager.bindings().clear();
+```
+
+## Skeleton Loaders
+
+### How Skeletons Work
+
+The `wm-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 `wm-bound` class (triggers CSS fade-out transition)
+4. After 300ms, removes `wm-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="wm-binding-skeleton" data-wm-bind="@text auth.user.displayName">&nbsp;</span>
+
+<!-- Skeleton resolves when 'checkout' key is updated (NOT when 'auth' updates) -->
+<span class="wm-binding-skeleton" data-wm-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
+webManager.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
+webManager.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="wm-binding-skeleton" data-wm-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
+webManager.bindings().update({
+  checkout: {
+    totalDueText: `${formatCurrency(prices.total)} due today`,
+  },
+});
+```
+
+```html
+<!-- CORRECT: single binding for composite text -->
+<span class="wm-binding-skeleton" data-wm-bind="@text checkout.totalDueText">&nbsp;</span>
+
+<!-- WRONG: mixing static text with binding inside skeleton -->
+<span class="wm-binding-skeleton">
+  <span data-wm-bind="@text checkout.pricing.total"></span> due today
+</span>
+```
+
+## Implementation Notes
+
+- Uses the `hidden` attribute for show/hide (`[hidden] { display: none !important; }`)
+- Queries `[data-wm-bind]` on each `update()` call — handles dynamic elements
+- Auth bindings are auto-populated when `webManager.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'
+webManager.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/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. WM has no dev server of its own; it runs INSIDE consumers (UJM sites, BXM extensions, EM renderers), so browser verification means driving a consumer.
+
+> Mirrored across the five sister frameworks (UJM / BEM / BXM / EM / WM) — 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 `EM_CDP_PORT`, default 9222, expanded once at session start) or EM's per-invocation `npx mgr cdp`. See EM's `docs/cdp-debugging.md`.
+
+## WM specifics
+
+- **Verify WM 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 WM changes, link the local web-manager into the consumer first (see the consumer framework's dev-install flow), then drive the site.
+- What to exercise from the browser: auth flows (`webManager.auth()` states, the Settler Pattern), `data-wm-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 (WM 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).
+- WM inside a BXM extension or EM renderer: drive those through their own surfaces — BXM's `chrome-devtools-extension` upstream, EM's `chrome-devtools-electron`/`mgr cdp` (see those repos' `docs/cdp-debugging.md`).

package/docs/modules.md

@@ -45,6 +45,7 @@ Auth uses a promise-based settler (`_authReady`) that resolves once Firebase's f
 - **Key Methods**: `update(data)`, `getContext()`, `clear()`
 - **HTML Attr**: `data-wm-bind`
 - **Actions**: `@text`, `@value`, `@show`, `@hide`, `@attr`, `@style`
+- **Deep reference**: [bindings.md](bindings.md) — comma syntax, condition operators, state paths, skeleton loaders, root-key filtering
 
 ## Firestore (`firestore.js`)
 

package/package.json

@@ -1,8 +1,14 @@
 {
   "name": "web-manager",
-  "version": "4.3.1",
+  "version": "4.3.3",
   "description": "Easily access important variables such as the query string, current domain, and current page in a single object.",
   "main": "dist/index.js",
+  "files": [
+    "dist/",
+    "src/",
+    "docs/",
+    "CLAUDE.md"
+  ],
   "module": "src/index.js",
   "exports": {
     ".": "./dist/index.js",
@@ -43,9 +49,9 @@
     "@sentry/browser": "Resolved by using OVERRIDES in web-manager (lighthouse is the issue"
   },
   "dependencies": {
-    "@sentry/browser": "^10.54.0",
+    "@sentry/browser": "^10.57.0",
     "chatsy": "^2.0.14",
-    "firebase": "^12.13.0",
+    "firebase": "^12.14.0",
     "itwcw-package-analytics": "^1.0.8",
     "lodash": "^4.18.1"
   },