@timber-js/app 0.2.0-alpha.180 → 0.2.0-alpha.182

package/dist/plugins/request-dep.d.ts

@@ -17,5 +17,16 @@
  */
 import type { Plugin } from 'vite';
 import type { PluginContext } from '../plugin-context.js';
+import { type ProgramNode } from './callsite-ast.js';
+export declare function isFrameworkModule(id: string): boolean;
+export interface ModuleFacts {
+    /** Module directly calls a request accessor. */
+    callsAccessor: boolean;
+    /** Module imports a definition factory (defineSearchParams/defineCookie). */
+    importsDefinitionFactory: boolean;
+    /** Import specifiers where `.get()` was called on the binding. */
+    getterCallSources: string[];
+}
+export declare function analyzeModule(code: string, program: ProgramNode): ModuleFacts;
 export declare function timberRequestDep(ctx: PluginContext): Plugin;
 //# sourceMappingURL=request-dep.d.ts.map

package/dist/plugins/request-dep.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"request-dep.d.ts","sourceRoot":"","sources":["../../src/plugins/request-dep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AACnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAoT1D,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CA0G3D"}
+{"version":3,"file":"request-dep.d.ts","sourceRoot":"","sources":["../../src/plugins/request-dep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AACnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAEL,KAAK,WAAW,EAIjB,MAAM,mBAAmB,CAAC;AA0B3B,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAKrD;AA2BD,MAAM,WAAW,WAAW;IAC1B,gDAAgD;IAChD,aAAa,EAAE,OAAO,CAAC;IACvB,6EAA6E;IAC7E,wBAAwB,EAAE,OAAO,CAAC;IAClC,kEAAkE;IAClE,iBAAiB,EAAE,MAAM,EAAE,CAAC;CAC7B;AAID,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,WAAW,CAiF7E;AA0LD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAgH3D"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.180",
+  "version": "0.2.0-alpha.182",
   "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",
@@ -158,7 +158,7 @@
     "jsonc-parser": "^3.3.1",
     "magic-string": "^0.30.21",
     "nitro": "3.0.260610-beta",
-    "srvx": "^0.11.22"
+    "srvx": "^0.12.0"
   },
   "peerDependencies": {
     "@content-collections/core": "^0.14.0 || ^0.15.0",
@@ -166,7 +166,7 @@
     "@content-collections/vite": "^0.2.0 || ^0.3.0",
     "@mdx-js/rollup": "^3.0.0",
     "@vitejs/plugin-react": "^6.0.0",
-    "@vitejs/plugin-rsc": ">=0.5.27",
+    "@vitejs/plugin-rsc": ">=0.5.28",
     "nuqs": "^2.0.0",
     "react": "19.2.7",
     "react-dom": "19.2.7",

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

@@ -63,13 +63,6 @@ function bootstrap(runtimeConfig: typeof config): void {
     setClientDeploymentId(deploymentId);
   }
 
-  // Take manual control of scroll restoration. Even though segment tree
-  // merging preserves shared layout DOM via cloneElement (so React doesn't
-  // reset scroll on those elements), the root-level reactRoot.render() with
-  // a new element tree can still cause scroll resets on the document during
-  // reconciliation. Manual control ensures consistent behavior.
-  window.history.scrollRestoration = 'manual';
-
   // Step 2: Decode inlined RSC payload (may be null for JS-only clients)
   const rscResult = createRscPayloadStream();
 

package/src/client/browser-entry/post-hydration.ts

@@ -59,13 +59,24 @@ export function setupPostHydration({
     segmentInfo: initialSegmentInfo,
   });
 
-  // Initialize scroll state for the initial entry.
-  // When Navigation API is available, use per-entry state.
-  // Otherwise fall back to history.state.
+  // Leave scrollRestoration = 'auto' so the browser natively restores
+  // scroll on reload, tab restore, and back-from-external-page — cases
+  // JS cannot reliably cover because 'manual' persists on the session
+  // history entry across reloads. For client navigations the router's
+  // restoreScrollAfterPaint() re-applies the saved position after React
+  // commits, writing last and winning over the browser's auto-restore.
+  // Explicitly set 'auto' to heal entries from previously-deployed builds
+  // that set 'manual'.
+  window.history.scrollRestoration = 'auto';
+
+  // Initialize scroll state for the initial entry. On reload the browser's
+  // native restoration may land before or after this runs; the debounced
+  // scroll listener below updates the entry state to the true position.
+  const initialScrollY = getScrollY();
   if (navApiController) {
-    navApiController.saveScrollPosition(0);
+    navApiController.saveScrollPosition(initialScrollY);
   } else {
-    window.history.replaceState({ timber: true, scrollY: 0 }, '');
+    window.history.replaceState({ timber: true, scrollY: initialScrollY }, '');
   }
 
   // Register popstate handler for back/forward navigation.

package/src/client/router.ts

@@ -16,6 +16,7 @@ import {
   RedirectError,
   ServerErrorResponse,
   VersionSkewError,
+  NonRscResponse,
 } from './rsc-fetch.js';
 import { setHardNavigating, supersedeNavigationTransitions } from './navigation-root.js';
 import type { FetchResult } from './rsc-fetch.js';
@@ -542,8 +543,16 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       departingUrl?: string;
     }
   ): Promise<FetchResult & { navState: NavigationState }> {
-    // Check prefetch cache first. PrefetchResult has optional segmentInfo/params
-    // fields — normalize to null for FetchResult compatibility.
+    // Check prefetch cache first. A negative entry means a prior prefetch
+    // determined this URL is not a route (non-RSC Content-Type). Hard-navigate
+    // immediately without a second fetch. See TIM-1231.
+    if (prefetchCache.isNegative(url)) {
+      prefetchCache.consume(url);
+      throw new NonRscResponse(url);
+    }
+
+    // PrefetchResult has optional segmentInfo/params fields — normalize
+    // to null for FetchResult compatibility.
     const prefetched = prefetchCache.consume(url);
     let result: FetchResult | undefined = prefetched
       ? {
@@ -686,7 +695,17 @@ export function createRouter(deps: RouterDeps): RouterInstance {
           }
           if (error instanceof ServerErrorResponse) {
             setHardNavigating(true);
-            window.location.href = error.url;
+            // Use the original `url` (with #fragment), not error.url which
+            // is hash-stripped. Preserves fragment on hard navigation.
+            window.location.href = url;
+            await new Promise(() => {});
+          }
+          if (error instanceof NonRscResponse) {
+            setHardNavigating(true);
+            // Use the original `url` (with #fragment), not error.url which
+            // is hash-stripped. Preserves fragment on hard navigation (e.g.,
+            // /manual.pdf#page=5). Matches no-JS <a> behavior.
+            window.location.href = url;
             await new Promise(() => {});
           }
           throw error;
@@ -804,7 +823,11 @@ export function createRouter(deps: RouterDeps): RouterInstance {
         result.decodePromise?.catch(() => {});
         prefetchCache.set(fetchUrl, result);
       },
-      () => {
+      (error) => {
+        if (error instanceof NonRscResponse) {
+          prefetchCache.setNegative(fetchUrl);
+          return;
+        }
         // Prefetch failure is non-fatal — navigation will fetch fresh
       }
     );

package/src/client/rsc-fetch.ts

@@ -246,6 +246,24 @@ export class ServerErrorResponse extends Error {
   }
 }
 
+/**
+ * Thrown when the RSC fetch response has a Content-Type that is not
+ * text/x-component — e.g., a static asset (image, CSS, JS) served
+ * for a same-origin URL that isn't a route. The response body is
+ * cancelled immediately (headers-only cost). Caught in navigate()
+ * to trigger a hard navigation; caught in prefetch() to store a
+ * negative cache entry so click hard-navigates without a second fetch.
+ *
+ * See TIM-1231.
+ */
+export class NonRscResponse extends Error {
+  readonly url: string;
+  constructor(url: string) {
+    super(`Non-RSC response for ${url}`);
+    this.url = url;
+  }
+}
+
 // ─── Stream Completion Tracking ───────────────────────────────────
 
 /**
@@ -350,6 +368,15 @@ export async function fetchRscPayload(
       if (response.headers.get('X-Timber-Error') === '1') {
         throw new ServerErrorResponse(response.status, url);
       }
+      // Content-Type guard: reject non-RSC responses (static assets, proxied
+      // files, etc.) before createFromFetch tries to parse the body as Flight
+      // data. Cancel the body immediately so the asset is never downloaded.
+      // See TIM-1231.
+      const contentType = response.headers.get('content-type');
+      if (!contentType || !contentType.split(';')[0].trim().includes(RSC_CONTENT_TYPE)) {
+        response.body?.cancel();
+        throw new NonRscResponse(url);
+      }
       // Metadata (<title>/<meta>/<link>) now rides the RSC Flight payload
       // as React elements — React 19 Float handles them. See TIM-1151.
       segmentInfo = extractSegmentInfo(response);
@@ -405,6 +432,19 @@ export async function fetchRscPayload(
       throw new RedirectError(location);
     }
   }
+  // Server error guard (same as production path above).
+  if (response.headers.get('X-Timber-Error') === '1') {
+    throw new ServerErrorResponse(response.status, url);
+  }
+  // Content-Type guard (same as production path above). See TIM-1231.
+  const fallbackContentType = response.headers.get('content-type');
+  if (
+    !fallbackContentType ||
+    !fallbackContentType.split(';')[0].trim().includes(RSC_CONTENT_TYPE)
+  ) {
+    response.body?.cancel();
+    throw new NonRscResponse(url);
+  }
   return {
     payload: await response.text(),
     decodePromise: null,

package/src/client/segment-cache.ts

@@ -239,6 +239,9 @@ interface PrefetchEntry {
   expiresAt: number;
 }
 
+/** Sentinel value for negative cache entries (URL is not a route). */
+const NEGATIVE_ENTRY: PrefetchResult = Object.freeze({ payload: null });
+
 /**
  * Short-lived cache for hover-triggered prefetches. Entries expire after
  * 30 seconds. When a link is clicked, the prefetched payload is consumed
@@ -276,4 +279,15 @@ export class PrefetchCache {
     }
     return result;
   }
+
+  /** Store a negative entry — the URL is not a route (non-RSC Content-Type). */
+  setNegative(url: string): void {
+    this.set(url, NEGATIVE_ENTRY);
+  }
+
+  /** Check if the entry is a negative cache entry (URL is not a route). */
+  isNegative(url: string): boolean {
+    const entry = this.get(url);
+    return entry === NEGATIVE_ENTRY;
+  }
 }

package/src/plugins/request-dep.ts

@@ -48,6 +48,15 @@ const DEFINITION_FACTORY_SOURCES = new Set([
 
 const DEFINITION_FACTORY_NAMES = new Set(['defineSearchParams', 'defineCookie']);
 
+// ─── Framework module detection ─────────────────────────────────────────
+
+export function isFrameworkModule(id: string): boolean {
+  return (
+    /[\\/]node_modules[\\/]@timber-js[\\/]app[\\/]/.test(id) ||
+    /[\\/]packages[\\/]timber-app[\\/]src[\\/]/.test(id)
+  );
+}
+
 // ─── Fast token pre-filter ───────────────────────────────────────────────
 
 const ACCESSOR_TOKENS = [
@@ -73,7 +82,7 @@ function hasRelevantToken(code: string): boolean {
 
 // ─── Per-module facts ────────────────────────────────────────────────────
 
-interface ModuleFacts {
+export interface ModuleFacts {
   /** Module directly calls a request accessor. */
   callsAccessor: boolean;
   /** Module imports a definition factory (defineSearchParams/defineCookie). */
@@ -84,7 +93,7 @@ interface ModuleFacts {
 
 // ─── AST analysis ────────────────────────────────────────────────────────
 
-function analyzeModule(code: string, program: ProgramNode): ModuleFacts {
+export function analyzeModule(code: string, program: ProgramNode): ModuleFacts {
   const facts: ModuleFacts = {
     callsAccessor: false,
     importsDefinitionFactory: false,
@@ -224,7 +233,34 @@ function walkForCall(
   return false;
 }
 
-/** Check if `localName.get(...)` appears anywhere in the module. */
+/**
+ * Check if the object chain of a `.get()` call contains `localName`.
+ * Walks through MemberExpression objects and CallExpression callees
+ * to handle chained patterns like `getFilterCookie(key).get()` or
+ * `cookies.theme.get()`.
+ */
+function objectChainContains(node: Record<string, unknown>, name: string): boolean {
+  if (node.type === 'Identifier' && (node as unknown as IdentifierNode).name === name) return true;
+  if (node.type === 'MemberExpression') {
+    return objectChainContains(
+      (node as unknown as MemberExpressionNode).object as Record<string, unknown>,
+      name
+    );
+  }
+  if (node.type === 'CallExpression') {
+    return objectChainContains(
+      (node as unknown as CallExpressionNode).callee as Record<string, unknown>,
+      name
+    );
+  }
+  return false;
+}
+
+/**
+ * Check if `.get(...)` is called on `localName` anywhere in the module.
+ * Handles direct (`localName.get()`), chained call (`localName(args).get()`),
+ * and nested member (`localName.prop.get()`) patterns.
+ */
 function hasGetterCall(node: Record<string, unknown>, localName: string): boolean {
   if (node.type === 'CallExpression') {
     const call = node as unknown as CallExpressionNode;
@@ -232,10 +268,9 @@ function hasGetterCall(node: Record<string, unknown>, localName: string): boolea
       const member = call.callee as MemberExpressionNode;
       if (
         !member.computed &&
-        member.object.type === 'Identifier' &&
-        (member.object as IdentifierNode).name === localName &&
         member.property.type === 'Identifier' &&
-        (member.property as IdentifierNode).name === 'get'
+        (member.property as IdentifierNode).name === 'get' &&
+        objectChainContains(member.object as Record<string, unknown>, localName)
       ) {
         return true;
       }
@@ -342,6 +377,12 @@ export function timberRequestDep(ctx: PluginContext): Plugin {
       if (!/\.[mc]?[jt]sx?$/.test(id) && !/\.mdx?$/.test(id)) return;
       // Skip virtual modules
       if (id.startsWith('\0') || id.startsWith('virtual:')) return;
+      // Skip framework modules — their internal accessor calls (e.g.,
+      // getCookieJar in define-cookie.ts) are implementation details.
+      // In dev they're externalized and never reach transform; in prod
+      // they would cause false positives (any module importing defineCookie
+      // would be tainted). Analysis relies on user-code .get() patterns.
+      if (isFrameworkModule(id)) return;
       // Fast token check
       if (!hasRelevantToken(code)) return;