@rangojs/router 0.0.0-experimental.fb4fdc18 → 0.0.0-experimental.fce7fbd1

package/src/rsc/rsc-rendering.ts

@@ -13,8 +13,9 @@ import {
 } from "../server/request-context.js";
 import { resolveLocationStateEntries } from "../browser/react/location-state-shared.js";
 import { appendMetric } from "../router/metrics.js";
-import { getSSRSetup } from "./ssr-setup.js";
+import { getSSRSetup, isRscRequest } from "./ssr-setup.js";
 import type { RscPayload } from "./types.js";
+import type { MatchResult } from "../types.js";
 import {
   createResponseWithMergedHeaders,
   createSimpleRedirectResponse,
@@ -35,6 +36,28 @@ export async function handleRscRendering<TEnv>(
   let payload: RscPayload;
   let hasInterceptSlots = false;
 
+  // Shared by the partial-fallback and full-render paths. The partial-success
+  // payload below is intentionally different (omits rootLayout/theme, adds slots).
+  const buildFullPayload = (m: MatchResult): RscPayload => ({
+    metadata: {
+      pathname: url.pathname,
+      routerId: ctx.router.id,
+      basename: ctx.router.basename,
+      segments: m.segments,
+      matched: m.matched,
+      diff: m.diff,
+      resolvedIds: m.resolvedIds,
+      params: m.params,
+      isPartial: false,
+      rootLayout: ctx.router.rootLayout,
+      handles: handleStore.stream(),
+      version: ctx.version,
+      prefetchCacheTTL: ctx.router.prefetchCacheTTL,
+      themeConfig: ctx.router.themeConfig,
+      initialTheme: reqCtx.theme,
+    },
+  });
+
   if (isPartial) {
     // Partial render (navigation)
     const result = await ctx.router.matchPartial(request, { env });
@@ -51,25 +74,7 @@ export async function handleRscRendering<TEnv>(
         return createSimpleRedirectResponse(match.redirect);
       }
 
-      payload = {
-        metadata: {
-          pathname: url.pathname,
-          routerId: ctx.router.id,
-          basename: ctx.router.basename,
-          segments: match.segments,
-          matched: match.matched,
-          diff: match.diff,
-          resolvedIds: match.resolvedIds,
-          params: match.params,
-          isPartial: false,
-          rootLayout: ctx.router.rootLayout,
-          handles: handleStore.stream(),
-          version: ctx.version,
-          prefetchCacheTTL: ctx.router.prefetchCacheTTL,
-          themeConfig: ctx.router.themeConfig,
-          initialTheme: reqCtx.theme,
-        },
-      };
+      payload = buildFullPayload(match);
     } else {
       setRequestContextParams(result.params, result.routeName);
 
@@ -135,28 +140,7 @@ export async function handleRscRendering<TEnv>(
         { headers: { "Content-Type": "application/json" } },
       );
     } else {
-      payload = {
-        // Initial SSR can reconstruct the tree from segments + rootLayout,
-        // so we omit root to avoid sending the same structure twice.
-
-        metadata: {
-          pathname: url.pathname,
-          routerId: ctx.router.id,
-          basename: ctx.router.basename,
-          segments: match.segments,
-          matched: match.matched,
-          diff: match.diff,
-          resolvedIds: match.resolvedIds,
-          params: match.params,
-          isPartial: false,
-          rootLayout: ctx.router.rootLayout,
-          handles: handleStore.stream(),
-          version: ctx.version,
-          prefetchCacheTTL: ctx.router.prefetchCacheTTL,
-          themeConfig: ctx.router.themeConfig,
-          initialTheme: reqCtx.theme,
-        },
-      };
+      payload = buildFullPayload(match);
     }
   }
 
@@ -190,17 +174,7 @@ export async function handleRscRendering<TEnv>(
     rscSerializeDur,
   );
 
-  // Determine if this is an RSC request or HTML request.
-  // Partial requests (_rsc_partial) are always RSC -- they come from client-side
-  // navigation or prefetch fetch(). We cannot rely on Accept alone since some
-  // browsers may send Accept: text/html for non-HTML requests.
-  const isRscRequest =
-    isPartial ||
-    (!request.headers.get("accept")?.includes("text/html") &&
-      !url.searchParams.has("__html")) ||
-    url.searchParams.has("__rsc");
-
-  if (isRscRequest) {
+  if (isRscRequest(request, url, isPartial)) {
     const renderDur = performance.now() - renderStart;
     appendMetric(metricsStore, "render:total", renderStart, renderDur);
     const rscHeaders: Record<string, string> = {

package/src/rsc/runtime-warnings.ts

@@ -8,6 +8,7 @@ import {
   createResponseWithMergedHeaders,
   carryOverRedirectHeaders,
 } from "./helpers.js";
+import { isRedirectResponse } from "../response-utils.js";
 
 // W3 -----------------------------------------------------------------------
 
@@ -18,16 +19,14 @@ import {
  */
 export function extractRedirectResponse(value: unknown): Response | null {
   if (!(value instanceof Response)) return null;
-  const location = value.headers.get("Location");
-  if (value.status >= 300 && value.status < 400 && location) {
-    const redirect = createResponseWithMergedHeaders(null, {
-      status: value.status,
-      headers: { Location: location },
-    });
-    carryOverRedirectHeaders(value, redirect);
-    return redirect;
-  }
-  return null;
+  if (!isRedirectResponse(value)) return null;
+  const location = value.headers.get("Location")!;
+  const redirect = createResponseWithMergedHeaders(null, {
+    status: value.status,
+    headers: { Location: location },
+  });
+  carryOverRedirectHeaders(value, redirect);
+  return redirect;
 }
 
 /**

package/src/rsc/server-action.ts

@@ -27,7 +27,7 @@ import {
   hasBodyContent,
   createResponseWithMergedHeaders,
   createSimpleRedirectResponse,
-  carryOverRedirectHeaders,
+  interceptRedirectForPartial,
 } from "./helpers.js";
 import type { HandlerContext } from "./handler-context.js";
 
@@ -111,49 +111,25 @@ export async function executeServerAction<TEnv>(
     loadedAction = await ctx.loadServerAction(actionId);
     const data = await loadedAction!.apply(null, args);
 
-    // Intercept redirect responses from actions. Without this, the redirect
-    // Response would be serialized as the action returnValue (which fails)
-    // and the revalidation step would run unnecessarily.
+    // Intercept redirect Responses: serializing one as the action returnValue
+    // would fail, and revalidation would run needlessly.
     if (data instanceof Response) {
-      const redirectUrl = data.headers.get("Location");
-      const isRedirect = data.status >= 300 && data.status < 400 && redirectUrl;
-      if (isRedirect) {
-        const locationState = getLocationState();
-        let redirect: Response;
-        if (locationState) {
-          redirect = ctx.createRedirectFlightResponse(
-            redirectUrl,
-            resolveLocationStateEntries(locationState),
-          );
-        } else {
-          redirect = createSimpleRedirectResponse(redirectUrl);
-        }
-        carryOverRedirectHeaders(data, redirect);
-        return redirect;
-      }
+      const intercepted = interceptRedirectForPartial(
+        data,
+        ctx.createRedirectFlightResponse,
+      );
+      if (intercepted) return intercepted;
     }
 
     returnValue = { ok: true, data };
   } catch (error) {
     // Handle thrown redirect (e.g., throw redirect('/path'))
     if (error instanceof Response) {
-      const redirectUrl = error.headers.get("Location");
-      const isRedirect =
-        error.status >= 300 && error.status < 400 && redirectUrl;
-      if (isRedirect) {
-        const locationState = getLocationState();
-        let redirect: Response;
-        if (locationState) {
-          redirect = ctx.createRedirectFlightResponse(
-            redirectUrl,
-            resolveLocationStateEntries(locationState),
-          );
-        } else {
-          redirect = createSimpleRedirectResponse(redirectUrl);
-        }
-        carryOverRedirectHeaders(error, redirect);
-        return redirect;
-      }
+      const intercepted = interceptRedirectForPartial(
+        error,
+        ctx.createRedirectFlightResponse,
+      );
+      if (intercepted) return intercepted;
 
       // Non-redirect Response thrown from action — this will be treated
       // as a regular error and routed to the error boundary. Warn in dev

package/src/rsc/ssr-setup.ts

@@ -126,3 +126,19 @@ export function mayNeedSSR(request: Request, url: URL): boolean {
 
   return true;
 }
+
+// Final render-time decision: is the response an RSC stream (vs HTML)? Distinct
+// from mayNeedSSR, which is a conservative pre-classifier (it treats a missing
+// Accept header as needing SSR; this treats it as RSC).
+export function isRscRequest(
+  request: Request,
+  url: URL,
+  isPartial: boolean,
+): boolean {
+  return (
+    isPartial ||
+    (!request.headers.get("accept")?.includes("text/html") &&
+      !url.searchParams.has("__html")) ||
+    url.searchParams.has("__rsc")
+  );
+}

package/src/rsc/types.ts

@@ -7,7 +7,7 @@
 
 import type { ResolvedSegment, SlotState } from "../types.js";
 import type { HandleData } from "../server/handle-store.js";
-import type { RSCRouterInternal } from "../router/router-interfaces.js";
+import type { RangoInternal } from "../router/router-interfaces.js";
 import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
 
 /**
@@ -185,7 +185,7 @@ export interface CreateRSCHandlerOptions<
   /**
    * The RSC router instance
    */
-  router: RSCRouterInternal<TEnv, TRoutes>;
+  router: RangoInternal<TEnv, TRoutes>;
 
   /**
    * RSC dependencies from @vitejs/plugin-rsc/rsc.

package/src/search-params.ts

@@ -81,11 +81,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.

package/src/segment-system.tsx

@@ -3,7 +3,7 @@ import { createElement, type ReactNode, type ComponentType } from "react";
 import { OutletProvider } from "./client.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,
@@ -59,42 +59,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
  */
@@ -131,6 +95,50 @@ export interface RenderSegmentsOptions {
   rootLayout?: ComponentType<RootLayoutProps>;
 }
 
+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, {
+    ...vtProps,
+    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
  *
@@ -211,6 +219,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) {
@@ -223,17 +250,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
@@ -274,35 +315,50 @@ export async function renderSegments(
     // <ViewTransition> components inside (with name/share props) morph independently
     // from the parent's default cross-fade.
     //
-    // When this commit is intercept-driven (modal opening into a parallel slot),
-    // override `update` to "none" so React's commit walker doesn't apply
-    // view-transition-names to the underlying main subtree — otherwise the cover/
-    // title/eyebrow get hoisted above the modal overlay. The wrapper element
-    // identity stays stable across commits, so the layout doesn't remount.
-    if (ReactViewTransition && node.segment.transition) {
-      const transitionConfig =
-        normalizedInterceptSegments && normalizedInterceptSegments.length > 0
-          ? { ...node.segment.transition, update: "none" }
-          : node.segment.transition;
-      nodeContent = createElement(ReactViewTransition, {
-        ...transitionConfig,
-        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.).
+    //
+    // `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 &&
+      transition.viewTransition !== false
+    ) {
+      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 = 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) {
+      // Aggregate built here only — the loaderless and no-loading branches don't
+      // read it (the latter builds its own per-parallel promises).
+      const loaderDataPromise = getMemoizedLoaderPromise(loaderEntries);
       content = createElement(LoaderBoundary, {
         key: `loader-boundary-${key}`,
         loaderDataPromise:
@@ -346,7 +402,7 @@ export async function renderSegments(
             )
           : Promise.resolve([]);
       const resolvedData = await layoutLoaderDataPromise;
-      const { loaderData, errorFallback } = resolveLoaderData(
+      const { loaderData, errorFallback } = decodeLoaderResults(
         resolvedData,
         layoutLoaderIds,
       );