@timber-js/app 0.2.0-alpha.2 → 0.2.0-alpha.21

package/src/client/segment-merger.ts

@@ -186,10 +186,7 @@ function walkChildren(children: ReactNode, out: CachedSegmentEntry[]): void {
  * Cache all segment subtrees from a fully-rendered RSC element tree.
  * Call this after every full RSC payload render (navigate, refresh, hydration).
  */
-export function cacheSegmentElements(
-  element: unknown,
-  cache: SegmentElementCache
-): void {
+export function cacheSegmentElements(element: unknown, cache: SegmentElementCache): void {
   const segments = extractSegments(element);
   for (const entry of segments) {
     cache.set(entry.segmentPath, entry);
@@ -208,10 +205,7 @@ export function cacheSegmentElements(
  */
 type TreePath = Array<{ element: ReactElement; childIndex: number }>;
 
-function findSegmentProviderPath(
-  node: ReactElement,
-  targetPath?: string
-): TreePath | null {
+function findSegmentProviderPath(node: ReactElement, targetPath?: string): TreePath | null {
   const children = (node.props as { children?: ReactNode }).children;
   if (children == null) return null;
 

package/src/client/stale-reload.ts

@@ -29,7 +29,7 @@ const RELOAD_FLAG_KEY = '__timber_stale_reload';
 export function isStaleClientReference(error: unknown): boolean {
   if (!(error instanceof Error)) return false;
   const msg = error.message;
-  return msg.includes('Could not find the module');
+  return msg.includes('Could not find the module') || msg.includes('client reference not found');
 }
 
 /**
@@ -48,8 +48,8 @@ export function triggerStaleReload(): boolean {
     if (sessionStorage.getItem(RELOAD_FLAG_KEY)) {
       console.warn(
         '[timber] Stale client reference detected again after reload. ' +
-        'Not reloading to prevent infinite loop. ' +
-        'This may indicate a deployment issue — try a hard refresh.'
+          'Not reloading to prevent infinite loop. ' +
+          'This may indicate a deployment issue — try a hard refresh.'
       );
       return false;
     }
@@ -59,7 +59,7 @@ export function triggerStaleReload(): boolean {
 
     console.warn(
       '[timber] Stale client reference detected — the server has been ' +
-      'redeployed with new bundles. Reloading to pick up the new version.'
+        'redeployed with new bundles. Reloading to pick up the new version.'
     );
 
     window.location.reload();
@@ -67,9 +67,7 @@ export function triggerStaleReload(): boolean {
   } catch {
     // sessionStorage may be unavailable (private browsing, storage full, etc.)
     // Fall back to reloading without loop protection
-    console.warn(
-      '[timber] Stale client reference detected. Reloading page.'
-    );
+    console.warn('[timber] Stale client reference detected. Reloading page.');
     window.location.reload();
     return true;
   }

package/src/client/top-loader.tsx

@@ -60,6 +60,7 @@ const DEFAULT_Z_INDEX = 1600;
 // Unique keyframes name to avoid collisions with user styles.
 const CRAWL_KEYFRAMES = '__timber_top_loader_crawl';
 const APPEAR_KEYFRAMES = '__timber_top_loader_appear';
+const FINISH_KEYFRAMES = '__timber_top_loader_finish';
 
 // Track whether the @keyframes rules have been injected into the document.
 let keyframesInjected = false;
@@ -83,6 +84,11 @@ function ensureKeyframes(): void {
   from { opacity: 0; }
   to { opacity: 1; }
 }
+@keyframes ${FINISH_KEYFRAMES} {
+  0% { width: 90%; opacity: 1; }
+  50% { width: 100%; opacity: 1; }
+  100% { width: 100%; opacity: 0; }
+}
 `;
   document.head.appendChild(style);
   keyframesInjected = true;
@@ -161,14 +167,13 @@ export function TopLoader({ config }: { config?: TopLoaderConfig }): React.React
           ].join(', '),
         }
       : {
-          // Finishing: snap to 100% width (200ms), THEN fade out (200ms).
-          // The opacity transition is delayed so the user sees the bar
-          // reach 100% before it disappears. Without the delay, both
-          // transitions run simultaneously and the bar fades before the
-          // fill animation is visible.
-          width: '100%',
-          opacity: 0,
-          transition: 'width 200ms ease, opacity 200ms ease 200ms',
+          // Finishing: fill to 100% then fade out via a keyframe animation.
+          // We use a keyframe instead of a CSS transition because the
+          // animation-to-transition handoff is unreliable — the browser
+          // may not capture the animated width as the transition's "from"
+          // value when both the animation removal and transition are
+          // applied in the same render frame.
+          animation: `${FINISH_KEYFRAMES} 400ms ease forwards`,
         }),
     ...(shadow
       ? {
@@ -177,24 +182,23 @@ export function TopLoader({ config }: { config?: TopLoaderConfig }): React.React
       : {}),
   };
 
-  // Clean up the finishing phase when the CSS transition completes.
-  // onTransitionEnd fires once per transitioned property — we act on
-  // the first one (opacity) and ignore subsequent (width).
-  const handleTransitionEnd = phase === 'finishing'
-    ? (e: React.TransitionEvent) => {
-        if (e.propertyName === 'opacity') {
-          setPhase('hidden');
+  // Clean up the finishing phase when the finish animation completes.
+  const handleAnimationEnd =
+    phase === 'finishing'
+      ? (e: React.AnimationEvent) => {
+          if (e.animationName === FINISH_KEYFRAMES) {
+            setPhase('hidden');
+          }
         }
-      }
-    : undefined;
+      : undefined;
 
   return createElement(
     'div',
     {
-      style: containerStyle,
+      'style': containerStyle,
       'aria-hidden': 'true',
       'data-timber-top-loader': '',
     },
-    createElement('div', { style: barStyle, onTransitionEnd: handleTransitionEnd })
+    createElement('div', { style: barStyle, onAnimationEnd: handleAnimationEnd })
   );
 }

package/src/client/transition-root.tsx

@@ -62,7 +62,13 @@ let _navigateTransition:
  * Non-navigation renders:
  *   transitionRender(newWrappedElement);
  */
-export function TransitionRoot({ initial, topLoaderConfig }: { initial: ReactNode; topLoaderConfig?: TopLoaderConfig }): ReactNode {
+export function TransitionRoot({
+  initial,
+  topLoaderConfig,
+}: {
+  initial: ReactNode;
+  topLoaderConfig?: TopLoaderConfig;
+}): ReactNode {
   const [element, setElement] = useState<ReactNode>(initial);
   const [pendingUrl, setPendingUrl] = useState<string | null>(null);
   const [, startTransition] = useTransition();

package/src/fonts/css.ts

@@ -39,6 +39,7 @@ export function generateFontFaces(descriptors: FontFaceDescriptor[]): string {
  * ```css
  * .timber-font-inter {
  *   --font-sans: 'Inter', 'Inter Fallback', system-ui, sans-serif;
+ *   font-family: 'Inter', 'Inter Fallback', system-ui, sans-serif;
  * }
  * ```
  */
@@ -47,7 +48,7 @@ export function generateVariableClass(
   variable: string,
   fontFamily: string
 ): string {
-  return `.${className} {\n  ${variable}: ${fontFamily};\n}`;
+  return `.${className} {\n  ${variable}: ${fontFamily};\n  font-family: ${fontFamily};\n}`;
 }
 
 /**

package/src/fonts/local.ts

@@ -100,18 +100,22 @@ export function generateFamilyName(sources: LocalFontSrc[]): string {
  * Generate @font-face descriptors for local font sources.
  *
  * Each source entry produces one @font-face rule. The `src` descriptor
- * uses a `url()` pointing to the resolved file path with the inferred format.
+ * uses a `url()` pointing to the served path under `/_timber/fonts/`.
+ * The `urlPrefix` defaults to `/_timber/fonts` — the path used by both
+ * the dev server middleware and the production build output.
  */
 export function generateLocalFontFaces(
   family: string,
   sources: LocalFontSrc[],
-  display: string
+  display: string,
+  urlPrefix = '/_timber/fonts'
 ): FontFaceDescriptor[] {
   return sources.map((entry) => {
     const format = inferFontFormat(entry.path);
+    const basename = entry.path.split('/').pop() ?? entry.path;
     return {
       family,
-      src: `url('${entry.path}') format('${format}')`,
+      src: `url('${urlPrefix}/${basename}') format('${format}')`,
       weight: entry.weight,
       style: entry.style,
       display,

package/src/index.ts

@@ -46,6 +46,18 @@ export interface ResolvedClientJavascript {
 
 export interface TimberUserConfig {
   output?: 'server' | 'static';
+  /**
+   * Enable timber debug logging in production builds.
+   *
+   * When `true`, timber's own diagnostics (dev warnings, verbose logging)
+   * are active even in production mode. React stays in production mode —
+   * only timber's logs are affected.
+   *
+   * Can also be enabled at runtime via the `TIMBER_DEBUG` environment variable.
+   *
+   * Default: `false`.
+   */
+  debug?: boolean;
   /**
    * Control client-side JavaScript output.
    *
@@ -95,6 +107,22 @@ export interface TimberUserConfig {
     /** Array of signing secrets for key rotation. Index 0 signs; all verify. */
     secrets?: string[];
   };
+  /**
+   * Control Server-Timing header output.
+   *
+   * - `'detailed'` — per-phase breakdown (proxy, middleware, render). Useful
+   *   for APM / network monitoring. Exposes phase names to clients.
+   * - `'total'` — single `total;dur=N` entry. Safe to expose, gives
+   *   browser DevTools useful timing without internal details.
+   * - `false` — no Server-Timing header at all.
+   *
+   * Default: `'detailed'` in dev, `'total'` in production.
+   *
+   * This is separate from `debug` / `TIMBER_DEBUG` — it's an intentional
+   * decision to expose timing data to clients, not a side effect of debug
+   * logging.
+   */
+  serverTiming?: 'detailed' | 'total' | false;
   /**
    * Override the app directory location. By default, timber auto-detects
    * `app/` at the project root, falling back to `src/app/`.
@@ -400,8 +428,13 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
           ssr: 'virtual:timber-ssr-entry',
           client: 'virtual:timber-browser-entry',
         },
-        // No custom clientChunks — Rolldown handles natural code splitting.
-        // See design/27-chunking-strategy.md and LOCAL-337.
+        // Group all client reference wrappers into a single chunk instead of
+        // creating one tiny file per "use client" module. Without this, each
+        // server chunk's client references become a separate entry point,
+        // producing many sub-500B wrapper files (e.g., 30-byte re-exports).
+        // A single group eliminates 10+ unnecessary HTTP requests.
+        // See design/27-chunking-strategy.md and TIM-440.
+        clientChunks: () => 'client-refs',
       });
     }
   );

package/src/plugins/build-report.ts

@@ -80,7 +80,17 @@ interface RouteInfo {
   entryFilePath: string | null;
 }
 
-/** Walk the route tree and collect all leaf routes (pages + API endpoints). */
+/**
+ * Walk the route tree and collect all leaf routes (pages + API endpoints).
+ *
+ * Parallel slots (`@artists`, `@shows`, etc.) are intentionally skipped —
+ * they render alongside the parent page at the same URL and are not
+ * separately URL-addressable. Their JS is captured in shared/layout chunks.
+ *
+ * After collection, entries are deduplicated by URL path so that overlapping
+ * route groups (e.g. `(browse)` and `(marketing)` both producing `/`) only
+ * appear once. The entry with the largest route-specific size wins.
+ */
 export function collectRoutes(tree: RouteTree): RouteInfo[] {
   const routes: RouteInfo[] = [];
 
@@ -95,12 +105,22 @@ export function collectRoutes(tree: RouteTree): RouteInfo[] {
       routes.push({ path, segments: currentChain, entryFilePath: node.route.filePath });
     }
 
+    // Recurse into child segments only — skip parallel slots (node.slots)
     for (const child of node.children) walk(child, currentChain);
-    for (const slot of node.slots.values()) walk(slot, currentChain);
   }
 
   walk(tree.root, []);
-  return routes;
+
+  // Deduplicate entries with the same URL path (e.g. from overlapping route groups).
+  // Keep the entry with the longest segment chain (most specific match).
+  const seen = new Map<string, RouteInfo>();
+  for (const route of routes) {
+    const existing = seen.get(route.path);
+    if (!existing || route.segments.length > existing.segments.length) {
+      seen.set(route.path, route);
+    }
+  }
+  return Array.from(seen.values());
 }
 
 // ─── Report formatting ────────────────────────────────────────────────────

package/src/plugins/entries.ts

@@ -110,6 +110,8 @@ function generateConfigModule(ctx: PluginContext): string {
     slowRequestMs: ctx.config.slowRequestMs ?? 3000,
     cookieSecrets,
     topLoader: ctx.config.topLoader,
+    debug: ctx.config.debug ?? false,
+    serverTiming: ctx.config.serverTiming,
   };
 
   return [
@@ -128,11 +130,14 @@ function generateConfigModule(ctx: PluginContext): string {
  * Checks for instrumentation.ts, .js, and .mjs — matching the same
  * extensions as timber.config.ts detection.
  */
-function detectInstrumentationFile(root: string): string | null {
+export function detectInstrumentationFile(root: string): string | null {
   const extensions = ['.ts', '.js', '.mjs'];
-  for (const ext of extensions) {
-    const candidate = resolve(root, `instrumentation${ext}`);
-    if (existsSync(candidate)) return candidate;
+  const dirs = [root, resolve(root, 'src')];
+  for (const dir of dirs) {
+    for (const ext of extensions) {
+      const candidate = resolve(dir, `instrumentation${ext}`);
+      if (existsSync(candidate)) return candidate;
+    }
   }
   return null;
 }

package/src/plugins/fonts.ts

@@ -14,13 +14,15 @@
  * Design doc: 24-fonts.md
  */
 
-import type { Plugin } from 'vite';
+import type { Plugin, ViteDevServer } from 'vite';
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, normalize } from 'node:path';
 import type { PluginContext } from '#/index.js';
 import type { ExtractedFont, GoogleFontConfig } from '#/fonts/types.js';
 import type { ManifestFontEntry } from '#/server/build-manifest.js';
-import { generateVariableClass, generateFontFamilyClass } from '#/fonts/css.js';
+import { generateVariableClass, generateFontFamilyClass, generateFontFaces } from '#/fonts/css.js';
 import { generateFallbackCss, buildFontStack } from '#/fonts/fallbacks.js';
-import { processLocalFont } from '#/fonts/local.js';
+import { processLocalFont, generateLocalFontFaces } from '#/fonts/local.js';
 import { inferFontFormat } from '#/fonts/local.js';
 import { downloadAndCacheFonts, type CachedFont } from '#/fonts/google.js';
 import {
@@ -34,6 +36,23 @@ const VIRTUAL_LOCAL = '@timber/fonts/local';
 const RESOLVED_GOOGLE = '\0@timber/fonts/google';
 const RESOLVED_LOCAL = '\0@timber/fonts/local';
 
+/**
+ * Virtual side-effect module that registers font CSS on globalThis.
+ *
+ * When a file calls localFont() or a Google font function, the transform
+ * hook injects `import 'virtual:timber-font-css-register'` into that file.
+ * This virtual module sets `globalThis.__timber_font_css` with the combined
+ * @font-face CSS. The RSC entry reads it at render time to inline a <style> tag.
+ *
+ * This approach avoids timing issues because:
+ * 1. The font file is in the RSC module graph (imported by layout.tsx)
+ * 2. The side-effect import is added to the font file during transform
+ * 3. When layout.tsx is loaded, fonts.ts runs → side-effect module runs → globalThis is set
+ * 4. RSC entry renders → reads globalThis → inlines <style>
+ */
+const VIRTUAL_FONT_CSS_REGISTER = 'virtual:timber-font-css-register';
+const RESOLVED_FONT_CSS_REGISTER = '\0virtual:timber-font-css-register';
+
 /**
  * Registry of fonts extracted during transform.
  * Keyed by a unique font ID derived from family + config.
@@ -242,27 +261,44 @@ function generateLocalVirtualModule(): string {
   ].join('\n');
 }
 
+/**
+ * Generate CSS for a single extracted font.
+ *
+ * Includes @font-face rules (for local fonts), fallback @font-face,
+ * and the scoped class rule.
+ */
+export function generateFontCss(font: ExtractedFont): string {
+  const cssParts: string[] = [];
+
+  if (font.provider === 'local' && font.localSources) {
+    const faces = generateLocalFontFaces(font.family, font.localSources, font.display);
+    const faceCss = generateFontFaces(faces);
+    if (faceCss) cssParts.push(faceCss);
+  }
+
+  const fallbackCss = generateFallbackCss(font.family);
+  if (fallbackCss) cssParts.push(fallbackCss);
+
+  if (font.variable) {
+    cssParts.push(generateVariableClass(font.className, font.variable, font.fontFamily));
+  } else {
+    cssParts.push(generateFontFamilyClass(font.className, font.fontFamily));
+  }
+
+  return cssParts.join('\n\n');
+}
+
 /**
  * Generate the CSS output for all extracted fonts.
  *
- * Includes @font-face rules, fallback @font-face rules, and scoped classes.
+ * Includes @font-face rules for local fonts, fallback @font-face rules,
+ * and scoped classes.
  */
 export function generateAllFontCss(registry: FontRegistry): string {
   const cssParts: string[] = [];
-
   for (const font of registry.values()) {
-    // Generate fallback @font-face if metrics are available
-    const fallbackCss = generateFallbackCss(font.family);
-    if (fallbackCss) cssParts.push(fallbackCss);
-
-    // Generate scoped class
-    if (font.variable) {
-      cssParts.push(generateVariableClass(font.className, font.variable, font.fontFamily));
-    } else {
-      cssParts.push(generateFontFamilyClass(font.className, font.fontFamily));
-    }
+    cssParts.push(generateFontCss(font));
   }
-
   return cssParts.join('\n\n');
 }
 
@@ -359,23 +395,112 @@ export function timberFonts(ctx: PluginContext): Plugin {
     name: 'timber-fonts',
 
     /**
-     * Resolve `@timber/fonts/google` and `@timber/fonts/local` to virtual modules.
+     * Resolve `@timber/fonts/google`, `@timber/fonts/local`,
+     * and `virtual:timber-font-css` virtual modules.
+     *
+     * Handles \0 prefix and root prefix stripping for RSC/SSR
+     * environments where the RSC plugin re-imports virtual modules
+     * with additional prefixes.
      */
     resolveId(id: string) {
-      if (id === VIRTUAL_GOOGLE) return RESOLVED_GOOGLE;
-      if (id === VIRTUAL_LOCAL) return RESOLVED_LOCAL;
+      // Strip \0 prefix (RSC plugin re-imports)
+      let cleanId = id.startsWith('\0') ? id.slice(1) : id;
+      // Strip root prefix (SSR build entries)
+      if (cleanId.startsWith(ctx.root)) {
+        const stripped = cleanId.slice(ctx.root.length);
+        if (stripped.startsWith('/') || stripped.startsWith('\\')) {
+          cleanId = stripped.slice(1);
+        } else {
+          cleanId = stripped;
+        }
+      }
+
+      if (cleanId === VIRTUAL_GOOGLE) return RESOLVED_GOOGLE;
+      if (cleanId === VIRTUAL_LOCAL) return RESOLVED_LOCAL;
+      if (cleanId === VIRTUAL_FONT_CSS_REGISTER) return RESOLVED_FONT_CSS_REGISTER;
       return null;
     },
 
     /**
      * Return generated source for font virtual modules.
+     *
+     * `virtual:timber-font-css` exports the combined @font-face CSS
+     * as a string. The RSC entry imports it and inlines a <style> tag.
+     * Because this is loaded lazily (on first request), the font
+     * registry is always populated by the time it's needed.
      */
     load(id: string) {
       if (id === RESOLVED_GOOGLE) return generateGoogleVirtualModule(registry);
       if (id === RESOLVED_LOCAL) return generateLocalVirtualModule();
+
+      if (id === RESOLVED_FONT_CSS_REGISTER) {
+        const css = generateAllFontCss(registry);
+        // Side-effect module: sets font CSS on globalThis for the RSC entry to read.
+        return `globalThis.__timber_font_css = ${JSON.stringify(css)};`;
+      }
       return null;
     },
 
+    /**
+     * Serve local font files and font CSS in dev mode under `/_timber/fonts/`.
+     *
+     * Serves:
+     * - `/_timber/fonts/fonts.css` — combined @font-face + scoped class CSS
+     * - `/_timber/fonts/<filename>` — individual font files from the registry
+     *
+     * Only files registered in the font registry are served.
+     * Paths are validated to prevent directory traversal.
+     */
+    configureServer(server: ViteDevServer) {
+      server.middlewares.use((req, res, next) => {
+        const url = req.url;
+        if (!url || !url.startsWith('/_timber/fonts/')) return next();
+
+        const requestedFilename = url.slice('/_timber/fonts/'.length);
+        // Reject path traversal attempts
+        if (requestedFilename.includes('..') || requestedFilename.includes('/')) {
+          res.statusCode = 400;
+          res.end('Bad request');
+          return;
+        }
+
+        // Font CSS is now injected via Vite's CSS pipeline (virtual:timber-font-css modules).
+        // This middleware only serves font binary files (woff2, etc.).
+
+        // Find the matching font file in the registry
+        for (const font of registry.values()) {
+          if (font.provider !== 'local' || !font.localSources) continue;
+          for (const src of font.localSources) {
+            const basename = src.path.split('/').pop() ?? '';
+            if (basename === requestedFilename) {
+              const absolutePath = normalize(resolve(src.path));
+              if (!existsSync(absolutePath)) {
+                res.statusCode = 404;
+                res.end('Not found');
+                return;
+              }
+              const data = readFileSync(absolutePath);
+              const ext = absolutePath.split('.').pop()?.toLowerCase();
+              const mimeMap: Record<string, string> = {
+                woff2: 'font/woff2',
+                woff: 'font/woff',
+                ttf: 'font/ttf',
+                otf: 'font/otf',
+                eot: 'application/vnd.ms-fontopen',
+              };
+              res.setHeader('Content-Type', mimeMap[ext ?? ''] ?? 'application/octet-stream');
+              res.setHeader('Cache-Control', 'public, max-age=31536000, immutable');
+              res.setHeader('Access-Control-Allow-Origin', '*');
+              res.end(data);
+              return;
+            }
+          }
+        }
+
+        next();
+      });
+    },
+
     /**
      * Download and cache Google Fonts during production builds.
      *
@@ -499,6 +624,11 @@ export function timberFonts(ctx: PluginContext): Plugin {
       }
 
       if (transformedCode !== code) {
+        // Inject side-effect import that registers font CSS on globalThis.
+        // The RSC entry reads globalThis.__timber_font_css to inline a <style> tag.
+        if (registry.size > 0) {
+          transformedCode = `import '${VIRTUAL_FONT_CSS_REGISTER}';\n` + transformedCode;
+        }
         return { code: transformedCode, map: null };
       }
 
@@ -525,6 +655,28 @@ export function timberFonts(ctx: PluginContext): Plugin {
         });
       }
 
+      // Emit local font files as assets
+      for (const font of registry.values()) {
+        if (font.provider !== 'local' || !font.localSources) continue;
+        for (const src of font.localSources) {
+          const absolutePath = normalize(resolve(src.path));
+          if (!existsSync(absolutePath)) {
+            this.warn(`Local font file not found: ${absolutePath}`);
+            continue;
+          }
+          const basename = src.path.split('/').pop() ?? src.path;
+          const data = readFileSync(absolutePath);
+          this.emitFile({
+            type: 'asset',
+            fileName: `_timber/fonts/${basename}`,
+            source: data,
+          });
+        }
+      }
+
+      // Font CSS is emitted by Vite's CSS pipeline via virtual:timber-font-css modules.
+      // We only need to emit font binary files and update the build manifest here.
+
       if (!ctx.buildManifest) return;
 
       // Build a lookup from font family → cached files for manifest entries

package/src/plugins/mdx.ts

@@ -16,19 +16,23 @@ import type { PluginContext } from '#/index.js';
 const MDX_EXTENSIONS = ['mdx', 'md'];
 
 /**
- * Check if mdx-components.tsx (or .ts, .jsx, .js) exists at the project root.
+ * Check if mdx-components.tsx (or .ts, .jsx, .js) exists at the project root
+ * or in src/. Root takes precedence, matching Next.js behavior.
  * Returns the absolute path if found, otherwise undefined.
  */
-function findMdxComponents(root: string): string | undefined {
+export function findMdxComponents(root: string): string | undefined {
   const candidates = [
     'mdx-components.tsx',
     'mdx-components.ts',
     'mdx-components.jsx',
     'mdx-components.js',
   ];
-  for (const name of candidates) {
-    const p = join(root, name);
-    if (existsSync(p)) return p;
+  const dirs = [root, join(root, 'src')];
+  for (const dir of dirs) {
+    for (const name of candidates) {
+      const p = join(dir, name);
+      if (existsSync(p)) return p;
+    }
   }
   return undefined;
 }

package/src/plugins/server-bundle.ts

@@ -65,6 +65,10 @@ export function timberServerBundle(): Plugin[] {
       // eliminated by Rollup's tree-shaking. Without this, the runtime
       // check falls through on platforms where process.env is empty
       // (e.g. Cloudflare Workers), causing dev code to run in production.
+      // Define process.env.NODE_ENV so dev-only React code is tree-shaken.
+      // TIMBER_DEBUG is intentionally NOT defined here — it must remain a
+      // runtime check so `isDebug()` in server/debug.ts can read it at
+      // request time. See TIM-365.
       const serverDefine = {
         'process.env.NODE_ENV': JSON.stringify('production'),
       };

package/src/server/access-gate.tsx

@@ -16,6 +16,7 @@
 import { DenySignal, RedirectSignal } from './primitives.js';
 import type { AccessGateProps, SlotAccessGateProps, ReactElement } from './tree-builder.js';
 import { withSpan, setSpanAttribute } from './tracing.js';
+import { isDebug } from './debug.js';
 
 // ─── AccessGate ─────────────────────────────────────────────────────────────
 
@@ -114,7 +115,7 @@ export async function SlotAccessGate(props: SlotAccessGateProps): Promise<ReactE
     // slot would redirect the entire page, which breaks the contract that
     // slot failure is graceful degradation.
     if (error instanceof RedirectSignal) {
-      if (process.env.NODE_ENV !== 'production') {
+      if (isDebug()) {
         console.error(
           '[timber] redirect() is not allowed in slot access.ts. ' +
             'Slots use deny() for graceful degradation — denied.tsx → default.tsx → null. ' +
@@ -127,7 +128,7 @@ export async function SlotAccessGate(props: SlotAccessGateProps): Promise<ReactE
 
     // Unhandled error — re-throw so error boundaries can catch it.
     // Dev-mode warning: slot access should use deny(), not throw.
-    if (process.env.NODE_ENV !== 'production') {
+    if (isDebug()) {
       console.warn(
         '[timber] Unhandled error in slot access.ts. ' +
           'Use deny() for access control, not unhandled throws.',