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

package/src/browser/scroll-restoration.ts

@@ -332,6 +332,8 @@ export function scrollToHash(): boolean {
  * Scroll to top of page
  */
 export function scrollToTop(): void {
+  if (typeof window === "undefined") return;
+  if (typeof window.scrollTo !== "function") return;
   window.scrollTo(0, 0);
 }
 
@@ -374,20 +376,26 @@ export function handleNavigationEnd(options: {
     // Fall through to hash or top if no saved position
   }
 
-  // Defer hash and scroll-to-top to after React paints the new content,
-  // so the user doesn't see the current page jump before the new route appears.
-  deferToNextPaint(() => {
-    // Re-check: the deferred callback may fire after environment teardown
-    if (typeof window === "undefined") return;
-
-    // Try hash scrolling first
-    if (scrollToHash()) {
-      return;
-    }
-
-    // Default: scroll to top
-    scrollToTop();
-  });
+  // scrollToHash / scrollToTop run synchronously here.
+  // handleNavigationEnd is invoked from NavigationProvider's
+  // useLayoutEffect (post-commit, pre-paint), so a sync scrollTo is
+  // captured by the upcoming paint AND by startViewTransition's snapshot.
+  // Deferring via rAF here pushed the call past the snapshot capture,
+  // making forward navigations wrapped in a layout/route view transition
+  // skip scroll-to-top — the live DOM scrolled but the captured snapshot
+  // was at the previous scroll position, so the user-facing page stayed
+  // visually clamped at the source page's scrollY (often the new tree's
+  // max scroll for tall→short navs). Y=0 / a hash element are robust
+  // against unmeasured layout, so sync scroll is correct here even
+  // before the new tree's scrollHeight settles.
+  //
+  // (The restore branch above keeps deferToNextPaint because savedY
+  // depends on the new tree's max scroll; sync scrollTo against an
+  // unmeasured DOM would clamp savedY to whatever the old/zero max was.)
+  if (scrollToHash()) {
+    return;
+  }
+  scrollToTop();
 }
 
 /**

package/src/href-client.ts

@@ -186,7 +186,10 @@ export function href<T extends ValidPaths>(path: T, mount?: string): string {
     const normalizedMount = mount.endsWith("/") ? mount.slice(0, -1) : mount;
     return normalizedMount + path;
   }
-  return path;
+  // ValidPaths is built from template literals so T does extend string at
+  // runtime, but the inference can fail past a certain route-union complexity
+  // and TypeScript reports T as not assignable to string.
+  return path as string;
 }
 
 /**

package/src/loader-store.ts

@@ -0,0 +1,202 @@
+/**
+ * LoaderStore — shared subscription model for `useLoader` / `useFetchLoader`.
+ *
+ * Each loader id (loader.$$id) gets one entry that holds the latest committed
+ * snapshot plus a set of listeners. Snapshots are frozen and replaced atomically
+ * on mutation, so subscribers can compare snapshot identity and avoid
+ * unnecessary updates between real changes.
+ *
+ * Mutations that come in for an old request id (e.g. a slow response that
+ * resolves after a newer load() was issued, or after a navigation cleared the
+ * entry) are silently dropped. `reserveRequestId` is the only way to claim the
+ * "latest" slot; `clear` bumps it too so pre-navigation in-flight loads cannot
+ * commit into the new route's context.
+ *
+ * The store is intentionally module-level: each browser tab is its own JS
+ * realm, so there is no cross-request pollution. Server renders never mutate
+ * the store — the hook falls back to `OutletContext.loaderData`.
+ */
+
+export interface LoaderEntry<T = unknown> {
+  readonly value: T | undefined;
+  readonly error: Error | null;
+  readonly isLoading: boolean;
+  /** Identifies the request that produced this snapshot. 0 means "no request". */
+  readonly requestId: number;
+}
+
+const EMPTY_SNAPSHOT: LoaderEntry = Object.freeze({
+  value: undefined,
+  error: null,
+  isLoading: false,
+  requestId: 0,
+});
+
+interface InternalEntry {
+  snapshot: LoaderEntry;
+  listeners: Set<() => void>;
+  /** Monotonically increasing. Bumped by reserveRequestId() and clear(). */
+  latestRequestId: number;
+}
+
+export class LoaderStore {
+  private readonly entries = new Map<string, InternalEntry>();
+
+  private getOrCreate(id: string): InternalEntry {
+    let e = this.entries.get(id);
+    if (!e) {
+      e = {
+        snapshot: EMPTY_SNAPSHOT,
+        listeners: new Set(),
+        latestRequestId: 0,
+      };
+      this.entries.set(id, e);
+    }
+    return e;
+  }
+
+  /**
+   * Subscribe to entry changes for `id`.
+   * Returns an unsubscribe function. The store keeps the entry around even
+   * after the last subscriber leaves so that an in-flight `load()` can still
+   * commit if the consumer remounts.
+   */
+  subscribe(id: string, cb: () => void): () => void {
+    const e = this.getOrCreate(id);
+    e.listeners.add(cb);
+    return () => {
+      e.listeners.delete(cb);
+    };
+  }
+
+  /**
+   * Returns the current snapshot for `id`. Stable reference between mutations
+   * — subscribers rely on this to avoid spurious re-renders.
+   * Returns `EMPTY_SNAPSHOT` (a singleton) when the entry has never been
+   * mutated or has been cleared.
+   */
+  getSnapshot(id: string): LoaderEntry {
+    return this.entries.get(id)?.snapshot ?? EMPTY_SNAPSHOT;
+  }
+
+  /**
+   * Reserve a fresh request id for an upcoming `load()` call. The returned id
+   * is the new "latest"; any older in-flight requests will fail their gating
+   * check on `finishData` / `finishError` / `finishLoading` and be dropped.
+   *
+   * Callers should follow with `beginRequest(id, requestId)` to flip the
+   * loading flag on AND clear any leftover error from a previous attempt
+   * — the latter matters for `throwOnError: false` consumers, which would
+   * otherwise keep showing the stale error throughout the retry.
+   */
+  reserveRequestId(id: string): number {
+    const e = this.getOrCreate(id);
+    e.latestRequestId++;
+    return e.latestRequestId;
+  }
+
+  /**
+   * Mark the request as in-flight: `isLoading = true`, `error = null`.
+   * Combines the two operations so a retry doesn't render the previous
+   * error during the new request. Gated on `requestId === latestRequestId`
+   * for symmetry with the other mutators.
+   */
+  beginRequest(id: string, requestId: number): void {
+    const e = this.entries.get(id);
+    if (!e || requestId !== e.latestRequestId) return;
+    if (e.snapshot.isLoading && e.snapshot.error === null) return;
+    e.snapshot = Object.freeze({
+      value: e.snapshot.value,
+      error: null,
+      isLoading: true,
+      requestId,
+    });
+    this.notify(e);
+  }
+
+  /**
+   * Commit a successful result. No-op if `requestId` is not the latest
+   * (a newer `load()` was issued or `clear()` ran). Clearing `error` is
+   * intentional: a successful refetch should hide the previous failure.
+   */
+  finishData<T>(id: string, requestId: number, value: T): void {
+    const e = this.entries.get(id);
+    if (!e || requestId !== e.latestRequestId) return;
+    e.snapshot = Object.freeze({
+      value,
+      error: null,
+      isLoading: false,
+      requestId,
+    });
+    this.notify(e);
+  }
+
+  /**
+   * Commit an error. Preserves the last good `value` so consumers can keep
+   * showing previous data while displaying the error if they choose. No-op
+   * if `requestId` is not the latest.
+   */
+  finishError(id: string, requestId: number, error: Error): void {
+    const e = this.entries.get(id);
+    if (!e || requestId !== e.latestRequestId) return;
+    e.snapshot = Object.freeze({
+      value: e.snapshot.value,
+      error,
+      isLoading: false,
+      requestId,
+    });
+    this.notify(e);
+  }
+
+  /**
+   * Update loading flag. Gated on `requestId` to fix the race where an old
+   * load() finishes after a new one started — its `setLoading(false)` would
+   * otherwise hide the new request's spinner.
+   */
+  setLoading(id: string, requestId: number, isLoading: boolean): void {
+    const e = this.entries.get(id);
+    if (!e || requestId !== e.latestRequestId) return;
+    if (e.snapshot.isLoading === isLoading) return;
+    e.snapshot = Object.freeze({
+      ...e.snapshot,
+      isLoading,
+    });
+    this.notify(e);
+  }
+
+  /**
+   * Reset the entry. Bumps `latestRequestId` so any in-flight `load()` whose
+   * promise is still pending will fail its gate when it resolves and be
+   * dropped — prevents pre-navigation loads from clobbering the new route's
+   * context.
+   */
+  clear(id: string): void {
+    const e = this.entries.get(id);
+    if (!e) return;
+    e.latestRequestId++;
+    if (e.snapshot === EMPTY_SNAPSHOT) return;
+    e.snapshot = EMPTY_SNAPSHOT;
+    this.notify(e);
+  }
+
+  private notify(e: InternalEntry): void {
+    for (const cb of e.listeners) cb();
+  }
+
+  /**
+   * Test-only escape hatch. Drops every entry. Production code should never
+   * call this; the store is process-scoped and lives for the tab's lifetime.
+   * @internal
+   */
+  reset(): void {
+    this.entries.clear();
+  }
+}
+
+/**
+ * Module-level singleton. Each browser tab gets its own; SSR never mutates it.
+ * The hook falls through to `OutletContext.loaderData` during the server render.
+ */
+export const loaderStore: LoaderStore = new LoaderStore();
+
+export const EMPTY_LOADER_SNAPSHOT: LoaderEntry = EMPTY_SNAPSHOT;

package/src/use-loader.tsx

@@ -12,8 +12,31 @@ import {
   type ReactNode,
 } from "react";
 import { OutletContext, type OutletContextValue } from "./outlet-context.js";
+import { loaderStore, type LoaderEntry } from "./loader-store.js";
 import type { LoaderDefinition, LoadOptions } from "./types.js";
 
+/**
+ * Plain route-context refetch — a `load()` call with no options or a
+ * trivially-defaulted GET (no params, no body). Results from these are
+ * broadcast to every component reading the same loader id via the shared
+ * store, so a layout's refetch button updates page + parallel-slot reads
+ * automatically.
+ *
+ * Calls with explicit `params`, an explicit non-GET method, or a `body`
+ * stay local to the call site — that preserves the today-semantics of
+ * `useFetchLoader(SearchLoader).load({ params: { q } })` style code where
+ * each component owns its own fetched view.
+ */
+function isPlainRefetch(options: LoadOptions | undefined): boolean {
+  if (!options) return true;
+  if (options.method && options.method !== "GET") return false;
+  if (options.params && Object.keys(options.params).length > 0) return false;
+  if ("body" in options && (options as { body?: unknown }).body !== undefined) {
+    return false;
+  }
+  return true;
+}
+
 /**
  * Extract a specific loader's data from a content ReactNode.
  *
@@ -132,12 +155,23 @@ function useLoaderInternal<T>(
 ): UseFetchLoaderResult<T> {
   const context = useContext(OutletContext);
 
-  // Get data from context (SSR/navigation)
-  const contextData = useMemo((): T | undefined => {
+  // Get data from context (SSR/navigation). `hasContextData` distinguishes
+  // "loader registered on the route, value happens to be undefined" from
+  // "loader is not in any parent's context at all". The shared store is
+  // only consulted when the loader really is in route context — that
+  // preserves per-component isolation for ad-hoc useFetchLoader callers
+  // who use the same fetchable loader without registering it.
+  const { contextData, hasContextData } = useMemo((): {
+    contextData: T | undefined;
+    hasContextData: boolean;
+  } => {
     let current: OutletContextValue | null | undefined = context;
     while (current) {
       if (current.loaderData && loader.$$id in current.loaderData) {
-        return current.loaderData[loader.$$id] as T;
+        return {
+          contextData: current.loaderData[loader.$$id] as T,
+          hasContextData: true,
+        };
       }
       // Check content element — the route's OutletProvider is rendered as
       // <Outlet /> content (a child), so its loaderData isn't in the parent
@@ -147,32 +181,102 @@ function useLoaderInternal<T>(
         loader.$$id,
       );
       if (contentData !== NOT_FOUND) {
-        return contentData as T;
+        return { contextData: contentData as T, hasContextData: true };
       }
       current = current.parent;
     }
-    return undefined;
+    return { contextData: undefined, hasContextData: false };
   }, [context, loader.$$id]);
 
-  // Local state for fetched data (from load() calls)
-  const [fetchedData, setFetchedData] = useState<T | undefined>(undefined);
-  const [isLoading, setIsLoading] = useState(false);
-  const [error, setError] = useState<Error | null>(null);
-  const requestIdRef = useRef(0);
-
-  // Track context data changes to reset fetched data on navigation
+  // Shared subscription: every component reading the same loader id sees
+  // the same snapshot, so a plain refetch from one component propagates to
+  // the others. Mirrors the convention used by useParams / useLinkStatus —
+  // useState seeded from the store, useEffect subscribes for updates and
+  // calls setState inside startTransition so subscriber re-renders don't
+  // trip Suspense fallbacks during a refetch (matches the per-hook
+  // startTransition the old code wrapped setFetchedData in).
+  const loaderId = loader.$$id;
+  const [sharedState, setSharedState] = useState<{
+    loaderId: string;
+    snapshot: LoaderEntry;
+  }>(() => ({
+    loaderId,
+    snapshot: loaderStore.getSnapshot(loaderId),
+  }));
+  const sharedSnapshot =
+    sharedState.loaderId === loaderId
+      ? sharedState.snapshot
+      : loaderStore.getSnapshot(loaderId);
+  useEffect(() => {
+    // Sync any value the store committed between this hook's lazy
+    // initializer and effect-time (e.g. a sibling that mounted earlier
+    // already triggered a load()).
+    const initial = loaderStore.getSnapshot(loaderId);
+    if (initial !== sharedSnapshot) {
+      startTransition(() => {
+        setSharedState({ loaderId, snapshot: initial });
+      });
+    }
+    return loaderStore.subscribe(loaderId, () => {
+      const next = loaderStore.getSnapshot(loaderId);
+      startTransition(() => {
+        setSharedState({ loaderId, snapshot: next });
+      });
+    });
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- intentional:
+    // sharedSnapshot is captured for the one-shot init sync; we don't want
+    // to re-subscribe on every snapshot change.
+  }, [loaderId]);
+
+  // Local state holds the result of:
+  //   - parameterized / mutation `load()` calls (load({ params }), POST,
+  //     etc.) — stay scoped so concurrent same-loader different-params
+  //     fetches don't clobber each other through the shared store;
+  //   - any `load()` made by hooks that are NOT in route context (i.e.
+  //     useFetchLoader of an unregistered loader) — keeping those local
+  //     prevents two unrelated components from accidentally sharing data
+  //     through the global store just because they reference the same
+  //     loader id.
+  const [localFetchedData, setLocalFetchedData] = useState<T | undefined>(
+    undefined,
+  );
+  const [localIsLoading, setLocalIsLoading] = useState(false);
+  const [localError, setLocalError] = useState<Error | null>(null);
+
+  // Local request id, mirrors the per-hook gating the previous
+  // implementation provided. Two quick parameterized loads from the same
+  // hook (e.g. load({ params: { q: "a" } }) then load({ params: { q: "b" } }))
+  // can resolve out of order — only the latest must commit.
+  const localRequestIdRef = useRef(0);
+
+  // Tracks the request id of the most recent SHARED load() this hook
+  // initiated. The render-throw rule below uses it to scope the throw
+  // to the originating hook only — sibling readers see the error in
+  // `error` but don't blow up their own boundaries.
+  const lastSharedRequestIdRef = useRef<number | null>(null);
+
+  // Reset on navigation. clear() bumps the entry's latest request id so
+  // any pre-navigation load() promise that resolves later fails its gate
+  // and is dropped — fixes the race where a stale fetch overwrites the
+  // new route's context.
   const prevContextDataRef = useRef(contextData);
   useEffect(() => {
     if (prevContextDataRef.current !== contextData) {
-      // Navigation happened, clear fetched data so context takes precedence
-      setFetchedData(undefined);
-      setError(null);
+      setLocalFetchedData(undefined);
+      setLocalIsLoading(false);
+      setLocalError(null);
+      lastSharedRequestIdRef.current = null;
+      loaderStore.clear(loaderId);
       prevContextDataRef.current = contextData;
     }
-  }, [contextData]);
+  }, [contextData, loaderId]);
 
-  // Data priority: fetched data (if any) > context data
-  const data = fetchedData ?? contextData;
+  // Read priority: a parameterized load() result overrides the shared
+  // snapshot; the shared snapshot overrides the server-seeded context.
+  const data =
+    localFetchedData ?? (sharedSnapshot.value as T | undefined) ?? contextData;
+  const isLoading = localIsLoading || sharedSnapshot.isLoading;
+  const error = localError ?? sharedSnapshot.error;
 
   const throwOnError = options?.throwOnError ?? true;
 
@@ -180,30 +284,47 @@ function useLoaderInternal<T>(
   // churn. loader.$$id can change if a reusable component receives a different
   // loader without remounting; data changes on every navigation. Refs keep the
   // callback stable while always reading the latest values.
-  const loaderIdRef = useRef(loader.$$id);
-  loaderIdRef.current = loader.$$id;
+  const loaderIdRef = useRef(loaderId);
+  loaderIdRef.current = loaderId;
   const dataRef = useRef(data);
   dataRef.current = data;
+  const hasContextDataRef = useRef(hasContextData);
+  hasContextDataRef.current = hasContextData;
 
   // Load function for fetching data via the ?_rsc_loader endpoint.
   // Supports GET (data fetching) and POST/PUT/PATCH/DELETE (mutations).
   const load = useCallback(
     async (loadOptions?: LoadOptions): Promise<T> => {
-      const requestId = ++requestIdRef.current;
-      const loaderId = loaderIdRef.current;
-      // Verify the loader has $$id
-      if (!loaderId) {
+      const id = loaderIdRef.current;
+      if (!id) {
         throw new Error(
           `Loader is missing $$id. Make sure the exposeLoaderId Vite plugin is enabled.`,
         );
       }
 
-      setIsLoading(true);
-      setError(null);
+      // Sharing the result is only correct when the loader is actually
+      // registered on the route — otherwise two unrelated components
+      // calling load() on the same fetchable loader would suddenly start
+      // overwriting each other's local view through the global store.
+      const shared = isPlainRefetch(loadOptions) && hasContextDataRef.current;
+      let sharedRequestId = -1;
+      let localRequestId = -1;
+      if (shared) {
+        sharedRequestId = loaderStore.reserveRequestId(id);
+        lastSharedRequestIdRef.current = sharedRequestId;
+        // beginRequest flips loading on AND clears any prior error so a
+        // throwOnError: false consumer doesn't keep showing the stale
+        // error during the retry. Gated on requestId === latest.
+        loaderStore.beginRequest(id, sharedRequestId);
+      } else {
+        localRequestId = ++localRequestIdRef.current;
+        setLocalIsLoading(true);
+        setLocalError(null);
+      }
 
       try {
         const url = new URL(window.location.href);
-        url.searchParams.set("_rsc_loader", loaderId);
+        url.searchParams.set("_rsc_loader", id);
 
         const method = loadOptions?.method ?? "GET";
         const isBodyMethod = method !== "GET";
@@ -284,16 +405,26 @@ function useLoaderInternal<T>(
         }
 
         const result = payload.loaderResult;
-        if (requestId === requestIdRef.current) {
+        if (shared) {
+          // finishData is gated on requestId; a stale response is dropped.
+          loaderStore.finishData(id, sharedRequestId, result);
+        } else if (localRequestId === localRequestIdRef.current) {
+          // Local-branch gate, mirrors the shared-branch requestId check:
+          // if a newer load() was issued from this hook before this one
+          // resolved, drop the stale result.
           startTransition(() => {
-            setFetchedData(result);
+            setLocalFetchedData(result);
+            setLocalIsLoading(false);
           });
         }
         return result;
       } catch (e) {
         const err = e instanceof Error ? e : new Error(String(e));
-        if (requestId === requestIdRef.current) {
-          setError(err);
+        if (shared) {
+          loaderStore.finishError(id, sharedRequestId, err);
+        } else if (localRequestId === localRequestIdRef.current) {
+          setLocalError(err);
+          setLocalIsLoading(false);
         }
         if (throwOnError) {
           throw err;
@@ -302,18 +433,31 @@ function useLoaderInternal<T>(
         // successful value or undefined). Caller should check error state.
         return dataRef.current as T;
       } finally {
-        if (requestId === requestIdRef.current) {
-          setIsLoading(false);
+        if (shared) {
+          // setLoading is gated; only the latest request flips the flag off.
+          loaderStore.setLoading(id, sharedRequestId, false);
         }
       }
     },
     [throwOnError],
   );
 
-  // Throw during render if there's an error and throwOnError is true
-  // This allows ErrorBoundaries to catch async errors from load()
-  if (error && throwOnError) {
-    throw error;
+  // Throw during render if there's an error and throwOnError is true.
+  // - Local errors always belong to this hook, so always throw on opt-in.
+  // - Shared errors throw only when this hook initiated the failing
+  //   request (entry.requestId matches lastSharedRequestIdRef). Sibling
+  //   readers expose the error via `error` but do not throw, so a
+  //   throwOnError: true reader never explodes because of someone else's
+  //   throwOnError: false load() failure.
+  if (throwOnError) {
+    if (localError) throw localError;
+    if (
+      sharedSnapshot.error &&
+      lastSharedRequestIdRef.current !== null &&
+      sharedSnapshot.requestId === lastSharedRequestIdRef.current
+    ) {
+      throw sharedSnapshot.error;
+    }
   }
 
   return {

package/src/vite/discovery/state.ts

@@ -76,6 +76,14 @@ export interface DiscoveryState {
   resolvedBuildEnv?: Record<string, unknown>;
   /** Cleanup function for build-time env resources (e.g., miniflare). */
   buildEnvDispose?: (() => Promise<void> | void) | null;
+
+  /**
+   * Set when the most recent HMR re-discovery threw. Cleared on the next
+   * successful discovery. Surfaced via debug logs so we can detect "manifest
+   * frozen at last-good after error → user fix in non-route file → no
+   * rediscovery trigger" scenarios.
+   */
+  lastDiscoveryError?: { message: string; at: number } | null;
 }
 
 export function createDiscoveryState(
@@ -113,5 +121,6 @@ export function createDiscoveryState(
     devServer: null,
     selfWrittenGenFiles: new Map(),
     SELF_WRITE_WINDOW_MS: 5_000,
+    lastDiscoveryError: null,
   };
 }

package/src/vite/plugins/version-plugin.ts

@@ -133,6 +133,7 @@ export function createVersionPlugin(): Plugin {
   let currentVersion = buildVersion;
   let isDev = false;
   let server: any = null;
+  let resolvedCacheDir: string | undefined;
   const clientModuleSignatures = new Map<string, ClientModuleSignature>();
 
   let versionCounter = 0;
@@ -157,6 +158,12 @@ export function createVersionPlugin(): Plugin {
 
     configResolved(config) {
       isDev = config.command === "serve";
+      // Capture the resolved cacheDir so we can ignore optimizer-output
+      // writes inside it. Vite resolves cacheDir against the project root,
+      // so this is a stable absolute path for the lifetime of the server.
+      resolvedCacheDir = config.cacheDir
+        ? String(config.cacheDir).replace(/\\/g, "/")
+        : undefined;
     },
 
     configureServer(devServer) {
@@ -214,6 +221,14 @@ export function createVersionPlugin(): Plugin {
 
       if (!isRscModule) return;
 
+      // Skip Vite's own pre-bundled dep cache writes. The optimizer rewrites
+      // files inside the configured `cacheDir` on every discovery cycle
+      // (and when other dev servers under the same cwd populate their own
+      // isolated cache dirs). These are not user-source changes, so bumping
+      // the app version on them produces spurious version mismatches that
+      // surface as forced reloads on in-flight actions.
+      if (isViteDepCachePath(ctx.file, resolvedCacheDir)) return;
+
       // Skip re-bumping when the version virtual module itself is invalidated
       // (our own bumpVersion() invalidates it, which re-triggers hotUpdate).
       if (
@@ -264,3 +279,45 @@ export function createVersionPlugin(): Plugin {
     },
   };
 }
+
+/**
+ * Match Vite's pre-bundled dep cache directories. These paths are rewritten
+ * by the dep optimizer (and by isolated test fixtures sharing the same cwd),
+ * not by user source changes, so they should not bump the app version (which
+ * would force a client reload mid-request).
+ *
+ * Two checks:
+ * 1. Anything inside the resolved `cacheDir` (precise — covers custom paths
+ *    like the `RANGO_E2E_VITE_CACHE_DIR` overrides in the test fixtures).
+ * 2. Heuristic match for any `node_modules/.vite*` directory or a
+ *    `.vite-isolated/` segment anywhere in the path. This catches the
+ *    *other* dev servers in the same cwd whose cacheDir we cannot read
+ *    (we only see config of the server we're attached to).
+ */
+export function isViteDepCachePath(
+  filePath: string | undefined,
+  cacheDir?: string,
+): boolean {
+  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;
+    }
+  }
+
+  // Vite/optimizer convention: cache dirs always sit directly under
+  // `node_modules/` and start with `.vite` (e.g. `.vite`, `.vite-temp`,
+  // `.vite_rango_generate`, `.vite-e2e-test-app`). The `/.vite-isolated/`
+  // segment covers the test-fixture pattern that places the cache outside
+  // node_modules.
+  return (
+    /\/node_modules\/\.vite[^/]*\//.test(normalized) ||
+    normalized.includes("/.vite-isolated/")
+  );
+}