@rangojs/router 0.5.2 → 0.7.0

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

@@ -129,6 +129,14 @@ export async function resolveLoadersWithRevalidation<TEnv>(
 
   const shortCode = shortCodeOverride ?? entry.shortCode;
 
+  // Pin `_currentSegmentId` to the OWNING entry before the kickoffs below —
+  // createLoaderExecutor captures it synchronously for ctx.use(Handle) push
+  // attribution. Same pin as resolveLoaders (fresh.ts); this REVALIDATION
+  // funnel is the navigation/action lane's kickoff site, where nothing else
+  // assigns the id first (pushes silently vanished: an id outside
+  // matched/segmentOrder is dropped by collectHandleData).
+  (ctx as InternalHandlerContext<any, TEnv>)._currentSegmentId = shortCode;
+
   const loaderMeta = loaderEntries.map((loaderEntry, i) => ({
     loaderEntry,
     loader: loaderEntry.loader,
@@ -232,7 +240,9 @@ export async function resolveLoadersWithRevalidation<TEnv>(
             loaderEntry,
             ctx,
             ctx.pathname,
-            bakeLane ? segmentId : null,
+            bakeLane || loaderEntry.awaitBeforeFlush === true
+              ? segmentId
+              : null,
           ),
         ),
         entry,
@@ -605,7 +615,17 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
       // For non-empty client sets, consult user revalidate fns. When the slot
       // is unknown to the client, override the type-derived default so the
       // soft chain seeds with the right "new segment" / "parent-chain" value.
-      let defaultOverride: { value: boolean; reason: string } | undefined;
+      //
+      // A "new segment" seed is floored: the client has no cached copy of this
+      // slot, so a user `false` would render component:null and leave it blank
+      // rather than keep anything. Sibling resolvers (loaders, layout/route
+      // entries, orphan layouts) get the same guarantee by short-circuiting
+      // without consulting user fns at all; #482 made this path consult them so
+      // a "skip-parent-chain" seed could still be raised, so floor instead of
+      // short-circuiting — user fns run, and may only raise.
+      let defaultOverride:
+        | { value: boolean; reason: string; floor?: boolean }
+        | undefined;
       if (!clientSegmentIds.has(parallelId)) {
         const value =
           parentChainDefault === "force-render"
@@ -614,6 +634,7 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
         defaultOverride = {
           value,
           reason: value ? "new-segment" : "skip-parent-chain",
+          floor: value,
         };
       }
 

package/src/router/trie-matching.ts

@@ -9,7 +9,7 @@ import type {
   TrieNode,
   TrieLeaf,
   NegotiateVariant,
-} from "../build/route-trie.js";
+} from "./route-trie-builder.js";
 import { safeDecodeURIComponent } from "./url-params.js";
 
 export interface TrieMatchResult {
@@ -219,8 +219,8 @@ function walkTrie(
 
   if (node.xp) {
     // node.xp keys are pre-sorted longest-suffix-first at build time
-    // (route-trie.ts sortSuffixParams), so the first match is the most specific
-    // suffix: `/app.min.js` matches `:file.min.js` before `:file.js`.
+    // (route-trie-builder.ts sortSuffixParams), so the first match is the most
+    // specific suffix: `/app.min.js` matches `:file.min.js` before `:file.js`.
     for (const suffix in node.xp) {
       if (segment.endsWith(suffix) && segment.length > suffix.length) {
         const paramValue = segment.slice(0, -suffix.length);

package/src/router.ts

@@ -3,6 +3,11 @@ import { createCacheScope } from "./cache/cache-scope.js";
 import { resolveCacheProfiles } from "./cache/profile-registry.js";
 import { isCachedFunction } from "./cache/taint.js";
 import { assertClientComponent } from "./component-utils.js";
+import {
+  isClientUrlPatterns,
+  isClientUrlReference,
+} from "./client-urls/server-projection.js";
+import type { ClientUrlPatterns } from "./client-urls/types.js";
 import { DefaultDocument } from "./components/DefaultDocument.js";
 import type { SerializedManifest } from "./debug.js";
 import {
@@ -100,6 +105,7 @@ import type {
   Rango,
   RangoInternal,
   RouterRequestInput,
+  UrlPatternMount,
 } from "./router/router-interfaces.js";
 
 // Extracted closure functions
@@ -330,6 +336,7 @@ export function createRouter<TEnv = any>(
 
   // Store reference to urlpatterns for runtime manifest generation
   let storedUrlPatterns: UrlPatterns<TEnv, any> | null = null;
+  const urlpatternMounts: UrlPatternMount<TEnv>[] = [];
 
   // Global middleware storage
   const globalMiddleware: MiddlewareEntry<TEnv>[] = [];
@@ -572,6 +579,13 @@ export function createRouter<TEnv = any>(
             }
           }
         : undefined,
+      // notFound() resolution deps: the streamed envelope carries the
+      // server-rendered not-found UI, mirroring the consumption lane's
+      // boundary resolution (segment-resolution/helpers.ts).
+      {
+        findNearestNotFoundBoundary,
+        notFoundComponent: notFound,
+      },
     );
 
     // Emit loader.end after the promise settles (fire-and-forget)
@@ -756,7 +770,30 @@ export function createRouter<TEnv = any>(
     id: routerId,
     basename,
 
-    routes(patternsOrBuilder: UrlPatterns<TEnv> | UrlBuilder<TEnv>): any {
+    routes(
+      patternsOrBuilder:
+        | UrlPatterns<TEnv>
+        | UrlBuilder<TEnv>
+        | ClientUrlPatterns,
+    ): any {
+      // Pure-client mounting shorthand: a clientUrls() definition passed
+      // directly NORMALIZES to a root include in the canonical urls() tree —
+      // exactly `include("/", definition, { name: "" })`, keeping local route
+      // names bare and local patterns app-absolute. This is sugar over the
+      // ONE composition model, not a second registration path: it rides the
+      // same lazy include materialization, so no ordering, one-definition, or
+      // deferral rules exist. Prefixing, wrapping RSC layouts, and middleware
+      // scope still come from mounting through include() in urls() yourself.
+      if (
+        isClientUrlPatterns(patternsOrBuilder) ||
+        isClientUrlReference(patternsOrBuilder)
+      ) {
+        const clientSource = patternsOrBuilder as ClientUrlPatterns;
+        patternsOrBuilder = urls(({ include }) => [
+          include("/", clientSource, { name: "" }),
+        ]) as UrlPatterns<TEnv>;
+      }
+
       // Wrap builder functions in urls() automatically
       const urlPatterns: UrlPatterns<TEnv> =
         typeof patternsOrBuilder === "function"
@@ -766,6 +803,10 @@ export function createRouter<TEnv = any>(
       // Store reference for runtime manifest generation
       storedUrlPatterns = urlPatterns;
       const currentMountIndex = mountIndex++;
+      urlpatternMounts.push({
+        patterns: urlPatterns,
+        mountIndex: currentMountIndex,
+      });
 
       // Create manifest and patterns maps for route registration
       const manifest = new Map<string, EntryData>();
@@ -1095,6 +1136,10 @@ export function createRouter<TEnv = any>(
       return storedUrlPatterns ?? undefined;
     },
 
+    get __urlpatternMounts() {
+      return urlpatternMounts;
+    },
+
     // Expose source file for per-router type generation
     __sourceFile,
 

package/src/rsc/full-payload.ts

@@ -44,11 +44,17 @@ export function buildFullPayload(
       resolvedIds: m.resolvedIds,
       params: m.params,
       isPartial: false,
+      interceptTargets: m.interceptTargets,
       rootLayout: ctx.router.rootLayout,
       // Full render: resolve deferred handle values server-side so SSR markup and
       // the first sync useHandle read see resolved values. Partial payloads
       // (rsc-rendering.ts) keep streaming (handleStore.stream()).
       handles: resolvedHandleStream(handleStore),
+      // Post-handler-barrier pushes (streaming loader ctx.handle() writes)
+      // stream here; the client applies them after hydration. Instantly
+      // complete when the loader lane is idle — including PPR shell capture,
+      // where masked loaders never run.
+      handlesLate: handleStore.streamLate(),
       version: ctx.version,
       prefetchCacheTTL: ctx.router.prefetchCacheTTL,
       prefetchCacheSize: ctx.router.prefetchCacheSize,

package/src/rsc/handler.ts

@@ -7,7 +7,6 @@
  * and progressive enhancement (no-JS form submissions).
  */
 
-import { createElement } from "react";
 import { isRouteNotFoundError } from "../errors.js";
 import { matchMiddleware, executeMiddleware } from "../router/middleware.js";
 import {
@@ -50,7 +49,10 @@ import { generateNonce, nonce as nonceToken } from "./nonce.js";
 import { VERSION } from "@rangojs/router:version";
 import type { ErrorPhase } from "../types.js";
 import type { RouterRequestInput } from "../router/router-interfaces.js";
-import { invokeOnError } from "../router/error-handling.js";
+import {
+  invokeOnError,
+  resolveDefaultNotFound,
+} from "../router/error-handling.js";
 import {
   createReverseFunction,
   stripInternalParams,
@@ -1309,11 +1311,12 @@ export function createRSCHandler<
             handledByBoundary: true,
           });
 
-          const notFoundOption = router.notFound;
-          const notFoundComponent =
-            typeof notFoundOption === "function"
-              ? notFoundOption({ pathname: url.pathname })
-              : (notFoundOption ?? createElement("h1", null, "Not Found"));
+          // No boundary to consult: an unmatched route has no entry chain, so
+          // this always lands on the router option or the shared default.
+          const notFoundComponent = resolveDefaultNotFound(
+            router.notFound,
+            url.pathname,
+          );
 
           const notFoundSegment = {
             id: "notFound",

package/src/rsc/loader-fetch.ts

@@ -12,7 +12,7 @@
  */
 
 import { getLoaderLazy } from "../server/loader-registry.js";
-import { DataNotFoundError } from "../errors.js";
+import { isDataNotFoundError } from "../errors.js";
 import { executeLoaderMiddleware } from "../router/middleware.js";
 import { getRequestContext } from "../server/request-context.js";
 import { observePhase, PHASES } from "../router/instrument.js";
@@ -289,7 +289,7 @@ export async function handleLoaderFetch<TEnv>(
     // so it does not match the branch above. Map it to a 404 before the generic
     // 500 coercion so a no-middleware fetchable loader's notFound() is honored
     // (the with-middleware path resolves it through the notFoundBoundary).
-    if (error instanceof DataNotFoundError) {
+    if (isDataNotFoundError(error)) {
       return finalizeResponse(
         createResponseWithMergedHeaders(null, { status: 404 }),
       );

package/src/rsc/manifest-init.ts

@@ -1,8 +1,8 @@
 /**
  * Router Manifest Initialization
  *
- * Builds a fresh route trie from router.urlpatterns for dev/HMR scenarios
- * where the manifest exists but the trie needs rebuilding.
+ * Builds a fresh route trie from every registered URL-pattern mount for
+ * dev/HMR scenarios where the manifest exists but the trie needs rebuilding.
  */
 
 import {
@@ -13,11 +13,12 @@ import {
   setRouterTrie,
   setRouterPrecomputedEntries,
 } from "../route-map-builder.js";
+import { mergeFullManifests } from "../build/merge-full-manifests.js";
 
 /**
- * Build a fresh route trie from router.urlpatterns and store it in the
- * per-router cache. Also sets the per-router manifest and merges into
- * the global manifest for reverse()/href().
+ * Build a fresh route trie from the router's URL-pattern mounts and store it in
+ * the per-router cache. Also sets the per-router manifest and merges into the
+ * global manifest for reverse()/href().
  *
  * Called when manifest data may exist but the per-router trie is missing,
  * which happens in dev mode after HMR: the virtual module sets the manifest
@@ -30,10 +31,28 @@ export async function buildRouterTrieFromUrlpatterns(
 ): Promise<void> {
   const { generateManifestFull } =
     await import("../build/generate-manifest.js");
-  const generated = await generateManifestFull(router.urlpatterns, undefined, {
-    routerId: router.id,
-    ...(router.basename ? { urlPrefix: router.basename } : {}),
-  });
+  const mounts =
+    router.__urlpatternMounts ??
+    (router.urlpatterns
+      ? [{ patterns: router.urlpatterns, mountIndex: undefined }]
+      : []);
+  // mount.mountIndex mirrors the live router's per-mount counter partitioning
+  // (context.ts getShortCode `M{i}` prefixes), so entries generated here carry
+  // the same shortCodes as runtime registration. Build discovery
+  // (discover-routers.ts / runtime-discovery.ts) numbers mounts GLOBALLY across
+  // routers instead — that divergence is invisible: shortCodes never leave
+  // their realm, and route names (the trie keys) carry no mount index (unnamed
+  // routes are `$path_*`, see path-helper.ts).
+  const mountManifests = [];
+  for (const mount of mounts) {
+    mountManifests.push(
+      await generateManifestFull(mount.patterns, mount.mountIndex, {
+        routerId: router.id,
+        ...(router.basename ? { urlPrefix: router.basename } : {}),
+      }),
+    );
+  }
+  const generated = mergeFullManifests(mountManifests);
   // Build the trie through the SAME shared helper the production discovery uses
   // (discover-routers.ts), so the dev runtime-rebuilt trie and the prod
   // serialized trie cannot drift. buildPerRouterTrie returns null when there

package/src/rsc/rsc-rendering.ts

@@ -57,6 +57,7 @@ import {
   SHELL_STATUS_HEADER,
   resolvePprConfig,
   buildShellKey,
+  shellSearchSeed,
   isValidShellHit,
   hasIntactShellPayload,
   base64ToBytes,
@@ -153,12 +154,14 @@ function buildNavigationShellKey(
 function createShellCaptureDescriptor(
   ctx: HandlerContext<any>,
   key: string,
+  searchSeed: string,
   pprConfig: ResolvedPprConfig,
   store: SegmentCacheStore<any>,
   navigationOnly?: true,
 ): ShellCaptureDescriptor {
   return {
     key,
+    searchSeed,
     buildVersion: ctx.version,
     ttl: pprConfig.ttl,
     swr: pprConfig.swr,
@@ -512,7 +515,13 @@ function* shellServePlan<TEnv>(
   ) {
     return { kind: "pass" };
   }
-  const descriptor = createShellCaptureDescriptor(ctx, key, pprConfig, store);
+  const descriptor = createShellCaptureDescriptor(
+    ctx,
+    key,
+    shellSearchSeed(url, reqCtx._searchParamsFilter),
+    pprConfig,
+    store,
+  );
 
   if (
     cached &&
@@ -699,6 +708,7 @@ function* preparePayloadPlan<TEnv>(
           params: result.params,
           isPartial: true,
           slots: result.slots,
+          interceptTargets: result.interceptTargets,
           handles: handleStore.stream(),
           version: ctx.version,
           prefetchCacheTTL: ctx.router.prefetchCacheTTL,
@@ -993,6 +1003,7 @@ function scheduleNavigationShellCapture<TEnv>(
       ctx,
       partialCaptureKey ??
         buildNavigationShellKey(url, reqCtx._searchParamsFilter),
+      shellSearchSeed(url, reqCtx._searchParamsFilter),
       pprConfig,
       store,
       true,
@@ -1510,6 +1521,9 @@ function serveShellHit(
       ssrModule.resumeShellHTML!(rscStream, {
         postponed: entry.postponed,
         nonce: undefined,
+        // The shell key's own search — identical to the capture seed for
+        // this key, so the resume tree matches the captured tree.
+        search: shellSearchSeed(url, reqCtx._searchParamsFilter),
       }),
     );
   };

package/src/rsc/shell-capture.ts

@@ -907,6 +907,15 @@ export function gateFlightForCapture(
  */
 export interface ShellCaptureDescriptor {
   key: string;
+  /**
+   * The key's search portion (shellSearchSeed: `?`-prefixed sorted search,
+   * cache.searchParams filter applied, or ""). Seeds the capture render's SSR
+   * store so static-part `useSearchParams` reads bake markup consistent with
+   * the shell's own key; the resume pass derives the identical string from
+   * the HIT request. Computed next to the key so the two cannot drift.
+   * Omitted (build-time bare-pathname captures) = search-less, same as "".
+   */
+  searchSeed?: string;
   /**
    * The RSC handler's build version (HandlerContext.version), stamped into the
    * stored entry as ShellCacheEntry.buildVersion — the serve-side
@@ -1753,6 +1762,9 @@ async function captureAndStoreShell(
         captureShellHTML(gate.stream, {
           quiesce,
           maxWaitMs: capture.captureTimeout ?? SHELL_CAPTURE_MAX_WAIT_MS,
+          // The shell key's own search seeds the capture render's store —
+          // static-part search reads bake what the key names.
+          search: capture.searchSeed,
         }),
       );
     } catch (error) {

package/src/rsc/shell-serve.ts

@@ -129,9 +129,22 @@ export function resolvePprConfig(
  * and lookup makes every shell request a permanent miss.
  */
 export function buildShellKey(url: URL, filter?: SearchParamsFilter): string {
+  return `${url.host}${url.pathname}${shellSearchSeed(url, filter)}:shell`;
+}
+
+/**
+ * The shell key's search portion (`?`-prefixed sorted search with the
+ * cache.searchParams filter applied, or "") — ALSO the string the capture and
+ * resume SSR renders seed their store location with (SSRRenderOptions.search
+ * / ShellCaptureOptions.search / ShellResumeOptions.search). Search is part
+ * of shell identity, so static-part `useSearchParams` reads render exactly
+ * what the key names; deriving seed and key from this one helper is what
+ * keeps capture, resume, and lookup byte-agreed (drift = replay mismatch or
+ * permanent MISS).
+ */
+export function shellSearchSeed(url: URL, filter?: SearchParamsFilter): string {
   const sorted = sortedSearchString(url.searchParams, filter);
-  const searchSuffix = sorted ? `?${sorted}` : "";
-  return `${url.host}${url.pathname}${searchSuffix}:shell`;
+  return sorted ? `?${sorted}` : "";
 }
 
 /**

package/src/rsc/ssr-setup.ts

@@ -111,7 +111,16 @@ export function createSsrHtmlStage<TEnv>(
     );
     return {
       render: () =>
-        ssrModule.renderHTML(flight.stream, { ...options.render, streamMode }),
+        // search: the LIVE request's query string, threaded out-of-band into
+        // the SSR pass so useSearchParams sees real values during document
+        // renders. Deliberately not payload metadata: cached/prerendered
+        // payloads replay captured metadata, and search is not route
+        // identity — it must always come from the request being served.
+        ssrModule.renderHTML(flight.stream, {
+          ...options.render,
+          streamMode,
+          search: options.url.search,
+        }),
       ...(options.init && { init: options.init }),
     };
   };

package/src/rsc/types.ts

@@ -35,10 +35,27 @@ export interface RscPayload {
     /** Merged route params from the matched route */
     params?: Record<string, string>;
     slots?: Record<string, SlotState>;
+    /**
+     * Intercept TARGET route names reachable from this location as a
+     * navigation origin (see MatchResult.interceptTargets). The browser-local
+     * clientUrls matcher declines optimistic presentation for these.
+     */
+    interceptTargets?: string[];
     /** Root layout component for browser-side re-renders (client component reference) */
     rootLayout?: React.ComponentType<{ children: React.ReactNode }>;
     /** Handle data accumulated across route segments (async generator that yields on each push) */
     handles?: AsyncGenerator<HandleData, void, unknown>;
+    /**
+     * Document-lane late handle channel: full-state updates for pushes landing
+     * AFTER the handler barrier (streaming loader bodies writing handles
+     * mid-body). `handles` above is drained to completion in blocking
+     * positions (SSR seed, pre-hydration), so late pushes need this separate
+     * generator, consumed non-blocking post-hydration (rsc-router.tsx).
+     * Empty/instantly-complete when no auxiliary-lane work is pending at the
+     * handler barrier. Full payloads only — partial payloads' `handles`
+     * generator streams to full settle already.
+     */
+    handlesLate?: AsyncGenerator<HandleData, void, unknown>;
     /** RSC version string for cache invalidation */
     version?: string;
     /** Cloudflare dev worker generation used for stale-document convergence. */
@@ -158,6 +175,18 @@ export interface SSRRenderOptions {
    * - `"allReady"` — await `stream.allReady` before returning.
    */
   streamMode?: import("../router/router-options.js").SSRStreamMode;
+
+  /**
+   * The live request's query string (`url.search`, `?`-prefixed or empty).
+   * Seeds the SSR navigation store so `useSearchParams` (and
+   * `useNavigation().location`) carry real values during document renders.
+   * Out-of-band by design — never payload metadata, which cached/prerendered
+   * payloads replay; search is not route identity. The build-time prerender
+   * pass passes none — build shells capture bare pathnames and serve
+   * search-less requests only (runtime ppr captures seed the shell key's
+   * search; see ShellCaptureOptions.search in the SSR entry).
+   */
+  search?: string;
 }
 
 /**
@@ -179,7 +208,7 @@ export interface SSRModule {
    */
   captureShellHTML?: (
     rscStream: ReadableStream<Uint8Array>,
-    options: { quiesce: Promise<void>; maxWaitMs?: number },
+    options: { quiesce: Promise<void>; maxWaitMs?: number; search?: string },
   ) => Promise<{ prelude: Uint8Array; postponed: string | null } | null>;
 
   /**
@@ -192,7 +221,7 @@ export interface SSRModule {
    */
   resumeShellHTML?: (
     rscStream: ReadableStream<Uint8Array>,
-    options: { postponed: string | null; nonce?: string },
+    options: { postponed: string | null; nonce?: string; search?: string },
   ) => Promise<ReadableStream<Uint8Array>>;
 }