tanstack-router-cache 0.1.2 → 0.1.4

package/README.md

@@ -55,8 +55,7 @@ For the full API, see [docs](./docs).
 
 ## Examples
 
-- [Basic](https://github.com/santiago-ramos-02/tanstack-router-cache/tree/main/examples/basic): the smallest useful setup. Start here; most apps only need this pattern.
-- [Power-user demo](https://github.com/santiago-ramos-02/tanstack-router-cache/tree/main/examples/power-user-demo): a larger demo with retained forms, filtered lists, cache controls, route lifecycle state, and window scroll restoration. Use it when you need to inspect edge cases.
+- [Demo app](https://github.com/santiago-ramos-02/tanstack-router-cache/tree/main/examples/demo): one Vite app with a basic flow for most users and a power-user flow for edge cases.
 
 ## Acknowledgements
 

package/dist/index.cjs

@@ -371,10 +371,7 @@ function useRouterCacheDebug(cachedRoutes, visiblePathname) {
 				warningThreshold: warningThresholdRef.current
 			};
 			const warningThreshold = warningThresholdRef.current;
-			if (typeof warningThreshold === "number" && nextSnapshot.totalCachedRouteCount > warningThreshold && lastWarnedCountRef.current !== nextSnapshot.totalCachedRouteCount) {
-				lastWarnedCountRef.current = nextSnapshot.totalCachedRouteCount;
-				console.warn("[tanstack-router-cache] cached route count exceeded threshold", nextSnapshot);
-			}
+			if (typeof warningThreshold === "number" && nextSnapshot.totalCachedRouteCount > warningThreshold && lastWarnedCountRef.current !== nextSnapshot.totalCachedRouteCount) lastWarnedCountRef.current = nextSnapshot.totalCachedRouteCount;
 		});
 		return () => {
 			globalThis.cancelAnimationFrame(rafId);
@@ -790,12 +787,50 @@ const LIVE_ROUTER_METHODS = [
 	"navigate",
 	"preloadRoute"
 ];
-function createStaticStore(value) {
+const routerSnapshotUpdaters = /* @__PURE__ */ new WeakMap();
+function createSnapshotStore(value) {
+	let currentValue = value;
+	const listeners = /* @__PURE__ */ new Set();
 	return {
-		get: () => value,
-		subscribe: () => ({ unsubscribe: () => void 0 })
+		get: () => currentValue,
+		set: (nextValue) => {
+			if (Object.is(currentValue, nextValue)) return;
+			currentValue = nextValue;
+			for (const listener of listeners) listener(currentValue);
+		},
+		subscribe: (listener) => {
+			if (listener) listeners.add(listener);
+			return { unsubscribe: listener ? () => {
+				listeners.delete(listener);
+			} : () => void 0 };
+		}
 	};
 }
+function createRouterSnapshotData({ matches, router, routerLocation, routerResolvedLocation }) {
+	const snapshotMatches = matches.reduce((snapshot, match) => {
+		const nextMatch = snapshotMatch(match, routerLocation);
+		if (isRouterMatch(nextMatch)) snapshot.push(nextMatch);
+		return snapshot;
+	}, []);
+	return {
+		matches: snapshotMatches,
+		state: {
+			...router.stores.__store.get(),
+			matches: snapshotMatches,
+			location: routerLocation,
+			resolvedLocation: routerResolvedLocation
+		}
+	};
+}
+function createMatchStore(match) {
+	return Object.assign(createSnapshotStore(match), { routeId: match.routeId });
+}
+function syncRouterSnapshot(routerSnapshot, input) {
+	const update = routerSnapshotUpdaters.get(routerSnapshot);
+	if (!update) return false;
+	update(input);
+	return true;
+}
 function getLiveRouterMethodDescriptors(router) {
 	return Object.fromEntries(LIVE_ROUTER_METHODS.flatMap((methodName) => {
 		const method = router[methodName];
@@ -831,29 +866,40 @@ function hasCurrentRouteError({ erroredRouteCounts, matches, resolvedPathname, r
 function isRouterMatch(match) {
 	return Boolean(match?.id && match.routeId);
 }
-function snapshotMatch(match) {
+function snapshotMatch(match, routerLocation) {
 	if (!isRouterMatch(match)) return;
+	const isLocationMatch = match.pathname ? normalizeCachedRoutePathname(match.pathname) === normalizeCachedRoutePathname(routerLocation.pathname) : false;
 	return {
 		...match,
+		...isLocationMatch ? {
+			_strictSearch: routerLocation.search,
+			search: routerLocation.search
+		} : {},
 		_nonReactive: { ...match._nonReactive }
 	};
 }
-function shouldRefreshCachedRoute(route, routerHref) {
-	return !(isRouteCacheEnabled(route?.staticData) && route.ready) || route.href !== routerHref;
+function isCurrentUnmanagedCachedRoute(route, routerHref) {
+	return Boolean(route && isRouteCacheEnabled(route.staticData) && route.ready && route.routerSnapshot && route.href === routerHref);
 }
 function syncReadyCachedRoute({ matchId, matches, routeId, route, routerLocation, router, routerResolvedLocation, routerHref, routerPathname, setCachedRoutes, staticData }) {
-	if (!shouldRefreshCachedRoute(route, routerHref)) return;
+	const routerSnapshotInput = {
+		matches,
+		router,
+		routerLocation,
+		routerResolvedLocation
+	};
+	let routerSnapshot = matchId ? route?.routerSnapshot : void 0;
+	if (routerSnapshot && !syncRouterSnapshot(routerSnapshot, routerSnapshotInput)) {
+		if (isCurrentUnmanagedCachedRoute(route, routerHref)) return;
+		routerSnapshot = void 0;
+	}
+	if (matchId && !routerSnapshot) routerSnapshot = createRouterSnapshot(routerSnapshotInput);
 	setCachedRoutes(routerPathname, {
 		href: routerHref,
 		matchId,
 		routeId,
 		ready: true,
-		routerSnapshot: matchId ? createRouterSnapshot({
-			matches,
-			router,
-			routerLocation,
-			routerResolvedLocation
-		}) : void 0,
+		routerSnapshot,
 		staticData
 	});
 }
@@ -882,54 +928,43 @@ function syncCachedRouteState({ isCurrentMatchReady, isCurrentMatchResolved, del
 	}
 	if (route) deleteCachedRoutes([routerPathname]);
 }
-function createRouterSnapshot({ matches, router, routerLocation, routerResolvedLocation }) {
-	const snapshotMatches = matches.reduce((snapshot, match) => {
-		const nextMatch = snapshotMatch(match);
-		if (isRouterMatch(nextMatch)) snapshot.push(nextMatch);
-		return snapshot;
-	}, []);
-	const matchStores = new Map(snapshotMatches.map((match) => {
-		const store = Object.assign(createStaticStore(match), { routeId: match.routeId });
-		return [match.id, store];
-	}));
-	const snapshotState = {
-		...router.stores.__store.get(),
-		matches: snapshotMatches,
-		location: routerLocation,
-		resolvedLocation: routerResolvedLocation
-	};
+function createRouterSnapshot(input) {
+	const { router, routerLocation, routerResolvedLocation } = input;
+	const snapshotData = createRouterSnapshotData(input);
+	const snapshotMatches = snapshotData.matches;
+	const matchStores = new Map(snapshotMatches.map((match) => [match.id, createMatchStore(match)]));
 	const routeMatchStoreCache = /* @__PURE__ */ new Map();
 	const stores = {
 		...router.stores,
-		status: createStaticStore(router.stores.status.get()),
-		loadedAt: createStaticStore(router.stores.loadedAt.get()),
-		isLoading: createStaticStore(router.stores.isLoading.get()),
-		isTransitioning: createStaticStore(router.stores.isTransitioning.get()),
-		location: createStaticStore(routerLocation),
-		resolvedLocation: createStaticStore(routerResolvedLocation),
-		statusCode: createStaticStore(router.stores.statusCode.get()),
-		redirect: createStaticStore(router.stores.redirect.get()),
-		matchesId: createStaticStore(snapshotMatches.map((match) => match.id)),
-		pendingIds: createStaticStore([]),
-		cachedIds: createStaticStore([]),
-		matches: createStaticStore(snapshotMatches),
-		pendingMatches: createStaticStore([]),
-		cachedMatches: createStaticStore([]),
-		firstId: createStaticStore(snapshotMatches[0]?.id),
-		hasPending: createStaticStore(snapshotMatches.some((match) => match.status === "pending")),
-		matchRouteDeps: createStaticStore({
+		status: createSnapshotStore(router.stores.status.get()),
+		loadedAt: createSnapshotStore(router.stores.loadedAt.get()),
+		isLoading: createSnapshotStore(router.stores.isLoading.get()),
+		isTransitioning: createSnapshotStore(router.stores.isTransitioning.get()),
+		location: createSnapshotStore(routerLocation),
+		resolvedLocation: createSnapshotStore(routerResolvedLocation),
+		statusCode: createSnapshotStore(router.stores.statusCode.get()),
+		redirect: createSnapshotStore(router.stores.redirect.get()),
+		matchesId: createSnapshotStore(snapshotMatches.map((match) => match.id)),
+		pendingIds: createSnapshotStore([]),
+		cachedIds: createSnapshotStore([]),
+		matches: createSnapshotStore(snapshotMatches),
+		pendingMatches: createSnapshotStore([]),
+		cachedMatches: createSnapshotStore([]),
+		firstId: createSnapshotStore(snapshotMatches[0]?.id),
+		hasPending: createSnapshotStore(snapshotMatches.some((match) => match.status === "pending")),
+		matchRouteDeps: createSnapshotStore({
 			locationHref: routerLocation.href,
 			resolvedLocationHref: routerResolvedLocation?.href,
-			status: snapshotState.status
+			status: snapshotData.state.status
 		}),
-		__store: createStaticStore(snapshotState),
+		__store: createSnapshotStore(snapshotData.state),
 		matchStores,
 		pendingMatchStores: /* @__PURE__ */ new Map(),
 		cachedMatchStores: /* @__PURE__ */ new Map(),
 		getRouteMatchStore: (routeId) => {
 			let cached = routeMatchStoreCache.get(routeId);
 			if (!cached) {
-				cached = createStaticStore(snapshotMatches.find((match) => match.routeId === routeId));
+				cached = createSnapshotStore(snapshotMatches.find((match) => match.routeId === routeId));
 				routeMatchStoreCache.set(routeId, cached);
 			}
 			return cached;
@@ -938,14 +973,53 @@ function createRouterSnapshot({ matches, router, routerLocation, routerResolvedL
 		setPending: () => void 0,
 		setCached: () => void 0
 	};
+	const updateSnapshot = (nextInput) => {
+		const nextData = createRouterSnapshotData(nextInput);
+		const nextMatches = nextData.matches;
+		const nextMatchIds = new Set(nextMatches.map((match) => match.id));
+		const nextMatchesByRouteId = new Map(nextMatches.map((match) => [match.routeId, match]));
+		for (const match of nextMatches) {
+			const store = matchStores.get(match.id);
+			if (store) {
+				store.set(match);
+				continue;
+			}
+			matchStores.set(match.id, createMatchStore(match));
+		}
+		for (const [matchId] of matchStores) if (!nextMatchIds.has(matchId)) matchStores.delete(matchId);
+		stores.status.set(nextInput.router.stores.status.get());
+		stores.loadedAt.set(nextInput.router.stores.loadedAt.get());
+		stores.isLoading.set(nextInput.router.stores.isLoading.get());
+		stores.isTransitioning.set(nextInput.router.stores.isTransitioning.get());
+		stores.location.set(nextInput.routerLocation);
+		stores.resolvedLocation.set(nextInput.routerResolvedLocation);
+		stores.statusCode.set(nextInput.router.stores.statusCode.get());
+		stores.redirect.set(nextInput.router.stores.redirect.get());
+		stores.matchesId.set(nextMatches.map((match) => match.id));
+		stores.pendingIds.set([]);
+		stores.cachedIds.set([]);
+		stores.matches.set(nextMatches);
+		stores.pendingMatches.set([]);
+		stores.cachedMatches.set([]);
+		stores.firstId.set(nextMatches[0]?.id);
+		stores.hasPending.set(nextMatches.some((match) => match.status === "pending"));
+		stores.matchRouteDeps.set({
+			locationHref: nextInput.routerLocation.href,
+			resolvedLocationHref: nextInput.routerResolvedLocation?.href,
+			status: nextData.state.status
+		});
+		stores.__store.set(nextData.state);
+		for (const [routeId, store] of routeMatchStoreCache) store.set(nextMatchesByRouteId.get(routeId));
+	};
 	const routerSnapshot = Object.create(router);
 	Object.defineProperties(routerSnapshot, {
 		stores: { value: stores },
-		latestLocation: { value: routerLocation },
+		latestLocation: { get: () => stores.location.get() },
 		getMatch: { value: (matchId) => matchStores.get(matchId)?.get() },
 		updateMatch: { value: () => void 0 },
 		...getLiveRouterMethodDescriptors(router)
 	});
+	routerSnapshotUpdaters.set(routerSnapshot, updateSnapshot);
 	return routerSnapshot;
 }
 function getRouterCacheStaticData(childMatches, isCurrentMatchResolved) {
@@ -1017,7 +1091,7 @@ function RouteCacheManager() {
 	const previousPathnameRef = (0, react.useRef)(void 0);
 	const previousHrefRef = (0, react.useRef)(void 0);
 	const previousRouteCacheModesRef = (0, react.useRef)(null);
-	if (previousRouteCacheModesRef.current === null) previousRouteCacheModesRef.current = /* @__PURE__ */ new Map();
+	previousRouteCacheModesRef.current ??= /* @__PURE__ */ new Map();
 	const previousVisiblePathnameRef = (0, react.useRef)(void 0);
 	const routerLocation = (0, _tanstack_react_router.useRouterState)({ select: (state) => toRouterLocation(state.location) });
 	const routerHref = routerLocation.href;
@@ -1113,7 +1187,7 @@ function RouteCacheManager() {
 		visiblePathname
 	]);
 	(0, react.useLayoutEffect)(() => {
-		if (previousRouteCacheModesRef.current === null) previousRouteCacheModesRef.current = /* @__PURE__ */ new Map();
+		previousRouteCacheModesRef.current ??= /* @__PURE__ */ new Map();
 		previousRouteCacheModesRef.current = syncCachedRouteActivityEvents({
 			cachedRoutes,
 			eventListener,

package/dist/index.js

@@ -370,10 +370,7 @@ function useRouterCacheDebug(cachedRoutes, visiblePathname) {
 				warningThreshold: warningThresholdRef.current
 			};
 			const warningThreshold = warningThresholdRef.current;
-			if (typeof warningThreshold === "number" && nextSnapshot.totalCachedRouteCount > warningThreshold && lastWarnedCountRef.current !== nextSnapshot.totalCachedRouteCount) {
-				lastWarnedCountRef.current = nextSnapshot.totalCachedRouteCount;
-				console.warn("[tanstack-router-cache] cached route count exceeded threshold", nextSnapshot);
-			}
+			if (typeof warningThreshold === "number" && nextSnapshot.totalCachedRouteCount > warningThreshold && lastWarnedCountRef.current !== nextSnapshot.totalCachedRouteCount) lastWarnedCountRef.current = nextSnapshot.totalCachedRouteCount;
 		});
 		return () => {
 			globalThis.cancelAnimationFrame(rafId);
@@ -789,12 +786,50 @@ const LIVE_ROUTER_METHODS = [
 	"navigate",
 	"preloadRoute"
 ];
-function createStaticStore(value) {
+const routerSnapshotUpdaters = /* @__PURE__ */ new WeakMap();
+function createSnapshotStore(value) {
+	let currentValue = value;
+	const listeners = /* @__PURE__ */ new Set();
 	return {
-		get: () => value,
-		subscribe: () => ({ unsubscribe: () => void 0 })
+		get: () => currentValue,
+		set: (nextValue) => {
+			if (Object.is(currentValue, nextValue)) return;
+			currentValue = nextValue;
+			for (const listener of listeners) listener(currentValue);
+		},
+		subscribe: (listener) => {
+			if (listener) listeners.add(listener);
+			return { unsubscribe: listener ? () => {
+				listeners.delete(listener);
+			} : () => void 0 };
+		}
 	};
 }
+function createRouterSnapshotData({ matches, router, routerLocation, routerResolvedLocation }) {
+	const snapshotMatches = matches.reduce((snapshot, match) => {
+		const nextMatch = snapshotMatch(match, routerLocation);
+		if (isRouterMatch(nextMatch)) snapshot.push(nextMatch);
+		return snapshot;
+	}, []);
+	return {
+		matches: snapshotMatches,
+		state: {
+			...router.stores.__store.get(),
+			matches: snapshotMatches,
+			location: routerLocation,
+			resolvedLocation: routerResolvedLocation
+		}
+	};
+}
+function createMatchStore(match) {
+	return Object.assign(createSnapshotStore(match), { routeId: match.routeId });
+}
+function syncRouterSnapshot(routerSnapshot, input) {
+	const update = routerSnapshotUpdaters.get(routerSnapshot);
+	if (!update) return false;
+	update(input);
+	return true;
+}
 function getLiveRouterMethodDescriptors(router) {
 	return Object.fromEntries(LIVE_ROUTER_METHODS.flatMap((methodName) => {
 		const method = router[methodName];
@@ -830,29 +865,40 @@ function hasCurrentRouteError({ erroredRouteCounts, matches, resolvedPathname, r
 function isRouterMatch(match) {
 	return Boolean(match?.id && match.routeId);
 }
-function snapshotMatch(match) {
+function snapshotMatch(match, routerLocation) {
 	if (!isRouterMatch(match)) return;
+	const isLocationMatch = match.pathname ? normalizeCachedRoutePathname(match.pathname) === normalizeCachedRoutePathname(routerLocation.pathname) : false;
 	return {
 		...match,
+		...isLocationMatch ? {
+			_strictSearch: routerLocation.search,
+			search: routerLocation.search
+		} : {},
 		_nonReactive: { ...match._nonReactive }
 	};
 }
-function shouldRefreshCachedRoute(route, routerHref) {
-	return !(isRouteCacheEnabled(route?.staticData) && route.ready) || route.href !== routerHref;
+function isCurrentUnmanagedCachedRoute(route, routerHref) {
+	return Boolean(route && isRouteCacheEnabled(route.staticData) && route.ready && route.routerSnapshot && route.href === routerHref);
 }
 function syncReadyCachedRoute({ matchId, matches, routeId, route, routerLocation, router, routerResolvedLocation, routerHref, routerPathname, setCachedRoutes, staticData }) {
-	if (!shouldRefreshCachedRoute(route, routerHref)) return;
+	const routerSnapshotInput = {
+		matches,
+		router,
+		routerLocation,
+		routerResolvedLocation
+	};
+	let routerSnapshot = matchId ? route?.routerSnapshot : void 0;
+	if (routerSnapshot && !syncRouterSnapshot(routerSnapshot, routerSnapshotInput)) {
+		if (isCurrentUnmanagedCachedRoute(route, routerHref)) return;
+		routerSnapshot = void 0;
+	}
+	if (matchId && !routerSnapshot) routerSnapshot = createRouterSnapshot(routerSnapshotInput);
 	setCachedRoutes(routerPathname, {
 		href: routerHref,
 		matchId,
 		routeId,
 		ready: true,
-		routerSnapshot: matchId ? createRouterSnapshot({
-			matches,
-			router,
-			routerLocation,
-			routerResolvedLocation
-		}) : void 0,
+		routerSnapshot,
 		staticData
 	});
 }
@@ -881,54 +927,43 @@ function syncCachedRouteState({ isCurrentMatchReady, isCurrentMatchResolved, del
 	}
 	if (route) deleteCachedRoutes([routerPathname]);
 }
-function createRouterSnapshot({ matches, router, routerLocation, routerResolvedLocation }) {
-	const snapshotMatches = matches.reduce((snapshot, match) => {
-		const nextMatch = snapshotMatch(match);
-		if (isRouterMatch(nextMatch)) snapshot.push(nextMatch);
-		return snapshot;
-	}, []);
-	const matchStores = new Map(snapshotMatches.map((match) => {
-		const store = Object.assign(createStaticStore(match), { routeId: match.routeId });
-		return [match.id, store];
-	}));
-	const snapshotState = {
-		...router.stores.__store.get(),
-		matches: snapshotMatches,
-		location: routerLocation,
-		resolvedLocation: routerResolvedLocation
-	};
+function createRouterSnapshot(input) {
+	const { router, routerLocation, routerResolvedLocation } = input;
+	const snapshotData = createRouterSnapshotData(input);
+	const snapshotMatches = snapshotData.matches;
+	const matchStores = new Map(snapshotMatches.map((match) => [match.id, createMatchStore(match)]));
 	const routeMatchStoreCache = /* @__PURE__ */ new Map();
 	const stores = {
 		...router.stores,
-		status: createStaticStore(router.stores.status.get()),
-		loadedAt: createStaticStore(router.stores.loadedAt.get()),
-		isLoading: createStaticStore(router.stores.isLoading.get()),
-		isTransitioning: createStaticStore(router.stores.isTransitioning.get()),
-		location: createStaticStore(routerLocation),
-		resolvedLocation: createStaticStore(routerResolvedLocation),
-		statusCode: createStaticStore(router.stores.statusCode.get()),
-		redirect: createStaticStore(router.stores.redirect.get()),
-		matchesId: createStaticStore(snapshotMatches.map((match) => match.id)),
-		pendingIds: createStaticStore([]),
-		cachedIds: createStaticStore([]),
-		matches: createStaticStore(snapshotMatches),
-		pendingMatches: createStaticStore([]),
-		cachedMatches: createStaticStore([]),
-		firstId: createStaticStore(snapshotMatches[0]?.id),
-		hasPending: createStaticStore(snapshotMatches.some((match) => match.status === "pending")),
-		matchRouteDeps: createStaticStore({
+		status: createSnapshotStore(router.stores.status.get()),
+		loadedAt: createSnapshotStore(router.stores.loadedAt.get()),
+		isLoading: createSnapshotStore(router.stores.isLoading.get()),
+		isTransitioning: createSnapshotStore(router.stores.isTransitioning.get()),
+		location: createSnapshotStore(routerLocation),
+		resolvedLocation: createSnapshotStore(routerResolvedLocation),
+		statusCode: createSnapshotStore(router.stores.statusCode.get()),
+		redirect: createSnapshotStore(router.stores.redirect.get()),
+		matchesId: createSnapshotStore(snapshotMatches.map((match) => match.id)),
+		pendingIds: createSnapshotStore([]),
+		cachedIds: createSnapshotStore([]),
+		matches: createSnapshotStore(snapshotMatches),
+		pendingMatches: createSnapshotStore([]),
+		cachedMatches: createSnapshotStore([]),
+		firstId: createSnapshotStore(snapshotMatches[0]?.id),
+		hasPending: createSnapshotStore(snapshotMatches.some((match) => match.status === "pending")),
+		matchRouteDeps: createSnapshotStore({
 			locationHref: routerLocation.href,
 			resolvedLocationHref: routerResolvedLocation?.href,
-			status: snapshotState.status
+			status: snapshotData.state.status
 		}),
-		__store: createStaticStore(snapshotState),
+		__store: createSnapshotStore(snapshotData.state),
 		matchStores,
 		pendingMatchStores: /* @__PURE__ */ new Map(),
 		cachedMatchStores: /* @__PURE__ */ new Map(),
 		getRouteMatchStore: (routeId) => {
 			let cached = routeMatchStoreCache.get(routeId);
 			if (!cached) {
-				cached = createStaticStore(snapshotMatches.find((match) => match.routeId === routeId));
+				cached = createSnapshotStore(snapshotMatches.find((match) => match.routeId === routeId));
 				routeMatchStoreCache.set(routeId, cached);
 			}
 			return cached;
@@ -937,14 +972,53 @@ function createRouterSnapshot({ matches, router, routerLocation, routerResolvedL
 		setPending: () => void 0,
 		setCached: () => void 0
 	};
+	const updateSnapshot = (nextInput) => {
+		const nextData = createRouterSnapshotData(nextInput);
+		const nextMatches = nextData.matches;
+		const nextMatchIds = new Set(nextMatches.map((match) => match.id));
+		const nextMatchesByRouteId = new Map(nextMatches.map((match) => [match.routeId, match]));
+		for (const match of nextMatches) {
+			const store = matchStores.get(match.id);
+			if (store) {
+				store.set(match);
+				continue;
+			}
+			matchStores.set(match.id, createMatchStore(match));
+		}
+		for (const [matchId] of matchStores) if (!nextMatchIds.has(matchId)) matchStores.delete(matchId);
+		stores.status.set(nextInput.router.stores.status.get());
+		stores.loadedAt.set(nextInput.router.stores.loadedAt.get());
+		stores.isLoading.set(nextInput.router.stores.isLoading.get());
+		stores.isTransitioning.set(nextInput.router.stores.isTransitioning.get());
+		stores.location.set(nextInput.routerLocation);
+		stores.resolvedLocation.set(nextInput.routerResolvedLocation);
+		stores.statusCode.set(nextInput.router.stores.statusCode.get());
+		stores.redirect.set(nextInput.router.stores.redirect.get());
+		stores.matchesId.set(nextMatches.map((match) => match.id));
+		stores.pendingIds.set([]);
+		stores.cachedIds.set([]);
+		stores.matches.set(nextMatches);
+		stores.pendingMatches.set([]);
+		stores.cachedMatches.set([]);
+		stores.firstId.set(nextMatches[0]?.id);
+		stores.hasPending.set(nextMatches.some((match) => match.status === "pending"));
+		stores.matchRouteDeps.set({
+			locationHref: nextInput.routerLocation.href,
+			resolvedLocationHref: nextInput.routerResolvedLocation?.href,
+			status: nextData.state.status
+		});
+		stores.__store.set(nextData.state);
+		for (const [routeId, store] of routeMatchStoreCache) store.set(nextMatchesByRouteId.get(routeId));
+	};
 	const routerSnapshot = Object.create(router);
 	Object.defineProperties(routerSnapshot, {
 		stores: { value: stores },
-		latestLocation: { value: routerLocation },
+		latestLocation: { get: () => stores.location.get() },
 		getMatch: { value: (matchId) => matchStores.get(matchId)?.get() },
 		updateMatch: { value: () => void 0 },
 		...getLiveRouterMethodDescriptors(router)
 	});
+	routerSnapshotUpdaters.set(routerSnapshot, updateSnapshot);
 	return routerSnapshot;
 }
 function getRouterCacheStaticData(childMatches, isCurrentMatchResolved) {
@@ -1016,7 +1090,7 @@ function RouteCacheManager() {
 	const previousPathnameRef = useRef(void 0);
 	const previousHrefRef = useRef(void 0);
 	const previousRouteCacheModesRef = useRef(null);
-	if (previousRouteCacheModesRef.current === null) previousRouteCacheModesRef.current = /* @__PURE__ */ new Map();
+	previousRouteCacheModesRef.current ??= /* @__PURE__ */ new Map();
 	const previousVisiblePathnameRef = useRef(void 0);
 	const routerLocation = useRouterState({ select: (state) => toRouterLocation(state.location) });
 	const routerHref = routerLocation.href;
@@ -1112,7 +1186,7 @@ function RouteCacheManager() {
 		visiblePathname
 	]);
 	useLayoutEffect(() => {
-		if (previousRouteCacheModesRef.current === null) previousRouteCacheModesRef.current = /* @__PURE__ */ new Map();
+		previousRouteCacheModesRef.current ??= /* @__PURE__ */ new Map();
 		previousRouteCacheModesRef.current = syncCachedRouteActivityEvents({
 			cachedRoutes,
 			eventListener,

package/docs/architecture.md

@@ -131,8 +131,8 @@ classDiagram
   }
 
   class RouterSnapshot {
-    static stores
-    static matches
+    snapshot stores
+    snapshot matches
     live navigate
     live invalidate
     live preloadRoute
@@ -149,21 +149,21 @@ classDiagram
 | `routeId` | TanStack route id. Used by `maxEntriesPerRouteId`. |
 | `staticData` | Route static data. The route is cacheable when `routeCache` is `true`. |
 | `matchId` | Match id used to render the cached route with TanStack Router's `Match`. |
-| `routerSnapshot` | Frozen router-like object used by the cached route tree. |
+| `routerSnapshot` | Router-like object with isolated snapshot stores used by the cached route tree. |
 | `ready` | Marks that the route has a complete snapshot and can be rendered from cache. |
 
 Pathnames are normalized by removing trailing slashes except for `/`, so `/customers/` and `/customers` share one cache key.
 
 ## Router snapshot
 
-Cached route trees still expect TanStack Router context. Instead of keeping every cached tree connected to the live router stores, the package creates a router snapshot when a route becomes ready.
+Cached route trees still expect TanStack Router context. Instead of connecting every cached tree directly to the live router stores, the package creates a router-like snapshot when a route becomes ready.
 
 ```mermaid
 flowchart TD
   liveRouter["Live router"]
   matches["Current matches"]
   location["Current location"]
-  staticStores["Static stores"]
+  snapshotStores["Snapshot stores"]
   liveMethods["Bound live methods"]
   routerSnapshot["Router snapshot"]
   cachedOutlet["CachedOutlet"]
@@ -171,18 +171,18 @@ flowchart TD
 
   liveRouter --> matches
   liveRouter --> location
-  matches --> staticStores
-  location --> staticStores
+  matches --> snapshotStores
+  location --> snapshotStores
   liveRouter --> liveMethods
-  staticStores --> routerSnapshot
+  snapshotStores --> routerSnapshot
   liveMethods --> routerSnapshot
   routerSnapshot --> cachedOutlet
   cachedOutlet --> match
 ```
 
-The snapshot copies the current matches, location, resolved location, and match stores. It also keeps selected live router methods bound to the real router, including `navigate`, `invalidate`, `preloadRoute`, and location builders.
+The snapshot owns isolated stores for the current matches, location, resolved location, and match stores. It also keeps selected live router methods bound to the real router, including `navigate`, `invalidate`, `preloadRoute`, and location builders.
 
-This gives hidden cached routes a stable route view while still allowing imperative router actions to call through to the real router.
+When the cached entry is refreshed, the cache manager updates those snapshot stores in place. This lets route hooks read current match and search data without remounting the retained route tree. Imperative router actions still call through to the real router.
 
 `CachedOutlet` renders that snapshot like this:
 

package/docs/releases.md

@@ -1,6 +1,6 @@
 # Releases
 
-This package publishes from GitHub Actions after a version tag is pushed.
+This package publishes from GitHub Actions after a version tag is pushed. A regular commit to `main` only runs CI and updates the GitHub repo. It does not publish to npm.
 
 ## Trusted publishing
 
@@ -14,13 +14,37 @@ npm trust github tanstack-router-cache --repo santiago-ramos-02/tanstack-router-
 
 ## Publishing a version
 
-1. Update `version` in `package.json`.
-2. Commit the change.
-3. Tag the same version:
+Work in the package repo:
 
 ```sh
-git tag v0.2.0
-git push origin main --tags
+cd packages/tanstack-router-cache
 ```
 
-The workflow checks that the tag matches `package.json` before publishing.
+For normal changes:
+
+```sh
+bun run check
+git add .
+git commit -m "Your change"
+git push origin main
+```
+
+That updates GitHub and runs CI, but it does not publish to npm.
+
+For a release, start from a clean `main` branch after your changes are already committed:
+
+```sh
+bun run release:prepare patch
+bun run release:push
+```
+
+Use `minor`, `major`, or an exact version when needed:
+
+```sh
+bun run release:prepare minor
+bun run release:prepare 0.2.0
+```
+
+`release:prepare` updates `package.json`, runs the package checks, commits the version bump, and creates the matching tag locally. `release:push` pushes `main` and that exact tag. The tag starts the npm publish workflow.
+
+The workflow checks that the tag matches `package.json` before publishing, so a mismatched tag cannot publish accidentally.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tanstack-router-cache",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Route view caching for TanStack Router.",
   "type": "module",
   "license": "MIT",
@@ -46,9 +46,12 @@
     "build": "bun run clean && rolldown -c && tsc",
     "typecheck": "tsc --noEmit",
     "clean": "node -e \"fs.rmSync('dist',{recursive:true,force:true})\"",
-    "lint": "biome lint src rolldown.config.ts --skip=lint/performance/noBarrelFile --skip=lint/style/useConsistentTypeDefinitions --skip=lint/suspicious/noConsole",
-    "lint:fix": "biome lint src rolldown.config.ts --write --skip=lint/performance/noBarrelFile --skip=lint/style/useConsistentTypeDefinitions --skip=lint/suspicious/noConsole",
-    "pack:dry-run": "bun pm pack --dry-run",
+    "lint": "biome lint src scripts .github/scripts rolldown.config.ts --skip=lint/performance/noBarrelFile --skip=lint/style/useConsistentTypeDefinitions --skip=lint/suspicious/noConsole",
+    "lint:fix": "biome lint src scripts .github/scripts rolldown.config.ts --write --skip=lint/performance/noBarrelFile --skip=lint/style/useConsistentTypeDefinitions --skip=lint/suspicious/noConsole",
+    "check": "bun run lint && bun run typecheck && bun run build && bun run pack:dry-run",
+    "pack:dry-run": "npm pack --dry-run",
+    "release:prepare": "node scripts/release.mjs prepare",
+    "release:push": "node scripts/release.mjs push",
     "prepack": "bun run build",
     "prepublishOnly": "bun run lint && bun run typecheck"
   },