@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.210

package/src/client/router-pipeline.ts

@@ -0,0 +1,458 @@
+/**
+ * Navigation Pipeline — URL in, tree in React's hands.
+ *
+ * Everything between "the user asked for this URL" and "React is holding the
+ * destination's tree": consult the prefetch cache or fetch, prepare the commit
+ * that makes the page current, and hand the result over inside a transition.
+ *
+ * `router.ts` keeps the *operations* — `navigate`, `refresh`, `handlePopState`,
+ * `prefetch`, `applyActionResult` — and each of them is a call into here. The
+ * split is the same one `router-effects.ts` and `router-lifecycle.ts` made
+ * (design/18-build-system.md §"No file >500 lines").
+ *
+ * See design/19-client-navigation.md §"Partial Rendering" and §"Prefetching".
+ */
+
+import { fetchRscPayload, NonRscResponse } from './rsc-fetch.ts';
+import type { FetchResult } from './rsc-fetch.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';
+import { isPartialNavigation, type NavigationCommitter } from './navigation-commit.ts';
+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';
+
+/**
+ * Race a promise against an abort signal. The promise continues regardless —
+ * only the *await* gives up. Used so a click superseded by a newer navigation
+ * stops waiting for a shared prefetch flight without aborting the flight
+ * itself (TIM-1438).
+ */
+function raceAbort<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T> {
+  if (!signal) return promise;
+  if (signal.aborted) return Promise.reject(signal.reason);
+  return Promise.race([
+    promise,
+    new Promise<never>((_, reject) => {
+      signal.addEventListener('abort', () => reject(signal.reason), { once: true });
+    }),
+  ]);
+}
+
+/** A fetched payload plus the state update that makes it the current page. */
+export type NavigationPayload = FetchResult & {
+  navState: NavigationState;
+  commit: () => void;
+};
+
+/** Options for a single `performNavigationFetch` call. */
+export interface NavigationFetchOptions {
+  replace: boolean;
+  commitUrl?: string;
+  signal?: AbortSignal;
+  skipHistory?: boolean;
+  departingUrl?: string;
+}
+
+export interface NavigationPipelineDeps extends Pick<
+  NavigationCommitter,
+  'prepareNavigation' | 'currentStateTree' | 'isSegmentReuseSuppressed' | 'restoreSegmentReuse'
+> {
+  deps: RouterDeps;
+  prefetchCache: PrefetchCache;
+  /** Record that this navigation's tree reached React (router-lifecycle.ts). */
+  markHandedOff: (owner: RenderOwner) => void;
+  /** React committed this navigation's tree (router-lifecycle.ts). */
+  forgetOlderHandoffs: (owner: RenderOwner) => void;
+}
+
+export interface NavigationPipeline {
+  /** Fetch (or replay a prefetch), then stage the commit. */
+  performNavigationFetch: (
+    url: string,
+    options: NavigationFetchOptions
+  ) => Promise<NavigationPayload>;
+  /** Hand a payload to React inside a transition. */
+  renderViaTransition: (
+    url: string,
+    owner: RenderOwner,
+    /** The view transition types the render adds (`NavigationRender`). */
+    types: readonly string[],
+    perform: () => Promise<NavigationPayload>,
+    /** See `NavigationOptions.onCommit`. */
+    onCommit?: (outcome: CommitOutcome) => void
+  ) => Promise<void>;
+}
+
+/**
+ * Normalize a departing URL to the pathname the server is told about.
+ *
+ * This is the value sent as `X-Timber-URL` *and* the source half of the
+ * prefetch cache key — one function so a prefetch and the click that consumes
+ * it can never disagree about what "where we came from" means (TIM-1265). The
+ * query is dropped deliberately: it would land in the `_rsc` digest, which is
+ * logged (TIM-1268), and nothing downstream reads it — slot-skip resolution
+ * and interception scope both compare pathnames.
+ *
+ * Absolute inputs parse against the base and ignore it, so one call handles
+ * both `location.href` and a bare pathname.
+ */
+export function departingPathname(raw: string): string {
+  return parseRouterUrl(raw).pathname;
+}
+
+/**
+ * The prefetch cache key for a destination.
+ *
+ * Both halves of the cache are keyed through here — the hover that writes an
+ * entry (`router.ts`'s `prefetch()`) and the click that consumes it
+ * (`performNavigationFetch` below) — so the two cannot disagree about what
+ * identifies a payload. That is the whole point of the key: `from` scopes it
+ * to the page the link was on (TIM-1265) and `scope` to the tree that was
+ * mounted (TIM-1282), and an entry written under one reading of either would
+ * simply never be found under the other, silently costing every prefetch.
+ *
+ * `departingPathname` is applied here rather than by callers for the same
+ * reason: it is also what goes out as `X-Timber-URL`, so the key and the
+ * request describe the same departure point.
+ */
+export function prefetchKeyFor(
+  url: string,
+  departingUrl: string,
+  stateTree: StateTree | undefined
+): PrefetchKey {
+  return { url, from: departingPathname(departingUrl), scope: prefetchScopeOf(stateTree) };
+}
+
+/**
+ * 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, 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, payload);
+        break;
+      }
+    }
+  }
+  return updates;
+}
+
+/**
+ * Inspect a decode rejection for version skew before handing the promise on,
+ * without changing what the consumer sees.
+ *
+ * The decode rejects independently of the fetch, and not every consumer
+ * awaits it — NavigationRoot drops it outright when the transition has been
+ * superseded. A stale client reference arriving that way is still evidence
+ * the bundle is superseded, so record it here where every consumer is fed
+ * from, rather than at each place that might drop it (TIM-1275).
+ */
+function observeSkew(decodePromise: Promise<void> | null): Promise<void> | null {
+  decodePromise?.catch((error: unknown) => void recordSkew(error));
+  return decodePromise;
+}
+
+export function createNavigationPipeline({
+  deps,
+  prefetchCache,
+  currentStateTree,
+  prepareNavigation,
+  isSegmentReuseSuppressed,
+  restoreSegmentReuse,
+  markHandedOff,
+  forgetOlderHandoffs,
+}: NavigationPipelineDeps): NavigationPipeline {
+  /**
+   * 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 (segment cache, history stack, address bar) has to happen on
+   * the far side of the supersession check, which only NavigationRoot can
+   * make (TIM-1301).
+   */
+  async function renderViaTransition(
+    url: string,
+    owner: RenderOwner,
+    types: readonly string[],
+    perform: () => Promise<NavigationPayload>,
+    onCommit?: (outcome: CommitOutcome) => void
+  ): Promise<void> {
+    // Record that THIS navigation's payload has reached React, at the moment
+    // the tree is built and handed back for `navigateTransition` to give to
+    // React — NOT on commit, which is a whole commit phase too late. See
+    // `RenderOwner.handedOff` in router-lifecycle.ts.
+    const handOff = (): void => markHandedOff(owner);
+
+    // Settle the owner as committed once React has committed this tree.
+    // Wrapped around the commit thunk so it runs on React's commit and not
+    // at handover; see `forgetOlderHandoffs`.
+    const commitAndForget = (commit: () => void) => (): void => {
+      forgetOlderHandoffs(owner);
+      commit();
+    };
+
+    await deps.navigateTransition(
+      url,
+      owner,
+      types,
+      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, 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?.() ?? 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(payload, result.navState, params);
+        handOff();
+        return {
+          element,
+          decodePromise: observeSkew(result.decodePromise),
+          commit: commitAndForget(result.commit),
+        };
+      },
+      onCommit
+    );
+  }
+
+  /**
+   * 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,
+    options: NavigationFetchOptions
+  ): Promise<NavigationPayload> {
+    // Both halves of the key are sampled here, before the prefetch cache is
+    // consulted, and both are reused for the request itself:
+    //
+    // - the departing page, because an entry fetched from somewhere else
+    //   answers a different question (TIM-1265). `getCurrentUrl()` can't be
+    //   read any later either — the Navigation API may have already committed
+    //   the destination URL (TIM-1232).
+    // - the mounted tree, so the entry this navigation looks up is keyed by
+    //   the same scope the fetch would have been issued with (TIM-1282).
+    //
+    // `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;
+
+    // Check prefetch cache first. A negative entry means a prior prefetch
+    // determined this URL is not a route (non-RSC Content-Type). Hard-navigate
+    // immediately without a second fetch. See TIM-1231.
+    if (prefetchCache.isNegative(cacheKey)) {
+      prefetchCache.consume(cacheKey);
+      throw new NonRscResponse(url);
+    }
+
+    // PrefetchResult has optional segmentInfo/params fields — normalize
+    // to null for FetchResult compatibility.
+    const prefetched = prefetchCache.consume(cacheKey);
+    let result: FetchResult | undefined = prefetched
+      ? {
+          payload: prefetched.payload,
+          // A prefetch that predates this field (or the negative-entry
+          // sentinel) publishes nothing rather than the previous route's.
+          params: prefetched.params ?? readPublishedParams(undefined),
+          // Carry the prefetch's stream completion through. It may still be
+          // decoding, and a stale client reference arriving after the click
+          // must reach *this* navigation's recovery rather than dying with
+          // the prefetch that started it (TIM-1275).
+          decodePromise: prefetched.decodePromise ?? null,
+          segmentInfo: prefetched.segmentInfo ?? null,
+          skippedSegments: prefetched.skippedSegments ?? null,
+        }
+      : undefined;
+
+    // If a hover prefetch is in-flight, join it instead of issuing a
+    // duplicate (TIM-1438). The click races its await against its own signal
+    // so a superseded navigation gives up immediately — the shared flight
+    // continues for other consumers. On flight failure (network error,
+    // singleflight timeout), fall through to a fresh fetch — the failed
+    // hover should not block a click that might succeed.
+    if (result === undefined) {
+      const inflight = prefetchCache.joinInflight(cacheKey);
+      if (inflight) {
+        // 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 || 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);
+          } else {
+            // Consume the ready entry so a second click re-fetches
+            prefetchCache.consume(cacheKey);
+            result = {
+              payload: outcome.result.payload,
+              params: outcome.result.params ?? readPublishedParams(undefined),
+              decodePromise: outcome.result.decodePromise ?? null,
+              segmentInfo: outcome.result.segmentInfo ?? null,
+              skippedSegments: outcome.result.skippedSegments ?? null,
+            };
+          }
+        } catch (error) {
+          // Supersession aborts propagate — don't retry a cancelled navigation
+          if (error instanceof DOMException && error.name === 'AbortError') throw error;
+          if (options.signal?.aborted) throw options.signal.reason;
+          // Retriable failures fall through to a fresh fetch: singleflight
+          // timeout (hover hung) and transport TypeError (transient network
+          // error). Framework control-flow errors — NonRscResponse,
+          // VersionSkewError, RedirectError, ServerErrorResponse — are
+          // definitive server answers and must reach navigate's recovery.
+          if (error instanceof SingleflightTimeoutError || error instanceof TypeError) {
+            // fall through to fresh fetch below
+          } else {
+            throw error;
+          }
+        }
+      }
+    }
+
+    if (result === undefined) {
+      // No in-flight hover prefetch, or the joined flight failed — fetch
+      // directly with the navigation's signal so superseded navigations
+      // abort immediately.
+      // 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
+    // updated the URL via event.intercept() (external navigations).
+    // The committed URL keeps the #fragment (commitUrl) even though the
+    // fetch/history-stack URL is hash-less (TIM-1035).
+    //
+    // Deferred with the rest of the commit: the address bar is navigation
+    // state like the segment cache and the history stack, and a superseded
+    // navigation must not move it either. That guarantee used to hold only
+    // because the superseded fetch was aborted before it got here — a
+    // response that won the race anyway re-pushed the abandoned URL
+    // (TIM-1022's failure mode, made unconditional by TIM-1301).
+    const commitHistoryUrl = (): void => {
+      if (options.skipHistory) return;
+      const commitUrl = options.commitUrl ?? url;
+      // Set the router-navigating flag so the Navigation API's navigate
+      // listener doesn't double-intercept this pushState/replaceState.
+      deps.setRouterNavigating?.(true);
+      if (options.replace) {
+        deps.replaceState({ timber: true, scrollY: 0 }, '', commitUrl);
+      } else {
+        deps.pushState({ timber: true, scrollY: 0 }, '', commitUrl);
+      }
+      deps.setRouterNavigating?.(false);
+    };
+
+    const params = await result.params;
+
+    // Prepare the atomic navigation-state update. It is published by the
+    // caller once this navigation is known to have won (TIM-1301). Whether
+    // the payload is stored for replay — not when it has skip holes — is
+    // `prepareNavigation`'s decision, made from `skippedSegments` and
+    // `segmentInfo` (TIM-1432).
+    const { navState, commit } = prepareNavigation(url, {
+      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,
+      params,
+      navState,
+      commit: () => {
+        commitHistoryUrl();
+        commit();
+        // Notify nuqs (and any other listener) that the URL is now the
+        // destination's. It travels *inside* the commit rather than after
+        // the navigation resolves because the listener answers it by reading
+        // `window.location.search`, and the commit is what moves it — the
+        // publish happens on React's commit of the tree, which can land after
+        // the navigation promise settles (TIM-1301, codex on #998).
+        window.dispatchEvent(new Event('timber:navigation-end'));
+      },
+    };
+  }
+
+  return { performNavigationFetch, renderViaTransition };
+}

package/src/client/router-ref.ts

@@ -6,8 +6,8 @@
 //
 // See design/18-build-system.md §"Module Singleton Strategy"
 
-import type { RouterInstance } from './router.js';
-import { globalRouter, _setGlobalRouter } from './state.js';
+import type { RouterInstance } from './router-types.ts';
+import { globalRouter, _setGlobalRouter } from './state.ts';
 
 /**
  * Set the global router instance. Called once during bootstrap.
@@ -18,7 +18,7 @@ export function setGlobalRouter(router: RouterInstance): void {
 
 /**
  * Get the global router instance. Throws if called before bootstrap.
- * Used by client-side hooks (useNavigationPending, etc.)
+ * Used by client-side hooks (usePendingNavigation, etc.)
  */
 export function getRouter(): RouterInstance {
   if (!globalRouter) {

package/src/client/router-skew.ts

@@ -0,0 +1,30 @@
+/**
+ * Router Skew Recording — turning a rejection into "this bundle is superseded".
+ *
+ * Detection lives in `stale-client.ts`; this is the one place the router (and
+ * anything else holding an RSC rejection) turns an error into that verdict.
+ * Recovery is not here: every path that gives up on client-side navigation —
+ * skew or not — leaves through `createSpaExits()` in `router-effects.ts`.
+ *
+ * See design/33-version-skew.md §"Recovery on the next navigation"
+ */
+
+import { VersionSkewError } from './rsc-fetch.ts';
+import { markClientStale, markStaleFromError } from './stale-client.ts';
+
+/**
+ * Record a version skew if `error` is one, and report whether it was.
+ *
+ * `VersionSkewError` is the origin saying so outright; the reactive shapes are
+ * inferred from the error text and are a no-op in dev.
+ *
+ * Closes over nothing — anywhere an RSC payload can fail needs it, including
+ * places that have no router instance to hand.
+ */
+export function recordSkew(error: unknown): boolean {
+  if (error instanceof VersionSkewError) {
+    markClientStale();
+    return true;
+  }
+  return markStaleFromError(error);
+}