@farm.js/pwa 0.1.0-beta.1 → 0.1.0-beta.3

package/dist/build.d.ts

@@ -5,6 +5,8 @@ export interface PwaBuildInput {
     publicDir?: string;
     preset: string;
     basePath: string;
+    /** Prefix already present in emitted HTML paths (localized Farm SSG output). */
+    htmlBasePath?: string;
     options: ResolvedPwaOptions;
 }
 export interface PwaBuildResult {
@@ -17,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,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,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,CAsG1F;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",
@@ -15,8 +15,10 @@ const PRECACHE_EXTENSIONS = new Set([
 export async function writePwaBuildArtifacts(input) {
     const publicDir = input.publicDir ?? resolvePwaPublicDir(input.outputDir, input.preset);
     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;
@@ -38,23 +40,25 @@ export async function writePwaBuildArtifacts(input) {
         };
     }
     const files = await walkFiles(publicDir);
-    const staticRouteFiles = resolveStaticRouteFiles(files);
+    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")}`;
@@ -62,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,
@@ -71,6 +76,8 @@ export async function writePwaBuildArtifacts(input) {
         .slice(0, 16);
     await mkdir(path.dirname(workerPath), { recursive: true });
     await writeFile(workerPath, generateServiceWorker({
+        basePath,
+        htmlBasePath,
         cacheId,
         precacheUrls,
         staticRoutes: selectedRoutes,
@@ -88,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)};
@@ -111,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();
   })());
@@ -139,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);
   }
 });
 
@@ -166,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) {
@@ -234,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 "/";
@@ -244,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) {
@@ -260,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")
@@ -270,7 +386,7 @@ function resolveStaticRouteFiles(files) {
         const route = withoutIndex
             ? `/${withoutIndex.replace(/\.html$/, "").replace(/^\/+|\/+$/g, "")}`
             : "/";
-        routes[route] = normalized;
+        routes[stripBasePath(route, htmlBasePath)] = normalized;
     }
     return routes;
 }
@@ -283,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.`);
         }
@@ -291,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

@@ -21,8 +21,6 @@ export interface PwaServiceWorkerOptions {
     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. */
@@ -38,7 +36,6 @@ export interface ResolvedPwaImageCacheOptions {
     ttlMs: number;
 }
 export interface ResolvedPwaOptions {
-    enabled: boolean;
     offline: string | false;
     update: "prompt" | "auto";
     serviceWorker: Required<PwaServiceWorkerOptions> | 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,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,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,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,OAAO,CAAC;IACjB,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,CAkCpF;AAcD,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,15 +1,36 @@
 const DEFAULT_IMAGE_LIMIT = 100;
 const DEFAULT_IMAGE_TTL = "30d";
 export function resolvePwaOptions(options = {}) {
+    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 cache = options.cache ?? "auto";
+    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: serviceWorker ? false : normalizeRoute(options.offline ?? false, "offline"),
         update: options.update ?? "prompt",
         serviceWorker,
@@ -20,20 +41,26 @@ export function resolvePwaOptions(options = {}) {
                     ? true
                     : cache === false
                         ? false
-                        : normalizeStaticRoutes(customCache?.staticRoutes ?? false),
+                        : normalizeStaticRoutes(customCache?.staticRoutes === undefined ? false : customCache.staticRoutes),
             images: serviceWorker
                 ? false
                 : usesAutomaticCache
                     ? resolveImageCache("swr")
                     : cache === false
                         ? false
-                        : resolveImageCache(customCache?.images ?? false),
+                        : resolveImageCache(customCache?.images === undefined ? false : customCache.images),
         },
     };
 }
 function resolveServiceWorker(value) {
-    if (!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");
@@ -69,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;
@@ -84,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) {
@@ -95,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

@@ -22,10 +22,9 @@ declare global {
 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";
     workerType: "classic" | "module";
-}, unknown, false>;
+}, 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,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;;;;;;;;mBA6IjD"}
+{"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

@@ -10,9 +10,9 @@ 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,
@@ -24,14 +24,16 @@ export function pwa(options = {}) {
             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"];
@@ -45,6 +47,7 @@ export function pwa(options = {}) {
                         publicDir: nitroConfig.output?.publicDir,
                         preset: nitroConfig.preset ?? "node-server",
                         basePath: configuredBasePath,
+                        htmlBasePath,
                         options: resolved,
                     });
                     generated = true;
@@ -73,7 +76,7 @@ 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, config.workerType === "module"
                     ? { scope: config.scope, type: "module" }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farm.js/pwa",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.3",
   "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.69"
+    "@farm.js/core": "0.1.0-beta.107"
   },
   "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",