@rangojs/router 0.22.1 → 0.24.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,7 +51,9 @@ import { hashServerRefs } from "./plugins/server-ref-hashing.js";
 import { defineEncryptionKeyExpr } from "./encryption-key.js";
 import { extractHandlerExportsFromChunk } from "./utils/bundle-analysis.js";
 import {
+  canRefreshRuntimeDiscovery,
   createDiscoveryState,
+  recordDiscoveryFailure,
   VIRTUAL_ROUTES_MANIFEST_ID,
   type DiscoveryState,
   type PluginOptions,
@@ -75,6 +78,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 +110,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 +332,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),
@@ -1014,12 +1051,20 @@ export function createRouterDiscoveryPlugin(
               acquireBuildEnv(s, viteCommand, viteMode),
             );
 
-            tempRscEnv = (
-              await timed(debugDiscovery, "getOrCreateTempServer", () =>
-                getOrCreateTempServer(),
-              )
-            ).env;
-            if (tempRscEnv) {
+            const temp = await timed(
+              debugDiscovery,
+              "getOrCreateTempServer",
+              () => getOrCreateTempServer(),
+            );
+            tempRscEnv = temp.env;
+            if (!tempRscEnv) {
+              // Recovery mode, as in the catch below. getOrCreateTempServer
+              // already logged why the temp runner failed.
+              recordDiscoveryFailure(
+                s,
+                temp.error ?? "temp runner unavailable for discovery",
+              );
+            } else {
               optimizerHashBefore =
                 tempRscEnv.depsOptimizer?.metadata?.browserHash;
               await timed(debugDiscovery, "discoverRouters (cloudflare)", () =>
@@ -1034,6 +1079,7 @@ export function createRouterDiscoveryPlugin(
               );
             }
           } catch (err: any) {
+            recordDiscoveryFailure(s, err);
             emitDiscoveryFailure(
               err,
               optimizerHashBefore,
@@ -1066,20 +1112,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 +1148,9 @@ 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.
+          recordDiscoveryFailure(s, err);
           emitDiscoveryFailure(
             err,
             optimizerHashBefore,
@@ -1630,6 +1676,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 +1731,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
@@ -1684,18 +1751,12 @@ export function createRouterDiscoveryPlugin(
         const refreshRuntimeDiscovery = async () => {
           const rscEnv = (server.environments as any)?.rsc;
           const hasMainRunner = !!rscEnv?.runner;
-          // Cloudflare HMR has no main RSC runner (workerd is a separate
-          // runtime). When we have a populated runtime manifest from cold
-          // start, we can re-discover via the temp Node runner — the same
-          // mechanism getOrCreateTempServer() uses at startup. Without a
-          // populated manifest there's nothing useful to do, so bail
-          // before involving the gate machine at all.
-          if (!hasMainRunner && s.perRouterManifests.length === 0) return;
           let previousRouteShape = routeShapeSignature();
           await gate.runRefreshCycle(async () => {
             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,12 +1766,20 @@ 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
-                // re-reads the freshly edited source. Keeping the same
+                // Cloudflare HMR has no main RSC runner (workerd is a separate
+                // runtime): re-discover on the temp Node runner. Invalidate its
+                // RSC module graph (or close+recreate as a fallback) so the
+                // runner re-reads the freshly edited source. Keeping the same
                 // Vite instance alive avoids disrupting workerd's transport
-                // during the first post-cold-start module-fetch window.
+                // during the first post-cold-start module-fetch window. After
+                // a cold start whose temp runner failed there is none, and
+                // getOrCreateTempServer creates one. A recovering cycle needs
+                // no routes-manifest invalidation here: the worker reload below
+                // invalidates its whole module graph.
                 const tempRscEnv = await timed(
                   debugDiscovery,
                   "hmr refreshTempRscEnv (cloudflare)",
@@ -1766,10 +1835,7 @@ export function createRouterDiscoveryPlugin(
                 forceCloudflareWorkerReload(rscEnv, expectedEpoch);
               }
             } catch (err: any) {
-              s.lastDiscoveryError = {
-                message: err?.message ?? String(err),
-                at: Date.now(),
-              };
+              recordDiscoveryFailure(s, err);
               // An invalid transition({ when }) is a definition error the
               // user must see: terminal error plus the browser's Vite overlay,
               // not a warning while the last-good route tree keeps serving.
@@ -1924,16 +1990,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 +2027,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)) {
               // 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 +2044,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 +2188,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 +2228,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)) {
               gate.noteRouteEvent();
             }
             scheduleRouteRegeneration();
@@ -2194,7 +2257,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;
-  }
-}