Load-then-render SPA navigation with subtle top progress bar

docs/contributing/architecture/request-lifecycle.md

@@ -95,6 +95,30 @@ submissions (`GET`/`POST`) and routes them in-place through the client router.
 Normal app navigations stay in-place through the client router instead of
 requiring a full document refresh.
 
+### Preload-then-commit
+
+SPA navigations use a **preload-then-commit** model (similar to React Router
+data routers): before `history.pushState` and the route swap, the client router
+runs a registered **route loader** for the destination URL, fetches JSON API
+data, and stores it in a single-slot preloaded navigation store. Only after the
+loader finishes (or is skipped when no loader matches) does the router commit
+the URL change and notify subscribers. Route components consume that payload
+synchronously on first render via `tryConsumeRouteLoaderData`, so the UI updates
+once with data already present instead of swapping routes into a loading state.
+
+Route loaders are registered in `clientRouteLoaders` (`routes/index.tsx`) and
+matched with the same Remix route-pattern specificity as `clientRoutes`. Loaders
+return `null` to abort the SPA navigation (for example, `401` → full-page login
+redirect). Loader errors still commit the navigation so the destination route
+can fall back to its own fetch. Hash-only changes commit immediately without a
+loader. Back/forward (`popstate`) and same-path refreshes after form POST also
+run loaders before notifying, keeping the previous UI visible until data is
+ready.
+
+A thin top-of-viewport **navigation progress bar** listens for `navigationstart`
+/ `navigationend` on `routerEvents` and appears only when a navigation is still
+pending after a short delay.
+
 Full page navigations occur for:
 
 - Explicit browser reloads/new tab loads

packages/worker/client/app.tsx

@@ -1,7 +1,12 @@
 import { type Handle, css } from 'remix/ui'
-import { clientRoutes } from './routes/index.tsx'
-import { listenToRouterNavigation, Router } from './client-router.tsx'
+import { clientRouteLoaders, clientRoutes } from './routes/index.tsx'
+import {
+	listenToRouterNavigation,
+	registerRouteLoaders,
+	Router,
+} from './client-router.tsx'
 import { AppLoaderDataProvider } from './loader-data-context.tsx'
+import { NavigationProgress } from './navigation-progress.tsx'
 import { readRouterPathname, readRouterSearch } from './router-location.tsx'
 import {
 	fetchSessionInfo,
@@ -15,6 +20,8 @@ import { userHasRole } from '#app/permissions.ts'
 import { buildAuthLink } from './auth-links.ts'
 import { colors, mq, spacing, typography } from './styles/tokens.ts'
 
+registerRouteLoaders(clientRouteLoaders)
+
 type AppProps = {
 	embeddedSession?: SessionInfo | null
 	loaderData?: AppLoaderData
@@ -144,6 +151,7 @@ export function App(handle: Handle<AppProps>) {
 
 		return (
 			<AppLoaderDataProvider loaderData={handle.props.loaderData}>
+				<NavigationProgress />
 				<main
 					mix={css({
 						maxWidth: isWideLayout ? 'none' : '52rem',

packages/worker/client/client-router.node.test.ts

@@ -1,5 +1,9 @@
 import { expect, test } from 'vitest'
-import { matchRoute } from './client-router.tsx'
+import {
+	matchRoute,
+	matchRouteLoader,
+	type RouteLoader,
+} from './client-router.tsx'
 
 test('client route matching uses Remix route-pattern specificity', () => {
 	const tokenDetailRoute = 'token-detail-route' as unknown as JSX.Element
@@ -32,3 +36,45 @@ test('client route matching handles nested static routes over dynamic parents',
 		genericSecretRoute,
 	)
 })
+
+test('route loader matching uses the same route-pattern specificity', () => {
+	const accountLoader = (async () => ({
+		accountProfile: { ok: true },
+	})) as RouteLoader
+	const tokenLoader = (async () => ({
+		accountPackageInvocationTokens: { ok: true },
+	})) as RouteLoader
+	const loaders = {
+		'/account/package-invocation-tokens/:tokenId': tokenLoader,
+		'/account/package-invocation-tokens/new': tokenLoader,
+		'/account': accountLoader,
+	}
+
+	expect(matchRouteLoader('/account', loaders)).toBe(accountLoader)
+	expect(
+		matchRouteLoader('/account/package-invocation-tokens/new', loaders),
+	).toBe(tokenLoader)
+	expect(
+		matchRouteLoader('/account/package-invocation-tokens/token-1', loaders),
+	).toBe(tokenLoader)
+})
+
+test('route loader matching prefers nested static routes over dynamic parents', () => {
+	const genericSecretLoader = (async () => ({
+		accountSecrets: { ok: true },
+	})) as RouteLoader
+	const userSecretLoader = (async () => ({
+		accountSecrets: { ok: true },
+	})) as RouteLoader
+	const loaders = {
+		'/account/secrets/:secretId': genericSecretLoader,
+		'/account/secrets/user/:secretName': userSecretLoader,
+	}
+
+	expect(matchRouteLoader('/account/secrets/user/github-token', loaders)).toBe(
+		userSecretLoader,
+	)
+	expect(matchRouteLoader('/account/secrets/secret-1', loaders)).toBe(
+		genericSecretLoader,
+	)
+})