@swoff/cli 0.3.6 → 0.3.8

package/dist/lib/generators/file-generators/mutation-queue.js

@@ -1,6 +1,3 @@
-/**
- * Generates mutation-queue.js - offline mutation queue with IndexedDB.
- */
 import { writeFile } from "./context.js";
 export function generateMutationQueue(ctx) {
     const ext = ctx.ext;
@@ -10,24 +7,32 @@ export function generateMutationQueue(ctx) {
     const PT = (type) => (ts ? `<${type}>` : "");
     const AS = (type) => (ts ? ` as ${type}` : "");
     const authEnabled = ctx.config.features.auth.enabled;
+    const mqConfig = ctx.config.features.mutationQueue;
+    const batchSize = mqConfig.batchSize;
+    const batchDelayMs = mqConfig.batchDelayMs;
+    const maxRetries = mqConfig.maxRetries;
+    const retryBackoffMs = mqConfig.retryBackoffMs;
     const importLines = authEnabled
         ? `import { getAuth } from "./auth/store.${ext}";
 `
         : "";
     const additionalImports = `import { invalidateByTags } from "./cache.${ext}";
-${ts ? `import type { MutationQueueItem } from "./swoff.d.ts";
-` : ""}`;
-    const authReplayBlock = authEnabled
+${ts
+        ? `import type { MutationQueueItem } from "./swoff.d.ts";
+`
+        : ""}`;
+    const authReplayHeaders = authEnabled
         ? `  const auth = await getAuth();
   const authHeader${T("Record<string, string>")} = auth?.token ? { Authorization: \`Bearer \${auth.token}\` } : {};
 `
         : "";
-    const authHeadersSpread = authEnabled
-        ? `            ...authHeader,`
-        : "";
+    const authHeaderSpread = authEnabled
+        ? `            ...authHeader,\n`
+        : "            ";
     const code = `/**
  * Swoff Mutation Queue
  * Queue offline writes and sync when connection returns.
+ * Supports configurable batch size, rate limiting, and exponential backoff.
  *
  * Usage:
  *   import { queueMutation, processMutationQueue, flushMutations, getPendingCount } from './swoff/mutation-queue.${ext}';
@@ -44,11 +49,24 @@ ${ts ? `import type { MutationQueueItem } from "./swoff.d.ts";
  *   await flushMutations();
  *
  *   // Auto-processes on online event
+ *
+ * Config:
+ *   batchSize: ${batchSize}      — mutations per progress event
+ *   batchDelayMs: ${batchDelayMs} — delay between mutations (rate limiting)
+ *   maxRetries: ${maxRetries}      — max retries before dropping
+ *   retryBackoffMs: ${retryBackoffMs} — exponential backoff base
  */
 
 ${importLines}${additionalImports}const DB_NAME = "swoff-queue";
 const STORE_NAME = "mutations";
-const MAX_RETRIES = 5;
+const BATCH_SIZE = ${batchSize};
+const BATCH_DELAY_MS = ${batchDelayMs};
+const MAX_RETRIES = ${maxRetries};
+const RETRY_BACKOFF_MS = ${retryBackoffMs};
+
+function sleep(ms${T("number")})${R("Promise<void>")}{
+  return new Promise((r) => setTimeout(r, ms));
+}
 
 function openQueueDB()${R("Promise<IDBDatabase>")}{
   return new Promise${PT("IDBDatabase")}((resolve, reject) => {
@@ -73,14 +91,27 @@ export async function queueMutation(mutation${T("Partial<MutationQueueItem>")})$
   const tx = db.transaction(STORE_NAME, "readwrite");
   const store = tx.objectStore(STORE_NAME);
 
+  let body = mutation.body;
+  let bodyType = "json";
+  if (body instanceof FormData) {
+    bodyType = "formdata";
+    body = [...body.entries()];
+  } else if (body instanceof Blob) {
+    bodyType = "blob";
+  } else if (body instanceof ArrayBuffer || ArrayBuffer.isView(body)) {
+    bodyType = "buffer";
+  }
+
   store.add({
     id: crypto.randomUUID(),
     method: mutation.method,
     url: mutation.url,
-    body: mutation.body,
+    body,
+    bodyType,
     headers: mutation.headers || {},
     timestamp: Date.now(),
     retryCount: 0,
+    nextRetryAt: 0,
     tags: mutation.tags || [],
   });
 
@@ -92,13 +123,57 @@ export async function queueMutation(mutation${T("Partial<MutationQueueItem>")})$
   window.dispatchEvent(new CustomEvent("mutation-queue-changed"));
 }
 
-/** Process all queued mutations in order. Sends them to the server. Runs automatically on the online event. */
+/** Replay a single queued mutation. Returns true on success, false on failure. */
+async function replayMutation(item${T("MutationQueueItem")})${R("Promise<boolean>")}{
+  try {
+${authReplayHeaders}    let replayBody${T("BodyInit | null")}${ts ? " = null" : ""};
+    let contentType${T("string | undefined")};
+    const bt = item.bodyType || "json";
+    if (bt === "formdata") {
+      replayBody = new FormData();
+      for (const [key, value] of (item.body || [])${AS("[string, FormDataEntryValue][]")}) {
+        replayBody.append(key, value);
+      }
+    } else if (bt === "blob") {
+      replayBody = item.body${AS("BodyInit | null")};
+    } else if (bt === "buffer") {
+      replayBody = item.body instanceof ArrayBuffer ? new Uint8Array(item.body)${AS("BodyInit")} : item.body${AS("BodyInit")};
+    } else {
+      replayBody = JSON.stringify(item.body);
+      contentType = "application/json";
+    }
+    const response = await fetch(item.url, {
+      method: item.method,
+      headers: {
+        ...(contentType ? { "Content-Type": contentType } : {}),
+${authHeaderSpread}        ...item.headers,
+      },
+      body: replayBody,
+    });
+
+    if (!response.ok) throw new Error(\`HTTP \${response.status}\`);
+
+    if (item.tags && item.tags.length > 0) {
+      await invalidateByTags(item.tags);
+    }
+
+    await removeFromQueue(item.id);
+    return true;
+  } catch {
+    item.retryCount++;
+    item.nextRetryAt = Date.now() + RETRY_BACKOFF_MS * Math.pow(2, item.retryCount - 1);
+    await updateInQueue(item);
+    return false;
+  }
+}
+
+/** Process all queued mutations in order. Sends them to the server. Runs automatically on the online event. Respects batchSize for progress reporting and batchDelayMs for rate limiting. */
 export async function processMutationQueue()${R("Promise<void>")}{
   if (!navigator.onLine || isSyncing) return;
   isSyncing = true;
 
   try {
-${authReplayBlock}    const db = await openQueueDB();
+    const db = await openQueueDB();
     const tx = db.transaction(STORE_NAME, "readonly");
     const store = tx.objectStore(STORE_NAME);
     const index = store.index("by-timestamp");
@@ -110,6 +185,7 @@ ${authReplayBlock}    const db = await openQueueDB();
 
     let succeeded = 0;
     let failed = 0;
+    const total = queue.length;
 
     for (const item of queue) {
       if (item.retryCount >= MAX_RETRIES) {
@@ -118,34 +194,36 @@ ${authReplayBlock}    const db = await openQueueDB();
         continue;
       }
 
-      try {
-        const response = await fetch(item.url, {
-          method: item.method,
-          headers: {
-            "Content-Type": "application/json",
-${authHeadersSpread}            ...item.headers,
-          },
-          body: JSON.stringify(item.body),
-        });
-
-        if (!response.ok) throw new Error(\`HTTP \${response.status}\`);
-
-        if (item.tags && item.tags.length > 0) {
-          await invalidateByTags(item.tags);
-        }
+      // Skip items whose backoff delay hasn't elapsed yet
+      if (item.nextRetryAt && Date.now() < item.nextRetryAt) {
+        continue;
+      }
 
-        await removeFromQueue(item.id);
+      const ok = await replayMutation(item);
+      if (ok) {
         succeeded++;
-      } catch {
-        item.retryCount++;
-        await updateInQueue(item);
+      } else {
         failed++;
       }
+
+      // Rate limiting delay between mutations
+      if (BATCH_DELAY_MS > 0 && succeeded + (failed - succeeded) < total) {
+        await sleep(BATCH_DELAY_MS);
+      }
+
+      // Emit progress after every BATCH_SIZE mutations
+      if ((succeeded + failed) % BATCH_SIZE === 0 || succeeded + failed === total) {
+        window.dispatchEvent(
+          new CustomEvent("mutation-sync-complete", {
+            detail: { succeeded, failed, total, current: succeeded + failed },
+          })
+        );
+      }
     }
 
     window.dispatchEvent(
       new CustomEvent("mutation-sync-complete", {
-        detail: { succeeded, failed },
+        detail: { succeeded, failed, total },
       })
     );
   } finally {
@@ -159,7 +237,6 @@ export async function flushMutations()${R("Promise<void>")}{
   await processMutationQueue();
 }
 `;
-    // Helper functions appended outside the template string
     const helpers = `
 async function removeFromQueue(id${T("string")})${R("Promise<void>")}{
   const db = await openQueueDB();
@@ -191,6 +268,25 @@ export async function getPendingCount()${R("Promise<number>")}{
     request.onerror = () => reject((request${AS("IDBRequest")}).error);
   });
 }
+
+/** Get the position of a mutation in the queue (0-based). Returns -1 if not found. */
+export async function getQueuePosition(id${T("string")})${R("Promise<number>")}{
+  const items = await getQueueItems();
+  return items.findIndex((item) => item.id === id);
+}
+
+/** Get all pending queue items with their details. */
+export async function getQueueItems()${R("Promise<MutationQueueItem[]>")}{
+  const db = await openQueueDB();
+  const tx = db.transaction(STORE_NAME, "readonly");
+  const store = tx.objectStore(STORE_NAME);
+  const index = store.index("by-timestamp");
+  return new Promise${PT("MutationQueueItem[]")}((resolve, reject) => {
+    const request = index.getAll();
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error);
+  });
+}
 `;
     writeFile(ctx, `mutation-queue.${ext}`, code + helpers);
 }

package/dist/lib/generators/file-generators/mutation-queue.js.map

@@ -1 +1 @@
-{"version":3,"file":"mutation-queue.js","sourceRoot":"","sources":["../../../../src/lib/generators/file-generators/mutation-queue.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAoB,SAAS,EAAE,MAAM,cAAc,CAAC;AAE3D,MAAM,UAAU,qBAAqB,CAAC,GAAqB;IACzD,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC;IACpB,MAAM,EAAE,GAAG,GAAG,KAAK,IAAI,CAAC;IACxB,MAAM,CAAC,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACpD,MAAM,CAAC,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACtD,MAAM,EAAE,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACrD,MAAM,EAAE,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACvD,MAAM,WAAW,GAAG,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC;IAErD,MAAM,WAAW,GAAG,WAAW;QAC7B,CAAC,CAAC,yCAAyC,GAAG;CACjD;QACG,CAAC,CAAC,EAAE,CAAC;IAEP,MAAM,iBAAiB,GAAG,6CAA6C,GAAG;EAC1E,EAAE,CAAC,CAAC,CAAC;CACN,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IAEP,MAAM,eAAe,GAAG,WAAW;QACjC,CAAC,CAAC;oBACc,CAAC,CAAC,wBAAwB,CAAC;CAC9C;QACG,CAAC,CAAC,EAAE,CAAC;IAEP,MAAM,iBAAiB,GAAG,WAAW;QACnC,CAAC,CAAC,4BAA4B;QAC9B,CAAC,CAAC,EAAE,CAAC;IAEP,MAAM,IAAI,GAAG;;;;;oHAKqG,GAAG;;;;;;;;;;;;;;;;EAgBrH,WAAW,GAAG,iBAAiB;;;;wBAIT,CAAC,CAAC,sBAAsB,CAAC;sBAC3B,EAAE,CAAC,aAAa,CAAC;;;4BAGX,EAAE,CAAC,kBAAkB,CAAC;;;;;;kDAMA,EAAE,CAAC,kBAAkB,CAAC;+CACzB,EAAE,CAAC,YAAY,CAAC;;;;;;;8CAOjB,CAAC,CAAC,4BAA4B,CAAC,IAAI,CAAC,CAAC,eAAe,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;8CAyBrD,CAAC,CAAC,eAAe,CAAC;;;;;EAK9D,eAAe;;;;iBAIA,CAAC,CAAC,qBAAqB,CAAC,uBAAuB,EAAE,CAAC,qBAAqB,CAAC;;;;;;;;;;;;;;;;;;;;;EAqBvF,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wCAgCqB,CAAC,CAAC,eAAe,CAAC;;;CAGzD,CAAC;IAEA,wDAAwD;IACxD,MAAM,OAAO,GAAG;mCACiB,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,eAAe,CAAC;;;;qBAI/C,EAAE,CAAC,MAAM,CAAC;;;;;;mCAMI,CAAC,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC,eAAe,CAAC;;;;qBAI1D,EAAE,CAAC,MAAM,CAAC;;;;;;;yCAOU,CAAC,CAAC,iBAAiB,CAAC;;sBAEvC,EAAE,CAAC,QAAQ,CAAC;;;gDAGc,EAAE,CAAC,oBAAoB,CAAC;6CAC3B,EAAE,CAAC,YAAY,CAAC;;;CAG5D,CAAC;IAEA,SAAS,CAAC,GAAG,EAAE,kBAAkB,GAAG,EAAE,EAAE,IAAI,GAAG,OAAO,CAAC,CAAC;AAC1D,CAAC"}
+{"version":3,"file":"mutation-queue.js","sourceRoot":"","sources":["../../../../src/lib/generators/file-generators/mutation-queue.ts"],"names":[],"mappings":"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"}

package/dist/lib/generators/file-generators/mutation-state.js

@@ -0,0 +1,126 @@
+/**
+ * Generates mutation-state.ts/js — per-mutation state tracking.
+ * Provides a lightweight store for tracking individual mutation lifecycle states,
+ * enabling useMutation-style hooks and fine-grained mutation status UI.
+ */
+import { writeFile } from "./context.js";
+export function generateMutationState(ctx) {
+    const ext = ctx.ext;
+    const ts = ext === "ts";
+    const T = (type) => (ts ? `: ${type}` : "");
+    const R = (type) => (ts ? `: ${type}` : " ");
+    const code = `/**
+ * Swoff Mutation State
+ * Lightweight in-memory mutation state tracker.
+ * Enables per-mutation status UI (loading spinners, error states, success indicators).
+ *
+ * Usage:
+ *   import { trackMutation, getMutationState, clearMutationState } from './swoff/mutation-state.${ext}';
+ *
+ *   // After queueing a mutation
+ *   const id = "mutation-" + crypto.randomUUID();
+ *   trackMutation(id, "pending");
+ *
+ *   // Check state later
+ *   const state = getMutationState(id);
+ *   if (state?.status === "error") { showError(state.error); }
+ *
+ *   // Clear when done
+ *   clearMutationState(id);
+ */
+
+export type MutationStatus = "idle" | "pending" | "success" | "error";
+
+export interface MutationState {
+  id${T("string")};
+  status${T("MutationStatus")};
+  error${T("Error | null")};
+  data${T("unknown")};
+  timestamp${T("number")};
+}
+
+const mutations = new Map<string, MutationState>();
+
+let listenerId = 0;
+const listeners = new Map<number, (state: MutationState) => void>();
+
+/** Track a mutation with the given ID and initial status. */
+export function trackMutation(id${T("string")}, status${T("MutationStatus")} = "idle")${R("MutationState")}{
+  let state = mutations.get(id);
+  if (!state) {
+    state = { id, status, error: null, data: null, timestamp: Date.now() };
+    mutations.set(id, state);
+  } else {
+    state.status = status;
+    state.timestamp = Date.now();
+  }
+  notifyListeners(state);
+  window.dispatchEvent(new CustomEvent("mutation-state-changed", { detail: state }));
+  return state;
+}
+
+/** Update an existing mutation's state. */
+export function updateMutationState(id${T("string")}, partial${T("Partial<MutationState>")})${R("MutationState | null")}{
+  const state = mutations.get(id);
+  if (!state) return null;
+  Object.assign(state, partial);
+  state.timestamp = Date.now();
+  notifyListeners(state);
+  window.dispatchEvent(new CustomEvent("mutation-state-changed", { detail: state }));
+  return state;
+}
+
+/** Mark a mutation as successful with optional data. */
+export function resolveMutation(id${T("string")}, data${T("unknown")} = null)${R("void")}{
+  updateMutationState(id, { status: "success", data, error: null });
+}
+
+/** Mark a mutation as failed with an error. */
+export function rejectMutation(id${T("string")}, error${T("Error")})${R("void")}{
+  updateMutationState(id, { status: "error", error });
+}
+
+/** Get the current state of a mutation by ID. */
+export function getMutationState(id${T("string")})${R("MutationState | undefined")}{
+  return mutations.get(id);
+}
+
+/** Remove a mutation's state from the tracker. */
+export function clearMutationState(id${T("string")})${R("void")}{
+  mutations.delete(id);
+}
+
+/** Get all tracked mutations. */
+export function getAllMutationStates()${R("MutationState[]")}{
+  return Array.from(mutations.values());
+}
+
+/** Get the count of mutations in a given status. */
+export function getMutationCount(status${T("MutationStatus")})${R("number")}{
+  let count = 0;
+  for (const state of mutations.values()) {
+    if (state.status === status) count++;
+  }
+  return count;
+}
+
+/** Subscribe to mutation state changes. Returns an unsubscribe function. */
+export function onMutationStateChange(callback${T("(state: MutationState) => void")})${R("() => void")}{
+  const id = ++listenerId;
+  listeners.set(id, callback);
+  return () => { listeners.delete(id); };
+}
+
+function notifyListeners(state${T("MutationState")})${R("void")}{
+  for (const cb of listeners.values()) {
+    try {
+      cb(state);
+    } catch {
+      // Handle listener errors silently
+    }
+  }
+}
+`;
+    writeFile(ctx, `mutation-state.${ext}`, code);
+}
+//# sourceMappingURL=mutation-state.js.map

package/dist/lib/generators/file-generators/mutation-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutation-state.js","sourceRoot":"","sources":["../../../../src/lib/generators/file-generators/mutation-state.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAoB,SAAS,EAAE,MAAM,cAAc,CAAC;AAE3D,MAAM,UAAU,qBAAqB,CAAC,GAAqB;IACzD,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC;IACpB,MAAM,EAAE,GAAG,GAAG,KAAK,IAAI,CAAC;IACxB,MAAM,CAAC,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACpD,MAAM,CAAC,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAErD,MAAM,IAAI,GAAG;;;;;;mGAMoF,GAAG;;;;;;;;;;;;;;;;;MAiBhG,CAAC,CAAC,QAAQ,CAAC;UACP,CAAC,CAAC,gBAAgB,CAAC;SACpB,CAAC,CAAC,cAAc,CAAC;QAClB,CAAC,CAAC,SAAS,CAAC;aACP,CAAC,CAAC,QAAQ,CAAC;;;;;;;;;kCASU,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,gBAAgB,CAAC,aAAa,CAAC,CAAC,eAAe,CAAC;;;;;;;;;;;;;;;wCAelE,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,wBAAwB,CAAC,IAAI,CAAC,CAAC,sBAAsB,CAAC;;;;;;;;;;;oCAWnF,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC;;;;;mCAKrD,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;;;;;qCAK1C,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,2BAA2B,CAAC;;;;;uCAK3C,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;;;;;wCAKvB,CAAC,CAAC,iBAAiB,CAAC;;;;;yCAKnB,CAAC,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC;;;;;;;;;gDAS3B,CAAC,CAAC,gCAAgC,CAAC,IAAI,CAAC,CAAC,YAAY,CAAC;;;;;;gCAMtE,CAAC,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;;;;;;;;;CAS9D,CAAC;IAEA,SAAS,CAAC,GAAG,EAAE,kBAAkB,GAAG,EAAE,EAAE,IAAI,CAAC,CAAC;AAChD,CAAC"}

package/dist/lib/generators/file-generators/push.js

@@ -0,0 +1,143 @@
+/**
+ * Generates push.{js|ts} - push notification subscription management.
+ */
+import { writeFile } from "./context.js";
+export function generatePush(ctx) {
+    const ext = ctx.ext;
+    const ts = ext === "ts";
+    const T = (type) => (ts ? `: ${type}` : "");
+    const R = (type) => (ts ? `: ${type} ` : " ");
+    const PT = (type) => (ts ? `<${type}>` : "");
+    const AS = (type) => (ts ? ` as ${type}` : "");
+    const code = `/**
+ * Swoff Push Notifications
+ * Push subscription management with IndexedDB persistence.
+ *
+ * Usage:
+ *   import { subscribeToPush, unsubscribeFromPush, isSubscribed } from './swoff/push.${ext}';
+ *
+ *   // Enable (triggers permission prompt)
+ *   const subscription = await subscribeToPush("YOUR_VAPID_PUBLIC_KEY");
+ *   await fetch("/api/push/subscribe", {
+ *     method: "POST",
+ *     body: JSON.stringify(subscription.toJSON()),
+ *   });
+ *
+ *   // Disable
+ *   await unsubscribeFromPush();
+ *
+ * Window events:
+ *   push-permission-changed   - Permission granted/denied (detail: { permission })
+ *   push-subscription-changed - Subscribed/unsubscribed (detail: { subscribed })
+ */
+
+const SUBSCRIPTION_DB = "swoff-push";
+const SUBSCRIPTION_STORE = "subscription";
+
+let permissionState = Notification.permission;
+
+function openPushDB()${R("Promise<IDBDatabase>")}{
+  return new Promise${PT("IDBDatabase")}((resolve, reject) => {
+    const request = indexedDB.open(SUBSCRIPTION_DB, 1);
+    request.onupgradeneeded = (e) => {
+      const db = (e.target${AS("IDBOpenDBRequest")}).result;
+      if (!db.objectStoreNames.contains(SUBSCRIPTION_STORE)) {
+        db.createObjectStore(SUBSCRIPTION_STORE, { keyPath: "id" });
+      }
+    };
+    request.onsuccess = (e) => resolve((e.target${AS("IDBOpenDBRequest")}).result);
+    request.onerror = (e) => reject((e.target${AS("IDBRequest")}).error);
+  });
+}
+
+/** Request notification permission from the user. Returns true if granted. */
+export async function requestNotificationPermission()${R("Promise<boolean>")}{
+  if (permissionState === "granted") return true;
+  if (permissionState === "denied") return false;
+
+  const result = await Notification.requestPermission();
+  permissionState = result;
+  window.dispatchEvent(
+    new CustomEvent("push-permission-changed", { detail: { permission: result } }),
+  );
+  return result === "granted";
+}
+
+/** Get the current push subscription, or null if not subscribed. */
+export async function getPushSubscription()${R("Promise<PushSubscription | null>")}{
+  try {
+    const registration = await navigator.serviceWorker.ready;
+    return await registration.pushManager.getSubscription();
+  } catch {
+    return null;
+  }
+}
+
+/** Subscribe to push notifications. Returns the subscription or null if permission denied. */
+export async function subscribeToPush(vapidPublicKey${T("string")})${R("Promise<PushSubscription | null>")}{
+  const granted = await requestNotificationPermission();
+  if (!granted) return null;
+
+  const registration = await navigator.serviceWorker.ready;
+  const subscription = await registration.pushManager.subscribe({
+    userVisibleOnly: true,
+    applicationServerKey: urlBase64ToUint8Array(vapidPublicKey)${AS("BufferSource")},
+  });
+
+  const db = await openPushDB();
+  const tx = db.transaction(SUBSCRIPTION_STORE, "readwrite");
+  tx.objectStore(SUBSCRIPTION_STORE).put({
+    id: "current",
+    endpoint: subscription.endpoint,
+    keys: subscription.toJSON().keys,
+    subscribedAt: Date.now(),
+  });
+  await new Promise<void>((resolve, reject) => {
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error);
+  });
+
+  window.dispatchEvent(
+    new CustomEvent("push-subscription-changed", { detail: { subscribed: true } }),
+  );
+
+  return subscription;
+}
+
+/** Unsubscribe from push notifications. */
+export async function unsubscribeFromPush()${R("Promise<void>")}{
+  const subscription = await getPushSubscription();
+  if (!subscription) return;
+
+  await subscription.unsubscribe();
+
+  const db = await openPushDB();
+  const tx = db.transaction(SUBSCRIPTION_STORE, "readwrite");
+  tx.objectStore(SUBSCRIPTION_STORE).delete("current");
+  await new Promise<void>((resolve, reject) => {
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error);
+  });
+
+  window.dispatchEvent(
+    new CustomEvent("push-subscription-changed", { detail: { subscribed: false } }),
+  );
+}
+
+/** Check if the user is subscribed to push notifications. */
+export async function isSubscribed()${R("Promise<boolean>")}{
+  const sub = await getPushSubscription();
+  return sub !== null;
+}
+
+/** Convert a base64 VAPID public key to a Uint8Array for pushManager.subscribe(). */
+function urlBase64ToUint8Array(base64String${T("string")})${R("Uint8Array")}{
+  const padding = "=".repeat((4 - (base64String.length % 4)) % 4);
+  const base64 = (base64String + padding).replace(/-/g, "+").replace(/_/g, "/");
+  const rawData = atob(base64);
+  return Uint8Array.from(rawData, (c) => c.charCodeAt(0));
+}
+`;
+    writeFile(ctx, `push.${ext}`, code);
+}
+//# sourceMappingURL=push.js.map

package/dist/lib/generators/file-generators/push.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"push.js","sourceRoot":"","sources":["../../../../src/lib/generators/file-generators/push.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAoB,SAAS,EAAE,MAAM,cAAc,CAAC;AAE3D,MAAM,UAAU,YAAY,CAAC,GAAqB;IAChD,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC;IACpB,MAAM,EAAE,GAAG,GAAG,KAAK,IAAI,CAAC;IACxB,MAAM,CAAC,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACpD,MAAM,CAAC,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACtD,MAAM,EAAE,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACrD,MAAM,EAAE,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAEvD,MAAM,IAAI,GAAG;;;;;wFAKyE,GAAG;;;;;;;;;;;;;;;;;;;;;;uBAsBpE,CAAC,CAAC,sBAAsB,CAAC;sBAC1B,EAAE,CAAC,aAAa,CAAC;;;4BAGX,EAAE,CAAC,kBAAkB,CAAC;;;;;kDAKA,EAAE,CAAC,kBAAkB,CAAC;+CACzB,EAAE,CAAC,YAAY,CAAC;;;;;uDAKR,CAAC,CAAC,kBAAkB,CAAC;;;;;;;;;;;;;6CAa/B,CAAC,CAAC,kCAAkC,CAAC;;;;;;;;;;sDAU5B,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,kCAAkC,CAAC;;;;;;;iEAOzC,EAAE,CAAC,cAAc,CAAC;;;;;;;;;;;;;;;;;;;;;;;;6CAwBtC,CAAC,CAAC,eAAe,CAAC;;;;;;;;;;;;;;;;;;;;sCAoBzB,CAAC,CAAC,kBAAkB,CAAC;;;;;;6CAMd,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,YAAY,CAAC;;;;;;CAM1E,CAAC;IAEA,SAAS,CAAC,GAAG,EAAE,QAAQ,GAAG,EAAE,EAAE,IAAI,CAAC,CAAC;AACtC,CAAC"}

package/dist/lib/generators/file-generators/quick-readme.js

@@ -11,7 +11,7 @@ export function generateReadme(ctx) {
     w("");
     w("For the full guide with explanations, read **[GUIDE.md](./GUIDE.md)**.");
     w("");
-    const hasClientInjector = config.features.clientRegistration || config.features.pwa.enabled || config.features.crossTabSync;
+    const hasClientInjector = true;
     if (hasClientInjector) {
         w("## Entry point");
         w("```ts");
@@ -21,6 +21,8 @@ export function generateReadme(ctx) {
         w("");
     }
     w("## API calls (use for all fetch requests)");
+    w("Use `fetchWithCache` instead of `fetch()` — it sets caching headers the SW needs.");
+    w("Plain `fetch()` skips SW caching when `cacheStrategy` is `\"explicit-only\"`.");
     w("```ts");
     w(`import { fetchWithCache } from "./swoff/fetch-wrapper.${ext}";`);
     w('const data = await fetchWithCache("/api/data").then(r => r.json());');
@@ -29,12 +31,12 @@ export function generateReadme(ctx) {
     if (config.features.auth.enabled) {
         w("## Authenticated API calls");
         w("```ts");
-        w(`import { authenticatedFetch } from "./swoff/auth/fetch.${ext}";`);
-        w('const data = await authenticatedFetch("/api/me").then(r => r.json());');
+        w(`import { fetchWithCache } from "./swoff/fetch-wrapper.${ext}";`);
+        w('const data = await fetchWithCache("/api/me", { auth: true }).then(r => r.json());');
         w("```");
         w("");
     }
-    if (config.features.mutationQueue) {
+    if (config.features.mutationQueue.enabled) {
         w("## Offline mutations (queue writes when offline)");
         w("```ts");
         w(`import { queueMutation, getPendingCount } from "./swoff/mutation-queue.${ext}";`);
@@ -50,20 +52,78 @@ export function generateReadme(ctx) {
             w("");
         }
     }
-    if (config.features.tagInvalidation) {
-        w("## Cache invalidation");
+    if (config.features.graphql.enabled) {
+        w("## GraphQL (cached queries with body-hash)");
         w("```ts");
-        w(`import { generateTags, invalidateUrl } from "./swoff/invalidation-tags.${ext}";`);
-        w('const data = await fetchWithCache("/api/todos", { tags: generateTags("/api/todos") });');
-        w('await invalidateUrl("/api/todos/42"); // after mutation');
+        w(`import { queryGql, mutateGql } from "./swoff/gql-wrapper.${ext}";`);
+        w('const { data } = await queryGql("{ todos { id title } }");');
+        w('const { data: created } = await mutateGql(');
+        w('  "mutation CreateTodo($t: String!) { createTodo(title: $t) { id } }",');
+        w('  { t: "New task" },');
+        w(");");
+        w("```");
+        w("");
+    }
+    if (config.features.serverPush.enabled) {
+        w("## Server push events (real-time cache invalidation)");
+        w("```ts");
+        w(`import { startPushEvents } from "./swoff/server-push.${ext}";`);
+        w("startPushEvents();");
+        w("```");
+        w("");
+    }
+    if (config.features.pushNotifications?.enabled) {
+        w("## Push notifications");
+        w("```ts");
+        w(`import { subscribeToPush, unsubscribeFromPush, isSubscribed } from "./swoff/push.${ext}";`);
+        w('const sub = await subscribeToPush("YOUR_VAPID_PUBLIC_KEY");');
         w("```");
         w("");
     }
     if (ctx.frameworkName === "react") {
-        w("## React hook — auto-refetch on cache invalidation");
+        w("## React hooks");
         w("```tsx");
         w(`import { useCachedFetch } from "./swoff/hooks/useCachedFetch.${ext}x";`);
-        w('const { data, error, loading, refetch } = useCachedFetch("/api/todos");');
+        w(`import { useMutation } from "./swoff/hooks/useMutation.${ext}x";`);
+        w(`import { usePrefetch } from "./swoff/hooks/usePrefetch.${ext}x";`);
+        w(`import { useMutationState } from "./swoff/hooks/useMutationState.${ext}x";`);
+        w("");
+        w('const { data, error, loading, refetch } = useCachedFetch("/api/todos", {');
+        w('  refetchOnWindowFocus: true,');
+        w('});');
+        w("");
+        w('// Dependent query — skip until user is loaded');
+        w('const { data: posts } = useCachedFetch("/api/posts", { enabled: !!user });');
+        w("");
+        w('const { mutate } = useMutation({ onSuccess: (data) => console.log(data) });');
+        w('mutate("/api/todos", { method: "POST", body: JSON.stringify({ title: "New" }) });');
+        w("");
+        w('const prefetch = usePrefetch();');
+        w('prefetch("/api/todos");');
+        w("");
+        w('// Track a specific mutation by its returned id');
+        w('const mutation = useMutationState(mutationId);');
+        w("```");
+        w("");
+        if (config.features.mutationQueue.enabled) {
+            w("## Mutation queue hooks");
+            w("```tsx");
+            w(`import { useMutationQueue } from "./swoff/hooks/useMutationQueue.${ext}x";`);
+            w(`import { useMutationState } from "./swoff/hooks/useMutationState.${ext}x";`);
+            w("");
+            w('const { pending, items, lastSync } = useMutationQueue();');
+            w("// items: MutationQueueItem[] — each with id, url, method, status, retryCount");
+            w("// lastSync: { succeeded, failed } | null — result of the last sync attempt");
+            w("```");
+            w("");
+        }
+    }
+    if (config.features.tagInvalidation) {
+        w("## Cache invalidation");
+        w("```ts");
+        w(`import { generateTags, invalidateUrl } from "./swoff/invalidation-tags.${ext}";`);
+        w('const data = await fetchWithCache("/api/todos", { tags: generateTags("/api/todos") });');
+        w('await invalidateUrl("/api/todos/42"); // after mutation');
         w("```");
         w("");
     }