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

package/src/adapters/types.ts

@@ -19,6 +19,20 @@ export interface TimberConfig {
    * Undefined when no build manifest was produced (e.g., dev mode or no client assets).
    */
   manifestInit?: string;
+  /**
+   * Absolute path to the directory containing pre-rendered static HTML,
+   * RSC flight files, and API route outputs. Present only when
+   * output: 'static' and the static generation pass completed.
+   * Layout: path/index.html, _rsc/path.rsc, api-route-path
+   */
+  staticPagesDir?: string;
+  /**
+   * Content-Type mappings for extensionless API route outputs.
+   * Map from URL path (e.g. "/api/data") to Content-Type value.
+   * Written during static generation, consumed by adapters when
+   * writing _headers. See TIM-1241.
+   */
+  staticContentTypes?: Record<string, string>;
 }
 
 /**

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,6 +63,12 @@ function bootstrap(runtimeConfig: typeof config): void {
     setClientDeploymentId(deploymentId);
   }
 
+  // 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/rsc-fetch.ts

@@ -88,6 +88,108 @@ 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;
+}
+
+/**
+ * RSC manifest mapping unhashed → hashed URLs. Populated from
+ * `window.__TIMBER_RSC_MANIFEST__` (injected into HTML during
+ * static generation). See TIM-1254.
+ */
+let rscManifest: Record<string, string> | null = null;
+
+function getRscManifest(): Record<string, string> | null {
+  if (rscManifest) return rscManifest;
+  if (typeof window !== 'undefined' && (window as any).__TIMBER_RSC_MANIFEST__) {
+    rscManifest = (window as any).__TIMBER_RSC_MANIFEST__;
+  }
+  return rscManifest;
+}
+
+/** @internal Exported for testing. */
+export function setRscManifest(manifest: Record<string, string> | null): void {
+  rscManifest = manifest;
+}
+
+/**
+ * Convert a route URL to the corresponding _rsc/*.rsc file path.
+ * Mirrors the naming in plugins/static-build.ts staticOutputPath.
+ *
+ * When an RSC manifest is available (hashed filenames from TIM-1254),
+ * the manifest is consulted to resolve to the hashed path.
+ *
+ *   /           → /_rsc/index.rsc (or /_rsc/index-B7YxEKdN.rsc with manifest)
+ *   /about      → /_rsc/about.rsc (or /_rsc/about-C8ZzFLfO.rsc with manifest)
+ *   /blog/hello → /_rsc/blog/hello.rsc
+ */
+function toStaticRscUrl(url: string): string {
+  const unhashed = toUnhashedRscUrl(url);
+  return manifestLookup(unhashed) ?? unhashed;
+}
+
+/**
+ * Compute the unhashed _rsc/*.rsc URL for a route path.
+ * @internal Exported for testing.
+ */
+export function toUnhashedRscUrl(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.
+ *
+ * Consults the RSC manifest for hashed filenames (TIM-1254).
+ */
+/**
+ * Look up a key in the RSC manifest, falling back to percent-decoded
+ * lookup for encoded browser URLs. Returns null if not found.
+ */
+function manifestLookup(key: string): string | null {
+  const manifest = getRscManifest();
+  if (!manifest) return null;
+  if (manifest[key]) return manifest[key];
+  try {
+    const decoded = decodeURIComponent(key);
+    if (decoded !== key && manifest[decoded]) return manifest[decoded];
+  } catch {
+    // Malformed percent sequence (e.g. /100%.rsc) — skip decoded lookup
+  }
+  return null;
+}
+
+function toStaticParamsUrl(url: string): string {
+  const unhashed = toUnhashedRscUrl(url).replace(/\.rsc$/, '.params.json');
+  return manifestLookup(unhashed) ?? unhashed;
+}
+
 // ─── Reload Signal ───────────────────────────────────────────────
 
 /** Header name used by the server to signal a version skew reload. */
@@ -326,8 +428,16 @@ 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.
+  const fetchTarget = staticMode ? toStaticRscUrl(url) : url;
+  // Skip the cache-bust param when the manifest supplies a content-hashed
+  // URL — the hash itself guarantees freshness, and the param would defeat
+  // the immutable cache headers on /_rsc/* (TIM-1254).
+  const isHashedFromManifest = staticMode && fetchTarget !== toUnhashedRscUrl(url);
+  const rscUrl = isHashedFromManifest ? fetchTarget : 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 +446,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 +493,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 +538,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
@@ -436,20 +579,45 @@ export async function fetchRscPayload(
   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);
+  // 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,18 @@ 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>;
+  /**
+   * RSC flight payload manifest mapping unhashed → hashed URLs.
+   * Populated during static generation, consumed by adapters to set
+   * immutable cache headers for `_rsc/` files. See TIM-1254.
+   */
+  rscManifest?: 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 ─────────────────────────────────────────────────────────