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

package/dist/plugins/chunks.d.ts

@@ -31,7 +31,15 @@ export declare 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 declare function timberChunks(): Plugin;
 //# sourceMappingURL=chunks.d.ts.map

package/dist/plugins/chunks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunks.d.ts","sourceRoot":"","sources":["../../src/plugins/chunks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAEnC;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAOnD;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAIrC"}
+{"version":3,"file":"chunks.d.ts","sourceRoot":"","sources":["../../src/plugins/chunks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAEnC;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAOnD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAIrC"}

package/dist/shims/image.d.ts

@@ -51,17 +51,17 @@ export declare function Image({ priority: _priority, quality: _quality, fill: _f
     autoCapitalize?: "off" | "none" | "on" | "sentences" | "words" | "characters" | undefined | (string & {});
     autoFocus?: boolean | undefined;
     className?: string | undefined;
-    contentEditable?: (boolean | "false" | "true") | "inherit" | "plaintext-only" | undefined;
+    contentEditable?: (boolean | "true" | "false") | "inherit" | "plaintext-only" | undefined;
     contextMenu?: string | undefined;
     dir?: string | undefined;
-    draggable?: (boolean | "false" | "true") | undefined;
+    draggable?: (boolean | "true" | "false") | undefined;
     enterKeyHint?: "enter" | "done" | "go" | "next" | "previous" | "search" | "send" | undefined;
     hidden?: boolean | undefined;
     id?: string | undefined;
     lang?: string | undefined;
     nonce?: string | undefined;
     slot?: string | undefined;
-    spellCheck?: (boolean | "false" | "true") | undefined;
+    spellCheck?: (boolean | "true" | "false") | undefined;
     style?: import("react").CSSProperties | undefined;
     tabIndex?: number | undefined;
     title?: string | undefined;
@@ -99,11 +99,11 @@ export declare function Image({ priority: _priority, quality: _quality, fill: _f
     exportparts?: string | undefined;
     part?: string | undefined;
     "aria-activedescendant"?: string | undefined;
-    "aria-atomic"?: (boolean | "false" | "true") | undefined;
+    "aria-atomic"?: (boolean | "true" | "false") | undefined;
     "aria-autocomplete"?: "none" | "inline" | "list" | "both" | undefined;
     "aria-braillelabel"?: string | undefined;
     "aria-brailleroledescription"?: string | undefined;
-    "aria-busy"?: (boolean | "false" | "true") | undefined;
+    "aria-busy"?: (boolean | "true" | "false") | undefined;
     "aria-checked"?: boolean | "false" | "mixed" | "true" | undefined;
     "aria-colcount"?: number | undefined;
     "aria-colindex"?: number | undefined;
@@ -114,37 +114,37 @@ export declare function Image({ priority: _priority, quality: _quality, fill: _f
     "aria-describedby"?: string | undefined;
     "aria-description"?: string | undefined;
     "aria-details"?: string | undefined;
-    "aria-disabled"?: (boolean | "false" | "true") | undefined;
+    "aria-disabled"?: (boolean | "true" | "false") | undefined;
     "aria-dropeffect"?: "none" | "copy" | "execute" | "link" | "move" | "popup" | undefined;
     "aria-errormessage"?: string | undefined;
-    "aria-expanded"?: (boolean | "false" | "true") | undefined;
+    "aria-expanded"?: (boolean | "true" | "false") | undefined;
     "aria-flowto"?: string | undefined;
-    "aria-grabbed"?: (boolean | "false" | "true") | undefined;
+    "aria-grabbed"?: (boolean | "true" | "false") | undefined;
     "aria-haspopup"?: boolean | "false" | "true" | "menu" | "listbox" | "tree" | "grid" | "dialog" | undefined;
-    "aria-hidden"?: (boolean | "false" | "true") | undefined;
+    "aria-hidden"?: (boolean | "true" | "false") | undefined;
     "aria-invalid"?: boolean | "false" | "true" | "grammar" | "spelling" | undefined;
     "aria-keyshortcuts"?: string | undefined;
     "aria-label"?: string | undefined;
     "aria-labelledby"?: string | undefined;
     "aria-level"?: number | undefined;
     "aria-live"?: "off" | "assertive" | "polite" | undefined;
-    "aria-modal"?: (boolean | "false" | "true") | undefined;
-    "aria-multiline"?: (boolean | "false" | "true") | undefined;
-    "aria-multiselectable"?: (boolean | "false" | "true") | undefined;
+    "aria-modal"?: (boolean | "true" | "false") | undefined;
+    "aria-multiline"?: (boolean | "true" | "false") | undefined;
+    "aria-multiselectable"?: (boolean | "true" | "false") | undefined;
     "aria-orientation"?: "horizontal" | "vertical" | undefined;
     "aria-owns"?: string | undefined;
     "aria-placeholder"?: string | undefined;
     "aria-posinset"?: number | undefined;
     "aria-pressed"?: boolean | "false" | "mixed" | "true" | undefined;
-    "aria-readonly"?: (boolean | "false" | "true") | undefined;
+    "aria-readonly"?: (boolean | "true" | "false") | undefined;
     "aria-relevant"?: "additions" | "additions removals" | "additions text" | "all" | "removals" | "removals additions" | "removals text" | "text" | "text additions" | "text removals" | undefined;
-    "aria-required"?: (boolean | "false" | "true") | undefined;
+    "aria-required"?: (boolean | "true" | "false") | undefined;
     "aria-roledescription"?: string | undefined;
     "aria-rowcount"?: number | undefined;
     "aria-rowindex"?: number | undefined;
     "aria-rowindextext"?: string | undefined;
     "aria-rowspan"?: number | undefined;
-    "aria-selected"?: (boolean | "false" | "true") | undefined;
+    "aria-selected"?: (boolean | "true" | "false") | undefined;
     "aria-setsize"?: number | undefined;
     "aria-sort"?: "none" | "ascending" | "descending" | "other" | undefined;
     "aria-valuemax"?: number | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.1",
+  "version": "0.2.0-alpha.3",
   "description": "Vite-native React framework for Cloudflare Workers — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",

package/src/client/browser-entry.ts

@@ -12,8 +12,7 @@
  * 3. Setting up client-side navigation for subsequent page transitions
  *
  * After hydration, the browser entry:
- * - Intercepts clicks on <a data-timber-link> for SPA navigation
- * - Listens for mouseenter on <a data-timber-prefetch> for hover prefetch
+ * - Link click handling is per-component (Link's onClick), not global delegation
  * - Listens for popstate events for back/forward navigation
  *
  * Design docs: 18-build-system.md §"Entry Files", 19-client-navigation.md
@@ -50,7 +49,8 @@ import {
   setNavigationState,
 } from './navigation-context.js';
 import { setupServerLogReplay, setupClientErrorForwarding } from './browser-dev.js';
-import { handleLinkClick, handleLinkHover } from './browser-links.js';
+// 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';
 
@@ -593,21 +593,9 @@ function bootstrap(runtimeConfig: typeof config): void {
   }
   window.addEventListener('scroll', saveScrollPosition, { passive: true });
 
-  // Delegate click events on <a data-timber-link> for SPA navigation.
-  // Uses event delegation on document for efficiency — no per-link listeners.
-  document.addEventListener('click', (event: MouseEvent) => {
-    handleLinkClick(event, router);
-  });
-
-  // Delegate mouseenter events on <a data-timber-prefetch> for hover prefetch.
-  // Uses capture phase to detect mouseenter on nested elements.
-  document.addEventListener(
-    'mouseenter',
-    (event: MouseEvent) => {
-      handleLinkHover(event, router);
-    },
-    true // capture phase — mouseenter doesn't bubble
-  );
+  // Link click and hover prefetch are handled per-component by Link's
+  // onClick and onMouseEnter handlers. No global delegation needed.
+  // See LOCAL-340.
 
   // Dev-only: Listen for RSC module invalidation events from @vitejs/plugin-rsc.
   // When a server component is edited, the RSC plugin sends an "rsc:update"

package/src/client/index.ts

@@ -6,7 +6,7 @@ export type { JsonSerializable, RenderErrorDigest } from './types';
 // Navigation
 export { Link, interpolateParams, resolveHref, validateLinkHref, buildLinkProps } from './link';
 export type { LinkProps, LinkPropsWithHref, LinkPropsWithParams } from './link';
-export type { OnNavigateHandler, OnNavigateEvent } from './link-navigate-interceptor';
+export type { OnNavigateHandler, OnNavigateEvent } from './link';
 export { createRouter } from './router';
 export type {
   RouterInstance,

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,58 @@ 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/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,12 +182,10 @@ 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') {
+  // Clean up the finishing phase when the finish animation completes.
+  const handleAnimationEnd = phase === 'finishing'
+    ? (e: React.AnimationEvent) => {
+        if (e.animationName === FINISH_KEYFRAMES) {
           setPhase('hidden');
         }
       }
@@ -195,6 +198,6 @@ export function TopLoader({ config }: { config?: TopLoaderConfig }): React.React
       'aria-hidden': 'true',
       'data-timber-top-loader': '',
     },
-    createElement('div', { style: barStyle, onTransitionEnd: handleTransitionEnd })
+    createElement('div', { style: barStyle, onAnimationEnd: handleAnimationEnd })
   );
 }

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 {

package/dist/client/browser-links.d.ts

@@ -1,32 +0,0 @@
-/**
- * Link click interception and hover prefetch for SPA navigation.
- *
- * Handles click events on <a data-timber-link> and mouseenter events
- * on <a data-timber-prefetch> for client-side navigation.
- *
- * Extracted from browser-entry.ts to keep files under 500 lines.
- *
- * See design/19-client-navigation.md
- */
-import type { RouterInstance } from '@timber-js/app/client';
-/**
- * Handle click events on timber links. Intercepts clicks on <a> elements
- * marked with data-timber-link and triggers SPA navigation instead of
- * a full page load.
- *
- * Passes through to default browser behavior when:
- * - Modified keys are held (Ctrl, Meta, Shift, Alt) — open in new tab
- * - The click is not the primary button
- * - The link has a target attribute (e.g., target="_blank")
- * - The link has a download attribute
- */
-export declare function handleLinkClick(event: MouseEvent, router: RouterInstance): void;
-/**
- * Handle mouseenter events on prefetch-enabled links. When the user
- * hovers over <a data-timber-prefetch>, the RSC payload is fetched
- * and cached for near-instant navigation.
- *
- * See design/19-client-navigation.md §"Prefetch Cache"
- */
-export declare function handleLinkHover(event: MouseEvent, router: RouterInstance): void;
-//# sourceMappingURL=browser-links.d.ts.map

package/dist/client/browser-links.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"browser-links.d.ts","sourceRoot":"","sources":["../../src/client/browser-links.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAK5D;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,cAAc,GAAG,IAAI,CAyC/E;AAID;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,cAAc,GAAG,IAAI,CAU/E"}

package/dist/client/link-navigate-interceptor.d.ts

@@ -1,28 +0,0 @@
-import { type ReactNode } from 'react';
-/** Symbol used to store the onNavigate callback on anchor elements. */
-export declare const ON_NAVIGATE_KEY: "__timberOnNavigate";
-export type OnNavigateEvent = {
-    preventDefault: () => void;
-};
-export type OnNavigateHandler = (e: OnNavigateEvent) => void;
-/**
- * Augment HTMLAnchorElement with the optional onNavigate property.
- * Used by browser-entry.ts handleLinkClick to check for the callback.
- */
-declare global {
-    interface HTMLAnchorElement {
-        [ON_NAVIGATE_KEY]?: OnNavigateHandler;
-    }
-}
-/**
- * Client component rendered inside <Link> that attaches the onNavigate
- * callback to the closest <a> ancestor via a DOM property. The callback
- * is cleaned up on unmount.
- *
- * Renders no extra DOM — just a transparent wrapper.
- */
-export declare function LinkNavigateInterceptor({ onNavigate, children, }: {
-    onNavigate: OnNavigateHandler;
-    children: ReactNode;
-}): import("react/jsx-runtime").JSX.Element;
-//# sourceMappingURL=link-navigate-interceptor.d.ts.map

package/dist/client/link-navigate-interceptor.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"link-navigate-interceptor.d.ts","sourceRoot":"","sources":["../../src/client/link-navigate-interceptor.tsx"],"names":[],"mappings":"AAQA,OAAO,EAAqB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAE1D,uEAAuE;AACvE,eAAO,MAAM,eAAe,EAAG,oBAA6B,CAAC;AAE7D,MAAM,MAAM,eAAe,GAAG;IAC5B,cAAc,EAAE,MAAM,IAAI,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,EAAE,eAAe,KAAK,IAAI,CAAC;AAE7D;;;GAGG;AACH,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,iBAAiB;QACzB,CAAC,eAAe,CAAC,CAAC,EAAE,iBAAiB,CAAC;KACvC;CACF;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,EACtC,UAAU,EACV,QAAQ,GACT,EAAE;IACD,UAAU,EAAE,iBAAiB,CAAC;IAC9B,QAAQ,EAAE,SAAS,CAAC;CACrB,2CAmBA"}