@rangojs/router 0.0.0-experimental.e16b7c00 → 0.0.0-experimental.e9c0b2f2

package/src/use-loader.tsx

@@ -15,14 +15,6 @@ import { OutletContext, type OutletContextValue } from "./outlet-context.js";
 import { loaderStore, type LoaderEntry } from "./loader-store.js";
 import type { LoaderDefinition, LoadOptions } from "./types.js";
 
-/**
- * A shareable GET — a `load()` call that reads data (GET or defaulted method)
- * with no request body. Params are allowed. This is the gate for keyed sharing:
- * when a hook is given an explicit `key`, every shareable GET writes to the
- * keyed bucket so co-keyed readers (including parameterized views) refresh
- * together. Non-GET methods and body-bearing calls are mutations and stay local
- * to the call site.
- */
 function isShareableGet(options: LoadOptions | undefined): boolean {
   if (!options) return true;
   if (options.method && options.method !== "GET") return false;
@@ -32,44 +24,14 @@ function isShareableGet(options: LoadOptions | undefined): boolean {
   return true;
 }
 
-/**
- * Plain route-context refetch — a `load()` call with no options or a
- * trivially-defaulted GET (no params, no body). Results from these are
- * broadcast to every component reading the same loader id via the shared
- * store, so a layout's refetch button updates page + parallel-slot reads
- * automatically.
- *
- * Calls with explicit `params`, an explicit non-GET method, or a `body`
- * stay local to the call site — that preserves the today-semantics of
- * `useFetchLoader(SearchLoader).load({ params: { q } })` style code where
- * each component owns its own fetched view. (An explicit `key` opts a
- * parameterized GET back into sharing; see `isShareableGet`.)
- */
 function isPlainRefetch(options: LoadOptions | undefined): boolean {
   if (!isShareableGet(options)) return false;
   if (options?.params && Object.keys(options.params).length > 0) return false;
   return true;
 }
 
-// Per-hook unique suffix for grouped reads that have no explicit `key`. Such a
-// read must NOT share the bare `loader.$$id` bucket, or a cross-loader group
-// refresh would leak into unrelated unkeyed readers of the same loader (which
-// the contract keeps local). Sharing within a group is opt-in via an explicit
-// `key`; without one, each grouped read gets its own private bucket. The value
-// is only ever used as a client-side store bucket key (never rendered), so the
-// counter has no SSR/hydration consistency requirement.
 let privateGroupBucketSeq = 0;
 
-/**
- * Extract a specific loader's data from a content ReactNode.
- *
- * When a route registers loaders via loader(), the resolved data lives in
- * the route's OutletProvider (rendered as <Outlet /> content). Parallel
- * slots are siblings of <Outlet />, so they can't find it by walking
- * the parent context chain. This helper traverses wrapper elements
- * (MountContextProvider, ViewTransition, etc.) to reach the OutletProvider
- * and extract the loader data directly.
- */
 const NOT_FOUND = Symbol("not-found");
 
 function extractContentLoaderData(
@@ -85,10 +47,6 @@ function extractContentLoaderData(
     return props.loaderData[loaderId];
   }
 
-  // LoaderBoundary: loaderIds + loaderDataPromise (already resolved array).
-  // When the segment has loading(), loaderData is resolved inside
-  // LoaderBoundary via use(). If the promise was pre-awaited (forceAwait
-  // or isAction), the prop is a raw array we can index into.
   if (
     props.loaderIds &&
     Array.isArray(props.loaderIds) &&
@@ -98,7 +56,6 @@ function extractContentLoaderData(
     const idx = (props.loaderIds as string[]).indexOf(loaderId);
     if (idx !== -1) {
       const data = (props.loaderDataPromise as any[])[idx];
-      // loaderDataPromise entries may be { ok, data } result objects
       if (data && typeof data === "object" && "ok" in data) {
         return data.ok ? data.data : NOT_FOUND;
       }
@@ -106,118 +63,45 @@ function extractContentLoaderData(
     }
   }
 
-  // Traverse into wrapper elements (MountContextProvider, ViewTransition,
-  // Suspense wrappers, etc.)
   if (props.children) return extractContentLoaderData(props.children, loaderId);
   return NOT_FOUND;
 }
 
-/**
- * Payload returned by loader RSC requests
- */
 interface LoaderRscPayload<T = unknown> {
   loaderResult: T;
   loaderError?: { message: string; name: string };
 }
 
-/**
- * Load function type for fetching loader data from the client
- */
 export type LoadFunction<T> = (options?: LoadOptions) => Promise<T>;
 
-/**
- * Result type for useLoader hook (strict - data is required)
- */
 export interface UseLoaderResult<T> {
-  /** The loaded data - guaranteed to exist when loader is registered on route */
   data: T;
-  /** True while a load() is in progress */
   isLoading: boolean;
-  /** Error from the most recent load attempt, null if successful */
   error: Error | null;
-  /** Function to trigger a fetch (only works if loader is fetchable) */
   load: LoadFunction<T>;
-  /** Alias for load */
   refetch: LoadFunction<T>;
 }
 
-/**
- * Result type for useFetchLoader hook (flexible - data is optional)
- */
 export interface UseFetchLoaderResult<T> {
-  /** The loaded data - may be undefined if not yet fetched or not in context */
   data: T | undefined;
-  /** True while a load() is in progress */
   isLoading: boolean;
-  /** Error from the most recent load attempt, null if successful */
   error: Error | null;
-  /** Function to trigger a fetch (only works if loader is fetchable) */
   load: LoadFunction<T>;
-  /** Alias for load */
   refetch: LoadFunction<T>;
 }
 
-/**
- * Options for useLoader hook
- */
 export interface UseLoaderOptions {
-  /**
-   * If true (default), errors from load() will be thrown to the nearest error boundary.
-   * If false, errors are only captured in the `error` state.
-   * @default true
-   */
   throwOnError?: boolean;
-  /**
-   * Client refresh key. Partitions the shared refresh store so that only hooks
-   * using the same `key` refresh together when one of them calls `load()`.
-   *
-   * Without a `key` (default), a plain `load()` on a route-registered loader
-   * broadcasts to every reader of that loader, and any parameterized / unregistered
-   * load stays local to the calling hook. With a `key`:
-   *   - readers of the same loader that share a `key` form one refresh group —
-   *     a `load()` from any of them updates the whole group, including
-   *     parameterized GETs;
-   *   - readers with different keys are independent;
-   *   - it works even when the loader is NOT registered on the route (keyed
-   *     `useFetchLoader`), letting unrelated components opt into sharing.
-   *
-   * This is a client-side refresh identity only. It is unrelated to the server
-   * `cache({ key })` option and to `revalidate()`; it never changes the request
-   * sent to the server.
-   */
   key?: string;
-  /**
-   * Cross-loader refresh group tag(s). Tag reads of DIFFERENT loaders with a
-   * shared name, then call `useRefreshLoaders()(name)` to refresh the whole group
-   * at once. Pass an array to tag one read into several groups — it is refreshed
-   * when ANY of its groups is refreshed, so a coarse tag can cover the whole set
-   * while a finer tag targets a subset. Each member is refreshed with a plain GET
-   * against the current route URL — no params, no body, no mutation methods —
-   * because a group spans heterogeneous loaders with different param/return
-   * shapes.
-   *
-   * For parameterized sharing of a SINGLE loader, use `key` instead; group
-   * members should be registered or non-parameterized-keyed reads (a plain-GET
-   * group refresh would drop any per-call params).
-   */
   refreshGroup?: string | string[];
 }
 
-/**
- * Internal hook implementation shared by useLoader and useFetchLoader
- */
 function useLoaderInternal<T>(
   loader: LoaderDefinition<T>,
   options?: UseLoaderOptions,
 ): UseFetchLoaderResult<T> {
   const context = useContext(OutletContext);
 
-  // Get data from context (SSR/navigation). `hasContextData` distinguishes
-  // "loader registered on the route, value happens to be undefined" from
-  // "loader is not in any parent's context at all". The shared store is
-  // only consulted when the loader really is in route context — that
-  // preserves per-component isolation for ad-hoc useFetchLoader callers
-  // who use the same fetchable loader without registering it.
   const { contextData, hasContextData } = useMemo((): {
     contextData: T | undefined;
     hasContextData: boolean;
@@ -230,9 +114,6 @@ function useLoaderInternal<T>(
           hasContextData: true,
         };
       }
-      // Check content element — the route's OutletProvider is rendered as
-      // <Outlet /> content (a child), so its loaderData isn't in the parent
-      // chain. Parallel slots need to reach into it to find route-level loaders.
       const contentData = extractContentLoaderData(
         current.content,
         loader.$$id,
@@ -245,23 +126,8 @@ function useLoaderInternal<T>(
     return { contextData: undefined, hasContextData: false };
   }, [context, loader.$$id]);
 
-  // Shared subscription: every component reading the same loader id sees
-  // the same snapshot, so a plain refetch from one component propagates to
-  // the others. Mirrors the convention used by useParams / useLinkStatus —
-  // useState seeded from the store, useEffect subscribes for updates and
-  // calls setState inside startTransition so subscriber re-renders don't
-  // trip Suspense fallbacks during a refetch (matches the per-hook
-  // startTransition the old code wrapped setFetchedData in).
   const loaderId = loader.$$id;
-  // Client refresh key. The shared store is partitioned by bucket key so that
-  // only hooks with the same `key` refresh together. Default (no key) keeps the
-  // historical behavior: one bucket per loader id.
   const key = options?.key;
-  // Normalize the refresh-group tag(s) to a stable, deduped, sorted list. The
-  // joined `groupKey` string is the subscribe effect's dependency, so passing an
-  // inline array literal (`refreshGroup={["a", "b"]}`) does not force a
-  // resubscribe on every render. An empty list means "no groups" — identical to
-  // omitting the option (`hasGroups` stays false, no private bucket is created).
   const refreshGroupOption = options?.refreshGroup;
   const groupKey =
     refreshGroupOption === undefined
@@ -276,10 +142,6 @@ function useLoaderInternal<T>(
     [groupKey],
   );
   const hasGroups = groupList.length > 0;
-  // A grouped reader with no explicit key gets a private per-hook bucket so a
-  // cross-loader group refresh cannot leak into the bare `loader.$$id` bucket
-  // shared by unrelated unkeyed readers. Sharing within a group is opt-in via
-  // an explicit `key`.
   const privateBucketIdRef = useRef<string | null>(null);
   if (hasGroups && key === undefined && privateBucketIdRef.current === null) {
     privateBucketIdRef.current = `__rg${privateGroupBucketSeq++}`;
@@ -289,12 +151,6 @@ function useLoaderInternal<T>(
   const bucketKey =
     effectiveKey === undefined ? loaderId : `${loaderId}::${effectiveKey}`;
 
-  // Plain-GET refresh thunk registered with the store for cross-loader group
-  // refresh (useRefreshLoaders). Always shares into this hook's bucket, never
-  // touches lastSharedRequestIdRef (so a group refresh never render-throws —
-  // errors surface via `error` and reject the refreshGroups() promise instead),
-  // and sends no params/body. Stable across navigations (depends only on
-  // loaderId + bucketKey), so the store keeps one current thunk per bucket.
   const groupRefetch = useCallback(async (): Promise<void> => {
     if (!loaderId) return;
     const requestId = loaderStore.reserveRequestId(bucketKey);
@@ -333,9 +189,6 @@ function useLoaderInternal<T>(
       ? sharedState.snapshot
       : loaderStore.getSnapshot(bucketKey);
   useEffect(() => {
-    // Sync any value the store committed between this hook's lazy
-    // initializer and effect-time (e.g. a sibling that mounted earlier
-    // already triggered a load()).
     const initial = loaderStore.getSnapshot(bucketKey);
     if (initial !== sharedSnapshot) {
       startTransition(() => {
@@ -430,10 +283,6 @@ function useLoaderInternal<T>(
 
   const throwOnError = options?.throwOnError ?? true;
 
-  // Refs for values used inside load() that should NOT cause callback identity
-  // churn. loader.$$id can change if a reusable component receives a different
-  // loader without remounting; data changes on every navigation. Refs keep the
-  // callback stable while always reading the latest values.
   const loaderIdRef = useRef(loaderId);
   loaderIdRef.current = loaderId;
   const bucketKeyRef = useRef(bucketKey);
@@ -443,8 +292,6 @@ function useLoaderInternal<T>(
   const hasContextDataRef = useRef(hasContextData);
   hasContextDataRef.current = hasContextData;
 
-  // Load function for fetching data via the ?_rsc_loader endpoint.
-  // Supports GET (data fetching) and POST/PUT/PATCH/DELETE (mutations).
   const load = useCallback(
     async (loadOptions?: LoadOptions): Promise<T> => {
       const id = loaderIdRef.current;
@@ -455,20 +302,8 @@ function useLoaderInternal<T>(
       }
 
       const bucket = bucketKeyRef.current;
-      // A dedicated bucket means this read owns a bucket distinct from the bare
-      // loader id — either an explicit `key` (`$$id::key`) or a refreshGroup's
-      // private bucket (`$$id::<private>`).
       const hasDedicatedBucket = bucket !== id;
 
-      // Deciding shared vs local:
-      //   - With a dedicated bucket, every shareable GET (params allowed) writes
-      //     to that bucket — the key/group is an explicit opt-in to sharing, and
-      //     a direct load() must land in the same bucket a group refresh uses.
-      //   - On the bare loader-id bucket, sharing is only correct when the
-      //     loader is registered on the route and the call is a plain refetch —
-      //     otherwise two unrelated components calling load() on the same
-      //     fetchable loader would overwrite each other's local view.
-      // Mutations (non-GET / body) stay local in both cases.
       const shared = hasDedicatedBucket
         ? isShareableGet(loadOptions)
         : isPlainRefetch(loadOptions) && hasContextDataRef.current;
@@ -477,9 +312,6 @@ function useLoaderInternal<T>(
       if (shared) {
         sharedRequestId = loaderStore.reserveRequestId(bucket);
         lastSharedRequestIdRef.current = sharedRequestId;
-        // beginRequest flips loading on AND clears any prior error so a
-        // throwOnError: false consumer doesn't keep showing the stale
-        // error during the retry. Gated on requestId === latest.
         loaderStore.beginRequest(bucket, sharedRequestId);
       } else {
         localRequestId = ++localRequestIdRef.current;
@@ -505,8 +337,6 @@ function useLoaderInternal<T>(
             loadOptions?.params && Object.keys(loadOptions.params).length > 0;
 
           if (bodyValue instanceof FormData) {
-            // FormData body — send as multipart/form-data (preserves File objects).
-            // Params are appended as a JSON string in a special field.
             if (hasParams) {
               bodyValue.set(
                 "_rsc_loader_params",
@@ -519,7 +349,6 @@ function useLoaderInternal<T>(
               body: bodyValue,
             };
           } else {
-            // JSON body — send params and body as JSON
             const bodyPayload: {
               params?: Record<string, string>;
               body?: unknown;
@@ -541,7 +370,6 @@ function useLoaderInternal<T>(
             };
           }
         } else {
-          // GET - send params in query string
           if (
             loadOptions?.params &&
             Object.keys(loadOptions.params).length > 0
@@ -571,12 +399,8 @@ function useLoaderInternal<T>(
 
         const result = payload.loaderResult;
         if (shared) {
-          // finishData is gated on requestId; a stale response is dropped.
           loaderStore.finishData(bucket, sharedRequestId, result);
         } else if (localRequestId === localRequestIdRef.current) {
-          // Local-branch gate, mirrors the shared-branch requestId check:
-          // if a newer load() was issued from this hook before this one
-          // resolved, drop the stale result.
           startTransition(() => {
             setLocalFetchedData({ has: true, value: result });
             setLocalIsLoading(false);
@@ -594,12 +418,9 @@ function useLoaderInternal<T>(
         if (throwOnError) {
           throw err;
         }
-        // When throwOnError is false, return the latest data snapshot (previous
-        // successful value or undefined). Caller should check error state.
         return dataRef.current as T;
       } finally {
         if (shared) {
-          // setLoading is gated; only the latest request flips the flag off.
           loaderStore.setLoading(bucket, sharedRequestId, false);
         }
       }
@@ -607,13 +428,6 @@ function useLoaderInternal<T>(
     [throwOnError],
   );
 
-  // Throw during render if there's an error and throwOnError is true.
-  // - Local errors always belong to this hook, so always throw on opt-in.
-  // - Shared errors throw only when this hook initiated the failing
-  //   request (entry.requestId matches lastSharedRequestIdRef). Sibling
-  //   readers expose the error via `error` but do not throw, so a
-  //   throwOnError: true reader never explodes because of someone else's
-  //   throwOnError: false load() failure.
   if (throwOnError) {
     if (localError) throw localError;
     if (

package/src/vercel/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Vercel preset integration surface for @rangojs/router.
+ *
+ * Imported via `@rangojs/router/vercel`. Vercel-only helpers live here so
+ * Node/other-platform consumers never pull them in. The Vercel cache store
+ * (`VercelCacheStore`) is exported from `@rangojs/router/cache`, mirroring the
+ * Cloudflare split where the store lives in `/cache` and the tracing helper in
+ * the platform subpath.
+ */
+
+export { createVercelTracing, type VercelTracingOptions } from "./tracing.js";

package/src/vercel/tracing.ts

@@ -0,0 +1,88 @@
+/**
+ * Vercel OpenTelemetry tracing integration.
+ *
+ * Bridges the router's performance phases (request, middleware, action,
+ * loaders, handler, render, ssr) onto OpenTelemetry spans so they show up in
+ * Vercel's trace waterfall next to the platform's automatic spans, with correct
+ * nesting. Vercel exposes tracing through OpenTelemetry (not a native import-free
+ * API like Cloudflare), so this is a thin convenience over `createOTelTracing`:
+ * it reads the global OTel tracer that `@vercel/otel`'s `registerOTel()` installs.
+ *
+ * Usage (vercel preset). A Rango/Vite app does NOT auto-load `instrumentation.ts`
+ * the way Next.js does, so export the tracing config from there and import it —
+ * the import is what runs `registerOTel()`. A standalone `registerOTel()` that
+ * nothing imports is a silent no-op (the tracer never registers, spans drop):
+ *
+ *   // instrumentation.ts
+ *   import { registerOTel } from "@vercel/otel";
+ *   import { createVercelTracing } from "@rangojs/router/vercel";
+ *   registerOTel({ serviceName: "my-app" });
+ *   export const tracing = createVercelTracing();
+ *
+ *   // router.tsx — importing `tracing` runs instrumentation.ts (and registerOTel)
+ *   import { createRouter } from "@rangojs/router";
+ *   import { tracing } from "./instrumentation.js";
+ *   export const router = createRouter({ tracing });
+ *
+ * Two runtime caveats inherited from the platform:
+ *   - Node.js runtime only. Vercel custom spans are unsupported on the Edge
+ *     runtime; `startActiveSpan` also needs an AsyncLocalStorage context manager
+ *     (which @vercel/otel configures on Node) for spans to nest correctly.
+ *   - `registerOTel()` must run before the first request. Reading the tracer via
+ *     `trace.getTracer` here is safe even if it runs first — the API's proxy
+ *     tracer delegates to the provider once registered — but no provider means
+ *     every span is a no-op (the request behaves exactly as if tracing were off).
+ *
+ * Whether spans are actually exported is governed by your OTel setup / Vercel
+ * tracing destination, not by this adapter.
+ */
+
+import { trace } from "@opentelemetry/api";
+import {
+  createOTelTracing,
+  type OTelActiveSpanTracer,
+} from "../router/telemetry-otel.js";
+import type {
+  RouterTracingConfig,
+  TracePhaseToggles,
+} from "../router/tracing.js";
+
+/** Options for createVercelTracing. */
+export interface VercelTracingOptions {
+  /** Master switch. Defaults to true. */
+  enabled?: boolean;
+  /** Per-phase span toggles. Omitted phases default to enabled. */
+  spans?: TracePhaseToggles;
+  /**
+   * OTel instrumentation-scope name passed to `trace.getTracer()`. Defaults to
+   * `"rango"`. Ignored when `tracer` is provided.
+   */
+  tracerName?: string;
+  /**
+   * Explicit tracer override. Defaults to the global OTel tracer
+   * (`trace.getTracer(tracerName)`) — the provider `@vercel/otel`'s
+   * `registerOTel()` installs. Pass this to bridge onto a tracer you own.
+   */
+  tracer?: OTelActiveSpanTracer;
+}
+
+/**
+ * Create the tracing config for a Vercel router. Pass the result to
+ * `createRouter({ tracing })`. Spans are emitted for the request, middleware,
+ * action, loaders, handler, render, and ssr phases; pass `spans` to turn
+ * individual phases off.
+ *
+ * @see createOTelTracing (`@rangojs/router`) for the underlying adapter on any
+ *   platform with an OpenTelemetry SDK.
+ * @see createCloudflareTracing (`@rangojs/router/cloudflare`) for the same slot
+ *   using Cloudflare Workers native custom spans.
+ */
+export function createVercelTracing(
+  options: VercelTracingOptions = {},
+): RouterTracingConfig {
+  const { tracerName = "rango", tracer, enabled, spans } = options;
+  return createOTelTracing(tracer ?? trace.getTracer(tracerName), {
+    enabled,
+    spans,
+  });
+}

package/src/vite/discovery/bundle-postprocess.ts

@@ -9,6 +9,7 @@ import { resolve } from "node:path";
 import { readFileSync, writeFileSync, existsSync } from "node:fs";
 import { evictHandlerCode } from "../utils/bundle-analysis.js";
 import { copyStagedBuildAssets } from "../utils/prerender-utils.js";
+import { jsonParseExpression } from "../utils/manifest-utils.js";
 import type { DiscoveryState } from "./state.js";
 
 /**
@@ -104,7 +105,7 @@ export function postprocessBundle(state: DiscoveryState): void {
         }
 
         const manifestCode = [
-          `const m=JSON.parse('${JSON.stringify(manifestMap).replace(/'/g, "\\'")}');`,
+          `const m=${jsonParseExpression(manifestMap)};`,
           `export function loadPrerenderAsset(s){return import(s)}`,
           `export default m;`,
           "",

package/src/vite/discovery/discover-routers.ts

@@ -11,6 +11,16 @@ import {
   formatNestedRouterConflictError,
   findNestedRouterConflict,
 } from "../../build/generate-route-types.js";
+// Pure data transforms over generateManifestFull's output. Imported directly
+// from source (not the public ./build barrel, and not the runner) because they
+// are realm-independent: buildRouteTrie/buildPerRouterTrie operate on plain
+// manifest data, and collectFallbackClientRefs keys on the global-registry
+// Symbol.for("react.client.reference"), so it detects client references in a
+// boundary tree regardless of which realm imported the walker. Only
+// generateManifestFull must stay on the runner (it invokes user handlers via
+// RangoContext from the runner realm) — see the runner.import below.
+import { buildRouteTrie, buildPerRouterTrie } from "../../build/route-trie.js";
+import { collectFallbackClientRefs } from "../../build/collect-fallback-refs.js";
 import {
   flattenLeafEntries,
   buildRouteToStaticPrefix,
@@ -107,7 +117,10 @@ export async function discoverRouters(
     }
   }
 
-  // Import build utilities for manifest generation
+  // generateManifestFull must run in the RSC runner realm: it invokes the
+  // user's urlpatterns.handler() via RangoContext, consuming router instances
+  // from the runner. The trie/fallback-ref builders are pure transforms over
+  // its output and are imported directly from source above.
   const buildMod = await timed(
     debug,
     "inner: import @rangojs/router/build",
@@ -158,11 +171,12 @@ export async function discoverRouters(
   // are NOT in EntryData, so generateManifestFull's walk misses them. Collect any
   // "use client" default boundary directly off the router instance. The value is
   // commonly a handler function wrapping the client boundary in server providers,
-  // so collectFallbackClientRefs invokes + walks the tree. Routed through buildMod
-  // so it runs in the same RSC runner realm the boundary value came from.
+  // so collectFallbackClientRefs invokes + walks the tree. The walker keys on the
+  // global-registry Symbol.for("react.client.reference"), so it detects client
+  // references in a runner-realm boundary tree even when imported here directly.
   const collectFromBoundaryNode = (node: unknown): void => {
-    if (collectClientFallbackRef && buildMod.collectFallbackClientRefs) {
-      buildMod.collectFallbackClientRefs(node, collectClientFallbackRef);
+    if (collectClientFallbackRef) {
+      collectFallbackClientRefs(node, collectClientFallbackRef);
     }
   };
 
@@ -243,20 +257,19 @@ export async function discoverRouters(
     // Flatten prefix tree leaf nodes into precomputed entries.
     // Leaf nodes (no children) can have their routes used directly by
     // evaluateLazyEntry() without running the handler at runtime.
+    // Walk once into a per-router array, then fold it into the merged array;
+    // the merged and per-router entries are identical, so a second walk is
+    // redundant. Append order is preserved within and across routers.
+    const routerPrecomputed: PrecomputedEntry[] = [];
     flattenLeafEntries(
       manifest.prefixTree,
       manifest.routeManifest,
-      newMergedPrecomputedEntries,
+      routerPrecomputed,
     );
+    newMergedPrecomputedEntries.push(...routerPrecomputed);
 
     // Store per-router manifest and precomputed entries for isolated virtual modules.
     newPerRouterManifestDataMap.set(id, manifest.routeManifest);
-    const routerPrecomputed: PrecomputedEntry[] = [];
-    flattenLeafEntries(
-      manifest.prefixTree,
-      manifest.routeManifest,
-      routerPrecomputed,
-    );
     newPerRouterPrecomputedMap.set(id, routerPrecomputed);
 
     console.log(
@@ -294,8 +307,7 @@ export async function discoverRouters(
   let newMergedRouteTrie: any = null;
   const trieStart = debug ? performance.now() : 0;
   if (Object.keys(newMergedRouteManifest).length > 0) {
-    const buildRouteTrie = buildMod.buildRouteTrie;
-    if (buildRouteTrie && mergedRouteAncestry) {
+    if (mergedRouteAncestry) {
       // Build routeToStaticPrefix from saved manifests
       const routeToStaticPrefix: Record<string, string> = {};
       for (const { manifest } of allManifests) {
@@ -340,36 +352,15 @@ export async function discoverRouters(
         mergedResponseTypeRoutes,
       );
 
-      // Build per-router tries for multi-router isolation.
+      // Build per-router tries for multi-router isolation. Uses the single
+      // shared buildPerRouterTrie so the production serialized trie is built by
+      // exactly the same code as the dev/HMR runtime rebuild (manifest-init.ts).
+      // Returns null for route-less manifests (route-trie.ts).
       for (const { id, manifest } of allManifests) {
-        if (
-          !manifest._routeAncestry ||
-          Object.keys(manifest._routeAncestry).length === 0
-        )
-          continue;
-        const perRouterStaticPrefix: Record<string, string> = {};
-        for (const name of Object.keys(manifest.routeManifest)) {
-          perRouterStaticPrefix[name] = "";
+        const perRouterTrie = buildPerRouterTrie(manifest);
+        if (perRouterTrie) {
+          newPerRouterTrieMap.set(id, perRouterTrie);
         }
-        buildRouteToStaticPrefix(manifest.prefixTree, perRouterStaticPrefix);
-
-        const perRouterPrerenderNames = manifest.prerenderRoutes
-          ? new Set<string>(manifest.prerenderRoutes)
-          : undefined;
-        const perRouterPassthroughNames = manifest.passthroughRoutes
-          ? new Set<string>(manifest.passthroughRoutes)
-          : undefined;
-
-        const perRouterTrie = buildRouteTrie(
-          manifest.routeManifest,
-          manifest._routeAncestry,
-          perRouterStaticPrefix,
-          manifest.routeTrailingSlash,
-          perRouterPrerenderNames,
-          perRouterPassthroughNames,
-          manifest.responseTypeRoutes,
-        );
-        newPerRouterTrieMap.set(id, perRouterTrie);
       }
     }
   }