@tanstack/router-core 1.171.14 → 1.171.16-pre.0

package/src/router.ts

@@ -1,8 +1,7 @@
 import { createBrowserHistory, parseHref } from '@tanstack/history'
-import { isServer } from '@tanstack/router-core/isServer'
+import { isServer, loadServerRoute } from '@tanstack/router-core/isServer'
 import {
   DEFAULT_PROTOCOL_ALLOWLIST,
-  createControlledPromise,
   decodePath,
   deepEqual,
   encodePathLikeUrl,
@@ -35,8 +34,15 @@ import { isNotFound } from './not-found'
 import { setupScrollRestoration } from './scroll-restoration'
 import { defaultParseSearch, defaultStringifySearch } from './searchParams'
 import { rootRouteId } from './root'
-import { isRedirect, redirect } from './redirect'
-import { loadMatches, loadRouteChunk, routeNeedsPreload } from './load-matches'
+import { isRedirect } from './redirect'
+import {
+  loadClientRoute,
+  loadRouteChunk,
+  preloadClientRoute,
+  refreshClientRoute,
+  replaceRouteChunk,
+  transferMatchResources,
+} from './load-client'
 import {
   composeRewrites,
   executeRewriteInput,
@@ -51,6 +57,13 @@ import type {
 } from './new-process-route-tree'
 import type { SearchParser, SearchSerializer } from './searchParams'
 import type { AnyRedirect, ResolvedRedirect } from './redirect'
+import type {
+  ActivePreload,
+  LoadTransaction,
+  LoaderFlight,
+  PendingSession,
+} from './load-client'
+import type { ServerLoadResult } from './load-server'
 import type {
   HistoryAction,
   HistoryLocation,
@@ -62,7 +75,6 @@ import type {
 import type {
   Awaitable,
   Constrain,
-  ControlledPromise,
   NoInfer,
   NonNullableUpdater,
   PickAsRequired,
@@ -75,8 +87,6 @@ import type {
   AnyRouteWithContext,
   LoaderStaleReloadMode,
   MakeRemountDepsOptionsUnion,
-  RouteContextOptions,
-  RouteLike,
   RouteMask,
   SearchMiddleware,
   SearchMiddlewareMeta,
@@ -106,7 +116,6 @@ import type {
 } from './manifest'
 import type { AnySchema, AnyValidator } from './validators'
 import type { NavigateOptions, ResolveRelativePath, ToOptions } from './link'
-import type { NotFoundError } from './not-found'
 import type {
   AnySerializationAdapter,
   ValidateSerializableInput,
@@ -263,9 +272,9 @@ export interface RouterOptions<
    */
   defaultPreloadStaleTime?: number
   /**
-   * The default `defaultPreloadGcTime` a route should use if no preloadGcTime is provided.
+   * The default `preloadGcTime` a route should use if none is provided.
    *
-   * @default 1_800_000 `(30 minutes)`
+   * @default 300_000 `(5 minutes)`
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultpreloadgctime-property)
    * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/preloading)
    */
@@ -297,7 +306,7 @@ export interface RouterOptions<
   /**
    * The default `gcTime` a route should use if no gcTime is provided.
    *
-   * @default 1_800_000 `(30 minutes)`
+   * @default 300_000 `(5 minutes)`
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultgctime-property)
    * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading#key-options)
    */
@@ -544,14 +553,10 @@ export interface RouterState<
   in out TRouteMatch = MakeRouteMatchUnion,
 > {
   status: 'pending' | 'idle'
-  loadedAt: number
   isLoading: boolean
-  isTransitioning: boolean
   matches: Array<TRouteMatch>
   location: ParsedLocation<FullSearchSchema<TRouteTree>>
   resolvedLocation?: ParsedLocation<FullSearchSchema<TRouteTree>>
-  statusCode: number
-  redirect?: AnyRedirect
 }
 
 export interface BuildNextOptions {
@@ -619,9 +624,21 @@ export type SubscribeFn = <TType extends keyof RouterEvents>(
 ) => () => void
 
 export interface MatchRoutesOpts {
-  preload?: boolean
   throwOnError?: boolean
-  dest?: BuildNextOptions
+  /** @internal */
+  _controller?: AbortController
+  /** @internal */
+  _rematerialize?: boolean
+}
+
+function routeNeedsLoad(route: AnyRoute): unknown {
+  return (
+    route.options.loader ||
+    route.options.beforeLoad ||
+    route.lazyFn ||
+    (route.options.component as any)?.preload ||
+    (route.options.pendingComponent as any)?.preload
+  )
 }
 
 export type InferRouterContext<TRouteTree extends AnyRoute> =
@@ -748,6 +765,8 @@ export type EmitFn = (routerEvent: RouterEvent) => void
 export type LoadFn = (opts?: {
   sync?: boolean
   action?: { type: HistoryAction }
+  _signal?: AbortSignal
+  _dedupe?: boolean
 }) => Promise<void>
 
 export type CommitLocationFn = ({
@@ -756,7 +775,11 @@ export type CommitLocationFn = ({
   ...next
 }: ParsedLocation & CommitLocationOptions) => Promise<void>
 
-export type StartTransitionFn = (fn: () => void) => void
+export type StartTransitionFn = (
+  fn: () => void,
+  expected: Array<AnyRouteMatch>,
+  urgent?: boolean,
+) => Promise<boolean>
 
 export interface MatchRoutesFn {
   (
@@ -775,13 +798,6 @@ export interface MatchRoutesFn {
   ): Array<AnyRouteMatch>
 }
 
-export type GetMatchFn = (matchId: string) => AnyRouteMatch | undefined
-
-export type UpdateMatchFn = (
-  id: string,
-  updater: (match: AnyRouteMatch) => AnyRouteMatch,
-) => void
-
 export type LoadRouteChunkFn = (route: AnyRoute) => Promise<Array<void>>
 
 export type ResolveRedirect = (err: AnyRedirect) => ResolvedRedirect
@@ -896,18 +912,61 @@ export function getLocationChangeInfo(
   location: ParsedLocation,
   resolvedLocation?: ParsedLocation,
 ) {
-  const fromLocation = resolvedLocation
-  const toLocation = location
-  const pathChanged = fromLocation?.pathname !== toLocation.pathname
-  const hrefChanged = fromLocation?.href !== toLocation.href
-  const hashChanged = fromLocation?.hash !== toLocation.hash
-  return { fromLocation, toLocation, pathChanged, hrefChanged, hashChanged }
+  return {
+    fromLocation: resolvedLocation,
+    toLocation: location,
+    pathChanged: resolvedLocation?.pathname !== location.pathname,
+    hrefChanged: resolvedLocation?.href !== location.href,
+    hashChanged: resolvedLocation?.hash !== location.hash,
+  }
 }
 
-export const locationHistoryActions = new WeakMap<
-  ParsedLocation,
-  HistoryAction
->()
+/**
+ * Return only state owned by the application, excluding volatile history
+ * bookkeeping. Mask payloads (`__tempLocation`/`__tempKey`) are kept: they
+ * distinguish otherwise-identical locations.
+ */
+export function _getUserHistoryState({
+  key: _key,
+  __TSR_key: _tsrKey,
+  __TSR_index: _tsrIndex,
+  __hashScrollIntoViewOptions: _hashScroll,
+  ...state
+}: ParsedHistoryState): HistoryState {
+  return state
+}
+
+/** Run route lifecycle callbacks in leave/enter/stay phases. */
+export function runRouteLifecycle(
+  router: AnyRouter,
+  previous: Array<AnyRouteMatch>,
+  matches: Array<AnyRouteMatch>,
+  isCurrent?: () => boolean,
+): void {
+  for (const match of previous) {
+    if (isCurrent?.() === false) {
+      return
+    }
+    if (!matches.some((candidate) => candidate.routeId === match.routeId)) {
+      ;(router.routesById as Record<string, AnyRoute>)[
+        match.routeId
+      ]!.options.onLeave?.(match)
+    }
+  }
+  for (const match of matches) {
+    if (isCurrent?.() === false) {
+      return
+    }
+    const route = (router.routesById as Record<string, AnyRoute>)[
+      match.routeId
+    ]!
+    route.options[
+      previous.some((candidate) => candidate.routeId === match.routeId)
+        ? 'onStay'
+        : 'onEnter'
+    ]?.(match)
+  }
+}
 
 type LightweightRouteMatchResult = {
   matchedRoutes: ReadonlyArray<AnyRoute>
@@ -956,6 +1015,43 @@ declare global {
     | undefined
 }
 
+export interface RouterCore<
+  in out TRouteTree extends AnyRoute,
+  in out TTrailingSlashOption extends TrailingSlashOption,
+  in out TDefaultStructuralSharingOption extends boolean,
+  in out TRouterHistory extends RouterHistory = RouterHistory,
+  in out TDehydrated extends Record<string, any> = Record<string, any>,
+> {
+  shouldViewTransition?: boolean | ViewTransitionOptions
+  /** Current client load transaction and owner of navigation writes. */
+  _tx?: LoadTransaction
+  /** Joinable in-flight loader generations keyed by match ID. */
+  _flights?: Map<string, LoaderFlight>
+  /** Whole speculative lanes that an identical navigation may adopt. */
+  _preloads?: Map<string, ActivePreload>
+  /** Owns cancellable work before a client transaction publishes. */
+  _preflight?: AbortController
+  /** Transfers one reconstructed SSR prefix into its initial client load. */
+  _handoff?: HydrationHandoff
+  /** Pending-boundary reveal and minimum-visible timing state. */
+  _pending?: PendingSession
+  /** Result of the latest server load, used to render or redirect. */
+  _serverResult?: ServerLoadResult
+  /** Framework callback that acknowledges an exact matches publication. */
+  _rendered?: (matches: Array<AnyRouteMatch>) => void
+  /** Development-only HMR reload for a route and its descendants. */
+  _refreshRoute: (() => Promise<void>) | undefined
+  /** Development-only replacement for a route's lazy chunk owner. */
+  _replaceRouteChunk:
+    | ((route: AnyRoute, lazyFn: AnyRoute['lazyFn']) => void)
+    | undefined
+}
+
+export type HydrationHandoff = [
+  claim: () => AbortController | undefined,
+  finish: (matches?: Array<AnyRouteMatch>) => number | undefined,
+]
+
 /**
  * Core, framework-agnostic router engine that powers TanStack Router.
  *
@@ -978,14 +1074,17 @@ export class RouterCore<
   )}`
   _scroll: {
     next: boolean
+    // True until the current PUSH/REPLACE renders, so its hash owns window scroll.
+    hash?: boolean
     restoring?: boolean
     restoration?: boolean
     reset?: boolean
   } = { next: true }
-  shouldViewTransition?: boolean | ViewTransitionOptions = undefined
-  isViewTransitionTypesSupported?: boolean = undefined
   subscribers = new Set<RouterListener<RouterEvent>>()
-  viewTransitionPromise?: ControlledPromise<true>
+  /** Accepted off-screen loader generations keyed by match ID. */
+  _cache = new Map<string, AnyRouteMatch>()
+  /** Accepted semantic lane, excluding temporary pending presentation. */
+  _committed: Array<AnyRouteMatch> = []
 
   // Must build in constructor
   stores!: RouterStores<TRouteTree>
@@ -1006,7 +1105,7 @@ export class RouterCore<
   rewrite?: LocationRewrite
   origin?: string
   latestLocation!: ParsedLocation<FullSearchSchema<TRouteTree>>
-  pendingBuiltLocation?: ParsedLocation<FullSearchSchema<TRouteTree>>
+  _pendingLocation?: ParsedLocation<FullSearchSchema<TRouteTree>>
   basepath!: string
   routeTree!: TRouteTree
   routesById!: RoutesById<TRouteTree>
@@ -1051,24 +1150,19 @@ export class RouterCore<
         options.protocolAllowlist ?? DEFAULT_PROTOCOL_ALLOWLIST,
     })
 
-    if (typeof document !== 'undefined') {
+    if (!(isServer ?? typeof document === 'undefined')) {
       self.__TSR_ROUTER__ = this
     }
   }
 
-  // This is a default implementation that can optionally be overridden
-  // by the router provider once rendered. We provide this so that the
-  // router can be used in a non-react environment if necessary
-  startTransition: StartTransitionFn = (fn) => fn()
-
+  startTransition: StartTransitionFn = async (fn) => {
+    fn()
+    return false
+  }
   isShell() {
     return !!this.options.isShell
   }
 
-  isPrerendering() {
-    return !!this.options.isPrerendering
-  }
-
   update: UpdateFn<
     TRouteTree,
     TTrailingSlashOption,
@@ -1094,7 +1188,8 @@ export class RouterCore<
       ...newOptions,
     }
 
-    this.isServer = this.options.isServer ?? typeof document === 'undefined'
+    this.isServer =
+      this.options.isServer ?? isServer ?? typeof document === 'undefined'
 
     this.protocolAllowlist = new Set(this.options.protocolAllowlist)
 
@@ -1168,17 +1263,13 @@ export class RouterCore<
     if (!this.stores && this.latestLocation) {
       const config = this.getStoreConfig(this)
       this.batch = config.batch
-      this.stores = createRouterStores(
-        getInitialRouterState(this.latestLocation),
-        config,
-      )
+      this.stores = createRouterStores(this.latestLocation, config)
 
       if (!(isServer ?? this.isServer)) {
         setupScrollRestoration(this)
       }
     }
 
-    let needsLocationUpdate = false
     const nextBasepath = this.options.basepath ?? '/'
     const nextRewriteOption = this.options.rewrite
     const basepathChanged = basepathWasUnset || prevBasepath !== nextBasepath
@@ -1211,21 +1302,9 @@ export class RouterCore<
         this.updateLatestLocation()
       }
 
-      needsLocationUpdate = true
-    }
-
-    if (needsLocationUpdate && this.stores) {
-      this.stores.location.set(this.latestLocation)
-    }
-
-    if (
-      typeof window !== 'undefined' &&
-      'CSS' in window &&
-      typeof window.CSS?.supports === 'function'
-    ) {
-      this.isViewTransitionTypesSupported = window.CSS.supports(
-        'selector(:active-view-transition-type(a))',
-      )
+      if (this.stores) {
+        this.stores.location.set(this.latestLocation)
+      }
     }
   }
 
@@ -1296,11 +1375,15 @@ export class RouterCore<
   }
 
   emit: EmitFn = (routerEvent) => {
-    this.subscribers.forEach((listener) => {
+    for (const listener of this.subscribers) {
       if (listener.eventType === routerEvent.type) {
-        listener.fn(routerEvent)
+        try {
+          listener.fn(routerEvent)
+        } catch (e) {
+          console.error(e)
+        }
       }
-    })
+    }
   }
 
   /**
@@ -1408,10 +1491,6 @@ export class RouterCore<
     return branch
   }
 
-  get looseRoutesById() {
-    return this.routesById as Record<string, AnyRoute>
-  }
-
   matchRoutes: MatchRoutesFn = (
     pathnameOrNext: string | ParsedLocation,
     locationSearchOrOpts?: AnySchema | MatchRoutesOpts,
@@ -1430,16 +1509,6 @@ export class RouterCore<
     return this.matchRoutesInternal(pathnameOrNext, locationSearchOrOpts)
   }
 
-  private getParentContext(parentMatch?: AnyRouteMatch) {
-    const parentMatchId = parentMatch?.id
-
-    const parentContext = !parentMatchId
-      ? ((this.options.context as any) ?? undefined)
-      : (parentMatch.context ?? this.options.context ?? undefined)
-
-    return parentContext
-  }
-
   private matchRoutesInternal(
     next: ParsedLocation,
     opts?: MatchRoutesOpts,
@@ -1466,18 +1535,19 @@ export class RouterCore<
       }
     }
 
-    const globalNotFoundRouteId = isGlobalNotFound
+    const _notFoundRouteId = isGlobalNotFound
       ? findGlobalNotFoundRouteId(this.options.notFoundMode, matchedRoutes)
       : undefined
 
     const matches = new Array<AnyRouteMatch>(matchedRoutes.length)
-    // Snapshot of active match state keyed by routeId, used to stabilise
-    // params/search across navigations.
-    const previousActiveMatchesByRouteId = new Map<string, AnyRouteMatch>()
-    for (const store of this.stores.matchStores.values()) {
-      if (store.routeId) {
-        previousActiveMatchesByRouteId.set(store.routeId, store.get())
-      }
+    const committed = this._committed
+    const previousAt = (route: AnyRoute, index: number) => {
+      const match = committed[index]
+      return match?.routeId === route.id
+        ? match
+        : route === this.options.notFoundRoute
+          ? committed.find((candidate) => candidate.routeId === route.id)
+          : undefined
     }
 
     for (let index = 0; index < matchedRoutes.length; index++) {
@@ -1509,7 +1579,6 @@ export class RouterCore<
             ...strictSearch,
           }
           strictMatchSearch = { ...parentStrictSearch, ...strictSearch }
-          searchError = undefined
         } catch (err: any) {
           let searchParamError = err
           if (!(err instanceof SearchParamError)) {
@@ -1527,19 +1596,25 @@ export class RouterCore<
           searchError = searchParamError
         }
       }
-
       // This is where we need to call route.options.loaderDeps() to get any additional
       // deps that the route's loader function might need to run. We need to do this
       // before we create the match so that we can pass the deps to the route's
       // potential key function which is used to uniquely identify the route match in state
 
-      const loaderDeps =
-        route.options.loaderDeps?.({
-          search: preMatchSearch,
-        }) ?? ''
-
-      const loaderDepsHash = loaderDeps ? JSON.stringify(loaderDeps) : ''
-
+      let loaderDeps: any = ''
+      let loaderDepsHash = ''
+      try {
+        loaderDeps =
+          route.options.loaderDeps?.({
+            search: preMatchSearch,
+          }) ?? ''
+        loaderDepsHash = loaderDeps ? JSON.stringify(loaderDeps) || '' : ''
+      } catch (cause) {
+        if (opts?.throwOnError) {
+          throw cause
+        }
+        searchError ??= cause
+      }
       const { interpolatedPath, usedParams } = interpolatePath({
         path: route.fullPath,
         params: routeParams,
@@ -1547,12 +1622,9 @@ export class RouterCore<
         server: this.isServer,
       })
 
-      // Waste not, want not. If we already have a match for this route,
-      // reuse it. This is important for layout routes, which might stick
-      // around between navigation actions that only change leaf routes.
-
-      // Existing matches are matches that are already loaded along with
-      // pending matches that are still loading
+      // Seed planning from the accepted same-ID cache generation first, then
+      // from the committed generation for this route. Presentation stores are
+      // deliberately not a semantic reuse authority.
       const matchId =
         // route.id for disambiguation
         route.id +
@@ -1561,13 +1633,16 @@ export class RouterCore<
         // explicit deps
         loaderDepsHash
 
-      const existingMatch = this.getMatch(matchId)
-
-      const previousMatch = previousActiveMatchesByRouteId.get(route.id)
+      const previousMatch = previousAt(route, index)
+      const existingMatch =
+        process.env.NODE_ENV !== 'production' && opts?._rematerialize
+          ? undefined
+          : (this._cache.get(matchId) ??
+            (previousMatch?.id === matchId ? previousMatch : undefined))
 
       const strictParams = existingMatch?._strictParams ?? usedParams
 
-      let paramsError: unknown = undefined
+      let paramsError: unknown
 
       if (!existingMatch) {
         try {
@@ -1603,15 +1678,10 @@ export class RouterCore<
             ? nullReplaceEqualDeep(previousMatch.search, preMatchSearch)
             : nullReplaceEqualDeep(existingMatch.search, preMatchSearch),
           _strictSearch: strictMatchSearch,
+          searchError,
         }
       } else {
-        const status =
-          route.options.loader ||
-          route.options.beforeLoad ||
-          route.lazyFn ||
-          routeNeedsPreload(route)
-            ? 'pending'
-            : 'success'
+        const status = routeNeedsLoad(route) ? 'pending' : 'success'
 
         match = {
           id: matchId,
@@ -1626,96 +1696,42 @@ export class RouterCore<
             ? nullReplaceEqualDeep(previousMatch.search, preMatchSearch)
             : preMatchSearch,
           _strictSearch: strictMatchSearch,
-          searchError: undefined,
+          searchError,
           status,
           isFetching: false,
           error: undefined,
           paramsError,
-          __routeContext: undefined,
-          _nonReactive: {
-            loadPromise: createControlledPromise(),
-          },
-          __beforeLoadContext: undefined,
           context: {},
-          abortController: new AbortController(),
-          fetchCount: 0,
+          abortController: opts?._controller ?? new AbortController(),
           cause,
           loaderDeps: previousMatch
             ? replaceEqualDeep(previousMatch.loaderDeps, loaderDeps)
             : loaderDeps,
           invalid: false,
           preload: false,
-          links: undefined,
-          scripts: undefined,
-          headScripts: undefined,
-          meta: undefined,
           staticData: route.options.staticData || {},
           fullPath: route.fullPath,
         }
       }
 
-      if (!opts?.preload) {
-        // If we have a global not found, mark the right match as global not found
-        match.globalNotFound = globalNotFoundRouteId === route.id
-      }
-
-      // update the searchError if there is one
-      match.searchError = searchError
-
-      const parentContext = this.getParentContext(parentMatch)
-
-      match.context = {
-        ...parentContext,
-        ...match.__routeContext,
-        ...match.__beforeLoadContext,
+      // If we have a global not found, mark the right match as global not found
+      const _notFound = _notFoundRouteId === route.id
+      if (match._notFound && !_notFound) {
+        match.error = undefined
       }
+      match._notFound = _notFound
 
       matches[index] = match
     }
 
     for (let index = 0; index < matches.length; index++) {
       const match = matches[index]!
-      const route = this.looseRoutesById[match.routeId]!
-      const existingMatch = this.getMatch(match.id)
-
-      // Update the match's params
-      const previousMatch = previousActiveMatchesByRouteId.get(match.routeId)
-      match.params = previousMatch
-        ? nullReplaceEqualDeep(previousMatch.params, routeParams)
-        : routeParams
-
-      if (!existingMatch) {
-        const parentMatch = matches[index - 1]
-        const parentContext = this.getParentContext(parentMatch)
-
-        // Update the match's context
-
-        if (route.options.context) {
-          const contextFnContext: RouteContextOptions<any, any, any, any, any> =
-            {
-              deps: match.loaderDeps,
-              params: match.params,
-              context: parentContext ?? {},
-              location: next,
-              navigate: (opts: any) =>
-                this.navigate({ ...opts, _fromLocation: next }),
-              buildLocation: this.buildLocation,
-              cause: match.cause,
-              abortController: match.abortController,
-              preload: !!match.preload,
-              matches,
-              routeId: route.id,
-            }
-          // Get the route context
-          match.__routeContext =
-            route.options.context(contextFnContext) ?? undefined
-        }
-
-        match.context = {
-          ...parentContext,
-          ...match.__routeContext,
-          ...match.__beforeLoadContext,
-        }
+      match.params =
+        match.cause === 'stay'
+          ? nullReplaceEqualDeep(match.params, routeParams)
+          : routeParams
+      if (opts?._controller) {
+        match.context = {}
       }
     }
 
@@ -1723,22 +1739,35 @@ export class RouterCore<
   }
 
   getMatchedRoutes: GetMatchRoutesFn = (pathname) => {
-    return getMatchedRoutes({
-      pathname,
-      routesById: this.routesById,
-      processedTree: this.processedTree,
-    })
+    const routeParams: Record<string, string> = Object.create(null)
+    const match = findRouteMatch(
+      trimPathRight(pathname),
+      this.processedTree,
+      true,
+    )
+    if (match) {
+      Object.assign(routeParams, match.rawParams)
+    }
+    return {
+      matchedRoutes: match?.branch || [this.routesById[rootRouteId]!],
+      routeParams,
+      foundRoute: match?.route,
+    }
   }
 
   /**
    * Lightweight route matching for buildLocation.
    * Only computes fullPath, accumulated search, and params - skipping expensive
-   * operations like AbortController, ControlledPromise, loaderDeps, and full match objects.
+   * operations like AbortController, loaderDeps, and full match objects.
    */
   private matchRoutesLightweight(
     location: ParsedLocation,
   ): LightweightRouteMatchResult {
-    const lastStateMatchId = last(this.stores.matchesId.get())
+    const lastRouteId = last(this.stores.ids.get())
+    const lastStateMatch = lastRouteId
+      ? this.stores.byRoute.get(lastRouteId)!.get()
+      : undefined
+    const lastStateMatchId = lastStateMatch?.id
     const cached = this.lightweightCache.get(location)
     if (cached && cached[0] === lastStateMatchId) {
       return cached[1]
@@ -1772,8 +1801,6 @@ export class RouterCore<
     }
 
     // Determine params: reuse from state if possible, otherwise parse
-    const lastStateMatch =
-      lastStateMatchId && this.stores.matchStores.get(lastStateMatchId)?.get()
     const canReuseParams =
       lastStateMatch &&
       lastStateMatch.routeId === lastRoute.id &&
@@ -1808,37 +1835,6 @@ export class RouterCore<
     return result
   }
 
-  cancelMatch = (id: string) => {
-    const match = this.getMatch(id)
-
-    if (!match) return
-
-    match.abortController.abort()
-    clearTimeout(match._nonReactive.pendingTimeout)
-    match._nonReactive.pendingTimeout = undefined
-  }
-
-  cancelMatches = () => {
-    this.stores.pendingIds.get().forEach((matchId) => {
-      this.cancelMatch(matchId)
-    })
-
-    this.stores.matchesId.get().forEach((matchId) => {
-      if (this.stores.pendingMatchStores.has(matchId)) {
-        return
-      }
-
-      const match = this.stores.matchStores.get(matchId)?.get()
-      if (!match) {
-        return
-      }
-
-      if (match.status === 'pending' || match.isFetching === 'loader') {
-        this.cancelMatch(matchId)
-      }
-    })
-  }
-
   /**
    * Build the next ParsedLocation from navigation options without committing.
    * Resolves `to`/`from`, params/search/hash/state, applies search validation
@@ -1854,7 +1850,7 @@ export class RouterCore<
     ): ParsedLocation => {
       // We allow the caller to override the current location
       const currentLocation =
-        dest._fromLocation || this.pendingBuiltLocation || this.latestLocation
+        dest._fromLocation || this._pendingLocation || this.latestLocation
 
       // Use lightweight matching - only computes what buildLocation needs
       // (fullPath, search, params) without creating full match objects
@@ -1909,15 +1905,7 @@ export class RouterCore<
         : sourcePath
 
       // Resolve the next params
-      const nextParams =
-        dest.params === false || dest.params === null
-          ? Object.create(null)
-          : (dest.params ?? true) === true
-            ? fromParams
-            : Object.assign(
-                fromParams,
-                functionalUpdate(dest.params as any, fromParams),
-              )
+      const nextParams = resolveNextParams(dest.params, fromParams)
 
       const destRoute = this.routesByPath[
         trimPathRight(nextTo) as keyof typeof this.routesByPath
@@ -2015,12 +2003,12 @@ export class RouterCore<
         nextSearch = validatedSearch
       }
 
-      nextSearch = applySearchMiddleware({
-        search: nextSearch,
+      nextSearch = applySearchMiddleware(
+        nextSearch,
         dest,
         destRoutes,
-        _includeValidateSearch: opts._includeValidateSearch,
-      })
+        opts._includeValidateSearch,
+      )
 
       // Replace the equal deep
       nextSearch = nullReplaceEqualDeep(fromSearch, nextSearch)
@@ -2120,12 +2108,7 @@ export class RouterCore<
 
             // If mask has a params function, call it with the matched params as context
             // Otherwise, use the matched params or the provided params value
-            const nextParams =
-              maskParams === false || maskParams === null
-                ? Object.create(null)
-                : (maskParams ?? true) === true
-                  ? params
-                  : Object.assign(params, functionalUpdate(maskParams, params))
+            const nextParams = resolveNextParams(maskParams, params)
 
             maskedDest = {
               from: opts.from,
@@ -2154,7 +2137,7 @@ export class RouterCore<
     return buildWithMatches(opts)
   }
 
-  commitLocationPromise: undefined | ControlledPromise<void>
+  _commitPromise: (Promise<void> & { resolve: () => void }) | undefined
 
   /**
    * Commit a previously built location to history (push/replace), optionally
@@ -2166,38 +2149,27 @@ export class RouterCore<
     ...next
   }) => {
     let historyAction: HistoryAction | undefined
-    const isSameState = () => {
-      // the following props are ignored but may still be provided when navigating,
-      // temporarily add the previous values to the next state so they don't affect
-      // the comparison
-      const ignoredProps = [
-        'key', // TODO: Remove in v2 - use __TSR_key instead
-        '__TSR_key',
-        '__TSR_index',
-        '__hashScrollIntoViewOptions',
-      ] as const
-      ignoredProps.forEach((prop) => {
-        ;(next.state as any)[prop] = this.latestLocation.state[prop]
-      })
-      const isEqual = deepEqual(next.state, this.latestLocation.state)
-      ignoredProps.forEach((prop) => {
-        delete next.state[prop]
-      })
-      return isEqual
-    }
-
-    const isSameUrl =
-      trimPathRight(this.latestLocation.href) === trimPathRight(next.href)
+    const isSameLocation =
+      trimPathRight(this.latestLocation.href) === trimPathRight(next.href) &&
+      deepEqual(
+        _getUserHistoryState(next.state),
+        _getUserHistoryState(this.latestLocation.state),
+      )
 
-    let previousCommitPromise = this.commitLocationPromise
-    this.commitLocationPromise = createControlledPromise<void>(() => {
+    const previousCommitPromise = this._commitPromise
+    let resolve!: () => void
+    const commitPromise = new Promise<void>((done) => {
+      resolve = done
+    }) as Promise<void> & { resolve: () => void }
+    commitPromise.resolve = () => {
+      resolve()
       previousCommitPromise?.resolve()
-      previousCommitPromise = undefined
-    })
+    }
+    this._commitPromise = commitPromise
 
     // Don't commit to history if nothing changed
-    if (isSameUrl && isSameState()) {
-      this.load()
+    if (isSameLocation) {
+      this.load({ _dedupe: true })
     } else {
       let {
         // eslint-disable-next-line prefer-const
@@ -2248,21 +2220,17 @@ export class RouterCore<
         nextHistory.state,
         { ignoreBlocker },
       )
+
+      // Without a subscribed adapter the history commit cannot trigger the
+      // load itself. The same-location branch already loads directly.
+      if (!this.history.subscribers.size) {
+        this.load({ action: { type: historyAction } })
+      }
     }
 
     this._scroll.next = next.resetScroll ?? true
 
-    if (!this.history.subscribers.size) {
-      this.load(
-        historyAction
-          ? {
-              action: { type: historyAction },
-            }
-          : undefined,
-      )
-    }
-
-    return this.commitLocationPromise
+    return this._commitPromise
   }
 
   /** Convenience helper: build a location from options, then commit it. */
@@ -2272,9 +2240,11 @@ export class RouterCore<
     hashScrollIntoView,
     viewTransition,
     ignoreBlocker,
+    _redirects,
     href,
     ...rest
-  }: BuildNextOptions & CommitLocationOptions = {}) => {
+  }: BuildNextOptions &
+    CommitLocationOptions & { _redirects?: number } = {}) => {
     if (href) {
       const currentIndex = this.history.location.state.__TSR_index
 
@@ -2298,8 +2268,12 @@ export class RouterCore<
       ...(rest as any),
       _includeValidateSearch: true,
     })
+    if (_redirects) {
+      ;(location as typeof location & { _redirects?: number })._redirects =
+        _redirects
+    }
 
-    this.pendingBuiltLocation = location as ParsedLocation<
+    this._pendingLocation = location as ParsedLocation<
       FullSearchSchema<TRouteTree>
     >
 
@@ -2315,8 +2289,8 @@ export class RouterCore<
     // Clear pending location after commit starts
     // We do this on next microtask to allow synchronous navigate calls to chain
     queueMicrotask(() => {
-      if (this.pendingBuiltLocation === location) {
-        this.pendingBuiltLocation = undefined
+      if (this._pendingLocation === location) {
+        this._pendingLocation = undefined
       }
     })
 
@@ -2412,254 +2386,17 @@ export class RouterCore<
     })
   }
 
-  latestLoadPromise: undefined | Promise<void>
-
-  beforeLoad = () => {
-    // Cancel any pending matches
-    this.cancelMatches()
-    this.updateLatestLocation()
-
-    if (isServer ?? this.isServer) {
-      // for SPAs on the initial load, this is handled by the Transitioner
-      const nextLocation = this.buildLocation({
-        to: this.latestLocation.pathname,
-        search: true,
-        params: true,
-        hash: true,
-        state: true,
-        _includeValidateSearch: true,
-      })
-
-      // Check if location changed - origin check is unnecessary since buildLocation
-      // always uses this.origin when constructing URLs
-      if (this.latestLocation.publicHref !== nextLocation.publicHref) {
-        const href = this.getParsedLocationHref(nextLocation)
-        if (nextLocation.external) {
-          throw redirect({ href })
-        } else {
-          throw redirect({ href, _builtLocation: nextLocation })
-        }
-      }
-    }
-
-    // Match the routes
-    const pendingMatches = this.matchRoutes(this.latestLocation)
-
-    const nextCachedMatches = this.stores.cachedMatches
-      .get()
-      .filter((d) => !pendingMatches.some((e) => e.id === d.id))
-
-    // Ingest the new matches
-    this.batch(() => {
-      this.stores.status.set('pending')
-      this.stores.statusCode.set(200)
-      this.stores.isLoading.set(true)
-      this.stores.location.set(this.latestLocation)
-      this.stores.setPending(pendingMatches)
-      // If a cached match moved to pending matches, remove it from cached matches
-      this.stores.setCached(nextCachedMatches)
-    })
-  }
-
   load: LoadFn = async (opts): Promise<void> => {
-    const historyAction = opts?.action?.type
-    let redirect: AnyRedirect | undefined
-    let notFound: NotFoundError | undefined
-    let loadPromise: Promise<void>
-    const previousLocation =
-      this.stores.resolvedLocation.get() ?? this.stores.location.get()
-
-    // eslint-disable-next-line prefer-const
-    loadPromise = new Promise<void>((resolve) => {
-      this.startTransition(async () => {
-        try {
-          this.beforeLoad()
-          if (historyAction) {
-            locationHistoryActions.set(this.latestLocation, historyAction)
-          } else {
-            locationHistoryActions.delete(this.latestLocation)
-          }
-          const next = this.latestLocation
-          const prevLocation = this.stores.resolvedLocation.get()
-          const locationChangeInfo = getLocationChangeInfo(next, prevLocation)
-
-          if (!this.stores.redirect.get()) {
-            this.emit({
-              type: 'onBeforeNavigate',
-              ...locationChangeInfo,
-            })
-          }
-
-          this.emit({
-            type: 'onBeforeLoad',
-            ...locationChangeInfo,
-          })
-
-          await loadMatches({
-            router: this,
-            sync: opts?.sync,
-            forceStaleReload: previousLocation.href === next.href,
-            matches: this.stores.pendingMatches.get(),
-            location: next,
-            updateMatch: this.updateMatch,
-            // eslint-disable-next-line @typescript-eslint/require-await
-            onReady: async () => {
-              // Wrap batch in framework-specific transition wrapper (e.g., Solid's startTransition)
-              this.startTransition(() => {
-                this.startViewTransition(async () => {
-                  // this.viewTransitionPromise = createControlledPromise<true>()
-
-                  // Commit the pending matches. If a previous match was
-                  // removed, place it in the cachedMatches
-                  //
-                  // exitingMatches uses match.id (routeId + params + loaderDeps) so
-                  // navigating /foo?page=1 → /foo?page=2 correctly caches the page=1 entry.
-                  let exitingMatches: Array<AnyRouteMatch> | null = null
-
-                  // Lifecycle-hook identity uses routeId only so that navigating between
-                  // different params/deps of the same route fires onStay (not onLeave+onEnter).
-                  let hookExitingMatches: Array<AnyRouteMatch> | null = null
-                  let hookEnteringMatches: Array<AnyRouteMatch> | null = null
-                  let hookStayingMatches: Array<AnyRouteMatch> | null = null
-
-                  this.batch(() => {
-                    const pendingMatches = this.stores.pendingMatches.get()
-                    const mountPending = pendingMatches.length
-                    const currentMatches = this.stores.matches.get()
-
-                    exitingMatches = mountPending
-                      ? currentMatches.filter(
-                          (match) =>
-                            !this.stores.pendingMatchStores.has(match.id),
-                        )
-                      : null
-
-                    // Lifecycle-hook identity: routeId only (route presence in tree)
-                    // Build routeId sets from pools to avoid derived stores.
-                    const pendingRouteIds = new Set<string>()
-                    for (const s of this.stores.pendingMatchStores.values()) {
-                      if (s.routeId) pendingRouteIds.add(s.routeId)
-                    }
-                    const activeRouteIds = new Set<string>()
-                    for (const s of this.stores.matchStores.values()) {
-                      if (s.routeId) activeRouteIds.add(s.routeId)
-                    }
-
-                    hookExitingMatches = mountPending
-                      ? currentMatches.filter(
-                          (match) => !pendingRouteIds.has(match.routeId),
-                        )
-                      : null
-                    hookEnteringMatches = mountPending
-                      ? pendingMatches.filter(
-                          (match) => !activeRouteIds.has(match.routeId),
-                        )
-                      : null
-                    hookStayingMatches = mountPending
-                      ? pendingMatches.filter((match) =>
-                          activeRouteIds.has(match.routeId),
-                        )
-                      : currentMatches
-
-                    this.stores.isLoading.set(false)
-                    this.stores.loadedAt.set(Date.now())
-                    /**
-                     * When committing new matches, cache any exiting matches that are still usable.
-                     * Routes that resolved with `status: 'error'` or `status: 'notFound'` are
-                     * deliberately excluded from `cachedMatches` so that subsequent invalidations
-                     * or reloads re-run their loaders instead of reusing the failed/not-found data.
-                     */
-                    if (mountPending) {
-                      this.stores.setMatches(pendingMatches)
-                      this.stores.setPending([])
-                      this.stores.setCached([
-                        ...this.stores.cachedMatches.get(),
-                        ...exitingMatches!.filter(
-                          (d) =>
-                            d.status !== 'error' &&
-                            d.status !== 'notFound' &&
-                            d.status !== 'redirected',
-                        ),
-                      ])
-                      this.clearExpiredCache()
-                    }
-                  })
-
-                  //
-                  for (const [matches, hook] of [
-                    [hookExitingMatches, 'onLeave'],
-                    [hookEnteringMatches, 'onEnter'],
-                    [hookStayingMatches, 'onStay'],
-                  ] as const) {
-                    if (!matches) continue
-                    for (const match of matches as Array<AnyRouteMatch>) {
-                      this.looseRoutesById[match.routeId]!.options[hook]?.(
-                        match,
-                      )
-                    }
-                  }
-                })
-              })
-            },
-          })
-        } catch (err) {
-          if (isRedirect(err)) {
-            redirect = err
-            if (!(isServer ?? this.isServer)) {
-              this.navigate({
-                ...redirect.options,
-                replace: true,
-                ignoreBlocker: true,
-              })
-            }
-          } else if (isNotFound(err)) {
-            notFound = err
-          }
-
-          const nextStatusCode = redirect
-            ? redirect.status
-            : notFound
-              ? 404
-              : this.stores.matches.get().some((d) => d.status === 'error')
-                ? 500
-                : 200
-
-          this.batch(() => {
-            this.stores.statusCode.set(nextStatusCode)
-            this.stores.redirect.set(redirect)
-          })
-        }
-
-        if (this.latestLoadPromise === loadPromise) {
-          this.commitLocationPromise?.resolve()
-          this.latestLoadPromise = undefined
-          this.commitLocationPromise = undefined
-        }
-
-        resolve()
-      })
-    })
-
-    this.latestLoadPromise = loadPromise
-
-    await loadPromise
-
-    while (
-      (this.latestLoadPromise as any) &&
-      loadPromise !== this.latestLoadPromise
-    ) {
-      await this.latestLoadPromise
+    if (isServer ?? this.isServer) {
+      return loadServerRoute(this, opts)
     }
 
-    let newStatusCode: number | undefined = undefined
-    if (this.hasNotFoundMatch()) {
-      newStatusCode = 404
-    } else if (this.stores.matches.get().some((d) => d.status === 'error')) {
-      newStatusCode = 500
-    }
-    if (newStatusCode !== undefined) {
-      this.stores.statusCode.set(newStatusCode)
+    this.updateLatestLocation()
+    if (opts?.action) {
+      this._scroll.hash =
+        opts.action.type === 'PUSH' || opts.action.type === 'REPLACE'
     }
+    await loadClientRoute(this, opts)
   }
 
   startViewTransition = (fn: () => Promise<void>) => {
@@ -2674,9 +2411,8 @@ export class RouterCore<
     // Attempt to start a view transition (or just apply the changes if we can't)
     if (
       shouldViewTransition &&
-      typeof document !== 'undefined' &&
-      'startViewTransition' in document &&
-      typeof document.startViewTransition === 'function'
+      !(isServer ?? typeof document === 'undefined') &&
+      typeof (document as any).startViewTransition === 'function'
     ) {
       // lib.dom.ts doesn't support viewTransition types variant yet.
       // TODO: Fix this when dom types are updated
@@ -2684,7 +2420,7 @@ export class RouterCore<
 
       if (
         typeof shouldViewTransition === 'object' &&
-        this.isViewTransitionTypesSupported
+        window.CSS?.supports?.('selector(:active-view-transition-type(a))')
       ) {
         const next = this.latestLocation
         const prevLocation = this.stores.resolvedLocation.get()
@@ -2697,8 +2433,7 @@ export class RouterCore<
             : shouldViewTransition.types
 
         if (resolvedViewTransitionTypes === false) {
-          fn()
-          return
+          return fn()
         }
 
         startViewTransitionParams = {
@@ -2709,58 +2444,19 @@ export class RouterCore<
         startViewTransitionParams = fn
       }
 
-      document.startViewTransition(startViewTransitionParams)
-    } else {
-      fn()
+      return (document as any).startViewTransition(startViewTransitionParams)
+        .updateCallbackDone
     }
-  }
-
-  updateMatch: UpdateMatchFn = (id, updater) => {
-    this.startTransition(() => {
-      const pendingMatch = this.stores.pendingMatchStores.get(id)
-      if (pendingMatch) {
-        pendingMatch.set(updater)
-        return
-      }
-
-      const activeMatch = this.stores.matchStores.get(id)
-      if (activeMatch) {
-        activeMatch.set(updater)
-        return
-      }
-
-      const cachedMatch = this.stores.cachedMatchStores.get(id)
-      if (cachedMatch) {
-        const next = updater(cachedMatch.get())
-        if (next.status === 'redirected') {
-          const deleted = this.stores.cachedMatchStores.delete(id)
-          if (deleted) {
-            this.stores.cachedIds.set((prev) =>
-              prev.filter((matchId) => matchId !== id),
-            )
-          }
-        } else {
-          cachedMatch.set(next)
-        }
-      }
-    })
-  }
-
-  getMatch: GetMatchFn = (matchId: string): AnyRouteMatch | undefined => {
-    return (
-      this.stores.cachedMatchStores.get(matchId)?.get() ??
-      this.stores.pendingMatchStores.get(matchId)?.get() ??
-      this.stores.matchStores.get(matchId)?.get()
-    )
+    return fn()
   }
 
   /**
    * Invalidate the current matches and optionally force them back into a pending state.
    *
    * - Marks all matches that pass the optional `filter` as `invalid: true`.
-   * - If `forcePending` is true, or a match is currently in `'error'` or `'notFound'` status,
-   *   its status is reset to `'pending'` and its `error` cleared so that the loader is re-run
-   *   on the next `load()` call (eg. after HMR or a manual invalidation).
+   *
+   * The next load decides when to publish pending UI, so invalidation does not
+   * mutate the currently rendered status.
    */
   invalidate: InvalidateFn<
     RouterCore<
@@ -2771,44 +2467,54 @@ export class RouterCore<
       TDehydrated
     >
   > = (opts) => {
+    const committedMatches = this._committed
+    const filter = opts?.filter
+    const invalidIds = filter
+      ? new Set(
+          [...committedMatches, ...this._cache.values()]
+            .filter((match) => filter(match as MakeRouteMatchUnion<this>))
+            .map((match) => match.id),
+        )
+      : undefined
     const invalidate = (d: MakeRouteMatch<TRouteTree>) => {
-      if (opts?.filter?.(d as MakeRouteMatchUnion<this>) ?? true) {
-        return {
+      if (!invalidIds || invalidIds.has(d.id)) {
+        const route = this.routesById[d.routeId] as AnyRoute
+        const next = {
           ...d,
           invalid: true,
-          ...(opts?.forcePending ||
-          d.status === 'error' ||
-          d.status === 'notFound'
+          ...((opts?.forcePending ||
+            d.status === 'error' ||
+            d.status === 'notFound') &&
+          routeNeedsLoad(route)
             ? ({ status: 'pending', error: undefined } as const)
             : undefined),
         }
+        // Invalidation replaces this owner; it does not create another lease.
+        ;(d as AnyRouteMatch & { _flight?: LoaderFlight })._flight = undefined
+        return next
       }
       return d
     }
 
-    this.batch(() => {
-      this.stores.setMatches(this.stores.matches.get().map(invalidate))
-      this.stores.setCached(this.stores.cachedMatches.get().map(invalidate))
-      this.stores.setPending(this.stores.pendingMatches.get().map(invalidate))
-    })
+    const committed = committedMatches.map(invalidate)
+    this._committed = committed
+    const cache = new Map<string, AnyRouteMatch>()
+    for (const [id, match] of this._cache) {
+      cache.set(id, invalidate(match))
+    }
+    this._cache = cache
 
     this.shouldViewTransition = false
     return this.load({ sync: opts?.sync })
   }
 
-  getParsedLocationHref = (location: ParsedLocation) => {
-    // For redirects and external use, we need publicHref (with rewrite output applied)
-    // href is the internal path after rewrite input, publicHref is user-facing
-    return location.publicHref || '/'
-  }
-
   resolveRedirect = (redirect: AnyRedirect): AnyRedirect => {
     const locationHeader = redirect.headers.get('Location')
 
     if (!redirect.options.href || redirect.options._builtLocation) {
       const location =
         redirect.options._builtLocation ?? this.buildLocation(redirect.options)
-      const href = this.getParsedLocationHref(location)
+      const href = location.publicHref || '/'
       redirect.options.href = href
       redirect.headers.set('Location', href)
     } else if (locationHeader) {
@@ -2845,43 +2551,37 @@ export class RouterCore<
   }
 
   clearCache: ClearCacheFn<this> = (opts) => {
+    const cached = this._cache
+    const preloads = this._preloads
     const filter = opts?.filter
-    if (filter !== undefined) {
-      this.stores.setCached(
-        this.stores.cachedMatches
-          .get()
-          .filter((m) => !filter(m as MakeRouteMatchUnion<this>)),
-      )
-    } else {
-      this.stores.setCached([])
+    const retained = new Map<string, AnyRouteMatch>()
+    const discarded: Array<AnyRouteMatch> = []
+    for (const [id, match] of cached) {
+      if (filter && !filter(match as MakeRouteMatchUnion<this>)) {
+        retained.set(id, match)
+      } else {
+        discarded.push(match)
+      }
     }
-  }
-
-  clearExpiredCache = () => {
-    const now = Date.now()
-    // This is where all of the garbage collection magic happens
-    const filter = (d: MakeRouteMatch<TRouteTree>) => {
-      const route = this.looseRoutesById[d.routeId]!
-
-      if (!route.options.loader) {
-        return true
+    const retainedPreloads = new Map<string, ActivePreload>()
+    const discardedPreloads: Array<ActivePreload> = []
+    for (const [href, preload] of preloads ?? []) {
+      if (!filter || preload[0].some(filter as any)) {
+        discardedPreloads.push(preload)
+        discarded.push(...preload[0])
+      } else {
+        retainedPreloads.set(href, preload)
       }
+    }
 
-      // If the route was preloaded, use the preloadGcTime
-      // otherwise, use the gcTime
-      const gcTime =
-        (d.preload
-          ? (route.options.preloadGcTime ?? this.options.defaultPreloadGcTime)
-          : (route.options.gcTime ?? this.options.defaultGcTime)) ??
-        5 * 60 * 1000
-
-      const isError = d.status === 'error'
-      if (isError) return true
-
-      const gcEligible = now - d.updatedAt >= gcTime
-      return gcEligible
+    // Install both replacement authorities before releasing a public loader
+    // signal, whose abort listeners can synchronously reenter the router.
+    this._cache = retained
+    this._preloads = retainedPreloads
+    transferMatchResources(this, discarded)
+    for (const preload of discardedPreloads) {
+      preload[1].abort()
     }
-    this.clearCache({ filter })
   }
 
   loadRouteChunk = loadRouteChunk
@@ -2891,69 +2591,7 @@ export class RouterCore<
     TTrailingSlashOption,
     TDefaultStructuralSharingOption,
     TRouterHistory
-  > = async (opts) => {
-    const next = opts._builtLocation ?? this.buildLocation(opts as any)
-
-    let matches = this.matchRoutes(next, {
-      throwOnError: true,
-      preload: true,
-      dest: opts,
-    })
-
-    const activeMatchIds = new Set([
-      ...this.stores.matchesId.get(),
-      ...this.stores.pendingIds.get(),
-    ])
-
-    const loadedMatchIds = new Set([
-      ...activeMatchIds,
-      ...this.stores.cachedIds.get(),
-    ])
-
-    // If the matches are already loaded, we need to add them to the cached matches.
-    const matchesToCache = matches.filter(
-      (match) => !loadedMatchIds.has(match.id),
-    )
-    if (matchesToCache.length) {
-      const cachedMatches = this.stores.cachedMatches.get()
-      this.stores.setCached([...cachedMatches, ...matchesToCache])
-    }
-
-    try {
-      matches = await loadMatches({
-        router: this,
-        matches,
-        location: next,
-        preload: true,
-        updateMatch: (id, updater) => {
-          // Don't update the match if it's currently loaded
-          if (activeMatchIds.has(id)) {
-            matches = matches.map((d) => (d.id === id ? updater(d) : d))
-          } else {
-            this.updateMatch(id, updater)
-          }
-        },
-      })
-
-      return matches
-    } catch (err) {
-      if (isRedirect(err)) {
-        if (err.options.reloadDocument) {
-          return undefined
-        }
-
-        return await this.preloadRoute({
-          ...err.options,
-          _fromLocation: next,
-        })
-      }
-      if (!isNotFound(err)) {
-        // Preload errors are not fatal, but we should still log them
-        console.error(err)
-      }
-      return undefined
-    }
-  }
+  > = (opts) => preloadClientRoute(this, opts)
 
   matchRoute: MatchRouteFn<
     TRouteTree,
@@ -2971,12 +2609,12 @@ export class RouterCore<
     }
     const next = this.buildLocation(matchLocation as any)
 
-    if (opts?.pending && this.stores.status.get() !== 'pending') {
+    const isPending = this.stores.status.get() === 'pending'
+    if (opts?.pending && !isPending) {
       return false
     }
 
-    const pending =
-      opts?.pending === undefined ? !this.stores.isLoading.get() : opts.pending
+    const pending = opts?.pending ?? !isPending
 
     const baseLocation = pending
       ? this.latestLocation
@@ -3016,11 +2654,19 @@ export class RouterCore<
   serverSsr?: ServerSsr
 
   serverSsrLifecycle?: RouterSsrLifecycle
+}
 
-  hasNotFoundMatch = () => {
-    return this.stores.matches
-      .get()
-      .some((d) => d.status === 'notFound' || d.globalNotFound)
+/**
+ * In non-production environments,
+ * augment the RouterCore class with a `_refreshRoute` method
+ * dedicated to HMR.
+ */
+if (process.env.NODE_ENV !== 'production') {
+  RouterCore.prototype._replaceRouteChunk = replaceRouteChunk
+  RouterCore.prototype._refreshRoute = async function () {
+    this._serverResult = undefined
+    this.updateLatestLocation()
+    await refreshClientRoute(this)
   }
 }
 
@@ -3057,14 +2703,11 @@ export function getInitialRouterState(
   location: ParsedLocation,
 ): RouterState<any> {
   return {
-    loadedAt: 0,
     isLoading: false,
-    isTransitioning: false,
     status: 'idle',
     resolvedLocation: undefined,
     location,
     matches: [],
-    statusCode: 200,
   }
 }
 
@@ -3096,56 +2739,12 @@ function validateSearch(validateSearch: AnyValidator, input: unknown): unknown {
   return {}
 }
 
-/**
- * Build the matched route chain and extract params for a pathname.
- * Falls back to the root route if no specific route is found.
- */
-export function getMatchedRoutes<TRouteLike extends RouteLike>({
-  pathname,
-  routesById,
-  processedTree,
-}: {
-  pathname: string
-  routesById: Record<string, TRouteLike>
-  processedTree: ProcessedTree<any, any, any>
-}) {
-  const routeParams: Record<string, string> = Object.create(null)
-  const trimmedPath = trimPathRight(pathname)
-
-  let foundRoute: TRouteLike | undefined = undefined
-  const match = findRouteMatch<TRouteLike>(trimmedPath, processedTree, true)
-  if (match) {
-    foundRoute = match.route
-    Object.assign(routeParams, match.rawParams) // Copy params, because they're cached
-  }
-
-  const matchedRoutes = match?.branch || [routesById[rootRouteId]!]
-
-  return { matchedRoutes, routeParams, foundRoute }
-}
-
-/**
- * TODO: once caches are persisted across requests on the server,
- * we can cache the built middleware chain using `last(destRoutes)` as the key
- */
-function applySearchMiddleware({
-  search,
-  dest,
-  destRoutes,
-  _includeValidateSearch,
-}: {
-  search: any
-  dest: { search?: unknown }
-  destRoutes: ReadonlyArray<AnyRoute>
-  _includeValidateSearch: boolean | undefined
-}) {
-  const middleware = buildMiddlewareChain(destRoutes)
-  return middleware(search, dest, _includeValidateSearch ?? false)
-}
-
-function buildMiddlewareChain(destRoutes: ReadonlyArray<AnyRoute>) {
-  let dest: BuildNextOptions
-  let includeValidateSearch: boolean | undefined
+function applySearchMiddleware(
+  search: any,
+  dest: BuildNextOptions,
+  destRoutes: ReadonlyArray<AnyRoute>,
+  includeValidateSearch: boolean | undefined,
+) {
   const middlewares = [] as Array<SearchMiddleware<any>>
 
   for (const route of destRoutes) {
@@ -3238,15 +2837,7 @@ function buildMiddlewareChain(destRoutes: ReadonlyArray<AnyRoute>) {
     return (middlewares[index]! as any)({ search: currentSearch, next, meta })
   }
 
-  return function middleware(
-    search: any,
-    nextDest: BuildNextOptions,
-    _includeValidateSearch: boolean,
-  ) {
-    dest = nextDest
-    includeValidateSearch = _includeValidateSearch
-    return applyNext(0, search)
-  }
+  return applyNext(0, search)
 }
 
 function findGlobalNotFoundRouteId(
@@ -3254,26 +2845,41 @@ function findGlobalNotFoundRouteId(
   routes: ReadonlyArray<AnyRoute>,
 ) {
   if (notFoundMode !== 'root') {
+    let fallback
     for (let i = routes.length - 1; i >= 0; i--) {
       const route = routes[i]!
-      if (route.children) {
+      if (route.options.notFoundComponent) {
         return route.id
       }
+      fallback ||= route.children && route.id
+    }
+    if (fallback) {
+      return fallback
     }
   }
   return rootRouteId
 }
 
+function resolveNextParams(
+  spec: unknown,
+  base: Record<string, unknown>,
+): Record<string, unknown> {
+  return spec === false || spec === null
+    ? Object.create(null)
+    : (spec ?? true) === true
+      ? base
+      : Object.assign(base, functionalUpdate(spec as any, base))
+}
+
 function extractStrictParams(
   route: AnyRoute,
   accumulatedParams: Record<string, unknown>,
 ) {
   const parseParams = route.options.params?.parse ?? route.options.parseParams
   if (parseParams) {
-    const result = parseParams(accumulatedParams as Record<string, string>)
-    if (result === false) {
-      throw new Error('Route params.parse returned false for a matched route')
-    }
-    Object.assign(accumulatedParams, result)
+    Object.assign(
+      accumulatedParams,
+      parseParams(accumulatedParams as Record<string, string>),
+    )
   }
 }