@rangojs/router 0.0.0-experimental.13 → 0.0.0-experimental.130

package/src/router/instrument.ts

@@ -0,0 +1,308 @@
+/**
+ * Phase + event instrumentation — the single internal API for observing router
+ * work.
+ *
+ * The router exposes the same work on three surfaces, and the rule is: each
+ * surface has exactly one owner here, so they cannot drift.
+ *
+ *   - observePhase(): a span of work. Co-emits the `debugPerformance` perf
+ *     metric (metrics store -> [RSC Perf] timeline + Server-Timing) AND the
+ *     platform span (tracing runner -> Cloudflare custom spans / OTel). From one
+ *     wrap site, so the span set is always a subset of the perf phases and the
+ *     two can't disagree. Phases that meter their own perf metric with a finer
+ *     decomposition (request, middleware) pass `metric: false` and get the span
+ *     only — still co-located, still one owner per surface.
+ *   - observeEvent(): a discrete fact (TelemetrySink): cache decisions,
+ *     revalidation decisions, handler errors, timeouts, origin rejections.
+ *     Event-shaped, not phase-shaped — derived from the same call sites but a
+ *     separate surface from spans.
+ *
+ * Why phases, not events, are the parent abstraction: Cloudflare's span API is
+ * callback-bound (enterSpan wraps the actual work), so the callback boundary is
+ * the source of truth — async-context nesting (a loader's KV/D1/fetch spans
+ * landing under rango.loader) cannot be faithfully reconstructed from
+ * after-the-fact start/end events. Spans drive; events are emitted alongside.
+ *
+ * Phase identity lives in the PHASES registry below, so the raw `rango.*` span
+ * names, perf-metric labels, and span attributes have a single definition each.
+ *
+ * When neither perf surface nor tracing is active on the request, observePhase
+ * is a direct call — no wrapper, no timestamp, no allocation.
+ */
+
+import { _getRequestContext } from "../server/request-context.js";
+import { isAutoGeneratedRouteName } from "../route-name.js";
+import { getRouterContext } from "./router-context.js";
+import { resolveSink, safeEmit, type TelemetryEvent } from "./telemetry.js";
+import { appendMetric } from "./metrics.js";
+import { type MetricsStore } from "../server/context.js";
+import {
+  NOOP_TRACE_SPAN,
+  traceSpan,
+  runThenSettle,
+  type TracePhase,
+  type TraceSpan,
+} from "./tracing.js";
+
+/**
+ * Perf-metric boundary for a phase, or `false` for span-only. `false` means the
+ * caller records its own perf metric with a finer decomposition than a single
+ * wrap (request: a grand total incl. pre-context bootstrap; middleware: pre/post
+ * own-time), so observePhase opens the span but records no metric of its own.
+ */
+export type PhaseMetric =
+  | { label: string | (() => string); depth?: number }
+  | false;
+
+/** Describes one observable phase across the perf and span surfaces. */
+export interface PhaseSpec {
+  /** Perf timeline label + Server-Timing name, or false for span-only. */
+  metric: PhaseMetric;
+  /** Span phase gate (per-phase toggle in the tracing config). */
+  tracePhase: TracePhase;
+  /** Span name (rango.*). */
+  spanName: string;
+  /** Span attributes set automatically when the span opens. */
+  attributes?: Record<string, string | number | boolean>;
+  /**
+   * Span attributes resolved AFTER the wrapped work runs (so they can read state
+   * that only exists once the work is underway, e.g. the matched route name).
+   * Applied for streaming phases once fn has constructed its value. Return
+   * undefined to add nothing.
+   */
+  lazyAttributes?: () => Record<string, string | number | boolean> | undefined;
+}
+
+/**
+ * The matched route name for the current request, or undefined when there is no
+ * named route (unmatched / auto-generated). Shared by the render phase's metric
+ * label and its rango.route span attribute so the two can't disagree.
+ */
+function currentRouteName(): string | undefined {
+  const routeName = _getRequestContext()?._routeName;
+  return routeName && !isAutoGeneratedRouteName(routeName)
+    ? routeName
+    : undefined;
+}
+
+/**
+ * The router's observable phases. One definition per phase keeps the `rango.*`
+ * span names, perf-metric labels, and identifying attributes from spreading
+ * across call sites.
+ */
+export const PHASES = {
+  /** Whole request pipeline. Span only — handler:total is metered directly. */
+  request: {
+    metric: false,
+    tracePhase: "request",
+    spanName: "rango.request",
+  } as PhaseSpec,
+
+  /** One middleware (incl. its downstream onion). Span only — the perf metric
+   * is the middleware's exclusive pre/post own-time, recorded directly.
+   * `metricLabel` is that metric's label (e.g. "middleware:auth@*"); it doubles
+   * as the rango.middleware_name span attribute. */
+  middleware: (metricLabel: string): PhaseSpec => ({
+    metric: false,
+    tracePhase: "middleware",
+    spanName: "rango.middleware",
+    attributes: { "rango.middleware_name": metricLabel },
+  }),
+
+  /** The server-action execution (decode args + run the action body), before
+   * the revalidation render. The metric label carries the action id (the
+   * _rsc_action / action $$id) so the perf timeline shows WHICH action ran, not
+   * just "an action"; the span also gets it as rango.action_id. */
+  action: (id: string): PhaseSpec => ({
+    metric: { label: `action:${id}` },
+    tracePhase: "action",
+    spanName: "rango.action",
+    attributes: { "rango.action_id": id },
+  }),
+
+  /**
+   * One loader execution. `depth` is the perf-timeline indentation: 2 (default)
+   * for render-time loaders that nest under the render phase; 1 for a standalone
+   * fetchable `_rsc_loader` request, which has no render parent.
+   */
+  loader: (id: string, depth: number = 2): PhaseSpec => ({
+    metric: { label: `loader:${id}`, depth },
+    tracePhase: "loader",
+    spanName: "rango.loader",
+    attributes: { "rango.loader_id": id },
+  }),
+
+  /** One segment route/layout handler execution (the component/handler that
+   * produces a segment). Span only — the perf metric (handler:<id>) is owned by
+   * the legacy track() at the same call site, so observePhase here adds the
+   * rango.handler span without double-recording. `id` is the segment id, carried
+   * as the rango.segment_id attribute to match the handler:<id> perf row. */
+  handler: (id: string): PhaseSpec => ({
+    metric: false,
+    tracePhase: "handler",
+    spanName: "rango.handler",
+    attributes: { "rango.segment_id": id },
+  }),
+
+  /** Whole render phase: match + serialize + SSR. The metric label is resolved
+   * lazily at record time (after match has set the route name) so the perf
+   * timeline shows WHICH route rendered: `render:total:<routeName>`, falling back
+   * to `render:total` when there is no named route (unmatched / auto-generated). */
+  render: {
+    metric: {
+      label: () => {
+        const routeName = currentRouteName();
+        return routeName ? `render:total:${routeName}` : "render:total";
+      },
+    },
+    tracePhase: "render",
+    spanName: "rango.render",
+    // Tag the render span with the matched route so the Cloudflare/OTel waterfall
+    // shows WHICH route rendered (rango.render + rango.route=index), resolved
+    // after match has run. Kept an attribute (not baked into the span name) so the
+    // span name stays low-cardinality and aggregatable across routes.
+    lazyAttributes: () => {
+      const routeName = currentRouteName();
+      return routeName ? { "rango.route": routeName } : undefined;
+    },
+  } as PhaseSpec,
+
+  /** SSR HTML render from the RSC stream. Colon-delimited like the other ssr:*
+   * setup metrics (ssr:module-load / ssr:stream-mode). */
+  ssr: {
+    metric: { label: "ssr:render-html" },
+    tracePhase: "ssr",
+    spanName: "rango.ssr",
+  } as PhaseSpec,
+} as const;
+
+/** Apply a phase spec's static attributes to a span (the no-op span ignores them). */
+function applyAttributes(
+  span: TraceSpan,
+  attributes: Record<string, string | number | boolean>,
+): void {
+  for (const key in attributes) span.setAttribute(key, attributes[key]);
+}
+
+/**
+ * Record a phase's perf metric for the interval [start, now]. The label may be
+ * lazy (resolved here, e.g. render:total needs the route name that match sets
+ * partway through the wrapped work).
+ */
+function recordPhaseMetric(
+  store: MetricsStore,
+  metric: Exclude<PhaseMetric, false>,
+  start: number,
+): void {
+  const label =
+    typeof metric.label === "function" ? metric.label() : metric.label;
+  appendMetric(store, label, start, performance.now() - start, metric.depth);
+}
+
+/**
+ * Instrument one unit of work: open its span AND (unless `metric: false`) record
+ * its perf metric, from a single wrap site. fn is invoked exactly once with the
+ * span (a no-op span when tracing is off); its return value is returned
+ * unchanged and thrown errors / rejected promises propagate unchanged. When fn
+ * returns a promise both the metric duration and the span end when it settles.
+ *
+ * This is the ONLY phase primitive: every phase (request/middleware/action/
+ * loader/handler/render/ssr) is construction-bound — the span and metric settle
+ * when fn's own work completes (for the streaming phases, when the RSC/HTML
+ * stream is constructed, NOT when the body drains). Instrumentation is strictly
+ * best-effort: it never wraps or buffers the response and adds no work on the
+ * streaming path, so it cannot regress response latency or streaming. A loader
+ * that resolves while the body streams therefore keeps a rango.loader span that
+ * may extend past its render parent — overlapping spans are valid; the loader
+ * really did take that long.
+ *
+ * Reads the metrics store + tracing off the RequestContext ALS, which is active
+ * for the WHOLE request — contrast observeEvent, which reads the RouterContext
+ * ALS (entered later, during match).
+ */
+export function observePhase<T>(
+  spec: PhaseSpec,
+  fn: (span: TraceSpan) => T,
+): T {
+  const reqCtx = _getRequestContext();
+  const store = reqCtx?._metricsStore;
+  const tracing = reqCtx?._tracing;
+
+  // Neither surface active: direct call, zero overhead.
+  if (!store && !tracing) return fn(NOOP_TRACE_SPAN);
+
+  // Attributes only land on a real span, so skip the wrapper when only the perf
+  // surface is active (traceSpan would apply them to NOOP_TRACE_SPAN for nothing).
+  // `lazyAttributes` resolve AFTER fn runs (e.g. rango.route, known post-match).
+  const attributes = spec.attributes;
+  const lazy = spec.lazyAttributes;
+  const wrapped: (span: TraceSpan) => T =
+    (attributes || lazy) && tracing
+      ? (span) => {
+          if (attributes) applyAttributes(span, attributes);
+          const out = fn(span);
+          if (!lazy) return out;
+          if (out instanceof Promise) {
+            return out.then((value) => {
+              const late = lazy();
+              if (late) applyAttributes(span, late);
+              return value;
+            }) as T;
+          }
+          const late = lazy();
+          if (late) applyAttributes(span, late);
+          return out;
+        }
+      : fn;
+
+  const runSpan = (): T =>
+    traceSpan(tracing, spec.tracePhase, spec.spanName, wrapped);
+
+  // Span-only — no perf metric to record (metric:false, or perf surface off).
+  const metric = spec.metric;
+  if (!store || metric === false) return runSpan();
+
+  // Record the phase duration on EVERY termination — success or failure — so a
+  // failed loader/render still shows its timing in the perf report (parity with
+  // the old track().finally() path it replaced).
+  const start = performance.now();
+  return runThenSettle(runSpan, () => recordPhaseMetric(store, metric, start));
+}
+
+/**
+ * Emit one discrete telemetry event (the event-shaped counterpart to
+ * observePhase). Resolves the sink from the active router context and stamps the
+ * request id when the event omits it. No-op (and total — never throws) when no
+ * sink is configured.
+ *
+ * This is the canonical emitter for SYNCHRONOUS facts that fire inside the
+ * request's ALS scope (handler errors, timeouts, origin rejections, revalidation
+ * decisions). A few emitters deliberately stay on the lower-level
+ * resolveSink + safeEmit because observeEvent's lazy, per-call
+ * getRouterContext() read does not fit them — keep this the complete list:
+ *   - router.ts wrapLoaderPromise (loader.start/end/error) and
+ *     segment-resolution/streamed-handler-telemetry.ts (streamed handler.error)
+ *     capture the sink + request id EAGERLY and emit from a fire-and-forget
+ *     continuation that runs after the ALS scope may have unwound.
+ *   - router/match-handlers.ts resolves the sink ONCE for the hot match-pipeline
+ *     loop (request.start/end/error, cache.decision, ...).
+ *   - segment-resolution/helpers.ts emits via a caller-provided report.telemetry
+ *     sink rather than the ALS router context.
+ */
+export function observeEvent(event: TelemetryEvent): void {
+  // getRouterContext() either throws (real impl, outside a router context — e.g.
+  // the build-time prerender path) or returns null/undefined (e.g. mocked).
+  // Either way there is no sink to emit to, so swallow and return.
+  let routerCtx: ReturnType<typeof getRouterContext> | null | undefined;
+  try {
+    routerCtx = getRouterContext();
+  } catch {
+    return;
+  }
+  if (!routerCtx?.telemetry) return;
+  const stamped =
+    event.requestId === undefined && routerCtx.requestId !== undefined
+      ? ({ ...event, requestId: routerCtx.requestId } as TelemetryEvent)
+      : event;
+  safeEmit(resolveSink(routerCtx.telemetry), stamped);
+}

package/src/router/intercept-resolution.ts

@@ -11,13 +11,23 @@ import type {
   InterceptEntry,
   InterceptSelectorContext,
 } from "../server/context";
-import type { HandlerContext, ResolvedSegment } from "../types";
+import type {
+  HandlerContext,
+  InternalHandlerContext,
+  ResolvedSegment,
+} from "../types";
 import { evaluateRevalidation } from "./revalidation.js";
 import { getRequestContext } from "../server/request-context.js";
 import { executeInterceptMiddleware } from "./middleware.js";
-import { handleHandlerResult } from "./segment-resolution.js";
+import { createReverseFunction } from "./handler-context.js";
+import { getGlobalRouteMap } from "../route-map-builder.js";
+import {
+  handleHandlerResult,
+  warnOnStreamedResponse,
+} from "./segment-resolution.js";
 import type { SegmentResolutionDeps } from "./types.js";
 import { debugLog } from "./logging.js";
+import { runInsideLoaderScope } from "../server/context.js";
 
 /**
  * Check if an intercept's when conditions are satisfied.
@@ -59,28 +69,14 @@ export function findInterceptForRoute(
   let current: EntryData | null = fromEntry;
 
   while (current) {
-    if (current.intercept && current.intercept.length > 0) {
-      for (const intercept of current.intercept) {
+    // current first, then its sibling layouts — same order as before.
+    for (const source of [current, ...current.layout]) {
+      for (const intercept of source.intercept) {
         if (
           intercept.routeName === targetRouteKey &&
           evaluateInterceptWhen(intercept, selectorContext, isAction)
         ) {
-          return { intercept, entry: current };
-        }
-      }
-    }
-
-    if (current.layout && current.layout.length > 0) {
-      for (const siblingLayout of current.layout) {
-        if (siblingLayout.intercept && siblingLayout.intercept.length > 0) {
-          for (const intercept of siblingLayout.intercept) {
-            if (
-              intercept.routeName === targetRouteKey &&
-              evaluateInterceptWhen(intercept, selectorContext, isAction)
-            ) {
-              return { intercept, entry: siblingLayout };
-            }
-          }
+          return { intercept, entry: source };
         }
       }
     }
@@ -131,8 +127,9 @@ export async function resolveInterceptEntry<TEnv>(
       context.request,
       context.env,
       params,
-      context.var as Record<string, any>,
+      (context as InternalHandlerContext<any, TEnv>)._variables,
       requestCtx.res,
+      createReverseFunction(getGlobalRouteMap()),
     );
     if (middlewareResponse) throw middlewareResponse;
   }
@@ -185,6 +182,7 @@ export async function resolveInterceptEntry<TEnv>(
           context,
           actionContext,
           stale,
+          traceSource: "intercept-loader",
         });
 
         if (!shouldRevalidate) {
@@ -203,7 +201,7 @@ export async function resolveInterceptEntry<TEnv>(
     loaderIds.push(loader.$$id);
     loaderPromises.push(
       deps.wrapLoaderPromise(
-        context.use(loader),
+        runInsideLoaderScope(() => context.use(loader)),
         parentEntry,
         segmentId,
         context.pathname,
@@ -233,6 +231,12 @@ export async function resolveInterceptEntry<TEnv>(
   let loaderDataPromise: Promise<any[]> | any[] | undefined;
 
   if (interceptEntry.loading && loaderPromises.length > 0) {
+    if (handlerResult instanceof Promise) {
+      warnOnStreamedResponse(
+        handlerResult,
+        `intercept ${interceptEntry.slotName}`,
+      );
+    }
     component =
       handlerResult instanceof Promise
         ? handlerResult
@@ -352,6 +356,7 @@ export async function resolveInterceptLoadersOnly<TEnv>(
         context,
         actionContext,
         stale,
+        traceSource: "intercept-loader",
       });
 
       if (!shouldRevalidate) {
@@ -369,7 +374,7 @@ export async function resolveInterceptLoadersOnly<TEnv>(
     loaderIds.push(loader.$$id);
     loaderPromises.push(
       deps.wrapLoaderPromise(
-        context.use(loader),
+        runInsideLoaderScope(() => context.use(loader)),
         parentEntry,
         segmentId,
         context.pathname,
@@ -381,10 +386,12 @@ export async function resolveInterceptLoadersOnly<TEnv>(
     return null;
   }
 
-  const loaderDataPromise =
-    interceptEntry.loading !== undefined
-      ? Promise.all(loaderPromises)
-      : await Promise.all(loaderPromises);
+  // Match fresh-path semantics: only defer (no await) when loading is truthy.
+  // `loading: false` means "no loading UI, await loaders before render" —
+  // same as the fresh path's `if (interceptEntry.loading && ...)` check.
+  const loaderDataPromise = interceptEntry.loading
+    ? Promise.all(loaderPromises)
+    : await Promise.all(loaderPromises);
 
   return { loaderDataPromise, loaderIds };
 }

package/src/router/lazy-includes.ts

@@ -0,0 +1,200 @@
+import { registerRouteMap } from "../route-map-builder.js";
+import { extractStaticPrefix, joinPrefix } from "./pattern-matching.js";
+import {
+  type EntryData,
+  RangoContext,
+  runWithPrefixes,
+  getIsolatedLazyParent,
+} from "../server/context";
+import type { UrlPatterns } from "../urls.js";
+import type { AllUseItems, IncludeItem } from "../route-types.js";
+import type { ResolvedRouteMap, RouteEntry, TrailingSlashMode } from "../types";
+
+export interface LazyEvalDeps<TEnv = any> {
+  routesEntries: RouteEntry<TEnv>[];
+  mergedRouteMap: Record<string, string>;
+  nextMountIndex: () => number;
+  getPrecomputedByPrefix: () => Map<string, Record<string, string>> | null;
+  routerId?: string;
+}
+
+export function findLazyIncludes<TEnv = any>(
+  items: AllUseItems[],
+): Array<{
+  prefix: string;
+  patterns: UrlPatterns<TEnv>;
+  context: {
+    urlPrefix: string;
+    namePrefix: string | undefined;
+    parent: unknown;
+    rootScoped?: boolean;
+  };
+}> {
+  const lazyItems: Array<{
+    prefix: string;
+    patterns: UrlPatterns<TEnv>;
+    context: {
+      urlPrefix: string;
+      namePrefix: string | undefined;
+      parent: unknown;
+      rootScoped?: boolean;
+    };
+  }> = [];
+
+  for (const item of items) {
+    if (!item) continue;
+    if (item.type === "include") {
+      const includeItem = item as IncludeItem;
+      if (includeItem.lazy === true && includeItem._lazyContext) {
+        lazyItems.push({
+          prefix: includeItem.prefix,
+          patterns: includeItem.patterns as UrlPatterns<TEnv>,
+          context: includeItem._lazyContext,
+        });
+      }
+    }
+    if ((item as any).uses && Array.isArray((item as any).uses)) {
+      lazyItems.push(...findLazyIncludes((item as any).uses));
+    }
+  }
+
+  return lazyItems;
+}
+
+/**
+ * Evaluate a lazy entry's patterns and populate its routes
+ * This runs the lazy patterns handler and updates the entry in-place
+ * Also detects nested lazy includes and registers them as new entries
+ */
+export function evaluateLazyEntry<TEnv = any>(
+  entry: RouteEntry<TEnv>,
+  deps: LazyEvalDeps<TEnv>,
+): void {
+  if (!entry.lazy || entry.lazyEvaluated || !entry.lazyPatterns) {
+    return;
+  }
+
+  const currentPrecomputed = deps.getPrecomputedByPrefix();
+  if (currentPrecomputed) {
+    const routes = currentPrecomputed.get(entry.staticPrefix);
+    if (routes) {
+      const prefixIsShared =
+        deps.routesEntries.filter((e) => e.staticPrefix === entry.staticPrefix)
+          .length > 1;
+      if (!prefixIsShared) {
+        entry.lazyEvaluated = true;
+        entry.routes = routes as ResolvedRouteMap<any>;
+        for (const [name, pattern] of Object.entries(routes)) {
+          deps.mergedRouteMap[name] = pattern;
+        }
+        registerRouteMap(deps.mergedRouteMap);
+        return;
+      }
+    }
+  }
+
+  entry.lazyEvaluated = true;
+
+  const lazyPatterns = entry.lazyPatterns as UrlPatterns<TEnv>;
+  const lazyContext = entry.lazyContext;
+
+  const manifest = new Map<string, EntryData>();
+  const patterns = new Map<string, string>();
+  const patternsByPrefix = new Map<string, Map<string, string>>();
+  const trailingSlashMap = new Map<string, TrailingSlashMode>();
+
+  let handlerResult: AllUseItems[] = [];
+
+  const lazyCounters: Record<string, number> = {};
+  if (lazyContext?.counters) {
+    for (const [key, value] of Object.entries(lazyContext.counters)) {
+      lazyCounters[key] = value;
+    }
+  }
+
+  RangoContext.run(
+    {
+      manifest,
+      patterns,
+      patternsByPrefix,
+      trailingSlash: trailingSlashMap,
+      namespace: "lazy",
+      parent: getIsolatedLazyParent(lazyContext?.parent as EntryData | null),
+      counters: lazyCounters,
+      cacheProfiles: lazyContext?.cacheProfiles,
+      rootScoped: lazyContext?.rootScoped,
+      includeScope: lazyContext?.includeScope,
+    },
+    () => {
+      const includePrefix = (entry as any)._lazyPrefix || "";
+      const fullPrefix = joinPrefix(lazyContext?.urlPrefix, includePrefix);
+
+      if (fullPrefix || lazyContext?.namePrefix) {
+        runWithPrefixes(fullPrefix, lazyContext?.namePrefix, () => {
+          handlerResult = lazyPatterns.handler() as AllUseItems[];
+        });
+      } else {
+        handlerResult = lazyPatterns.handler() as AllUseItems[];
+      }
+    },
+  );
+
+  const routesObject: Record<string, string> = {};
+  for (const [name, pattern] of patterns.entries()) {
+    routesObject[name] = pattern;
+    const existingPattern = deps.mergedRouteMap[name];
+    if (existingPattern !== undefined && existingPattern !== pattern) {
+      console.warn(
+        `[@rangojs/router] Route name conflict: "${name}" already maps to "${existingPattern}", ` +
+          `overwriting with "${pattern}" (from lazy include). Use unique route names to avoid this.`,
+      );
+    }
+    deps.mergedRouteMap[name] = pattern;
+  }
+
+  entry.routes = routesObject as ResolvedRouteMap<any>;
+
+  if (trailingSlashMap.size > 0) {
+    entry.trailingSlash = Object.fromEntries(trailingSlashMap);
+  }
+
+  const nestedLazyIncludes = findLazyIncludes(handlerResult);
+  for (const lazyInclude of nestedLazyIncludes) {
+    const fullPrefix = joinPrefix(
+      lazyInclude.context.urlPrefix,
+      lazyInclude.prefix,
+    );
+
+    const nestedEntry: RouteEntry<TEnv> & { _lazyPrefix?: string } = {
+      prefix: "",
+      staticPrefix: extractStaticPrefix(fullPrefix),
+      routes: {} as ResolvedRouteMap<any>,
+      trailingSlash: entry.trailingSlash,
+      handler: (lazyInclude.patterns as UrlPatterns<TEnv>).handler,
+      mountIndex: deps.nextMountIndex(),
+      routerId: deps.routerId,
+      lazy: true,
+      lazyPatterns: lazyInclude.patterns,
+      lazyContext: lazyInclude.context,
+      lazyEvaluated: false,
+      _lazyPrefix: lazyInclude.prefix,
+    };
+    const nestedPrefix = nestedEntry.staticPrefix;
+    let insertIndex = deps.routesEntries.length;
+    if (nestedPrefix) {
+      for (let i = 0; i < deps.routesEntries.length; i++) {
+        const existing = deps.routesEntries[i]!;
+        if (
+          nestedPrefix.startsWith(existing.staticPrefix) &&
+          nestedPrefix.length > existing.staticPrefix.length
+        ) {
+          insertIndex = i;
+          break;
+        }
+      }
+    }
+    deps.routesEntries.splice(insertIndex, 0, nestedEntry);
+  }
+
+  registerRouteMap(deps.mergedRouteMap);
+}