@jgamaraalv/ts-dev-kit 1.0.0

package/skills/service-worker/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: service-worker
+description: "Service Worker API implementation guide — registration, lifecycle management, caching strategies, push notifications, and background sync. Use when: (1) creating or modifying service worker files (sw.js), (2) implementing offline-first caching (cache-first, network-first, stale-while-revalidate), (3) setting up push notifications or background sync, (4) debugging service worker registration, scope, or update issues, (5) implementing navigation preload, (6) user mentions 'service worker', 'sw.js', 'offline support', 'cache strategy', 'push notification', 'background sync', 'workbox alternative', or 'PWA caching'."
+---
+
+# Service Worker
+
+## Table of Contents
+
+- [Constraints](#constraints)
+- [Lifecycle](#lifecycle)
+- [Registration](#registration)
+- [Install Event — Pre-cache Assets](#install-event--pre-cache-assets)
+- [Activate Event — Clean Up Old Caches](#activate-event--clean-up-old-caches)
+- [Fetch Event — Intercept Requests](#fetch-event--intercept-requests)
+- [Navigation Preload](#navigation-preload)
+- [Updating a Service Worker](#updating-a-service-worker)
+- [Communicating with Pages](#communicating-with-pages)
+- [Common Pitfalls](#common-pitfalls)
+- [Push Notifications & Background Sync](#push-notifications--background-sync)
+- [API Quick Reference](#api-quick-reference)
+- [Next.js Integration](#nextjs-integration)
+- [DevTools](#devtools)
+
+## Constraints
+
+- HTTPS required (localhost exempt for dev)
+- No DOM access — runs on separate thread
+- Fully async — no synchronous XHR, no localStorage
+- No dynamic `import()` — only static `import` statements
+- Scope defaults to the directory containing the SW file
+- `self` refers to `ServiceWorkerGlobalScope`
+
+## Lifecycle
+
+```
+register() → Download → Install → [Wait] → Activate → Fetch control
+```
+
+1. **Register** from main thread via `navigator.serviceWorker.register()`
+2. **Install** event fires once — use to pre-cache static assets
+3. **Wait** — new SW waits until all tabs using old SW are closed (skip with `self.skipWaiting()`)
+4. **Activate** event fires — use to clean up old caches
+5. **Fetch** events start flowing — SW controls page network requests
+
+A document must reload to be controlled (or call `clients.claim()` during activate).
+
+## Registration
+
+```js
+// main.js — register from the page
+if ("serviceWorker" in navigator) {
+  const reg = await navigator.serviceWorker.register("/sw.js", { scope: "/" });
+  // reg.installing | reg.waiting | reg.active
+}
+```
+
+**Scope rules:**
+
+- SW at `/sw.js` can control `/` and all subpaths
+- SW at `/app/sw.js` can only control `/app/` by default
+- Broaden scope with `Service-Worker-Allowed` response header
+
+## Install Event — Pre-cache Assets
+
+```js
+// sw.js
+const CACHE_NAME = "v1";
+const PRECACHE_URLS = ["/", "/index.html", "/style.css", "/app.js"];
+
+self.addEventListener("install", (event) => {
+  event.waitUntil(caches.open(CACHE_NAME).then((cache) => cache.addAll(PRECACHE_URLS)));
+});
+```
+
+`waitUntil(promise)` — keeps install phase alive until the promise settles. If rejected, installation fails and the SW won't activate.
+
+## Activate Event — Clean Up Old Caches
+
+```js
+self.addEventListener("activate", (event) => {
+  event.waitUntil(
+    caches
+      .keys()
+      .then((keys) =>
+        Promise.all(keys.filter((key) => key !== CACHE_NAME).map((key) => caches.delete(key))),
+      ),
+  );
+});
+```
+
+## Fetch Event — Intercept Requests
+
+```js
+self.addEventListener("fetch", (event) => {
+  event.respondWith(caches.match(event.request).then((cached) => cached || fetch(event.request)));
+});
+```
+
+`respondWith(promise)` — must be called synchronously (within the event handler, not in a microtask). The promise resolves to a `Response`.
+
+For caching strategy patterns (cache-first, network-first, stale-while-revalidate), see [references/caching-strategies.md](references/caching-strategies.md).
+
+## Navigation Preload
+
+Avoid the startup delay when a SW boots to handle a navigation:
+
+```js
+self.addEventListener("activate", (event) => {
+  event.waitUntil(self.registration?.navigationPreload.enable());
+});
+
+self.addEventListener("fetch", (event) => {
+  event.respondWith(
+    (async () => {
+      const cached = await caches.match(event.request);
+      if (cached) return cached;
+
+      const preloaded = await event.preloadResponse;
+      if (preloaded) return preloaded;
+
+      return fetch(event.request);
+    })(),
+  );
+});
+```
+
+## Updating a Service Worker
+
+- Browser byte-compares the SW file on each navigation (or every 24h)
+- New version installs in background while old version still serves
+- Increment the cache name (e.g., `v1` → `v2`) in the new version
+- Delete old caches in the `activate` handler
+- Call `self.skipWaiting()` in `install` to activate immediately
+- Call `self.clients.claim()` in `activate` to take control of open pages
+
+## Communicating with Pages
+
+```js
+// Page → SW
+navigator.serviceWorker.controller.postMessage({ type: "SKIP_WAITING" });
+
+// SW → Page (via Clients API)
+const clients = await self.clients.matchAll({ type: "window" });
+clients.forEach((client) => client.postMessage({ type: "UPDATED" }));
+
+// SW listens
+self.addEventListener("message", (event) => {
+  if (event.data?.type === "SKIP_WAITING") self.skipWaiting();
+});
+```
+
+## Common Pitfalls
+
+1. **Response cloning** — `response.clone()` before both caching and returning, since body streams can only be read once
+2. **Opaque responses** — cross-origin fetches without CORS return opaque responses (status 0). `cache.add()` will refuse them. Use `cache.put()` but you can't inspect the response
+3. **waitUntil timing** — call `event.waitUntil()` synchronously within the event handler, not inside an async callback
+4. **Scope ceiling** — a SW cannot control URLs above its own directory unless `Service-Worker-Allowed` header is set
+5. **No state persistence** — the SW may terminate at any time when idle. Don't store state in global variables — use Cache API or IndexedDB
+
+## Push Notifications & Background Sync
+
+For push subscription, handling push events, and background sync implementation, see [references/push-and-sync.md](references/push-and-sync.md).
+
+## API Quick Reference
+
+For detailed interfaces (`Cache`, `CacheStorage`, `FetchEvent`, `Clients`, `ServiceWorkerRegistration`, `ServiceWorkerGlobalScope`), see [references/api-reference.md](references/api-reference.md).
+
+## Next.js Integration
+
+In Next.js, place the service worker file in `public/sw.js`. `public/sw.js` is intentionally plain JS (not processed by Next.js build pipeline). Register it from a client component:
+
+```tsx
+"use client";
+import { useEffect } from "react";
+
+export function ServiceWorkerRegistrar() {
+  useEffect(() => {
+    if ("serviceWorker" in navigator) {
+      navigator.serviceWorker.register("/sw.js");
+    }
+  }, []);
+  return null;
+}
+```
+
+Add to root layout. Next.js serves `public/` files at the root, so `/sw.js` scope covers `/`.
+
+## DevTools
+
+- **Chrome**: `chrome://inspect/#service-workers` or Application > Service Workers
+- **Firefox**: `about:debugging#/runtime/this-firefox` or Application > Service Workers
+- **Edge**: `edge://inspect/#service-workers` or Application > Service Workers
+
+Unregister, update, and inspect caches from the Application panel. Use "Update on reload" checkbox during development.

package/skills/service-worker/references/api-reference.md

@@ -0,0 +1,114 @@
+# Service Worker API Reference
+
+## Table of Contents
+
+- [Cache](#cache)
+- [CacheStorage (caches)](#cachestorage)
+- [FetchEvent](#fetchevent)
+- [Clients](#clients)
+- [Client / WindowClient](#client--windowclient)
+
+## Cache
+
+A single named cache. Stores `Request`/`Response` pairs.
+
+### Methods
+
+| Method                         | Returns                          | Description                        |
+| ------------------------------ | -------------------------------- | ---------------------------------- |
+| `match(request, options?)`     | `Promise<Response \| undefined>` | Find first matching response       |
+| `matchAll(request?, options?)` | `Promise<Response[]>`            | Find all matching responses        |
+| `add(request)`                 | `Promise<void>`                  | Fetch URL and cache the response   |
+| `addAll(requests)`             | `Promise<void>`                  | Fetch all URLs and cache responses |
+| `put(request, response)`       | `Promise<void>`                  | Store a request/response pair      |
+| `delete(request, options?)`    | `Promise<boolean>`               | Remove a cached entry              |
+| `keys(request?, options?)`     | `Promise<Request[]>`             | List cached requests               |
+
+**Match options:** `{ ignoreSearch, ignoreMethod, ignoreVary }`
+
+**Notes:**
+
+- `add()`/`addAll()` will reject for non-2xx responses
+- `put()` accepts any response (including opaque)
+- Always `response.clone()` before caching if you also need to return it
+- Cache API ignores HTTP caching headers
+- `Set-Cookie` headers are stripped from cached responses
+
+## CacheStorage
+
+Accessed via `caches` (global in SW and window).
+
+### Methods
+
+| Method                     | Returns                          | Description                 |
+| -------------------------- | -------------------------------- | --------------------------- |
+| `open(name)`               | `Promise<Cache>`                 | Open/create a named cache   |
+| `match(request, options?)` | `Promise<Response \| undefined>` | Search across all caches    |
+| `has(name)`                | `Promise<boolean>`               | Check if named cache exists |
+| `delete(name)`             | `Promise<boolean>`               | Delete a named cache        |
+| `keys()`                   | `Promise<string[]>`              | List all cache names        |
+
+## FetchEvent
+
+Passed to `fetch` event handlers. Only available in SW context.
+
+### Properties
+
+| Property            | Type                             | Description                               |
+| ------------------- | -------------------------------- | ----------------------------------------- |
+| `request`           | `Request`                        | The intercepted request                   |
+| `clientId`          | `string`                         | ID of the client that initiated the fetch |
+| `resultingClientId` | `string`                         | ID of the client being navigated to       |
+| `replacesClientId`  | `string`                         | ID of the client being replaced           |
+| `preloadResponse`   | `Promise<Response \| undefined>` | Navigation preload response               |
+| `handled`           | `Promise<void>`                  | Resolves when the event has been handled  |
+
+### Methods
+
+| Method                 | Description                                              |
+| ---------------------- | -------------------------------------------------------- |
+| `respondWith(promise)` | Provide a custom response. Must be called synchronously. |
+| `waitUntil(promise)`   | Extend event lifetime (inherited from ExtendableEvent)   |
+
+## Clients
+
+Access controlled pages from the SW. Available via `self.clients`.
+
+### Methods
+
+| Method               | Returns                         | Description                                                        |
+| -------------------- | ------------------------------- | ------------------------------------------------------------------ |
+| `get(id)`            | `Promise<Client \| undefined>`  | Get a client by ID                                                 |
+| `matchAll(options?)` | `Promise<Client[]>`             | Get all matching clients. Options: `{ type, includeUncontrolled }` |
+| `openWindow(url)`    | `Promise<WindowClient \| null>` | Open a new window/tab                                              |
+| `claim()`            | `Promise<void>`                 | Take control of all in-scope clients without reload                |
+
+## Client / WindowClient
+
+Represents a controlled page/worker.
+
+### Client Properties
+
+| Property | Type     | Description                              |
+| -------- | -------- | ---------------------------------------- |
+| `id`     | `string` | Unique identifier                        |
+| `type`   | `string` | `"window" \| "worker" \| "sharedworker"` |
+| `url`    | `string` | URL of the client                        |
+
+### Client Methods
+
+| Method                         | Description                |
+| ------------------------------ | -------------------------- |
+| `postMessage(data, transfer?)` | Send message to the client |
+
+### WindowClient (extends Client)
+
+| Property          | Type      | Description                   |
+| ----------------- | --------- | ----------------------------- |
+| `focused`         | `boolean` | Whether the window is focused |
+| `visibilityState` | `string`  | `"visible" \| "hidden"`       |
+
+| Method          | Returns                         | Description      |
+| --------------- | ------------------------------- | ---------------- |
+| `focus()`       | `Promise<WindowClient>`         | Focus the window |
+| `navigate(url)` | `Promise<WindowClient \| null>` | Navigate to URL  |

package/skills/service-worker/references/caching-strategies.md

@@ -0,0 +1,202 @@
+# Caching Strategies
+
+## Table of Contents
+
+- [Cache-First (Cache Falling Back to Network)](#cache-first)
+- [Network-First (Network Falling Back to Cache)](#network-first)
+- [Stale-While-Revalidate](#stale-while-revalidate)
+- [Cache-Only](#cache-only)
+- [Network-Only](#network-only)
+- [Dynamic Caching with Fallback](#dynamic-caching-with-fallback)
+- [Cache Versioning and Cleanup](#cache-versioning-and-cleanup)
+- [Strategy Selection Guide](#strategy-selection-guide)
+
+## Cache-First
+
+Best for: static assets (CSS, JS, images, fonts) that change infrequently.
+
+```js
+self.addEventListener("fetch", (event) => {
+  event.respondWith(
+    caches.match(event.request).then((cached) => {
+      if (cached) return cached;
+      return fetch(event.request).then((response) => {
+        // Cache new responses for future use
+        const clone = response.clone();
+        caches.open("static-v1").then((cache) => cache.put(event.request, clone));
+        return response;
+      });
+    }),
+  );
+});
+```
+
+## Network-First
+
+Best for: API calls, frequently updated content, HTML pages.
+
+```js
+const networkFirst = async (request, cacheName = "dynamic-v1") => {
+  try {
+    const response = await fetch(request);
+    const cache = await caches.open(cacheName);
+    cache.put(request, response.clone()); // update cache in background
+    return response;
+  } catch {
+    const cached = await caches.match(request);
+    if (cached) return cached;
+    return new Response("Offline", { status: 503, headers: { "Content-Type": "text/plain" } });
+  }
+};
+
+self.addEventListener("fetch", (event) => {
+  if (event.request.url.includes("/api/")) {
+    event.respondWith(networkFirst(event.request));
+  }
+});
+```
+
+## Stale-While-Revalidate
+
+Best for: resources where freshness matters but stale content is acceptable briefly (avatars, non-critical API data).
+
+```js
+self.addEventListener("fetch", (event) => {
+  const cache = caches.open("swr-v1");
+  const cached = cache.then((c) => c.match(event.request));
+  const fetched = fetch(event.request);
+  const fetchedCopy = fetched.then((r) => r.clone());
+
+  // Return cached immediately if available, race with network otherwise
+  event.respondWith(
+    Promise.race([fetched.catch(() => cached), cached])
+      .then((r) => r || fetched)
+      .catch(() => new Response("Offline", { status: 503 })),
+  );
+
+  // Keep SW alive until the cache is updated with the fresh response
+  event.waitUntil(Promise.all([cache, fetchedCopy]).then(([c, r]) => c.put(event.request, r)));
+});
+```
+
+**Important:** Always use `event.waitUntil()` around the cache update promise. Without it, the SW may terminate before the background fetch completes, and the cache will never be refreshed.
+
+## Cache-Only
+
+Best for: pre-cached assets during install that never change within a version.
+
+```js
+self.addEventListener("fetch", (event) => {
+  event.respondWith(caches.match(event.request));
+});
+```
+
+## Network-Only
+
+Best for: non-GET requests, analytics pings, real-time data. Typically just don't call `respondWith()`:
+
+```js
+self.addEventListener("fetch", (event) => {
+  // Non-GET → let browser handle normally
+  if (event.request.method !== "GET") return;
+  // Otherwise apply a cache strategy
+  event.respondWith(/* ... */);
+});
+```
+
+## Dynamic Caching with Fallback
+
+Complete pattern combining pre-cache, dynamic cache, and offline fallback:
+
+```js
+const CACHE_NAME = "app-v1";
+const PRECACHE = ["/", "/offline.html", "/style.css", "/app.js"];
+
+self.addEventListener("install", (event) => {
+  event.waitUntil(caches.open(CACHE_NAME).then((cache) => cache.addAll(PRECACHE)));
+});
+
+self.addEventListener("fetch", (event) => {
+  if (event.request.method !== "GET") return;
+
+  event.respondWith(
+    (async () => {
+      // 1. Check cache
+      const cached = await caches.match(event.request);
+      if (cached) return cached;
+
+      // 2. Try network
+      try {
+        const response = await fetch(event.request);
+        // Cache successful responses
+        if (response.ok) {
+          const cache = await caches.open(CACHE_NAME);
+          event.waitUntil(cache.put(event.request, response.clone()));
+        }
+        return response;
+      } catch {
+        // 3. Offline fallback for navigations
+        if (event.request.mode === "navigate") {
+          return caches.match("/offline.html");
+        }
+        return new Response("Offline", { status: 503 });
+      }
+    })(),
+  );
+});
+```
+
+## Cache Versioning and Cleanup
+
+Increment the cache name on each deploy. Delete stale caches during activate:
+
+```js
+const CACHE_VERSION = 2;
+const CACHES = {
+  static: `static-v${CACHE_VERSION}`,
+  dynamic: `dynamic-v${CACHE_VERSION}`,
+};
+
+self.addEventListener("activate", (event) => {
+  const keep = new Set(Object.values(CACHES));
+  event.waitUntil(
+    caches
+      .keys()
+      .then((keys) => Promise.all(keys.filter((k) => !keep.has(k)).map((k) => caches.delete(k)))),
+  );
+});
+```
+
+## Strategy Selection Guide
+
+| Content type              | Strategy                | Why                                |
+| ------------------------- | ----------------------- | ---------------------------------- |
+| App shell (HTML, CSS, JS) | Cache-first             | Instant load, update on next visit |
+| API responses             | Network-first           | Fresh data, offline fallback       |
+| User avatars, thumbnails  | Stale-while-revalidate  | Fast display, background update    |
+| Fonts, icons              | Cache-first             | Rarely change                      |
+| Analytics, real-time data | Network-only            | Must be fresh, no offline value    |
+| Critical offline page     | Cache-only (pre-cached) | Always available                   |
+
+### Per-route strategy pattern
+
+```js
+self.addEventListener("fetch", (event) => {
+  const { request } = event;
+  const url = new URL(request.url);
+
+  if (request.method !== "GET") return;
+
+  if (url.origin === location.origin) {
+    // Same-origin: cache-first for assets, network-first for HTML
+    if (request.destination === "document") {
+      event.respondWith(networkFirst(request));
+    } else {
+      event.respondWith(cacheFirst(request));
+    }
+  } else {
+    // Cross-origin: stale-while-revalidate
+    event.respondWith(staleWhileRevalidate(request));
+  }
+});
+```