@tanstack/router-core 1.132.0-alpha.2 → 1.132.0-alpha.21

package/src/router.ts

@@ -1,17 +1,12 @@
 import { Store, batch } from '@tanstack/store'
-import {
-  createBrowserHistory,
-  createMemoryHistory,
-  parseHref,
-} from '@tanstack/history'
+import { createBrowserHistory, parseHref } from '@tanstack/history'
 import invariant from 'tiny-invariant'
 import {
   createControlledPromise,
   deepEqual,
+  findLast,
   functionalUpdate,
-  isPromise,
   last,
-  pick,
   replaceEqualDeep,
 } from './utils'
 import {
@@ -21,7 +16,6 @@ import {
   SEGMENT_TYPE_WILDCARD,
   cleanPath,
   interpolatePath,
-  joinPaths,
   matchPathname,
   parsePathname,
   resolvePath,
@@ -35,6 +29,13 @@ import { defaultParseSearch, defaultStringifySearch } from './searchParams'
 import { rootRouteId } from './root'
 import { isRedirect, redirect } from './redirect'
 import { createLRUCache } from './lru-cache'
+import { loadMatches, loadRouteChunk, routeNeedsPreload } from './load-matches'
+import {
+  composeRewrites,
+  executeRewriteInput,
+  executeRewriteOutput,
+  rewriteBasepath,
+} from './rewrite'
 import type { ParsePathnameCache, Segment } from './path'
 import type { SearchParser, SearchSerializer } from './searchParams'
 import type { AnyRedirect, ResolvedRedirect } from './redirect'
@@ -46,6 +47,7 @@ import type {
 } from '@tanstack/history'
 import type {
   Awaitable,
+  Constrain,
   ControlledPromise,
   NoInfer,
   NonNullableUpdater,
@@ -57,13 +59,10 @@ import type {
   AnyContext,
   AnyRoute,
   AnyRouteWithContext,
-  BeforeLoadContextOptions,
-  LoaderFnContext,
   MakeRemountDepsOptionsUnion,
   RouteContextOptions,
   RouteMask,
   SearchMiddleware,
-  SsrContextOptions,
 } from './route'
 import type {
   FullSearchSchema,
@@ -87,6 +86,11 @@ import type { Manifest } 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,
+} from './ssr/serializer/transformer'
+import type { AnyRouterConfig } from './config'
 
 export type ControllablePromise<T = any> = Promise<T> & {
   resolve: (value: T) => void
@@ -97,6 +101,8 @@ export type InjectedHtmlEntry = Promise<string>
 
 export interface DefaultRegister {
   router: AnyRouter
+  config: AnyRouterConfig
+  ssr: SSROption
 }
 
 export interface Register extends DefaultRegister {
@@ -114,12 +120,14 @@ export interface DefaultRouterOptionsExtensions {}
 export interface RouterOptionsExtensions
   extends DefaultRouterOptionsExtensions {}
 
+export type SSROption = boolean | 'data-only'
+
 export interface RouterOptions<
   TRouteTree extends AnyRoute,
   TTrailingSlashOption extends TrailingSlashOption,
   TDefaultStructuralSharingOption extends boolean = false,
   TRouterHistory extends RouterHistory = RouterHistory,
-  TDehydrated extends Record<string, any> = Record<string, any>,
+  TDehydrated = undefined,
 > extends RouterOptionsExtensions {
   /**
    * The history object that will be used to manage the browser history.
@@ -264,6 +272,18 @@ export interface RouterOptions<
   /**
    * The basepath for then entire router. This is useful for mounting a router instance at a subpath.
    *
+   * @deprecated - use `rewrite.input` with the new `rewriteBasepath` utility instead:
+   * ```ts
+   * const router = createRouter({
+   *   routeTree,
+   *   rewrite: rewriteBasepath('/basepath')
+   *   // Or wrap existing rewrite functionality
+   *   rewrite: rewriteBasepath('/basepath', {
+   *     output: ({ url }) => {...},
+   *     input: ({ url }) => {...},
+   *   })
+   * })
+   * ```
    * @default '/'
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#basepath-property)
    */
@@ -287,7 +307,10 @@ export interface RouterOptions<
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#dehydrate-method)
    * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/external-data-loading#critical-dehydrationhydration)
    */
-  dehydrate?: () => Awaitable<TDehydrated>
+  dehydrate?: () => Constrain<
+    TDehydrated,
+    ValidateSerializableInput<Register, TDehydrated>
+  >
   /**
    * A function that will be called when the router is hydrated.
    *
@@ -357,7 +380,7 @@ export interface RouterOptions<
    *
    * @default true
    */
-  defaultSsr?: boolean | 'data-only'
+  defaultSsr?: SSROption
 
   search?: {
     /**
@@ -393,7 +416,9 @@ export interface RouterOptions<
    *
    * @default false
    */
-  scrollRestoration?: boolean
+  scrollRestoration?:
+    | boolean
+    | ((opts: { location: ParsedLocation }) => boolean)
 
   /**
    * A function that will be called to get the key for the scroll restoration cache.
@@ -424,8 +449,48 @@ export interface RouterOptions<
    * @default false
    */
   disableGlobalCatchBoundary?: boolean
+
+  serializationAdapters?: ReadonlyArray<AnySerializationAdapter>
+  /**
+   * Configures how the router will rewrite the location between the actual href and the internal href of the router.
+   *
+   * @default undefined
+   * @description You can provide a custom rewrite pair (in/out) or use the utilities like `rewriteBasepath` as a convenience for common use cases, or even do both!
+   * This is useful for basepath rewriting, shifting data from the origin to the path (for things like )
+   */
+  rewrite?: LocationRewrite
+  origin?: string
 }
 
+export type LocationRewrite = {
+  /**
+   * A function that will be called to rewrite the URL before it is interpreted by the router from the history instance.
+   * Utilities like `rewriteBasepath` are provided as a convenience for common use cases.
+   *
+   * @default undefined
+   */
+  input?: LocationRewriteFunction
+  /**
+   * A function that will be called to rewrite the URL before it is committed to the actual history instance from the router.
+   * Utilities like `rewriteBasepath` are provided as a convenience for common use cases.
+   *
+   * @default undefined
+   */
+  output?: LocationRewriteFunction
+}
+
+/**
+ * A function that will be called to rewrite the URL.
+ *
+ * @param url The URL to rewrite.
+ * @returns The rewritten URL (as a URL instance or full href string) or undefined if no rewrite is needed.
+ */
+export type LocationRewriteFunction = ({
+  url,
+}: {
+  url: URL
+}) => undefined | string | URL
+
 export interface RouterState<
   in out TRouteTree extends AnyRoute = AnyRoute,
   in out TRouteMatch = MakeRouteMatchUnion,
@@ -615,8 +680,8 @@ export type InvalidateFn<TRouter extends AnyRouter> = (opts?: {
 }) => Promise<void>
 
 export type ParseLocationFn<TRouteTree extends AnyRoute> = (
+  locationToParse: HistoryLocation,
   previousLocation?: ParsedLocation<FullSearchSchema<TRouteTree>>,
-  locationToParse?: HistoryLocation,
 ) => ParsedLocation<FullSearchSchema<TRouteTree>>
 
 export type GetMatchRoutesFn = (
@@ -706,6 +771,7 @@ export interface ViewTransitionOptions {
       }) => Array<string>)
 }
 
+// TODO where is this used? can we remove this?
 export function defaultSerializeError(err: unknown) {
   if (err instanceof Error) {
     const obj = {
@@ -763,18 +829,6 @@ export type CreateRouterFn = <
   TDehydrated
 >
 
-type InnerLoadContext = {
-  location: ParsedLocation
-  firstBadMatchIndex?: number
-  rendered?: boolean
-  updateMatch: UpdateMatchFn
-  matches: Array<AnyRouteMatch>
-  preload?: boolean
-  onReady?: () => Promise<void>
-  sync?: boolean
-  matchPromises: Array<Promise<AnyRouteMatch>>
-}
-
 export class RouterCore<
   in out TRouteTree extends AnyRoute,
   in out TTrailingSlashOption extends TrailingSlashOption,
@@ -807,7 +861,10 @@ export class RouterCore<
     'stringifySearch' | 'parseSearch' | 'context'
   >
   history!: TRouterHistory
+  rewrite?: LocationRewrite
+  origin?: string
   latestLocation!: ParsedLocation<FullSearchSchema<TRouteTree>>
+  // @deprecated - basepath functionality is now implemented via the `rewrite` option
   basepath!: string
   routeTree!: TRouteTree
   routesById!: RoutesById<TRouteTree>
@@ -871,7 +928,6 @@ export class RouterCore<
       )
     }
 
-    const previousOptions = this.options
     this.options = {
       ...this.options,
       ...newOptions,
@@ -889,32 +945,42 @@ export class RouterCore<
       : undefined
 
     if (
-      !this.basepath ||
-      (newOptions.basepath && newOptions.basepath !== previousOptions.basepath)
+      !this.history ||
+      (this.options.history && this.options.history !== this.history)
     ) {
-      if (
-        newOptions.basepath === undefined ||
-        newOptions.basepath === '' ||
-        newOptions.basepath === '/'
-      ) {
-        this.basepath = '/'
+      if (!this.options.history) {
+        if (!this.isServer) {
+          this.history = createBrowserHistory() as TRouterHistory
+        }
       } else {
-        this.basepath = `/${trimPath(newOptions.basepath)}`
+        this.history = this.options.history
       }
     }
+    // For backwards compatibility, we support a basepath option, which we now implement as a rewrite
+    if (this.options.basepath) {
+      const basepathRewrite = rewriteBasepath({
+        basepath: this.options.basepath,
+      })
+      if (this.options.rewrite) {
+        this.rewrite = composeRewrites([basepathRewrite, this.options.rewrite])
+      } else {
+        this.rewrite = basepathRewrite
+      }
+    } else {
+      this.rewrite = this.options.rewrite
+    }
 
-    if (
-      !this.history ||
-      (this.options.history && this.options.history !== this.history)
-    ) {
-      this.history =
-        this.options.history ??
-        ((this.isServer
-          ? createMemoryHistory({
-              initialEntries: [this.basepath || '/'],
-            })
-          : createBrowserHistory()) as TRouterHistory)
-      this.latestLocation = this.parseLocation()
+    this.origin = this.options.origin
+    if (!this.origin) {
+      if (!this.isServer) {
+        this.origin = window.origin
+      } else {
+        // fallback for the server, can be overridden by calling router.update({origin}) on the server
+        this.origin = 'http://localhost'
+      }
+    }
+    if (this.history) {
+      this.updateLatestLocation()
     }
 
     if (this.options.routeTree !== this.routeTree) {
@@ -922,7 +988,7 @@ export class RouterCore<
       this.buildRouteTree()
     }
 
-    if (!this.__store) {
+    if (!this.__store && this.latestLocation) {
       this.__store = new Store(getInitialRouterState(this.latestLocation), {
         onUpdate: () => {
           this.__store.state = {
@@ -948,10 +1014,17 @@ export class RouterCore<
     }
   }
 
-  get state() {
+  get state(): RouterState<TRouteTree> {
     return this.__store.state
   }
 
+  updateLatestLocation = () => {
+    this.latestLocation = this.parseLocation(
+      this.history.location,
+      this.latestLocation,
+    )
+  }
+
   buildRouteTree = () => {
     const { routesById, routesByPath, flatRoutes } = processRouteTree({
       routeTree: this.routeTree,
@@ -998,29 +1071,41 @@ export class RouterCore<
   }
 
   parseLocation: ParseLocationFn<TRouteTree> = (
-    previousLocation,
     locationToParse,
+    previousLocation,
   ) => {
     const parse = ({
-      pathname,
-      search,
-      hash,
+      href,
       state,
     }: HistoryLocation): ParsedLocation<FullSearchSchema<TRouteTree>> => {
-      const parsedSearch = this.options.parseSearch(search)
+      // Before we do any processing, we need to allow rewrites to modify the URL
+      // build up the full URL by combining the href from history with the router's origin
+      const fullUrl = new URL(href, this.origin)
+      const url = executeRewriteInput(this.rewrite, fullUrl)
+
+      const parsedSearch = this.options.parseSearch(url.search)
       const searchStr = this.options.stringifySearch(parsedSearch)
+      // Make sure our final url uses the re-stringified pathname, search, and has for consistency
+      // (We were already doing this, so just keeping it for now)
+      url.search = searchStr
+
+      const fullPath = url.href.replace(url.origin, '')
+
+      const { pathname, hash } = url
 
       return {
+        href: fullPath,
+        publicHref: href,
+        url: url.href,
         pathname,
         searchStr,
         search: replaceEqualDeep(previousLocation?.search, parsedSearch) as any,
         hash: hash.split('#').reverse()[0] ?? '',
-        href: `${pathname}${searchStr}${hash}`,
         state: replaceEqualDeep(previousLocation?.state, state),
       }
     }
 
-    const location = parse(locationToParse ?? this.history.location)
+    const location = parse(locationToParse)
 
     const { __tempLocation, __tempKey } = location.state
 
@@ -1043,11 +1128,9 @@ export class RouterCore<
 
   resolvePathWithBase = (from: string, path: string) => {
     const resolvedPath = resolvePath({
-      basepath: this.basepath,
       base: from,
       to: cleanPath(path),
       trailingSlash: this.options.trailingSlash,
-      caseSensitive: this.options.caseSensitive,
       parseCache: this.parsePathnameCache,
     })
     return resolvedPath
@@ -1119,33 +1202,6 @@ export class RouterCore<
       return rootRouteId
     })()
 
-    const parseErrors = matchedRoutes.map((route) => {
-      let parsedParamsError
-
-      const parseParams =
-        route.options.params?.parse ?? route.options.parseParams
-
-      if (parseParams) {
-        try {
-          const parsedParams = parseParams(routeParams)
-          // Add the parsed params to the accumulated params bag
-          Object.assign(routeParams, parsedParams)
-        } catch (err: any) {
-          parsedParamsError = new PathParamError(err.message, {
-            cause: err,
-          })
-
-          if (opts?.throwOnError) {
-            throw parsedParamsError
-          }
-
-          return parsedParamsError
-        }
-      }
-
-      return
-    })
-
     const matches: Array<AnyRouteMatch> = []
 
     const getParentContext = (parentMatch?: AnyRouteMatch) => {
@@ -1218,12 +1274,18 @@ export class RouterCore<
 
       const loaderDepsHash = loaderDeps ? JSON.stringify(loaderDeps) : ''
 
-      const { usedParams, interpolatedPath } = interpolatePath({
+      const { interpolatedPath, usedParams } = interpolatePath({
         path: route.fullPath,
         params: routeParams,
         decodeCharMap: this.pathParamsDecodeCharMap,
       })
 
+      // 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
       const matchId =
         interpolatePath({
           path: route.id,
@@ -1233,18 +1295,40 @@ export class RouterCore<
           parseCache: this.parsePathnameCache,
         }).interpolatedPath + loaderDepsHash
 
-      // 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
       const existingMatch = this.getMatch(matchId)
 
       const previousMatch = this.state.matches.find(
         (d) => d.routeId === route.id,
       )
 
+      const strictParams = existingMatch?._strictParams ?? usedParams
+
+      let paramsError: PathParamError | undefined = undefined
+
+      if (!existingMatch) {
+        const strictParseParams =
+          route.options.params?.parse ?? route.options.parseParams
+
+        if (strictParseParams) {
+          try {
+            Object.assign(
+              strictParams,
+              strictParseParams(strictParams as Record<string, string>),
+            )
+          } catch (err: any) {
+            paramsError = new PathParamError(err.message, {
+              cause: err,
+            })
+
+            if (opts?.throwOnError) {
+              throw paramsError
+            }
+          }
+        }
+      }
+
+      Object.assign(routeParams, strictParams)
+
       const cause = previousMatch ? 'stay' : 'enter'
 
       let match: AnyRouteMatch
@@ -1256,7 +1340,7 @@ export class RouterCore<
           params: previousMatch
             ? replaceEqualDeep(previousMatch.params, routeParams)
             : routeParams,
-          _strictParams: usedParams,
+          _strictParams: strictParams,
           search: previousMatch
             ? replaceEqualDeep(previousMatch.search, preMatchSearch)
             : replaceEqualDeep(existingMatch.search, preMatchSearch),
@@ -1278,8 +1362,8 @@ export class RouterCore<
           params: previousMatch
             ? replaceEqualDeep(previousMatch.params, routeParams)
             : routeParams,
-          _strictParams: usedParams,
-          pathname: joinPaths([this.basepath, interpolatedPath]),
+          _strictParams: strictParams,
+          pathname: interpolatedPath,
           updatedAt: Date.now(),
           search: previousMatch
             ? replaceEqualDeep(previousMatch.search, preMatchSearch)
@@ -1289,7 +1373,7 @@ export class RouterCore<
           status,
           isFetching: false,
           error: undefined,
-          paramsError: parseErrors[index],
+          paramsError,
           __routeContext: undefined,
           _nonReactive: {
             loadPromise: createControlledPromise(),
@@ -1384,7 +1468,6 @@ export class RouterCore<
     return getMatchedRoutes({
       pathname,
       routePathname,
-      basepath: this.basepath,
       caseSensitive: this.options.caseSensitive,
       routesByPath: this.routesByPath,
       routesById: this.routesById,
@@ -1422,52 +1505,44 @@ export class RouterCore<
         _buildLocation: true,
       })
 
+      // Now let's find the starting pathname
+      // This should default to the current location if no from is provided
       const lastMatch = last(allCurrentLocationMatches)!
 
-      // First let's find the starting pathname
-      // By default, start with the current location
-      let fromPath = this.resolvePathWithBase(lastMatch.fullPath, '.')
-      const toPath = dest.to
-        ? this.resolvePathWithBase(fromPath, `${dest.to}`)
-        : this.resolvePathWithBase(fromPath, '.')
-
-      const routeIsChanging =
-        !!dest.to &&
-        !comparePaths(dest.to.toString(), fromPath) &&
-        !comparePaths(toPath, fromPath)
-
-      // If the route is changing we need to find the relative fromPath
-      if (dest.unsafeRelative === 'path') {
-        fromPath = currentLocation.pathname
-      } else if (routeIsChanging && dest.from) {
-        fromPath = dest.from
-
-        // do this check only on navigations during test or development
-        if (process.env.NODE_ENV !== 'production' && dest._isNavigate) {
-          const allFromMatches = this.getMatchedRoutes(
-            dest.from,
-            undefined,
-          ).matchedRoutes
+      // check that from path exists in the current route tree
+      // do this check only on navigations during test or development
+      if (
+        dest.from &&
+        process.env.NODE_ENV !== 'production' &&
+        dest._isNavigate
+      ) {
+        const allFromMatches = this.getMatchedRoutes(
+          dest.from,
+          undefined,
+        ).matchedRoutes
 
-          const matchedFrom = [...allCurrentLocationMatches]
-            .reverse()
-            .find((d) => {
-              return comparePaths(d.fullPath, fromPath)
-            })
+        const matchedFrom = findLast(allCurrentLocationMatches, (d) => {
+          return comparePaths(d.fullPath, dest.from!)
+        })
 
-          const matchedCurrent = [...allFromMatches].reverse().find((d) => {
-            return comparePaths(d.fullPath, currentLocation.pathname)
-          })
+        const matchedCurrent = findLast(allFromMatches, (d) => {
+          return comparePaths(d.fullPath, lastMatch.fullPath)
+        })
 
-          // for from to be invalid it shouldn't just be unmatched to currentLocation
-          // but the currentLocation should also be unmatched to from
-          if (!matchedFrom && !matchedCurrent) {
-            console.warn(`Could not find match for from: ${fromPath}`)
-          }
+        // for from to be invalid it shouldn't just be unmatched to currentLocation
+        // but the currentLocation should also be unmatched to from
+        if (!matchedFrom && !matchedCurrent) {
+          console.warn(`Could not find match for from: ${dest.from}`)
         }
       }
 
-      fromPath = this.resolvePathWithBase(fromPath, '.')
+      const defaultedFromPath =
+        dest.unsafeRelative === 'path'
+          ? currentLocation.pathname
+          : (dest.from ?? lastMatch.fullPath)
+
+      // ensure this includes the basePath if set
+      const fromPath = this.resolvePathWithBase(defaultedFromPath, '.')
 
       // From search should always use the current location
       const fromSearch = lastMatch.search
@@ -1475,25 +1550,26 @@ export class RouterCore<
       const fromParams = { ...lastMatch.params }
 
       // Resolve the next to
+      // ensure this includes the basePath if set
       const nextTo = dest.to
         ? this.resolvePathWithBase(fromPath, `${dest.to}`)
         : this.resolvePathWithBase(fromPath, '.')
 
       // Resolve the next params
-      let nextParams =
+      const nextParams =
         dest.params === false || dest.params === null
           ? {}
           : (dest.params ?? true) === true
             ? fromParams
-            : {
-                ...fromParams,
-                ...functionalUpdate(dest.params as any, fromParams),
-              }
+            : Object.assign(
+                fromParams,
+                functionalUpdate(dest.params as any, fromParams),
+              )
 
       // Interpolate the path first to get the actual resolved path, then match against that
       const interpolatedNextTo = interpolatePath({
         path: nextTo,
-        params: nextParams ?? {},
+        params: nextParams,
         parseCache: this.parsePathnameCache,
       }).interpolatedPath
 
@@ -1503,23 +1579,20 @@ export class RouterCore<
 
       // If there are any params, we need to stringify them
       if (Object.keys(nextParams).length > 0) {
-        destRoutes
-          .map((route) => {
-            return (
-              route.options.params?.stringify ?? route.options.stringifyParams
-            )
-          })
-          .filter(Boolean)
-          .forEach((fn) => {
-            nextParams = { ...nextParams!, ...fn!(nextParams) }
-          })
+        for (const route of destRoutes) {
+          const fn =
+            route.options.params?.stringify ?? route.options.stringifyParams
+          if (fn) {
+            Object.assign(nextParams, fn(nextParams))
+          }
+        }
       }
 
       const nextPathname = interpolatePath({
         // Use the original template path for interpolation
         // This preserves the original parameter syntax including optional parameters
         path: nextTo,
-        params: nextParams ?? {},
+        params: nextParams,
         leaveWildcards: false,
         leaveParams: opts.leaveParams,
         decodeCharMap: this.pathParamsDecodeCharMap,
@@ -1529,20 +1602,20 @@ export class RouterCore<
       // Resolve the next search
       let nextSearch = fromSearch
       if (opts._includeValidateSearch && this.options.search?.strict) {
-        let validatedSearch = {}
+        const validatedSearch = {}
         destRoutes.forEach((route) => {
-          try {
-            if (route.options.validateSearch) {
-              validatedSearch = {
-                ...validatedSearch,
-                ...(validateSearch(route.options.validateSearch, {
+          if (route.options.validateSearch) {
+            try {
+              Object.assign(
+                validatedSearch,
+                validateSearch(route.options.validateSearch, {
                   ...validatedSearch,
                   ...nextSearch,
-                }) ?? {}),
-              }
+                }),
+              )
+            } catch {
+              // ignore errors here because they are already handled in matchRoutes
             }
-          } catch {
-            // ignore errors here because they are already handled in matchRoutes
           }
         })
         nextSearch = validatedSearch
@@ -1583,14 +1656,25 @@ export class RouterCore<
       // Replace the equal deep
       nextState = replaceEqualDeep(currentLocation.state, nextState)
 
-      // Return the next location
+      // Create the full path of the location
+      const fullPath = `${nextPathname}${searchStr}${hashStr}`
+
+      // Create the new href with full origin
+      const url = new URL(fullPath, this.origin)
+
+      // If a rewrite function is provided, use it to rewrite the URL
+      const rewrittenUrl = executeRewriteOutput(this.rewrite, url)
+
       return {
+        publicHref:
+          rewrittenUrl.pathname + rewrittenUrl.search + rewrittenUrl.hash,
+        href: fullPath,
+        url: rewrittenUrl.href,
         pathname: nextPathname,
         search: nextSearch,
         searchStr,
         state: nextState as any,
         hash: hash ?? '',
-        href: `${nextPathname}${searchStr}${hashStr}`,
         unmaskOnReload: dest.unmaskOnReload,
       }
     }
@@ -1608,7 +1692,6 @@ export class RouterCore<
 
         const foundMask = this.options.routeMasks?.find((d) => {
           const match = matchPathname(
-            this.basepath,
             next.pathname,
             {
               to: d.from,
@@ -1629,7 +1712,7 @@ export class RouterCore<
         if (foundMask) {
           const { from: _from, ...maskProps } = foundMask
           maskedDest = {
-            ...pick(opts, ['from']),
+            from: opts.from,
             ...maskProps,
             params,
           }
@@ -1638,8 +1721,7 @@ export class RouterCore<
       }
 
       if (maskedNext) {
-        const maskedFinal = build(maskedDest)
-        next.maskedLocation = maskedFinal
+        next.maskedLocation = maskedNext
       }
 
       return next
@@ -1647,7 +1729,7 @@ export class RouterCore<
 
     if (opts.mask) {
       return buildWithMatches(opts, {
-        ...pick(opts, ['from']),
+        from: opts.from,
         ...opts.mask,
       })
     }
@@ -1682,7 +1764,8 @@ export class RouterCore<
       return isEqual
     }
 
-    const isSameUrl = this.latestLocation.href === next.href
+    const isSameUrl =
+      trimPathRight(this.latestLocation.href) === trimPathRight(next.href)
 
     const previousCommitPromise = this.commitLocationPromise
     this.commitLocationPromise = createControlledPromise<void>(() => {
@@ -1731,7 +1814,7 @@ export class RouterCore<
       this.shouldViewTransition = viewTransition
 
       this.history[next.replace ? 'replace' : 'push'](
-        nextHistory.href,
+        nextHistory.publicHref,
         nextHistory.state,
         { ignoreBlocker },
       )
@@ -1793,7 +1876,7 @@ export class RouterCore<
     if (reloadDocument) {
       if (!href) {
         const location = this.buildLocation({ to, ...rest } as any)
-        href = this.history.createHref(location.href)
+        href = location.href
       }
       if (rest.replace) {
         window.location.replace(href)
@@ -1816,7 +1899,7 @@ export class RouterCore<
   beforeLoad = () => {
     // Cancel any pending matches
     this.cancelMatches()
-    this.latestLocation = this.parseLocation(this.latestLocation)
+    this.updateLatestLocation()
 
     if (this.isServer) {
       // for SPAs on the initial load, this is handled by the Transitioner
@@ -1846,6 +1929,7 @@ export class RouterCore<
         throw redirect({ href: nextLocation.href })
       }
     }
+
     // Match the routes
     const pendingMatches = this.matchRoutes(this.latestLocation)
 
@@ -1895,10 +1979,12 @@ export class RouterCore<
             }),
           })
 
-          await this.loadMatches({
+          await loadMatches({
+            router: this,
             sync: opts?.sync,
             matches: this.state.pendingMatches as Array<AnyRouteMatch>,
             location: next,
+            updateMatch: this.updateMatch,
             // eslint-disable-next-line @typescript-eslint/require-await
             onReady: async () => {
               // eslint-disable-next-line @typescript-eslint/require-await
@@ -1989,6 +2075,7 @@ export class RouterCore<
           this.latestLoadPromise = undefined
           this.commitLocationPromise = undefined
         }
+
         resolve()
       })
     })
@@ -2088,873 +2175,6 @@ export class RouterCore<
     )
   }
 
-  private triggerOnReady = (
-    innerLoadContext: InnerLoadContext,
-  ): void | Promise<void> => {
-    if (!innerLoadContext.rendered) {
-      innerLoadContext.rendered = true
-      return innerLoadContext.onReady?.()
-    }
-  }
-
-  private resolvePreload = (
-    innerLoadContext: InnerLoadContext,
-    matchId: string,
-  ): boolean => {
-    return !!(
-      innerLoadContext.preload &&
-      !this.state.matches.some((d) => d.id === matchId)
-    )
-  }
-
-  private handleRedirectAndNotFound = (
-    innerLoadContext: InnerLoadContext,
-    match: AnyRouteMatch | undefined,
-    err: unknown,
-  ): void => {
-    if (!isRedirect(err) && !isNotFound(err)) return
-
-    if (isRedirect(err) && err.redirectHandled && !err.options.reloadDocument) {
-      throw err
-    }
-
-    // in case of a redirecting match during preload, the match does not exist
-    if (match) {
-      match._nonReactive.beforeLoadPromise?.resolve()
-      match._nonReactive.loaderPromise?.resolve()
-      match._nonReactive.beforeLoadPromise = undefined
-      match._nonReactive.loaderPromise = undefined
-
-      const status = isRedirect(err) ? 'redirected' : 'notFound'
-
-      innerLoadContext.updateMatch(match.id, (prev) => ({
-        ...prev,
-        status,
-        isFetching: false,
-        error: err,
-      }))
-
-      if (isNotFound(err) && !err.routeId) {
-        err.routeId = match.routeId
-      }
-
-      match._nonReactive.loadPromise?.resolve()
-    }
-
-    if (isRedirect(err)) {
-      innerLoadContext.rendered = true
-      err.options._fromLocation = innerLoadContext.location
-      err.redirectHandled = true
-      err = this.resolveRedirect(err)
-      throw err
-    } else {
-      this._handleNotFound(innerLoadContext, err)
-      throw err
-    }
-  }
-
-  private shouldSkipLoader = (matchId: string): boolean => {
-    const match = this.getMatch(matchId)!
-    // upon hydration, we skip the loader if the match has been dehydrated on the server
-    if (!this.isServer && match._nonReactive.dehydrated) {
-      return true
-    }
-
-    if (this.isServer) {
-      if (match.ssr === false) {
-        return true
-      }
-    }
-    return false
-  }
-
-  private handleSerialError = (
-    innerLoadContext: InnerLoadContext,
-    index: number,
-    err: any,
-    routerCode: string,
-  ): void => {
-    const { id: matchId, routeId } = innerLoadContext.matches[index]!
-    const route = this.looseRoutesById[routeId]!
-
-    // Much like suspense, we use a promise here to know if
-    // we've been outdated by a new loadMatches call and
-    // should abort the current async operation
-    if (err instanceof Promise) {
-      throw err
-    }
-
-    err.routerCode = routerCode
-    innerLoadContext.firstBadMatchIndex ??= index
-    this.handleRedirectAndNotFound(
-      innerLoadContext,
-      this.getMatch(matchId),
-      err,
-    )
-
-    try {
-      route.options.onError?.(err)
-    } catch (errorHandlerErr) {
-      err = errorHandlerErr
-      this.handleRedirectAndNotFound(
-        innerLoadContext,
-        this.getMatch(matchId),
-        err,
-      )
-    }
-
-    innerLoadContext.updateMatch(matchId, (prev) => {
-      prev._nonReactive.beforeLoadPromise?.resolve()
-      prev._nonReactive.beforeLoadPromise = undefined
-      prev._nonReactive.loadPromise?.resolve()
-
-      return {
-        ...prev,
-        error: err,
-        status: 'error',
-        isFetching: false,
-        updatedAt: Date.now(),
-        abortController: new AbortController(),
-      }
-    })
-  }
-
-  private isBeforeLoadSsr = (
-    innerLoadContext: InnerLoadContext,
-    matchId: string,
-    index: number,
-    route: AnyRoute,
-  ): void | Promise<void> => {
-    const existingMatch = this.getMatch(matchId)!
-    const parentMatchId = innerLoadContext.matches[index - 1]?.id
-    const parentMatch = parentMatchId
-      ? this.getMatch(parentMatchId)!
-      : undefined
-
-    // in SPA mode, only SSR the root route
-    if (this.isShell()) {
-      existingMatch.ssr = matchId === rootRouteId
-      return
-    }
-
-    if (parentMatch?.ssr === false) {
-      existingMatch.ssr = false
-      return
-    }
-
-    const parentOverride = (tempSsr: boolean | 'data-only') => {
-      if (tempSsr === true && parentMatch?.ssr === 'data-only') {
-        return 'data-only'
-      }
-      return tempSsr
-    }
-
-    const defaultSsr = this.options.defaultSsr ?? true
-
-    if (route.options.ssr === undefined) {
-      existingMatch.ssr = parentOverride(defaultSsr)
-      return
-    }
-
-    if (typeof route.options.ssr !== 'function') {
-      existingMatch.ssr = parentOverride(route.options.ssr)
-      return
-    }
-    const { search, params } = this.getMatch(matchId)!
-
-    const ssrFnContext: SsrContextOptions<any, any, any> = {
-      search: makeMaybe(search, existingMatch.searchError),
-      params: makeMaybe(params, existingMatch.paramsError),
-      location: innerLoadContext.location,
-      matches: innerLoadContext.matches.map((match) => ({
-        index: match.index,
-        pathname: match.pathname,
-        fullPath: match.fullPath,
-        staticData: match.staticData,
-        id: match.id,
-        routeId: match.routeId,
-        search: makeMaybe(match.search, match.searchError),
-        params: makeMaybe(match.params, match.paramsError),
-        ssr: match.ssr,
-      })),
-    }
-
-    const tempSsr = route.options.ssr(ssrFnContext)
-    if (isPromise(tempSsr)) {
-      return tempSsr.then((ssr) => {
-        existingMatch.ssr = parentOverride(ssr ?? defaultSsr)
-      })
-    }
-
-    existingMatch.ssr = parentOverride(tempSsr ?? defaultSsr)
-    return
-  }
-
-  private setupPendingTimeout = (
-    innerLoadContext: InnerLoadContext,
-    matchId: string,
-    route: AnyRoute,
-  ): void => {
-    const pendingMs = route.options.pendingMs ?? this.options.defaultPendingMs
-    const shouldPending = !!(
-      innerLoadContext.onReady &&
-      !this.isServer &&
-      !this.resolvePreload(innerLoadContext, matchId) &&
-      (route.options.loader ||
-        route.options.beforeLoad ||
-        routeNeedsPreload(route)) &&
-      typeof pendingMs === 'number' &&
-      pendingMs !== Infinity &&
-      (route.options.pendingComponent ??
-        (this.options as any)?.defaultPendingComponent)
-    )
-    const match = this.getMatch(matchId)!
-    if (shouldPending && match._nonReactive.pendingTimeout === undefined) {
-      const pendingTimeout = setTimeout(() => {
-        // Update the match and prematurely resolve the loadMatches promise so that
-        // the pending component can start rendering
-        this.triggerOnReady(innerLoadContext)
-      }, pendingMs)
-      match._nonReactive.pendingTimeout = pendingTimeout
-    }
-  }
-
-  private shouldExecuteBeforeLoad = (
-    innerLoadContext: InnerLoadContext,
-    matchId: string,
-    route: AnyRoute,
-  ): boolean | Promise<boolean> => {
-    const existingMatch = this.getMatch(matchId)!
-
-    // If we are in the middle of a load, either of these will be present
-    // (not to be confused with `loadPromise`, which is always defined)
-    if (
-      !existingMatch._nonReactive.beforeLoadPromise &&
-      !existingMatch._nonReactive.loaderPromise
-    )
-      return true
-
-    this.setupPendingTimeout(innerLoadContext, matchId, route)
-
-    const then = () => {
-      let shouldExecuteBeforeLoad = true
-      const match = this.getMatch(matchId)!
-      if (match.status === 'error') {
-        shouldExecuteBeforeLoad = true
-      } else if (
-        match.preload &&
-        (match.status === 'redirected' || match.status === 'notFound')
-      ) {
-        this.handleRedirectAndNotFound(innerLoadContext, match, match.error)
-      }
-      return shouldExecuteBeforeLoad
-    }
-
-    // Wait for the beforeLoad to resolve before we continue
-    return existingMatch._nonReactive.beforeLoadPromise
-      ? existingMatch._nonReactive.beforeLoadPromise.then(then)
-      : then()
-  }
-
-  private executeBeforeLoad = (
-    innerLoadContext: InnerLoadContext,
-    matchId: string,
-    index: number,
-    route: AnyRoute,
-  ): void | Promise<void> => {
-    const match = this.getMatch(matchId)!
-
-    match._nonReactive.beforeLoadPromise = createControlledPromise<void>()
-    // explicitly capture the previous loadPromise
-    const prevLoadPromise = match._nonReactive.loadPromise
-    match._nonReactive.loadPromise = createControlledPromise<void>(() => {
-      prevLoadPromise?.resolve()
-    })
-
-    const { paramsError, searchError } = match
-
-    if (paramsError) {
-      this.handleSerialError(
-        innerLoadContext,
-        index,
-        paramsError,
-        'PARSE_PARAMS',
-      )
-    }
-
-    if (searchError) {
-      this.handleSerialError(
-        innerLoadContext,
-        index,
-        searchError,
-        'VALIDATE_SEARCH',
-      )
-    }
-
-    this.setupPendingTimeout(innerLoadContext, matchId, route)
-
-    const abortController = new AbortController()
-
-    const parentMatchId = innerLoadContext.matches[index - 1]?.id
-    const parentMatch = parentMatchId
-      ? this.getMatch(parentMatchId)!
-      : undefined
-    const parentMatchContext =
-      parentMatch?.context ?? this.options.context ?? undefined
-
-    const context = { ...parentMatchContext, ...match.__routeContext }
-
-    let isPending = false
-    const pending = () => {
-      if (isPending) return
-      isPending = true
-      innerLoadContext.updateMatch(matchId, (prev) => ({
-        ...prev,
-        isFetching: 'beforeLoad',
-        fetchCount: prev.fetchCount + 1,
-        abortController,
-        context,
-      }))
-    }
-
-    const resolve = () => {
-      match._nonReactive.beforeLoadPromise?.resolve()
-      match._nonReactive.beforeLoadPromise = undefined
-      innerLoadContext.updateMatch(matchId, (prev) => ({
-        ...prev,
-        isFetching: false,
-      }))
-    }
-
-    // if there is no `beforeLoad` option, skip everything, batch update the store, return early
-    if (!route.options.beforeLoad) {
-      batch(() => {
-        pending()
-        resolve()
-      })
-      return
-    }
-
-    const { search, params, cause } = match
-    const preload = this.resolvePreload(innerLoadContext, matchId)
-    const beforeLoadFnContext: BeforeLoadContextOptions<
-      any,
-      any,
-      any,
-      any,
-      any
-    > = {
-      search,
-      abortController,
-      params,
-      preload,
-      context,
-      location: innerLoadContext.location,
-      navigate: (opts: any) =>
-        this.navigate({ ...opts, _fromLocation: innerLoadContext.location }),
-      buildLocation: this.buildLocation,
-      cause: preload ? 'preload' : cause,
-      matches: innerLoadContext.matches,
-    }
-
-    const updateContext = (beforeLoadContext: any) => {
-      if (beforeLoadContext === undefined) {
-        batch(() => {
-          pending()
-          resolve()
-        })
-        return
-      }
-      if (isRedirect(beforeLoadContext) || isNotFound(beforeLoadContext)) {
-        pending()
-        this.handleSerialError(
-          innerLoadContext,
-          index,
-          beforeLoadContext,
-          'BEFORE_LOAD',
-        )
-      }
-
-      batch(() => {
-        pending()
-        innerLoadContext.updateMatch(matchId, (prev) => ({
-          ...prev,
-          __beforeLoadContext: beforeLoadContext,
-          context: {
-            ...prev.context,
-            ...beforeLoadContext,
-          },
-        }))
-        resolve()
-      })
-    }
-
-    let beforeLoadContext
-    try {
-      beforeLoadContext = route.options.beforeLoad(beforeLoadFnContext)
-      if (isPromise(beforeLoadContext)) {
-        pending()
-        return beforeLoadContext
-          .catch((err) => {
-            this.handleSerialError(innerLoadContext, index, err, 'BEFORE_LOAD')
-          })
-          .then(updateContext)
-      }
-    } catch (err) {
-      pending()
-      this.handleSerialError(innerLoadContext, index, err, 'BEFORE_LOAD')
-    }
-
-    updateContext(beforeLoadContext)
-    return
-  }
-
-  private handleBeforeLoad = (
-    innerLoadContext: InnerLoadContext,
-    index: number,
-  ): void | Promise<void> => {
-    const { id: matchId, routeId } = innerLoadContext.matches[index]!
-    const route = this.looseRoutesById[routeId]!
-
-    const serverSsr = () => {
-      // on the server, determine whether SSR the current match or not
-      if (this.isServer) {
-        const maybePromise = this.isBeforeLoadSsr(
-          innerLoadContext,
-          matchId,
-          index,
-          route,
-        )
-        if (isPromise(maybePromise)) return maybePromise.then(queueExecution)
-      }
-      return queueExecution()
-    }
-
-    const queueExecution = () => {
-      if (this.shouldSkipLoader(matchId)) return
-      const shouldExecuteBeforeLoadResult = this.shouldExecuteBeforeLoad(
-        innerLoadContext,
-        matchId,
-        route,
-      )
-      return isPromise(shouldExecuteBeforeLoadResult)
-        ? shouldExecuteBeforeLoadResult.then(execute)
-        : execute(shouldExecuteBeforeLoadResult)
-    }
-
-    const execute = (shouldExecuteBeforeLoad: boolean) => {
-      if (shouldExecuteBeforeLoad) {
-        // If we are not in the middle of a load OR the previous load failed, start it
-        return this.executeBeforeLoad(innerLoadContext, matchId, index, route)
-      }
-      return
-    }
-
-    return serverSsr()
-  }
-
-  private executeHead = (
-    innerLoadContext: InnerLoadContext,
-    matchId: string,
-    route: AnyRoute,
-  ): void | Promise<
-    Pick<
-      AnyRouteMatch,
-      'meta' | 'links' | 'headScripts' | 'headers' | 'scripts' | 'styles'
-    >
-  > => {
-    const match = this.getMatch(matchId)
-    // in case of a redirecting match during preload, the match does not exist
-    if (!match) {
-      return
-    }
-    if (
-      !route.options.head &&
-      !route.options.scripts &&
-      !route.options.headers
-    ) {
-      return
-    }
-    const assetContext = {
-      matches: innerLoadContext.matches,
-      match,
-      params: match.params,
-      loaderData: match.loaderData,
-    }
-
-    return Promise.all([
-      route.options.head?.(assetContext),
-      route.options.scripts?.(assetContext),
-      route.options.headers?.(assetContext),
-    ]).then(([headFnContent, scripts, headers]) => {
-      const meta = headFnContent?.meta
-      const links = headFnContent?.links
-      const headScripts = headFnContent?.scripts
-      const styles = headFnContent?.styles
-
-      return {
-        meta,
-        links,
-        headScripts,
-        headers,
-        scripts,
-        styles,
-      }
-    })
-  }
-
-  private potentialPendingMinPromise = (
-    matchId: string,
-  ): void | ControlledPromise<void> => {
-    const latestMatch = this.getMatch(matchId)!
-    return latestMatch._nonReactive.minPendingPromise
-  }
-
-  private getLoaderContext = (
-    innerLoadContext: InnerLoadContext,
-    matchId: string,
-    index: number,
-    route: AnyRoute,
-  ): LoaderFnContext => {
-    const parentMatchPromise = innerLoadContext.matchPromises[index - 1] as any
-    const { params, loaderDeps, abortController, context, cause } =
-      this.getMatch(matchId)!
-
-    const preload = this.resolvePreload(innerLoadContext, matchId)
-
-    return {
-      params,
-      deps: loaderDeps,
-      preload: !!preload,
-      parentMatchPromise,
-      abortController: abortController,
-      context,
-      location: innerLoadContext.location,
-      navigate: (opts) =>
-        this.navigate({ ...opts, _fromLocation: innerLoadContext.location }),
-      cause: preload ? 'preload' : cause,
-      route,
-    }
-  }
-
-  private runLoader = async (
-    innerLoadContext: InnerLoadContext,
-    matchId: string,
-    index: number,
-    route: AnyRoute,
-  ): Promise<void> => {
-    try {
-      // If the Matches component rendered
-      // the pending component and needs to show it for
-      // a minimum duration, we''ll wait for it to resolve
-      // before committing to the match and resolving
-      // the loadPromise
-
-      // Actually run the loader and handle the result
-      try {
-        if (!this.isServer || this.getMatch(matchId)!.ssr === true) {
-          this.loadRouteChunk(route)
-        }
-
-        // Kick off the loader!
-        const loaderResult = route.options.loader?.(
-          this.getLoaderContext(innerLoadContext, matchId, index, route),
-        )
-        const loaderResultIsPromise =
-          route.options.loader && isPromise(loaderResult)
-
-        const willLoadSomething = !!(
-          loaderResultIsPromise ||
-          route._lazyPromise ||
-          route._componentsPromise ||
-          route.options.head ||
-          route.options.scripts ||
-          route.options.headers ||
-          this.getMatch(matchId)!._nonReactive.minPendingPromise
-        )
-
-        if (willLoadSomething) {
-          innerLoadContext.updateMatch(matchId, (prev) => ({
-            ...prev,
-            isFetching: 'loader',
-          }))
-        }
-
-        if (route.options.loader) {
-          const loaderData = loaderResultIsPromise
-            ? await loaderResult
-            : loaderResult
-
-          this.handleRedirectAndNotFound(
-            innerLoadContext,
-            this.getMatch(matchId),
-            loaderData,
-          )
-          if (loaderData !== undefined) {
-            innerLoadContext.updateMatch(matchId, (prev) => ({
-              ...prev,
-              loaderData,
-            }))
-          }
-        }
-
-        // Lazy option can modify the route options,
-        // so we need to wait for it to resolve before
-        // we can use the options
-        if (route._lazyPromise) await route._lazyPromise
-        const headResult = this.executeHead(innerLoadContext, matchId, route)
-        const head = headResult ? await headResult : undefined
-        const pendingPromise = this.potentialPendingMinPromise(matchId)
-        if (pendingPromise) await pendingPromise
-
-        // Last but not least, wait for the the components
-        // to be preloaded before we resolve the match
-        if (route._componentsPromise) await route._componentsPromise
-        innerLoadContext.updateMatch(matchId, (prev) => ({
-          ...prev,
-          error: undefined,
-          status: 'success',
-          isFetching: false,
-          updatedAt: Date.now(),
-          ...head,
-        }))
-      } catch (e) {
-        let error = e
-
-        const pendingPromise = this.potentialPendingMinPromise(matchId)
-        if (pendingPromise) await pendingPromise
-
-        this.handleRedirectAndNotFound(
-          innerLoadContext,
-          this.getMatch(matchId),
-          e,
-        )
-
-        try {
-          route.options.onError?.(e)
-        } catch (onErrorError) {
-          error = onErrorError
-          this.handleRedirectAndNotFound(
-            innerLoadContext,
-            this.getMatch(matchId),
-            onErrorError,
-          )
-        }
-        const headResult = this.executeHead(innerLoadContext, matchId, route)
-        const head = headResult ? await headResult : undefined
-        innerLoadContext.updateMatch(matchId, (prev) => ({
-          ...prev,
-          error,
-          status: 'error',
-          isFetching: false,
-          ...head,
-        }))
-      }
-    } catch (err) {
-      const match = this.getMatch(matchId)
-      // in case of a redirecting match during preload, the match does not exist
-      if (match) {
-        const headResult = this.executeHead(innerLoadContext, matchId, route)
-        if (headResult) {
-          const head = await headResult
-          innerLoadContext.updateMatch(matchId, (prev) => ({
-            ...prev,
-            ...head,
-          }))
-        }
-        match._nonReactive.loaderPromise = undefined
-      }
-      this.handleRedirectAndNotFound(innerLoadContext, match, err)
-    }
-  }
-
-  private loadRouteMatch = async (
-    innerLoadContext: InnerLoadContext,
-    index: number,
-  ): Promise<AnyRouteMatch> => {
-    const { id: matchId, routeId } = innerLoadContext.matches[index]!
-    let loaderShouldRunAsync = false
-    let loaderIsRunningAsync = false
-    const route = this.looseRoutesById[routeId]!
-
-    const prevMatch = this.getMatch(matchId)!
-    if (this.shouldSkipLoader(matchId)) {
-      if (this.isServer) {
-        const headResult = this.executeHead(innerLoadContext, matchId, route)
-        if (headResult) {
-          const head = await headResult
-          innerLoadContext.updateMatch(matchId, (prev) => ({
-            ...prev,
-            ...head,
-          }))
-        }
-        return this.getMatch(matchId)!
-      }
-    }
-    // there is a loaderPromise, so we are in the middle of a load
-    else if (prevMatch._nonReactive.loaderPromise) {
-      // do not block if we already have stale data we can show
-      // but only if the ongoing load is not a preload since error handling is different for preloads
-      // and we don't want to swallow errors
-      if (
-        prevMatch.status === 'success' &&
-        !innerLoadContext.sync &&
-        !prevMatch.preload
-      ) {
-        return this.getMatch(matchId)!
-      }
-      await prevMatch._nonReactive.loaderPromise
-      const match = this.getMatch(matchId)!
-      if (match.error) {
-        this.handleRedirectAndNotFound(innerLoadContext, match, match.error)
-      }
-    } else {
-      // This is where all of the stale-while-revalidate magic happens
-      const age = Date.now() - this.getMatch(matchId)!.updatedAt
-
-      const preload = this.resolvePreload(innerLoadContext, matchId)
-
-      const staleAge = preload
-        ? (route.options.preloadStaleTime ??
-          this.options.defaultPreloadStaleTime ??
-          30_000) // 30 seconds for preloads by default
-        : (route.options.staleTime ?? this.options.defaultStaleTime ?? 0)
-
-      const shouldReloadOption = route.options.shouldReload
-
-      // Default to reloading the route all the time
-      // Allow shouldReload to get the last say,
-      // if provided.
-      const shouldReload =
-        typeof shouldReloadOption === 'function'
-          ? shouldReloadOption(
-              this.getLoaderContext(innerLoadContext, matchId, index, route),
-            )
-          : shouldReloadOption
-
-      const nextPreload =
-        !!preload && !this.state.matches.some((d) => d.id === matchId)
-      const match = this.getMatch(matchId)!
-      match._nonReactive.loaderPromise = createControlledPromise<void>()
-      if (nextPreload !== match.preload) {
-        innerLoadContext.updateMatch(matchId, (prev) => ({
-          ...prev,
-          preload: nextPreload,
-        }))
-      }
-
-      // If the route is successful and still fresh, just resolve
-      const { status, invalid } = this.getMatch(matchId)!
-      loaderShouldRunAsync =
-        status === 'success' && (invalid || (shouldReload ?? age > staleAge))
-      if (preload && route.options.preload === false) {
-        // Do nothing
-      } else if (loaderShouldRunAsync && !innerLoadContext.sync) {
-        loaderIsRunningAsync = true
-        ;(async () => {
-          try {
-            await this.runLoader(innerLoadContext, matchId, index, route)
-            const match = this.getMatch(matchId)!
-            match._nonReactive.loaderPromise?.resolve()
-            match._nonReactive.loadPromise?.resolve()
-            match._nonReactive.loaderPromise = undefined
-          } catch (err) {
-            if (isRedirect(err)) {
-              await this.navigate(err.options)
-            }
-          }
-        })()
-      } else if (
-        status !== 'success' ||
-        (loaderShouldRunAsync && innerLoadContext.sync)
-      ) {
-        await this.runLoader(innerLoadContext, matchId, index, route)
-      } else {
-        // if the loader did not run, still update head.
-        // reason: parent's beforeLoad may have changed the route context
-        // and only now do we know the route context (and that the loader would not run)
-        const headResult = this.executeHead(innerLoadContext, matchId, route)
-        if (headResult) {
-          const head = await headResult
-          innerLoadContext.updateMatch(matchId, (prev) => ({
-            ...prev,
-            ...head,
-          }))
-        }
-      }
-    }
-    const match = this.getMatch(matchId)!
-    if (!loaderIsRunningAsync) {
-      match._nonReactive.loaderPromise?.resolve()
-      match._nonReactive.loadPromise?.resolve()
-    }
-
-    clearTimeout(match._nonReactive.pendingTimeout)
-    match._nonReactive.pendingTimeout = undefined
-    if (!loaderIsRunningAsync) match._nonReactive.loaderPromise = undefined
-    match._nonReactive.dehydrated = undefined
-    const nextIsFetching = loaderIsRunningAsync ? match.isFetching : false
-    if (nextIsFetching !== match.isFetching || match.invalid !== false) {
-      innerLoadContext.updateMatch(matchId, (prev) => ({
-        ...prev,
-        isFetching: nextIsFetching,
-        invalid: false,
-      }))
-    }
-    return this.getMatch(matchId)!
-  }
-
-  loadMatches = async (baseContext: {
-    location: ParsedLocation
-    matches: Array<AnyRouteMatch>
-    preload?: boolean
-    onReady?: () => Promise<void>
-    updateMatch?: UpdateMatchFn
-    sync?: boolean
-  }): Promise<Array<MakeRouteMatch>> => {
-    const innerLoadContext = baseContext as InnerLoadContext
-    innerLoadContext.updateMatch ??= this.updateMatch
-    innerLoadContext.matchPromises = []
-
-    // make sure the pending component is immediately rendered when hydrating a match that is not SSRed
-    // the pending component was already rendered on the server and we want to keep it shown on the client until minPendingMs is reached
-    if (!this.isServer && this.state.matches.some((d) => d._forcePending)) {
-      this.triggerOnReady(innerLoadContext)
-    }
-
-    try {
-      // Execute all beforeLoads one by one
-      for (let i = 0; i < innerLoadContext.matches.length; i++) {
-        const beforeLoad = this.handleBeforeLoad(innerLoadContext, i)
-        if (isPromise(beforeLoad)) await beforeLoad
-      }
-
-      // Execute all loaders in parallel
-      const max =
-        innerLoadContext.firstBadMatchIndex ?? innerLoadContext.matches.length
-      for (let i = 0; i < max; i++) {
-        innerLoadContext.matchPromises.push(
-          this.loadRouteMatch(innerLoadContext, i),
-        )
-      }
-      await Promise.all(innerLoadContext.matchPromises)
-
-      const readyPromise = this.triggerOnReady(innerLoadContext)
-      if (isPromise(readyPromise)) await readyPromise
-    } catch (err) {
-      if (isNotFound(err) && !innerLoadContext.preload) {
-        const readyPromise = this.triggerOnReady(innerLoadContext)
-        if (isPromise(readyPromise)) await readyPromise
-        throw err
-      }
-      if (isRedirect(err)) {
-        throw err
-      }
-    }
-
-    return innerLoadContext.matches
-  }
-
   invalidate: InvalidateFn<
     RouterCore<
       TRouteTree,
@@ -3048,47 +2268,7 @@ export class RouterCore<
     this.clearCache({ filter })
   }
 
-  loadRouteChunk = (route: AnyRoute) => {
-    if (!route._lazyLoaded && route._lazyPromise === undefined) {
-      if (route.lazyFn) {
-        route._lazyPromise = route.lazyFn().then((lazyRoute) => {
-          // explicitly don't copy over the lazy route's id
-          const { id: _id, ...options } = lazyRoute.options
-          Object.assign(route.options, options)
-          route._lazyLoaded = true
-          route._lazyPromise = undefined // gc promise, we won't need it anymore
-        })
-      } else {
-        route._lazyLoaded = true
-      }
-    }
-
-    // If for some reason lazy resolves more lazy components...
-    // We'll wait for that before we attempt to preload the
-    // components themselves.
-    if (!route._componentsLoaded && route._componentsPromise === undefined) {
-      const loadComponents = () => {
-        const preloads = []
-        for (const type of componentTypes) {
-          const preload = (route.options[type] as any)?.preload
-          if (preload) preloads.push(preload())
-        }
-        if (preloads.length)
-          return Promise.all(preloads).then(() => {
-            route._componentsLoaded = true
-            route._componentsPromise = undefined // gc promise, we won't need it anymore
-          })
-        route._componentsLoaded = true
-        route._componentsPromise = undefined // gc promise, we won't need it anymore
-        return
-      }
-      route._componentsPromise = route._lazyPromise
-        ? route._lazyPromise.then(loadComponents)
-        : loadComponents()
-    }
-
-    return route._componentsPromise
-  }
+  loadRouteChunk = loadRouteChunk
 
   preloadRoute: PreloadRouteFn<
     TRouteTree,
@@ -3128,7 +2308,8 @@ export class RouterCore<
     })
 
     try {
-      matches = await this.loadMatches({
+      matches = await loadMatches({
+        router: this,
         matches,
         location: next,
         preload: true,
@@ -3193,7 +2374,6 @@ export class RouterCore<
       : this.state.resolvedLocation || this.state.location
 
     const match = matchPathname(
-      this.basepath,
       baseLocation.pathname,
       {
         ...opts,
@@ -3226,58 +2406,6 @@ export class RouterCore<
 
   serverSsr?: ServerSsr
 
-  private _handleNotFound = (
-    innerLoadContext: InnerLoadContext,
-    err: NotFoundError,
-  ) => {
-    // Find the route that should handle the not found error
-    // First check if a specific route is requested to show the error
-    const routeCursor = this.routesById[err.routeId ?? ''] ?? this.routeTree
-    const matchesByRouteId: Record<string, AnyRouteMatch> = {}
-
-    // Setup routesByRouteId object for quick access
-    for (const match of innerLoadContext.matches) {
-      matchesByRouteId[match.routeId] = match
-    }
-
-    // Ensure a NotFoundComponent exists on the route
-    if (
-      !routeCursor.options.notFoundComponent &&
-      (this.options as any)?.defaultNotFoundComponent
-    ) {
-      routeCursor.options.notFoundComponent = (
-        this.options as any
-      ).defaultNotFoundComponent
-    }
-
-    // Ensure we have a notFoundComponent
-    invariant(
-      routeCursor.options.notFoundComponent,
-      'No notFoundComponent found. Please set a notFoundComponent on your route or provide a defaultNotFoundComponent to the router.',
-    )
-
-    // Find the match for this route
-    const matchForRoute = matchesByRouteId[routeCursor.id]
-
-    invariant(
-      matchForRoute,
-      'Could not find match for route: ' + routeCursor.id,
-    )
-
-    // Assign the error to the match - using non-null assertion since we've checked with invariant
-    innerLoadContext.updateMatch(matchForRoute.id, (prev) => ({
-      ...prev,
-      status: 'notFound',
-      error: err,
-      isFetching: false,
-    }))
-
-    if ((err as any).routerCode === 'BEFORE_LOAD' && routeCursor.parentRoute) {
-      err.routeId = routeCursor.parentRoute.id
-      this._handleNotFound(innerLoadContext, err)
-    }
-  }
-
   hasNotFoundMatch = () => {
     return this.__store.state.matches.some(
       (d) => d.status === 'notFound' || d.globalNotFound,
@@ -3289,16 +2417,6 @@ export class SearchParamError extends Error {}
 
 export class PathParamError extends Error {}
 
-function makeMaybe<TValue, TError>(
-  value: TValue,
-  error: TError,
-): { status: 'success'; value: TValue } | { status: 'error'; error: TError } {
-  if (error) {
-    return { status: 'error' as const, error }
-  }
-  return { status: 'success' as const, value }
-}
-
 const normalize = (str: string) =>
   str.endsWith('/') && str.length > 1 ? str.slice(0, -1) : str
 function comparePaths(a: string, b: string) {
@@ -3365,22 +2483,6 @@ function validateSearch(validateSearch: AnyValidator, input: unknown): unknown {
   return {}
 }
 
-export const componentTypes = [
-  'component',
-  'errorComponent',
-  'pendingComponent',
-  'notFoundComponent',
-] as const
-
-function routeNeedsPreload(route: AnyRoute) {
-  for (const componentType of componentTypes) {
-    if ((route.options[componentType] as any)?.preload) {
-      return true
-    }
-  }
-  return false
-}
-
 interface RouteLike {
   id: string
   isRoot?: boolean
@@ -3607,7 +2709,6 @@ export function processRouteTree<TRouteLike extends RouteLike>({
 export function getMatchedRoutes<TRouteLike extends RouteLike>({
   pathname,
   routePathname,
-  basepath,
   caseSensitive,
   routesByPath,
   routesById,
@@ -3616,7 +2717,6 @@ export function getMatchedRoutes<TRouteLike extends RouteLike>({
 }: {
   pathname: string
   routePathname?: string
-  basepath: string
   caseSensitive?: boolean
   routesByPath: Record<string, TRouteLike>
   routesById: Record<string, TRouteLike>
@@ -3627,7 +2727,6 @@ export function getMatchedRoutes<TRouteLike extends RouteLike>({
   const trimmedPath = trimPathRight(pathname)
   const getMatchedParams = (route: TRouteLike) => {
     const result = matchPathname(
-      basepath,
       trimmedPath,
       {
         to: route.fullPath,