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

package/src/router/revalidation.ts

@@ -4,7 +4,7 @@
  * Evaluates whether segments should revalidate based on params, actions, and custom functions.
  */
 
-import type { ResolvedSegment, HandlerContext } from "../types";
+import type { ResolvedSegment, HandlerContext, ActionRef } from "../types";
 import type { ActionContext } from "./types";
 import {
   debugLog,
@@ -15,6 +15,47 @@ import type { RevalidationTraceEntry } from "./logging.js";
 import { _getRequestContext } from "../server/request-context.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
 
+/**
+ * Resolve a server-action reference's stable id, mirroring how the action
+ * boundary derives `actionContext.actionId` in `rsc/server-action.ts`
+ * (`$id ?? $$id`): the file-path `$id` set by the expose-action-id plugin in a
+ * production RSC build when present, otherwise React's `$$id`. Resolving both
+ * the incoming `actionId` and the reference with the same precedence makes
+ * `isAction()` form-agnostic across dev and production.
+ */
+function resolveActionRefId(ref: unknown): string | undefined {
+  if (ref == null) return undefined;
+  const r = ref as { $id?: unknown; $$id?: unknown };
+  if (typeof r.$id === "string") return r.$id;
+  if (typeof r.$$id === "string") return r.$$id;
+  return undefined;
+}
+
+/**
+ * Build the `isAction()` helper bound to the current action's id. Matches a
+ * single imported action reference, several (variadic), or any export of a
+ * namespace import (`import * as Mod`). Returns `false` when there is no action
+ * (plain navigation) or nothing matches.
+ */
+function makeIsAction(
+  currentActionId: string | undefined,
+): (...actions: ActionRef[]) => boolean {
+  return (...actions: ActionRef[]): boolean => {
+    if (!currentActionId) return false;
+    for (const action of actions) {
+      if (typeof action === "function") {
+        if (resolveActionRefId(action) === currentActionId) return true;
+      } else if (action && typeof action === "object") {
+        // Namespace import: match any export of the module.
+        for (const value of Object.values(action)) {
+          if (resolveActionRefId(value) === currentActionId) return true;
+        }
+      }
+    }
+    return false;
+  };
+}
+
 function paramsEqual(
   a: Record<string, string>,
   b: Record<string, string>,
@@ -59,6 +100,14 @@ interface EvaluateRevalidationOptions<TEnv> {
   stale?: boolean;
   /** Trace source hint for the revalidation trace */
   traceSource?: RevalidationTraceEntry["source"];
+  /**
+   * Override the segment-type-derived default. When set, the value is used as
+   * the seed `defaultShouldRevalidate` passed to user revalidate fns and the
+   * reason flows into the trace. Callers use this when client-knowledge
+   * (e.g. parallel slot not in clientSegmentIds) should dictate the seed
+   * instead of the params/method-based heuristic.
+   */
+  defaultOverride?: { value: boolean; reason: string };
 }
 
 /**
@@ -81,6 +130,7 @@ export async function evaluateRevalidation<TEnv>(
     actionContext,
     stale,
     traceSource,
+    defaultOverride,
   } = options;
   const nextParams = segment.params || {};
   const paramsChanged = !paramsEqual(nextParams, prevParams);
@@ -110,7 +160,12 @@ export async function evaluateRevalidation<TEnv>(
   let defaultShouldRevalidate: boolean;
   let defaultReason: string;
 
-  if (request.method === "POST") {
+  if (defaultOverride) {
+    // Caller injected the seed (e.g. parallel slot not in clientSegmentIds).
+    // Skip the type-derived heuristic — caller knows better in this context.
+    defaultShouldRevalidate = defaultOverride.value;
+    defaultReason = defaultOverride.reason;
+  } else if (request.method === "POST") {
     // Actions: revalidate segments that belong to the route, skip parent chain
     if (segment.type === "route") {
       // Route segment always revalidates on actions
@@ -226,6 +281,7 @@ export async function evaluateRevalidation<TEnv>(
       slotName: segment.slot,
       // Action context (only populated when triggered by server action)
       actionId: actionContext?.actionId,
+      isAction: makeIsAction(actionContext?.actionId),
       actionUrl: actionContext?.actionUrl,
       actionResult: actionContext?.actionResult,
       formData: actionContext?.formData,

package/src/router/router-interfaces.ts

@@ -2,7 +2,7 @@ import type { ComponentType, ReactNode } from "react";
 import type { SerializedManifest } from "../debug.js";
 import type { ReverseFunction } from "../reverse.js";
 import type { UrlPatterns } from "../urls.js";
-import type { UrlBuilder } from "../urls/pattern-types.js";
+import type { UrlBuilder, EnvCompatible } from "../urls/pattern-types.js";
 import type { EntryData } from "../server/context";
 import type { ErrorInfo, MatchResult } from "../types";
 import type { NonceProvider } from "../rsc/types.js";
@@ -13,7 +13,7 @@ import type {
 } from "../cache/types.js";
 import type { MiddlewareEntry, MiddlewareFn } from "./middleware.js";
 import { RSC_ROUTER_BRAND } from "./router-registry.js";
-import type { RSCRouterOptions, RootLayoutProps } from "./router-options.js";
+import type { RangoOptions, RootLayoutProps } from "./router-options.js";
 import type { DefaultVars } from "../types/global-namespace.js";
 import type { ResolvedTimeouts, OnTimeoutCallback } from "./timeout.js";
 
@@ -49,16 +49,16 @@ type MergeRoutesWithResponses<
 };
 
 /**
- * Public RSC Router interface — the user-facing API surface.
+ * Public Rango router interface — the user-facing API surface.
  *
  * Users interact with this type when building and using routers.
- * Internal framework code uses RSCRouterInternal (via toInternal()) to access
+ * Internal framework code uses RangoInternal (via toInternal()) to access
  * matching, build-time, and configuration members that are not part of the
  * public contract.
  *
  * TRoutes accumulates all registered route types through the builder chain.
  */
-export interface RSCRouter<
+export interface Rango<
   TEnv = any,
   TRoutes extends Record<string, unknown> = Record<string, string>,
 > {
@@ -89,16 +89,16 @@ export interface RSCRouter<
    * ])
    * ```
    */
-  routes<T extends UrlPatterns<TEnv, any>>(
-    patterns: T,
-  ): RSCRouter<
+  routes<T extends UrlPatterns<any, any, any>>(
+    patterns: T & EnvCompatible<T, TEnv>,
+  ): Rango<
     TEnv,
     TRoutes &
       (NonNullable<T["_routes"]> extends Record<string, unknown>
         ? MergeRoutesWithResponses<NonNullable<T["_routes"]>, T["_responses"]>
         : Record<string, string>)
   >;
-  routes(builder: UrlBuilder<TEnv>): RSCRouter<TEnv, TRoutes>;
+  routes(builder: UrlBuilder<TEnv>): Rango<TEnv, TRoutes>;
 
   /**
    * Add global middleware that runs on all routes
@@ -114,7 +114,7 @@ export interface RSCRouter<
   use(
     patternOrMiddleware: string | MiddlewareFn<TEnv>,
     middleware?: MiddlewareFn<TEnv>,
-  ): RSCRouter<TEnv, TRoutes>;
+  ): Rango<TEnv, TRoutes>;
 
   /**
    * Type-safe URL builder for registered routes
@@ -141,7 +141,7 @@ export interface RSCRouter<
    * type AppRoutes = typeof _router.routeMap;
    *
    * declare global {
-   *   namespace RSCRouter {
+   *   namespace Rango {
    *     interface RegisteredRoutes extends AppRoutes {}
    *   }
    * }
@@ -177,16 +177,16 @@ export interface RSCRouter<
 }
 
 /**
- * Internal RSC Router interface — the full framework-facing API.
+ * Internal Rango router interface — the full framework-facing API.
  *
  * This type includes all members used by the Vite plugin, RSC handler,
  * pre-rendering pipeline, and other framework internals. It is NOT exported
  * from the public package API.
  *
- * Use toInternal(router) to assert a public RSCRouter into this type
+ * Use toInternal(router) to assert a public Rango into this type
  * at the boundary where framework code receives a user-provided router.
  */
-export interface RSCRouterInternal<
+export interface RangoInternal<
   TEnv = any,
   TRoutes extends Record<string, unknown> = Record<string, string>,
 > {
@@ -206,18 +206,24 @@ export interface RSCRouterInternal<
   readonly basename: string | undefined;
 
   /**
-   * Register routes using URL patterns from urls() or a builder function
-   */
-  routes<T extends UrlPatterns<TEnv, any>>(
-    patterns: T,
-  ): RSCRouter<
+   * Register routes using URL patterns from urls() or a builder function.
+   *
+   * Env compatibility is checked by EnvCompatible: an env-agnostic urls() block
+   * (its env is `unknown` — e.g. a shared module, or an app that does not augment
+   * `Rango.Env`) attaches to any router, while a urls<TEnv>() block carrying a
+   * concrete env is accepted only when this router's `TEnv` satisfies it. So a
+   * `urls<{ DB }>()` cannot be mounted on a `createRouter<{}>()`.
+   */
+  routes<T extends UrlPatterns<any, any, any>>(
+    patterns: T & EnvCompatible<T, TEnv>,
+  ): Rango<
     TEnv,
     TRoutes &
       (NonNullable<T["_routes"]> extends Record<string, unknown>
         ? MergeRoutesWithResponses<NonNullable<T["_routes"]>, T["_responses"]>
         : Record<string, string>)
   >;
-  routes(builder: UrlBuilder<TEnv>): RSCRouter<TEnv, TRoutes>;
+  routes(builder: UrlBuilder<TEnv>): Rango<TEnv, TRoutes>;
 
   /**
    * Add global middleware that runs on all routes
@@ -225,7 +231,7 @@ export interface RSCRouterInternal<
   use(
     patternOrMiddleware: string | MiddlewareFn<TEnv>,
     middleware?: MiddlewareFn<TEnv>,
-  ): RSCRouter<TEnv, TRoutes>;
+  ): Rango<TEnv, TRoutes>;
 
   /**
    * Type-safe URL builder for registered routes
@@ -247,17 +253,17 @@ export interface RSCRouterInternal<
    * Error callback for monitoring/alerting
    * Called when errors occur in loaders, actions, or routes
    */
-  readonly onError?: RSCRouterOptions<TEnv>["onError"];
+  readonly onError?: RangoOptions<TEnv>["onError"];
 
   /**
    * Cache configuration
    */
-  readonly cache?: RSCRouterOptions<TEnv>["cache"];
+  readonly cache?: RangoOptions<TEnv>["cache"];
 
   /**
    * Not found component to render when no route matches
    */
-  readonly notFound?: RSCRouterOptions<TEnv>["notFound"];
+  readonly notFound?: RangoOptions<TEnv>["notFound"];
 
   /**
    * Resolved theme configuration (null if theme not enabled)
@@ -359,6 +365,17 @@ export interface RSCRouterInternal<
   /** @internal basename for runtime manifest generation */
   readonly __basename?: string;
 
+  /**
+   * @internal Router-level error/notFound fallbacks (`createRouter` options),
+   * exposed for the build-time clientChunks discovery so a `"use client"`
+   * default boundary is routed into the dedicated `app-fallback` chunk. Unlike
+   * the route-tree `errorBoundary()`/`notFoundBoundary()` helpers these never
+   * land in `EntryData`, so they are read directly off the router instance.
+   */
+  readonly __defaultErrorBoundary?: RangoOptions<TEnv>["defaultErrorBoundary"];
+  readonly __defaultNotFoundBoundary?: RangoOptions<TEnv>["defaultNotFoundBoundary"];
+  readonly __notFound?: RangoOptions<TEnv>["notFound"];
+
   match(
     request: Request,
     input?: RouterRequestInput<TEnv>,
@@ -469,16 +486,16 @@ export interface RSCRouterInternal<
 }
 
 /**
- * Assert a public RSCRouter into the internal type.
+ * Assert a public Rango into the internal type.
  *
  * Use this at the boundary where framework code receives a user-provided
  * router and needs access to internal members (match, config, build-time).
  * The cast is safe because createRouter() always produces an object that
- * satisfies RSCRouterInternal; the public type is just a narrower view.
+ * satisfies RangoInternal; the public type is just a narrower view.
  */
 export function toInternal<
   TEnv = any,
   TRoutes extends Record<string, unknown> = Record<string, string>,
->(router: RSCRouter<TEnv, TRoutes>): RSCRouterInternal<TEnv, TRoutes> {
-  return router as RSCRouterInternal<TEnv, TRoutes>;
+>(router: Rango<TEnv, TRoutes>): RangoInternal<TEnv, TRoutes> {
+  return router as RangoInternal<TEnv, TRoutes>;
 }

package/src/router/router-options.ts

@@ -73,7 +73,7 @@ export interface RootLayoutProps {
 /**
  * Router configuration options
  */
-export interface RSCRouterOptions<TEnv = any> {
+export interface RangoOptions<TEnv = any> {
   /**
    * Unique identifier for this router instance.
    * Used to namespace static output files and route maps.
@@ -357,6 +357,30 @@ export interface RSCRouterOptions<TEnv = any> {
    */
   theme?: import("../theme/types.js").ThemeConfig | true;
 
+  /**
+   * Default for whether the router wraps `transition()` segments in its own
+   * React `<ViewTransition>` boundary (experimental React only).
+   *
+   * - "auto" (default): every route/layout that opts in via `transition()`
+   *   gets a router-owned cross-fade.
+   * - false: the router never places its own boundary. Routes that use
+   *   `transition()` still drive navigation through startTransition (so loaders
+   *   hold instead of flashing a skeleton) and still let consumer-placed
+   *   `<ViewTransition>` elements animate — the router just contributes no
+   *   cross-fade of its own. This is the "router triggers, you place the
+   *   transitions" model.
+   *
+   * A per-segment `transition({ viewTransition })` overrides this default.
+   *
+   * @example
+   * ```typescript
+   * // App-wide: drive + hold, but never auto-wrap. Place <ViewTransition>
+   * // yourself in components where you want a morph.
+   * const router = createRouter<AppEnv>({ viewTransition: false });
+   * ```
+   */
+  viewTransition?: "auto" | false;
+
   /**
    * URL patterns to register with the router.
    *

package/src/router/router-registry.ts

@@ -1,4 +1,4 @@
-import type { RSCRouterInternal } from "./router-interfaces.js";
+import type { RangoInternal } from "./router-interfaces.js";
 
 /**
  * Brand marker for identifying router instances at build time.
@@ -12,10 +12,7 @@ export const RSC_ROUTER_BRAND = "__rsc_router__" as const;
  * Used by the Vite plugin at build time to discover routers and extract
  * manifests, prefix trees, and pre-render candidates.
  */
-export const RouterRegistry: Map<
-  string,
-  RSCRouterInternal<any, any>
-> = new Map();
+export const RouterRegistry: Map<string, RangoInternal<any, any>> = new Map();
 
 export let routerAutoId = 0;
 

package/src/router/segment-resolution/fresh.ts

@@ -28,11 +28,12 @@ import {
   resolveLayoutComponent,
   resolveWithErrorBoundary,
 } from "./helpers.js";
+import { applyViewTransitionDefault } from "./view-transition-default.js";
 import { getRouterContext } from "../router-context.js";
 import { resolveSink, safeEmit } from "../telemetry.js";
 import {
   track,
-  RSCRouterContext,
+  RangoContext,
   runInsideLoaderScope,
 } from "../../server/context.js";
 
@@ -224,7 +225,10 @@ export async function resolveSegment<TEnv>(
       index: 0,
       component,
       loading: entry.loading === false ? null : entry.loading,
-      transition: entry.transition,
+      transition: applyViewTransitionDefault(
+        entry.transition,
+        deps.viewTransitionDefault,
+      ),
       params,
       belongsToRoute: false,
       layoutName: entry.id,
@@ -359,7 +363,10 @@ export async function resolveSegment<TEnv>(
       index: 0,
       component: component ?? null,
       loading: entry.loading === false ? null : entry.loading,
-      transition: entry.transition,
+      transition: applyViewTransitionDefault(
+        entry.transition,
+        deps.viewTransitionDefault,
+      ),
       params,
       belongsToRoute: true,
       ...(entry.mountPath ? { mountPath: entry.mountPath } : {}),
@@ -419,6 +426,10 @@ export async function resolveOrphanLayout<TEnv>(
         deps,
         orphan.shortCode,
       );
+      // Tag as inherited so buildMatchResult can deduplicate when safe
+      for (const s of inheritedLoaders) {
+        s._inherited = true;
+      }
       segments.push(...inheritedLoaders);
     }
   }
@@ -439,7 +450,10 @@ export async function resolveOrphanLayout<TEnv>(
     belongsToRoute,
     layoutName: orphan.id,
     loading: orphan.loading === false ? null : orphan.loading,
-    transition: orphan.transition,
+    transition: applyViewTransitionDefault(
+      orphan.transition,
+      deps.viewTransitionDefault,
+    ),
     ...(orphan.mountPath ? { mountPath: orphan.mountPath } : {}),
   });
 
@@ -511,6 +525,14 @@ export async function resolveParallelEntry<TEnv>(
       if (handler === undefined) {
         continue;
       }
+      // Pin `_currentSegmentId` to the slot's own id so handle pushes from
+      // inside the slot handler get their own bucket in the HandleStore.
+      // Parent-keying would collapse them into the parent layout's bucket;
+      // the partial-update merge then replaces the parent's bucket on a
+      // slot-only revalidation and drops layout-pushed Meta/Breadcrumbs.
+      // filterSegmentOrder() retains slot ids so the client preserves them.
+      (context as InternalHandlerContext<any, TEnv>)._currentSegmentId =
+        `${parentShortCode}.${slot}`;
       const doneParallelHandler = track(
         `handler:${parallelEntry.id}.${slot}`,
         2,
@@ -553,7 +575,10 @@ export async function resolveParallelEntry<TEnv>(
       index: 0,
       component,
       loading: parallelEntry.loading === false ? null : parallelEntry.loading,
-      transition: parallelEntry.transition,
+      transition: applyViewTransitionDefault(
+        parallelEntry.transition,
+        deps.viewTransitionDefault,
+      ),
       params,
       slot,
       belongsToRoute,
@@ -620,7 +645,7 @@ export async function resolveAllSegments<TEnv>(
     // can guard non-cacheable variable reads. Also guards response-level
     // side effects (headers.set). Persists for all descendant entries.
     if (entry.type === "cache") {
-      const store = RSCRouterContext.getStore();
+      const store = RangoContext.getStore();
       if (store) store.insideCacheScope = true;
     }
     const doneEntry = track(`segment:${entry.id}`, 1);
@@ -728,6 +753,7 @@ export async function resolveLoadersOnly<TEnv>(
         for (const seg of inherited) {
           if (!seenIds.has(seg.id)) {
             seenIds.add(seg.id);
+            seg._inherited = true;
             loaderSegments.push(seg);
           }
         }

package/src/router/segment-resolution/loader-cache.ts

@@ -28,9 +28,11 @@ import {
   resolveSwrWindow,
   resolveCacheKey,
   resolveCacheStore,
+  resolveTagsOption,
   DEFAULT_ROUTE_TTL,
 } from "../../cache/cache-policy.js";
 import { readThroughItem } from "../../cache/read-through-swr.js";
+import { recordRequestTags } from "../../cache/cache-tag.js";
 // Lazy-loaded to avoid pulling @vitejs/plugin-rsc/rsc into modules that
 // import segment-resolution but never use loader caching.
 let _serializeResult: typeof import("../../cache/segment-codec.js").serializeResult;
@@ -87,23 +89,8 @@ async function resolveLoaderKey(
  */
 function resolveTags(loaderEntry: LoaderEntry): string[] | undefined {
   const options = loaderEntry.cache?.options;
-  if (!options || !options.tags) return undefined;
-
-  if (typeof options.tags === "function") {
-    const requestCtx = getRequestContext();
-    if (!requestCtx) return undefined;
-    try {
-      return options.tags(requestCtx);
-    } catch (error) {
-      console.error(
-        `[LoaderCache] Tags function failed, caching without tags:`,
-        error,
-      );
-      return undefined;
-    }
-  }
-
-  return options.tags;
+  if (!options) return undefined;
+  return resolveTagsOption(options.tags, getRequestContext(), "LoaderCache");
 }
 
 function getLoaderStore(
@@ -152,6 +139,10 @@ export function resolveLoaderData<TEnv>(
   const swrWindow = resolveSwrWindow(options.swr, store.defaults);
   const swr = swrWindow || undefined;
   const tags = resolveTags(loaderEntry);
+  // Loader tags are config-derived, so they are the complete set whether this is
+  // a cache hit or miss; record them every time so a document built from this
+  // loader is tagged for invalidation.
+  recordRequestTags(tags);
 
   // Wrap ctx.use() so cache HIT primes the handler's memoization map.
   // ctx.use() closes over the match context's loaderPromises (not request context's).