@rangojs/router 0.0.0-experimental.debug-cache-fix → 0.0.0-experimental.df7974ff

package/src/segment-system.tsx

@@ -2,11 +2,7 @@ import * as React from "react";
 import { createElement, type ReactNode, type ComponentType } from "react";
 import { OutletProvider } from "./client.js";
 import { MountContextProvider } from "./browser/react/mount-context.js";
-import type {
-  ResolvedSegment,
-  LoaderDataResult,
-  RootLayoutProps,
-} from "./types.js";
+import type { ResolvedSegment, RootLayoutProps } from "./types.js";
 import { isLoaderDataResult } from "./types.js";
 import { invariant } from "./errors.js";
 import {
@@ -14,6 +10,8 @@ import {
   LoaderBoundary,
 } 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";
 
 // ViewTransition is only available in React experimental.
 // Access via namespace import to avoid compile-time errors on stable React.
@@ -61,20 +59,6 @@ function restoreParallelLoaderMarkers(
   return nextSegments ?? segments;
 }
 
-function hasSameReferences(a: unknown[] | undefined, b: unknown[]): boolean {
-  if (!a || a.length !== b.length) {
-    return false;
-  }
-
-  for (let i = 0; i < a.length; i++) {
-    if (a[i] !== b[i]) {
-      return false;
-    }
-  }
-
-  return true;
-}
-
 /**
  * Resolve loader data from raw results, unwrapping LoaderDataResult wrappers
  */
@@ -147,6 +131,47 @@ export interface RenderSegmentsOptions {
   rootLayout?: ComponentType<RootLayoutProps>;
 }
 
+function createViewTransitionBoundary(
+  transition: NonNullable<ResolvedSegment["transition"]>,
+  children: ReactNode,
+): ReactNode {
+  return createElement(ReactViewTransition, {
+    ...transition,
+    children,
+  });
+}
+
+function wrapDefaultOutletContent(
+  content: ReactNode,
+  transition: NonNullable<ResolvedSegment["transition"]>,
+): ReactNode {
+  if (!React.isValidElement(content)) {
+    return createViewTransitionBoundary(transition, content);
+  }
+
+  const props = content.props as any;
+
+  if (content.type === MountContextProvider) {
+    return React.cloneElement(content, {
+      children: wrapDefaultOutletContent(props.children, transition),
+    } as any);
+  }
+
+  if (content.type === OutletProvider && props.segment?.type === "layout") {
+    return React.cloneElement(content, {
+      content: wrapDefaultOutletContent(props.content, transition),
+    } as any);
+  }
+
+  if (content.type === LoaderBoundary && props.segment?.type === "layout") {
+    return React.cloneElement(content, {
+      outletContent: wrapDefaultOutletContent(props.outletContent, transition),
+    } as any);
+  }
+
+  return createViewTransitionBoundary(transition, content);
+}
+
 /**
  * Render segments into a React tree with proper layout nesting
  *
@@ -278,10 +303,7 @@ export async function renderSegments(
       loading !== null && loading !== undefined && loading !== false
         ? createElement(RouteContentWrapper, {
             key: `suspense-loading-${id}`,
-            content:
-              resolvedComponent instanceof Promise
-                ? resolvedComponent
-                : Promise.resolve(resolvedComponent),
+            content: getMemoizedContentPromise(resolvedComponent),
             fallback: loading,
             segmentId: id,
           })
@@ -292,29 +314,30 @@ export async function renderSegments(
     // in transitions without adding custom animation classes. Named element-level
     // <ViewTransition> components inside (with name/share props) morph independently
     // from the parent's default cross-fade.
-    if (ReactViewTransition && node.segment.transition) {
-      nodeContent = createElement(ReactViewTransition, {
-        ...node.segment.transition,
-        children: nodeContent,
-      });
-    }
-
-    // Common props for OutletProvider
-    const outletContent: ReactNode =
+    //
+    // For layouts, wrap the outlet content (what `<Outlet />` renders) rather
+    // than the layout component itself. Parallel slots like `<ParallelOutlet
+    // name="@modal" />` read from a separate context channel and end up as
+    // siblings of the VT in the rendered tree, so modal mounts don't trigger a
+    // 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.).
+    let outletContent: ReactNode =
       node.segment.type === "layout" ? content : null;
 
+    const transition = node.segment.transition;
+
+    if (ReactViewTransition && transition) {
+      if (node.segment.type === "layout") {
+        outletContent = wrapDefaultOutletContent(outletContent, transition);
+      } else {
+        nodeContent = createViewTransitionBoundary(transition, nodeContent);
+      }
+    }
+
     // Prepare loader data if there are loaders
     const loaderIds = loaderEntries.map((loader) => loader.loaderId!);
-    const loaderDataPromise =
-      loaderEntries.length > 0
-        ? Promise.all(
-            loaderEntries.map((loader) =>
-              loader.loaderData instanceof Promise
-                ? loader.loaderData
-                : Promise.resolve(loader.loaderData),
-            ),
-          )
-        : Promise.resolve([]);
+    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
@@ -396,34 +419,12 @@ export async function renderSegments(
             continue;
           }
 
-          const parallelLoaderIds = ownedLoaders.map((l) => l.loaderId!);
-          const parallelLoaderSources = ownedLoaders.map((l) => l.loaderData);
-          p.loaderIds = parallelLoaderIds;
-
-          const shouldReuseParallelPromise =
-            p.loaderDataPromise !== undefined &&
-            hasSameReferences(p.parallelLoaderSources, parallelLoaderSources);
-
-          const parallelLoaderDataPromise = shouldReuseParallelPromise
-            ? p.loaderDataPromise
-            : forceAwait || isAction
-              ? await Promise.all(
-                  ownedLoaders.map((l) =>
-                    l.loaderData instanceof Promise
-                      ? l.loaderData
-                      : Promise.resolve(l.loaderData),
-                  ),
-                )
-              : Promise.all(
-                  ownedLoaders.map((l) =>
-                    l.loaderData instanceof Promise
-                      ? l.loaderData
-                      : Promise.resolve(l.loaderData),
-                  ),
-                );
-
-          p.loaderDataPromise = parallelLoaderDataPromise;
-          p.parallelLoaderSources = parallelLoaderSources;
+          p.loaderIds = ownedLoaders.map((l) => l.loaderId!);
+          const aggregated = getMemoizedLoaderPromise(ownedLoaders);
+          p.loaderDataPromise =
+            (forceAwait || isAction) && aggregated instanceof Promise
+              ? await aggregated
+              : aggregated;
         }
       }
 

package/src/server/context.ts

@@ -191,8 +191,12 @@ export type EntryData =
       /** Original PrerenderHandlerDefinition (for build-time getParams access) */
       prerenderDef?: {
         getParams?: (ctx: any) => Promise<any[]> | any[];
-        options?: { passthrough?: boolean };
+        options?: { concurrency?: number };
       };
+      /** Set when route is wrapped with Passthrough() — has a separate live handler */
+      isPassthrough?: true;
+      /** Live handler for runtime fallback (only set on Passthrough routes) */
+      liveHandler?: Handler<any, any, any>;
       /** Set when handler is a Static definition (build-time only) */
       isStaticPrerender?: true;
       /** Static handler $$id for build-time store lookup */
@@ -273,6 +277,25 @@ interface HelperContext {
     string,
     import("../cache/profile-registry.js").CacheProfile
   >;
+  /** True when resolving handlers inside a cache() DSL boundary.
+   *  Read by ctx.get() to guard non-cacheable variable reads. */
+  insideCacheScope?: boolean;
+  /**
+   * Include scope string applied to direct-descendant shortCodes.
+   *
+   * Each `include(...)` call allocates a sibling-positional token like `I0`,
+   * `I1` from its parent's include counter and stores the composed scope
+   * (`${parentScope}I${idx}`) in its lazyContext. When the include's handler
+   * evaluates lazily, the store's `includeScope` is set from that context so
+   * every direct-descendant shortCode is generated as
+   * `${parent.shortCode}${includeScope}${prefix}${index}` — preventing
+   * collisions with siblings declared outside the include.
+   *
+   * The scope is NOT propagated through `store.run(...)`, so layouts /
+   * parallels / caches inside the include absorb the scope into their own
+   * shortCodes and their children start fresh.
+   */
+  includeScope?: string;
 }
 // Use a global symbol key so the AsyncLocalStorage instance survives HMR
 // module re-evaluation. Without this, Vite's RSC module runner may create
@@ -375,6 +398,8 @@ export const getContext = (): {
       const mountPrefix =
         store.mountIndex !== undefined ? `M${store.mountIndex}` : "";
 
+      const includeScope = store.includeScope ?? "";
+
       if (!parent) {
         // Root entry: prefix with mount index and use mount-scoped counter
         const counterKey = mountPrefix
@@ -385,12 +410,16 @@ export const getContext = (): {
         store.counters[counterKey] = index + 1;
         return `${mountPrefix}${prefix}${index}`;
       } else {
-        // Child entry: use parent-scoped counter (parent already has M prefix)
-        const counterKey = `${parent.shortCode}_${type}`;
+        // Child entry: use parent-scoped counter with includeScope appended.
+        // When we're evaluating a lazy include's direct children, includeScope
+        // is a per-include token like "I0" / "I1I0" that partitions the
+        // parent's counter namespace so routes inside one include cannot
+        // collide with siblings declared outside it.
+        const counterKey = `${parent.shortCode}${includeScope}_${type}`;
         store.counters[counterKey] ??= 0;
         const index = store.counters[counterKey];
         store.counters[counterKey] = index + 1;
-        return `${parent.shortCode}${prefix}${index}`;
+        return `${parent.shortCode}${includeScope}${prefix}${index}`;
       }
     },
     runWithStore: <T>(
@@ -417,6 +446,7 @@ export const getContext = (): {
           rootScoped: store.rootScoped,
           trackedIncludes: store.trackedIncludes,
           cacheProfiles: store.cacheProfiles,
+          includeScope: store.includeScope,
         },
         callback,
       );
@@ -666,3 +696,45 @@ export function track(label: string, depth?: number): () => void {
     });
   };
 }
+
+/**
+ * Separate ALS for tracking loader execution scope.
+ * Uses a dedicated ALS (not RSCRouterContext) to avoid issues with
+ * nested RSCRouterContext.run() calls in Vite's module runner.
+ */
+const LOADER_SCOPE_KEY = Symbol.for("rangojs-router:loader-scope");
+const loaderScopeALS: AsyncLocalStorage<{ active: true }> = ((
+  globalThis as any
+)[LOADER_SCOPE_KEY] ??= new AsyncLocalStorage<{ active: true }>());
+
+/**
+ * Check if the current execution is inside a cache() DSL boundary.
+ * Returns false inside loader execution — loaders are always fresh
+ * (never cached), so non-cacheable reads are safe.
+ */
+export function isInsideCacheScope(): boolean {
+  if (RSCRouterContext.getStore()?.insideCacheScope !== true) return false;
+  // Loaders are always fresh — even inside a cache() boundary, the loader
+  // function re-executes on every request. Skip the guard when running
+  // inside a loader.
+  if (loaderScopeALS.getStore()?.active) return false;
+  return true;
+}
+
+/**
+ * Check if the current execution is inside a DSL loader scope
+ * (wrapped by runInsideLoaderScope). Used by rendered() barrier
+ * to distinguish DSL loaders from handler-invoked loaders.
+ */
+export function isInsideLoaderScope(): boolean {
+  return loaderScopeALS.getStore()?.active === true;
+}
+
+/**
+ * Run `fn` inside a loader scope. While active, cache-scope guards
+ * are bypassed because loaders are always fresh (never cached) and
+ * their side effects (setCookie, header, etc.) are safe.
+ */
+export function runInsideLoaderScope<T>(fn: () => T): T {
+  return loaderScopeALS.run({ active: true }, fn);
+}

package/src/server/handle-store.ts

@@ -13,6 +13,25 @@
  */
 export type HandleData = Record<string, Record<string, unknown[]>>;
 
+/**
+ * Build a HandleData snapshot from a HandleStore using segment ordering.
+ * Reads data directly from the store for each segment in order.
+ */
+export function buildHandleSnapshot(
+  handleStore: HandleStore,
+  segmentOrder: string[],
+): HandleData {
+  const data: HandleData = {};
+  for (const segmentId of segmentOrder) {
+    const segData = handleStore.getDataForSegment(segmentId);
+    for (const handleName in segData) {
+      if (!data[handleName]) data[handleName] = {};
+      data[handleName][segmentId] = segData[handleName];
+    }
+  }
+  return data;
+}
+
 function createLateHandlePushError(
   handleName: string,
   segmentId: string,

package/src/server/loader-registry.ts

@@ -44,20 +44,21 @@ export function setLoaderImports(
 export async function getLoaderLazy(
   id: string,
 ): Promise<LoaderRegistryEntry | undefined> {
-  // Check if already cached in main registry
-  const existing = loaderRegistry.get(id);
-  if (existing) {
-    return existing;
-  }
-
-  // Check the fetchable loader registry (populated by createLoader)
+  // Always check fetchableLoaderRegistry first — it's the source of truth.
+  // createLoader() updates it during module re-evaluation (HMR), so checking
+  // here ensures we pick up the fresh function after a loader file change.
   const fetchable = getFetchableLoader(id);
   if (fetchable) {
-    // Cache in main registry for future requests
     loaderRegistry.set(id, fetchable);
     return fetchable;
   }
 
+  // Fall back to local cache (populated by previous lazy imports in production)
+  const existing = loaderRegistry.get(id);
+  if (existing) {
+    return existing;
+  }
+
   // Try to lazy load from the import map (production mode)
   if (lazyLoaderImports && lazyLoaderImports.size > 0) {
     const lazyImport = lazyLoaderImports.get(id);