@rangojs/router 0.22.1 → 0.23.0

package/src/vite/rango.ts

@@ -14,6 +14,7 @@ import {
 } from "./plugins/expose-internal-ids.js";
 import { useCacheTransform } from "./plugins/use-cache-transform.js";
 import { transitionWhenHoistPlugin } from "./plugins/transition-when-hoist.js";
+import { clientUrlsRevalidateHoistPlugin } from "./plugins/client-urls-revalidate-hoist.js";
 import { clientRefDedup } from "./plugins/client-ref-dedup.js";
 import { stableRscOutput } from "./plugins/stable-rsc-output.js";
 import { VIRTUAL_IDS } from "./plugins/virtual-entries.js";
@@ -592,6 +593,7 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
 
   plugins.push(createLoaderDirectiveGuardPlugin());
   plugins.push(transitionWhenHoistPlugin());
+  plugins.push(...clientUrlsRevalidateHoistPlugin());
   plugins.push(createLoaderScanStubPlugin());
   plugins.push(exposeActionId());
   plugins.push(

package/src/vite/router-discovery.ts

@@ -7,7 +7,7 @@
  */
 
 import type { Plugin, ViteDevServer } from "vite";
-import { createServer as createViteServer } from "vite";
+import { createServer as createViteServer, normalizePath } from "vite";
 import { dirname, join, resolve } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
 import { createRequire, register } from "node:module";
@@ -17,6 +17,7 @@ import {
   findNestedRouterConflict,
   findRouterFiles,
   createScanFilter,
+  isInSkippedScanDir,
 } from "../build/generate-route-types.js";
 import { firstCodeMatchIndex } from "../build/route-types/source-scan.js";
 import {
@@ -50,6 +51,7 @@ import { hashServerRefs } from "./plugins/server-ref-hashing.js";
 import { defineEncryptionKeyExpr } from "./encryption-key.js";
 import { extractHandlerExportsFromChunk } from "./utils/bundle-analysis.js";
 import {
+  canRefreshRuntimeDiscovery,
   createDiscoveryState,
   VIRTUAL_ROUTES_MANIFEST_ID,
   type DiscoveryState,
@@ -75,6 +77,7 @@ import {
 import { describeDiscoveryFailure } from "./discovery/discovery-errors.js";
 import { findTransitionWhenError } from "../transition-when-ref.js";
 import { transitionWhenHoistPlugin } from "./plugins/transition-when-hoist.js";
+import { clientUrlsRevalidateHoistPlugin } from "./plugins/client-urls-revalidate-hoist.js";
 import {
   createDevPrerenderCache,
   devPrerenderCacheKey,
@@ -106,6 +109,35 @@ const debugDev = createRangoDebugger(NS.dev);
 
 export { VIRTUAL_ROUTES_MANIFEST_ID };
 
+/** The slice of a Vite environment module graph the route-file watcher reads. */
+interface ModulesByFileGraph {
+  getModulesByFile(file: string): ReadonlySet<unknown> | undefined;
+}
+
+/** Modules a Vite graph holds for `file`; Vite keys its file index by normalized path. */
+function modulesForFile(
+  graph: ModulesByFileGraph,
+  file: string,
+): ReadonlySet<unknown> | undefined {
+  return graph.getModulesByFile(normalizePath(file));
+}
+
+/**
+ * Whether the dev route-file watcher ignores `file`: it sits in a directory
+ * every discovery scan skips (isInSkippedScanDir) and the RSC graph has not
+ * loaded it. See docs/manifests.md, "A reload no file of the app asked for".
+ */
+export function isFileOutsideApp(
+  root: string,
+  file: string,
+  rscGraph: ModulesByFileGraph | undefined,
+): boolean {
+  return (
+    isInSkippedScanDir(root, file) &&
+    !(rscGraph && modulesForFile(rscGraph, file)?.size)
+  );
+}
+
 // ============================================================================
 // Node ESM Loader Hook Registration
 // ============================================================================
@@ -299,6 +331,10 @@ export async function createTempRscServer(
       // Inline transition({ when }) literals become client references here
       // too, or discovery would see (and reject) the plain function.
       transitionWhenHoistPlugin(),
+      // clientUrls() revalidate() predicates move to the server here too:
+      // discovery serializes the SSR copy's markers and the RSC realm
+      // registers the predicates the materialized stubs call.
+      ...clientUrlsRevalidateHoistPlugin(),
       // Dev prerender must use dev-mode IDs (path-based) to match the workerd
       // runtime. forceBuild produces hashed IDs for production bundle consistency.
       exposeInternalIds(options.forceBuild ? { forceBuild: true } : undefined),
@@ -1066,20 +1102,17 @@ export function createRouterDiscoveryPlugin(
           // Discover routers FIRST, then arm the manifest-readiness gate on the
           // server module discovery actually read the registry from.
           //
-          // We deliberately do NOT pre-import "@rangojs/router/server" before the
-          // entry to arm the gate early. During a Vite dependency re-optimization
-          // (dev boot after a lockfile change, or `vite dev --force`), a module
-          // imported here before the entry resolves to the pre-optimize copy of
-          // the runner's module graph, while discoverRouters' entry import — which
-          // awaits the in-flight re-optimization — resolves to the post-optimize
-          // copy. createRouter() then populates RouterRegistry on the fresh copy,
-          // but a stale pre-imported "@rangojs/router/server" reads the other
-          // copy's empty Map and discovery throws a spurious "No routers found"
-          // even though the app is configured correctly. discoverRouters imports
-          // the entry first and reads the registry off the same instance, keeping
-          // read and write on one copy. The virtual manifest module's own gate
-          // (s.discoveryDone, armed by beginDiscoveryGate) already blocks early
-          // requests during discovery on the Node path, so arming
+          // We deliberately do NOT pre-import "@rangojs/router/server" here to
+          // arm the gate early. During a Vite dependency re-optimization (dev
+          // boot after a lockfile change, or `vite dev --force`) or any runner
+          // full reload, a module imported before the entry can be a stale copy
+          // of the runner's module graph: createRouter() populates RouterRegistry
+          // on the fresh copy and the stale one reads an empty Map, a spurious
+          // "No routers found" (#637). discoverRouters returns the instance it
+          // read the registry from and verified the runner still serves (it
+          // redoes a pass that a reload split). The virtual manifest module's
+          // own gate (s.discoveryDone, armed by beginDiscoveryGate) already
+          // blocks early requests during discovery on the Node path, so arming
           // manifestReadyPromise after discovery is sufficient here.
           const serverMod = await timed(debugDiscovery, "discoverRouters", () =>
             discoverRouters(s, rscEnv, (server.environments as any)?.ssr),
@@ -1105,6 +1138,12 @@ export function createRouterDiscoveryPlugin(
             propagateDiscoveryState(rscEnv),
           );
         } catch (err: any) {
+          // Recovery mode: the next in-scan source change re-runs discovery
+          // (canRefreshRuntimeDiscovery) instead of waiting for a restart.
+          s.lastDiscoveryError = {
+            message: err?.message ?? String(err),
+            at: Date.now(),
+          };
           emitDiscoveryFailure(
             err,
             optimizerHashBefore,
@@ -1630,6 +1669,15 @@ export function createRouterDiscoveryPlugin(
           (filePath.includes("named-routes.gen.ts") ||
             filePath.includes("urls.gen.ts"));
 
+        // Files no discovery scan reaches are ignored unless the RSC graph
+        // loaded them (docs/manifests.md, "A reload no file of the app asked for").
+        const isOutsideApp = (filePath: string): boolean =>
+          isFileOutsideApp(
+            s.projectRoot,
+            filePath,
+            (server.environments as any)?.rsc?.moduleGraph,
+          );
+
         const regenerateGeneratedRouteFiles = () => {
           if (s.perRouterManifests.length > 0) {
             writeRouteTypesFiles(s);
@@ -1676,6 +1724,18 @@ export function createRouterDiscoveryPlugin(
         // only the expensive regeneration is debounced.
         let routeChangeTimer: ReturnType<typeof setTimeout> | undefined;
 
+        // Drop the routes-manifest virtual module's cached transform so the
+        // next runner evaluation regenerates it from current state.
+        const invalidateRoutesManifestModule = (rscEnv: any) => {
+          for (const virtualId of [
+            VIRTUAL_ROUTES_MANIFEST_ID,
+            `\0${VIRTUAL_ROUTES_MANIFEST_ID}`,
+          ]) {
+            const virtualMod = rscEnv.moduleGraph?.getModuleById?.(virtualId);
+            if (virtualMod) rscEnv.moduleGraph.invalidateModule(virtualMod);
+          }
+        };
+
         // Re-run runtime discovery so factory-generated routes that the
         // static parser cannot see are refreshed after source changes.
         // The state-machine concerns (queued/pending/gatePending) are
@@ -1696,6 +1756,7 @@ export function createRouterDiscoveryPlugin(
             const hmrStart = performance.now();
             try {
               if (hasMainRunner) {
+                const recoveringColdStart = s.perRouterManifests.length === 0;
                 await timed(debugDiscovery, "hmr discoverRouters", () =>
                   discoverRouters(s, rscEnv, (server.environments as any)?.ssr),
                 );
@@ -1705,6 +1766,9 @@ export function createRouterDiscoveryPlugin(
                 await timed(debugDiscovery, "hmr propagateDiscoveryState", () =>
                   propagateDiscoveryState(rscEnv),
                 );
+                // The manifest module emitted after a failed cold discovery has
+                // no gen-file import, so no gen write ever invalidates it.
+                if (recoveringColdStart) invalidateRoutesManifestModule(rscEnv);
               } else {
                 // Cloudflare HMR: invalidate the temp server's RSC module
                 // graph (or close+recreate as a fallback) so the runner
@@ -1924,16 +1988,7 @@ export function createRouterDiscoveryPlugin(
                 // stale replay after propagateDiscoveryState would clobber
                 // the refreshed registry as the realm's last write and the
                 // next router evaluation would materialize the old mount.
-                for (const virtualId of [
-                  VIRTUAL_ROUTES_MANIFEST_ID,
-                  `\0${VIRTUAL_ROUTES_MANIFEST_ID}`,
-                ]) {
-                  const virtualMod =
-                    rscEnv.moduleGraph?.getModuleById?.(virtualId);
-                  if (virtualMod) {
-                    rscEnv.moduleGraph.invalidateModule(virtualMod);
-                  }
-                }
+                invalidateRoutesManifestModule(rscEnv);
               } catch (err: any) {
                 debugDiscovery?.(
                   "watcher: clientUrls projection pre-refresh failed: %s",
@@ -1970,7 +2025,7 @@ export function createRouterDiscoveryPlugin(
             // Async: re-run runtime discovery to refresh factory-generated
             // routes that the static parser cannot resolve. Resolves the
             // discovery gate when complete.
-            if (s.perRouterManifests.length > 0) {
+            if (canRefreshRuntimeDiscovery(s, !!rscEnv?.runner)) {
               // The cloudflare workerd reload fires inside refreshRuntimeDiscovery
               // on the successful cycle (see forceCloudflareWorkerReload call
               // there) so queued follow-up cycles also trigger it.
@@ -1987,6 +2042,13 @@ export function createRouterDiscoveryPlugin(
         };
 
         const handleRouteFileChange = (filePath: string) => {
+          if (isOutsideApp(filePath)) {
+            debugDiscovery?.(
+              "watcher: skip %s (outside the discovery scan)",
+              filePath,
+            );
+            return;
+          }
           if (maybeHandleGeneratedRouteFileMutation(filePath)) return;
           if (
             !filePath.endsWith(".ts") &&
@@ -2124,9 +2186,7 @@ export function createRouterDiscoveryPlugin(
                 }
                 const seen = new Set<any>();
                 for (const file of routerSourceFiles) {
-                  const mods = rscGraph.getModulesByFile(
-                    file.replaceAll("\\", "/"),
-                  );
+                  const mods = modulesForFile(rscGraph, file);
                   if (!mods) {
                     debugDiscovery?.(
                       "watcher: clientUrls invalidation found no rsc modules for %s",
@@ -2166,8 +2226,9 @@ export function createRouterDiscoveryPlugin(
             // and resets `discoveryDone` to a fresh pending promise (so
             // workerd reloads triggered by the same source change can't
             // observe a stale resolved gate from cold-start). Resolved
-            // by the trailing refreshRuntimeDiscovery() cycle.
-            if (s.perRouterManifests.length > 0) {
+            // by the trailing refreshRuntimeDiscovery() cycle, which runs
+            // under the same predicate.
+            if (canRefreshRuntimeDiscovery(s, !!mainRscEnv?.runner)) {
               gate.noteRouteEvent();
             }
             scheduleRouteRegeneration();
@@ -2194,7 +2255,7 @@ export function createRouterDiscoveryPlugin(
         // Same no-runner guard as change/add: stale perRouterManifests would
         // reintroduce reverted content.
         server.watcher.on("unlink", (filePath) => {
-          if (!isGeneratedRouteFile(filePath)) return;
+          if (!isGeneratedRouteFile(filePath) || isOutsideApp(filePath)) return;
           const hasRunner = !!(server.environments as any)?.rsc?.runner;
           if (!hasRunner) return;
           regenerateGeneratedRouteFiles();

package/dist/types/client-urls/revalidate-chain.d.ts

@@ -1,33 +0,0 @@
-/**
- * The clientUrls revalidate() chain evaluator, shared by the browser
- * collector (navigation.ts) and the public testing primitive
- * (testing/run-client-revalidate.ts) so the two can never drift.
- *
- * Semantics mirror the server's evaluateRevalidation
- * (src/router/revalidation.ts): a boolean verdict is a hard decision and
- * short-circuits the rest of the chain; a `{ defaultShouldRevalidate }`
- * object updates the running suggestion, which later predicates receive as
- * their `defaultShouldRevalidate`; null/undefined defers; a throwing
- * predicate fails open to the current suggestion (logged). One deliberate
- * divergence: the object form is accepted only with a boolean value — the
- * server is laxer, but never re-compares the value, while this decision
- * feeds a strict-equality delta gate and the wire encoding
- * (navigation.ts), where a truthy non-boolean would invert intent.
- */
-import type { ClientRevalidateArgs, ClientRevalidateFn } from "./types.js";
-/**
- * The locked default the server will apply to the request these decisions
- * ride on. `actionRequest` is about the REQUEST, not the user gesture: only
- * the action POST itself is evaluated server-side with actionContext
- * (default `true`); the follow-up refetch GETs an action can trigger carry
- * no actionContext and get navigation defaults — even though their
- * predicates still see `isAction()` as true.
- */
-export declare function lockedClientDefault(options: {
-    actionRequest: boolean;
-    currentParams: Record<string, string>;
-    nextParams: Record<string, string>;
-    currentUrl: URL;
-    nextUrl: URL;
-}): boolean;
-export declare function runClientRevalidateChain(fns: readonly ClientRevalidateFn[], baseArgs: Omit<ClientRevalidateArgs, "defaultShouldRevalidate">, lockedDefault: boolean, label: string): boolean;

package/dist/types/client-urls/revalidation-protocol.d.ts

@@ -1,25 +0,0 @@
-/**
- * Wire protocol for CLIENT-RUN per-loader revalidation decisions.
- *
- * clientUrls() revalidate() predicates are declared in a "use client" module,
- * so they cannot cross the projection boundary as functions — instead they
- * EXECUTE in the browser and only their DECISIONS cross: the browser attaches
- * this header to partial-navigation and action requests, and the synthesized
- * per-loader revalidate() on every materialized loader stub reads it back
- * (see materializeRouteItems in server-projection.ts).
- *
- * Trust model: same class as `_rsc_segments` — a decision can only make the
- * CLIENT's own view staler (skip) or fresher (force), and the synthesized
- * predicates exist only on client-urls loader stubs, so the header can never
- * influence server-tree loaders. Requests without the header (no-JS, PE,
- * prefetch, document loads) fall back to the locked server defaults.
- */
-export declare const CLIENT_REVALIDATION_HEADER = "X-Rango-Client-Reval";
-export interface ClientRevalidationDecisions {
-    /** Loader $$ids whose client predicate said false (keep held data). */
-    readonly skip: readonly string[];
-    /** Loader $$ids whose client predicate said true against a false default. */
-    readonly force: readonly string[];
-}
-export declare function encodeClientRevalidationDecisions(decisions: ClientRevalidationDecisions): string | null;
-export declare function decodeClientRevalidationDecisions(headerValue: string | null): ClientRevalidationDecisions | null;

package/dist/types/testing/run-client-revalidate.d.ts

@@ -1,43 +0,0 @@
-/**
- * runClientRevalidate — unit-test clientUrls() revalidate() predicates.
- *
- * Builds the same {@link ClientRevalidateArgs} the browser collector passes
- * and evaluates the predicate(s) through the SAME chain evaluator production
- * uses (client-urls/revalidate-chain.ts) — locked default, boolean
- * short-circuit, soft-verdict threading, and fail-open are the production
- * code paths, not a re-implementation. Pass an array to test a chain.
- *
- * Synchronous: client revalidate functions must be sync.
- */
-import type { ClientRevalidateFn } from "../client-urls/types.js";
-/**
- * Options for {@link runClientRevalidate}. Defaults model a same-URL
- * navigation with no action (locked default `false`).
- */
-export interface RunClientRevalidateOptions {
-    currentUrl?: string | URL;
-    nextUrl?: string | URL;
-    currentParams?: Record<string, string>;
-    nextParams?: Record<string, string>;
-    stale?: boolean;
-    /**
-     * The triggering action: a single imported reference (id resolved via
-     * `$id ?? $$id`; throws if the function carries neither) or a raw actionId
-     * string. A namespace/object is rejected — it cannot identify the ONE
-     * action that triggered the request. Omit for a plain navigation.
-     */
-    action?: ((...args: never[]) => unknown) | string;
-    /**
-     * Model an action-triggered refetch GET: predicates see `isAction()` as
-     * true, but the locked default stays the navigation default, matching how
-     * the server evaluates that request (no actionContext). Defaults to
-     * treating a provided `action` as the action POST itself.
-     */
-    actionRequest?: boolean;
-}
-/**
- * Run one clientUrls `revalidate()` predicate — or a chain, in declaration
- * order — against production-built args. Returns the final boolean decision
- * (locked default if every predicate defers or throws).
- */
-export declare function runClientRevalidate(fn: ClientRevalidateFn | readonly ClientRevalidateFn[], opts?: RunClientRevalidateOptions): boolean;

package/src/client-urls/revalidate-chain.ts

@@ -1,83 +0,0 @@
-/**
- * The clientUrls revalidate() chain evaluator, shared by the browser
- * collector (navigation.ts) and the public testing primitive
- * (testing/run-client-revalidate.ts) so the two can never drift.
- *
- * Semantics mirror the server's evaluateRevalidation
- * (src/router/revalidation.ts): a boolean verdict is a hard decision and
- * short-circuits the rest of the chain; a `{ defaultShouldRevalidate }`
- * object updates the running suggestion, which later predicates receive as
- * their `defaultShouldRevalidate`; null/undefined defers; a throwing
- * predicate fails open to the current suggestion (logged). One deliberate
- * divergence: the object form is accepted only with a boolean value — the
- * server is laxer, but never re-compares the value, while this decision
- * feeds a strict-equality delta gate and the wire encoding
- * (navigation.ts), where a truthy non-boolean would invert intent.
- */
-
-import { paramsEqual } from "../router/params-util.js";
-import type { ClientRevalidateArgs, ClientRevalidateFn } from "./types.js";
-
-/**
- * The locked default the server will apply to the request these decisions
- * ride on. `actionRequest` is about the REQUEST, not the user gesture: only
- * the action POST itself is evaluated server-side with actionContext
- * (default `true`); the follow-up refetch GETs an action can trigger carry
- * no actionContext and get navigation defaults — even though their
- * predicates still see `isAction()` as true.
- */
-export function lockedClientDefault(options: {
-  actionRequest: boolean;
-  currentParams: Record<string, string>;
-  nextParams: Record<string, string>;
-  currentUrl: URL;
-  nextUrl: URL;
-}): boolean {
-  if (options.actionRequest) return true;
-  return (
-    !paramsEqual(options.currentParams, options.nextParams) ||
-    options.currentUrl.search !== options.nextUrl.search
-  );
-}
-
-export function runClientRevalidateChain(
-  fns: readonly ClientRevalidateFn[],
-  baseArgs: Omit<ClientRevalidateArgs, "defaultShouldRevalidate">,
-  lockedDefault: boolean,
-  label: string,
-): boolean {
-  let suggestion = lockedDefault;
-  for (const fn of fns) {
-    let verdict: ReturnType<ClientRevalidateFn>;
-    try {
-      verdict = fn({ ...baseArgs, defaultShouldRevalidate: suggestion });
-    } catch (error) {
-      console.error(
-        `[@rangojs/router] clientUrls revalidate() threw for ${label}; using default decision:`,
-        error,
-      );
-      continue;
-    }
-    if (
-      process.env.NODE_ENV !== "production" &&
-      verdict != null &&
-      typeof (verdict as { then?: unknown }).then === "function"
-    ) {
-      console.warn(
-        `[rango] clientUrls revalidate() for ${label} returned a Promise; ` +
-          `predicates must be synchronous (return a boolean, ` +
-          `{ defaultShouldRevalidate }, or null/undefined). The async result ` +
-          `was IGNORED and the default (${suggestion}) was kept.`,
-      );
-    }
-    if (typeof verdict === "boolean") return verdict;
-    if (
-      verdict &&
-      typeof verdict === "object" &&
-      typeof verdict.defaultShouldRevalidate === "boolean"
-    ) {
-      suggestion = verdict.defaultShouldRevalidate;
-    }
-  }
-  return suggestion;
-}

package/src/client-urls/revalidation-protocol.ts

@@ -1,56 +0,0 @@
-/**
- * Wire protocol for CLIENT-RUN per-loader revalidation decisions.
- *
- * clientUrls() revalidate() predicates are declared in a "use client" module,
- * so they cannot cross the projection boundary as functions — instead they
- * EXECUTE in the browser and only their DECISIONS cross: the browser attaches
- * this header to partial-navigation and action requests, and the synthesized
- * per-loader revalidate() on every materialized loader stub reads it back
- * (see materializeRouteItems in server-projection.ts).
- *
- * Trust model: same class as `_rsc_segments` — a decision can only make the
- * CLIENT's own view staler (skip) or fresher (force), and the synthesized
- * predicates exist only on client-urls loader stubs, so the header can never
- * influence server-tree loaders. Requests without the header (no-JS, PE,
- * prefetch, document loads) fall back to the locked server defaults.
- */
-
-export const CLIENT_REVALIDATION_HEADER = "X-Rango-Client-Reval";
-
-export interface ClientRevalidationDecisions {
-  /** Loader $$ids whose client predicate said false (keep held data). */
-  readonly skip: readonly string[];
-  /** Loader $$ids whose client predicate said true against a false default. */
-  readonly force: readonly string[];
-}
-
-export function encodeClientRevalidationDecisions(
-  decisions: ClientRevalidationDecisions,
-): string | null {
-  if (decisions.skip.length === 0 && decisions.force.length === 0) return null;
-  // encodeURIComponent keeps the header value ISO-8859-1-safe regardless of
-  // what characters loader module ids contain.
-  return encodeURIComponent(
-    JSON.stringify({ skip: decisions.skip, force: decisions.force }),
-  );
-}
-
-export function decodeClientRevalidationDecisions(
-  headerValue: string | null,
-): ClientRevalidationDecisions | null {
-  if (!headerValue) return null;
-  try {
-    const parsed = JSON.parse(decodeURIComponent(headerValue)) as {
-      skip?: unknown;
-      force?: unknown;
-    };
-    const toIds = (value: unknown): readonly string[] =>
-      Array.isArray(value)
-        ? value.filter((entry): entry is string => typeof entry === "string")
-        : [];
-    return { skip: toIds(parsed.skip), force: toIds(parsed.force) };
-  } catch {
-    // A malformed header is treated as absent: locked defaults apply.
-    return null;
-  }
-}

package/src/testing/run-client-revalidate.ts

@@ -1,92 +0,0 @@
-/**
- * runClientRevalidate — unit-test clientUrls() revalidate() predicates.
- *
- * Builds the same {@link ClientRevalidateArgs} the browser collector passes
- * and evaluates the predicate(s) through the SAME chain evaluator production
- * uses (client-urls/revalidate-chain.ts) — locked default, boolean
- * short-circuit, soft-verdict threading, and fail-open are the production
- * code paths, not a re-implementation. Pass an array to test a chain.
- *
- * Synchronous: client revalidate functions must be sync.
- */
-
-import { makeIsAction } from "../router/is-action.js";
-import { resolveTestActionId } from "./internal/action-id.js";
-import {
-  lockedClientDefault,
-  runClientRevalidateChain,
-} from "../client-urls/revalidate-chain.js";
-import { toURL } from "./to-url.js";
-import type {
-  ClientRevalidateArgs,
-  ClientRevalidateFn,
-} from "../client-urls/types.js";
-
-const DEFAULT_URL = "http://localhost/";
-
-/**
- * Options for {@link runClientRevalidate}. Defaults model a same-URL
- * navigation with no action (locked default `false`).
- */
-export interface RunClientRevalidateOptions {
-  currentUrl?: string | URL;
-  nextUrl?: string | URL;
-  currentParams?: Record<string, string>;
-  nextParams?: Record<string, string>;
-  stale?: boolean;
-  /**
-   * The triggering action: a single imported reference (id resolved via
-   * `$id ?? $$id`; throws if the function carries neither) or a raw actionId
-   * string. A namespace/object is rejected — it cannot identify the ONE
-   * action that triggered the request. Omit for a plain navigation.
-   */
-  action?: ((...args: never[]) => unknown) | string;
-  /**
-   * Model an action-triggered refetch GET: predicates see `isAction()` as
-   * true, but the locked default stays the navigation default, matching how
-   * the server evaluates that request (no actionContext). Defaults to
-   * treating a provided `action` as the action POST itself.
-   */
-  actionRequest?: boolean;
-}
-
-/**
- * Run one clientUrls `revalidate()` predicate — or a chain, in declaration
- * order — against production-built args. Returns the final boolean decision
- * (locked default if every predicate defers or throws).
- */
-export function runClientRevalidate(
-  fn: ClientRevalidateFn | readonly ClientRevalidateFn[],
-  opts: RunClientRevalidateOptions = {},
-): boolean {
-  const currentUrl = toURL(opts.currentUrl, new URL(DEFAULT_URL));
-  const nextUrl = toURL(opts.nextUrl, currentUrl);
-  const currentParams = opts.currentParams ?? {};
-  const nextParams = opts.nextParams ?? currentParams;
-  const inAction = opts.action !== undefined;
-  const actionId = resolveTestActionId(opts.action, "runClientRevalidate");
-  const defaultShouldRevalidate = lockedClientDefault({
-    actionRequest: opts.actionRequest ?? inAction,
-    currentParams,
-    nextParams,
-    currentUrl,
-    nextUrl,
-  });
-
-  const baseArgs: Omit<ClientRevalidateArgs, "defaultShouldRevalidate"> = {
-    currentUrl,
-    nextUrl,
-    currentParams,
-    nextParams,
-    stale: opts.stale ?? false,
-    isAction: makeIsAction(actionId, inAction),
-    ...(actionId !== undefined ? { actionId } : {}),
-  };
-
-  return runClientRevalidateChain(
-    Array.isArray(fn) ? fn : [fn],
-    baseArgs,
-    defaultShouldRevalidate,
-    "runClientRevalidate predicate",
-  );
-}