@rangojs/router 0.0.0-experimental.83 → 0.0.0-experimental.8332dbe4

package/src/browser/react/filter-segment-order.ts

@@ -1,11 +1,55 @@
 /**
- * Filter segment IDs to only include routes and layouts.
- * Excludes parallels (contain .@) and loaders (contain D followed by digit).
+ * Build the handle-collection segment order from a raw `matched` list.
+ *
+ * Two responsibilities:
+ *
+ * 1. Drop loader sub-ids ("D" followed by a digit, e.g. "M0L0D1.user") —
+ *    loaders never push handles.
+ *
+ * 2. Place each parallel slot id (contains ".@") immediately after its
+ *    parent layout/route id. Raw segment-resolution emission order does NOT
+ *    guarantee this: route-mounted parallels are resolved/pushed BEFORE the
+ *    route handler's segment is appended (see fresh.ts:resolveSegment for
+ *    routes, and revalidation.ts ~915-919), so matched can read
+ *    `[..., R0.@panel, R0]`. collectHandleData consumes segmentOrder verbatim
+ *    with later-wins semantics, so without normalization the route handler's
+ *    Meta would override the slot's more-specific Meta — backwards.
+ *
+ * Slot-id format is `<parentShortCode>.@<slotName>`; `parentShortCode` never
+ * contains ".@", so splitting at the first ".@" reliably yields the parent.
  */
 export function filterSegmentOrder(matched: string[]): string[] {
-  return matched.filter((id) => {
-    if (id.includes(".@")) return false;
-    if (/D\d+\./.test(id)) return false;
-    return true;
-  });
+  const slotsByParent = new Map<string, string[]>();
+  const nonSlots: string[] = [];
+  const nonSlotSet = new Set<string>();
+
+  for (const id of matched) {
+    if (/D\d+\./.test(id)) continue;
+    const slotIdx = id.indexOf(".@");
+    if (slotIdx >= 0) {
+      const parent = id.slice(0, slotIdx);
+      const list = slotsByParent.get(parent);
+      if (list) {
+        list.push(id);
+      } else {
+        slotsByParent.set(parent, [id]);
+      }
+    } else {
+      nonSlots.push(id);
+      nonSlotSet.add(id);
+    }
+  }
+
+  const result: string[] = [];
+  for (const id of nonSlots) {
+    result.push(id);
+    const slots = slotsByParent.get(id);
+    if (slots) result.push(...slots);
+  }
+  // Defensive: any slot whose parent is missing from the filtered list still
+  // gets included rather than silently dropped. Shouldn't happen in practice.
+  for (const [parent, slots] of slotsByParent) {
+    if (!nonSlotSet.has(parent)) result.push(...slots);
+  }
+  return result;
 }

package/src/browser/react/index.ts

@@ -20,6 +20,9 @@ export { useSegments, type SegmentsState } from "./use-segments.js";
 // Handle data hook
 export { useHandle } from "./use-handle.js";
 
+// Mount-aware reverse hook
+export { useReverse } from "./use-reverse.js";
+
 // Client cache controls hook
 export {
   useClientCache,

package/src/browser/react/use-params.ts

@@ -27,16 +27,19 @@ import { shallowEqual } from "./shallow-equal.js";
 // interface shapes pass the constraint — interfaces lack an implicit
 // index signature and would otherwise be rejected. The generic is a
 // shape annotation, not a runtime check; the body always returns the
-// underlying params map unchanged.
+// underlying params map unchanged. The default and selector input use
+// `string | undefined` because absent optional params are omitted from
+// the params record at runtime — the type must reflect that so callers
+// don't write `p.locale.length` and crash when the segment is absent.
 export function useParams<
-  T extends object = Record<string, string>,
+  T extends object = Record<string, string | undefined>,
 >(): Readonly<T>;
 export function useParams<T>(
-  selector: (params: Record<string, string>) => T,
+  selector: (params: Record<string, string | undefined>) => T,
 ): T;
 export function useParams<T>(
-  selector?: (params: Record<string, string>) => T,
-): T | Record<string, string> {
+  selector?: (params: Record<string, string | undefined>) => T,
+): T | Record<string, string | undefined> {
   const ctx = useContext(NavigationStoreContext);
 
   const [value, setValue] = useState<T | Record<string, string>>(() => {

package/src/browser/react/use-reverse.ts

@@ -0,0 +1,99 @@
+"use client";
+
+import { useCallback } from "react";
+import type { LocalReverseFunction } from "../../reverse.js";
+import { substitutePatternParams } from "../../router/substitute-pattern-params.js";
+import { serializeSearchParams } from "../../search-params.js";
+import { useMount } from "./use-mount.js";
+import { useParams } from "./use-params.js";
+
+type RouteEntry = string | { readonly path: string };
+type LocalRouteMap = Readonly<Record<string, RouteEntry>>;
+
+function getPattern(entry: RouteEntry | undefined): string | undefined {
+  if (entry === undefined) return undefined;
+  return typeof entry === "string" ? entry : entry.path;
+}
+
+/**
+ * Join an include mount prefix with a mount-relative pattern.
+ *
+ * `pattern === "/"` is the index of the local module — under a non-root
+ * mount it must collapse so `/` under `/blog` becomes `/blog`, not
+ * `/blog/`. This matches `ctx.reverse(".index")` on the server.
+ */
+function joinMount(mount: string, pattern: string): string {
+  if (pattern === "/") {
+    if (mount === "" || mount === "/") return "/";
+    return mount.endsWith("/") ? mount.slice(0, -1) : mount;
+  }
+  const normalizedMount = mount === "/" ? "" : mount.replace(/\/+$/, "");
+  return normalizedMount + pattern;
+}
+
+/**
+ * Mount-aware reverse function for a locally-imported `routes` map.
+ *
+ * Resolves dot-prefixed route names against the passed `routes` (typically
+ * a generated `routes` from a `urls()` module's `.gen.ts`), prefixes the
+ * result with the surrounding `include()` mount path, and substitutes
+ * params — auto-filling from the current matched route's params and
+ * letting explicit params override.
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ * import { Link, useReverse } from "@rangojs/router/client";
+ * import { routes as blogRoutes } from "../urls/blog.gen.js";
+ *
+ * function BlogNav() {
+ *   const reverse = useReverse(blogRoutes);
+ *   return (
+ *     <>
+ *       <Link to={reverse(".index")}>Blog</Link>
+ *       <Link to={reverse(".post", { postId: "hello" })}>Post</Link>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export function useReverse<const TRoutes extends LocalRouteMap>(
+  routes: TRoutes,
+): LocalReverseFunction<TRoutes> {
+  const mount = useMount();
+  const currentParams = useParams();
+
+  return useCallback(
+    ((
+      name: string,
+      explicitParams?: Record<string, string | undefined>,
+      search?: Record<string, unknown>,
+    ): string => {
+      if (!name.startsWith(".")) {
+        throw new Error(`Local route names must start with ".": "${name}"`);
+      }
+      const lookupName = name.slice(1);
+      const entry = (routes as LocalRouteMap)[lookupName];
+      const pattern = getPattern(entry);
+      if (pattern === undefined) {
+        throw new Error(`Unknown local route: "${name}"`);
+      }
+
+      const joined = joinMount(mount, pattern);
+
+      const mergedParams = explicitParams
+        ? { ...currentParams, ...explicitParams }
+        : currentParams;
+
+      const substituted = substitutePatternParams(joined, mergedParams, name);
+
+      if (search) {
+        const qs = serializeSearchParams(search);
+        if (qs) return `${substituted}?${qs}`;
+      }
+
+      return substituted;
+    }) as LocalReverseFunction<TRoutes>,
+    [routes, mount, currentParams],
+  );
+}

package/src/browser/react/use-router.ts

@@ -13,6 +13,10 @@ import type { RouterInstance, RouterNavigateOptions } from "../types.js";
  * useRouter() do not re-render on navigation state changes.
  * For reactive navigation state, use useNavigation() instead.
  *
+ * Methods read `basename` from the live context on each call so that
+ * cross-app navigation (app-switch) sees the current app's basename
+ * rather than the one captured at mount time.
+ *
  * @example
  * ```tsx
  * const router = useRouter();
@@ -29,7 +33,10 @@ export function useRouter(): RouterInstance {
     throw new Error("useRouter must be used within NavigationProvider");
   }
 
-  // Stable reference: ctx is itself stable (NavigationProvider memoizes with [])
+  // Stable reference: ctx itself is stable, and reads on each method call
+  // pick up live basename values from the context (backed by a live ref
+  // in NavigationProvider), so app-switch transitions are reflected without
+  // recreating this object.
   return useMemo<RouterInstance>(() => {
     /** Prefix a root-relative path with basename if not already prefixed. */
     function withBasename(url: string): string {

package/src/browser/react/use-segments.ts

@@ -25,15 +25,18 @@ function parsePathname(pathname: string): string[] {
 }
 
 /**
- * Build segments state from event controller
+ * Build segments state from event controller. `segmentIds` is the
+ * route-only list (parallels and loaders stripped) — distinct from the
+ * controller's `segmentOrder` which drives handle collection and includes
+ * parallel slot ids.
  */
 function buildSegmentsState(
   location: URL,
-  segmentOrder: string[],
+  routeSegmentIds: string[],
 ): SegmentsState {
   return {
     path: parsePathname(location.pathname),
-    segmentIds: segmentOrder,
+    segmentIds: routeSegmentIds,
     location,
   };
 }
@@ -74,7 +77,7 @@ export function useSegments<T>(
     const handleState = ctx.eventController.getHandleState();
     const segmentsState = buildSegmentsState(
       location as URL,
-      handleState.segmentOrder,
+      handleState.routeSegmentIds,
     );
     return selector ? selector(segmentsState) : segmentsState;
   });
@@ -94,7 +97,7 @@ export function useSegments<T>(
   // render-time setState calls.
   const segmentsCache = useRef<{
     location: URL;
-    segmentOrder: string[];
+    routeSegmentIds: string[];
     state: SegmentsState;
   } | null>(null);
 
@@ -113,17 +116,17 @@ export function useSegments<T>(
     if (
       cache &&
       cache.location === location &&
-      cache.segmentOrder === handleState.segmentOrder
+      cache.routeSegmentIds === handleState.routeSegmentIds
     ) {
       segmentsState = cache.state;
     } else {
       segmentsState = buildSegmentsState(
         location as URL,
-        handleState.segmentOrder,
+        handleState.routeSegmentIds,
       );
       segmentsCache.current = {
         location: location as URL,
-        segmentOrder: handleState.segmentOrder,
+        routeSegmentIds: handleState.routeSegmentIds,
         state: segmentsState,
       };
     }

package/src/browser/rsc-router.tsx

@@ -28,6 +28,7 @@ import {
   isInterceptSegment,
   splitInterceptSegments,
 } from "./intercept-utils.js";
+import { createAppShellRef } from "./app-shell.js";
 
 // Vite HMR types are provided by vite/client
 
@@ -114,6 +115,13 @@ export interface BrowserAppContext {
   warmupEnabled?: boolean;
   /** App version for prefetch version mismatch detection */
   version?: string;
+  /**
+   * Live app-shell ref. Cross-app navigations replace its contents so the
+   * NavigationProvider and renderSegments pick up the target app's
+   * rootLayout, basename, and version without consumer rerenders. Theme,
+   * warmup, and prefetch TTL are document-lifetime (see AppShell).
+   */
+  appShellRef?: import("./app-shell.js").AppShellRef;
 }
 
 // Module-level state for the initialized app
@@ -204,13 +212,23 @@ export async function initBrowserApp(
   // Create composable utilities
   const client = createNavigationClient(deps);
 
-  // Extract rootLayout and version from metadata for browser-side re-renders
-  const rootLayout = initialPayload.metadata?.rootLayout;
+  // Capture the per-router app-shell so cross-app navigations can replace
+  // it atomically. rootLayout, basename, and version live here and are
+  // read through the ref at call time rather than closed over. Theme,
+  // warmup, and prefetch TTL are deliberately excluded — they are
+  // document-lifetime and stay stable across smooth cross-app transitions.
   const version = initialPayload.metadata?.version;
+  const appShellRef = createAppShellRef({
+    routerId: initialPayload.metadata?.routerId,
+    rootLayout: initialPayload.metadata?.rootLayout,
+    basename: initialPayload.metadata?.basename,
+    version,
+  });
 
   // Initialize the localStorage state key for cache invalidation.
-  // Uses the build version so a new deploy automatically busts all cached prefetches.
-  initRangoState(version ?? "0");
+  // The build version busts cached prefetches on deploy; the routerId
+  // namespaces the key so sibling apps on the same origin don't collide.
+  initRangoState(version ?? "0", initialPayload.metadata?.routerId);
   setAppVersion(version);
 
   // Initialize the in-memory prefetch cache TTL from server config.
@@ -220,11 +238,17 @@ export async function initBrowserApp(
     initPrefetchCache(prefetchCacheTTL);
   }
 
-  // Create a bound renderSegments that includes rootLayout
+  // Create a bound renderSegments that reads rootLayout through the shell
+  // ref. On app switch the ref is updated before the tree re-renders, so
+  // the new app's Document (rootLayout) replaces the previous one.
   const renderSegments = (
     segments: ResolvedSegment[],
     options?: RenderSegmentsOptions,
-  ) => baseRenderSegments(segments, { ...options, rootLayout });
+  ) =>
+    baseRenderSegments(segments, {
+      ...options,
+      rootLayout: appShellRef.get().rootLayout,
+    });
 
   // Lazy reference for navigation bridge — the action bridge is created first
   // but may need to trigger SPA navigation for action redirects.
@@ -256,6 +280,7 @@ export async function initBrowserApp(
     onUpdate: (update) => store.emitUpdate(update),
     renderSegments,
     version: version,
+    appShellRef,
   });
 
   // Connect action redirect → navigation bridge (now that both are initialized)
@@ -416,6 +441,7 @@ export async function initBrowserApp(
     initialTheme: effectiveInitialTheme,
     warmupEnabled: initialPayload.metadata?.warmupEnabled ?? true,
     version,
+    appShellRef,
   };
   browserAppContext = context;
 
@@ -481,6 +507,7 @@ export function RSCRouter(_props: RSCRouterProps): React.ReactElement {
     initialTheme,
     warmupEnabled,
     version,
+    appShellRef,
   } = getBrowserAppContext();
 
   // Signal that the React tree has hydrated. useEffect only fires after
@@ -501,6 +528,7 @@ export function RSCRouter(_props: RSCRouterProps): React.ReactElement {
       warmupEnabled={warmupEnabled}
       version={version}
       basename={initialPayload.metadata?.basename}
+      appShellRef={appShellRef}
     />
   );
 }

package/src/browser/types.ts

@@ -39,6 +39,12 @@ export interface RscMetadata {
   isError?: boolean;
   matched?: string[];
   diff?: string[];
+  /**
+   * All segment ids re-resolved on the server, including null-component
+   * ones excluded from `segments`/`diff`. Drives client-side handle-bucket
+   * cleanup. Superset of `diff`. See MatchResult.resolvedIds.
+   */
+  resolvedIds?: string[];
   /** Merged route params from the matched route */
   params?: Record<string, string>;
   /**
@@ -427,6 +433,12 @@ export interface NavigationStore {
   markCacheAsStale(): void;
   markCacheAsStaleAndBroadcast(): void;
   clearHistoryCache(): void;
+  /**
+   * Clear this tab's nav + prefetch caches without broadcasting or rotating
+   * shared state. Intended for app-switch transitions that affect only this
+   * tab's session.
+   */
+  clearHistoryCacheLocal(): void;
   broadcastCacheInvalidation(): void;
 
   // Cross-tab refresh callback (set by navigation bridge)
@@ -542,6 +554,13 @@ export interface NavigationBridge {
   registerLinkInterception(): () => void;
   /** Update the RSC version (e.g. after HMR). Clears prefetch cache. */
   updateVersion(newVersion: string): void;
+  /**
+   * Replace the active app-shell snapshot (rootLayout, basename, version)
+   * atomically. Used on cross-app navigations when the response's routerId
+   * indicates the user entered a different app. Theme, warmup, and prefetch
+   * TTL are document-lifetime and not part of the shell.
+   */
+  updateAppShell(next: import("./app-shell.js").AppShell): void;
 }
 
 /**

package/src/build/route-trie.ts

@@ -20,7 +20,8 @@ export interface TrieLeaf {
   sp: string;
   /** Ancestry shortCodes from root to route [M0L0, M0L0L0, M0L0L0R499] */
   a: string[];
-  /** Optional param names (absent params get empty string value) */
+  /** Optional param names declared on the route. Absent params are
+   * omitted from the matched params record (read as `undefined`). */
   op?: string[];
   /** Constraint validation: paramName -> allowed values */
   cv?: Record<string, string[]>;

package/src/cache/cf/cf-cache-store.ts

@@ -67,13 +67,11 @@ export const MAX_REVALIDATION_INTERVAL = 30;
 // Types
 // ============================================================================
 
-/**
- * Cloudflare Workers ExecutionContext (subset we need)
- */
-export interface ExecutionContext {
-  waitUntil(promise: Promise<any>): void;
-  passThroughOnException(): void;
-}
+// Re-exported from the canonical home so cf-cache-store consumers keep
+// importing `ExecutionContext` from this module without a second interface
+// drifting over time.
+export type { ExecutionContext } from "../../types/request-scope.js";
+import type { ExecutionContext } from "../../types/request-scope.js";
 
 /**
  * Minimal Cloudflare KV Namespace interface.

package/src/client.rsc.tsx

@@ -78,6 +78,9 @@ export {
 // Re-export useHref - it's a "use client" hook
 export { useHref } from "./browser/react/use-href.js";
 
+// Re-export useReverse - it's a "use client" hook
+export { useReverse } from "./browser/react/use-reverse.js";
+
 // Re-export useHandle - it's a "use client" hook
 export { useHandle } from "./browser/react/use-handle.js";
 

package/src/client.tsx

@@ -448,8 +448,12 @@ export { MountContext } from "./browser/react/mount-context.js";
 // Mount-aware href hook - auto-prefixes paths with include() mount
 export { useHref } from "./browser/react/use-href.js";
 
+// Mount-aware reverse hook - resolves dot-prefixed names against an imported
+// generated routes map (from a urls() module's .gen.ts).
+export { useReverse } from "./browser/react/use-reverse.js";
+
 // Type-safe scoped reverse function for scopedReverse<typeof patterns>()
-export type { ScopedReverseFunction } from "./reverse.js";
+export type { ScopedReverseFunction, LocalReverseFunction } from "./reverse.js";
 
 // Loader definition type - for typing loader props in client components
 export type { LoaderDefinition } from "./types.js";

package/src/href-client.ts

@@ -186,7 +186,10 @@ export function href<T extends ValidPaths>(path: T, mount?: string): string {
     const normalizedMount = mount.endsWith("/") ? mount.slice(0, -1) : mount;
     return normalizedMount + path;
   }
-  return path;
+  // ValidPaths is built from template literals so T does extend string at
+  // runtime, but the inference can fail past a certain route-union complexity
+  // and TypeScript reports T as not assignable to string.
+  return path as string;
 }
 
 /**

package/src/index.rsc.ts

@@ -172,6 +172,9 @@ export type { PublicRequestContext as RequestContext } from "./server/request-co
 import type { PublicRequestContext } from "./server/request-context.js";
 import type { DefaultEnv } from "./types/global-namespace.js";
 
+// Shared base for every user-facing request context (mirrors index.ts).
+export type { RequestScope, ExecutionContext } from "./types/request-scope.js";
+
 export const getRequestContext: <
   TEnv = DefaultEnv,
 >() => PublicRequestContext<TEnv> = _getRequestContextInternal;

package/src/index.ts

@@ -264,6 +264,9 @@ export function transition(): never {
 // Request context type (safe for client)
 export type { PublicRequestContext as RequestContext } from "./server/request-context.js";
 
+// Shared base for every user-facing request context.
+export type { RequestScope, ExecutionContext } from "./types/request-scope.js";
+
 // Cookie store types (safe for client)
 export type {
   CookieStore,

package/src/outlet-context.ts

@@ -1,4 +1,4 @@
-import { Context, createContext, type ReactNode } from "react";
+import { type Context, createContext, type ReactNode } from "react";
 import type { ResolvedSegment } from "./types";
 
 export interface OutletContextValue {

package/src/response-utils.ts

@@ -0,0 +1,28 @@
+/**
+ * Runtime-neutral Response shape utilities.
+ *
+ * Kept at the src/ root so both `router/` and `rsc/` can depend on it
+ * without creating a cross-layer import cycle.
+ */
+
+/**
+ * True when a Response represents a WebSocket upgrade handoff and must not
+ * be reconstructed or mutated:
+ *
+ * - Status 101 (Switching Protocols) is outside the standard Response
+ *   constructor's 200–599 range, so `new Response(body, { status: 101 })`
+ *   throws RangeError on Node/undici and any spec-compliant runtime.
+ * - Cloudflare's workerd attaches a non-standard `webSocket` property on
+ *   the upgrade Response (e.g. from `acceptWebSocket`/`handleWebSocketUpgrade`
+ *   or the `agents` library's `routeAgentRequest`). That property is dropped
+ *   by a `new Response(...)` copy, breaking the upgrade even on workerd
+ *   where the status range is relaxed.
+ *
+ * Callers should short-circuit header/body merges for these responses.
+ */
+export function isWebSocketUpgradeResponse(response: Response): boolean {
+  return (
+    response.status === 101 ||
+    (response as unknown as { webSocket?: unknown }).webSocket != null
+  );
+}