@timber-js/app 0.1.51 → 0.1.52

package/dist/server/compress.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compress.d.ts","sourceRoot":"","sources":["../../src/server/compress.ts"],"names":[],"mappings":"AAYA;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,aAc7B,CAAC;AASH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASvE;AAID;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAmB1D;AAID;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,GAAG,QAAQ,CAiC/E"}
+{"version":3,"file":"compress.d.ts","sourceRoot":"","sources":["../../src/server/compress.ts"],"names":[],"mappings":"AAYA;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,aAc7B,CAAC;AASH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA4BvE;AAID;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAmB1D;AAID;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,GAAG,QAAQ,CAiC/E"}

package/dist/server/state-tree-diff.d.ts

@@ -39,5 +39,5 @@ export declare function parseClientStateTree(req: Request): Set<string> | null;
  * @param isLeaf - Whether this is the leaf segment (page segment)
  * @param clientSegments - Set of paths from X-Timber-State-Tree, or null
  */
-export declare function shouldSkipSegment(urlPath: string, layoutComponent: ((...args: unknown[]) => unknown) | undefined, isLeaf: boolean, clientSegments: Set<string> | null): boolean;
+export declare function shouldSkipSegment(_urlPath: string, _layoutComponent: ((...args: unknown[]) => unknown) | undefined, _isLeaf: boolean, _clientSegments: Set<string> | null): boolean;
 //# sourceMappingURL=state-tree-diff.d.ts.map

package/dist/server/state-tree-diff.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state-tree-diff.d.ts","sourceRoot":"","sources":["../../src/server/state-tree-diff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAarE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,eAAe,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,GAAG,SAAS,EAC9D,MAAM,EAAE,OAAO,EACf,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,GACjC,OAAO,CAeT"}
+{"version":3,"file":"state-tree-diff.d.ts","sourceRoot":"","sources":["../../src/server/state-tree-diff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAarE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,gBAAgB,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,GAAG,SAAS,EAC/D,OAAO,EAAE,OAAO,EAChB,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,GAClC,OAAO,CAgBT"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.1.51",
+  "version": "0.1.52",
   "description": "Vite-native React framework for Cloudflare Workers — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",

package/src/adapters/compress-module.ts

@@ -37,12 +37,25 @@ const NO_COMPRESS_STATUSES = new Set([204, 304]);
 
 function negotiateEncoding(acceptEncoding) {
   if (!acceptEncoding) return null;
-  const tokens = acceptEncoding.split(',').map(s => s.split(';')[0].trim().toLowerCase());
+  // Parse tokens with quality values. Per RFC 9110 §12.5.3, q=0 means
+  // "not acceptable" — the client explicitly rejects that encoding.
   // Brotli (br) is intentionally not handled at the application level.
-  // At streaming-friendly quality levels (0-4), brotli's ratio advantage over
-  // gzip is marginal, and node:zlib's brotli transform buffers output internally.
-  // CDNs/reverse proxies apply brotli at higher quality levels on cached responses.
-  if (tokens.includes('gzip')) return 'gzip';
+  const parts = acceptEncoding.split(',');
+  for (const part of parts) {
+    const [token, ...params] = part.split(';');
+    const name = token.trim().toLowerCase();
+    if (name !== 'gzip') continue;
+    let qValue = 1;
+    for (const param of params) {
+      const trimmed = param.trim().toLowerCase();
+      if (trimmed.startsWith('q=')) {
+        qValue = parseFloat(trimmed.slice(2));
+        if (Number.isNaN(qValue)) qValue = 1;
+        break;
+      }
+    }
+    if (qValue > 0) return 'gzip';
+  }
   return null;
 }
 

package/src/adapters/nitro.ts

@@ -341,19 +341,20 @@ export function generateNitroEntry(
   return `// Generated by @timber-js/app/adapters/nitro
 // Do not edit — this file is regenerated on each build.
 
-${manifestImport}import handler, { runWithEarlyHintsSender${waitUntilImport} } from '${serverEntryRelative}'
+${manifestImport}import { defineEventHandler } from 'nitro/h3'
+import handler, { runWithEarlyHintsSender${waitUntilImport} } from '${serverEntryRelative}'
 import { compressResponse } from './_compress.mjs'
 
 // Set TIMBER_RUNTIME for instrumentation.ts conditional SDK initialization.
 // See design/25-production-deployments.md §"TIMBER_RUNTIME".
 process.env.TIMBER_RUNTIME = '${runtimeName}'
 
-export default async (event) => {
+export default defineEventHandler(async (event) => {
   // h3 v2: event.req is the Web Request
   const webRequest = event.req
 ${handlerCall}
   return compressResponse(webRequest, webResponse)
-}
+})
 `;
 }
 

package/src/client/browser-entry.ts

@@ -52,6 +52,7 @@ import {
 import { setupServerLogReplay, setupClientErrorForwarding } from './browser-dev.js';
 import { handleLinkClick, handleLinkHover } from './browser-links.js';
 import { TransitionRoot, transitionRender, navigateTransition } from './transition-root.js';
+import { isStaleClientReference, triggerStaleReload, clearStaleReloadFlag } from './stale-reload.js';
 
 // ─── Server Action Dispatch ──────────────────────────────────────
 
@@ -94,7 +95,17 @@ setServerCallback(async (id: string, args: unknown[]) => {
     return res;
   });
 
-  const decoded = await createFromFetch(response);
+  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;
+  }
 
   // Handle redirect — server encoded the redirect location in the RSC stream
   // instead of returning HTTP 302. Perform a client-side SPA navigation.
@@ -169,25 +180,33 @@ function getScrollY(): number {
  * (scrollHeight > clientHeight). Returns the first match, or null.
  *
  * This heuristic covers the common layout patterns:
- *   <body> → <html-wrapper> → <div class="overflow-y-auto">
- *   <body> → <main class="overflow-y-auto">
+ *   <body> → <root-layout> → <div class="overflow-y-auto">
+ *   <body> → <root-layout> → <main> → <nested-layout overflow-y-auto>
  *
- * We limit depth to avoid expensive full-tree traversals.
+ * We limit depth to 3 to avoid expensive full-tree traversals while still
+ * reaching nested layout scroll containers (e.g., parallel route layouts
+ * inside a root layout's <main> element).
  *
  * DIVERGENCE FROM NEXT.JS: Next.js's ScrollAndFocusHandler scrolls only
  * document.documentElement.scrollTop — it does NOT handle overflow containers.
  * Layouts using h-screen + overflow-y-auto have the same scroll bug in Next.js.
- * This heuristic is a deliberate improvement. The tradeoff is fragility: depth-2
+ * This heuristic is a deliberate improvement. The tradeoff is fragility: depth-3
  * traversal may miss deeply nested containers or match the wrong element.
  * See design/19-client-navigation.md §"Overflow Scroll Containers".
  */
 function findOverflowContainer(): HTMLElement | null {
   const candidates: HTMLElement[] = [];
-  // Check body's direct children and their children (depth 2)
+  // Check body's descendants up to depth 3. Depth 3 covers the common case:
+  //   <body> → <root-layout-div> → <main> → <overflow-container>
+  // React context providers (SegmentProvider, NavigationProvider) don't add
+  // DOM elements, so depth 3 from body reaches nested layout scroll containers.
   for (const child of document.body.children) {
     candidates.push(child as HTMLElement);
     for (const grandchild of child.children) {
       candidates.push(grandchild as HTMLElement);
+      for (const greatGrandchild of grandchild.children) {
+        candidates.push(greatGrandchild as HTMLElement);
+      }
     }
   }
   for (const el of candidates) {
@@ -425,8 +444,24 @@ function bootstrap(runtimeConfig: typeof config): void {
       // Decode RSC Flight stream using createFromFetch.
       // createFromFetch takes a Promise<Response> and progressively
       // parses the RSC stream as chunks arrive.
-      decodeRsc: (fetchPromise: Promise<Response>) => {
-        return createFromFetch(fetchPromise);
+      //
+      // 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.
+      decodeRsc: async (fetchPromise: Promise<Response>) => {
+        try {
+          return await createFromFetch(fetchPromise);
+        } catch (error) {
+          if (isStaleClientReference(error)) {
+            triggerStaleReload();
+            // Return a never-resolving promise to prevent further processing
+            // while the page is reloading.
+            return new Promise(() => {});
+          }
+          throw error;
+        }
       },
 
       // Render decoded RSC tree via TransitionRoot's state-based mechanism.
@@ -614,6 +649,24 @@ function bootstrap(runtimeConfig: typeof config): void {
 
 bootstrap(config);
 
+// 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.
+window.addEventListener('unhandledrejection', (event) => {
+  if (isStaleClientReference(event.reason)) {
+    event.preventDefault();
+    triggerStaleReload();
+  }
+});
+
 // Signal that the client runtime has been initialized.
 // Used by E2E tests to wait for hydration before interacting.
 // We append a <meta name="timber-ready"> tag rather than setting a

package/src/client/stale-reload.ts

@@ -0,0 +1,89 @@
+/**
+ * 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';
+
+/**
+ * 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');
+}
+
+/**
+ * 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 may be unavailable (private browsing, storage full, etc.)
+    // Fall back to reloading without loop protection
+    console.warn(
+      '[timber] Stale client reference detected. Reloading page.'
+    );
+    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 {
+  try {
+    sessionStorage.removeItem(RELOAD_FLAG_KEY);
+  } catch {
+    // sessionStorage unavailable — nothing to clear
+  }
+}

package/src/server/compress.ts

@@ -55,11 +55,30 @@ const NO_COMPRESS_STATUSES = new Set([204, 304]);
 export function negotiateEncoding(acceptEncoding: string): 'gzip' | null {
   if (!acceptEncoding) return null;
 
-  // Parse tokens from the Accept-Encoding header (ignore quality values).
-  // e.g. "gzip;q=1.0, br;q=0.8, deflate" → ['gzip', 'br', 'deflate']
-  const tokens = acceptEncoding.split(',').map((s) => s.split(';')[0].trim().toLowerCase());
+  // Parse tokens with quality values from the Accept-Encoding header.
+  // Per RFC 9110 §12.5.3, q=0 means "not acceptable" — the client explicitly
+  // rejects that encoding. Tokens without a q-value default to q=1.
+  // e.g. "gzip;q=1.0, br;q=0" → gzip is acceptable, br is rejected.
+  const parts = acceptEncoding.split(',');
+  for (const part of parts) {
+    const [token, ...params] = part.split(';');
+    const name = token.trim().toLowerCase();
+    if (name !== 'gzip') continue;
+
+    // Check for q=0 (explicitly disabled)
+    let qValue = 1; // default quality is 1
+    for (const param of params) {
+      const trimmed = param.trim().toLowerCase();
+      if (trimmed.startsWith('q=')) {
+        qValue = parseFloat(trimmed.slice(2));
+        if (Number.isNaN(qValue)) qValue = 1;
+        break;
+      }
+    }
+
+    if (qValue > 0) return 'gzip';
+  }
 
-  if (tokens.includes('gzip')) return 'gzip';
   return null;
 }
 

package/src/server/state-tree-diff.ts

@@ -55,23 +55,24 @@ export function parseClientStateTree(req: Request): Set<string> | null {
  * @param clientSegments - Set of paths from X-Timber-State-Tree, or null
  */
 export function shouldSkipSegment(
-  urlPath: string,
-  layoutComponent: ((...args: unknown[]) => unknown) | undefined,
-  isLeaf: boolean,
-  clientSegments: Set<string> | null
+  _urlPath: string,
+  _layoutComponent: ((...args: unknown[]) => unknown) | undefined,
+  _isLeaf: boolean,
+  _clientSegments: Set<string> | null
 ): boolean {
-  // No state tree → full render (initial load, refresh, etc.)
-  if (!clientSegments) return false;
-
-  // Leaf segments (pages) are never skipped
-  if (isLeaf) return false;
-
-  // No layout → nothing to skip
-  if (!layoutComponent) return false;
-
-  // Async layouts always re-render (they may depend on request context)
-  if (layoutComponent.constructor?.name === 'AsyncFunction') return false;
-
-  // Skip if the client already has this segment cached
-  return clientSegments.has(urlPath);
+  // DISABLED: Server-side segment skipping is not safe without client-side
+  // tree merging. When the server omits a layout from the RSC payload, the
+  // client receives a tree with a different structure (no SegmentProvider,
+  // no layout wrapper). React sees a different component tree shape and
+  // re-mounts everything — destroying DOM state (input values, focus,
+  // scroll position) in layouts that should have been preserved.
+  //
+  // The correct fix requires client-side tree merging: the router must
+  // splice the partial RSC response into the existing cached tree, only
+  // replacing changed segments. Until that's implemented, always render
+  // the full tree. RSC naturally handles this efficiently — client
+  // components are sent as references, not re-serialized.
+  //
+  // See design/19-client-navigation.md §"X-Timber-State-Tree Header"
+  return false;
 }