@rangojs/router 0.0.0-experimental.100 → 0.0.0-experimental.102

package/dist/bin/rango.js

@@ -1050,7 +1050,8 @@ export const renderHTML = createSSRHandler({
 // src/vite/plugins/version-plugin.ts
 var version_plugin_exports = {};
 __export(version_plugin_exports, {
-  createVersionPlugin: () => createVersionPlugin
+  createVersionPlugin: () => createVersionPlugin,
+  isViteDepCachePath: () => isViteDepCachePath
 });
 import { parseAst } from "vite";
 function isCodeModule(id) {
@@ -1145,6 +1146,7 @@ function createVersionPlugin() {
   let currentVersion = buildVersion;
   let isDev = false;
   let server = null;
+  let resolvedCacheDir;
   const clientModuleSignatures = /* @__PURE__ */ new Map();
   let versionCounter = 0;
   const bumpVersion = (reason) => {
@@ -1163,6 +1165,7 @@ function createVersionPlugin() {
     enforce: "pre",
     configResolved(config) {
       isDev = config.command === "serve";
+      resolvedCacheDir = config.cacheDir ? String(config.cacheDir).replace(/\\/g, "/") : void 0;
     },
     configureServer(devServer) {
       server = devServer;
@@ -1204,6 +1207,7 @@ function createVersionPlugin() {
       if (!isDev) return;
       const isRscModule = this.environment?.name === "rsc";
       if (!isRscModule) return;
+      if (isViteDepCachePath(ctx.file, resolvedCacheDir)) return;
       if (ctx.modules.length === 1 && ctx.modules[0].id === "\0" + VIRTUAL_IDS.version) {
         return;
       }
@@ -1233,6 +1237,17 @@ function createVersionPlugin() {
     }
   };
 }
+function isViteDepCachePath(filePath, cacheDir) {
+  if (!filePath) return false;
+  const normalized = filePath.replace(/\\/g, "/");
+  if (cacheDir) {
+    const normalizedCacheDir = cacheDir.replace(/\\/g, "/").replace(/\/+$/, "");
+    if (normalized === normalizedCacheDir || normalized.startsWith(normalizedCacheDir + "/")) {
+      return true;
+    }
+  }
+  return /\/node_modules\/\.vite[^/]*\//.test(normalized) || normalized.includes("/.vite-isolated/");
+}
 var init_version_plugin = __esm({
   "src/vite/plugins/version-plugin.ts"() {
     "use strict";

package/dist/vite/index.js

@@ -2040,7 +2040,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.100",
+  version: "0.0.0-experimental.102",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -3077,6 +3077,7 @@ function createVersionPlugin() {
   let currentVersion = buildVersion;
   let isDev = false;
   let server = null;
+  let resolvedCacheDir;
   const clientModuleSignatures = /* @__PURE__ */ new Map();
   let versionCounter = 0;
   const bumpVersion = (reason) => {
@@ -3095,6 +3096,7 @@ function createVersionPlugin() {
     enforce: "pre",
     configResolved(config) {
       isDev = config.command === "serve";
+      resolvedCacheDir = config.cacheDir ? String(config.cacheDir).replace(/\\/g, "/") : void 0;
     },
     configureServer(devServer) {
       server = devServer;
@@ -3136,6 +3138,7 @@ function createVersionPlugin() {
       if (!isDev) return;
       const isRscModule = this.environment?.name === "rsc";
       if (!isRscModule) return;
+      if (isViteDepCachePath(ctx.file, resolvedCacheDir)) return;
       if (ctx.modules.length === 1 && ctx.modules[0].id === "\0" + VIRTUAL_IDS.version) {
         return;
       }
@@ -3165,6 +3168,17 @@ function createVersionPlugin() {
     }
   };
 }
+function isViteDepCachePath(filePath, cacheDir) {
+  if (!filePath) return false;
+  const normalized = filePath.replace(/\\/g, "/");
+  if (cacheDir) {
+    const normalizedCacheDir = cacheDir.replace(/\\/g, "/").replace(/\/+$/, "");
+    if (normalized === normalizedCacheDir || normalized.startsWith(normalizedCacheDir + "/")) {
+      return true;
+    }
+  }
+  return /\/node_modules\/\.vite[^/]*\//.test(normalized) || normalized.includes("/.vite-isolated/");
+}
 
 // src/vite/utils/shared-utils.ts
 import * as Vite from "vite";
@@ -3784,7 +3798,8 @@ function createDiscoveryState(entryPath, opts) {
     devServerOrigin: null,
     devServer: null,
     selfWrittenGenFiles: /* @__PURE__ */ new Map(),
-    SELF_WRITE_WINDOW_MS: 5e3
+    SELF_WRITE_WINDOW_MS: 5e3,
+    lastDiscoveryError: null
   };
 }
 
@@ -5768,10 +5783,25 @@ ${err.stack}`
                   () => writeRouteTypesFiles(s)
                 );
               }
+              if (s.lastDiscoveryError) {
+                debugDiscovery?.(
+                  "hmr: cleared lastDiscoveryError (%s) after successful rediscovery",
+                  s.lastDiscoveryError.message
+                );
+                s.lastDiscoveryError = null;
+              }
             } catch (err) {
+              s.lastDiscoveryError = {
+                message: err?.message ?? String(err),
+                at: Date.now()
+              };
               console.warn(
                 `[rsc-router] Runtime re-discovery failed: ${err.message}`
               );
+              debugDiscovery?.(
+                "hmr: lastDiscoveryError set (%s) \u2014 manifest preserved at last-good; recovery mode active (any in-scan source change will trigger rediscovery)",
+                err?.message
+              );
             } finally {
               debugDiscovery?.(
                 "hmr re-discovery done (%sms)",
@@ -5819,23 +5849,52 @@ ${err.stack}`
         };
         const handleRouteFileChange = (filePath) => {
           if (maybeHandleGeneratedRouteFileMutation(filePath)) return;
-          if (!filePath.endsWith(".ts") && !filePath.endsWith(".tsx") && !filePath.endsWith(".js") && !filePath.endsWith(".jsx"))
+          if (!filePath.endsWith(".ts") && !filePath.endsWith(".tsx") && !filePath.endsWith(".js") && !filePath.endsWith(".jsx")) {
+            if (s.lastDiscoveryError) {
+              debugDiscovery?.(
+                "watcher: skip non-source %s [LASTERR %s]",
+                filePath,
+                s.lastDiscoveryError.message
+              );
+            }
             return;
-          if (s.scanFilter && !s.scanFilter(filePath)) return;
+          }
+          if (s.scanFilter && !s.scanFilter(filePath)) {
+            if (s.lastDiscoveryError) {
+              debugDiscovery?.(
+                "watcher: skip scan-filter %s [LASTERR %s]",
+                filePath,
+                s.lastDiscoveryError.message
+              );
+            }
+            return;
+          }
+          const inRecoveryMode = !!s.lastDiscoveryError;
           try {
             const source = readFileSync6(filePath, "utf-8");
             const trimmed = source.trimStart();
-            if (trimmed.startsWith('"use client"') || trimmed.startsWith("'use client'"))
-              return;
+            const isUseClient = trimmed.startsWith('"use client"') || trimmed.startsWith("'use client'");
+            if (!inRecoveryMode && isUseClient) return;
             const hasUrls = source.includes("urls(");
             const hasCreateRouter = /\bcreateRouter\s*[<(]/.test(source);
-            if (!hasUrls && !hasCreateRouter) return;
-            debugDiscovery?.(
-              "watcher: %s matches (urls=%s, router=%s)",
-              filePath,
-              hasUrls,
-              hasCreateRouter
-            );
+            if (!inRecoveryMode && !hasUrls && !hasCreateRouter) return;
+            if (inRecoveryMode) {
+              debugDiscovery?.(
+                "watcher: recovery rediscovery for %s (urls=%s, router=%s, useClient=%s) [LASTERR %s]",
+                filePath,
+                hasUrls,
+                hasCreateRouter,
+                isUseClient,
+                s.lastDiscoveryError.message
+              );
+            } else {
+              debugDiscovery?.(
+                "watcher: %s matches (urls=%s, router=%s)",
+                filePath,
+                hasUrls,
+                hasCreateRouter
+              );
+            }
             if (hasCreateRouter) {
               const nestedRouterConflict = findNestedRouterConflict([
                 ...s.cachedRouterFiles ?? [],
@@ -5853,7 +5912,15 @@ ${err.stack}`
               gate.noteRouteEvent();
             }
             scheduleRouteRegeneration();
-          } catch {
+          } catch (readErr) {
+            if (s.lastDiscoveryError) {
+              debugDiscovery?.(
+                "watcher: read error %s: %s [LASTERR %s]",
+                filePath,
+                readErr?.message,
+                s.lastDiscoveryError.message
+              );
+            }
           }
         };
         server.watcher.on("add", handleRouteFileChange);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.100",
+  "version": "0.0.0-experimental.102",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/hooks/SKILL.md

@@ -190,6 +190,47 @@ function SearchResults() {
 }
 ```
 
+**Shared refetch behavior**:
+
+When the loader is registered on the route via `loader()`, a plain
+`load()` call (no options, or a trivially-defaulted GET with no
+`params` and no `body`) broadcasts its result to every component
+reading the same loader id. Layout, page, and parallel-slot reads
+all converge on the new value:
+
+```tsx
+// Layout button calls load() — the page read below sees the update too.
+function Layout() {
+  const { data, load } = useLoader(CartLoader);
+  return <button onClick={() => load()}>Refresh ({data.count})</button>;
+}
+function Page() {
+  const { data } = useLoader(CartLoader); // updates with the layout's load()
+  return <span>{data.count} items</span>;
+}
+```
+
+`isLoading` and `error` follow the same scope. `throwOnError: true`
+render-throws are scoped to the **originating** hook — sibling readers
+see the error in their `error` state but their boundaries are not
+triggered by someone else's failure. A successful follow-up `load()`
+clears the shared error.
+
+**`load()` calls that stay local** (no broadcast, per-hook state, same
+semantics as the old per-component `useState`):
+
+- `load({ params: { ... } })` — explicit params.
+- `load({ method: "POST", body })` — mutations.
+- Any `load()` on a `useFetchLoader(loader)` whose loader is **not**
+  registered on the current route. Two unrelated components calling
+  `load()` on the same fetchable-but-unregistered loader keep
+  independent results.
+
+So the search/list pattern still works — two components calling
+`load({ params: { q } })` with different `q` values each keep their
+own result; they do not collapse to last-write-wins through a shared
+store.
+
 **Load options**:
 
 ```tsx
@@ -511,6 +552,43 @@ const flash = FlashMessage.read();
 const product = ProductState.read();
 ```
 
+> **Hydration:** `.read()` returns `undefined` on the server but may return
+> a real value on the first client render (history state survives reload).
+> Do not call `.read()` directly during the initial render of a component;
+> call it from an event handler or inside a `useEffect` post-mount. For
+> reactive hydration-safe access, use `useLocationState()` instead.
+
+### .write() / .delete() (static, non-reactive)
+
+Static counterparts to `.read()`. Both mutate the current history entry's
+`history.state` via `replaceState`, preserving any other keys (router
+bookkeeping, other location state slots). Both are client-only; they throw
+when called on the server.
+
+Neither dispatches an event, so components reading via `useLocationState`
+will NOT re-render until the next navigation/popstate. Pair with `.read()`
+(or a fresh mount via back/forward/reload) instead.
+
+```tsx
+"use client";
+import { ProductState } from "./state";
+
+// Persisted across hard refresh and back/forward of this entry.
+ProductState.write({ name: "Widget", price: 9.99 });
+
+// Read later (or on next mount).
+const current = ProductState.read();
+
+// Manually clear the slot. Idempotent if it isn't set.
+ProductState.delete();
+```
+
+| Method      | Updates `history.state` | Fires `useLocationState` rerender | SSR behavior        |
+| ----------- | ----------------------- | --------------------------------- | ------------------- |
+| `.read()`   | no                      | n/a (returns snapshot)            | returns `undefined` |
+| `.write()`  | yes (replace this slot) | no                                | throws              |
+| `.delete()` | yes (remove this slot)  | no                                | throws              |
+
 ## Cache Hooks
 
 ### useClientCache()

package/skills/loader/SKILL.md

@@ -606,6 +606,13 @@ export const FileUploadLoader = createLoader(async (ctx) => {
 
 Client usage — see `/hooks useFetchLoader` for the full client-side pattern.
 
+> **Refetch sharing**: when the loader is registered on the route via
+> `loader()`, a plain `load()` call (no `params`, no `body`) broadcasts
+> the new value to every component reading the same loader id —
+> `useLoader` reads in layouts, pages, and parallel slots all converge.
+> Calls with `params` or a non-GET method stay local to the call site.
+> See `/hooks` → "Shared refetch behavior" for the full contract.
+
 ## Complete Example
 
 ```typescript

package/src/browser/history-state.ts

@@ -61,6 +61,27 @@ export function buildHistoryState(
   return Object.keys(result).length > 0 ? result : null;
 }
 
+/**
+ * Stamp an `idx` on the next history entry's state and call push/replaceState.
+ * Push increments the current idx; replace keeps it. Initial entry idx is 0.
+ * Used by useRouter().back() to detect "first entry in this session" without
+ * relying on the Navigation API.
+ */
+export function pushHistoryWithIdx(
+  state: Record<string, unknown> | null,
+  url: string,
+  replace: boolean,
+): void {
+  const oldIdx = (window.history.state as { idx?: number } | null)?.idx ?? 0;
+  const newIdx = replace ? oldIdx : oldIdx + 1;
+  const finalState = { ...(state ?? {}), idx: newIdx };
+  if (replace) {
+    window.history.replaceState(finalState, "", url);
+  } else {
+    window.history.pushState(finalState, "", url);
+  }
+}
+
 /**
  * Merge server-set location state into the current history entry.
  * Replaces the current history state and dispatches notification event

package/src/browser/navigation-bridge.ts

@@ -13,7 +13,7 @@ import {
   createNavigationTransaction,
   resolveNavigationState,
 } from "./navigation-transaction.js";
-import { buildHistoryState } from "./history-state.js";
+import { buildHistoryState, pushHistoryWithIdx } from "./history-state.js";
 import {
   handleNavigationStart,
   handleNavigationEnd,
@@ -204,11 +204,7 @@ export function createNavigationBridge(
           },
           {},
         );
-        if (options.replace) {
-          window.history.replaceState(historyState, "", url);
-        } else {
-          window.history.pushState(historyState, "", url);
-        }
+        pushHistoryWithIdx(historyState, url, options?.replace ?? false);
 
         // Ensure new history entry has a scroll restoration key
         ensureHistoryKey();

package/src/browser/navigation-transaction.ts

@@ -11,7 +11,7 @@ import {
 } from "./scroll-restoration.js";
 import type { EventController, NavigationHandle } from "./event-controller.js";
 import { debugLog } from "./logging.js";
-import { buildHistoryState } from "./history-state.js";
+import { buildHistoryState, pushHistoryWithIdx } from "./history-state.js";
 
 // Re-export for consumers that import from navigation-transaction
 export { resolveNavigationState } from "./history-state.js";
@@ -186,12 +186,8 @@ export function createNavigationTransaction(
     // Used to detect when location state is being cleared.
     const oldState = window.history.state;
 
-    // Update browser URL
-    if (replace) {
-      window.history.replaceState(historyState, "", url);
-    } else {
-      window.history.pushState(historyState, "", url);
-    }
+    // Update browser URL (stamps history.state.idx for back() first-entry detection)
+    pushHistoryWithIdx(historyState, url, replace ?? false);
     // Ensure new history entry has a scroll restoration key
     ensureHistoryKey();
 

package/src/browser/react/location-state-shared.ts

@@ -34,8 +34,43 @@ export interface LocationStateDefinition<TArgs extends unknown[], TState> {
   __rsc_ls_key: string;
   /** Whether this state auto-clears after first read */
   readonly __rsc_ls_flash: boolean;
-  /** Read the current value from history.state (client-side only, undefined during SSR) */
+  /**
+   * Read the current value from history.state.
+   *
+   * Returns undefined during SSR (no `window`). To stay hydration-safe, do
+   * NOT call read() inline during the initial render — the server returns
+   * undefined while the client may have a value preserved in history.state
+   * (e.g. after a hard reload of an entry that earlier called write()),
+   * which causes a hydration mismatch. Call read() inside an event handler
+   * or a useEffect post-mount instead, or use useLocationState() if you
+   * want React to manage subscription/hydration for you.
+   */
   read(): TState | undefined;
+  /**
+   * Statically write the value into the current history entry under this
+   * definition's key, preserving any other keys already on history.state
+   * (e.g. router bookkeeping, other LocationState slots).
+   *
+   * This is the non-reactive counterpart to read(): it does not dispatch any
+   * event, so components reading via useLocationState() will NOT re-render
+   * until the next navigation/popstate. Use it when you only need the value
+   * to be there on the next read() or on the next mount (including after
+   * back/forward and hard refresh of the same entry).
+   *
+   * Client-only: throws when called on the server (no history available).
+   */
+  write(value: TState): void;
+  /**
+   * Statically remove this definition's slot from the current history entry,
+   * leaving any other keys on history.state untouched. Idempotent: removing
+   * a slot that isn't present is a no-op.
+   *
+   * Same non-reactive semantics as write(): no event is dispatched, so
+   * useLocationState() readers will NOT re-render until the next navigation.
+   *
+   * Client-only: throws when called on the server (no history available).
+   */
+  delete(): void;
 }
 
 /**
@@ -70,6 +105,15 @@ export interface LocationStateDefinition<TArgs extends unknown[], TState> {
  *
  * // Read without hook (snapshot, client-side only)
  * const snap = ProductState.read();
+ *
+ * // Static write to current history entry (non-reactive, client-side only).
+ * // Survives back/forward and hard refresh; useLocationState() readers will
+ * // NOT see the new value until the next navigation. Pair with .read() or a
+ * // fresh mount.
+ * ProductState.write({ name: "Widget", price: 9.99 });
+ *
+ * // Manually clear the slot (non-reactive, client-side only).
+ * ProductState.delete();
  * ```
  */
 export function createLocationState<TState>(
@@ -128,6 +172,43 @@ export function createLocationState<TState>(
     enumerable: true,
   });
 
+  Object.defineProperty(fn, "write", {
+    value: (value: TState): void => {
+      if (typeof window === "undefined") {
+        throw new Error(
+          "[rsc-router] LocationState.write() is client-only. " +
+            "It mutates window.history.state and cannot run on the server.",
+        );
+      }
+      const key = getKey();
+      const current = window.history.state ?? {};
+      window.history.replaceState(
+        { ...current, [key]: value },
+        "",
+        window.location.href,
+      );
+    },
+    enumerable: true,
+  });
+
+  Object.defineProperty(fn, "delete", {
+    value: (): void => {
+      if (typeof window === "undefined") {
+        throw new Error(
+          "[rsc-router] LocationState.delete() is client-only. " +
+            "It mutates window.history.state and cannot run on the server.",
+        );
+      }
+      const key = getKey();
+      const current = window.history.state;
+      if (current == null || !(key in current)) return;
+      const next = { ...current };
+      delete next[key];
+      window.history.replaceState(next, "", window.location.href);
+    },
+    enumerable: true,
+  });
+
   return fn as LocationStateDefinition<[TState | (() => TState)], TState>;
 }
 

package/src/browser/react/location-state.ts

@@ -1,6 +1,6 @@
 "use client";
 
-import { useState, useEffect } from "react";
+import { useState, useEffect, useRef } from "react";
 import type { LocationStateDefinition } from "./location-state-shared.js";
 
 // Re-export shared utilities and types
@@ -13,6 +13,24 @@ export {
   type LocationStateOptions,
 } from "./location-state-shared.js";
 
+function readLocationStateValue<TState>(
+  key: string | undefined,
+): TState | undefined {
+  if (typeof window === "undefined") return undefined;
+  if (key) {
+    return window.history.state?.[key] as TState | undefined;
+  }
+  // Plain state: stored under history.state.state
+  return window.history.state?.state as TState | undefined;
+}
+
+function hasHydrated(): boolean {
+  return (
+    typeof document !== "undefined" &&
+    document.documentElement.hasAttribute("data-hydrated")
+  );
+}
+
 /**
  * Hook to read location state from history.state
  *
@@ -48,30 +66,33 @@ export function useLocationState<TArgs extends unknown[], TState>(
   const key = definition?.__rsc_ls_key;
   const isFlash = definition?.__rsc_ls_flash ?? false;
 
+  // Track whether the initial render returned undefined because the page
+  // hadn't hydrated yet. If so, the mount effect catches up by reading
+  // history.state once. If not, we already have the right value and must
+  // not re-read on mount — under StrictMode, the flash-cleanup effect runs
+  // before the second setup pass, so a re-read would clobber the captured
+  // value with the now-cleared `undefined`.
+  const initialReadDeferredRef = useRef(false);
+
   const [state, setState] = useState<TState | undefined>(() => {
-    if (typeof window === "undefined") return undefined;
-    if (key) {
-      return window.history.state?.[key] as TState | undefined;
+    if (!hasHydrated()) {
+      initialReadDeferredRef.current = true;
+      return undefined;
     }
-    // Plain state: stored under history.state.state
-    return window.history.state?.state as TState | undefined;
+    return readLocationStateValue<TState>(key);
   });
 
   // Subscribe to popstate and programmatic state changes
   useEffect(() => {
     const handlePopstate = () => {
-      if (key) {
-        setState(window.history.state?.[key] as TState | undefined);
-      } else {
-        setState(window.history.state?.state as TState | undefined);
-      }
+      setState(readLocationStateValue<TState>(key));
     };
 
     // Handle programmatic state changes (same-page navigation with
     // ctx.setLocationState where components don't remount)
     const handleLocationState = () => {
       if (key) {
-        const val = window.history.state?.[key] as TState | undefined;
+        const val = readLocationStateValue<TState>(key);
         if (isFlash) {
           // For flash state, only update if there's a new value
           if (val !== undefined) {
@@ -81,10 +102,15 @@ export function useLocationState<TArgs extends unknown[], TState>(
           setState(val);
         }
       } else {
-        setState(window.history.state?.state as TState | undefined);
+        setState(readLocationStateValue<TState>(key));
       }
     };
 
+    if (initialReadDeferredRef.current) {
+      initialReadDeferredRef.current = false;
+      setState(readLocationStateValue<TState>(key));
+    }
+
     window.addEventListener("popstate", handlePopstate);
     window.addEventListener("__rsc_locationstate", handleLocationState);
     return () => {

package/src/browser/react/use-router.ts

@@ -72,7 +72,20 @@ export function useRouter(): RouterInstance {
       },
 
       back(): void {
-        window.history.back();
+        // Avoid escaping the host on the first entry of this session.
+        // Prefer the Navigation API; fall back to the router-stamped
+        // history.state.idx (set by pushHistoryWithIdx) for older browsers.
+        const nav = (window as { navigation?: { canGoBack: boolean } })
+          .navigation;
+        const canGoBack =
+          nav && typeof nav.canGoBack === "boolean"
+            ? nav.canGoBack
+            : ((window.history.state as { idx?: number } | null)?.idx ?? 0) > 0;
+        if (canGoBack) {
+          window.history.back();
+        } else {
+          ctx.navigate(withBasename("/"), { replace: true });
+        }
       },
 
       forward(): void {