@timber-js/app 0.2.0-alpha.141 → 0.2.0-alpha.143

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.141",
+  "version": "0.2.0-alpha.143",
   "description": "Vite-native React framework built for Servers and Serverless Platforms — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",
@@ -114,11 +114,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "vite build --config vite.lib.config.ts && tsc --emitDeclarationOnly --project tsconfig.json --outDir dist",
-    "typecheck": "tsgo --noEmit",
-    "prepublishOnly": "pnpm run build"
-  },
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/context-async-hooks": "^2.7.1",
@@ -132,10 +127,11 @@
     "@content-collections/vite": "^0.2.0",
     "@mdx-js/rollup": "^3.0.0",
     "@vitejs/plugin-react": "^6.0.0",
-    "@vitejs/plugin-rsc": ">=0.5.21",
+    "@vitejs/plugin-rsc": ">=0.5.27",
     "nuqs": "^2.0.0",
-    "react": "19.3.0-canary-d5736f09-20260507",
-    "react-dom": "19.3.0-canary-d5736f09-20260507",
+    "react": ">=19.3.0-canary-43bcbf80-20260603",
+    "react-dom": ">=19.3.0-canary-43bcbf80-20260603",
+    "react-server-dom-webpack": ">=19.3.0-canary-43bcbf80-20260603",
     "vite": "^8.0.13",
     "wrangler": "^4.0.0",
     "zod": "^3.22.0 || ^4.0.0"
@@ -162,5 +158,9 @@
   },
   "engines": {
     "node": ">=22.12.0"
+  },
+  "scripts": {
+    "build": "vite build --config vite.lib.config.ts && tsc --emitDeclarationOnly --project tsconfig.json --outDir dist",
+    "typecheck": "tsgo --noEmit"
   }
-}
+}

package/src/client/browser-entry/action-dispatch.ts

@@ -17,7 +17,6 @@
 import { setServerCallback, encodeReply, createFromFetch } from '../../rsc-runtime/browser.js';
 import { getRouter, getRouterOrNull } from '#client-internal';
 import { setHardNavigating } from '../navigation-root.js';
-import { isStaleClientReference, triggerStaleReload } from '../stale-reload.js';
 import { getClientDeploymentId, DEPLOYMENT_ID_HEADER, RELOAD_HEADER } from '../rsc-fetch.js';
 
 export function setupServerActions(): void {
@@ -59,17 +58,7 @@ export function setupServerActions(): void {
       return res;
     });
 
-    let decoded: unknown;
-    try {
-      decoded = await createFromFetch(response);
-    } catch (error) {
-      if (isStaleClientReference(error)) {
-        triggerStaleReload();
-        // Return a never-resolving promise to prevent further processing
-        return new Promise(() => {});
-      }
-      throw error;
-    }
+    const decoded = await createFromFetch(response);
 
     // Handle redirect — server encoded the redirect location in the RSC stream
     // instead of returning HTTP 302. Perform a client-side SPA navigation.

package/src/client/browser-entry/index.ts

@@ -21,8 +21,7 @@
  *   5. hydrateApp()              — hydrateRoot or deferred createRoot
  *   6. setupPostHydration()      — history stack, popstate, scroll
  *   7. setupHmr()                — dev-only HMR wiring
- *   8. stale reload handlers     — global error listeners
- *   9. timber-ready signal       — E2E test readiness indicator
+ *   8. timber-ready signal       — E2E test readiness indicator
  *
  * Design docs: 18-build-system.md §"Entry Files", 19-client-navigation.md
  */
@@ -42,12 +41,6 @@ import { setLinkCodecs } from '../../params/codec-registry.js';
 setLinkCodecs(schemaCodecs);
 
 import { setClientDeploymentId } from '../rsc-fetch.js';
-import {
-  isStaleClientReference,
-  isChunkLoadError,
-  triggerStaleReload,
-  clearStaleReloadFlag,
-} from '../stale-reload.js';
 
 import { setupServerActions } from './action-dispatch.js';
 import { createRscPayloadStream } from './rsc-stream.js';
@@ -104,40 +97,7 @@ function bootstrap(runtimeConfig: typeof config): void {
 
 bootstrap(config);
 
-// ─── 8. Stale Reload Handlers ───────────────────────────────────
-
-// Clear the stale reload flag on successful bootstrap. If the page
-// loaded and bootstrapped without hitting a stale reference error,
-// the loop guard should reset so the next stale error gets a fresh
-// reload attempt.
-clearStaleReloadFlag();
-
-// Global error handler for stale client reference errors during hydration.
-// The initial RSC payload is decoded lazily by React via createFromReadableStream.
-// If the payload references a module ID from a newer deployment, the error
-// surfaces as an unhandled rejection during React's render/hydration cycle.
-// This handler catches those errors and triggers a full page reload.
-//
-// Also catches chunk load failures (dynamic import of missing assets after
-// a deployment) — these surface as "Failed to fetch dynamically imported module"
-// or "Loading chunk <name> failed" errors. See TIM-446.
-window.addEventListener('unhandledrejection', (event) => {
-  if (isStaleClientReference(event.reason) || isChunkLoadError(event.reason)) {
-    event.preventDefault();
-    triggerStaleReload();
-  }
-});
-
-// Also catch synchronous errors from chunk loads (some browsers throw
-// TypeError synchronously instead of via unhandled rejection).
-window.addEventListener('error', (event) => {
-  if (isChunkLoadError(event.error)) {
-    event.preventDefault();
-    triggerStaleReload();
-  }
-});
-
-// ─── 9. Ready Signal ────────────────────────────────────────────
+// ─── 8. Ready Signal ────────────────────────────────────────────
 
 // Signal that the client runtime has been initialized.
 // Used by E2E tests to wait for hydration before interacting.

package/src/client/browser-entry/router-init.ts

@@ -17,7 +17,6 @@ import { TimberNuqsAdapter } from '../nuqs-adapter.js';
 import { NavigationProvider } from '../navigation-context.js';
 import { transitionRender, navigateTransition } from '../navigation-root.js';
 import { SegmentUpdateContext, EMPTY_SEGMENT_UPDATES } from '../segment-update-context.js';
-import { isStaleClientReference, triggerStaleReload } from '../stale-reload.js';
 import {
   hasNavigationApi,
   setupNavigationApi,
@@ -79,30 +78,8 @@ export function createTimberRouter(options?: RouterInitOptions): RouterInitResul
     getCurrentUrl: () => window.location.pathname + window.location.search,
     getScrollY,
 
-    // Decode RSC Flight stream using createFromFetch.
-    // createFromFetch takes a Promise<Response> and progressively
-    // parses the RSC stream as chunks arrive.
-    //
-    // Wrapped with stale client reference detection: if the server
-    // has been redeployed with new bundles, the RSC payload may
-    // reference module IDs that don't exist in the old client bundle.
-    // We catch "Could not find the module" errors and trigger a full
-    // page reload so the browser fetches the new bundle.
-    // Pass the fetch promise directly to createFromFetch for streaming.
-    // React progressively renders chunks via Suspense as they arrive.
-    // The transition stays open via decodePromise (awaited inside
-    // startTransition) so useOptimistic pending state persists for
-    // the full stream duration.
     decodeRsc: (fetchPromise: Promise<Response>) => {
-      try {
-        return createFromFetch(fetchPromise);
-      } catch (error) {
-        if (isStaleClientReference(error)) {
-          triggerStaleReload();
-          return new Promise(() => {});
-        }
-        throw error;
-      }
+      return createFromFetch(fetchPromise);
     },
 
     // Render decoded RSC tree via NavigationRoot's state-based mechanism.

package/src/client/router.ts

@@ -19,7 +19,6 @@ import {
   VersionSkewError,
 } from './rsc-fetch.js';
 import { setHardNavigating } from './navigation-root.js';
-import { isStaleClientReference, triggerStaleReload } from './stale-reload.js';
 import type { FetchResult } from './rsc-fetch.js';
 
 // ─── Types ───────────────────────────────────────────────────────
@@ -565,17 +564,11 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       // scroll during DOM reconciliation, so all scroll must be actively managed.
       restoreScrollAfterPaint(scroll ? 0 : currentScrollY);
     } catch (error) {
-      // Version skew — server has been redeployed. Trigger full page reload
+      // Version skew — server has been redeployed. Full page reload
       // so the browser fetches the new bundle. See TIM-446.
-      // Set hard-navigating flag to prevent Navigation API interception
-      // and React from rendering during page teardown. See TIM-626.
       if (error instanceof VersionSkewError) {
         setHardNavigating(true);
-        // Import triggerStaleReload dynamically to avoid circular deps
-        // and keep the reload logic centralized with its loop guard.
-        const { triggerStaleReload } = await import('./stale-reload.js');
-        triggerStaleReload();
-        // Return a never-resolving promise — page is reloading.
+        window.location.reload();
         return new Promise(() => {}) as never;
       }
       // Server-side redirect during RSC fetch → soft router navigation.
@@ -600,13 +593,6 @@ export function createRouter(deps: RouterDeps): RouterInstance {
         window.location.href = error.url;
         return new Promise(() => {}) as never;
       }
-      // Stale client reference from streaming RSC decode — the server
-      // was redeployed with new bundles. Same recovery as VersionSkewError.
-      if (isStaleClientReference(error)) {
-        setHardNavigating(true);
-        triggerStaleReload();
-        return new Promise(() => {}) as never;
-      }
       // Abort errors are not application errors — swallow silently.
       if (isAbortError(error)) return;
       throw error;
@@ -651,13 +637,6 @@ export function createRouter(deps: RouterDeps): RouterInstance {
 
       applyHead(headElements);
     } catch (error) {
-      if (isStaleClientReference(error)) {
-        setHardNavigating(true);
-        triggerStaleReload();
-        return new Promise(() => {}) as never;
-      }
-      // Stale transition (superseded by a newer navigation) or aborted
-      // fetch — silently ignore. See TIM-629.
       if (isAbortError(error)) return;
       throw error;
     } finally {
@@ -705,13 +684,6 @@ export function createRouter(deps: RouterDeps): RouterInstance {
         applyHead(headElements);
         restoreScrollAfterPaint(scrollY);
       } catch (error) {
-        if (isStaleClientReference(error)) {
-          setHardNavigating(true);
-          triggerStaleReload();
-          return new Promise(() => {}) as never;
-        }
-        // Stale transition (superseded by a newer navigation) or aborted
-        // fetch — silently ignore. See TIM-629.
         if (isAbortError(error)) return;
         throw error;
       } finally {

package/src/client/rsc-fetch.ts

@@ -230,7 +230,7 @@ export class RedirectError extends Error {
 
 /**
  * Thrown when the server signals a version skew (X-Timber-Reload header).
- * Caught in navigate() to trigger a full page reload via triggerStaleReload().
+ * Caught in navigate() to trigger a full page reload.
  * See TIM-446.
  */
 export class VersionSkewError extends Error {
@@ -345,7 +345,7 @@ export async function fetchRscPayload(
     const wrappedPromise = fetchPromise.then((response) => {
       // Version skew detection (TIM-446): if the server signals a reload,
       // throw VersionSkewError so the caller (router navigate) can trigger
-      // a full page reload via triggerStaleReload().
+      // a full page reload.
       if (checkReloadSignal(response)) {
         throw new VersionSkewError();
       }

package/src/server/build-manifest.ts

@@ -92,12 +92,12 @@ export function collectRouteCss(segments: SegmentWithFiles[], manifest: BuildMan
  * via injectHead() before </head>.
  */
 export function buildCssLinkTags(cssUrls: string[]): string {
-  // Emit <link rel="stylesheet"> tags as a fallback for platforms where
-  // React's Float system (via @vitejs/plugin-rsc preinit with
-  // data-precedence) doesn't handle CSS injection. In practice, Float
-  // deduplicates and these may be dropped. No preload hints — Float
-  // already starts the fetch via preinit(), and redundant preloads
-  // cause "ignored due to unknown as/type" browser warnings.
+  // Emit only <link rel="stylesheet"> — no preload tags. CSS preloading
+  // is handled by 103 Early Hints (Link header) which fires before the
+  // HTML stream. Float also emits `<link rel="stylesheet" data-precedence>`
+  // at the top of <head> during Fizz rendering — the browser discovers
+  // CSS from that tag. A <link rel="preload"> here would arrive *after*
+  // Float's stylesheet tag and trigger "Preload was ignored" warnings.
   return cssUrls.map((url) => `<link rel="stylesheet" href="${url}">`).join('');
 }
 

package/src/server/early-hints.ts

@@ -127,6 +127,8 @@ export function collectEarlyHintHeaders(
   };
 
   // Per-route CSS — as=style; rel=preload
+  // The HTML <head> also contains a matching <link rel="preload" as="style">
+  // tag so browsers can deduplicate the 103 hint against the HTML tag.
   for (const url of collectRouteCss(segments, manifest)) {
     add(url, formatLinkHeader({ href: url, rel: 'preload', as: 'style' }));
   }

package/dist/client/stale-reload.d.ts

@@ -1,59 +0,0 @@
-/**
- * Stale Client Reference Reload
- *
- * When a new deployment ships updated bundles, clients running stale
- * JavaScript may encounter "Could not find the module" errors during
- * RSC Flight stream decoding. This happens because the RSC payload
- * references module IDs from the new bundle that don't exist in the
- * old client bundle.
- *
- * This module detects these specific errors and triggers a full page
- * reload so the browser fetches the new bundle. A sessionStorage flag
- * guards against infinite reload loops.
- *
- * See: LOCAL-332
- */
-/**
- * Check if an error is a stale client reference error from React's
- * Flight client. These errors have the message pattern:
- *   "Could not find the module \"<id>\""
- *
- * This is thrown by react-server-dom-webpack's client when the RSC
- * payload references a module ID that doesn't exist in the client's
- * module map — typically because the server has been redeployed with
- * new bundle hashes while the client is still running old JavaScript.
- */
-export declare function isStaleClientReference(error: unknown): boolean;
-/**
- * Check if an error is a chunk load failure from a dynamic import.
- *
- * After a deployment, old chunk filenames no longer exist. When the client
- * tries to dynamically import a chunk that's been replaced, the browser
- * throws one of these errors:
- *
- * - Chromium: "Failed to fetch dynamically imported module: <url>"
- * - Firefox: "error loading dynamically imported module: <url>"
- * - Safari: "Importing a module script failed."
- * - Vite/Rollup: "Unable to preload CSS for <url>"
- *
- * See TIM-446
- */
-export declare function isChunkLoadError(error: unknown): boolean;
-/**
- * Trigger a full page reload to pick up new bundles.
- *
- * Sets a sessionStorage flag before reloading. If the flag is already
- * set (meaning we already reloaded once for this reason), we don't
- * reload again — this prevents infinite reload loops if the error
- * persists after reload (e.g., a genuine bug rather than a stale bundle).
- *
- * @returns true if a reload was triggered, false if suppressed (loop guard)
- */
-export declare function triggerStaleReload(): boolean;
-/**
- * Clear the stale reload flag. Called on successful bootstrap to reset
- * the loop guard — if the page loaded successfully, the next stale
- * reference error should trigger a fresh reload attempt.
- */
-export declare function clearStaleReloadFlag(): void;
-//# sourceMappingURL=stale-reload.d.ts.map

package/dist/client/stale-reload.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"stale-reload.d.ts","sourceRoot":"","sources":["../../src/client/stale-reload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAcH;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAI9D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAYxD;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAqD5C;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAa3C"}

package/src/client/stale-reload.ts

@@ -1,156 +0,0 @@
-/**
- * Stale Client Reference Reload
- *
- * When a new deployment ships updated bundles, clients running stale
- * JavaScript may encounter "Could not find the module" errors during
- * RSC Flight stream decoding. This happens because the RSC payload
- * references module IDs from the new bundle that don't exist in the
- * old client bundle.
- *
- * This module detects these specific errors and triggers a full page
- * reload so the browser fetches the new bundle. A sessionStorage flag
- * guards against infinite reload loops.
- *
- * See: LOCAL-332
- */
-
-const RELOAD_FLAG_KEY = '__timber_stale_reload';
-
-/**
- * In-memory fallback counter for environments where sessionStorage is
- * unavailable (private browsing, storage full, extension interference).
- * Incremented each time triggerStaleReload() falls into the catch path.
- * If the counter exceeds 0 on a subsequent call, the reload is suppressed
- * to prevent an infinite loop. Resets naturally on page load (module
- * re-evaluates) and can be manually reset via clearStaleReloadFlag().
- */
-let memoryReloadCount = 0;
-
-/**
- * Check if an error is a stale client reference error from React's
- * Flight client. These errors have the message pattern:
- *   "Could not find the module \"<id>\""
- *
- * This is thrown by react-server-dom-webpack's client when the RSC
- * payload references a module ID that doesn't exist in the client's
- * module map — typically because the server has been redeployed with
- * new bundle hashes while the client is still running old JavaScript.
- */
-export function isStaleClientReference(error: unknown): boolean {
-  if (!(error instanceof Error)) return false;
-  const msg = error.message;
-  return msg.includes('Could not find the module') || msg.includes('client reference not found');
-}
-
-/**
- * Check if an error is a chunk load failure from a dynamic import.
- *
- * After a deployment, old chunk filenames no longer exist. When the client
- * tries to dynamically import a chunk that's been replaced, the browser
- * throws one of these errors:
- *
- * - Chromium: "Failed to fetch dynamically imported module: <url>"
- * - Firefox: "error loading dynamically imported module: <url>"
- * - Safari: "Importing a module script failed."
- * - Vite/Rollup: "Unable to preload CSS for <url>"
- *
- * See TIM-446
- */
-export function isChunkLoadError(error: unknown): boolean {
-  if (!(error instanceof Error)) return false;
-  const msg = error.message.toLowerCase();
-  return (
-    msg.includes('failed to fetch dynamically imported module') ||
-    msg.includes('error loading dynamically imported module') ||
-    msg.includes('importing a module script failed') ||
-    msg.includes('unable to preload css') ||
-    // Webpack-style chunk load errors (unlikely in Vite but defensive)
-    msg.includes('loading chunk') ||
-    msg.includes('loading css chunk')
-  );
-}
-
-/**
- * Trigger a full page reload to pick up new bundles.
- *
- * Sets a sessionStorage flag before reloading. If the flag is already
- * set (meaning we already reloaded once for this reason), we don't
- * reload again — this prevents infinite reload loops if the error
- * persists after reload (e.g., a genuine bug rather than a stale bundle).
- *
- * @returns true if a reload was triggered, false if suppressed (loop guard)
- */
-export function triggerStaleReload(): boolean {
-  try {
-    // Check if we already reloaded — prevent infinite loop
-    if (sessionStorage.getItem(RELOAD_FLAG_KEY)) {
-      console.warn(
-        '[timber] Stale client reference detected again after reload. ' +
-          'Not reloading to prevent infinite loop. ' +
-          'This may indicate a deployment issue — try a hard refresh.'
-      );
-      return false;
-    }
-
-    // Set the flag before reloading
-    sessionStorage.setItem(RELOAD_FLAG_KEY, '1');
-
-    console.warn(
-      '[timber] Stale client reference detected — the server has been ' +
-        'redeployed with new bundles. Reloading to pick up the new version.'
-    );
-
-    window.location.reload();
-    return true;
-  } catch {
-    // sessionStorage unavailable (private browsing, storage full, etc.)
-    // Use document.cookie as a reload-persistent fallback loop guard.
-    // Module-level memoryReloadCount resets on every reload, so it can't
-    // detect cross-reload loops. Cookies persist across reloads and are
-    // available even when sessionStorage is blocked (TIM-576).
-    const cookieFlag = document.cookie.includes(RELOAD_FLAG_KEY + '=1');
-    if (cookieFlag || memoryReloadCount > 0) {
-      console.warn(
-        '[timber] Stale client reference detected again after reload. ' +
-          'Not reloading to prevent infinite loop. ' +
-          'This may indicate a deployment issue — try a hard refresh.'
-      );
-      return false;
-    }
-
-    memoryReloadCount++;
-    // Set a short-lived cookie (60s) as the persistent loop guard.
-    // It auto-expires so it won't block future legitimate reloads.
-    try {
-      document.cookie = `${RELOAD_FLAG_KEY}=1; max-age=60; path=/; SameSite=Lax`;
-    } catch {
-      // Cookie API unavailable — proceed anyway, memoryReloadCount guards same-page loops
-    }
-    console.warn(
-      '[timber] Stale client reference detected — the server has been ' +
-        'redeployed with new bundles. Reloading to pick up the new version.'
-    );
-    window.location.reload();
-    return true;
-  }
-}
-
-/**
- * Clear the stale reload flag. Called on successful bootstrap to reset
- * the loop guard — if the page loaded successfully, the next stale
- * reference error should trigger a fresh reload attempt.
- */
-export function clearStaleReloadFlag(): void {
-  memoryReloadCount = 0;
-  try {
-    sessionStorage.removeItem(RELOAD_FLAG_KEY);
-  } catch {
-    // sessionStorage unavailable — nothing to clear
-  }
-  // Also clear the cookie fallback
-  try {
-    document.cookie = `${RELOAD_FLAG_KEY}=; max-age=0; path=/; SameSite=Lax`;
-  } catch {
-    // Cookie API unavailable
-  }
-}