@farm.js/pwa 0.1.0-beta.2 → 0.1.0-beta.4

package/README.md

@@ -4,7 +4,7 @@ Installable, offline-aware Progressive Web Apps for Farm.js. The plugin generate
 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
 

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 {
@@ -18,6 +20,7 @@ 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,CAyG1F;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,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,CAyKnF;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,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

@@ -15,6 +15,7 @@ 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);
@@ -39,14 +40,14 @@ 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.");
@@ -56,7 +57,8 @@ export async function writePwaBuildArtifacts(input) {
     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((file) => toPublicUrl(file, basePath));
+    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")}`;
@@ -64,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,
@@ -74,6 +77,7 @@ export async function writePwaBuildArtifacts(input) {
     await mkdir(path.dirname(workerPath), { recursive: true });
     await writeFile(workerPath, generateServiceWorker({
         basePath,
+        htmlBasePath,
         cacheId,
         precacheUrls,
         staticRoutes: selectedRoutes,
@@ -92,11 +96,11 @@ export async function writePwaBuildArtifacts(input) {
 }
 export function generateServiceWorker(options) {
     const routeFiles = Object.fromEntries(Object.entries(options.staticRoutes).map(([route, file]) => [
-        encodePathname(route),
-        toPublicUrl(file, options.basePath),
+        encodeRoutePathname(route),
+        toPublicUrl(file, options.basePath, options.htmlBasePath ?? "/"),
     ]));
     const offlineFile = options.offlineRoute
-        ? (routeFiles[encodePathname(options.offlineRoute)] ?? null)
+        ? (routeFiles[encodeRoutePathname(options.offlineRoute)] ?? null)
         : null;
     const cacheScope = createHash("sha256")
         .update(normalizeBasePath(options.basePath))
@@ -187,8 +191,15 @@ function staleWhileRevalidateImage(request) {
   const response = (async () => {
     if (request.headers.has("authorization")) return fetch(request);
 
-    const cache = await caches.open(IMAGE_CACHE);
-    const cached = await cache.match(request);
+    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);
@@ -218,22 +229,64 @@ 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) {
@@ -310,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) {
@@ -326,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")
@@ -336,7 +386,7 @@ function resolveStaticRouteFiles(files) {
         const route = withoutIndex
             ? `/${withoutIndex.replace(/\.html$/, "").replace(/^\/+|\/+$/g, "")}`
             : "/";
-        routes[route] = normalized;
+        routes[stripBasePath(route, htmlBasePath)] = normalized;
     }
     return routes;
 }
@@ -349,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.`);
         }
@@ -357,17 +407,39 @@ function selectStaticRoutes(emitted, configured, basePath) {
     }
     return selected;
 }
-function toPublicUrl(file, basePath) {
-    const url = `/${file
-        .replace(/\\/g, "/")
-        .split("/")
-        .map((segment) => encodeURIComponent(segment))
-        .join("/")}`;
-    return withBasePath(url, basePath);
+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))
+        .map((segment) => encodeURIComponent(segment).replace(/%(24|26|2B|2C|3A|3B|3D|40)/gi, (match) => decodeURIComponent(match)))
         .join("/");
 }

package/dist/index.d.ts

@@ -26,5 +26,5 @@ export declare function pwa(options?: PwaPluginOptions): import("@farm.js/core/p
     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;;;;;;;mBA0IjD"}
+{"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,6 +10,7 @@ export function pwa(options = {}) {
     const resolved = resolvePwaOptions(options);
     let configuredRoot = ".";
     let configuredBasePath = "/";
+    let htmlBasePath = "/";
     let configuredOutputDir = ".farm/.output";
     const publicConfig = {
         workerUrl: "/sw.js",
@@ -23,6 +24,10 @@ 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}/`;
@@ -42,6 +47,7 @@ export function pwa(options = {}) {
                         publicDir: nitroConfig.output?.publicDir,
                         preset: nitroConfig.preset ?? "node-server",
                         basePath: configuredBasePath,
+                        htmlBasePath,
                         options: resolved,
                     });
                     generated = true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farm.js/pwa",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0-beta.4",
   "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.93"
+    "@farm.js/core": "0.1.0"
   },
   "devDependencies": {
     "@types/node": "^20.10.5",