@tanstack/router-core 0.0.1-beta.8 → 1.20.3-alpha.1

package/src/router.ts

@@ -1,1284 +1,3324 @@
+import { Store, batch } from '@tanstack/store'
 import {
-  BrowserHistory,
   createBrowserHistory,
   createMemoryHistory,
-  HashHistory,
-  History,
-  MemoryHistory,
-} from 'history'
+  parseHref,
+} from '@tanstack/history'
 import invariant from 'tiny-invariant'
-import { GetFrameworkGeneric } from './frameworks'
-
 import {
-  LinkInfo,
-  LinkOptions,
-  NavigateOptionsAbsolute,
-  ToOptions,
-  ValidFromPath,
-} from './link'
+  createControlledPromise,
+  deepEqual,
+  functionalUpdate,
+  last,
+  pick,
+  replaceEqualDeep,
+} from './utils'
 import {
   cleanPath,
   interpolatePath,
   joinPaths,
   matchPathname,
+  parsePathname,
   resolvePath,
+  trimPath,
+  trimPathLeft,
+  trimPathRight,
 } from './path'
-import { AnyRoute, cascadeLoaderData, createRoute, Route } from './route'
-import {
-  AnyLoaderData,
-  AnyPathParams,
-  AnyRouteConfig,
-  AnySearchSchema,
-  LoaderContext,
-  RouteConfig,
-  SearchFilter,
-} from './routeConfig'
-import {
-  AllRouteInfo,
-  AnyAllRouteInfo,
-  AnyRouteInfo,
-  RouteInfo,
-  RoutesById,
-} from './routeInfo'
-import { createRouteMatch, RouteMatch } from './routeMatch'
+import { isNotFound } from './not-found'
+import { setupScrollRestoration } from './scroll-restoration'
 import { defaultParseSearch, defaultStringifySearch } from './searchParams'
-import {
-  functionalUpdate,
-  last,
-  pick,
+import { rootRouteId } from './root'
+import { isRedirect } from './redirect'
+import type { SearchParser, SearchSerializer } from './searchParams'
+import type { AnyRedirect, ResolvedRedirect } from './redirect'
+import type {
+  HistoryLocation,
+  HistoryState,
+  ParsedHistoryState,
+  RouterHistory,
+} from '@tanstack/history'
+import type {
+  ControlledPromise,
+  NoInfer,
+  NonNullableUpdater,
   PickAsRequired,
-  PickRequired,
-  replaceEqualDeep,
-  Timeout,
   Updater,
 } from './utils'
+import type { ParsedLocation } from './location'
+import type { DeferredPromiseState } from './defer'
+import type {
+  AnyContext,
+  AnyRoute,
+  AnyRouteWithContext,
+  BeforeLoadContextOptions,
+  LoaderFnContext,
+  MakeRemountDepsOptionsUnion,
+  RouteContextOptions,
+  RouteMask,
+  SearchMiddleware,
+} from './route'
+import type {
+  FullSearchSchema,
+  RouteById,
+  RoutePaths,
+  RoutesById,
+  RoutesByPath,
+} from './routeInfo'
+import type {
+  AnyRouteMatch,
+  MakeRouteMatch,
+  MakeRouteMatchUnion,
+  MatchRouteOptions,
+} from './Matches'
+import type {
+  BuildLocationFn,
+  CommitLocationOptions,
+  NavigateFn,
+} from './RouterProvider'
+import type { Manifest } from './manifest'
+import type { StartSerializer } from './serializer'
+import type { AnySchema, AnyValidator } from './validators'
+import type { NavigateOptions, ResolveRelativePath, ToOptions } from './link'
+import type { NotFoundError } from './not-found'
+
+declare global {
+  interface Window {
+    __TSR_ROUTER__?: AnyRouter
+  }
+}
 
-export interface LocationState {}
-
-export interface Location<
-  TSearchObj extends AnySearchSchema = {},
-  TState extends LocationState = LocationState,
-> {
-  href: string
-  pathname: string
-  search: TSearchObj
-  searchStr: string
-  state: TState
-  hash: string
-  key?: string
+export type ControllablePromise<T = any> = Promise<T> & {
+  resolve: (value: T) => void
+  reject: (value?: any) => void
 }
 
-export interface FromLocation {
-  pathname: string
-  search?: unknown
-  key?: string
-  hash?: string
+export type InjectedHtmlEntry = Promise<string>
+
+export interface DefaultRegister {
+  router: AnyRouter
 }
 
-export type SearchSerializer = (searchObj: Record<string, any>) => string
-export type SearchParser = (searchStr: string) => Record<string, any>
-export type FilterRoutesFn = <TRoute extends Route<any, RouteInfo>>(
-  routeConfigs: TRoute[],
-) => TRoute[]
+export interface Register extends DefaultRegister {
+  // router: Router
+}
 
-export interface RouterOptions<TRouteConfig extends AnyRouteConfig> {
-  history?: BrowserHistory | MemoryHistory | HashHistory
+export type RegisteredRouter = Register['router']
+
+export type DefaultRemountDepsFn<TRouteTree extends AnyRoute> = (
+  opts: MakeRemountDepsOptionsUnion<TRouteTree>,
+) => any
+
+export interface DefaultRouterOptionsExtensions {}
+
+export interface RouterOptionsExtensions
+  extends DefaultRouterOptionsExtensions {}
+
+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>,
+> extends RouterOptionsExtensions {
+  /**
+   * The history object that will be used to manage the browser history.
+   *
+   * If not provided, a new createBrowserHistory instance will be created and used.
+   *
+   * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#history-property)
+   * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/history-types)
+   */
+  history?: TRouterHistory
+  /**
+   * A function that will be used to stringify search params when generating links.
+   *
+   * @default defaultStringifySearch
+   * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#stringifysearch-method)
+   * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/custom-search-param-serialization)
+   */
   stringifySearch?: SearchSerializer
+  /**
+   * A function that will be used to parse search params when parsing the current location.
+   *
+   * @default defaultParseSearch
+   * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#parsesearch-method)
+   * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/custom-search-param-serialization)
+   */
   parseSearch?: SearchParser
-  filterRoutes?: FilterRoutesFn
-  defaultPreload?: false | 'intent'
-  defaultPreloadMaxAge?: number
-  defaultPreloadGcMaxAge?: number
+  /**
+   * If `false`, routes will not be preloaded by default in any way.
+   *
+   * If `'intent'`, routes will be preloaded by default when the user hovers over a link or a `touchstart` event is detected on a `<Link>`.
+   *
+   * If `'viewport'`, routes will be preloaded by default when they are within the viewport.
+   *
+   * @default false
+   * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultpreload-property)
+   * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/preloading)
+   */
+  defaultPreload?: false | 'intent' | 'viewport' | 'render'
+  /**
+   * The delay in milliseconds that a route must be hovered over or touched before it is preloaded.
+   *
+   * @default 50
+   * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultpreloaddelay-property)
+   * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/preloading#preload-delay)
+   */
   defaultPreloadDelay?: number
-  useErrorBoundary?: boolean
-  defaultElement?: GetFrameworkGeneric<'Element'>
-  defaultErrorElement?: GetFrameworkGeneric<'Element'>
-  defaultCatchElement?: GetFrameworkGeneric<'Element'>
-  defaultPendingElement?: GetFrameworkGeneric<'Element'>
+  /**
+   * The default `preloadIntentProximity` a route should use if no preloadIntentProximity is provided.
+   *
+   * @default 0
+   * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultpreloadintentproximity-property)
+   * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/preloading#preload-intent-proximity)
+   */
+  defaultPreloadIntentProximity?: number
+  /**
+   * The default `pendingMs` a route should use if no pendingMs is provided.
+   *
+   * @default 1000
+   * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultpendingms-property)
+   * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading#avoiding-pending-component-flash)
+   */
   defaultPendingMs?: number
+  /**
+   * The default `pendingMinMs` a route should use if no pendingMinMs is provided.
+   *
+   * @default 500
+   * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultpendingminms-property)
+   * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading#avoiding-pending-component-flash)
+   */
   defaultPendingMinMs?: number
-  defaultLoaderMaxAge?: number
-  defaultLoaderGcMaxAge?: number
+  /**
+   * The default `staleTime` a route should use if no staleTime is provided. This is the time in milliseconds that a route will be considered fresh.
+   *
+   * @default 0
+   * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultstaletime-property)
+   * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading#key-options)
+   */
+  defaultStaleTime?: number
+  /**
+   * The default `preloadStaleTime` a route should use if no preloadStaleTime is provided.
+   *
+   * @default 30_000 `(30 seconds)`
+   * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultpreloadstaletime-property)
+   * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/preloading)
+   */
+  defaultPreloadStaleTime?: number
+  /**
+   * The default `defaultPreloadGcTime` a route should use if no preloadGcTime is provided.
+   *
+   * @default 1_800_000 `(30 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)
+   */
+  defaultPreloadGcTime?: number
+  /**
+   * If `true`, route navigations will called using `document.startViewTransition()`.
+   *
+   * If the browser does not support this api, this option will be ignored.
+   *
+   * See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Document/startViewTransition) for more information on how this function works.
+   *
+   * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultviewtransition-property)
+   */
+  defaultViewTransition?: boolean | ViewTransitionOptions
+  /**
+   * The default `hashScrollIntoView` a route should use if no hashScrollIntoView is provided while navigating
+   *
+   * See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView) for more information on `ScrollIntoViewOptions`.
+   *
+   * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaulthashscrollintoview-property)
+   */
+  defaultHashScrollIntoView?: boolean | ScrollIntoViewOptions
+  /**
+   * @default 'fuzzy'
+   * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#notfoundmode-property)
+   * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/not-found-errors#the-notfoundmode-option)
+   */
+  notFoundMode?: 'root' | 'fuzzy'
+  /**
+   * The default `gcTime` a route should use if no gcTime is provided.
+   *
+   * @default 1_800_000 `(30 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)
+   */
+  defaultGcTime?: number
+  /**
+   * If `true`, all routes will be matched as case-sensitive.
+   *
+   * @default false
+   * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#casesensitive-property)
+   */
   caseSensitive?: boolean
-  routeConfig?: TRouteConfig
+  /**
+   *
+   * The route tree that will be used to configure the router instance.
+   *
+   * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#routetree-property)
+   * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/routing/route-trees)
+   */
+  routeTree?: TRouteTree
+  /**
+   * The basepath for then entire router. This is useful for mounting a router instance at a subpath.
+   *
+   * @default '/'
+   * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#basepath-property)
+   */
   basepath?: string
-  createRouter?: (router: Router<any, any>) => void
-  createRoute?: (opts: { route: AnyRoute; router: Router<any, any> }) => void
-  createElement?: (
-    element: GetFrameworkGeneric<'SyncOrAsyncElement'>,
-  ) => Promise<GetFrameworkGeneric<'Element'>>
+  /**
+   * The root context that will be provided to all routes in the route tree.
+   *
+   * This can be used to provide a context to all routes in the tree without having to provide it to each route individually.
+   *
+   * Optional or required if the root route was created with [`createRootRouteWithContext()`](https://tanstack.com/router/latest/docs/framework/react/api/router/createRootRouteWithContextFunction).
+   *
+   * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#context-property)
+   * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/router-context)
+   */
+  context?: InferRouterContext<TRouteTree>
+  /**
+   * A function that will be called when the router is dehydrated.
+   *
+   * The return value of this function will be serialized and stored in the router's dehydrated state.
+   *
+   * @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?: () => TDehydrated
+  /**
+   * A function that will be called when the router is hydrated.
+   *
+   * The return value of this function will be serialized and stored in the router's dehydrated state.
+   *
+   * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#hydrate-method)
+   * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/external-data-loading#critical-dehydrationhydration)
+   */
+  hydrate?: (dehydrated: TDehydrated) => void
+  /**
+   * An array of route masks that will be used to mask routes in the route tree.
+   *
+   * Route masking is when you display a route at a different path than the one it is configured to match, like a modal popup that when shared will unmask to the modal's content instead of the modal's context.
+   *
+   * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#routemasks-property)
+   * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/route-masking)
+   */
+  routeMasks?: Array<RouteMask<TRouteTree>>
+  /**
+   * If `true`, route masks will, by default, be removed when the page is reloaded.
+   *
+   * This can be overridden on a per-mask basis by setting the `unmaskOnReload` option on the mask, or on a per-navigation basis by setting the `unmaskOnReload` option in the `Navigate` options.
+   *
+   * @default false
+   * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#unmaskonreload-property)
+   * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/route-masking#unmasking-on-page-reload)
+   */
+  unmaskOnReload?: boolean
+
+  /**
+   * Use `notFoundComponent` instead.
+   *
+   * @deprecated
+   * See https://tanstack.com/router/v1/docs/guide/not-found-errors#migrating-from-notfoundroute for more info.
+   * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#notfoundroute-property)
+   */
+  notFoundRoute?: AnyRoute
+  /**
+   * Configures how trailing slashes are treated.
+   *
+   * - `'always'` will add a trailing slash if not present
+   * - `'never'` will remove the trailing slash if present
+   * - `'preserve'` will not modify the trailing slash.
+   *
+   * @default 'never'
+   * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#trailingslash-property)
+   */
+  trailingSlash?: TTrailingSlashOption
+  /**
+   * While usually automatic, sometimes it can be useful to force the router into a server-side state, e.g. when using the router in a non-browser environment that has access to a global.document object.
+   *
+   * @default typeof document !== 'undefined'
+   * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#isserver-property)
+   */
+  isServer?: boolean
+
+  defaultSsr?: boolean
+
+  search?: {
+    /**
+     * Configures how unknown search params (= not returned by any `validateSearch`) are treated.
+     *
+     * @default false
+     * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#search.strict-property)
+     */
+    strict?: boolean
+  }
+
+  /**
+   * Configures whether structural sharing is enabled by default for fine-grained selectors.
+   *
+   * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultstructuralsharing-property)
+   */
+  defaultStructuralSharing?: TDefaultStructuralSharingOption
+
+  /**
+   * Configures which URI characters are allowed in path params that would ordinarily be escaped by encodeURIComponent.
+   *
+   * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#pathparamsallowedcharacters-property)
+   * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/path-params#allowed-characters)
+   */
+  pathParamsAllowedCharacters?: Array<
+    ';' | ':' | '@' | '&' | '=' | '+' | '$' | ','
+  >
+
+  defaultRemountDeps?: DefaultRemountDepsFn<TRouteTree>
+
+  /**
+   * If `true`, scroll restoration will be enabled
+   *
+   * @default false
+   */
+  scrollRestoration?: boolean
+
+  /**
+   * A function that will be called to get the key for the scroll restoration cache.
+   *
+   * @default (location) => location.href
+   */
+  getScrollRestorationKey?: (location: ParsedLocation) => string
+  /**
+   * The default behavior for scroll restoration.
+   *
+   * @default 'auto'
+   */
+  scrollRestorationBehavior?: ScrollBehavior
+  /**
+   * An array of selectors that will be used to scroll to the top of the page in addition to `window`
+   *
+   * @default ['window']
+   */
+  scrollToTopSelectors?: Array<string>
 }
 
-export interface Action<
-  TPayload = unknown,
-  TResponse = unknown,
-  // TError = unknown,
+export interface RouterState<
+  in out TRouteTree extends AnyRoute = AnyRoute,
+  in out TRouteMatch = MakeRouteMatchUnion,
 > {
-  submit: (submission?: TPayload) => Promise<TResponse>
-  current?: ActionState<TPayload, TResponse>
-  latest?: ActionState<TPayload, TResponse>
-  pending: ActionState<TPayload, TResponse>[]
+  status: 'pending' | 'idle'
+  loadedAt: number
+  isLoading: boolean
+  isTransitioning: boolean
+  matches: Array<TRouteMatch>
+  pendingMatches?: Array<TRouteMatch>
+  cachedMatches: Array<TRouteMatch>
+  location: ParsedLocation<FullSearchSchema<TRouteTree>>
+  resolvedLocation?: ParsedLocation<FullSearchSchema<TRouteTree>>
+  statusCode: number
+  redirect?: AnyRedirect
 }
 
-export interface ActionState<
-  TPayload = unknown,
-  TResponse = unknown,
-  // TError = unknown,
-> {
-  submittedAt: number
-  status: 'idle' | 'pending' | 'success' | 'error'
-  submission: TPayload
-  data?: TResponse
-  error?: unknown
+export interface BuildNextOptions {
+  to?: string | number | null
+  params?: true | Updater<unknown>
+  search?: true | Updater<unknown>
+  hash?: true | Updater<string>
+  state?: true | NonNullableUpdater<ParsedHistoryState, HistoryState>
+  mask?: {
+    to?: string | number | null
+    params?: true | Updater<unknown>
+    search?: true | Updater<unknown>
+    hash?: true | Updater<string>
+    state?: true | NonNullableUpdater<ParsedHistoryState, HistoryState>
+    unmaskOnReload?: boolean
+  }
+  from?: string
+  _fromLocation?: ParsedLocation
+  href?: string
 }
 
-export interface Loader<
-  TFullSearchSchema extends AnySearchSchema = {},
-  TAllParams extends AnyPathParams = {},
-  TRouteLoaderData = AnyLoaderData,
-> {
-  fetch: keyof PickRequired<TFullSearchSchema> extends never
-    ? keyof TAllParams extends never
-      ? (loaderContext: { signal?: AbortSignal }) => Promise<TRouteLoaderData>
-      : (loaderContext: {
-          params: TAllParams
-          search?: TFullSearchSchema
-          signal?: AbortSignal
-        }) => Promise<TRouteLoaderData>
-    : keyof TAllParams extends never
-    ? (loaderContext: {
-        search: TFullSearchSchema
-        params: TAllParams
-        signal?: AbortSignal
-      }) => Promise<TRouteLoaderData>
-    : (loaderContext: {
-        search: TFullSearchSchema
-        signal?: AbortSignal
-      }) => Promise<TRouteLoaderData>
-  current?: LoaderState<TFullSearchSchema, TAllParams>
-  latest?: LoaderState<TFullSearchSchema, TAllParams>
-  pending: LoaderState<TFullSearchSchema, TAllParams>[]
+type NavigationEventInfo = {
+  fromLocation?: ParsedLocation
+  toLocation: ParsedLocation
+  pathChanged: boolean
+  hrefChanged: boolean
+  hashChanged: boolean
 }
 
-export interface LoaderState<
-  TFullSearchSchema = unknown,
-  TAllParams = unknown,
-> {
-  loadedAt: number
-  loaderContext: LoaderContext<TFullSearchSchema, TAllParams>
+export type RouterEvents = {
+  onBeforeNavigate: {
+    type: 'onBeforeNavigate'
+  } & NavigationEventInfo
+  onBeforeLoad: {
+    type: 'onBeforeLoad'
+  } & NavigationEventInfo
+  onLoad: {
+    type: 'onLoad'
+  } & NavigationEventInfo
+  onResolved: {
+    type: 'onResolved'
+  } & NavigationEventInfo
+  onBeforeRouteMount: {
+    type: 'onBeforeRouteMount'
+  } & NavigationEventInfo
+  onInjectedHtml: {
+    type: 'onInjectedHtml'
+    promise: Promise<string>
+  }
+  onRendered: {
+    type: 'onRendered'
+  } & NavigationEventInfo
 }
 
-export interface RouterState {
-  status: 'idle' | 'loading'
-  location: Location
-  matches: RouteMatch[]
-  lastUpdated: number
-  currentAction?: ActionState
-  latestAction?: ActionState
-  actions: Record<string, Action>
-  loaders: Record<string, Loader>
-  pending?: PendingState
-  isFetching: boolean
-  isPreloading: boolean
+export type RouterEvent = RouterEvents[keyof RouterEvents]
+
+export type ListenerFn<TEvent extends RouterEvent> = (event: TEvent) => void
+
+export type RouterListener<TRouterEvent extends RouterEvent> = {
+  eventType: TRouterEvent['type']
+  fn: ListenerFn<TRouterEvent>
 }
 
-export interface PendingState {
-  location: Location
-  matches: RouteMatch[]
+export interface MatchRoutesOpts {
+  preload?: boolean
+  throwOnError?: boolean
+  _buildLocation?: boolean
+  dest?: BuildNextOptions
 }
 
-type Listener = (router: Router<any, any>) => void
+export type InferRouterContext<TRouteTree extends AnyRoute> =
+  TRouteTree['types']['routerContext']
 
-export type ListenerFn = () => void
+export type RouterContextOptions<TRouteTree extends AnyRoute> =
+  AnyContext extends InferRouterContext<TRouteTree>
+    ? {
+        context?: InferRouterContext<TRouteTree>
+      }
+    : {
+        context: InferRouterContext<TRouteTree>
+      }
 
-export interface BuildNextOptions {
-  to?: string | number | null
-  params?: true | Updater<Record<string, any>>
-  search?: true | Updater<unknown>
-  hash?: true | Updater<string>
-  key?: string
-  from?: string
-  fromCurrent?: boolean
-  __preSearchFilters?: SearchFilter<any>[]
-  __postSearchFilters?: SearchFilter<any>[]
+export type RouterConstructorOptions<
+  TRouteTree extends AnyRoute,
+  TTrailingSlashOption extends TrailingSlashOption,
+  TDefaultStructuralSharingOption extends boolean,
+  TRouterHistory extends RouterHistory,
+  TDehydrated extends Record<string, any>,
+> = Omit<
+  RouterOptions<
+    TRouteTree,
+    TTrailingSlashOption,
+    TDefaultStructuralSharingOption,
+    TRouterHistory,
+    TDehydrated
+  >,
+  'context'
+> &
+  RouterContextOptions<TRouteTree>
+
+export interface RouterErrorSerializer<TSerializedError> {
+  serialize: (err: unknown) => TSerializedError
+  deserialize: (err: TSerializedError) => unknown
 }
 
-export type MatchCacheEntry = {
-  gc: number
-  match: RouteMatch
+export interface MatchedRoutesResult {
+  matchedRoutes: Array<AnyRoute>
+  routeParams: Record<string, string>
 }
 
-export interface MatchLocation {
-  to?: string | number | null
-  fuzzy?: boolean
-  caseSensitive?: boolean
-  from?: string
-  fromCurrent?: boolean
+export type PreloadRouteFn<
+  TRouteTree extends AnyRoute,
+  TTrailingSlashOption extends TrailingSlashOption,
+  TDefaultStructuralSharingOption extends boolean,
+  TRouterHistory extends RouterHistory,
+> = <
+  TFrom extends RoutePaths<TRouteTree> | string = string,
+  TTo extends string | undefined = undefined,
+  TMaskFrom extends RoutePaths<TRouteTree> | string = TFrom,
+  TMaskTo extends string = '',
+>(
+  opts: NavigateOptions<
+    RouterCore<
+      TRouteTree,
+      TTrailingSlashOption,
+      TDefaultStructuralSharingOption,
+      TRouterHistory
+    >,
+    TFrom,
+    TTo,
+    TMaskFrom,
+    TMaskTo
+  >,
+) => Promise<Array<AnyRouteMatch> | undefined>
+
+export type MatchRouteFn<
+  TRouteTree extends AnyRoute,
+  TTrailingSlashOption extends TrailingSlashOption,
+  TDefaultStructuralSharingOption extends boolean,
+  TRouterHistory extends RouterHistory,
+> = <
+  TFrom extends RoutePaths<TRouteTree> = '/',
+  TTo extends string | undefined = undefined,
+  TResolved = ResolveRelativePath<TFrom, NoInfer<TTo>>,
+>(
+  location: ToOptions<
+    RouterCore<
+      TRouteTree,
+      TTrailingSlashOption,
+      TDefaultStructuralSharingOption,
+      TRouterHistory
+    >,
+    TFrom,
+    TTo
+  >,
+  opts?: MatchRouteOptions,
+) => false | RouteById<TRouteTree, TResolved>['types']['allParams']
+
+export type UpdateFn<
+  TRouteTree extends AnyRoute,
+  TTrailingSlashOption extends TrailingSlashOption,
+  TDefaultStructuralSharingOption extends boolean,
+  TRouterHistory extends RouterHistory,
+  TDehydrated extends Record<string, any>,
+> = (
+  newOptions: RouterConstructorOptions<
+    TRouteTree,
+    TTrailingSlashOption,
+    TDefaultStructuralSharingOption,
+    TRouterHistory,
+    TDehydrated
+  >,
+) => void
+
+export type InvalidateFn<TRouter extends AnyRouter> = (opts?: {
+  filter?: (d: MakeRouteMatchUnion<TRouter>) => boolean
+  sync?: boolean
+}) => Promise<void>
+
+export type ParseLocationFn<TRouteTree extends AnyRoute> = (
+  previousLocation?: ParsedLocation<FullSearchSchema<TRouteTree>>,
+  locationToParse?: HistoryLocation,
+) => ParsedLocation<FullSearchSchema<TRouteTree>>
+
+export type GetMatchRoutesFn = (
+  pathname: string,
+  routePathname: string | undefined,
+) => {
+  matchedRoutes: Array<AnyRoute>
+  routeParams: Record<string, string>
+  foundRoute: AnyRoute | undefined
 }
 
-export interface MatchRouteOptions {
-  pending: boolean
-  caseSensitive?: boolean
+export type EmitFn = (routerEvent: RouterEvent) => void
+
+export type LoadFn = (opts?: { sync?: boolean }) => Promise<void>
+
+export type CommitLocationFn = ({
+  viewTransition,
+  ignoreBlocker,
+  ...next
+}: ParsedLocation & CommitLocationOptions) => Promise<void>
+
+export type StartTransitionFn = (fn: () => void) => void
+
+export type SubscribeFn = <TType extends keyof RouterEvents>(
+  eventType: TType,
+  fn: ListenerFn<RouterEvents[TType]>,
+) => () => void
+
+export interface MatchRoutesFn {
+  (
+    pathname: string,
+    locationSearch: AnySchema,
+    opts?: MatchRoutesOpts,
+  ): Array<AnyRouteMatch>
+  (next: ParsedLocation, opts?: MatchRoutesOpts): Array<AnyRouteMatch>
+  (
+    pathnameOrNext: string | ParsedLocation,
+    locationSearchOrOpts?: AnySchema | MatchRoutesOpts,
+    opts?: MatchRoutesOpts,
+  ): Array<AnyRouteMatch>
 }
 
-type LinkCurrentTargetElement = {
-  preloadTimeout?: null | ReturnType<typeof setTimeout>
+export type GetMatchFn = (matchId: string) => AnyRouteMatch | undefined
+
+export type UpdateMatchFn = (
+  id: string,
+  updater: (match: AnyRouteMatch) => AnyRouteMatch,
+) => AnyRouteMatch
+
+export type LoadRouteChunkFn = (route: AnyRoute) => Promise<Array<void>>
+
+export type ResolveRedirect = (err: AnyRedirect) => ResolvedRedirect
+
+export type ClearCacheFn<TRouter extends AnyRouter> = (opts?: {
+  filter?: (d: MakeRouteMatchUnion<TRouter>) => boolean
+}) => void
+
+export interface ServerSrr {
+  injectedHtml: Array<InjectedHtmlEntry>
+  injectHtml: (getHtml: () => string | Promise<string>) => Promise<void>
+  injectScript: (
+    getScript: () => string | Promise<string>,
+    opts?: { logScript?: boolean },
+  ) => Promise<void>
+  streamValue: (key: string, value: any) => void
+  streamedKeys: Set<string>
+  onMatchSettled: (opts: { router: AnyRouter; match: AnyRouteMatch }) => any
 }
 
-interface DehydratedRouterState
-  extends Pick<RouterState, 'status' | 'location' | 'lastUpdated'> {
-  matches: DehydratedRouteMatch[]
+export type AnyRouterWithContext<TContext> = RouterCore<
+  AnyRouteWithContext<TContext>,
+  any,
+  any,
+  any,
+  any
+>
+
+export type AnyRouter = RouterCore<any, any, any, any, any>
+
+export interface ViewTransitionOptions {
+  types:
+    | Array<string>
+    | ((locationChangeInfo: {
+        fromLocation?: ParsedLocation
+        toLocation: ParsedLocation
+        pathChanged: boolean
+        hrefChanged: boolean
+        hashChanged: boolean
+      }) => Array<string>)
 }
 
-interface DehydratedRouteMatch
-  extends Pick<
-    RouteMatch<any, any>,
-    | 'matchId'
-    | 'status'
-    | 'routeLoaderData'
-    | 'loaderData'
-    | 'isInvalid'
-    | 'invalidAt'
-  > {}
-
-export interface Router<
-  TRouteConfig extends AnyRouteConfig = RouteConfig,
-  TAllRouteInfo extends AnyAllRouteInfo = AllRouteInfo<TRouteConfig>,
-> {
-  history: BrowserHistory | MemoryHistory | HashHistory
-  options: PickAsRequired<
-    RouterOptions<TRouteConfig>,
-    'stringifySearch' | 'parseSearch'
-  >
-  // Computed in this.update()
-  basepath: string
-  // Internal:
-  allRouteInfo: TAllRouteInfo
-  listeners: Listener[]
-  location: Location
-  navigateTimeout?: Timeout
-  nextAction?: 'push' | 'replace'
-  state: RouterState
-  routeTree: Route<TAllRouteInfo, RouteInfo>
-  routesById: RoutesById<TAllRouteInfo>
-  navigationPromise: Promise<void>
-  removeActionQueue: { action: Action; actionState: ActionState }[]
-  startedLoadingAt: number
-  resolveNavigation: () => void
-  subscribe: (listener: Listener) => () => void
-  notify: () => void
-  mount: () => () => void
-  onFocus: () => void
-  update: <TRouteConfig extends RouteConfig = RouteConfig>(
-    opts?: RouterOptions<TRouteConfig>,
-  ) => Router<TRouteConfig>
-
-  buildNext: (opts: BuildNextOptions) => Location
-  cancelMatches: () => void
-  loadLocation: (next?: Location) => Promise<void>
-  matchCache: Record<string, MatchCacheEntry>
-  cleanMatchCache: () => void
-  getRoute: <TId extends keyof TAllRouteInfo['routeInfoById']>(
-    id: TId,
-  ) => Route<TAllRouteInfo, TAllRouteInfo['routeInfoById'][TId]>
-  loadRoute: (navigateOpts: BuildNextOptions) => Promise<RouteMatch[]>
-  preloadRoute: (
-    navigateOpts: BuildNextOptions,
-    loaderOpts: { maxAge?: number; gcMaxAge?: number },
-  ) => Promise<RouteMatch[]>
-  matchRoutes: (
-    pathname: string,
-    opts?: { strictParseParams?: boolean },
-  ) => RouteMatch[]
-  loadMatches: (
-    resolvedMatches: RouteMatch[],
-    loaderOpts?: { withPending?: boolean } & (
-      | { preload: true; maxAge: number; gcMaxAge: number }
-      | { preload?: false; maxAge?: never; gcMaxAge?: never }
-    ),
-  ) => Promise<void>
-  invalidateRoute: (opts: MatchLocation) => void
-  reload: () => Promise<void>
-  resolvePath: (from: string, path: string) => string
-  navigate: <
-    TFrom extends ValidFromPath<TAllRouteInfo> = '/',
-    TTo extends string = '.',
-  >(
-    opts: NavigateOptionsAbsolute<TAllRouteInfo, TFrom, TTo>,
-  ) => Promise<void>
-  matchRoute: <
-    TFrom extends ValidFromPath<TAllRouteInfo> = '/',
-    TTo extends string = '.',
-  >(
-    matchLocation: ToOptions<TAllRouteInfo, TFrom, TTo>,
-    opts?: MatchRouteOptions,
-  ) => boolean
-  buildLink: <
-    TFrom extends ValidFromPath<TAllRouteInfo> = '/',
-    TTo extends string = '.',
-  >(
-    opts: LinkOptions<TAllRouteInfo, TFrom, TTo>,
-  ) => LinkInfo
-  dehydrateState: () => DehydratedRouterState
-  hydrateState: (state: DehydratedRouterState) => void
-  __: {
-    buildRouteTree: (
-      routeConfig: RouteConfig,
-    ) => Route<TAllRouteInfo, AnyRouteInfo>
-    parseLocation: (
-      location: History['location'],
-      previousLocation?: Location,
-    ) => Location
-    buildLocation: (dest: BuildNextOptions) => Location
-    commitLocation: (next: Location, replace?: boolean) => Promise<void>
-    navigate: (
-      location: BuildNextOptions & { replace?: boolean },
-    ) => Promise<void>
+export function defaultSerializeError(err: unknown) {
+  if (err instanceof Error) {
+    const obj = {
+      name: err.name,
+      message: err.message,
+    }
+
+    if (process.env.NODE_ENV === 'development') {
+      ;(obj as any).stack = err.stack
+    }
+
+    return obj
   }
+
+  return {
+    data: err,
+  }
+}
+export interface ExtractedBaseEntry {
+  dataType: '__beforeLoadContext' | 'loaderData'
+  type: string
+  path: Array<string>
+  id: number
+  matchIndex: number
+}
+
+export interface ExtractedStream extends ExtractedBaseEntry {
+  type: 'stream'
+  streamState: StreamState
 }
 
-// Detect if we're in the DOM
-const isServer =
-  typeof window === 'undefined' || !window.document?.createElement
+export interface ExtractedPromise extends ExtractedBaseEntry {
+  type: 'promise'
+  promiseState: DeferredPromiseState<any>
+}
+
+export type ExtractedEntry = ExtractedStream | ExtractedPromise
 
-// This is the default history object if none is defined
-const createDefaultHistory = () =>
-  isServer ? createMemoryHistory() : createBrowserHistory()
+export type StreamState = {
+  promises: Array<ControlledPromise<string | null>>
+}
 
-export function createRouter<
-  TRouteConfig extends AnyRouteConfig = RouteConfig,
-  TAllRouteInfo extends AnyAllRouteInfo = AllRouteInfo<TRouteConfig>,
+export type TrailingSlashOption = 'always' | 'never' | 'preserve'
+
+export function getLocationChangeInfo(routerState: {
+  resolvedLocation?: ParsedLocation
+  location: ParsedLocation
+}) {
+  const fromLocation = routerState.resolvedLocation
+  const toLocation = routerState.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 }
+}
+
+export type CreateRouterFn = <
+  TRouteTree extends AnyRoute,
+  TTrailingSlashOption extends TrailingSlashOption = 'never',
+  TDefaultStructuralSharingOption extends boolean = false,
+  TRouterHistory extends RouterHistory = RouterHistory,
+  TDehydrated extends Record<string, any> = Record<string, any>,
 >(
-  userOptions?: RouterOptions<TRouteConfig>,
-): Router<TRouteConfig, TAllRouteInfo> {
-  const history = userOptions?.history || createDefaultHistory()
-
-  const originalOptions = {
-    defaultLoaderGcMaxAge: 5 * 60 * 1000,
-    defaultLoaderMaxAge: 0,
-    defaultPreloadMaxAge: 2000,
-    defaultPreloadDelay: 50,
-    ...userOptions,
-    stringifySearch: userOptions?.stringifySearch ?? defaultStringifySearch,
-    parseSearch: userOptions?.parseSearch ?? defaultParseSearch,
+  options: undefined extends number
+    ? 'strictNullChecks must be enabled in tsconfig.json'
+    : RouterConstructorOptions<
+        TRouteTree,
+        TTrailingSlashOption,
+        TDefaultStructuralSharingOption,
+        TRouterHistory,
+        TDehydrated
+      >,
+) => RouterCore<
+  TRouteTree,
+  TTrailingSlashOption,
+  TDefaultStructuralSharingOption,
+  TRouterHistory,
+  TDehydrated
+>
+
+export class 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>,
+> {
+  // Option-independent properties
+  tempLocationKey: string | undefined = `${Math.round(
+    Math.random() * 10000000,
+  )}`
+  resetNextScroll = true
+  shouldViewTransition?: boolean | ViewTransitionOptions = undefined
+  isViewTransitionTypesSupported?: boolean = undefined
+  subscribers = new Set<RouterListener<RouterEvent>>()
+  viewTransitionPromise?: ControlledPromise<true>
+  isScrollRestoring = false
+  isScrollRestorationSetup = false
+
+  // Must build in constructor
+  __store!: Store<RouterState<TRouteTree>>
+  options!: PickAsRequired<
+    RouterOptions<
+      TRouteTree,
+      TTrailingSlashOption,
+      TDefaultStructuralSharingOption,
+      TRouterHistory,
+      TDehydrated
+    >,
+    'stringifySearch' | 'parseSearch' | 'context'
+  >
+  history!: TRouterHistory
+  latestLocation!: ParsedLocation<FullSearchSchema<TRouteTree>>
+  basepath!: string
+  routeTree!: TRouteTree
+  routesById!: RoutesById<TRouteTree>
+  routesByPath!: RoutesByPath<TRouteTree>
+  flatRoutes!: Array<AnyRoute>
+  isServer!: boolean
+  pathParamsDecodeCharMap?: Map<string, string>
+
+  /**
+   * @deprecated Use the `createRouter` function instead
+   */
+  constructor(
+    options: RouterConstructorOptions<
+      TRouteTree,
+      TTrailingSlashOption,
+      TDefaultStructuralSharingOption,
+      TRouterHistory,
+      TDehydrated
+    >,
+  ) {
+    this.update({
+      defaultPreloadDelay: 50,
+      defaultPendingMs: 1000,
+      defaultPendingMinMs: 500,
+      context: undefined!,
+      ...options,
+      caseSensitive: options.caseSensitive ?? false,
+      notFoundMode: options.notFoundMode ?? 'fuzzy',
+      stringifySearch: options.stringifySearch ?? defaultStringifySearch,
+      parseSearch: options.parseSearch ?? defaultParseSearch,
+    })
+
+    if (typeof document !== 'undefined') {
+      ;(window as any).__TSR_ROUTER__ = this
+    }
   }
 
-  let router: Router<TRouteConfig, TAllRouteInfo> = {
-    history,
-    options: originalOptions,
-    listeners: [],
-    removeActionQueue: [],
-    // Resolved after construction
-    basepath: '',
-    routeTree: undefined!,
-    routesById: {} as any,
-    location: undefined!,
-    allRouteInfo: undefined!,
-    //
-    navigationPromise: Promise.resolve(),
-    resolveNavigation: () => {},
-    matchCache: {},
-    state: {
-      status: 'idle',
-      location: null!,
-      matches: [],
-      actions: {},
-      loaders: {},
-      lastUpdated: Date.now(),
-      isFetching: false,
-      isPreloading: false,
-    },
-    startedLoadingAt: Date.now(),
-    subscribe: (listener: Listener): (() => void) => {
-      router.listeners.push(listener as Listener)
-      return () => {
-        router.listeners = router.listeners.filter((x) => x !== listener)
-      }
-    },
-    getRoute: (id) => {
-      return router.routesById[id]
-    },
-    notify: (): void => {
-      router.state = {
-        ...router.state,
-        isFetching:
-          router.state.status === 'loading' ||
-          router.state.matches.some((d) => d.isFetching),
-        isPreloading: Object.values(router.matchCache).some(
-          (d) =>
-            d.match.isFetching &&
-            !router.state.matches.find((dd) => dd.matchId === d.match.matchId),
-        ),
-      }
+  // These are default implementations that can optionally be overridden
+  // by the router provider once rendered. We provide these so that the
+  // router can be used in a non-react environment if necessary
+  startTransition: StartTransitionFn = (fn) => fn()
+
+  update: UpdateFn<
+    TRouteTree,
+    TTrailingSlashOption,
+    TDefaultStructuralSharingOption,
+    TRouterHistory,
+    TDehydrated
+  > = (newOptions) => {
+    if (newOptions.notFoundRoute) {
+      console.warn(
+        'The notFoundRoute API is deprecated and will be removed in the next major version. See https://tanstack.com/router/v1/docs/framework/react/guide/not-found-errors#migrating-from-notfoundroute for more info.',
+      )
+    }
 
-      cascadeLoaderData(router.state.matches)
-      router.listeners.forEach((listener) => listener(router))
-    },
+    const previousOptions = this.options
+    this.options = {
+      ...this.options,
+      ...newOptions,
+    }
 
-    dehydrateState: () => {
-      return {
-        ...pick(router.state, ['status', 'location', 'lastUpdated']),
-        matches: router.state.matches.map((match) =>
-          pick(match, [
-            'matchId',
-            'status',
-            'routeLoaderData',
-            'loaderData',
-            'isInvalid',
-            'invalidAt',
+    this.isServer = this.options.isServer ?? typeof document === 'undefined'
+
+    this.pathParamsDecodeCharMap = this.options.pathParamsAllowedCharacters
+      ? new Map(
+          this.options.pathParamsAllowedCharacters.map((char) => [
+            encodeURIComponent(char),
+            char,
           ]),
-        ),
+        )
+      : undefined
+
+    if (
+      !this.basepath ||
+      (newOptions.basepath && newOptions.basepath !== previousOptions.basepath)
+    ) {
+      if (
+        newOptions.basepath === undefined ||
+        newOptions.basepath === '' ||
+        newOptions.basepath === '/'
+      ) {
+        this.basepath = '/'
+      } else {
+        this.basepath = `/${trimPath(newOptions.basepath)}`
       }
-    },
+    }
+
+    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()
+    }
+
+    if (this.options.routeTree !== this.routeTree) {
+      this.routeTree = this.options.routeTree as TRouteTree
+      this.buildRouteTree()
+    }
+
+    if (!this.__store) {
+      this.__store = new Store(getInitialRouterState(this.latestLocation), {
+        onUpdate: () => {
+          this.__store.state = {
+            ...this.state,
+            cachedMatches: this.state.cachedMatches.filter(
+              (d) => !['redirected'].includes(d.status),
+            ),
+          }
+        },
+      })
+
+      setupScrollRestoration(this)
+    }
+
+    if (
+      typeof window !== 'undefined' &&
+      'CSS' in window &&
+      typeof window.CSS?.supports === 'function'
+    ) {
+      this.isViewTransitionTypesSupported = window.CSS.supports(
+        'selector(:active-view-transition-type(a)',
+      )
+    }
+  }
+
+  get state() {
+    return this.__store.state
+  }
 
-    hydrateState: (dehydratedState) => {
-      // Match the routes
-      const matches = router.matchRoutes(router.location.pathname, {
-        strictParseParams: true,
+  buildRouteTree = () => {
+    const { routesById, routesByPath, flatRoutes } = processRouteTree({
+      routeTree: this.routeTree,
+      initRoute: (route, i) => {
+        route.init({
+          originalIndex: i,
+          defaultSsr: this.options.defaultSsr,
+        })
+      },
+    })
+
+    this.routesById = routesById as RoutesById<TRouteTree>
+    this.routesByPath = routesByPath as RoutesByPath<TRouteTree>
+    this.flatRoutes = flatRoutes as Array<AnyRoute>
+
+    const notFoundRoute = this.options.notFoundRoute
+
+    if (notFoundRoute) {
+      notFoundRoute.init({
+        originalIndex: 99999999999,
+        defaultSsr: this.options.defaultSsr,
       })
+      this.routesById[notFoundRoute.id] = notFoundRoute
+    }
+  }
 
-      router.state = {
-        ...router.state,
-        ...dehydratedState,
-        matches: matches.map((match) => {
-          const dehydratedMatch = dehydratedState.matches.find(
-            (d: any) => d.matchId === match.matchId,
-          )
-          invariant(
-            dehydratedMatch,
-            'Oh no! Dehydrated route matches did not match the active state of the router 😬',
-          )
-          Object.assign(match, dehydratedMatch)
-          return match
-        }),
+  subscribe: SubscribeFn = (eventType, fn) => {
+    const listener: RouterListener<any> = {
+      eventType,
+      fn,
+    }
+
+    this.subscribers.add(listener)
+
+    return () => {
+      this.subscribers.delete(listener)
+    }
+  }
+
+  emit: EmitFn = (routerEvent) => {
+    this.subscribers.forEach((listener) => {
+      if (listener.eventType === routerEvent.type) {
+        listener.fn(routerEvent)
       }
-    },
+    })
+  }
 
-    mount: () => {
-      const next = router.__.buildLocation({
-        to: '.',
-        search: true,
-        hash: true,
-      })
+  parseLocation: ParseLocationFn<TRouteTree> = (
+    previousLocation,
+    locationToParse,
+  ) => {
+    const parse = ({
+      pathname,
+      search,
+      hash,
+      state,
+    }: HistoryLocation): ParsedLocation<FullSearchSchema<TRouteTree>> => {
+      const parsedSearch = this.options.parseSearch(search)
+      const searchStr = this.options.stringifySearch(parsedSearch)
 
-      // If the current location isn't updated, trigger a navigation
-      // to the current location. Otherwise, load the current location.
-      if (next.href !== router.location.href) {
-        router.__.commitLocation(next, true)
+      return {
+        pathname,
+        searchStr,
+        search: replaceEqualDeep(previousLocation?.search, parsedSearch) as any,
+        hash: hash.split('#').reverse()[0] ?? '',
+        href: `${pathname}${searchStr}${hash}`,
+        state: replaceEqualDeep(previousLocation?.state, state),
       }
+    }
 
-      router.loadLocation()
+    const location = parse(locationToParse ?? this.history.location)
 
-      const unsub = router.history.listen((event) => {
-        console.log(event.location)
-        router.loadLocation(
-          router.__.parseLocation(event.location, router.location),
-        )
-      })
+    const { __tempLocation, __tempKey } = location.state
 
-      // addEventListener does not exist in React Native, but window does
-      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-      if (!isServer && window.addEventListener) {
-        // Listen to visibillitychange and focus
-        window.addEventListener('visibilitychange', router.onFocus, false)
-        window.addEventListener('focus', router.onFocus, false)
+    if (__tempLocation && (!__tempKey || __tempKey === this.tempLocationKey)) {
+      // Sync up the location keys
+      const parsedTempLocation = parse(__tempLocation) as any
+      parsedTempLocation.state.key = location.state.key
+
+      delete parsedTempLocation.state.__tempLocation
+
+      return {
+        ...parsedTempLocation,
+        maskedLocation: location,
       }
+    }
+
+    return location
+  }
+
+  resolvePathWithBase = (from: string, path: string) => {
+    const resolvedPath = resolvePath({
+      basepath: this.basepath,
+      base: from,
+      to: cleanPath(path),
+      trailingSlash: this.options.trailingSlash,
+      caseSensitive: this.options.caseSensitive,
+    })
+    return resolvedPath
+  }
+
+  get looseRoutesById() {
+    return this.routesById as Record<string, AnyRoute>
+  }
+
+  /**
+  @deprecated use the following signature instead
+  ```ts
+  matchRoutes (
+    next: ParsedLocation,
+    opts?: { preload?: boolean; throwOnError?: boolean },
+  ): Array<AnyRouteMatch>;
+  ```
+*/
+  matchRoutes: MatchRoutesFn = (
+    pathnameOrNext: string | ParsedLocation,
+    locationSearchOrOpts?: AnySchema | MatchRoutesOpts,
+    opts?: MatchRoutesOpts,
+  ) => {
+    if (typeof pathnameOrNext === 'string') {
+      return this.matchRoutesInternal(
+        {
+          pathname: pathnameOrNext,
+          search: locationSearchOrOpts,
+        } as ParsedLocation,
+        opts,
+      )
+    } else {
+      return this.matchRoutesInternal(pathnameOrNext, locationSearchOrOpts)
+    }
+  }
 
-      return () => {
-        unsub()
-        // Be sure to unsubscribe if a new handler is set
-        window.removeEventListener('visibilitychange', router.onFocus)
-        window.removeEventListener('focus', router.onFocus)
+  private matchRoutesInternal(
+    next: ParsedLocation,
+    opts?: MatchRoutesOpts,
+  ): Array<AnyRouteMatch> {
+    const { foundRoute, matchedRoutes, routeParams } = this.getMatchedRoutes(
+      next.pathname,
+      opts?.dest?.to as string,
+    )
+    let isGlobalNotFound = false
+
+    // Check to see if the route needs a 404 entry
+    if (
+      // If we found a route, and it's not an index route and we have left over path
+      foundRoute
+        ? foundRoute.path !== '/' && routeParams['**']
+        : // Or if we didn't find a route and we have left over path
+          trimPathRight(next.pathname)
+    ) {
+      // If the user has defined an (old) 404 route, use it
+      if (this.options.notFoundRoute) {
+        matchedRoutes.push(this.options.notFoundRoute)
+      } else {
+        // If there is no routes found during path matching
+        isGlobalNotFound = true
       }
-    },
+    }
 
-    onFocus: () => {
-      router.loadLocation()
-    },
+    const globalNotFoundRouteId = (() => {
+      if (!isGlobalNotFound) {
+        return undefined
+      }
 
-    update: (opts) => {
-      const newHistory = opts?.history !== router.history
-      if (!router.location || newHistory) {
-        if (opts?.history) {
-          router.history = opts.history
+      if (this.options.notFoundMode !== 'root') {
+        for (let i = matchedRoutes.length - 1; i >= 0; i--) {
+          const route = matchedRoutes[i]!
+          if (route.children) {
+            return route.id
+          }
         }
-        router.location = router.__.parseLocation(router.history.location)
-        router.state.location = router.location
       }
 
-      Object.assign(router.options, opts)
+      return rootRouteId
+    })()
+
+    const parseErrors = matchedRoutes.map((route) => {
+      let parsedParamsError
+
+      const parseParams =
+        route.options.params?.parse ?? route.options.parseParams
 
-      const { basepath, routeConfig } = router.options
+      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,
+          })
 
-      router.basepath = cleanPath(`/${basepath ?? ''}`)
+          if (opts?.throwOnError) {
+            throw parsedParamsError
+          }
 
-      if (routeConfig) {
-        router.routesById = {} as any
-        router.routeTree = router.__.buildRouteTree(routeConfig)
+          return parsedParamsError
+        }
       }
 
-      return router as any
-    },
+      return
+    })
 
-    cancelMatches: () => {
-      ;[
-        ...router.state.matches,
-        ...(router.state.pending?.matches ?? []),
-      ].forEach((match) => {
-        match.cancel()
-      })
-    },
+    const matches: Array<AnyRouteMatch> = []
 
-    loadLocation: async (next?: Location) => {
-      const id = Math.random()
-      router.startedLoadingAt = id
+    const getParentContext = (parentMatch?: AnyRouteMatch) => {
+      const parentMatchId = parentMatch?.id
 
-      if (next) {
-        // Ingest the new location
-        router.location = next
-      }
+      const parentContext = !parentMatchId
+        ? ((this.options.context as any) ?? {})
+        : (parentMatch.context ?? this.options.context ?? {})
 
-      // Clear out old actions
-      router.removeActionQueue.forEach(({ action, actionState }) => {
-        if (router.state.currentAction === actionState) {
-          router.state.currentAction = undefined
-        }
-        if (action.current === actionState) {
-          action.current = undefined
+      return parentContext
+    }
+
+    matchedRoutes.forEach((route, index) => {
+      // Take each matched route and resolve + validate its search params
+      // This has to happen serially because each route's search params
+      // can depend on the parent route's search params
+      // It must also happen before we create the match so that we can
+      // pass the search params to the route's potential key function
+      // which is used to uniquely identify the route match in state
+
+      const parentMatch = matches[index - 1]
+
+      const [preMatchSearch, strictMatchSearch, searchError]: [
+        Record<string, any>,
+        Record<string, any>,
+        any,
+      ] = (() => {
+        // Validate the search params and stabilize them
+        const parentSearch = parentMatch?.search ?? next.search
+        const parentStrictSearch = parentMatch?._strictSearch ?? {}
+
+        try {
+          const strictSearch =
+            validateSearch(route.options.validateSearch, { ...parentSearch }) ??
+            {}
+
+          return [
+            {
+              ...parentSearch,
+              ...strictSearch,
+            },
+            { ...parentStrictSearch, ...strictSearch },
+            undefined,
+          ]
+        } catch (err: any) {
+          let searchParamError = err
+          if (!(err instanceof SearchParamError)) {
+            searchParamError = new SearchParamError(err.message, {
+              cause: err,
+            })
+          }
+
+          if (opts?.throwOnError) {
+            throw searchParamError
+          }
+
+          return [parentSearch, {}, searchParamError]
         }
-      })
-      router.removeActionQueue = []
+      })()
 
-      // Cancel any pending matches
-      router.cancelMatches()
+      // 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
 
-      // Match the routes
-      const matches = router.matchRoutes(router.location.pathname, {
-        strictParseParams: true,
+      const loaderDeps =
+        route.options.loaderDeps?.({
+          search: preMatchSearch,
+        }) ?? ''
+
+      const loaderDepsHash = loaderDeps ? JSON.stringify(loaderDeps) : ''
+
+      const { usedParams, interpolatedPath } = interpolatePath({
+        path: route.fullPath,
+        params: routeParams,
+        decodeCharMap: this.pathParamsDecodeCharMap,
       })
 
-      router.state = {
-        ...router.state,
-        pending: {
-          matches: matches,
-          location: router.location,
-        },
-        status: 'loading',
-      }
+      const matchId =
+        interpolatePath({
+          path: route.id,
+          params: routeParams,
+          leaveWildcards: true,
+          decodeCharMap: this.pathParamsDecodeCharMap,
+        }).interpolatedPath + loaderDepsHash
 
-      router.notify()
+      // 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.
 
-      // Load the matches
-      await router.loadMatches(matches, {
-        withPending: true,
-      })
+      // 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,
+      )
 
-      if (router.startedLoadingAt !== id) {
-        // Ignore side-effects of match loading
-        return router.navigationPromise
+      const cause = previousMatch ? 'stay' : 'enter'
+
+      let match: AnyRouteMatch
+
+      if (existingMatch) {
+        match = {
+          ...existingMatch,
+          cause,
+          params: previousMatch
+            ? replaceEqualDeep(previousMatch.params, routeParams)
+            : routeParams,
+          _strictParams: usedParams,
+          search: previousMatch
+            ? replaceEqualDeep(previousMatch.search, preMatchSearch)
+            : replaceEqualDeep(existingMatch.search, preMatchSearch),
+          _strictSearch: strictMatchSearch,
+        }
+      } else {
+        const status =
+          route.options.loader ||
+          route.options.beforeLoad ||
+          route.lazyFn ||
+          routeNeedsPreload(route)
+            ? 'pending'
+            : 'success'
+
+        match = {
+          id: matchId,
+          index,
+          routeId: route.id,
+          params: previousMatch
+            ? replaceEqualDeep(previousMatch.params, routeParams)
+            : routeParams,
+          _strictParams: usedParams,
+          pathname: joinPaths([this.basepath, interpolatedPath]),
+          updatedAt: Date.now(),
+          search: previousMatch
+            ? replaceEqualDeep(previousMatch.search, preMatchSearch)
+            : preMatchSearch,
+          _strictSearch: strictMatchSearch,
+          searchError: undefined,
+          status,
+          isFetching: false,
+          error: undefined,
+          paramsError: parseErrors[index],
+          __routeContext: {},
+          __beforeLoadContext: {},
+          context: {},
+          abortController: new AbortController(),
+          fetchCount: 0,
+          cause,
+          loaderDeps: previousMatch
+            ? replaceEqualDeep(previousMatch.loaderDeps, loaderDeps)
+            : loaderDeps,
+          invalid: false,
+          preload: false,
+          links: undefined,
+          scripts: undefined,
+          headScripts: undefined,
+          meta: undefined,
+          staticData: route.options.staticData || {},
+          loadPromise: createControlledPromise(),
+          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
       }
 
-      const previousMatches = router.state.matches
+      // update the searchError if there is one
+      match.searchError = searchError
+
+      const parentContext = getParentContext(parentMatch)
 
-      const exiting: RouteMatch[] = [],
-        staying: RouteMatch[] = []
+      match.context = {
+        ...parentContext,
+        ...match.__routeContext,
+        ...match.__beforeLoadContext,
+      }
 
-      previousMatches.forEach((d) => {
-        if (matches.find((dd) => dd.matchId === d.matchId)) {
-          staying.push(d)
-        } else {
-          exiting.push(d)
+      matches.push(match)
+    })
+
+    matches.forEach((match, index) => {
+      const route = this.looseRoutesById[match.routeId]!
+      const existingMatch = this.getMatch(match.id)
+
+      // only execute `context` if we are not just building a location
+      if (!existingMatch && opts?._buildLocation !== true) {
+        const parentMatch = matches[index - 1]
+        const parentContext = getParentContext(parentMatch)
+
+        // Update the match's context
+        const contextFnContext: RouteContextOptions<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,
         }
-      })
 
-      const now = Date.now()
+        // Get the route context
+        match.__routeContext = route.options.context?.(contextFnContext) ?? {}
 
-      exiting.forEach((d) => {
-        d.__.onExit?.({
-          params: d.params,
-          search: d.routeSearch,
+        match.context = {
+          ...parentContext,
+          ...match.__routeContext,
+          ...match.__beforeLoadContext,
+        }
+      }
+
+      // If it's already a success, update headers and head content
+      // These may get updated again if the match is refreshed
+      // due to being stale
+      if (match.status === 'success') {
+        match.headers = route.options.headers?.({
+          loaderData: match.loaderData,
         })
-        // Clear idle error states when match leaves
-        if (d.status === 'error' && !d.isFetching) {
-          d.status = 'idle'
-          d.error = undefined
+        const assetContext = {
+          matches,
+          match,
+          params: match.params,
+          loaderData: match.loaderData,
         }
-        const gc = Math.max(
-          d.options.loaderGcMaxAge ?? router.options.defaultLoaderGcMaxAge ?? 0,
-          d.options.loaderMaxAge ?? router.options.defaultLoaderMaxAge ?? 0,
+        const headFnContent = route.options.head?.(assetContext)
+        match.links = headFnContent?.links
+        match.headScripts = headFnContent?.scripts
+        match.meta = headFnContent?.meta
+        match.scripts = route.options.scripts?.(assetContext)
+      }
+    })
+
+    return matches
+  }
+
+  getMatchedRoutes: GetMatchRoutesFn = (
+    pathname: string,
+    routePathname: string | undefined,
+  ) => {
+    return getMatchedRoutes({
+      pathname,
+      routePathname,
+      basepath: this.basepath,
+      caseSensitive: this.options.caseSensitive,
+      routesByPath: this.routesByPath,
+      routesById: this.routesById,
+      flatRoutes: this.flatRoutes,
+    })
+  }
+
+  cancelMatch = (id: string) => {
+    const match = this.getMatch(id)
+
+    if (!match) return
+
+    match.abortController.abort()
+    clearTimeout(match.pendingTimeout)
+  }
+
+  cancelMatches = () => {
+    this.state.pendingMatches?.forEach((match) => {
+      this.cancelMatch(match.id)
+    })
+  }
+
+  buildLocation: BuildLocationFn = (opts) => {
+    const build = (
+      dest: BuildNextOptions & {
+        unmaskOnReload?: boolean
+      } = {},
+      matchedRoutesResult?: MatchedRoutesResult,
+    ): ParsedLocation => {
+      const fromMatches = dest._fromLocation
+        ? this.matchRoutes(dest._fromLocation, { _buildLocation: true })
+        : this.state.matches
+
+      const fromMatch =
+        dest.from != null
+          ? fromMatches.find((d) =>
+              matchPathname(this.basepath, trimPathRight(d.pathname), {
+                to: dest.from,
+                caseSensitive: false,
+                fuzzy: false,
+              }),
+            )
+          : undefined
+
+      const fromPath = fromMatch?.pathname || this.latestLocation.pathname
+
+      invariant(
+        dest.from == null || fromMatch != null,
+        'Could not find match for from: ' + dest.from,
+      )
+
+      const fromSearch = this.state.pendingMatches?.length
+        ? last(this.state.pendingMatches)?.search
+        : last(fromMatches)?.search || this.latestLocation.search
+
+      const stayingMatches = matchedRoutesResult?.matchedRoutes.filter((d) =>
+        fromMatches.find((e) => e.routeId === d.id),
+      )
+      let pathname: string
+      if (dest.to) {
+        const resolvePathTo =
+          fromMatch?.fullPath ||
+          last(fromMatches)?.fullPath ||
+          this.latestLocation.pathname
+        pathname = this.resolvePathWithBase(resolvePathTo, `${dest.to}`)
+      } else {
+        const fromRouteByFromPathRouteId =
+          this.routesById[
+            stayingMatches?.find((route) => {
+              const interpolatedPath = interpolatePath({
+                path: route.fullPath,
+                params: matchedRoutesResult?.routeParams ?? {},
+                decodeCharMap: this.pathParamsDecodeCharMap,
+              }).interpolatedPath
+              const pathname = joinPaths([this.basepath, interpolatedPath])
+              return pathname === fromPath
+            })?.id as keyof this['routesById']
+          ]
+        pathname = this.resolvePathWithBase(
+          fromPath,
+          fromRouteByFromPathRouteId?.to ?? fromPath,
         )
-        if (gc > 0) {
-          router.matchCache[d.matchId] = {
-            gc: gc == Infinity ? Number.MAX_SAFE_INTEGER : now + gc,
-            match: d,
+      }
+
+      const prevParams = { ...last(fromMatches)?.params }
+
+      let nextParams =
+        (dest.params ?? true) === true
+          ? prevParams
+          : {
+              ...prevParams,
+              ...functionalUpdate(dest.params as any, prevParams),
+            }
+
+      if (Object.keys(nextParams).length > 0) {
+        matchedRoutesResult?.matchedRoutes
+          .map((route) => {
+            return (
+              route.options.params?.stringify ?? route.options.stringifyParams
+            )
+          })
+          .filter(Boolean)
+          .forEach((fn) => {
+            nextParams = { ...nextParams!, ...fn!(nextParams) }
+          })
+      }
+
+      pathname = interpolatePath({
+        path: pathname,
+        params: nextParams ?? {},
+        leaveWildcards: false,
+        leaveParams: opts.leaveParams,
+        decodeCharMap: this.pathParamsDecodeCharMap,
+      }).interpolatedPath
+
+      let search = fromSearch
+      if (opts._includeValidateSearch && this.options.search?.strict) {
+        let validatedSearch = {}
+        matchedRoutesResult?.matchedRoutes.forEach((route) => {
+          try {
+            if (route.options.validateSearch) {
+              validatedSearch = {
+                ...validatedSearch,
+                ...(validateSearch(route.options.validateSearch, {
+                  ...validatedSearch,
+                  ...search,
+                }) ?? {}),
+              }
+            }
+          } catch {
+            // ignore errors here because they are already handled in matchRoutes
           }
+        })
+        search = validatedSearch
+      }
+
+      const applyMiddlewares = (search: any) => {
+        const allMiddlewares =
+          matchedRoutesResult?.matchedRoutes.reduce(
+            (acc, route) => {
+              const middlewares: Array<SearchMiddleware<any>> = []
+              if ('search' in route.options) {
+                if (route.options.search?.middlewares) {
+                  middlewares.push(...route.options.search.middlewares)
+                }
+              }
+              // TODO remove preSearchFilters and postSearchFilters in v2
+              else if (
+                route.options.preSearchFilters ||
+                route.options.postSearchFilters
+              ) {
+                const legacyMiddleware: SearchMiddleware<any> = ({
+                  search,
+                  next,
+                }) => {
+                  let nextSearch = search
+                  if (
+                    'preSearchFilters' in route.options &&
+                    route.options.preSearchFilters
+                  ) {
+                    nextSearch = route.options.preSearchFilters.reduce(
+                      (prev, next) => next(prev),
+                      search,
+                    )
+                  }
+                  const result = next(nextSearch)
+                  if (
+                    'postSearchFilters' in route.options &&
+                    route.options.postSearchFilters
+                  ) {
+                    return route.options.postSearchFilters.reduce(
+                      (prev, next) => next(prev),
+                      result,
+                    )
+                  }
+                  return result
+                }
+                middlewares.push(legacyMiddleware)
+              }
+              if (opts._includeValidateSearch && route.options.validateSearch) {
+                const validate: SearchMiddleware<any> = ({ search, next }) => {
+                  const result = next(search)
+                  try {
+                    const validatedSearch = {
+                      ...result,
+                      ...(validateSearch(
+                        route.options.validateSearch,
+                        result,
+                      ) ?? {}),
+                    }
+                    return validatedSearch
+                  } catch {
+                    // ignore errors here because they are already handled in matchRoutes
+                    return result
+                  }
+                }
+                middlewares.push(validate)
+              }
+              return acc.concat(middlewares)
+            },
+            [] as Array<SearchMiddleware<any>>,
+          ) ?? []
+
+        // the chain ends here since `next` is not called
+        const final: SearchMiddleware<any> = ({ search }) => {
+          if (!dest.search) {
+            return {}
+          }
+          if (dest.search === true) {
+            return search
+          }
+          return functionalUpdate(dest.search, search)
         }
-      })
+        allMiddlewares.push(final)
+
+        const applyNext = (index: number, currentSearch: any): any => {
+          // no more middlewares left, return the current search
+          if (index >= allMiddlewares.length) {
+            return currentSearch
+          }
+
+          const middleware = allMiddlewares[index]!
+
+          const next = (newSearch: any): any => {
+            return applyNext(index + 1, newSearch)
+          }
 
-      staying.forEach((d) => {
-        d.options.onTransition?.({
-          params: d.params,
-          search: d.routeSearch,
+          return middleware({ search: currentSearch, next })
+        }
+
+        // Start applying middlewares
+        return applyNext(0, search)
+      }
+
+      search = applyMiddlewares(search)
+
+      search = replaceEqualDeep(fromSearch, search)
+      const searchStr = this.options.stringifySearch(search)
+
+      const hash =
+        dest.hash === true
+          ? this.latestLocation.hash
+          : dest.hash
+            ? functionalUpdate(dest.hash, this.latestLocation.hash)
+            : undefined
+
+      const hashStr = hash ? `#${hash}` : ''
+
+      let nextState =
+        dest.state === true
+          ? this.latestLocation.state
+          : dest.state
+            ? functionalUpdate(dest.state, this.latestLocation.state)
+            : {}
+
+      nextState = replaceEqualDeep(this.latestLocation.state, nextState)
+
+      return {
+        pathname,
+        search,
+        searchStr,
+        state: nextState as any,
+        hash: hash ?? '',
+        href: `${pathname}${searchStr}${hashStr}`,
+        unmaskOnReload: dest.unmaskOnReload,
+      }
+    }
+
+    const buildWithMatches = (
+      dest: BuildNextOptions = {},
+      maskedDest?: BuildNextOptions,
+    ) => {
+      const next = build(dest)
+      let maskedNext = maskedDest ? build(maskedDest) : undefined
+
+      if (!maskedNext) {
+        let params = {}
+
+        const foundMask = this.options.routeMasks?.find((d) => {
+          const match = matchPathname(this.basepath, next.pathname, {
+            to: d.from,
+            caseSensitive: false,
+            fuzzy: false,
+          })
+
+          if (match) {
+            params = match
+            return true
+          }
+
+          return false
         })
+
+        if (foundMask) {
+          const { from: _from, ...maskProps } = foundMask
+          maskedDest = {
+            ...pick(opts, ['from']),
+            ...maskProps,
+            params,
+          }
+          maskedNext = build(maskedDest)
+        }
+      }
+
+      const nextMatches = this.getMatchedRoutes(
+        next.pathname,
+        dest.to as string,
+      )
+      const final = build(dest, nextMatches)
+
+      if (maskedNext) {
+        const maskedMatches = this.getMatchedRoutes(
+          maskedNext.pathname,
+          maskedDest?.to as string,
+        )
+        const maskedFinal = build(maskedDest, maskedMatches)
+        final.maskedLocation = maskedFinal
+      }
+
+      return final
+    }
+
+    if (opts.mask) {
+      return buildWithMatches(opts, {
+        ...pick(opts, ['from']),
+        ...opts.mask,
       })
+    }
 
-      const entering = matches.filter((d) => {
-        return !previousMatches.find((dd) => dd.matchId === d.matchId)
+    return buildWithMatches(opts)
+  }
+
+  commitLocationPromise: undefined | ControlledPromise<void>
+
+  commitLocation: CommitLocationFn = ({
+    viewTransition,
+    ignoreBlocker,
+    ...next
+  }) => {
+    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',
+        '__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 = this.latestLocation.href === next.href
+
+    const previousCommitPromise = this.commitLocationPromise
+    this.commitLocationPromise = createControlledPromise<void>(() => {
+      previousCommitPromise?.resolve()
+    })
+
+    // Don't commit to history if nothing changed
+    if (isSameUrl && isSameState()) {
+      this.load()
+    } else {
+      // eslint-disable-next-line prefer-const
+      let { maskedLocation, hashScrollIntoView, ...nextHistory } = next
+
+      if (maskedLocation) {
+        nextHistory = {
+          ...maskedLocation,
+          state: {
+            ...maskedLocation.state,
+            __tempKey: undefined,
+            __tempLocation: {
+              ...nextHistory,
+              search: nextHistory.searchStr,
+              state: {
+                ...nextHistory.state,
+                __tempKey: undefined!,
+                __tempLocation: undefined!,
+                key: undefined!,
+              },
+            },
+          },
+        }
 
-      entering.forEach((d) => {
-        d.__.onExit = d.options.onMatch?.({
-          params: d.params,
-          search: d.search,
-        })
-        delete router.matchCache[d.matchId]
+        if (
+          nextHistory.unmaskOnReload ??
+          this.options.unmaskOnReload ??
+          false
+        ) {
+          nextHistory.state.__tempKey = this.tempLocationKey
+        }
+      }
+
+      nextHistory.state.__hashScrollIntoViewOptions =
+        hashScrollIntoView ?? this.options.defaultHashScrollIntoView ?? true
+
+      this.shouldViewTransition = viewTransition
+
+      this.history[next.replace ? 'replace' : 'push'](
+        nextHistory.href,
+        nextHistory.state,
+        { ignoreBlocker },
+      )
+    }
+
+    this.resetNextScroll = next.resetScroll ?? true
+
+    if (!this.history.subscribers.size) {
+      this.load()
+    }
+
+    return this.commitLocationPromise
+  }
+
+  buildAndCommitLocation = ({
+    replace,
+    resetScroll,
+    hashScrollIntoView,
+    viewTransition,
+    ignoreBlocker,
+    href,
+    ...rest
+  }: BuildNextOptions & CommitLocationOptions = {}) => {
+    if (href) {
+      const currentIndex = this.history.location.state.__TSR_index
+      const parsed = parseHref(href, {
+        __TSR_index: replace ? currentIndex : currentIndex + 1,
       })
+      rest.to = parsed.pathname
+      rest.search = this.options.parseSearch(parsed.search)
+      // remove the leading `#` from the hash
+      rest.hash = parsed.hash.slice(1)
+    }
+
+    const location = this.buildLocation({
+      ...(rest as any),
+      _includeValidateSearch: true,
+    })
+    return this.commitLocation({
+      ...location,
+      viewTransition,
+      replace,
+      resetScroll,
+      hashScrollIntoView,
+      ignoreBlocker,
+    })
+  }
 
-      if (matches.some((d) => d.status === 'loading')) {
-        router.notify()
-        await Promise.all(
-          matches.map((d) => d.__.loaderPromise || Promise.resolve()),
-        )
+  navigate: NavigateFn = ({ to, reloadDocument, href, ...rest }) => {
+    if (!reloadDocument && href) {
+      try {
+        new URL(`${href}`)
+        reloadDocument = true
+      } catch {}
+    }
+
+    if (reloadDocument) {
+      if (!href) {
+        const location = this.buildLocation({ to, ...rest } as any)
+        href = this.history.createHref(location.href)
       }
-      if (router.startedLoadingAt !== id) {
-        // Ignore side-effects of match loading
-        return
+      if (rest.replace) {
+        window.location.replace(href)
+      } else {
+        window.location.href = href
       }
+      return
+    }
+
+    return this.buildAndCommitLocation({
+      ...rest,
+      href,
+      to: to as string,
+    })
+  }
 
-      router.state = {
-        ...router.state,
-        location: router.location,
-        matches,
-        pending: undefined,
-        status: 'idle',
-      }
+  latestLoadPromise: undefined | Promise<void>
+
+  beforeLoad = () => {
+    // Cancel any pending matches
+    this.cancelMatches()
+    this.latestLocation = this.parseLocation(this.latestLocation)
+
+    // Match the routes
+    const pendingMatches = this.matchRoutes(this.latestLocation)
+
+    // Ingest the new matches
+    this.__store.setState((s) => ({
+      ...s,
+      status: 'pending',
+      isLoading: true,
+      location: this.latestLocation,
+      pendingMatches,
+      // If a cached moved to pendingMatches, remove it from cachedMatches
+      cachedMatches: s.cachedMatches.filter((d) => {
+        return !pendingMatches.find((e) => e.id === d.id)
+      }),
+    }))
+  }
 
-      router.notify()
-      router.resolveNavigation()
-    },
+  load: LoadFn = async (opts?: { sync?: boolean }): Promise<void> => {
+    let redirect: AnyRedirect | undefined
+    let notFound: NotFoundError | undefined
+
+    let loadPromise: Promise<void>
+
+    // eslint-disable-next-line prefer-const
+    loadPromise = new Promise<void>((resolve) => {
+      this.startTransition(async () => {
+        try {
+          this.beforeLoad()
+          const next = this.latestLocation
+          const prevLocation = this.state.resolvedLocation
+
+          if (!this.state.redirect) {
+            this.emit({
+              type: 'onBeforeNavigate',
+              ...getLocationChangeInfo({
+                resolvedLocation: prevLocation,
+                location: next,
+              }),
+            })
+          }
 
-    cleanMatchCache: () => {
-      const now = Date.now()
+          this.emit({
+            type: 'onBeforeLoad',
+            ...getLocationChangeInfo({
+              resolvedLocation: prevLocation,
+              location: next,
+            }),
+          })
 
-      Object.keys(router.matchCache).forEach((matchId) => {
-        const entry = router.matchCache[matchId]!
+          await this.loadMatches({
+            sync: opts?.sync,
+            matches: this.state.pendingMatches as Array<AnyRouteMatch>,
+            location: next,
+            // eslint-disable-next-line @typescript-eslint/require-await
+            onReady: async () => {
+              // eslint-disable-next-line @typescript-eslint/require-await
+              this.startViewTransition(async () => {
+                // this.viewTransitionPromise = createControlledPromise<true>()
+
+                // Commit the pending matches. If a previous match was
+                // removed, place it in the cachedMatches
+                let exitingMatches!: Array<AnyRouteMatch>
+                let enteringMatches!: Array<AnyRouteMatch>
+                let stayingMatches!: Array<AnyRouteMatch>
+
+                batch(() => {
+                  this.__store.setState((s) => {
+                    const previousMatches = s.matches
+                    const newMatches = s.pendingMatches || s.matches
+
+                    exitingMatches = previousMatches.filter(
+                      (match) => !newMatches.find((d) => d.id === match.id),
+                    )
+                    enteringMatches = newMatches.filter(
+                      (match) =>
+                        !previousMatches.find((d) => d.id === match.id),
+                    )
+                    stayingMatches = previousMatches.filter((match) =>
+                      newMatches.find((d) => d.id === match.id),
+                    )
+
+                    return {
+                      ...s,
+                      isLoading: false,
+                      loadedAt: Date.now(),
+                      matches: newMatches,
+                      pendingMatches: undefined,
+                      cachedMatches: [
+                        ...s.cachedMatches,
+                        ...exitingMatches.filter((d) => d.status !== 'error'),
+                      ],
+                    }
+                  })
+                  this.clearExpiredCache()
+                })
+
+                //
+                ;(
+                  [
+                    [exitingMatches, 'onLeave'],
+                    [enteringMatches, 'onEnter'],
+                    [stayingMatches, 'onStay'],
+                  ] as const
+                ).forEach(([matches, hook]) => {
+                  matches.forEach((match) => {
+                    this.looseRoutesById[match.routeId]!.options[hook]?.(match)
+                  })
+                })
+              })
+            },
+          })
+        } catch (err) {
+          if (isRedirect(err)) {
+            redirect = err
+            if (!this.isServer) {
+              this.navigate({
+                ...redirect.options,
+                replace: true,
+                ignoreBlocker: true,
+              })
+            }
+          } else if (isNotFound(err)) {
+            notFound = err
+          }
 
-        // Don't remove loading matches
-        if (entry.match.status === 'loading') {
-          return
+          this.__store.setState((s) => ({
+            ...s,
+            statusCode: redirect
+              ? redirect.status
+              : notFound
+                ? 404
+                : s.matches.some((d) => d.status === 'error')
+                  ? 500
+                  : 200,
+            redirect,
+          }))
         }
 
-        // Do not remove successful matches that are still valid
-        if (entry.gc > 0 && entry.gc > now) {
-          return
+        if (this.latestLoadPromise === loadPromise) {
+          this.commitLocationPromise?.resolve()
+          this.latestLoadPromise = undefined
+          this.commitLocationPromise = undefined
         }
-
-        // Everything else gets removed
-        delete router.matchCache[matchId]
+        resolve()
       })
-    },
+    })
 
-    loadRoute: async (navigateOpts = router.location) => {
-      const next = router.buildNext(navigateOpts)
-      const matches = router.matchRoutes(next.pathname, {
-        strictParseParams: true,
-      })
-      await router.loadMatches(matches)
-      return matches
-    },
+    this.latestLoadPromise = loadPromise
 
-    preloadRoute: async (navigateOpts = router.location, loaderOpts) => {
-      const next = router.buildNext(navigateOpts)
-      const matches = router.matchRoutes(next.pathname, {
-        strictParseParams: true,
-      })
-      await router.loadMatches(matches, {
-        preload: true,
-        maxAge:
-          loaderOpts.maxAge ??
-          router.options.defaultPreloadMaxAge ??
-          router.options.defaultLoaderMaxAge ??
-          0,
-        gcMaxAge:
-          loaderOpts.gcMaxAge ??
-          router.options.defaultPreloadGcMaxAge ??
-          router.options.defaultLoaderGcMaxAge ??
-          0,
-      })
-      return matches
-    },
+    await loadPromise
 
-    matchRoutes: (pathname, opts) => {
-      router.cleanMatchCache()
+    while (
+      (this.latestLoadPromise as any) &&
+      loadPromise !== this.latestLoadPromise
+    ) {
+      await this.latestLoadPromise
+    }
 
-      const matches: RouteMatch[] = []
+    if (this.hasNotFoundMatch()) {
+      this.__store.setState((s) => ({
+        ...s,
+        statusCode: 404,
+      }))
+    }
+  }
 
-      if (!router.routeTree) {
-        return matches
+  startViewTransition = (fn: () => Promise<void>) => {
+    // Determine if we should start a view transition from the navigation
+    // or from the router default
+    const shouldViewTransition =
+      this.shouldViewTransition ?? this.options.defaultViewTransition
+
+    // Reset the view transition flag
+    delete this.shouldViewTransition
+    // 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'
+    ) {
+      // lib.dom.ts doesn't support viewTransition types variant yet.
+      // TODO: Fix this when dom types are updated
+      let startViewTransitionParams: any
+
+      if (
+        typeof shouldViewTransition === 'object' &&
+        this.isViewTransitionTypesSupported
+      ) {
+        const next = this.latestLocation
+        const prevLocation = this.state.resolvedLocation
+
+        const resolvedViewTransitionTypes =
+          typeof shouldViewTransition.types === 'function'
+            ? shouldViewTransition.types(
+                getLocationChangeInfo({
+                  resolvedLocation: prevLocation,
+                  location: next,
+                }),
+              )
+            : shouldViewTransition.types
+
+        startViewTransitionParams = {
+          update: fn,
+          types: resolvedViewTransitionTypes,
+        }
+      } else {
+        startViewTransitionParams = fn
       }
 
-      const existingMatches = [
-        ...router.state.matches,
-        ...(router.state.pending?.matches ?? []),
-      ]
+      document.startViewTransition(startViewTransitionParams)
+    } else {
+      fn()
+    }
+  }
 
-      const recurse = async (routes: Route<any, any>[]): Promise<void> => {
-        const parentMatch = last(matches)
-        let params = parentMatch?.params ?? {}
+  updateMatch: UpdateMatchFn = (id, updater) => {
+    let updated!: AnyRouteMatch
+    const isPending = this.state.pendingMatches?.find((d) => d.id === id)
+    const isMatched = this.state.matches.find((d) => d.id === id)
+    const isCached = this.state.cachedMatches.find((d) => d.id === id)
+
+    const matchesKey = isPending
+      ? 'pendingMatches'
+      : isMatched
+        ? 'matches'
+        : isCached
+          ? 'cachedMatches'
+          : ''
+
+    if (matchesKey) {
+      this.__store.setState((s) => ({
+        ...s,
+        [matchesKey]: s[matchesKey]?.map((d) =>
+          d.id === id ? (updated = updater(d)) : d,
+        ),
+      }))
+    }
 
-        const filteredRoutes = router.options.filterRoutes?.(routes) ?? routes
+    return updated
+  }
 
-        let foundRoutes: Route[] = []
+  getMatch: GetMatchFn = (matchId: string) => {
+    return [
+      ...this.state.cachedMatches,
+      ...(this.state.pendingMatches ?? []),
+      ...this.state.matches,
+    ].find((d) => d.id === matchId)
+  }
 
-        const findMatchInRoutes = (parentRoutes: Route[], routes: Route[]) => {
-          routes.some((route) => {
-            if (!route.routePath && route.childRoutes?.length) {
-              return findMatchInRoutes(
-                [...foundRoutes, route],
-                route.childRoutes,
-              )
+  loadMatches = async ({
+    location,
+    matches,
+    preload: allPreload,
+    onReady,
+    updateMatch = this.updateMatch,
+    sync,
+  }: {
+    location: ParsedLocation
+    matches: Array<AnyRouteMatch>
+    preload?: boolean
+    onReady?: () => Promise<void>
+    updateMatch?: (
+      id: string,
+      updater: (match: AnyRouteMatch) => AnyRouteMatch,
+    ) => void
+    getMatch?: (matchId: string) => AnyRouteMatch | undefined
+    sync?: boolean
+  }): Promise<Array<MakeRouteMatch>> => {
+    let firstBadMatchIndex: number | undefined
+    let rendered = false
+
+    const triggerOnReady = async () => {
+      if (!rendered) {
+        rendered = true
+        await onReady?.()
+      }
+    }
+
+    const resolvePreload = (matchId: string) => {
+      return !!(allPreload && !this.state.matches.find((d) => d.id === matchId))
+    }
+
+    const handleRedirectAndNotFound = (match: AnyRouteMatch, err: any) => {
+      if (isRedirect(err) || isNotFound(err)) {
+        if (isRedirect(err)) {
+          if (err.redirectHandled) {
+            if (!err.options.reloadDocument) {
+              throw err
             }
+          }
+        }
 
-            const fuzzy = !!(
-              route.routePath !== '/' || route.childRoutes?.length
-            )
+        updateMatch(match.id, (prev) => ({
+          ...prev,
+          status: isRedirect(err)
+            ? 'redirected'
+            : isNotFound(err)
+              ? 'notFound'
+              : 'error',
+          isFetching: false,
+          error: err,
+          beforeLoadPromise: undefined,
+          loaderPromise: undefined,
+        }))
+
+        if (!(err as any).routeId) {
+          ;(err as any).routeId = match.routeId
+        }
 
-            const matchParams = matchPathname(pathname, {
-              to: route.fullPath,
-              fuzzy,
-              caseSensitive:
-                route.options.caseSensitive ?? router.options.caseSensitive,
-            })
+        match.beforeLoadPromise?.resolve()
+        match.loaderPromise?.resolve()
+        match.loadPromise?.resolve()
+
+        if (isRedirect(err)) {
+          rendered = true
+          err.options._fromLocation = location
+          err.redirectHandled = true
+          err = this.resolveRedirect(err)
+          throw err
+        } else if (isNotFound(err)) {
+          this._handleNotFound(matches, err, {
+            updateMatch,
+          })
+          this.serverSsr?.onMatchSettled({
+            router: this,
+            match: this.getMatch(match.id)!,
+          })
+          throw err
+        }
+      }
+    }
+
+    try {
+      await new Promise<void>((resolveAll, rejectAll) => {
+        ;(async () => {
+          try {
+            const handleSerialError = (
+              index: number,
+              err: any,
+              routerCode: string,
+            ) => {
+              const { id: matchId, routeId } = 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
+              }
 
-            if (matchParams) {
-              let parsedParams
+              err.routerCode = routerCode
+              firstBadMatchIndex = firstBadMatchIndex ?? index
+              handleRedirectAndNotFound(this.getMatch(matchId)!, err)
 
               try {
-                parsedParams =
-                  route.options.parseParams?.(matchParams!) ?? matchParams
-              } catch (err) {
-                if (opts?.strictParseParams) {
-                  throw err
-                }
+                route.options.onError?.(err)
+              } catch (errorHandlerErr) {
+                err = errorHandlerErr
+                handleRedirectAndNotFound(this.getMatch(matchId)!, err)
               }
 
-              params = {
-                ...params,
-                ...parsedParams,
-              }
+              updateMatch(matchId, (prev) => {
+                prev.beforeLoadPromise?.resolve()
+                prev.loadPromise?.resolve()
+
+                return {
+                  ...prev,
+                  error: err,
+                  status: 'error',
+                  isFetching: false,
+                  updatedAt: Date.now(),
+                  abortController: new AbortController(),
+                  beforeLoadPromise: undefined,
+                }
+              })
             }
 
-            if (!!matchParams) {
-              foundRoutes = [...parentRoutes, route]
-            }
+            for (const [index, { id: matchId, routeId }] of matches.entries()) {
+              const existingMatch = this.getMatch(matchId)!
+              const parentMatchId = matches[index - 1]?.id
+
+              const route = this.looseRoutesById[routeId]!
+
+              const pendingMs =
+                route.options.pendingMs ?? this.options.defaultPendingMs
+
+              const shouldPending = !!(
+                onReady &&
+                !this.isServer &&
+                !resolvePreload(matchId) &&
+                (route.options.loader ||
+                  route.options.beforeLoad ||
+                  routeNeedsPreload(route)) &&
+                typeof pendingMs === 'number' &&
+                pendingMs !== Infinity &&
+                (route.options.pendingComponent ??
+                  (this.options as any)?.defaultPendingComponent)
+              )
 
-            return !!foundRoutes.length
-          })
+              let executeBeforeLoad = true
+              if (
+                // 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)
+                existingMatch.beforeLoadPromise ||
+                existingMatch.loaderPromise
+              ) {
+                if (shouldPending) {
+                  setTimeout(() => {
+                    try {
+                      // Update the match and prematurely resolve the loadMatches promise so that
+                      // the pending component can start rendering
+                      triggerOnReady()
+                    } catch {}
+                  }, pendingMs)
+                }
 
-          return !!foundRoutes.length
-        }
+                // Wait for the beforeLoad to resolve before we continue
+                await existingMatch.beforeLoadPromise
+                executeBeforeLoad = this.getMatch(matchId)!.status !== 'success'
+              }
+              if (executeBeforeLoad) {
+                // If we are not in the middle of a load OR the previous load failed, start it
+                try {
+                  updateMatch(matchId, (prev) => {
+                    // explicitly capture the previous loadPromise
+                    const prevLoadPromise = prev.loadPromise
+                    return {
+                      ...prev,
+                      loadPromise: createControlledPromise<void>(() => {
+                        prevLoadPromise?.resolve()
+                      }),
+                      beforeLoadPromise: createControlledPromise<void>(),
+                    }
+                  })
+                  const abortController = new AbortController()
+
+                  let pendingTimeout: ReturnType<typeof setTimeout>
+
+                  if (shouldPending) {
+                    // If we might show a pending component, we need to wait for the
+                    // pending promise to resolve before we start showing that state
+                    pendingTimeout = setTimeout(() => {
+                      try {
+                        // Update the match and prematurely resolve the loadMatches promise so that
+                        // the pending component can start rendering
+                        triggerOnReady()
+                      } catch {}
+                    }, pendingMs)
+                  }
+
+                  const { paramsError, searchError } = this.getMatch(matchId)!
+
+                  if (paramsError) {
+                    handleSerialError(index, paramsError, 'PARSE_PARAMS')
+                  }
+
+                  if (searchError) {
+                    handleSerialError(index, searchError, 'VALIDATE_SEARCH')
+                  }
+
+                  const getParentMatchContext = () =>
+                    parentMatchId
+                      ? this.getMatch(parentMatchId)!.context
+                      : (this.options.context ?? {})
+
+                  updateMatch(matchId, (prev) => ({
+                    ...prev,
+                    isFetching: 'beforeLoad',
+                    fetchCount: prev.fetchCount + 1,
+                    abortController,
+                    pendingTimeout,
+                    context: {
+                      ...getParentMatchContext(),
+                      ...prev.__routeContext,
+                    },
+                  }))
+
+                  const { search, params, context, cause } =
+                    this.getMatch(matchId)!
+
+                  const preload = resolvePreload(matchId)
+
+                  const beforeLoadFnContext: BeforeLoadContextOptions<
+                    any,
+                    any,
+                    any,
+                    any,
+                    any
+                  > = {
+                    search,
+                    abortController,
+                    params,
+                    preload,
+                    context,
+                    location,
+                    navigate: (opts: any) =>
+                      this.navigate({ ...opts, _fromLocation: location }),
+                    buildLocation: this.buildLocation,
+                    cause: preload ? 'preload' : cause,
+                    matches,
+                  }
+
+                  const beforeLoadContext =
+                    (await route.options.beforeLoad?.(beforeLoadFnContext)) ??
+                    {}
+
+                  if (
+                    isRedirect(beforeLoadContext) ||
+                    isNotFound(beforeLoadContext)
+                  ) {
+                    handleSerialError(index, beforeLoadContext, 'BEFORE_LOAD')
+                  }
+
+                  updateMatch(matchId, (prev) => {
+                    return {
+                      ...prev,
+                      __beforeLoadContext: beforeLoadContext,
+                      context: {
+                        ...getParentMatchContext(),
+                        ...prev.__routeContext,
+                        ...beforeLoadContext,
+                      },
+                      abortController,
+                    }
+                  })
+                } catch (err) {
+                  handleSerialError(index, err, 'BEFORE_LOAD')
+                }
 
-        findMatchInRoutes([], filteredRoutes)
+                updateMatch(matchId, (prev) => {
+                  prev.beforeLoadPromise?.resolve()
 
-        if (!foundRoutes.length) {
-          return
-        }
+                  return {
+                    ...prev,
+                    beforeLoadPromise: undefined,
+                    isFetching: false,
+                  }
+                })
+              }
+            }
 
-        foundRoutes.forEach((foundRoute) => {
-          const interpolatedPath = interpolatePath(foundRoute.routePath, params)
-          const matchId = interpolatePath(foundRoute.routeId, params, true)
-
-          const match =
-            existingMatches.find((d) => d.matchId === matchId) ||
-            router.matchCache[matchId]?.match ||
-            createRouteMatch(router, foundRoute, {
-              matchId,
-              params,
-              pathname: joinPaths([pathname, interpolatedPath]),
+            const validResolvedMatches = matches.slice(0, firstBadMatchIndex)
+            const matchPromises: Array<Promise<AnyRouteMatch>> = []
+
+            validResolvedMatches.forEach(({ id: matchId, routeId }, index) => {
+              matchPromises.push(
+                (async () => {
+                  const { loaderPromise: prevLoaderPromise } =
+                    this.getMatch(matchId)!
+
+                  let loaderShouldRunAsync = false
+                  let loaderIsRunningAsync = false
+
+                  if (prevLoaderPromise) {
+                    await prevLoaderPromise
+                    const match = this.getMatch(matchId)!
+                    if (match.error) {
+                      handleRedirectAndNotFound(match, match.error)
+                    }
+                  } else {
+                    const parentMatchPromise = matchPromises[index - 1] as any
+                    const route = this.looseRoutesById[routeId]!
+
+                    const getLoaderContext = (): LoaderFnContext => {
+                      const {
+                        params,
+                        loaderDeps,
+                        abortController,
+                        context,
+                        cause,
+                      } = this.getMatch(matchId)!
+
+                      const preload = resolvePreload(matchId)
+
+                      return {
+                        params,
+                        deps: loaderDeps,
+                        preload: !!preload,
+                        parentMatchPromise,
+                        abortController: abortController,
+                        context,
+                        location,
+                        navigate: (opts) =>
+                          this.navigate({ ...opts, _fromLocation: location }),
+                        cause: preload ? 'preload' : cause,
+                        route,
+                      }
+                    }
+
+                    // This is where all of the stale-while-revalidate magic happens
+                    const age = Date.now() - this.getMatch(matchId)!.updatedAt
+
+                    const preload = resolvePreload(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(getLoaderContext())
+                        : shouldReloadOption
+
+                    updateMatch(matchId, (prev) => ({
+                      ...prev,
+                      loaderPromise: createControlledPromise<void>(),
+                      preload:
+                        !!preload &&
+                        !this.state.matches.find((d) => d.id === matchId),
+                    }))
+
+                    const runLoader = async () => {
+                      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
+                        const potentialPendingMinPromise = async () => {
+                          const latestMatch = this.getMatch(matchId)!
+
+                          if (latestMatch.minPendingPromise) {
+                            await latestMatch.minPendingPromise
+                          }
+                        }
+
+                        // Actually run the loader and handle the result
+                        try {
+                          this.loadRouteChunk(route)
+
+                          updateMatch(matchId, (prev) => ({
+                            ...prev,
+                            isFetching: 'loader',
+                          }))
+
+                          // Kick off the loader!
+                          const loaderData =
+                            await route.options.loader?.(getLoaderContext())
+
+                          handleRedirectAndNotFound(
+                            this.getMatch(matchId)!,
+                            loaderData,
+                          )
+
+                          // Lazy option can modify the route options,
+                          // so we need to wait for it to resolve before
+                          // we can use the options
+                          await route._lazyPromise
+
+                          await potentialPendingMinPromise()
+
+                          const assetContext = {
+                            matches,
+                            match: this.getMatch(matchId)!,
+                            params: this.getMatch(matchId)!.params,
+                            loaderData,
+                          }
+                          const headFnContent =
+                            route.options.head?.(assetContext)
+                          const meta = headFnContent?.meta
+                          const links = headFnContent?.links
+                          const headScripts = headFnContent?.scripts
+
+                          const scripts = route.options.scripts?.(assetContext)
+                          const headers = route.options.headers?.({
+                            loaderData,
+                          })
+
+                          // Last but not least, wait for the the components
+                          // to be preloaded before we resolve the match
+                          await route._componentsPromise
+
+                          updateMatch(matchId, (prev) => ({
+                            ...prev,
+                            error: undefined,
+                            status: 'success',
+                            isFetching: false,
+                            updatedAt: Date.now(),
+                            loaderData,
+                            meta,
+                            links,
+                            headScripts,
+                            headers,
+                            scripts,
+                          }))
+                        } catch (e) {
+                          let error = e
+
+                          await potentialPendingMinPromise()
+
+                          handleRedirectAndNotFound(this.getMatch(matchId)!, e)
+
+                          try {
+                            route.options.onError?.(e)
+                          } catch (onErrorError) {
+                            error = onErrorError
+                            handleRedirectAndNotFound(
+                              this.getMatch(matchId)!,
+                              onErrorError,
+                            )
+                          }
+
+                          updateMatch(matchId, (prev) => ({
+                            ...prev,
+                            error,
+                            status: 'error',
+                            isFetching: false,
+                          }))
+                        }
+
+                        this.serverSsr?.onMatchSettled({
+                          router: this,
+                          match: this.getMatch(matchId)!,
+                        })
+                      } catch (err) {
+                        updateMatch(matchId, (prev) => ({
+                          ...prev,
+                          loaderPromise: undefined,
+                        }))
+                        handleRedirectAndNotFound(this.getMatch(matchId)!, err)
+                      }
+                    }
+
+                    // 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 && !sync) {
+                      loaderIsRunningAsync = true
+                      ;(async () => {
+                        try {
+                          await runLoader()
+                          const { loaderPromise, loadPromise } =
+                            this.getMatch(matchId)!
+                          loaderPromise?.resolve()
+                          loadPromise?.resolve()
+                          updateMatch(matchId, (prev) => ({
+                            ...prev,
+                            loaderPromise: undefined,
+                          }))
+                        } catch (err) {
+                          if (isRedirect(err)) {
+                            await this.navigate(err.options)
+                          }
+                        }
+                      })()
+                    } else if (
+                      status !== 'success' ||
+                      (loaderShouldRunAsync && sync)
+                    ) {
+                      await runLoader()
+                    }
+                  }
+                  if (!loaderIsRunningAsync) {
+                    const { loaderPromise, loadPromise } =
+                      this.getMatch(matchId)!
+                    loaderPromise?.resolve()
+                    loadPromise?.resolve()
+                  }
+
+                  updateMatch(matchId, (prev) => ({
+                    ...prev,
+                    isFetching: loaderIsRunningAsync ? prev.isFetching : false,
+                    loaderPromise: loaderIsRunningAsync
+                      ? prev.loaderPromise
+                      : undefined,
+                    invalid: false,
+                  }))
+                  return this.getMatch(matchId)!
+                })(),
+              )
             })
 
-          matches.push(match)
-        })
+            await Promise.all(matchPromises)
 
-        const foundRoute = last(foundRoutes)!
+            resolveAll()
+          } catch (err) {
+            rejectAll(err)
+          }
+        })()
+      })
+      await triggerOnReady()
+    } catch (err) {
+      if (isRedirect(err) || isNotFound(err)) {
+        if (isNotFound(err) && !allPreload) {
+          await triggerOnReady()
+        }
+
+        throw err
+      }
+    }
 
-        if (foundRoute.childRoutes?.length) {
-          recurse(foundRoute.childRoutes)
+    return matches
+  }
+
+  invalidate: InvalidateFn<
+    RouterCore<
+      TRouteTree,
+      TTrailingSlashOption,
+      TDefaultStructuralSharingOption,
+      TRouterHistory,
+      TDehydrated
+    >
+  > = (opts) => {
+    const invalidate = (d: MakeRouteMatch<TRouteTree>) => {
+      if (opts?.filter?.(d as MakeRouteMatchUnion<this>) ?? true) {
+        return {
+          ...d,
+          invalid: true,
+          ...(d.status === 'error'
+            ? ({ status: 'pending', error: undefined } as const)
+            : {}),
         }
       }
+      return d
+    }
 
-      recurse([router.routeTree])
+    this.__store.setState((s) => ({
+      ...s,
+      matches: s.matches.map(invalidate),
+      cachedMatches: s.cachedMatches.map(invalidate),
+      pendingMatches: s.pendingMatches?.map(invalidate),
+    }))
 
-      cascadeLoaderData(matches)
+    return this.load({ sync: opts?.sync })
+  }
 
-      return matches
-    },
+  resolveRedirect = (redirect: AnyRedirect): AnyRedirect => {
+    if (!redirect.options.href) {
+      redirect.options.href = this.buildLocation(redirect.options).href
+      redirect.headers.set('Location', redirect.options.href)
+    }
 
-    loadMatches: async (resolvedMatches, loaderOpts) => {
-      const matchPromises = resolvedMatches.map(async (match) => {
-        // Validate the match (loads search params etc)
-        match.__.validate()
-        match.load(loaderOpts)
+    if (!redirect.headers.get('Location')) {
+      redirect.headers.set('Location', redirect.options.href)
+    }
 
-        if (match.status === 'loading') {
-          // If requested, start the pending timers
-          if (loaderOpts?.withPending) match.__.startPending()
+    return redirect
+  }
 
-          // Wait for the first sign of activity from the match
-          // This might be completion, error, or a pending state
-          await match.__.loadPromise
+  clearCache: ClearCacheFn<this> = (opts) => {
+    const filter = opts?.filter
+    if (filter !== undefined) {
+      this.__store.setState((s) => {
+        return {
+          ...s,
+          cachedMatches: s.cachedMatches.filter(
+            (m) => !filter(m as MakeRouteMatchUnion<this>),
+          ),
         }
       })
-
-      router.notify()
-
-      await Promise.all(matchPromises)
-    },
-
-    invalidateRoute: (opts: MatchLocation) => {
-      const next = router.buildNext(opts)
-      const unloadedMatchIds = router
-        .matchRoutes(next.pathname)
-        .map((d) => d.matchId)
-      ;[
-        ...router.state.matches,
-        ...(router.state.pending?.matches ?? []),
-      ].forEach((match) => {
-        if (unloadedMatchIds.includes(match.matchId)) {
-          match.invalidate()
+    } else {
+      this.__store.setState((s) => {
+        return {
+          ...s,
+          cachedMatches: [],
         }
       })
-    },
+    }
+  }
 
-    reload: () =>
-      router.__.navigate({
-        fromCurrent: true,
-        replace: true,
-        search: true,
-      }),
+  clearExpiredCache = () => {
+    // This is where all of the garbage collection magic happens
+    const filter = (d: MakeRouteMatch<TRouteTree>) => {
+      const route = this.looseRoutesById[d.routeId]!
 
-    resolvePath: (from: string, path: string) => {
-      return resolvePath(router.basepath!, from, cleanPath(path))
-    },
+      if (!route.options.loader) {
+        return true
+      }
 
-    matchRoute: (location, opts) => {
-      // const location = router.buildNext(opts)
+      // 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
+
+      return !(d.status !== 'error' && Date.now() - d.updatedAt < gcTime)
+    }
+    this.clearCache({ filter })
+  }
 
-      location = {
-        ...location,
-        to: location.to
-          ? router.resolvePath(location.from ?? '', location.to)
-          : undefined,
+  loadRouteChunk = (route: AnyRoute) => {
+    if (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)
+        })
+      } else {
+        route._lazyPromise = Promise.resolve()
       }
+    }
+
+    // If for some reason lazy resolves more lazy components...
+    // We'll wait for that before pre attempt to preload any
+    // components themselves.
+    if (route._componentsPromise === undefined) {
+      route._componentsPromise = route._lazyPromise.then(() =>
+        Promise.all(
+          componentTypes.map(async (type) => {
+            const component = route.options[type]
+            if ((component as any)?.preload) {
+              await (component as any).preload()
+            }
+          }),
+        ),
+      )
+    }
+    return route._componentsPromise
+  }
 
-      const next = router.buildNext(location)
+  preloadRoute: PreloadRouteFn<
+    TRouteTree,
+    TTrailingSlashOption,
+    TDefaultStructuralSharingOption,
+    TRouterHistory
+  > = async (opts) => {
+    const next = this.buildLocation(opts as any)
+
+    let matches = this.matchRoutes(next, {
+      throwOnError: true,
+      preload: true,
+      dest: opts,
+    })
+
+    const activeMatchIds = new Set(
+      [...this.state.matches, ...(this.state.pendingMatches ?? [])].map(
+        (d) => d.id,
+      ),
+    )
+
+    const loadedMatchIds = new Set([
+      ...activeMatchIds,
+      ...this.state.cachedMatches.map((d) => d.id),
+    ])
+
+    // If the matches are already loaded, we need to add them to the cachedMatches
+    batch(() => {
+      matches.forEach((match) => {
+        if (!loadedMatchIds.has(match.id)) {
+          this.__store.setState((s) => ({
+            ...s,
+            cachedMatches: [...(s.cachedMatches as any), match],
+          }))
+        }
+      })
+    })
 
-      if (opts?.pending) {
-        if (!router.state.pending?.location) {
-          return false
+    try {
+      matches = await this.loadMatches({
+        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 !!matchPathname(router.state.pending.location.pathname, {
-          ...opts,
-          to: next.pathname,
+        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
+    }
+  }
 
-      return !!matchPathname(router.state.location.pathname, {
-        ...opts,
-        to: next.pathname,
-      })
-    },
+  matchRoute: MatchRouteFn<
+    TRouteTree,
+    TTrailingSlashOption,
+    TDefaultStructuralSharingOption,
+    TRouterHistory
+  > = (location, opts) => {
+    const matchLocation = {
+      ...location,
+      to: location.to
+        ? this.resolvePathWithBase(
+            (location.from || '') as string,
+            location.to as string,
+          )
+        : undefined,
+      params: location.params || {},
+      leaveParams: true,
+    }
+    const next = this.buildLocation(matchLocation as any)
+
+    if (opts?.pending && this.state.status !== 'pending') {
+      return false
+    }
+
+    const pending =
+      opts?.pending === undefined ? !this.state.isLoading : opts.pending
+
+    const baseLocation = pending
+      ? this.latestLocation
+      : this.state.resolvedLocation || this.state.location
+
+    const match = matchPathname(this.basepath, baseLocation.pathname, {
+      ...opts,
+      to: next.pathname,
+    }) as any
+
+    if (!match) {
+      return false
+    }
+    if (location.params) {
+      if (!deepEqual(match, location.params, { partial: true })) {
+        return false
+      }
+    }
 
-    navigate: async ({ from, to = '.', search, hash, replace, params }) => {
-      // If this link simply reloads the current route,
-      // make sure it has a new key so it will trigger a data refresh
+    if (match && (opts?.includeSearch ?? true)) {
+      return deepEqual(baseLocation.search, next.search, { partial: true })
+        ? match
+        : false
+    }
 
-      // If this `to` is a valid external URL, return
-      // null for LinkUtils
-      const toString = String(to)
-      const fromString = String(from)
+    return match
+  }
 
-      let isExternal
+  ssr?: {
+    manifest: Manifest | undefined
+    serializer: StartSerializer
+  }
 
-      try {
-        new URL(`${toString}`)
-        isExternal = true
-      } catch (e) {}
+  serverSsr?: {
+    injectedHtml: Array<InjectedHtmlEntry>
+    injectHtml: (getHtml: () => string | Promise<string>) => Promise<void>
+    injectScript: (
+      getScript: () => string | Promise<string>,
+      opts?: { logScript?: boolean },
+    ) => Promise<void>
+    streamValue: (key: string, value: any) => void
+    streamedKeys: Set<string>
+    onMatchSettled: (opts: { router: AnyRouter; match: AnyRouteMatch }) => any
+  }
 
-      invariant(
-        !isExternal,
-        'Attempting to navigate to external url with router.navigate!',
-      )
+  clientSsr?: {
+    getStreamedValue: <T>(key: string) => T | undefined
+  }
 
-      return router.__.navigate({
-        from: fromString,
-        to: toString,
-        search,
-        hash,
-        replace,
-        params,
-      })
-    },
+  _handleNotFound = (
+    matches: Array<AnyRouteMatch>,
+    err: NotFoundError,
+    {
+      updateMatch = this.updateMatch,
+    }: {
+      updateMatch?: (
+        id: string,
+        updater: (match: AnyRouteMatch) => AnyRouteMatch,
+      ) => void
+    } = {},
+  ) => {
+    // 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 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
+    updateMatch(matchForRoute.id, (prev) => ({
+      ...prev,
+      status: 'notFound',
+      error: err,
+      isFetching: false,
+    }))
 
-    buildLink: ({
-      from,
-      to = '.',
-      search,
-      params,
-      hash,
-      target,
-      replace,
-      activeOptions,
-      preload,
-      preloadMaxAge: userPreloadMaxAge,
-      preloadGcMaxAge: userPreloadGcMaxAge,
-      preloadDelay: userPreloadDelay,
-      disabled,
-    }) => {
-      // If this link simply reloads the current route,
-      // make sure it has a new key so it will trigger a data refresh
-
-      // If this `to` is a valid external URL, return
-      // null for LinkUtils
+    if ((err as any).routerCode === 'BEFORE_LOAD' && routeCursor.parentRoute) {
+      err.routeId = routeCursor.parentRoute.id
+      this._handleNotFound(matches, err, {
+        updateMatch,
+      })
+    }
+  }
 
-      try {
-        new URL(`${to}`)
-        return {
-          type: 'external',
-          href: to,
-        }
-      } catch (e) {}
+  hasNotFoundMatch = () => {
+    return this.__store.state.matches.some(
+      (d) => d.status === 'notFound' || d.globalNotFound,
+    )
+  }
+}
 
-      const nextOpts = {
-        from,
-        to,
-        search,
-        params,
-        hash,
-        replace,
-      }
+export class SearchParamError extends Error {}
+
+export class PathParamError extends Error {}
+
+// A function that takes an import() argument which is a function and returns a new function that will
+// proxy arguments from the caller to the imported function, retaining all type
+// information along the way
+export function lazyFn<
+  T extends Record<string, (...args: Array<any>) => any>,
+  TKey extends keyof T = 'default',
+>(fn: () => Promise<T>, key?: TKey) {
+  return async (
+    ...args: Parameters<T[TKey]>
+  ): Promise<Awaited<ReturnType<T[TKey]>>> => {
+    const imported = await fn()
+    return imported[key || 'default'](...args)
+  }
+}
 
-      const next = router.buildNext(nextOpts)
+export function getInitialRouterState(
+  location: ParsedLocation,
+): RouterState<any> {
+  return {
+    loadedAt: 0,
+    isLoading: false,
+    isTransitioning: false,
+    status: 'idle',
+    resolvedLocation: undefined,
+    location,
+    matches: [],
+    pendingMatches: [],
+    cachedMatches: [],
+    statusCode: 200,
+  }
+}
 
-      preload = preload ?? router.options.defaultPreload
-      const preloadDelay =
-        userPreloadDelay ?? router.options.defaultPreloadDelay ?? 0
+function validateSearch(validateSearch: AnyValidator, input: unknown): unknown {
+  if (validateSearch == null) return {}
 
-      // Compare path/hash for matches
-      const pathIsEqual = router.state.location.pathname === next.pathname
-      const currentPathSplit = router.state.location.pathname.split('/')
-      const nextPathSplit = next.pathname.split('/')
-      const pathIsFuzzyEqual = nextPathSplit.every(
-        (d, i) => d === currentPathSplit[i],
-      )
-      const hashIsEqual = router.state.location.hash === next.hash
-      // Combine the matches based on user options
-      const pathTest = activeOptions?.exact ? pathIsEqual : pathIsFuzzyEqual
-      const hashTest = activeOptions?.includeHash ? hashIsEqual : true
+  if ('~standard' in validateSearch) {
+    const result = validateSearch['~standard'].validate(input)
 
-      // The final "active" test
-      const isActive = pathTest && hashTest
+    if (result instanceof Promise)
+      throw new SearchParamError('Async validation not supported')
 
-      // The click handler
-      const handleClick = (e: MouseEvent) => {
-        if (
-          !disabled &&
-          !isCtrlEvent(e) &&
-          !e.defaultPrevented &&
-          (!target || target === '_self') &&
-          e.button === 0
-        ) {
-          e.preventDefault()
-          if (pathIsEqual && !search && !hash) {
-            router.invalidateRoute(nextOpts)
-          }
+    if (result.issues)
+      throw new SearchParamError(JSON.stringify(result.issues, undefined, 2), {
+        cause: result,
+      })
 
-          // All is well? Navigate!)
-          router.__.navigate(nextOpts)
-        }
-      }
+    return result.value
+  }
 
-      // The click handler
-      const handleFocus = (e: MouseEvent) => {
-        if (preload) {
-          router.preloadRoute(nextOpts, {
-            maxAge: userPreloadMaxAge,
-            gcMaxAge: userPreloadGcMaxAge,
-          })
-        }
-      }
+  if ('parse' in validateSearch) {
+    return validateSearch.parse(input)
+  }
 
-      const handleEnter = (e: MouseEvent) => {
-        const target = (e.target || {}) as LinkCurrentTargetElement
+  if (typeof validateSearch === 'function') {
+    return validateSearch(input)
+  }
 
-        if (preload) {
-          if (target.preloadTimeout) {
-            return
-          }
+  return {}
+}
 
-          target.preloadTimeout = setTimeout(() => {
-            target.preloadTimeout = null
-            router.preloadRoute(nextOpts, {
-              maxAge: userPreloadMaxAge,
-              gcMaxAge: userPreloadGcMaxAge,
-            })
-          }, preloadDelay)
-        }
-      }
+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
+}
 
-      const handleLeave = (e: MouseEvent) => {
-        const target = (e.target || {}) as LinkCurrentTargetElement
+interface RouteLike {
+  id: string
+  isRoot?: boolean
+  path?: string
+  fullPath: string
+  rank?: number
+  parentRoute?: RouteLike
+  children?: Array<RouteLike>
+  options?: {
+    caseSensitive?: boolean
+  }
+}
 
-        if (target.preloadTimeout) {
-          clearTimeout(target.preloadTimeout)
-          target.preloadTimeout = null
-        }
-      }
+export function processRouteTree<TRouteLike extends RouteLike>({
+  routeTree,
+  initRoute,
+}: {
+  routeTree: TRouteLike
+  initRoute?: (route: TRouteLike, index: number) => void
+}) {
+  const routesById = {} as Record<string, TRouteLike>
+  const routesByPath = {} as Record<string, TRouteLike>
 
-      return {
-        type: 'internal',
-        next,
-        handleFocus,
-        handleClick,
-        handleEnter,
-        handleLeave,
-        isActive,
-        disabled,
-      }
-    },
-    buildNext: (opts: BuildNextOptions) => {
-      const next = router.__.buildLocation(opts)
-
-      const matches = router.matchRoutes(next.pathname)
-
-      const __preSearchFilters = matches
-        .map((match) => match.options.preSearchFilters ?? [])
-        .flat()
-        .filter(Boolean)
-
-      const __postSearchFilters = matches
-        .map((match) => match.options.postSearchFilters ?? [])
-        .flat()
-        .filter(Boolean)
-
-      return router.__.buildLocation({
-        ...opts,
-        __preSearchFilters,
-        __postSearchFilters,
-      })
-    },
-
-    __: {
-      buildRouteTree: (rootRouteConfig: RouteConfig) => {
-        const recurseRoutes = (
-          routeConfigs: RouteConfig[],
-          parent?: Route<TAllRouteInfo, any>,
-        ): Route<TAllRouteInfo, any>[] => {
-          return routeConfigs.map((routeConfig) => {
-            const routeOptions = routeConfig.options
-            const route = createRoute(routeConfig, routeOptions, parent, router)
-            const existingRoute = (router.routesById as any)[route.routeId]
-
-            if (existingRoute) {
-              if (process.env.NODE_ENV !== 'production') {
-                console.warn(
-                  `Duplicate routes found with id: ${String(route.routeId)}`,
-                  router.routesById,
-                  route,
-                )
-              }
-              throw new Error()
-            }
+  const recurseRoutes = (childRoutes: Array<TRouteLike>) => {
+    childRoutes.forEach((childRoute, i) => {
+      initRoute?.(childRoute, i)
 
-            ;(router.routesById as any)[route.routeId] = route
+      const existingRoute = routesById[childRoute.id]
 
-            const children = routeConfig.children as RouteConfig[]
+      invariant(
+        !existingRoute,
+        `Duplicate routes found with id: ${String(childRoute.id)}`,
+      )
 
-            route.childRoutes = children?.length
-              ? recurseRoutes(children, route)
-              : undefined
+      routesById[childRoute.id] = childRoute
 
-            return route
-          })
+      if (!childRoute.isRoot && childRoute.path) {
+        const trimmedFullPath = trimPathRight(childRoute.fullPath)
+        if (
+          !routesByPath[trimmedFullPath] ||
+          childRoute.fullPath.endsWith('/')
+        ) {
+          routesByPath[trimmedFullPath] = childRoute
         }
+      }
 
-        const routes = recurseRoutes([rootRouteConfig])
+      const children = childRoute.children as Array<TRouteLike>
 
-        return routes[0]!
-      },
+      if (children?.length) {
+        recurseRoutes(children)
+      }
+    })
+  }
 
-      parseLocation: (
-        location: History['location'],
-        previousLocation?: Location,
-      ): Location => {
-        const parsedSearch = router.options.parseSearch(location.search)
+  recurseRoutes([routeTree])
 
-        return {
-          pathname: location.pathname,
-          searchStr: location.search,
-          search: replaceEqualDeep(previousLocation?.search, parsedSearch),
-          hash: location.hash.split('#').reverse()[0] ?? '',
-          href: `${location.pathname}${location.search}${location.hash}`,
-          state: location.state as LocationState,
-          key: location.key,
-        }
-      },
+  const scoredRoutes: Array<{
+    child: TRouteLike
+    trimmed: string
+    parsed: ReturnType<typeof parsePathname>
+    index: number
+    scores: Array<number>
+  }> = []
 
-      navigate: (location: BuildNextOptions & { replace?: boolean }) => {
-        const next = router.buildNext(location)
-        return router.__.commitLocation(next, location.replace)
-      },
+  const routes: Array<TRouteLike> = Object.values(routesById)
 
-      buildLocation: (dest: BuildNextOptions = {}): Location => {
-        // const resolvedFrom: Location = {
-        //   ...router.location,
-        const fromPathname = dest.fromCurrent
-          ? router.location.pathname
-          : dest.from ?? router.location.pathname
-
-        let pathname = resolvePath(
-          router.basepath ?? '/',
-          fromPathname,
-          `${dest.to ?? '.'}`,
-        )
+  routes.forEach((d, i) => {
+    if (d.isRoot || !d.path) {
+      return
+    }
 
-        const fromMatches = router.matchRoutes(router.location.pathname, {
-          strictParseParams: true,
-        })
+    const trimmed = trimPathLeft(d.fullPath)
+    const parsed = parsePathname(trimmed)
 
-        const toMatches = router.matchRoutes(pathname)
+    // Removes the leading slash if it is not the only remaining segment
+    while (parsed.length > 1 && parsed[0]?.value === '/') {
+      parsed.shift()
+    }
 
-        const prevParams = { ...last(fromMatches)?.params }
+    const scores = parsed.map((segment) => {
+      if (segment.value === '/') {
+        return 0.75
+      }
 
-        let nextParams =
-          (dest.params ?? true) === true
-            ? prevParams
-            : functionalUpdate(dest.params!, prevParams)
+      if (
+        segment.type === 'param' &&
+        segment.prefixSegment &&
+        segment.suffixSegment
+      ) {
+        return 0.55
+      }
 
-        if (nextParams) {
-          toMatches
-            .map((d) => d.options.stringifyParams)
-            .filter(Boolean)
-            .forEach((fn) => {
-              Object.assign({}, nextParams!, fn!(nextParams!))
-            })
-        }
+      if (segment.type === 'param' && segment.prefixSegment) {
+        return 0.52
+      }
 
-        pathname = interpolatePath(pathname, nextParams ?? {})
+      if (segment.type === 'param' && segment.suffixSegment) {
+        return 0.51
+      }
 
-        // Pre filters first
-        const preFilteredSearch = dest.__preSearchFilters?.length
-          ? dest.__preSearchFilters.reduce(
-              (prev, next) => next(prev),
-              router.location.search,
-            )
-          : router.location.search
-
-        // Then the link/navigate function
-        const destSearch =
-          dest.search === true
-            ? preFilteredSearch // Preserve resolvedFrom true
-            : dest.search
-            ? functionalUpdate(dest.search, preFilteredSearch) ?? {} // Updater
-            : dest.__preSearchFilters?.length
-            ? preFilteredSearch // Preserve resolvedFrom filters
-            : {}
+      if (segment.type === 'param') {
+        return 0.5
+      }
 
-        // Then post filters
-        const postFilteredSearch = dest.__postSearchFilters?.length
-          ? dest.__postSearchFilters.reduce(
-              (prev, next) => next(prev),
-              destSearch,
-            )
-          : destSearch
+      if (
+        segment.type === 'wildcard' &&
+        segment.prefixSegment &&
+        segment.suffixSegment
+      ) {
+        return 0.3
+      }
 
-        const search = replaceEqualDeep(
-          router.location.search,
-          postFilteredSearch,
-        )
+      if (segment.type === 'wildcard' && segment.prefixSegment) {
+        return 0.27
+      }
 
-        const searchStr = router.options.stringifySearch(search)
-        let hash =
-          dest.hash === true
-            ? router.location.hash
-            : functionalUpdate(dest.hash!, router.location.hash)
-        hash = hash ? `#${hash}` : ''
+      if (segment.type === 'wildcard' && segment.suffixSegment) {
+        return 0.26
+      }
 
-        return {
-          pathname,
-          search,
-          searchStr,
-          state: router.location.state,
-          hash,
-          href: `${pathname}${searchStr}${hash}`,
-          key: dest.key,
-        }
-      },
+      if (segment.type === 'wildcard') {
+        return 0.25
+      }
 
-      commitLocation: (next: Location, replace?: boolean): Promise<void> => {
-        const id = '' + Date.now() + Math.random()
+      return 1
+    })
 
-        if (router.navigateTimeout) clearTimeout(router.navigateTimeout)
+    scoredRoutes.push({ child: d, trimmed, parsed, index: i, scores })
+  })
 
-        let nextAction: 'push' | 'replace' = 'replace'
+  const flatRoutes = scoredRoutes
+    .sort((a, b) => {
+      const minLength = Math.min(a.scores.length, b.scores.length)
 
-        if (!replace) {
-          nextAction = 'push'
+      // Sort by min available score
+      for (let i = 0; i < minLength; i++) {
+        if (a.scores[i] !== b.scores[i]) {
+          return b.scores[i]! - a.scores[i]!
         }
+      }
 
-        const isSameUrl =
-          router.__.parseLocation(history.location).href === next.href
+      // Sort by length of score
+      if (a.scores.length !== b.scores.length) {
+        return b.scores.length - a.scores.length
+      }
 
-        if (isSameUrl && !next.key) {
-          nextAction = 'replace'
+      // Sort by min available parsed value
+      for (let i = 0; i < minLength; i++) {
+        if (a.parsed[i]!.value !== b.parsed[i]!.value) {
+          return a.parsed[i]!.value > b.parsed[i]!.value ? 1 : -1
         }
+      }
 
-        if (nextAction === 'replace') {
-          history.replace(
-            {
-              pathname: next.pathname,
-              hash: next.hash,
-              search: next.searchStr,
-            },
-            {
-              id,
-            },
-          )
-        } else {
-          history.push(
-            {
-              pathname: next.pathname,
-              hash: next.hash,
-              search: next.searchStr,
-            },
-            {
-              id,
-            },
-          )
-        }
+      // Sort by original index
+      return a.index - b.index
+    })
+    .map((d, i) => {
+      d.child.rank = i
+      return d.child
+    })
 
-        router.navigationPromise = new Promise((resolve) => {
-          const previousNavigationResolve = router.resolveNavigation
+  return { routesById, routesByPath, flatRoutes }
+}
 
-          router.resolveNavigation = () => {
-            previousNavigationResolve()
-            resolve()
-          }
-        })
+export function getMatchedRoutes<TRouteLike extends RouteLike>({
+  pathname,
+  routePathname,
+  basepath,
+  caseSensitive,
+  routesByPath,
+  routesById,
+  flatRoutes,
+}: {
+  pathname: string
+  routePathname?: string
+  basepath: string
+  caseSensitive?: boolean
+  routesByPath: Record<string, TRouteLike>
+  routesById: Record<string, TRouteLike>
+  flatRoutes: Array<TRouteLike>
+}) {
+  let routeParams: Record<string, string> = {}
+  const trimmedPath = trimPathRight(pathname)
+  const getMatchedParams = (route: TRouteLike) => {
+    const result = matchPathname(basepath, trimmedPath, {
+      to: route.fullPath,
+      caseSensitive: route.options?.caseSensitive ?? caseSensitive,
+      fuzzy: true,
+    })
+    return result
+  }
 
-        return router.navigationPromise
-      },
-    },
+  let foundRoute: TRouteLike | undefined =
+    routePathname !== undefined ? routesByPath[routePathname] : undefined
+  if (foundRoute) {
+    routeParams = getMatchedParams(foundRoute)!
+  } else {
+    foundRoute = flatRoutes.find((route) => {
+      const matchedParams = getMatchedParams(route)
+
+      if (matchedParams) {
+        routeParams = matchedParams
+        return true
+      }
+
+      return false
+    })
   }
 
-  router.update(userOptions)
+  let routeCursor: TRouteLike = foundRoute || routesById[rootRouteId]!
 
-  // Allow frameworks to hook into the router creation
-  router.options.createRouter?.(router)
+  const matchedRoutes: Array<TRouteLike> = [routeCursor]
 
-  return router
-}
+  while (routeCursor.parentRoute) {
+    routeCursor = routeCursor.parentRoute as TRouteLike
+    matchedRoutes.unshift(routeCursor)
+  }
 
-function isCtrlEvent(e: MouseEvent) {
-  return !!(e.metaKey || e.altKey || e.ctrlKey || e.shiftKey)
+  return { matchedRoutes, routeParams, foundRoute }
 }