@rangojs/router 0.17.0 → 0.19.0

package/src/vite/rango.ts

@@ -10,6 +10,7 @@ import {
   exposeRouterId,
 } from "./plugins/expose-internal-ids.js";
 import { useCacheTransform } from "./plugins/use-cache-transform.js";
+import { transitionWhenHoistPlugin } from "./plugins/transition-when-hoist.js";
 import { clientRefDedup } from "./plugins/client-ref-dedup.js";
 import { VIRTUAL_IDS } from "./plugins/virtual-entries.js";
 import {
@@ -563,6 +564,7 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
   });
 
   plugins.push(createLoaderDirectiveGuardPlugin());
+  plugins.push(transitionWhenHoistPlugin());
   plugins.push(createLoaderScanStubPlugin());
   plugins.push(exposeActionId());
   plugins.push(

package/src/vite/router-discovery.ts

@@ -6,7 +6,7 @@
  * generation, virtual module codegen, and bundle post-processing.
  */
 
-import type { Plugin } from "vite";
+import type { Plugin, ViteDevServer } from "vite";
 import { createServer as createViteServer } from "vite";
 import { resolve } from "node:path";
 import { readFileSync } from "node:fs";
@@ -65,6 +65,8 @@ import {
 } from "./discovery/client-urls-projection.js";
 import { runShellPrerenderPhase } from "./discovery/shell-prerender-phase.js";
 import { describeDiscoveryFailure } from "./discovery/discovery-errors.js";
+import { findTransitionWhenError } from "../transition-when-ref.js";
+import { transitionWhenHoistPlugin } from "./plugins/transition-when-hoist.js";
 import {
   createDevPrerenderCache,
   devPrerenderCacheKey,
@@ -177,8 +179,9 @@ const injectedShellNotReadyPaths = new Set<string>();
  * - Build: hashed IDs (forceBuild), hashClientRefs for production bundles
  *
  * Returns the ViteDevServer instance. Callers access .environments.rsc as needed.
+ * @internal Exported for tests.
  */
-async function createTempRscServer(
+export async function createTempRscServer(
   state: DiscoveryState,
   options: {
     forceBuild?: boolean;
@@ -195,7 +198,7 @@ async function createTempRscServer(
      */
     realSsrEntry?: boolean;
   } = {},
-) {
+): Promise<ViteDevServer> {
   // Install the Node ESM loader hook before any module evaluation so
   // `cloudflare:*` specifiers in externalized/loader-delegated modules
   // (e.g. packages plugin-rsc marks as external) resolve to stubs
@@ -216,7 +219,16 @@ async function createTempRscServer(
   return createViteServer({
     root: state.projectRoot,
     configFile: false,
-    server: { middlewareMode: true },
+    server: {
+      middlewareMode: true,
+      // Build mode: no file watching. buildStart installs the per-router tries
+      // into this realm and runShellPrerenderPhase reuses it after the bundles
+      // are written. A watched write in between (writeRouteTypesFiles' own
+      // <router>.named-routes.gen.ts, which every router file imports) can
+      // make Vite full-reload the RSC runner; the shell phase then matches in
+      // a fresh realm with no tries and a root path("/*") wins (#947).
+      ...(options.forceBuild ? { watch: null } : {}),
+    },
     appType: "custom",
     logLevel: "silent",
     resolve: resolveConfig,
@@ -276,6 +288,9 @@ async function createTempRscServer(
         : []),
       createVirtualStubPlugin(),
       createCloudflareProtocolStubPlugin(),
+      // Inline transition({ when }) literals become client references here
+      // too, or discovery would see (and reject) the plain function.
+      transitionWhenHoistPlugin(),
       // 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),
@@ -433,6 +448,37 @@ export function createRouterDiscoveryPlugin(
   let viteCommand: "serve" | "build" = "build";
   let viteMode = "production";
 
+  // Dev: an invalid transition({ when }) is a definition error the user must
+  // see in the browser too, as the Vite error overlay. The overlay does not
+  // survive on its own: a reload clears it, and plugin-rsc closes every
+  // overlay on each "rsc:update" (the edit's own, the gen-file write's), each
+  // followed by the client's RSC refetch. So until a discovery succeeds the
+  // pending error is re-sent to every client that connects and after every
+  // request the dev server answers (configureServer).
+  let transitionWhenOverlay: {
+    message: string;
+    stack: string;
+    plugin: string;
+  } | null = null;
+  const sendTransitionWhenOverlay = (): void => {
+    if (!transitionWhenOverlay) return;
+    (s.devServer?.environments as any)?.client?.hot?.send({
+      type: "error",
+      err: transitionWhenOverlay,
+    });
+  };
+  const showTransitionWhenError = (err: unknown): Error | undefined => {
+    const whenError = findTransitionWhenError(err);
+    if (!whenError) return undefined;
+    transitionWhenOverlay = {
+      message: whenError.message,
+      stack: whenError.stack ?? "",
+      plugin: "@rangojs/router",
+    };
+    sendTransitionWhenOverlay();
+    return whenError;
+  };
+
   return {
     name: "@rangojs/router:discovery",
 
@@ -515,6 +561,32 @@ export function createRouterDiscoveryPlugin(
       if ((globalThis as any).__rscRouterDiscoveryActive) return;
       s.devServer = server;
 
+      (server.environments as any)?.client?.hot?.on?.(
+        "vite:client:connect",
+        (_payload: unknown, client: any) => {
+          if (transitionWhenOverlay) {
+            client?.send?.({ type: "error", err: transitionWhenOverlay });
+          }
+        },
+      );
+      // The http server's "request" event, not a middleware: plugin-rsc
+      // answers page and RSC requests before a middleware added here runs.
+      let overlayResendQueued = false;
+      server.httpServer?.on("request", (req, res) => {
+        // Documents and RSC fetches only (the refetch that follows each
+        // "rsc:update"), one send per burst.
+        const isPage =
+          req.url?.includes("_rsc") === true ||
+          req.headers.accept?.includes("text/html") === true;
+        if (transitionWhenOverlay && isPage && !overlayResendQueued) {
+          overlayResendQueued = true;
+          res.once("close", () => {
+            overlayResendQueued = false;
+            sendTransitionWhenOverlay();
+          });
+        }
+      });
+
       let workerReadyEpoch: number | undefined;
       const publishDevDiscoveryReady = (epoch: number) => {
         if (epoch <= (workerReadyEpoch ?? -1)) return;
@@ -860,6 +932,7 @@ export function createRouterDiscoveryPlugin(
         } else {
           console.error(report.message);
         }
+        showTransitionWhenError(err);
       };
 
       const discover = async () => {
@@ -1473,9 +1546,7 @@ export function createRouterDiscoveryPlugin(
             const body = JSON.stringify({
               entry: result.entry,
               ttl,
-              swr,
               tags: result.tags,
-              routeName,
             });
             devPrerenderCache.set(routerInstance, cacheKey, body);
             res.setHeader("content-type", "application/json");
@@ -1619,6 +1690,7 @@ export function createRouterDiscoveryPlugin(
                 );
                 s.lastDiscoveryError = null;
               }
+              transitionWhenOverlay = null;
               // Cloudflare dev: on a successful cycle drop the workerd runner's
               // cached worker-entry chain so the next request re-evaluates
               // createRouter() with the new routes. Fired here in the work path
@@ -1646,9 +1718,17 @@ export function createRouterDiscoveryPlugin(
                 message: err?.message ?? String(err),
                 at: Date.now(),
               };
-              console.warn(
-                `[rango] Runtime re-discovery failed: ${err.message}`,
-              );
+              // 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.
+              const whenError = showTransitionWhenError(err);
+              if (whenError) {
+                console.error(whenError.message);
+              } else {
+                console.warn(
+                  `[rango] Runtime re-discovery failed: ${err.message}`,
+                );
+              }
               debugDiscovery?.(
                 "hmr: lastDiscoveryError set (%s) — manifest preserved at last-good; recovery mode active (any in-scan source change will trigger rediscovery)",
                 err?.message,

package/dist/types/rsc/transition-gate.d.ts

@@ -1,23 +0,0 @@
-import type { MatchResult } from "../types.js";
-import type { getRequestContext } from "../server/request-context.js";
-import type { OnErrorCallback } from "../types/error-types.js";
-/**
- * Apply transition({ when }) gates to a payload's segments.
- *
- * PPR predicates were evaluated from the manifest before cache lookup and route
- * handlers; their request-specific decisions are projected onto a copy so they
- * never mutate reusable cache/prerender/shell records. Ordinary-route predicates
- * were collected during fresh resolution and are evaluated here after handlers.
- * Both paths drop the segment transition when the predicate does not hold.
- *
- * Mutating the segments here is safe: the segment cache stores a serialized copy
- * (segment-codec), written during match() BEFORE this gate runs, so dropping a
- * transition never corrupts a cache entry. On an ordinary route, a cache hit
- * skips resolution, collects no predicate, and replays the cached transition
- * as-is (it was serialized before the gate). PPR routes are the exception: their
- * manifest predicates were evaluated before lookup and apply to replayed data.
- *
- * Returns the same array for the ordinary post-handler path. A PPR drop returns a
- * copy containing only the request-specific transition changes.
- */
-export declare function gateTransitions(segments: MatchResult["segments"], ctx: ReturnType<typeof getRequestContext>, onError?: OnErrorCallback): MatchResult["segments"];

package/src/rsc/transition-gate.ts

@@ -1,86 +0,0 @@
-import type { MatchResult } from "../types.js";
-import type { getRequestContext } from "../server/request-context.js";
-import { invokeOnError } from "../router/error-handling.js";
-import type { OnErrorCallback } from "../types/error-types.js";
-import { createTransitionWhenContext } from "../router/transition-when.js";
-
-/**
- * Apply transition({ when }) gates to a payload's segments.
- *
- * PPR predicates were evaluated from the manifest before cache lookup and route
- * handlers; their request-specific decisions are projected onto a copy so they
- * never mutate reusable cache/prerender/shell records. Ordinary-route predicates
- * were collected during fresh resolution and are evaluated here after handlers.
- * Both paths drop the segment transition when the predicate does not hold.
- *
- * Mutating the segments here is safe: the segment cache stores a serialized copy
- * (segment-codec), written during match() BEFORE this gate runs, so dropping a
- * transition never corrupts a cache entry. On an ordinary route, a cache hit
- * skips resolution, collects no predicate, and replays the cached transition
- * as-is (it was serialized before the gate). PPR routes are the exception: their
- * manifest predicates were evaluated before lookup and apply to replayed data.
- *
- * Returns the same array for the ordinary post-handler path. A PPR drop returns a
- * copy containing only the request-specific transition changes.
- */
-export function gateTransitions(
-  segments: MatchResult["segments"],
-  ctx: ReturnType<typeof getRequestContext>,
-  onError?: OnErrorCallback,
-): MatchResult["segments"] {
-  const pprDecisions = ctx._pprTransitionDecisions;
-  let gatedSegments = segments;
-
-  const dropTransition = (id: string): void => {
-    const index = gatedSegments.findIndex((segment) => segment.id === id);
-    if (index === -1) return;
-    if (!pprDecisions) {
-      gatedSegments[index].transition = undefined;
-      return;
-    }
-    if (gatedSegments === segments) gatedSegments = [...segments];
-    gatedSegments[index] = {
-      ...gatedSegments[index],
-      transition: undefined,
-    };
-  };
-
-  if (pprDecisions) {
-    for (const [id, keep] of pprDecisions) {
-      if (!keep) dropTransition(id);
-    }
-  }
-  const predicates = ctx._transitionWhen;
-  if (predicates) {
-    for (const { id, when } of predicates) {
-      try {
-        // Assemble the ShouldRevalidateFn-shaped predicate context from the
-        // request context. Source fields (currentUrl/currentParams/fromRouteName)
-        // were stashed at match time from the navigation snapshot; action fields
-        // at the action-bearing gate call sites. nextUrl/nextParams/toRouteName/
-        // method/get/env come straight off ctx (setRequestContextParams ran
-        // before the gate). Source/action fields are undefined when absent —
-        // never fabricated (see TransitionWhenContext).
-        if (when(createTransitionWhenContext(ctx)) !== false) continue;
-      } catch (error) {
-        // A throwing predicate must not fail the response: report it and treat
-        // the transition as gated off (do not hold). invokeOnError no-ops when
-        // onError is undefined.
-        invokeOnError(
-          onError,
-          error,
-          "rendering",
-          {
-            request: ctx.request,
-            url: ctx.url,
-            params: ctx.params,
-            segmentId: id,
-          },
-          "RSC",
-        );
-      }
-      dropTransition(id);
-    }
-  }
-  return gatedSegments;
-}