@timber-js/app 0.2.0-alpha.207 → 0.2.0-alpha.209

package/src/index.ts

@@ -28,6 +28,7 @@ import { timberBuildManifest } from './plugins/build-manifest.ts';
 import { timberDevLogs, originalConsole, wrapLoggerWithOriginalConsole } from './dev-tools/logs.ts';
 import { resolveForwardConsole } from './dev-tools/browser-logs.ts';
 import { timberReactProd } from './plugins/react-prod.ts';
+import { timberReactResolve } from './plugins/react-resolve.ts';
 import { timberChunks } from './plugins/chunks.ts';
 import { clientChunkGroup } from './plugins/client-chunks.ts';
 import { timberServerBundle } from './plugins/server-bundle.ts';
@@ -36,7 +37,7 @@ import { timberRequestDep } from './plugins/request-dep/index.ts';
 import { timberPrebuilt } from './plugins/prebuilt.ts';
 import { timberPrerenderSugar } from './plugins/prerender-sugar.ts';
 import { timberCloudflareWasm } from './plugins/cloudflare-wasm.ts';
-import { timberAdapterBuild } from './plugins/adapter-build.ts';
+import { timberPostBuild } from './plugins/post-build.ts';
 import { timberBuildReport } from './plugins/build-report.ts';
 import { createNoopTimer } from './utils/startup-timer.ts';
 import {
@@ -288,11 +289,11 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
       // ── Resolve build output directory ─────────────────────────
       // Priority: timber.config.ts `buildDir` > Vite `build.outDir` > .timber/dist
       // Set Vite's build.outDir so the RSC plugin and all environment
-      // builds write to the correct location.
-      const viteOutDir = userConfig.build?.outDir;
-      const timberBuildDir = ctx.config.buildDir;
+      // builds write to the correct location. ctx.buildDir is read back
+      // from Vite in configResolved, so there is one answer to where the
+      // build went.
       const resolvedRoot = resolve(userConfig.root ?? process.cwd());
-      ctx.buildDir = resolveBuildDir(resolvedRoot, timberBuildDir, viteOutDir);
+      const buildDir = resolveBuildDir(resolvedRoot, ctx.config.buildDir, userConfig.build?.outDir);
 
       // Warn if the Vite root differs from cwd and the re-loaded config
       // has reactCompiler but the early cwd-based load missed it. In this
@@ -385,9 +386,9 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
         resolvedDevPortExplicit = start.explicit;
       }
 
-      // Derive relative buildOutDir from the absolute ctx.buildDir (set above)
+      // Derive relative buildOutDir from the absolute buildDir (set above)
       // so Vite's config receives a root-relative path.
-      const buildOutDir = relative(resolvedRoot, ctx.buildDir);
+      const buildOutDir = relative(resolvedRoot, buildDir);
 
       // Set per-environment build.outDir so Vite's RSC plugin writes
       // each environment to the correct subdirectory under our buildDir.
@@ -499,8 +500,10 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
       // The watcher.add() call in dev-server.ts ensures the files are
       // watched even if created after server start.
 
-      // Sync buildDir from Vite's resolved build.outDir. Vite keeps
-      // outDir as-is (may be relative), so resolve against root.
+      // The build directory is what Vite resolved build.outDir to — the
+      // config hook's value after every other plugin and the user config had
+      // their say. Vite keeps outDir as-is (may be relative), so resolve
+      // against root.
       ctx.buildDir = resolve(resolved.root, resolved.build.outDir);
       // In production builds, swap to a no-op timer to avoid overhead
       if (!ctx.dev) {
@@ -551,8 +554,17 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
   // We do NOT set customBuildApp — the RSC plugin's orchestration is correct
   // and handles bundle ordering, asset manifest generation, and environment
   // imports manifest. See @vitejs/plugin-rsc's buildApp implementation.
+  //
+  // Everything after it runs in timber-post-build, in the order that plugin
+  // states. The plugins that own a post-build step expose it as their `api`
+  // and are handed to it here, so no step's order depends on where a plugin
+  // sits in this array. See design/18-build-system.md §"Post-Build Phase".
+  const fonts = timberFonts(ctx);
+  const prebuilt = timberPrebuilt(ctx);
+  const buildReport = timberBuildReport(ctx);
   return [
     rootSync,
+    timberReactResolve(),
     timberReactProd(),
     // @vitejs/plugin-react provides React Fast Refresh (state-preserving HMR)
     // for client components via Babel transform. Placed before @vitejs/plugin-rsc
@@ -568,19 +580,19 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
     timberRouting(ctx),
     timberEntries(ctx),
     timberBuildManifest(ctx),
-    timberFonts(ctx),
+    fonts,
     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
+    prebuilt, // cache.component() → __prebuilt() callsite rewrite
+    timberStaticBuild(ctx), // Static mode: validate dynamic API usage
     timberContent(ctx),
     timberServerBundle(), // Bundle all deps in server environments for prod
     timberCloudflareWasm(ctx), // Externalize WASM for Cloudflare Workers
     timberChunks(ctx),
-    timberBuildReport(ctx), // Post-build: route table with bundle sizes
-    timberAdapterBuild(ctx), // Post-build: invoke adapter.buildOutput()
+    buildReport, // Route table with bundle sizes, printed by timber-post-build
+    timberPostBuild(ctx, { fonts: fonts.api, prebuilt: prebuilt.api, report: buildReport.api }),
     timberDevLogs(ctx), // Dev-only: forward server console.* to browser console
     timberDevServer(ctx), // Must be last — configureServer post-hook runs after all watchers
   ];

package/src/plugin-context.ts

@@ -14,13 +14,13 @@ import { createRequire } from 'node:module';
 import { parseAst } from 'vite';
 import type { RouteTree } from './routing/types.ts';
 import type { BuildManifest } from './server/build-manifest.ts';
-import type { CaptureSummary } from './server/prebuilt-builder.ts';
 import type { StartupTimer } from './utils/startup-timer.ts';
 import { createStartupTimer } from './utils/startup-timer.ts';
 import type { TimberUserConfig, ClientJavascriptConfig } from './config-types.ts';
-import type { RscManifest } from './plugins/static-build.ts';
 import type { HoldingServer } from './dev-tools/holding-server.ts';
 import type { ProgramNode } from './plugins/callsite-ast.ts';
+import type { TimberConfig, TimberPlatformAdapter } from './adapters/types.ts';
+import { normalizeBasePath } from './shared/base-path.ts';
 
 // Re-export for sub-plugin convenience — they import from plugin-context.ts
 export type { TimberUserConfig, ClientJavascriptConfig } from './config-types.ts';
@@ -88,7 +88,11 @@ export interface PluginContext {
    * does). See TIM-1261.
    */
   base: string;
-  /** CSS build manifest (populated by adapter after client build, null in dev) */
+  /**
+   * The build manifest. Created by timber-build-manifest from the client
+   * bundle and finalized by the post-build phase (plugins/post-build.ts),
+   * which is the only reader. Null in dev.
+   */
   buildManifest: BuildManifest | null;
   /** Per-build deployment ID for version skew detection (null in dev) */
   deploymentId: string | null;
@@ -103,13 +107,16 @@ export interface PluginContext {
    * `timber.config.ts` `buildDir` or Vite's `build.outDir`.
    * Timber config takes precedence when both are set.
    *
-   * Used by adapter-build and cli preview.
+   * The `config` hook resolves it into Vite's `build.outDir`, and
+   * `configResolved` reads it back from Vite — the one assignment after
+   * construction, so what the build writes to and what `timber preview`
+   * serves (through {@link TimberPluginApi}) are the same directory.
    */
   buildDir: string;
   /**
    * Per-route client reference keys captured during the RSC build.
    * Maps absolute route file paths to the set of client reference
-   * hash keys they transitively import. Used by adapter-build to
+   * hash keys they transitively import. Used by the post-build phase to
    * populate per-route modulepreload entries from clientReferenceDeps.
    */
   routeClientRefKeys?: Map<string, Set<string>>;
@@ -138,19 +145,6 @@ export interface PluginContext {
    * See design/27-chunking-strategy.md, TIM-1107.
    */
   sharedModuleFacades?: Map<string, string[]>;
-  /**
-   * Module ID → prebuilt component IDs declared in it. Recorded by the
-   * timber-prebuilt transform (RSC environment, production builds only),
-   * consumed by the RSC `generateBundle` module-graph walk that computes
-   * `routePrebuiltComponents`. See design/44-render-at-build-time.md.
-   */
-  prebuiltModuleComponents?: Map<string, string[]>;
-  /**
-   * Module ID → mapping of variable name to component ID for the prebuilt
-   * components declared in that module. Used at `generateBundle` time to
-   * trace imports from other modules back to specific component IDs.
-   */
-  prebuiltBindingNames?: Map<string, Map<string, string>>;
   /**
    * Component ID → distinct static call-site prop objects captured from
    * JSX usage sites during the transform and generateBundle phases.
@@ -165,12 +159,6 @@ export interface PluginContext {
    * components to render under which route's param combos.
    */
   routePrebuiltComponents?: Map<string, string[]>;
-  /**
-   * Page file paths that were desugared from `export const prerender` by
-   * timber-prerender-sugar. The prebuilt transform uses this to verify
-   * the generated `cache.component(...)` call was picked up.
-   */
-  prerenderSugarPages?: Set<string>;
   /**
    * Component ID → built chunk file name for prebuilt-declaring modules
    * that are only reachable via dynamic imports (import.meta.glob, lazy
@@ -179,8 +167,6 @@ export interface PluginContext {
    * RSC generateBundle alongside routePrebuiltComponents.
    */
   prebuiltLazyChunks?: Map<string, string>;
-  /** Post-build prebuilt capture summary (populated by timber-prebuilt, consumed by build-report). */
-  captureSummary?: CaptureSummary;
   /**
    * Content-keyed AST parse memo shared across cache/prebuilt/prerender-sugar
    * transforms. Collapses both cross-plugin and cross-environment duplicate
@@ -192,18 +178,6 @@ 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?: RscManifest;
 }
 
 // ── AST parse memo ───────────────────────────────────────────────────────
@@ -274,6 +248,30 @@ export function isTimberPluginApi(api: unknown): api is TimberPluginApi {
   );
 }
 
+/**
+ * The configured platform adapter. `adapter` is typed `unknown` on the user
+ * config so that `timber.config.ts` does not depend on the adapter types; the
+ * adapter factories are what produce values of this shape.
+ */
+export function contextAdapter(ctx: PluginContext): TimberPlatformAdapter | undefined {
+  return ctx.config.adapter as TimberPlatformAdapter | undefined;
+}
+
+/**
+ * The configuration an adapter is handed, derived once from the resolved
+ * context — by the post-build phase for `buildOutput` and by `timber preview`
+ * for `preview`.
+ */
+export function adapterConfig(ctx: PluginContext): TimberConfig {
+  return {
+    root: ctx.root,
+    // Normalized once here, not in each adapter: the platform files
+    // adapters write address deployed-URL space (TIM-1274).
+    base: normalizeBasePath(ctx.base),
+    clientJavascriptDisabled: ctx.clientJavascript.disabled,
+  };
+}
+
 /**
  * Resolve the app directory. Checks (in order):
  * 1. Explicit `configAppDir` from timber.config.ts
@@ -439,8 +437,9 @@ export function loadTimberConfigFile(root: string): TimberUserConfig | null {
 
 /**
  * Detect config keys set in both inline (vite.config.ts) and file (timber.config.ts)
- * and warn the user. The `output` key is excluded because it defaults to 'server'
- * in createPluginContext and would always appear as an inline key.
+ * and warn the user. Only keys the inline config actually sets count — the
+ * `output` default is applied after the merge (timber-root-sync), so it never
+ * appears here as an inline key.
  *
  * Returns the list of conflicting key names (for testing).
  */

package/src/plugins/build-manifest.ts

@@ -418,7 +418,7 @@ export function timberBuildManifest(ctx: PluginContext): Plugin {
 
       // RSC environment: walk the module graph to find which client
       // references each route file transitively imports. Store the
-      // mapping in ctx so the adapter-build post hook can cross-reference
+      // mapping in ctx so the post-build phase can cross-reference
       // with clientReferenceDeps to populate per-route modulepreloads.
       if (envName === 'rsc' && ctx.routeTree) {
         const clientRefIndex = buildClientRefIndex(bundle);
@@ -475,17 +475,10 @@ export function timberBuildManifest(ctx: PluginContext): Plugin {
 
         // When client JavaScript is disabled, strip JS chunks from the bundle
         // so Rollup never writes them to disk. CSS assets are preserved —
-        // they're still needed for server-rendered HTML.
-        //
-        // This is an optimization: adapter-build.ts still strips JS from the
-        // build manifest and RSC assets manifest as a defense-in-depth fallback.
+        // they're still needed for server-rendered HTML. The JS references
+        // in the manifest are stripped once, by the post-build phase, after
+        // it has merged in everything else (plugins/post-build.ts).
         if (ctx.clientJavascript.disabled) {
-          // Clear JS and modulepreload from the manifest (they'd be stripped
-          // by adapter-build.ts anyway, but doing it here avoids the round-trip).
-          ctx.buildManifest.js = {};
-          ctx.buildManifest.modulepreload = {};
-
-          // Remove JS chunks from the Rollup bundle — prevents disk writes.
           for (const [fileName, item] of Object.entries(bundle)) {
             if (item.type === 'chunk') {
               delete bundle[fileName];

package/src/plugins/build-report.ts

@@ -20,6 +20,7 @@ import type { Plugin, Logger } from 'vite';
 import type { PluginContext } from '../plugin-context.ts';
 import type { SegmentNode, RouteTree } from '../routing/types.ts';
 import type { CaptureSummary } from '../server/prebuilt-builder.ts';
+import type { PrebuiltCaptureResult } from './prebuilt-capture.ts';
 import type { PrebuiltManifest } from '../server/prebuilt/payload-source.ts';
 import { collectLeafRoutes } from '../routing/walkers.ts';
 import { formatSize } from '../utils/format.ts';
@@ -199,13 +200,10 @@ export interface PrebuiltReportData {
   skippedReasons: Array<{ componentId: string; route: string; message: string }>;
 }
 
-export function loadPrebuiltManifest(buildDir: string): PrebuiltManifest | null {
-  try {
-    const raw = readFileSync(join(buildDir, 'prebuilt', 'manifest.json'), 'utf-8');
-    return JSON.parse(raw) as PrebuiltManifest;
-  } catch {
-    return null;
-  }
+/** Read the manifest of the prebuilt artifact this build recorded, if any. */
+export function loadPrebuiltManifest(prebuiltDir: string | undefined): PrebuiltManifest | null {
+  if (!prebuiltDir) return null;
+  return JSON.parse(readFileSync(join(prebuiltDir, 'manifest.json'), 'utf-8')) as PrebuiltManifest;
 }
 
 export function buildPrebuiltReportData(
@@ -488,17 +486,79 @@ function suppressNonClientLogs(config: { command: string; logger: Logger }): voi
   };
 }
 
-export function timberBuildReport(ctx: PluginContext): Plugin {
+/**
+ * What the post-build phase asks of the build report (plugins/post-build.ts).
+ * Printed from there, once, after every environment is built and after the
+ * prebuilt capture pass — so nothing here depends on the order in which
+ * Vite closes each environment's bundle.
+ */
+export interface BuildReportStep {
+  print(prebuilt: PrebuiltCaptureResult | null): void;
+}
+
+export function timberBuildReport(ctx: PluginContext): Plugin & { api: BuildReportStep } {
   let logger: Logger | null = null;
   let chunkSizes: Map<string, ChunkSize> | null = null;
   let clientBundle: Record<string, OutputChunkLike> | null = null;
-  let reported = false;
-  let deferReport = false;
   const buildStart = performance.now();
 
+  function printRouteTable(): void {
+    if (!ctx.routeTree || !chunkSizes || !clientBundle || !logger) return;
+
+    const outputMode = ctx.config.output ?? 'server';
+    const clientJsDisabled = ctx.clientJavascript.disabled;
+    const { entries, sharedGzip } = clientJsDisabled
+      ? {
+          entries: collectRoutes(ctx.routeTree).map((info) => ({
+            path: info.path,
+            type: classifyRoute(info.segments, outputMode),
+            size: 0,
+            firstLoadSize: 0,
+          })),
+          sharedGzip: 0,
+        }
+      : buildEntries(ctx.routeTree, chunkSizes, clientBundle, outputMode, ctx.appDir, ctx.root);
+    const elapsed = ((performance.now() - buildStart) / 1000).toFixed(2);
+    const lines = buildRouteReport(entries, sharedGzip);
+
+    logger.info('');
+    for (const line of lines) logger.info(line);
+
+    const warnings = buildWarnings(entries, ctx.config.budget);
+    if (warnings.length > 0) {
+      logger.info('');
+      for (const w of warnings) logger.warn(w);
+    }
+
+    logger.info('');
+    logger.info(
+      `✓ built ${entries.length} routes for all three environments (rsc, ssr, client) in ${elapsed}s`
+    );
+    logger.info('');
+  }
+
+  function printPrebuiltReport(prebuilt: PrebuiltCaptureResult | null): void {
+    if (!logger || !prebuilt) return;
+    const manifest = loadPrebuiltManifest(prebuilt.artifact?.path);
+    const prebuiltData = buildPrebuiltReportData(manifest, prebuilt.summary);
+    if (!prebuiltData) return;
+
+    logger.info('');
+    for (const line of buildPrebuiltReport(prebuiltData)) logger.info(line);
+    logger.info('');
+  }
+
   return {
     name: 'timber-build-report',
 
+    api: {
+      print(prebuilt) {
+        if (ctx.dev) return;
+        printRouteTable();
+        printPrebuiltReport(prebuilt);
+      },
+    },
+
     config(_cfg, { command }) {
       if (command !== 'build') return;
       return {
@@ -520,66 +580,6 @@ export function timberBuildReport(ctx: PluginContext): Plugin {
 
       chunkSizes = collectChunkSizes(bundle as Record<string, OutputChunkLike>);
       clientBundle = { ...bundle } as Record<string, OutputChunkLike>;
-      deferReport = true; // skip client's closeBundle; emit after SSR's
-    },
-
-    closeBundle() {
-      if (ctx.dev || reported) return;
-
-      // The client build's closeBundle fires before SSR starts.
-      // Defer one cycle so the report appears after all builds complete.
-      if (deferReport) {
-        deferReport = false;
-        return;
-      }
-      if (!ctx.routeTree || !chunkSizes || !clientBundle || !logger) return;
-
-      reported = true;
-      const outputMode = ctx.config.output ?? 'server';
-      const clientJsDisabled = ctx.clientJavascript.disabled;
-      const { entries, sharedGzip } = clientJsDisabled
-        ? {
-            entries: collectRoutes(ctx.routeTree).map((info) => ({
-              path: info.path,
-              type: classifyRoute(info.segments, outputMode),
-              size: 0,
-              firstLoadSize: 0,
-            })),
-            sharedGzip: 0,
-          }
-        : buildEntries(ctx.routeTree, chunkSizes, clientBundle, outputMode, ctx.appDir, ctx.root);
-      const elapsed = ((performance.now() - buildStart) / 1000).toFixed(2);
-      const lines = buildRouteReport(entries, sharedGzip);
-
-      logger.info('');
-      for (const line of lines) logger.info(line);
-
-      const warnings = buildWarnings(entries, ctx.config.budget);
-      if (warnings.length > 0) {
-        logger.info('');
-        for (const w of warnings) logger.warn(w);
-      }
-
-      logger.info('');
-      logger.info(
-        `✓ built ${entries.length} routes for all three environments (rsc, ssr, client) in ${elapsed}s`
-      );
-      logger.info('');
-    },
-
-    buildApp: {
-      order: 'post' as const,
-      async handler() {
-        if (ctx.dev || !logger) return;
-        const manifest = loadPrebuiltManifest(ctx.buildDir);
-        const prebuiltData = buildPrebuiltReportData(manifest, ctx.captureSummary);
-        if (!prebuiltData) return;
-
-        logger.info('');
-        const prebuiltLines = buildPrebuiltReport(prebuiltData);
-        for (const line of prebuiltLines) logger.info(line);
-        logger.info('');
-      },
     },
   };
 }

package/src/plugins/dev-server.ts

@@ -22,12 +22,15 @@ import type { PluginContext } from '../plugin-context.ts';
 import {
   sendErrorToOverlay,
   classifyErrorPhase,
-  fixErrorStacktrace,
   parseFirstAppFrame,
   type ErrorPhase,
 } from '../dev-tools/overlay.ts';
 import { generateDevErrorPage } from '../dev-tools/error-page.ts';
-import { extractHmrOptions, type DevErrorHmrOptions } from '../dev-tools/dev-page-shell.ts';
+import {
+  extractHmrOptions,
+  type DevErrorHmrOptions,
+  type DevHooks,
+} from '../dev-tools/dev-page-shell.ts';
 import { addVirtualModuleContext } from '../config-validation.ts';
 import { registerDevDiscovery } from './dev-discovery.ts';
 import {
@@ -36,7 +39,6 @@ import {
   type GraphUpdateChannel,
 } from './graph-endpoint.ts';
 import { compressResponse } from '../server/compress.ts';
-import { isSsrStreamError } from '../server/primitives.ts';
 import { isMetadataRouteServePath } from '../server/metadata-routes.ts';
 import { canonicalize } from '../server/canonicalize.ts';
 import { matchUrlParts } from '../server/tree-match.ts';
@@ -317,37 +319,18 @@ function createTimberMiddleware(server: ViteDevServer, ctx: PluginContext) {
       const rscModule = await rscEnv.runner.import(RSC_ENTRY_ID);
       handler = rscModule.default as (req: Request) => Promise<Response>;
 
-      // Wire pipeline errors into the browser error overlay.
-      // Set devPipelineErrorHandler directly on the pipeline config —
-      // no module-level singleton.
-      const config = rscModule.pipelineConfig as
-        | {
-            devPipelineErrorHandler?: (error: Error, phase: string) => void;
-            devHmrOptions?: DevErrorHmrOptions;
-          }
-        | undefined;
-      if (config) {
-        config.devPipelineErrorHandler = (error) => {
+      // Wire pipeline errors into the browser error overlay, and plumb the
+      // resolved HMR options into the RSC environment. The RSC entry can't
+      // read the Vite server config (separate module graph), but its dev 404
+      // page and fallback error page need the HMR endpoint (including Vite
+      // 8's required WS token) for auto-reload (TIM-1067).
+      const setDevHooks = rscModule.setDevHooks as ((hooks: DevHooks) => void) | undefined;
+      setDevHooks?.({
+        onPipelineError: (error) => {
           sendErrorToOverlay(server, error, classifyErrorPhase(error, projectRoot), projectRoot);
-        };
-        // Plumb the resolved HMR options into the RSC environment. The RSC
-        // entry can't read the Vite server config (separate module graph),
-        // but its dev 404 page and fallback error page need the HMR endpoint
-        // (including Vite 8's required WS token) for auto-reload (TIM-1067).
-        config.devHmrOptions = hmrOptions;
-      }
-
-      // Wire source-map handler so error pages show original positions.
-      // fixErrorStacktrace rewrites the error's stack trace in-place using
-      // the Vite dev server's module graph. See TIM-811.
-      const setSourceMap = rscModule.setDevSourceMapHandler as
-        | ((fn: (error: Error) => void) => void)
-        | undefined;
-      if (typeof setSourceMap === 'function') {
-        setSourceMap((error: Error) => {
-          fixErrorStacktrace(server, error);
-        });
-      }
+        },
+        hmrOptions,
+      });
     } catch (error) {
       // Module transform error — syntax error, missing import, etc.
       // Vite may already show its own overlay for these, but we still
@@ -404,18 +387,15 @@ function createTimberMiddleware(server: ViteDevServer, ctx: PluginContext) {
       // srvx skips its own writeHead since headers are already sent.
       await sendNodeResponse(res, finalResponse);
     } catch (error) {
-      // Pipeline error — classify the phase, send to overlay, respond 500.
-      // The dev server remains running for recovery on file fix + HMR.
+      // An error the pipeline did not turn into a response, or one sending
+      // the response threw — classify the phase, send to overlay, respond
+      // 500. The pipeline answers render errors itself (an SsrStreamError
+      // never gets here), so this sees the error as thrown. The dev server
+      // remains running for recovery on file fix + HMR.
       if (error instanceof Error) {
-        // Unwrap SsrStreamError to show the real cause in the error overlay.
-        // SsrStreamError wraps the original RSC render error with a generic
-        // message; the developer needs to see the actual error (e.g.,
-        // "useSegmentParams is not a function"), not the wrapper.
-        const displayError =
-          isSsrStreamError(error) && error.cause instanceof Error ? error.cause : error;
-        const phase = classifyErrorPhase(displayError, projectRoot);
-        sendErrorToOverlay(server, displayError, phase, projectRoot);
-        respond500(res, displayError, phase, projectRoot, hmrOptions);
+        const phase = classifyErrorPhase(error, projectRoot);
+        sendErrorToOverlay(server, error, phase, projectRoot);
+        respond500(res, error, phase, projectRoot, hmrOptions);
       } else {
         process.stderr.write(`\x1b[31m[timber] Dev server error:\x1b[0m ${String(error)}\n`);
         respond500(res, error, 'render', projectRoot, hmrOptions);

package/src/plugins/entries.ts

@@ -16,6 +16,7 @@ import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { existsSync } from 'node:fs';
 import type { PluginContext } from '../plugin-context.ts';
+import { resolveRenderTimeoutMs } from '../server/render-timeout.ts';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -146,7 +147,7 @@ function generateConfigModule(ctx: PluginContext): string {
     topLoader: ctx.config.topLoader,
     debug: ctx.config.debug ?? false,
     serverTiming: ctx.config.serverTiming,
-    renderTimeoutMs: ctx.config.renderTimeoutMs ?? 30_000,
+    renderTimeoutMs: resolveRenderTimeoutMs(ctx.config.renderTimeoutMs),
     // Auto-generated sitemap config — opt-in via timber.config.ts.
     // See design/16-metadata.md §"Auto-generated Sitemap"
     sitemap: ctx.config.sitemap,

package/src/plugins/fonts.ts

@@ -21,12 +21,13 @@
 import { parseAst } from 'vite';
 import type { Plugin, ResolvedConfig, ViteDevServer } from 'vite';
 import type { PluginContext } from '../plugin-context.ts';
+import type { BuildManifest } from '../server/build-manifest.ts';
 import {
   downloadAndCacheFonts,
   generateProductionFontFaces,
   resolveDevFontFaces,
 } from '../fonts/google.ts';
-import { fontUrlPrefix } from '../fonts/paths.ts';
+import { FONT_OUTPUT_DIR, fontUrlPrefix } from '../fonts/paths.ts';
 import { FontPipeline } from '../fonts/pipeline.ts';
 import { runFontsTransform } from '../fonts/transform.ts';
 import { installFontDevMiddleware } from '../fonts/dev-middleware.ts';
@@ -57,15 +58,38 @@ export {
   parseLocalFontImportName,
 } from '../fonts/transform.ts';
 
+/**
+ * What the post-build phase asks of the font plugin (plugins/post-build.ts).
+ * Called after every environment has been built, so the font entries are
+ * complete — no environment's `generateBundle` has to run after the build
+ * manifest exists.
+ */
+export interface FontsBuildStep {
+  /** Write this build's font entries into the build manifest. */
+  contributeManifest(manifest: BuildManifest): void;
+  /**
+   * Directories of the client bundle this build filled with content-hashed
+   * font binaries — `[FONT_OUTPUT_DIR]` when any were emitted, else none.
+   */
+  immutableDirs(): string[];
+}
+
 /**
  * Create the timber-fonts Vite plugin.
  */
-export function timberFonts(ctx: PluginContext): Plugin {
+export function timberFonts(ctx: PluginContext): Plugin & { api: FontsBuildStep } {
   const pipeline = new FontPipeline({ hashOnRegister: !ctx.dev });
+  /** Whether the client environment emitted a binary this build. */
+  let emittedToClient = false;
 
   return {
     name: 'timber-fonts',
 
+    api: {
+      contributeManifest: (manifest) => writeFontManifest(pipeline, manifest, ctx.base),
+      immutableDirs: () => (emittedToClient ? [FONT_OUTPUT_DIR] : []),
+    },
+
     /**
      * Push Vite's resolved `base` into the pipeline so every font URL it
      * emits (@font-face src, manifest hrefs, dev middleware matching)
@@ -289,20 +313,24 @@ export function timberFonts(ctx: PluginContext): Plugin {
     },
 
     /**
-     * Emit font binaries and build-manifest entries.
+     * Emit font binaries.
      *
      * All font binaries (Google and local) use content-hashed filenames
      * for immutable caching. Font CSS is handled by Vite's CSS pipeline
-     * via virtual modules — we only emit binaries here.
+     * via virtual modules — we only emit binaries here. Manifest entries are
+     * written by the post-build phase through `api.contributeManifest`.
      */
     generateBundle() {
+      let emitted = 0;
       emitFontAssets(
         pipeline,
-        (asset) => this.emitFile(asset),
+        (asset) => {
+          emitted++;
+          return this.emitFile(asset);
+        },
         (msg) => this.warn(msg)
       );
-      if (!ctx.buildManifest) return;
-      writeFontManifest(pipeline, ctx.buildManifest, ctx.base);
+      if (this.environment?.name === 'client') emittedToClient = emitted > 0;
     },
   };
 }