fix: encode path params per RFC 3986 path-segment rules in href/generatePath

Follow-up to #15277, which fixed `href()` to URL-encode param values to
match `generatePath()`. Both now encode with `encodeURIComponent`, which
implements *query-string* escaping — a stricter rule than URL paths
require. This over-escapes characters that RFC 3986 explicitly allows
literally in a path segment:

    pchar      = unreserved / pct-encoded / sub-delims / ":" / "@"
    sub-delims = "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "="

https://datatracker.ietf.org/doc/html/rfc3986#section-3.3

`$ & + , ; = : @` only act as delimiters in a query string; in a path
segment they carry no special meaning, and browsers keep them literal in
`location.pathname`. Encoding them needlessly rewrites URLs:

    href("/releases/:v", { v: "1.0.0+1" })
    // before: /releases/1.0.0%2B1
    // after:  /releases/1.0.0+1

which breaks apps that compare generated URLs against
`window.location.pathname` (the browser reports the literal `+`), churns
canonical/shareable URLs, and makes `href()` output disagree with what
users see in the address bar.

Changes:

- Add an internal `encodePathParam()` that escapes structural/unsafe
  characters (`/ ? # %`, whitespace, non-ASCII) exactly as before, but
  restores the RFC 3986 pchar set that `encodeURIComponent` over-escapes
- Use it for named params in `generatePath()` and for named params and
  splat segments in `href()`
- Document path-segment vs query-string encoding semantics (with the RFC
  reference) in the `href()` and `generatePath()` JSDoc
- Update and extend unit tests; add a change file

Behavior is unchanged for every character outside `$ & + , ; = : @`, and
`generatePath()`'s splat values remain un-encoded, as before.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: nowells

packages/react-router/.changes/patch.encode-path-params-pchar.md

@@ -0,0 +1,4 @@
+Encode path params in `href`/`generatePath` per RFC 3986 path-segment rules instead of `encodeURIComponent`
+
+- Characters that are valid literally in a path segment (`$ & + , ; = : @` — RFC 3986 `pchar`) are no longer percent-encoded, so values like a semver build `1.0.0+1` interpolate unchanged instead of becoming `1.0.0%2B1`
+- Structural/unsafe characters (`/ ? # %`, whitespace, non-ASCII) are still escaped exactly as before

packages/react-router/__tests__/generatePath-test.tsx

@@ -141,6 +141,28 @@ describe("generatePath", () => {
     });
   });
 
+  describe("param encoding", () => {
+    it("encodes characters that would change the URL structure", () => {
+      expect(generatePath("/courses/:id", { id: "a b?c#d%e" })).toBe(
+        "/courses/a%20b%3Fc%23d%25e",
+      );
+      expect(generatePath("/courses/:id", { id: "café…" })).toBe(
+        "/courses/caf%C3%A9%E2%80%A6",
+      );
+    });
+
+    it("preserves characters RFC 3986 allows literally in a path segment", () => {
+      // pchar sub-delims plus ":" and "@" — see RFC 3986 §3.3
+      expect(generatePath("/courses/:id", { id: "$&+,;=:@" })).toBe(
+        "/courses/$&+,;=:@",
+      );
+      // e.g. a semver build suffix survives untouched
+      expect(generatePath("/releases/:version", { version: "1.0.0+1" })).toBe(
+        "/releases/1.0.0+1",
+      );
+    });
+  });
+
   it("throws only on missing named parameters, but not missing splat params", () => {
     expect(() => generatePath(":foo")).toThrow();
     expect(() => generatePath("/:foo")).toThrow();

packages/react-router/__tests__/href-test.ts

@@ -52,20 +52,43 @@ describe("href", () => {
     expect(href("/products/:id", { id: "abc#frag" })).toBe(
       "/products/abc%23frag",
     );
+    // "?" is escaped (it would start the query string), "=" is not (it is a
+    // valid pchar in a path segment, unlike in a query string)
     expect(href("/products/:id", { id: "abc?x=1" })).toBe(
-      "/products/abc%3Fx%3D1",
+      "/products/abc%3Fx=1",
+    );
+  });
+
+  it("preserves characters RFC 3986 allows literally in a path segment", () => {
+    // pchar sub-delims plus ":" and "@" — see RFC 3986 §3.3
+    expect(href("/products/:id", { id: "$&+,;=:@" })).toBe(
+      "/products/$&+,;=:@",
+    );
+    // e.g. a semver build suffix survives untouched
+    expect(href("/releases/:version", { version: "1.0.0+1" })).toBe(
+      "/releases/1.0.0+1",
     );
   });
 
   it("encodes splat param values while preserving segments", () => {
     expect(href("/:param/*", { param: "a?b/c#d", "*": "e?f/g#h" })).toBe(
       "/a%3Fb%2Fc%23d/e%3Ff/g%23h",
     );
+    expect(href("/releases/*", { "*": "v1/1.0.0+1" })).toBe(
+      "/releases/v1/1.0.0+1",
+    );
   });
 
   it("round-trips through matchPath for param values with special characters", () => {
     let pattern = "/products/:id";
-    for (let id of ["shoes/2026-summer", "abc#frag", "abc?x=1", "a b"]) {
+    for (let id of [
+      "shoes/2026-summer",
+      "abc#frag",
+      "abc?x=1",
+      "a b",
+      "$&+,;=:@",
+      "1.0.0+1",
+    ]) {
       let result = href(pattern, { id });
       // before the fix, href()'s own output didn't match its own pattern
       let match = matchPath(pattern, result);

packages/react-router/lib/href.ts

@@ -1,3 +1,4 @@
+import { encodePathParam } from "./router/utils";
 import type { Pages } from "./types/register";
 import type { Equal } from "./types/utils";
 
@@ -25,6 +26,16 @@ function stringify(p: any) {
 
   <Link to={href("/products/:id", { id: "abc123" })} />
   ```
+
+  Param values are percent-encoded for use in a path segment: characters that
+  would change the URL structure (`/`, `?`, `#`, `%`, whitespace, non-ASCII)
+  are escaped, while characters that RFC 3986 allows literally in a path
+  segment (`$ & + , ; = : @` — see
+  [RFC 3986 §3.3](https://datatracker.ietf.org/doc/html/rfc3986#section-3.3))
+  are kept as-is. Note this differs from query-string encoding
+  (`encodeURIComponent`/`URLSearchParams`), where those characters are
+  delimiters and must be escaped. Splat (`*`) values are encoded per segment,
+  preserving `/` separators.
  */
 export function href<Path extends keyof Args>(
   path: Path,
@@ -42,7 +53,7 @@ export function href<Path extends keyof Args>(
             `Path '${path}' requires param '${param}' but it was not provided`,
           );
         }
-        return value == null ? "" : "/" + encodeURIComponent(stringify(value));
+        return value == null ? "" : "/" + encodePathParam(stringify(value));
       },
     );
 
@@ -53,7 +64,7 @@ export function href<Path extends keyof Args>(
     const value = params?.["*"];
     if (value !== undefined) {
       result +=
-        "/" + stringify(value).split("/").map(encodeURIComponent).join("/");
+        "/" + stringify(value).split("/").map(encodePathParam).join("/");
     }
   }
 

packages/react-router/lib/router/utils.ts

@@ -1480,13 +1480,71 @@ function matchRouteBranch<
   return matches;
 }
 
+/**
+ * Characters that `encodeURIComponent` escapes but that are valid literally in
+ * a URL path segment. Per RFC 3986 §3.3, a path segment is made of `pchar`:
+ *
+ * ```
+ * pchar = unreserved / pct-encoded / sub-delims / ":" / "@"
+ * sub-delims = "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "="
+ * ```
+ *
+ * `encodeURIComponent` targets query-string values, where `$ & + , ; = : @`
+ * are delimiters and must be escaped — but in a path segment they carry no
+ * special meaning, and browsers keep them literal in `location.pathname`.
+ * (`! ' ( ) *` and the unreserved set are already left alone by
+ * `encodeURIComponent`, so they need no restoring.)
+ */
+const PATH_PARAM_OVERESCAPED: Record<string, string> = {
+  "%24": "$",
+  "%26": "&",
+  "%2B": "+",
+  "%2C": ",",
+  "%3A": ":",
+  "%3B": ";",
+  "%3D": "=",
+  "%40": "@",
+};
+
+/**
+ * Encodes a param value for interpolation into a single URL path segment.
+ *
+ * Escapes characters that would break the path (`/ ? # %`, whitespace,
+ * non-ASCII, …) while leaving characters that RFC 3986 permits literally in a
+ * path segment (see {@link PATH_PARAM_OVERESCAPED}) untouched. Escaping those
+ * would needlessly rewrite URLs — e.g. a semver build param `1.0.0+1` would
+ * become `1.0.0%2B1` even though browsers display and match the `+` literally
+ * in `location.pathname`.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc3986#section-3.3
+ * @param value The param value to encode.
+ * @returns The encoded value, safe for use as a single path segment.
+ */
+export function encodePathParam(value: string): string {
+  return encodeURIComponent(value).replace(
+    /%(?:24|26|2B|2C|3A|3B|3D|40)/g,
+    (match) => PATH_PARAM_OVERESCAPED[match],
+  );
+}
+
 /**
  * Returns a path with params interpolated.
  *
+ * Param values are percent-encoded for use in a path segment: characters that
+ * would change the URL structure (`/`, `?`, `#`, `%`, whitespace, non-ASCII)
+ * are escaped, while characters that RFC 3986 allows literally in a path
+ * segment (`$ & + , ; = : @` — see
+ * [RFC 3986 §3.3](https://datatracker.ietf.org/doc/html/rfc3986#section-3.3))
+ * are kept as-is. Note this differs from query-string encoding
+ * (`encodeURIComponent`/`URLSearchParams`), where those characters are
+ * delimiters and must be escaped.
+ *
  * @example
  * import { generatePath } from "react-router";
  *
  * generatePath("/users/:id", { id: "123" }); // "/users/123"
+ * generatePath("/files/:name", { name: "a b" }); // "/files/a%20b"
+ * generatePath("/releases/:v", { v: "1.0.0+1" }); // "/releases/1.0.0+1"
  *
  * @public
  * @category Utils
@@ -1532,7 +1590,7 @@ export function generatePath<Path extends string>(
         const [, key, optional, suffix] = keyMatch;
         let param = params[key as keyof typeof params];
         invariant(optional === "?" || param != null, `Missing ":${key}" param`);
-        return encodeURIComponent(stringify(param)) + suffix;
+        return encodePathParam(stringify(param)) + suffix;
       }
 
       // Remove any optional markers from optional static segments