@timber-js/app 0.2.0-alpha.208 → 0.2.0-alpha.209

package/src/client/router-pipeline.ts

@@ -15,8 +15,8 @@
 
 import { fetchRscPayload, NonRscResponse } from './rsc-fetch.ts';
 import type { FetchResult } from './rsc-fetch.ts';
-import { readPublishedParams, type ParamsSource } from '../shared/payload-root.ts';
-import type { PrefetchCache, PrefetchKey, FlightOutcome } from './segment-cache.ts';
+import { readPublishedParams } from '../shared/payload-root.ts';
+import type { PrefetchCache, PrefetchKey } from './segment-cache.ts';
 import { prefetchScopeOf } from './segment-cache.ts';
 import type { StateTree } from '../shared/segment-info.ts';
 import type { NavigationState } from './navigation-context.ts';
@@ -24,6 +24,7 @@ import { isPartialNavigation, type NavigationCommitter } from './navigation-comm
 import type { RouterDeps } from './router-types.ts';
 import type { CommitOutcome, RenderOwner } from './navigation-transition.ts';
 import { recordSkew } from './router-skew.ts';
+import { parseRouterUrl } from './router-url.ts';
 import { SingleflightTimeoutError } from '../cache/singleflight.ts';
 
 /**
@@ -76,7 +77,7 @@ export interface NavigationPipeline {
     url: string,
     options: NavigationFetchOptions
   ) => Promise<NavigationPayload>;
-  /** Hand a payload to React inside a transition, or render it directly in tests. */
+  /** Hand a payload to React inside a transition. */
   renderViaTransition: (
     url: string,
     owner: RenderOwner,
@@ -84,15 +85,6 @@ export interface NavigationPipeline {
     /** See `NavigationOptions.onCommit`. */
     onCommit?: (outcome: CommitOutcome) => void
   ) => Promise<void>;
-  /** Render a decoded payload into the DOM if a renderer is available. */
-  renderPayload: (
-    payload: unknown,
-    navState: NavigationState,
-    params: ParamsSource,
-    commit: () => void
-  ) => void;
-  /** Resolve thenable payloads on the fallback (test) path. */
-  resolveForFallback: (payload: unknown) => Promise<unknown>;
 }
 
 /**
@@ -109,7 +101,7 @@ export interface NavigationPipeline {
  * both `location.href` and a bare pathname.
  */
 export function departingPathname(raw: string): string {
-  return new URL(raw, 'http://localhost').pathname;
+  return parseRouterUrl(raw).pathname;
 }
 
 /**
@@ -139,14 +131,14 @@ export function prefetchKeyFor(
  * Build a segment updates map for partial navigation. Identifies the
  * first non-skipped segment and maps it to the payload content.
  */
-function buildSegmentUpdates(result: FetchResult): Map<string, unknown> {
+function buildSegmentUpdates(result: FetchResult, payload: unknown): Map<string, unknown> {
   const skipped = new Set(result.skippedSegments!);
   const segmentInfo = result.segmentInfo;
   const updates = new Map<string, unknown>();
   if (segmentInfo) {
     for (const info of segmentInfo) {
       if (!skipped.has(info.segmentId ?? info.path)) {
-        updates.set(info.segmentId ?? info.path, result.payload);
+        updates.set(info.segmentId ?? info.path, payload);
         break;
       }
     }
@@ -180,50 +172,13 @@ export function createNavigationPipeline({
   forgetOlderHandoffs,
 }: NavigationPipelineDeps): NavigationPipeline {
   /**
-   * Render a decoded RSC payload into the DOM, publishing `commit` when the
-   * tree is current. The renderer owns that moment (see `RootRenderer`);
-   * with no renderer there is no tree to wait for, so it publishes now.
-   */
-  function renderPayload(
-    payload: unknown,
-    navState: NavigationState,
-    params: ParamsSource,
-    commit: () => void
-  ): void {
-    if (deps.renderRoot) {
-      deps.renderRoot(payload, navState, params, commit);
-    } else {
-      commit();
-    }
-  }
-
-  /**
-   * Resolve thenable payloads in the test/fallback path (no navigateTransition).
-   * In production, React handles thenables from createFromFetch directly via
-   * Suspense. In tests, renderRoot is a plain mock that expects resolved values.
-   */
-  async function resolveForFallback(payload: unknown): Promise<unknown> {
-    if (
-      !deps.navigateTransition &&
-      payload != null &&
-      typeof payload === 'object' &&
-      'then' in payload
-    ) {
-      return await (payload as PromiseLike<unknown>);
-    }
-    return payload;
-  }
-
-  /**
-   * Render a payload via navigateTransition (production) or renderRoot (tests).
-   * The perform callback should fetch data, prepare the commit, and return the
+   * Hand a payload to React via navigateTransition. The perform callback should fetch data, prepare the commit, and return the
    * FetchResult plus the NavigationState and the commit thunk.
    *
    * The thunk is handed *through* to NavigationRoot rather than called here:
-   * state management (segmentCache, navState, historyStack) has to happen on
+   * state management (segment cache, history stack, address bar) has to happen on
    * the far side of the supersession check, which only NavigationRoot can
-   * make (TIM-1301). The fallback path below has no transition to be
-   * superseded by, so it commits directly.
+   * make (TIM-1301).
    */
   async function renderViaTransition(
     url: string,
@@ -245,84 +200,70 @@ export function createNavigationPipeline({
       commit();
     };
 
-    if (deps.navigateTransition) {
-      await deps.navigateTransition(
-        url,
-        owner,
-        async (wrapPayload) => {
-          const result = await perform();
-          // Await the payload's *root row* — the same thing React would suspend
-          // on to render the tree, and the first thing Flight emits. The
-          // previous UI stays on screen while this resolves: nothing has been
-          // handed to React yet, and when it is, NavigationRoot hands it over
-          // inside a transition so a tree that is still streaming does not
-          // displace the departing page (TIM-1306).
-          //
-          // Reading them here rather than with `use()` above the tree is what
-          // keeps a decode failure contained: `result.params` never rejects, so
-          // the rejection reaches React only through the tree, inside whatever
-          // error boundary the app put around it (TIM-1297).
-          const params = await result.params;
+    await deps.navigateTransition(
+      url,
+      owner,
+      async (wrapPayload) => {
+        const result = await perform();
+        // Await the payload's *root row* — the same thing React would suspend
+        // on to render the tree, and the first thing Flight emits. The
+        // previous UI stays on screen while this resolves: nothing has been
+        // handed to React yet, and when it is, NavigationRoot hands it over
+        // inside a transition so a tree that is still streaming does not
+        // displace the departing page (TIM-1306).
+        //
+        // Reading them here rather than with `use()` above the tree is what
+        // keeps a decode failure contained: `result.params` never rejects, so
+        // it can never take down the provider above every error boundary
+        // (TIM-1297). A failure after the root row reaches React through the
+        // tree, inside whatever boundary the app put around it.
+        const params = await result.params;
+        // And the tree itself — settled by the same root row, so this adds no
+        // wait, but it is the half that *rejects*: a root row that fails to
+        // decode fails this navigation here, before anything is wrapped or
+        // handed over, and the router takes its recovery path (TIM-1541).
+        // This used to happen by accident — the payload went through an
+        // `async` identity helper whose return adopted the thenable — and
+        // only on the paths that called it.
+        const payload = await result.payload;
 
-          if (isPartialNavigation(result.skippedSegments)) {
-            const segmentUpdates = buildSegmentUpdates(result);
+        if (isPartialNavigation(result.skippedSegments)) {
+          const segmentUpdates = buildSegmentUpdates(result, payload);
 
-            // Re-wrap the CURRENT element with new context values.
-            // SegmentOutlets read updates from SegmentUpdateContext;
-            // NavigationProvider gets the new pathname; the params published
-            // above the retained tree are the *incoming* route's.
-            const element = wrapPayload(
-              deps._getCurrentPayload?.() ?? result.payload,
-              result.navState,
-              params,
-              segmentUpdates
-            );
-            handOff();
-            return {
-              element,
-              decodePromise: observeSkew(result.decodePromise),
-              commit: commitAndForget(result.commit),
-            };
-          }
-
-          // Full navigation — empty updates, render the new tree.
-          const element = wrapPayload(result.payload, result.navState, params);
+          // Re-wrap the CURRENT element with new context values.
+          // SegmentOutlets read updates from SegmentUpdateContext;
+          // NavigationProvider gets the new pathname; the params published
+          // above the retained tree are the *incoming* route's.
+          const element = wrapPayload(
+            deps._getCurrentPayload?.() ?? payload,
+            result.navState,
+            params,
+            segmentUpdates
+          );
           handOff();
           return {
             element,
             decodePromise: observeSkew(result.decodePromise),
             commit: commitAndForget(result.commit),
           };
-        },
-        onCommit
-      );
-      return;
-    }
-    // Fallback: no transition (tests, no React tree). The commit is
-    // synchronous here, so the outcome is always 'committed' or 'failed' —
-    // no transition counter to supersede. The hook fires on the way out,
-    // on failure too, so it still fires exactly once.
-    let fallbackOutcome: CommitOutcome = 'committed';
-    try {
-      const result = await perform();
-      handOff();
-      const commit = commitAndForget(result.commit);
-      if (isPartialNavigation(result.skippedSegments)) {
-        commit();
-      } else {
-        renderPayload(result.payload, result.navState, await result.params, commit);
-      }
-    } catch (error) {
-      fallbackOutcome = 'failed';
-      throw error;
-    } finally {
-      onCommit?.(fallbackOutcome);
-    }
+        }
+
+        // Full navigation — empty updates, render the new tree.
+        const element = wrapPayload(payload, result.navState, params);
+        handOff();
+        return {
+          element,
+          decodePromise: observeSkew(result.decodePromise),
+          commit: commitAndForget(result.commit),
+        };
+      },
+      onCommit
+    );
   }
 
   /**
-   * Core navigation logic shared between the transition and fallback paths.
-   * Fetches the RSC payload, updates all state, and returns the result.
+   * Fetch (or take from the prefetch cache) a navigation's payload and
+   * prepare — without publishing — the commit that makes it current.
    */
   async function performNavigationFetch(
     url: string,
@@ -468,9 +409,6 @@ export function createNavigationPipeline({
       deps.setRouterNavigating?.(false);
     };
 
-    // Resolve thenable payloads in the test path so popstate replay
-    // and renderPayload receive plain values (see resolveForFallback).
-    const payload = await resolveForFallback(result.payload);
     const params = await result.params;
 
     // Prepare the atomic navigation-state update. It is published by the
@@ -479,7 +417,7 @@ export function createNavigationPipeline({
     // `prepareNavigation`'s decision, made from `skippedSegments` and
     // `segmentInfo` (TIM-1432).
     const { navState, commit } = prepareNavigation(url, {
-      payload,
+      payload: result.payload,
       params,
       segmentInfo: result.segmentInfo,
       skippedSegments: result.skippedSegments,
@@ -496,7 +434,6 @@ export function createNavigationPipeline({
 
     return {
       ...result,
-      payload,
       params,
       navState,
       commit: () => {
@@ -513,5 +450,5 @@ export function createNavigationPipeline({
     };
   }
 
-  return { performNavigationFetch, renderViaTransition, renderPayload, resolveForFallback };
+  return { performNavigationFetch, renderViaTransition };
 }

package/src/client/router-types.ts

@@ -13,7 +13,6 @@ import type { NavigationState } from './navigation-context.ts';
 import type { ParamsSource } from '../shared/payload-root.ts';
 import type { SegmentInfo } from '../shared/segment-info.ts';
 import type { SegmentCache, PrefetchCache } from './segment-cache.ts';
-import type { HistoryStack } from './history.ts';
 import type { TransitionResult, CommitOutcome, RenderOwner } from './navigation-transition.ts';
 import type { NavigationEpoch } from './router-lifecycle.ts';
 
@@ -53,37 +52,13 @@ export interface NavigationOptions {
 }
 
 /**
- * Function that decodes an RSC Flight stream into a React element tree.
- * In production: createFromFetch from @vitejs/plugin-rsc/browser.
- * In tests: a mock that returns the raw payload.
+ * Function that decodes an RSC Flight stream into the payload root.
+ * In production: createFromFetch from @vitejs/plugin-rsc/browser. Tests use
+ * the same Flight client over Flight bytes (tests/helpers/router-harness.ts),
+ * so every response is classified and decoded by the one path production runs.
  */
 export type RscDecoder = (fetchPromise: Promise<Response>) => unknown;
 
-/**
- * Function that renders a decoded RSC element tree into the DOM.
- * In production: reactRoot.render(element).
- * In tests: a no-op or mock.
- *
- * Receives the current NavigationState explicitly — no temporal
- * coupling with setNavigationState/getNavigationState. The renderer
- * wraps the element in NavigationProvider with this state.
- */
-export type RootRenderer = (
-  element: unknown,
-  navState: NavigationState,
-  params: ParamsSource,
-  /**
-   * Publishes the state that makes this tree the current page (segment
-   * cache, pathname, history stack, address bar). The renderer runs it when
-   * the tree is on screen — in production from React's commit of the tree
-   * (`NavigationRoot`'s layout effect), a test double synchronously. It is not run before
-   * handing the tree over: a replay or revalidation whose tree suspends is
-   * given to React without being on screen, and publishing then advertises
-   * slot content keys the slot content cache has not recorded (TIM-1423).
-   */
-  commit: () => void
-) => void;
-
 /**
  * Platform dependencies injected for testability. In production these
  * map to browser APIs; in tests they're replaced with mocks.
@@ -95,10 +70,8 @@ export interface RouterDeps {
   scrollTo: (x: number, y: number) => void;
   getCurrentUrl: () => string;
   getScrollY: () => number;
-  /** Decode RSC Flight stream into React elements. If not provided, raw response text is stored. */
-  decodeRsc?: RscDecoder;
-  /** Render decoded RSC tree into the DOM. If not provided, rendering is a no-op. */
-  renderRoot?: RootRenderer;
+  /** Decode an RSC Flight stream into the payload root. */
+  decodeRsc: RscDecoder;
   /**
    * Schedule a callback after the next paint. In the browser, this is
    * requestAnimationFrame + setTimeout(0) to run after React commits.
@@ -114,12 +87,14 @@ export interface RouterDeps {
    * The `perform` callback receives a `wrapPayload` function to wrap the
    * decoded RSC payload with NavigationProvider + NuqsAdapter before
    * NavigationRoot sets it as the new element. The `wrapPayload` function
-   * receives the NavigationState explicitly — no temporal coupling with
-   * getNavigationState().
+   * receives the NavigationState explicitly — there is no store to read it
+   * from.
    *
-   * If not provided (tests), the router falls back to renderRoot.
+   * Every render goes through here — a navigation, a refresh, a traversal
+   * (fetched or replayed) and a server action's revalidation — so each one
+   * gets the same handover, commit and supersession.
    */
-  navigateTransition?: (
+  navigateTransition: (
     pendingUrl: string,
     owner: RenderOwner,
     perform: (
@@ -225,6 +200,14 @@ export interface RouterInstance {
    * Hand the epoch back to `applyActionResult` with the response (TIM-1474).
    */
   epoch(): NavigationEpoch;
+  /**
+   * True when no navigation has started since `epoch` was taken and the
+   * router was idle then and is idle now — the same test
+   * `applyActionResult` applies. Action branches that never reach
+   * `applyActionResult` use it to detect a navigation that ran while the
+   * action was in flight and may have rendered pre-mutation data (TIM-1483).
+   */
+  isEpochCurrent(epoch: NavigationEpoch): boolean;
   /**
    * Reconcile the page after a server action. `tree` is the piggybacked
    * revalidation payload root, or `undefined` when the server sent none.
@@ -264,22 +247,41 @@ export interface RouterInstance {
    * affect any route's data, not just the paths the server named, so every
    * cached payload is stale. In-flight prefetch singleflights are fenced
    * by the eviction generation — their results are discarded if they
-   * complete after eviction. The current URL's history entry is preserved
-   * so `applyActionResult` can read its segment metadata.
+   * complete after eviction. `applyActionResult` does not need the history
+   * stack: the current page's segment metadata is the committer's record.
    */
   evictStaleCaches(): void;
   /**
-   * Populate the segment cache from server-provided segment metadata.
-   * Called on initial hydration with segment info embedded in the HTML.
+   * Make the server-rendered page the current page — the hydration entry
+   * point, and the only one: bootstrap does not reach into the router's
+   * caches. Returns the `NavigationState` the page renders with.
+   *
+   * Goes through the same `prepareNavigation` every navigation uses, and
+   * commits at once rather than on React's hydration commit. The server's
+   * HTML is already the page on screen, and React does not promise that
+   * commit: a render that reaches the root while hydration is suspended (a
+   * shallow search update, a navigation the Navigation API intercepted
+   * before hydration) switches the root to client rendering, and the
+   * hydration tree — with any publish attached to it — never commits. A
+   * status document is still kept out of the cache: its `StatusPageMarker`
+   * clears the cache when it reports (navigation-commit.ts).
    */
-  initSegmentCache(segments: SegmentInfo[]): void;
+  hydrate(page: HydrationPage): NavigationState;
 
   /** The segment cache (exposed for tests and <Link> prefetch) */
   segmentCache: SegmentCache;
   /** The prefetch cache (exposed for tests and <Link> prefetch) */
   prefetchCache: PrefetchCache;
-  /** The history stack (exposed for tests) */
-  historyStack: HistoryStack;
+}
+
+/** The page the server rendered, as the browser entry decoded it. */
+export interface HydrationPage {
+  /** The inlined payload's tree, or null when the document carried none. */
+  payload: unknown;
+  /** The params published beside it. */
+  params: ParamsSource;
+  /** The rendered chain's metadata (`self.__timber_segments`), or null. */
+  segmentInfo: SegmentInfo[] | null;
 }
 
 /**

package/src/client/router-url.ts

@@ -0,0 +1,32 @@
+/**
+ * How the client router reads the URLs it is handed.
+ *
+ * One parser, so the places that key or compare by URL — the history stack,
+ * the navigation state a page renders with, the departing page sent as
+ * `X-Timber-URL` — cannot disagree about what a URL says. They did: a
+ * history entry stored under `navigate('/café')`'s spelling was looked up
+ * under the address bar's `/caf%C3%A9`, and missed (TIM-1541).
+ */
+
+const BASE = 'http://localhost';
+
+/**
+ * Parse a router URL. A URL that starts with "/" is a path — including one
+ * that starts with "//": that is the pathname a document at
+ * `https://host//a/b` reports, and resolved against a base it would parse as
+ * a scheme-relative reference to host `a`. Anything else resolves against a
+ * placeholder origin, so an absolute URL keeps its own.
+ */
+export function parseRouterUrl(url: string): URL {
+  return url.startsWith('/') ? new URL(BASE + url) : new URL(url, BASE);
+}
+
+/**
+ * The spelling a URL is stored and looked up under: the browser's own
+ * pathname + search, so `/a?` and `/a`, `/café` and `/caf%C3%A9`, are one
+ * key. The fragment is dropped — it is client-only.
+ */
+export function routerUrlKey(url: string): string {
+  const parsed = parseRouterUrl(url);
+  return parsed.pathname + parsed.search;
+}

package/src/client/router.ts

@@ -12,7 +12,6 @@
 // See design/19-client-navigation.md for the full architecture.
 
 import { SegmentCache, PrefetchCache } from './segment-cache.ts';
-import type { SegmentInfo } from '../shared/segment-info.ts';
 import { HistoryStack } from './history.ts';
 import { createNavigationCommitter } from './navigation-commit.ts';
 
@@ -42,7 +41,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
   const {
     prepareNavigation,
     currentStateTree,
-    updateSegmentCache,
+    committedSegmentInfo,
     isSegmentReuseSuppressed,
     restoreSegmentReuse,
   } = createNavigationCommitter({
@@ -66,17 +65,16 @@ export function createRouter(deps: RouterDeps): RouterInstance {
   } = lifecycle;
 
   // Fetch → commit → hand to React. See router-pipeline.ts.
-  const { performNavigationFetch, renderViaTransition, resolveForFallback } =
-    createNavigationPipeline({
-      deps,
-      prefetchCache,
-      currentStateTree,
-      prepareNavigation,
-      isSegmentReuseSuppressed,
-      restoreSegmentReuse,
-      markHandedOff,
-      forgetOlderHandoffs,
-    });
+  const { performNavigationFetch, renderViaTransition } = createNavigationPipeline({
+    deps,
+    prefetchCache,
+    currentStateTree,
+    prepareNavigation,
+    isSegmentReuseSuppressed,
+    restoreSegmentReuse,
+    markHandedOff,
+    forgetOlderHandoffs,
+  });
 
   // Post-paint scroll effects.
   const { restoreScrollAfterPaint, scrollToHashAfterPaint } = createScrollEffects(deps);
@@ -231,15 +229,14 @@ export function createRouter(deps: RouterDeps): RouterInstance {
                 undefined,
                 owner.fetchAbort.signal
               );
-              const payload = await resolveForFallback(result.payload);
               const params = await result.params;
               const { navState, commit } = prepareNavigation(url, {
-                payload,
+                payload: result.payload,
                 params,
                 segmentInfo: result.segmentInfo,
                 skippedSegments: result.skippedSegments,
               });
-              return { ...result, payload, params, navState, commit };
+              return { ...result, params, navState, commit };
             },
             opts.onCommit
           );
@@ -436,6 +433,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     onPendingChange,
     prefetch,
     epoch: () => lifecycle.epoch(),
+    isEpochCurrent: (epoch) => lifecycle.isEpochCurrent(epoch),
 
     async applyActionResult(epoch, tree) {
       if (!lifecycle.isEpochCurrent(epoch)) return false;
@@ -461,7 +459,12 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       const currentUrl = deps.getCurrentUrl();
       const payloadTree = readPayloadTree(tree);
       const params = readPublishedParams(tree);
-      const existingEntry = historyStack.get(currentUrl);
+      // The response carries no segment metadata; the page it re-renders is
+      // the one the last commit made current, and the committer kept that
+      // page's. Not a history-stack lookup by `currentUrl`: the stack is keyed
+      // by the spelling `navigate()` was given, which need not be
+      // `window.location`'s (TIM-1541).
+      const segmentInfo = committedSegmentInfo();
 
       let outcomeResolve!: (o: CommitOutcome) => void;
       const outcomePromise = new Promise<CommitOutcome>((r) => (outcomeResolve = r));
@@ -479,7 +482,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
             const { navState, commit } = prepareNavigation(currentUrl, {
               payload: payloadTree,
               params,
-              segmentInfo: existingEntry?.segmentInfo,
+              segmentInfo,
             });
             return {
               payload: payloadTree,
@@ -487,7 +490,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
               navState,
               commit,
               decodePromise: null,
-              segmentInfo: existingEntry?.segmentInfo ?? null,
+              segmentInfo,
               skippedSegments: null,
             };
           },
@@ -517,11 +520,29 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     },
     evictStaleCaches(): void {
       prefetchCache.clearReady();
-      historyStack.clearExcept(deps.getCurrentUrl());
+      historyStack.clear();
+    },
+    hydrate(page) {
+      // Where hydration seeds the current page: the same prepare-and-commit
+      // every navigation goes through, so the segment cache, the committed
+      // segment metadata and the history entry are written by one commit
+      // rather than by bootstrap reaching into each (TIM-1541). Committed
+      // here, at once — see `RouterInstance.hydrate` for why not on React's
+      // hydration commit.
+      //
+      // Replaying this entry on a Back re-renders `payload` and republishes
+      // `params`. Both came out of one split of one decoded payload root
+      // (rsc-stream.ts), so the entry cannot replay with another route's
+      // params (TIM-1037, TIM-1285).
+      const { navState, commit } = prepareNavigation(deps.getCurrentUrl(), {
+        payload: page.payload,
+        params: page.params,
+        segmentInfo: page.segmentInfo,
+      });
+      commit();
+      return navState;
     },
-    initSegmentCache: (segments: SegmentInfo[]) => updateSegmentCache(segments),
     segmentCache,
     prefetchCache,
-    historyStack,
   };
 }