cursedbelt-core 2.8.0 → 2.9.0

package/dist/core/offline/shellWorker.d.ts

@@ -13,7 +13,9 @@
  *  - `install`  — precache the shell and the config's `precache` list, then `skipWaiting`.
  *  - `activate` — delete every cache named `<cachePrefix>*` that is not this version's,
  *                 then `clients.claim()`.
- *  - `fetch`    — same-origin static ASSETS cache-first; document NAVIGATIONS
+ *  - `fetch`    — same-origin static ASSETS: cache-first when the NAME carries a content
+ *                 hash, otherwise revalidated with the network and the cache as the
+ *                 offline fallback (see {@link isContentHashed}); document NAVIGATIONS
  *                 network-first, falling back offline to the exact URL, then the same
  *                 path ignoring the query, then the shell. Everything else is left on
  *                 the network: `respondWith` is never called for it.
@@ -44,7 +46,7 @@
 export type ShellRoute = 
 /** A document navigation — network-first, cached-document fallback offline. */
 'navigate'
-/** A same-origin static asset (JS/CSS/WASM/font/image/JSON) — cache-first. */
+/** A same-origin static asset (JS/CSS/WASM/font/image/JSON) — cache-first if content-hashed, else revalidated. */
  | 'asset'
 /** An auth-gated API call — never cached, never answered from a cache. */
  | 'api'
@@ -110,6 +112,23 @@ export interface ResolvedShellWorkerConfig {
 /** roms' `ASSET_EXT`, verbatim. */
 export declare const DEFAULT_ASSET_EXT: RegExp;
 /** Always an API prefix, whatever the config says. */
+/**
+ * A built file whose NAME carries its content hash — Vite's `index-BcHBclrL.js` — so
+ * the bytes under that name can never change, and cache-first is exact.
+ *
+ * 🔴 Every other asset is REVALIDATED (network, then the cache when offline), because
+ * cache-first on a fixed name is "the first copy this device ever saw, for ever":
+ * the cache is named by `version`, which an app bumps by hand, and nothing else
+ * evicts an entry. Measured on roms 2026-09-27: its emulator cores
+ * (`/vendor/cores/melonds_libretro.js`) and frame runtime (`/emulator-runtime.js`)
+ * are fixed names under a `v4` cache, so the DS audio fix deployed that day — and
+ * every core or runtime fix before it — could never reach a device that had already
+ * played the console. The edge answers those names `no-cache` with an ETag, so a
+ * revalidation is a 304 and no body.
+ */
+export declare const CONTENT_HASHED_NAME: RegExp;
+/** Whether this pathname's last segment is a content-hashed build output. */
+export declare function isContentHashed(pathname: string): boolean;
 export declare const ALWAYS_API_PREFIX = "/api/";
 /**
  * Classify a request. Order matters and is roms' order: non-GET and cross-origin

package/dist/core/offline/shellWorker.js

@@ -13,7 +13,9 @@
  *  - `install`  — precache the shell and the config's `precache` list, then `skipWaiting`.
  *  - `activate` — delete every cache named `<cachePrefix>*` that is not this version's,
  *                 then `clients.claim()`.
- *  - `fetch`    — same-origin static ASSETS cache-first; document NAVIGATIONS
+ *  - `fetch`    — same-origin static ASSETS: cache-first when the NAME carries a content
+ *                 hash, otherwise revalidated with the network and the cache as the
+ *                 offline fallback (see {@link isContentHashed}); document NAVIGATIONS
  *                 network-first, falling back offline to the exact URL, then the same
  *                 path ignoring the query, then the shell. Everything else is left on
  *                 the network: `respondWith` is never called for it.
@@ -43,6 +45,25 @@
 /** roms' `ASSET_EXT`, verbatim. */
 export const DEFAULT_ASSET_EXT = /\.(?:js|mjs|css|wasm|woff2?|ttf|png|jpe?g|webp|svg|ico|json)$/i;
 /** Always an API prefix, whatever the config says. */
+/**
+ * A built file whose NAME carries its content hash — Vite's `index-BcHBclrL.js` — so
+ * the bytes under that name can never change, and cache-first is exact.
+ *
+ * 🔴 Every other asset is REVALIDATED (network, then the cache when offline), because
+ * cache-first on a fixed name is "the first copy this device ever saw, for ever":
+ * the cache is named by `version`, which an app bumps by hand, and nothing else
+ * evicts an entry. Measured on roms 2026-09-27: its emulator cores
+ * (`/vendor/cores/melonds_libretro.js`) and frame runtime (`/emulator-runtime.js`)
+ * are fixed names under a `v4` cache, so the DS audio fix deployed that day — and
+ * every core or runtime fix before it — could never reach a device that had already
+ * played the console. The edge answers those names `no-cache` with an ETag, so a
+ * revalidation is a 304 and no body.
+ */
+export const CONTENT_HASHED_NAME = /-[A-Za-z0-9_-]{8,}\.[A-Za-z0-9]+$/;
+/** Whether this pathname's last segment is a content-hashed build output. */
+export function isContentHashed(pathname) {
+    return CONTENT_HASHED_NAME.test(pathname);
+}
 export const ALWAYS_API_PREFIX = '/api/';
 const apiPrefixesOf = (config) => {
     const extra = config.apiPrefixes ?? [];
@@ -143,6 +164,26 @@ export function installShellWorker(scope, config) {
         store(event, 'asset', response);
         return response;
     };
+    // A fixed-name asset: the network's answer when it has a good one (stored for
+    // offline), else the cached copy — offline, or an edge error — else whatever the
+    // network said. Never the cache first: see `isContentHashed`.
+    const revalidate = async (event) => {
+        let response;
+        try {
+            response = await scope.fetch(event.request);
+        }
+        catch (error) {
+            const cached = await caches.match(event.request);
+            if (cached)
+                return cached;
+            throw error;
+        }
+        if (response.ok) {
+            store(event, 'asset', response);
+            return response;
+        }
+        return (await caches.match(event.request)) ?? response;
+    };
     const networkFirst = async (event) => {
         const { request } = event;
         try {
@@ -190,7 +231,7 @@ export function installShellWorker(scope, config) {
             isNavigate: event.request.mode === 'navigate',
         }, resolved);
         if (route === 'asset')
-            event.respondWith(cacheFirst(event));
+            event.respondWith(isContentHashed(url.pathname) ? cacheFirst(event) : revalidate(event));
         else if (route === 'navigate')
             event.respondWith(networkFirst(event));
         // `api` and `passthrough`: no respondWith, so the browser goes to the network as

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-core",
-	"version": "2.8.0",
+	"version": "2.9.0",
 	"license": "ISC",
 	"type": "module",
 	"description": "Framework-agnostic core of the cursedbelt split — isomorphic domain logic. cwip below it, cursedbelt-server and cursedbelt (react) above it.",

package/src/core/offline/shellWorker.spec.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from 'bun:test';
 import {
   classifyRequest,
   installShellWorker,
+  isContentHashed,
   mayFallBackToShell,
   type RequestFacts,
   resolveShellWorkerConfig,
@@ -353,16 +354,50 @@ describe('installShellWorker — fetch', () => {
     );
   });
 
-  it('serves assets cache-first and caches only an ok response', async () => {
+  it('serves CONTENT-HASHED assets cache-first and caches only an ok response', async () => {
     const world = await installedRoms();
-    world.server.set(`${ORIGIN}/assets/app-1.js`, new FakeResponse('app'));
-    expect((await world.dispatch(req('/assets/app-1.js')).settled())?.body).toBe('app');
-    expect((await world.dispatch(req('/assets/missing.js')).settled())?.ok).toBe(false);
-    expect(world.cacheWrites).toEqual([`${ORIGIN}/assets/app-1.js`]);
-    world.goOffline();
+    world.server.set(`${ORIGIN}/assets/app-BcHBclrL.js`, new FakeResponse('app'));
+    expect((await world.dispatch(req('/assets/app-BcHBclrL.js')).settled())?.body).toBe('app');
+    expect((await world.dispatch(req('/assets/missing-DeadBeef.js')).settled())?.ok).toBe(false);
+    expect(world.cacheWrites).toEqual([`${ORIGIN}/assets/app-BcHBclrL.js`]);
     const calls = world.networkCalls.length;
-    expect((await world.dispatch(req('/assets/app-1.js')).settled())?.body).toBe('app');
-    expect(world.networkCalls.length).toBe(calls); // from the cache, not the network
+    expect((await world.dispatch(req('/assets/app-BcHBclrL.js')).settled())?.body).toBe('app');
+    expect(world.networkCalls.length).toBe(calls); // from the cache, not the network — even online
+  });
+
+  it('🔴 a FIXED-NAME asset reaches the device when its bytes change — the roms core that never updated (2026-09-27)', async () => {
+    const world = await installedRoms();
+    const core = `${ORIGIN}/vendor/cores/melonds_libretro.js`;
+    world.server.set(core, new FakeResponse('old driver'));
+    expect((await world.dispatch(req('/vendor/cores/melonds_libretro.js')).settled())?.body).toBe('old driver');
+    world.server.set(core, new FakeResponse('new driver')); // a deploy
+    expect((await world.dispatch(req('/vendor/cores/melonds_libretro.js')).settled())?.body).toBe('new driver');
+    // …and the runtime precached at install is refreshed the same way.
+    world.server.set(`${ORIGIN}/emulator-runtime.js`, new FakeResponse('runtime 2'));
+    expect((await world.dispatch(req('/emulator-runtime.js')).settled())?.body).toBe('runtime 2');
+    // Offline, the LATEST copy answers, not the first one.
+    world.goOffline();
+    expect((await world.dispatch(req('/vendor/cores/melonds_libretro.js')).settled())?.body).toBe('new driver');
+    expect((await world.dispatch(req('/emulator-runtime.js')).settled())?.body).toBe('runtime 2');
+  });
+
+  it('a fixed-name asset the edge errors on is served from the cache; with no copy, the error stands', async () => {
+    const world = await installedRoms();
+    world.server.set(`${ORIGIN}/controller-ds.webp`, new FakeResponse('pad'));
+    await world.dispatch(req('/controller-ds.webp')).settled();
+    world.server.set(`${ORIGIN}/controller-ds.webp`, new FakeResponse('bad gateway', false));
+    expect((await world.dispatch(req('/controller-ds.webp')).settled())?.body).toBe('pad');
+    expect((await world.dispatch(req('/favicon.svg')).settled())?.ok).toBe(false);
+    world.goOffline();
+    await expect(world.dispatch(req('/favicon.svg')).response as Promise<ShellWorkerResponse>).rejects.toThrow('Failed to fetch');
+  });
+
+  it('isContentHashed: Vite names are, fixed names are not', () => {
+    expect(isContentHashed('/assets/index-BcHBclrL.js')).toBe(true);
+    expect(isContentHashed('/assets/ps2-C7Rs0q_e.css')).toBe(true);
+    expect(isContentHashed('/vendor/cores/melonds_libretro.wasm')).toBe(false);
+    expect(isContentHashed('/emulator-runtime.js')).toBe(false);
+    expect(isContentHashed('/controller-ds.webp')).toBe(false);
   });
 
   it('🔴 never intercepts, reads or caches /api/ — even with a stale copy planted in the cache', async () => {

package/src/core/offline/shellWorker.ts

@@ -13,7 +13,9 @@
  *  - `install`  — precache the shell and the config's `precache` list, then `skipWaiting`.
  *  - `activate` — delete every cache named `<cachePrefix>*` that is not this version's,
  *                 then `clients.claim()`.
- *  - `fetch`    — same-origin static ASSETS cache-first; document NAVIGATIONS
+ *  - `fetch`    — same-origin static ASSETS: cache-first when the NAME carries a content
+ *                 hash, otherwise revalidated with the network and the cache as the
+ *                 offline fallback (see {@link isContentHashed}); document NAVIGATIONS
  *                 network-first, falling back offline to the exact URL, then the same
  *                 path ignoring the query, then the shell. Everything else is left on
  *                 the network: `respondWith` is never called for it.
@@ -45,7 +47,7 @@
 export type ShellRoute =
   /** A document navigation — network-first, cached-document fallback offline. */
   | 'navigate'
-  /** A same-origin static asset (JS/CSS/WASM/font/image/JSON) — cache-first. */
+  /** A same-origin static asset (JS/CSS/WASM/font/image/JSON) — cache-first if content-hashed, else revalidated. */
   | 'asset'
   /** An auth-gated API call — never cached, never answered from a cache. */
   | 'api'
@@ -116,6 +118,27 @@ export interface ResolvedShellWorkerConfig {
 export const DEFAULT_ASSET_EXT = /\.(?:js|mjs|css|wasm|woff2?|ttf|png|jpe?g|webp|svg|ico|json)$/i;
 
 /** Always an API prefix, whatever the config says. */
+/**
+ * A built file whose NAME carries its content hash — Vite's `index-BcHBclrL.js` — so
+ * the bytes under that name can never change, and cache-first is exact.
+ *
+ * 🔴 Every other asset is REVALIDATED (network, then the cache when offline), because
+ * cache-first on a fixed name is "the first copy this device ever saw, for ever":
+ * the cache is named by `version`, which an app bumps by hand, and nothing else
+ * evicts an entry. Measured on roms 2026-09-27: its emulator cores
+ * (`/vendor/cores/melonds_libretro.js`) and frame runtime (`/emulator-runtime.js`)
+ * are fixed names under a `v4` cache, so the DS audio fix deployed that day — and
+ * every core or runtime fix before it — could never reach a device that had already
+ * played the console. The edge answers those names `no-cache` with an ETag, so a
+ * revalidation is a 304 and no body.
+ */
+export const CONTENT_HASHED_NAME = /-[A-Za-z0-9_-]{8,}\.[A-Za-z0-9]+$/;
+
+/** Whether this pathname's last segment is a content-hashed build output. */
+export function isContentHashed(pathname: string): boolean {
+  return CONTENT_HASHED_NAME.test(pathname);
+}
+
 export const ALWAYS_API_PREFIX = '/api/';
 
 const apiPrefixesOf = (config: Pick<ShellWorkerConfig, 'apiPrefixes'>): readonly string[] => {
@@ -279,6 +302,25 @@ export function installShellWorker(scope: ShellWorkerScope, config: ShellWorkerC
     return response;
   };
 
+  // A fixed-name asset: the network's answer when it has a good one (stored for
+  // offline), else the cached copy — offline, or an edge error — else whatever the
+  // network said. Never the cache first: see `isContentHashed`.
+  const revalidate = async (event: ShellFetchEvent): Promise<ShellWorkerResponse> => {
+    let response: ShellWorkerResponse;
+    try {
+      response = await scope.fetch(event.request);
+    } catch (error) {
+      const cached = await caches.match(event.request);
+      if (cached) return cached;
+      throw error;
+    }
+    if (response.ok) {
+      store(event, 'asset', response);
+      return response;
+    }
+    return (await caches.match(event.request)) ?? response;
+  };
+
   const networkFirst = async (event: ShellFetchEvent): Promise<ShellWorkerResponse> => {
     const { request } = event;
     try {
@@ -336,7 +378,7 @@ export function installShellWorker(scope: ShellWorkerScope, config: ShellWorkerC
       },
       resolved,
     );
-    if (route === 'asset') event.respondWith(cacheFirst(event));
+    if (route === 'asset') event.respondWith(isContentHashed(url.pathname) ? cacheFirst(event) : revalidate(event));
     else if (route === 'navigate') event.respondWith(networkFirst(event));
     // `api` and `passthrough`: no respondWith, so the browser goes to the network as
     // if this worker did not exist. Never a cache read, never a cache write.