@rangojs/router 0.5.1 → 0.6.0

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,
@@ -110,6 +112,7 @@ import {
   type RequestPlan,
   type ExecutableRequestPlan,
 } from "../router/request-classification.js";
+import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 
 /**
  * Create an RSC request handler.
@@ -247,7 +250,8 @@ export function createRSCHandler<
     actionId?: string,
   ): Promise<Response> {
     const timeoutError = new RouterTimeoutError(phase, durationMs);
-    const cursor = _getRequestContext<TEnv>()?._renderForeground;
+    const requestContext = _getRequestContext<TEnv>();
+    const cursor = requestContext?._renderForeground;
     const render: RenderTimeoutContext | undefined =
       phase === "render-start" && cursor
         ? {
@@ -261,11 +265,29 @@ export function createRSCHandler<
             }),
           }
         : undefined;
+    const trace =
+      phase === "render-start" ? requestContext?._activeRoutine : undefined;
+    const activeEntries = trace?.active() ?? [];
+    const activeStep = activeEntries.at(-1);
+    const activeAt = performance.now();
+    const routineSnapshot =
+      trace && activeStep
+        ? {
+            name: trace.name,
+            path: activeEntries.map((entry) => entry.name),
+            durationMs: activeAt - activeStep.startedAt,
+          }
+        : undefined;
 
-    // Each surface gets its OWN shallow copy of the snapshot. onError, telemetry,
-    // and onTimeout are independent consumers; a consumer that mutates its
-    // `render` (e.g. an onError redacting metadata) must not corrupt what the
-    // other two observe.
+    if (INTERNAL_RANGO_DEBUG && trace && activeStep) {
+      console.log(
+        `[routine] TIMEOUT ${request.method} ${url.pathname} (${trace.name})\n${trace.formatActive(activeEntries, activeAt)}`,
+      );
+    }
+
+    // Each surface gets its OWN shallow render snapshot. A consumer that mutates
+    // its copy must not corrupt what the other two observe. The internal-debug
+    // routine snapshot is bounded metadata sent only to onError.
     callOnError(timeoutError, phase === "action" ? "action" : "handler", {
       request,
       url,
@@ -278,6 +300,7 @@ export function createRSCHandler<
         phase,
         durationMs,
         ...(render && { render: { ...render } }),
+        ...(routineSnapshot && { routine: routineSnapshot }),
       },
     });
 
@@ -1288,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/helpers.ts

@@ -7,6 +7,7 @@
 import {
   _getRequestContext,
   getLocationState,
+  setRequestContextParams,
 } from "../server/request-context.js";
 import type { RequestContext } from "../server/request-context.js";
 import { resolveLocationStateEntries } from "../browser/react/location-state-shared.js";
@@ -23,6 +24,7 @@ import {
 import type { MiddlewareEntry, MiddlewareFn } from "../router/middleware.js";
 import { formatCacheSignalHeader } from "../router/telemetry.js";
 import type { RscPayload } from "./types.js";
+import type { HandlerContext } from "./handler-context.js";
 
 /**
  * DEVELOPMENT/TEST ONLY. When the debug cache signal gate is on,
@@ -381,3 +383,14 @@ export function finalizeResponse(response: Response): Response {
   if (!ctx) return response;
   return drainOnResponseCallbacks(ctx, response);
 }
+
+/** Match and stamp params/routeName on the request context as one operation. */
+export async function matchAndRecordParams<TEnv>(
+  ctx: HandlerContext<TEnv>,
+  request: Request,
+  env: TEnv,
+): Promise<Awaited<ReturnType<HandlerContext<TEnv>["router"]["match"]>>> {
+  const match = await ctx.router.match(request, { env });
+  setRequestContextParams(match.params, match.routeName);
+  return match;
+}

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