@rangojs/router 0.0.0-experimental.98 → 0.0.0-experimental.98914650

package/src/router/params-util.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared route-param comparison helpers.
+ */
+
+/**
+ * Shallow equality for two route-param records. Same-reference is a fast path;
+ * otherwise compares key count then each value.
+ */
+export function paramsEqual(
+  a: Record<string, string>,
+  b: Record<string, string>,
+): boolean {
+  if (a === b) return true;
+
+  const keysA = Object.keys(a);
+  if (keysA.length !== Object.keys(b).length) return false;
+
+  for (const key of keysA) {
+    if (a[key] !== b[key]) return false;
+  }
+
+  return true;
+}

package/src/router/pattern-matching.ts

@@ -33,13 +33,6 @@ export interface ParsedSegment {
  */
 export function parsePattern(pattern: string): ParsedSegment[] {
   const segments: ParsedSegment[] = [];
-  // Match: /segment where segment can be:
-  // - static text
-  // - :param
-  // - :param?
-  // - :param(a|b)
-  // - :param(a|b)?
-  // - *
   const segmentRegex =
     /\/(:([a-zA-Z_][a-zA-Z0-9_]*)(\(([^)]+)\))?(\?)?([^/]*)|(\*)|([^/]+))/g;
 
@@ -81,7 +74,6 @@ export function parsePattern(pattern: string): ParsedSegment[] {
 export interface CompiledPattern {
   regex: RegExp;
   paramNames: string[];
-  optionalParams: Set<string>;
   hasTrailingSlash: boolean;
   /**
    * Param-name → allowed values for constrained params (e.g. `:lang(en|gb)`).
@@ -149,7 +141,6 @@ export function compilePattern(pattern: string): CompiledPattern {
 
   const segments = parsePattern(normalizedPattern);
   const paramNames: string[] = [];
-  const optionalParams = new Set<string>();
   let constraints: Record<string, string[]> | undefined;
 
   let regexPattern = "";
@@ -171,7 +162,6 @@ export function compilePattern(pattern: string): CompiledPattern {
       }
 
       if (segment.optional) {
-        optionalParams.add(segment.value);
         // Optional: make the whole /segment optional
         regexPattern += `(?:/${valuePattern}${suffixPattern})?`;
       } else {
@@ -183,7 +173,6 @@ export function compilePattern(pattern: string): CompiledPattern {
     }
   }
 
-  // Handle root path
   if (regexPattern === "") {
     regexPattern = "/";
   }
@@ -210,7 +199,6 @@ export function compilePattern(pattern: string): CompiledPattern {
   return {
     regex: new RegExp(`^${regexPattern}$`),
     paramNames,
-    optionalParams,
     hasTrailingSlash,
     ...(constraints ? { constraints } : {}),
   };
@@ -285,7 +273,6 @@ function buildParamsFromMatch(
 export function extractStaticPrefix(pattern: string): string {
   if (!pattern || pattern === "/") return "";
 
-  // Find the first occurrence of : or *
   const paramIndex = pattern.indexOf(":");
   const wildcardIndex = pattern.indexOf("*");
 
@@ -299,16 +286,13 @@ export function extractStaticPrefix(pattern: string): string {
   }
 
   if (cutIndex === -1) {
-    // No params or wildcards - entire pattern is static
     return pattern;
   }
 
   if (cutIndex === 0) {
-    // Pattern starts with : or * - no static prefix
     return "";
   }
 
-  // Find the last / before the param
   const lastSlash = pattern.lastIndexOf("/", cutIndex - 1);
   if (lastSlash === -1 || lastSlash === 0) {
     return "";
@@ -317,13 +301,28 @@ export function extractStaticPrefix(pattern: string): string {
   return pattern.slice(0, lastSlash);
 }
 
+/**
+ * Join a URL prefix to a sub-prefix, collapsing the duplicate slash when the
+ * base ends with "/" and the sub-prefix starts with "/". This mirrors the
+ * canonical join in `include()` (urls/include-helper.ts) and `runWithPrefixes`
+ * (server/context.ts) so a nested lazy include's runtime staticPrefix matches
+ * the build-time trie's `sp` (e.g. `include("/parent/", …)` containing
+ * `include("/child", …)` resolves to `/parent/child`, not `/parent//child`).
+ */
+export function joinPrefix(base: string | undefined, prefix: string): string {
+  if (!base) return prefix;
+  return base.endsWith("/") && prefix.startsWith("/")
+    ? base + prefix.slice(1)
+    : base + prefix;
+}
+
 /**
  * Match a pathname against registered routes
  *
  * Note: Optional params that are absent in the path are omitted from the
  * returned `params` (read as `undefined`), matching the trie matcher and
- * the `ExtractParams<"/:locale?/...">` type. Use the pattern definition or
- * `optionalParams` to determine which keys are optional.
+ * the `ExtractParams<"/:locale?/...">` type. Use the pattern definition to
+ * determine which keys are optional.
  *
  * Trailing slash handling (priority order):
  * 1. Per-route `trailingSlash` config from route()
@@ -341,10 +340,7 @@ export interface RouteMatchResult<TEnv = any> {
   entry: RouteEntry<TEnv>;
   routeKey: string;
   params: Record<string, string>;
-  optionalParams: Set<string>;
   redirectTo?: string;
-  /** Ancestry shortCodes for layout pruning (from trie match) */
-  ancestry?: string[];
   /** Route has pre-rendered data available (from trie) */
   pr?: true;
   /** Passthrough: handler kept for live fallback on unknown params (from trie) */
@@ -422,8 +418,6 @@ export function findMatch<TEnv>(
     : pathname + "/";
 
   for (const entry of routesEntries) {
-    // Short-circuit: skip entry if pathname doesn't start with static prefix
-    // staticPrefix is pre-computed at registration time, so this is O(1)
     if (entry.staticPrefix && !pathname.startsWith(entry.staticPrefix)) {
       if (effectiveDebug) {
         debugStats.entriesSkipped++;
@@ -435,8 +429,6 @@ export function findMatch<TEnv>(
       continue;
     }
 
-    // Check if this is a lazy entry that needs evaluation
-    // When staticPrefix matches but routes are not yet populated, signal caller to evaluate
     if (entry.lazy && !entry.lazyEvaluated) {
       if (effectiveDebug) {
         debugLog("findMatch", "lazy entry requires evaluation", {
@@ -457,7 +449,6 @@ export function findMatch<TEnv>(
         debugStats.routesChecked++;
       }
 
-      // Join prefix and pattern, handling edge cases
       let fullPattern: string;
       if (entry.prefix === "" || entry.prefix === "/") {
         fullPattern = pattern;
@@ -467,19 +458,12 @@ export function findMatch<TEnv>(
         fullPattern = entry.prefix + pattern;
       }
 
-      const {
-        regex,
-        paramNames,
-        optionalParams,
-        hasTrailingSlash,
-        constraints,
-      } = getCompiledPattern(fullPattern);
+      const { regex, paramNames, hasTrailingSlash, constraints } =
+        getCompiledPattern(fullPattern);
 
-      // Get trailing slash mode for this route (per-route config or pattern-based)
       const trailingSlashMode: TrailingSlashMode | undefined =
         entry.trailingSlash?.[routeKey];
 
-      // Prerender flag from entry metadata (set by urls() for prerender handlers)
       const prFlag = entry.prerenderRouteKeys?.has(routeKey)
         ? { pr: true as const }
         : {};
@@ -487,13 +471,10 @@ export function findMatch<TEnv>(
         ? { pt: true as const }
         : {};
 
-      // Try exact match first
       const match = regex.exec(pathname);
       if (match) {
         const params = buildParamsFromMatch(match, paramNames);
 
-        // Validate constraints against decoded values; a failure falls
-        // through to the next route so other patterns can still match.
         if (!satisfiesConstraints(params, constraints)) {
           continue;
         }
@@ -506,29 +487,24 @@ export function findMatch<TEnv>(
           });
         }
 
-        // Check if trailing slash mode requires redirect even on exact match
         if (
           trailingSlashMode === "always" &&
           !pathnameHasTrailingSlash &&
           pathname !== "/"
         ) {
-          // Mode says always have trailing slash, but pathname doesn't have it
           return {
             entry,
             routeKey,
             params,
-            optionalParams,
             redirectTo: pathname + "/",
             ...prFlag,
             ...ptFlag,
           };
         } else if (trailingSlashMode === "never" && pathnameHasTrailingSlash) {
-          // Mode says never have trailing slash, but pathname has it
           return {
             entry,
             routeKey,
             params,
-            optionalParams,
             redirectTo: pathname.slice(0, -1),
             ...prFlag,
             ...ptFlag,
@@ -539,13 +515,11 @@ export function findMatch<TEnv>(
           entry,
           routeKey,
           params,
-          optionalParams,
           ...prFlag,
           ...ptFlag,
         };
       }
 
-      // Try alternate pathname (opposite trailing slash)
       const altMatch = regex.exec(alternatePathname);
       if (altMatch) {
         const params = buildParamsFromMatch(altMatch, paramNames);
@@ -554,25 +528,20 @@ export function findMatch<TEnv>(
           continue;
         }
 
-        // Determine redirect behavior based on mode
         if (trailingSlashMode === "ignore") {
-          // Match without redirect
           return {
             entry,
             routeKey,
             params,
-            optionalParams,
             ...prFlag,
             ...ptFlag,
           };
         } else if (trailingSlashMode === "never") {
-          // Redirect to no trailing slash
           if (pathnameHasTrailingSlash) {
             return {
               entry,
               routeKey,
               params,
-              optionalParams,
               redirectTo: alternatePathname,
               ...prFlag,
               ...ptFlag,
@@ -582,18 +551,15 @@ export function findMatch<TEnv>(
             entry,
             routeKey,
             params,
-            optionalParams,
             ...prFlag,
             ...ptFlag,
           };
         } else if (trailingSlashMode === "always") {
-          // Redirect to with trailing slash
           if (!pathnameHasTrailingSlash) {
             return {
               entry,
               routeKey,
               params,
-              optionalParams,
               redirectTo: alternatePathname,
               ...prFlag,
               ...ptFlag,
@@ -603,13 +569,10 @@ export function findMatch<TEnv>(
             entry,
             routeKey,
             params,
-            optionalParams,
             ...prFlag,
             ...ptFlag,
           };
         } else {
-          // No explicit mode - use pattern-based detection
-          // Redirect to canonical form (what the pattern defines)
           const canonicalPath = hasTrailingSlash
             ? alternatePathname
             : pathname.slice(0, -1);
@@ -617,7 +580,6 @@ export function findMatch<TEnv>(
             entry,
             routeKey,
             params,
-            optionalParams,
             redirectTo: canonicalPath,
             ...prFlag,
             ...ptFlag,
@@ -638,7 +600,7 @@ export function* traverseBack(entry: EntryData): Generator<EntryData> {
   let current: EntryData | null = entry;
   const items = [] as EntryData[];
   while (current !== null) {
-    items.push(current); // Move up to next parent
+    items.push(current);
     current = current.parent;
   }
   for (let i = items.length - 1; i >= 0; i--) {

package/src/router/prerender-match.ts

@@ -5,13 +5,13 @@ import {
   runWithRequestContext,
   type RequestContext,
 } from "../server/request-context.js";
-import { contextGet, contextSet } from "../context-var.js";
+import { contextGet, contextSet, hasContextVars } from "../context-var.js";
 import {
   createPrerenderContext,
   createStaticContext,
   createReverseFunction,
 } from "./handler-context.js";
-import { isPrerenderPassthrough } from "../prerender.js";
+import { detectPrerenderPassthrough } from "../prerender.js";
 import { isRouteRootScoped } from "../route-map-builder.js";
 import { setupBuildUse } from "./loader-resolution.js";
 import { loadManifest } from "./manifest.js";
@@ -59,11 +59,16 @@ export async function matchForPrerender<TEnv = any>(
   devMode?: boolean,
 ): Promise<{
   segments: SerializedSegmentData[];
-  handles: Record<string, SegmentHandleData>;
+  /** RSC-encoded handle map ("" when none) — see handle-snapshot.ts. Encoded in
+   *  the producer (where the Flight codec resolves) so the node-side build/dev
+   *  sinks can persist it without touching the codec. */
+  handles: string;
   routeName: string;
   params: Record<string, string>;
   interceptSegments?: SerializedSegmentData[];
-  interceptHandles?: Record<string, SegmentHandleData>;
+  /** RSC-encoded MERGED (main + intercept) handle map for the intercept artifact;
+   *  the sinks store it as-is (no longer merge raw records). */
+  interceptHandles?: string;
   passthrough?: true;
 } | null> {
   // 1. Find the matching route entry
@@ -77,6 +82,17 @@ export async function matchForPrerender<TEnv = any>(
   // Build RouterContext for loadManifest/traverseBack
   const routerCtx = deps.buildRouterContext();
 
+  // Passthrough sentinel result: an unknown-param Passthrough route falls
+  // through to the live handler at runtime, so no artifact is baked. A fresh
+  // object is returned per call (no site mutates or identity-compares it).
+  const passthroughResult = () => ({
+    segments: [],
+    handles: "",
+    routeName: matched.routeKey,
+    params: matchedParams,
+    passthrough: true as const,
+  });
+
   return runWithRouterContext(routerCtx, async () => {
     // 2. Load the manifest entry tree
     const manifestEntry = await loadManifest(
@@ -126,7 +142,7 @@ export async function matchForPrerender<TEnv = any>(
             get env() {
               if (buildEnv !== undefined) return buildEnv;
               throw new Error(
-                "[rsc-router] ctx.env is not available during dev-mode getParams(). " +
+                "[rango] ctx.env is not available during dev-mode getParams(). " +
                   "Configure buildEnv in your rango() plugin options to enable build-time env access.",
               );
             },
@@ -140,19 +156,10 @@ export async function matchForPrerender<TEnv = any>(
             );
           });
           if (!isKnown) {
-            return {
-              segments: [],
-              handles: {},
-              routeName: matched.routeKey,
-              params: matchedParams,
-              passthrough: true as const,
-            };
+            return passthroughResult();
           }
           // Preserve vars set by getParams() for the render context
-          if (
-            Object.keys(probeBuildVars).length > 0 ||
-            Object.getOwnPropertySymbols(probeBuildVars).length > 0
-          ) {
+          if (hasContextVars(probeBuildVars)) {
             devProbeBuildVars = probeBuildVars;
           }
         } catch (err: any) {
@@ -160,13 +167,7 @@ export async function matchForPrerender<TEnv = any>(
           // Skip errors are intentional — treat as passthrough.
           // All other errors propagate so dev surfaces them.
           if (err?.name === "Skip") {
-            return {
-              segments: [],
-              handles: {},
-              routeName: matched.routeKey,
-              params: matchedParams,
-              passthrough: true as const,
-            };
+            return passthroughResult();
           }
           throw err;
         }
@@ -206,11 +207,14 @@ export async function matchForPrerender<TEnv = any>(
       header: () => {},
       setStatus: () => {},
       _setStatus: () => {},
+      _rotateStateCookie: () => {},
+      _setKeepCacheDirective: () => {},
       use: (() => {
         throw new Error("use() not available during pre-rendering");
       }) as any,
       method: "GET",
       _handleStore: handleStore,
+      _requestTags: new Set<string>(),
       waitUntil: () => {},
       onResponse: () => {},
       _onResponseCallbacks: [],
@@ -256,17 +260,13 @@ export async function matchForPrerender<TEnv = any>(
         { skipLoaders: true },
       );
 
-      // 9. Detect passthrough sentinel: handler returned ctx.passthrough()
-      for (const seg of allSegments) {
-        if (isPrerenderPassthrough(seg.component)) {
-          return {
-            segments: [],
-            handles: {},
-            routeName: matched.routeKey,
-            params: matchedParams,
-            passthrough: true as const,
-          };
-        }
+      // 9. Detect passthrough sentinel: handler returned ctx.passthrough().
+      // When the route declares loading(), the handler result is deferred so the
+      // component is a thenable resolving to the sentinel — detectPrerenderPassthrough
+      // resolves thenables before testing (a sync check would miss it and bake a
+      // corrupt artifact).
+      if (await detectPrerenderPassthrough(allSegments)) {
+        return passthroughResult();
       }
 
       // 10. Filter out any loader segments (belt-and-suspenders)
@@ -278,16 +278,22 @@ export async function matchForPrerender<TEnv = any>(
 
       // 12. Serialize segments using the cache serializer
       const { serializeSegments } = await import("../cache/segment-codec.js");
+      const { encodeHandles } = await import("../cache/handle-snapshot.js");
       const serializedSegments = await serializeSegments(nonLoaderSegments);
 
-      // 13. Collect handle data per segment (skip segments with no handle data)
-      const handles: Record<string, SegmentHandleData> = {};
+      // 13. Collect handle data per segment (skip segments with no handle data).
+      // Encoded through the Flight codec (not stored raw) so Promise/ReactNode
+      // handle values survive the JSON-serialized build artifact / dev wire —
+      // the same fix the runtime cache uses. Encode happens here, in the RSC
+      // environment where the codec resolves; the node-side sinks only persist.
+      const handlesRecord: Record<string, SegmentHandleData> = {};
       for (const seg of nonLoaderSegments) {
         const segHandles = handleStore.getDataForSegment(seg.id);
         if (Object.keys(segHandles).length > 0) {
-          handles[seg.id] = segHandles;
+          handlesRecord[seg.id] = segHandles;
         }
       }
+      const handles = await encodeHandles(handlesRecord);
 
       // Use the trie-level route key (e.g., "docs", "docs.article")
       const routeName = matched.routeKey;
@@ -297,7 +303,7 @@ export async function matchForPrerender<TEnv = any>(
       //     evaluation -- we pre-render all intercepts unconditionally and let
       //     runtime matching decide which to serve.
       let interceptSegments: SerializedSegmentData[] | undefined;
-      let interceptHandles: Record<string, SegmentHandleData> | undefined;
+      let interceptHandles: string | undefined;
 
       const foundIntercepts: {
         intercept: InterceptEntry;
@@ -305,24 +311,14 @@ export async function matchForPrerender<TEnv = any>(
       }[] = [];
       let current: EntryData | null = manifestEntry;
       while (current) {
-        if (current.intercept && current.intercept.length > 0) {
-          for (const ic of current.intercept) {
+        // Flatten the entry and its sibling layouts into one source list, the
+        // same traversal findInterceptForRoute uses; the build keeps ALL matches
+        // (not just the innermost) and skips when(). intercept/layout are
+        // non-optional arrays, so empty ones are a no-op here.
+        for (const source of [current, ...current.layout]) {
+          for (const ic of source.intercept) {
             if (ic.routeName === matched.routeKey) {
-              foundIntercepts.push({ intercept: ic, entry: current });
-            }
-          }
-        }
-        if (current.layout && current.layout.length > 0) {
-          for (const siblingLayout of current.layout) {
-            if (siblingLayout.intercept && siblingLayout.intercept.length > 0) {
-              for (const ic of siblingLayout.intercept) {
-                if (ic.routeName === matched.routeKey) {
-                  foundIntercepts.push({
-                    intercept: ic,
-                    entry: siblingLayout,
-                  });
-                }
-              }
+              foundIntercepts.push({ intercept: ic, entry: source });
             }
           }
         }
@@ -333,6 +329,18 @@ export async function matchForPrerender<TEnv = any>(
         const interceptResolvedSegments: typeof nonLoaderSegments = [];
 
         for (const { intercept, entry: parentEntry } of foundIntercepts) {
+          // setupBuildUse keys handle pushes by ctx._currentSegmentId. The main
+          // resolveAllSegments pass left it on the route's segment id, so pin it
+          // to THIS intercept's slot id before resolving the handler/layout --
+          // otherwise the intercept's ctx.use() handle pushes land in the wrong
+          // bucket and getDataForSegment(seg.id) below drops them from the baked
+          // artifact. Re-pinned per iteration so multiple intercepts targeting
+          // the same route each get their own id (mirrors fresh.ts parallel-slot
+          // pinning).
+          const interceptSegmentId = `${parentEntry.shortCode}.${intercept.slotName}`;
+          (buildCtx as InternalHandlerContext<any, TEnv>)._currentSegmentId =
+            interceptSegmentId;
+
           // Resolve handler
           const handlerRaw =
             typeof intercept.handler === "function"
@@ -359,7 +367,7 @@ export async function matchForPrerender<TEnv = any>(
           }
 
           interceptResolvedSegments.push({
-            id: `${parentEntry.shortCode}.${intercept.slotName}`,
+            id: interceptSegmentId,
             namespace: `intercept:${intercept.routeName}`,
             type: "parallel" as const,
             index: 0,
@@ -379,13 +387,20 @@ export async function matchForPrerender<TEnv = any>(
           interceptSegments = await serializeSegments(
             interceptResolvedSegments,
           );
-          interceptHandles = {};
+          const interceptHandlesRecord: Record<string, SegmentHandleData> = {};
           for (const seg of interceptResolvedSegments) {
             const segHandles = handleStore.getDataForSegment(seg.id);
             if (Object.keys(segHandles).length > 0) {
-              interceptHandles[seg.id] = segHandles;
+              interceptHandlesRecord[seg.id] = segHandles;
             }
           }
+          // The intercept artifact serves main + intercept segments together, so
+          // encode the MERGED handle map here (the sinks no longer merge raw
+          // records — they store this pre-encoded string as-is).
+          interceptHandles = await encodeHandles({
+            ...handlesRecord,
+            ...interceptHandlesRecord,
+          });
         }
       }
 
@@ -414,7 +429,7 @@ export async function renderStaticSegment<TEnv = any>(
   routeName?: string,
   buildEnv?: TEnv,
   devMode?: boolean,
-): Promise<{ encoded: string; handles: Record<string, unknown[]> } | null> {
+): Promise<{ encoded: string; handles: string } | null> {
   const syntheticUrl = new URL("http://prerender/");
   const syntheticRequest = new Request(syntheticUrl);
 
@@ -442,11 +457,14 @@ export async function renderStaticSegment<TEnv = any>(
     header: () => {},
     setStatus: () => {},
     _setStatus: () => {},
+    _rotateStateCookie: () => {},
+    _setKeepCacheDirective: () => {},
     use: (() => {
       throw new Error("use() not available during static pre-rendering");
     }) as any,
     method: "GET",
     _handleStore: handleStore,
+    _requestTags: new Set<string>(),
     waitUntil: () => {},
     onResponse: () => {},
     _onResponseCallbacks: [],
@@ -479,23 +497,41 @@ export async function renderStaticSegment<TEnv = any>(
     setupBuildUse(buildCtx);
 
     const raw = await handler(buildCtx);
-    const component = raw?.type ? raw : raw;
+
+    // Static handlers must return a ReactNode. A returned Response (e.g. an
+    // accidental redirect()) would otherwise be serialized as a corrupt build
+    // artifact; fail loudly instead. The fresh/revalidation paths route handler
+    // results through handleHandlerResult, which throws Responses; the static
+    // build path bypasses that, so guard here.
+    if (raw instanceof Response) {
+      throw new TypeError(
+        `Static handler "${routeName}" returned a Response. Static handlers must return a ReactNode; ` +
+          `Responses (redirects, file responses) are not supported during static pre-rendering.`,
+      );
+    }
 
     const segment: ResolvedSegment = {
       id: handlerId,
       namespace: handlerId,
       type: "layout",
       index: 0,
-      component,
+      component: raw,
       params: {},
       belongsToRoute: false,
     };
 
     const { serializeSegments } = await import("../cache/segment-codec.js");
+    const { encodeHandleValue } = await import("../cache/handle-snapshot.js");
     const [serialized] = await serializeSegments([segment]);
 
-    // Collect handle data pushed during rendering
-    const handles = handleStore.getDataForSegment(handlerId);
+    // Collect handle data pushed during rendering and Flight-encode it (so
+    // Promise/ReactNode handle values survive the JSON build artifact). "" when
+    // nothing was pushed.
+    const segHandles = handleStore.getDataForSegment(handlerId);
+    const handles =
+      Object.keys(segHandles).length > 0
+        ? await encodeHandleValue(segHandles)
+        : "";
 
     return { encoded: serialized.encoded, handles };
   });

package/src/router/preview-match.ts

@@ -67,9 +67,11 @@ export async function previewMatch<TEnv = any>(
             responseType: negotiation.responseType,
             handler: negotiation.handler,
             params: matched.params,
-            negotiated: true,
             manifestEntry: negotiation.manifestEntry,
             routeKey: matched.routeKey,
+            // omitted unless a variant negotiated, preserving the prior public
+            // shape (absent for plain response routes, not negotiated:false)
+            ...(negotiation.negotiated ? { negotiated: true } : {}),
           };
         }