@farm.js/pwa 0.1.0-beta.0 → 0.1.0-beta.10

package/README.md

@@ -1,9 +1,10 @@
 # @farm.js/pwa
 
 Installable, offline-aware Progressive Web Apps for Farm.js. The plugin generates a route-aware
-service worker during the production build and registers it through Farm's browser plugin lifecycle.
+service worker or copies a custom one during the production build, then registers it through Farm's
+browser plugin lifecycle.
 
-Farm.js is currently in beta.
+This package is in beta. See [Stability and Support](https://farmjs.dev/docs/stability).
 
 ## Install
 
@@ -21,7 +22,7 @@ export default defineConfig({
   plugins: [
     pwa({
       offline: "/offline",
-      cache: "recommended",
+      cache: "auto",
     }),
   ],
 });
@@ -33,15 +34,18 @@ does not duplicate it.
 
 ## Short cache configuration
 
-`recommended` precaches emitted static pages and uses SWR for public same-origin images:
+`auto` precaches emitted static pages and uses SWR for public same-origin images. It is the default,
+so you can omit `cache` when you want this behavior:
 
 ```ts
 pwa({
   offline: "/offline",
-  cache: "recommended",
+  cache: "auto",
 });
 ```
 
+The previous `recommended` value remains available as a compatibility alias for `auto`.
+
 The explicit short form is:
 
 ```ts
@@ -71,6 +75,25 @@ pwa({
 });
 ```
 
+## Bring your own service worker
+
+Advanced applications can replace the generated worker with a prebuilt JavaScript file:
+
+```ts
+pwa({
+  serviceWorker: {
+    source: "src/service-worker.js",
+    type: "module",
+  },
+});
+```
+
+The source path is relative to the Farm project root. Farm copies the file verbatim to the final
+`sw.js` location and keeps its production registration and update lifecycle. A custom worker owns
+all fetch, offline, and cache behavior, so `serviceWorker` cannot be combined with `offline` or
+`cache`. It must handle the `FARM_PWA_SKIP_WAITING` message for Farm's update action to activate a
+waiting worker.
+
 ## Updates
 
 `update: "prompt"` is the default. The plugin dispatches `farm:pwa:update-available` when a new

package/dist/build.d.ts

@@ -1,12 +1,16 @@
 import type { ResolvedPwaOptions } from "./config.js";
 export interface PwaBuildInput {
+    root?: string;
     outputDir: string;
     publicDir?: string;
     preset: string;
     basePath: string;
+    /** Prefix already present in emitted HTML paths (localized Farm SSG output). */
+    htmlBasePath?: string;
     options: ResolvedPwaOptions;
 }
 export interface PwaBuildResult {
+    mode: "generated" | "custom";
     workerPath: string;
     workerUrl: string;
     precacheUrls: string[];
@@ -15,6 +19,8 @@ export interface PwaBuildResult {
 }
 export declare function writePwaBuildArtifacts(input: PwaBuildInput): Promise<PwaBuildResult>;
 export interface GenerateServiceWorkerOptions {
+    basePath: string;
+    htmlBasePath?: string;
     cacheId: string;
     precacheUrls: string[];
     staticRoutes: Record<string, string>;

package/dist/build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,kBAAkB,CAAC;CAC7B;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,OAAO,EAAE,MAAM,CAAC;CACjB;AAcD,wBAAsB,sBAAsB,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CA0E1F;AAED,MAAM,WAAW,4BAA4B;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,YAAY,EAAE,MAAM,GAAG,KAAK,CAAC;IAC7B,MAAM,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC1B,MAAM,EAAE,kBAAkB,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,CAAC;CAC/C;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,4BAA4B,GAAG,MAAM,CAkJnF;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAK7E;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAGnE;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQpE"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,gFAAgF;IAChF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,kBAAkB,CAAC;CAC7B;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,WAAW,GAAG,QAAQ,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,OAAO,EAAE,MAAM,CAAC;CACjB;AAcD,wBAAsB,sBAAsB,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CA8G1F;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,YAAY,EAAE,MAAM,GAAG,KAAK,CAAC;IAC7B,MAAM,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC1B,MAAM,EAAE,kBAAkB,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,CAAC;CAC/C;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,4BAA4B,GAAG,MAAM,CA0NnF;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAK7E;AAiDD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAGnE;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKpE"}

package/dist/build.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { lstat, mkdir, readdir, readFile, realpath, writeFile } from "node:fs/promises";
 import path from "node:path";
 const PRECACHE_EXTENSIONS = new Set([
     ".css",
@@ -14,26 +14,51 @@ const PRECACHE_EXTENSIONS = new Set([
 ]);
 export async function writePwaBuildArtifacts(input) {
     const publicDir = input.publicDir ?? resolvePwaPublicDir(input.outputDir, input.preset);
-    const files = await walkFiles(publicDir);
-    const staticRouteFiles = resolveStaticRouteFiles(files);
     const basePath = normalizeBasePath(input.basePath);
+    const htmlBasePath = normalizeBasePath(input.htmlBasePath);
     const workerRelativePath = path.posix.join(basePath.replace(/^\//, ""), "sw.js");
+    const workerPath = path.join(publicDir, ...workerRelativePath.split("/"));
+    await assertWorkerPathInsidePublicDir(publicDir, workerPath);
+    if (input.options.serviceWorker) {
+        const sourcePath = path.resolve(input.root ?? process.cwd(), input.options.serviceWorker.source);
+        let source;
+        try {
+            source = await readFile(sourcePath);
+        }
+        catch (cause) {
+            throw new Error(`[farm:pwa] Custom service worker ${JSON.stringify(input.options.serviceWorker.source)} could not be read.`, { cause });
+        }
+        await mkdir(path.dirname(workerPath), { recursive: true });
+        await writeFile(workerPath, source);
+        return {
+            mode: "custom",
+            workerPath,
+            workerUrl: withBasePath("/sw.js", basePath),
+            precacheUrls: [],
+            staticRoutes: {},
+            cacheId: createHash("sha256").update(source).digest("hex").slice(0, 16),
+        };
+    }
+    const files = await walkFiles(publicDir);
+    const staticRouteFiles = resolveStaticRouteFiles(files, htmlBasePath);
     const selectedRoutes = selectStaticRoutes(staticRouteFiles, input.options.cache.staticRoutes, basePath);
     const configuredOfflineRoute = input.options.offline;
     const offlineRoute = configuredOfflineRoute
         ? withBasePath(configuredOfflineRoute, basePath)
         : false;
     if (offlineRoute && configuredOfflineRoute) {
-        const emittedOfflineFile = staticRouteFiles[configuredOfflineRoute] ?? staticRouteFiles[offlineRoute];
+        const emittedOfflineFile = staticRouteFiles[configuredOfflineRoute];
         if (!emittedOfflineFile) {
             throw new Error(`[farm:pwa] Offline route ${JSON.stringify(input.options.offline)} was not emitted as a static page. ` +
                 "Create that page as a static Farm route so it can be precached.");
         }
         selectedRoutes[offlineRoute] = emittedOfflineFile;
     }
-    const assetFiles = files.filter((file) => file !== workerRelativePath && PRECACHE_EXTENSIONS.has(path.extname(file).toLowerCase()));
+    const assetFiles = files.filter((file) => toPublicUrl(file, basePath) !== withBasePath("/sw.js", basePath) &&
+        PRECACHE_EXTENSIONS.has(path.extname(file).toLowerCase()));
     const precacheFiles = [...new Set([...assetFiles, ...Object.values(selectedRoutes)])].sort();
-    const precacheUrls = precacheFiles.map(toPublicUrl);
+    const htmlFiles = new Set(Object.values(selectedRoutes));
+    const precacheUrls = precacheFiles.map((file) => toPublicUrl(file, basePath, htmlFiles.has(file) ? htmlBasePath : basePath));
     const fileHashes = await Promise.all(precacheFiles.map(async (file) => {
         const content = await readFile(path.join(publicDir, file));
         return `${file}:${createHash("sha256").update(content).digest("hex")}`;
@@ -41,6 +66,7 @@ export async function writePwaBuildArtifacts(input) {
     const cacheId = createHash("sha256")
         .update(JSON.stringify({
         files: fileHashes,
+        urls: precacheUrls,
         routes: selectedRoutes,
         offlineRoute,
         update: input.options.update,
@@ -48,9 +74,10 @@ export async function writePwaBuildArtifacts(input) {
     }))
         .digest("hex")
         .slice(0, 16);
-    const workerPath = path.join(publicDir, ...workerRelativePath.split("/"));
     await mkdir(path.dirname(workerPath), { recursive: true });
     await writeFile(workerPath, generateServiceWorker({
+        basePath,
+        htmlBasePath,
         cacheId,
         precacheUrls,
         staticRoutes: selectedRoutes,
@@ -59,6 +86,7 @@ export async function writePwaBuildArtifacts(input) {
         images: input.options.cache.images,
     }));
     return {
+        mode: "generated",
         workerPath,
         workerUrl: withBasePath("/sw.js", basePath),
         precacheUrls,
@@ -67,11 +95,22 @@ export async function writePwaBuildArtifacts(input) {
     };
 }
 export function generateServiceWorker(options) {
-    const routeFiles = Object.fromEntries(Object.entries(options.staticRoutes).map(([route, file]) => [route, toPublicUrl(file)]));
-    const offlineFile = options.offlineRoute ? (routeFiles[options.offlineRoute] ?? null) : null;
+    const routeFiles = Object.fromEntries(Object.entries(options.staticRoutes).map(([route, file]) => [
+        encodeRoutePathname(route),
+        toPublicUrl(file, options.basePath, options.htmlBasePath ?? "/"),
+    ]));
+    const offlineFile = options.offlineRoute
+        ? (routeFiles[encodeRoutePathname(options.offlineRoute)] ?? null)
+        : null;
+    const cacheScope = createHash("sha256")
+        .update(normalizeBasePath(options.basePath))
+        .digest("hex")
+        .slice(0, 16);
+    const precachePrefix = `farm-pwa-precache-${cacheScope}-`;
     return `/* Generated by @farm.js/pwa. */
-const PRECACHE = ${JSON.stringify(`farm-pwa-precache-${options.cacheId}`)};
-const IMAGE_CACHE = "farm-pwa-images-v1";
+const PRECACHE_PREFIX = ${JSON.stringify(precachePrefix)};
+const PRECACHE = ${JSON.stringify(`${precachePrefix}${options.cacheId}`)};
+const IMAGE_CACHE = ${JSON.stringify(`farm-pwa-images-${cacheScope}-v1`)};
 const PRECACHE_URLS = ${JSON.stringify(options.precacheUrls)};
 const PRECACHE_PATHS = new Set(PRECACHE_URLS.map((value) => new URL(value, self.location.origin).pathname));
 const STATIC_ROUTES = ${JSON.stringify(routeFiles)};
@@ -90,7 +129,7 @@ self.addEventListener("activate", (event) => {
   event.waitUntil((async () => {
     const names = await caches.keys();
     await Promise.all(names
-      .filter((name) => name.startsWith("farm-pwa-precache-") && name !== PRECACHE)
+      .filter((name) => name.startsWith(PRECACHE_PREFIX) && name !== PRECACHE)
       .map((name) => caches.delete(name)));
     await self.clients.claim();
   })());
@@ -118,7 +157,9 @@ self.addEventListener("fetch", (event) => {
   }
 
   if (IMAGE_OPTIONS && request.destination === "image") {
-    event.respondWith(staleWhileRevalidateImage(request));
+    const image = staleWhileRevalidateImage(request);
+    event.respondWith(image.response);
+    event.waitUntil(image.lifetime);
   }
 });
 
@@ -145,48 +186,107 @@ async function handleNavigation(request, url) {
   }
 }
 
-async function staleWhileRevalidateImage(request) {
-  if (request.headers.has("authorization")) return fetch(request);
+function staleWhileRevalidateImage(request) {
+  let update = Promise.resolve();
+  const response = (async () => {
+    if (request.headers.has("authorization")) return fetch(request);
 
-  const cache = await caches.open(IMAGE_CACHE);
-  const cached = await cache.match(request);
-  const cachedAt = Number(cached?.headers.get("x-farm-pwa-cached-at") || 0);
-  const fresh = cached && Date.now() - cachedAt <= IMAGE_OPTIONS.ttlMs;
-  const update = fetchAndCacheImage(request, cache);
+    let cache;
+    let cached;
+    try {
+      cache = await caches.open(IMAGE_CACHE);
+      cached = await cache.match(request);
+    } catch {
+      // Runtime caching is optional when browser storage is unavailable.
+      return fetch(request);
+    }
+    const cachedAt = Number(cached?.headers.get("x-farm-pwa-cached-at") || 0);
+    const fresh = cached && Date.now() - cachedAt <= IMAGE_OPTIONS.ttlMs;
+    update = fetchAndCacheImage(request, cache);
 
-  if (fresh) {
-    void update.catch(() => undefined);
-    return cached;
-  }
+    if (fresh) return cached;
 
-  try {
-    return await update;
-  } catch (error) {
-    if (cached) return cached;
-    throw error;
-  }
+    try {
+      return await update;
+    } catch (error) {
+      if (cached) return cached;
+      throw error;
+    }
+  })();
+  const lifetime = response
+    .then(
+      () => update,
+      () => update,
+    )
+    .then(
+      () => undefined,
+      () => undefined,
+    );
+  return { response, lifetime };
 }
 
 async function fetchAndCacheImage(request, cache) {
   const response = await fetch(request);
   if (!isPublicCacheableImage(response)) return response;
 
-  const headers = new Headers(response.headers);
-  headers.set("x-farm-pwa-cached-at", String(Date.now()));
-  const stored = new Response(response.clone().body, {
-    status: response.status,
-    statusText: response.statusText,
-    headers,
-  });
-  await cache.put(request, stored);
-  await trimImageCache(cache, IMAGE_OPTIONS.limit);
+  let stored;
+  try {
+    const headers = new Headers(response.headers);
+    headers.set("x-farm-pwa-cached-at", String(Date.now()));
+    stored = new Response(response.clone().body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers,
+    });
+    await cache.put(request, stored);
+    await trimImageCache(cache, IMAGE_OPTIONS.limit);
+  } catch {
+    // Quota and storage failures must not discard a successful network response.
+    // Do not wait for tee cancellation, which can depend on the response consumer.
+    if (stored?.body) void stored.body.cancel().catch(() => undefined);
+  }
   return response;
 }
 
+// Cache Storage is shared by every account that signs in on this browser, and a
+// service worker cannot see the request's cookies to tell those accounts apart.
+// So an image is kept only when the server marked it shareable or it looks like a
+// static file, the same responses the browser's own HTTP cache would reuse.
 function isPublicCacheableImage(response) {
   if (!response.ok || response.type === "opaque") return false;
-  const policy = (response.headers.get("cache-control") || "").toLowerCase();
-  return !policy.includes("private") && !policy.includes("no-store") && !policy.includes("no-cache");
+  const directives = parseCacheControl(response.headers.get("cache-control"));
+  if (directives.has("private") || directives.has("no-store") || directives.has("no-cache")) {
+    return false;
+  }
+  const vary = (response.headers.get("vary") || "")
+    .toLowerCase()
+    .split(",")
+    .map((value) => value.trim());
+  // A response that varies on the caller's identity cannot be keyed here.
+  if (vary.includes("*") || vary.includes("cookie") || vary.includes("authorization")) {
+    return false;
+  }
+  if (directives.has("max-age")) return Number(directives.get("max-age")) > 0;
+  if (directives.has("public")) return true;
+  const expires = Date.parse(response.headers.get("expires") || "");
+  if (Number.isFinite(expires)) return expires > Date.now();
+  // Heuristic freshness (RFC 9111 section 4.2.2) needs a Last-Modified validator.
+  // Static files carry one. A dynamic response with no caching headers at all, such
+  // as an API route returning the signed-in account's avatar, does not, and keeping
+  // it would show that image to whoever uses this browser next.
+  return response.headers.has("last-modified");
+}
+
+function parseCacheControl(value) {
+  const directives = new Map();
+  for (const part of (value || "").toLowerCase().split(",")) {
+    const separator = part.indexOf("=");
+    const name = (separator === -1 ? part : part.slice(0, separator)).trim();
+    if (!name) continue;
+    const raw = separator === -1 ? "" : part.slice(separator + 1).trim();
+    directives.set(name, raw.startsWith('"') && raw.endsWith('"') ? raw.slice(1, -1) : raw);
+  }
+  return directives;
 }
 
 async function trimImageCache(cache, limit) {
@@ -213,6 +313,46 @@ function normalizePathname(pathname) {
 export function resolvePwaPublicDir(outputDir, preset) {
     return path.join(outputDir, preset === "vercel" || preset === "vercel-edge" ? "static" : "public");
 }
+async function assertWorkerPathInsidePublicDir(publicDir, workerPath) {
+    const prospectivePublicDir = await resolveProspectiveRealPath(publicDir);
+    const prospectiveWorkerPath = await resolveProspectiveRealPath(workerPath);
+    const relativePath = path.relative(prospectivePublicDir, prospectiveWorkerPath);
+    if (relativePath === ".." ||
+        relativePath.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relativePath)) {
+        throw new Error("[farm:pwa] Service worker output must stay inside the public output directory, including through symlinks.");
+    }
+}
+async function resolveProspectiveRealPath(candidate) {
+    const missingSegments = [];
+    let existingAncestor = path.resolve(candidate);
+    while (true) {
+        try {
+            return path.join(await realpath(existingAncestor), ...missingSegments);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            let existingEntry = false;
+            try {
+                await lstat(existingAncestor);
+                existingEntry = true;
+            }
+            catch (statError) {
+                if (statError.code !== "ENOENT")
+                    throw statError;
+            }
+            if (existingEntry) {
+                throw new Error("[farm:pwa] Service worker output must stay inside the public output directory, including through symlinks.");
+            }
+            const parent = path.dirname(existingAncestor);
+            if (parent === existingAncestor)
+                throw error;
+            missingSegments.unshift(path.basename(existingAncestor));
+            existingAncestor = parent;
+        }
+    }
+}
 export function normalizeBasePath(value) {
     if (!value || value === "/")
         return "/";
@@ -223,9 +363,6 @@ export function withBasePath(route, basePath) {
     const normalizedRoute = route === "/" ? "/" : `/${route.replace(/^\/+|\/+$/g, "")}`;
     if (normalizedBase === "/")
         return normalizedRoute;
-    if (normalizedRoute === normalizedBase || normalizedRoute.startsWith(`${normalizedBase}/`)) {
-        return normalizedRoute;
-    }
     return normalizedRoute === "/" ? normalizedBase : `${normalizedBase}${normalizedRoute}`;
 }
 async function walkFiles(root) {
@@ -239,7 +376,7 @@ async function walkFiles(root) {
     }));
     return files.flat().sort();
 }
-function resolveStaticRouteFiles(files) {
+function resolveStaticRouteFiles(files, htmlBasePath) {
     const routes = {};
     for (const file of files) {
         if (path.extname(file).toLowerCase() !== ".html")
@@ -249,7 +386,7 @@ function resolveStaticRouteFiles(files) {
         const route = withoutIndex
             ? `/${withoutIndex.replace(/\.html$/, "").replace(/^\/+|\/+$/g, "")}`
             : "/";
-        routes[route] = normalized;
+        routes[stripBasePath(route, htmlBasePath)] = normalized;
     }
     return routes;
 }
@@ -262,7 +399,7 @@ function selectStaticRoutes(emitted, configured, basePath) {
     const selected = {};
     for (const requested of configured) {
         const route = withBasePath(requested, basePath);
-        const emittedFile = emitted[requested] ?? emitted[route];
+        const emittedFile = emitted[requested];
         if (!emittedFile) {
             throw new Error(`[farm:pwa] Static route ${JSON.stringify(requested)} was not found in the production output.`);
         }
@@ -270,10 +407,39 @@ function selectStaticRoutes(emitted, configured, basePath) {
     }
     return selected;
 }
-function toPublicUrl(file) {
-    return `/${file
-        .replace(/\\/g, "/")
+function stripBasePath(route, basePath) {
+    const base = normalizeBasePath(basePath);
+    if (base === "/")
+        return route;
+    if (route === base)
+        return "/";
+    return route.startsWith(`${base}/`) ? route.slice(base.length) : route;
+}
+function toPublicUrl(file, basePath, fileBasePath = basePath) {
+    // Generated assets can already live under basePath. HTML uses the explicit
+    // SSG output prefix instead: a folder named like basePath can be a real route.
+    const route = stripBasePath(`/${file.replace(/\\/g, "/")}`, fileBasePath);
+    return withBasePath(encodePathname(route), basePath);
+}
+// Encode a route path the way browsers encode `location.pathname` so the
+// STATIC_ROUTES keys match the pathname a live navigation produces at runtime.
+// encodeURIComponent (used by toPublicUrl for asset URLs) is wrong for the keys:
+// it percent-encodes ordinary path characters such as @ , = + ; $ that browsers
+// leave untouched, so a route like /@alice would be keyed as /%40alice and never
+// match a navigation to /@alice, silently falling through to the offline page.
+function encodeRoutePathname(pathname) {
+    return new URL(pathname, "http://farm.localhost").pathname;
+}
+function encodePathname(pathname) {
+    // Match how a browser encodes location.pathname. encodeURIComponent is safe
+    // for every character but over-encodes the path sub-delimiters and ":"/"@"
+    // that browsers leave literal, so a precached asset like /logo@2x.css would
+    // be stored (and its PRECACHE_PATHS key derived) as /logo%402x.css and never
+    // match the live request for /logo@2x.css. Restore that path-safe set while
+    // leaving "?", "#", spaces and non-ASCII percent-encoded, the same divergence
+    // encodeRoutePathname documents for static-route keys.
+    return pathname
         .split("/")
-        .map((segment) => encodeURIComponent(segment))
-        .join("/")}`;
+        .map((segment) => encodeURIComponent(segment).replace(/%(24|26|2B|2C|3A|3B|3D|40)/gi, (match) => decodeURIComponent(match)))
+        .join("/");
 }

package/dist/config.d.ts

@@ -14,15 +14,21 @@ export interface PwaCacheOptions {
     /** Opt in to same-origin public image caching. */
     images?: PwaImageCache;
 }
+export interface PwaServiceWorkerOptions {
+    /** JavaScript file copied verbatim into the production output as sw.js. */
+    source: string;
+    /** Registration type for the custom worker. */
+    type?: "classic" | "module";
+}
 export interface PwaPluginOptions {
-    /** Set false to keep the plugin registered without emitting or registering a worker. */
-    enabled?: boolean;
     /** Static route to serve after an offline navigation misses the cache. */
     offline?: string | false;
     /** How a waiting service worker becomes active. */
     update?: "prompt" | "auto";
-    /** Recommended caching, custom caching, or build assets only. */
-    cache?: "recommended" | PwaCacheOptions | false;
+    /** Generated-worker caching, a custom cache policy, or build assets only. */
+    cache?: "auto" | "recommended" | PwaCacheOptions | false;
+    /** Copy and register a prebuilt service worker instead of generating one. */
+    serviceWorker?: PwaServiceWorkerOptions;
 }
 export interface ResolvedPwaImageCacheOptions {
     strategy: "swr";
@@ -30,9 +36,9 @@ export interface ResolvedPwaImageCacheOptions {
     ttlMs: number;
 }
 export interface ResolvedPwaOptions {
-    enabled: boolean;
     offline: string | false;
     update: "prompt" | "auto";
+    serviceWorker: Required<PwaServiceWorkerOptions> | false;
     cache: {
         staticRoutes: boolean | string[];
         images: ResolvedPwaImageCacheOptions | false;

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,GAAG,MAAM,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,EAAE,CAAC;AAE7E,MAAM,WAAW,oBAAoB;IACnC,0EAA0E;IAC1E,QAAQ,EAAE,KAAK,CAAC;IAChB,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,GAAG,CAAC,EAAE,WAAW,CAAC;CACnB;AAED,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,KAAK,GAAG,oBAAoB,CAAC;AAEnE,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,YAAY,CAAC,EAAE,OAAO,GAAG,MAAM,EAAE,CAAC;IAClC,kDAAkD;IAClD,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,wFAAwF;IACxF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACzB,mDAAmD;IACnD,MAAM,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC3B,iEAAiE;IACjE,KAAK,CAAC,EAAE,aAAa,GAAG,eAAe,GAAG,KAAK,CAAC;CACjD;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,EAAE,KAAK,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,KAAK,CAAC;IACxB,MAAM,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC1B,KAAK,EAAE;QACL,YAAY,EAAE,OAAO,GAAG,MAAM,EAAE,CAAC;QACjC,MAAM,EAAE,4BAA4B,GAAG,KAAK,CAAC;KAC9C,CAAC;CACH;AAKD,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,gBAAqB,GAAG,kBAAkB,CAuBpF;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CA0B3D"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,GAAG,MAAM,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,EAAE,CAAC;AAE7E,MAAM,WAAW,oBAAoB;IACnC,0EAA0E;IAC1E,QAAQ,EAAE,KAAK,CAAC;IAChB,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,GAAG,CAAC,EAAE,WAAW,CAAC;CACnB;AAED,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,KAAK,GAAG,oBAAoB,CAAC;AAEnE,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,YAAY,CAAC,EAAE,OAAO,GAAG,MAAM,EAAE,CAAC;IAClC,kDAAkD;IAClD,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED,MAAM,WAAW,uBAAuB;IACtC,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,IAAI,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;CAC7B;AAED,MAAM,WAAW,gBAAgB;IAC/B,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACzB,mDAAmD;IACnD,MAAM,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC3B,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,GAAG,aAAa,GAAG,eAAe,GAAG,KAAK,CAAC;IACzD,6EAA6E;IAC7E,aAAa,CAAC,EAAE,uBAAuB,CAAC;CACzC;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,EAAE,KAAK,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,GAAG,KAAK,CAAC;IACxB,MAAM,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC1B,aAAa,EAAE,QAAQ,CAAC,uBAAuB,CAAC,GAAG,KAAK,CAAC;IACzD,KAAK,EAAE;QACL,YAAY,EAAE,OAAO,GAAG,MAAM,EAAE,CAAC;QACjC,MAAM,EAAE,4BAA4B,GAAG,KAAK,CAAC;KAC9C,CAAC;CACH;AAKD,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,gBAAqB,GAAG,kBAAkB,CA8DpF;AAoBD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CA0B3D"}

package/dist/config.js

@@ -1,26 +1,74 @@
 const DEFAULT_IMAGE_LIMIT = 100;
 const DEFAULT_IMAGE_TTL = "30d";
 export function resolvePwaOptions(options = {}) {
-    const cache = options.cache ?? "recommended";
+    if (!options || typeof options !== "object" || Array.isArray(options)) {
+        throw new TypeError("PWA options must be an object");
+    }
+    if ("enabled" in options) {
+        throw new TypeError("PWA no longer accepts enabled; remove pwa() from plugins to disable it");
+    }
+    if (options.offline !== undefined &&
+        options.offline !== false &&
+        typeof options.offline !== "string") {
+        throw new TypeError('PWA offline must be a route starting with "/" or false');
+    }
+    if (options.update !== undefined && options.update !== "prompt" && options.update !== "auto") {
+        throw new TypeError('PWA update must be "prompt" or "auto"');
+    }
+    const serviceWorker = resolveServiceWorker(options.serviceWorker);
+    if (serviceWorker && (options.offline !== undefined || options.cache !== undefined)) {
+        throw new TypeError("PWA serviceWorker cannot be combined with offline or cache because the custom worker owns those behaviors");
+    }
+    const configuredCache = options.cache;
+    if (configuredCache !== undefined &&
+        configuredCache !== false &&
+        configuredCache !== "auto" &&
+        configuredCache !== "recommended" &&
+        (!configuredCache || typeof configuredCache !== "object" || Array.isArray(configuredCache))) {
+        throw new TypeError('PWA cache must be "auto", "recommended", an options object, or false');
+    }
+    const cache = configuredCache ?? "auto";
+    const usesAutomaticCache = cache === "auto" || cache === "recommended";
     const customCache = typeof cache === "object" ? cache : undefined;
     return {
-        enabled: options.enabled !== false,
-        offline: normalizeRoute(options.offline ?? false, "offline"),
+        offline: serviceWorker ? false : normalizeRoute(options.offline ?? false, "offline"),
         update: options.update ?? "prompt",
+        serviceWorker,
         cache: {
-            staticRoutes: cache === "recommended"
-                ? true
-                : cache === false
-                    ? false
-                    : normalizeStaticRoutes(customCache?.staticRoutes ?? false),
-            images: cache === "recommended"
-                ? resolveImageCache("swr")
-                : cache === false
-                    ? false
-                    : resolveImageCache(customCache?.images ?? false),
+            staticRoutes: serviceWorker
+                ? false
+                : usesAutomaticCache
+                    ? true
+                    : cache === false
+                        ? false
+                        : normalizeStaticRoutes(customCache?.staticRoutes === undefined ? false : customCache.staticRoutes),
+            images: serviceWorker
+                ? false
+                : usesAutomaticCache
+                    ? resolveImageCache("swr")
+                    : cache === false
+                        ? false
+                        : resolveImageCache(customCache?.images === undefined ? false : customCache.images),
         },
     };
 }
+function resolveServiceWorker(value) {
+    if (value === undefined)
+        return false;
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new TypeError("PWA serviceWorker must be an options object");
+    }
+    if (typeof value.source !== "string") {
+        throw new TypeError("PWA serviceWorker source must be a non-empty path");
+    }
+    const source = value.source.trim();
+    if (!source)
+        throw new TypeError("PWA serviceWorker source must be a non-empty path");
+    if (value.type !== undefined && value.type !== "classic" && value.type !== "module") {
+        throw new TypeError('PWA serviceWorker type must be "classic" or "module"');
+    }
+    return { source, type: value.type ?? "classic" };
+}
 export function parsePwaDuration(value) {
     if (typeof value === "number") {
         if (!Number.isFinite(value) || value <= 0) {
@@ -48,7 +96,9 @@ export function parsePwaDuration(value) {
 function resolveImageCache(value) {
     if (value === false)
         return false;
-    if (value !== true && value !== "swr" && value.strategy !== "swr") {
+    if (value !== true &&
+        value !== "swr" &&
+        (!value || typeof value !== "object" || Array.isArray(value) || value.strategy !== "swr")) {
         throw new TypeError('PWA image cache strategy must be "swr"');
     }
     const configured = typeof value === "object" ? value : undefined;
@@ -63,8 +113,11 @@ function resolveImageCache(value) {
     };
 }
 function normalizeStaticRoutes(value) {
-    if (!Array.isArray(value))
+    if (typeof value === "boolean")
         return value;
+    if (!Array.isArray(value)) {
+        throw new TypeError("PWA cache staticRoutes must be boolean or an array of routes");
+    }
     return [...new Set(value.map((route) => normalizeRoute(route, "static route")))];
 }
 function normalizeRoute(value, label) {
@@ -74,8 +127,36 @@ function normalizeRoute(value, label) {
     if (!route.startsWith("/")) {
         throw new TypeError(`PWA ${label} must start with "/"`);
     }
+    if (route.startsWith("//")) {
+        throw new TypeError(`PWA ${label} must be an application pathname, not a URL`);
+    }
     if (route.includes("?") || route.includes("#")) {
         throw new TypeError(`PWA ${label} cannot contain a query string or fragment`);
     }
+    if (hasUnstablePathCharacters(route)) {
+        throw new TypeError(`PWA ${label} cannot contain backslashes or control characters`);
+    }
+    for (const segment of route.split("/")) {
+        let decoded = segment;
+        try {
+            decoded = decodeURIComponent(segment);
+        }
+        catch {
+            // Malformed escapes remain literal URL pathname segments.
+        }
+        if (hasUnstablePathCharacters(decoded) || decoded.includes("/")) {
+            throw new TypeError(`PWA ${label} cannot contain encoded path separators`);
+        }
+        if (decoded === "." || decoded === "..") {
+            throw new TypeError(`PWA ${label} cannot contain "." or ".." path segments`);
+        }
+    }
     return route === "/" ? route : route.replace(/\/+$/, "");
 }
+function hasUnstablePathCharacters(value) {
+    return (value.includes("\\") ||
+        Array.from(value).some((character) => {
+            const code = character.charCodeAt(0);
+            return code <= 31 || (code >= 127 && code <= 159);
+        }));
+}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { type PwaCacheOptions, type PwaDuration, type PwaImageCache, type PwaImageCacheOptions, type PwaPluginOptions } from "./config.js";
-export type { PwaCacheOptions, PwaDuration, PwaImageCache, PwaImageCacheOptions, PwaPluginOptions };
+import { type PwaCacheOptions, type PwaDuration, type PwaImageCache, type PwaImageCacheOptions, type PwaPluginOptions, type PwaServiceWorkerOptions } from "./config.js";
+export type { PwaCacheOptions, PwaDuration, PwaImageCache, PwaImageCacheOptions, PwaPluginOptions, PwaServiceWorkerOptions, };
 export interface FarmPwaBrowserRuntime {
     registration: ServiceWorkerRegistration;
     applyUpdate(): void;
@@ -15,16 +15,16 @@ declare global {
     }
 }
 /**
- * Generate and register a route-aware service worker for a Farm application.
- * Build assets are always precached. Optional page and image caching stays
- * constrained to safe GET navigation and same-origin image requests.
+ * Generate or copy and then register a service worker for a Farm application.
+ * In generated mode, build assets are always precached while optional page and
+ * image caching stays constrained to safe GET navigation and same-origin images.
  */
 export declare function pwa(options?: PwaPluginOptions): import("@farm.js/core/plugin").FarmPlugin<undefined, Record<string, never>, {
     cleanup(): void;
 } | undefined, {
-    enabled: boolean;
     workerUrl: string;
     scope: string;
     update: "prompt" | "auto";
-}, unknown, false>;
+    workerType: "classic" | "module";
+}, unknown, false, import("@farm.js/core/plugin").PluginRoutes>;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACtB,MAAM,aAAa,CAAC;AAErB,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,aAAa,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,CAAC;AAEpG,MAAM,WAAW,qBAAqB;IACpC,YAAY,EAAE,yBAAyB,CAAC;IACxC,WAAW,IAAI,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,wBAAwB;IACvC,YAAY,EAAE,yBAAyB,CAAC;IACxC,WAAW,IAAI,IAAI,CAAC;CACrB;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,mDAAmD;QACnD,YAAY,CAAC,EAAE,qBAAqB,CAAC;KACtC;CACF;AAED;;;;GAIG;AACH,wBAAgB,GAAG,CAAC,OAAO,GAAE,gBAAqB;;;;;;;mBAoIjD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC7B,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,eAAe,EACf,WAAW,EACX,aAAa,EACb,oBAAoB,EACpB,gBAAgB,EAChB,uBAAuB,GACxB,CAAC;AAEF,MAAM,WAAW,qBAAqB;IACpC,YAAY,EAAE,yBAAyB,CAAC;IACxC,WAAW,IAAI,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,wBAAwB;IACvC,YAAY,EAAE,yBAAyB,CAAC;IACxC,WAAW,IAAI,IAAI,CAAC;CACrB;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,mDAAmD;QACnD,YAAY,CAAC,EAAE,qBAAqB,CAAC;KACtC;CACF;AAED;;;;GAIG;AACH,wBAAgB,GAAG,CAAC,OAAO,GAAE,gBAAqB;;;;;;;gEAgJjD"}

package/dist/index.js

@@ -2,33 +2,38 @@ import { definePlugin } from "@farm.js/core/plugin";
 import { normalizeBasePath, withBasePath, writePwaBuildArtifacts } from "./build.js";
 import { resolvePwaOptions, } from "./config.js";
 /**
- * Generate and register a route-aware service worker for a Farm application.
- * Build assets are always precached. Optional page and image caching stays
- * constrained to safe GET navigation and same-origin image requests.
+ * Generate or copy and then register a service worker for a Farm application.
+ * In generated mode, build assets are always precached while optional page and
+ * image caching stays constrained to safe GET navigation and same-origin images.
  */
 export function pwa(options = {}) {
     const resolved = resolvePwaOptions(options);
+    let configuredRoot = ".";
     let configuredBasePath = "/";
+    let htmlBasePath = "/";
     let configuredOutputDir = ".farm/.output";
     const publicConfig = {
-        enabled: resolved.enabled,
         workerUrl: "/sw.js",
         scope: "/",
         update: resolved.update,
+        workerType: resolved.serviceWorker ? resolved.serviceWorker.type : "classic",
     };
     return definePlugin({
         name: "farm:pwa",
         configure(config) {
+            configuredRoot = config.root ?? ".";
             const basePath = normalizeBasePath(config.basePath);
             configuredBasePath = basePath;
+            // Only localized SSG output already includes the application's basePath.
+            const i18n = config.i18n;
+            htmlBasePath =
+                i18n && typeof i18n === "object" && "enabled" in i18n && i18n.enabled ? basePath : "/";
             configuredOutputDir = `${config.root ?? "."}/.farm/.output`;
             publicConfig.workerUrl = withBasePath("/sw.js", basePath);
             publicConfig.scope = basePath === "/" ? "/" : `${basePath}/`;
         },
         build: {
             configure(nitroConfig) {
-                if (!resolved.enabled)
-                    return nitroConfig;
                 let generated = false;
                 const hooks = nitroConfig.hooks ?? {};
                 const previousPrerenderDone = hooks["prerender:done"];
@@ -37,14 +42,18 @@ export function pwa(options = {}) {
                     if (generated)
                         return;
                     const built = await writePwaBuildArtifacts({
+                        root: configuredRoot,
                         outputDir: nitroConfig.output?.dir ?? configuredOutputDir,
                         publicDir: nitroConfig.output?.publicDir,
                         preset: nitroConfig.preset ?? "node-server",
                         basePath: configuredBasePath,
+                        htmlBasePath,
                         options: resolved,
                     });
                     generated = true;
-                    console.info(`[farm:pwa] Generated ${built.workerUrl} with ${built.precacheUrls.length} precached files`);
+                    console.info(built.mode === "custom"
+                        ? `[farm:pwa] Copied custom service worker to ${built.workerUrl}`
+                        : `[farm:pwa] Generated ${built.workerUrl} with ${built.precacheUrls.length} precached files`);
                 };
                 return {
                     ...nitroConfig,
@@ -67,11 +76,11 @@ export function pwa(options = {}) {
         client: {
             public: publicConfig,
             async setup({ public: config, isProd }) {
-                if (!config.enabled || !isProd || !("serviceWorker" in navigator))
+                if (!isProd || !("serviceWorker" in navigator))
                     return undefined;
-                const registration = await navigator.serviceWorker.register(config.workerUrl, {
-                    scope: config.scope,
-                });
+                const registration = await navigator.serviceWorker.register(config.workerUrl, config.workerType === "module"
+                    ? { scope: config.scope, type: "module" }
+                    : { scope: config.scope });
                 const hadControllerAtSetup = Boolean(navigator.serviceWorker.controller);
                 let applyingUpdate = false;
                 let reloading = false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farm.js/pwa",
-  "version": "0.1.0-beta.0",
+  "version": "0.1.0-beta.10",
   "description": "Installable, offline-aware Progressive Web Apps for Farm.js",
   "keywords": [
     "farm.js",
@@ -32,7 +32,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@farm.js/core": "0.1.0-beta.68"
+    "@farm.js/core": "0.1.6"
   },
   "devDependencies": {
     "@types/node": "^20.10.5",
@@ -40,7 +40,7 @@
     "vitest": "^3.2.7"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.13.0"
   },
   "scripts": {
     "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc",