@rangojs/router 0.0.0-experimental.d20dd405 → 0.0.0-experimental.d5d3070a

package/src/search-params.ts

@@ -7,9 +7,16 @@
  * URLSearchParams instance.
  */
 
-// ============================================================================
-// Schema Types
-// ============================================================================
+import { encodeKV } from "./encode-kv.js";
+
+/**
+ * Decimal-number grammar for `"number"` search params: optional sign, digits
+ * with optional fraction, optional exponent. Deliberately excludes hex (`0x`),
+ * `Infinity`, and empty/whitespace so `Number()`'s lenient coercions
+ * (`Number("")===0`, `Number("0x10")===16`, `Number("Infinity")===Infinity`)
+ * do not slip non-decimal values into typed search.
+ */
+const DECIMAL_NUMBER_RE = /^[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/;
 
 /** Supported scalar types for search params (append ? for optional). */
 export type SearchSchemaValue =
@@ -23,10 +30,6 @@ export type SearchSchemaValue =
 /** A search schema maps param names to their type descriptors. */
 export type SearchSchema = Record<string, SearchSchemaValue>;
 
-// ============================================================================
-// Type-Level Schema Resolution
-// ============================================================================
-
 /** Strip trailing `?` from a schema value to get the base type. */
 type BaseType<T extends string> = T extends `${infer B}?` ? B : T;
 
@@ -81,11 +84,11 @@ export type ResolveSearchSchema<T extends SearchSchema> = Simplify<
 // ============================================================================
 
 /** Resolve the global route map from RegisteredRoutes or GeneratedRouteMap. */
-type GlobalRouteMap = keyof RSCRouter.RegisteredRoutes extends never
-  ? keyof RSCRouter.GeneratedRouteMap extends never
+type GlobalRouteMap = keyof Rango.RegisteredRoutes extends never
+  ? keyof Rango.GeneratedRouteMap extends never
     ? Record<string, string>
-    : RSCRouter.GeneratedRouteMap
-  : RSCRouter.RegisteredRoutes;
+    : Rango.GeneratedRouteMap
+  : Rango.RegisteredRoutes;
 
 /**
  * Extract the resolved search params type for a named route.
@@ -163,15 +166,15 @@ type ExtractParamsFromPattern<T extends string> =
             : { [K in Param]: string }
       : {};
 
-// ============================================================================
-// Runtime Parser
-// ============================================================================
-
 /**
  * Parse URLSearchParams into a typed object using the given schema.
  *
  * - `"string"` / `"string?"` - kept as-is
- * - `"number"` / `"number?"` - coerced via `Number()`; NaN treated as missing
+ * - `"number"` / `"number?"` - parsed as a finite decimal number. Accepts an
+ *   optional sign, digits with optional fraction, and optional exponent
+ *   (e.g. `42`, `-3.5`, `1e3`). Empty/whitespace-only, non-decimal forms
+ *   (`0x10`), and non-finite (`Infinity`) are treated as missing (omitted),
+ *   NOT coerced to `0`/`16`/`Infinity`.
  * - `"boolean"` / `"boolean?"` - `"true"` / `"1"` -> true, `"false"` / `"0"` / `""` -> false
  *
  * Missing params (both required and optional) are omitted from the result
@@ -197,11 +200,17 @@ export function parseSearchParams<T extends SearchSchema>(
     if (baseType === "string") {
       result[key] = raw;
     } else if (baseType === "number") {
-      const num = Number(raw);
-      if (!Number.isNaN(num)) {
-        result[key] = num;
+      // Trim, then require a valid decimal numeral and a finite result.
+      // Empty/whitespace, hex (0x10), and Infinity are treated as missing
+      // (omitted) — not coerced to 0/16/Infinity by Number()'s lenient rules.
+      const trimmed = raw.trim();
+      if (trimmed !== "" && DECIMAL_NUMBER_RE.test(trimmed)) {
+        const num = Number(trimmed);
+        if (Number.isFinite(num)) {
+          result[key] = num;
+        }
       }
-      // NaN treated as missing (undefined)
+      // Anything else treated as missing (undefined)
     } else if (baseType === "boolean") {
       result[key] = raw === "true" || raw === "1";
     }
@@ -210,21 +219,17 @@ export function parseSearchParams<T extends SearchSchema>(
   return result as ResolveSearchSchema<T>;
 }
 
-// ============================================================================
-// Runtime Serializer
-// ============================================================================
-
 /**
  * Serialize a typed search params object to a query string (without leading `?`).
- * Skips `undefined` and `null` values.
+ * Skips `undefined` and `null` values. Preserves insertion order (no sort).
  */
 export function serializeSearchParams(params: Record<string, unknown>): string {
-  const parts: string[] = [];
+  // Pre-filter null/undefined and coerce values to strings here so encodeKV
+  // (which never inspects values) reproduces this call site's exact output.
+  const pairs: [string, string][] = [];
   for (const [key, value] of Object.entries(params)) {
     if (value === undefined || value === null) continue;
-    parts.push(
-      `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`,
-    );
+    pairs.push([key, String(value)]);
   }
-  return parts.join("&");
+  return encodeKV(pairs);
 }

package/src/segment-loader-promise.ts

@@ -7,8 +7,9 @@ import type { ResolvedSegment } from "./types.js";
  * source array (typically a single entry, since distinct loader groups rarely
  * share a first source). Object first-refs live in a WeakMap (auto-GC);
  * primitive first-refs (strings/numbers/booleans/null) live in a Map so
- * loaders that resolve to primitive data are memoized too — bounded in
- * practice by the application's loader set.
+ * loaders that resolve to primitive data are memoized too. The per-key array
+ * is capped (MAX_ENTRIES_PER_KEY, oldest evicted) so a long session under a
+ * stable first-ref does not grow it without bound.
  *
  * Keying externally means reconciliation's fresh segment objects no longer
  * drop memoization — the cache survives as long as the underlying loader
@@ -26,9 +27,22 @@ const IS_BROWSER = typeof window !== "undefined";
 
 interface LoaderCacheEntry {
   sources: any[];
-  promise: Promise<any[]> | any[];
+  // buildLoaderPromise always returns a Promise, so the cached value is never a
+  // bare array. The public getMemoizedLoaderPromise return type stays broader
+  // (Promise<any[]> | any[]) to mirror its siblings.
+  promise: Promise<any[]>;
 }
 
+// Cap the per-key entries array. A stable first-ref (e.g. a layout loader whose
+// loaderData object survives reconciliation across navigations) keeps its
+// WeakMap/Map key alive, while a per-route loader whose ref changes each
+// navigation appends a brand-new sources array under that same live key on
+// every navigation. Nothing was ever removed, so the array grew linearly with
+// navigation count, pinning each stale Promise + sources array from GC — a
+// steady client-side leak over a long session. Only the current render's combo
+// needs to stay warm; evict the oldest beyond the cap.
+const MAX_ENTRIES_PER_KEY = 8;
+
 const objectLoaderCache = IS_BROWSER
   ? new WeakMap<object, LoaderCacheEntry[]>()
   : null;
@@ -56,7 +70,16 @@ function hasSameReferences(a: any[], b: any[]): boolean {
   return true;
 }
 
-function buildLoaderPromise(loaders: ResolvedSegment[]): Promise<any[]> {
+/**
+ * Build a fresh aggregate Promise.all over the loaders' resolved data refs.
+ * Unlike getMemoizedLoaderPromise this never caches, so each call yields a new
+ * Promise — correct for sites that await the result immediately (a shared,
+ * already-resolved promise would leak React's `.status` across server requests
+ * and skip the Suspense fallback).
+ *
+ * @internal
+ */
+export function buildLoaderPromise(loaders: ResolvedSegment[]): Promise<any[]> {
   if (loaders.length === 0) {
     return Promise.resolve([]);
   }
@@ -112,6 +135,10 @@ export function getMemoizedLoaderPromise(
   const promise = buildLoaderPromise(loaders);
   const newEntry: LoaderCacheEntry = { sources, promise };
   if (entries) {
+    // Bound the array: drop the oldest entry before appending when at the cap.
+    if (entries.length >= MAX_ENTRIES_PER_KEY) {
+      entries.shift();
+    }
     entries.push(newEntry);
   } else if (isObjectLike(first)) {
     objectLoaderCache.set(first, [newEntry]);

package/src/segment-system.tsx

@@ -1,9 +1,9 @@
 import * as React from "react";
 import { createElement, type ReactNode, type ComponentType } from "react";
-import { OutletProvider } from "./client.js";
+import { OutletProvider } from "./outlet-provider.js";
 import { MountContextProvider } from "./browser/react/mount-context.js";
 import type { ResolvedSegment, RootLayoutProps } from "./types.js";
-import { isLoaderDataResult } from "./types.js";
+import { decodeLoaderResults } from "./decode-loader-results.js";
 import { invariant } from "./errors.js";
 import {
   RouteContentWrapper,
@@ -11,16 +11,34 @@ import {
 } from "./route-content-wrapper.js";
 import { RootErrorBoundary } from "./root-error-boundary.js";
 import { getMemoizedContentPromise } from "./segment-content-promise.js";
-import { getMemoizedLoaderPromise } from "./segment-loader-promise.js";
+import {
+  buildLoaderPromise,
+  getMemoizedLoaderPromise,
+} from "./segment-loader-promise.js";
 
 // ViewTransition is only available in React experimental.
 // Access via namespace import to avoid compile-time errors on stable React.
 const ReactViewTransition: any =
   "ViewTransition" in React ? (React as any).ViewTransition : null;
 
-function restoreParallelLoaderMarkers(
+// A loading skeleton is renderable only when it is a real ReactNode value.
+// `false` is treated as "not renderable" here. This is the three-term gate;
+// the distinct two-term gate at the LoaderBoundary site deliberately treats
+// `false` as "create a boundary without a RouteContentWrapper"
+// (tree-structure.md), so it must NOT use this helper.
+function isRenderableLoading(loading: ReactNode): boolean {
+  return loading !== undefined && loading !== null && loading !== false;
+}
+
+// Exported for unit testing the no-parallel fast path (D6); internal otherwise.
+export function restoreParallelLoaderMarkers(
   segments: ResolvedSegment[],
 ): ResolvedSegment[] {
+  // Parallel-loading markers only exist when a parallel segment is present, so
+  // a list with no parallel slot has nothing to restore. Skip the Map alloc and
+  // full scan in that (common) case — this runs on every render.
+  if (!segments.some((s) => s.type === "parallel")) return segments;
+
   const parallelLoadingByNamespace = new Map<string, ReactNode>();
   let nextSegments: ResolvedSegment[] | null = null;
 
@@ -28,12 +46,7 @@ function restoreParallelLoaderMarkers(
     const segment = segments[i];
 
     if (segment.type === "parallel") {
-      if (
-        segment.namespace &&
-        segment.loading !== undefined &&
-        segment.loading !== null &&
-        segment.loading !== false
-      ) {
+      if (segment.namespace && isRenderableLoading(segment.loading)) {
         parallelLoadingByNamespace.set(segment.namespace, segment.loading);
       }
       continue;
@@ -59,42 +72,6 @@ function restoreParallelLoaderMarkers(
   return nextSegments ?? segments;
 }
 
-/**
- * Resolve loader data from raw results, unwrapping LoaderDataResult wrappers
- */
-function resolveLoaderData(
-  resolvedData: any[],
-  loaderIds: string[],
-): { loaderData: Record<string, any>; errorFallback: ReactNode } {
-  const loaderData: Record<string, any> = {};
-  let errorFallback: ReactNode = null;
-
-  for (let i = 0; i < loaderIds.length; i++) {
-    const id = loaderIds[i];
-    const result = resolvedData[i];
-
-    if (!isLoaderDataResult(result)) {
-      // Legacy format - direct data
-      loaderData[id] = result;
-      continue;
-    }
-
-    if (result.ok) {
-      loaderData[id] = result.data;
-      continue;
-    }
-
-    // Error case
-    if (result.fallback) {
-      errorFallback = result.fallback;
-    } else {
-      throw new Error(result.error.message);
-    }
-  }
-
-  return { loaderData, errorFallback };
-}
-
 /**
  * Options for renderSegments
  */
@@ -135,8 +112,11 @@ function createViewTransitionBoundary(
   transition: NonNullable<ResolvedSegment["transition"]>,
   children: ReactNode,
 ): ReactNode {
+  // `viewTransition` is a router-specific flag (boundary opt-out), not a React
+  // <ViewTransition> prop — strip it so it never reaches React.
+  const { viewTransition: _viewTransition, ...vtProps } = transition;
   return createElement(ReactViewTransition, {
-    ...transition,
+    ...vtProps,
     children,
   });
 }
@@ -175,8 +155,14 @@ function wrapDefaultOutletContent(
 /**
  * Render segments into a React tree with proper layout nesting
  *
- * Layouts nest using OutletProvider, while route + parallel + error + notFound segments
- * render as siblings in a Fragment.
+ * Layouts nest using OutletProvider; a layout receives the inner content via
+ * its `<Outlet />`. Parallel segments do NOT render as inline Fragment siblings
+ * — they flow through OutletContext.parallel and are resolved where a layout
+ * places `<ParallelOutlet name="@sidebar" />` (or `<Outlet name="@sidebar" />`).
+ *
+ * The result is always wrapped in RootErrorBoundary so unhandled errors never
+ * blank the screen. When `options.rootLayout` is provided it wraps the error
+ * boundary at the OUTERMOST level (so the app shell survives errors).
  *
  * Error segments are treated like route segments - they render their fallback
  * component in place of the failed segment. When an error occurs in a handler,
@@ -188,27 +174,30 @@ function wrapDefaultOutletContent(
  * notFoundBoundary's fallback component.
  *
  * @param segments - Array of resolved segments to render
- * @returns ReactNode representing the component tree
+ * @returns Promise resolving to the ReactNode tree (the function is async)
  *
  * @example
  * ```typescript
  * const segments = [
- *   { id: 'L0.0', type: 'layout', component: <RootLayout /> },
- *   { id: 'L1.0', type: 'layout', component: <BlogLayout /> },
- *   { id: 'R2.0', type: 'route', component: <BlogPost /> },
- *   { id: 'P3.0', type: 'parallel', component: <Sidebar />, slot: '@sidebar' }
+ *   { id: 'L0.0', type: 'layout', component: <BlogLayout /> },
+ *   { id: 'L0R1', type: 'route', component: <BlogPost /> },
+ *   { id: 'L0R1.@sidebar', type: 'parallel', component: <Sidebar />, slot: '@sidebar' }
  * ];
  *
- * const tree = renderSegments(segments);
- * // Results in:
- * // <OutletProvider><RootLayout>
- * //   <OutletProvider><BlogLayout>
- * //     <><BlogPost /><Sidebar /></>
- * //   </BlogLayout></OutletProvider>
- * // </RootLayout></OutletProvider>
+ * // BlogLayout renders <Outlet /> for the route and
+ * // <ParallelOutlet name="@sidebar" /> for the parallel slot.
+ * const tree = await renderSegments(segments, { rootLayout: RootLayout });
+ * // Results in (outermost first):
+ * // <RootLayout>
+ * //   <RootErrorBoundary>
+ * //     <OutletProvider segment={BlogLayout} parallel={[Sidebar]}>
+ * //       <BlogPost />
+ * //     </OutletProvider>
+ * //   </RootErrorBoundary>
+ * // </RootLayout>
  *
  * // For server actions, pass isAction to await components:
- * const tree = renderSegments(segments, { isAction: true });
+ * const tree = await renderSegments(segments, { isAction: true });
  * ```
  */
 export async function renderSegments(
@@ -252,6 +241,25 @@ export async function renderSegments(
   }
   // Separate segments by type, passing intercept segments for explicit injection
   const tree = segmentTreeWalk(normalizedSegments, normalizedInterceptSegments);
+
+  // A route is "in a transition scope" when its own segment OR any layout in
+  // its matched chain declares transition(). Both transition() forms land here:
+  // the per-route item form sets transition on the route entry, and the block
+  // wrapper form sets it on a transparent ancestor layout (dsl-helpers.ts). When
+  // in scope, the route and its route-owned layouts use param-agnostic keys so a
+  // same-route navigation reconciles (holds content) instead of remounting. The
+  // value is a static property of the route's position in the tree, so it is the
+  // same on every render of that route (SSR, navigation, action) — the keys
+  // never drift. Cross-route navigation still remounts: different routes have
+  // different segment ids regardless of transition scope.
+  const inTransitionScope = normalizedSegments.some(
+    (s) =>
+      s.transition != null &&
+      (s.type === "layout" ||
+        s.type === "route" ||
+        s.type === "error" ||
+        s.type === "notFound"),
+  );
   // Render content segments as siblings
   let content: ReactNode = null;
   for (const node of tree) {
@@ -264,17 +272,31 @@ export async function renderSegments(
     );
     const { component, id, params, loading } = node.segment;
 
-    // Only include params in key for segments that belong to the route
-    // - Routes: always include params (they render param-specific content)
-    // - Error/notFound segments: always include params (they replace failed route content)
-    // - Route's layouts (orphans): include params (children of parameterized route)
-    // - Parent chain layouts: exclude params (shared across routes, param-agnostic)
-    // This prevents unnecessary unmounting when params change
+    // Param-agnostic keys are opt-in via the transition() DSL (see
+    // inTransitionScope above). A route (and its route-owned layouts) inside a
+    // transition scope drops the param from its key, so navigating between two
+    // param values of the SAME route (e.g. /product/1 -> /product/2) reconciles
+    // the route subtree instead of remounting it. Combined with the
+    // startTransition wrap that shouldStartViewTransition already applies to
+    // transition routes (browser/partial-update.ts), the previous content stays
+    // on screen while the new loaders resolve (stale-while-revalidate) instead
+    // of flashing the loading skeleton. This works on stable React; experimental
+    // React adds the animated <ViewTransition> cross-fade on top.
+    //
+    // Outside a transition scope the key stays param-bearing and the route
+    // remounts on param change (the default: a fresh skeleton and fresh
+    // component state).
+    //
+    // error/notFound always keep param-bearing keys: createErrorSegment reuses
+    // the boundary layout's shortCode as the error segment id (router/
+    // error-handling.ts), so a param-agnostic error key could collide with that
+    // layout's key within the same render.
     const includeParams =
-      node.segment.type === "route" ||
       node.segment.type === "error" ||
       node.segment.type === "notFound" ||
-      (node.segment.type === "layout" && node.segment.belongsToRoute);
+      ((node.segment.type === "route" ||
+        (node.segment.type === "layout" && node.segment.belongsToRoute)) &&
+        !inTransitionScope);
 
     const paramStr =
       includeParams && params && Object.keys(params).length > 0
@@ -283,31 +305,25 @@ export async function renderSegments(
             .map(([k, v]) => `${k}=${v}`)
             .join(",")
         : "";
-    const key = `${paramStr ? `${id}-${paramStr}` : id}`;
+    const key = paramStr ? `${id}-${paramStr}` : id;
 
-    // Get loader entries for this node
     const loaderEntries = node.loaders.filter(
       (loader) => loader.loaderId && loader.loaderData !== undefined,
     );
 
-    // Determine the component content (with or without Suspense wrapper)
-    // Wrap when loading skeleton defined OR component is Promise (needs Suspense)
-    // During actions, await component Promise to prevent Suspense from triggering
-    // This keeps existing content visible instead of showing loading skeleton
     let resolvedComponent = component;
     if (isAction && component instanceof Promise) {
       resolvedComponent = await component;
     }
 
-    let nodeContent: ReactNode =
-      loading !== null && loading !== undefined && loading !== false
-        ? createElement(RouteContentWrapper, {
-            key: `suspense-loading-${id}`,
-            content: getMemoizedContentPromise(resolvedComponent),
-            fallback: loading,
-            segmentId: id,
-          })
-        : registerLazyRef(resolvedComponent);
+    let nodeContent: ReactNode = isRenderableLoading(loading)
+      ? createElement(RouteContentWrapper, {
+          key: `suspense-loading-${id}`,
+          content: getMemoizedContentPromise(resolvedComponent),
+          fallback: loading,
+          segmentId: id,
+        })
+      : registerLazyRef(resolvedComponent);
 
     // Wrap with <ViewTransition> if transition config exists (React experimental only).
     // An empty config ({}) creates a bare <ViewTransition> boundary that participates
@@ -322,12 +338,25 @@ export async function renderSegments(
     // subtree update on the layout-level VT — which would otherwise make
     // React's commit walker fire `document.startViewTransition` and apply
     // view-transition-names to the underlying main subtree (cover/title/etc.).
+    //
+    // `transition.viewTransition === false` opts out of the router-owned
+    // boundary only. Driving (the startTransition wrap in browser/partial-update.ts
+    // and the param-agnostic key/hold below) keys off transition *presence*, not
+    // this flag, so a boundary-less transition still holds content and lets
+    // consumer-placed <ViewTransition> elements animate. The global
+    // createRouter({ viewTransition }) default is resolved into this field
+    // during segment resolution (only `false` is stamped; unset/"auto" is left
+    // as-is and means "wrap"), so this gate needs no router-option threading.
     let outletContent: ReactNode =
       node.segment.type === "layout" ? content : null;
 
     const transition = node.segment.transition;
 
-    if (ReactViewTransition && transition) {
+    if (
+      ReactViewTransition &&
+      transition &&
+      transition.viewTransition !== false
+    ) {
       if (node.segment.type === "layout") {
         outletContent = wrapDefaultOutletContent(outletContent, transition);
       } else {
@@ -337,13 +366,9 @@ export async function renderSegments(
 
     // Prepare loader data if there are loaders
     const loaderIds = loaderEntries.map((loader) => loader.loaderId!);
-    const loaderDataPromise = getMemoizedLoaderPromise(loaderEntries);
 
-    // Use LoaderBoundary when loading is defined to maintain consistent tree structure
-    // This ensures cached segments (which may not have loader segments) have the same
-    // tree structure as fresh segments, preventing React remounts
-    // If forceAwait or isAction is set, pre-resolve promises so LoaderBoundary won't suspend
     if (loading !== undefined && loading !== null) {
+      const loaderDataPromise = getMemoizedLoaderPromise(loaderEntries);
       content = createElement(LoaderBoundary, {
         key: `loader-boundary-${key}`,
         loaderDataPromise:
@@ -357,7 +382,6 @@ export async function renderSegments(
         children: nodeContent,
       });
     } else if (loaderEntries.length === 0) {
-      // No loaders, no loading - simple OutletProvider
       content = createElement(OutletProvider, {
         key,
         content: outletContent,
@@ -366,34 +390,18 @@ export async function renderSegments(
         children: nodeContent,
       });
     } else {
-      // Has loaders but no loading skeleton.
-      // Split: parallel-owned loaders stream (their parallel has loading()),
-      // layout-owned loaders are awaited (they gate the layout content).
       const layoutLoaders = loaderEntries.filter((l) => !l.parallelLoading);
       const parallelOwnedLoaders = loaderEntries.filter(
         (l) => !!l.parallelLoading,
       );
 
-      // Await only layout-owned loaders
       const layoutLoaderIds = layoutLoaders.map((l) => l.loaderId!);
-      const layoutLoaderDataPromise =
-        layoutLoaders.length > 0
-          ? Promise.all(
-              layoutLoaders.map((l) =>
-                l.loaderData instanceof Promise
-                  ? l.loaderData
-                  : Promise.resolve(l.loaderData),
-              ),
-            )
-          : Promise.resolve([]);
-      const resolvedData = await layoutLoaderDataPromise;
-      const { loaderData, errorFallback } = resolveLoaderData(
+      const resolvedData = await buildLoaderPromise(layoutLoaders);
+      const { loaderData, errorFallback } = decodeLoaderResults(
         resolvedData,
         layoutLoaderIds,
       );
 
-      // Parallel-owned loaders: attach to their owning parallel segment
-      // as loaderDataPromise so ParallelOutlet wraps in LoaderBoundary
       if (parallelOwnedLoaders.length > 0) {
         const loadersByParallelNamespace = new Map<string, ResolvedSegment[]>();
 
@@ -450,8 +458,6 @@ export async function renderSegments(
     }
   }
 
-  // Always wrap with root error boundary to prevent white screens
-  // This catches any unhandled errors that bubble up from the segment tree
   const errorBoundaryWrapped = createElement(RootErrorBoundary, {
     children: content,
   });
@@ -459,11 +465,8 @@ export async function renderSegments(
     await Promise.allSettled(temporalLazyRefs);
   }
 
-  // Build the final result, optionally wrapped with root layout
   let result: ReactNode = errorBoundaryWrapped;
 
-  // If rootLayout is provided, wrap the error boundary with it
-  // This ensures the app shell stays mounted even during errors (prevents FOUC)
   if (RootLayout) {
     result = createElement(RootLayout, {
       children: errorBoundaryWrapped,
@@ -501,6 +504,31 @@ export async function renderSegments(
  * @param segments - Main segments from the route tree
  * @param interceptSegments - Optional intercept segments to inject
  */
+// Loader segment ids have the grammar `${parentId}D${index}.${loaderId}`.
+// parentId is the parent shortCode (M/L/P/R/C + digits, never "D") for normal
+// loaders, or `${shortCode}.${slotName}` for intercept-slot loaders, where the
+// slot name is user-controlled (`@${string}`) and may contain an uppercase "D"
+// (e.g. "@Detail"). Strip from the first `D<index>.` separator so the slot name
+// is preserved; splitting on a bare "D" mis-cut "@Detail" to "@" and silently
+// dropped the loader's data. The first-`D<index>.` strip is only correct because
+// slot names cannot contain "." -- assertValidSlotName (route-definition/
+// dsl-helpers.ts) rejects a "." at definition time, so a name like "@D3.foo"
+// (which WOULD mis-cut here) can never reach this function.
+function loaderParentId(loaderSegmentId: string): string {
+  return loaderSegmentId.replace(/D\d+\..*$/, "");
+}
+
+// Append a value to the array stored under `key`, creating the array on first
+// use. Single Map lookup (vs the has/get!().push double-lookup idiom).
+function pushToGroup<K, V>(map: Map<K, V[]>, key: K, value: V): void {
+  const arr = map.get(key);
+  if (arr) {
+    arr.push(value);
+  } else {
+    map.set(key, [value]);
+  }
+}
+
 function* segmentTreeWalk(
   segments: ResolvedSegment[],
   interceptSegments?: ResolvedSegment[],
@@ -521,19 +549,12 @@ function* segmentTreeWalk(
       // Extract parent ID from parallel ID
       // Example: "L0R1L0.@sidebar" → "L0R1L0"
       const parentId = segment.id.split(".")[0];
-      if (!parallelsByParent.has(parentId)) {
-        parallelsByParent.set(parentId, []);
-      }
-      parallelsByParent.get(parentId)!.push(segment);
+      pushToGroup(parallelsByParent, parentId, segment);
     } else if (segment.type === "loader") {
       // Extract parent ID from loader ID
-      // Example: "L0D0.cart" → "L0"
-      // Loader ID format: {parentShortCode}D{index}.{loaderId}
-      const parentId = segment.id.split("D")[0];
-      if (!loadersByParent.has(parentId)) {
-        loadersByParent.set(parentId, []);
-      }
-      loadersByParent.get(parentId)!.push(segment);
+      // Example: "L0D0.cart" → "L0"; "L0.@DetailD0.x" → "L0.@Detail"
+      const parentId = loaderParentId(segment.id);
+      pushToGroup(loadersByParent, parentId, segment);
     } else {
       // Layout, route, error, and notFound segments are all rendered in the tree
       // Error/notFound segments replace the failed segment with fallback UI
@@ -548,17 +569,11 @@ function* segmentTreeWalk(
       if (intercept.type === "parallel" && intercept.slot) {
         // Extract parent ID from intercept ID (e.g., "M4L0L0L2.@modal" → "M4L0L0L2")
         const parentId = intercept.id.split(".")[0];
-        if (!parallelsByParent.has(parentId)) {
-          parallelsByParent.set(parentId, []);
-        }
-        parallelsByParent.get(parentId)!.push(intercept);
+        pushToGroup(parallelsByParent, parentId, intercept);
       } else if (intercept.type === "loader") {
-        // Intercept loaders - extract parent from loader ID
-        const parentId = intercept.id.split("D")[0];
-        if (!loadersByParent.has(parentId)) {
-          loadersByParent.set(parentId, []);
-        }
-        loadersByParent.get(parentId)!.push(intercept);
+        // Intercept loaders - extract parent from loader ID (slot name preserved)
+        const parentId = loaderParentId(intercept.id);
+        pushToGroup(loadersByParent, parentId, intercept);
       }
     }
   }