fix: match loading — review fixes and #7713 edge cases

.changeset/violet-poets-wait.md

@@ -15,3 +15,12 @@ Fix match loading consistency across client navigation, preloading, background r
 - SSR hydration now handles dehydrated and data-only matches in a dedicated hydration pass, restoring route context and assets without rerunning client loaders.
 - Server loading now has a dedicated path for status codes, redirects, notFound and error responses.
 - React, Solid, and Vue match rendering now consume the simplified match readiness model, including aborted loader errors, SSR/data-only pending fallbacks, and stale render snapshots.
+- Awaiting `router.load()` or `router.invalidate()` now settles only when the whole navigation chain settles, including superseded and redirected loads; preloads that borrow a pending-published foreground match wait for its commit instead of being dropped.
+- A navigation that starts while a hover/intent preload for the same route is in flight adopts the preload's loader run once it succeeds — the loader executes once, like before. Adoption is data-only: the navigation always runs its own `beforeLoad` (with `preload: false` semantics), and a preload that ends in a redirect, notFound, or error is never adopted — the navigation runs its own loader instead, so preload-flavored control flow can no longer leak into navigations (the old implementation could land you on a preload-computed redirect). Concurrent preloads of the same route also share one loader run.
+- Preloads now cache the successful ancestor prefix even when a descendant throws an error or `notFound`, so repeated hovers do not re-run expensive ancestor loaders.
+- Route chunk (lazy import) failures now run the normal route failure lifecycle: `onError` fires and thrown redirects/notFounds are honored. Error/notFound boundary chunks load independently of the route's other component chunks, and failed chunk preloads are retried on the next load instead of being cached forever.
+- Server rendering keeps route `headers()` when a decorative `head()`/`scripts()` hook fails (async `headers()` are always awaited), background reloads never publish fresh `loaderData` whose asset projection failed, and hydration no longer executes `head()`/`scripts()` for matches the server omitted (`ssr: false` or a server-side error/notFound boundary). The follow-up client load after hydration replays a server-committed notFound/error boundary, so routes the server omitted are not loaded or asset-projected client-side.
+- With `pendingMs: 0`, the pending fallback is published synchronously on bare initial loads (nothing rendered yet) instead of after a macrotask, eliminating the blank first frame.
+- Starting a navigation no longer aborts the `abortController` of settled success matches that stay mounted — deferred/streamed data tied to a stay-match's loader signal survives child navigations and `invalidate()`. Matches with in-flight `beforeLoad`/loader work are still cancelled.
+- Fresh data for routes you navigate away from survives pending publication: if a navigation is superseded (e.g. back button) after its pending UI was published, the exited matches are served from cache instead of re-running their loaders.
+- Behavior change (Vue): `useMatch({ from })` no longer suppresses its missing-match invariant during a navigation whose destination includes `from` before that navigation's first commit — it throws (or returns `undefined` when `shouldThrow: false`) exactly as it does at idle, matching React.

e2e/react-start/basic/src/routeTree.gen.ts

@@ -26,6 +26,7 @@ import { Route as LayoutRouteImport } from './routes/_layout'
 import { Route as SpecialCharsRouteRouteImport } from './routes/specialChars/route'
 import { Route as SearchParamsRouteRouteImport } from './routes/search-params/route'
 import { Route as NotFoundRouteRouteImport } from './routes/not-found/route'
+import { Route as HydrationCappedAssetsRouteRouteImport } from './routes/hydration-capped-assets/route'
 import { Route as IndexRouteImport } from './routes/index'
 import { Route as UsersIndexRouteImport } from './routes/users.index'
 import { Route as SearchParamsIndexRouteImport } from './routes/search-params/index'
@@ -53,6 +54,7 @@ import { Route as NotFoundViaLoaderRouteImport } from './routes/not-found/via-lo
 import { Route as NotFoundViaBeforeLoadTargetRootRouteImport } from './routes/not-found/via-beforeLoad-target-root'
 import { Route as NotFoundViaBeforeLoadRouteImport } from './routes/not-found/via-beforeLoad'
 import { Route as MultiCookieRedirectTargetRouteImport } from './routes/multi-cookie-redirect/target'
+import { Route as HydrationCappedAssetsChildRouteImport } from './routes/hydration-capped-assets/child'
 import { Route as ApiUsersRouteImport } from './routes/api.users'
 import { Route as LayoutLayout2RouteImport } from './routes/_layout/_layout-2'
 import { Route as SpecialCharsMalformedRouteRouteImport } from './routes/specialChars/malformed/route'
@@ -165,6 +167,12 @@ const NotFoundRouteRoute = NotFoundRouteRouteImport.update({
   path: '/not-found',
   getParentRoute: () => rootRouteImport,
 } as any)
+const HydrationCappedAssetsRouteRoute =
+  HydrationCappedAssetsRouteRouteImport.update({
+    id: '/hydration-capped-assets',
+    path: '/hydration-capped-assets',
+    getParentRoute: () => rootRouteImport,
+  } as any)
 const IndexRoute = IndexRouteImport.update({
   id: '/',
   path: '/',
@@ -305,6 +313,12 @@ const MultiCookieRedirectTargetRoute =
     path: '/multi-cookie-redirect/target',
     getParentRoute: () => rootRouteImport,
   } as any)
+const HydrationCappedAssetsChildRoute =
+  HydrationCappedAssetsChildRouteImport.update({
+    id: '/child',
+    path: '/child',
+    getParentRoute: () => HydrationCappedAssetsRouteRoute,
+  } as any)
 const ApiUsersRoute = ApiUsersRouteImport.update({
   id: '/api/users',
   path: '/api/users',
@@ -448,6 +462,7 @@ const NotFoundDeepBCDRoute = NotFoundDeepBCDRouteImport.update({
 
 export interface FileRoutesByFullPath {
   '/': typeof IndexRoute
+  '/hydration-capped-assets': typeof HydrationCappedAssetsRouteRouteWithChildren
   '/not-found': typeof NotFoundRouteRouteWithChildren
   '/search-params': typeof SearchParamsRouteRouteWithChildren
   '/specialChars': typeof SpecialCharsRouteRouteWithChildren
@@ -468,6 +483,7 @@ export interface FileRoutesByFullPath {
   '/not-found/parent-boundary': typeof NotFoundParentBoundaryRouteRouteWithChildren
   '/specialChars/malformed': typeof SpecialCharsMalformedRouteRouteWithChildren
   '/api/users': typeof ApiUsersRouteWithChildren
+  '/hydration-capped-assets/child': typeof HydrationCappedAssetsChildRoute
   '/multi-cookie-redirect/target': typeof MultiCookieRedirectTargetRoute
   '/not-found/via-beforeLoad': typeof NotFoundViaBeforeLoadRoute
   '/not-found/via-beforeLoad-target-root': typeof NotFoundViaBeforeLoadTargetRootRoute
@@ -518,6 +534,7 @@ export interface FileRoutesByFullPath {
 }
 export interface FileRoutesByTo {
   '/': typeof IndexRoute
+  '/hydration-capped-assets': typeof HydrationCappedAssetsRouteRouteWithChildren
   '/specialChars': typeof SpecialCharsRouteRouteWithChildren
   '/async-scripts': typeof AsyncScriptsRoute
   '/client-only': typeof ClientOnlyRoute
@@ -531,6 +548,7 @@ export interface FileRoutesByTo {
   '/type-only-reexport': typeof TypeOnlyReexportRoute
   '/specialChars/malformed': typeof SpecialCharsMalformedRouteRouteWithChildren
   '/api/users': typeof ApiUsersRouteWithChildren
+  '/hydration-capped-assets/child': typeof HydrationCappedAssetsChildRoute
   '/multi-cookie-redirect/target': typeof MultiCookieRedirectTargetRoute
   '/not-found/via-beforeLoad': typeof NotFoundViaBeforeLoadRoute
   '/not-found/via-beforeLoad-target-root': typeof NotFoundViaBeforeLoadTargetRootRoute
@@ -580,6 +598,7 @@ export interface FileRoutesByTo {
 export interface FileRoutesById {
   __root__: typeof rootRouteImport
   '/': typeof IndexRoute
+  '/hydration-capped-assets': typeof HydrationCappedAssetsRouteRouteWithChildren
   '/not-found': typeof NotFoundRouteRouteWithChildren
   '/search-params': typeof SearchParamsRouteRouteWithChildren
   '/specialChars': typeof SpecialCharsRouteRouteWithChildren
@@ -602,6 +621,7 @@ export interface FileRoutesById {
   '/specialChars/malformed': typeof SpecialCharsMalformedRouteRouteWithChildren
   '/_layout/_layout-2': typeof LayoutLayout2RouteWithChildren
   '/api/users': typeof ApiUsersRouteWithChildren
+  '/hydration-capped-assets/child': typeof HydrationCappedAssetsChildRoute
   '/multi-cookie-redirect/target': typeof MultiCookieRedirectTargetRoute
   '/not-found/via-beforeLoad': typeof NotFoundViaBeforeLoadRoute
   '/not-found/via-beforeLoad-target-root': typeof NotFoundViaBeforeLoadTargetRootRoute
@@ -654,6 +674,7 @@ export interface FileRouteTypes {
   fileRoutesByFullPath: FileRoutesByFullPath
   fullPaths:
     | '/'
+    | '/hydration-capped-assets'
     | '/not-found'
     | '/search-params'
     | '/specialChars'
@@ -674,6 +695,7 @@ export interface FileRouteTypes {
     | '/not-found/parent-boundary'
     | '/specialChars/malformed'
     | '/api/users'
+    | '/hydration-capped-assets/child'
     | '/multi-cookie-redirect/target'
     | '/not-found/via-beforeLoad'
     | '/not-found/via-beforeLoad-target-root'
@@ -724,6 +746,7 @@ export interface FileRouteTypes {
   fileRoutesByTo: FileRoutesByTo
   to:
     | '/'
+    | '/hydration-capped-assets'
     | '/specialChars'
     | '/async-scripts'
     | '/client-only'
@@ -737,6 +760,7 @@ export interface FileRouteTypes {
     | '/type-only-reexport'
     | '/specialChars/malformed'
     | '/api/users'
+    | '/hydration-capped-assets/child'
     | '/multi-cookie-redirect/target'
     | '/not-found/via-beforeLoad'
     | '/not-found/via-beforeLoad-target-root'
@@ -785,6 +809,7 @@ export interface FileRouteTypes {
   id:
     | '__root__'
     | '/'
+    | '/hydration-capped-assets'
     | '/not-found'
     | '/search-params'
     | '/specialChars'
@@ -807,6 +832,7 @@ export interface FileRouteTypes {
     | '/specialChars/malformed'
     | '/_layout/_layout-2'
     | '/api/users'
+    | '/hydration-capped-assets/child'
     | '/multi-cookie-redirect/target'
     | '/not-found/via-beforeLoad'
     | '/not-found/via-beforeLoad-target-root'
@@ -858,6 +884,7 @@ export interface FileRouteTypes {
 }
 export interface RootRouteChildren {
   IndexRoute: typeof IndexRoute
+  HydrationCappedAssetsRouteRoute: typeof HydrationCappedAssetsRouteRouteWithChildren
   NotFoundRouteRoute: typeof NotFoundRouteRouteWithChildren
   SearchParamsRouteRoute: typeof SearchParamsRouteRouteWithChildren
   SpecialCharsRouteRoute: typeof SpecialCharsRouteRouteWithChildren
@@ -1005,6 +1032,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof NotFoundRouteRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/hydration-capped-assets': {
+      id: '/hydration-capped-assets'
+      path: '/hydration-capped-assets'
+      fullPath: '/hydration-capped-assets'
+      preLoaderRoute: typeof HydrationCappedAssetsRouteRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/': {
       id: '/'
       path: '/'
@@ -1194,6 +1228,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof MultiCookieRedirectTargetRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/hydration-capped-assets/child': {
+      id: '/hydration-capped-assets/child'
+      path: '/child'
+      fullPath: '/hydration-capped-assets/child'
+      preLoaderRoute: typeof HydrationCappedAssetsChildRouteImport
+      parentRoute: typeof HydrationCappedAssetsRouteRoute
+    }
     '/api/users': {
       id: '/api/users'
       path: '/api/users'
@@ -1379,6 +1420,20 @@ declare module '@tanstack/react-router' {
   }
 }
 
+interface HydrationCappedAssetsRouteRouteChildren {
+  HydrationCappedAssetsChildRoute: typeof HydrationCappedAssetsChildRoute
+}
+
+const HydrationCappedAssetsRouteRouteChildren: HydrationCappedAssetsRouteRouteChildren =
+  {
+    HydrationCappedAssetsChildRoute: HydrationCappedAssetsChildRoute,
+  }
+
+const HydrationCappedAssetsRouteRouteWithChildren =
+  HydrationCappedAssetsRouteRoute._addFileChildren(
+    HydrationCappedAssetsRouteRouteChildren,
+  )
+
 interface NotFoundDeepBCRouteRouteChildren {
   NotFoundDeepBCDRoute: typeof NotFoundDeepBCDRoute
 }
@@ -1630,6 +1685,7 @@ const FooBarQuxHereRouteWithChildren = FooBarQuxHereRoute._addFileChildren(
 
 const rootRouteChildren: RootRouteChildren = {
   IndexRoute: IndexRoute,
+  HydrationCappedAssetsRouteRoute: HydrationCappedAssetsRouteRouteWithChildren,
   NotFoundRouteRoute: NotFoundRouteRouteWithChildren,
   SearchParamsRouteRoute: SearchParamsRouteRouteWithChildren,
   SpecialCharsRouteRoute: SpecialCharsRouteRouteWithChildren,

e2e/react-start/basic/src/routes/hydration-capped-assets/child.tsx

@@ -0,0 +1,25 @@
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/hydration-capped-assets/child')({
+  loader: () => ({
+    title: 'child loader data',
+  }),
+  head: ({ loaderData }) => ({
+    meta: [
+      {
+        name: 'capped-assets-child-head',
+        content: loaderData?.title ?? 'missing-loader-data',
+      },
+    ],
+  }),
+  scripts: ({ loaderData }) => [
+    {
+      children: `window.__CAPPED_ASSETS_CHILD_SCRIPT = ${JSON.stringify(
+        loaderData?.title ?? 'missing-loader-data',
+      )}`,
+    },
+  ],
+  component: () => (
+    <div data-testid="capped-assets-child-component">Child route</div>
+  ),
+})

e2e/react-start/basic/src/routes/hydration-capped-assets/route.tsx

@@ -0,0 +1,11 @@
+import { Outlet, createFileRoute, notFound } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/hydration-capped-assets')({
+  beforeLoad: () => {
+    throw notFound()
+  },
+  notFoundComponent: () => (
+    <div data-testid="capped-assets-parent-not-found">Parent not found</div>
+  ),
+  component: () => <Outlet />,
+})

e2e/react-start/basic/start-mode-config.ts

@@ -32,6 +32,7 @@ export function getStartModeConfig() {
               '/redirect',
               '/i-do-not-exist',
               '/not-found',
+              '/hydration-capped-assets',
               '/primitive-beforeload-error',
               '/specialChars/search',
               '/specialChars/hash',

e2e/react-start/basic/tests/hydration-capped-assets.spec.ts

@@ -0,0 +1,51 @@
+import { expect } from '@playwright/test'
+import { test } from '@tanstack/router-e2e-utils'
+import { isPrerender } from './utils/isPrerender'
+import { isSpaMode } from './utils/isSpaMode'
+
+/**
+ * On a direct SSR hard load, the server can intentionally cap the
+ * committed match list at a parent notFound/error boundary. Hydration should not
+ * project head/scripts for the child route that was omitted from the server
+ * match list, because those assets can be added with missing or stale loader
+ * data before the follow-up client load enforces the same boundary.
+ *
+ * This Playwright repro uses the real React Start app, a real browser page load,
+ * the real SSR response, and normal client hydration. The parent route throws
+ * notFound from beforeLoad, while its child route defines a meta tag and inline
+ * script; neither child asset should appear after loading the capped parent
+ * boundary response.
+ */
+
+test.use({
+  whitelistErrors: [
+    'Failed to load resource: the server responded with a status of 404',
+  ],
+})
+
+test.describe('SSR hydration capped route assets', () => {
+  test.skip(isSpaMode || isPrerender, 'SSR hydration repro only')
+
+  test('does not project assets for a child route omitted by the server boundary', async ({
+    page,
+  }) => {
+    await page.goto('/hydration-capped-assets/child')
+    await page.waitForLoadState('networkidle')
+
+    await expect(
+      page.getByTestId('capped-assets-parent-not-found'),
+    ).toBeInViewport()
+    await expect(
+      page.getByTestId('capped-assets-child-component'),
+    ).not.toBeInViewport()
+
+    await expect(
+      page.locator('meta[name="capped-assets-child-head"]'),
+    ).toHaveCount(0)
+    expect(
+      await page.evaluate(() =>
+        Boolean((window as any).__CAPPED_ASSETS_CHILD_SCRIPT),
+      ),
+    ).toBe(false)
+  })
+})