@rangojs/router 0.0.0-experimental.f2d1a2f1 → 0.0.0-experimental.f4a8e8de

package/src/prerender/store.ts

@@ -1,21 +1,17 @@
 /**
- * Prerender Store
- *
- * Reads pre-rendered segment data from the worker bundle at build time.
- * The manifest module is lazily loaded via globalThis.__loadPrerenderManifestModule,
- * a function injected into the RSC entry that returns the manifest module
- * containing a key-to-specifier map and a `loadPrerenderAsset` function
- * that anchors import() resolution relative to the manifest file.
+ * Prerender Store — reads pre-rendered segment data from the worker bundle.
+ * Manifest module (injected via globalThis.__loadPrerenderManifestModule)
+ * contains key-to-specifier map and loadPrerenderAsset for import() resolution.
  */
 
-import type {
-  SerializedSegmentData,
-  SegmentHandleData,
-} from "../cache/types.js";
+import type { SerializedSegmentData } from "../cache/types.js";
 
 export interface PrerenderEntry {
   segments: SerializedSegmentData[];
-  handles: Record<string, SegmentHandleData>;
+  /** RSC-encoded handle map (see handle-snapshot.ts encodeHandles); "" when the
+   *  route pushed no handles. Encoded so Promise/ReactNode handle values survive
+   *  the JSON-serialized build artifact / dev wire, identical to the runtime cache. */
+  handles: string;
 }
 
 export interface PrerenderStore {
@@ -28,7 +24,9 @@ export interface PrerenderStore {
 
 export interface StaticEntry {
   encoded: string;
-  handles: Record<string, unknown[]>;
+  /** RSC-encoded single-segment handle data (see encodeHandleValue); "" when the
+   *  Static handler pushed no handles. */
+  handles: string;
 }
 
 export interface StaticStore {
@@ -56,6 +54,11 @@ declare global {
   var __STATIC_MANIFEST:
     | Record<string, () => Promise<{ default: string | StaticEntry }>>
     | undefined;
+  // Injected by closeBundle post-processing: lazy loader for the static
+  // manifest module (which assigns __STATIC_MANIFEST on evaluation). Resolved
+  // by static-store.ts on the first Static() lookup — issue #760.
+  // eslint-disable-next-line no-var
+  var __loadStaticManifestModule: (() => Promise<unknown>) | undefined;
   // Injected by virtual module in dev mode for on-demand prerender
   // eslint-disable-next-line no-var
   var __PRERENDER_DEV_URL: string | undefined;
@@ -75,7 +78,16 @@ export function createDevPrerenderStore(devUrl: string): PrerenderStore {
       if (isIntercept) url += "&intercept=1";
       if (meta.isPassthroughRoute) url += "&passthrough=1";
       try {
-        const res = await fetch(url);
+        // Bounded: this fetch also runs inside the PPR shell capture (a
+        // workerd waitUntil task), where an unsettled fetch does not reject —
+        // it pends until the task is torn down. Unbounded, one pending fetch
+        // wedged the per-isolate capture queue on GH runners (rotating dev
+        // capture failures; endpoint instrumentation showed 3-4ms memo HITs,
+        // so latency was never the issue — settlement was). On timeout the
+        // catch degrades to a store miss and the pipeline falls through to
+        // the live handler render (the documented dev fall-through), so the
+        // capture still lands with live content.
+        const res = await fetch(url, { signal: AbortSignal.timeout(10_000) });
         if (!res.ok) return null;
         return res.json();
       } catch {
@@ -99,13 +111,20 @@ export function createPrerenderStore(): PrerenderStore | null {
   if (!globalThis.__loadPrerenderManifestModule) return null;
 
   const cache = new Map<string, Promise<PrerenderEntry | null>>();
-  let manifestModulePromise: Promise<PrerenderManifestModule | null> | null =
-    null;
+  let manifestModulePromise: Promise<PrerenderManifestModule> | null = null;
 
-  function loadManifestModule(): Promise<PrerenderManifestModule | null> {
+  function loadManifestModule(): Promise<PrerenderManifestModule> {
     if (!manifestModulePromise) {
+      // Do not cache a failed manifest-module load: clear the memoized promise
+      // on rejection so the next get() retries, and let the error propagate
+      // (consistent with the per-asset load policy below) instead of caching a
+      // null for the isolate lifetime, which would silently degrade every
+      // prerendered route to a miss after one transient failure.
       manifestModulePromise = globalThis.__loadPrerenderManifestModule!().catch(
-        () => null,
+        (err) => {
+          manifestModulePromise = null;
+          throw err;
+        },
       );
     }
     return manifestModulePromise;
@@ -118,7 +137,6 @@ export function createPrerenderStore(): PrerenderStore | null {
       if (cached) return cached;
 
       const promise = loadManifestModule().then((mod) => {
-        if (!mod) return null;
         const specifier = mod.default[key];
         if (!specifier) return null;
         // Let asset load errors propagate — a missing/corrupted artifact
@@ -127,29 +145,20 @@ export function createPrerenderStore(): PrerenderStore | null {
         // (which the handler stub would misreport as a 404).
         return mod.loadPrerenderAsset(specifier).then((asset) => asset.default);
       });
-      cache.set(key, promise);
+      // Only memoize once the manifest module resolved: a manifest-load
+      // rejection must not poison the per-key cache, or the retry above is moot.
+      cache.set(
+        key,
+        promise.catch((err) => {
+          cache.delete(key);
+          throw err;
+        }),
+      );
       return promise;
     },
   };
 }
 
-/**
- * Load the prerender manifest index for test introspection.
- * Returns the key→specifier map or null if unavailable.
- */
-export async function loadPrerenderManifestIndex(): Promise<Record<
-  string,
-  string
-> | null> {
-  if (!globalThis.__loadPrerenderManifestModule) return null;
-  try {
-    const mod = await globalThis.__loadPrerenderManifestModule();
-    return mod.default;
-  } catch {
-    return null;
-  }
-}
-
 /**
  * Create a static segment store.
  * Production only: backed by globalThis.__STATIC_MANIFEST injected at build time.
@@ -174,7 +183,7 @@ export function createStaticStore(): StaticStore | null {
           const val = mod.default;
           // Normalize: string-only (no handles) or { encoded, handles }
           if (typeof val === "string") {
-            return { encoded: val, handles: {} } as StaticEntry;
+            return { encoded: val, handles: "" } as StaticEntry;
           }
           return val as StaticEntry;
         })

package/src/prerender.ts

@@ -33,11 +33,13 @@ import type {
   ExtractParams,
 } from "./types.js";
 import type { Handle } from "./handle.js";
+import type { HandlePush } from "./defer.js";
 import type { ContextVar } from "./context-var.js";
 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 +71,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
@@ -164,8 +166,14 @@ export interface BuildContext<TParams> {
     (key: string, value: any): void;
   };
 
-  /** Push handle data (frozen into pre-rendered output at build time). */
-  use: <T>(handle: Handle<T>) => (data: T) => void;
+  /**
+   * Push handle data (frozen into pre-rendered output at build time). Returns
+   * the full push function, including `.defer()` — a deferred slot resolved by
+   * a deep async component during the prerender render is awaited before the
+   * artifact is baked (resolve-by-default), so the baked output holds the
+   * resolved value.
+   */
+  use: <T>(handle: Handle<T>) => HandlePush<T>;
 
   /** Synthetic URL built from pattern + params (no real request). */
   url: URL;
@@ -221,8 +229,14 @@ export interface StaticBuildContext {
     (key: string, value: any): void;
   };
 
-  /** Push handle data (frozen into pre-rendered output at build time). */
-  use: <T>(handle: Handle<T>) => (data: T) => void;
+  /**
+   * Push handle data (frozen into pre-rendered output at build time). Returns
+   * the full push function, including `.defer()` — a deferred slot resolved by
+   * a deep async component during the prerender render is awaited before the
+   * artifact is baked (resolve-by-default), so the baked output holds the
+   * resolved value.
+   */
+  use: <T>(handle: Handle<T>) => HandlePush<T>;
 
   /** URL generation by route name. */
   reverse: BuildReverseFunction;
@@ -273,6 +287,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 +395,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,
@@ -421,6 +455,40 @@ export function isPrerenderPassthrough(
   );
 }
 
+/**
+ * Detect whether any resolved segment carries the passthrough sentinel.
+ *
+ * A build handler signals passthrough by returning `ctx.passthrough()` (the
+ * PRERENDER_PASSTHROUGH sentinel), which lands on the segment's `component`.
+ * But when the route declares `loading()`, the handler result is deferred
+ * upstream (segment-resolution/fresh.ts), so `component` is a thenable resolving
+ * to the sentinel rather than the sentinel itself — a synchronous
+ * `isPrerenderPassthrough(component)` on the Promise returns false and the build
+ * bakes a corrupt artifact instead of deferring. Resolve thenables first.
+ *
+ * Rejections are swallowed here: a throwing build handler resurfaces during
+ * segment serialization, preserving the prior error-handling behavior.
+ */
+export async function detectPrerenderPassthrough(
+  segments: ReadonlyArray<{ component: unknown }>,
+): Promise<boolean> {
+  for (const seg of segments) {
+    let component: unknown = seg.component;
+    if (
+      component &&
+      typeof (component as { then?: unknown }).then === "function"
+    ) {
+      try {
+        component = await component;
+      } catch {
+        continue;
+      }
+    }
+    if (isPrerenderPassthrough(component)) return true;
+  }
+  return false;
+}
+
 // -- Type guards ------------------------------------------------------------
 
 /**
@@ -472,7 +540,7 @@ export interface PassthroughHandlerDefinition<
   /** Live handler for runtime fallback on unknown params. */
   liveHandler: (
     ctx: HandlerContext<TParams, TEnv>,
-  ) => ReactNode | Promise<ReactNode> | Response | Promise<Response>;
+  ) => ReactNode | Response | Promise<ReactNode | Response>;
   /** Composable default DSL items merged when the handler is mounted. */
   use?: () => UseItems<HandlerUseItem>;
 }
@@ -484,7 +552,7 @@ export function Passthrough<
   prerenderDef: PrerenderHandlerDefinition<TParams>,
   liveHandler: (
     ctx: HandlerContext<TParams, TEnv>,
-  ) => ReactNode | Promise<ReactNode> | Response | Promise<Response>,
+  ) => ReactNode | Response | Promise<ReactNode | Response>,
 ): PassthroughHandlerDefinition<TParams, TEnv>;
 
 // Implementation
@@ -495,11 +563,11 @@ export function Passthrough<
   prerenderDef: PrerenderHandlerDefinition<TParams>,
   liveHandler: (
     ctx: HandlerContext<TParams, TEnv>,
-  ) => ReactNode | Promise<ReactNode> | Response | Promise<Response>,
+  ) => ReactNode | Response | Promise<ReactNode | Response>,
 ): 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/redirect-origin.ts

@@ -0,0 +1,143 @@
+/**
+ * Runtime-neutral same-origin redirect rule.
+ *
+ * Shared by the client redirect guard (`browser/validate-redirect-origin.ts`,
+ * which validates redirect targets the client JS is about to navigate to), the
+ * server outgoing 3xx guard (`rsc/redirect-guard.ts`, which validates every
+ * browser-followed `Location` header before it leaves the handler), and soft
+ * Flight / `X-RSC-Redirect` construction (`resolveSoftRedirectUrl`). Kept at
+ * the `src/` root so every layer imports the ONE rule and cannot drift -- a
+ * cross-origin target blocked on the JS/fetch path is blocked identically on the
+ * no-JS (PE), full-page document, and soft SPA channels.
+ */
+
+/**
+ * Resolve a redirect target against the current origin.
+ *
+ * Returns the canonical (normalized) same-origin href -- which also collapses
+ * protocol-relative (`//evil.com`) and other ambiguous forms -- or `null` when
+ * the target resolves to a different origin or is unparseable. Pure: no logging,
+ * no side effects.
+ */
+export function resolveSameOriginRedirect(
+  url: string,
+  currentOrigin: string,
+): string | null {
+  try {
+    const target = new URL(url, currentOrigin);
+    if (target.origin !== currentOrigin) {
+      return null;
+    }
+    return target.href;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Validate an explicit off-origin redirect target (`redirect(url, { external:
+ * true })`).
+ *
+ * `external` opts out of the same-origin rule, but NOT out of scheme safety:
+ * only `http:`/`https:` targets are allowed. A redirect ultimately reaches the
+ * browser via `window.location.assign()` on the SPA/action client paths, so a
+ * forged or mistaken `redirect("javascript:...", { external: true })` would be a
+ * scriptable navigation if the scheme were not checked here. Returns the
+ * normalized href for an http(s) target (same- or cross-origin), or `null`
+ * otherwise. Pure: no logging, no side effects.
+ */
+export function resolveExternalRedirect(
+  url: string,
+  currentOrigin: string,
+): string | null {
+  try {
+    const target = new URL(url, currentOrigin);
+    if (target.protocol !== "http:" && target.protocol !== "https:") {
+      return null;
+    }
+    return target.href;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The safe same-origin landing for a blocked redirect.
+ *
+ * Every guard that neutralizes a cross-origin/unsafe redirect target sends the
+ * browser here instead: the app's basename root, or `"/"` when unset. Kept
+ * beside the resolvers so the "where does a blocked redirect go" answer lives
+ * in ONE place -- the server 3xx guard (`rsc/redirect-guard.ts`), the
+ * shell-HIT degradation path (`rsc/rsc-rendering.ts`), and soft Flight/
+ * X-RSC-Redirect construction must agree, or a blocked redirect lands
+ * differently depending on which exit it took.
+ */
+export function safeSameOriginLanding(basename: string | undefined): string {
+  return basename && basename !== "/" ? basename : "/";
+}
+
+/**
+ * Resolve a soft (SPA/Flight) redirect target before it leaves the server.
+ *
+ * Soft redirects are 200/204 (`X-RSC-Redirect` / `metadata.redirect`), not 3xx,
+ * so they never hit `guardOutgoingRedirect`. This applies the same policy the
+ * 3xx guard uses: same-origin by default, `external` opts into http(s)-only
+ * off-host, anything else lands on {@link safeSameOriginLanding}. Returns the
+ * URL that should be written into the soft-redirect wire fields.
+ */
+export function resolveSoftRedirectUrl(
+  url: string,
+  requestOrigin: string,
+  basename: string | undefined,
+  external?: boolean,
+): string {
+  if (external) {
+    return (
+      resolveExternalRedirect(url, requestOrigin) ??
+      safeSameOriginLanding(basename)
+    );
+  }
+  return (
+    resolveSameOriginRedirect(url, requestOrigin) ??
+    safeSameOriginLanding(basename)
+  );
+}
+
+/**
+ * Out-of-band brand for `redirect(url, { external: true })`.
+ *
+ * The external opt-in MUST be settable only by app code calling `redirect(...,
+ * { external: true })`, never by an attacker. An earlier design carried the
+ * opt-in as a wire header (`x-rango-redirect-external`), but a wire header is
+ * forgeable: a proxy-style response route that copies an attacker-controlled
+ * upstream response's headers would let `302 Location: https://evil` plus that
+ * header bypass the same-origin guard without app code ever opting in. So the
+ * opt-in is now an out-of-band brand on the Response object itself, tracked in a
+ * `WeakSet` that cannot cross the wire. `redirect()` brands the Response; the
+ * small set of internal redirect-rebuild paths (middleware `mergeResponse`,
+ * `carryOverRedirectHeaders`, the response-route rewrap) transfer the brand onto
+ * the rebuilt Response; the guard and the SPA intercept read it. An upstream
+ * Response an app proxies is never branded, so its forged header is inert.
+ *
+ * Fail-closed: if a rebuild path ever drops the brand, the redirect is
+ * neutralized to the app root rather than allowed off-host.
+ */
+const externalRedirects = new WeakSet<Response>();
+
+/** Brand a Response as an explicit `{ external: true }` redirect (out-of-band). */
+export function markExternalRedirect(response: Response): void {
+  externalRedirects.add(response);
+}
+
+/** Read the out-of-band `{ external: true }` brand off a Response. */
+export function isExternalRedirect(response: Response): boolean {
+  return externalRedirects.has(response);
+}
+
+/**
+ * Reserved internal header name. No longer a trust signal -- the external
+ * opt-in is the out-of-band brand above. It is kept only so the redirect-rebuild
+ * paths and the guard can defensively strip any value (e.g. one forged by a
+ * proxied upstream) and guarantee it never reaches the browser.
+ */
+export const EXTERNAL_REDIRECT_MARKER: string = "x-rango-redirect-external";

package/src/regex-escape.ts

@@ -0,0 +1,8 @@
+/**
+ * Escape a string for literal use inside a RegExp. Single source of truth for
+ * the router runtime (matching) and the vite build (transform/scan); a pure,
+ * dependency-free leaf so both environments can share it.
+ */
+export function escapeRegExp(input: string): string {
+  return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/src/render-error-thrower.tsx

@@ -0,0 +1,20 @@
+"use client";
+
+import type { ReactNode } from "react";
+
+interface RenderErrorThrowerProps {
+  error: unknown;
+}
+
+/**
+ * Client component that throws the given error during render, so the nearest
+ * error boundary catches it. Errors thrown during render are caught by error
+ * boundaries; async errors (rejected promises) are not -- which is why the
+ * navigation bridge funnels processing failures through this component instead
+ * of letting them surface as uncaught rejections.
+ */
+export function RenderErrorThrower({
+  error,
+}: RenderErrorThrowerProps): ReactNode {
+  throw error;
+}

package/src/response-utils.ts

@@ -26,3 +26,37 @@ export function isWebSocketUpgradeResponse(response: Response): boolean {
     (response as unknown as { webSocket?: unknown }).webSocket != null
   );
 }
+
+/**
+ * Append `Accept` to a response's `Vary` header without duplicating it.
+ *
+ * Content-negotiated responses already carry `Vary: Accept` from the
+ * upstream layer (response-route-handler's callHandlerWithVary, or
+ * handleRscRendering baking `accept` into its vary list). The negotiated
+ * post-append in the handler would otherwise emit `Vary: Accept, Accept`,
+ * a redundant token some proxies/CDNs treat as a distinct cache key.
+ * Token match is case-insensitive (HTTP field tokens are case-insensitive)
+ * and whitespace-tolerant.
+ */
+export function appendVaryAccept(response: Response): void {
+  const existing = response.headers.get("Vary");
+  if (!existing) {
+    response.headers.set("Vary", "Accept");
+    return;
+  }
+  const hasAccept = existing
+    .split(",")
+    .some((token) => token.trim().toLowerCase() === "accept");
+  if (!hasAccept) {
+    response.headers.append("Vary", "Accept");
+  }
+}
+
+// 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,7 +1,7 @@
 import type { ExtractParams } from "./types.js";
 import type { SearchSchema, ResolveSearchSchema } from "./search-params.js";
 import { serializeSearchParams } from "./search-params.js";
-import { encodePathSegment } from "./router/url-params.js";
+import { substitutePatternParams } from "./router/substitute-pattern-params.js";
 
 /**
  * Sanitize prefix string by removing leading slash
@@ -219,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.
@@ -302,45 +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];
-          // Empty string is treated as omitted — the trie matcher fills
-          // unmatched optional params with "" (not undefined), so reverse
-          // must collapse those segments instead of leaving empty slots.
-          if (value === undefined || value === "") {
-            hadOmittedOptional = true;
-            return "";
-          }
-          return encodePathSegment(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 encodePathSegment(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) {