@timber-js/app 0.2.0-alpha.181 → 0.2.0-alpha.183

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

@@ -40,7 +40,7 @@ import schemaCodecs from 'virtual:timber-schema';
 import { setLinkCodecs } from '../../params/codec-registry.js';
 setLinkCodecs(schemaCodecs);
 
-import { setClientDeploymentId } from '../rsc-fetch.js';
+import { setClientDeploymentId, setStaticMode } from '../rsc-fetch.js';
 
 import { setupServerActions } from './action-dispatch.js';
 import { createRscPayloadStream } from './rsc-stream.js';
@@ -63,12 +63,11 @@ 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';
+  // Static mode: fetch _rsc/*.rsc files instead of route URLs with
+  // Accept headers. Static hosts ignore Accept headers (TIM-1243).
+  if ((runtimeConfig as Record<string, unknown>).output === 'static') {
+    setStaticMode(true);
+  }
 
   // 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

@@ -695,7 +695,9 @@ 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) {

package/src/client/rsc-fetch.ts

@@ -88,6 +88,56 @@ export function getClientDeploymentId(): string | null {
   return clientDeploymentId;
 }
 
+// ─── Static Mode ────────────────────────────────────────────────
+
+/**
+ * When true, RSC fetches use _rsc/*.rsc file URLs instead of
+ * the route URL with Accept headers. Static hosts ignore Accept
+ * headers, so the client must fetch the pre-generated .rsc files
+ * directly. Set at bootstrap from virtual:timber-config output mode.
+ */
+let staticMode = false;
+
+export function setStaticMode(enabled: boolean): void {
+  staticMode = enabled;
+}
+
+export function isStaticMode(): boolean {
+  return staticMode;
+}
+
+/**
+ * Convert a route URL to the corresponding _rsc/*.rsc file path.
+ * Mirrors the naming in plugins/static-build.ts staticOutputPath.
+ *
+ *   /           → /_rsc/index.rsc
+ *   /about      → /_rsc/about.rsc
+ *   /blog/hello → /_rsc/blog/hello.rsc
+ */
+function toStaticRscUrl(url: string): string {
+  const hashIndex = url.indexOf('#');
+  const queryIndex = url.indexOf('?');
+  const hashEnd = hashIndex === -1 ? url.length : hashIndex;
+  const queryEnd = queryIndex === -1 ? url.length : queryIndex;
+  const end = Math.min(hashEnd, queryEnd);
+  let pathname = url.slice(0, end);
+  // Strip trailing slash (unless root) to match static build output naming
+  if (pathname.length > 1 && pathname.endsWith('/')) {
+    pathname = pathname.slice(0, -1);
+  }
+  const rscPath = pathname === '/' ? '/index' : pathname;
+  return `/_rsc${rscPath}.rsc`;
+}
+
+/**
+ * Convert a route URL to the corresponding _rsc/*.params.json sidecar path.
+ * Used in static mode to fetch route params that are normally carried
+ * in the X-Timber-Params response header. See TIM-1246.
+ */
+function toStaticParamsUrl(url: string): string {
+  return toStaticRscUrl(url).replace(/\.rsc$/, '.params.json');
+}
+
 // ─── Reload Signal ───────────────────────────────────────────────
 
 /** Header name used by the server to signal a version skew reload. */
@@ -326,8 +376,13 @@ export async function fetchRscPayload(
   currentUrl?: string,
   signal?: AbortSignal
 ): Promise<FetchResult> {
-  const rscUrl = appendRscParam(url);
-  const headers = buildRscHeaders(stateTree, currentUrl);
+  // In static mode, fetch the pre-generated _rsc/*.rsc file directly
+  // instead of the route URL with Accept headers. Static hosts ignore
+  // Accept headers, so the route URL would return HTML. The _rsc param
+  // is still appended for cache busting.
+  const fetchTarget = staticMode ? toStaticRscUrl(url) : url;
+  const rscUrl = appendRscParam(fetchTarget);
+  const headers = buildRscHeaders(staticMode ? undefined : stateTree, currentUrl);
   if (deps.decodeRsc) {
     // Production path: use createFromFetch for streaming RSC decoding.
     // createFromFetch takes a Promise<Response> and progressively parses
@@ -336,6 +391,21 @@ export async function fetchRscPayload(
     // Intercept the response to read segment metadata before createFromFetch
     // consumes the body. Reading headers does NOT consume the body stream.
     const fetchPromise = deps.fetch(rscUrl, { headers, redirect: 'manual', signal });
+    // In static mode, fetch the params sidecar in parallel. The .rsc
+    // file has no HTTP headers, so params come from a .params.json
+    // sidecar written at build time. See TIM-1246.
+    const staticParamsFetch = staticMode
+      ? deps
+          .fetch(toStaticParamsUrl(url), { signal })
+          .then((r) => (r.ok ? (r.json() as Promise<Record<string, string | string[]>>) : null))
+          .catch((e) => {
+            if (e instanceof DOMException && e.name === 'AbortError') throw e;
+            return null;
+          })
+      : null;
+    // Observe the sidecar promise so its rejection doesn't become
+    // unhandled if wrappedPromise rejects first (TIM-1248).
+    staticParamsFetch?.catch(() => {});
     let segmentInfo: SegmentInfo[] | null = null;
     let params: Record<string, string | string[]> | null = null;
     let skippedSegments: string[] | null = null;
@@ -368,14 +438,27 @@ 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);
+      // Content-Type guard: reject non-RSC responses before createFromFetch
+      // tries to parse the body as Flight data.
+      // In static mode, accept octet-stream/text/plain/absent content-type
+      // (static hosts serve .rsc files with these), but still reject 404s
+      // and text/html (missing .rsc file → host returns 404 page or SPA
+      // HTML fallback). See TIM-1231, TIM-1243, TIM-1247.
+      if (staticMode) {
+        const contentType = response.headers.get('content-type');
+        if (
+          !response.ok ||
+          (contentType && contentType.split(';')[0].trim().toLowerCase() === 'text/html')
+        ) {
+          response.body?.cancel();
+          throw new NonRscResponse(url);
+        }
+      } else {
+        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.
@@ -400,6 +483,11 @@ export async function fetchRscPayload(
     });
     // Await headers so segmentInfo/params are populated.
     await wrappedPromise;
+    // In static mode, params come from the sidecar (header extraction
+    // returns null because .rsc files have no HTTP headers). TIM-1246.
+    if (staticParamsFetch && !params) {
+      params = await staticParamsFetch;
+    }
     // Start decoding but do NOT await — return the in-progress thenable.
     // React can render a Flight thenable directly: it suspends on unresolved
     // parts and progressively renders as chunks arrive, spreading work across
@@ -432,20 +520,49 @@ export async function fetchRscPayload(
       throw new RedirectError(location);
     }
   }
-  // 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);
+  // 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, TIM-1243, TIM-1247.
+  if (staticMode) {
+    const fallbackContentType = response.headers.get('content-type');
+    if (
+      !response.ok ||
+      (fallbackContentType &&
+        fallbackContentType.split(';')[0].trim().toLowerCase() === 'text/html')
+    ) {
+      response.body?.cancel();
+      throw new NonRscResponse(url);
+    }
+  } else {
+    const fallbackContentType = response.headers.get('content-type');
+    if (
+      !fallbackContentType ||
+      !fallbackContentType.split(';')[0].trim().includes(RSC_CONTENT_TYPE)
+    ) {
+      response.body?.cancel();
+      throw new NonRscResponse(url);
+    }
+  }
+  let fallbackParams = extractParams(response);
+  // In static mode, params come from the sidecar. TIM-1246.
+  if (staticMode && !fallbackParams) {
+    try {
+      const paramsResponse = await deps.fetch(toStaticParamsUrl(url), { signal });
+      if (paramsResponse.ok) {
+        fallbackParams = (await paramsResponse.json()) as Record<string, string | string[]>;
+      }
+    } catch (e) {
+      if (e instanceof DOMException && e.name === 'AbortError') throw e;
+      // No params sidecar — non-dynamic route, params stay null
+    }
   }
   return {
     payload: await response.text(),
     decodePromise: null,
     segmentInfo: extractSegmentInfo(response),
-    params: extractParams(response),
+    params: fallbackParams,
     skippedSegments: extractSkippedSegments(response),
   };
 }

package/src/index.ts

@@ -557,13 +557,13 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
     timberRouting(ctx),
     timberEntries(ctx),
     timberBuildManifest(ctx),
-    timberStaticBuild(ctx),
     timberFonts(ctx),
     timberMdx(ctx),
     timberRequestDep(ctx),
     timberCacheTransform(ctx),
     timberPrerenderSugar(ctx), // export const prerender → cache.component() desugaring
     timberPrebuilt(ctx), // cache.component() → __prebuilt() callsite rewrite
+    timberStaticBuild(ctx), // Static mode: validate + post-build HTML generation
     timberContent(ctx),
     timberServerBundle(), // Bundle all deps in server environments for prod
     timberCloudflareWasm(ctx), // Externalize WASM for Cloudflare Workers

package/src/plugin-context.ts

@@ -160,6 +160,12 @@ export interface PluginContext {
    * ranges and rewrite CODE via MagicString; the AST itself is never mutated.
    */
   parseCached?: ParseMemo;
+  /**
+   * Content-Type mappings for extensionless static API route outputs.
+   * Populated during static generation, consumed by adapter-build to
+   * write per-path Content-Type rules in _headers. See TIM-1241.
+   */
+  staticContentTypes?: Record<string, string>;
 }
 
 // ── AST parse memo ───────────────────────────────────────────────────────

package/src/plugins/adapter-build.ts

@@ -88,6 +88,11 @@ export function timberAdapterBuild(ctx: PluginContext): Plugin {
           output: ctx.config.output ?? 'server',
           clientJavascriptDisabled: ctx.clientJavascript.disabled,
           manifestInit,
+          staticPagesDir:
+            (ctx.config.output ?? 'server') === 'static'
+              ? join(buildDir, 'static-pages')
+              : undefined,
+          staticContentTypes: ctx.staticContentTypes,
         };
 
         await adapter.buildOutput(adapterConfig, buildDir);

package/src/plugins/build-report.ts

@@ -48,25 +48,19 @@ const ROUTE_TYPE_ICONS: Record<RouteType, string> = {
 /**
  * Classify a route by its segment chain and output mode.
  *
- * In server mode (default), all pages are dynamic (rendered per-request).
- * In static mode, only pages with dynamic/catch-all segments are dynamic.
- * API routes (route.ts) are always classified as function.
+ * In server mode (default), all pages are dynamic (rendered per-request)
+ * and API routes (route.ts) are classified as function.
+ * In static mode, everything is pre-rendered at build time — all routes
+ * are static regardless of dynamic segments or route.ts presence.
  */
 export function classifyRoute(
   segments: SegmentNode[],
   outputMode: 'server' | 'static' = 'server'
 ): RouteType {
+  if (outputMode === 'static') return 'static';
   const leaf = segments[segments.length - 1];
   if (leaf?.route) return 'function';
-  if (outputMode === 'server') return 'dynamic';
-
-  const isDynamic = segments.some(
-    (s) =>
-      s.segmentType === 'dynamic' ||
-      s.segmentType === 'catch-all' ||
-      s.segmentType === 'optional-catch-all'
-  );
-  return isDynamic ? 'dynamic' : 'static';
+  return 'dynamic';
 }
 
 // ─── Size helpers ─────────────────────────────────────────────────────────

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;