@rangojs/router 0.0.0-experimental.259 → 0.0.0-experimental.26

package/skills/typesafety/SKILL.md

@@ -17,8 +17,7 @@ import { urlpatterns } from "./urls";
 
 const router = createRouter<AppBindings>({
   document: Document,
-  urls: urlpatterns,
-});
+}).routes(urlpatterns);
 
 // Server-side named-route reverse (type-safe via routeMap)
 export const reverse = router.reverse;
@@ -26,6 +25,39 @@ export const reverse = router.reverse;
 export default router;
 ```
 
+### Which global type should I use?
+
+Use the generated route map by default. Manual `RegisteredRoutes` augmentation
+is only needed when you want the richer `typeof router.routeMap` shape
+available globally.
+
+- `GeneratedRouteMap` — auto-registered by `router.named-routes.gen.ts`
+  Use for `Handler<"name">`, `Prerender<"name">`, server `ctx.reverse()`,
+  and named-route param/search inference.
+- `typeof router.routeMap` — the real merged route map from your router
+  instance, including response-route metadata such as `{ path, response }`.
+- `RegisteredRoutes` — manual global hook for exposing `typeof router.routeMap`
+  to utilities like `href()`, `ValidPaths`, and `PathResponse`.
+
+Recommended setup:
+
+```typescript
+// router.tsx
+import { createRouter } from "@rangojs/router";
+import { urlpatterns } from "./urls";
+import type { AppBindings, AppVars } from "./env";
+
+export const router = createRouter<AppBindings>({}).routes(urlpatterns);
+
+declare global {
+  namespace RSCRouter {
+    interface Env extends AppBindings {}
+    interface Vars extends AppVars {}
+    interface RegisteredRoutes extends typeof router.routeMap {}
+  }
+}
+```
+
 ## Route Definition with Type-Safe Names
 
 ```typescript
@@ -95,6 +127,17 @@ function ShopNav() {
 }
 ```
 
+`href()` and path-based response utilities read from `RegisteredRoutes`, so if
+you want them typed globally you should augment:
+
+```typescript
+declare global {
+  namespace RSCRouter {
+    interface RegisteredRoutes extends typeof router.routeMap {}
+  }
+}
+```
+
 See `/links` for full URL generation guide.
 
 ## Environment Type Setup
@@ -128,8 +171,7 @@ import type { AppBindings, AppVariables } from "./env";
 
 const router = createRouter<AppBindings>({
   document: Document,
-  urls: urlpatterns,
-});
+}).routes(urlpatterns);
 
 // Register bindings and variables globally for implicit typing
 declare global {
@@ -140,19 +182,19 @@ declare global {
 }
 
 // middleware - typed via ctx.set / ctx.get
-import { createMiddleware } from "@rangojs/router";
+import type { Middleware } from "@rangojs/router";
 
-export const authMiddleware = createMiddleware(async (ctx, next) => {
+export const authMiddleware: Middleware = async (ctx, next) => {
   ctx.set("user", {
     id: "123",
     email: "user@example.com",
     role: "admin",
   });
   await next();
-});
+};
 
 // loaders - typed context
-export const UserLoader = createLoader("user", async (ctx) => {
+export const UserLoader = createLoader(async (ctx) => {
   const db = ctx.env.DB; // D1Database (plain bindings)
   const userId = ctx.get("user")?.id; // from RSCRouter.Vars
   return db.prepare("SELECT * FROM users WHERE id = ?").bind(userId).first();
@@ -177,7 +219,7 @@ Now handlers have typed context without explicit imports:
 
 ```typescript
 // In loaders
-export const DashboardLoader = createLoader("dashboard", async (ctx) => {
+export const DashboardLoader = createLoader(async (ctx) => {
   // ctx.env.DB is typed from global RSCRouter.Env
   // ctx.get("user") is typed from global RSCRouter.Vars
   const user = ctx.get("user");
@@ -239,7 +281,7 @@ import type { RouteSearchParams, RouteParams } from "@rangojs/router";
 
 // RouteSearchParams<"name"> resolves the search schema to a typed object
 type SP = RouteSearchParams<"search">;
-// { q: string; page?: number; sort?: string }
+// { q: string | undefined; page?: number; sort?: string }
 
 // RouteParams<"name"> resolves URL params from the route pattern
 type P = RouteParams<"blogPost">;
@@ -283,7 +325,7 @@ Loaders have typed return values:
 
 ```typescript
 // loaders/product.ts
-export const ProductLoader = createLoader("product", async (ctx) => {
+export const ProductLoader = createLoader(async (ctx) => {
   return {
     id: ctx.params.slug,
     name: "Widget",
@@ -292,7 +334,7 @@ export const ProductLoader = createLoader("product", async (ctx) => {
 });
 
 // In server component - type is inferred
-import { useLoader } from "@rangojs/router";
+import { useLoader } from "@rangojs/router/client";
 
 async function ProductPage() {
   const product = await useLoader(ProductLoader);
@@ -302,11 +344,12 @@ async function ProductPage() {
 
 // In client component - same type
 "use client";
-import { useLoaderData } from "@rangojs/router/client";
+import { useLoader } from "@rangojs/router/client";
 
 function ProductPrice() {
-  const { product } = useLoaderData(ProductLoader);
-  // product: { id: string; name: string; price: number }
+  const { data } = useLoader(ProductLoader);
+  // data: { id: string; name: string; price: number }
+  const product = data;
   return <span>${product.price}</span>;
 }
 ```
@@ -559,7 +602,7 @@ export default router;
 //    No manual RegisteredRoutes declaration needed.
 
 // 5. loaders/*.ts - Type-safe loaders
-export const ProductLoader = createLoader("product", async (ctx) => {
+export const ProductLoader = createLoader(async (ctx) => {
   // ctx.params: { slug: string }
   // ctx.get("user"): User | undefined  (from RSCRouter.Vars)
   // ctx.env.DB: D1Database  (plain bindings from RSCRouter.Env)

package/skills/use-cache/SKILL.md

@@ -102,14 +102,28 @@ export async function getProductData(ctx) {
 // On hit: return value restored, breadcrumb replayed.
 ```
 
-## ctx Side-Effect Guards
+## Request-Scoped Guards
+
+### Read Guards
+
+`cookies()` and `headers()` **throw** inside a `"use cache"` function because
+per-request values (cookies, headers) are not reflected in the cache key. Without
+this guard, one user's data would be served to another.
+
+Extract the value before the cached function and pass it as an argument:
+
+```typescript
+const locale = cookies().get("locale")?.value ?? "en";
+const data = await getCachedData(locale); // locale is now in the cache key
+```
+
+### Side-Effect Guards
 
 These ctx methods **throw** inside a `"use cache"` function because their effects
 are lost on cache hit (the function body is skipped):
 
 - `ctx.set()` / `ctx.get()` for passing values to children
 - `ctx.header()`
-- `ctx.setCookie()` / `ctx.deleteCookie()`
 - `ctx.setTheme()`
 - `ctx.setLocationState()`
 - `ctx.onResponse()`

package/src/__internal.ts

@@ -160,7 +160,7 @@ export type {
 /**
  * @internal
  * Internal handler context with additional props for router internals.
- * Includes `_originalRequest` and `_currentSegmentId`.
+ * Includes `_currentSegmentId` and `_responseType`.
  */
 export type { InternalHandlerContext } from "./types.js";
 

package/src/bin/rango.ts

@@ -5,6 +5,9 @@ import {
   writePerModuleRouteTypesForFile,
   writeCombinedRouteTypes,
   detectUnresolvableIncludes,
+  detectUnresolvableIncludesForUrlsFile,
+  findNestedRouterConflict,
+  formatNestedRouterConflictError,
   type UnresolvableInclude,
 } from "../build/generate-route-types.ts";
 
@@ -131,22 +134,18 @@ function runStaticGeneration(args: string[], mode: "default" | "static") {
     process.exit(0);
   }
 
+  // Phase 1: Classify files
   const routerFiles: string[] = [];
+  const urlsFiles: string[] = [];
 
   for (const filePath of files) {
     try {
       const source = readFileSync(filePath, "utf-8");
-
-      // Detect file type and generate accordingly
-      const isRouter = /\bcreateRouter\s*[<(]/.test(source);
-      const isUrls = source.includes("urls(");
-
-      if (isRouter) {
+      if (/\bcreateRouter\s*[<(]/.test(source)) {
         routerFiles.push(filePath);
       }
-
-      if (isUrls) {
-        writePerModuleRouteTypesForFile(filePath);
+      if (source.includes("urls(")) {
+        urlsFiles.push(filePath);
       }
     } catch (err) {
       console.warn(
@@ -155,9 +154,10 @@ function runStaticGeneration(args: string[], mode: "default" | "static") {
     }
   }
 
-  // Check for unresolvable includes across all router files
+  // Phase 2: Collect diagnostics from all files BEFORE writing anything
   const allDiagnostics: Array<UnresolvableInclude & { routerFile: string }> =
     [];
+
   for (const routerFile of routerFiles) {
     const diagnostics = detectUnresolvableIncludes(routerFile);
     for (const d of diagnostics) {
@@ -165,10 +165,29 @@ function runStaticGeneration(args: string[], mode: "default" | "static") {
     }
   }
 
-  if (allDiagnostics.length > 0 && mode === "default") {
-    // Hard error: unresolvable includes detected
+  // Also check standalone urls files not covered by router-level detection
+  const routerFileSet = new Set(routerFiles);
+  for (const urlsFile of urlsFiles) {
+    if (routerFileSet.has(urlsFile)) continue;
+    const diagnostics = detectUnresolvableIncludesForUrlsFile(urlsFile);
+    for (const d of diagnostics) {
+      allDiagnostics.push({ ...d, routerFile: urlsFile });
+    }
+  }
+
+  // Deduplicate diagnostics (router and urls detection may find the same issue)
+  const seen = new Set<string>();
+  const uniqueDiagnostics = allDiagnostics.filter((d) => {
+    const key = `${d.sourceFile}:${d.pathPrefix}:${d.reason}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+
+  if (uniqueDiagnostics.length > 0 && mode === "default") {
+    // Hard error: no files written
     console.error("\n[rango] Unresolvable includes detected:\n");
-    formatDiagnostics(allDiagnostics);
+    formatDiagnostics(uniqueDiagnostics);
     console.error(
       "\nThe static parser cannot resolve these includes because they use " +
         "factory functions or dynamic expressions.\n\n" +
@@ -179,16 +198,28 @@ function runStaticGeneration(args: string[], mode: "default" | "static") {
     process.exit(1);
   }
 
-  if (allDiagnostics.length > 0 && mode === "static") {
+  if (uniqueDiagnostics.length > 0 && mode === "static") {
     // Warning: partial output accepted
     console.warn(
       "\n[rango] Warning: partial output (unresolvable includes):\n",
     );
-    formatDiagnostics(allDiagnostics);
+    formatDiagnostics(uniqueDiagnostics);
     console.warn("");
   }
 
-  // Generate named-routes for any detected router files
+  const nestedRouterConflict = findNestedRouterConflict(routerFiles);
+  if (nestedRouterConflict) {
+    console.error(
+      `\n${formatNestedRouterConflictError(nestedRouterConflict, "[rango]")}\n`,
+    );
+    process.exit(1);
+  }
+
+  // Phase 3: Write all outputs (only reached if diagnostics pass or --static)
+  for (const urlsFile of urlsFiles) {
+    writePerModuleRouteTypesForFile(urlsFile);
+  }
+
   for (const routerFile of routerFiles) {
     const projectRoot = findProjectRoot(routerFile);
     writeCombinedRouteTypes(projectRoot, [routerFile]);
@@ -238,6 +269,14 @@ async function runRuntimeDiscovery(args: string[], configFile?: string) {
     process.exit(1);
   }
 
+  const nestedRouterConflict = findNestedRouterConflict(routerEntries);
+  if (nestedRouterConflict) {
+    console.error(
+      `\n${formatNestedRouterConflictError(nestedRouterConflict, "[rango]")}\n`,
+    );
+    process.exit(1);
+  }
+
   let discoverAndWriteRouteTypes: typeof import("../build/runtime-discovery.ts").discoverAndWriteRouteTypes;
   try {
     const mod = await import("../build/runtime-discovery.ts");
@@ -257,10 +296,8 @@ async function runRuntimeDiscovery(args: string[], configFile?: string) {
     process.exit(1);
   }
 
-  // Use a single project root for all routers (find from the first entry)
-  const projectRoot = findProjectRoot(routerEntries[0]);
-
   for (const entry of routerEntries) {
+    const projectRoot = findProjectRoot(entry);
     const result = await discoverAndWriteRouteTypes({
       root: projectRoot,
       configFile,

package/src/browser/action-coordinator.ts

@@ -0,0 +1,97 @@
+import {
+  classifyActionResponse,
+  type ActionScenario,
+} from "./action-response-classifier.js";
+import type { ActionEntry } from "./event-controller.js";
+
+/**
+ * Plain data inputs for classifying a post-reconciliation action outcome.
+ * No browser objects or controller references — all values are snapshots.
+ */
+export interface ActionOutcomeInput {
+  /** This action's unique instance ID */
+  handleId: string;
+  /** All in-flight action entries (snapshot from event controller) */
+  inflightActions: Map<string, ActionEntry>;
+  /** Whether any concurrent actions occurred (controller-level shared flag) */
+  hadAnyConcurrentActions: boolean;
+  /** Segments revalidated by concurrent actions (from tracking set) */
+  revalidatedSegments: Set<string>;
+  /** window.location.pathname captured at action start */
+  actionStartPathname: string;
+  /** window.location.pathname at classification time */
+  currentPathname: string;
+  /** window.history.state?.key captured at action start */
+  actionStartLocationKey: string | undefined;
+  /** window.history.state?.key at classification time */
+  currentLocationKey: string | undefined;
+  /** Number of segments after reconciliation */
+  reconciledSegmentCount: number;
+  /** Number of matched segment IDs from server */
+  matchedCount: number;
+  /** Current intercept source URL (null when not on intercept route) */
+  currentInterceptSource: string | null;
+}
+
+/**
+ * Compute consolidation segments from concurrent action state.
+ *
+ * Returns segment IDs that need re-fetching when concurrent actions
+ * have each revalidated different parts of the tree, or null if
+ * consolidation is not needed.
+ */
+function computeConsolidationSegments(
+  input: ActionOutcomeInput,
+): string[] | null {
+  if (!input.hadAnyConcurrentActions) return null;
+  if (input.revalidatedSegments.size === 0) return null;
+
+  // Can't consolidate while any action is still waiting for a server response
+  const stillFetchingCount = [...input.inflightActions.values()].filter(
+    (a) => a.phase === "fetching",
+  ).length;
+  if (stillFetchingCount > 0) return null;
+
+  return Array.from(input.revalidatedSegments);
+}
+
+/**
+ * Count other actions still in "fetching" phase (excluding this handle).
+ */
+function countOtherFetchingActions(input: ActionOutcomeInput): number {
+  let count = 0;
+  for (const [, a] of input.inflightActions) {
+    if (a.phase === "fetching" && a.id !== input.handleId) {
+      count++;
+    }
+  }
+  return count;
+}
+
+/**
+ * Classify a post-reconciliation action outcome into one of 5 scenarios.
+ *
+ * This is the single entry point for post-action decision logic.
+ * It gathers consolidation and concurrency data from the plain inputs,
+ * then delegates to the pure classifyActionResponse function.
+ *
+ * The server-action-bridge calls this after reconciliation to decide
+ * whether to render, skip, consolidate, or refetch.
+ */
+export function classifyActionOutcome(
+  input: ActionOutcomeInput,
+): ActionScenario {
+  return classifyActionResponse({
+    actionStartPathname: input.actionStartPathname,
+    currentPathname: input.currentPathname,
+    actionStartLocationKey: input.actionStartLocationKey,
+    currentLocationKey: input.currentLocationKey,
+    reconciledSegmentCount: input.reconciledSegmentCount,
+    matchedCount: input.matchedCount,
+    currentInterceptSource: input.currentInterceptSource,
+    consolidationSegments: computeConsolidationSegments(input),
+    otherFetchingActionCount: countOtherFetchingActions(input),
+  });
+}
+
+export type { ActionScenario };

package/src/browser/event-controller.ts

@@ -8,7 +8,9 @@ import type {
   ResolvedSegment,
   RscMetadata,
   HandleData,
+  StreamingToken,
 } from "./types.js";
+import { filterSegmentOrder } from "./react/filter-segment-order.js";
 
 // Polyfill Symbol.dispose for Safari and older browsers
 if (typeof Symbol.dispose === "undefined") {
@@ -116,15 +118,6 @@ export interface HandleState {
   segmentOrder: string[];
 }
 
-/**
- * Token for tracking an active stream
- * Call end() when the stream completes
- */
-export interface StreamingToken {
-  /** End this streaming operation */
-  end(): void;
-}
-
 /**
  * Result from starting a navigation
  * Implements Disposable for use with `using` keyword
@@ -165,8 +158,8 @@ export interface ActionHandle extends Disposable {
   readonly settled: boolean;
   /** Check if any concurrent actions were started */
   hadConcurrentActions: boolean;
-  /** Get segments to consolidate (only valid when this is the last action) */
-  getConsolidationSegments(): string[] | null;
+  /** Get raw set of segments revalidated by concurrent actions */
+  getRevalidatedSegments(): Set<string>;
   /** Clear consolidation tracking */
   clearConsolidation(): void;
 }
@@ -189,6 +182,7 @@ export interface EventController {
   // State access
   getState(): DerivedNavigationState;
   getActionState(actionId: string): TrackedActionState;
+  getLocation(): NavigationLocation;
 
   // Location updates (for popstate where navigation doesn't go through startNavigation)
   setLocation(location: NavigationLocation): void;
@@ -216,6 +210,8 @@ export interface EventController {
   // Direct state access for advanced use
   getCurrentNavigation(): NavigationEntry | null;
   getInflightActions(): Map<string, ActionEntry>;
+  /** Whether any concurrent actions have occurred (shared across all handles) */
+  hadAnyConcurrentActions(): boolean;
 }
 
 // ============================================================================
@@ -394,8 +390,8 @@ export function createEventController(
       state,
       isStreaming,
       location,
-      // pendingUrl only during fetching phase - once streaming starts (URL changed), not pending
-      // Background revalidations don't expose a pending URL
+      // pendingUrl only during fetching phase - once streaming starts (URL changed), not pending.
+      // Background revalidations (skipLoadingState) don't expose a pending URL.
       pendingUrl:
         currentNavigation?.phase === "fetching" &&
         !currentNavigation.options?.skipLoadingState
@@ -488,6 +484,7 @@ export function createEventController(
 
       startStreaming(): StreamingToken {
         let ended = false;
+        entry.phase = "streaming";
         activeStreamCount++;
         notify();
 
@@ -675,24 +672,8 @@ export function createEventController(
         // If streaming is in progress, tryFinalize() will be called when streaming ends
       },
 
-      getConsolidationSegments(): string[] | null {
-        // Only consolidate if all actions have at least received their response
-        // We don't need to wait for streaming to complete since we're refetching anyway
-        // Count actions that are still fetching (waiting for server response)
-        const stillFetchingCount = [...inflightActions.values()].filter(
-          (a) => a.phase === "fetching",
-        ).length;
-
-        if (stillFetchingCount > 0) {
-          return null; // Some actions still waiting for server response
-        }
-        if (!hadAnyConcurrentActions) {
-          return null; // No concurrent actions occurred
-        }
-        if (concurrentRevalidatedSegments.size === 0) {
-          return null; // No segments to consolidate
-        }
-        return Array.from(concurrentRevalidatedSegments);
+      getRevalidatedSegments(): Set<string> {
+        return concurrentRevalidatedSegments;
       },
 
       clearConsolidation() {
@@ -727,16 +708,26 @@ export function createEventController(
   }
 
   function abortAllActions() {
-    for (const entry of inflightActions.values()) {
+    for (const [id, entry] of inflightActions) {
+      // Preserve settling entries — they have already been handled by
+      // fail()/complete() and will self-cleanup via the settlement timeout.
+      // Clearing them here would prevent debounced notifications from
+      // delivering the error/result state to subscribers.
+      if (entry.phase === "settling") continue;
       entry.abort.abort();
+      inflightActions.delete(id);
     }
-    inflightActions.clear();
     hadAnyConcurrentActions = false;
     concurrentRevalidatedSegments.clear();
     notify();
-    // Notify all action listeners
-    for (const actionId of actionListeners.keys()) {
-      notifyAction(actionId);
+    // Notify all action listeners directly by subscription ID.
+    // actionListeners keys are subscription IDs (possibly short names like
+    // "addToCart"), not full entry actionIds. Passing them to notifyAction
+    // would fail the suffix matcher — instead, notify each subscriber with
+    // its own state.
+    for (const [subscriptionId, listeners] of actionListeners) {
+      const state = getActionState(subscriptionId);
+      listeners.forEach((listener) => listener(state));
     }
   }
 
@@ -744,18 +735,6 @@ export function createEventController(
   // Handle Operations
   // ========================================================================
 
-  /**
-   * Filter segment IDs to only include routes and layouts.
-   * Excludes parallels (contain .@) and loaders (contain D followed by digit).
-   */
-  function filterSegmentOrder(matched: string[]): string[] {
-    return matched.filter((id) => {
-      if (id.includes(".@")) return false;
-      if (/D\d+\./.test(id)) return false;
-      return true;
-    });
-  }
-
   function setHandleData(
     data: HandleData,
     matched?: string[],
@@ -859,6 +838,7 @@ export function createEventController(
     // State
     getState,
     getActionState,
+    getLocation: () => location,
     setLocation,
 
     // Handles
@@ -877,6 +857,7 @@ export function createEventController(
     // Direct access
     getCurrentNavigation: () => currentNavigation,
     getInflightActions: () => inflightActions,
+    hadAnyConcurrentActions: () => hadAnyConcurrentActions,
   };
 }
 

package/src/browser/history-state.ts

@@ -0,0 +1,80 @@
+import {
+  isLocationStateEntry,
+  resolveLocationStateEntries,
+} from "./react/location-state-shared.js";
+
+/**
+ * Check if state is from typed LocationStateEntry[] (has __rsc_ls_ keys)
+ */
+function isTypedLocationState(
+  state: unknown,
+): state is Record<string, unknown> {
+  if (state === null || typeof state !== "object") return false;
+  return Object.keys(state).some((key) => key.startsWith("__rsc_ls_"));
+}
+
+/**
+ * Resolve navigation state - handles both LocationStateEntry[] and plain formats
+ */
+export function resolveNavigationState(state: unknown): unknown {
+  if (
+    Array.isArray(state) &&
+    state.length > 0 &&
+    isLocationStateEntry(state[0])
+  ) {
+    return resolveLocationStateEntries(state);
+  }
+  return state;
+}
+
+/**
+ * Build history state object from user state
+ * - Typed state: spread directly into history.state
+ * - Plain state: store in history.state.state
+ */
+export function buildHistoryState(
+  userState: unknown,
+  routerState?: { intercept?: boolean; sourceUrl?: string },
+  serverState?: Record<string, unknown>,
+): Record<string, unknown> | null {
+  const result: Record<string, unknown> = {};
+
+  if (routerState?.intercept) {
+    result.intercept = true;
+    if (routerState.sourceUrl) {
+      result.sourceUrl = routerState.sourceUrl;
+    }
+  }
+
+  if (userState !== undefined) {
+    if (isTypedLocationState(userState)) {
+      Object.assign(result, userState);
+    } else {
+      result.state = userState;
+    }
+  }
+
+  if (serverState) {
+    Object.assign(result, serverState);
+  }
+
+  return Object.keys(result).length > 0 ? result : null;
+}
+
+/**
+ * Merge server-set location state into the current history entry.
+ * Replaces the current history state and dispatches notification event
+ * so useLocationState hooks re-read from history.state.
+ */
+export function mergeLocationState(
+  locationState: Record<string, unknown>,
+): void {
+  const merged = {
+    ...window.history.state,
+    ...locationState,
+  };
+  window.history.replaceState(merged, "", window.location.href);
+  if (Object.keys(locationState).some((k) => k.startsWith("__rsc_ls_"))) {
+    window.dispatchEvent(new Event("__rsc_locationstate"));
+  }
+}