@timber-js/app 0.2.0-alpha.1 → 0.2.0-alpha.11

package/src/client/link.tsx

@@ -4,8 +4,12 @@
 // See design/19-client-navigation.md § Progressive Enhancement
 //
 // Without JavaScript, <Link> renders as a plain <a> tag — standard browser
-// navigation. With JavaScript, the client runtime intercepts clicks on links
-// marked with data-timber-link, fetches RSC payloads, and reconciles the DOM.
+// navigation. With JavaScript, the Link component's onClick handler triggers
+// RSC-based client navigation via the router.
+//
+// Each Link owns its own click handler — no global event delegation.
+// This keeps navigation within React's component tree, ensuring pending
+// state (useLinkStatus) updates atomically with the navigation.
 //
 // Typed Link: design/09-typescript.md §"Typed Link"
 // - href validated against known routes (via codegen overloads, not runtime)
@@ -14,14 +18,19 @@
 // - params and fully-resolved string href are mutually exclusive
 // - searchParams and inline query string are mutually exclusive
 
-import type { AnchorHTMLAttributes, ReactNode } from 'react';
+import type { AnchorHTMLAttributes, ReactNode, MouseEvent as ReactMouseEvent } from 'react';
 import type { SearchParamsDefinition } from '#/search-params/create.js';
-import type { OnNavigateHandler } from './link-navigate-interceptor.js';
-import { LinkNavigateInterceptor } from './link-navigate-interceptor.js';
 import { LinkStatusProvider } from './link-status-provider.js';
+import { getRouterOrNull } from './router-ref.js';
 
 // ─── Types ───────────────────────────────────────────────────────
 
+export type OnNavigateEvent = {
+  preventDefault: () => void;
+};
+
+export type OnNavigateHandler = (e: OnNavigateEvent) => void;
+
 /**
  * Base props shared by all Link variants.
  */
@@ -108,7 +117,7 @@ export function validateLinkHref(href: string): void {
 // ─── Internal Link Detection ─────────────────────────────────────
 
 /** Returns true if the href is an internal path (not an external URL) */
-function isInternalHref(href: string): boolean {
+export function isInternalHref(href: string): boolean {
   // Relative paths, root-relative paths, and hash links are internal
   if (href.startsWith('/') || href.startsWith('#') || href.startsWith('?')) {
     return true;
@@ -232,10 +241,7 @@ export function resolveHref(
 // ─── Build Props ─────────────────────────────────────────────────
 
 interface LinkOutputProps {
-  'href': string;
-  'data-timber-link'?: boolean;
-  'data-timber-prefetch'?: boolean;
-  'data-timber-scroll'?: string;
+  href: string;
 }
 
 /**
@@ -243,7 +249,7 @@ interface LinkOutputProps {
  * for testability — the component just spreads these onto an <a>.
  */
 export function buildLinkProps(
-  props: Pick<LinkPropsWithHref, 'href' | 'prefetch' | 'scroll'> & {
+  props: Pick<LinkPropsWithHref, 'href'> & {
     params?: Record<string, string | number | string[]>;
     searchParams?: {
       definition: SearchParamsDefinition<Record<string, unknown>>;
@@ -252,25 +258,38 @@ export function buildLinkProps(
   }
 ): LinkOutputProps {
   const resolvedHref = resolveHref(props.href, props.params, props.searchParams);
-
   validateLinkHref(resolvedHref);
+  return { href: resolvedHref };
+}
 
-  const output: LinkOutputProps = { href: resolvedHref };
-  const internal = isInternalHref(resolvedHref);
+// ─── Click Handler ───────────────────────────────────────────────
 
-  if (internal) {
-    output['data-timber-link'] = true;
+/**
+ * Should this click be intercepted for SPA navigation?
+ *
+ * Returns false (pass through to browser) when:
+ * - Modified keys are held (Ctrl, Meta, Shift, Alt) — open in new tab
+ * - The click is not the primary button
+ * - The event was already prevented by a parent handler
+ * - The link has target="_blank" or similar
+ * - The link has a download attribute
+ * - The href is external
+ */
+function shouldInterceptClick(
+  event: ReactMouseEvent<HTMLAnchorElement>,
+  resolvedHref: string
+): boolean {
+  if (event.button !== 0) return false;
+  if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return false;
+  if (event.defaultPrevented) return false;
 
-    if (props.prefetch) {
-      output['data-timber-prefetch'] = true;
-    }
+  const anchor = event.currentTarget;
+  if (anchor.target && anchor.target !== '_self') return false;
+  if (anchor.hasAttribute('download')) return false;
 
-    if (props.scroll === false) {
-      output['data-timber-scroll'] = 'false';
-    }
-  }
+  if (!isInternalHref(resolvedHref)) return false;
 
-  return output;
+  return true;
 }
 
 // ─── Link Component ──────────────────────────────────────────────
@@ -279,8 +298,9 @@ export function buildLinkProps(
  * Navigation link with progressive enhancement.
  *
  * Renders as a plain `<a>` tag — works without JavaScript. When the client
- * runtime is active, it intercepts clicks on links marked with
- * `data-timber-link` to perform RSC-based client navigation.
+ * runtime is active, the Link's onClick handler triggers RSC-based client
+ * navigation via the router. No global event delegation — each Link owns
+ * its own click handling.
  *
  * Supports typed routes via codegen overloads. At runtime:
  * - `params` prop interpolates dynamic segments in the href pattern
@@ -293,20 +313,63 @@ export function Link({
   params,
   searchParams,
   onNavigate,
+  onClick: userOnClick,
+  onMouseEnter: userOnMouseEnter,
   children,
   ...rest
 }: LinkProps) {
-  const linkProps = buildLinkProps({ href, prefetch, scroll, params, searchParams });
+  const { href: resolvedHref } = buildLinkProps({ href, params, searchParams });
+  const internal = isInternalHref(resolvedHref);
 
-  const inner = <LinkStatusProvider href={linkProps.href}>{children}</LinkStatusProvider>;
+  // ─── Click handler ───────────────────────────────────────────
+  // Each Link component owns its click handling. The router is
+  // accessed via the singleton ref — during SSR, getRouterOrNull()
+  // returns null and onClick is a no-op (the <a> works as a plain link).
+  const handleClick = internal
+    ? (event: ReactMouseEvent<HTMLAnchorElement>) => {
+        // Call user's onClick first (e.g., analytics)
+        userOnClick?.(event);
+
+        if (!shouldInterceptClick(event, resolvedHref)) return;
+
+        // Call onNavigate if provided — allows caller to cancel
+        if (onNavigate) {
+          let prevented = false;
+          onNavigate({
+            preventDefault: () => {
+              prevented = true;
+            },
+          });
+          if (prevented) {
+            event.preventDefault();
+            return;
+          }
+        }
+
+        const router = getRouterOrNull();
+        if (!router) return; // SSR or pre-hydration — fall through to browser nav
+
+        event.preventDefault();
+        const shouldScroll = scroll !== false;
+        void router.navigate(resolvedHref, { scroll: shouldScroll });
+      }
+    : 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);
+          }
+        }
+      : userOnMouseEnter;
 
   return (
-    <a {...rest} {...linkProps}>
-      {onNavigate ? (
-        <LinkNavigateInterceptor onNavigate={onNavigate}>{inner}</LinkNavigateInterceptor>
-      ) : (
-        inner
-      )}
+    <a {...rest} href={resolvedHref} onClick={handleClick} onMouseEnter={handleMouseEnter}>
+      <LinkStatusProvider href={resolvedHref}>{children}</LinkStatusProvider>
     </a>
   );
 }

package/src/client/navigation-context.ts

@@ -25,9 +25,15 @@
  * that depend on these APIs are safe to call from any environment —
  * they return null or no-op when the APIs aren't available.
  *
- * Singleton guarantee: With the simplified chunking strategy (LOCAL-337),
- * this module lives in exactly one client chunk. The previous globalThis +
- * Symbol.for workaround for cross-chunk duplication is no longer needed.
+ * SINGLETON GUARANTEE: All shared mutable state uses globalThis via
+ * Symbol.for keys. The RSC client bundler can duplicate this module
+ * across chunks (browser-entry graph + client-reference graph). With
+ * ESM output, each chunk gets its own module scope — module-level
+ * variables would create separate singleton instances per chunk.
+ * globalThis guarantees a single instance regardless of duplication.
+ *
+ * This workaround will be removed when Rolldown ships `format: 'app'`
+ * (module registry format that deduplicates like webpack/Turbopack).
  * See design/27-chunking-strategy.md.
  *
  * See design/19-client-navigation.md §"NavigationContext"
@@ -52,17 +58,31 @@ export interface NavigationState {
  * The context is created lazily to avoid calling createContext at module
  * level. In the RSC environment, React.createContext doesn't exist —
  * calling it at import time would crash the server.
+ *
+ * Context instances are stored on globalThis (NOT in module-level
+ * variables) because the ESM bundler can duplicate this module across
+ * chunks. Module-level variables would create separate instances per
+ * chunk — the provider in TransitionRoot (index chunk) would use
+ * context A while the consumer in LinkStatusProvider (shared chunk)
+ * reads from context B. globalThis guarantees a single instance.
+ *
+ * See design/27-chunking-strategy.md §"Singleton Safety"
  */
 
-let _navCtx: React.Context<NavigationState | null> | undefined;
-let _pendingNavCtx: React.Context<string | null> | undefined;
+// Symbol keys for globalThis storage — prevents collisions with user code
+const NAV_CTX_KEY = Symbol.for('__timber_nav_ctx');
+const PENDING_CTX_KEY = Symbol.for('__timber_pending_nav_ctx');
 
 function getOrCreateContext(): React.Context<NavigationState | null> | undefined {
-  if (_navCtx !== undefined) return _navCtx;
+  const existing = (globalThis as Record<symbol, unknown>)[NAV_CTX_KEY] as
+    | React.Context<NavigationState | null>
+    | undefined;
+  if (existing !== undefined) return existing;
   // createContext may not exist in the RSC environment
   if (typeof React.createContext === 'function') {
-    _navCtx = React.createContext<NavigationState | null>(null);
-    return _navCtx;
+    const ctx = React.createContext<NavigationState | null>(null);
+    (globalThis as Record<symbol, unknown>)[NAV_CTX_KEY] = ctx;
+    return ctx;
   }
   return undefined;
 }
@@ -119,15 +139,27 @@ export function NavigationProvider({
  * NavigationProvider with the correct params/pathname.
  *
  * This is NOT used by hooks directly — hooks read from React context.
+ *
+ * Stored on globalThis (like the context instances above) because the
+ * router lives in one chunk while renderRoot lives in another. Module-
+ * level variables would be separate per chunk.
  */
-let _navState: NavigationState = { params: {}, pathname: '/' };
+const NAV_STATE_KEY = Symbol.for('__timber_nav_state');
+
+function _getNavStateStore(): { current: NavigationState } {
+  const g = globalThis as Record<symbol, unknown>;
+  if (!g[NAV_STATE_KEY]) {
+    g[NAV_STATE_KEY] = { current: { params: {}, pathname: '/' } };
+  }
+  return g[NAV_STATE_KEY] as { current: NavigationState };
+}
 
 export function setNavigationState(state: NavigationState): void {
-  _navState = state;
+  _getNavStateStore().current = state;
 }
 
 export function getNavigationState(): NavigationState {
-  return _navState;
+  return _getNavStateStore().current;
 }
 
 // ---------------------------------------------------------------------------
@@ -138,13 +170,21 @@ export function getNavigationState(): NavigationState {
  * Separate context for the in-flight navigation URL. Provided by
  * TransitionRoot (urgent useState), consumed by LinkStatusProvider
  * and useNavigationPending.
+ *
+ * Uses globalThis via Symbol.for for the same reason as NavigationContext
+ * above — the bundler may duplicate this module across chunks, and module-
+ * level variables would create separate context instances.
  */
 
 function getOrCreatePendingContext(): React.Context<string | null> | undefined {
-  if (_pendingNavCtx !== undefined) return _pendingNavCtx;
+  const existing = (globalThis as Record<symbol, unknown>)[PENDING_CTX_KEY] as
+    | React.Context<string | null>
+    | undefined;
+  if (existing !== undefined) return existing;
   if (typeof React.createContext === 'function') {
-    _pendingNavCtx = React.createContext<string | null>(null);
-    return _pendingNavCtx;
+    const ctx = React.createContext<string | null>(null);
+    (globalThis as Record<symbol, unknown>)[PENDING_CTX_KEY] = ctx;
+    return ctx;
   }
   return undefined;
 }

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

@@ -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/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.
    *
@@ -134,6 +146,34 @@ export interface TimberUserConfig {
     /** CSS z-index. Default: 1600. */
     zIndex?: number;
   };
+  /**
+   * Response-level caching and deduplication.
+   *
+   * When enabled, concurrent requests to the same URL share a single render
+   * (singleflight), and recently rendered responses are reused from a short-TTL
+   * LRU cache without re-executing the RSC-to-SSR pipeline.
+   *
+   * Set to `false` to disable entirely. Default: enabled with sensible defaults.
+   *
+   * See design/31-benchmarking.md for performance context.
+   */
+  responseCache?:
+    | false
+    | {
+        /** Maximum number of entries in the LRU cache. Default: 150. */
+        maxSize?: number;
+        /** TTL for cached entries in milliseconds. Default: 5000 (5s). */
+        ttlMs?: number;
+        /**
+         * When true (default), requests with Cookie or Authorization headers
+         * bypass the cache entirely. This prevents sharing user-specific
+         * responses across requests.
+         *
+         * Set to false to cache all responses regardless of auth state.
+         * Only do this if your pages are truly public and don't vary by user.
+         */
+        publicOnly?: boolean;
+      };
 }
 
 /**

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/chunks.ts

@@ -41,7 +41,15 @@ export function isTimberRuntime(id: string): boolean {
  *
  * Currently a no-op — Rolldown's default splitting produces the desired
  * output (one main bundle + per-route chunks). The plugin is retained as
- * a hook point for future chunking adjustments if needed.
+ * a hook point for future chunking adjustments.
+ *
+ * NOTE: Ideally we'd use Rolldown's `format: 'app'` (module registry format)
+ * which guarantees single-copy module semantics like webpack/Turbopack.
+ * However, `format: 'app'` is not yet implemented in Rolldown rc.10.
+ * Until it ships, singleton state in navigation-context.ts uses
+ * globalThis + Symbol.for as a cross-chunk safety net.
+ *
+ * Design docs: 27-chunking-strategy.md
  */
 export function timberChunks(): Plugin {
   return {