houdini-react 2.0.2 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "houdini-react",
-  "version": "2.0.2",
+  "version": "2.1.0",
   "description": "The React plugin for houdini",
   "keywords": [
     "typescript",
@@ -81,13 +81,13 @@
     }
   },
   "optionalDependencies": {
-    "houdini-react-darwin-x64": "2.0.2",
-    "houdini-react-darwin-arm64": "2.0.2",
-    "houdini-react-linux-x64": "2.0.2",
-    "houdini-react-linux-arm64": "2.0.2",
-    "houdini-react-win32-x64": "2.0.2",
-    "houdini-react-win32-arm64": "2.0.2",
-    "houdini-react-wasm": "2.0.2"
+    "houdini-react-darwin-x64": "2.1.0",
+    "houdini-react-darwin-arm64": "2.1.0",
+    "houdini-react-linux-x64": "2.1.0",
+    "houdini-react-linux-arm64": "2.1.0",
+    "houdini-react-win32-x64": "2.1.0",
+    "houdini-react-win32-arm64": "2.1.0",
+    "houdini-react-wasm": "2.1.0"
   },
   "scripts": {
     "compile": "scripts build-go",

package/postInstall.js

@@ -5,7 +5,7 @@ const https = require('https')
 const child_process = require('child_process')
 
 // Adjust the version you want to install. You can also make this dynamic.
-const BINARY_DISTRIBUTION_VERSION = '2.0.2'
+const BINARY_DISTRIBUTION_VERSION = '2.1.0'
 
 // Windows binaries end with .exe so we need to special case them.
 const binaryName = process.platform === 'win32' ? 'houdini-react.exe' : 'houdini-react'

package/runtime/contexts.ts

@@ -1,3 +1,4 @@
+import type { GraphQLError } from 'houdini/runtime'
 import { createContext } from 'react'
 
 import type { Goto } from './routes.js'
@@ -42,11 +43,37 @@ export const LocationContext = createContext<{
 
 export const Is404Context = createContext(false)
 
+// PendingURLContext (internal) carries the raw navigation target. Unlike
+// NavigationContext.to it is NOT nulled when the router considers itself idle, so it
+// reads the same in every render lane — the transition lane renders with isPending
+// false, which would hide the target from it. useQueryResult uses this to tell whether
+// the render it is part of is the destination of an in-flight navigation (suspend on a
+// missing store) or the still-visible previous page (keep rendering the store it has).
+export const PendingURLContext = createContext<string | null>(null)
+
+// NavigationContext carries the router's in-flight navigation, if any: `pending` is true
+// from the moment a navigation starts until the destination renders its actual content
+// (it stays true while the @loading state shows), and `to` is the destination url while
+// pending. Read through useNavigation().
+export const NavigationContext = createContext<{
+	pending: boolean
+	to: string | null
+	goto: Goto
+}>({
+	pending: false,
+	to: null,
+	goto: () => {},
+})
+
 export const PageContext = createContext<{ params: Record<string, any> }>({ params: {} })
 
-// Mutable ref passed from the server renderer so that a synchronous RoutingError
-// or redirect() can propagate the correct HTTP status/location before streaming.
-export const StatusContext = createContext<{ status: number; location?: string } | null>(null)
+// Mutable ref passed from the server renderer. It carries the HTTP status/location for
+// the response and, when the first SSR render pass threw (error boundaries don't run
+// during SSR), the errors the boundary should render on the second pass.
+export const StatusContext = createContext<{
+	status: number
+	errors?: Array<Error | GraphQLError>
+} | null>(null)
 
 // FormStatusContext carries the nearest <Form>'s pending state to useMutationFormStatus(),
 // the no-prop-drilling ergonomic of React's useFormStatus (which only tracks function-action

package/runtime/hooks/useDocumentHandle.ts

@@ -103,6 +103,15 @@ export function useDocumentHandle<
 					...args?.variables,
 				},
 				session,
+				// handle-driven sends (pagination, manual refetch) must not republish the
+				// document's @loading state — the skeleton is for router-driven loads. The
+				// page keeps its current data while the request is in flight; callers track
+				// progress through loadNextPending/loadPreviousPending instead. (matches
+				// useQueryHandle/useFragmentHandle and the svelte pagination stores)
+				stuff: {
+					silenceLoading: true,
+					...(args as { stuff?: App.Stuff } | undefined)?.stuff,
+				},
 			})
 		}
 
@@ -141,6 +150,7 @@ export function useDocumentHandle<
 							applyUpdates: updates,
 						},
 						session,
+						stuff: { silenceLoading: true, ...args?.stuff },
 					})
 				},
 				getSession: async () => session,
@@ -172,6 +182,7 @@ export function useDocumentHandle<
 							applyUpdates: updates,
 							...args?.cacheParams,
 						},
+						stuff: { silenceLoading: true, ...args?.stuff },
 					})
 				},
 				getSession: async () => session,

package/runtime/index.tsx

@@ -16,6 +16,7 @@ export {
 	useCache,
 	useSession,
 	useRoute,
+	useNavigation,
 	notFound,
 	unauthorized,
 	forbidden,

package/runtime/routing/Router.tsx

@@ -17,7 +17,9 @@ import {
 	RouterContextObject as Context,
 	LocationContext,
 	Is404Context,
+	NavigationContext,
 	PageContext,
+	PendingURLContext,
 } from '../contexts.js'
 import { escapeScriptTag } from '../escape.js'
 import { buildHref, scalarUnmarshalers, unmarshalScalars } from '../resolve-href.js'
@@ -27,7 +29,11 @@ import { useDocumentStore } from '../hooks/useDocumentStore.js'
 import { type SuspenseCache, suspense_cache } from './cache.js'
 import { GraphQLErrors, RoutingError, StatusContext } from './errors.js'
 
-type PageComponent = React.ComponentType<{ url: string; children?: React.ReactNode }>
+type PageComponent = React.ComponentType<{
+	url: string
+	showLoading?: boolean
+	children?: React.ReactNode
+}>
 
 const PreloadWhich = {
 	component: 'component',
@@ -37,6 +43,86 @@ const PreloadWhich = {
 
 type PreloadWhichValue = (typeof PreloadWhich)[keyof typeof PreloadWhich]
 type ComponentType = any
+
+// useLoadingState decides whether to show the route's @loading state during navigation.
+// `active` is the navigation transition's pending flag. The state flips on only once
+// `active` has been pending for at least `loadingDelay` ms (so fast navigations never
+// show it). Once shown it stays on until BOTH of these are true, so a response landing
+// just after the delay doesn't cause a skeleton flicker:
+//   - it has been visible for at least `minDuration` ms
+//   - the target page's data has landed (`waitForData` resolves)
+// A navigation that starts while the state is already showing re-arms the minDuration
+// clock, so the new destination's data can't flash in right as the original hold expires
+// — `target` (the destination url) is a dependency for exactly that reason: a second
+// navigation can start without `active` ever flipping (the first transition is still
+// pending), and the target change is what re-runs the effect.
+// Note that `active` flips false as soon as the loading frame commits (the frame doesn't
+// suspend, so the transition finishes with it on screen) — which is why the hide side
+// waits on the data explicitly instead of trusting `active`.
+function useLoadingState({
+	active,
+	target,
+	loadingDelay,
+	minDuration,
+	waitForData,
+}: {
+	active: boolean
+	target: string | null
+	loadingDelay: number
+	minDuration: number
+	waitForData: () => Promise<void>
+}): boolean {
+	const [show, setShow] = React.useState(false)
+	const shownAt = React.useRef<number | null>(null)
+
+	React.useEffect(() => {
+		if (active) {
+			// already showing — a new navigation is starting while the loading state is
+			// up. Keep it up, but re-arm the minimum-duration clock: measured from the
+			// first show, the hold could expire right as this navigation's data lands,
+			// flashing the freshly-loaded content in and out of the loading state.
+			if (show) {
+				shownAt.current = performance.now()
+				return
+			}
+			// wait out the delay; if we're still pending, switch the loading state on
+			const timeout = setTimeout(() => {
+				shownAt.current = performance.now()
+				setShow(true)
+			}, loadingDelay)
+			return () => clearTimeout(timeout)
+		}
+
+		// navigation finished. if we never showed the loading state, there's nothing to do
+		if (!show) {
+			return
+		}
+		// otherwise wait for the page's data, then keep the loading state up until it has
+		// been visible for at least minDuration. waiting on the data here means the page
+		// never mounts with its query still missing (which would re-suspend it into the
+		// Suspense fallback and briefly double-render the frame).
+		let cancelled = false
+		let timeout: ReturnType<typeof setTimeout> | undefined
+		waitForData().then(() => {
+			if (cancelled) {
+				return
+			}
+			const elapsed = performance.now() - (shownAt.current ?? performance.now())
+			const remaining = Math.max(0, minDuration - elapsed)
+			timeout = setTimeout(() => {
+				shownAt.current = null
+				setShow(false)
+			}, remaining)
+		})
+		return () => {
+			cancelled = true
+			clearTimeout(timeout)
+		}
+	}, [active, show, target, loadingDelay, minDuration])
+
+	return show
+}
+
 /**
  * Router is the top level entry point for the filesystem-based router.
  * It is responsible for loading various page sources (including API fetches) and
@@ -64,6 +150,20 @@ export function Router({
 		return initialURL || window.location.pathname + window.location.search
 	})
 
+	// Navigation runs inside a transition so React keeps the previously-rendered route
+	// on screen while the next one loads (instead of immediately falling back to the
+	// loading state). If the transition stays pending longer than `loadingDelay`, we
+	// surface the route's @loading frame (see showLoading → the entry's page slot);
+	// fast navigations never show it, and once shown it stays up for `minDuration`.
+	const [isNavigating, startNavigation] = React.useTransition()
+
+	// pendingURL tracks the navigation target *urgently* (outside the transition), so a
+	// render that happens while the transition is still pending can tell whether it is
+	// looking at the destination (transition lane: currentURL === pendingURL) or at the
+	// still-committed previous route (urgent lane: currentURL lags behind). The loading
+	// frame is only ever shown on the destination — see the showLoading prop below.
+	const [pendingURL, setPendingURL] = React.useState<string | null>(null)
+
 	// find the matching page for the current route. find_match also hands back the parsed
 	// query string (declared search params coerced, UI-only keys raw). custom-scalar route
 	// and search params arrive in their url transport form, so we unmarshal them once here
@@ -97,8 +197,35 @@ export function Router({
 		injectToStream,
 	})
 	// if we get this far, it's safe to load the component
-	const { component_cache, data_cache, ssr_signals } = useRouterContext()
+	const { component_cache, data_cache, artifact_cache, ssr_signals } = useRouterContext()
 	const PageComponent = component_cache.get(targetPage.id)!
+	const [session] = useSession()
+
+	// decide whether the entry should render its @loading frame instead of the page.
+	// values come from the router config (bundled client-side; they're UI timing, not
+	// secrets), clamped so a bad value can't schedule a negative timeout.
+	// The machine only arms when the *destination* can actually render a frame (one of
+	// its documents is @loading): a frameless destination just holds the previous page
+	// for the whole transition, and arming the invisible state anyway would keep
+	// useNavigation().pending true for up to minDuration after the content committed.
+	const routerConfig = getCurrentConfig()?.router ?? {}
+	const [pendingPage] = pendingURL !== null ? find_match(manifest, pendingURL) : [null]
+	const destinationHasFrame = pendingPage
+		? Object.values(pendingPage.documents).some((document) => document.loading)
+		: false
+	const showLoading = useLoadingState({
+		active: isNavigating && destinationHasFrame,
+		target: pendingURL,
+		loadingDelay: Math.max(0, routerConfig.loadingDelay ?? 200),
+		minDuration: Math.max(0, routerConfig.minDuration ?? 400),
+		// resolves once every query of the page being rendered has a store in data_cache
+		// (including error stores — load_query seeds those too, so an errored query
+		// releases the loading state instead of pinning it)
+		waitForData: () =>
+			Promise.all(
+				Object.keys(targetPage.documents).map((name) => data_cache.waitFor(name))
+			).then(() => {}),
+	})
 
 	// if we got this far then we're past suspense
 
@@ -113,13 +240,96 @@ export function Router({
 		}
 	}, [currentURL])
 
+	// (dev only) hot-swap regenerated query artifacts. The router loads artifacts through
+	// dynamic import and keeps them — and the DocumentStores built from them — in caches
+	// keyed by document name, so vite's module-level HMR can never reach them: after
+	// codegen rewrites an artifact, the caches keep serving the old document and the page
+	// renders stale data. The compiler emits a custom event listing the changed artifact
+	// modules (see flushClientUpdates in houdini's vite plugin); re-import each one fresh,
+	// swap it into the artifact cache, evict the stale store, and reload the current
+	// page's data. useQueryResult keeps the committed store on screen while the
+	// replacement loads (the same keep-last-store path as an abandoned navigation), so
+	// the swap doesn't flash a loading state.
+	const [, forceRender] = React.useReducer((n: number) => n + 1, 0)
+	// the listener is registered once but must act on the latest render's page/variables
+	// (and loadData's closure over the current session)
+	const hmr = React.useRef({ page: targetPage, variables, loadData })
+	hmr.current = { page: targetPage, variables, loadData }
+	React.useEffect(() => {
+		// dev only: vite statically replaces both tokens in production builds
+		// (env.DEV → false, hot → undefined), so the whole listener is dead-code
+		// eliminated. The casts erase to the literal `import.meta.env.DEV` /
+		// `import.meta.hot` tokens — don't alias import.meta or add optional
+		// chaining, or the replacement (and vite's hot-context injection) stops
+		// matching.
+		if (!(import.meta as unknown as { env: { DEV?: boolean } }).env.DEV) {
+			return
+		}
+		const hot = (import.meta as { hot?: any }).hot
+		if (!hot) {
+			return
+		}
+		const onArtifactUpdate = async ({
+			artifacts,
+		}: {
+			artifacts: Array<{ name: string; url: string }>
+		}) => {
+			let stale = false
+			for (const { name, url } of artifacts) {
+				// only documents this client has loaded can be stale
+				if (!artifact_cache.has(name)) {
+					continue
+				}
+				// bust the browser's module cache — re-importing the bare url would just
+				// return the module we already have
+				let artifact: QueryArtifact | undefined
+				try {
+					const bust = `${url.includes('?') ? '&' : '?'}t=${Date.now()}`
+					artifact = (await import(/* @vite-ignore */ `${url}${bust}`))?.default
+				} catch {
+					// the module failed to load (e.g. the document was deleted) — leave the
+					// caches alone rather than evicting a store we can't replace
+					continue
+				}
+				if (!artifact) {
+					continue
+				}
+				artifact_cache.set(name, artifact)
+				// evict the store built from the old artifact so the reload below creates a
+				// replacement. deliberately no cleanup(): mounted components keep rendering
+				// the old store until the new one lands (see SuspenseCache's delete() note)
+				data_cache.delete(name)
+				ssr_signals.delete(name)
+				stale = true
+			}
+			if (!stale) {
+				return
+			}
+			const { page, variables, loadData } = hmr.current
+			// the reload honors each query's cache policy: an edit that doesn't change
+			// what the document asks for (or asks for data the cache already holds)
+			// resolves instantly from cache; anything the old selection didn't cover
+			// misses and goes to the network
+			loadData(page, variables)
+			// re-render so useQueryResult sees the eviction and subscribes to the
+			// replacement — deleting a cache entry doesn't notify anyone on its own
+			forceRender()
+		}
+		hot.on('houdini:artifact-update', onArtifactUpdate)
+		return () => hot.off?.('houdini:artifact-update', onArtifactUpdate)
+	}, [])
+
 	// when we first mount we should start listening to the back button
 	React.useEffect(() => {
 		if (!globalThis.window) {
 			return
 		}
 		const onChange = (_evt: PopStateEvent) => {
-			setCurrentURL(window.location.pathname + window.location.search)
+			const url = window.location.pathname + window.location.search
+			setPendingURL(url)
+			startNavigation(() => {
+				setCurrentURL(url)
+			})
 		}
 		window.addEventListener('popstate', onChange)
 		return () => {
@@ -127,34 +337,72 @@ export function Router({
 		}
 	}, [])
 
+	// On navigation (but not the initial mount), re-fire the route's already-cached
+	// queries so each one's cache policy is honored (stale-while-revalidate). The
+	// observers are kept, so a query whose variables are unchanged and whose policy
+	// allows a cache read resolves without a loading frame; queries whose variables
+	// changed (or aren't cached) are evicted + reloaded by loadData with their loading
+	// state. We reuse the variables already unmarshaled for this render rather than
+	// re-parsing the URL. This also covers back/forward (popstate), which bypasses goto.
+	// The guard compares URLs (not a boolean) so Strict Mode's double effect invocation
+	// on mount doesn't slip past it and revalidate the initial page.
+	const lastRevalidatedURL = React.useRef(currentURL)
+	React.useEffect(() => {
+		if (lastRevalidatedURL.current === currentURL) {
+			return
+		}
+		lastRevalidatedURL.current = currentURL
+		for (const name of Object.keys(targetPage.documents)) {
+			if (data_cache.has(name)) {
+				data_cache.get(name).send({ variables, session })
+			}
+		}
+	}, [currentURL])
+
 	// the function to call to navigate. accepts either a ready-made url string or a
 	// typed target { to, params, search } that is assembled (and custom scalars
 	// marshaled) exactly the way <Link> builds its href. The typed surface is the
 	// shared Goto contract; the implementation takes the loose runtime shape.
-	const goto = ((
-		target:
-			| string
-			| { to: string; params?: Record<string, unknown>; search?: Record<string, unknown> }
-	) => {
-		const url =
-			typeof target === 'string'
-				? target
-				: buildHref(
-						target.to,
-						manifest.pages[manifest.pagesByUrl[target.to]],
-						getCurrentConfig()?.scalars,
-						target.params,
-						target.search
-					)
-
-		// clear the data cache so that we refetch queries with the new session (will force a cache-lookup)
-		data_cache.clear()
-		// clear pending signals so the next render starts fresh load_query calls
-		ssr_signals.clear()
-
-		// perform the navigation
-		setCurrentURL(url)
-	}) as Goto
+	// Referentially stable (everything it closes over is): it ships in the memoized
+	// NavigationContext value and anchors the link listener effect, so a new identity
+	// per render would re-render every useNavigation consumer and re-attach listeners.
+	const goto = React.useCallback(
+		(
+			target:
+				| string
+				| {
+						to: string
+						params?: Record<string, unknown>
+						search?: Record<string, unknown>
+				  }
+		) => {
+			const url =
+				typeof target === 'string'
+					? target
+					: buildHref(
+							target.to,
+							manifest.pages[manifest.pagesByUrl[target.to]],
+							getCurrentConfig()?.scalars,
+							target.params,
+							target.search
+						)
+
+			// We intentionally don't blanket-clear the data cache on navigation (that would
+			// force every query back through its loading state). Observers and their data
+			// survive, and per-query revalidation is handled by the navigation effect above
+			// (which honors each query's cache policy). A real session change still clears
+			// the cache (updateSession / the session event listener).
+
+			// track the destination urgently (so in-flight renders can identify it) and
+			// perform the navigation inside a transition so React keeps the current route on
+			// screen until the next one is ready (or until showLoading swaps in the frame).
+			setPendingURL(url)
+			startNavigation(() => {
+				setCurrentURL(url)
+			})
+		},
+		[manifest]
+	) as Goto
 
 	// links are powered using anchor tags that we intercept and handle ourselves
 	useLinkBehavior({
@@ -189,31 +437,71 @@ export function Router({
 		},
 	})
 
-	// TODO: cleanup navigation caches
+	// The loading frame only renders on the destination of the navigation: while a
+	// transition is pending, the committed tree still has the previous currentURL
+	// (pendingURL differs), so an urgent re-render of it — e.g. the showLoading flip —
+	// keeps showing the previous page instead of swapping it for its own frame. The
+	// destination (transition lane, where currentURL === pendingURL) renders the frame,
+	// which doesn't suspend, so the transition commits as soon as the rest of the entry
+	// (component, artifacts, layout data) is renderable.
+	const showFrame = showLoading && currentURL === pendingURL
+
+	// the public pending-navigation surface (useNavigation). A navigation counts as
+	// pending until the destination shows its actual content: the transition can commit
+	// with the @loading frame on screen (isNavigating flips false then), so the loading
+	// state extends it. Memoized so consumers only re-render when it actually changes.
+	const navigating = isNavigating || showLoading
+	const navigation = React.useMemo(
+		() => ({ pending: navigating, to: navigating ? pendingURL : null, goto }),
+		[navigating, pendingURL, goto]
+	)
+
 	// render the component embedded in the necessary context so it can orchestrate
 	// its needs
 	return (
-		<LocationContext.Provider
-			value={{
-				pathname: currentURL,
-				goto,
-				params: variables ?? {},
-				search,
-			}}
-		>
-			<Is404Context.Provider value={is404}>
-				{is404 ? (
-					<NotFoundLayoutBoundary key={targetPage.id}>
-						<PageComponent url={currentURL} key={targetPage.id + '__404'} />
-					</NotFoundLayoutBoundary>
-				) : (
-					<PageComponent url={currentURL} key={targetPage.id} />
-				)}
-			</Is404Context.Provider>
-		</LocationContext.Provider>
+		<PendingURLContext.Provider value={pendingURL}>
+			<NavigationContext.Provider value={navigation}>
+				<LocationContext.Provider
+					value={{
+						pathname: currentURL,
+						goto,
+						params: variables ?? {},
+						search,
+					}}
+				>
+					<Is404Context.Provider value={is404}>
+						{is404 ? (
+							<NotFoundLayoutBoundary key={targetPage.id}>
+								<PageComponent
+									url={currentURL}
+									showLoading={showFrame}
+									key={targetPage.id + '__404'}
+								/>
+							</NotFoundLayoutBoundary>
+						) : (
+							<PageComponent
+								url={currentURL}
+								showLoading={showFrame}
+								key={targetPage.id}
+							/>
+						)}
+					</Is404Context.Provider>
+				</LocationContext.Provider>
+			</NavigationContext.Provider>
+		</PendingURLContext.Provider>
 	)
 }
 
+// useNavigation exposes the router's in-flight navigation. `pending` is true from the
+// moment a navigation starts until the destination renders its actual content — it stays
+// true while the destination's @loading state is showing — and `to` carries the
+// destination url while pending (null when idle). It also carries `goto` — the same
+// navigate function useRoute exposes — so navigation chrome (progress bars, nav menus,
+// per-link spinners) only needs this one hook.
+export function useNavigation(): { pending: boolean; to: string | null; goto: Goto } {
+	return useContext(NavigationContext)
+}
+
 // internal accessor for the raw location context. the public surface is useRoute, which
 // layers the per-route param/search types on top of this. not re-exported from the package
 // index, so it isn't part of the public API.
@@ -350,6 +638,12 @@ function usePageData({
 			`)
 		}
 
+		// remember which cache generation this send belongs to: if the cache is
+		// invalidated while the request is in flight (a session change clears it), the
+		// result was fetched under state that no longer applies and must not be
+		// re-inserted — the invalidation already triggered a fresh send
+		const generation = data_cache.generation
+
 		// store the observer immediately so useQueryResult can access it
 		// during SSR rendering before the fetch resolves
 		let resolve: () => void = () => {}
@@ -364,6 +658,14 @@ function usePageData({
 					session,
 				})
 				.then(async () => {
+					// a stale-generation result: release the signal so nothing hangs, but
+					// don't put the observer (or its stream scripts) anywhere
+					if (data_cache.generation !== generation) {
+						ssr_signals.delete(id)
+						resolve()
+						return
+					}
+
 					data_cache.set(id, observer)
 
 					// if there is an error, stream it to the client (so an @loading query
@@ -490,6 +792,11 @@ function usePageData({
 					if (err?.name === 'AbortError') {
 						return
 					}
+					// same stale-generation rule as the success path
+					if (data_cache.generation !== generation) {
+						resolve()
+						return
+					}
 					// a thrown error (e.g. a throwOnError plugin) never lands in observer.state, so
 					// seed it as a synthetic GraphQL error on the store and stream it to the client,
 					// otherwise an @loading query that rejects hangs on the loading state
@@ -643,16 +950,26 @@ export function RouterContextProvider({
 	// if we detect an event that contains a new session value. The detail carries the subtree
 	// and whether to merge it into the current session (an @session(merge:) upsert) or replace
 	// it wholesale; a legacy plain-session detail is treated as a replace.
-	const handleNewSession = React.useCallback((event: Event) => {
-		const detail = (event as CustomEvent<HoudiniSessionEventDetail | App.Session>).detail
-		const isWrapped =
-			detail && typeof detail === 'object' && 'session' in detail && 'merge' in detail
-		const next = (
-			isWrapped ? (detail as HoudiniSessionEventDetail).session : detail
-		) as App.Session
-		const merge = isWrapped && (detail as HoudiniSessionEventDetail).merge
-		setSession((prev) => (merge ? { ...prev, ...next } : next))
-	}, [])
+	const handleNewSession = React.useCallback(
+		(event: Event) => {
+			const detail = (event as CustomEvent<HoudiniSessionEventDetail | App.Session>).detail
+			const isWrapped =
+				detail && typeof detail === 'object' && 'session' in detail && 'merge' in detail
+			const next = (
+				isWrapped ? (detail as HoudiniSessionEventDetail).session : detail
+			) as App.Session
+			const merge = isWrapped && (detail as HoudiniSessionEventDetail).merge
+
+			// a new session invalidates every cached query result, exactly like updateSession():
+			// navigation no longer clears the data cache, so without this an event-driven
+			// session change (updateLocalSession) would keep serving results fetched under the
+			// old session
+			invalidate_session_caches({ data_cache, ssr_signals, last_variables })
+
+			setSession((prev) => (merge ? { ...prev, ...next } : next))
+		},
+		[data_cache, ssr_signals, last_variables]
+	)
 
 	React.useEffect(() => {
 		window.addEventListener(HOUDINI_SESSION_EVENT, handleNewSession)
@@ -778,6 +1095,21 @@ export function updateLocalSession(session: App.Session, merge = false) {
 	)
 }
 
+// invalidate_session_caches drops everything derived from the previous session: query
+// results, in-flight signal bookkeeping, and the last-sent variables (so useQueryResult's
+// keep-last-store check can't match a store fetched under the old session — the page
+// suspends into its loading state and refetches). One helper shared by both session-change
+// paths (updateSession and the HOUDINI_SESSION_EVENT listener) so they can't drift.
+function invalidate_session_caches(caches: {
+	data_cache: SuspenseCache<DocumentStore<GraphQLObject, GraphQLVariables>>
+	ssr_signals: PendingCache
+	last_variables: LRUCache<GraphQLVariables>
+}) {
+	caches.data_cache.clear()
+	caches.ssr_signals.clear()
+	caches.last_variables.clear()
+}
+
 export function useSession(): [
 	App.Session,
 	(newSession: Partial<App.Session> | null) => Promise<void>,
@@ -790,9 +1122,8 @@ export function useSession(): [
 	// log out — clearing the local session and deleting the cookie. It's awaitable so callers
 	// can wait for the cookie to settle before navigating.
 	const updateSession = async (newSession: Partial<App.Session> | null) => {
-		// clear the data cache so that we refetch queries with the new session (will force a cache-lookup)
-		ctx.data_cache.clear()
-		ctx.ssr_signals.clear()
+		// drop everything derived from the previous session so queries refetch with the new one
+		invalidate_session_caches(ctx)
 
 		if (newSession === null) {
 			ctx.clearSession()
@@ -817,10 +1148,62 @@ export function useQueryResult<_Data extends GraphQLObject, _Input extends Graph
 	name: string
 ): [_Data | null, DocumentHandle<any, _Data, _Input>] {
 	// pull the global context values
-	const { data_cache, artifact_cache } = useRouterContext()
+	const { data_cache, artifact_cache, last_variables } = useRouterContext()
+	const { pathname } = useLocationContext()
+	const pendingURL = React.useContext(PendingURLContext)
+	// the store (and the router-level variables it was sent with) from this component's
+	// last COMMIT. Written in an effect, never during render: the ref object is shared
+	// between a fiber and its work-in-progress alternate, so a render-phase write from a
+	// transition lane that never commits would leak the wrong store into the committed
+	// tree's next render.
+	const last_store = React.useRef<DocumentStore<_Data, _Input> | null>(null)
+	const last_vars = React.useRef<GraphQLVariables | null>(null)
+	const [, bumpStore] = React.useReducer((n: number) => n + 1, 0)
+
+	// Decide which store to render. data_cache.get suspends when the store is missing —
+	// the right behavior for a first render or for the navigation destination (a
+	// transition waits on it, or the page's @loading boundary catches it). But the router
+	// evicts a document mid-navigation to reload it with new variables, and a re-render
+	// of the still-visible previous page must NOT re-suspend into its own loading state —
+	// it keeps rendering the store from its last commit and the in-flight navigation
+	// swaps the tree when the replacement resolves. Two cases keep the last store:
+	//   - the render's URL lags the navigation target (pendingURL is lane-independent —
+	//     see PendingURLContext). A lagging render always prefers its committed store,
+	//     even when the cache already holds a replacement for different variables.
+	//   - the store is missing but the router's current variables for this document
+	//     still match the ones the committed store was sent with: the eviction belongs
+	//     to a navigation that was abandoned (e.g. goto back to the committed URL), so
+	//     this render should keep its data while the document reloads.
+	// The bump effect re-renders once a replacement lands, so a kept-stale commit always
+	// converges to the fresh store.
+	const missing = !data_cache.has(name)
+	const lagging = pendingURL !== null && pathname !== pendingURL
+	const matches_render =
+		last_vars.current !== null && deepEquals(last_vars.current, last_variables.get(name))
+	const store_ref =
+		last_store.current && (lagging || (missing && matches_render))
+			? last_store.current
+			: (data_cache.get(name)! as unknown as DocumentStore<_Data, _Input>)
 
-	// load the store reference (this will suspend)
-	const store_ref = data_cache.get(name)! as unknown as DocumentStore<_Data, _Input>
+	React.useEffect(() => {
+		last_store.current = store_ref
+		last_vars.current = (last_variables.get(name) as GraphQLVariables | null) ?? null
+	})
+
+	React.useEffect(() => {
+		if (!missing) {
+			return
+		}
+		let cancelled = false
+		data_cache.waitFor(name).then(() => {
+			if (!cancelled) {
+				bumpStore()
+			}
+		})
+		return () => {
+			cancelled = true
+		}
+	}, [missing, name])
 
 	// get the live data from the store
 	const [storeValue, observer] = useDocumentStore<_Data, _Input>({
@@ -867,9 +1250,6 @@ function useLinkBehavior({
 }
 
 function useLinkNavigation({ goto }: { goto: Goto }) {
-	// navigations need to be registered as transitions
-	const [_pending, startTransition] = React.useTransition()
-
 	React.useEffect(() => {
 		const onClick: HTMLAnchorElement['onclick'] = (e) => {
 			if (!e.target) {
@@ -918,10 +1298,11 @@ function useLinkNavigation({ goto }: { goto: Goto }) {
 			e.preventDefault()
 			e.stopPropagation()
 
-			// go to the next route as a low priority update
-			startTransition(() => {
-				goto(target)
-			})
+			// goto() runs the URL update in its own transition and tracks the pending
+			// destination urgently. Don't wrap the call in another transition here: that
+			// would drag the urgent bookkeeping (pendingURL) into the transition lane,
+			// and the committed tree couldn't tell where the navigation is headed.
+			goto(target)
 		}
 
 		window.addEventListener('click', onClick)
@@ -1016,7 +1397,14 @@ export function router_cache({
 	const result: RouterCache = {
 		artifact_cache: suspense_cache(initialArtifacts),
 		component_cache: suspense_cache(),
-		data_cache: suspense_cache(initialData),
+		// observers accumulate across navigations now that goto doesn't clear the cache,
+		// so the LRU capacity limit is reachable on long sessions. When it silently evicts
+		// a store, let the store's plugins release whatever they hold. Best-effort: a
+		// cleanup that rejects must not become an unhandled rejection (which kills a node
+		// process outright).
+		data_cache: suspense_cache(initialData, (store) => {
+			store.cleanup().catch(() => {})
+		}),
 		ssr_signals: suspense_cache(),
 		last_variables: suspense_cache(),
 	}

package/runtime/routing/cache.ts

@@ -3,8 +3,11 @@
 // is thrown that resolves when a value is passed to set()
 import { LRUCache } from 'houdini/runtime'
 
-export function suspense_cache<T>(initialData?: Record<string, T>): SuspenseCache<T> {
-	const cache = new SuspenseCache<T>()
+export function suspense_cache<T>(
+	initialData?: Record<string, T>,
+	dispose?: (value: T) => void
+): SuspenseCache<T> {
+	const cache = new SuspenseCache<T>(dispose)
 
 	for (const [key, value] of Object.entries(initialData ?? {})) {
 		cache.set(key, value)
@@ -18,6 +21,26 @@ export class SuspenseCache<_Data> extends LRUCache<_Data> {
 	// that means we need a place to put our callbacks
 	#callbacks: Map<string, { resolve: () => void; reject: () => void }[]> = new Map()
 
+	// called when a value is silently evicted by the LRU capacity limit so it can
+	// release any resources it holds (e.g. a DocumentStore's plugin state). Explicit
+	// delete()/clear() don't dispose: their values may still be rendered by a mounted
+	// component that is about to re-suspend and receive a replacement.
+	#dispose?: (value: _Data) => void
+
+	constructor(dispose?: (value: _Data) => void) {
+		super()
+		this.#dispose = dispose
+	}
+
+	// bumped by clear() so async work started before an invalidation can tell its results
+	// are stale (see load_query, which drops a completed send from a previous generation
+	// instead of re-inserting data fetched under an old session)
+	#generation = 0
+
+	get generation(): number {
+		return this.#generation
+	}
+
 	get(key: string): _Data {
 		// if there is a value, use that
 		if (super.has(key)) {
@@ -26,17 +49,40 @@ export class SuspenseCache<_Data> extends LRUCache<_Data> {
 
 		// we don't have a value, so we need to throw a promise
 		// that resolves when a value is passed to set()
-		throw new Promise<void>((resolve, reject) => {
+		throw this.waitFor(key)
+	}
+
+	// waitFor resolves when the key holds a value — immediately if it already does,
+	// otherwise when set() is next called for it. The non-throwing counterpart to get()
+	// for code that isn't rendering (so it can't suspend).
+	waitFor(key: string): Promise<void> {
+		if (super.has(key)) {
+			return Promise.resolve()
+		}
+		return new Promise<void>((resolve, reject) => {
 			this.#subscribe(key, resolve, reject)
 		})
 	}
 
 	override clear() {
 		super.clear()
-		this.#callbacks.clear()
+		this.#generation++
+		// deliberately NOT clearing #callbacks: a waitFor()/get() subscriber is waiting
+		// for the key to hold a value, and after an invalidation the router refetches and
+		// set()s it again — the pre-clear subscribers must resolve then (with the fresh
+		// value) instead of hanging forever on a promise nothing can settle.
 	}
 
 	set(key: string, value: _Data) {
+		// inserting a new key at capacity silently evicts the least-recently-used entry —
+		// hand it to the dispose hook first so it can clean up after itself
+		if (this.#dispose && !super.has(key) && this.size() >= this._capacity) {
+			const oldest = this._map.keys().next()
+			if (!oldest.done) {
+				this.#dispose(this._map.get(oldest.value)!)
+			}
+		}
+
 		// perform the set like normal
 		super.set(key, value)
 

package/runtime/routing/errors.tsx

@@ -1,7 +1,7 @@
 import type { GraphQLError } from 'houdini/runtime'
 import React from 'react'
 
-import { StatusContext } from '../contexts.js'
+import { LocationContext, StatusContext } from '../contexts.js'
 
 export class GraphQLErrors extends Error {
 	graphqlErrors: GraphQLError[]
@@ -90,33 +90,67 @@ type HoudiniErrorBoundaryProps = {
 type HoudiniErrorBoundaryState = {
 	hasError: boolean
 	errors: Array<Error | GraphQLError>
+	// the resetKey (current pathname) the boundary last rendered for — a caught error is
+	// cleared when it changes (see getDerivedStateFromProps)
+	resetKey: string
 }
 
-export class HoudiniErrorBoundary extends React.Component<
-	HoudiniErrorBoundaryProps,
+// HoudiniErrorBoundary wraps the class boundary so it can read the current pathname:
+// route boundaries persist across same-route navigations (they aren't remounted per URL
+// anymore), so the boundary has to clear a caught error itself when the URL changes —
+// otherwise navigating away from an errored page would keep rendering the error view.
+export function HoudiniErrorBoundary(props: HoudiniErrorBoundaryProps) {
+	const { pathname } = React.useContext(LocationContext)
+	return <ErrorBoundary resetKey={pathname} {...props} />
+}
+
+class ErrorBoundary extends React.Component<
+	HoudiniErrorBoundaryProps & { resetKey: string },
 	HoudiniErrorBoundaryState
 > {
 	static contextType = StatusContext
 	declare context: React.ContextType<typeof StatusContext>
 
 	constructor(
-		props: HoudiniErrorBoundaryProps,
+		props: HoudiniErrorBoundaryProps & { resetKey: string },
 		context: React.ContextType<typeof StatusContext>
 	) {
 		super(props, context)
 		// Second-pass SSR: statusRef is pre-set to an error status by on_render after the first
-		// render threw. Start in error state immediately so children never render (and never throw).
+		// render threw. Start in error state immediately so children never render (and never
+		// throw). The ref carries the actual thrown errors when it has them (e.g. GraphQL
+		// errors from a query); a bare status (a routing error / unmatched URL) renders as a
+		// RoutingError so the view can branch on the status code.
 		if (typeof window === 'undefined' && context && context.status >= 400) {
 			this.state = {
 				hasError: true,
-				errors: [new RoutingError(context.status)],
+				errors: context.errors ?? [new RoutingError(context.status)],
+				resetKey: props.resetKey,
 			}
 		} else {
-			this.state = { hasError: false, errors: [] }
+			this.state = { hasError: false, errors: [], resetKey: props.resetKey }
+		}
+	}
+
+	// a navigation is a retry: clear a caught error the moment a render arrives for a new
+	// URL. Doing this in derived state (not componentDidUpdate + setState) matters: the
+	// reset happens inside whatever render is already in flight, so when the router
+	// navigates away from an errored route the children render — and suspend — inside the
+	// router's own transition. isNavigating/showLoading account for the wait, the error
+	// view stays on screen until the destination is renderable, and the destination's
+	// @loading frame can show. If the retry throws again the boundary re-catches, and
+	// since resetKey is unchanged then, it can't loop.
+	static getDerivedStateFromProps(
+		props: HoudiniErrorBoundaryProps & { resetKey: string },
+		state: HoudiniErrorBoundaryState
+	): Partial<HoudiniErrorBoundaryState> | null {
+		if (props.resetKey !== state.resetKey) {
+			return { hasError: false, errors: [], resetKey: props.resetKey }
 		}
+		return null
 	}
 
-	static getDerivedStateFromError(error: unknown): HoudiniErrorBoundaryState {
+	static getDerivedStateFromError(error: unknown): Partial<HoudiniErrorBoundaryState> {
 		if (error instanceof GraphQLErrors) {
 			return { hasError: true, errors: error.graphqlErrors }
 		}
@@ -126,17 +160,6 @@ export class HoudiniErrorBoundary extends React.Component<
 		}
 	}
 
-	componentDidCatch(error: Error): void {
-		if (this.context) {
-			if (error instanceof RoutingError) {
-				this.context.status = error.status
-			} else if (error instanceof RedirectError) {
-				this.context.status = error.status
-				this.context.location = error.location
-			}
-		}
-	}
-
 	render() {
 		if (this.state.hasError) {
 			const ErrorView = this.props.errorView