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

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';
 
@@ -39,7 +38,13 @@ export function createRouter(deps: RouterDeps): RouterInstance {
 
   // Every write that makes a page "current", and the read that reports the
   // current page back to the server. See navigation-commit.ts.
-  const { prepareNavigation, currentStateTree, updateSegmentCache } = createNavigationCommitter({
+  const {
+    prepareNavigation,
+    currentStateTree,
+    committedSegmentInfo,
+    isSegmentReuseSuppressed,
+    restoreSegmentReuse,
+  } = createNavigationCommitter({
     segmentCache,
     historyStack,
     clientSegmentCache: () => deps.clientSegmentCache,
@@ -60,15 +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,
-      markHandedOff,
-      forgetOlderHandoffs,
-    });
+  const { performNavigationFetch, renderViaTransition } = createNavigationPipeline({
+    deps,
+    prefetchCache,
+    currentStateTree,
+    prepareNavigation,
+    isSegmentReuseSuppressed,
+    restoreSegmentReuse,
+    markHandedOff,
+    forgetOlderHandoffs,
+  });
 
   // Post-paint scroll effects.
   const { restoreScrollAfterPaint, scrollToHashAfterPaint } = createScrollEffects(deps);
@@ -223,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
           );
@@ -428,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;
@@ -453,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));
@@ -471,7 +482,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
             const { navState, commit } = prepareNavigation(currentUrl, {
               payload: payloadTree,
               params,
-              segmentInfo: existingEntry?.segmentInfo,
+              segmentInfo,
             });
             return {
               payload: payloadTree,
@@ -479,7 +490,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
               navState,
               commit,
               decodePromise: null,
-              segmentInfo: existingEntry?.segmentInfo ?? null,
+              segmentInfo,
               skippedSegments: null,
             };
           },
@@ -492,16 +503,46 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     runWhenIdle: (task: () => void) => lifecycle.runWhenIdle(task),
     settleHandoffs: () => lifecycle.settleHandoffs(),
     invalidatePath(path: string): void {
-      historyStack.delete(path);
+      const hasSearch = path.includes('?');
+      if (hasSearch) {
+        historyStack.delete(path);
+      } else {
+        // TIM-1465: evict all query variants sharing this pathname
+        historyStack.deleteByPathname(path);
+      }
       prefetchCache.invalidateUrl(path);
+      // TIM-1466: suppress segment/slot reuse so the next navigation
+      // gets a full render instead of reusing stale shared layouts.
+      // Uses invalidateReuse() instead of clear() to preserve treePaths
+      // for interception scoping — a modal mounted on the current tree
+      // must still be navigable (codex on #1167).
+      segmentCache.invalidateReuse();
     },
     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,
   };
 }

package/src/client/rsc-fetch.ts

@@ -18,11 +18,7 @@ import {
   RSC_KEY_PARAM,
 } from '../shared/rsc-cache-key.ts';
 import type { RscManifest, RscManifestEntry } from '../shared/rsc-manifest.ts';
-import {
-  splitPayloadRoot,
-  readPublishedParams,
-  type PublishedParams,
-} from '../shared/payload-root.ts';
+import { splitPayloadRoot, type PublishedParams } from '../shared/payload-root.ts';
 import { normalizeBasePath, stripBasePath, withBasePath } from '../shared/base-path.ts';
 import { rscPayloadPath } from '../shared/rsc-payload-path.ts';
 import type { SegmentInfo, StateTree } from '../shared/segment-info.ts';
@@ -401,7 +397,8 @@ export class VersionSkewError extends Error {
 /**
  * Thrown when the server returns an error for an RSC payload request.
  * The server sends X-Timber-Error header and a JSON body instead of a
- * broken RSC stream for any RenderError (4xx or 5xx). Caught in
+ * RSC stream it cannot answer in-SPA (a deny that needs a fallback page, a
+ * broken first read). Caught in
  * navigate() to trigger a hard navigation so the server can render
  * the error page as HTML.
  *
@@ -487,9 +484,12 @@ function trackStreamCompletion(body: ReadableStream<Uint8Array>): {
 // ─── Fetch ───────────────────────────────────────────────────────
 
 /**
- * Fetch an RSC payload from the server. If a decodeRsc function is provided,
- * the response is decoded into a React element tree via createFromFetch.
- * Otherwise, the raw response text is returned (test mode).
+ * Fetch an RSC payload from the server and start decoding it.
+ *
+ * Every response is classified here, once: a version-skew reload, a 204 or
+ * 3xx redirect, a server error envelope and a non-RSC body are each turned
+ * into their error before `decodeRsc` sees the body. There is no second
+ * path — tests decode real Flight bytes through the same code (TIM-1541).
  */
 export async function fetchRscPayload(
   url: string,
@@ -518,156 +518,118 @@ export async function fetchRscPayload(
   // during that window would otherwise still hit the network with an
   // already-aborted signal.
   signal?.throwIfAborted();
-  if (deps.decodeRsc) {
-    // Production path: use createFromFetch for streaming RSC decoding.
-    // createFromFetch takes a Promise<Response> and progressively parses
-    // the RSC Flight stream as chunks arrive.
-    //
-    // Intercept the response to read segment metadata before createFromFetch
-    // consumes the body. Reading headers does NOT consume the body stream.
-    const fetchPromise = deps.fetch(rscUrl, { headers, redirect: 'manual', signal });
-    let segmentInfo: SegmentInfo[] | null = null;
-    let skippedSegments: string[] | null = null;
-    // Track when the full RSC body stream is consumed (not just shell).
-    // Initialized to resolved for bodyless responses; overwritten when
-    // the response has a body.
-    let streamDone: Promise<void> = Promise.resolve();
-
-    const wrappedPromise = fetchPromise.then((response) => {
-      // Version skew detection (TIM-446): if the server signals a reload,
-      // throw VersionSkewError so the caller (router navigate) can trigger
-      // a full page reload.
-      if (checkReloadSignal(response)) {
-        throw new VersionSkewError();
-      }
-      // Detect server-side redirects. The server returns 204 + X-Timber-Redirect
-      // for RSC payload requests instead of a raw 302, because fetch with
-      // redirect: "manual" turns 302s into opaque redirects (status 0, null body)
-      // which crashes createFromFetch when it tries to read the body stream.
-      const redirectLocation =
-        response.headers.get('X-Timber-Redirect') ||
-        (response.status >= 300 && response.status < 400 ? response.headers.get('Location') : null);
-      if (redirectLocation) {
-        throw new RedirectError(redirectLocation);
-      }
-      // Detect server error responses. The server returns X-Timber-Error header
-      // with a JSON body instead of a broken RSC stream for any RenderError
-      // (4xx or 5xx). Hard-navigate so the server renders the error page as HTML.
-      // See design/10-error-handling.md §"Error Page Rendering for Client Navigation"
-      if (response.headers.get(TIMBER_ERROR_HEADER) === '1') {
-        throw new ServerErrorResponse(response.status, url);
-      }
-      // Content-Type guard: reject non-RSC responses before createFromFetch
-      // tries to parse the body as Flight data.
-      // In static mode, accept octet-stream/text/plain/absent content-type
-      // (static hosts serve .rsc files with these), but still reject 404s
-      // and text/html (missing .rsc file → host returns 404 page or SPA
-      // HTML fallback). See TIM-1231, TIM-1243, TIM-1247.
-      if (staticMode) {
-        const contentType = response.headers.get('content-type');
-        if (
-          !response.ok ||
-          (contentType && contentType.split(';')[0].trim().toLowerCase() === 'text/html')
-        ) {
-          response.body?.cancel();
-          throw new NonRscResponse(url);
-        }
-      } else {
-        if (!isRscContentType(response.headers.get('content-type'))) {
-          response.body?.cancel();
-          throw new NonRscResponse(url);
-        }
+  // createFromFetch takes a Promise<Response> and progressively parses
+  // the RSC Flight stream as chunks arrive.
+  //
+  // Intercept the response to read segment metadata before createFromFetch
+  // consumes the body. Reading headers does NOT consume the body stream.
+  const fetchPromise = deps.fetch(rscUrl, { headers, redirect: 'manual', signal });
+  let segmentInfo: SegmentInfo[] | null = null;
+  let skippedSegments: string[] | null = null;
+  // Track when the full RSC body stream is consumed (not just shell).
+  // Initialized to resolved for bodyless responses; overwritten when
+  // the response has a body.
+  let streamDone: Promise<void> = Promise.resolve();
+
+  const wrappedPromise = fetchPromise.then((response) => {
+    // Version skew detection (TIM-446): if the server signals a reload,
+    // throw VersionSkewError so the caller (router navigate) can trigger
+    // a full page reload.
+    if (checkReloadSignal(response)) {
+      throw new VersionSkewError();
+    }
+    // Detect server-side redirects. The server returns 204 + X-Timber-Redirect
+    // for RSC payload requests instead of a raw 302, because fetch with
+    // redirect: "manual" turns 302s into opaque redirects (status 0, null body)
+    // which crashes createFromFetch when it tries to read the body stream.
+    const redirectLocation =
+      response.headers.get('X-Timber-Redirect') ||
+      (response.status >= 300 && response.status < 400 ? response.headers.get('Location') : null);
+    if (redirectLocation) {
+      throw new RedirectError(redirectLocation);
+    }
+    // Detect server error responses. The server returns X-Timber-Error header
+    // with a JSON body instead of an RSC stream it cannot answer in-SPA.
+    // Hard-navigate so the server renders the error page as HTML.
+    // See design/10-error-handling.md §"Error Page Rendering for Client Navigation"
+    if (response.headers.get(TIMBER_ERROR_HEADER) === '1') {
+      throw new ServerErrorResponse(response.status, url);
+    }
+    // Content-Type guard: reject non-RSC responses before createFromFetch
+    // tries to parse the body as Flight data.
+    // In static mode, accept octet-stream/text/plain/absent content-type
+    // (static hosts serve .rsc files with these), but still reject 404s
+    // and text/html (missing .rsc file → host returns 404 page or SPA
+    // HTML fallback). See TIM-1231, TIM-1243, TIM-1247.
+    if (staticMode) {
+      const contentType = response.headers.get('content-type');
+      if (
+        !response.ok ||
+        (contentType && contentType.split(';')[0].trim().toLowerCase() === 'text/html')
+      ) {
+        response.body?.cancel();
+        throw new NonRscResponse(url);
       }
-      // Metadata (<title>/<meta>/<link>) now rides the RSC Flight payload
-      // as React elements — React 19 Float handles them. See TIM-1151.
-      segmentInfo = extractSegmentInfo(response);
-      skippedSegments = extractSkippedSegments(response);
-
-      // Wrap the body to track full stream consumption. createFromFetch's
-      // thenable resolves when the root model (shell) arrives, but we need
-      // to know when ALL chunks are read — that is what the navigation
-      // promise resolving means, and what keeps the pending store set.
-      if (response.body) {
-        const tracked = trackStreamCompletion(response.body);
-        streamDone = tracked.done;
-        streamDone.catch(() => {}); // prevent unhandled rejection
-        return new Response(tracked.body, {
-          headers: response.headers,
-          status: response.status,
-        });
+    } else {
+      if (!isRscContentType(response.headers.get('content-type'))) {
+        response.body?.cancel();
+        throw new NonRscResponse(url);
       }
-      return response;
-    });
-    // Await headers so segmentInfo is populated.
-    await wrappedPromise;
-    // Start decoding but do NOT await — return the in-progress thenable.
-    // React can render a Flight thenable directly: it suspends on unresolved
-    // parts and progressively renders as chunks arrive, spreading work across
-    // frames instead of blocking the main thread in one burst.
-    const root = deps.decodeRsc(wrappedPromise);
-    // One split, one root: the tree and the params it was rendered with come
-    // apart here and nowhere else, so nothing downstream has to keep them
-    // paired by hand.
-    const { tree: payload, params } = splitPayloadRoot(root);
-    // Combine stream completion with payload error propagation.
-    // streamDone marks the end of the RSC stream, which is what the
-    // navigation promise resolves on. payloadError propagates
-    // decode failures (stale client references, Flight parse errors)
-    // so the router's catch block can trigger recovery (stale reload).
-    const payloadError = new Promise<void>((_, reject) => {
-      Promise.resolve(root).then(() => {}, reject);
-    });
-    payloadError.catch(() => {});
-    const decodePromise = Promise.race([streamDone, payloadError]);
-    // Mark handled, like payloadError above. The same rejection reaches the
-    // router through `payload`, and a navigation that recovers by hard
-    // navigating (version skew, non-RSC response) hangs deliberately and never
-    // awaits this one — leaving it to surface as an unhandled rejection.
-    decodePromise.catch(() => {});
-    return {
-      payload,
-      params,
-      decodePromise,
-      segmentInfo,
-      skippedSegments,
-    };
-  }
-  // Test/fallback path: return raw text
-  const response = await deps.fetch(rscUrl, { headers, redirect: 'manual', signal });
-  // Check for redirect in test path too
-  if (response.status >= 300 && response.status < 400) {
-    const location = response.headers.get('Location');
-    if (location) {
-      throw new RedirectError(location);
-    }
-  }
-  // Server error guard (same as production path above).
-  if (response.headers.get(TIMBER_ERROR_HEADER) === '1') {
-    throw new ServerErrorResponse(response.status, url);
-  }
-  // Content-Type guard (same as production path above). See TIM-1231, TIM-1243, TIM-1247.
-  if (staticMode) {
-    const fallbackContentType = response.headers.get('content-type');
-    if (
-      !response.ok ||
-      (fallbackContentType &&
-        fallbackContentType.split(';')[0].trim().toLowerCase() === 'text/html')
-    ) {
-      response.body?.cancel();
-      throw new NonRscResponse(url);
     }
-  } else {
-    if (!isRscContentType(response.headers.get('content-type'))) {
-      response.body?.cancel();
-      throw new NonRscResponse(url);
+    // Metadata (<title>/<meta>/<link>) now rides the RSC Flight payload
+    // as React elements — React 19 Float handles them. See TIM-1151.
+    segmentInfo = extractSegmentInfo(response);
+    skippedSegments = extractSkippedSegments(response);
+
+    // Wrap the body to track full stream consumption. createFromFetch's
+    // thenable resolves when the root model (shell) arrives, but we need
+    // to know when ALL chunks are read — that is what the navigation
+    // promise resolving means, and what keeps the pending store set.
+    if (response.body) {
+      const tracked = trackStreamCompletion(response.body);
+      streamDone = tracked.done;
+      streamDone.catch(() => {}); // prevent unhandled rejection
+      return new Response(tracked.body, {
+        headers: response.headers,
+        status: response.status,
+      });
     }
-  }
-  // Test/fallback path: raw text carries no payload root, so no params.
+    return response;
+  });
+  // Await headers so segmentInfo is populated.
+  await wrappedPromise;
+  // Start decoding but do NOT await — return the in-progress thenable.
+  // React can render a Flight thenable directly: it suspends on unresolved
+  // parts and progressively renders as chunks arrive, spreading work across
+  // frames instead of blocking the main thread in one burst.
+  const root = deps.decodeRsc(wrappedPromise);
+  // One split, one root: the tree and the params it was rendered with come
+  // apart here and nowhere else, so nothing downstream has to keep them
+  // paired by hand.
+  const { tree: payload, params } = splitPayloadRoot(root);
+  // Settles once the stream has ended AND the root has decoded, and rejects
+  // as soon as either fails. streamDone marks the end of the RSC stream,
+  // which is what the navigation promise resolves on; the root's rejection
+  // carries decode failures (stale client references, Flight parse errors)
+  // so the router's catch block can trigger recovery (stale reload).
+  //
+  // Not a race between the two: a payload that arrives whole — a small
+  // static `.rsc` file — ends its stream before Flight rejects the root it
+  // could not decode, and a race resolved on the stream, so the failure
+  // never reached recovery and the skew was never recorded (TIM-1541).
+  const rootDecoded = Promise.resolve(root).then(() => {});
+  rootDecoded.catch(() => {});
+  const decodePromise = Promise.all([streamDone, rootDecoded]).then(() => {});
+  // Mark handled, like rootDecoded above. The same rejection reaches the
+  // router through `payload`, and a navigation that recovers by hard
+  // navigating (version skew, non-RSC response) hangs deliberately and never
+  // awaits this one — leaving it to surface as an unhandled rejection.
+  decodePromise.catch(() => {});
   return {
-    payload: await response.text(),
-    params: readPublishedParams(undefined),
-    decodePromise: null,
-    segmentInfo: extractSegmentInfo(response),
-    skippedSegments: extractSkippedSegments(response),
+    payload,
+    params,
+    decodePromise,
+    segmentInfo,
+    skippedSegments,
   };
 }

package/src/client/segment-cache.ts

@@ -74,6 +74,16 @@ export interface SegmentNode {
  */
 export class SegmentCache {
   private root: SegmentNode | undefined;
+  /**
+   * Monotonic counter. Bumped by `invalidateReuse()` (TIM-1466).
+   * `serializeStateTree` suppresses `segments` and `slots` when
+   * `reuseInvalidatedAt > reuseRestoredAt`. Only `restoreReuse()`
+   * advances `reuseRestoredAt` — `set()` does not, because a
+   * pre-invalidation navigation's commit thunk would lift suppression
+   * before a post-invalidation request has been sent (codex on #1167).
+   */
+  private reuseInvalidatedAt = 0;
+  private reuseRestoredAt = 0;
 
   get(segment: string): SegmentNode | undefined {
     if (segment === '/' || segment === this.root?.segment) {
@@ -90,6 +100,33 @@ export class SegmentCache {
 
   clear(): void {
     this.root = undefined;
+    this.reuseRestoredAt = this.reuseInvalidatedAt;
+  }
+
+  /**
+   * Suppress segment and slot reuse without destroying the tree
+   * structure (TIM-1466). `serializeStateTree` sends empty
+   * `segments`/`slots` (forcing a full render) while `treePaths`
+   * still reflects the mounted tree for interception scoping.
+   * Call `restoreReuse()` once post-invalidation data has been
+   * fetched and committed.
+   */
+  invalidateReuse(): void {
+    this.reuseInvalidatedAt++;
+  }
+
+  /**
+   * Lift reuse suppression. Called after the segment cache has been
+   * rebuilt from a response that was fetched with suppression active
+   * (i.e. the server sent a full render). Safe to call idempotently.
+   */
+  restoreReuse(): void {
+    this.reuseRestoredAt = this.reuseInvalidatedAt;
+  }
+
+  /** Whether segment/slot reuse is currently suppressed (TIM-1466). */
+  isReuseSuppressed(): boolean {
+    return this.reuseInvalidatedAt > this.reuseRestoredAt;
   }
 
   /**
@@ -116,9 +153,12 @@ export class SegmentCache {
     const segments: string[] = [];
     const slots: string[] = [];
     const treePaths: string[] = [];
+    const suppressed = this.reuseInvalidatedAt > this.reuseRestoredAt;
     if (this.root) {
-      collectSyncSegments(this.root, segments, mergeableFilter);
-      collectSyncSlots(this.root, slots);
+      if (!suppressed) {
+        collectSyncSegments(this.root, segments, mergeableFilter);
+        collectSyncSlots(this.root, slots);
+      }
       collectTreePaths(this.root, treePaths);
     }
     const tree: StateTree = { segments };
@@ -324,6 +364,27 @@ function prefetchMapKey(key: PrefetchKey): string {
   return `${key.from.length}:${key.from}:${key.scope.length}:${key.scope}:${key.url}`;
 }
 
+/**
+ * Extract the destination URL from a length-prefixed map key.
+ * Key format: `${from.length}:${from}:${scope.length}:${scope}:${url}`
+ */
+function extractUrlFromMapKey(mapKey: string): string | null {
+  // Parse from-length prefix
+  const firstColon = mapKey.indexOf(':');
+  if (firstColon === -1) return null;
+  const fromLen = parseInt(mapKey.slice(0, firstColon), 10);
+  if (Number.isNaN(fromLen)) return null;
+  // Skip past `from.length:from:`
+  const scopeStart = firstColon + 1 + fromLen + 1;
+  // Parse scope-length prefix
+  const secondColon = mapKey.indexOf(':', scopeStart);
+  if (secondColon === -1) return null;
+  const scopeLen = parseInt(mapKey.slice(scopeStart, secondColon), 10);
+  if (Number.isNaN(scopeLen)) return null;
+  // Skip past `scope.length:scope:` — remainder is the URL
+  return mapKey.slice(secondColon + 1 + scopeLen + 1);
+}
+
 /**
  * The `scope` half of a `PrefetchKey`, derived from the state tree that will
  * actually be sent. Taking it from the header value rather than re-walking the
@@ -334,8 +395,12 @@ export function prefetchScopeOf(stateTree: StateTree | undefined): string {
 }
 
 /** Outcome of a prefetch flight — discriminated so NonRscResponse is a
- *  success (stores a negative entry) rather than a rejection. */
-export type FlightOutcome = { kind: 'ready'; result: PrefetchResult } | { kind: 'non-route' };
+ *  success (stores a negative entry) rather than a rejection.
+ *  `startGen` is the eviction generation at flight start — joiners that
+ *  started after a gen bump must reject pre-invalidation results (TIM-1464). */
+export type FlightOutcome =
+  | { kind: 'ready'; result: PrefetchResult; startGen: number }
+  | { kind: 'non-route'; startGen: number };
 
 /**
  * Short-lived cache for hover-triggered prefetches. Entries expire after
@@ -410,16 +475,19 @@ export class PrefetchCache {
     // Capture the eviction generation before the flight starts. If an
     // action evicts caches while this flight is in progress, the gen
     // will have bumped and the stale result is discarded (TIM-1476).
+    // The starting gen is also included in the outcome so joiners
+    // that started after a gen bump can detect pre-invalidation
+    // results (TIM-1464).
     const genAtStart = this.evictionGen;
     return this.flights.do(prefetchMapKey(key), async (signal) => {
       try {
         const result = await doFetch(signal);
         if (!signal.aborted && this.evictionGen === genAtStart) this.set(key, result);
-        return { kind: 'ready' as const, result };
+        return { kind: 'ready' as const, result, startGen: genAtStart };
       } catch (err) {
         if (isNonRoute(err)) {
           if (!signal.aborted && this.evictionGen === genAtStart) this.setNegative(key);
-          return { kind: 'non-route' as const };
+          return { kind: 'non-route' as const, startGen: genAtStart };
         }
         throw err;
       }
@@ -455,16 +523,47 @@ export class PrefetchCache {
   }
 
   /**
-   * Invalidate all entries whose destination URL matches (TIM-1454).
-   * Used by `revalidatePath` on a non-current route so the next navigation
-   * fetches fresh data instead of replaying a stale prefetch.
+   * Invalidate entries whose destination URL matches (TIM-1454).
+   *
+   * When `url` has no search string, evicts all entries sharing that
+   * pathname — `/products` evicts `/products?page=1` too, because
+   * `revalidatePath('/products')` invalidates the route regardless of
+   * query (TIM-1465).
+   *
+   * When `url` has a search string, only the exact URL is evicted.
+   *
+   * Also bumps the eviction generation so in-flight singleflight
+   * flights for the invalidated URL(s) discard their results on
+   * completion (TIM-1464).
    */
   invalidateUrl(url: string): void {
+    const hasSearch = url.includes('?');
+    const pathname = hasSearch ? null : url;
+
     for (const [mapKey] of this.entries) {
-      if (mapKey.endsWith(':' + url)) {
-        this.entries.delete(mapKey);
+      // The map key is `${from.length}:${from}:${scope.length}:${scope}:${url}`.
+      // The destination URL is the suffix after the last unescaped colon pair.
+      if (hasSearch) {
+        if (mapKey.endsWith(':' + url)) {
+          this.entries.delete(mapKey);
+        }
+      } else {
+        // Extract the URL suffix — everything after the scope block.
+        // Match any entry whose URL pathname matches.
+        const entryUrl = extractUrlFromMapKey(mapKey);
+        if (entryUrl !== null) {
+          const qIndex = entryUrl.indexOf('?');
+          const entryPathname = qIndex === -1 ? entryUrl : entryUrl.slice(0, qIndex);
+          if (entryPathname === pathname) {
+            this.entries.delete(mapKey);
+          }
+        }
       }
     }
+
+    // Fence in-flight flights so a prefetch that started before
+    // invalidation cannot store its stale result (TIM-1464).
+    this.evictionGen++;
   }
 
   /**