@timber-js/app 0.2.0-alpha.20 → 0.2.0-alpha.201

package/src/client/router-pipeline.ts

@@ -0,0 +1,490 @@
+/**
+ * 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, type ParamsSource } from '../shared/payload-root.ts';
+import type { PrefetchCache, PrefetchKey, FlightOutcome } 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 { 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'
+> {
+  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, or render it directly in tests. */
+  renderViaTransition: (
+    url: string,
+    owner: RenderOwner,
+    perform: () => Promise<NavigationPayload>,
+    /** 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>;
+}
+
+/**
+ * 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 new URL(raw, 'http://localhost').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): 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);
+        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,
+  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
+   * 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
+   * 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.
+   */
+  async function renderViaTransition(
+    url: string,
+    owner: RenderOwner,
+    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();
+    };
+
+    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;
+
+          if (isPartialNavigation(result.skippedSegments)) {
+            const segmentUpdates = buildSegmentUpdates(result);
+
+            // 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);
+          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);
+    }
+  }
+
+  /**
+   * Core navigation logic shared between the transition and fallback paths.
+   * Fetches the RSC payload, updates all state, and returns the result.
+   */
+  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();
+    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).
+        const genBefore = prefetchCache.getEvictionGen();
+        try {
+          const outcome = await raceAbort(inflight, options.signal);
+          if (prefetchCache.getEvictionGen() !== genBefore) {
+            // Eviction happened while we waited — 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.
+      result = await fetchRscPayload(url, deps, stateTree, 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);
+    };
+
+    // 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
+    // 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,
+      params,
+      segmentInfo: result.segmentInfo,
+      skippedSegments: result.skippedSegments,
+    });
+
+    return {
+      ...result,
+      payload,
+      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, renderPayload, resolveForFallback };
+}

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