@rangojs/router 0.0.0-experimental.d7eeaa75 → 0.0.0-experimental.d98a8e9d

package/src/loader.ts

@@ -1,5 +1,5 @@
 /**
- * rsc-router/loader (client version)
+ * @rangojs/router/loader (client version)
  *
  * Client-only stub for createLoader. Returns a minimal loader definition
  * ({ __brand, $$id }) that can be passed to hooks like useLoader.
@@ -18,6 +18,8 @@ import type {
   LoaderDefinition,
   LoaderFn,
 } from "./types.js";
+import { missingInjectedIdError } from "./missing-id-error.js";
+import { isUnderTestRunner } from "./runtime-env.js";
 
 // Overload 1: With function only (not fetchable)
 export function createLoader<T>(
@@ -38,10 +40,6 @@ export function createLoader<T>(
 
 // Implementation - client stub that just returns the loader definition
 // The $$id parameter is injected by Vite plugin, not user-provided
-//
-// NOTE: For export-only loader files, the Vite plugin replaces the entire
-// file with object literals (bypassing this function). This function only
-// runs when loaders are in mixed files (not export-only).
 export function createLoader<T>(
   _fn: LoaderFn<T, Record<string, string | undefined>, any>,
   _fetchable?: true | FetchableLoaderOptions,
@@ -49,11 +47,20 @@ export function createLoader<T>(
 ): LoaderDefinition<Awaited<T>, Record<string, string | undefined>> {
   const loaderId = __injectedId || "";
 
-  if (!loaderId && process.env.NODE_ENV === "development") {
+  // Client/SSR build of createLoader. Under a test runner it needs no id
+  // (loaderId stays ""; the react-server build in loader.rsc.ts adds the runtime
+  // fallback for whole-router construction). Otherwise (dev or a real build) a
+  // missing id means an UNSUPPORTED shape the plugin skipped — fail loud rather
+  // than ship `$$id: ""` (which would make a client useLoader read the wrong
+  // key). The rich diagnostic stays behind the NODE_ENV check so production folds
+  // it away and ships the small throw. isUnderTestRunner() is runtime-safe.
+  if (!loaderId && !isUnderTestRunner()) {
+    if (process.env.NODE_ENV !== "production") {
+      throw missingInjectedIdError("Loader", "createLoader");
+    }
     throw new Error(
-      "[rsc-router] Loader is missing $$id. " +
-        "Make sure the exposeInternalIds Vite plugin is enabled and " +
-        "the loader is exported with: export const MyLoader = createLoader(...)",
+      "[rango] Loader is missing $$id — the build plugin did not inject one. " +
+        "Export it as `export const X = createLoader(...)`.",
     );
   }
 

package/src/missing-id-error.ts

@@ -0,0 +1,68 @@
+// Builds the error thrown when a create*() call (createLoader / createHandle)
+// reaches runtime without an injected $$id. The exposeInternalIds Vite transform
+// injects $$id only for an EXPORTED const declaration, so a non-exported const,
+// an `export let/var`, or an inline create*() call gets none. Previously this
+// failed with a terse message and no source location; this helper adds the
+// offending call site (best-effort, from the stack) and actionable guidance.
+//
+// The "<Kind> is missing $$id" prefix is preserved so existing tests and any
+// log scrapers keep matching. Dev-only: the call sites guard on
+// process.env.NODE_ENV === "development", so production builds fold the branch
+// away and tree-shake this module out.
+
+// create*() implementation files to skip when locating the user's call site.
+const SELF_FILES = new Set([
+  "missing-id-error",
+  "loader",
+  "loader.rsc",
+  "handle",
+]);
+
+/**
+ * Best-effort "path:line:column" of the user's create*() call, parsed from the
+ * current stack. Skips @rangojs/router internals and node_modules. Returns
+ * undefined if nothing usable is found (stack parsing is inherently fragile).
+ */
+function findUserCallSite(): string | undefined {
+  try {
+    const stack = new Error().stack;
+    if (!stack) return undefined;
+    for (const frame of stack.split("\n").slice(1)) {
+      const m = frame.match(
+        /(?:\(|@|\s)(?:file:\/\/)?((?:\/|[A-Za-z]:[\\/])[^()\s]+?\.(?:ts|tsx|js|jsx|mts|cts)):(\d+):(\d+)\)?/,
+      );
+      if (!m) continue;
+      const path = m[1];
+      if (path.includes("node_modules") || path.includes("@rangojs/router")) {
+        continue;
+      }
+      const base = path
+        .split(/[\\/]/)
+        .pop()!
+        .replace(/\.(?:ts|tsx|js|jsx|mts|cts)$/, "");
+      if (SELF_FILES.has(base)) continue;
+      return `${path}:${m[2]}:${m[3]}`;
+    }
+  } catch {
+    // best-effort only
+  }
+  return undefined;
+}
+
+export function missingInjectedIdError(
+  kind: "Loader" | "Handle",
+  fnName: "createLoader" | "createHandle",
+): Error {
+  const site = findUserCallSite();
+  const at = site ? ` (created at ${site})` : "";
+  return new Error(
+    `[rango] ${kind} is missing $$id${at}.\n` +
+      `The @rangojs/router:expose-internal-ids Vite transform injects ${fnName}()'s ` +
+      `stable $$id from an EXPORTED const declaration only:\n` +
+      `  export const X = ${fnName}(...)\n` +
+      `  const X = ${fnName}(...); export { X }\n` +
+      `A non-exported const, an \`export let/var\`, or an inline ${fnName}(...) ` +
+      `call gets no $$id — export it as \`export const\`. (A matching ` +
+      `"Unsupported ${fnName} shape" warning names the exact file:line.)`,
+  );
+}

package/src/outlet-context.ts

@@ -1,4 +1,4 @@
-import { Context, createContext, type ReactNode } from "react";
+import { type Context, createContext, type ReactNode } from "react";
 import type { ResolvedSegment } from "./types";
 
 export interface OutletContextValue {

package/src/prerender.ts

@@ -38,6 +38,7 @@ import type { ReverseFunction } from "./reverse.js";
 import type { DefaultReverseRouteMap } from "./types/global-namespace.js";
 import type { UseItems, HandlerUseItem } from "./route-types.js";
 import { isCachedFunction } from "./cache/taint.js";
+import { isUnderTestRunner } from "./runtime-env.js";
 
 // -- Named route resolution types -------------------------------------------
 
@@ -69,9 +70,9 @@ type BuildReverseFunction = [DefaultReverseRouteMap] extends [
  * Default route map for Prerender named route resolution.
  * Uses GeneratedRouteMap (from gen file) to avoid circular dependencies.
  */
-type DefaultPrerenderRouteMap = keyof RSCRouter.GeneratedRouteMap extends never
+type DefaultPrerenderRouteMap = keyof Rango.GeneratedRouteMap extends never
   ? {}
-  : RSCRouter.GeneratedRouteMap;
+  : Rango.GeneratedRouteMap;
 
 /** Extract params from a route map entry (string pattern or { path } object). */
 type ExtractParamsFromEntry<TEntry> = TEntry extends string
@@ -273,6 +274,11 @@ export interface PrerenderHandlerDefinition<
   use?: () => UseItems<HandlerUseItem>;
 }
 
+// Process-stable fallback id counter (mirrors createHandle / createLoader). Only
+// assigned in a bare unit test where the Vite plugin did not inject an id; never
+// fires in a real build (the plugin always injects).
+let runtimePrerenderIdCounter = 0;
+
 // -- Overloads --------------------------------------------------------------
 //
 // T accepts: named route string (global or .local) OR explicit param object.
@@ -376,12 +382,27 @@ export function Prerender<TParams extends Record<string, any>>(
     );
   }
 
-  if (!id) {
+  // Throw unless under a test runner. The plugin always injects $$id for a
+  // supported `export const` Prerender on every build, so a missing id means
+  // either no plugin (a bare test — fall back below) or an UNSUPPORTED shape the
+  // plugin silently skipped (dev OR a real build — fail loud; a synthetic id
+  // would degrade to a silent prerender miss). The message is already small (no
+  // stack-parsing diagnostic), so it ships as-is. isUnderTestRunner() is
+  // runtime-safe — never a bare `process.env` access.
+  if (!id && !isUnderTestRunner()) {
     throw new Error(
-      "[rsc-router] Prerender: missing $$id. " +
-        "Ensure the exposeInternalIds Vite plugin is configured.",
+      "[rango] Prerender: missing $$id. Use `export const X = Prerender(...)` " +
+        "and ensure the exposeInternalIds Vite plugin is configured.",
     );
   }
+  // Under vitest with no plugin id: assign a process-stable runtime id so a
+  // whole-app router with Prerender routes constructs in a bare test (for
+  // dispatch / assertGeneratedRoutesMatch). Never reached in a real build (the
+  // throw above fires there); prerender storage/lookup keys on routeName +
+  // paramHash, never $$id (mirrors createHandle / createLoader).
+  if (!id) {
+    id = `__rango_runtime_prerender_${runtimePrerenderIdCounter++}`;
+  }
 
   return {
     __brand: "prerenderHandler" as const,
@@ -499,7 +520,7 @@ export function Passthrough<
 ): PassthroughHandlerDefinition<TParams, TEnv> {
   if (!isPrerenderHandler(prerenderDef)) {
     throw new Error(
-      "[rsc-router] Passthrough: first argument must be a Prerender() definition.",
+      "[rango] Passthrough: first argument must be a Prerender() definition.",
     );
   }
   return {

package/src/response-utils.ts

@@ -0,0 +1,37 @@
+/**
+ * Runtime-neutral Response shape utilities.
+ *
+ * Kept at the src/ root so both `router/` and `rsc/` can depend on it
+ * without creating a cross-layer import cycle.
+ */
+
+/**
+ * True when a Response represents a WebSocket upgrade handoff and must not
+ * be reconstructed or mutated:
+ *
+ * - Status 101 (Switching Protocols) is outside the standard Response
+ *   constructor's 200–599 range, so `new Response(body, { status: 101 })`
+ *   throws RangeError on Node/undici and any spec-compliant runtime.
+ * - Cloudflare's workerd attaches a non-standard `webSocket` property on
+ *   the upgrade Response (e.g. from `acceptWebSocket`/`handleWebSocketUpgrade`
+ *   or the `agents` library's `routeAgentRequest`). That property is dropped
+ *   by a `new Response(...)` copy, breaking the upgrade even on workerd
+ *   where the status range is relaxed.
+ *
+ * Callers should short-circuit header/body merges for these responses.
+ */
+export function isWebSocketUpgradeResponse(response: Response): boolean {
+  return (
+    response.status === 101 ||
+    (response as unknown as { webSocket?: unknown }).webSocket != null
+  );
+}
+
+// Location truthiness (not presence) so an empty `Location: ""` is not a redirect.
+export function isRedirectResponse(response: Response): boolean {
+  return (
+    response.status >= 300 &&
+    response.status < 400 &&
+    Boolean(response.headers.get("Location"))
+  );
+}

package/src/reverse.ts

@@ -1,6 +1,7 @@
 import type { ExtractParams } from "./types.js";
 import type { SearchSchema, ResolveSearchSchema } from "./search-params.js";
 import { serializeSearchParams } from "./search-params.js";
+import { substitutePatternParams } from "./router/substitute-pattern-params.js";
 
 /**
  * Sanitize prefix string by removing leading slash
@@ -218,6 +219,67 @@ export type ExtractLocalRoutes<TPatterns> = TPatterns extends {
     ? TPatterns
     : Record<string, string>;
 
+/**
+ * Params accepted by `useReverse(routes)`. The route's own params are
+ * required, and additional string keys are permitted so callers can
+ * override values that would otherwise be auto-filled from the matched
+ * route's `useParams()` (e.g. an enclosing `:tenantId` mount segment).
+ */
+export type LocalReverseParams<TPattern extends string> =
+  ExtractParams<TPattern> & {
+    readonly [extra: string]: string | undefined;
+  };
+
+/**
+ * Type-safe local reverse function.
+ *
+ * Returned by `useReverse(routes)` on the client. The route map is the
+ * exposure boundary (a generated `routes` from a `urls()` module) and the
+ * scope is implicit from that import. Names may be written with or without a
+ * leading dot — `reverse("post")` and `reverse(".post")` are identical. The dot
+ * is a cosmetic readability convention (and parity with `ctx.reverse(".name")`);
+ * there is no separate global namespace here, so it carries no meaning.
+ *
+ * @example
+ * ```typescript
+ * const reverse = useReverse(blogRoutes);
+ * reverse("index");                          // ✓ no params (dot optional)
+ * reverse(".index");                         // ✓ identical to the above
+ * reverse("post", { postId: "hello" });      // ✓ with params
+ * reverse("search", {}, { q: "hi" });        // ✓ with search schema
+ * reverse("typo");                           // ✗ compile error
+ * ```
+ */
+export type LocalReverseFunction<TLocalRoutes> = {
+  /**
+   * Route without params (leading dot optional)
+   */
+  <TName extends keyof TLocalRoutes & string>(
+    name: IsEmptyObject<
+      ExtractParams<RoutePatternFor<TLocalRoutes, TName>>
+    > extends true
+      ? TName | `.${TName}`
+      : never,
+  ): string;
+
+  /**
+   * Route with params (leading dot optional)
+   */
+  <TName extends keyof TLocalRoutes & string>(
+    name: TName | `.${TName}`,
+    params: LocalReverseParams<RoutePatternFor<TLocalRoutes, TName>>,
+  ): string;
+
+  /**
+   * Route with params and search (leading dot optional)
+   */
+  <TName extends keyof TLocalRoutes & string>(
+    name: TName | `.${TName}`,
+    params: LocalReverseParams<RoutePatternFor<TLocalRoutes, TName>>,
+    search: ResolveSearchSchema<ExtractSearchSchema<TLocalRoutes, TName>>,
+  ): string;
+};
+
 /**
  * Extract the response data type for a named route from a UrlPatterns instance.
  * Re-exported from urls.ts for consumer convenience.
@@ -301,42 +363,9 @@ export function createReverse<TRoutes extends Record<string, string>>(
       throw new Error(`Unknown route: ${name}`);
     }
 
-    let result = pattern;
-    if (params) {
-      // Replace :param placeholders with actual values
-      // Strip constraint syntax: :param(a|b) -> use "param" as key
-      // Optional params (:param?) are omitted when not provided
-      let hadOmittedOptional = false;
-      result = result.replace(
-        /:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?(\?)/g,
-        (_, key, _constraint, optional) => {
-          const value = params[key];
-          if (value === undefined) {
-            hadOmittedOptional = true;
-            return "";
-          }
-          return encodeURIComponent(value);
-        },
-      );
-      // Second pass: required params (no trailing ?)
-      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);
-        },
-      );
-      // Clean up slashes only when an optional param was actually omitted,
-      // so intentional trailing-slash patterns like "/blog/" are preserved.
-      if (hadOmittedOptional) {
-        const hadTrailingSlash = pattern.length > 1 && pattern.endsWith("/");
-        result = result.replace(/\/\/+/g, "/").replace(/\/+$/, "") || "/";
-        if (hadTrailingSlash && !result.endsWith("/")) result += "/";
-      }
-    }
+    let result = params
+      ? substitutePatternParams(pattern, params, name)
+      : pattern;
 
     // Append search params as query string
     if (search) {

package/src/route-content-wrapper.tsx

@@ -4,7 +4,7 @@ import { Suspense, use, useId } from "react";
 import { invariant } from "./errors";
 import { OutletProvider } from "./outlet-provider.js";
 import type { ResolvedSegment } from "./types.js";
-import { isLoaderDataResult } from "./types.js";
+import { decodeLoaderResults } from "./decode-loader-results.js";
 
 /**
  * Stable async wrapper component for route content
@@ -26,10 +26,6 @@ export function RouteContentWrapper({
   fallback?: ReactNode;
   segmentId?: string;
 }): ReactNode {
-  if (!content) {
-    // Already resolved
-    return content as ReactNode;
-  }
   return (
     <Suspense
       fallback={fallback ?? null}
@@ -159,28 +155,10 @@ function LoaderResolver({
       ? use(loaderDataPromise)
       : loaderDataPromise;
 
-  // Build loaderData record from resolved values
-  const loaderData: Record<string, any> = {};
-  let loaderErrorFallback: ReactNode = null;
-
-  loaderIds.forEach((id, i) => {
-    const result = resolvedData[i];
-
-    if (isLoaderDataResult(result)) {
-      if (result.ok) {
-        loaderData[id] = result.data;
-      } else {
-        if (result.fallback) {
-          loaderErrorFallback = result.fallback;
-        } else {
-          throw new Error(result.error.message);
-        }
-      }
-    } else {
-      // Legacy format - direct data
-      loaderData[id] = result;
-    }
-  });
+  const { loaderData, errorFallback } = decodeLoaderResults(
+    resolvedData,
+    loaderIds,
+  );
 
   return (
     <OutletProvider
@@ -190,7 +168,7 @@ function LoaderResolver({
       parallel={parallel}
       loaderData={Object.keys(loaderData).length > 0 ? loaderData : undefined}
     >
-      {loaderErrorFallback ?? children}
+      {errorFallback ?? children}
     </OutletProvider>
   );
 }