@timber-js/app 0.2.0-alpha.33 → 0.2.0-alpha.35

package/src/client/browser-entry.ts

@@ -47,6 +47,7 @@ import {
   NavigationProvider,
   getNavigationState,
   setNavigationState,
+  type NavigationState,
 } from './navigation-context.js';
 import { setupServerLogReplay, setupClientErrorForwarding } from './browser-dev.js';
 // browser-links.ts removed — Link components own their click/hover handlers directly.
@@ -54,9 +55,16 @@ import { setupServerLogReplay, setupClientErrorForwarding } from './browser-dev.
 import { TransitionRoot, transitionRender, navigateTransition } from './transition-root.js';
 import {
   isStaleClientReference,
+  isChunkLoadError,
   triggerStaleReload,
   clearStaleReloadFlag,
 } from './stale-reload.js';
+import {
+  setClientDeploymentId,
+  getClientDeploymentId,
+  DEPLOYMENT_ID_HEADER,
+  RELOAD_HEADER,
+} from './rsc-fetch.js';
 
 // ─── Server Action Dispatch ──────────────────────────────────────
 
@@ -85,14 +93,28 @@ setServerCallback(async (id: string, args: unknown[]) => {
   let hasRedirect = false;
   let headElementsJson: string | null = null;
 
+  // Build action request headers. Include deployment ID for version
+  // skew detection (TIM-446) — the server rejects stale actions gracefully.
+  const actionHeaders: Record<string, string> = {
+    'Accept': 'text/x-component',
+    'x-rsc-action': id,
+  };
+  const actionDeploymentId = getClientDeploymentId();
+  if (actionDeploymentId) {
+    actionHeaders[DEPLOYMENT_ID_HEADER] = actionDeploymentId;
+  }
+
   const response = fetch(window.location.href, {
     method: 'POST',
-    headers: {
-      'Accept': 'text/x-component',
-      'x-rsc-action': id,
-    },
+    headers: actionHeaders,
     body,
   }).then((res) => {
+    // Version skew detection (TIM-446): if the server signals a reload,
+    // trigger a full page load to pick up the new deployment.
+    if (res.headers.get(RELOAD_HEADER) === '1') {
+      window.location.reload();
+      throw new Error('Version skew detected — reloading page');
+    }
     hasRevalidation = res.headers.get('X-Timber-Revalidation') === '1';
     hasRedirect = res.headers.get('X-Timber-Redirect') != null;
     headElementsJson = res.headers.get('X-Timber-Head');
@@ -159,7 +181,17 @@ setServerCallback(async (id: string, args: unknown[]) => {
  * Hydrates the server-rendered HTML with React, then initializes
  * client-side navigation for SPA transitions.
  */
-/** Read scroll position from window or scroll containers. */
+/**
+ * Read the current scroll position.
+ *
+ * Checks window scroll first, then explicit `data-timber-scroll-restoration`
+ * containers. With segment tree merging, shared layouts are reconciled in
+ * place via `cloneElement` — React preserves their DOM and scroll state
+ * naturally. We don't need to auto-detect overflow containers; only
+ * explicitly marked containers are tracked.
+ *
+ * See design/19-client-navigation.md §"Overflow Scroll Containers".
+ */
 function getScrollY(): number {
   if (window.scrollY || document.documentElement.scrollTop || document.body.scrollTop) {
     return window.scrollY || document.documentElement.scrollTop || document.body.scrollTop;
@@ -167,71 +199,24 @@ function getScrollY(): number {
   for (const el of document.querySelectorAll('[data-timber-scroll-restoration]')) {
     if ((el as HTMLElement).scrollTop > 0) return (el as HTMLElement).scrollTop;
   }
-  // Auto-detect: if window isn't scrolled, check for overflow containers.
-  // Common pattern: layouts use a scrollable div (overflow-y: auto/scroll)
-  // inside a fixed-height parent (h-screen). In this case window.scrollY is
-  // always 0 and the real scroll position lives on the overflow container.
-  const container = findOverflowContainer();
-  if (container && container.scrollTop > 0) return container.scrollTop;
   return 0;
 }
 
-/**
- * Find the primary overflow scroll container in the document.
- *
- * Walks direct children of body and their immediate children looking for
- * an element with overflow-y: auto|scroll that is actually scrollable
- * (scrollHeight > clientHeight). Returns the first match, or null.
- *
- * This heuristic covers the common layout patterns:
- *   <body> → <root-layout> → <div class="overflow-y-auto">
- *   <body> → <root-layout> → <main> → <nested-layout overflow-y-auto>
- *
- * We limit depth to 3 to avoid expensive full-tree traversals while still
- * reaching nested layout scroll containers (e.g., parallel route layouts
- * inside a root layout's <main> element).
- *
- * DIVERGENCE FROM NEXT.JS: Next.js's ScrollAndFocusHandler scrolls only
- * document.documentElement.scrollTop — it does NOT handle overflow containers.
- * Layouts using h-screen + overflow-y-auto have the same scroll bug in Next.js.
- * This heuristic is a deliberate improvement. The tradeoff is fragility: depth-3
- * traversal may miss deeply nested containers or match the wrong element.
- * See design/19-client-navigation.md §"Overflow Scroll Containers".
- */
-function findOverflowContainer(): HTMLElement | null {
-  const candidates: HTMLElement[] = [];
-  // Check body's descendants up to depth 3. Depth 3 covers the common case:
-  //   <body> → <root-layout-div> → <main> → <overflow-container>
-  // React context providers (SegmentProvider, NavigationProvider) don't add
-  // DOM elements, so depth 3 from body reaches nested layout scroll containers.
-  for (const child of document.body.children) {
-    candidates.push(child as HTMLElement);
-    for (const grandchild of child.children) {
-      candidates.push(grandchild as HTMLElement);
-      for (const greatGrandchild of grandchild.children) {
-        candidates.push(greatGrandchild as HTMLElement);
-      }
-    }
-  }
-  for (const el of candidates) {
-    if (!(el instanceof HTMLElement)) continue;
-    const style = getComputedStyle(el);
-    const overflowY = style.overflowY;
-    if ((overflowY === 'auto' || overflowY === 'scroll') && el.scrollHeight > el.clientHeight) {
-      return el;
-    }
-  }
-  return null;
-}
-
 function bootstrap(runtimeConfig: typeof config): void {
   const _config = runtimeConfig;
 
-  // Take manual control of scroll restoration. React's render() on the
-  // document root resets scroll during DOM reconciliation, so the browser's
-  // native scroll restoration (scrollRestoration = 'auto') doesn't work —
-  // the browser restores scroll, then React's commit resets it to 0.
-  // We save/restore scroll positions explicitly in the history stack.
+  // Initialize deployment ID for version skew detection (TIM-446).
+  // In dev mode this is null — skew checks are skipped.
+  const deploymentId = (_config as Record<string, unknown>).deploymentId as string | null;
+  if (deploymentId) {
+    setClientDeploymentId(deploymentId);
+  }
+
+  // Take manual control of scroll restoration. Even though segment tree
+  // merging preserves shared layout DOM via cloneElement (so React doesn't
+  // reset scroll on those elements), the root-level reactRoot.render() with
+  // a new element tree can still cause scroll resets on the document during
+  // reconciliation. Manual control ensures consistent behavior.
   window.history.scrollRestoration = 'manual';
 
   // Hydrate the React tree from the RSC payload.
@@ -247,6 +232,21 @@ function bootstrap(runtimeConfig: typeof config): void {
   // For subsequent navigations, it's fetched from the server.
   type FlightSegment = [isBootstrap: 0] | [isData: 1, data: string];
 
+  // On streaming pages, the browser entry module may load before the RSC
+  // payload scripts arrive. The <script id="_R_"> tag is in the shell (flushed
+  // on onShellReady), but the RSC bootstrap script `(self.__timber_f=...).push([0])`
+  // is injected by the flight injector AFTER Suspense resolution scripts.
+  // If the module import resolves before those scripts execute, __timber_f
+  // will be undefined.
+  //
+  // Fix: if __timber_f isn't available yet, pre-initialize it so the RSC
+  // bootstrap script's `(self.__timber_f=self.__timber_f||[]).push([0])` finds
+  // our array and pushes into it. This avoids a race condition that causes
+  // the browser entry to fall through to createRoot() (no hydration) on
+  // streaming pages.
+  if (!(self as unknown as Record<string, unknown>).__timber_f) {
+    (self as unknown as Record<string, FlightSegment[]>).__timber_f = [];
+  }
   const timberChunks = (self as unknown as Record<string, FlightSegment[]>).__timber_f;
 
   let _reactRoot: Root | null = null;
@@ -348,7 +348,7 @@ function bootstrap(runtimeConfig: typeof config): void {
 
     // ── Initialize navigation state BEFORE hydration ───────────────────
     // Read server-embedded params and set navigation state so that
-    // useParams() and usePathname() return correct values during hydration.
+    // useSegmentParams() and usePathname() return correct values during hydration.
     // This must happen before hydrateRoot so the NavigationProvider
     // wrapping the element has the right values on the initial render.
     const earlyParams = (self as unknown as Record<string, unknown>).__timber_params;
@@ -424,23 +424,20 @@ function bootstrap(runtimeConfig: typeof config): void {
       pushState: (data, unused, url) => window.history.pushState(data, unused, url),
       replaceState: (data, unused, url) => window.history.replaceState(data, unused, url),
       scrollTo: (x, y) => {
+        // Scroll the document viewport.
         window.scrollTo(x, y);
         document.documentElement.scrollTop = y;
         document.body.scrollTop = y;
-        // Also scroll any element explicitly marked as a scroll container.
+        // Scroll any element explicitly marked as a scroll container.
+        // With segment tree merging, shared layouts (sidebars, nav bars)
+        // are reconciled in place via cloneElement — React preserves their
+        // DOM and scroll state naturally. We no longer auto-detect overflow
+        // containers, which previously found the wrong element (e.g.,
+        // scrolling a sidebar instead of the main content area).
+        // Use `data-timber-scroll-restoration` to opt in specific containers.
         for (const el of document.querySelectorAll('[data-timber-scroll-restoration]')) {
           (el as HTMLElement).scrollTop = y;
         }
-        // Auto-detect overflow containers for layouts that scroll inside
-        // a fixed-height wrapper (e.g., h-screen + overflow-y-auto).
-        // In these layouts, window.scrollY is always 0 and the real scroll
-        // lives on the overflow container. Without this, forward navigation
-        // between pages that share a layout with parallel route slots won't
-        // scroll to top — the router's window.scrollTo(0,0) is a no-op.
-        const container = findOverflowContainer();
-        if (container) {
-          container.scrollTop = y;
-        }
       },
       getCurrentUrl: () => window.location.pathname + window.location.search,
       getScrollY,
@@ -475,8 +472,10 @@ function bootstrap(runtimeConfig: typeof config): void {
       // For navigation renders (navigate, refresh, popstate-with-fetch),
       // navigateTransition is used instead — it wraps the entire navigation
       // in a React transition with useOptimistic for the pending URL.
-      renderRoot: (element: unknown) => {
-        const navState = getNavigationState();
+      //
+      // navState is passed explicitly by the router — no temporal coupling
+      // with getNavigationState().
+      renderRoot: (element: unknown, navState: NavigationState) => {
         const withNav = createElement(
           NavigationProvider,
           { value: navState },
@@ -492,13 +491,11 @@ function bootstrap(runtimeConfig: typeof config): void {
       // commits (atomic with the new tree + params).
       //
       // The perform callback receives a wrapPayload function that wraps the
-      // decoded RSC payload with NavigationProvider + NuqsAdapter — this must
-      // happen inside the transition so the NavigationProvider reads the
-      // UPDATED navigation state (set by the router inside perform).
+      // decoded RSC payload with NavigationProvider + NuqsAdapter. navState
+      // is passed explicitly by the router — no getNavigationState() needed.
       navigateTransition: (pendingUrl: string, perform) => {
         return navigateTransition(pendingUrl, async () => {
-          const payload = await perform((rawPayload: unknown) => {
-            const navState = getNavigationState();
+          const payload = await perform((rawPayload: unknown, navState: NavigationState) => {
             const withNav = createElement(
               NavigationProvider,
               { value: navState },
@@ -590,7 +587,6 @@ function bootstrap(runtimeConfig: typeof config): void {
     scrollTimer = setTimeout(() => {
       const state = window.history.state;
       if (state && typeof state === 'object') {
-        // Use getScrollY to capture scroll from overflow containers too.
         window.history.replaceState({ ...state, scrollY: getScrollY() }, '');
       }
     }, 100);
@@ -659,8 +655,21 @@ clearStaleReloadFlag();
 // If the payload references a module ID from a newer deployment, the error
 // surfaces as an unhandled rejection during React's render/hydration cycle.
 // This handler catches those errors and triggers a full page reload.
+//
+// Also catches chunk load failures (dynamic import of missing assets after
+// a deployment) — these surface as "Failed to fetch dynamically imported module"
+// or "Loading chunk <name> failed" errors. See TIM-446.
 window.addEventListener('unhandledrejection', (event) => {
-  if (isStaleClientReference(event.reason)) {
+  if (isStaleClientReference(event.reason) || isChunkLoadError(event.reason)) {
+    event.preventDefault();
+    triggerStaleReload();
+  }
+});
+
+// Also catch synchronous errors from chunk loads (some browsers throw
+// TypeError synchronously instead of via unhandled rejection).
+window.addEventListener('error', (event) => {
+  if (isChunkLoadError(event.error)) {
     event.preventDefault();
     triggerStaleReload();
   }

package/src/client/error-boundary.tsx

@@ -65,7 +65,16 @@ type ParsedDigest = DenyDigest | RenderErrorDigest | RedirectDigest;
 
 export interface TimberErrorBoundaryProps {
   /** The component to render when an error is caught. */
-  fallbackComponent: (...args: unknown[]) => ReactNode;
+  fallbackComponent?: (...args: unknown[]) => ReactNode;
+  /**
+   * Pre-rendered fallback element. Used for MDX status files which are server
+   * components and cannot be passed as function props across the RSC→client
+   * boundary. When set, rendered directly instead of calling fallbackComponent.
+   *
+   * See design/10-error-handling.md §"Status-Code File Variants" — MDX status
+   * files are server components by default (zero client JS).
+   */
+  fallbackElement?: ReactNode;
   /**
    * Status code filter. If set, only catches errors matching this status.
    * 400 = any 4xx, 500 = any 5xx, specific number = exact match.
@@ -162,6 +171,14 @@ export class TimberErrorBoundary extends Component<
       }
     }
 
+    // Pre-rendered fallback element (MDX status files) — render directly.
+    // MDX components are server components that cannot be passed as function
+    // props across the RSC→client boundary. Instead, they are pre-rendered
+    // as elements in the RSC environment and passed here as fallbackElement.
+    if (this.props.fallbackElement != null) {
+      return this.props.fallbackElement;
+    }
+
     // Render the fallback component with the right props shape.
     if (parsed?.type === 'deny') {
       return createElement(this.props.fallbackComponent as never, {

package/src/client/index.ts

@@ -12,6 +12,7 @@ export type {
   RouterInstance,
   NavigationOptions,
   RouterDeps,
+  RouterPhase,
   RscDecoder,
   RootRenderer,
 } from './router';
@@ -42,7 +43,7 @@ export { useActionState, useFormAction, useFormErrors } from './form';
 export type { UseActionStateFn, UseActionStateReturn, FormErrorsResult } from './form';
 
 // Params
-export { useParams, setCurrentParams } from './use-params';
+export { useSegmentParams, setCurrentParams } from './use-params';
 
 // Navigation context (framework-internal, used by browser-entry for atomic updates)
 export { NavigationProvider, getNavigationState, setNavigationState } from './navigation-context';
@@ -55,6 +56,13 @@ export { useQueryStates, bindUseQueryStates } from './use-query-states';
 export { useCookie } from './use-cookie';
 export type { ClientCookieOptions, CookieSetter } from './use-cookie';
 
+// Register the client cookie module with defineCookie's lazy reference.
+// This runs at module load time in the client/SSR environment, wiring up
+// the useCookie hook without a top-level import in define-cookie.ts.
+import * as _useCookieMod from './use-cookie.js';
+import { _registerUseCookieModule } from '#/cookies/define-cookie.js';
+_registerUseCookieModule(_useCookieMod);
+
 // SSR data (framework-internal, used by ssr-entry to provide request data to hooks)
 export { setSsrData, clearSsrData, getSsrData } from './ssr-data';
 export type { SsrData } from './ssr-data';

package/src/client/link.tsx

@@ -19,7 +19,7 @@
 // - searchParams and inline query string are mutually exclusive
 
 import type { AnchorHTMLAttributes, ReactNode, MouseEvent as ReactMouseEvent } from 'react';
-import type { SearchParamsDefinition } from '#/search-params/create.js';
+import type { SearchParamsDefinition } from '#/search-params/define.js';
 import { LinkStatusProvider } from './link-status-provider.js';
 import { getRouterOrNull } from './router-ref.js';
 
@@ -61,7 +61,7 @@ interface LinkBaseProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'h
  */
 export interface LinkPropsWithHref extends LinkBaseProps {
   href: string;
-  params?: never;
+  segmentParams?: never;
   /**
    * Typed search params — serialized via the route's SearchParamsDefinition.
    * Mutually exclusive with an inline query string in href.
@@ -73,9 +73,9 @@ export interface LinkPropsWithHref extends LinkBaseProps {
 }
 
 /**
- * Link with a route pattern + params for interpolation.
- * e.g. <Link href="/products/[id]" params={{ id: "123" }}>
- *      <Link href="/products/[id]" params={{ id: 123 }}>
+ * Link with a route pattern + segmentParams for interpolation.
+ * e.g. <Link href="/products/[id]" segmentParams={{ id: "123" }}>
+ *      <Link href="/products/[id]" segmentParams={{ id: 123 }}>
  */
 export interface LinkPropsWithParams extends LinkBaseProps {
   /** Route pattern with dynamic segments (e.g. "/products/[id]") */
@@ -85,7 +85,7 @@ export interface LinkPropsWithParams extends LinkBaseProps {
    * Single dynamic segments accept string | number (numbers are stringified).
    * Catch-all segments accept string[].
    */
-  params: Record<string, string | number | string[]>;
+  segmentParams: Record<string, string | number | string[]>;
   /**
    * Typed search params — serialized via the route's SearchParamsDefinition.
    */
@@ -303,14 +303,14 @@ function shouldInterceptClick(
  * its own click handling.
  *
  * Supports typed routes via codegen overloads. At runtime:
- * - `params` prop interpolates dynamic segments in the href pattern
+ * - `segmentParams` prop interpolates dynamic segments in the href pattern
  * - `searchParams` prop serializes query parameters via a SearchParamsDefinition
  */
 export function Link({
   href,
   prefetch,
   scroll,
-  params,
+  segmentParams,
   searchParams,
   onNavigate,
   onClick: userOnClick,
@@ -318,7 +318,7 @@ export function Link({
   children,
   ...rest
 }: LinkProps) {
-  const { href: resolvedHref } = buildLinkProps({ href, params, searchParams });
+  const { href: resolvedHref } = buildLinkProps({ href, params: segmentParams, searchParams });
   const internal = isInternalHref(resolvedHref);
 
   // ─── Click handler ───────────────────────────────────────────

package/src/client/navigation-context.ts

@@ -5,7 +5,7 @@
  *
  * Holds the current route params and pathname, updated atomically
  * with the RSC tree on each navigation. This replaces the previous
- * useSyncExternalStore approach for useParams() and usePathname(),
+ * useSyncExternalStore approach for useSegmentParams() and usePathname(),
  * which suffered from a timing gap: the new tree could commit before
  * the external store re-renders fired, causing a frame where both
  * old and new active states were visible simultaneously.
@@ -90,7 +90,7 @@ function getOrCreateContext(): React.Context<NavigationState | null> | undefined
 /**
  * Read the navigation context. Returns null during SSR (no provider)
  * or in the RSC environment (no context available).
- * Internal — used by useParams() and usePathname().
+ * Internal — used by useSegmentParams() and usePathname().
  */
 export function useNavigationContext(): NavigationState | null {
   const ctx = getOrCreateContext();