@rangojs/router 0.0.0-experimental.18 → 0.0.0-experimental.19

package/src/prerender.ts

@@ -34,10 +34,36 @@ import type {
 } from "./types.js";
 import type { Handle } from "./handle.js";
 import type { ContextVar } from "./context-var.js";
+import type { ReverseFunction } from "./reverse.js";
+import type { DefaultReverseRouteMap } from "./types/global-namespace.js";
 import { isCachedFunction } from "./cache/taint.js";
 
 // -- Named route resolution types -------------------------------------------
 
+/**
+ * Reverse function for build contexts (BuildContext, StaticBuildContext, GetParamsContext).
+ * Global names get full autocomplete and param validation from the generated route map.
+ * Local `.name` calls are accepted but not validated (the include() scope is unknown
+ * at the type level).
+ */
+type BuildReverseFunction = [DefaultReverseRouteMap] extends [
+  Record<string, string>,
+]
+  ? // No generated route map — permissive fallback
+    (
+      name: string,
+      params?: Record<string, string>,
+      search?: Record<string, unknown>,
+    ) => string
+  : // Generated route map available — typed globals + permissive locals
+    ReverseFunction<DefaultReverseRouteMap> & {
+      (
+        name: `.${string}`,
+        params?: Record<string, string>,
+        search?: Record<string, unknown>,
+      ): string;
+    };
+
 /**
  * Default route map for Prerender named route resolution.
  * Uses GeneratedRouteMap (from gen file) to avoid circular dependencies.
@@ -143,11 +169,14 @@ export interface BuildContext<TParams> {
   search: {};
 
   /** URL generation by route name. */
-  reverse: (
-    name: string,
-    params?: Record<string, string>,
-    search?: Record<string, unknown>,
-  ) => string;
+  reverse: BuildReverseFunction;
+
+  /**
+   * Signal that this param set should not produce a local prerender artifact.
+   * At runtime the handler runs live instead. Only valid on routes declared
+   * with `{ passthrough: true }`.
+   */
+  passthrough: () => PrerenderPassthroughResult;
 }
 
 /**
@@ -174,11 +203,7 @@ export interface StaticBuildContext {
   use: <T>(handle: Handle<T>) => (data: T) => void;
 
   /** URL generation by route name. */
-  reverse: (
-    name: string,
-    params?: Record<string, string>,
-    search?: Record<string, unknown>,
-  ) => string;
+  reverse: BuildReverseFunction;
 }
 
 /**
@@ -196,11 +221,7 @@ export interface GetParamsContext {
   };
 
   /** URL generation by route name. */
-  reverse: (
-    name: string,
-    params?: Record<string, string>,
-    search?: Record<string, unknown>,
-  ) => string;
+  reverse: BuildReverseFunction;
 }
 
 /**
@@ -216,7 +237,9 @@ export interface GetParamsContext {
 export type PrerenderPassthroughContext<
   TParams = {},
   TEnv = DefaultEnv,
-> = HandlerContext<TParams, TEnv>;
+> = HandlerContext<TParams, TEnv> & {
+  passthrough: () => PrerenderPassthroughResult;
+};
 
 export interface PrerenderHandlerDefinition<
   TParams extends Record<string, any> = any,
@@ -269,7 +292,10 @@ export function Prerender<
       ResolvePrerenderParams<T, TRouteMap>,
       TEnv
     >,
-  ) => ReactNode | Promise<ReactNode>,
+  ) =>
+    | ReactNode
+    | PrerenderPassthroughResult
+    | Promise<ReactNode | PrerenderPassthroughResult>,
   options: PrerenderOptions & { passthrough: true },
   __injectedId?: string,
 ): PrerenderHandlerDefinition<ResolvePrerenderParams<T, TRouteMap>>;
@@ -313,7 +339,10 @@ export function Prerender<
       ResolvePrerenderParams<T, TRouteMap>,
       TEnv
     >,
-  ) => ReactNode | Promise<ReactNode>,
+  ) =>
+    | ReactNode
+    | PrerenderPassthroughResult
+    | Promise<ReactNode | PrerenderPassthroughResult>,
   options: PrerenderOptions & { passthrough: true },
   __injectedId?: string,
 ): PrerenderHandlerDefinition<ResolvePrerenderParams<T, TRouteMap>>;
@@ -388,6 +417,35 @@ export function Prerender<TParams extends Record<string, any>>(
   };
 }
 
+// -- Passthrough sentinel ---------------------------------------------------
+
+/**
+ * Sentinel returned by `ctx.passthrough()` to signal that a specific param set
+ * should not produce a local prerender artifact. The build skips writing the
+ * entry; at runtime the handler runs live (requires `{ passthrough: true }`).
+ */
+export const PRERENDER_PASSTHROUGH: Readonly<{
+  __brand: "prerenderPassthrough";
+}> = Object.freeze({
+  __brand: "prerenderPassthrough" as const,
+});
+
+export type PrerenderPassthroughResult = typeof PRERENDER_PASSTHROUGH;
+
+/**
+ * Type guard to check if a value is the passthrough sentinel.
+ */
+export function isPrerenderPassthrough(
+  value: unknown,
+): value is PrerenderPassthroughResult {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "__brand" in value &&
+    (value as { __brand: unknown }).__brand === "prerenderPassthrough"
+  );
+}
+
 // -- Type guard -------------------------------------------------------------
 
 /**

package/src/reverse.ts

@@ -304,13 +304,17 @@ export function createReverse<TRoutes extends Record<string, string>>(
     let result = pattern;
     if (params) {
       // Replace :param placeholders with actual values
-      result = result.replace(/:([^/]+)/g, (_: string, key: string) => {
-        const value = params[key];
-        if (value === undefined) {
-          throw new Error(`Missing param "${key}" for route "${name}"`);
-        }
-        return encodeURIComponent(value);
-      });
+      // Strip constraint syntax: :param(a|b) -> use "param" as key
+      result = result.replace(
+        /:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?\??/g,
+        (_, key) => {
+          const value = params[key];
+          if (value === undefined) {
+            throw new Error(`Missing param "${key}" for route "${name}"`);
+          }
+          return encodeURIComponent(value);
+        },
+      );
     }
 
     // Append search params as query string

package/src/root-error-boundary.tsx

@@ -109,6 +109,8 @@ function RootErrorFallback({
   error,
   reset,
 }: ClientErrorBoundaryFallbackProps): ReactNode {
+  const isDev = process.env.NODE_ENV !== "production";
+
   return (
     <div
       style={{
@@ -135,38 +137,40 @@ function RootErrorFallback({
       >
         An unexpected error occurred while processing your request.
       </p>
-      <div
-        style={{
-          background: "#fef2f2",
-          border: "1px solid #fecaca",
-          borderRadius: "0.5rem",
-          padding: "1rem",
-          marginBottom: "1rem",
-        }}
-      >
-        <p
+      {isDev && (
+        <div
           style={{
-            fontWeight: 600,
-            color: "#991b1b",
-            marginBottom: "0.5rem",
+            background: "#fef2f2",
+            border: "1px solid #fecaca",
+            borderRadius: "0.5rem",
+            padding: "1rem",
+            marginBottom: "1rem",
           }}
         >
-          {error.name}: {error.message}
-        </p>
-        {error.stack && (
-          <pre
+          <p
             style={{
-              fontSize: "0.75rem",
-              color: "#6b7280",
-              overflow: "auto",
-              whiteSpace: "pre-wrap",
-              wordBreak: "break-word",
+              fontWeight: 600,
+              color: "#991b1b",
+              marginBottom: "0.5rem",
             }}
           >
-            {error.stack}
-          </pre>
-        )}
-      </div>
+            {error.name}: {error.message}
+          </p>
+          {error.stack && (
+            <pre
+              style={{
+                fontSize: "0.75rem",
+                color: "#6b7280",
+                overflow: "auto",
+                whiteSpace: "pre-wrap",
+                wordBreak: "break-word",
+              }}
+            >
+              {error.stack}
+            </pre>
+          )}
+        </div>
+      )}
       <div style={{ display: "flex", gap: "1rem" }}>
         <button
           type="button"

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

@@ -16,7 +16,7 @@ import {
 } from "../server/context";
 import { invariant } from "../errors";
 import { isCachedFunction } from "../cache/taint.js";
-import { getCacheProfile } from "../cache/profile-registry.js";
+import { RSCRouterContext } from "../server/context";
 import { isStaticHandler } from "../static-handler.js";
 import RootLayout from "../server/root-layout";
 import type {
@@ -227,7 +227,9 @@ const cache: RouteHelpers<any, any>["cache"] = (
     children = undefined;
   } else if (typeof optionsOrChildren === "string") {
     // cache('profileName') or cache('profileName', () => [...])
-    const profile = getCacheProfile(optionsOrChildren);
+    // Resolve from context-scoped profiles (set per-router via HelperContext).
+    const ctxStore = RSCRouterContext.getStore();
+    const profile = ctxStore?.cacheProfiles?.[optionsOrChildren];
     invariant(
       profile,
       `cache("${optionsOrChildren}"): unknown cache profile. ` +
@@ -245,7 +247,9 @@ const cache: RouteHelpers<any, any>["cache"] = (
     children = maybeChildren;
   }
 
-  const name = `$${store.getNextIndex("cache")}`;
+  // Allocate a single index for this cache() call (used in all paths)
+  const cacheIndex = store.getNextIndex("cache");
+  const name = `$${cacheIndex}`;
   const cacheConfig = { options };
 
   // If no children, create an orphan cache entry (like orphan layouts)
@@ -262,7 +266,7 @@ const cache: RouteHelpers<any, any>["cache"] = (
 
     // Create orphan cache entry (like orphan layout)
     // Subsequent siblings in the same array will attach to this entry
-    const namespace = `${ctx.namespace}.${store.getNextIndex("cache")}`;
+    const namespace = `${ctx.namespace}.${cacheIndex}`;
     const cacheUrlPrefix = getUrlPrefix();
 
     const entry = {
@@ -297,8 +301,7 @@ const cache: RouteHelpers<any, any>["cache"] = (
   }
 
   // With children: create a cache entry (like layout with caching semantics)
-  const cacheNextIndex = store.getNextIndex("cache");
-  const namespace = `${ctx.namespace}.${cacheNextIndex}`;
+  const namespace = `${ctx.namespace}.${cacheIndex}`;
   const cacheShortCode = store.getShortCode("cache");
 
   const cacheUrlPrefix2 = getUrlPrefix();

package/src/route-definition/redirect.ts

@@ -43,11 +43,16 @@ import {
 export function redirect(url: string, status?: number): Response;
 export function redirect(
   url: string,
-  options: { status?: number; state?: LocationStateEntry[] },
+  options: {
+    status?: number;
+    state?: LocationStateEntry | LocationStateEntry[];
+  },
 ): Response;
 export function redirect(
   url: string,
-  statusOrOptions?: number | { status?: number; state?: LocationStateEntry[] },
+  statusOrOptions?:
+    | number
+    | { status?: number; state?: LocationStateEntry | LocationStateEntry[] },
 ): Response {
   const status =
     typeof statusOrOptions === "number"
@@ -62,7 +67,14 @@ export function redirect(
 
     if (process.env.NODE_ENV !== "production") {
       const reqCtx = getRequestContext();
-      if (reqCtx && !reqCtx.url.searchParams.has("_rsc_partial")) {
+      // Warn only on true full-page SSR loads. SPA partial requests and server
+      // actions both deliver state through Flight payloads, so suppress for those.
+      if (
+        reqCtx &&
+        !reqCtx.url.searchParams.has("_rsc_partial") &&
+        !reqCtx.request.headers.has("rsc-action") &&
+        !reqCtx.url.searchParams.has("_rsc_action")
+      ) {
         console.warn(
           `[Router] redirect() with state during a full-page (SSR) request to "${url}". ` +
             "Location state is only delivered during SPA navigations and will be lost on this request.",

package/src/route-map-builder.ts

@@ -128,15 +128,23 @@ const perRouterPrecomputedEntriesMap: Map<
 > = new Map();
 
 /**
- * Clear all per-router cached data (manifest, trie, precomputed entries).
+ * Clear all cached route data (global and per-router).
  * Called during HMR when route definitions change so the handler rebuilds
  * the trie from the updated router.urlpatterns on the next request.
+ *
+ * The virtual module calls this before repopulating with fresh data,
+ * preventing stale entries from removed routes from accumulating.
  */
 export function clearAllRouterData(): void {
+  globalRouteMap = {};
+  cachedManifest = null;
+  cachedPrecomputedEntries = null;
+  cachedRouteTrie = null;
+  rootScopeRoutes.clear();
+  globalSearchSchemas.clear();
   perRouterManifestMap.clear();
   perRouterTrieMap.clear();
   perRouterPrecomputedEntriesMap.clear();
-  cachedRouteTrie = null;
 }
 
 export function setRouterManifest(
@@ -217,6 +225,34 @@ export function waitForManifestReady(): Promise<void> | null {
   return manifestReadyPromise;
 }
 
+// ============================================================================
+// Route Scope Registry
+// ============================================================================
+
+// Tracks whether each route is at root scope (no named include boundary above).
+// Used by dot-local reverse resolution to decide whether bare-name fallback
+// is allowed after scoped lookups are exhausted.
+const rootScopeRoutes: Map<string, boolean> = new Map();
+
+/**
+ * Register whether a route is at root scope.
+ * Called by path() during route evaluation.
+ */
+export function registerRouteRootScope(
+  routeName: string,
+  rootScoped: boolean,
+): void {
+  rootScopeRoutes.set(routeName, rootScoped);
+}
+
+/**
+ * Check if a route is at root scope.
+ * Returns undefined if the route has not been registered (e.g. in unit tests).
+ */
+export function isRouteRootScoped(routeName: string): boolean | undefined {
+  return rootScopeRoutes.get(routeName);
+}
+
 // ============================================================================
 // Search Schema Registry
 // ============================================================================

package/src/route-name.ts

@@ -0,0 +1,53 @@
+/**
+ * Route name utilities for filtering internal route names.
+ *
+ * Internal names stay active in the runtime manifest for matching and local
+ * reverse() resolution, but they must not leak into public APIs or generated
+ * route maps.
+ */
+
+export const AUTO_GENERATED_ROUTE_PREFIX = "$path_";
+export const INTERNAL_INCLUDE_SCOPE_PREFIX = "$prefix_";
+
+const RESERVED_PREFIXES = [
+  AUTO_GENERATED_ROUTE_PREFIX,
+  INTERNAL_INCLUDE_SCOPE_PREFIX,
+] as const;
+
+/**
+ * Check if a route name is internal.
+ * Internal names include:
+ * - unnamed path() routes like "$path__health" or "docs.$path__health"
+ * - hidden include scopes like "$prefix_0.index" or "blog.$prefix_1.post"
+ *
+ * User-defined names containing "$" (e.g. "docs.$admin") are valid and must
+ * be preserved.
+ */
+export function isAutoGeneratedRouteName(name: string): boolean {
+  return name.split(".").some((segment) => {
+    return (
+      segment.startsWith(AUTO_GENERATED_ROUTE_PREFIX) ||
+      segment.startsWith(INTERNAL_INCLUDE_SCOPE_PREFIX)
+    );
+  });
+}
+
+/**
+ * Validate that a user-provided route name does not collide with
+ * reserved internal prefixes. Checks every dot-separated segment,
+ * mirroring the same rule used by isAutoGeneratedRouteName().
+ *
+ * Throws with a clear message when a reserved prefix is detected.
+ */
+export function validateUserRouteName(name: string): void {
+  for (const segment of name.split(".")) {
+    for (const prefix of RESERVED_PREFIXES) {
+      if (segment.startsWith(prefix)) {
+        throw new Error(
+          `Route name "${name}" contains segment "${segment}" which uses reserved internal prefix "${prefix}". ` +
+            `Choose a different name to avoid collision with auto-generated route names.`,
+        );
+      }
+    }
+  }
+}

package/src/route-types.ts

@@ -169,6 +169,13 @@ export type IncludeItem = {
     parent: unknown; // EntryData - avoid circular import
     /** Counter snapshot from pattern extraction for consistent shortCode indices */
     counters?: Record<string, number>;
+    /** Cache profiles for DSL-time cache("profileName") resolution */
+    cacheProfiles?: Record<
+      string,
+      import("./cache/profile-registry.js").CacheProfile
+    >;
+    /** Root scope flag for dot-local reverse resolution */
+    rootScoped?: boolean;
   };
   [IncludeBrand]: void;
 };

package/src/router/content-negotiation.ts

@@ -52,7 +52,7 @@ export function parseAcceptTypes(accept: string): AcceptEntry[] {
   for (let i = 0; i < parts.length; i++) {
     const part = parts[i]!;
     const segments = part.split(";");
-    const mime = segments[0]!.trim();
+    const mime = segments[0]!.trim().toLowerCase();
     if (!mime) continue;
     let q = 1.0;
     for (let j = 1; j < segments.length; j++) {

package/src/router/debug-manifest.ts

@@ -45,10 +45,23 @@ export async function buildDebugManifest<TEnv = any>(
         if (promiseResult !== null) {
           const load = await (promiseResult as Promise<any>);
           if (load && typeof load === "object" && "default" in load) {
-            const useItems = load.default;
-            if (typeof useItems === "function") {
-              useItems(helpers);
+            // Promise<{ default: fn }> — e.g. dynamic import
+            if (typeof load.default !== "function") {
+              throw new Error(
+                `[@rangojs/router] Unsupported async handler: { default } must be a function, ` +
+                  `got ${typeof load.default}. Use () => import('./urls') for lazy loading.`,
+              );
             }
+            load.default(helpers);
+          } else if (typeof load === "function") {
+            // Promise<fn>
+            load(helpers);
+          } else {
+            // Reject unsupported async handler results (same policy as manifest.ts)
+            throw new Error(
+              `[@rangojs/router] Unsupported async handler result (${typeof load}). ` +
+                `Lazy route handlers must resolve to a function or { default: fn }.`,
+            );
           }
         }
       },