@pyreon/router 0.18.0 → 0.19.0

package/lib/analysis/index.js.html

@@ -5386,7 +5386,7 @@ var drawChart = (function (exports) {
   </script>
   <script>
     /*<!--*/
-    const data = {"version":2,"tree":{"name":"root","children":[{"name":"index.js","children":[{"name":"src","children":[{"uid":"93e1055e-1","name":"loader.ts"},{"uid":"93e1055e-3","name":"match.ts"},{"uid":"93e1055e-5","name":"redirect.ts"},{"uid":"93e1055e-7","name":"scroll.ts"},{"uid":"93e1055e-9","name":"types.ts"},{"uid":"93e1055e-11","name":"router.ts"},{"uid":"93e1055e-13","name":"components.tsx"},{"uid":"93e1055e-15","name":"not-found.ts"},{"uid":"93e1055e-17","name":"index.ts"}]}]}],"isRoot":true},"nodeParts":{"93e1055e-1":{"renderedLength":5692,"gzipLength":2467,"brotliLength":0,"metaUid":"93e1055e-0"},"93e1055e-3":{"renderedLength":16699,"gzipLength":5143,"brotliLength":0,"metaUid":"93e1055e-2"},"93e1055e-5":{"renderedLength":1966,"gzipLength":1043,"brotliLength":0,"metaUid":"93e1055e-4"},"93e1055e-7":{"renderedLength":2194,"gzipLength":899,"brotliLength":0,"metaUid":"93e1055e-6"},"93e1055e-9":{"renderedLength":385,"gzipLength":246,"brotliLength":0,"metaUid":"93e1055e-8"},"93e1055e-11":{"renderedLength":29175,"gzipLength":8093,"brotliLength":0,"metaUid":"93e1055e-10"},"93e1055e-13":{"renderedLength":10756,"gzipLength":3576,"brotliLength":0,"metaUid":"93e1055e-12"},"93e1055e-15":{"renderedLength":1315,"gzipLength":682,"brotliLength":0,"metaUid":"93e1055e-14"},"93e1055e-17":{"renderedLength":0,"gzipLength":0,"brotliLength":0,"metaUid":"93e1055e-16"}},"nodeMetas":{"93e1055e-0":{"id":"/src/loader.ts","moduleParts":{"index.js":"93e1055e-1"},"imported":[{"uid":"93e1055e-18"}],"importedBy":[{"uid":"93e1055e-16"},{"uid":"93e1055e-12"}]},"93e1055e-2":{"id":"/src/match.ts","moduleParts":{"index.js":"93e1055e-3"},"imported":[],"importedBy":[{"uid":"93e1055e-16"},{"uid":"93e1055e-12"},{"uid":"93e1055e-10"}]},"93e1055e-4":{"id":"/src/redirect.ts","moduleParts":{"index.js":"93e1055e-5"},"imported":[],"importedBy":[{"uid":"93e1055e-16"},{"uid":"93e1055e-10"}]},"93e1055e-6":{"id":"/src/scroll.ts","moduleParts":{"index.js":"93e1055e-7"},"imported":[],"importedBy":[{"uid":"93e1055e-10"}]},"93e1055e-8":{"id":"/src/types.ts","moduleParts":{"index.js":"93e1055e-9"},"imported":[],"importedBy":[{"uid":"93e1055e-16"},{"uid":"93e1055e-10"}]},"93e1055e-10":{"id":"/src/router.ts","moduleParts":{"index.js":"93e1055e-11"},"imported":[{"uid":"93e1055e-18"},{"uid":"93e1055e-19"},{"uid":"93e1055e-2"},{"uid":"93e1055e-4"},{"uid":"93e1055e-6"},{"uid":"93e1055e-8"}],"importedBy":[{"uid":"93e1055e-16"},{"uid":"93e1055e-12"}]},"93e1055e-12":{"id":"/src/components.tsx","moduleParts":{"index.js":"93e1055e-13"},"imported":[{"uid":"93e1055e-18"},{"uid":"93e1055e-19"},{"uid":"93e1055e-0"},{"uid":"93e1055e-2"},{"uid":"93e1055e-10"}],"importedBy":[{"uid":"93e1055e-16"}]},"93e1055e-14":{"id":"/src/not-found.ts","moduleParts":{"index.js":"93e1055e-15"},"imported":[{"uid":"93e1055e-18"}],"importedBy":[{"uid":"93e1055e-16"}]},"93e1055e-16":{"id":"/src/index.ts","moduleParts":{"index.js":"93e1055e-17"},"imported":[{"uid":"93e1055e-12"},{"uid":"93e1055e-14"},{"uid":"93e1055e-4"},{"uid":"93e1055e-0"},{"uid":"93e1055e-2"},{"uid":"93e1055e-10"},{"uid":"93e1055e-8"}],"importedBy":[],"isEntry":true},"93e1055e-18":{"id":"@pyreon/core","moduleParts":{},"imported":[],"importedBy":[{"uid":"93e1055e-12"},{"uid":"93e1055e-14"},{"uid":"93e1055e-0"},{"uid":"93e1055e-10"}]},"93e1055e-19":{"id":"@pyreon/reactivity","moduleParts":{},"imported":[],"importedBy":[{"uid":"93e1055e-12"},{"uid":"93e1055e-10"}]}},"env":{"rollup":"4.23.0"},"options":{"gzip":true,"brotli":false,"sourcemap":false}};
+    const data = {"version":2,"tree":{"name":"root","children":[{"name":"index.js","children":[{"name":"src","children":[{"uid":"86e1f850-1","name":"loader.ts"},{"uid":"86e1f850-3","name":"match.ts"},{"uid":"86e1f850-5","name":"redirect.ts"},{"uid":"86e1f850-7","name":"scroll.ts"},{"uid":"86e1f850-9","name":"types.ts"},{"uid":"86e1f850-11","name":"router.ts"},{"uid":"86e1f850-13","name":"components.tsx"},{"uid":"86e1f850-15","name":"not-found.ts"},{"uid":"86e1f850-17","name":"index.ts"}]}]}],"isRoot":true},"nodeParts":{"86e1f850-1":{"renderedLength":6146,"gzipLength":2628,"brotliLength":0,"metaUid":"86e1f850-0"},"86e1f850-3":{"renderedLength":16699,"gzipLength":5143,"brotliLength":0,"metaUid":"86e1f850-2"},"86e1f850-5":{"renderedLength":1966,"gzipLength":1043,"brotliLength":0,"metaUid":"86e1f850-4"},"86e1f850-7":{"renderedLength":2194,"gzipLength":899,"brotliLength":0,"metaUid":"86e1f850-6"},"86e1f850-9":{"renderedLength":439,"gzipLength":262,"brotliLength":0,"metaUid":"86e1f850-8"},"86e1f850-11":{"renderedLength":31150,"gzipLength":8783,"brotliLength":0,"metaUid":"86e1f850-10"},"86e1f850-13":{"renderedLength":10955,"gzipLength":3659,"brotliLength":0,"metaUid":"86e1f850-12"},"86e1f850-15":{"renderedLength":1315,"gzipLength":682,"brotliLength":0,"metaUid":"86e1f850-14"},"86e1f850-17":{"renderedLength":0,"gzipLength":0,"brotliLength":0,"metaUid":"86e1f850-16"}},"nodeMetas":{"86e1f850-0":{"id":"/src/loader.ts","moduleParts":{"index.js":"86e1f850-1"},"imported":[{"uid":"86e1f850-18"}],"importedBy":[{"uid":"86e1f850-16"},{"uid":"86e1f850-12"}]},"86e1f850-2":{"id":"/src/match.ts","moduleParts":{"index.js":"86e1f850-3"},"imported":[],"importedBy":[{"uid":"86e1f850-16"},{"uid":"86e1f850-12"},{"uid":"86e1f850-10"}]},"86e1f850-4":{"id":"/src/redirect.ts","moduleParts":{"index.js":"86e1f850-5"},"imported":[],"importedBy":[{"uid":"86e1f850-16"},{"uid":"86e1f850-10"}]},"86e1f850-6":{"id":"/src/scroll.ts","moduleParts":{"index.js":"86e1f850-7"},"imported":[],"importedBy":[{"uid":"86e1f850-10"}]},"86e1f850-8":{"id":"/src/types.ts","moduleParts":{"index.js":"86e1f850-9"},"imported":[],"importedBy":[{"uid":"86e1f850-16"},{"uid":"86e1f850-10"}]},"86e1f850-10":{"id":"/src/router.ts","moduleParts":{"index.js":"86e1f850-11"},"imported":[{"uid":"86e1f850-18"},{"uid":"86e1f850-19"},{"uid":"86e1f850-2"},{"uid":"86e1f850-4"},{"uid":"86e1f850-6"},{"uid":"86e1f850-8"}],"importedBy":[{"uid":"86e1f850-16"},{"uid":"86e1f850-12"}]},"86e1f850-12":{"id":"/src/components.tsx","moduleParts":{"index.js":"86e1f850-13"},"imported":[{"uid":"86e1f850-18"},{"uid":"86e1f850-19"},{"uid":"86e1f850-0"},{"uid":"86e1f850-2"},{"uid":"86e1f850-10"}],"importedBy":[{"uid":"86e1f850-16"}]},"86e1f850-14":{"id":"/src/not-found.ts","moduleParts":{"index.js":"86e1f850-15"},"imported":[{"uid":"86e1f850-18"}],"importedBy":[{"uid":"86e1f850-16"}]},"86e1f850-16":{"id":"/src/index.ts","moduleParts":{"index.js":"86e1f850-17"},"imported":[{"uid":"86e1f850-12"},{"uid":"86e1f850-14"},{"uid":"86e1f850-4"},{"uid":"86e1f850-0"},{"uid":"86e1f850-2"},{"uid":"86e1f850-10"},{"uid":"86e1f850-8"}],"importedBy":[],"isEntry":true},"86e1f850-18":{"id":"@pyreon/core","moduleParts":{},"imported":[],"importedBy":[{"uid":"86e1f850-12"},{"uid":"86e1f850-14"},{"uid":"86e1f850-0"},{"uid":"86e1f850-10"}]},"86e1f850-19":{"id":"@pyreon/reactivity","moduleParts":{},"imported":[],"importedBy":[{"uid":"86e1f850-12"},{"uid":"86e1f850-10"}]}},"env":{"rollup":"4.23.0"},"options":{"gzip":true,"brotli":false,"sourcemap":false}};
 
     const run = () => {
       const width = window.innerWidth;

package/lib/index.js

@@ -98,18 +98,25 @@ function serializeLoaderData(router) {
 * const tag = `<script>window.__PYREON_LOADER_DATA__=${json}<\/script>`
 */
 function stringifyLoaderData(loaderData) {
-	const seen = /* @__PURE__ */ new WeakSet();
-	const keyStack = [];
-	const replacer = (key, value) => {
-		if (key !== "") keyStack.push(key);
-		if (typeof value === "function" || typeof value === "symbol") return;
-		if (value && typeof value === "object") {
-			if (seen.has(value)) {
-				const path = keyStack.join(".") || "<root>";
-				throw new Error(`[Pyreon] Loader returned circular reference at "${path}". Loaders must return JSON-serializable data (no cycles, no functions, no Date/Map/Set without a custom replacer). Common cause: returning a Mongo/Prisma model with back-references intact.`);
-			}
-			seen.add(value);
+	const ancestors = /* @__PURE__ */ new Set();
+	const detectCycle = (value, path) => {
+		if (value === null || typeof value !== "object") return;
+		const v = typeof value.toJSON === "function" ? value.toJSON() : value;
+		if (v === null || typeof v !== "object") return;
+		const obj = v;
+		if (ancestors.has(obj)) throw new Error(`[Pyreon] Loader returned circular reference at "${path || "<root>"}". Loaders must return JSON-serializable data (no cycles, no functions, no Date/Map/Set without a custom replacer). Common cause: returning a Mongo/Prisma model with back-references intact.`);
+		ancestors.add(obj);
+		if (Array.isArray(obj)) for (let i = 0; i < obj.length; i++) detectCycle(obj[i], `${path}[${i}]`);
+		else for (const k of Object.keys(obj)) {
+			const child = obj[k];
+			if (typeof child === "function" || typeof child === "symbol") continue;
+			detectCycle(child, path ? `${path}.${k}` : k);
 		}
+		ancestors.delete(obj);
+	};
+	detectCycle(loaderData, "");
+	const replacer = (_key, value) => {
+		if (typeof value === "function" || typeof value === "symbol") return void 0;
 		return value;
 	};
 	return JSON.stringify(loaderData, replacer).replace(/<\//g, "<\\/");
@@ -809,7 +816,8 @@ function lazy(loader, options) {
 		[LAZY_SYMBOL]: true,
 		loader,
 		...options?.loading ? { loadingComponent: options.loading } : {},
-		...options?.error ? { errorComponent: options.error } : {}
+		...options?.error ? { errorComponent: options.error } : {},
+		...options?.hmrId ? { _hmrId: options.hmrId } : {}
 	};
 }
 function isLazy(c) {
@@ -1332,7 +1340,10 @@ function createRouter(options) {
 					loadingSignal.update((n) => n + 1);
 					loadingSignal.update((n) => n - 1);
 				}
-			}).catch(() => {});
+			}).catch((err) => {
+				if (__DEV__) console.warn(`[Pyreon Router] SWR background revalidation failed for "${r.path}" — serving stale data:`, err);
+				router._onError?.(err, to);
+			});
 		}
 	}
 	async function runLoaders(to, gen, ac) {
@@ -1355,7 +1366,7 @@ function createRouter(options) {
 			currentPath.set(path);
 			syncBrowserUrl(path, replace);
 			if (_isBrowser && to.meta.title) document.title = to.meta.title;
-			for (const record of router._loaderData.keys()) if (!to.matched.includes(record)) router._loaderData.delete(record);
+			for (const record of router._loaderData.keys()) if (!to.matched.includes(record) && !record.staleWhileRevalidate) router._loaderData.delete(record);
 		};
 		if (_isBrowser && to.meta.viewTransition !== false && typeof document.startViewTransition === "function") {
 			const vt = document.startViewTransition(() => {
@@ -1568,8 +1579,29 @@ function createRouter(options) {
 			router._abortController?.abort();
 			router._abortController = null;
 			if (_activeRouter === router) _activeRouter = null;
+			if (__DEV__ && _isBrowser) {
+				const g = globalThis;
+				if (g.__pyreon_hmr_swap__ === router._hmrSwap) delete g.__pyreon_hmr_swap__;
+			}
 		},
-		_resolve: (rawPath) => resolveRoute(rawPath, routes)
+		_resolve: (rawPath) => resolveRoute(rawPath, routes),
+		...__DEV__ && _isBrowser ? { _hmrSwap(id, mod) {
+			const m = mod;
+			const next = typeof m === "function" ? m : m?.default ?? void 0;
+			if (typeof next !== "function") return false;
+			const matched = currentRoute().matched;
+			let changed = false;
+			for (const record of matched) {
+				const raw = record.component;
+				if (!isLazy(raw) || !raw._hmrId) continue;
+				if (!_hmrIdMatches(raw._hmrId, id)) continue;
+				componentCache.set(record, next);
+				router._erroredChunks.delete(record);
+				changed = true;
+			}
+			if (changed) loadingSignal.update((n) => n + 1);
+			return changed;
+		} } : {}
 	};
 	queueMicrotask(() => {
 		if (router._readyResolve) {
@@ -1577,8 +1609,26 @@ function createRouter(options) {
 			router._readyResolve = null;
 		}
 	});
+	if (__DEV__ && _isBrowser && router._hmrSwap) globalThis.__pyreon_hmr_swap__ = router._hmrSwap;
 	return router;
 }
+/**
+* Match a lazy route's `_hmrId` (emitted by `@pyreon/zero`'s fs-router as the
+* absolute route-file path) against the module id `@pyreon/vite-plugin`'s
+* accept handler reports. Both are absolute paths to the same file but may
+* differ in query suffix (`?t=…`, `?v=…`) or, in some Vite setups, a `/@fs`
+* prefix. Strip queries, then accept exact equality OR a suffix match on the
+* longer path — route-file paths are unique within an app so suffix matching
+* can't cross-fire. A miss makes `_hmrSwap` return false → the plugin falls
+* back to an automatic reload (correct, just not in-place), so a too-strict
+* match degrades safely rather than swapping the wrong component.
+*/
+function _hmrIdMatches(recordId, incomingId) {
+	const a = recordId.split("?")[0] ?? recordId;
+	const b = incomingId.split("?")[0] ?? incomingId;
+	if (a === b) return true;
+	return a.length >= b.length ? a.endsWith(b) : b.endsWith(a);
+}
 async function runGuard(guard, to, from) {
 	try {
 		return await guard(to, from);
@@ -1779,13 +1829,18 @@ const RouterLink = (props) => {
 	const ariaCurrent = () => isExactMatch() ? "page" : void 0;
 	const ref = createRef();
 	if (prefetchMode === "viewport" && router && typeof IntersectionObserver !== "undefined") {
+		const ric = globalThis.requestIdleCallback;
+		const scheduleIdle = (fn) => {
+			if (typeof ric === "function") ric(fn);
+			else setTimeout(fn, 1);
+		};
 		const observer = new IntersectionObserver((entries) => {
 			for (const entry of entries) if (entry.isIntersecting) {
-				prefetchRoute(router, props.to);
 				observer.disconnect();
+				scheduleIdle(() => prefetchRoute(router, props.to));
 				break;
 			}
-		});
+		}, { rootMargin: "200px" });
 		queueMicrotask(() => {
 			observer.observe(ref.current);
 		});

package/lib/types/index.d.ts

@@ -76,12 +76,24 @@ interface LazyComponent {
   readonly loadingComponent?: ComponentFn$1;
   /** Optional component shown after all retries have failed */
   readonly errorComponent?: ComponentFn$1;
+  /**
+   * Dev-only module id, emitted by `@pyreon/zero`'s fs-router codegen as
+   * `lazy(() => import("/abs/X"), { hmrId: "/abs/X" })`. The HMR coordinator
+   * keys the active route's matched records by this id so a hot-updated
+   * module can be swapped IN PLACE (no page reload) using the fresh module
+   * Vite hands the `import.meta.hot.accept` callback — sidestepping the
+   * stale-`?t=` problem where re-running the dynamic-import thunk inside a
+   * non-invalidated virtual routes module would return the OLD module.
+   * Inert in production (no coordinator is registered when not in dev).
+   */
+  readonly _hmrId?: string;
 }
 declare function lazy(loader: () => Promise<ComponentFn$1 | {
   default: ComponentFn$1;
 }>, options?: {
   loading?: ComponentFn$1;
   error?: ComponentFn$1;
+  hmrId?: string;
 }): LazyComponent;
 type RouteComponent = ComponentFn$1 | LazyComponent;
 type NavigationGuardResult = boolean | string | undefined;
@@ -409,6 +421,28 @@ interface RouterInstance extends Router {
     promise: Promise<unknown>;
     signal: AbortSignal;
   }>;
+  /**
+   * Dev-only HMR coordinator. Given a hot-updated module's id and the FRESH
+   * module namespace Vite handed `import.meta.hot.accept`, swaps the new
+   * component into every matched record whose lazy `_hmrId` equals `id`,
+   * then bumps `_loadingSignal` so `RouterView` re-renders ONLY that subtree
+   * in place — no page reload, so `__pyreon_hmr_registry__` (module-scope
+   * signal values) survives and `__hmr_signal` restores them.
+   *
+   * Using the namespace Vite passed (not a re-run of the lazy thunk)
+   * sidesteps the stale-`?t=` trap: the dynamic-import thunk lives in the
+   * virtual routes module, which is NOT invalidated when a leaf route
+   * self-accepts, so re-importing it would return the OLD module.
+   *
+   * Returns `true` when at least one matched component was swapped. `false`
+   * tells `@pyreon/vite-plugin`'s accept handler the edit was outside the
+   * active route tree (a nested non-route component, an unrelated route, a
+   * signal-only module) so it falls back to `import.meta.hot.invalidate()`
+   * → an automatic full reload (no manual refresh either way).
+   *
+   * Present only when the router is created in a dev browser context.
+   */
+  _hmrSwap?: (id: string, mod: unknown) => boolean;
 }
 //#endregion
 //#region src/components.d.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/router",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Official router for Pyreon",
   "homepage": "https://github.com/pyreon/pyreon/tree/main/packages/router#readme",
   "bugs": {
@@ -44,14 +44,14 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@pyreon/core": "^0.18.0",
-    "@pyreon/reactivity": "^0.18.0",
-    "@pyreon/runtime-dom": "^0.18.0"
+    "@pyreon/core": "^0.19.0",
+    "@pyreon/reactivity": "^0.19.0",
+    "@pyreon/runtime-dom": "^0.19.0"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.8.9",
     "@pyreon/manifest": "0.13.1",
-    "@pyreon/test-utils": "^0.13.5",
+    "@pyreon/test-utils": "^0.13.6",
     "@vitest/browser-playwright": "^4.1.4",
     "happy-dom": "^20.8.3"
   }

package/src/components.tsx

@@ -275,18 +275,46 @@ export const RouterLink: ComponentFn<RouterLinkProps> = (props) => {
 
   const ariaCurrent = (): string | undefined => isExactMatch() ? 'page' : undefined
 
-  // Viewport prefetching — observe link visibility with IntersectionObserver
+  // Viewport prefetching — observe link visibility with IntersectionObserver.
+  //
+  // Two refinements over the naive "fire prefetch the instant the link
+  // intersects" shape:
+  //
+  //   1. `rootMargin: '200px'` — start the prefetch BEFORE the link is
+  //      fully on screen. By the time the user scrolls to it and clicks,
+  //      the loader data is typically already resolved. Matches the
+  //      margin instant.page / Astro use; 0px (the previous default)
+  //      only started the fetch once the link was already visible,
+  //      leaving a window where a fast scroll-then-click still waited.
+  //   2. Schedule the prefetch via `requestIdleCallback` so it never
+  //      contends with active scrolling / paint. Prefetch is best-effort
+  //      background work — running it in an idle slice keeps the main
+  //      thread free for the scroll the user is actively performing.
+  //      Falls back to a 1ms `setTimeout` where rIC is unavailable
+  //      (Safari < 16.4, jsdom) so the behaviour degrades, not breaks.
   const ref = createRef<Element>()
   if (prefetchMode === 'viewport' && router && typeof IntersectionObserver !== 'undefined') {
-    const observer = new IntersectionObserver((entries) => {
-      for (const entry of entries) {
-        if (entry.isIntersecting) {
-          prefetchRoute(router as RouterInstance, props.to)
-          observer.disconnect()
-          break
+    const ric = (
+      globalThis as { requestIdleCallback?: (cb: () => void) => number }
+    ).requestIdleCallback
+    const scheduleIdle = (fn: () => void): void => {
+      if (typeof ric === 'function') ric(fn)
+      else setTimeout(fn, 1)
+    }
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (entry.isIntersecting) {
+            // Disconnect synchronously so a re-intersection (scroll
+            // jitter) before the idle callback runs can't double-schedule.
+            observer.disconnect()
+            scheduleIdle(() => prefetchRoute(router as RouterInstance, props.to))
+            break
+          }
         }
-      }
-    })
+      },
+      { rootMargin: '200px' },
+    )
     // Observe after mount — the ref will be populated once the element is in the DOM
     queueMicrotask(() => {
       observer.observe(ref.current as Element)

package/src/loader.ts

@@ -118,30 +118,56 @@ export function serializeLoaderData(router: RouterInstance): Record<string, unkn
  * const tag = `<script>window.__PYREON_LOADER_DATA__=${json}</script>`
  */
 export function stringifyLoaderData(loaderData: Record<string, unknown>): string {
-  const seen = new WeakSet<object>()
-  const keyStack: string[] = []
-  const replacer = (key: string, value: unknown): unknown => {
-    // JSON.stringify calls the replacer with key = '' for the root, then
-    // the property name for each subsequent member. Track the path so the
-    // circular-ref error message names the offending route key.
-    if (key !== '') keyStack.push(key)
-    if (typeof value === 'function' || typeof value === 'symbol') {
-      // Drop silently. JSON.stringify already drops these as VALUES, but
-      // an explicit drop also handles array entries (where it'd convert
-      // to null otherwise — undesirable for downstream typed hydration).
-      return undefined
+  // True cycle detection: track the ANCESTOR PATH only (add on descend,
+  // remove on ascend), NOT every object ever visited. The prior
+  // implementation kept an all-seen WeakSet that was never pruned, so any
+  // object referenced more than once — a DAG, not a cycle — falsely threw
+  // "circular reference" and 500'd the SSR response. Shared references are
+  // extremely common in loader payloads (`{ author: user, lastEditor: user }`
+  // where both are the same ORM instance; a list whose rows share a lookup
+  // object). `JSON.stringify` serializes those fine; only a real cycle must
+  // throw. A `JSON.stringify` replacer has no "leave" hook, so cycle
+  // detection runs as a single recursive pre-pass that maintains the
+  // ancestor set, then `JSON.stringify` does the (now cycle-free) encode.
+  const ancestors = new Set<object>()
+  const detectCycle = (value: unknown, path: string): void => {
+    if (value === null || typeof value !== 'object') return
+    // Respect `toJSON` so detection matches what JSON.stringify actually
+    // serializes (Date/etc. become primitives — no cycle through them).
+    const v =
+      typeof (value as { toJSON?: unknown }).toJSON === 'function'
+        ? (value as { toJSON: () => unknown }).toJSON()
+        : value
+    if (v === null || typeof v !== 'object') return
+    const obj = v as object
+    if (ancestors.has(obj)) {
+      throw new Error(
+        `[Pyreon] Loader returned circular reference at "${path || '<root>'}". ` +
+          `Loaders must return JSON-serializable data (no cycles, no functions, no Date/Map/Set without a custom replacer). ` +
+          `Common cause: returning a Mongo/Prisma model with back-references intact.`,
+      )
     }
-    if (value && typeof value === 'object') {
-      if (seen.has(value as object)) {
-        const path = keyStack.join('.') || '<root>'
-        throw new Error(
-          `[Pyreon] Loader returned circular reference at "${path}". ` +
-            `Loaders must return JSON-serializable data (no cycles, no functions, no Date/Map/Set without a custom replacer). ` +
-            `Common cause: returning a Mongo/Prisma model with back-references intact.`,
-        )
+    ancestors.add(obj)
+    if (Array.isArray(obj)) {
+      for (let i = 0; i < obj.length; i++) detectCycle(obj[i], `${path}[${i}]`)
+    } else {
+      for (const k of Object.keys(obj)) {
+        const child = (obj as Record<string, unknown>)[k]
+        // Mirror the encode-time drop: function/symbol values are not
+        // serialized, so a cycle reachable only THROUGH one can't occur.
+        if (typeof child === 'function' || typeof child === 'symbol') continue
+        detectCycle(child, path ? `${path}.${k}` : k)
       }
-      seen.add(value as object)
     }
+    ancestors.delete(obj) // ascend — siblings / shared refs are NOT cycles
+  }
+  detectCycle(loaderData, '')
+
+  const replacer = (_key: string, value: unknown): unknown => {
+    // Drop silently. JSON.stringify already drops these as VALUES, but an
+    // explicit drop also handles array entries (where it'd convert to null
+    // otherwise — undesirable for downstream typed hydration).
+    if (typeof value === 'function' || typeof value === 'symbol') return undefined
     return value
   }
   return JSON.stringify(loaderData, replacer).replace(/<\//g, '<\\/')

package/src/manifest.ts

@@ -48,7 +48,7 @@ const User = () => {
   const data = useLoaderData<UserData>()
   const router = useRouter()
   const isAdmin = useIsActive("/admin")
-  const { isTransitioning } = useTransition()
+  const isTransitioning = useTransition()
   const params = useTypedSearchParams({ tab: "string", page: "number" })
 
   return (
@@ -214,10 +214,10 @@ params.set({ page: 2 })  // updates URL`,
     {
       name: 'useTransition',
       kind: 'hook',
-      signature: 'useTransition(): { isTransitioning: () => boolean }',
+      signature: 'useTransition(): () => boolean',
       summary:
-        'Reactive signal for route transition state. `isTransitioning()` is true during navigation (while guards run + loaders resolve), false when the new route is mounted. Useful for progress bars and global loading indicators.',
-      example: `const { isTransitioning } = useTransition()
+        'Returns a reactive accessor for route transition state. The accessor is true during navigation (while guards run + loaders resolve), false when the new route is mounted. Call it inside a reactive scope. Useful for progress bars and global loading indicators.',
+      example: `const isTransitioning = useTransition()
 
 <Show when={isTransitioning()}>
   <ProgressBar />
@@ -227,17 +227,17 @@ params.set({ page: 2 })  // updates URL`,
     {
       name: 'useMiddlewareData',
       kind: 'hook',
-      signature: 'useMiddlewareData<T>(): T',
+      signature: 'useMiddlewareData(): () => Record<string, unknown>',
       summary:
-        'Read data set by `RouteMiddleware` in the middleware chain. Middleware functions receive `ctx` with a mutable `ctx.data` object — properties set there are available to all downstream components via this hook.',
+        'Returns a reactive accessor for data set by `RouteMiddleware` in the middleware chain. Middleware functions receive `ctx` with a mutable `ctx.data` object — properties set there are read by calling the returned accessor inside a reactive scope.',
       example: `// Middleware:
 const authMiddleware: RouteMiddleware = async (ctx) => {
   ctx.data.user = await getUser(ctx.to)
 }
 
 // Component:
-const data = useMiddlewareData<{ user: User }>()
-// data.user is available`,
+const data = useMiddlewareData()
+// data().user is available`,
       seeAlso: ['createRouter', 'useLoaderData'],
     },
     {

package/src/router.ts

@@ -754,8 +754,27 @@ export function createRouter<TNames extends string = string>(
             loadingSignal.update((n) => n - 1)
           }
         })
-        .catch(() => {
-          /* Background revalidation failure — stale data remains valid */
+        .catch((err: unknown) => {
+          // Background revalidation failed — the stale data remains valid
+          // and on screen, so this MUST NOT cancel/redirect the (already
+          // settled) navigation. But an empty catch is the silent-failure
+          // anti-pattern the project forbids: a persistently-failing
+          // revalidation loader (auth expiry, API outage, a bug thrown in
+          // the loader) produces ZERO signal — the developer sees
+          // permanently-stale data with nothing pointing at the cause.
+          // Surface it like every other loader error (dev warn + the
+          // user-supplied onError hook) WITHOUT acting on the return
+          // value. This path was dead code until the SWR prune fix
+          // (#617) made `revalidateSwrLoaders` actually run for the
+          // nav-away/back case.
+          if (__DEV__) {
+            // oxlint-disable-next-line no-console
+            console.warn(
+              `[Pyreon Router] SWR background revalidation failed for "${r.path}" — serving stale data:`,
+              err,
+            )
+          }
+          router._onError?.(err, to)
         })
     }
   }
@@ -802,8 +821,20 @@ export function createRouter<TNames extends string = string>(
         document.title = to.meta.title
       }
 
+      // Drop loader data for routes no longer matched — EXCEPT
+      // `staleWhileRevalidate` routes. SWR's entire contract is "on
+      // return to this route, serve the previously-loaded data stale
+      // while revalidating in the background"; that requires the data to
+      // SURVIVE navigating away. Pruning it here (the pre-fix behaviour)
+      // meant `runLoaders`' `_loaderData.has(r)` gate was always false on
+      // return, so `revalidateSwrLoaders` never ran and every visit went
+      // through the blocking path — `staleWhileRevalidate` was a no-op
+      // for the realistic nav-away/back case. Retained SWR data is
+      // bounded by the number of SWR route RECORDS (a developer-declared
+      // set; param routes share one record), and per-key freshness/LRU
+      // is still handled by `_loaderCache`.
       for (const record of router._loaderData.keys()) {
-        if (!to.matched.includes(record)) {
+        if (!to.matched.includes(record) && !record.staleWhileRevalidate) {
           router._loaderData.delete(record)
         }
       }
@@ -1193,9 +1224,48 @@ export function createRouter<TNames extends string = string>(
       router._abortController = null
       // Clear global ref so stale router doesn't survive in SSR or re-creation
       if (_activeRouter === router) _activeRouter = null
+      if (__DEV__ && _isBrowser) {
+        const g = globalThis as Record<string, unknown>
+        if (g.__pyreon_hmr_swap__ === router._hmrSwap) {
+          delete g.__pyreon_hmr_swap__
+        }
+      }
     },
 
     _resolve: (rawPath: string) => resolveRoute(rawPath, routes),
+
+    // Dev-only HMR coordinator — see RouterInstance._hmrSwap JSDoc.
+    // Gated to dev+browser so it's tree-shaken from production bundles.
+    ...(__DEV__ && _isBrowser
+      ? {
+          _hmrSwap(id: string, mod: unknown): boolean {
+            const m = mod as { default?: ComponentFn } | ComponentFn | null
+            const next: ComponentFn | undefined =
+              typeof m === 'function' ? m : (m?.default ?? undefined)
+            // No default export in the fresh namespace (named-only edit, or
+            // the module no longer exports a component) — let the plugin
+            // fall back to an automatic reload rather than blank the route.
+            if (typeof next !== 'function') return false
+
+            const matched = currentRoute().matched
+            let changed = false
+            for (const record of matched) {
+              const raw = record.component
+              if (!isLazy(raw) || !raw._hmrId) continue
+              if (!_hmrIdMatches(raw._hmrId, id)) continue
+              componentCache.set(record, next)
+              router._erroredChunks.delete(record)
+              changed = true
+            }
+            // Bump `_loadingSignal` so `RouterView`'s `depthEntry` computed
+            // re-emits; its `equals` compares `comp` identity, so only the
+            // depth whose component actually changed re-renders — every
+            // other depth (layout, siblings) stays mounted, signals intact.
+            if (changed) loadingSignal.update((n) => n + 1)
+            return changed
+          },
+        }
+      : {}),
   }
 
   // Initial route is resolved synchronously — mark ready on next microtask
@@ -1207,11 +1277,42 @@ export function createRouter<TNames extends string = string>(
     }
   })
 
+  // Expose the HMR coordinator on globalThis so `@pyreon/vite-plugin`'s
+  // injected `import.meta.hot.accept` handler can reach it WITHOUT importing
+  // `@pyreon/router` (zero import coupling — same pattern as the perf-harness
+  // counter sink). Last router wins; single-router apps (the norm, every
+  // `@pyreon/zero` app) are unaffected. Dev+browser only.
+  if (__DEV__ && _isBrowser && router._hmrSwap) {
+    // `_hmrSwap` closes over `currentRoute`/`componentCache`/`loadingSignal`
+    // (not `this`), so the raw reference is safe to expose and to compare by
+    // identity on `destroy()`.
+    ;(globalThis as Record<string, unknown>).__pyreon_hmr_swap__ =
+      router._hmrSwap
+  }
+
   return router as unknown as Router<TNames>
 }
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 
+/**
+ * Match a lazy route's `_hmrId` (emitted by `@pyreon/zero`'s fs-router as the
+ * absolute route-file path) against the module id `@pyreon/vite-plugin`'s
+ * accept handler reports. Both are absolute paths to the same file but may
+ * differ in query suffix (`?t=…`, `?v=…`) or, in some Vite setups, a `/@fs`
+ * prefix. Strip queries, then accept exact equality OR a suffix match on the
+ * longer path — route-file paths are unique within an app so suffix matching
+ * can't cross-fire. A miss makes `_hmrSwap` return false → the plugin falls
+ * back to an automatic reload (correct, just not in-place), so a too-strict
+ * match degrades safely rather than swapping the wrong component.
+ */
+function _hmrIdMatches(recordId: string, incomingId: string): boolean {
+  const a = recordId.split('?')[0] ?? recordId
+  const b = incomingId.split('?')[0] ?? incomingId
+  if (a === b) return true
+  return a.length >= b.length ? a.endsWith(b) : b.endsWith(a)
+}
+
 async function runGuard(
   guard: NavigationGuard,
   to: ResolvedRoute,

package/src/tests/loader.test.ts

@@ -184,20 +184,44 @@ describe('stringifyLoaderData (M2.2)', () => {
     })
   })
 
-  test('handles deeply-nested data without falsely flagging shared references as cycles', () => {
-    // A non-cyclic shared reference (two keys pointing at the same array)
-    // SHOULD throw — JSON serialization can't represent shared identity
-    // without `references`, and a runtime cycle-detector treating shared
-    // refs as cycles is the safe default for hydration semantics. Verify
-    // the throw shape — if this becomes too aggressive, relax with a
-    // post-visit drop instead of WeakSet.
+  test('shared (DAG) references serialize — only true cycles throw', () => {
+    // BEHAVIOUR CHANGE (intentional, bug fix). Previously the all-seen
+    // WeakSet threw "circular reference" on ANY object visited twice — a
+    // shared reference (DAG), not a cycle. That 500'd the SSR response for
+    // extremely common loader payloads (an ORM returning the same instance
+    // twice). The original code's own comment anticipated this remedy:
+    // "if this becomes too aggressive, relax with a post-visit drop
+    // instead of WeakSet" — which is exactly what ancestor-path detection
+    // does. Strictly more permissive: inputs that throw before now succeed;
+    // inputs that worked are unchanged; real cycles still throw.
     const shared = [1, 2, 3]
-    expect(() =>
-      stringifyLoaderData({
-        '/a': shared,
-        '/b': shared,
-      }),
-    ).toThrow(/circular reference/)
+    const json = stringifyLoaderData({ '/a': shared, '/b': shared })
+    expect(JSON.parse(json)).toEqual({ '/a': [1, 2, 3], '/b': [1, 2, 3] })
+
+    // Canonical real-world shape: one user object referenced twice.
+    const user = { id: 7, name: 'Ada' }
+    const post = stringifyLoaderData({ '/posts/1': { author: user, lastEditor: user } })
+    expect(JSON.parse(post)).toEqual({
+      '/posts/1': { author: { id: 7, name: 'Ada' }, lastEditor: { id: 7, name: 'Ada' } },
+    })
+
+    // Diamond: same node reachable via two paths, no cycle.
+    const leaf = { v: 1 }
+    const diamond = stringifyLoaderData({ '/d': { left: { leaf }, right: { leaf } } })
+    expect(JSON.parse(diamond)).toEqual({ '/d': { left: { leaf: { v: 1 } }, right: { leaf: { v: 1 } } } })
+  })
+
+  test('still throws on a true cycle through a shared-looking path', () => {
+    // A shared ref that ALSO closes a cycle must still throw.
+    interface N {
+      id: number
+      next?: N
+    }
+    const a: N = { id: 1 }
+    const b: N = { id: 2 }
+    a.next = b
+    b.next = a // real cycle
+    expect(() => stringifyLoaderData({ '/x': { a, b } })).toThrow(/\[Pyreon\] Loader returned circular reference/)
   })
 
   test('empty record produces empty object JSON', () => {
@@ -587,25 +611,117 @@ describe('router — staleWhileRevalidate', () => {
         staleWhileRevalidate: true,
         loader: async () => {
           loaderCallCount++
-          return `data-v${loaderCallCount}`
+          const v = loaderCallCount
+          // The revalidation call (2nd) takes REAL async time so the
+          // stale window is deterministic, not microtask-races. The
+          // first (blocking) call resolves immediately.
+          if (v >= 2) await new Promise<void>((r) => setTimeout(r, 40))
+          return `data-v${v}`
         },
       },
     ]
+    const swrRecord = routes[1] as RouteRecord
     const router = createRouter({ routes, url: '/' }) as RouterInstance
 
     // First navigation — loader runs as blocking
     await router.push('/data')
     expect(loaderCallCount).toBe(1)
-    expect(router._loaderData.get(routes[1] as RouteRecord)).toBe('data-v1')
+    expect(router._loaderData.get(swrRecord)).toBe('data-v1')
 
-    // Navigate away and back — should show stale data and revalidate
+    // Navigate AWAY, then BACK. The away nav must NOT prune the SWR
+    // route's loader data (that was the bug — see the regression note
+    // below); on return the SWR fast-path must serve the STALE value
+    // immediately and revalidate in the BACKGROUND.
     await router.push('/')
     await router.push('/data')
 
-    // Give background revalidation time
-    await new Promise<void>((r) => setTimeout(r, 50))
+    // SWR discriminator (load-bearing): the return navigation resolves
+    // WITHOUT blocking on the (40ms) loader — the served data is still
+    // STALE `data-v1`, revalidation pending. Pre-fix this navigation
+    // went through the BLOCKING path (the prune wiped the entry), so
+    // `await push('/data')` would have awaited the loader and the data
+    // here would already be `data-v2`.
+    expect(router._loaderData.get(swrRecord)).toBe('data-v1')
+
+    // Background revalidation then completes and swaps in fresh data.
+    await new Promise<void>((r) => setTimeout(r, 80))
+    expect(loaderCallCount).toBe(2)
+    expect(router._loaderData.get(swrRecord)).toBe('data-v2')
+  })
+
+  test('a failing background revalidation surfaces via onError without cancelling or clobbering', async () => {
+    // This path only became testable after #617 made the SWR branch
+    // actually run (the prune previously made `revalidateSwrLoaders`
+    // dead code — the reason an earlier attempt at this fix shipped
+    // WITHOUT a test and was reverted). With SWR live, an empty `.catch`
+    // is the silent-failure anti-pattern: a persistently-failing
+    // revalidation gives the developer zero signal. Contract: the error
+    // is surfaced via `onError` exactly once; the (already-settled)
+    // navigation is NOT cancelled; the failed revalidation does NOT
+    // clobber the stale data (it stays valid + on screen).
+    let loaderCallCount = 0
+    const onError = vi.fn<(err: unknown, route: unknown) => undefined | false>(() => undefined)
+    const routes: RouteRecord[] = [
+      { path: '/', component: Home },
+      {
+        path: '/data',
+        component: About,
+        staleWhileRevalidate: true,
+        loader: async () => {
+          loaderCallCount++
+          const v = loaderCallCount
+          if (v >= 2) {
+            // Real async delay so the rejection is genuinely a
+            // background failure (deterministic, not a microtask race).
+            await new Promise<void>((r) => setTimeout(r, 40))
+            throw new Error('revalidation upstream 503')
+          }
+          return `data-v${v}`
+        },
+      },
+    ]
+    const swrRecord = routes[1] as RouteRecord
+    const router = createRouter({ routes, url: '/', onError }) as RouterInstance
+
+    await router.push('/data') // blocking — primes stale data-v1
+    expect(router._loaderData.get(swrRecord)).toBe('data-v1')
+
+    await router.push('/') // nav away (SWR data survives — #617)
+    await router.push('/data') // SWR: stale served, revalidate in bg
+
+    // Returned on STALE data without blocking; revalidation not failed yet.
+    expect(router.currentRoute().path).toBe('/data')
+    expect(router._loaderData.get(swrRecord)).toBe('data-v1')
+    expect(onError).not.toHaveBeenCalled()
+
+    await new Promise<void>((r) => setTimeout(r, 90)) // revalidation rejects
+
     expect(loaderCallCount).toBe(2)
+    // The previously-empty `.catch` swallowed this entirely. Contract:
+    expect(onError).toHaveBeenCalledTimes(1)
+    expect(onError.mock.calls[0]?.[0]).toBeInstanceOf(Error)
+    expect((onError.mock.calls[0]?.[0] as Error).message).toBe('revalidation upstream 503')
+    // Navigation was NOT cancelled, and the stale value was NOT clobbered
+    // by the failed revalidation — it stays valid and on screen.
+    expect(router.currentRoute().path).toBe('/data')
+    expect(router._loaderData.get(swrRecord)).toBe('data-v1')
   })
+
+  // REGRESSION NOTE (fixed in this PR). `staleWhileRevalidate` was
+  // effectively a no-op for the realistic nav-away/back case:
+  // `commitNavigation`'s `doCommit` pruned `_loaderData` for every
+  // record not in the NEW matched chain on every navigation, so
+  // navigating away deleted the SWR route's data and `runLoaders`'
+  // `r.staleWhileRevalidate && _loaderData.has(r)` gate was always false
+  // on return — `revalidateSwrLoaders` never ran; every visit went
+  // through the blocking path. (NB: the earlier hypothesis that
+  // `resolveRoute` returns fresh `RouteRecord` objects was WRONG —
+  // identity is stable; the prune was the sole cause, proven by an
+  // instrumented probe showing SWR fires correctly for `/data → /data`
+  // with no nav-away but not for `/data → / → /data`.) Fix: the prune
+  // skips `staleWhileRevalidate` records so their data survives
+  // navigating away. The strengthened test above is the regression
+  // guard — its stale-window assertion fails on the pre-fix prune.
 })
 
 describe('router.preload', () => {

package/src/tests/manifest-snapshot.test.ts

@@ -57,7 +57,7 @@ describe('gen-docs — router snapshot', () => {
         const data = useLoaderData<UserData>()
         const router = useRouter()
         const isAdmin = useIsActive("/admin")
-        const { isTransitioning } = useTransition()
+        const isTransitioning = useTransition()
         const params = useTypedSearchParams({ tab: "string", page: "number" })
 
         return (

package/src/tests/router.test.ts

@@ -2531,6 +2531,96 @@ describe('RouterLink viewport prefetch', () => {
 
     globalThis.IntersectionObserver = origIO
   })
+
+  // Regression — the viewport-prefetch polish (PR: prefetch DX):
+  //   (a) IntersectionObserver is constructed with rootMargin '200px' so
+  //       the prefetch starts BEFORE the link is fully on screen.
+  //   (b) The prefetch is scheduled via requestIdleCallback, NOT called
+  //       synchronously inside the observer callback — so it never
+  //       contends with the scroll the user is actively performing.
+  test('viewport prefetch uses 200px rootMargin + idle scheduling', async () => {
+    const el = container()
+    let loaderCalled = false
+    const prefetchRoutes: RouteRecord[] = [
+      { path: '/', component: Home },
+      {
+        path: '/idle',
+        component: About,
+        loader: async () => {
+          loaderCalled = true
+          return 'data'
+        },
+      },
+    ]
+    const router = createRouter({ routes: prefetchRoutes, url: '/' })
+
+    const origIO = globalThis.IntersectionObserver
+    const origRic = (globalThis as { requestIdleCallback?: unknown }).requestIdleCallback
+    let capturedRootMargin: string | undefined
+    let idleCb: (() => void) | null = null
+    ;(globalThis as { requestIdleCallback?: unknown }).requestIdleCallback = (
+      cb: () => void,
+    ): number => {
+      idleCb = cb
+      return 1
+    }
+    globalThis.IntersectionObserver = class {
+      constructor(
+        private cb: IntersectionObserverCallback,
+        opts?: IntersectionObserverInit,
+      ) {
+        capturedRootMargin = opts?.rootMargin
+      }
+      observe(observedEl: Element) {
+        this.cb(
+          [{ isIntersecting: true, target: observedEl } as IntersectionObserverEntry],
+          this as unknown as IntersectionObserver,
+        )
+      }
+      disconnect() {}
+      unobserve() {}
+      takeRecords() {
+        return []
+      }
+      get root() {
+        return null
+      }
+      get rootMargin() {
+        return ''
+      }
+      get thresholds() {
+        return []
+      }
+    } as unknown as typeof IntersectionObserver
+
+    mount(
+      h(
+        RouterProvider,
+        { router },
+        h(RouterLink, { to: '/idle', prefetch: 'viewport' }, 'Idle'),
+      ),
+      el,
+    )
+
+    await new Promise<void>((r) => setTimeout(r, 50))
+
+    // (a) Constructed with the 200px margin.
+    expect(capturedRootMargin).toBe('200px')
+    // (b) The prefetch was DEFERRED to the idle callback — it must NOT
+    //     have run synchronously inside the observer callback.
+    expect(idleCb).not.toBeNull()
+    expect(loaderCalled).toBe(false)
+
+    // Fire the idle slice — now the prefetch runs.
+    idleCb!()
+    await new Promise<void>((r) => setTimeout(r, 50))
+    expect(loaderCalled).toBe(true)
+
+    globalThis.IntersectionObserver = origIO
+    if (origRic === undefined)
+      delete (globalThis as { requestIdleCallback?: unknown }).requestIdleCallback
+    else (globalThis as { requestIdleCallback?: unknown }).requestIdleCallback = origRic
+  })
 })
 
 // ─── matchPath additional branches (match.ts) ────────────────────────────────

package/src/types.ts

@@ -100,17 +100,29 @@ export interface LazyComponent {
   readonly loadingComponent?: ComponentFn
   /** Optional component shown after all retries have failed */
   readonly errorComponent?: ComponentFn
+  /**
+   * Dev-only module id, emitted by `@pyreon/zero`'s fs-router codegen as
+   * `lazy(() => import("/abs/X"), { hmrId: "/abs/X" })`. The HMR coordinator
+   * keys the active route's matched records by this id so a hot-updated
+   * module can be swapped IN PLACE (no page reload) using the fresh module
+   * Vite hands the `import.meta.hot.accept` callback — sidestepping the
+   * stale-`?t=` problem where re-running the dynamic-import thunk inside a
+   * non-invalidated virtual routes module would return the OLD module.
+   * Inert in production (no coordinator is registered when not in dev).
+   */
+  readonly _hmrId?: string
 }
 
 export function lazy(
   loader: () => Promise<ComponentFn | { default: ComponentFn }>,
-  options?: { loading?: ComponentFn; error?: ComponentFn },
+  options?: { loading?: ComponentFn; error?: ComponentFn; hmrId?: string },
 ): LazyComponent {
   return {
     [LAZY_SYMBOL]: true,
     loader,
     ...(options?.loading ? { loadingComponent: options.loading } : {}),
     ...(options?.error ? { errorComponent: options.error } : {}),
+    ...(options?.hmrId ? { _hmrId: options.hmrId } : {}),
   }
 }
 
@@ -480,4 +492,26 @@ export interface RouterInstance extends Router {
    * nav-1's aborted fetch).
    */
   _loaderInflight: Map<string, { promise: Promise<unknown>; signal: AbortSignal }>
+  /**
+   * Dev-only HMR coordinator. Given a hot-updated module's id and the FRESH
+   * module namespace Vite handed `import.meta.hot.accept`, swaps the new
+   * component into every matched record whose lazy `_hmrId` equals `id`,
+   * then bumps `_loadingSignal` so `RouterView` re-renders ONLY that subtree
+   * in place — no page reload, so `__pyreon_hmr_registry__` (module-scope
+   * signal values) survives and `__hmr_signal` restores them.
+   *
+   * Using the namespace Vite passed (not a re-run of the lazy thunk)
+   * sidesteps the stale-`?t=` trap: the dynamic-import thunk lives in the
+   * virtual routes module, which is NOT invalidated when a leaf route
+   * self-accepts, so re-importing it would return the OLD module.
+   *
+   * Returns `true` when at least one matched component was swapped. `false`
+   * tells `@pyreon/vite-plugin`'s accept handler the edit was outside the
+   * active route tree (a nested non-route component, an unrelated route, a
+   * signal-only module) so it falls back to `import.meta.hot.invalidate()`
+   * → an automatic full reload (no manual refresh either way).
+   *
+   * Present only when the router is created in a dev browser context.
+   */
+  _hmrSwap?: (id: string, mod: unknown) => boolean
 }