@timber-js/app 0.2.0-alpha.3 → 0.2.0-alpha.30

package/src/cache/timber-cache.ts

@@ -1,17 +1,23 @@
-import { createHash } from 'node:crypto';
 import type { CacheHandler, CacheOptions } from './index';
 import { stableStringify } from './stable-stringify';
 import { createSingleflight } from './singleflight';
-import { addSpanEvent } from '#/server/tracing.js';
+import { addSpanEventSync } from '#/server/tracing.js';
+import { fnv1aHash } from './fast-hash.js';
 
 const singleflight = createSingleflight();
 
 /**
- * Generate a SHA-256 cache key from function identity and serialized args.
+ * Generate a cache key from function identity and serialized args.
+ *
+ * Uses FNV-1a (fast non-crypto hash) instead of SHA-256. Cache keys don't
+ * need collision resistance — they need speed. The fnId prefix provides
+ * namespace isolation; the hash covers the args.
+ *
+ * See TIM-370 for perf motivation.
  */
 function defaultKeyGenerator(fnId: string, args: unknown[]): string {
   const raw = fnId + ':' + stableStringify(args);
-  return createHash('sha256').update(raw).digest('hex');
+  return fnId + ':' + fnv1aHash(raw);
 }
 
 /**
@@ -57,8 +63,9 @@ export function createCache<Fn extends (...args: any[]) => Promise<any>>(
     const cached = await handler.get(key);
 
     if (cached && !cached.stale) {
-      // Record as OTEL span event on enclosing span (not a child span)
-      await addSpanEvent('timber.cache.hit', {
+      // Record as OTEL span event on enclosing span (not a child span).
+      // Fire-and-forget — no microtask overhead on the cache hot path.
+      addSpanEventSync('timber.cache.hit', {
         key,
         duration_ms: Math.round(performance.now() - cacheStart),
       });
@@ -66,8 +73,8 @@ export function createCache<Fn extends (...args: any[]) => Promise<any>>(
     }
 
     if (cached && cached.stale && opts.staleWhileRevalidate) {
-      // Record stale cache hit as OTEL span event
-      await addSpanEvent('timber.cache.hit', {
+      // Record stale cache hit as OTEL span event (fire-and-forget).
+      addSpanEventSync('timber.cache.hit', {
         key,
         duration_ms: Math.round(performance.now() - cacheStart),
         stale: true,
@@ -95,8 +102,8 @@ export function createCache<Fn extends (...args: any[]) => Promise<any>>(
     const tags = resolveTags(opts, args);
     await handler.set(key, result, { ttl: opts.ttl, tags });
 
-    // Record cache miss as OTEL span event
-    await addSpanEvent('timber.cache.miss', {
+    // Record cache miss as OTEL span event (fire-and-forget).
+    addSpanEventSync('timber.cache.miss', {
       key,
       duration_ms: Math.round(performance.now() - cacheStart),
     });

package/src/client/browser-entry.ts

@@ -52,7 +52,11 @@ import { setupServerLogReplay, setupClientErrorForwarding } from './browser-dev.
 // browser-links.ts removed — Link components own their click/hover handlers directly.
 // See LOCAL-340.
 import { TransitionRoot, transitionRender, navigateTransition } from './transition-root.js';
-import { isStaleClientReference, triggerStaleReload, clearStaleReloadFlag } from './stale-reload.js';
+import {
+  isStaleClientReference,
+  triggerStaleReload,
+  clearStaleReloadFlag,
+} from './stale-reload.js';
 
 // ─── Server Action Dispatch ──────────────────────────────────────
 
@@ -213,10 +217,7 @@ function findOverflowContainer(): HTMLElement | null {
     if (!(el instanceof HTMLElement)) continue;
     const style = getComputedStyle(el);
     const overflowY = style.overflowY;
-    if (
-      (overflowY === 'auto' || overflowY === 'scroll') &&
-      el.scrollHeight > el.clientHeight
-    ) {
+    if ((overflowY === 'auto' || overflowY === 'scroll') && el.scrollHeight > el.clientHeight) {
       return el;
     }
   }
@@ -381,7 +382,10 @@ function bootstrap(runtimeConfig: typeof config): void {
       element as React.ReactNode
     );
     const wrapped = createElement(TimberNuqsAdapter, null, withNav);
-    const rootElement = createElement(TransitionRoot, { initial: wrapped, topLoaderConfig: _config.topLoader });
+    const rootElement = createElement(TransitionRoot, {
+      initial: wrapped,
+      topLoaderConfig: _config.topLoader,
+    });
     _reactRoot = hydrateRoot(document, rootElement, {
       // Suppress recoverable hydration errors from deny/error signals
       // inside Suspense boundaries. The server already handled these

package/src/client/link.tsx

@@ -335,7 +335,11 @@ export function Link({
         // Call onNavigate if provided — allows caller to cancel
         if (onNavigate) {
           let prevented = false;
-          onNavigate({ preventDefault: () => { prevented = true; } });
+          onNavigate({
+            preventDefault: () => {
+              prevented = true;
+            },
+          });
           if (prevented) {
             event.preventDefault();
             return;
@@ -352,15 +356,16 @@ export function Link({
     : userOnClick; // External links — just pass through user's onClick
 
   // ─── Hover prefetch ──────────────────────────────────────────
-  const handleMouseEnter = internal && prefetch
-    ? (event: ReactMouseEvent<HTMLAnchorElement>) => {
-        userOnMouseEnter?.(event);
-        const router = getRouterOrNull();
-        if (router) {
-          router.prefetch(resolvedHref);
+  const handleMouseEnter =
+    internal && prefetch
+      ? (event: ReactMouseEvent<HTMLAnchorElement>) => {
+          userOnMouseEnter?.(event);
+          const router = getRouterOrNull();
+          if (router) {
+            router.prefetch(resolvedHref);
+          }
         }
-      }
-    : userOnMouseEnter;
+      : userOnMouseEnter;
 
   return (
     <a {...rest} href={resolvedHref} onClick={handleClick} onMouseEnter={handleMouseEnter}>

package/src/client/router.ts

@@ -7,11 +7,7 @@ import { HistoryStack } from './history';
 import type { HeadElement } from './head';
 import { setCurrentParams } from './use-params.js';
 import { setNavigationState } from './navigation-context.js';
-import {
-  SegmentElementCache,
-  cacheSegmentElements,
-  mergeSegmentTree,
-} from './segment-merger.js';
+import { SegmentElementCache, cacheSegmentElements, mergeSegmentTree } from './segment-merger.js';
 import { fetchRscPayload, RedirectError } from './rsc-fetch.js';
 import type { FetchResult } from './rsc-fetch.js';
 
@@ -421,7 +417,9 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       setPending(true, url);
       try {
         const headElements = await renderViaTransition(url, async () => {
-          const stateTree = segmentCache.serializeStateTree(segmentElementCache.getMergeablePaths());
+          const stateTree = segmentCache.serializeStateTree(
+            segmentElementCache.getMergeablePaths()
+          );
           const result = await fetchRscPayload(url, deps, stateTree);
           updateSegmentCache(result.segmentInfo);
           updateNavigationState(result.params, url);

package/src/client/segment-context.ts

@@ -52,7 +52,12 @@ interface SegmentProviderProps {
  * Wraps each layout to provide segment position context.
  * Injected by rsc-entry.ts during element tree construction.
  */
-export function SegmentProvider({ segments, segmentId: _segmentId, parallelRouteKeys, children }: SegmentProviderProps) {
+export function SegmentProvider({
+  segments,
+  segmentId: _segmentId,
+  parallelRouteKeys,
+  children,
+}: SegmentProviderProps) {
   const value = useMemo(
     () => ({ segments, parallelRouteKeys }),
     // segments and parallelRouteKeys are static per layout — they don't change

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

@@ -183,18 +183,19 @@ export function TopLoader({ config }: { config?: TopLoaderConfig }): React.React
   };
 
   // Clean up the finishing phase when the finish animation completes.
-  const handleAnimationEnd = phase === 'finishing'
-    ? (e: React.AnimationEvent) => {
-        if (e.animationName === FINISH_KEYFRAMES) {
-          setPhase('hidden');
+  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': '',
     },

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;
 }