fix(router-core): complete lane match loader rewrite

[Sheraff]

Summary

This is a stacked follow-up to #7805 that brings the lane match-loader rewrite to its reviewed final state.

• consolidates client navigation, preload adoption, background reloads, hydration handoff, and render acknowledgement around transactional lanes
• keeps beforeLoad context lane-owned while retaining loader cache reuse by match identity
• preserves SSR loader and beforeLoad results during hydration, including selective SSR continuation
• exposes complete presentation lanes while rendering only through the active pending or terminal boundary
• simplifies lifecycle ordering to leave-first, with no public relative ordering contract between enter and stay
• removes unreachable-state defenses, legacy runtime authorities, and obsolete SSR match-ID machinery
• updates React, Solid, Vue, Start integrations, public documentation, architecture documentation, and behavior-level regression coverage

Additional fixes

The follow-up review pass also:

• adds a minimal, collision-safe dehydrated match identity to validate an SSR prefix before hydration adopts it, including reserved-character round trips, longer server lanes, root global not-found lanes, and ancestor-capped fuzzy URLs
• makes hydration reconstruction a cancellable preflight and rejects stale handoffs after the location, history state, router context, route tree, or accepted prefix identity changes
• preserves the complete structural lane for route context and head hooks without granting unresolved or terminal descendants hydration execution authority
• retries hydration from the earliest failed lazy chunk without waiting for irrelevant descendants, while preserving transported data and terminal errors that remain authoritative
• observes already-rejected and late promises during cancellation, propagates abort reasons, and avoids unhandled rejections
• centralizes SSR stream cleanup across request aborts, pending render callbacks, middleware replacement or failure, redirects, HEAD responses, and late response handoff, with exactly-once ownership
• moves HMR lazy-chunk replacement into the live router owner so a stale dynamic import cannot overwrite freshly hot-reloaded route options
• resets global React, Solid, and Vue catch boundaries when a newly committed background child generation recovers from a render error
• fixes the preload redirect boundary so a twenty-hop chain completes and only the following hop is rejected
• removes duplicate or unused HMR refresh and Start disposal paths and shares hydration's existing navigation closure

Bundle size

Final production output compared with main:

• React Router: 27–59 gzip bytes smaller and 3.9–4.1 KB smaller raw
• Solid Router: 454–583 gzip bytes smaller and 5.4–5.7 KB smaller raw
• Vue Router: 663–669 gzip bytes smaller and 6.0–6.3 KB smaller raw
• every measured Router/Start output is 3.9–6.6 KB smaller raw

Three React Start scenarios fluctuate by +14, +19, and +84 gzip bytes despite being 4.2–4.5 KB smaller raw.

The additional review fixes were simplified against their first correct implementation, reducing the 17-scenario matrix by another 629 raw bytes, 200 gzip bytes, and 362 brotli bytes. Sixteen gzip scenarios are neutral or smaller; vue-router.minimal is the sole exception at +3 gzip bytes while still being 24 raw bytes and 68 brotli bytes smaller.

Validation

• Router Core unit and type suites
• React Router unit and type suites
• Solid Router unit and type suites
• affected lint and type graphs
• selective-SSR E2E suite, including server/client loader and beforeLoad behavior
• production bundle-size matrix
• Prettier and git diff --check
• Start Server Core and Router Plugin unit suites
• focused hydration-currentness, SSR cleanup, HMR lazy-owner, and React/Solid/Vue boundary-recovery regressions
• uncached 17-scenario production bundle-size matrix

Two Vue redirect cases remain best-effort and are intentionally not blocking this review. One search-validator adapter suite also fails locally because its generated test setup resolves an absolute dependency path from another worktree rather than because of router behavior.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6d2410f5-591f-479c-9211-dbece16d3a5d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/match-loading-final

---

_{Comment @coderabbitai help to get the list of available commands.}

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 8ad0dc5

Command	Status	Duration	Result
nx affected --targets=test:eslint,test:unit,tes...	✅ Succeeded	7m 9s	View ↗
nx run-many --target=build --exclude=examples/*...	✅ Succeeded	23s	View ↗

---

☁️ Nx Cloud last updated this comment at 2026-07-20 13:26:47 UTC

[github-actions]

🚀 Changeset Version Preview

No changeset entries found. Merging this PR will not cause a version bump for any packages.

[github-actions]

Bundle Size Benchmarks

• Commit: 03f713dcce67
• Measured at: 2026-07-20T13:20:49.943Z
• Baseline source: history:edf55759d8e9
• Dashboard: bundle-size history

Scenario	Current (gzip)	Delta vs baseline	Initial gzip	Raw	Brotli	Trend
react-router.minimal	87.33 KiB	-22 B (-0.02%)	87.19 KiB	269.82 KiB	76.06 KiB	███████████▁
react-router.full	91.01 KiB	-57 B (-0.06%)	90.87 KiB	281.55 KiB	79.33 KiB	███████████▁
solid-router.minimal	35.08 KiB	-452 B (-1.24%)	34.96 KiB	100.64 KiB	31.65 KiB	███████████▁
solid-router.full	40.02 KiB	-580 B (-1.40%)	39.89 KiB	115.51 KiB	36.02 KiB	███████████▁
vue-router.minimal	52.36 KiB	-658 B (-1.21%)	52.23 KiB	144.04 KiB	47.17 KiB	███████████▁
vue-router.full	58.29 KiB	-662 B (-1.10%)	58.16 KiB	162.57 KiB	52.34 KiB	███████████▁
react-start.minimal	102.32 KiB	+338 B (+0.32%)	102.18 KiB	318.40 KiB	88.61 KiB	▁▁▁▁▁▁▁▁▁▁▁█
react-start.deferred-hydration	103.05 KiB	+339 B (+0.32%)	102.20 KiB	319.78 KiB	89.25 KiB	▁▁▁▁▁▁▁▁▁▁▁█
react-start.full	105.63 KiB	+276 B (+0.26%)	105.50 KiB	328.33 KiB	91.50 KiB	▁▁▁▁▁▁▁▁▁▁▁█
react-start.rsbuild.minimal	99.91 KiB	+232 B (+0.23%)	99.74 KiB	312.89 KiB	86.15 KiB	▁▁▁▁▁▁▁▁▁▁▁█
react-start.rsbuild.minimal-iife	100.30 KiB	+227 B (+0.22%)	100.14 KiB	313.83 KiB	86.43 KiB	▁▁▁▁▁▁▁▁▁▁▁█
react-start.rsbuild.full	103.23 KiB	+343 B (+0.33%)	103.06 KiB	322.97 KiB	88.90 KiB	▁▁▁▁▁▁▁▁▁▁▁█
solid-start.minimal	49.88 KiB	+274 B (+0.54%)	49.75 KiB	148.13 KiB	44.20 KiB	▁▁▁▁▁▁▁▁▁▁▁█
solid-start.deferred-hydration	53.14 KiB	+279 B (+0.52%)	49.81 KiB	156.17 KiB	47.21 KiB	▁▁▁▁▁▁▁▁▁▁▁█
solid-start.full	55.12 KiB	-311 B (-0.55%)	54.99 KiB	163.75 KiB	48.66 KiB	███████████▁
vue-start.minimal	70.68 KiB	-358 B (-0.49%)	70.55 KiB	201.40 KiB	62.73 KiB	███████████▁
vue-start.full	74.67 KiB	-366 B (-0.48%)	74.54 KiB	213.98 KiB	66.22 KiB	███████████▁

Current gzip tracks all emitted client JS chunks. Initial gzip tracks only the entry/import graph. Trend sparkline is historical current gzip ending with this PR measurement; lower is better.

[pkg-pr-new]

More templates

• tanstack-router-react-example-authenticated-routes
• tanstack-router-react-example-authenticated-routes-firebase
• tanstack-router-react-example-basic
• tanstack-router-react-example-basic-default-search-params
• tanstack-router-react-example-basic-devtools-panel
• tanstack-router-react-example-basic-file-based
• tanstack-router-react-example-basic-non-nested-devtools
• tanstack-router-react-example-react-query
• tanstack-router-react-example-basic-react-query-file-based
• tanstack-router-react-example-basic-ssr-file-based
• tanstack-router-react-example-basic-ssr-streaming-file-based
• tanstack-router-react-example-basic-virtual-file-based
• tanstack-router-react-example-basic-virtual-inside-file-based
• tanstack-router-react-example-deferred-data
• tanstack-router-i18n-paraglide
• tanstack-router-react-example-kitchen-sink
• tanstack-router-react-example-kitchen-sink-file-based
• tanstack-router-react-example-kitchen-sink-react-query
• tanstack-router-react-example-kitchen-sink-react-query-file-based
• tanstack-router-react-example-large-file-based
• tanstack-router-react-example-location-masking
• tanstack-router-react-example-navigation-blocking
• tanstack-router-react-example-quickstart
• tanstack-router-react-example-quickstart-esbuild-file-based
• tanstack-router-react-example-quickstart-file-based
• tanstack-router-react-example-quickstart-rspack-file-based
• tanstack-router-react-example-quickstart-webpack-file-based
• router-monorepo-react-query
• router-mono-simple
• router-mono-simple-lazy
• tanstack-router-react-example-scroll-restoration
• tanstack-search-validator-adapters
• tanstack-start-example-bare
• tanstack-start-example-basic
• tanstack-start-example-basic-auth
• tanstack-router-react-example-basic-authjs
• tanstack-start-example-basic-cloudflare
• tanstack-start-example-basic-react-query
• tanstack-start-example-basic-static
• tanstack-start-bun-hosting
• tanstack-start-example-clerk-basic
• tanstack-start-example-convex-trellaux
• tanstack-start-example-counter
• tanstack-start-i18n-paraglide
• tanstack-start-example-large
• tanstack-start-example-material-ui
• tanstack-start-example-rscs
• tanstack-start-streaming-data-from-server-functions
• tanstack-start-example-supabase-basic
• tanstack-start-tailwind-v4
• tanstack-start-example-trellaux
• tanstack-start-example-workos
• tanstack-router-react-example-view-transitions
• tanstack-router-react-example-with-framer-motion
• tanstack-router-react-example-with-trpc
• tanstack-router-react-example-with-trpc-react-query
• tanstack-router-solid-example-authenticated-routes
• tanstack-router-solid-example-authenticated-routes-firebase
• tanstack-router-solid-example-basic
• tanstack-router-solid-example-basic-default-search-params
• tanstack-router-solid-example-basic-devtools-panel
• tanstack-router-solid-example-basic-file-based
• tanstack-router-solid-example-basic-non-nested-devtools
• tanstack-router-solid-example-basic-solid-query
• tanstack-router-solid-example-basic-solid-query-file-based
• tanstack-router-solid-example-basic-ssr-file-based
• tanstack-router-solid-example-basic-ssr-streaming-file-based
• tanstack-router-solid-example-basic-virtual-file-based
• tanstack-router-solid-example-basic-virtual-inside-file-based
• tanstack-router-solid-example-deferred-data
• tanstack-router-solid-i18n-paraglide
• tanstack-router-solid-example-kitchen-sink
• tanstack-router-solid-example-kitchen-sink-file-based
• tanstack-router-solid-example-kitchen-sink-solid-query
• tanstack-router-solid-example-kitchen-sink-solid-query-file-based
• tanstack-router-solid-example-large-file-based
• tanstack-router-solid-example-location-masking
• tanstack-router-solid-example-navigation-blocking
• tanstack-router-solid-example-quickstart
• tanstack-router-solid-example-quickstart-esbuild-file-based
• tanstack-router-solid-example-quickstart-file-based
• tanstack-router-solid-example-quickstart-rspack-file-based
• tanstack-router-solid-example-quickstart-webpack-file-based
• @tanstack/router-solid-mono-simple
• router-solid-mono-simple-lazy
• router-solid-monorepo-solid-query
• tanstack-router-solid-example-scroll-restoration
• tanstack-solid-router-search-validator-adapters
• tanstack-solid-start-example-basic
• tanstack-solid-start-example-basic-auth
• tanstack-solid-start-example-basic-authjs
• tanstack-solid-start-example-basic-cloudflare
• tanstack-solid-start-example-basic-netlify
• tanstack-solid-start-example-basic-nitro
• tanstack-start-example-basic-solid-query
• tanstack-solid-start-example-basic-static
• tanstack-solid-start-bun-hosting
• tanstack-solid-start-example-convex-better-auth
• tanstack-solid-start-example-counter
• tanstack-solid-start-i18n-paraglide
• tanstack-solid-start-example-large
• tanstack-solid-start-streaming-data-from-server-functions
• tanstack-solid-start-example-supabase-basic
• tanstack-solid-start-tailwind-v4
• tanstack-router-solid-example-view-transitions
• tanstack-router-solid-example-with-framer-motion
• tanstack-router-solid-example-with-trpc
• tanstack-router-vue-example-basic-jsx
• tanstack-router-vue-example-basic-file-based-jsx
• tanstack-router-vue-example-basic-file-based-sfc

@tanstack/arktype-adapter

npm i https://pkg.pr.new/@tanstack/arktype-adapter@7858

@tanstack/eslint-plugin-router

npm i https://pkg.pr.new/@tanstack/eslint-plugin-router@7858

@tanstack/eslint-plugin-start

npm i https://pkg.pr.new/@tanstack/eslint-plugin-start@7858

@tanstack/history

npm i https://pkg.pr.new/@tanstack/history@7858

@tanstack/nitro-v2-vite-plugin

npm i https://pkg.pr.new/@tanstack/nitro-v2-vite-plugin@7858

@tanstack/react-router

npm i https://pkg.pr.new/@tanstack/react-router@7858

@tanstack/react-router-devtools

npm i https://pkg.pr.new/@tanstack/react-router-devtools@7858

@tanstack/react-router-ssr-query

npm i https://pkg.pr.new/@tanstack/react-router-ssr-query@7858

@tanstack/react-start

npm i https://pkg.pr.new/@tanstack/react-start@7858

@tanstack/react-start-client

npm i https://pkg.pr.new/@tanstack/react-start-client@7858

@tanstack/react-start-rsc

npm i https://pkg.pr.new/@tanstack/react-start-rsc@7858

@tanstack/react-start-server

npm i https://pkg.pr.new/@tanstack/react-start-server@7858

@tanstack/router-cli

npm i https://pkg.pr.new/@tanstack/router-cli@7858

@tanstack/router-core

npm i https://pkg.pr.new/@tanstack/router-core@7858

@tanstack/router-devtools

npm i https://pkg.pr.new/@tanstack/router-devtools@7858

@tanstack/router-devtools-core

npm i https://pkg.pr.new/@tanstack/router-devtools-core@7858

@tanstack/router-generator

npm i https://pkg.pr.new/@tanstack/router-generator@7858

@tanstack/router-plugin

npm i https://pkg.pr.new/@tanstack/router-plugin@7858

@tanstack/router-ssr-query-core

npm i https://pkg.pr.new/@tanstack/router-ssr-query-core@7858

@tanstack/router-utils

npm i https://pkg.pr.new/@tanstack/router-utils@7858

@tanstack/router-vite-plugin

npm i https://pkg.pr.new/@tanstack/router-vite-plugin@7858

@tanstack/solid-router

npm i https://pkg.pr.new/@tanstack/solid-router@7858

@tanstack/solid-router-devtools

npm i https://pkg.pr.new/@tanstack/solid-router-devtools@7858

@tanstack/solid-router-ssr-query

npm i https://pkg.pr.new/@tanstack/solid-router-ssr-query@7858

@tanstack/solid-start

npm i https://pkg.pr.new/@tanstack/solid-start@7858

@tanstack/solid-start-client

npm i https://pkg.pr.new/@tanstack/solid-start-client@7858

@tanstack/solid-start-server

npm i https://pkg.pr.new/@tanstack/solid-start-server@7858

@tanstack/start-client-core

npm i https://pkg.pr.new/@tanstack/start-client-core@7858

@tanstack/start-fn-stubs

npm i https://pkg.pr.new/@tanstack/start-fn-stubs@7858

@tanstack/start-plugin-core

npm i https://pkg.pr.new/@tanstack/start-plugin-core@7858

@tanstack/start-server-core

npm i https://pkg.pr.new/@tanstack/start-server-core@7858

@tanstack/start-static-server-functions

npm i https://pkg.pr.new/@tanstack/start-static-server-functions@7858

@tanstack/start-storage-context

npm i https://pkg.pr.new/@tanstack/start-storage-context@7858

@tanstack/valibot-adapter

npm i https://pkg.pr.new/@tanstack/valibot-adapter@7858

@tanstack/virtual-file-routes

npm i https://pkg.pr.new/@tanstack/virtual-file-routes@7858

@tanstack/vue-router

npm i https://pkg.pr.new/@tanstack/vue-router@7858

@tanstack/vue-router-devtools

npm i https://pkg.pr.new/@tanstack/vue-router-devtools@7858

@tanstack/vue-router-ssr-query

npm i https://pkg.pr.new/@tanstack/vue-router-ssr-query@7858

@tanstack/vue-start

npm i https://pkg.pr.new/@tanstack/vue-start@7858

@tanstack/vue-start-client

npm i https://pkg.pr.new/@tanstack/vue-start-client@7858

@tanstack/vue-start-server

npm i https://pkg.pr.new/@tanstack/vue-start-server@7858

@tanstack/zod-adapter

npm i https://pkg.pr.new/@tanstack/zod-adapter@7858

commit: 8ad0dc5

[codspeed-hq]

Merging this PR will regress 93 benchmarks

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

⚡ 32 improved benchmarks
❌ 93 regressed benchmarks
✅ 55 untouched benchmarks

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Mode	Benchmark	BASE	HEAD	Efficiency
❌	Memory	mem server request-churn (vue)	454.1 KB	779.8 KB	-41.77%
❌	Memory	mem server aborted-requests (vue)	480.8 KB	720.6 KB	-33.28%
❌	Memory	mem server aborted-requests (react)	521.8 KB	746.5 KB	-30.09%
❌	Simulation	ssr server-route middleware (solid)	54.1 ms	73.2 ms	-26.03%
❌	Simulation	ssr server-route middleware (react)	55.2 ms	73.9 ms	-25.28%
❌	Simulation	ssr global-mw server-route (vue)	65.2 ms	86.9 ms	-25.04%
❌	Simulation	ssr server-route middleware (vue)	56.5 ms	73.8 ms	-23.43%
❌	Simulation	ssr global-mw server-route (solid)	61.7 ms	80.5 ms	-23.39%
❌	Simulation	ssr server-route (react)	55.6 ms	68.3 ms	-18.56%
❌	Simulation	ssr server-fn not-found (solid)	60.9 ms	74.3 ms	-17.96%
❌	Simulation	ssr server-route (solid)	53.3 ms	64.8 ms	-17.78%
❌	Simulation	ssr redirect (solid)	39.3 ms	47.5 ms	-17.36%
❌	Simulation	ssr before-load chain (react)	48 ms	57.4 ms	-16.39%
❌	Simulation	ssr server-fn POST (solid)	62.8 ms	74.7 ms	-16.04%
❌	Simulation	ssr not-found (react)	45 ms	53.6 ms	-16.03%
❌	Simulation	ssr server-route (vue)	57.1 ms	67.9 ms	-15.85%
❌	Simulation	ssr server-fn raw-response (vue)	56.9 ms	67 ms	-15.03%
❌	Simulation	ssr server-fn not-found (vue)	74 ms	86.4 ms	-14.38%
❌	Simulation	ssr redirect (vue)	46.3 ms	54 ms	-14.23%
❌	Memory	mem server error-paths redirect (vue)	436.7 KB	507.9 KB	-14.02%
...	...	...	...	...	...

ℹ️ Only the first 20 benchmarks are displayed. Go to the app to view all benchmarks.

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing codex/match-loading-final (8ad0dc5) with fix-router-core-lane-match-loader (3d68db6)}