@rangojs/router 0.0.0-experimental.115 → 0.0.0-experimental.117

package/src/href-client.ts

@@ -16,7 +16,6 @@
 
 import type { GetRegisteredRoutes } from "./types.js";
 import type { JsonSerialize } from "./serialize.js";
-import type { ResponseEnvelope } from "./urls.js";
 
 /**
  * Parse constraint values into a union type for paths
@@ -163,16 +162,16 @@ type ResponsePayloadForKey<
     }[keyof TRoutes];
 
 /**
- * Public response type for a route, keyed by pattern or concrete path. The
- * payload is wrapped in `JsonSerialize` so it describes the JSON **wire** value a
- * consumer receives from `fetch().then(r => r.json())`, not the handler's raw
- * return type — e.g. a handler returning `{ createdAt: Date }` resolves here to
- * `ResponseEnvelope<{ createdAt: string }>`.
+ * Public response type for a route, keyed by pattern or concrete path. JSON
+ * response routes send the handler's return value verbatim (bare), so the
+ * payload is wrapped only in `JsonSerialize` to describe the JSON **wire** value
+ * a consumer receives from `fetch().then(r => r.json())` — e.g. a handler
+ * returning `{ createdAt: Date }` resolves here to `{ createdAt: string }`.
  */
 export type PathResponse<
   TPath extends string,
   TRoutes = GetRegisteredRoutes,
-> = ResponseEnvelope<JsonSerialize<ResponsePayloadFor<TPath, TRoutes>>>;
+> = JsonSerialize<ResponsePayloadFor<TPath, TRoutes>>;
 
 /**
  * Strip trailing slash from a path (e.g., "/blog/" -> "/blog" | "/blog/")
@@ -256,7 +255,7 @@ declare global {
      *
      * The payload is the JSON **wire** shape (via `Rango.JsonSerialize`), not the
      * handler's raw return — a handler returning `{ createdAt: Date }` resolves
-     * here to `ResponseEnvelope<{ createdAt: string }>`, matching what
+     * here to `{ createdAt: string }` (bare, no envelope), matching what
      * `fetch().then(r => r.json())` actually yields.
      *
      * Only resolves once `Rango.RegisteredRoutes` carries response metadata (the

package/src/index.rsc.ts

@@ -138,8 +138,7 @@ export {
   type IncludeOptions,
   type IncludeItem,
   type RouteResponse,
-  type ResponseError,
-  type ResponseEnvelope,
+  type ProblemDetails,
   type ResponseHandler,
   type ResponseHandlerContext,
   type JsonResponseHandler,

package/src/index.ts

@@ -104,8 +104,7 @@ export type {
   JsonResponsePathFn,
   TextResponsePathFn,
   RouteResponse,
-  ResponseError,
-  ResponseEnvelope,
+  ProblemDetails,
 } from "./urls.js";
 
 // Middleware context types

package/src/router/find-match.ts

@@ -1,5 +1,5 @@
 import { tryTrieMatch } from "./trie-matching.js";
-import { getRouteTrie, getRouterTrie } from "../route-map-builder.js";
+import { getRouterTrie } from "../route-map-builder.js";
 import {
   findMatch as findRouteMatch,
   isLazyEvaluationNeeded,
@@ -8,6 +8,19 @@ import {
 import type { MetricsStore } from "../server/context";
 import type { RouteEntry } from "../types";
 
+// Return a shallow copy with an independent `params` object. The single-entry
+// cache below is module-lifetime and keyed only on pathname, so the same result
+// object is handed to every same-pathname request in the isolate. ctx.params
+// aliases this `params` (see request-context), so without an own copy a handler
+// that mutates ctx.params would corrupt the cached entry for later requests.
+// `entry` and the flags are intentionally shared by reference: they are
+// read-only, and entry identity is compared in match-api (prevMatch.entry).
+function cloneMatchResult<TEnv>(
+  r: RouteMatchResult<TEnv> | null,
+): RouteMatchResult<TEnv> | null {
+  return r ? { ...r, params: { ...r.params } } : null;
+}
+
 export interface FindMatchDeps<TEnv = any> {
   routesEntries: RouteEntry<TEnv>[];
   evaluateLazyEntry: (entry: RouteEntry<TEnv>) => void;
@@ -35,9 +48,10 @@ export function createFindMatch<TEnv = any>(
     pathname: string,
     ms?: MetricsStore,
   ): RouteMatchResult<TEnv> | null {
-    // Return cached result if same pathname (avoids double-match per request)
+    // Return cached result if same pathname (avoids double-match per request).
+    // Clone so a caller mutating ctx.params cannot corrupt the shared cache.
     if (lastFindMatchPathname === pathname) {
-      return lastFindMatchResult;
+      return cloneMatchResult(lastFindMatchResult);
     }
 
     // Helper to push sub-metrics
@@ -56,12 +70,19 @@ export function createFindMatch<TEnv = any>(
     // routers and must not be used — in multi-router setups (host routing)
     // overlapping paths like "/" would match the wrong app's route.
     const routeTrie = getRouterTrie(deps.routerId);
+    // Whether the trie produced a match for this pathname (independent of
+    // whether the owning RouteEntry was resolvable yet). Used to suppress the
+    // R3 dev warning below: if the trie DID match but we fell through to the
+    // regex fallback only because a lazy entry was not spliced in yet, that is
+    // not a trie gap.
+    let trieMatched = false;
     if (routeTrie) {
       const trieStart = performance.now();
       const trieResult = tryTrieMatch(routeTrie, pathname);
       pushMetric?.("match:trie", trieStart);
 
       if (trieResult) {
+        trieMatched = true;
         // Find the RouteEntry that contains this route.
         // Multiple entries can share the same staticPrefix (e.g., several
         // include("/", patterns) calls all produce staticPrefix=""). Evaluate
@@ -114,7 +135,6 @@ export function createFindMatch<TEnv = any>(
             params: trieResult.params,
             optionalParams: new Set(trieResult.optionalParams || []),
             redirectTo: trieResult.redirectTo,
-            ancestry: trieResult.ancestry,
             ...(trieResult.pr ? { pr: true } : {}),
             ...(trieResult.pt ? { pt: true } : {}),
             ...(trieResult.responseType
@@ -125,7 +145,7 @@ export function createFindMatch<TEnv = any>(
               : {}),
             ...(trieResult.rscFirst ? { rscFirst: true } : {}),
           };
-          return lastFindMatchResult;
+          return cloneMatchResult(lastFindMatchResult);
         }
       }
     }
@@ -153,8 +173,36 @@ export function createFindMatch<TEnv = any>(
     }
     pushMetric?.("match:regex-fallback", regexStart);
 
+    // The trie is the single source of truth and is built before findMatch in
+    // both dev (handler rebuild) and production (ensureRouterManifest). If the
+    // trie was present yet the regex fallback resolved a real match, the trie
+    // has a gap (e.g. a route shape it cannot represent) and dev/prod could
+    // diverge if the trie were ever absent. Surface it in dev; folded out in
+    // production builds.
+    //
+    // Suppress when the trie DID match (`trieMatched`): that path falls through
+    // to the regex fallback only on the first request to a not-yet-spliced lazy
+    // entry (e.g. a 2+-level nested include whose deeper parent has not been
+    // evaluated). The trie knew the route; runtime lazy discovery simply lagged.
+    // That is the supported lazy-include flow, not a trie gap, so warning on it
+    // is a false positive (it manufactures bug reports and erodes the signal).
+    if (
+      process.env.NODE_ENV !== "production" &&
+      routeTrie &&
+      !trieMatched &&
+      result &&
+      !isLazyEvaluationNeeded(result)
+    ) {
+      console.warn(
+        `[@rangojs/router] Route "${pathname}" resolved via the regex fallback ` +
+          `even though the route trie was present. The trie should be the single ` +
+          `matching source of truth; this indicates a trie gap. Please report this ` +
+          `with your route configuration.`,
+      );
+    }
+
     lastFindMatchPathname = pathname;
     lastFindMatchResult = result;
-    return result;
+    return cloneMatchResult(result);
   };
 }

package/src/router/lazy-includes.ts

@@ -1,5 +1,5 @@
 import { registerRouteMap } from "../route-map-builder.js";
-import { extractStaticPrefix } from "./pattern-matching.js";
+import { extractStaticPrefix, joinPrefix } from "./pattern-matching.js";
 import {
   type EntryData,
   RangoContext,
@@ -81,11 +81,16 @@ export function evaluateLazyEntry<TEnv = any>(
   // Check for pre-computed routes from build-time data.
   // Only leaf nodes (no nested includes) are precomputed, so entries with
   // nested lazy includes fall through to the handler below.
-  // When multiple entries share the same staticPrefix (e.g., several
-  // include("/", ...) calls), the precomputed data merges all their routes
-  // into one entry. Assigning that merged set to the first matching entry
-  // causes findMatch to pick the wrong handler for routes belonging to a
-  // different include. Skip the shortcut when the prefix is shared.
+  //
+  // The load-bearing protection against two includes sharing a staticPrefix
+  // lives UPSTREAM in buildPrecomputedByPrefix (build/prefix-tree-utils): a
+  // shared staticPrefix is omitted from the map entirely, so currentPrecomputed
+  // never returns routes for it and the shortcut is skipped. The live-count
+  // check below is a secondary guard only — it is TIMING-BLIND (it counts
+  // routesEntries, which cannot see a nested sibling that has not been spliced
+  // in yet), so it must NOT be relied on alone. Kept as defense-in-depth for the
+  // all-siblings-live case (e.g. several include("/", ...) placeholders created
+  // up front).
   const currentPrecomputed = deps.getPrecomputedByPrefix();
   if (currentPrecomputed) {
     const routes = currentPrecomputed.get(entry.staticPrefix);
@@ -113,7 +118,15 @@ export function evaluateLazyEntry<TEnv = any>(
   const lazyPatterns = entry.lazyPatterns as UrlPatterns<TEnv>;
   const lazyContext = entry.lazyContext;
 
-  // Create a new context for evaluating the lazy patterns
+  // Create a new context for evaluating the lazy patterns.
+  // KNOWN REDUNDANCY (LP3, docs/internal/matching-and-lazy-discovery.md): this
+  // runs lazyPatterns.handler() purely to extract `patterns` (route name ->
+  // pattern) for matching, and DISCARDS the EntryData `manifest` it builds.
+  // loadManifest() then runs the SAME handler again on the first request to
+  // build the EntryData tree for rendering. Unifying the two runs is deferred
+  // (the two run in different contexts — see the LP3 todo in
+  // lazy-include-perf.test.ts). The precomputed-entries shortcut above avoids
+  // THIS run entirely for leaf includes.
   const manifest = new Map<string, EntryData>();
   const patterns = new Map<string, string>();
   const patternsByPrefix = new Map<string, Map<string, string>>();
@@ -145,10 +158,13 @@ export function evaluateLazyEntry<TEnv = any>(
       includeScope: lazyContext?.includeScope,
     },
     () => {
-      // Run the lazy patterns handler with the original context prefixes
-      // The prefix comes from the IncludeItem stored in lazyPatterns
+      // Run the lazy patterns handler with the original context prefixes.
+      // The prefix comes from the IncludeItem stored in lazyPatterns. Use the
+      // slash-collapsing join so a trailing-slash parent prefix does not bake a
+      // double slash into the registered route patterns (entry.routes,
+      // reverse(), EntryData.pattern, mountPath) when the handler runs.
       const includePrefix = (entry as any)._lazyPrefix || "";
-      const fullPrefix = (lazyContext?.urlPrefix || "") + includePrefix;
+      const fullPrefix = joinPrefix(lazyContext?.urlPrefix, includePrefix);
 
       if (fullPrefix || lazyContext?.namePrefix) {
         runWithPrefixes(fullPrefix, lazyContext?.namePrefix, () => {
@@ -190,10 +206,13 @@ export function evaluateLazyEntry<TEnv = any>(
   // Detect nested lazy includes and register them as new entries
   const nestedLazyIncludes = findLazyIncludes(handlerResult);
   for (const lazyInclude of nestedLazyIncludes) {
-    // Compute the full URL prefix (combining parent prefix if any)
-    const fullPrefix = lazyInclude.context.urlPrefix
-      ? lazyInclude.context.urlPrefix + lazyInclude.prefix
-      : lazyInclude.prefix;
+    // Compute the full URL prefix (combining parent prefix if any). Use the
+    // slash-collapsing join so a trailing-slash parent prefix does not produce
+    // a double-slash staticPrefix the trie's sp can never match.
+    const fullPrefix = joinPrefix(
+      lazyInclude.context.urlPrefix,
+      lazyInclude.prefix,
+    );
 
     const nestedEntry: RouteEntry<TEnv> & { _lazyPrefix?: string } = {
       prefix: "",

package/src/router/loader-resolution.ts

@@ -27,6 +27,8 @@ import { _getRequestContext } from "../server/request-context.js";
 import {
   isInsideLoaderScope,
   runInsideLoaderBodyScope,
+  isInsidePushCallbackScope,
+  runInsidePushCallbackScope,
 } from "../server/context.js";
 import { debugLog } from "./logging.js";
 
@@ -290,6 +292,12 @@ function createLoaderExecutor<TEnv>(
             );
           }
           const segmentOrder = reqCtx._renderBarrierSegmentOrder ?? [];
+          // The complete snapshot is cached at barrier resolution for
+          // non-streaming trees, and by rendered() after handleStore.settled for
+          // streaming trees (where the eager snapshot would have been incomplete
+          // because loading() handlers were still in flight). Either way it is
+          // present by the time a loader reads a handle; the fresh build is only
+          // a defensive fallback.
           const snapshot =
             reqCtx._renderBarrierHandleSnapshot ??
             buildHandleSnapshot(reqCtx._handleStore, segmentOrder);
@@ -311,15 +319,7 @@ function createLoaderExecutor<TEnv>(
           );
         }
 
-        // Guard: reject streaming trees
         const reqCtx = reqCtxRef ?? _getRequestContext();
-        if (reqCtx?._treeHasStreaming) {
-          throw new Error(
-            `ctx.rendered() is not supported when the matched route tree uses loading(). ` +
-              `Streaming handlers may not have settled when rendered() resolves. ` +
-              `Remove loading() from the route tree or restructure to avoid rendered().`,
-          );
-        }
 
         if (renderedPromise) return renderedPromise;
 
@@ -330,7 +330,10 @@ function createLoaderExecutor<TEnv>(
         }
 
         // Bidirectional deadlock check: if a handler already started
-        // awaiting this loader, calling rendered() would deadlock.
+        // awaiting this loader, calling rendered() would deadlock. This is the
+        // real cycle guard (it holds for both streaming and non-streaming): the
+        // handler blocks segment resolution, which blocks the barrier, which
+        // blocks this loader.
         if (reqCtx._handlerLoaderDeps?.has(currentLoaderId)) {
           throw new Error(
             `Deadlock: loader "${currentLoaderId}" called ctx.rendered() but a handler ` +
@@ -348,7 +351,29 @@ function createLoaderExecutor<TEnv>(
         }
         reqCtx._renderBarrierWaiters.add(currentLoaderId);
 
-        renderedPromise = reqCtx._renderBarrier.then(() => {
+        // Streaming trees (loading()): the barrier resolves once the segment
+        // tree is resolved, but loading() handlers stream behind Suspense and
+        // their handle pushes are still in flight then. Their async execution
+        // IS tracked in the handle store (trackHandler -> store.track), so after
+        // the barrier we seal (no further handlers register once the tree is
+        // resolved) and wait for settled — every tracked handler, streaming
+        // included, has finished pushing. The loader's own segment streams in
+        // after, so this does not block the shell; the deadlock guard above
+        // keeps a handler from depending on this loader.
+        const streaming = reqCtx._treeHasStreaming === true;
+        renderedPromise = reqCtx._renderBarrier.then(async () => {
+          if (streaming) {
+            reqCtx._handleStore.seal();
+            await reqCtx._handleStore.settled;
+            // The eager snapshot was intentionally left unbuilt for streaming
+            // (it would have been incomplete). Build the complete one once, now
+            // that the store has settled, so every ctx.use(handle) reads the
+            // cached snapshot instead of rebuilding it per call.
+            reqCtx._renderBarrierHandleSnapshot ??= buildHandleSnapshot(
+              reqCtx._handleStore,
+              reqCtx._renderBarrierSegmentOrder ?? [],
+            );
+          }
           renderedResolved = true;
         });
         return renderedPromise;
@@ -404,12 +429,6 @@ export function setupLoaderAccess<TEnv>(
 
   const useLoader = createLoaderExecutor(ctx, loaderPromises);
 
-  // Track whether we're inside a handle push callback. Loaders started
-  // from push callbacks (e.g. push(async () => ctx.use(Loader))) do NOT
-  // block segment resolution, so they must not be registered as handler
-  // dependencies for deadlock detection.
-  let insideHandlePush = false;
-
   ctx.use = ((item: LoaderDefinition<any, any> | Handle<any, any>) => {
     if (isHandle(item)) {
       const handle = item;
@@ -430,15 +449,17 @@ export function setupLoaderAccess<TEnv>(
         if (!store) return;
 
         if (typeof dataOrFn === "function") {
-          // Mark scope so ctx.use(loader) calls inside the callback
-          // are not registered as handler-to-loader deps.
-          insideHandlePush = true;
-          try {
-            const result = (dataOrFn as () => Promise<unknown>)();
-            store.push(handle.$$id, segmentId, result);
-          } finally {
-            insideHandlePush = false;
-          }
+          // Run the callback inside the push-callback scope so ctx.use(loader)
+          // calls it makes — including after its own awaits, for an async
+          // callback — are not registered as handler-to-loader deps and do not
+          // trip the deadlock guard. A pushed promise value is not tracked by
+          // handleStore.settled and does not block segment resolution, so it
+          // cannot form a rendered() deadlock. The ALS scope (not a plain
+          // boolean) is what survives the callback's awaits.
+          const result = runInsidePushCallbackScope(() =>
+            (dataOrFn as () => Promise<unknown>)(),
+          );
+          store.push(handle.$$id, segmentId, result);
           return;
         }
 
@@ -450,9 +471,12 @@ export function setupLoaderAccess<TEnv>(
     // Skip when inside a DSL loader scope (resolveLoaderData also calls
     // ctx.use() but that's DSL-to-DSL, not handler-to-loader) or when
     // inside a handle push callback (push callbacks don't block segment
-    // resolution so they can't cause rendered() deadlocks).
+    // resolution so they can't cause rendered() deadlocks). The push-callback
+    // check is an ALS scope so it also exempts an ASYNC callback's continuation
+    // after its first await — relevant on streaming trees, where the guard
+    // state now stays live until handleStore.settled.
     const loader = item as LoaderDefinition<any, any>;
-    if (!isInsideLoaderScope() && !insideHandlePush) {
+    if (!isInsideLoaderScope() && !isInsidePushCallbackScope()) {
       const reqCtx = reqCtxRef ?? _getRequestContext();
       if (reqCtx) {
         // Direction 1: handler awaits loader that already called rendered()
@@ -466,13 +490,18 @@ export function setupLoaderAccess<TEnv>(
               `Move the data dependency to a loader-to-loader pattern instead.`,
           );
         }
-        // Direction 2: track dep so rendered() can detect the deadlock
-        // if the loader calls it later. Skip when the barrier has already
-        // resolved — no deadlock is possible (rendered() resolves immediately).
-        // _renderBarrierSegmentOrder is undefined before resolution, string[]
-        // after. This also prevents false positives from handle push callbacks
-        // that resume after their first await (post-barrier-resolution).
-        if (reqCtx._renderBarrierSegmentOrder === undefined) {
+        // Direction 2: track dep so rendered() can detect the deadlock if the
+        // loader calls it later. Skip once the guard window is CLOSED — for a
+        // non-streaming tree that is when the barrier resolves (rendered()
+        // resolves immediately), and for a streaming tree it is when
+        // handleStore.settled completes (rendered() keeps waiting until then, so
+        // a loading() handler resuming after the barrier can still form a
+        // cycle). Using the explicit guard-closed flag rather than
+        // _renderBarrierSegmentOrder keeps tracking live across the streaming
+        // settle wait. (Handle push callbacks are already excluded above via
+        // isInsidePushCallbackScope(), so they cannot produce false positives
+        // here.)
+        if (!reqCtx._renderBarrierGuardClosed) {
           if (!reqCtx._handlerLoaderDeps) reqCtx._handlerLoaderDeps = new Set();
           reqCtx._handlerLoaderDeps.add(loader.$$id);
         }

package/src/router/manifest.ts

@@ -14,6 +14,7 @@ import {
   type MetricsStore,
 } from "../server/context";
 import MapRootLayout from "../server/root-layout";
+import { joinPrefix } from "./pattern-matching.js";
 import type { RouteEntry } from "../types";
 import type { UrlPatterns } from "../urls";
 import { VERSION } from "@rangojs/router:version";
@@ -23,10 +24,17 @@ import { VERSION } from "@rangojs/router:version";
 // stable references), so the resulting EntryData tree can be safely cached and reused
 // across requests within the same isolate.
 //
-// Cache is keyed by (VERSION, mountIndex, routeKey, isSSR). VERSION comes from the
+// Cache is keyed by (VERSION, routerId, mountIndex, routeKey, isSSR). routeKey is
+// REQUIRED in the key: loadManifest() runs the handler with forRoute=routeKey, and
+// path-helper.ts prunes (skips registering) every route except forRoute, so the
+// resulting Store.manifest is pruned to the requested route — NOT the full include.
+// Dropping routeKey would make a sibling route miss and overwrite this entry with its
+// own pruned manifest, so alternating sibling requests would thrash (re-run the
+// handler every time). Running the include handler once per isolate instead of once
+// per route is possible but needs an unpruned manifest cache with prune-on-read — see
+// LP1 in docs/internal/matching-and-lazy-discovery.md. VERSION comes from the
 // @rangojs/router:version virtual module which Vite invalidates on RSC module HMR.
 // When VERSION changes, this module re-evaluates and the cache is recreated empty.
-// Including VERSION in the key is additional defense against stale entries.
 const manifestModuleCache = new Map<string, Map<string, EntryData>>();
 
 /**
@@ -34,8 +42,8 @@ const manifestModuleCache = new Map<string, Map<string, EntryData>>();
  * Handles lazy imports, unwrapping, and validation
  *
  * Results are cached at module level after first execution. Subsequent calls
- * for the same (routeKey, isSSR) within the same isolate return cached data
- * without re-executing the DSL handler.
+ * for the same (routerId, mountIndex, routeKey, isSSR) within the same isolate
+ * return cached data without re-executing the DSL handler.
  */
 /**
  * Clear the module-level manifest cache.
@@ -65,9 +73,11 @@ export async function loadManifest(
 
   const mountIndex = entry.mountIndex;
 
-  // Check module-level cache (persists across requests within same isolate)
+  // Check module-level cache (persists across requests within same isolate).
   // Include routerId so multi-router setups (host routing) don't share cached
   // EntryData across routers with overlapping mountIndex + routeKey combinations.
+  // routeKey is in the key because loadManifest() builds a manifest pruned to
+  // forRoute=routeKey (see path-helper.ts) — see the cache comment above.
   const cacheKey = `${VERSION}:${entry.routerId ?? ""}:${mountIndex ?? ""}:${routeKey}:${isSSR ? 1 : 0}`;
   const cached = manifestModuleCache.get(cacheKey);
   if (cached) {
@@ -176,7 +186,10 @@ export async function loadManifest(
         if (entry.lazy && entry.lazyPatterns) {
           const lazyPatterns = entry.lazyPatterns as UrlPatterns<any>;
           const includePrefix = (entry as any)._lazyPrefix || "";
-          const fullPrefix = (lazyContext?.urlPrefix || "") + includePrefix;
+          // Slash-collapsing join so a trailing-slash parent prefix does not
+          // bake a double slash into the registered route patterns (must match
+          // the same join in evaluateLazyEntry / the build-time runWithPrefixes).
+          const fullPrefix = joinPrefix(lazyContext?.urlPrefix, includePrefix);
 
           if (fullPrefix || lazyContext?.namePrefix) {
             return runWithPrefixes(fullPrefix, lazyContext?.namePrefix, () =>

package/src/router/pattern-matching.ts

@@ -317,6 +317,21 @@ export function extractStaticPrefix(pattern: string): string {
   return pattern.slice(0, lastSlash);
 }
 
+/**
+ * Join a URL prefix to a sub-prefix, collapsing the duplicate slash when the
+ * base ends with "/" and the sub-prefix starts with "/". This mirrors the
+ * canonical join in `include()` (urls/include-helper.ts) and `runWithPrefixes`
+ * (server/context.ts) so a nested lazy include's runtime staticPrefix matches
+ * the build-time trie's `sp` (e.g. `include("/parent/", …)` containing
+ * `include("/child", …)` resolves to `/parent/child`, not `/parent//child`).
+ */
+export function joinPrefix(base: string | undefined, prefix: string): string {
+  if (!base) return prefix;
+  return base.endsWith("/") && prefix.startsWith("/")
+    ? base + prefix.slice(1)
+    : base + prefix;
+}
+
 /**
  * Match a pathname against registered routes
  *
@@ -343,8 +358,6 @@ export interface RouteMatchResult<TEnv = any> {
   params: Record<string, string>;
   optionalParams: Set<string>;
   redirectTo?: string;
-  /** Ancestry shortCodes for layout pruning (from trie match) */
-  ancestry?: string[];
   /** Route has pre-rendered data available (from trie) */
   pr?: true;
   /** Passthrough: handler kept for live fallback on unknown params (from trie) */

package/src/router/router-interfaces.ts

@@ -365,6 +365,17 @@ export interface RangoInternal<
   /** @internal basename for runtime manifest generation */
   readonly __basename?: string;
 
+  /**
+   * @internal Router-level error/notFound fallbacks (`createRouter` options),
+   * exposed for the build-time clientChunks discovery so a `"use client"`
+   * default boundary is routed into the dedicated `app-fallback` chunk. Unlike
+   * the route-tree `errorBoundary()`/`notFoundBoundary()` helpers these never
+   * land in `EntryData`, so they are read directly off the router instance.
+   */
+  readonly __defaultErrorBoundary?: RangoOptions<TEnv>["defaultErrorBoundary"];
+  readonly __defaultNotFoundBoundary?: RangoOptions<TEnv>["defaultNotFoundBoundary"];
+  readonly __notFound?: RangoOptions<TEnv>["notFound"];
+
   match(
     request: Request,
     input?: RouterRequestInput<TEnv>,

package/src/router/trie-matching.ts

@@ -19,8 +19,6 @@ export interface TrieMatchResult {
    * from `params` (read as `undefined`), matching the
    * `ExtractParams<"/:locale?/...">` type. */
   optionalParams?: string[];
-  /** Ancestry shortCodes for layout pruning */
-  ancestry: string[];
   /** Redirect target if trailing slash requires it */
   redirectTo?: string;
   /** Route has pre-rendered data available */
@@ -63,6 +61,19 @@ export function tryTrieMatch(
         pathnameHasTrailingSlash,
       );
     }
+    // A root-level wildcard ("/*") matches "/" with an empty remainder, the
+    // 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) {
+      return validateAndBuild(
+        trie.w,
+        [],
+        "",
+        pathname,
+        pathnameHasTrailingSlash,
+      );
+    }
     return null;
   }
 
@@ -105,6 +116,15 @@ function walkTrie(
     if (node.r) {
       return { leaf: node.r, paramValues: [...paramValues] };
     }
+    // A wildcard at this node matches the bare prefix with an empty remainder
+    // (e.g. "/files" against "/files/*"), mirroring the regex matcher's `*=""`.
+    // 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) {
+      return { leaf: node.w, paramValues: [...paramValues], wildcardValue: "" };
+    }
     return null;
   }
 
@@ -229,7 +249,6 @@ function validateAndBuild(
     routeKey: leaf.n,
     sp: leaf.sp,
     params,
-    ancestry: leaf.a,
   };
 
   if (leaf.op) result.optionalParams = leaf.op;

package/src/router.ts

@@ -21,6 +21,7 @@ import type { AllUseItems } from "./route-types.js";
 import type { UrlPatterns } from "./urls.js";
 import type { UrlBuilder } from "./urls/pattern-types.js";
 import { urls } from "./urls.js";
+import { buildPrecomputedByPrefix } from "./build/prefix-tree-utils.js";
 import {
   type EntryData,
   getContext,
@@ -70,6 +71,7 @@ import {
 } from "./router/middleware.js";
 import {
   extractStaticPrefix,
+  joinPrefix,
   traverseBack,
 } from "./router/pattern-matching.js";
 import { resolveSink, safeEmit, getRequestId } from "./router/telemetry.js";
@@ -363,9 +365,11 @@ export function createRouter<TEnv = any>(
       getRouterPrecomputedEntries(routerId) ?? getPrecomputedEntries();
     if (current !== precomputedSource) {
       precomputedSource = current;
-      precomputedByPrefix = current
-        ? new Map(current.map((e) => [e.staticPrefix, e.routes]))
-        : null;
+      // buildPrecomputedByPrefix drops any staticPrefix owned by more than one
+      // leaf include instead of collapsing it last-wins (which would mis-assign
+      // one include's routes to another's entry and 500 a valid sibling route).
+      // Such shared-prefix includes resolve via the handler path instead.
+      precomputedByPrefix = current ? buildPrecomputedByPrefix(current) : null;
     }
     return precomputedByPrefix;
   }
@@ -832,10 +836,13 @@ export function createRouter<TEnv = any>(
 
       // Create placeholder RouteEntry for each lazy include
       for (const lazyInclude of lazyIncludes) {
-        // Compute the full URL prefix (combining parent prefix if any)
-        const fullPrefix = lazyInclude.context.urlPrefix
-          ? lazyInclude.context.urlPrefix + lazyInclude.prefix
-          : lazyInclude.prefix;
+        // Compute the full URL prefix (combining parent prefix if any). Use the
+        // slash-collapsing join so a trailing-slash parent prefix does not
+        // produce a double-slash staticPrefix the trie's sp can never match.
+        const fullPrefix = joinPrefix(
+          lazyInclude.context.urlPrefix,
+          lazyInclude.prefix,
+        );
 
         const lazyEntry: RouteEntry<TEnv> & { _lazyPrefix?: string } = {
           prefix: "",
@@ -998,6 +1005,13 @@ export function createRouter<TEnv = any>(
     // Expose basename for runtime manifest generation
     __basename: basename,
 
+    // Expose router-level boundary defaults for build-time clientChunks
+    // discovery (so a "use client" default boundary lands in app-fallback).
+    // These are createRouter options, never pushed onto EntryData.
+    __defaultErrorBoundary: defaultErrorBoundary,
+    __defaultNotFoundBoundary: defaultNotFoundBoundary,
+    __notFound: notFound,
+
     // RSC request handler (lazily created on first call)
     fetch: (() => {
       // Handler is created on first call and reused