@rangojs/router 0.0.0-experimental.91 → 0.0.0-experimental.93

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.91",
+  version: "0.0.0-experimental.93",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -3376,11 +3376,10 @@ function createVersionInjectorPlugin(rscEntryPath) {
       if (normalizedId !== normalizedEntry) {
         return null;
       }
-      const prepend = [];
+      const prepend = [
+        `import "virtual:rsc-router/routes-manifest";`
+      ];
       let newCode = code;
-      if (!code.includes("virtual:rsc-router/routes-manifest")) {
-        prepend.push(`import "virtual:rsc-router/routes-manifest";`);
-      }
       const needsVersion = code.includes("createRSCHandler") && !code.includes("@rangojs/router:version") && /createRSCHandler\s*\(\s*\{/.test(code);
       if (needsVersion) {
         prepend.push(`import { VERSION } from "@rangojs/router:version";`);
@@ -3389,8 +3388,21 @@ function createVersionInjectorPlugin(rscEntryPath) {
           "createRSCHandler({\n  version: VERSION,"
         );
       }
-      if (prepend.length === 0 && newCode === code) return null;
-      newCode = prepend.join("\n") + (prepend.length > 0 ? "\n" : "") + newCode;
+      const lines = newCode.split("\n");
+      let insertAt = 0;
+      while (insertAt < lines.length) {
+        const trimmed = lines[insertAt].trim();
+        if (trimmed === "" || /^\/\/\/\s*<reference\b/.test(trimmed)) {
+          insertAt++;
+        } else {
+          break;
+        }
+      }
+      newCode = [
+        ...lines.slice(0, insertAt),
+        ...prepend,
+        ...lines.slice(insertAt)
+      ].join("\n");
       return {
         code: newCode,
         map: null
@@ -3784,6 +3796,12 @@ function markSelfGenWrite(state, filePath, content) {
   state.selfWrittenGenFiles.set(filePath, { at: Date.now(), hash });
 }
 function consumeSelfGenWrite(state, filePath) {
+  return checkSelfGenWrite(state, filePath, true);
+}
+function peekSelfGenWrite(state, filePath) {
+  return checkSelfGenWrite(state, filePath, false);
+}
+function checkSelfGenWrite(state, filePath, consume) {
   const info = state.selfWrittenGenFiles.get(filePath);
   if (!info) return false;
   if (Date.now() - info.at > state.SELF_WRITE_WINDOW_MS) {
@@ -3794,7 +3812,7 @@ function consumeSelfGenWrite(state, filePath) {
     const current = readFileSync3(filePath, "utf-8");
     const currentHash = createHash3("sha256").update(current).digest("hex");
     if (currentHash === info.hash) {
-      state.selfWrittenGenFiles.delete(filePath);
+      if (consume) state.selfWrittenGenFiles.delete(filePath);
       return true;
     }
     return false;
@@ -5067,6 +5085,80 @@ function postprocessBundle(state) {
   }
 }
 
+// src/vite/discovery/gate-state.ts
+function createDiscoveryGate(s, debug11) {
+  let gatePending = false;
+  let gateResolver = () => {
+  };
+  let inProgress = false;
+  let queued = false;
+  let pendingEvents = false;
+  const beginGate = () => {
+    if (gatePending) return;
+    s.discoveryDone = new Promise((resolve10) => {
+      gateResolver = resolve10;
+    });
+    gatePending = true;
+  };
+  const resolveGate = () => {
+    if (!gatePending) return;
+    if (inProgress || queued || pendingEvents) {
+      debug11?.(
+        "hmr: resolveGate deferred \u2014 work in flight (inProgress=%s queued=%s pendingEvents=%s)",
+        inProgress,
+        queued,
+        pendingEvents
+      );
+      return;
+    }
+    gatePending = false;
+    debug11?.("hmr: discoveryDone resolved");
+    gateResolver();
+  };
+  const noteRouteEvent = () => {
+    pendingEvents = true;
+    beginGate();
+  };
+  const runRefreshCycle = async (work) => {
+    if (inProgress) {
+      queued = true;
+      debug11?.("hmr: rediscovery in flight \u2014 queued for a follow-up cycle");
+      return;
+    }
+    pendingEvents = false;
+    inProgress = true;
+    try {
+      await work();
+    } finally {
+      inProgress = false;
+      if (queued) {
+        queued = false;
+        debug11?.("hmr: consuming queued rediscovery");
+        runRefreshCycle(work).catch((err) => {
+          debug11?.(
+            "hmr: queued cycle rejected \u2014 releasing gate (%s)",
+            err instanceof Error ? err.message : String(err)
+          );
+          resolveGate();
+        });
+      } else if (pendingEvents) {
+        debug11?.(
+          "hmr: holding gate for pending events (debounce not yet fired)"
+        );
+      } else {
+        resolveGate();
+      }
+    }
+  };
+  return {
+    beginGate,
+    resolveGate,
+    noteRouteEvent,
+    runRefreshCycle,
+    state: () => ({ gatePending, inProgress, queued, pendingEvents })
+  };
+}
+
 // src/vite/router-discovery.ts
 var debugDiscovery = createRangoDebugger(NS.discovery);
 var debugRoutes = createRangoDebugger(NS.routes);
@@ -5231,6 +5323,9 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
       const discoveryPromise = new Promise((resolve10) => {
         resolveDiscovery = resolve10;
       });
+      const gate = createDiscoveryGate(s, debugDiscovery);
+      const beginDiscoveryGate = gate.beginGate;
+      const resolveDiscoveryGate = gate.resolveGate;
       const getDevServerOrigin = () => server.resolvedUrls?.local?.[0]?.replace(/\/$/, "") || `http://localhost:${server.config.server.port || 5173}`;
       let prerenderTempServer = null;
       let prerenderNodeRegistry = null;
@@ -5243,35 +5338,157 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
         releaseBuildEnv(s).catch(() => {
         });
       });
+      async function importEntryAndRegistry(tempRscEnv) {
+        const flagAlreadySet = !!globalThis.__rscRouterDiscoveryActive;
+        if (!flagAlreadySet) {
+          globalThis.__rscRouterDiscoveryActive = true;
+        }
+        try {
+          debugDiscovery?.(
+            "importEntryAndRegistry: importing entry (flag=%s)",
+            globalThis.__rscRouterDiscoveryActive ?? false
+          );
+          await tempRscEnv.runner.import(s.resolvedEntryPath);
+          debugDiscovery?.(
+            "importEntryAndRegistry: entry import OK, fetching RouterRegistry"
+          );
+          const serverMod = await tempRscEnv.runner.import(
+            "@rangojs/router/server"
+          );
+          prerenderNodeRegistry = serverMod.RouterRegistry;
+          debugDiscovery?.(
+            "importEntryAndRegistry: registry size=%d",
+            prerenderNodeRegistry?.size ?? 0
+          );
+        } finally {
+          if (!flagAlreadySet) {
+            delete globalThis.__rscRouterDiscoveryActive;
+            debugDiscovery?.(
+              "importEntryAndRegistry: cleared __rscRouterDiscoveryActive"
+            );
+          }
+        }
+      }
       async function getOrCreateTempServer() {
-        if (prerenderNodeRegistry) {
-          return prerenderTempServer.environments?.rsc ?? null;
+        if (prerenderTempServer) {
+          const existingEnv = prerenderTempServer.environments?.rsc;
+          if (existingEnv?.runner) {
+            if (prerenderNodeRegistry) {
+              debugDiscovery?.(
+                "getOrCreateTempServer: cached temp runner reused"
+              );
+              return existingEnv;
+            }
+            debugDiscovery?.(
+              "getOrCreateTempServer: server alive but registry missing \u2014 re-importing"
+            );
+            try {
+              await importEntryAndRegistry(existingEnv);
+              return existingEnv;
+            } catch (err) {
+              debugDiscovery?.(
+                "getOrCreateTempServer: reuse import failed (%s) \u2014 closing orphan and creating fresh",
+                err?.message ?? String(err)
+              );
+              await prerenderTempServer.close().catch(() => {
+              });
+              prerenderTempServer = null;
+              prerenderNodeRegistry = null;
+            }
+          } else {
+            debugDiscovery?.(
+              "getOrCreateTempServer: existing server has no rsc.runner \u2014 closing and recreating"
+            );
+            await prerenderTempServer.close().catch(() => {
+            });
+            prerenderTempServer = null;
+            prerenderNodeRegistry = null;
+          }
         }
+        debugDiscovery?.(
+          "getOrCreateTempServer: creating new temp server, entry=%s",
+          s.resolvedEntryPath ?? "(unset)"
+        );
         try {
           prerenderTempServer = await createTempRscServer(s, {
             cacheDir: "node_modules/.vite_prerender"
           });
           const tempRscEnv = prerenderTempServer.environments?.rsc;
           if (tempRscEnv?.runner) {
-            await tempRscEnv.runner.import(s.resolvedEntryPath);
-            const serverMod = await tempRscEnv.runner.import(
-              "@rangojs/router/server"
-            );
-            prerenderNodeRegistry = serverMod.RouterRegistry;
+            await importEntryAndRegistry(tempRscEnv);
             return tempRscEnv;
           }
+          debugDiscovery?.(
+            "getOrCreateTempServer: tempRscEnv.runner unavailable"
+          );
         } catch (err) {
+          debugDiscovery?.(
+            "getOrCreateTempServer: FAILED message=%s",
+            err.message
+          );
           console.warn(
             `[rsc-router] Failed to create temp runner: ${err.message}`
           );
         }
         return null;
       }
+      async function clearTempRegistries(tempRscEnv) {
+        try {
+          const serverMod = await tempRscEnv.runner.import(
+            "@rangojs/router/server"
+          );
+          if (typeof serverMod?.RouterRegistry?.clear === "function") {
+            serverMod.RouterRegistry.clear();
+          }
+          if (typeof serverMod?.HostRouterRegistry?.clear === "function") {
+            serverMod.HostRouterRegistry.clear();
+          }
+          debugDiscovery?.(
+            "clearTempRegistries: cleared RouterRegistry + HostRouterRegistry"
+          );
+        } catch (err) {
+          debugDiscovery?.(
+            "clearTempRegistries: import @rangojs/router/server failed (%s)",
+            err?.message ?? String(err)
+          );
+        }
+      }
+      async function refreshTempRscEnv() {
+        let tempRscEnv = await getOrCreateTempServer();
+        if (!tempRscEnv) return null;
+        const envGraph = tempRscEnv.moduleGraph;
+        const serverGraph = prerenderTempServer?.moduleGraph;
+        const target = envGraph?.invalidateAll ? envGraph : serverGraph?.invalidateAll ? serverGraph : null;
+        if (!target) {
+          debugDiscovery?.(
+            "refreshTempRscEnv: invalidateAll unavailable on env+server graphs, falling back to close+recreate"
+          );
+          if (prerenderTempServer) {
+            await prerenderTempServer.close().catch(() => {
+            });
+            prerenderTempServer = null;
+            prerenderNodeRegistry = null;
+          }
+          return await getOrCreateTempServer();
+        }
+        debugDiscovery?.(
+          "refreshTempRscEnv: invalidating module graph (%s)",
+          envGraph?.invalidateAll ? "env" : "server"
+        );
+        target.invalidateAll();
+        prerenderNodeRegistry = null;
+        await clearTempRegistries(tempRscEnv);
+        await importEntryAndRegistry(tempRscEnv);
+        return tempRscEnv;
+      }
       const discover = async () => {
         const discoverStart = performance.now();
         const rscEnv = server.environments?.rsc;
         if (!rscEnv?.runner) {
-          debugDiscovery?.("dev: no rsc runner (cloudflare path)");
+          debugDiscovery?.(
+            "dev: cloudflare path start, __rscRouterDiscoveryActive=%s",
+            globalThis.__rscRouterDiscoveryActive ?? false
+          );
           s.devServerOrigin = getDevServerOrigin();
           try {
             await timed(
@@ -5353,9 +5570,11 @@ ${err.stack}`
           resolveDiscovery();
         }
       };
-      s.discoveryDone = new Promise((resolve10) => {
-        setTimeout(() => discover().then(resolve10, resolve10), 0);
-      });
+      beginDiscoveryGate();
+      setTimeout(
+        () => discover().then(resolveDiscoveryGate, resolveDiscoveryGate),
+        0
+      );
       let mainRegistry = null;
       const propagateDiscoveryState = async (rscEnv) => {
         const serverMod = await rscEnv.runner.import("@rangojs/router/server");
@@ -5504,49 +5723,80 @@ ${err.stack}`
           return true;
         };
         let routeChangeTimer;
-        let runtimeRediscoveryInProgress = false;
         const refreshRuntimeDiscovery = async () => {
           const rscEnv = server.environments?.rsc;
-          if (!rscEnv?.runner || runtimeRediscoveryInProgress) return;
-          runtimeRediscoveryInProgress = true;
-          const hmrStart = performance.now();
-          try {
-            await timed(
-              debugDiscovery,
-              "hmr discoverRouters",
-              () => discoverRouters(s, rscEnv)
-            );
-            timedSync(
-              debugDiscovery,
-              "hmr writeRouteTypesFiles",
-              () => writeRouteTypesFiles(s)
-            );
-            await timed(
-              debugDiscovery,
-              "hmr propagateDiscoveryState",
-              () => propagateDiscoveryState(rscEnv)
-            );
-          } catch (err) {
-            console.warn(
-              `[rsc-router] Runtime re-discovery failed: ${err.message}`
-            );
-          } finally {
-            debugDiscovery?.(
-              "hmr re-discovery done (%sms)",
-              (performance.now() - hmrStart).toFixed(1)
-            );
-            runtimeRediscoveryInProgress = false;
-          }
+          const hasMainRunner = !!rscEnv?.runner;
+          if (!hasMainRunner && s.perRouterManifests.length === 0) return;
+          await gate.runRefreshCycle(async () => {
+            const hmrStart = performance.now();
+            try {
+              if (hasMainRunner) {
+                await timed(
+                  debugDiscovery,
+                  "hmr discoverRouters",
+                  () => discoverRouters(s, rscEnv)
+                );
+                timedSync(
+                  debugDiscovery,
+                  "hmr writeRouteTypesFiles",
+                  () => writeRouteTypesFiles(s)
+                );
+                await timed(
+                  debugDiscovery,
+                  "hmr propagateDiscoveryState",
+                  () => propagateDiscoveryState(rscEnv)
+                );
+              } else {
+                const tempRscEnv = await timed(
+                  debugDiscovery,
+                  "hmr refreshTempRscEnv (cloudflare)",
+                  () => refreshTempRscEnv()
+                );
+                if (!tempRscEnv) {
+                  throw new Error(
+                    "temp runner unavailable for cloudflare HMR rediscovery"
+                  );
+                }
+                await timed(
+                  debugDiscovery,
+                  "hmr discoverRouters (cloudflare)",
+                  () => discoverRouters(s, tempRscEnv)
+                );
+                timedSync(
+                  debugDiscovery,
+                  "hmr writeRouteTypesFiles",
+                  () => writeRouteTypesFiles(s)
+                );
+              }
+            } catch (err) {
+              console.warn(
+                `[rsc-router] Runtime re-discovery failed: ${err.message}`
+              );
+            } finally {
+              debugDiscovery?.(
+                "hmr re-discovery done (%sms)",
+                (performance.now() - hmrStart).toFixed(1)
+              );
+            }
+          });
         };
         const scheduleRouteRegeneration = () => {
           clearTimeout(routeChangeTimer);
           routeChangeTimer = setTimeout(() => {
             routeChangeTimer = void 0;
             const regenStart = debugDiscovery ? performance.now() : 0;
+            const rscEnv = server.environments?.rsc;
+            const skipStaticWrite = !rscEnv?.runner && s.perRouterManifests.length > 0;
             try {
-              writeCombinedRouteTypesWithTracking(s);
-              if (s.perRouterManifests.length > 0) {
-                supplementGenFilesWithRuntimeRoutes(s);
+              if (skipStaticWrite) {
+                debugDiscovery?.(
+                  "watcher: skipping static write (cloudflare HMR \u2014 runtime rediscovery owns gen file)"
+                );
+              } else {
+                writeCombinedRouteTypesWithTracking(s);
+                if (s.perRouterManifests.length > 0) {
+                  supplementGenFilesWithRuntimeRoutes(s);
+                }
               }
             } catch (err) {
               console.error(
@@ -5562,6 +5812,7 @@ ${err.stack}`
                 console.warn(
                   `[rsc-router] Runtime re-discovery error: ${err.message}`
                 );
+                resolveDiscoveryGate();
               });
             }
           }, 100);
@@ -5598,6 +5849,9 @@ ${err.stack}`
               }
               s.cachedRouterFiles = void 0;
             }
+            if (s.perRouterManifests.length > 0) {
+              gate.noteRouteEvent();
+            }
             scheduleRouteRegeneration();
           } catch {
           }
@@ -5696,6 +5950,34 @@ ${details}`
         );
       }
     },
+    // Suppress vite's HMR cascade for our own gen-file writes.
+    //
+    // After every cf HMR cycle, refreshTempRscEnv → writeRouteTypesFiles
+    // writes the configured gen files (default `router.named-routes.gen.ts`,
+    // but the source filenames and gen suffix are user-configurable). The
+    // chokidar watcher then fires twice independently: our
+    // `handleRouteFileChange` (already short-circuited by
+    // `consumeSelfGenWrite` inside `maybeHandleGeneratedRouteFileMutation`),
+    // AND vite's own HMR pipeline (which invalidates the gen file's
+    // importers and triggers a second workerd full reload — visible to the
+    // user as a duplicate "[RSCRouter] HMR: version changed" on the client).
+    //
+    // `peekSelfGenWrite` is the authoritative filter: its map only contains
+    // paths that `markSelfGenWrite` has registered, so it natively works
+    // for any configured gen-file name. It is non-consuming so the chokidar
+    // handler that fires later can still consume the same entry. Returning
+    // [] tells vite "no modules invalidated by this change" — safe because
+    // `s.perRouterManifests` is already up-to-date (the write that just
+    // happened is the consequence of our just-completed rediscovery).
+    handleHotUpdate(ctx) {
+      if (peekSelfGenWrite(s, ctx.file)) {
+        debugDiscovery?.(
+          "handleHotUpdate: suppressing self-write HMR cascade for %s",
+          ctx.file
+        );
+        return [];
+      }
+    },
     // Virtual module: provides the pre-generated route manifest as a JS module
     // that calls setCachedManifest() at import time.
     resolveId(id) {

package/package.json

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

package/skills/loader/SKILL.md

@@ -248,6 +248,37 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
 ]);
 ```
 
+### `revalidate()` return shapes
+
+A `revalidate(fn)` callback can return one of four shapes. The chain
+processes revalidators in order; each call's return controls how the
+chain continues:
+
+```typescript
+// 1) Hard decision — short-circuits the chain, used as the final answer.
+revalidate(() => true);
+revalidate(({ actionId }) => actionId?.includes("Cart") ?? false);
+
+// 2) Soft decision — updates the running suggestion for downstream
+//    revalidators on the same segment, chain continues.
+revalidate(({ defaultShouldRevalidate }) => ({
+  defaultShouldRevalidate: !defaultShouldRevalidate,
+}));
+
+// 3) Defer (no opinion) — leaves the running suggestion unchanged and
+//    continues to the next revalidator. Implicit return / null /
+//    undefined are all equivalent and consumer-friendly.
+revalidate(({ actionId }) => {
+  if (actionId?.includes("Cart")) return true; // hard for this branch only
+  // implicit return — let downstream revalidators or the segment default decide
+});
+revalidate(() => undefined); // explicit defer
+revalidate(() => null); // explicit defer
+```
+
+If every revalidator on a segment defers, the segment-type default
+(e.g. params-changed for routes, `false` for parallels) is used.
+
 ### Revalidation Contracts for Loader Dependencies
 
 If a loader reads `ctx.get()` data produced by an outer handler/layout, share

package/skills/parallel/SKILL.md

@@ -347,6 +347,13 @@ Revalidating only the parallel does not re-run outer handlers/layouts.
 If the slot reads `ctx.get()` data established above it, opt the outer
 segment into revalidation as well.
 
+A `revalidate()` callback may return a hard `boolean`, a soft
+`{ defaultShouldRevalidate }` object, or nothing (`void` / `null` /
+`undefined`) to defer to the next revalidator. See
+[loader/SKILL.md#revalidate-return-shapes](../loader/SKILL.md#revalidate-return-shapes)
+for the full contract — it's the same across `loader()`, `path()`,
+`layout()`, `parallel()`, and `intercept()`.
+
 ### Revalidation Contracts for Parallel Dependencies
 
 Prefer named revalidation contracts shared by both the upstream producer and

package/src/route-definition/helpers-types.ts

@@ -259,7 +259,12 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    *   ({ defaultShouldRevalidate: true })
    * )
    * ```
-   * @param fn - Function that returns boolean (hard) or { defaultShouldRevalidate } (soft)
+   * @param fn - Function returning either:
+   *   - `boolean` (hard decision — short-circuits the chain),
+   *   - `{ defaultShouldRevalidate: boolean }` (soft — updates the suggestion
+   *     for downstream revalidators),
+   *   - or nothing / `null` / `undefined` (defer — leaves the suggestion
+   *     unchanged and continues to the next revalidator).
    */
   revalidate: (fn: ShouldRevalidateFn<any, TEnv>) => RevalidateItem;
   /**

package/src/types/handler-context.ts

@@ -471,13 +471,16 @@ export type RevalidateParams<TParams = GenericParams, TEnv = any> = Parameters<
  * **Return Types:**
  * - `boolean` - Hard decision: immediately returns this value (short-circuits)
  * - `{ defaultShouldRevalidate: boolean }` - Soft decision: updates suggestion for next revalidator
+ * - `void` / `null` / `undefined` - Defer to the current suggestion (no opinion); the
+ *   loop continues to the next revalidator without changing the running default
  *
  * **Execution Flow:**
  * 1. Start with built-in `defaultShouldRevalidate` (true if params changed)
  * 2. Execute global revalidators first, then route-specific
  * 3. Hard decision (boolean): stop immediately and use that value
  * 4. Soft decision (object): update suggestion and continue to next revalidator
- * 5. If all return soft decisions: use the final suggestion
+ * 5. Defer (`void` / `null` / `undefined`): leave suggestion unchanged and continue
+ * 6. If no hard decision was returned: use the final running suggestion
  *
  * @param args.currentParams - Previous route params (generic by default, can be narrowed)
  * @param args.currentUrl - Previous URL
@@ -489,7 +492,8 @@ export type RevalidateParams<TParams = GenericParams, TEnv = any> = Parameters<
  * @param args.formData - Form data from action (future support)
  * @param args.formMethod - HTTP method from action (future support)
  *
- * @returns Hard decision (boolean) or soft suggestion (object)
+ * @returns Hard decision (boolean), soft suggestion (object), or defer
+ *   (`void` / `null` / `undefined`) to keep the running suggestion as-is.
  *
  * @example
  * ```typescript
@@ -514,8 +518,9 @@ export type RevalidateParams<TParams = GenericParams, TEnv = any> = Parameters<
  * a segment (layout, route, parallel slot, or loader) should be re-rendered.
  *
  * Return `true` to re-render, `false` to skip (keep client's current version),
- * or `{ defaultShouldRevalidate: boolean }` to override the default for
- * downstream segments.
+ * `{ defaultShouldRevalidate: boolean }` to update the running suggestion for
+ * downstream revalidators, or nothing (`void` / `null` / `undefined`) to defer
+ * to the current suggestion without changing it.
  *
  * @example
  * ```ts
@@ -615,7 +620,7 @@ export type ShouldRevalidateFn<TParams = GenericParams, TEnv = any> = (args: {
    * action that may have mutated backend state.
    */
   stale?: boolean;
-}) => boolean | { defaultShouldRevalidate: boolean };
+}) => boolean | { defaultShouldRevalidate: boolean } | null | void;
 
 // MiddlewareFn is imported from "../router/middleware.js" and re-exported