@timber-js/app 0.2.0-alpha.195 → 0.2.0-alpha.197

package/src/client/link.tsx

@@ -20,6 +20,7 @@
 // - searchParams and inline query string are mutually exclusive
 
 import {
+  startTransition,
   useRef,
   useState,
   type AnchorHTMLAttributes,
@@ -37,6 +38,8 @@ import { getRouterOrNull } from './router-ref.ts';
 import { getSsrData } from './ssr-data.ts';
 import { mergePreservedSearchParams } from '../shared/merge-search-params.ts';
 import { getLinkCodec } from '../params/codec-registry.ts';
+import { locationSearch } from './location-search.ts';
+import { stripRscCacheKey } from '../shared/rsc-cache-key.ts';
 import type { LinkStatus } from './use-link-status.ts';
 
 const LINK_PENDING: LinkStatus = { isPending: true };
@@ -46,16 +49,15 @@ const LINK_IDLE: LinkStatus = { isPending: false };
 
 /**
  * Read the current URL's search string without requiring a React hook.
- * On the client, reads window.location.search. During SSR, reads from
- * the request context (getSsrData). Returns empty string if unavailable.
+ * On the client, reads window.location.search. During SSR, reads the raw
+ * query string from the request context (getSsrData) — the same `''` or
+ * `?…` shape, preserving repeated keys (`?tag=a&tag=b`) so the
+ * server-rendered href matches what the hydrated client rebuilds from the
+ * address bar (TIM-1428). Returns empty string if unavailable.
  */
 function getCurrentSearch(): string {
-  if (typeof window !== 'undefined') return window.location.search;
-  const data = getSsrData();
-  if (!data) return '';
-  const sp = new URLSearchParams(data.searchParams);
-  const str = sp.toString();
-  return str ? `?${str}` : '';
+  if (typeof window !== 'undefined') return locationSearch();
+  return getSsrData()?.search ?? '';
 }
 
 // ─── Types ───────────────────────────────────────────────────────
@@ -482,7 +484,7 @@ export const Link: LinkFunction = function LinkImpl(props: any) {
   // a thenable from `startTransition` hands it to `ReactSharedInternals.S`,
   // which calls react-dom's `entangleAsyncAction`. That opens an action scope
   // whose `currentEntangledLane` collects every transition update scheduled
-  // while it is open — including `NavigationRoot`'s `setRendered`, which is a
+  // while it is open — including the router's `root.render` of `NavigationRoot`, which is a
   // fully synchronous `startTransition` in a different component — and
   // rendering that lane suspends on `currentEntangledActionThenable` until the
   // action settles. `navigateTransition` awaits `decodePromise`, so a Link
@@ -496,7 +498,12 @@ export const Link: LinkFunction = function LinkImpl(props: any) {
   //
   // `isPending` runs from the click until `router.navigate()` settles, which
   // is after `decodePromise` — the same lifecycle the router's pending store
-  // and the TopLoader use.
+  // and the TopLoader use. The clear wraps in `startTransition` so it lands
+  // on the same React lane as the router's `root.render` — without it,
+  // the clear is an urgent update that paints before the transition commits,
+  // and destinations with pending Suspense boundaries flash idle for one frame
+  // while the old page is still showing (TIM-1418). The callback is
+  // synchronous, so no action scope is opened (TIM-1306/1307 safe).
   //
   // `clickSeq` exists because a superseded navigation RESOLVES rather than
   // rejecting: `runNavigation` swallows AbortErrors. So clicking the same link
@@ -509,11 +516,10 @@ export const Link: LinkFunction = function LinkImpl(props: any) {
   const linkStatus = isPending ? LINK_PENDING : LINK_IDLE;
 
   // Preserve search params from the current URL when requested.
-  // useSearchParams() works during both SSR (reads from request context)
-  // and on the client (reads from window.location, reactive to URL changes).
-  // We read current search params directly to avoid unconditional hook calls.
-  // On the client, window.location.search is always current; during SSR,
-  // getSsrData() provides the request's search params.
+  // Read via getCurrentSearch() rather than a hook, to avoid an
+  // unconditional hook call for a prop most links don't pass. On the
+  // client, window.location.search is always current; during SSR,
+  // getSsrData() provides the request's raw query string.
   const internal = isInternalHref(baseHref);
 
   // Only preserve search params for internal links — leaking current
@@ -559,7 +565,7 @@ export const Link: LinkFunction = function LinkImpl(props: any) {
 
         if (
           resolved.pathname === window.location.pathname &&
-          resolved.search === window.location.search &&
+          stripRscCacheKey(resolved.search) === locationSearch() &&
           resolved.hash
         ) {
           return;
@@ -571,11 +577,11 @@ export const Link: LinkFunction = function LinkImpl(props: any) {
         // Keep the #fragment — the router commits it to the address bar and
         // scrolls to the matching element after render. The hash is stripped
         // from the RSC fetch URL inside the router (TIM-1035).
-        const absoluteHref = resolved.pathname + resolved.search + resolved.hash;
+        const absoluteHref = resolved.pathname + stripRscCacheKey(resolved.search) + resolved.hash;
 
         const seq = ++clickSeq.current;
         const settle = () => {
-          if (clickSeq.current === seq) setIsPending(false);
+          if (clickSeq.current === seq) startTransition(() => setIsPending(false));
         };
         setIsPending(true);
         router.navigate(absoluteHref, { scroll: shouldScroll }).then(settle, (error: unknown) => {
@@ -609,7 +615,7 @@ export const Link: LinkFunction = function LinkImpl(props: any) {
               ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams)
               : resolvedHref;
             const resolved = new URL(prefetchHref, window.location.href);
-            router.prefetch(resolved.pathname + resolved.search);
+            router.prefetch(resolved.pathname + stripRscCacheKey(resolved.search));
           }
         }
       : userOnMouseEnter;

package/src/client/location-search.ts

@@ -0,0 +1,15 @@
+import { stripRscCacheKey } from '../shared/rsc-cache-key.ts';
+
+/**
+ * The app-visible search string from the address bar.
+ *
+ * Mirrors what `appVisibleSearch()` does on the server: strips key-shaped
+ * `_rsc` values so the client and server agree on search state regardless
+ * of whether the document URL itself carries a payload cache key (a user
+ * pasting/sharing an RSC payload URL). Non-key-shaped `_rsc` values — an
+ * application legitimately owning that name — survive, using the same
+ * `isRscCacheKeyShape` predicate the server uses.
+ */
+export function locationSearch(): string {
+  return stripRscCacheKey(window.location.search);
+}

package/src/client/navigation-api.ts

@@ -18,6 +18,7 @@
  */
 
 import { isHardNavigating } from './navigation-root.tsx';
+import { stripRscCacheKey } from '../shared/rsc-cache-key.ts';
 
 // ─── Feature Detection ───────────────────────────────────────────
 
@@ -220,7 +221,7 @@ export function setupNavigationApi(callbacks: NavigationApiCallbacks): Navigatio
     // Skip reload navigations — let the browser handle full page reload
     if (event.navigationType === 'reload') return;
 
-    const url = destUrl.pathname + destUrl.search;
+    const url = destUrl.pathname + stripRscCacheKey(destUrl.search);
 
     if (event.navigationType === 'traverse') {
       // Back/forward button — intercept and delegate to router.
@@ -265,7 +266,8 @@ export function setupNavigationApi(callbacks: NavigationApiCallbacks): Navigatio
       // destination. Once intercept() is called, currentEntry switches and
       // getCurrentUrl() returns the destination (TIM-1232).
       const departingUrl = nav.currentEntry?.url
-        ? new URL(nav.currentEntry.url).pathname + new URL(nav.currentEntry.url).search
+        ? new URL(nav.currentEntry.url).pathname +
+          stripRscCacheKey(new URL(nav.currentEntry.url).search)
         : undefined;
 
       event.intercept({

package/src/client/navigation-commit.ts

@@ -54,6 +54,51 @@ export interface NavigationCommitInput {
    * See TIM-1356.
    */
   status?: number;
+  /**
+   * Layouts the server skipped on this response (`X-Timber-Skipped-Segments`),
+   * when it came from a fetch. Omitted by replays and revalidation.
+   *
+   * Together with `skipped` slot entries in `segmentInfo`, this decides
+   * whether the payload can be *replayed*. A partial payload only renders
+   * merged over the tree on screen, and a `skip=true` outlet resolves against
+   * the slot content cache at render time — so a stored copy of either,
+   * replayed later, shows whatever the client holds *then*, not what was on
+   * screen when the entry committed. Such entries store a null payload and
+   * traversals to them fetch instead. Decided here, not at the fetch call
+   * sites, for the same reason as `status`: `performNavigationFetch` had the
+   * check and `fetchCommitAndRender` did not, so a back/forward fetch that
+   * was answered with skips stored the holes (TIM-1432).
+   */
+  skippedSegments?: string[] | null;
+}
+
+/** Whether a response skipped layouts — its payload merges over the tree on screen. */
+export function isPartialNavigation(skippedSegments: string[] | null | undefined): boolean {
+  return skippedSegments != null && skippedSegments.length > 0;
+}
+
+/**
+ * Whether a payload can stand on its own when replayed from the history
+ * stack. See `NavigationCommitInput.skippedSegments`.
+ */
+function isReplayable(opts: NavigationCommitInput): boolean {
+  return !isPartialNavigation(opts.skippedSegments) && !hasSkippedSlot(opts.segmentInfo);
+}
+
+function hasSkippedSlot(segmentInfo: SegmentInfo[] | null | undefined): boolean {
+  return segmentInfo?.some((s) => s.slot && s.skipped) ?? false;
+}
+
+/**
+ * The metadata a history entry keeps. `skipped` describes the *response*
+ * — "this slot's content was omitted" — and the entry stores no such
+ * payload (it stores null). Left on the entry, the flag outlives the
+ * response: `applyRevalidation()` reuses the entry's metadata beside a full
+ * re-render and would have that judged non-replayable too.
+ */
+function storedSegmentInfo(segmentInfo: SegmentInfo[] | null | undefined) {
+  if (!hasSkippedSlot(segmentInfo)) return segmentInfo;
+  return segmentInfo!.map(({ skipped: _skipped, ...rest }) => rest);
 }
 
 /**
@@ -173,6 +218,7 @@ export function createNavigationCommitter(deps: {
       // traversal back to this URL would replay the metadata this drops.
       const cacheable = opts.status === undefined || opts.status < 400;
       const segmentInfo = cacheable ? opts.segmentInfo : [];
+      const payload = isReplayable(opts) ? opts.payload : null;
 
       return {
         navState,
@@ -186,9 +232,9 @@ export function createNavigationCommitter(deps: {
           setNavigationState(navState);
 
           historyStack.push(url, {
-            payload: opts.payload,
+            payload,
             params: opts.params,
-            segmentInfo,
+            segmentInfo: storedSegmentInfo(segmentInfo),
           });
         },
       };

package/src/client/navigation-context.ts

@@ -18,14 +18,15 @@
  * All consumers (usePathname, useSearchParams) see the new values in the
  * same render pass as the new tree.
  *
- * During SSR, no NavigationProvider is mounted. Hooks fall back to
- * the ALS-backed getSsrData() for per-request isolation.
+ * During SSR, the wrapper chain mounts this same provider with the
+ * request's pathname and raw search string (TIM-1424), so the hooks
+ * resolve through the identical code path on both sides. Per-request
+ * isolation is by construction — the value is part of the request's
+ * element tree.
  *
- * IMPORTANT: createContext and useContext are NOT available in the RSC
- * environment (React Server Components use a stripped-down React).
- * The context is lazily initialized on first access, and all functions
- * that depend on these APIs are safe to call from any environment —
- * they return null or no-op when the APIs aren't available.
+ * This module is `'use client'` and is never evaluated in the RSC
+ * environment. The shims plugin resolves next/navigation to
+ * navigation-rsc.ts in RSC, which has throwing stubs (TIM-1420).
  *
  * SINGLETON GUARANTEE: All shared mutable state uses globalThis via
  * Symbol.for keys. The RSC client bundler can duplicate this module
@@ -41,7 +42,7 @@
  * See design/19-client-navigation.md §"NavigationContext"
  */
 
-import React, { createElement, type ReactNode } from 'react';
+import { createContext, useContext, createElement, type ReactNode } from 'react';
 import type { SlotParamsRecord } from '../shared/slot-params.ts';
 
 // ---------------------------------------------------------------------------
@@ -68,10 +69,6 @@ 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
@@ -79,38 +76,34 @@ export interface NavigationState {
  * context A while the consumer in usePendingNavigation (shared chunk)
  * reads from context B. globalThis guarantees a single instance.
  *
+ * This module is `'use client'` so it is never evaluated in the RSC
+ * environment — `createContext` and `useContext` are always available.
+ * The shims plugin resolves next/navigation to navigation-rsc.ts in RSC,
+ * which has throwing stubs for the hooks (TIM-1420).
+ *
  * See design/27-chunking-strategy.md §"Singleton Safety"
  */
 
-// Symbol keys for globalThis storage — prevents collisions with user code
 const NAV_CTX_KEY = Symbol.for('__timber_nav_ctx');
 
-function getOrCreateContext(): React.Context<NavigationState | null> | undefined {
+function getOrCreateContext(): import('react').Context<NavigationState | null> {
   const existing = (globalThis as Record<symbol, unknown>)[NAV_CTX_KEY] as
-    | React.Context<NavigationState | null>
+    | import('react').Context<NavigationState | null>
     | undefined;
   if (existing !== undefined) return existing;
-  // createContext may not exist in the RSC environment
-  if (typeof React.createContext === 'function') {
-    const ctx = React.createContext<NavigationState | null>(null);
-    (globalThis as Record<symbol, unknown>)[NAV_CTX_KEY] = ctx;
-    return ctx;
-  }
-  return undefined;
+  const ctx = createContext<NavigationState | null>(null);
+  (globalThis as Record<symbol, unknown>)[NAV_CTX_KEY] = ctx;
+  return ctx;
 }
 
 /**
- * Read the navigation context. Returns null during SSR (no provider)
- * or in the RSC environment (no context available).
+ * Read the navigation context. Returns null only when no provider is above
+ * the caller — a component rendered outside the timber app.
+ *
  * Internal — used by usePathname() and useSearchParams().
  */
 export function useNavigationContext(): NavigationState | null {
-  const ctx = getOrCreateContext();
-  if (!ctx) return null;
-  // useContext may not exist in the RSC environment — caller wraps in try/catch
-  if (typeof React.useContext !== 'function') return null;
-  // eslint-disable-next-line rules-of-hooks -- conditional on environment, not render path
-  return React.useContext(ctx);
+  return useContext(getOrCreateContext());
 }
 
 // ---------------------------------------------------------------------------
@@ -131,13 +124,8 @@ export interface NavigationProviderProps {
 export function NavigationProvider({
   value,
   children,
-}: NavigationProviderProps): React.ReactElement {
-  const ctx = getOrCreateContext();
-  if (!ctx) {
-    // RSC environment — no context available. Return children as-is.
-    return children as React.ReactElement;
-  }
-  return createElement(ctx.Provider, { value }, children);
+}: NavigationProviderProps): import('react').ReactElement {
+  return createElement(getOrCreateContext().Provider, { value }, children);
 }
 
 // ---------------------------------------------------------------------------