@rangojs/router 0.0.0-experimental.139 → 0.0.0-experimental.140

package/src/index.ts

@@ -228,6 +228,23 @@ export function headers(): never {
   throw serverOnlyStubError("headers");
 }
 
+/**
+ * Client/SSR passthrough for `live()` (the PPR hole primitive). Unlike the
+ * cookies()/headers() stubs this is a REAL function: there is no shell capture
+ * off the react-server condition, so live() simply runs the thunk (or returns
+ * the promise). The capture-aware implementation lives in index.rsc.ts
+ * (./server/live.js). See docs/design/ppr-shell-resume.md.
+ */
+export function live<T>(fn: () => Promise<T> | T): Promise<T>;
+export function live<T>(promise: Promise<T>): Promise<T>;
+export function live<T>(
+  input: (() => Promise<T> | T) | Promise<T>,
+): Promise<T> {
+  return typeof input === "function"
+    ? Promise.resolve((input as () => Promise<T> | T)())
+    : input;
+}
+
 /**
  * Client implementation of `invalidateClientCache()`. Unlike the server-only
  * stubs above this is a REAL function under the `default` condition (it marks

package/src/router/middleware.ts

@@ -104,11 +104,20 @@ export function compileMiddlewarePattern(pattern: string): {
     const segment = segments[i];
 
     if (segment.type === "wildcard") {
-      // Optional subtree match (parity with the original middleware parser,
-      // which compiled every `*` as `(?:/.*)?`). A trailing `*` matches the
-      // subtree; a non-trailing `*` matches zero-or-more intermediate segments,
-      // so `/a/<star>/b` still matches `/a/b`.
-      regexStr += "(?:/.*)?";
+      if (segment.value === "*") {
+        // Bare `*`: optional subtree match, no capture (parity with the original
+        // middleware parser). A trailing `*` matches the subtree; a non-trailing
+        // `*` matches zero-or-more intermediate segments, so `/a/<star>/b` still
+        // matches `/a/b`.
+        regexStr += "(?:/.*)?";
+      } else {
+        // Named catch-all `:name+` / `:name*`: capture the remainder under the
+        // name so a scoping middleware sees `ctx.params.<name>`, and respect the
+        // one-or-more arity (`+` must not match the bare prefix), mirroring the
+        // route matcher instead of collapsing to the bare-`*` subtree.
+        paramNames.push(segment.value);
+        regexStr += segment.oneOrMore ? "/(.+)" : "(?:/(.*))?";
+      }
       if (i === segments.length - 1) {
         hasTrailingWildcard = true;
       }

package/src/router/parse-pattern.ts

@@ -0,0 +1,115 @@
+/**
+ * Route pattern parsing (grammar only).
+ *
+ * Deliberately dependency-free so it is safe to bundle into the CLIENT — the
+ * reverse helper (`substitute-pattern-params.ts` -> `use-reverse`) needs it, and
+ * pulling it from `pattern-matching.ts` would drag that module's server-only
+ * transitive imports (`node:async_hooks` via `logging.ts`) into the browser.
+ * `pattern-matching.ts` re-exports these so existing importers are unaffected.
+ */
+
+/**
+ * Parsed segment info
+ */
+export interface ParsedSegment {
+  type: "static" | "param" | "wildcard";
+  value: string; // static text, param name, or "*"
+  optional: boolean;
+  constraint?: string[]; // enum values like ["en", "gb"]
+  suffix?: string; // literal text after param in same segment (e.g., ".html")
+  /**
+   * Named catch-all repeat modifier. On a `wildcard` segment whose `value` is a
+   * param name (`:name+` / `:name*`), `true` marks one-or-more (`+`, rejects the
+   * zero-segment case); absent/false marks zero-or-more (`*`, and the bare `/*`).
+   */
+  oneOrMore?: boolean;
+}
+
+/**
+ * Parse a route pattern into segments
+ *
+ * Supports:
+ * - Static: /blog, /about
+ * - Params: /:slug, /:id
+ * - Optional: /:locale?, /:page?
+ * - Constrained: /:locale(en|gb), /:type(post|page)
+ * - Optional + Constrained: /:locale(en|gb)?
+ * - Wildcard: /*
+ * - Named catch-all: /:slug* (zero-or-more), /:path+ (one-or-more)
+ */
+export function parsePattern(pattern: string): ParsedSegment[] {
+  const segments: ParsedSegment[] = [];
+  // The `([+*])?` group peels a trailing `+`/`*` off a `:name` BEFORE the
+  // literal-suffix group `([^/]*)` so it can be inspected. Whether it is a
+  // catch-all MODIFIER or a literal suffix character is decided below — a bare
+  // trailing `+`/`*` is the named catch-all of issue #634; any other combination
+  // is folded back into the literal suffix so previously-valid patterns are
+  // unaffected. It sits after `(\?)?` so `:name?*` is seen as `?` + suffix `*`.
+  const segmentRegex =
+    /\/(:([a-zA-Z_][a-zA-Z0-9_]*)(\(([^)]+)\))?(\?)?([+*])?([^/]*)|(\*)|([^/]+))/g;
+
+  let match;
+  while ((match = segmentRegex.exec(pattern)) !== null) {
+    const [
+      ,
+      ,
+      paramName,
+      ,
+      constraint,
+      optional,
+      repeat,
+      suffix,
+      wildcard,
+      staticText,
+    ] = match;
+
+    if (wildcard) {
+      // Bare `/*`: zero-or-more, captured under "*".
+      segments.push({ type: "wildcard", value: "*", optional: false });
+    } else if (paramName) {
+      // A trailing `+`/`*` is a named catch-all ONLY when it stands alone on the
+      // param — no `?`, no constraint, no literal suffix after it. In any other
+      // combination it is the start of a literal suffix, exactly as before this
+      // feature existed, so `:version+build` still matches `/…/v1+build` and
+      // never throws at registration.
+      if (repeat && !suffix && optional !== "?" && !constraint) {
+        segments.push({
+          type: "wildcard",
+          value: paramName,
+          optional: false,
+          oneOrMore: repeat === "+",
+        });
+      } else {
+        segments.push({
+          type: "param",
+          value: paramName,
+          optional: optional === "?",
+          constraint: constraint ? constraint.split("|") : undefined,
+          // Fold a non-modifier `+`/`*` back into the literal suffix.
+          suffix: (repeat ?? "") + (suffix ?? "") || undefined,
+        });
+      }
+    } else if (staticText) {
+      segments.push({ type: "static", value: staticText, optional: false });
+    }
+  }
+
+  // A named catch-all consumes the remainder, so it only makes sense as the final
+  // segment. If it isn't last, it isn't really a catch-all: restore the literal
+  // parse (`:name` + literal `+`/`*` suffix) rather than error, so a pattern like
+  // `/docs/:slug+/edit` keeps its pre-feature behavior (matches `/docs/x+/edit`).
+  // Bare `/*` keeps its historical mid-pattern leniency and is left untouched.
+  for (let i = 0; i < segments.length - 1; i++) {
+    const s = segments[i];
+    if (s.type === "wildcard" && s.value !== "*") {
+      segments[i] = {
+        type: "param",
+        value: s.value,
+        optional: false,
+        suffix: s.oneOrMore ? "+" : "*",
+      };
+    }
+  }
+
+  return segments;
+}

package/src/router/pattern-matching.ts

@@ -9,65 +9,13 @@ import type { EntryData } from "../server/context";
 import { debugLog, isRouterDebugEnabled } from "./logging.js";
 import { escapeRegExp } from "../regex-escape.js";
 import { safeDecodeURIComponent } from "./url-params.js";
+import { parsePattern, type ParsedSegment } from "./parse-pattern.js";
 
-/**
- * Parsed segment info
- */
-export interface ParsedSegment {
-  type: "static" | "param" | "wildcard";
-  value: string; // static text, param name, or "*"
-  optional: boolean;
-  constraint?: string[]; // enum values like ["en", "gb"]
-  suffix?: string; // literal text after param in same segment (e.g., ".html")
-}
-
-/**
- * Parse a route pattern into segments
- *
- * Supports:
- * - Static: /blog, /about
- * - Params: /:slug, /:id
- * - Optional: /:locale?, /:page?
- * - Constrained: /:locale(en|gb), /:type(post|page)
- * - Optional + Constrained: /:locale(en|gb)?
- * - Wildcard: /*
- */
-export function parsePattern(pattern: string): ParsedSegment[] {
-  const segments: ParsedSegment[] = [];
-  const segmentRegex =
-    /\/(:([a-zA-Z_][a-zA-Z0-9_]*)(\(([^)]+)\))?(\?)?([^/]*)|(\*)|([^/]+))/g;
-
-  let match;
-  while ((match = segmentRegex.exec(pattern)) !== null) {
-    const [
-      ,
-      ,
-      paramName,
-      ,
-      constraint,
-      optional,
-      suffix,
-      wildcard,
-      staticText,
-    ] = match;
-
-    if (wildcard) {
-      segments.push({ type: "wildcard", value: "*", optional: false });
-    } else if (paramName) {
-      segments.push({
-        type: "param",
-        value: paramName,
-        optional: optional === "?",
-        constraint: constraint ? constraint.split("|") : undefined,
-        suffix: suffix || undefined,
-      });
-    } else if (staticText) {
-      segments.push({ type: "static", value: staticText, optional: false });
-    }
-  }
-
-  return segments;
-}
+// `parsePattern`/`ParsedSegment` live in the dependency-free `parse-pattern.ts`
+// so the client reverse helper can import them without dragging this module's
+// server-only deps into the browser bundle. Re-exported here for existing
+// importers (build/route-trie, middleware, tests).
+export { parsePattern, type ParsedSegment };
 
 /**
  * Compiled pattern result containing regex, param metadata, and trailing slash info.
@@ -83,6 +31,14 @@ export interface CompiledPattern {
    * path's behavior (trie-matching.ts:validateAndBuild).
    */
   constraints?: Record<string, string[]>;
+  /**
+   * The pattern's catch-all param, if any (`*` for bare `/*`, the name for a
+   * named `:name+`/`:name*`). A zero-or-more catch-all (`oneOrMore: false`)
+   * whose optional group is absent binds "" rather than being omitted — so
+   * `/docs` matches `/docs/:slug*` with `slug === ""`. `oneOrMore` keeps the
+   * same polarity as `ParsedSegment.oneOrMore` and the trie's `w1`.
+   */
+  catchAll?: { name: string; oneOrMore: boolean };
 }
 
 // Module-level cache for compiled patterns. Route patterns are a finite set
@@ -143,13 +99,32 @@ export function compilePattern(pattern: string): CompiledPattern {
   const segments = parsePattern(normalizedPattern);
   const paramNames: string[] = [];
   let constraints: Record<string, string[]> | undefined;
+  let catchAll: { name: string; oneOrMore: boolean } | undefined;
 
   let regexPattern = "";
 
   for (const segment of segments) {
     if (segment.type === "wildcard") {
-      paramNames.push("*");
-      regexPattern += "/(.*)";
+      // Wildcards capture the remainder under `segment.value` ("*" for the bare
+      // form, the param name for a named catch-all).
+      paramNames.push(segment.value);
+      catchAll = { name: segment.value, oneOrMore: Boolean(segment.oneOrMore) };
+      if (segment.oneOrMore) {
+        // `:name+` — one-or-more, rejects the zero-segment (bare-prefix) case.
+        regexPattern += "/(.+)";
+      } else {
+        // Zero-or-more catch-all: named `:name*` OR the bare `/*` (both parse to
+        // `oneOrMore: false`). The whole `/segment` is optional so the bare
+        // prefix matches directly, aligning the regex fallback with the trie
+        // (which already matches the bare prefix binding "" — trie-matching.ts);
+        // buildParamsFromMatch binds "" when the optional group is absent.
+        //
+        // The bare `/*` previously used a required `/(.*)`, so `/files/*` failed
+        // to match `/files` and fell through to trailing-slash normalization,
+        // emitting a corrupt `/file` redirect instead of a match (issue #636,
+        // parity row C1). It is the same alignment #635 made for named `:name*`.
+        regexPattern += "(?:/(.*))?";
+      }
     } else if (segment.type === "param") {
       paramNames.push(segment.value);
       const suffixPattern = segment.suffix ? escapeRegExp(segment.suffix) : "";
@@ -202,6 +177,7 @@ export function compilePattern(pattern: string): CompiledPattern {
     paramNames,
     hasTrailingSlash,
     ...(constraints ? { constraints } : {}),
+    ...(catchAll ? { catchAll } : {}),
   };
 }
 
@@ -236,16 +212,29 @@ function satisfiesConstraints(
  * keys so `ctx.params.<name>` reads as `undefined` rather than `""`. This
  * keeps the runtime aligned with the `ExtractParams` type and matches the
  * trie matcher's contract (see `trie-matching.ts:validateAndBuild`).
+ *
+ * A zero-or-more catch-all (`compiled.catchAll`, `oneOrMore: false`) whose
+ * optional group didn't capture binds "" instead of being omitted, so `/docs`
+ * matches `/docs/:slug*` with `slug === ""`. Exported so the `renderRoute`
+ * testing harness (`matchLeaf`) shares this exact logic instead of forking it.
  */
-function buildParamsFromMatch(
+export function buildParamsFromMatch(
   match: RegExpExecArray,
   paramNames: string[],
+  catchAll?: { name: string; oneOrMore: boolean },
 ): Record<string, string> {
   const params: Record<string, string> = {};
   paramNames.forEach((name, index) => {
     const captured = match[index + 1];
     if (captured !== undefined) {
+      // A catch-all remainder decodes identically whether split-per-segment or
+      // whole-string (a literal `/` never lives inside a `%XX` escape), so a
+      // single decode is correct and cheapest.
       params[name] = safeDecodeURIComponent(captured);
+    } else if (catchAll && name === catchAll.name && !catchAll.oneOrMore) {
+      // A zero-or-more catch-all (`:name*` or the bare `/*`) whose optional
+      // group was absent binds "" rather than being omitted.
+      params[name] = "";
     }
   });
   return params;
@@ -454,7 +443,7 @@ export function findMatch<TEnv>(
         fullPattern = entry.prefix + pattern;
       }
 
-      const { regex, paramNames, hasTrailingSlash, constraints } =
+      const { regex, paramNames, hasTrailingSlash, constraints, catchAll } =
         getCompiledPattern(fullPattern);
 
       const trailingSlashMode: TrailingSlashMode | undefined =
@@ -469,7 +458,7 @@ export function findMatch<TEnv>(
 
       const match = regex.exec(pathname);
       if (match) {
-        const params = buildParamsFromMatch(match, paramNames);
+        const params = buildParamsFromMatch(match, paramNames, catchAll);
 
         if (!satisfiesConstraints(params, constraints)) {
           continue;
@@ -518,7 +507,7 @@ export function findMatch<TEnv>(
 
       const altMatch = regex.exec(alternatePathname);
       if (altMatch) {
-        const params = buildParamsFromMatch(altMatch, paramNames);
+        const params = buildParamsFromMatch(altMatch, paramNames, catchAll);
 
         if (!satisfiesConstraints(params, constraints)) {
           continue;

package/src/router/segment-resolution/fresh.ts

@@ -19,6 +19,7 @@ import type {
 } from "../../types";
 import type { SegmentResolutionDeps } from "../types.js";
 import { resolveLoaderData } from "./loader-cache.js";
+import { isShellCaptureActive } from "./loader-mask.js";
 import {
   handleHandlerResult,
   tryStaticHandler,
@@ -60,6 +61,16 @@ export async function resolveLoaders<TEnv>(
   const hasLoading = "loading" in entry && entry.loading !== undefined;
   const loadingDisabled = hasLoading && entry.loading === false;
 
+  // Emit the streaming (non-awaiting) loader shape when loading is enabled OR
+  // during a PPR shell capture. In capture, loaders are masked with
+  // never-resolving promises (loader-mask.ts); the loading-disabled branch below
+  // AWAITS the loader promises, which would hang the capture render's match()
+  // forever on those masked promises. Forcing the streaming shape lets match()
+  // complete so the prerender can postpone the loader subtrees as holes. The
+  // `!loadingDisabled` short-circuit keeps the ALS check off the hot path (only
+  // loading-disabled entries consult it), so normal requests are unchanged.
+  const emitStreaming = !loadingDisabled || isShellCaptureActive();
+
   // Error context for wrapLoaderPromise: without it, a throwing DSL loader never
   // fires createRouter({ onError }) (phase "loader") nor emits the loader.error
   // telemetry event — wrapLoaderPromise only builds the onError/telemetry path
@@ -67,7 +78,7 @@ export async function resolveLoaders<TEnv>(
   // loader failures the same way handlers/actions/routing/fetchable-loaders do.
   const errorContext = buildLoaderErrorContext(ctx);
 
-  if (!loadingDisabled) {
+  if (emitStreaming) {
     // Streaming loaders: promises kick off now, settle during RSC serialization.
     const segments = loaderEntries.map((loaderEntry, i) => {
       const { loader } = loaderEntry;

package/src/router/segment-resolution/loader-cache.ts

@@ -36,6 +36,10 @@ import {
 } from "../../cache/cache-policy.js";
 import { readThroughItem } from "../../cache/read-through-swr.js";
 import { recordRequestTags } from "../../cache/cache-tag.js";
+import {
+  isShellCaptureActive,
+  createMaskedLoaderPromise,
+} from "./loader-mask.js";
 // Lazy-loaded to avoid pulling @vitejs/plugin-rsc/rsc into modules that
 // import segment-resolution but never use loader caching.
 let _serializeResult: typeof import("../../cache/segment-codec.js").serializeResult;
@@ -127,6 +131,16 @@ export function resolveLoaderData<TEnv>(
   ctx: HandlerContext<any, TEnv>,
   pathname: string,
 ): Promise<any> {
+  // PPR shell capture: never execute the loader. Its slot gets a never-resolving
+  // promise so the Suspense subtree postpones (a hole). Gate here — the single
+  // funnel every loader segment path routes through (fresh resolveLoaders,
+  // cache-hit resolveLoadersOnly, revalidation resolveLoadersOnlyWithRevalidation)
+  // — so no loader fn runs and no loader-cache getItem/setItem round-trip happens
+  // during capture. See loader-mask.ts and docs/design/ppr-shell-resume.md.
+  if (isShellCaptureActive()) {
+    return createMaskedLoaderPromise();
+  }
+
   const cacheConfig = loaderEntry.cache;
 
   // No cache config or disabled — run fresh (zero overhead path)

package/src/router/segment-resolution/loader-mask.ts

@@ -0,0 +1,44 @@
+/**
+ * PPR shell-capture loader masking.
+ *
+ * During a shell CAPTURE re-render (Axis 2, see docs/design/ppr-shell-resume.md)
+ * route loaders are the "live lane": they must NOT execute — no side effects, no
+ * cost, no cache round-trips. Instead every loader segment's value slot receives
+ * a never-resolving promise, so the loader-consuming Suspense subtree stays
+ * pending and React's static `prerender` marks it as a postponed hole. The frozen
+ * shell (prelude) captures only the fallback; the resumed serve pass runs the
+ * loaders fresh through the unchanged execution path and streams their output
+ * into the holes.
+ *
+ * Capture mode is signalled by `requestCtx._shellCaptureRun`, set to true ONLY on
+ * the derived request context of the background capture task (shell-capture.ts) —
+ * NOT by the foreground render, whose `_shellCapture` descriptor merely means "a
+ * capture is wanted" and must not change behavior. This module is the single home
+ * for the mask so every loader execution site gates the same way (loader-cache.ts
+ * `resolveLoaderData`, fresh.ts `resolveLoaders`).
+ */
+
+import { _getRequestContext } from "../../server/request-context.js";
+
+/**
+ * True when the current render is the active PPR shell capture and route loaders
+ * must be masked rather than executed. Reads `_shellCaptureRun` off the ALS
+ * request context (the capture task re-establishes its derived context via
+ * runWithRequestContext), so it is accurate at the loader resolution sites, which
+ * run synchronously inside the pipeline's context frame.
+ */
+export function isShellCaptureActive(): boolean {
+  return _getRequestContext()?._shellCaptureRun === true;
+}
+
+/**
+ * A promise that never settles — the masked stand-in for a loader's value during
+ * shell capture. The consuming Suspense subtree suspends forever, so the static
+ * prerender postpones it as a hole instead of baking a per-request value into the
+ * shared shell. The capture abort (`maxWaitMs` in captureShellHTML) bounds how
+ * long the prerender waits before it freezes the prelude, so this never hangs the
+ * request.
+ */
+export function createMaskedLoaderPromise<T = unknown>(): Promise<T> {
+  return new Promise<T>(() => {});
+}

package/src/router/substitute-pattern-params.ts

@@ -1,12 +1,23 @@
-import { encodePathSegment } from "./url-params.js";
+import { encodePathSegment, encodePathRemainder } from "./url-params.js";
+import { parsePattern } from "./parse-pattern.js";
 
 /**
  * Substitute `:param` placeholders in a route pattern with values from
- * `params`. Two-pass: optional params (`:name?`) first so absent values
- * collapse cleanly, then required params (throws on missing). Constraint
- * syntax (`:name(en|gb)`) is stripped from the result. Trailing-slash
- * patterns like `/blog/` are preserved unless an optional segment was
- * actually omitted.
+ * `params`, producing a URL. Built by walking the SAME parsed segments the
+ * matcher uses (`parsePattern`) and emitting one piece per segment — so a
+ * substituted value is never re-scanned as if it were another placeholder (a
+ * catch-all value like `sha:abc/x` used to make the "required" pass read `:abc`
+ * and throw). Constraint syntax (`:name(en|gb)`) is stripped; trailing-slash
+ * patterns like `/blog/` are preserved unless an optional segment was omitted.
+ *
+ * Semantics per segment:
+ * - static             -> emitted verbatim.
+ * - `:name`            -> required; `undefined` throws, `""` yields an empty segment.
+ * - `:name?`           -> optional; `undefined`/`""` omitted.
+ * - `:name*` / `:name+`-> catch-all; the value is multi-segment, so each segment
+ *                         is encoded and the `/` separators are preserved. `+`
+ *                         (one-or-more) throws when absent; `*` (and bare `*`)
+ *                         omit when absent.
  *
  * Shared by `ctx.reverse()` (server), `createReverse()` (typed runtime
  * helper), and `useReverse()` (client hook). The behavior must stay
@@ -17,40 +28,48 @@ export function substitutePatternParams(
   params: Record<string, string | undefined>,
   routeName: string,
 ): string {
-  let result = pattern;
-  let hadOmittedOptional = false;
+  const hasTrailingSlash = pattern.length > 1 && pattern.endsWith("/");
+  const normalized = hasTrailingSlash ? pattern.slice(0, -1) : pattern;
+  const segments = parsePattern(normalized);
 
-  result = result.replace(
-    /:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?(\?)/g,
-    (_match, key) => {
-      const value = params[key as string];
-      // The matcher omits absent optional params (so `value` is `undefined`
-      // here), but caller-supplied params or `getParams()` shapes may still
-      // pass `""` explicitly. Treat both as the absent form.
+  const parts: string[] = [];
+  for (const seg of segments) {
+    if (seg.type === "static") {
+      parts.push("/" + seg.value);
+    } else if (seg.type === "wildcard") {
+      const value = params[seg.value];
       if (value === undefined || value === "") {
-        hadOmittedOptional = true;
-        return "";
+        // `:name+` requires at least one segment; bare `*` / `:name*` collapse.
+        if (seg.oneOrMore) {
+          throw new Error(
+            `Missing param "${seg.value}" for route "${routeName}"`,
+          );
+        }
+      } else {
+        parts.push("/" + encodePathRemainder(value));
       }
-      return encodePathSegment(value);
-    },
-  );
-
-  result = result.replace(
-    /:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?(?!\?)/g,
-    (_match, key) => {
-      const value = params[key as string];
-      if (value === undefined) {
-        throw new Error(`Missing param "${key}" for route "${routeName}"`);
+    } else {
+      // Plain param. Constraint (`seg.constraint`) is intentionally not re-emitted.
+      const value = params[seg.value];
+      const suffix = seg.suffix ?? "";
+      if (seg.optional) {
+        // The matcher omits absent optionals (`undefined`); callers/getParams()
+        // may pass `""` explicitly — treat both as absent.
+        if (value !== undefined && value !== "") {
+          parts.push("/" + encodePathSegment(value) + suffix);
+        }
+      } else {
+        if (value === undefined) {
+          throw new Error(
+            `Missing param "${seg.value}" for route "${routeName}"`,
+          );
+        }
+        parts.push("/" + encodePathSegment(value) + suffix);
       }
-      return encodePathSegment(value);
-    },
-  );
-
-  if (hadOmittedOptional) {
-    const hadTrailingSlash = pattern.length > 1 && pattern.endsWith("/");
-    result = result.replace(/\/\/+/g, "/").replace(/\/+$/, "") || "/";
-    if (hadTrailingSlash && !result.endsWith("/")) result += "/";
+    }
   }
 
+  let result = parts.join("") || "/";
+  if (hasTrailingSlash && !result.endsWith("/")) result += "/";
   return result;
 }

package/src/router/trie-matching.ts

@@ -63,7 +63,8 @@ export function tryTrieMatch(
     // same value the regex matcher produces for the bare prefix. Without this
     // the trie misses, the regex fallback runs, and its no-config branch emits
     // a corrupt slice-off redirect. The static terminal still wins above.
-    if (trie.w) {
+    // A one-or-more catch-all (`w1`, from `:name+`) rejects this empty case.
+    if (trie.w && !trie.w.w1) {
       return validateAndBuild(
         trie.w,
         [],
@@ -192,8 +193,9 @@ function walkTrie(
     // walkTrie otherwise only reaches node.w in the index<length branch below,
     // so without this a request to the wildcard's own prefix misses the trie
     // and the regex fallback emits a corrupt redirect. A static terminal
-    // (node.r) still wins.
-    if (node.w) {
+    // (node.r) still wins. A one-or-more catch-all (`w1`, from `:name+`) rejects
+    // this empty case — it requires at least one trailing segment.
+    if (node.w && !node.w.w1) {
       const validatedParams = leafConstraintsPass(node.w, paramValues, "");
       if (validatedParams) {
         return {
@@ -250,14 +252,20 @@ function walkTrie(
 
   if (node.w) {
     const rest = joinRemainingSegments(segments, index);
-    const validatedParams = leafConstraintsPass(node.w, paramValues, rest);
-    if (validatedParams) {
-      return {
-        leaf: node.w,
-        paramValues: [...paramValues],
-        wildcardValue: rest,
-        validatedParams,
-      };
+    // A one-or-more catch-all (`w1`, from `:name+`) requires at least one
+    // non-empty trailing segment. `rest` can still be "" here on a malformed
+    // double-slash URL (e.g. `/docs//` splits to a trailing "" segment), so
+    // guard this in-path site the same way the root and base-case sites are.
+    if (!(node.w.w1 && rest === "")) {
+      const validatedParams = leafConstraintsPass(node.w, paramValues, rest);
+      if (validatedParams) {
+        return {
+          leaf: node.w,
+          paramValues: [...paramValues],
+          wildcardValue: rest,
+          validatedParams,
+        };
+      }
     }
   }
 

package/src/router/url-params.ts

@@ -42,3 +42,16 @@ export function encodePathSegment(value: string): string {
     (match) => PATH_SAFE_ESCAPES[match.toUpperCase()] ?? match,
   );
 }
+
+/**
+ * Encode a catch-all remainder: encode each `/`-separated segment but keep the
+ * separators, so `a/b c` -> `a/b%20c` (not `a%2Fb%20c`). Shared by the reverse
+ * helper and the build-time prerender substitution so both produce identical
+ * URLs. `encode` defaults to the path-safe `encodePathSegment`.
+ */
+export function encodePathRemainder(
+  value: string,
+  encode: (segment: string) => string = encodePathSegment,
+): string {
+  return value.split("/").map(encode).join("/");
+}