@swoff/cli 0.3.8 → 0.3.9

package/docs/COMPARISON.md

@@ -0,0 +1,192 @@
+# Offline-First Infrastructure: Library Comparison
+
+## Libraries Compared
+
+| Library             | Category                  | Approach                           | Runtime size                             |
+| ------------------- | ------------------------- | ---------------------------------- | ---------------------------------------- |
+| **Swoff**           | All-in-one generator      | Config-driven code gen             | 0 kB                                     |
+| **Workbox**         | SW toolkit                | Build-time + runtime modules       | ~30 kB                                   |
+| **vite-plugin-pwa** | SW (Vite)                 | Vite plugin wrapping Workbox       | ~30 kB                                   |
+| **TanStack Query**  | Server state              | Runtime JS                         | 3.8 kB gzip                              |
+| **SWR**             | Server state              | Runtime JS                         | 3.3 kB gzip                              |
+| **RTK Query**       | Server state              | Runtime JS + Redux                 | 2.9 kB + Redux                           |
+| **Apollo Client**   | GraphQL client            | Runtime JS                         | ~32 kB gzip                              |
+| **RxDB**            | Offline-first DB          | Runtime JS                         | ~40 kB gzip                              |
+| **TanStack DB**     | Client DB + offline-first | Runtime JS (differential dataflow) | ~6 kB gzip core (+ SQLite WASM optional) |
+
+## Feature Matrix
+
+### Caching & Strategies
+
+| Feature                           | Swoff               | Workbox            | TanStack Query | Apollo           | RxDB           | TanStack DB             |
+| --------------------------------- | ------------------- | ------------------ | -------------- | ---------------- | -------------- | ----------------------- |
+| SW code generation                | ✅ Full source      | 🟡 Partial runtime | ❌             | ❌               | ❌             | ❌                      |
+| Caching strategies                | ✅ 6                | ✅ 5               | ❌             | ❌               | ❌             | 🟡 via Query            |
+| Stale-while-revalidate            | ✅                  | ✅                 | ✅             | ✅               | ❌             | ✅ via Query            |
+| Cache-first / Network-first       | ✅ both             | ✅ both            | ❌             | ❌               | ❌             | ❌                      |
+| Reactive strategy (staleTime)     | ✅                  | ❌                 | ✅             | ❌               | ❌             | ✅ via Query            |
+| Configurable mode (all/explicit)  | ✅                  | ❌                 | ❌             | ❌               | ❌             | ❌                      |
+| Cache key normalization           | ✅                  | ❌                 | ❌             | ❌               | ❌             | ❌                      |
+| Ignore query params in cache key  | ✅                  | ❌                 | ❌             | ❌               | ❌             | ❌                      |
+| Precaching at install time        | ✅                  | ✅                 | ❌             | ❌               | ❌             | ❌                      |
+
+### Invalidation
+
+| Feature                           | Swoff               | Workbox            | TanStack Query | Apollo           | RxDB           | TanStack DB             |
+| --------------------------------- | ------------------- | ------------------ | -------------- | ---------------- | -------------- | ----------------------- |
+| Tag-based invalidation            | ✅ URL/op-name      | ❌                 | ✅ query-key   | 🟡 custom        | ❌             | ❌ query-key only       |
+| Cascading tag dependencies        | ✅ client-expanded  | ❌                 | ❌             | ❌               | ❌             | ❌                      |
+| Glob-pattern invalidation         | ✅                  | ❌                 | ❌             | ❌               | ❌             | ❌                      |
+| Tag introspection (urls→tags, tags→urls) | ✅          | ❌                 | ❌             | ❌               | ❌             | ❌                      |
+| Server push invalidation (SSE/WS) | ✅ built-in         | ❌                 | ❌             | ✅ subscriptions | ✅ replication | 🟡 via sync engine      |
+| SW confirmation before event      | ✅                  | ❌                 | ❌             | ❌               | ❌             | ❌                      |
+| De-duplicated refresh queue       | ✅ batch + Map      | ❌                 | ❌             | ❌               | ❌             | ❌                      |
+
+### Offline & Background Sync
+
+| Feature                           | Swoff               | Workbox            | TanStack Query | Apollo           | RxDB           | TanStack DB             |
+| --------------------------------- | ------------------- | ------------------ | -------------- | ---------------- | -------------- | ----------------------- |
+| Offline write queue               | ✅ IndexedDB        | 🟡 basic           | ❌             | ❌               | ✅             | ✅ optimistic + offline |
+| Configurable retry+backoff        | ✅                  | 🟡                 | ❌             | ❌               | ❌             | 🟡 via Query            |
+| Background sync (post-tab-close)  | ✅ SW via sync API  | ✅ plugin          | ❌             | ❌               | ❌             | ✅ offline tx           |
+| Per-mutation online check         | ✅ before each      | ❌                 | ❌             | ❌               | ❌             | ❌                      |
+| Manual flush (after re-login)     | ✅                  | ❌                 | ❌             | ❌               | ❌             | ❌                      |
+| Mutation progress tracking        | ✅ per-item + batch | ❌                 | ❌             | ❌               | ❌             | 🟡 per-item            |
+
+### Service Worker
+
+| Feature                           | Swoff               | Workbox            | TanStack Query | Apollo           | RxDB           | TanStack DB             |
+| --------------------------------- | ------------------- | ------------------ | -------------- | ---------------- | -------------- | ----------------------- |
+| Generated auditable SW code       | ✅ full source      | 🟡 loader module   | ❌             | ❌               | ❌             | ❌                      |
+| 3-tier config resolution          | ✅ per-request → pattern → global | 🟡 2-tier | ❌     | ❌               | ❌             | ❌                      |
+| SW update versioning              | ✅ 3 modes          | ✅ runtime         | ❌             | ❌               | ❌             | ❌                      |
+| Navigation preload                | ✅                  | ✅                 | ❌             | ❌               | ❌             | ❌                      |
+| SPA fallback for navigation       | ✅                  | ✅                 | ❌             | ❌               | ❌             | ❌                      |
+| SW lifecycle coordination         | ✅ client-injector  | ✅ built-in        | ❌             | ❌               | ❌             | ❌                      |
+
+### Auth
+
+| Feature                           | Swoff               | Workbox            | TanStack Query | Apollo           | RxDB           | TanStack DB             |
+| --------------------------------- | ------------------- | ------------------ | -------------- | ---------------- | -------------- | ----------------------- |
+| Built-in auth header injection    | ✅ 3 types          | ❌                 | ❌             | ❌               | ❌             | ❌                      |
+| Auth-aware offline queue          | ✅                  | ❌                 | ❌             | ❌               | ❌             | ❌                      |
+| Token refresh before expiry       | ✅                  | ❌                 | ❌             | ❌               | ❌             | ❌                      |
+| 401 detection → clear auth        | ✅ SW + client      | ❌                 | ❌             | ❌               | ❌             | ❌                      |
+| Memory-only token storage         | ✅                  | ❌                 | ❌             | ❌               | ❌             | ❌                      |
+| Offline user data cache           | ✅ IndexedDB        | ❌                 | ❌             | ❌               | ❌             | ✅                     |
+
+### GraphQL
+
+| Feature                           | Swoff               | Workbox            | TanStack Query | Apollo           | RxDB           | TanStack DB             |
+| --------------------------------- | ------------------- | ------------------ | -------------- | ---------------- | -------------- | ----------------------- |
+| Body-hash GQL caching             | ✅ SHA-256          | ❌                 | ❌             | ✅ in-memory     | ❌             | 🟡 normalized cols      |
+| GQL operation-name auto-tags      | ✅                  | ❌                 | ❌             | 🟡 custom        | ❌             | ❌                      |
+| GQL offline mutation queue        | ✅                  | ❌                 | ❌             | ❌               | ❌             | ✅                     |
+
+### Real-time & PWA
+
+| Feature                           | Swoff               | Workbox            | TanStack Query | Apollo           | RxDB           | TanStack DB             |
+| --------------------------------- | ------------------- | ------------------ | -------------- | ---------------- | -------------- | ----------------------- |
+| SSE/WS connection management      | ✅ built-in         | ❌                 | ❌             | 🟡 link          | ✅ replication | 🟡 via sync engine      |
+| PWA install prompt                | ✅                  | ❌                 | ❌             | ❌               | ❌             | ❌                      |
+| Push notifications                | ✅ + React hook     | ❌                 | ❌             | ❌               | ❌             | ❌                      |
+| Manifest generation               | ✅                  | 🟡                  | ❌             | ❌               | ❌             | ❌                      |
+
+### Cross-tab & State
+
+| Feature                           | Swoff               | Workbox            | TanStack Query | Apollo           | RxDB           | TanStack DB             |
+| --------------------------------- | ------------------- | ------------------ | -------------- | ---------------- | -------------- | ----------------------- |
+| Cross-tab invalidation sync       | ✅ SW-broadcast     | ❌                 | 🟡 limited     | ❌               | ❌             | 🟡 LocalStorage         |
+| Tag registry (IndexedDB)          | ✅ persistent       | ❌                 | ❌             | ❌               | ❌             | ❌                      |
+| Cache persistence model           | Cache API + IDB     | Cache API          | In-memory      | In-memory + IDB  | IDB            | IDB + SQLite            |
+| State survives page refresh       | ✅ Cache API + IDB  | ✅ Cache API       | ❌             | 🟡 persisted     | ✅             | ✅                      |
+
+### Developer Experience
+
+| Feature                           | Swoff               | Workbox            | TanStack Query | Apollo           | RxDB           | TanStack DB             |
+| --------------------------------- | ------------------- | ------------------ | -------------- | ---------------- | -------------- | ----------------------- |
+| Zero runtime dependencies         | ✅ generated code   | ❌ Workbox         | ❌ 3.8 kB      | ❌ 32 kB         | ❌ 40 kB       | ❌ + Query + DB         |
+| Config-driven setup               | ✅ single file      | ✅ workbox-config  | ❌ code-only   | ❌ code-only     | ❌ code-only   | ❌ code-only            |
+| Build-tool agnostic               | ✅ any              | ✅ any             | ✅ any         | ✅ any           | ✅ any         | ✅ any                  |
+| React hooks                       | ✅ 11               | 🟡 minimal         | ✅ extensive   | ✅               | ✅             | ✅ useLiveQuery         |
+| TypeScript declarations generated | ✅                  | ❌                 | ✅ built-in    | ✅ built-in      | ✅ built-in    | ✅ built-in             |
+| Auditable generated code          | ✅ every file       | 🟡 only SW        | ❌             | ❌               | ❌             | ❌                      |
+
+## Edge Case Handling
+
+| Edge Case                         | Swoff                                    | TanStack Query / SWR | Workbox                     |
+| --------------------------------- | ---------------------------------------- | -------------------- | --------------------------- |
+| **Concurrent invalidation + SWR refresh** | Tagless refresh never clobbers invalidation entry in queue | N/A (no SW) | No tag system |
+| **SW update during offline write** | Cache API + Tag IDB survive SW restart; refresh queue recreated on next fetch | N/A | Cached assets survive; runtime cache cleared if configured |
+| **Tab crash mid-mutation replay** | SW detects no clients → replays via Background Sync | N/A (no SW) | No mutation system |
+| **Rapid repeated invalidations** | Debounced INVALIDATE_TAG coalescing (configurable) | N/A | No tag system |
+| **Offline mid-batch mutation replay** | Per-mutation online check stops processing; remaining mutations stay queued | N/A | No mutation system |
+| **Query param cache-busting** | Configurable ignore params + sorted normalization | N/A | No SW-level caching |
+| **Network flicker on reconnect** | Batch delay + retry backoff prevent stampede | ❌ no SW batching | ❌ per-request only |
+| **staleVersions memory limit** | Max 100 entries, 30 min TTL; lost entries just skip stale fallback | N/A | N/A |
+| **Tag IDB deleted mid-refresh** | Refresh re-populates tag IDB from queue entry's stored tags | N/A | N/A |
+| **Dual-replay client + SW race** | SW checks clients.open() → skips entirely if any client page is open | N/A | No mutation system |
+| **Background sync after all tabs close** | SW wakes via sync event, processes queue, IndexedDB persists | N/A | N/A |
+| **Fetch error during stale refetch** | Exponential backoff retry via setTimeout keeps SW alive | Retry via hook | ❌ |
+| **No service worker support** | SW-all features degrade gracefully; mutation queue falls back to client-only IDB | N/A (normal) | N/A (no SW = nothing) |
+
+### How each library handles persistence model failure
+
+| Failure Scenario                  | Swoff                                    | TanStack Query       | RxDB                  | TanStack DB           |
+| --------------------------------- | ---------------------------------------- | -------------------- | --------------------- | --------------------- |
+| Memory cleared (tab close/refresh) | ✅ Tag IDB + Cache API survive | ❌ Full loss | ✅ IDB survives | ✅ IDB survives |
+| SW terminated (idle)              | ✅ IDB + Cache API survive; Maps rebuilt on next wake | N/A | N/A | N/A |
+| SW killed during fetch handler    | ✅ Cache API atomic; partial writes discarded | N/A | N/A | N/A |
+| IndexedDB quota exceeded          | ✅ Cache API still functional; only tag introspection lost | N/A | ❌ Full loss | ❌ Full loss |
+| Browser storage cleared           | ✅ All caches lost, SW stays installed; next generation re-caches | ❌ | ❌ | ❌ |
+
+### How Swoff handles race conditions
+
+| Race Condition                    | Mitigation                               |
+| --------------------------------- | ---------------------------------------- |
+| SWR queues refresh without tags → invalidation queues with tags | `queueRefresh` guard: tagless call doesn't override if entry with tags exists |
+| Refresh completes after invalidation deletes tag IDB | `_processRefreshQueue` re-populates tags from queue entry |
+| Client triggers `invalidateByTag` before SW caches response | SW processes `INVALIDATE_TAG` at message time; if cache entry doesn't exist yet, it's a no-op for that URL |
+| Multiple tabs call `invalidateByTag` simultaneously | SW debounce (configurable) + Map dedup on tag; single IDB scan |
+| SW and client both try to replay mutation queue | SW skips entirely if any client page is open |
+| Refresh fails → staleVersions entry → next SWR serves stale | staleVersions TTL 30 min, max 100 entries; serves old cache as fallback until retry succeeds |
+
+## Key Differentiators
+
+**Where Swoff leads:**
+
+- **Offline-first integration** — combines SW caching, data fetching, auth, mutation queue, GraphQL, PWA, push notifications, cross-tab sync, and real-time invalidation in a single config-driven system. Others require 4-6 separate tools.
+- **Zero runtime dependencies** — generated code uses only browser APIs. No bundle impact, no version mismatches.
+- **Auth across the stack** — token injection, 401 handling, refresh, offline user caching, and state detection built into fetch wrapper, mutation queue, and SW.
+- **Generated auditable code** — every line visible in `swoff/`. Read, edit, and commit it.
+- **Config-driven resolution** — 3-tier priority for strategy (per-request → route pattern → global default).
+- **SW confirmation-driven events** — `cache-invalidated` fires only after SW confirms via `TAG_INVALIDATED`, not before SW clears cache. Eliminates the "event before action" race.
+- **Tag registry repopulation on refresh** — after invalidation deletes tag→URL mappings from IDB, the background refresh re-populates them. Subsequent invalidations still find the URL.
+- **SW-broadcast cross-tab invalidation** — `TAG_INVALIDATED` is posted to every connected client via `self.clients.matchAll()`. No BroadcastChannel needed.
+
+**Where TanStack DB leads (and Swoff still needs to catch up):**
+
+- **Optimistic updates** — instant local writes with automatic rollback on failure.
+- **Normalized collections** — query across related data with joins, filters, and aggregates.
+- **Differential dataflow** — sub-millisecond incremental query re-computation even with 100k+ items.
+- **SSR support** — works with server rendering (TanStack DB is actively developing this).
+
+**Where Swoff still leads vs TanStack DB:**
+
+- **SW-level caching** — Swoff intercepts at the `fetch` event, caching even third-party and plain `fetch()` calls. TanStack DB operates at the application layer only.
+- **Auth across the stack** — token injection, 401 handling, refresh in SW + client.
+- **Zero runtime deps** — generated code vs TanStack DB's ~6 kB core + Query + optional SQLite WASM.
+- **Config-driven setup** — one config file vs code-only setup.
+- **PWA + push notifications** — built into the generated output.
+
+**Where Swoff still needs to catch up:**
+
+- **Framework hooks** — React only. Vue, Svelte, Solid adapters planned.
+- **Infinite queries / pagination** — not yet built.
+- **Optimistic updates** — not yet built.
+- **Normalized GraphQL cache** — body-hash caching is simple but cannot merge overlapping query results like Apollo/Relay.
+- **Devtools** — no browser extension yet.
+
+## Architecture fit
+
+Swoff operates at the **browser infrastructure layer** (Service Worker + `fetch` event), not the application layer. This means it works with any backend (PHP, Laravel, Django, Rails, Go, Java), any frontend (React, Vue, Svelte, HTMX, vanilla), and any rendering strategy (SSR, SSG, SPA, islands, HTML-over-wire). See [ECOSYSTEM.md](./ECOSYSTEM.md).

package/docs/CONFIG.md

@@ -0,0 +1,277 @@
+# Configuration Reference
+
+Full schema for `swoff.config.json` — every field, its type, default, and description.
+
+## Quick reference
+
+```json
+{
+  "$schema": "https://swoff.netlify.app/schema/v1.json",
+  "enabled": true,
+  "framework": "react",
+  "build": {
+    "outputDir": "dist",
+    "swFilename": "sw"
+  },
+  "features": {
+    "pwa": {
+      "enabled": true,
+      "preventDefaultInstall": false
+    },
+    "serviceWorker": {
+      "version": "package",
+      "minSupportedVersion": "1.0.0",
+      "autoUpdate": true,
+      "autoActivate": false,
+      "strategy": {
+        "default": "cache-first",
+        "patterns": {
+          "/api/*": { "strategy": "reactive", "staleTime": 30, "refetchOnFocus": true },
+          "/static/*": "cache-first"
+        },
+        "reactive": {
+          "defaults": {
+            "staleTime": 0,
+            "refetchInterval": 0,
+            "refetchOnReconnect": false,
+            "refetchOnFocus": false
+          }
+        },
+        "mode": "all",
+        "clearRuntimeOnUpdate": false,
+        "normalizeKey": false,
+        "ignoreQueryParams": []
+      },
+      "navigation": {
+        "mode": "spa",
+        "preload": true,
+        "fallback": "/index.html"
+      }
+    },
+    "refetchQueue": {
+      "batchSize": 5,
+      "batchDelayMs": 1000,
+      "maxRetries": 3,
+      "retryDelayMs": 1000
+    },
+    "mutationQueue": {
+      "enabled": false,
+      "batchSize": 1,
+      "batchDelayMs": 0,
+      "maxRetries": 5,
+      "retryBackoffMs": 1000
+    },
+    "backgroundSync": false,
+    "auth": {
+      "enabled": false,
+      "type": "bearer",
+      "refreshPath": "/api/refresh",
+      "userEndpoint": "/api/me"
+    },
+    "graphql": {
+      "enabled": false,
+      "endpoint": "/graphql"
+    },
+    "crossTabSync": true,
+    "tagInvalidation": {
+      "enabled": true
+    },
+    "pushNotifications": {
+      "enabled": false,
+      "vapidPublicKey": ""
+    },
+    "serverPush": {
+      "enabled": false,
+      "type": "sse",
+      "endpoint": "/api/events",
+      "reconnectDelayMs": 5000
+    }
+  }
+}
+```
+
+---
+
+## Top-level fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `$schema` | `string` | — | JSON Schema URL (for IDE autocomplete) |
+| `enabled` | `boolean` | `true` | Master switch — disables all Swoff features |
+| `framework` | `"react"` \| `"vue"` \| `"svelte"` \| `"vanilla"` | auto-detected | Your UI framework. Controls whether React hooks are generated. |
+| `build.outputDir` | `string` | `"dist"` | Build tool output directory |
+| `build.swFilename` | `string` | `"sw"` | Service worker filename prefix (e.g. `sw-v1.2.3.js`) |
+
+---
+
+## `features.serviceWorker`
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `version` | `"package"` \| `"hash"` \| `string` \| `false` | `"package"` | SW version mode. `"package"`: reads from `package.json`. `"hash"`: SHA-256 hash of generated SW content (deterministic, fixed SW URL). Semver string (e.g. `"1.2.3"`): explicit version. `false`: no versioning (simple mode, hash-based cache name). |
+| `minSupportedVersion` | `string` | `"0.0.0"` | Minimum supported SW version — clients below this are force-updated on page load |
+| `autoUpdate` | `boolean` | `true` | Automatically register new service worker versions when detected. When false, dispatches `sw-update-available` event for manual registration via `handleUpdateApproved()`. |
+| `autoActivate` | `boolean` | `false` | Automatically activate newly registered service workers (`skipWaiting`). Only applies when a new version is registered — use with `autoUpdate` for fully silent updates, or wait for user consent then call `handleUpdateApproved()`. |
+
+### `features.serviceWorker.strategy`
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `default` | `string` | `"cache-first"` | Default caching strategy (lowest priority in 3-tier resolution). One of: `cache-first`, `network-first`, `stale-while-revalidate`, `cache-only`, `network-only`, `reactive` |
+| `patterns` | `object` | `{}` | Per-route strategy overrides. Keys are URL patterns (e.g. `/api/*`). Values can be a strategy name string or a `StrategyEntry` object |
+| `reactive.defaults.staleTime` | `number` | `0` | Global stale time in seconds for reactive strategy. Data is considered fresh for this long; after expiry, SW serves cached but triggers a background refresh. 0 = always stale. |
+| `reactive.defaults.refetchInterval` | `number` | `0` | Global auto-refetch interval in seconds for reactive strategy. SW periodically re-fetches matching routes in the background. 0 disables. |
+| `reactive.defaults.refetchOnReconnect` | `boolean` | `false` | Global default — refetch reactive entries when the browser comes back online |
+| `reactive.defaults.refetchOnFocus` | `boolean` | `false` | Global default — refetch reactive entries when the tab gains focus |
+| `mode` | `"all"` \| `"explicit-only"` | `"all"` | When to apply caching strategies. `"all"`: every GET/HEAD request; `"explicit-only"`: only requests with `X-SW-Cache-Strategy` header |
+| `clearRuntimeOnUpdate` | `boolean` | `false` | Clear runtime cache when a new SW version activates |
+| `normalizeKey` | `boolean` | `false` | When `true`, query params are sorted alphabetically in cache keys so `?b=1&a=2` and `?a=2&b=1` resolve to the same entry. |
+| `ignoreQueryParams` | `string[]` | `[]` | Query params to strip from cache keys (e.g. `["_t", "utm_source"]`). Prevents cache-busting params from creating duplicate cache entries. |
+
+### `features.serviceWorker.navigation`
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `mode` | `"spa"` \| `"default"` | `"spa"` | SPA mode sends unmatched navigation requests to `fallback` |
+| `preload` | `boolean` | `true` | Enable Navigation Preload API — reduces SW startup latency |
+| `fallback` | `string` | `"/index.html"` | Fallback HTML for SPA navigation requests |
+
+### `StrategyEntry` object
+
+When a strategy value is an object instead of a string:
+
+```json
+"/api/*": {
+  "strategy": "reactive",
+  "staleTime": 30,
+  "refetchOnFocus": true
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `strategy` | `string` | (required) | Caching strategy name. One of: `cache-first`, `network-first`, `stale-while-revalidate`, `cache-only`, `network-only`, `reactive` |
+| `staleTime` | `number` | — | Stale time in seconds. **Reactive-only** — only valid when `strategy` is `"reactive"`. Data is considered fresh for this long; after expiry, SW serves cached but triggers a background refresh. 0 = always stale. |
+| `refetchInterval` | `number` | — | Auto-refetch interval in seconds. **Reactive-only**. The SW periodically re-fetches this route in the background. 0 disables. |
+| `refetchOnReconnect` | `boolean` | `false` | Refetch when the browser comes back online. **Reactive-only**. |
+| `refetchOnFocus` | `boolean` | `false` | Refetch when the browser tab gains focus. **Reactive-only**. |
+
+---
+
+## `features.refetchQueue`
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `batchSize` | `number` | `5` | Max stale cache entries to refetch per batch |
+| `batchDelayMs` | `number` | `1000` | Delay in ms between batch cycles (rate limiting) |
+| `maxRetries` | `number` | `3` | Max retries for background refetches (exponential backoff) |
+| `retryDelayMs` | `number` | `1000` | Base delay in ms for retry backoff (delay × 2^retryCount) |
+
+---
+
+### Resolution tiers
+
+`strategy` and `staleTime` resolve in 3 tiers (highest to lowest priority):
+
+1. **Per-request** — passed as options to `fetchWithCache({ strategy })` or `useCachedFetch()`, or via `X-SW-Strategy` / `X-SW-Stale-Time` headers
+2. **Route pattern** — configured in `features.serviceWorker.strategy.patterns`
+3. **Global default** — configured at `features.serviceWorker.strategy.reactive.defaults.*` (for `staleTime`) or `features.serviceWorker.strategy.default` (for `strategy`)
+
+`refetchInterval`, `refetchOnReconnect`, and `refetchOnFocus` are SW-initiated (interval timers, online/focus event handlers) and resolve in 2 tiers only:
+
+1. **Route pattern** — configured in the pattern entry
+2. **Global default** — configured at `features.serviceWorker.strategy.reactive.defaults.*`
+
+---
+
+## `features.mutationQueue`
+
+Object-only feature (boolean shorthand not supported).
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `enabled` | `boolean` | `false` | Enable offline write queue |
+| `batchSize` | `number` | `1` | Mutations per progress event |
+| `batchDelayMs` | `number` | `0` | Delay between mutations (rate limiting) |
+| `maxRetries` | `number` | `5` | Max retries before dropping a mutation |
+| `retryBackoffMs` | `number` | `1000` | Exponential backoff base (nextRetry = backoff × 2^retryCount) |
+
+---
+
+## `features.auth`
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `enabled` | `boolean` | `false` | Enable auth module |
+| `type` | `"bearer"` \| `"cookie"` \| `"custom"` | `"bearer"` | Auth strategy |
+| `refreshPath` | `string` | `"/api/refresh"` | Token refresh endpoint |
+| `userEndpoint` | `string` | `"/api/me"` | Current user fetch endpoint |
+
+---
+
+## `features.graphql`
+
+Object-only feature (boolean shorthand not supported).
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `enabled` | `boolean` | `false` | Generate GraphQL wrapper (`queryGql` / `mutateGql`) |
+| `endpoint` | `string` | `"/graphql"` | GraphQL endpoint URL |
+
+---
+
+## `features.pushNotifications`
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `enabled` | `boolean` | `false` | Generate push notification subscription management |
+| `vapidPublicKey` | `string` | `""` | VAPID public key. Baked into the generated push handler at build time — not needed at runtime. |
+
+---
+
+## `features.serverPush`
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `enabled` | `boolean` | `false` | Enable real-time cache invalidation via SSE or WebSocket |
+| `type` | `"sse"` \| `"websocket"` | `"sse"` | Transport protocol |
+| `endpoint` | `string` | `"/api/events"` | Push endpoint URL |
+| `reconnectDelayMs` | `number` | `5000` | Initial reconnect delay on connection loss (exponential backoff, capped at 30s) |
+
+---
+
+## `features.tagInvalidation`
+
+Object-only feature (boolean shorthand not supported).
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `enabled` | `boolean` | `true` | Enable tag-based cache invalidation |
+| `debounceMs` | `number` | `0` | Debounce window (ms) for coalescing rapid invalidations. When > 0, repeated `INVALIDATE_TAG` messages within the window are batched and processed once, reducing redundant cache scans. |
+| `prefixes` | `string[]` | `["api","v1","v2","v3","rest","graphql","gql"]` | URL path prefixes to skip during tag generation |
+| `patterns` | `object` | `{}` | Custom glob patterns for tag generation. Keys are URL patterns (`/api/:id`), values are tag template arrays (`["{id}"]`) |
+| `singularization` | `object` | `{}` | Custom plural→singular mapping (e.g. `{"categories": "category"}`). Default: strips trailing `s`. |
+| `cascading` | `object` | `{}` | Cascading tag dependencies. `{"todos": ["categories"]}` — invalidating `todos` also invalidates `categories` |
+
+---
+
+## Boolean features
+
+| Feature | Config path | Default |
+|---------|-------------|---------|
+| Background Sync | `features.backgroundSync` | `false` |
+| Cross-tab Sync | `features.crossTabSync` | `true` |
+
+---
+
+## Feature dependencies
+
+Some features work best together:
+
+| Feature | Recommended combo | Why |
+|---------|------------------|-----|
+| `mutationQueue` | + `backgroundSync` | Background Sync processes mutations even after tab close |
+| `tagInvalidation` | + `crossTabSync` | Invalidation events broadcast to all open tabs |
+| `serverPush` | + `tagInvalidation` | Server push triggers `invalidateByTag()` — requires tag invalidation to function |
+| `auth` + `mutationQueue` | — | `flushMutations()` after re-login replays mutations that failed with 401 |
+| `graphql` | + `mutationQueue` + `tagInvalidation` | Offline GQL mutations queue in IndexedDB; mutations auto-invalidate operation-name tags |

package/docs/ECOSYSTEM.md

@@ -0,0 +1,33 @@
+# Ecosystem Compatibility
+
+Swoff operates at the **`fetch` event** + **Service Worker** layer — below the application and data-fetching layers. This makes it compatible with any web stack regardless of backend language, frontend framework, or rendering strategy.
+
+```
+Application Layer (React, Vue, Svelte, HTMX, vanilla)
+  Data Fetching Layer (TanStack Query, SWR, Apollo, fetch())
+    SWOFF — SW + Client (fetch interception, cache, offline)
+      Browser APIs (Cache Storage, IndexedDB, fetch, push)
+```
+
+The only framework-specific surface is **view adapters** (React hooks, future Vue/Svelte). These are optional thin wrappers over `postMessage` to the SW. The core caching, offline, invalidation, and auth work without them.
+
+## Compatible with everything
+
+| Category | Examples | Notes |
+|---|---|---|
+| **Backend** | PHP, Laravel, Django, Rails, ASP.NET, Go, Java, Node | Serve `client-injector.js` as a static asset; zero backend integration needed |
+| **HTML-over-wire** | HTMX, Turbo Hotwire, Unpoly, Livewire | SW caches HTML fragments by URL — body format is irrelevant |
+| **SSG** | Astro, Hugo, 11ty, Jekyll | Precaches all built assets at install time; SW works even if no hydration occurs |
+| **SPA frameworks** | React, Vue, Svelte, Solid, Angular, Alpine | Core SW + client utilities are plain JS; React gets generated hooks |
+| **SSR meta-frameworks** | Next.js, Remix, Nuxt, SvelteKit, Analog | Intercepts `fetch()` transparently at the SW level; disable the framework's own SW |
+| **Edge / Serverless** | Cloudflare Workers, Deno Deploy, Vercel Edge | Edge runs on CDN, Swoff runs in browser — independent layers, no conflict |
+| **Islands / Resumability** | Astro islands, Qwik, Marko | SW runs in its own thread regardless of component hydration |
+
+## Why it matters
+
+- **TanStack Query / SWR** — in-memory state only; no SW integration, no offline writes, no push
+- **Workbox** — SW only; no data fetching, auth, or framework hooks
+- **Apollo Client** — GraphQL only; no SW caching
+- **Next.js / Remix** — full meta-frameworks dictating your entire architecture
+
+Swoff is the only tool that combines SW caching, data fetching, offline writes, auth, real-time sync, and push into a single config-driven system — all framework-agnostic at the core, with optional reactive hooks per framework.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swoff/cli",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "type": "module",
   "description": "CLI for Swoff - Offline-first web apps made easy",
   "bin": {
@@ -19,6 +19,7 @@
   "files": [
     "bin/",
     "dist/",
+    "docs/",
     "templates/"
   ],
   "keywords": [

package/templates/hooks/useAuth.jsx

@@ -9,11 +9,11 @@ export function useAuth() {
   });
 
   useEffect(() => {
-    getAuthState().then(setState);
+    getAuthState().then(setState).catch(() => {});
 
     const onOnline = () => setState((s) => ({ ...s, online: true }));
     const onOffline = () => setState((s) => ({ ...s, online: false }));
-    const onAuthChange = () => getAuthState().then(setState);
+    const onAuthChange = () => getAuthState().then(setState).catch(() => {});
 
     window.addEventListener("online", onOnline);
     window.addEventListener("offline", onOffline);

package/templates/hooks/useAuth.tsx

@@ -9,11 +9,11 @@ export function useAuth() {
   });
 
   useEffect(() => {
-    getAuthState().then(setState);
+    getAuthState().then(setState).catch(() => {});
 
     const onOnline = () => setState((s) => ({ ...s, online: true }));
     const onOffline = () => setState((s) => ({ ...s, online: false }));
-    const onAuthChange = () => getAuthState().then(setState);
+    const onAuthChange = () => getAuthState().then(setState).catch(() => {});
 
     window.addEventListener("online", onOnline);
     window.addEventListener("offline", onOffline);

package/templates/hooks/useCachedFetch.jsx

@@ -1,4 +1,4 @@
-import { useState, useEffect, useCallback, useRef, startTransition } from "react";
+import { useState, useEffect, useCallback, startTransition } from "react";
 import { fetchWithCache } from "../fetch-wrapper.js";
 import { generateTags } from "../invalidation-tags.js";
 
@@ -7,8 +7,6 @@ export function useCachedFetch(url, options = {}) {
   const [error, setError] = useState(null);
   const [loading, setLoading] = useState(true);
   const [refetchCount, setRefetchCount] = useState(0);
-  const optionsRef = useRef(options);
-  useEffect(() => { optionsRef.current = options; }, [options]);
 
   const refetch = useCallback(() => setRefetchCount((c) => c + 1), []);
 
@@ -16,7 +14,7 @@ export function useCachedFetch(url, options = {}) {
 
   useEffect(() => {
     if (!isEnabled) {
-      setLoading(false);
+      startTransition(() => setLoading(false));
       return;
     }
     let cancelled = false;
@@ -26,7 +24,7 @@ export function useCachedFetch(url, options = {}) {
     const doFetch = async () => {
       try {
         const { response } = await fetchWithCache(url, {
-          ...optionsRef.current,
+          ...options,
           signal: controller.signal,
         });
         if (cancelled) return;
@@ -67,28 +65,5 @@ export function useCachedFetch(url, options = {}) {
     return () => window.removeEventListener("cache-invalidated", onInvalidated);
   }, [url, isEnabled]);
 
-  // Auto-refetch on window focus
-  useEffect(() => {
-    if (!options.refetchOnWindowFocus || !isEnabled) return;
-    const onFocus = () => refetch();
-    window.addEventListener("focus", onFocus);
-    return () => window.removeEventListener("focus", onFocus);
-  }, [options.refetchOnWindowFocus, refetch, isEnabled]);
-
-  // Auto-refetch on reconnect
-  useEffect(() => {
-    if (!options.refetchOnReconnect || !isEnabled) return;
-    const onOnline = () => refetch();
-    window.addEventListener("online", onOnline);
-    return () => window.removeEventListener("online", onOnline);
-  }, [options.refetchOnReconnect, refetch, isEnabled]);
-
-  // Auto-refetch on interval
-  useEffect(() => {
-    if (!options.refetchInterval || options.refetchInterval <= 0 || !isEnabled) return;
-    const id = setInterval(refetch, options.refetchInterval * 1000);
-    return () => clearInterval(id);
-  }, [options.refetchInterval, refetch, isEnabled]);
-
   return { data, error, loading, refetch };
 }