@rangojs/router 0.0.0-experimental.84 → 0.0.0-experimental.85

package/skills/links/SKILL.md

@@ -1,16 +1,20 @@
 ---
 name: links
-description: URL generation with ctx.reverse (server), href (client), useHref (mounted), useMount, and scopedReverse
-argument-hint: [href|useHref|useMount|scopedReverse]
+description: URL generation with ctx.reverse (server default), href (client), useHref (mounted), useMount, and scopedReverse
+argument-hint: [ctx.reverse|href|useHref|useMount|scopedReverse]
 ---
 
 # Links & URL Generation
 
 @rangojs/router provides different href APIs for server and client contexts.
 
+**Default server API: `ctx.reverse()`.** Generate URLs from the handler context — it's typed, auto-fills mount params, and resolves local (`.name`) and absolute (`name.sub`) names.
+
+**`reverse()` is server-only.** It depends on the route manifest and handler context, neither of which are available in the browser. Client components receive URLs as props, loader data, or server-action return values — they never call `reverse` directly.
+
 ## Server: ctx.reverse()
 
-Available in route handlers via HandlerContext. Resolves named routes using the full route map.
+Available in route handlers via HandlerContext. Resolves named routes using the full route map. This is the default way to generate URLs on the server.
 
 ```typescript
 import { urls, scopedReverse } from "@rangojs/router";
@@ -103,7 +107,7 @@ path("/search", (ctx) => {
 
 ### scopedReverse() - type-safe ctx.reverse
 
-Wraps `ctx.reverse` with local route type information for autocomplete and validation:
+Wraps `ctx.reverse` with local route type information for autocomplete and validation. Runtime behavior is identical to `ctx.reverse` — `scopedReverse` is a type-only cast. The same dot-prefix rule applies: local names use `.name`, global names use `name.sub`.
 
 ```typescript
 import { scopedReverse } from "@rangojs/router";
@@ -111,18 +115,74 @@ import { scopedReverse } from "@rangojs/router";
 path("/product/:slug", (ctx) => {
   const reverse = scopedReverse<typeof shopPatterns>(ctx.reverse);
 
-  reverse("cart");                        // Type-safe local name
-  reverse("product", { slug: "widget" }); // Type-safe with params
-  reverse("blog.post");                   // Absolute names (dot notation) always allowed
-  reverse("/about");                      // Path-based always allowed
+  reverse(".cart");                        // Local name (dot-prefixed) — resolves in include scope
+  reverse(".product", { slug: "widget" }); // Local name with params
+  reverse("blog.post", { slug: "hi" });    // Global name (dotted) — full route map
 
   return <ProductPage slug={ctx.params.slug} />;
 }, { name: "product" })
 ```
 
+`reverse()` does not accept raw path strings (`"/about"`). For static paths in client components, use `href("/about")`; on the server, look up the route by name.
+
+## Client components: receive URLs as props
+
+`reverse()` is not available inside `"use client"` modules — there is no handler context and no route manifest in the browser bundle. Generate the URL on the server and hand it to the client component.
+
+Three patterns, in order of preference:
+
+```tsx
+// 1. Pass as a prop from a server component
+// server
+function BlogPostPage(ctx: HandlerContext) {
+  return <ShareButton url={ctx.reverse(".post", { slug: ctx.params.slug })} />;
+}
+
+// client
+"use client";
+export function ShareButton({ url }: { url: string }) {
+  return <button onClick={() => navigator.clipboard.writeText(url)}>Share</button>;
+}
+```
+
+```tsx
+// 2. Return from a loader (attached to the route via the DSL)
+// server — loaders/nav.ts
+export const NavLoader = createLoader((ctx) => ({
+  home: ctx.reverse("home"),
+  blog: ctx.reverse("blog.index"),
+}));
+
+// server — urls.tsx: attach the loader so useLoader has data in context
+const urlpatterns = urls(({ path, loader }) => [
+  path("/", HomePage, { name: "home" }, () => [loader(NavLoader)]),
+]);
+
+// client
+"use client";
+function Nav() {
+  const { data } = useLoader(NavLoader);
+  return <Link to={data.home}>Home</Link>;
+}
+```
+
+`useLoader()` requires the loader to be attached to an active route. If you need on-demand fetching instead, use `useFetchLoader()`.
+
+```tsx
+// 3. Return from a server action
+// server
+"use server";
+export async function getProductUrl(slug: string) {
+  const ctx = getRequestContext();
+  return ctx.reverse("product", { slug });
+}
+```
+
+For static path strings (not named routes), client components can use `href()` — see below.
+
 ## Client: href()
 
-Plain function for absolute path-based URLs. No hook needed - works anywhere.
+Plain function for absolute path-based URLs. No hook needed - works anywhere in client components. `href()` validates paths at compile time, but does **not** resolve named routes — for named routes, use one of the patterns above.
 
 ```typescript
 "use client";
@@ -189,12 +249,15 @@ function MountInfo() {
 
 | Context          | API                             | Resolves                        | Use for                             |
 | ---------------- | ------------------------------- | ------------------------------- | ----------------------------------- |
-| Server handler   | `ctx.reverse("name")`           | Named routes (local + absolute) | Server-side URL generation          |
+| Server handler   | `ctx.reverse("name")`           | Named routes (local + absolute) | **Default** server-side URL generation |
 | Server handler   | `scopedReverse<T>(ctx.reverse)` | Same, with type safety          | Type-safe server URLs               |
-| Client component | `href("/path")`                 | Absolute paths                  | Global navigation                   |
+| Client component | (URL passed as prop / loader data / action return) | Named routes | Any URL derived from a named route — generate on server, pass in |
+| Client component | `href("/path")`                 | Absolute paths (static strings) | Static navigation where no named-route lookup is needed |
 | Client component | `useHref()`                     | Mount-prefixed paths            | Local navigation inside `include()` |
 | Client component | `useMount()`                    | Raw mount path                  | Custom mount-aware logic            |
 
+> `reverse()` is server-only. Client components never import or call it — they receive the already-resolved string.
+
 ## Complete example: mounted module
 
 ```typescript

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 { encodePathSegment } from "./router/url-params.js";
 
 /**
  * Sanitize prefix string by removing leading slash
@@ -318,7 +319,7 @@ export function createReverse<TRoutes extends Record<string, string>>(
             hadOmittedOptional = true;
             return "";
           }
-          return encodeURIComponent(value);
+          return encodePathSegment(value);
         },
       );
       // Second pass: required params (no trailing ?)
@@ -329,7 +330,7 @@ export function createReverse<TRoutes extends Record<string, string>>(
           if (value === undefined) {
             throw new Error(`Missing param "${key}" for route "${name}"`);
           }
-          return encodeURIComponent(value);
+          return encodePathSegment(value);
         },
       );
       // Clean up slashes only when an optional param was actually omitted,

package/src/router/handler-context.ts

@@ -18,6 +18,7 @@ import { isInsideCacheScope } from "../server/context.js";
 import { NOCACHE_SYMBOL, assertNotInsideCacheExec } from "../cache/taint.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
 import { PRERENDER_PASSTHROUGH } from "../prerender.js";
+import { encodePathSegment } from "./url-params.js";
 
 /**
  * Strip internal _rsc* query params from a URL.
@@ -181,7 +182,7 @@ export function createReverseFunction(
             hadOmittedOptional = true;
             return "";
           }
-          return encodeURIComponent(value);
+          return encodePathSegment(value);
         },
       );
       // Second pass: required params (no trailing ?)
@@ -192,7 +193,7 @@ export function createReverseFunction(
           if (value === undefined) {
             throw new Error(`Missing param "${key}" for route "${name}"`);
           }
-          return encodeURIComponent(value);
+          return encodePathSegment(value);
         },
       );
       // Clean up slashes only when an optional param was actually omitted,

package/src/router/middleware.ts

@@ -10,6 +10,7 @@
  */
 
 import { contextGet, contextSet } from "../context-var.js";
+import { safeDecodeURIComponent } from "./url-params.js";
 import type {
   CollectedMiddleware,
   MiddlewareCollectableEntry,
@@ -113,7 +114,12 @@ function escapeRegex(str: string): string {
 }
 
 /**
- * Extract params from a pathname using a pattern's regex and param names
+ * Extract params from a pathname using a pattern's regex and param names.
+ *
+ * Values are URL-decoded so apps see the raw string (e.g. "ivo@example.com")
+ * instead of the percent-encoded form ("ivo%40example.com"). This matches the
+ * contract assumed by ctx.reverse (which re-encodes) and aligns with
+ * Express/React Router/Fastify/Koa.
  */
 export function extractParams(
   pathname: string,
@@ -125,7 +131,7 @@ export function extractParams(
 
   const params: Record<string, string> = {};
   for (let i = 0; i < paramNames.length; i++) {
-    params[paramNames[i]] = match[i + 1] || "";
+    params[paramNames[i]] = safeDecodeURIComponent(match[i + 1] || "");
   }
   return params;
 }

package/src/router/pattern-matching.ts

@@ -7,6 +7,7 @@
 import type { RouteEntry, TrailingSlashMode } from "../types";
 import type { EntryData } from "../server/context";
 import { debugLog, isRouterDebugEnabled } from "./logging.js";
+import { safeDecodeURIComponent } from "./url-params.js";
 
 /**
  * Parsed segment info
@@ -82,6 +83,13 @@ export interface CompiledPattern {
   paramNames: string[];
   optionalParams: Set<string>;
   hasTrailingSlash: boolean;
+  /**
+   * Param-name → allowed values for constrained params (e.g. `:lang(en|gb)`).
+   * Validated against the **decoded** param value after regex extraction so
+   * a URL like `/en%20GB` still matches `:lang(en GB)` — matching the trie
+   * path's behavior (trie-matching.ts:validateAndBuild).
+   */
+  constraints?: Record<string, string[]>;
 }
 
 // Module-level cache for compiled patterns. Route patterns are a finite set
@@ -142,6 +150,7 @@ 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 = "";
 
@@ -152,11 +161,14 @@ export function compilePattern(pattern: string): CompiledPattern {
     } else if (segment.type === "param") {
       paramNames.push(segment.value);
       const suffixPattern = segment.suffix ? escapeRegex(segment.suffix) : "";
-      const valuePattern = segment.constraint
-        ? `(${segment.constraint.map(escapeRegex).join("|")})`
-        : segment.suffix
-          ? "([^/]+?)"
-          : "([^/]+)";
+      // Constrained params capture anything here; the allowed values are
+      // checked post-decode in findMatch so URL-encoded constraint values
+      // (e.g. `:lang(en GB)` via `/en%20GB`) still match.
+      const valuePattern = segment.suffix ? "([^/]+?)" : "([^/]+)";
+
+      if (segment.constraint) {
+        (constraints ??= {})[segment.value] = segment.constraint;
+      }
 
       if (segment.optional) {
         optionalParams.add(segment.value);
@@ -186,9 +198,33 @@ export function compilePattern(pattern: string): CompiledPattern {
     paramNames,
     optionalParams,
     hasTrailingSlash,
+    ...(constraints ? { constraints } : {}),
   };
 }
 
+/**
+ * Validate decoded params against a compiled pattern's constraints.
+ * Returns false if any constrained param has a non-empty value not in the
+ * allowed list (empty-string = absent optional, which is allowed).
+ */
+function satisfiesConstraints(
+  params: Record<string, string>,
+  constraints: Record<string, string[]> | undefined,
+): boolean {
+  if (!constraints) return true;
+  for (const name in constraints) {
+    const value = params[name];
+    if (
+      value !== undefined &&
+      value !== "" &&
+      !constraints[name].includes(value)
+    ) {
+      return false;
+    }
+  }
+  return true;
+}
+
 /**
  * Escape special regex characters in a string
  */
@@ -392,8 +428,13 @@ export function findMatch<TEnv>(
         fullPattern = entry.prefix + pattern;
       }
 
-      const { regex, paramNames, optionalParams, hasTrailingSlash } =
-        getCompiledPattern(fullPattern);
+      const {
+        regex,
+        paramNames,
+        optionalParams,
+        hasTrailingSlash,
+        constraints,
+      } = getCompiledPattern(fullPattern);
 
       // Get trailing slash mode for this route (per-route config or pattern-based)
       const trailingSlashMode: TrailingSlashMode | undefined =
@@ -412,9 +453,15 @@ export function findMatch<TEnv>(
       if (match) {
         const params: Record<string, string> = {};
         paramNames.forEach((name, index) => {
-          params[name] = match[index + 1] ?? "";
+          params[name] = safeDecodeURIComponent(match[index + 1] ?? "");
         });
 
+        // Validate constraints against decoded values; a failure falls
+        // through to the next route so other patterns can still match.
+        if (!satisfiesConstraints(params, constraints)) {
+          continue;
+        }
+
         if (effectiveDebug) {
           debugLog("findMatch", "matched route", {
             routeKey,
@@ -467,9 +514,13 @@ export function findMatch<TEnv>(
       if (altMatch) {
         const params: Record<string, string> = {};
         paramNames.forEach((name, index) => {
-          params[name] = altMatch[index + 1] ?? "";
+          params[name] = safeDecodeURIComponent(altMatch[index + 1] ?? "");
         });
 
+        if (!satisfiesConstraints(params, constraints)) {
+          continue;
+        }
+
         // Determine redirect behavior based on mode
         if (trailingSlashMode === "ignore") {
           // Match without redirect

package/src/router/trie-matching.ts

@@ -6,6 +6,7 @@
  */
 
 import type { TrieNode, TrieLeaf } from "../build/route-trie.js";
+import { safeDecodeURIComponent } from "./url-params.js";
 
 export interface TrieMatchResult {
   /** Route name */
@@ -173,20 +174,25 @@ function validateAndBuild(
   originalPathname: string,
   pathnameHasTrailingSlash: boolean,
 ): TrieMatchResult | null {
-  // Build named params by zipping leaf.pa with positional paramValues
+  // Build named params by zipping leaf.pa with positional paramValues.
+  // Params are URL-decoded at this boundary so ctx.params holds the values
+  // apps expect (matching Express/React Router) and round-trip cleanly
+  // through ctx.reverse.
   const params: Record<string, string> = {};
   if (leaf.pa) {
     for (let i = 0; i < leaf.pa.length && i < paramValues.length; i++) {
-      params[leaf.pa[i]] = paramValues[i];
+      params[leaf.pa[i]] = safeDecodeURIComponent(paramValues[i]);
     }
   }
 
   // Add wildcard param (wildcard leaves have pn from TrieNode.w type)
   if (wildcardValue !== undefined && "pn" in leaf) {
-    params[(leaf as TrieLeaf & { pn: string }).pn] = wildcardValue;
+    params[(leaf as TrieLeaf & { pn: string }).pn] =
+      safeDecodeURIComponent(wildcardValue);
   }
 
-  // Validate constraints
+  // Validate constraints against decoded values so constraint lists can be
+  // written in decoded form (e.g. ["en-GB", "en US"]).
   if (leaf.cv) {
     for (const paramName in leaf.cv) {
       const allowed = leaf.cv[paramName]!;

package/src/router/url-params.ts

@@ -0,0 +1,49 @@
+/**
+ * URL param encode/decode at the route boundary.
+ *
+ * Extraction (decode): regex/trie matchers keep param values URL-encoded;
+ * `safeDecodeURIComponent` turns them back into raw strings so `ctx.params`
+ * matches the contract apps expect (Express/React Router/Fastify/Koa) and
+ * round-trips through reverse stay stable. Malformed %-encoding is
+ * preserved as-is so a broken URL doesn't crash matching.
+ *
+ * Reversal (encode): `encodePathSegment` escapes only what RFC 3986
+ * requires for a path segment — `/`, `?`, `#`, space, control chars,
+ * non-ASCII — and leaves pchar sub-delims (`@ : $ & + , ; =` and friends)
+ * readable. `encodeURIComponent` over-encodes for path segments, which
+ * makes generated URLs harder for humans to read in the address bar
+ * (e.g. mailbox IDs like `ivo@example.com` would become
+ * `ivo%40example.com` even though `@` is path-legal).
+ */
+
+export function safeDecodeURIComponent(raw: string): string {
+  if (raw === "" || raw.indexOf("%") === -1) return raw;
+  try {
+    return decodeURIComponent(raw);
+  } catch {
+    return raw;
+  }
+}
+
+// encodeURIComponent over-encodes for path segments. After running it,
+// un-encode the pchar sub-delims + (`:` / `@`) so the resulting URL
+// keeps human-readable characters that are legal in a path segment.
+// Everything dangerous — `/ ? # %` and space/control/non-ASCII — stays
+// encoded.
+const PATH_SAFE_ESCAPES: Record<string, string> = {
+  "%3A": ":",
+  "%40": "@",
+  "%24": "$",
+  "%26": "&",
+  "%2B": "+",
+  "%2C": ",",
+  "%3B": ";",
+  "%3D": "=",
+};
+
+export function encodePathSegment(value: string): string {
+  return encodeURIComponent(value).replace(
+    /%(?:3A|40|24|26|2B|2C|3B|3D)/gi,
+    (match) => PATH_SAFE_ESCAPES[match.toUpperCase()] ?? match,
+  );
+}