@rangojs/router 0.0.0-experimental.ea6d5eec → 0.0.0-experimental.ea9f40f2

package/src/types/request-scope.ts

@@ -0,0 +1,112 @@
+import type { DefaultEnv } from "./global-namespace.js";
+
+/**
+ * Minimal subset of Cloudflare Workers' ExecutionContext that the router
+ * uses. Defined locally so the package does not depend on
+ * `@cloudflare/workers-types`. Consumers that want the full type can cast.
+ *
+ * On non-Cloudflare runtimes (Node, dev server, tests), this is undefined
+ * — portable apps should prefer `ctx.waitUntil(...)`, which degrades
+ * gracefully. `ctx.executionContext` is the escape hatch for libraries
+ * (MCP, Durable Object routing, etc.) that type their arguments as the
+ * raw ExecutionContext.
+ */
+export interface ExecutionContext {
+  waitUntil(promise: Promise<any>): void;
+  passThroughOnException(): void;
+}
+
+/**
+ * Fallback `waitUntil` body used when no Cloudflare `ExecutionContext`
+ * is available (Node, dev, tests). Runs the work fire-and-forget and
+ * logs errors so they don't silently swallow.
+ *
+ * Exported so every `waitUntil` call site degrades identically instead
+ * of inventing its own fallback policy.
+ */
+export function fireAndForgetWaitUntil(fn: () => Promise<void>): void {
+  // Defer fn() invocation to a microtask so a SYNCHRONOUS throw in a non-async
+  // callback (e.g. `() => { somethingThatThrows(); return p; }`) becomes a
+  // rejected promise we catch here, not an exception that escapes into the
+  // request flow. waitUntil is fire-and-forget: a background-task failure must
+  // never break the response.
+  Promise.resolve()
+    .then(fn)
+    .catch((err) => console.error("[waitUntil] Background task failed:", err));
+}
+
+/**
+ * Fields present on every user-facing request context.
+ *
+ * @template TEnv - Platform bindings type (Cloudflare env, etc.).
+ */
+export interface RequestScope<TEnv = DefaultEnv> {
+  /**
+   * The original incoming Request object (transport URL intact).
+   * Use `url` / `searchParams` for application logic — those have
+   * internal `_rsc*` params stripped. `request` preserves the raw URL
+   * when you need original headers, method, or body.
+   */
+  request: Request;
+
+  /**
+   * The request URL with internal `_rsc*` transport params stripped.
+   * Use this for routing, link generation, and display.
+   */
+  url: URL;
+
+  /**
+   * The original request URL with all parameters intact, including
+   * internal `_rsc*` transport params. Use `url` for application logic
+   * — this is only needed for advanced cases like debugging or custom
+   * cache keying.
+   */
+  originalUrl: URL;
+
+  /** URL pathname (same as `url.pathname`). */
+  pathname: string;
+
+  /**
+   * Query parameters from the URL (system params like `_rsc*` are
+   * filtered). Always a standard `URLSearchParams` instance.
+   */
+  searchParams: URLSearchParams;
+
+  /**
+   * Platform bindings (DB, KV, secrets, etc.). On Cloudflare Workers
+   * these are the `env` object passed to the Worker's `fetch()` handler.
+   */
+  env: TEnv;
+
+  /**
+   * Schedule work to run after the response is sent.
+   * On Cloudflare Workers, delegates to `executionContext.waitUntil()`.
+   * On Node / dev / tests, runs as fire-and-forget with error logging.
+   *
+   * @example
+   * ```typescript
+   * ctx.waitUntil(async () => {
+   *   await cacheStore.set(key, data, ttl);
+   * });
+   * ```
+   */
+  waitUntil(fn: () => Promise<void>): void;
+
+  /**
+   * Raw Cloudflare Workers `ExecutionContext`, when running on a
+   * Cloudflare-compatible runtime. Undefined elsewhere.
+   *
+   * Escape hatch for libraries that type their arguments as
+   * `ExecutionContext` (MCP `fetch`, `routeAgentRequest`, etc.).
+   * For the common "do work after the response" case, prefer
+   * `ctx.waitUntil(...)` — it is platform-neutral.
+   *
+   * @example
+   * ```typescript
+   * path.any("/mcp", (ctx) =>
+   *   emailMcp.fetch(ctx.request, ctx.env, ctx.executionContext!),
+   * );
+   * ```
+   */
+  executionContext?: ExecutionContext;
+}

package/src/types/route-config.ts

@@ -7,47 +7,33 @@ export type DocumentProps = {
   children: ReactNode;
 };
 
-/**
- * Parse constraint values into a union type
- * "a|b|c" -> "a" | "b" | "c"
- */
 type ParseConstraint<T extends string> =
   T extends `${infer First}|${infer Rest}` ? First | ParseConstraint<Rest> : T;
 
-/**
- * Extract param info from a param segment
- *
- * Handles:
- * - :param -> { name: "param", optional: false, type: string }
- * - :param? -> { name: "param", optional: true, type: string }
- * - :param(a|b) -> { name: "param", optional: false, type: "a" | "b" }
- * - :param(a|b)? -> { name: "param", optional: true, type: "a" | "b" }
- */
+// Named catch-all (`:name*` / `:name+`) is matched BEFORE the `?`/suffix
+// branches. Its modifier is anchored to the END of the token (no trailing
+// `${string}`) so it is a true suffix and never mis-splits a constraint body
+// such as `id(\d+)`. Both are a required `string`: a matched catch-all always
+// binds a value (possibly ""), so the key is always present.
 type ExtractParamInfo<T extends string> =
-  // Optional + constrained (with optional suffix): :param(a|b)?suffix
   T extends `${infer Name}(${infer Constraint})?${string}`
     ? { name: Name; optional: true; type: ParseConstraint<Constraint> }
-    : // Constrained (with optional suffix): :param(a|b)suffix
-      T extends `${infer Name}(${infer Constraint})${string}`
+    : T extends `${infer Name}(${infer Constraint})${string}`
       ? { name: Name; optional: false; type: ParseConstraint<Constraint> }
-      : // Optional (with optional suffix): :param?suffix
-        T extends `${infer Name}?${string}`
-        ? { name: Name; optional: true; type: string }
-        : // Param with dot-suffix: :param.html
-          T extends `${infer Name}.${string}`
+      : T extends `${infer Name}*`
+        ? { name: Name; optional: false; type: string }
+        : T extends `${infer Name}+`
           ? { name: Name; optional: false; type: string }
-          : // Param with dash-suffix: :param-slug
-            T extends `${infer Name}-${string}`
-            ? { name: Name; optional: false; type: string }
-            : // Param with tilde-suffix: :param~v2
-              T extends `${infer Name}~${string}`
+          : T extends `${infer Name}?${string}`
+            ? { name: Name; optional: true; type: string }
+            : T extends `${infer Name}.${string}`
               ? { name: Name; optional: false; type: string }
-              : // Required: :param (no suffix)
-                { name: T; optional: false; type: string };
+              : T extends `${infer Name}-${string}`
+                ? { name: Name; optional: false; type: string }
+                : T extends `${infer Name}~${string}`
+                  ? { name: Name; optional: false; type: string }
+                  : { name: T; optional: false; type: string };
 
-/**
- * Build param object from info
- */
 type ParamFromInfo<Info> = Info extends {
   name: infer N extends string;
   optional: true;
@@ -62,10 +48,6 @@ type ParamFromInfo<Info> = Info extends {
     ? { [K in N]: V }
     : never;
 
-/**
- * Merge two param objects preserving optionality
- * Uses Pick to preserve the modifiers from source types
- */
 type MergeParams<A, B> = Pick<A, keyof A> & Pick<B, keyof B> extends infer O
   ? { [K in keyof O]: O[K] }
   : never;
@@ -78,12 +60,15 @@ type MergeParams<A, B> = Pick<A, keyof A> & Pick<B, keyof B> extends infer O
  * - Optional params: /:locale? -> { locale?: string }
  * - Constrained params: /:locale(en|gb) -> { locale: "en" | "gb" }
  * - Optional + constrained: /:locale(en|gb)? -> { locale?: "en" | "gb" }
+ * - Named catch-all: /:path+ (one-or-more), /:slug* (zero-or-more) -> string
  *
  * @example
  * ExtractParams<"/products/:id"> // { id: string }
  * ExtractParams<"/:locale?/blog/:slug"> // { locale?: string; slug: string }
  * ExtractParams<"/:locale(en|gb)/blog"> // { locale: "en" | "gb" }
  * ExtractParams<"/:locale(en|gb)?/blog/:slug"> // { locale?: "en" | "gb"; slug: string }
+ * ExtractParams<"/docs/:slug*"> // { slug: string }
+ * ExtractParams<"/shop/:path+"> // { path: string }
  */
 export type ExtractParams<
   T extends string,
@@ -109,17 +94,11 @@ export type ExtractParams<
  */
 export type TrailingSlashMode = "never" | "always" | "ignore";
 
-/**
- * Route configuration object (alternative to string path)
- */
 export type RouteConfig = {
   path: string;
   trailingSlash?: TrailingSlashMode;
 };
 
-/**
- * Route definition options (global defaults)
- */
 export type RouteDefinitionOptions = {
   trailingSlash?: TrailingSlashMode;
 };
@@ -128,11 +107,6 @@ export type RouteDefinition = {
   [key: string]: string | RouteConfig | RouteDefinition;
 };
 
-/**
- * Recursively flatten nested routes with depth limit to prevent infinite recursion
- * Transforms: { products: { detail: "/product/:slug" } } => { "products.detail": "/product/:slug" }
- * Also handles RouteConfig objects: { api: { path: "/api" } } => { "api": "/api" }
- */
 type FlattenRoutes<
   T extends RouteDefinition,
   Prefix extends string = "",
@@ -153,18 +127,12 @@ type FlattenRoutes<
             : never;
     }[keyof T];
 
-/**
- * Union to intersection helper
- */
 type UnionToIntersection<U> = (
   U extends unknown ? (k: U) => void : never
 ) extends (k: infer I) => void
   ? I
   : never;
 
-/**
- * Resolved route map - flattened route definitions with full paths
- */
 export type ResolvedRouteMap<T extends RouteDefinition> = UnionToIntersection<
   FlattenRoutes<T>
 >;

package/src/types/route-entry.ts

@@ -1,22 +1,27 @@
 import type { AllUseItems } from "../route-types.js";
 import type { TrailingSlashMode, ResolvedRouteMap } from "./route-config.js";
 
-/**
- * Context captured for lazy include evaluation
- */
 export interface LazyIncludeContext {
   urlPrefix: string;
   namePrefix: string | undefined;
   parent: unknown; // EntryData - avoid circular import
+  /** Counter snapshot from pattern extraction for consistent shortCode indices */
+  counters?: Record<string, number>;
   cacheProfiles?: Record<
     string,
     import("../cache/profile-registry.js").CacheProfile
   >;
+  /** Root scope flag for dot-local reverse resolution */
+  rootScoped?: boolean;
+  /**
+   * Positional include scope token composed from the parent scope plus this
+   * include's sibling index (`${parentScope}I${idx}`). Applied to direct-
+   * descendant shortCodes during lazy evaluation so routes inside the
+   * include cannot collide with siblings declared outside it.
+   */
+  includeScope?: string;
 }
 
-/**
- * Internal route entry stored in router
- */
 export interface RouteEntry<TEnv = any> {
   prefix: string;
   /**
@@ -69,7 +74,7 @@ export interface RouteEntry<TEnv = any> {
   prerenderRouteKeys?: Set<string>;
 
   /**
-   * Route keys in this entry that use `{ passthrough: true }`.
+   * Route keys in this entry that are wrapped with `Passthrough()`.
    * Used by the non-trie match path to set the `pt` flag.
    */
   passthroughRouteKeys?: Set<string>;

package/src/types/segments.ts

@@ -1,5 +1,6 @@
 import type { ReactNode } from "react";
 import type { ErrorInfo, NotFoundInfo } from "./boundaries.js";
+import type { RevalidateParams, HandlerContext } from "./handler-context.js";
 
 /**
  * CSS class(es) for a ViewTransition phase.
@@ -8,9 +9,102 @@ import type { ErrorInfo, NotFoundInfo } from "./boundaries.js";
  */
 export type ViewTransitionClass = Record<string, string> | string;
 
+/**
+ * The context a transition({ when }) predicate receives.
+ *
+ * It mirrors the {@link ShouldRevalidateFn} args a `revalidate()` predicate
+ * gets — the same navigation/action metadata — so the two read the same shape,
+ * plus `get`/`env` for post-handler reads. There is no full `HandlerContext`
+ * here: the gate runs at the RSC-payload layer with the request context, not a
+ * handler context, so handler-only sugar (`search`/`build`/`dev`/`headers`) is
+ * absent by design. `get` is the way to read what the handler/middleware set
+ * via `ctx.set(...)` this request.
+ *
+ * Field availability (all source fields are optional — never fabricated):
+ * - `currentUrl` / `currentParams` / `fromRouteName` (the navigation SOURCE) are
+ *   populated on soft navigations and action-success revalidations. They are
+ *   undefined on an initial full document load and on action-error / no-JS error
+ *   paths that skip the navigation snapshot — there is no prior page to name.
+ * - `nextUrl` / `nextParams` / `get` / `env` / `method` are always present;
+ *   `toRouteName` is present only when the target route is named (undefined for
+ *   unnamed/auto-generated routes, like `fromRouteName`).
+ * - `actionId` / `actionUrl` / `actionResult` / `formData` are populated only
+ *   when a server action triggered the render; `method` is "POST" then, "GET"
+ *   otherwise. On no-JS (progressive-enhancement) action paths `actionId` may be
+ *   undefined when React cannot surface the action's stable id: the success
+ *   re-render still sets `actionUrl`/`formData` for a recognized action, but the
+ *   error-boundary re-render exposes `actionUrl` only when `actionId` resolved.
+ *   Malformed form bodies that fail before action detection expose no action
+ *   fields. Treat `actionId` as "the action, if known", not as "was this an
+ *   action".
+ *
+ * PREFETCH / CACHE CAVEAT (read this before gating on the source): the gate runs
+ * server-side during resolution. A PREFETCHED navigation renders at prefetch
+ * time, so `currentUrl`/`currentParams`/`fromRouteName` reflect the page the
+ * prefetch fired from, NOT necessarily the page the user actually navigates from
+ * — the decision is baked into the stored Flight payload and replayed verbatim.
+ * A `cache()`/prerender hit replays the stored transition with the predicate NOT
+ * re-run at all. So a source-sensitive predicate can be frozen to prefetch-time
+ * or store-time state. This is accepted (~99% of navigations match), but if your
+ * gate must reflect the exact click-time source, source-scope the prefetch
+ * (`<Link prefetchKey=":source">`) and do not `cache()` that segment.
+ */
+export type TransitionWhenContext<
+  TParams = Record<string, string>,
+  TEnv = unknown,
+> = Partial<
+  Pick<
+    RevalidateParams<TParams, TEnv>,
+    "currentUrl" | "currentParams" | "fromRouteName"
+  >
+> &
+  Pick<
+    RevalidateParams<TParams, TEnv>,
+    | "nextUrl"
+    | "nextParams"
+    | "toRouteName"
+    | "actionId"
+    | "actionUrl"
+    | "actionResult"
+    | "formData"
+    | "method"
+  > &
+  Pick<HandlerContext<any, TEnv>, "get" | "env">;
+
+/**
+ * Predicate that gates whether a transition() applies for the current request.
+ *
+ * Evaluated server-side AFTER the route's handler runs (so `get(...)` can read
+ * handler/middleware-set state) and outside any cache scope. Return false to
+ * drop this segment's transition for the request; return true to apply it. The
+ * context ({@link TransitionWhenContext}) carries the same navigation/action
+ * metadata a `revalidate()` predicate sees plus `get`/`env`. If it throws, the
+ * error is reported to the router's onError (phase "rendering") and the
+ * transition is dropped (the navigation does not hold).
+ *
+ * Distinct from intercept()'s `when` config selector, which runs at MATCH time
+ * over `{ from, to, params, segments, … }`; a transition `when` runs
+ * post-handler over the resolved payload.
+ *
+ * Scope: dropping a transition removes only THIS segment's contribution to the
+ * navigation's hold. The startTransition hold is navigation-wide — it engages if
+ * any matched segment still has a transition — so `when: false` makes the
+ * navigation stream its loading fallback only when no other matched segment
+ * keeps a transition (the common case: a single transition on the route).
+ *
+ * Evaluated on every fresh (cache-miss) resolution; it is NOT re-run when a
+ * segment is replayed from the runtime cache or a build-time prerender, and a
+ * prefetched navigation freezes it to prefetch-time state — see the caveat on
+ * {@link TransitionWhenContext}.
+ */
+export type TransitionWhenFn = (ctx: TransitionWhenContext) => boolean;
+
 /**
  * Configuration for React's <ViewTransition> component.
- * Maps directly to ViewTransitionProps (minus children/ref/callbacks).
+ *
+ * The phase fields (enter/exit/update/share/default/name) map directly to
+ * ViewTransitionProps (minus children/ref/callbacks). The `viewTransition`
+ * field is router-specific and is stripped before the config reaches React.
  */
 export interface TransitionConfig {
   enter?: ViewTransitionClass;
@@ -19,19 +113,34 @@ export interface TransitionConfig {
   share?: ViewTransitionClass;
   default?: ViewTransitionClass;
   name?: string;
+  /**
+   * Whether the router wraps this segment's content in its own
+   * <ViewTransition> boundary.
+   *
+   * - "auto" (default): the router places the boundary, producing the
+   *   router-owned cross-fade described by the phase fields above.
+   * - false: the router places no boundary. The navigation commit is still
+   *   driven through startTransition (so loaders hold instead of flashing a
+   *   skeleton, and consumer-placed <ViewTransition> elements still animate),
+   *   but the router contributes no cross-fade of its own.
+   *
+   * When unset, inherits the createRouter({ viewTransition }) default.
+   */
+  viewTransition?: "auto" | false;
+  /**
+   * Optional server-side predicate that gates this transition per request. When
+   * present and it returns false (evaluated post-handler), the router drops this
+   * segment's transition for the request, so the navigation streams its loading
+   * fallback instead of holding. The predicate is server-only and never
+   * serialized to the client; only its resolved effect (transition kept or
+   * dropped) crosses. See {@link TransitionWhenFn}.
+   */
+  when?: TransitionWhenFn;
 }
 
 /**
  * Resolved segment with component
  *
- * Segment types:
- * - layout: Wraps child content via <Outlet />
- * - route: The leaf content for a URL
- * - parallel: Named slots rendered via <ParallelOutlet name="@slot" />
- * - loader: Data segment (no visual rendering, carries loaderData)
- * - error: Error fallback segment (replaces failed segment with error UI)
- * - notFound: Not found fallback segment (replaces segment when data not found)
- *
  * @internal This type is an implementation detail and may change without notice.
  */
 export interface ResolvedSegment {
@@ -50,7 +159,9 @@ export interface ResolvedSegment {
   parallelName?: string; // For parallels: the parallel group name (used to match with revalidations)
   // Loader-specific fields
   loaderId?: string; // For loaders: the loader $$id identifier
+  _inherited?: boolean; // For inherited loaders: dedup marker for buildMatchResult
   loaderData?: any; // For loaders: the resolved data from loader execution
+  parallelLoading?: ReactNode; // For parallel-owned loaders: the parallel's loading fallback
   // Intercept loader fields (for streaming loader data in parallel segments)
   loaderDataPromise?: Promise<any[]> | any[]; // Loader data promise or resolved array
   loaderIds?: string[]; // IDs ($$id) of loaders for this segment
@@ -60,13 +171,16 @@ export interface ResolvedSegment {
   notFoundInfo?: NotFoundInfo; // For notFound segments: the not found information
   // Mount path from include() scope, used for MountContext.Provider wrapping
   mountPath?: string;
+  /**
+   * @internal Server-side marker: true when the segment's handler actually ran
+   * this request (not skipped via the revalidate cache path). Used by
+   * match-result.ts to populate `MatchResult.resolvedIds` for client-side
+   * handle-bucket cleanup. Stripped from the wire payload before serialization
+   * — never reaches the client.
+   */
+  _handlerRan?: boolean;
 }
 
-/**
- * Segment metadata (without component)
- *
- * @internal This type is an implementation detail and may change without notice.
- */
 export interface SegmentMetadata {
   id: string;
   type: "layout" | "route" | "parallel" | "loader" | "error" | "notFound";
@@ -114,6 +228,15 @@ export interface MatchResult {
   segments: ResolvedSegment[];
   matched: string[];
   diff: string[];
+  /**
+   * Every segment id whose handler actually ran on the server this request,
+   * including ones with `component === null` that get filtered out of
+   * `segments`/`diff` to avoid wasted bytes. Drives the client's handle-
+   * cleanup pass — a slot that re-resolves and pushes nothing must clear
+   * its previous handle bucket, but `diff` doesn't carry it because the
+   * segment payload doesn't either. A superset of `diff`.
+   */
+  resolvedIds: string[];
   /**
    * Merged route params from all matched segments
    * Available for use by the handler after route matching