web-manager 4.1.42 → 4.3.0

package/CHANGELOG.md

@@ -14,6 +14,18 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - `Fixed` for any bug fixes.
 - `Security` in case of vulnerabilities.
 
+---
+## [4.2.0] - 2026-05-21
+### Added
+- **Consent defaults in `DEFAULT_ACCOUNT`.** Phase A companion to `backend-manager` v5.2.0's marketing-consent system. `src/modules/auth.js` now defaults `account.consent.{legal,marketing}` to the canonical shape (`status: 'revoked'`, `grantedAt`/`revokedAt` with null leaves) so `resolveAccount()` always populates the field for legacy users whose Firestore doc predates the consent system. Without this, the account-page email-preferences toggle would read `undefined` for pre-migration users and mis-state.
+- **`docs/<topic>.md` deep references.** New `docs/architecture.md`, `docs/build-system.md`, `docs/code-patterns.md`, `docs/common-tasks.md`, `docs/dependencies.md`, `docs/modules.md`, `docs/testing.md`. Mirrors the architectural-overview-plus-deep-references pattern used in `backend-manager` and `electron-manager`.
+
+### Changed
+- **`CLAUDE.md` refactored to the architectural-overview pattern.** Trimmed from 301 lines to ~80; per-subsystem detail moved to the new `docs/*.md` files. Keeps Claude's loaded-context cost down on every conversation.
+
+### Fixed
+- **Toast notification width.** `src/modules/utilities.js`: notifications now have `width: calc(100% - 2rem); max-width: 500px` so longer text doesn't render as a narrow cramped strip at the top of the page.
+
 ---
 ## [4.1.42] - 2026-05-11
 ### Changed

package/CLAUDE.md

@@ -1,301 +1,82 @@
-# Web Manager - AI Agent Guide
+# Web Manager
 
-This document helps AI agents understand the web-manager codebase for effective contributions.
+> **Note for contributors and Claude:** This file is the architectural overview — identity, top-level conventions, and a map to deep references. The **meat** (module APIs, patterns, behavior tables) lives in `docs/<topic>.md`. 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. Goal: keep this file under 250 lines.
 
-## Project Overview
+## Identity
 
-**Purpose**: Modern JavaScript utility library for web applications with Firebase integration. Provides authentication, data binding, storage, push notifications, error tracking, and more.
+Web Manager 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:
 
-**Target Environments**:
-- Web (primary, webpack-optimized)
-- Electron (renderer process)
-- Chrome/Firefox Extensions (content scripts, popups)
+- A singleton `Manager` instance exposing authentication, reactive DOM data binding, Firestore, storage, push notifications, error tracking (Sentry), service-worker helpers, and DOM/utility functions
+- Lazy Firebase imports to keep consumer bundles small
+- Reactive `data-wm-bind` DOM directives wired to auth + usage state
+- A `resolveSubscription()` helper unified with backend-manager's `User.resolveSubscription()` so subscription-state logic is identical across frontend and backend
 
-**Version**: 4.0.x | **Node**: >=12 | **License**: CC-BY-4.0
+### Consumed by the frontend Manager family
 
-## Architecture
-
-### Singleton Pattern
-The library exports a singleton `Manager` instance. Import it directly from any file — it's always the same initialized instance:
-```javascript
-import webManager from 'web-manager';
-
-// Same instance everywhere — config, auth, firestore, all ready
-webManager.auth().listen((state) => { ... });
-webManager.utilities().escapeHTML(untrustedText);
-webManager.config.environment; // 'development' or 'production'
-```
-**Do NOT create new instances** (`new Manager()`). UJM and BXM initialize the singleton — every import gets that same object. Do NOT pass `webManager` through function params or store it in module-level variables — just import it.
-
-### Directory Structure
-```
-web-manager/
-├── src/                       # Source code (ES6+)
-│   ├── index.js               # Manager class, initialization, Firebase setup
-│   └── modules/               # Feature modules
-│       ├── auth.js            # Firebase Auth wrapper
-│       ├── bindings.js        # Reactive DOM data binding
-│       ├── dom.js             # loadScript, ready utilities
-│       ├── firestore.js       # Firestore wrapper with chainable queries
-│       ├── notifications.js   # FCM push notifications
-│       ├── sentry.js          # Error tracking integration
-│       ├── service-worker.js  # SW registration and messaging
-│       ├── storage.js         # localStorage/sessionStorage wrapper
-│       └── utilities.js       # Helper functions (clipboard, escape, etc.)
-├── dist/                      # Transpiled ES5 output (generated)
-├── _legacy/                   # Old implementation (reference only, DO NOT MODIFY)
-└── test/                      # Mocha tests
-```
-
-### Module Dependencies
-```
-Manager (index.js)
-├── Storage (standalone, no deps)
-├── Auth → Manager, Bindings, Storage, Firestore
-├── Bindings → Manager
-├── Firestore → Manager (lazy Firebase import)
-├── Notifications → Manager, Storage, Firestore
-├── ServiceWorker → Manager
-├── Sentry → Manager (dynamic import)
-├── DOM utilities (standalone)
-└── Utilities (standalone)
-```
-
-## Key Patterns
+Web Manager is the runtime singleton powering **Ultimate Jekyll Manager (UJM)**, **Browser Extension Manager (BXM)**, and **Electron Manager (EM)**. Each framework initializes the singleton once and exposes it as `manager.webManager`. Any consumer of those frameworks gets a fully-wired web-manager via `import webManager from 'web-manager'`.
 
-### 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;
+## Recommended skills
 
-// WRONG
-const result = conditionA ||
-  conditionB ||
-  conditionC;
-```
+- **`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.
 
-### 4. Firestore Path Syntax
-Prefer path syntax over collection/doc chaining:
-```javascript
-// PREFERRED
-db.doc('users/userId')
+## Quick Start
 
-// ALSO SUPPORTED
-db.doc('users', 'userId')
-```
+### For Consuming Projects
 
-### 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');
-```
+Web Manager is consumed indirectly through UJM, BXM, or EM — those frameworks initialize the singleton for you. Inside any consuming code:
 
-### 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. Event Delegation
-Auth UI uses event delegation on document body:
-```javascript
-document.body.addEventListener('click', (e) => {
-  if (e.target.closest('.auth-signout-btn')) {
-    // Handle signout
-  }
-});
-```
-
-## Module Quick Reference
-
-### Storage (`storage.js`)
-- **Class**: `Storage`
-- **Key Methods**: `get(path, default)`, `set(path, value)`, `remove(path)`, `clear()`
-- **Session**: Same methods under `.session` namespace
-- **Storage Key**: `_manager` in localStorage
-
-### Auth (`auth.js`)
-- **Class**: `Auth`
-- **Key Methods**: `listen(options, callback)`, `isAuthenticated()`, `getUser()`, `signInWithEmailAndPassword()`, `signOut()`, `getIdToken()`, `resolveSubscription(account?)`
-- **Bindings**: Updates `auth` and `usage` context on auth settle
-- **Usage Resolution**: `_resolveUsage(state)` merges `account.usage` (Firestore) with product limits from `config.payment.products` (OMEGA-canonical shape — same key name in BEM, UJM, and EM) to produce the `usage` bindings key (e.g., `{ credits: { monthly: 5, limit: 100 } }`)
-
-#### resolveSubscription(account?)
-Derives calculated subscription fields from raw account data. Returns only fields that require derivation logic — raw data (product.id, status, trial, cancellation) lives on `account.subscription` directly.
-
-```javascript
-const resolved = auth.resolveSubscription(account);
-// Returns: { plan, active, trialing, cancelling }
-```
-- `plan`: Effective plan ID the user has access to RIGHT NOW (`'basic'` if cancelled/suspended)
-- `active`: User has active access (active, trialing, or cancelling — all mean the user can use the product)
-- `trialing`: In an active trial (status `'active'` + `trial.claimed` + unexpired `trial.expires`)
-- `cancelling`: Cancellation pending (status `'active'` + `cancellation.pending` + NOT trialing)
-
-**Unified with BEM**: The same function exists on `User.resolveSubscription(account)` in backend-manager (`helpers/user.js`) with identical logic and return shape.
-
-#### Auth Settler Pattern
-Auth uses a promise-based settler (`_authReady`) that resolves once Firebase's first `onAuthStateChanged` fires — the moment auth state is guaranteed (authenticated user OR null). This eliminates race conditions.
-
-- **`once` listeners** (`listen({ once: true }, cb)`): Wait for `_authReady`, fire once, done. No cleanup needed.
-- **Persistent listeners** (`listen({}, cb)`): Subscribe to `_authStateCallbacks`. If auth already settled when registered, catch up via `_authReady.then()`. Otherwise, `_handleAuthStateChange` handles the initial call naturally.
-- **`_hasProcessedStateChange`**: Ensures bindings/storage updates run only once per auth state change across all listeners.
-- **Manager owns the promise**: `_authReady` and `_authReadyResolve` live on the Manager instance. The `onAuthStateChanged` callback in `index.js` resolves it on first fire and sets `_firebaseAuthInitialized = true`.
-
-### Bindings (`bindings.js`)
-- **Class**: `Bindings`
-- **Key Methods**: `update(data)`, `getContext()`, `clear()`
-- **HTML Attr**: `data-wm-bind`
-- **Actions**: `@text`, `@value`, `@show`, `@hide`, `@attr`, `@style`
-
-### Firestore (`firestore.js`)
-- **Class**: `Firestore`
-- **Key Methods**: `doc(path)`, `collection(path)`
-- **Doc Methods**: `.get()`, `.set()`, `.update()`, `.delete()`
-- **Query Methods**: `.where()`, `.orderBy()`, `.limit()`, `.startAt()`, `.endAt()`
-
-### Notifications (`notifications.js`)
-- **Class**: `Notifications`
-- **Key Methods**: `isSupported()`, `isSubscribed()`, `subscribe()`, `unsubscribe()`, `getToken()`, `onMessage()`
-- **Storage**: Saves to localStorage and Firestore
-
-### ServiceWorker (`service-worker.js`)
-- **Class**: `ServiceWorker`
-- **Key Methods**: `isSupported()`, `register()`, `ready()`, `postMessage()`, `onMessage()`, `getState()`
-
-### Sentry (`sentry.js`)
-- **Class**: `Sentry` (named `mod` internally)
-- **Key Methods**: `init(config)`, `captureException(error, context)`
-- **Filtering**: Blocks dev mode, Lighthouse, Selenium/Puppeteer
-
-### DOM (`dom.js`)
-- **Exports**: `loadScript(options)`, `ready()`
-- **loadScript Options**: src, async, defer, crossorigin, integrity, timeout, retries
-
-### Utilities (`utilities.js`)
-- **Exports**: `clipboardCopy()`, `escapeHTML()`, `showNotification()`, `getPlatform()`, `getBrowser()`, `getRuntime()`, `isMobile()`, `getDevice()`, `getContext()`
-
-## Build System
-
-### prepare-package
-The library uses `prepare-package` for ES5 transpilation:
+import webManager from 'web-manager';
 
-```json
-{
-  "preparePackage": {
-    "input": "./src",
-    "output": "./dist"
-  }
-}
+webManager.auth().listen({ once: true }, async () => { /* auth settled */ });
+webManager.utilities().escapeHTML(untrustedText);
+webManager.firestore().doc('users/abc').get();
 ```
 
-**Commands**:
-- `npm run prepare` - Build once
-- `npm start` - Watch mode
-- `npm test` - Run Mocha tests
+### For Framework Development (This Repository)
 
-### Package Exports
-```json
-{
-  "main": "dist/index.js",
-  "module": "src/index.js",
-  "exports": {
-    ".": "./dist/index.js",
-    "./modules/*": "./dist/modules/*"
-  }
-}
-```
+1. `npm install` — install Web Manager'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
 
-## Testing
+> **Important:** Web Manager is a library, not an app. There is no `npm run build` / `npm run serve` here. Consume it from inside a UJM / BXM / EM project for end-to-end behavior.
 
-Tests are in `test/test.js` using Mocha:
-```bash
-npm test
-```
+## Architecture
 
-Current test coverage is minimal - focuses on configuration and storage.
+Web Manager exports a singleton `Manager` instance from `src/index.js`. Every `import webManager from 'web-manager'` returns the same already-initialized object — do NOT call `new Manager()`, and do NOT pass `webManager` through function params or module-level variables.
 
-## Common Tasks
+The singleton owns nine feature modules under `src/modules/`: `storage`, `auth`, `bindings`, `firestore`, `notifications`, `service-worker`, `sentry`, `dom`, `utilities`. Firebase modules are dynamically imported to keep the bundle small. 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.
 
-### 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
+## File Conventions
 
-### 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`
+- **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).
 
-### Modifying Configuration Defaults
-1. Edit `_processConfiguration()` in `src/index.js`
-2. Add to `defaults` object (e.g., `payment: { processors: {}, products: [] }`)
-3. Document in README.md Configuration section
+## Doc-update parity
 
-### Payment Configuration
-Payment config shape mirrors OMEGA (the SSOT) — same key names used in BEM, UJM, and EM:
-- `processors`: 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
+Whenever you make a behavioral change (new module, new method, new pattern, removed feature), update:
 
-### 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
+1. **`README.md`** — user-facing summary
+2. **`CLAUDE.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
 
-## Dependencies
+Don't ship behavioral changes with stale docs. Validate first, then document — write docs that describe shipped reality, not intentions.
 
-| 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) |
+## Documentation
 
-## Important Notes
+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.**
 
-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
+- [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/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/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/dist/index.js

@@ -133,9 +133,9 @@ class Manager {
       // Set up auth event listeners (uses event delegation, no need to wait for DOM)
       this._auth.setupEventListeners();
 
-      // Set up push notification auto-request if enabled
-      if (this.config.pushNotifications?.enabled && this.config.pushNotifications?.config?.autoRequest > 0) {
-        this._setupNotificationAutoRequest();
+      // Set up push notifications
+      if (this.config.pushNotifications?.enabled) {
+        this._notifications.initialize(this.config.pushNotifications.config);
       }
 
       // Initialize Chatsy chat widget if enabled
@@ -568,29 +568,6 @@ class Manager {
     }, this.config.refreshNewVersion.config.interval);
   }
 
-  _setupNotificationAutoRequest() {
-    // Quit if document is not available
-    if (typeof document === 'undefined') {
-      return;
-    }
-
-    // Set up click listener to request notification permissions
-    const handleClick = () => {
-      // Remove listener after first click
-      document.removeEventListener('click', handleClick);
-
-      // Set timeout to request notifications
-      setTimeout(() => {
-        console.log('Auto-requesting notification permissions...');
-        this._notifications.subscribe().catch(err => {
-          console.error('Notification subscription failed:', err.message);
-        });
-      }, this.config.pushNotifications.config.autoRequest);
-    };
-
-    // Wait for user click
-    document.addEventListener('click', handleClick);
-  }
 
   // async _loadPolyfillsIfNeeded() {
   //   // Check if polyfills are needed by testing for ES6 features

package/dist/modules/auth.js

@@ -35,6 +35,17 @@ const DEFAULT_ACCOUNT = {
     affiliate: { code: null, timestamp: null, url: null, page: null },
     utm: { tags: {}, timestamp: null, url: null, page: null },
   },
+  consent: {
+    legal: {
+      status: 'revoked',
+      grantedAt: { timestamp: null, timestampUNIX: null, source: null, ip: null, text: null },
+    },
+    marketing: {
+      status: 'revoked',
+      grantedAt: { timestamp: null, timestampUNIX: null, source: null, ip: null, text: null },
+      revokedAt: { timestamp: null, timestampUNIX: null, source: null, ip: null, text: null },
+    },
+  },
 };
 
 function resolveAccount(rawData, firebaseUser) {

package/dist/modules/notifications.js

@@ -4,6 +4,56 @@ class Notifications {
     this._requestInProgress = false;
   }
 
+  initialize(config) {
+    const storage = this.manager.storage();
+    const stored = storage.get('notifications');
+    const permission = typeof Notification !== 'undefined' ? Notification.permission : 'default';
+
+    console.log('[WM:push] Page load check:', { storedSubscribed: stored?.subscribed, storedToken: stored?.token?.slice(-8), permission });
+
+    // If localStorage says subscribed but browser permission disagrees, clear it
+    if (stored?.subscribed && permission !== 'granted') {
+      console.log('[WM:push] Clearing stale subscription — permission is', permission);
+      storage.set('notifications', { subscribed: false, token: null });
+    }
+
+    // Arm auto-request if not currently subscribed (including just-cleared)
+    const autoRequest = config?.autoRequest;
+    if ((!stored?.subscribed || permission !== 'granted') && autoRequest > 0) {
+      console.log('[WM:push] Arming auto-request (delay:', autoRequest + 'ms)');
+      this._setupAutoRequest(autoRequest);
+    }
+
+    // Listen for foreground messages (tab is focused)
+    if (permission === 'granted') {
+      console.log('[WM:push] Setting up foreground listener...', { supported: this.isSupported(), hasMessaging: !!this.manager.firebaseMessaging });
+      this.onMessage((payload) => {
+        console.log('[WM:push] Foreground message received:', payload);
+      }).then(unsub => {
+        console.log('[WM:push] Foreground listener registered:', typeof unsub === 'function' ? 'OK' : 'FAILED (got empty fn)');
+      });
+    }
+  }
+
+  _setupAutoRequest(delay) {
+    if (typeof document === 'undefined') {
+      return;
+    }
+
+    const handleClick = () => {
+      document.removeEventListener('click', handleClick);
+
+      setTimeout(() => {
+        console.log('[WM:push] Auto-requesting notification permissions...');
+        this.subscribe().catch(err => {
+          console.error('[WM:push] Auto-subscription failed:', err.message);
+        });
+      }, delay);
+    };
+
+    document.addEventListener('click', handleClick);
+  }
+
   // Check if notifications are supported
   isSupported() {
     return 'Notification' in window &&
@@ -222,31 +272,54 @@ class Notifications {
     }
   }
 
-  // Sync subscription when auth state changes
+  // Sync subscription when auth state changes or on page load.
+  // Re-fetches the current FCM token — if it changed (browser rotated it,
+  // service worker was re-registered, etc.), saves the new token to Firestore
+  // and updates localStorage. Clears the subscribed state if the token is gone.
   async syncSubscription() {
     try {
-      // Check if we have a stored notification token
       const storage = this.manager.storage();
       const storedNotification = storage.get('notifications');
 
-      if (!storedNotification?.token) {
+      const permission = typeof Notification !== 'undefined' ? Notification.permission : 'default';
+
+      console.log('[WM:push:sync] Starting sync:', { storedSubscribed: storedNotification?.subscribed, storedToken: storedNotification?.token?.slice(-8), permission });
+
+      if (permission !== 'granted') {
+        if (storedNotification?.subscribed) {
+          console.log('[WM:push:sync] Permission not granted — clearing localStorage');
+          storage.set('notifications', { subscribed: false, token: null });
+        } else {
+          console.log('[WM:push:sync] Permission not granted and not subscribed — nothing to do');
+        }
         return false;
       }
 
-      // Update the subscription in Firestore with current auth state
-      await this._saveSubscription(storedNotification.token);
+      // Permission is granted — check if there's a live token (covers localStorage cleared, new browser, etc.)
+      const currentToken = await this.getToken();
+
+      if (!currentToken) {
+        console.log('[WM:push:sync] Token fetch returned null — clearing localStorage');
+        storage.set('notifications', { subscribed: false, token: null });
+        return false;
+      }
+
+      console.log('[WM:push:sync] Token valid:', currentToken.slice(-8), storedNotification?.token ? (storedNotification.token.slice(-8) === currentToken.slice(-8) ? '(unchanged)' : '(CHANGED from ' + storedNotification.token.slice(-8) + ')') : '(recovered — localStorage was empty)');
+
+      await this._saveSubscription(currentToken);
 
-      // Update local storage with current user ID
       const user = this.manager.auth().getUser();
       storage.set('notifications', {
-        ...storedNotification,
+        subscribed: true,
+        token: currentToken,
         uid: user?.uid || null,
-        timestamp: new Date().toISOString()
+        timestamp: new Date().toISOString(),
       });
 
+      console.log('[WM:push:sync] Sync complete — subscribed');
       return true;
     } catch (error) {
-      console.error('Sync subscription error:', error);
+      console.error('[WM:push:sync] Sync error:', error);
       return false;
     }
   }

package/dist/modules/utilities.js

@@ -130,7 +130,7 @@ class Utilities {
 
     const $notification = document.createElement('div');
     $notification.className = `alert alert-${type} alert-dismissible fade show position-fixed`;
-    $notification.style.cssText = 'z-index: 9999; top: 1rem; left: 50%; transform: translateX(-50%);';
+    $notification.style.cssText = 'z-index: 9999; top: 1rem; left: 50%; transform: translateX(-50%); width: calc(100% - 2rem); max-width: 500px;';
 
     const $text = document.createElement('span');
     $text.textContent = text;

package/docs/architecture.md

@@ -0,0 +1,52 @@
+# Architecture
+
+## Singleton Pattern
+
+The library exports a singleton `Manager` instance. Import it directly from any file — it's always the same initialized instance:
+
+```javascript
+import webManager from 'web-manager';
+
+// Same instance everywhere — config, auth, firestore, all ready
+webManager.auth().listen((state) => { ... });
+webManager.utilities().escapeHTML(untrustedText);
+webManager.config.environment; // 'development' or 'production'
+```
+
+**Do NOT create new instances** (`new Manager()`). UJM and BXM initialize the singleton — every import gets that same object. Do NOT pass `webManager` through function params or store it in module-level variables — just import it.
+
+## Directory Structure
+
+```
+web-manager/
+├── src/                       # Source code (ES6+)
+│   ├── index.js               # Manager class, initialization, Firebase setup
+│   └── modules/               # Feature modules
+│       ├── auth.js            # Firebase Auth wrapper
+│       ├── bindings.js        # Reactive DOM data binding
+│       ├── dom.js             # loadScript, ready utilities
+│       ├── firestore.js       # Firestore wrapper with chainable queries
+│       ├── notifications.js   # FCM push notifications
+│       ├── sentry.js          # Error tracking integration
+│       ├── service-worker.js  # SW registration and messaging
+│       ├── storage.js         # localStorage/sessionStorage wrapper
+│       └── utilities.js       # Helper functions (clipboard, escape, etc.)
+├── dist/                      # Transpiled ES5 output (generated)
+├── _legacy/                   # Old implementation (reference only, DO NOT MODIFY)
+└── test/                      # Mocha tests
+```
+
+## Module Dependencies
+
+```
+Manager (index.js)
+├── Storage (standalone, no deps)
+├── Auth → Manager, Bindings, Storage, Firestore
+├── Bindings → Manager
+├── Firestore → Manager (lazy Firebase import)
+├── Notifications → Manager, Storage, Firestore
+├── ServiceWorker → Manager
+├── Sentry → Manager (dynamic import)
+├── DOM utilities (standalone)
+└── Utilities (standalone)
+```

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/code-patterns.md

@@ -0,0 +1,93 @@
+# 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. Event Delegation
+
+Auth UI uses event delegation on document body:
+
+```javascript
+document.body.addEventListener('click', (e) => {
+  if (e.target.closest('.auth-signout-btn')) {
+    // 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: { processors: {}, products: [] }`)
+3. Document in README.md Configuration section
+
+## Payment Configuration
+
+Payment config shape mirrors OMEGA (the SSOT) — same key names used in BEM, UJM, and EM:
+- `processors`: 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/modules.md

@@ -0,0 +1,80 @@
+# Module Quick Reference
+
+## Storage (`storage.js`)
+
+- **Class**: `Storage`
+- **Key Methods**: `get(path, default)`, `set(path, value)`, `remove(path)`, `clear()`
+- **Session**: Same methods under `.session` namespace
+- **Storage Key**: `_manager` in localStorage
+
+## Auth (`auth.js`)
+
+- **Class**: `Auth`
+- **Key Methods**: `listen(options, callback)`, `isAuthenticated()`, `getUser()`, `signInWithEmailAndPassword()`, `signOut()`, `getIdToken()`, `resolveSubscription(account?)`
+- **Bindings**: Updates `auth` and `usage` context on auth settle
+- **Usage Resolution**: `_resolveUsage(state)` merges `account.usage` (Firestore) with product limits from `config.payment.products` (OMEGA-canonical shape — same key name in BEM, UJM, and EM) to produce the `usage` bindings key (e.g., `{ credits: { monthly: 5, limit: 100 } }`)
+
+### resolveSubscription(account?)
+
+Derives calculated subscription fields from raw account data. Returns only fields that require derivation logic — raw data (product.id, status, trial, cancellation) lives on `account.subscription` directly.
+
+```javascript
+const resolved = auth.resolveSubscription(account);
+// Returns: { plan, active, trialing, cancelling }
+```
+
+- `plan`: Effective plan ID the user has access to RIGHT NOW (`'basic'` if cancelled/suspended)
+- `active`: User has active access (active, trialing, or cancelling — all mean the user can use the product)
+- `trialing`: In an active trial (status `'active'` + `trial.claimed` + unexpired `trial.expires`)
+- `cancelling`: Cancellation pending (status `'active'` + `cancellation.pending` + NOT trialing)
+
+**Unified with BEM**: The same function exists on `User.resolveSubscription(account)` in backend-manager (`helpers/user.js`) with identical logic and return shape.
+
+### Auth Settler Pattern
+
+Auth uses a promise-based settler (`_authReady`) that resolves once Firebase's first `onAuthStateChanged` fires — the moment auth state is guaranteed (authenticated user OR null). This eliminates race conditions.
+
+- **`once` listeners** (`listen({ once: true }, cb)`): Wait for `_authReady`, fire once, done. No cleanup needed.
+- **Persistent listeners** (`listen({}, cb)`): Subscribe to `_authStateCallbacks`. If auth already settled when registered, catch up via `_authReady.then()`. Otherwise, `_handleAuthStateChange` handles the initial call naturally.
+- **`_hasProcessedStateChange`**: Ensures bindings/storage updates run only once per auth state change across all listeners.
+- **Manager owns the promise**: `_authReady` and `_authReadyResolve` live on the Manager instance. The `onAuthStateChanged` callback in `index.js` resolves it on first fire and sets `_firebaseAuthInitialized = true`.
+
+## Bindings (`bindings.js`)
+
+- **Class**: `Bindings`
+- **Key Methods**: `update(data)`, `getContext()`, `clear()`
+- **HTML Attr**: `data-wm-bind`
+- **Actions**: `@text`, `@value`, `@show`, `@hide`, `@attr`, `@style`
+
+## Firestore (`firestore.js`)
+
+- **Class**: `Firestore`
+- **Key Methods**: `doc(path)`, `collection(path)`
+- **Doc Methods**: `.get()`, `.set()`, `.update()`, `.delete()`
+- **Query Methods**: `.where()`, `.orderBy()`, `.limit()`, `.startAt()`, `.endAt()`
+
+## Notifications (`notifications.js`)
+
+- **Class**: `Notifications`
+- **Key Methods**: `isSupported()`, `isSubscribed()`, `subscribe()`, `unsubscribe()`, `getToken()`, `onMessage()`
+- **Storage**: Saves to localStorage and Firestore
+
+## ServiceWorker (`service-worker.js`)
+
+- **Class**: `ServiceWorker`
+- **Key Methods**: `isSupported()`, `register()`, `ready()`, `postMessage()`, `onMessage()`, `getState()`
+
+## Sentry (`sentry.js`)
+
+- **Class**: `Sentry` (named `mod` internally)
+- **Key Methods**: `init(config)`, `captureException(error, context)`
+- **Filtering**: Blocks dev mode, Lighthouse, Selenium/Puppeteer
+
+## DOM (`dom.js`)
+
+- **Exports**: `loadScript(options)`, `ready()`
+- **loadScript Options**: src, async, defer, crossorigin, integrity, timeout, retries
+
+## Utilities (`utilities.js`)
+
+- **Exports**: `clipboardCopy()`, `escapeHTML()`, `showNotification()`, `getPlatform()`, `getBrowser()`, `getRuntime()`, `isMobile()`, `getDevice()`, `getContext()`

package/docs/testing.md

@@ -0,0 +1,9 @@
+# Testing
+
+Tests are in `test/test.js` using Mocha:
+
+```bash
+npm test
+```
+
+Current test coverage is minimal — focuses on configuration and storage.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "web-manager",
-  "version": "4.1.42",
+  "version": "4.3.0",
   "description": "Easily access important variables such as the query string, current domain, and current page in a single object.",
   "main": "dist/index.js",
   "module": "src/index.js",
@@ -43,14 +43,14 @@
     "@sentry/browser": "Resolved by using OVERRIDES in web-manager (lighthouse is the issue"
   },
   "dependencies": {
-    "@sentry/browser": "^10.52.0",
+    "@sentry/browser": "^10.54.0",
     "chatsy": "^2.0.14",
     "firebase": "^12.13.0",
     "itwcw-package-analytics": "^1.0.8",
     "lodash": "^4.18.1"
   },
   "devDependencies": {
-    "mocha": "^11.7.5",
+    "mocha": "^11.7.6",
     "prepare-package": "^2.1.0"
   }
 }