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

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
@@ -436,20 +524,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,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/static-build.ts

@@ -3,13 +3,24 @@
  *
  * When `output: 'static'` is set in timber.config.ts, this plugin:
  * 1. Validates that no dynamic APIs (getCookies(), getHeaders()) are used
- * 2. Coordinates build-time rendering of all pages
+ * 2. After the build, renders all routes to static HTML + RSC flight files
  *
- * Design doc: design/15-future-prerendering.md
+ * Design doc: design/11-platform.md §"static output mode"
  */
 
 import type { Plugin } from 'vite';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile, rename } from 'node:fs/promises';
+import { dirname, extname, join, resolve, relative } from 'node:path';
+import { pathToFileURL } from 'node:url';
 import type { PluginContext } from '../plugin-context.js';
+import type {
+  StaticGenerationOptions,
+  StaticGenerationSummary,
+  StaticPageEntry,
+  StaticRedirectEntry,
+} from '../server/static-generator.js';
+import { mergeRscAssetsManifest } from './adapter-build.js';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -74,6 +85,237 @@ export function detectDynamicApis(code: string, fileId: string): StaticValidatio
   return errors;
 }
 
+// ---------------------------------------------------------------------------
+// Redirect rules
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a `_redirects` file from collected redirect entries.
+ * Uses the Cloudflare Pages / Netlify format: `/from /to statusCode`
+ *
+ * @internal Exported for testing.
+ */
+export function generateRedirectsFile(redirects: StaticRedirectEntry[]): string {
+  const lines = redirects.map((r) => `${r.from} ${r.to} ${r.status}`);
+  return lines.join('\n') + '\n';
+}
+
+// ---------------------------------------------------------------------------
+// File output helpers
+// ---------------------------------------------------------------------------
+
+/** Write a file atomically: temp sibling + rename. */
+async function writeFileAtomic(path: string, data: Uint8Array | string): Promise<void> {
+  const tmp = `${path}.tmp`;
+  await writeFile(tmp, data);
+  await rename(tmp, path);
+}
+
+/**
+ * Determine the output file path for a static page entry.
+ *
+ * Pages: /about → about/index.html, / → index.html
+ * RSC:   /about → _rsc/about.rsc, / → _rsc/index.rsc
+ * API:   /feed.xml → feed.xml, /api/data → api/data
+ */
+export function staticOutputPath(entry: StaticPageEntry): string {
+  const urlPath = entry.urlPath === '/' ? '' : entry.urlPath;
+
+  if (entry.kind === 'rsc') {
+    const rscPath = urlPath || '/index';
+    return `_rsc${rscPath}.rsc`;
+  }
+
+  if (entry.kind === 'api') {
+    // API routes use their URL path directly. If no extension, fall
+    // back to the path as-is (static host serves based on content type).
+    return urlPath.startsWith('/') ? urlPath.slice(1) : urlPath || 'index';
+  }
+
+  // HTML pages
+  if (!urlPath) return 'index.html';
+  // Synthetic 404 entry from static generation — must be 404.html at the
+  // root so static hosts (GitHub Pages, Cloudflare Pages, Netlify) serve
+  // it automatically for unmatched URLs. Uses an internal urlPath to avoid
+  // colliding with a real /404 page route.
+  if (urlPath === '/_timber_not_found') return '404.html';
+  return `${urlPath.startsWith('/') ? urlPath.slice(1) : urlPath}/index.html`;
+}
+
+// ---------------------------------------------------------------------------
+// Static generation orchestration (runs after Vite build)
+// ---------------------------------------------------------------------------
+
+interface StaticGenerateModule {
+  __timber_generateStaticSite?: (
+    options: StaticGenerationOptions
+  ) => Promise<StaticGenerationSummary>;
+}
+
+/**
+ * Load the built RSC entry and run the static generation pass.
+ *
+ * Unlike prebuilt capture, this needs the FULL pipeline handler, so
+ * __TIMBER_CAPTURE_MODE__ must be false.
+ */
+async function runStaticGeneration(ctx: PluginContext): Promise<StaticGenerationSummary> {
+  const entryPath = join(ctx.buildDir, 'rsc', 'index.js');
+  if (!existsSync(entryPath)) {
+    throw new Error(
+      `[timber] Static generation: built RSC entry not found at ${entryPath} — ` +
+        `the build output is missing`
+    );
+  }
+
+  const g = globalThis as Record<string, unknown>;
+
+  // Set up the build manifest (same as adapter-build and prebuilt-capture).
+  if (ctx.buildManifest) g.__TIMBER_BUILD_MANIFEST__ ??= ctx.buildManifest;
+  if (ctx.deploymentId) g.__TIMBER_DEPLOYMENT_ID__ ??= ctx.deploymentId;
+
+  // Ensure capture mode is off — we need the full handler.
+  g.__TIMBER_CAPTURE_MODE__ = false;
+
+  // Merge per-route CSS and modulepreload entries from the RSC assets
+  // manifest into the build manifest BEFORE rendering, so rendered HTML
+  // includes all <link> tags. This same merge normally runs in
+  // adapter-build, but static generation runs first.
+  if (ctx.buildManifest) {
+    await mergeRscAssetsManifest(ctx.buildDir, ctx.root, ctx.buildManifest, ctx.routeClientRefKeys);
+  }
+
+  console.log('[timber] Static generation: building site…');
+
+  let mod: StaticGenerateModule;
+  try {
+    const entryUrl = `${pathToFileURL(entryPath).href}?t=${Date.now()}`;
+    mod = (await import(/* @vite-ignore */ entryUrl)) as StaticGenerateModule;
+  } catch (error) {
+    throw new Error(
+      `[timber] Static generation: failed to load the built RSC entry (${entryPath}). ` +
+        `The full request handler must initialize for static rendering.`,
+      { cause: error }
+    );
+  }
+
+  const generate = mod.__timber_generateStaticSite;
+  if (typeof generate !== 'function') {
+    throw new Error(
+      `[timber] Static generation: built RSC entry does not export ` +
+        `__timber_generateStaticSite — rebuild from a clean build directory`
+    );
+  }
+
+  const staticDir = join(ctx.buildDir, 'static-pages');
+  await mkdir(staticDir, { recursive: true });
+
+  const sitemapConfig = ctx.config.sitemap;
+  const autoSitemapEnabled = Boolean(sitemapConfig?.enabled && sitemapConfig?.baseUrl);
+
+  const contentTypes: Record<string, string> = {};
+
+  const summary = await generate({
+    autoSitemapEnabled,
+    renderTimeoutMs: ctx.config.renderTimeoutMs,
+    onEntry: async (entry: StaticPageEntry) => {
+      const relPath = staticOutputPath(entry);
+      const fullPath = resolve(staticDir, relPath);
+
+      // Reject path traversal: generated params with "../" could escape
+      // the output directory and overwrite build artifacts.
+      const rel = relative(staticDir, fullPath);
+      if (rel.startsWith('..') || resolve(staticDir, rel) !== fullPath) {
+        throw new Error(
+          `[timber] Static generation: output path "${relPath}" escapes the ` +
+            `static output directory — check generateStaticSegmentParams for ` +
+            `path traversal characters in ${entry.urlPath}`
+        );
+      }
+
+      await mkdir(dirname(fullPath), { recursive: true });
+      await writeFileAtomic(fullPath, entry.body);
+
+      // Write params sidecar for RSC entries with route params.
+      // Static .rsc files don't carry HTTP headers, so the client
+      // fetches this sidecar to populate useSegmentParams(). TIM-1246.
+      if (entry.kind === 'rsc' && entry.headers['x-timber-params']) {
+        const paramsPath = fullPath.replace(/\.rsc$/, '.params.json');
+        await writeFileAtomic(paramsPath, entry.headers['x-timber-params']);
+      }
+
+      // Track Content-Type for extensionless API routes so adapters
+      // can write per-path Content-Type rules in _headers. TIM-1241.
+      if (entry.kind === 'api' && !extname(relPath) && entry.contentType) {
+        contentTypes[entry.urlPath] = entry.contentType;
+      }
+    },
+  });
+
+  const totalUrls = summary.rendered + summary.errors.length;
+  console.log(
+    `[timber] Static generation: rendered ${summary.rendered}/${totalUrls} entries.` +
+      (summary.errors.length > 0 ? ` ${summary.errors.length} failed.` : '') +
+      (summary.redirects.length > 0 ? ` ${summary.redirects.length} redirect(s).` : '')
+  );
+
+  if (summary.errors.length > 0) {
+    const details = summary.errors.map((e) => `  - ${e.urlPath}: ${e.message}`).join('\n');
+    throw new Error(`[timber] Static generation failed:\n${details}`);
+  }
+
+  // Store content-type mappings on the plugin context so adapters
+  // can include them in the _headers file. TIM-1241.
+  if (Object.keys(contentTypes).length > 0) {
+    ctx.staticContentTypes = contentTypes;
+  }
+
+  // Write _redirects file for platform redirect rules (Cloudflare Pages,
+  // Netlify, etc.). Format: /from /to status. See TIM-1245.
+  if (summary.redirects.length > 0) {
+    const generated = generateRedirectsFile(summary.redirects);
+    const redirectsPath = join(staticDir, '_redirects');
+
+    // Merge with user-authored _redirects if present. TIM-1249.
+    const userRedirects = await readUserRedirects(ctx.root);
+    if (userRedirects !== null) {
+      await writeFileAtomic(redirectsPath, generated + '\n' + userRedirects);
+      console.log(
+        `[timber] Static generation: wrote _redirects with ${summary.redirects.length} ` +
+          `generated rule(s), merged with user-authored _redirects`
+      );
+    } else {
+      await writeFileAtomic(redirectsPath, generated);
+      console.log(
+        `[timber] Static generation: wrote _redirects with ${summary.redirects.length} rule(s)`
+      );
+    }
+  }
+
+  return summary;
+}
+
+// ---------------------------------------------------------------------------
+// User-authored _redirects merge (TIM-1249)
+// ---------------------------------------------------------------------------
+
+/**
+ * Read a user-authored `_redirects` file from the project's `public/`
+ * directory. Returns `null` if no file exists.
+ *
+ * @internal Exported for testing.
+ */
+export async function readUserRedirects(root: string): Promise<string | null> {
+  const candidates = [join(root, 'public', '_redirects')];
+  for (const path of candidates) {
+    try {
+      return await readFile(path, 'utf-8');
+    } catch {
+      // File doesn't exist — try next
+    }
+  }
+  return null;
+}
+
 // ---------------------------------------------------------------------------
 // Vite Plugin
 // ---------------------------------------------------------------------------
@@ -85,6 +327,7 @@ export function detectDynamicApis(code: string, fileId: string): StaticValidatio
  *
  * Hooks:
  * - transform: Validates source files for static mode violations
+ * - buildApp (post): Renders all routes to static HTML after the build
  */
 export function timberStaticBuild(ctx: PluginContext): Plugin {
   return {
@@ -128,5 +371,24 @@ export function timberStaticBuild(ctx: PluginContext): Plugin {
 
       return null;
     },
+
+    /**
+     * After all environments are built, render every route to static HTML.
+     *
+     * Runs with order: 'post' so the RSC plugin's buildApp completes first,
+     * producing the built entry we import. Must run BEFORE the adapter
+     * build copies output to its platform-specific directory.
+     */
+    buildApp: {
+      order: 'post' as const,
+      async handler() {
+        if (ctx.dev) return;
+
+        const isStatic = ctx.config.output === 'static';
+        if (!isStatic) return;
+
+        await runStaticGeneration(ctx);
+      },
+    },
   };
 }

package/src/server/rsc-entry/index.ts

@@ -69,6 +69,7 @@ import { capturePrebuiltPayloads } from '../prebuilt-builder.js';
 import { setPrebuiltPayloadSource } from '../prebuilt/payload-source.js';
 import { setRscFunctions, setComponentRefreshTimeout } from '../prebuilt-runtime.js';
 import { createAutoSitemapHandler } from '../sitemap-handler.js';
+import { generateStaticSite } from '../static-generator.js';
 
 /**
  * Resolve the Server-Timing mode from timber.config.ts.
@@ -461,6 +462,29 @@ export function __timber_capturePrebuilt(
   return capturePrebuiltPayloads(routeManifest, options);
 }
 
+/**
+ * Post-build static site generation entry point (TIM-1238). Renders every
+ * route in the manifest to HTML + RSC flight payloads. Must run inside the
+ * built RSC bundle — the handler, route manifest, and page module loaders
+ * are module instances in THIS bundle's graph.
+ *
+ * Unlike capture mode, this needs the full pipeline handler, so it must
+ * NOT run when __TIMBER_CAPTURE_MODE__ is set.
+ *
+ * See design/11-platform.md §"static output mode".
+ */
+export function __timber_generateStaticSite(
+  options: import('../static-generator.js').StaticGenerationOptions
+): Promise<import('../static-generator.js').StaticGenerationSummary> {
+  if (!_handler) {
+    throw new Error(
+      '[timber] __timber_generateStaticSite requires the full request handler. ' +
+        'Do not call in capture mode (__TIMBER_CAPTURE_MODE__).'
+    );
+  }
+  return generateStaticSite(routeManifest, _handler, options);
+}
+
 // Schema codecs are needed by both the capture path (param coercion) and
 // the request handler, so register them unconditionally.
 setGlobalSchemaCodecs(globalSchemaCodecs);

package/src/server/sitemap-generator.ts

@@ -339,7 +339,7 @@ export async function generateSitemap(
  * When a user-authored sitemap exists at the root, auto-generation is disabled
  * to avoid conflicts — the user takes full control.
  */
-export function hasUserSitemap(root: SegmentNode): boolean {
+export function hasUserSitemap(root: SegmentNode<unknown>): boolean {
   if (!root.metadataRoutes) return false;
   return 'sitemap' in root.metadataRoutes;
 }