@timber-js/app 0.2.0-alpha.196 → 0.2.0-alpha.198

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