@timber-js/app 0.2.0-alpha.207 → 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';
 
 /**
@@ -60,7 +61,7 @@ export interface NavigationFetchOptions {
 
 export interface NavigationPipelineDeps extends Pick<
   NavigationCommitter,
-  'prepareNavigation' | 'currentStateTree'
+  'prepareNavigation' | 'currentStateTree' | 'isSegmentReuseSuppressed' | 'restoreSegmentReuse'
 > {
   deps: RouterDeps;
   prefetchCache: PrefetchCache;
@@ -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;
       }
     }
@@ -174,54 +166,19 @@ export function createNavigationPipeline({
   prefetchCache,
   currentStateTree,
   prepareNavigation,
+  isSegmentReuseSuppressed,
+  restoreSegmentReuse,
   markHandedOff,
   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,
@@ -243,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,
@@ -339,6 +282,11 @@ export function createNavigationPipeline({
     // `currentUrl` is read back off the key rather than computed beside it, so
     // the pathname sent as X-Timber-URL is the one the lookup used.
     const stateTree = currentStateTree();
+    // Capture whether reuse is suppressed at the time we build the state
+    // tree. If so, segments/slots are empty and the server will send a
+    // full render. We restore reuse after the response is processed so
+    // only navigations that fetched with suppression can lift it (TIM-1466).
+    let reuseSuppressedAtFetch = isSegmentReuseSuppressed();
     const cacheKey = prefetchKeyFor(url, options.departingUrl ?? deps.getCurrentUrl(), stateTree);
     const currentUrl = cacheKey.from;
 
@@ -381,11 +329,16 @@ export function createNavigationPipeline({
         // Capture the eviction generation before awaiting the flight.
         // If an action evicts caches while we wait, the result predates
         // the mutation and must be discarded (TIM-1476, codex on #1131).
+        // Also check the flight's own starting gen: if the flight started
+        // before a per-URL invalidation (TIM-1464), a joiner that arrived
+        // after the bump would see genBefore === genAfter but the flight
+        // still predates the invalidation.
         const genBefore = prefetchCache.getEvictionGen();
         try {
           const outcome = await raceAbort(inflight, options.signal);
-          if (prefetchCache.getEvictionGen() !== genBefore) {
-            // Eviction happened while we waited — discard stale result,
+          if (prefetchCache.getEvictionGen() !== genBefore || outcome.startGen !== genBefore) {
+            // Eviction happened while we waited, or the flight predates
+            // an invalidation we arrived after — discard stale result,
             // fall through to a fresh fetch below.
           } else if (outcome.kind === 'non-route') {
             throw new NonRscResponse(url);
@@ -422,7 +375,13 @@ export function createNavigationPipeline({
       // No in-flight hover prefetch, or the joined flight failed — fetch
       // directly with the navigation's signal so superseded navigations
       // abort immediately.
-      result = await fetchRscPayload(url, deps, stateTree, currentUrl, options.signal);
+      // Resample both the state tree and the suppression flag: if we fell
+      // through because an invalidation bumped the eviction gen,
+      // invalidateReuse() has suppressed segment/slot reuse since our
+      // original capture (TIM-1466, codex on #1167).
+      reuseSuppressedAtFetch = isSegmentReuseSuppressed();
+      const freshStateTree = currentStateTree();
+      result = await fetchRscPayload(url, deps, freshStateTree, currentUrl, options.signal);
     }
 
     // Update the browser history — skip when the Navigation API has already
@@ -450,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
@@ -461,15 +417,23 @@ 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,
     });
 
+    // This navigation's fetch used the suppressed state tree (empty
+    // segments/slots), so the server sent a full render. The response
+    // data is post-invalidation — safe to restore reuse for subsequent
+    // navigations. Must happen here (at response time, before the commit
+    // thunk), not in set(), because a pre-invalidation navigation's
+    // commit thunk also calls set() and would lift suppression too early
+    // (codex on #1167).
+    if (reuseSuppressedAtFetch) restoreSegmentReuse();
+
     return {
       ...result,
-      payload,
       params,
       navState,
       commit: () => {
@@ -486,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;
+}