@prabhask5/stellar-engine 1.1.7 → 1.1.9

package/dist/sw/build/vite-plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vite-plugin.d.ts","sourceRoot":"","sources":["../../../src/sw/build/vite-plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAWH,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AA8CD;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,QAAQ;;;;EAqE1C"}
+{"version":3,"file":"vite-plugin.d.ts","sourceRoot":"","sources":["../../../src/sw/build/vite-plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAWH;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAmED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,QAAQ;;;;EAyE1C"}

package/dist/sw/build/vite-plugin.js

@@ -2,9 +2,30 @@
  * @fileoverview Vite plugin that generates the service worker and asset manifest
  * at build time. Projects import this instead of maintaining their own SW logic.
  *
- * Usage in vite.config.ts:
- *   import { stellarPWA } from '@prabhask5/stellar-engine/vite';
- *   export default defineConfig({ plugins: [sveltekit(), stellarPWA({ prefix: 'myapp', name: 'My App' })] });
+ * The plugin hooks into two Vite/Rollup lifecycle events:
+ *   - **`buildStart`** — reads the compiled SW template from the stellar-engine
+ *     package, patches in app-specific tokens, and writes `static/sw.js`.
+ *   - **`closeBundle`** — after Rollup finishes writing chunks, scans the
+ *     immutable output directory and writes `asset-manifest.json` listing
+ *     all JS/CSS files for the service worker to precache.
+ *
+ * @example
+ * ```ts
+ * // vite.config.ts
+ * import { sveltekit } from '@sveltejs/kit/vite';
+ * import { stellarPWA } from '@prabhask5/stellar-engine/vite';
+ * import { defineConfig } from 'vite';
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     sveltekit(),
+ *     stellarPWA({ prefix: 'myapp', name: 'My App' })
+ *   ]
+ * });
+ * ```
+ *
+ * @see {@link stellarPWA} for the main plugin factory
+ * @see {@link SWConfig} for configuration options
  */
 import { readFileSync, writeFileSync, readdirSync, statSync, existsSync, mkdirSync } from 'fs';
 import { resolve, join, dirname } from 'path';
@@ -18,6 +39,16 @@ import { createRequire } from 'module';
  *
  * Used after the build to enumerate all immutable assets so they can be written
  * into the asset manifest consumed by the service worker.
+ *
+ * @param dir - The root directory to scan.
+ * @param files - Accumulator array (used internally for recursion).
+ * @returns A flat array of absolute file paths found under `dir`.
+ *
+ * @example
+ * ```ts
+ * const allFiles = getAllFiles('/path/to/_app/immutable');
+ * // => ['/path/to/_app/immutable/chunks/foo.abc123.js', ...]
+ * ```
  */
 function getAllFiles(dir, files = []) {
     if (!existsSync(dir))
@@ -36,15 +67,26 @@ function getAllFiles(dir, files = []) {
 }
 /**
  * Locates the compiled SW source (`dist/sw/sw.js`) within the installed package.
- * Works whether the package is installed in node_modules or linked locally.
+ *
+ * Uses two resolution strategies:
+ *   1. **Relative resolution** — resolves relative to this file's compiled
+ *      location in `dist/sw/build/vite-plugin.js`, navigating up to `dist/sw/sw.js`.
+ *      Works for both installed packages and locally-linked development.
+ *   2. **`createRequire` fallback** — uses Node's module resolution to find
+ *      the package root via `package.json`, then appends the known dist path.
+ *
+ * @returns The absolute path to the compiled `sw.js` source file.
+ *
+ * @throws {Error} If the SW source cannot be found via either strategy
+ *         (will throw from the `readFileSync` call in the consumer).
  */
 function findSwSource() {
-    // Resolve relative to this file's location in dist/sw/build/vite-plugin.js
+    /* Resolve relative to this file's location in dist/sw/build/vite-plugin.js */
     const thisDir = dirname(fileURLToPath(import.meta.url));
     const swPath = join(thisDir, '..', 'sw.js');
     if (existsSync(swPath))
         return swPath;
-    // Fallback: use createRequire to resolve from the package
+    /* Fallback: use createRequire to resolve from the package */
     const require = createRequire(import.meta.url);
     const pkgDir = dirname(require.resolve('@prabhask5/stellar-engine/package.json'));
     return join(pkgDir, 'dist', 'sw', 'sw.js');
@@ -53,32 +95,46 @@ function findSwSource() {
 //                           VITE PLUGIN
 // =============================================================================
 /**
- * Vite plugin that generates `static/sw.js` and `asset-manifest.json` at build time.
+ * Vite plugin factory that generates `static/sw.js` and `asset-manifest.json`
+ * at build time.
+ *
+ * **`buildStart` hook:**
+ *   - Reads the compiled SW source from stellar-engine's `dist/sw/sw.js`.
+ *   - Replaces placeholder tokens (`__SW_VERSION__`, `__SW_PREFIX__`, `__SW_NAME__`)
+ *     with app-specific values and a unique version stamp (base-36 timestamp).
+ *   - Strips the `export {};` that TypeScript adds (SW runs as a classic script).
+ *   - Writes the final `static/sw.js`.
+ *
+ * **`closeBundle` hook:**
+ *   - Scans SvelteKit's immutable output directory for JS and CSS files.
+ *   - Writes `asset-manifest.json` to both `static/` and the build output
+ *     directory so the service worker can precache all app chunks.
  *
- * - **`buildStart` hook**: Reads the compiled SW source from stellar-engine,
- *   replaces placeholder tokens with app-specific values and a unique version
- *   stamp, then writes the final `static/sw.js`.
+ * @param config - The {@link SWConfig} with `prefix` and `name` values.
+ * @returns A Vite plugin object with `name`, `buildStart`, and `closeBundle` hooks.
  *
- * - **`closeBundle` hook**: After Rollup finishes writing chunks, scans the immutable
- *   output directory and writes `asset-manifest.json` listing all JS/CSS files for
- *   the service worker to precache.
+ * @example
+ * ```ts
+ * stellarPWA({ prefix: 'myapp', name: 'My App' })
+ * ```
  */
 export function stellarPWA(config) {
     return {
         name: 'stellar-pwa',
         /* ── buildStart — generate sw.js from compiled source ────────── */
         buildStart() {
+            /* Generate a unique version stamp using base-36 timestamp */
             const version = Date.now().toString(36);
             const swSourcePath = findSwSource();
             let swContent = readFileSync(swSourcePath, 'utf-8');
-            // Replace placeholder tokens with app-specific values
+            /* Replace placeholder tokens with app-specific values */
             swContent = swContent
                 .replace(/__SW_VERSION__/g, version)
                 .replace(/__SW_PREFIX__/g, config.prefix)
                 .replace(/__SW_NAME__/g, config.name);
-            // Strip the `export {};` that tsc adds (SW runs as a script, not a module)
+            /* Strip the `export {};` that tsc adds (SW runs as a script, not a module) */
             swContent = swContent.replace(/^export\s*\{\s*\}\s*;\s*$/m, '');
-            // Ensure static/ directory exists
+            /* Ensure static/ directory exists */
             const staticDir = resolve('static');
             if (!existsSync(staticDir)) {
                 mkdirSync(staticDir, { recursive: true });
@@ -98,7 +154,8 @@ export function stellarPWA(config) {
                 const allFiles = getAllFiles(buildDir);
                 /**
                  * Only JS and CSS are worth precaching — images/fonts are better
-                 * served on-demand via the SW's cache-first strategy.
+                 * served on-demand via the SW's cache-first strategy, keeping the
+                 * manifest small and the initial precache fast.
                  */
                 const assets = allFiles
                     .map((f) => f.replace(resolve('.svelte-kit/output/client'), ''))
@@ -110,7 +167,9 @@ export function stellarPWA(config) {
                 const manifestContent = JSON.stringify(manifest, null, 2);
                 /* Write to `static/` — available to the dev server and future builds */
                 writeFileSync(resolve('static/asset-manifest.json'), manifestContent);
-                /* Write to build output — static files are already copied before `closeBundle` runs */
+                /* Write to build output — static files are already copied before
+                 * `closeBundle` runs, so the manifest must also land in the output
+                 * directory for it to be served from the production build. */
                 const buildOutputPath = resolve('.svelte-kit/output/client/asset-manifest.json');
                 writeFileSync(buildOutputPath, manifestContent);
                 console.log(`[stellar-pwa] Generated asset manifest with ${assets.length} files`);

package/dist/sw/build/vite-plugin.js.map

@@ -1 +1 @@
-{"version":3,"file":"vite-plugin.js","sourceRoot":"","sources":["../../../src/sw/build/vite-plugin.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"vite-plugin.js","sourceRoot":"","sources":["../../../src/sw/build/vite-plugin.ts"],"names":[],"mappings":"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"}

package/dist/sw/sw.js

@@ -24,25 +24,36 @@
  *
  * The `APP_VERSION` constant is patched automatically by the stellarPWA
  * Vite plugin on every production build.
+ *
+ * @see {@link handleNavigationRequest} for HTML page caching (network-first)
+ * @see {@link handleImmutableAsset} for content-hashed asset caching (cache-first)
+ * @see {@link handleStaticAsset} for general static asset caching (cache-first)
+ * @see {@link backgroundPrecache} for offline-readiness precaching
+ * @see {@link cleanupOldAssets} for stale immutable asset removal
  */
 // =============================================================================
 //                              VERSIONING
 // =============================================================================
-/** Build-stamped version — updated automatically by the stellarPWA Vite plugin on each build */
+/**
+ * Build-stamped version string — updated automatically by the stellarPWA
+ * Vite plugin on each build. Used to key the shell cache and reported
+ * back to clients via the `GET_VERSION` message handler.
+ */
 const APP_VERSION = '__SW_VERSION__';
 // =============================================================================
 //                            CACHE NAMING
 // =============================================================================
 /**
  * Persistent cache for immutable assets (`/_app/immutable/*`).
- * These files contain content hashes → safe to cache indefinitely.
- * NOT cleared on deploy — assets accumulate and are cleaned by `cleanupOldAssets()`.
+ * These files contain content hashes in their filenames, making them safe
+ * to cache indefinitely. NOT cleared on deploy — assets accumulate across
+ * builds and are pruned by {@link cleanupOldAssets} when triggered.
  */
 const ASSET_CACHE = '__SW_PREFIX__-assets-v1';
 /**
  * Versioned cache for the app shell (HTML, manifest, icons) and other
  * static assets. Re-created on each deploy; old versions are deleted
- * during the `activate` event.
+ * during the `activate` event so only one shell cache exists at a time.
  */
 const SHELL_CACHE = '__SW_PREFIX__-shell-' + APP_VERSION;
 // =============================================================================
@@ -51,6 +62,9 @@ const SHELL_CACHE = '__SW_PREFIX__-shell-' + APP_VERSION;
 /**
  * Core app shell resources to precache during the `install` event.
  * These are the minimum files needed for the app to render offline.
+ *
+ * Note: The root HTML (`/`) is cached separately in the install handler
+ * because its failure should abort the installation entirely.
  */
 const PRECACHE_ASSETS = [
     '/manifest.json',
@@ -65,7 +79,7 @@ const PRECACHE_ASSETS = [
 /**
  * Install handler — precaches the minimal app shell.
  *
- * Strategy:
+ * **Strategy:**
  *   1. The root HTML (`/`) is **required** — if it fails, install fails.
  *      Better to stay on the working old SW than activate with no cached HTML.
  *   2. Other shell assets (icons, manifest) are **optional** — failures
@@ -74,6 +88,8 @@ const PRECACHE_ASSETS = [
  *      "update available" prompt.
  *   4. Auto-promotes via `skipWaiting()` after 5 minutes as a fallback for
  *      iOS PWA where the update prompt may never be interacted with.
+ *
+ * @param event - The `install` {@link ExtendableEvent}.
  */
 self.addEventListener('install', (event) => {
     console.log(`[SW] Installing version: ${APP_VERSION}`);
@@ -106,14 +122,16 @@ self.addEventListener('install', (event) => {
 /**
  * Activate handler — cleans up stale caches and claims all clients.
  *
- * Deletes:
+ * **Deletes:**
  *   - Old versioned shell caches (e.g., `__SW_PREFIX__-shell-<old-version>`)
  *   - The legacy `__SW_PREFIX__-cache-v1` cache (one-time migration from the
  *     original single-cache strategy)
  *
- * Keeps:
+ * **Keeps:**
  *   - `ASSET_CACHE` — immutable assets persist across versions
  *   - `SHELL_CACHE` — the current deploy's shell cache
+ *
+ * @param event - The `activate` {@link ExtendableEvent}.
  */
 self.addEventListener('activate', (event) => {
     console.log(`[SW] Activating version: ${APP_VERSION}`);
@@ -144,14 +162,16 @@ self.addEventListener('activate', (event) => {
 /**
  * Fetch handler — routes requests to the appropriate caching strategy.
  *
- * Routing logic (in priority order):
+ * **Routing logic** (in priority order):
  *   1. Skip non-GET requests (mutations should always hit the network)
  *   2. Skip external origins (only cache same-origin resources)
  *   3. Skip `/api/*` routes (backend data — never cache)
- *   4. Navigation requests → `handleNavigationRequest()` (network-first)
- *   5. Immutable assets     → `handleImmutableAsset()`   (cache-first, permanent)
- *   6. Static assets        → `handleStaticAsset()`      (cache-first)
- *   7. Everything else      → `handleOtherRequest()`     (network-first)
+ *   4. Navigation requests  --> {@link handleNavigationRequest} (network-first)
+ *   5. Immutable assets     --> {@link handleImmutableAsset}    (cache-first, permanent)
+ *   6. Static assets        --> {@link handleStaticAsset}       (cache-first)
+ *   7. Everything else      --> {@link handleOtherRequest}      (network-first)
+ *
+ * @param event - The {@link FetchEvent} to handle.
  */
 self.addEventListener('fetch', (event) => {
     /* Only intercept GET requests — let POST/PUT/DELETE go straight to network */
@@ -190,8 +210,17 @@ self.addEventListener('fetch', (event) => {
  * Determines whether a given pathname looks like a static asset
  * (scripts, styles, images, fonts, data files).
  *
- * @param pathname — The URL pathname to test (e.g., `/_app/version.json`)
- * @returns `true` if the path matches a known static-asset extension
+ * Matches by file extension or by the `/_app/` prefix (SvelteKit's
+ * client-side output directory).
+ *
+ * @param pathname - The URL pathname to test (e.g., `/_app/version.json`).
+ * @returns `true` if the path matches a known static-asset extension.
+ *
+ * @example
+ * ```ts
+ * isStaticAsset('/icon-192.png');  // true
+ * isStaticAsset('/api/config');    // false
+ * ```
  */
 function isStaticAsset(pathname) {
     return (pathname.startsWith('/_app/') ||
@@ -214,13 +243,17 @@ function isStaticAsset(pathname) {
 /**
  * Handles HTML navigation requests with a **network-first** strategy.
  *
- * 1. Attempt a network fetch with a 3-second timeout (abort via `AbortController`)
- * 2. If successful → cache the response as `/` and return it
- * 3. If failed → serve the cached root HTML for offline use
- * 4. If nothing cached → return a minimal offline fallback page
+ * **Flow:**
+ *   1. Attempt a network fetch with a 3-second timeout (abort via `AbortController`)
+ *   2. If successful --> cache the response as `/` and return it
+ *   3. If failed --> serve the cached root HTML for offline use
+ *   4. If nothing cached --> return a minimal offline fallback page
  *
- * @param request — The navigation `Request` object
- * @returns A `Response` (from network, cache, or inline fallback)
+ * The 3-second timeout prevents the user from staring at a blank screen
+ * on flaky connections while still preferring fresh content.
+ *
+ * @param request - The navigation `Request` object.
+ * @returns A `Response` (from network, cache, or inline fallback).
  */
 async function handleNavigationRequest(request) {
     const cache = await caches.open(SHELL_CACHE);
@@ -260,12 +293,15 @@ async function handleNavigationRequest(request) {
 /**
  * Handles requests for immutable assets (`/_app/immutable/*`).
  *
- * Strategy: **cache-first, NEVER revalidate**. These files have content
+ * **Strategy:** cache-first, NEVER revalidate. These files have content
  * hashes baked into their filenames — if the content changes, the filename
  * changes, so a cached version is always correct.
  *
- * @param request — The `Request` for an immutable asset
- * @returns The cached `Response`, or a freshly-fetched one (then cached)
+ * Uses `ASSET_CACHE` which persists across SW versions (not cleared on
+ * deploy). Old entries are pruned by {@link cleanupOldAssets}.
+ *
+ * @param request - The `Request` for an immutable asset.
+ * @returns The cached `Response`, or a freshly-fetched one (then cached).
  */
 async function handleImmutableAsset(request) {
     const cache = await caches.open(ASSET_CACHE);
@@ -294,12 +330,12 @@ async function handleImmutableAsset(request) {
  * Handles requests for general static assets (non-immutable JS, CSS, images,
  * fonts, JSON files).
  *
- * Strategy: **cache-first, NO background revalidation**. This saves
+ * **Strategy:** cache-first, NO background revalidation. This saves
  * bandwidth — the shell cache is versioned per deploy, so stale assets
  * are cleaned up automatically when the new SW activates.
  *
- * @param request — The `Request` for a static asset
- * @returns The cached `Response`, or a freshly-fetched one (then cached)
+ * @param request - The `Request` for a static asset.
+ * @returns The cached `Response`, or a freshly-fetched one (then cached).
  */
 async function handleStaticAsset(request) {
     const cache = await caches.open(SHELL_CACHE);
@@ -327,13 +363,14 @@ async function handleStaticAsset(request) {
 /**
  * Handles all other same-origin GET requests with a **network-first** strategy.
  *
- * 1. Try the network
- * 2. If successful → cache and return
- * 3. If failed → return cached version
- * 4. If nothing cached → return a 503 "Offline" response
+ * **Flow:**
+ *   1. Try the network
+ *   2. If successful --> cache and return
+ *   3. If failed --> return cached version
+ *   4. If nothing cached --> return a 503 "Offline" response
  *
- * @param request — The `Request` object
- * @returns A `Response` from network or cache
+ * @param request - The `Request` object.
+ * @returns A `Response` from network or cache.
  */
 async function handleOtherRequest(request) {
     const cache = await caches.open(SHELL_CACHE);
@@ -359,7 +396,7 @@ async function handleOtherRequest(request) {
  * cached. This makes the entire app available offline without blocking the
  * install event.
  *
- * Key behaviors:
+ * **Key behaviours:**
  *   - Fetches the manifest with a cache-busting query param (`?_=<timestamp>`)
  *   - Checks both `ASSET_CACHE` and `SHELL_CACHE` to avoid redundant downloads
  *   - Downloads in batches of 5 with a 50 ms pause between batches to avoid
@@ -367,6 +404,10 @@ async function handleOtherRequest(request) {
  *   - Notifies all open windows with `PRECACHE_COMPLETE` when done
  *
  * Triggered by sending `{ type: 'PRECACHE_ALL' }` to the service worker.
+ *
+ * @returns A promise that resolves when precaching is complete (or fails).
+ *
+ * @see {@link cleanupOldAssets} for removing assets no longer in the manifest
  */
 async function backgroundPrecache() {
     try {
@@ -389,6 +430,7 @@ async function backgroundPrecache() {
         /* ── Determine which assets still need caching ────────────────── */
         const uncached = [];
         for (const url of assets) {
+            /* Route to the correct cache based on whether the asset is immutable */
             const isImmutable = url.includes('/_app/immutable/');
             const cache = isImmutable ? assetCache : shellCache;
             const cached = await cache.match(url);
@@ -442,6 +484,8 @@ async function backgroundPrecache() {
  * versioned and cleaned during the `activate` event.
  *
  * Triggered by sending `{ type: 'CLEANUP_OLD' }` to the service worker.
+ *
+ * @returns A promise that resolves when cleanup is complete.
  */
 async function cleanupOldAssets() {
     try {
@@ -478,7 +522,12 @@ async function cleanupOldAssets() {
 /**
  * Broadcasts a message to all open windows/tabs.
  *
- * @param message — The message object to send (e.g., `{ type: 'PRECACHE_COMPLETE', ... }`)
+ * @param message - The message object to send (e.g., `{ type: 'PRECACHE_COMPLETE', ... }`).
+ *
+ * @example
+ * ```ts
+ * notifyClients({ type: 'PRECACHE_COMPLETE', cached: 42, total: 50 });
+ * ```
  */
 function notifyClients(message) {
     self.clients.matchAll({ type: 'window' }).then((clients) => {
@@ -496,7 +545,7 @@ function notifyClients(message) {
  * styling — it will be precached and served automatically instead of
  * this bare-bones fallback.
  *
- * @returns An unstyled HTML string for the offline fallback
+ * @returns An unstyled HTML string for the offline fallback.
  */
 function getOfflineHTML() {
     return `<!DOCTYPE html>
@@ -519,13 +568,15 @@ function getOfflineHTML() {
 /**
  * Listens for messages from the app's client-side code.
  *
- * Supported message types:
- *   - `SKIP_WAITING`     → Immediately activate the waiting SW (user accepted update)
- *   - `GET_VERSION`      → Responds with the current `APP_VERSION` via `MessagePort`
- *   - `PRECACHE_ALL`     → Triggers `backgroundPrecache()` to download all assets
- *   - `CLEANUP_OLD`      → Triggers `cleanupOldAssets()` to remove stale cache entries
- *   - `CACHE_URLS`       → Caches a specific list of URLs (used for route prefetching)
- *   - `GET_CACHE_STATUS` → Responds with cache completeness info via `MessagePort`
+ * **Supported message types:**
+ *   - `SKIP_WAITING`     --> Immediately activate the waiting SW (user accepted update)
+ *   - `GET_VERSION`      --> Responds with the current `APP_VERSION` via `MessagePort`
+ *   - `PRECACHE_ALL`     --> Triggers {@link backgroundPrecache} to download all assets
+ *   - `CLEANUP_OLD`      --> Triggers {@link cleanupOldAssets} to remove stale cache entries
+ *   - `CACHE_URLS`       --> Caches a specific list of URLs (used for route prefetching)
+ *   - `GET_CACHE_STATUS` --> Responds with cache completeness info via `MessagePort`
+ *
+ * @param event - The {@link ExtendableMessageEvent} from a client.
  */
 self.addEventListener('message', (event) => {
     const { type } = event.data || {};
@@ -552,6 +603,7 @@ self.addEventListener('message', (event) => {
         const shellCachePromise = caches.open(SHELL_CACHE);
         Promise.all([assetCachePromise, shellCachePromise]).then(([ac, sc]) => {
             urls.forEach((url) => {
+                /* Route each URL to the correct cache based on immutability */
                 const isImmutable = url.includes('/_app/immutable/');
                 const cache = isImmutable ? ac : sc;
                 cache.add(url).catch(() => { });
@@ -572,11 +624,14 @@ self.addEventListener('message', (event) => {
  * Computes the current cache completeness by comparing cached entries
  * against the asset manifest.
  *
- * @returns An object with:
+ * Attempts to find the manifest in cache first (for offline use), then
+ * falls back to a network fetch.
+ *
+ * @returns An object describing cache readiness:
  *   - `cached`  — Number of manifest assets currently in cache
  *   - `total`   — Total number of assets in the manifest
  *   - `ready`   — `true` if every asset is cached (full offline support)
- *   - `version` — The manifest version string
+ *   - `version` — The manifest version string (if available)
  *   - `error`   — Error message string (only present if something went wrong)
  */
 async function getCacheStatus() {