@omega.js/web 0.1.0

package/scaffold/.github/workflows/build.yml

@@ -0,0 +1,139 @@
+# Ruby-free CI — @omega.js/web replaces the Jekyll pipeline: no Ruby, no
+# bundler, no Gemfile. Node + `omega build` is the whole toolchain.
+# Regenerated by every verb's ensureTarget — customize via config/omega.json5, not here.
+#
+# Deliberate deploys (D13): commits never auto-publish — save = commit,
+# publish = an explicit dispatch (`omega deploy`, the CMS publish action, or
+# a plain HTTP workflow_dispatch/repository_dispatch call).
+name: Compile and Build Site
+
+on:
+  workflow_dispatch:
+  repository_dispatch:
+    types: [omega-deploy]
+
+concurrency:
+  group: ${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  GH_TOKEN: ${{ secrets.GH_TOKEN }}
+  # The purge step's gate reads this (#715): the `secrets` context is available
+  # in NO `if` expression — one such line and GitHub refuses to parse the whole
+  # file, so an absent secret has to arrive as an empty env value instead.
+  CLOUDFLARE_TOKEN: ${{ secrets.CLOUDFLARE_TOKEN }}
+  NODE_VERSION: '{{ versions.node }}'
+  NODE_ENV: 'production'
+  # Generated from the brand's .env cascade — one line per published Actions
+  # secret. Regenerated by every verb's ensureTarget; edit .env, not this.
+  {{ githubSecrets }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Setup git config
+        run: |
+          git config --global user.email "$GITHUB_ACTOR@users.noreply.github.com"
+          git config --global user.name "$GITHUB_ACTOR"
+
+      # Shallow on purpose (#568): nothing in an omega build reads git HISTORY
+      # — the service worker asks `git rev-parse --short HEAD` (present at
+      # depth 1) and `omega deploy --direct` inits a fresh repo in dist. A
+      # full-history checkout is what took an image-heavy consumer's runner
+      # down with ENOSPC (~4 GB of packed history on a ~14 GB disk).
+      - name: Checkout main branch
+        uses: actions/checkout@v7
+        with:
+          token: ${{ secrets.GH_TOKEN }}
+          fetch-depth: 1
+
+      - name: Setup node
+        uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+
+      - name: Install Socket Firewall
+        run: npm install -g sfw
+
+      - name: Run node install
+        run: |
+          for attempt in 1 2 3; do
+            echo "Install attempt $attempt of 3 (sfw)..."
+            sfw npm install && break
+            echo "Attempt $attempt failed"
+            if [ "$attempt" -eq 3 ]; then
+              echo "⚠ All sfw attempts failed, falling back to plain npm install"
+              npm install
+            fi
+            sleep 15
+          done
+
+      - name: Log versions
+        run: |
+          echo "Node: $(node -v)"
+          echo "NPM: $(npm -v)"
+          echo "Omega: $(npx omega version)"
+
+      # Optimized-image cache (the cache-uj-imagemin branch successor):
+      # content-addressed, reproducible binaries — never committed. An exact
+      # key hit skips all image processing; a prefix hit re-processes only
+      # changed images.
+      - name: Restore optimized-image cache
+        uses: actions/cache@v4
+        with:
+          path: .omega/cache/imagemin
+          key: omega-imagemin-${{ hashFiles('src/assets/images/**') }}
+          restore-keys: |
+            omega-imagemin-
+
+      # Base path (#358): a Pages PROJECT site serves under `/<repo>/`, a
+      # custom domain (brand.url → CNAME) at the domain root — and everything
+      # the build emits is root-relative, so the build has to be told. Derived
+      # by the SAME function `omega deploy --direct` uses, off the config in
+      # this checkout (GITHUB_REPOSITORY names the repo when it carries no
+      # slug); an explicitly set OMEGA_PATH_PREFIX wins and passes through.
+      - name: Resolve base path
+        run: |
+          PREFIX="$(node -p "require('@omega.js/web/deploy').targetPathPrefix()")"
+          echo "Base path: $PREFIX"
+          echo "OMEGA_PATH_PREFIX=$PREFIX" >> "$GITHUB_ENV"
+
+      # Tracked files only (#568) — `ls -R` printed node_modules (~45k lines)
+      # and hid the build output in every run, truncating the log exactly when
+      # a failure needed reading.
+      - name: Log repo files
+        run: |
+          echo "Tracked files:"
+          git ls-files
+
+      - name: Log disk usage (before build)
+        run: df -h /
+
+      - name: Build
+        run: |
+          npm run build
+
+      # `if: always()` (#568): this reading is the one that matters when the
+      # build itself is what ran out of room.
+      - name: Log disk usage (after build)
+        if: always()
+        run: df -h /
+
+      - name: Deploy to gh-pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GH_TOKEN }}
+          publish_dir: ./dist
+          # One commit on gh-pages, forever (#568). Without it the branch grows
+          # by a whole site per deploy, and the deploy action clones it again
+          # before copying the build in. It holds build artifacts only, so
+          # discarding its history is intended.
+          force_orphan: true
+
+      # Post-publish edge-cache purge — runs only when the repo has a
+      # CLOUDFLARE_TOKEN secret; skips silently otherwise.
+      - name: Purge Cloudflare cache
+        if: env.CLOUDFLARE_TOKEN != ''
+        run: npx omega purge

package/scaffold/.nvmrc

@@ -0,0 +1 @@
+v{{ versions.node }}

package/scaffold/AGENTS.md

@@ -0,0 +1,55 @@
+# ========== Default Values ==========
+# @omega.js/web consumer project
+
+<!-- MAINTAINERS (framework repo): this consumer template is MIRRORED across all OMEGA framework consumer templates (src/defaults/AGENTS.md ×N; web's lives at scaffold/AGENTS.md).
+  Same sections in the same order: framework-specific extras may be inserted; canonical sections are never reordered/renamed. Edit every framework consumer template together.
+  The mirroring rule lives in each framework guide's Doc-update parity section (docs/<framework>/index.md) -->
+
+## Framework
+
+This project consumes **@omega.js/web**, the OMEGA web framework (Eleventy 3 + LiquidJS). It ships ~60 default pages as virtual templates (nothing copied into this repo), layered themes with zero file copying, a `page.resolved` data cascade, the esbuild/sass/PurgeCSS asset pipeline, and an ESM boot runtime around the @omega.js/client singleton.
+
+## 🚨 READ THE FRAMEWORK DOCS FIRST
+
+**Before doing ANY work on this codebase, the agent MUST read the framework documentation: that is where the architecture, conventions, APIs, and gotchas live. Skipping these will result in solutions that conflict with framework patterns.**
+
+**Required reading:**
+- **`node_modules/@omega.js/AGENTS.md`**: the OMEGA map, the one agent entry into the framework docs; follow it to `docs/web/index.md` (the @omega.js/web guide: identity, architecture, conventions)
+- **the deep references beside that guide** (`docs/web/sections.md`, `docs/web/template-kit.md`, `docs/shared/theming.md`, …): read the relevant ones for the task at hand
+
+## 🚨 READ @omega.js/client TOO
+
+**@omega.js/web boots `@omega.js/client` as a runtime singleton on every page.**
+- It powers auth, Firebase, reactive `data-omega-bind` directives, analytics, error tracking, and utilities (`escapeHTML`, etc.).
+- Any task that touches auth flows, Firestore reads/writes, subscription resolution, push notifications, or DOM bindings means you are working with @omega.js/client as much as with @omega.js/web.
+
+**Required reading:**
+- **`node_modules/@omega.js/AGENTS.md`** → `docs/client/index.md`, the @omega.js/client guide: identity, module list, conventions
+- **`node_modules/@omega.js/client/docs/`**: module deep references (Auth, Bindings, Firestore, Notifications, etc.)
+
+## Quick start
+
+```bash
+npm start           # omega dev: dev server (Eleventy watch + asset rebuild)
+npm run build       # omega build: production build → dist/
+npm test            # omega test: production build + smoke checks + test/
+npm run deploy      # omega deploy: commit + push, then dispatch the build workflow (CI publishes)
+npx omega clean     # remove dist/ and .omega/
+```
+
+## Project layout
+
+- `src/pages/`: your pages (frontmatter-only files override same-URL default pages). `example.md.txt` is a commented walkthrough of meta-only frontmatter and `{% section %}` composition; its `.txt` suffix keeps it out of the build, so copy it to `<name>.md` to start from it
+- `src/_posts/`: blog posts (`YYYY-MM-DD-slug.md`)
+- `src/_layouts/`: consumer-local layouts (top layout layer)
+- `src/assets/js/pages/`, `src/assets/css/pages/`: per-page modules/styles (layered over theme + core)
+- `config/omega.json5`: the ONE config file (never put secrets here; use `.env`)
+- `dist/`, `.omega/`: build output + machinery (gitignored, never edit)
+
+## Rules
+
+- Only work in `src/` and `config/`, never `dist/`, `.omega/`, or `node_modules/`.
+- Framework defaults (this file's Default section, `.gitignore`, `.env`, CI workflow) are re-synced by every omega verb; customize below the Custom marker only.
+
+# ========== Custom Values ==========
+<!-- Add your project-specific notes below this line -->

package/scaffold/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/scaffold/_.gitattributes

@@ -0,0 +1,4 @@
+# Machine-written translation string caches — committed build INPUT (they make
+# clone→build deterministic and credential-free), but collapsed in PR diffs and
+# excluded from language stats. See @omega.js/web docs/shared/translation.md.
+translations/** linguist-generated=true

package/scaffold/_.gitignore

@@ -0,0 +1,27 @@
+# ========== Default Values ==========
+# macOS
+.DS_Store
+
+# Logs
+logs
+*.log
+npm-debug.log*
+
+# Dependency directories
+node_modules/
+
+# dotenv environment variables file
+.env
+
+# Build output + machinery (omega build / omega dev)
+/dist
+/.omega
+/.cache
+/.temp
+
+# Output of 'npm pack'
+*.tgz
+
+# ========== Custom Values ==========
+# Add your custom ignore patterns below this line
+# ...

package/scaffold/config/omega.json5

@@ -0,0 +1,20 @@
+{
+  // OMEGA config — one file, one shape, every project type.
+  // Docs: node_modules/@omega.js/web/README.md + docs/shared/config.md in the Omega repo.
+  // Secrets NEVER live here — they go in .env (the validator hard-fails on
+  // secret-shaped keys).
+  brand: {
+    id: 'my-brand',
+    name: 'My Brand',
+    url: 'https://example.com',
+  },
+
+  theme: {
+    id: 'classy',
+  },
+
+  // Key presence = this project enables this target
+  targets: {
+    web: {},
+  },
+}

package/scaffold/src/pages/example.md.txt

@@ -0,0 +1,94 @@
+This file is a WALKTHROUGH, not a page. The `.txt` suffix keeps it out of the
+build (Eleventy only templates .md/.html/.liquid here, and nothing under
+src/pages is copied verbatim), so it can sit in your project as a reference
+for as long as it is useful.
+
+To turn it into a real page: copy it to `src/pages/<name>.md`, drop everything
+above and below the rule lines, and edit. The file path IS the URL unless a
+permalink says otherwise: `src/pages/about.md` serves /about.
+
+Everything inside the rule lines is safe to ship as-is: the notes in it are
+Liquid comments, which the render drops. An HTML comment would NOT be. It is
+shipped bytes, published to every visitor, so keep private notes in the
+Liquid form.
+
+────────────────────────────────────────────────────────────────────────────
+---
+# Page frontmatter is META-ONLY. These are the only keys the engine reads:
+#
+#   layout                          which layout renders the page chrome
+#   permalink                       the URL, when it isn't the file path
+#   meta                            title / description / image / index for the <head>
+#   schema                          structured data (JSON-LD) for this page
+#   config                          per-page omega.json5 overrides (theme, client…)
+#   redirect                        url / querystring for the redirect layout
+#   templateEngineOverride          the engine, when it isn't inferred
+#   eleventyExcludeFromCollections  keep the page out of collections
+#
+# Any OTHER key is content-in-frontmatter, a lane that does not exist. The
+# build strips it before rendering and warns; sections never see it. Content
+# lives in the page BODY, below, as {% section %} calls. The `config:` rule
+# runs both ways: a config section (theme, client, analytics…) restated BARE
+# is a build ERROR, and a key under `config:` that omega.json5 has no section
+# for is one too. Everything above except `config` is page machinery — `meta`
+# included, which is why omega.json5 carries no meta section at all.
+layout: frontend/core/base
+permalink: /example
+meta:
+  title: Example page
+  description: How a page composes sections.
+---
+
+{% comment %}
+  A page is a stack of full-width bands. Each section call names a section
+  id and passes its args; the section's own defaults fill in the rest, so
+  you write only what you want to change.
+
+  These notes are LIQUID comments, and that is deliberate. An HTML comment
+  is shipped bytes: it survives into dist/ for every visitor to read. So
+  anything you would not publish belongs in a Liquid comment, which the
+  render drops. Two more traps worth knowing: Liquid runs INSIDE an HTML
+  comment (a tag in there really executes), and a comment of either kind is
+  still tokenized, so a stray brace is a build error even here. That is why
+  these notes spell no tags.
+{% endcomment %}
+
+{% comment %} Inline form: simple values, which are real Liquid expressions. {% endcomment %}
+{% section "marketing/hero", headline: "Everything you need", description: "Built with {{ resolved.config.brand.name }}." %}
+
+{% comment %} No args at all: the section renders its own defaults. {% endcomment %}
+{% section "marketing/stats" %}
+
+{% comment %}
+  Block form: structured args, written as YAML. Liquid output tokens
+  inside the values render against this page.
+{% endcomment %}
+{% section "marketing/faq" %}
+headline: "Questions, answered"
+items:
+  - question: "Do I have to write every page?"
+    answer: "No. The stock pages already render; this one is extra."
+  - question: "Where does the copy live?"
+    answer: "Right here, in the section call, never in frontmatter."
+{% endsection %}
+
+{% comment %} Slots pass finished MARKUP where a string won't do. {% endcomment %}
+{% section "marketing/hero" %}
+  {% slot demo_html %}
+    <div class="my-demo"><i class="fa-solid fa-rocket"></i> {{ resolved.config.brand.name }}</div>
+  {% endslot %}
+{% endsection %}
+────────────────────────────────────────────────────────────────────────────
+
+Every stock page (home, pricing, about, the legal set, the whole auth flow)
+already renders without a file here; this directory is empty on purpose. To
+start from one of them instead of a blank page, materialize it:
+
+    npx omega customize <url>
+
+`npx omega customize /pricing` writes the real pricing page into src/pages/
+with its composition intact, yours to edit. Bare `npx omega customize` lists
+every customizable URL.
+
+The framework's docs/web/sections.md is the full contract: every section id,
+the arg schemas, slots, and the directory-data lane for site-wide overrides.

package/scaffold/src/service-worker.js

@@ -0,0 +1,16 @@
+// The OMEGA service worker manager is bundled into /service-worker.js by the
+// framework build (esbuild). Custom service-worker code goes below.
+import Manager from '@omega.js/web/service-worker';
+
+// Load Manager
+const manager = new Manager();
+
+// Initialize
+manager.initialize()
+.then(() => {
+  // Log
+  console.log('Initialized service-worker.js');
+
+  // Custom code
+  // ...
+});

package/sw/entry.js

@@ -0,0 +1,19 @@
+/**
+ * The default service-worker entry — used when the consumer has no
+ * src/service-worker.js of its own. The scaffolded consumer file starts as
+ * an exact copy of this; custom SW code goes there.
+ */
+import Manager from '@omega.js/web/service-worker';
+
+// Load Manager
+const manager = new Manager();
+
+// Initialize
+manager.initialize()
+.then(() => {
+  // Log
+  console.log('Initialized service-worker.js');
+
+  // Custom code
+  // ...
+});

package/sw/manager.js

@@ -0,0 +1,281 @@
+/**
+ * The OMEGA service worker manager — the master-service-worker successor.
+ * Bundled (esbuild iife) from the consumer's src/service-worker.js entry
+ * (or the packaged default) to dist root /service-worker.js.
+ *
+ * Config transport: the build emits /build.js (`self.OMEGA_BUILD_JSON = {…}`)
+ * with the brand id, environment, version, cacheBreaker, main asset URLs and
+ * firebase config — imported synchronously below, BEFORE the class reads it.
+ * Because the registration uses `updateViaCache: 'none'`, a changed /build.js
+ * (new build, or a DIFFERENT project on the same localhost port) makes the
+ * browser install this worker fresh: skipWaiting + clients.claim take the
+ * scope over immediately, and initialize() evicts every cache that doesn't
+ * carry this brand+build's name. One project per origin, self-healing.
+ *
+ * ⚠️ NO fetch handler, ON PURPOSE (Ian 2026-07-18: page speed wins) — with
+ * no fetch listener the browser skips SW startup for navigations entirely,
+ * so pages load at full network speed. Adding offline caching means adding
+ * a fetch handler, which taxes EVERY request through the worker; don't.
+ */
+const sw = self;
+
+// The base path this site is mounted under (#355/#360). A worker has no
+// document to read the `data-omega-path-prefix` stamp from, so @omega.js/client
+// hands the value over on this script's query string at registration time —
+// which also scopes the worker to `<prefix>/`. Empty means the domain root.
+const PATH_PREFIX = new URLSearchParams(sw.location.search).get('omega-path-prefix') || '';
+
+// Mount a root-relative site URL under that base path. A no-op at the domain
+// root, and anything the payload supplies (absolute URLs from FCM) is left alone.
+function sitePath(url) {
+  if (!PATH_PREFIX || typeof url !== 'string') return url;
+  if (!url.startsWith('/') || url.startsWith('//')) return url;
+
+  return `${PATH_PREFIX}${url}`;
+}
+
+// Cache warming is DISABLED (Ian 2026-07-18: page speed wins — nothing reads
+// the cache today, and no fetch handler exists to serve from it). The
+// machinery stays wired (updateCache + the update-cache message command) so
+// this single flag re-enables it if an offline/caching lane ever lands.
+const CACHE_WARMING_ENABLED = false;
+
+// Build config — synchronous, top-level (importScripts cannot run later)
+importScripts(sitePath('/build.js'));
+
+// ⚠️ Global listeners BEFORE the Firebase imports — firebase-messaging
+// registers its own notificationclick handler, and ours must come first:
+// https://stackoverflow.com/questions/78270541
+setupGlobalHandlers();
+
+// Firebase compat libraries for background messaging (FCM push). The version
+// is pinned at build time to @omega.js/client's own firebase dependency.
+// Skipped when the brand has no firebase config, and guarded either way — a
+// failed CDN fetch (offline, CSP, blocked gstatic) must never abort script
+// evaluation and take down the SW's cache-eviction/takeover role.
+let firebaseScriptsLoaded = false;
+if (sw.OMEGA_BUILD_JSON && sw.OMEGA_BUILD_JSON.firebase) {
+  try {
+    importScripts(
+      `https://www.gstatic.com/firebasejs/${__OMEGA_FIREBASE_VERSION__}/firebase-app-compat.js`,
+      `https://www.gstatic.com/firebasejs/${__OMEGA_FIREBASE_VERSION__}/firebase-messaging-compat.js`,
+    );
+    firebaseScriptsLoaded = true;
+  } catch (e) {
+    console.error('[service-worker] Firebase libraries failed to load; push messaging disabled:', e);
+  }
+}
+
+// Manager Class
+class Manager {
+  constructor() {
+    // Properties
+    this.serviceWorker = null;
+
+    // Load config from the emitted /build.js
+    this.config = sw.OMEGA_BUILD_JSON || {};
+
+    // Defaults
+    this.brand = this.config.brand || 'default';
+    this.environment = this.config.environment || 'production';
+    this.cache = {
+      breaker: this.config.cacheBreaker || new Date().getTime(),
+    };
+    this.cache.name = `${this.brand}-${this.cache.breaker}`;
+
+    // Libraries
+    this.libraries = {
+      firebase: false,
+      messaging: false,
+    };
+  }
+
+  // Initialize
+  async initialize() {
+    // Properties
+    this.serviceWorker = sw;
+
+    // Setup instance-specific message handlers
+    this.setupInstanceHandlers();
+
+    // Initialize Firebase
+    this.initializeFirebase();
+
+    // Evict caches that don't belong to this brand+build — a previous build's
+    // caches, or a DIFFERENT project's caches left on this origin (the
+    // localhost:4000 case). Then warm this build's cache (a no-op while
+    // CACHE_WARMING_ENABLED is off — eviction still clears leftovers).
+    await this.cleanCaches();
+    this.updateCache();
+
+    // Log
+    console.log(`[service-worker] Initialized: ${this.cache.name} (${this.environment})`, sw.location.pathname);
+
+    // Return
+    return sw;
+  }
+
+  // Setup instance-specific message handlers
+  setupInstanceHandlers() {
+    sw.addEventListener('message', (event) => {
+      // Get the data
+      const data = event.data || {};
+
+      // Parse the data
+      const command = data.command || '';
+      const payload = data.payload || {};
+
+      // Quit if no command
+      if (!command) {
+        return;
+      }
+
+      // Log
+      console.log('[service-worker] message', command, payload);
+
+      // Handle commands
+      if (command === 'update-cache') {
+        const pages = payload.pages || [];
+        this.updateCache(pages)
+          .then(() => {
+            event.ports[0]?.postMessage({ status: 'success' });
+          })
+          .catch((error) => {
+            event.ports[0]?.postMessage({ status: 'error', error: error.message });
+          });
+      }
+    });
+  }
+
+  // Setup Firebase init
+  initializeFirebase() {
+    // Get Firebase config
+    const firebaseConfig = this.config.firebase;
+
+    // Check if Firebase config is available
+    if (!firebaseConfig) {
+      console.log('[service-worker] Firebase config not available, skipping Firebase initialization');
+      return;
+    }
+
+    // Check the libraries actually loaded (guarded top-level importScripts)
+    if (!firebaseScriptsLoaded) {
+      return;
+    }
+
+    // Check if already initialized
+    if (this.libraries.firebase) {
+      return;
+    }
+
+    // Initialize app (libraries were already imported at the top)
+    firebase.initializeApp(firebaseConfig);
+
+    // Initialize messaging
+    this.libraries.messaging = firebase.messaging();
+
+    // Handle background push messages (when the page is not focused)
+    this.libraries.messaging.onBackgroundMessage((payload) => {
+      console.log('[service-worker] Background message received:', payload);
+
+      const notification = payload.notification || {};
+      const data = payload.data || {};
+
+      const title = notification.title || 'New notification';
+      const options = {
+        body: notification.body || '',
+        icon: notification.icon || notification.image || sitePath('/assets/images/favicon/favicon-192x192.png'),
+        data: payload,
+      };
+
+      if (data.click_action) {
+        options.data.click_action = data.click_action;
+      }
+
+      sw.registration.showNotification(title, options);
+    });
+
+    // Attach firebase to the manager
+    this.libraries.firebase = firebase;
+  }
+
+  // Delete every cache on this origin that isn't THIS brand+build's cache
+  cleanCaches() {
+    return caches.keys()
+      .then((names) => {
+        const stale = names.filter((name) => name !== this.cache.name);
+        return Promise.all(stale.map((name) => caches.delete(name)))
+          .then(() => {
+            if (stale.length > 0) {
+              console.log('[service-worker] Evicted stale caches:', stale);
+            }
+          });
+      })
+      .catch((error) => console.error('[service-worker] Failed to clean caches:', error));
+  }
+
+  // Setup cache update — disabled by CACHE_WARMING_ENABLED (see top of file)
+  updateCache(pages) {
+    if (!CACHE_WARMING_ENABLED) {
+      return Promise.resolve();
+    }
+
+    // Set default resources to cache: the home page + the main bundles
+    // (their URLs ride /build.js — hashed names in production builds)
+    const defaults = ['/', this.config.assets?.js, this.config.assets?.css].filter(Boolean).map(sitePath);
+
+    // Ensure pages is an array, mounted the same way the defaults are: the
+    // update-cache caller supplies SITE-relative pages (it knows nothing about
+    // this worker's base path), so they ride sitePath() too
+    pages = (pages || []).map(sitePath);
+
+    // Merge with additional pages
+    const pagesToCache = [...new Set([...defaults, ...pages])];
+
+    // Open cache and add pages
+    return caches.open(this.cache.name)
+      .then((cache) => cache.addAll(pagesToCache))
+      .then(() => console.log('[service-worker] Cached resources:', pagesToCache))
+      .catch((error) => console.error('[service-worker] Failed to cache resources:', error));
+  }
+}
+
+// Helper: Setup global listeners
+// Called at top-level before the Firebase imports so these register first
+function setupGlobalHandlers() {
+  // Force this service worker to take the scope over immediately — the
+  // cross-project takeover depends on it
+  sw.addEventListener('install', () => {
+    sw.skipWaiting();
+  });
+
+  sw.addEventListener('activate', (event) => {
+    event.waitUntil(sw.clients.claim());
+  });
+
+  // Handle clicks on notifications
+  // ⚠️ MUST be registered before the Firebase imports
+  sw.addEventListener('notificationclick', (event) => {
+    // Get the properties of the notification
+    const notification = event.notification;
+    const data = (notification.data && notification.data.FCM_MSG ? notification.data.FCM_MSG.data : null) || {};
+    const payload = (notification.data && notification.data.FCM_MSG ? notification.data.FCM_MSG.notification : null) || {};
+
+    // Get the click action
+    const clickAction = payload.click_action || data.click_action || sitePath('/');
+
+    // Log
+    console.log('[service-worker] notificationclick', clickAction, event);
+
+    // Handle the click
+    event.waitUntil(
+      sw.clients.openWindow(clickAction)
+    );
+
+    // Close the notification
+    notification.close();
+  });
+}
+
+// Export
+export default Manager;