@rangojs/router 0.0.0-experimental.29 → 0.0.0-experimental.2a0dea97

package/skills/route/SKILL.md

@@ -181,6 +181,37 @@ String keys still work (`ctx.set("key", value)` / `ctx.get("key")`), but
 Only route handlers and middleware can call `ctx.set()`. Layouts, parallels,
 and intercepts can only read via `ctx.get()`.
 
+#### Non-cacheable context variables
+
+Mark a var as non-cacheable when it holds inherently request-specific data
+(sessions, auth tokens, per-request IDs). There are two ways:
+
+```typescript
+// Var-level: every value written to this var is non-cacheable
+const Session = createVar<SessionData>({ cache: false });
+
+// Write-level: escalate a normally-cacheable var for this specific write
+const Theme = createVar<string>();
+ctx.set(Theme, userTheme, { cache: false });
+```
+
+"Least cacheable wins" — if either the var definition or the write site says
+`cache: false`, the value is non-cacheable.
+
+Reading a non-cacheable var inside `cache()` or `"use cache"` throws at
+runtime. This prevents request-specific data from leaking into cached output:
+
+```typescript
+// This throws — Session is non-cacheable
+async function CachedWidget(ctx) {
+  "use cache";
+  const session = ctx.get(Session); // Error: non-cacheable var read inside cache scope
+  return <Widget />;
+}
+```
+
+Cacheable vars (the default) can be read freely inside cache scopes.
+
 ### Revalidation Contracts for Handler Data
 
 Handler-first guarantees apply within a single full render pass. For partial
@@ -352,11 +383,34 @@ urls(({ path, layout }) => [
 ])
 ```
 
+## Handler-attached `.use`
+
+Page handlers can carry their own loader, middleware, error boundaries, parallels, and other defaults via a `.use` callback — so the page is self-contained and reusable across mount sites without re-wiring the same items.
+
+```typescript
+const ProductPage: Handler<"/product/:slug"> = async (ctx) => {
+  const product = await ctx.use(ProductLoader);
+  return <ProductView product={product} />;
+};
+ProductPage.use = () => [
+  loader(ProductLoader),
+  loading(<ProductSkeleton />),
+  middleware(async (ctx, next) => {
+    await next();
+    ctx.header("Cache-Control", "private, max-age=60");
+  }),
+];
+
+// Mount site has no per-page wiring — defaults travel with the handler.
+path("/product/:slug", ProductPage, { name: "product" });
+```
+
+Explicit `use()` at the mount site merges with `handler.use` (handler defaults first, explicit second). See [skills/handler-use](../handler-use/SKILL.md) for the merge order, allowed item types per mount site, and override semantics.
+
 ## Complete Example
 
 ```typescript
-import { urls } from "@rangojs/router";
-import { Breadcrumbs } from "./handles/breadcrumbs";
+import { urls, Breadcrumbs } from "@rangojs/router";
 
 export const urlpatterns = urls(({ path, layout, loader, loading }) => [
   // Simple route

package/skills/router-setup/SKILL.md

@@ -78,16 +78,21 @@ interface RSCRouterOptions<TEnv> {
   // Document component wrapping entire app
   document?: ComponentType<{ children: ReactNode }>;
 
+  // URL prefix for sub-path deployments (e.g. "/admin")
+  // All routes, reverse(), href(), Link, redirect(), and router.use()
+  // patterns are automatically prefixed. Route names stay unprefixed.
+  basename?: string;
+
   // Enable per-request performance timeline (console waterfall + Server-Timing header)
   debugPerformance?: boolean;
 
   // Default error boundary
   defaultErrorBoundary?: ReactNode | ErrorBoundaryHandler;
 
-  // Default not-found boundary
+  // Default not-found boundary for notFound() thrown in handlers/loaders
   defaultNotFoundBoundary?: ReactNode | NotFoundBoundaryHandler;
 
-  // Component for 404 routes
+  // Component for 404 (no route match, or notFound() without a boundary)
   notFound?: ReactNode | ((props: { pathname: string }) => ReactNode);
 
   // Error logging callback
@@ -124,6 +129,36 @@ interface RSCRouterOptions<TEnv> {
 }
 ```
 
+## Basename (Sub-Path Deployment)
+
+When your app is served under a sub-path (e.g. `/admin` or `/v2`), set `basename`:
+
+```typescript
+const router = createRouter({
+  basename: "/admin",
+  document: Document,
+}).routes(({ path, include }) => [
+  path("/", Dashboard, { name: "home" }), // matches /admin
+  path("/users", Users, { name: "users" }), // matches /admin/users
+  include("/api", apiPatterns, { name: "api" }), // matches /admin/api/*
+]);
+
+router.reverse("home"); // "/admin"
+router.reverse("users"); // "/admin/users"
+```
+
+Router-owned APIs are basename-aware:
+
+- `reverse()` returns prefixed paths
+- `<Link to="/users">` renders `<a href="/admin/users">`
+- `redirect("/login")` redirects to `"/admin/login"`
+- `router.use("/users/*", mw)` matches `/admin/users/*`
+- `useRouter().push("/users")` navigates to `/admin/users`
+- Route names stay unprefixed (`"home"`, not `"admin.home"`)
+
+Note: `href()` is a raw path helper and does **not** auto-prefix with basename.
+Use `reverse()` or `<Link>` for basename-aware URLs.
+
 ## Using the Request Handler
 
 The router provides a `fetch` method to handle RSC requests:
@@ -290,6 +325,56 @@ const router = createRouter({
 export default router;
 ```
 
+## Not Found Handling
+
+Two distinct 404 scenarios:
+
+**1. No route matches the URL** — the router renders the `notFound` component from `createRouter()` config. This is automatic.
+
+**2. A handler/loader calls `notFound()`** — signals that the route matched but the data doesn't exist (e.g., invalid product ID).
+
+```typescript
+import { notFound } from "@rangojs/router";
+
+// In a handler or loader
+path("/product/:slug", async (ctx) => {
+  const product = await db.getProduct(ctx.params.slug);
+  if (!product) notFound("Product not found");
+  return <ProductPage product={product} />;
+});
+```
+
+### Fallback chain for `notFound()`
+
+When `notFound()` is thrown, the router looks for a fallback in this order:
+
+1. **`notFoundBoundary()`** — nearest boundary in the route tree (route-level)
+2. **`defaultNotFoundBoundary`** — from `createRouter()` config (app-level)
+3. **`notFound`** — from `createRouter()` config (same component used for no-route-match)
+4. **Default `<h1>Not Found</h1>`** — built-in fallback
+
+All cases set HTTP 404 status.
+
+### notFoundBoundary
+
+Wrap routes with `notFoundBoundary()` for route-specific not-found UI:
+
+```typescript
+urls(({ path, layout }) => [
+  layout(ShopLayout, () => [
+    notFoundBoundary(({ notFound: info }) => (
+      <div>
+        <h1>Not Found</h1>
+        <p>{info.message}</p>
+      </div>
+    )),
+    path("/product/:slug", ProductPage),
+  ]),
+]);
+```
+
+`notFoundBoundary` receives `{ notFound: NotFoundInfo }` where `NotFoundInfo` contains `message`, `segmentId`, `segmentType`, and `pathname`.
+
 ## Including Sub-patterns
 
 ```typescript

package/skills/typesafety/SKILL.md

@@ -369,8 +369,18 @@ interface PaginationData {
   perPage: number;
 }
 export const Pagination = createVar<PaginationData>();
+
+// Non-cacheable var — reading inside cache() or "use cache" throws at runtime
+const Session = createVar<SessionData>({ cache: false });
 ```
 
+`createVar` accepts an optional options object. The `cache` option (default
+`true`) controls whether the var's values can be read inside cache scopes.
+Write-level escalation is also supported: `ctx.set(Var, value, { cache: false })`
+marks a specific write as non-cacheable even if the var itself is cacheable.
+"Least cacheable wins" — if either says `cache: false`, the value throws on
+read inside `cache()` or `"use cache"`.
+
 ### Producer (handler or middleware)
 
 ```typescript
@@ -414,26 +424,30 @@ Both approaches coexist: `ctx.get("user")` (global via Vars) and
 Handles have typed data:
 
 ```typescript
-// handles/breadcrumbs.ts
-import { createHandle } from "@rangojs/router";
-
-// All export patterns work: export const, const + export { X }, export { X as Y }
-export const Breadcrumbs = createHandle<{ label: string; href: string }>();
-
-// In route definition - use handle() DSL
-import { urls } from "@rangojs/router";
-
-export const urlpatterns = urls(({ path, handle }) => [
-  path("/shop/product/:slug", ProductPage, { name: "product" }, () => [
-    handle(Breadcrumbs, { label: "Products", href: "/shop/products" }),
-  ]),
-]);
-
-// In client - typed array
+// Built-in Breadcrumbs handle — import from "@rangojs/router"
+import { Breadcrumbs } from "@rangojs/router";
+// Type: Handle<BreadcrumbItem, BreadcrumbItem[]>
+// BreadcrumbItem: { label: string; href: string; content?: ReactNode | Promise<ReactNode> }
+
+// In route handler — push is fully typed
+path("/shop/product/:slug", (ctx) => {
+  const breadcrumb = ctx.use(Breadcrumbs);
+  breadcrumb({ label: "Products", href: "/shop/products" });
+  return <ProductPage />;
+}, { name: "product" });
+
+// In client — typed array
+import { useHandle, Breadcrumbs } from "@rangojs/router/client";
 function BreadcrumbNav() {
   const crumbs = useHandle(Breadcrumbs);
-  // crumbs: Array<{ label: string; href: string }>
+  // crumbs: BreadcrumbItem[]
 }
+
+// Custom handles also work the same way
+import { createHandle } from "@rangojs/router";
+export const PageTitle = createHandle<string, string>(
+  (segments) => segments.flat().at(-1) ?? "Default Title"
+);
 ```
 
 ## Ref Prop Type Safety (Loaders & Handles)
@@ -447,14 +461,12 @@ export const ProductLoader = createLoader(async (ctx) => {
   return { product: await fetchProduct(ctx.params.slug) };
 });
 
-// handles.ts
-export const Breadcrumbs = createHandle<{ label: string; href: string }>();
+// Built-in Breadcrumbs — or any custom handle created with createHandle()
 
 // Client component — typeof infers all generics
 ("use client");
-import { useLoader, useHandle } from "@rangojs/router/client";
+import { useLoader, useHandle, type Breadcrumbs } from "@rangojs/router/client";
 import type { ProductLoader } from "../loaders";
-import type { Breadcrumbs } from "../handles";
 
 function MyComponent({
   loader,

package/src/__internal.ts

@@ -164,6 +164,98 @@ export type {
  */
 export type { InternalHandlerContext } from "./types.js";
 
+// ============================================================================
+// Rendering (Internal)
+// ============================================================================
+
+/**
+ * @internal
+ * Builds React element trees from route segments.
+ */
+export { renderSegments } from "./segment-system.js";
+
+// ============================================================================
+// Error Utilities (Internal)
+// ============================================================================
+
+/**
+ * @internal
+ * Error sanitization and network error utilities.
+ */
+export { sanitizeError, NetworkError, isNetworkError } from "./errors.js";
+
+// ============================================================================
+// Type Utilities (Internal)
+// ============================================================================
+
+/**
+ * @internal
+ * Scoped view of GeneratedRouteMap for Handler<"localName", ScopedRouteMap<"prefix">>.
+ */
+export type { ScopedRouteMap } from "./types.js";
+
+/**
+ * @internal
+ * Type-level utilities for reverse URL generation.
+ */
+export type { MergeRoutes, SanitizePrefix } from "./reverse.js";
+
+/**
+ * @internal
+ * Individual telemetry event types.
+ */
+export type {
+  RequestStartEvent,
+  RequestEndEvent,
+  RequestErrorEvent,
+  RequestTimeoutEvent,
+  LoaderStartEvent,
+  LoaderEndEvent,
+  LoaderErrorEvent,
+  HandlerErrorEvent,
+  CacheDecisionEvent,
+  RevalidationDecisionEvent,
+} from "./router/telemetry.js";
+
+// ============================================================================
+// Pre-render / Static Handler Guards (Internal)
+// ============================================================================
+
+/**
+ * @internal
+ * Type guard for prerender handler definitions.
+ */
+export { isPrerenderHandler, isPassthroughHandler } from "./prerender.js";
+
+/**
+ * @internal
+ * Type guard for static handler definitions.
+ */
+export { isStaticHandler } from "./static-handler.js";
+
+// ============================================================================
+// URL Pattern Internals
+// ============================================================================
+
+/**
+ * @internal
+ * Sentinel used to tag response-type route entries.
+ */
+export { RESPONSE_TYPE } from "./urls.js";
+
+// ============================================================================
+// Route Match Debug (Internal)
+// ============================================================================
+
+/**
+ * @internal
+ * Debug utilities for route matching performance analysis.
+ */
+export {
+  enableMatchDebug,
+  getMatchDebugStats,
+} from "./router/pattern-matching.js";
+
 // ============================================================================
 // Debug Utilities (Internal)
 // ============================================================================

package/src/browser/app-version.ts

@@ -0,0 +1,14 @@
+/**
+ * Mutable app version — updated after HMR revalidation.
+ * Read by prefetch, navigation, and context code.
+ */
+
+let currentVersion: string | undefined;
+
+export function getAppVersion(): string | undefined {
+  return currentVersion;
+}
+
+export function setAppVersion(version: string | undefined): void {
+  currentVersion = version;
+}

package/src/browser/event-controller.ts

@@ -79,6 +79,8 @@ export interface DerivedNavigationState {
   state: "idle" | "loading";
   /** Whether any operation is streaming */
   isStreaming: boolean;
+  /** Whether a navigation is active (fetching or streaming, before commit) */
+  isNavigating: boolean;
   /** Current committed location */
   location: NavigationLocation;
   /** URL being navigated to (null if idle) */
@@ -389,6 +391,9 @@ export function createEventController(
     return {
       state,
       isStreaming,
+      // True when a navigation is active (fetching or streaming, before
+      // commit). Broader than pendingUrl which clears during streaming.
+      isNavigating: currentNavigation !== null,
       location,
       // pendingUrl only during fetching phase - once streaming starts (URL changed), not pending.
       // Background revalidations (skipLoadingState) don't expose a pending URL.

package/src/browser/link-interceptor.ts

@@ -117,6 +117,7 @@ export function setupLinkInterception(
     // Read navigation options from data attributes (set by Link component)
     const scrollAttr = link.getAttribute("data-scroll");
     const replaceAttr = link.getAttribute("data-replace");
+    const revalidateAttr = link.getAttribute("data-revalidate");
 
     const navigateOptions: NavigateOptions = {};
     if (scrollAttr === "false") {
@@ -125,6 +126,9 @@ export function setupLinkInterception(
     if (replaceAttr === "true") {
       navigateOptions.replace = true;
     }
+    if (revalidateAttr === "false") {
+      navigateOptions.revalidate = false;
+    }
 
     onNavigate(href, navigateOptions);
   };

package/src/browser/navigation-bridge.ts

@@ -4,12 +4,19 @@ import type {
   NavigateOptionsInternal,
   ResolvedSegment,
 } from "./types.js";
+import { setAppVersion } from "./app-version.js";
 import * as React from "react";
 import { startTransition } from "react";
 import {
   createNavigationTransaction,
   resolveNavigationState,
 } from "./navigation-transaction.js";
+import { buildHistoryState } from "./history-state.js";
+import {
+  handleNavigationStart,
+  handleNavigationEnd,
+  ensureHistoryKey,
+} from "./scroll-restoration.js";
 
 // addTransitionType is only available in React experimental
 const addTransitionType: ((type: string) => void) | undefined =
@@ -18,7 +25,6 @@ const addTransitionType: ((type: string) => void) | undefined =
 import { setupLinkInterception } from "./link-interceptor.js";
 import { createPartialUpdater } from "./partial-update.js";
 import { generateHistoryKey } from "./navigation-store.js";
-import { handleNavigationEnd } from "./scroll-restoration.js";
 import type { EventController } from "./event-controller.js";
 import { isInterceptOnlyCache } from "./intercept-utils.js";
 import {
@@ -35,11 +41,6 @@ if (typeof Symbol.dispose === "undefined") {
   (Symbol as any).dispose = Symbol("Symbol.dispose");
 }
 
-/** Get IDs of non-loader segments (layouts, routes, parallels). */
-function getNonLoaderSegmentIds(segments: ResolvedSegment[]): string[] {
-  return segments.filter((s) => s.type !== "loader").map((s) => s.id);
-}
-
 export { createNavigationTransaction };
 
 /**
@@ -67,8 +68,8 @@ export interface NavigationBridgeConfigWithController extends NavigationBridgeCo
 export function createNavigationBridge(
   config: NavigationBridgeConfigWithController,
 ): NavigationBridge {
-  const { store, client, eventController, onUpdate, renderSegments, version } =
-    config;
+  const { store, client, eventController, onUpdate, renderSegments } = config;
+  let version = config.version;
 
   // Create shared partial updater
   const fetchPartialUpdate = createPartialUpdater({
@@ -76,7 +77,7 @@ export function createNavigationBridge(
     client,
     onUpdate,
     renderSegments,
-    version,
+    getVersion: () => version,
   });
 
   return {
@@ -114,6 +115,85 @@ export function createNavigationBridge(
         return;
       }
 
+      // Shallow navigation: skip RSC fetch when revalidate is false
+      // and the pathname hasn't changed (search param / hash only change).
+      if (
+        options?.revalidate === false &&
+        targetUrl.pathname === new URL(window.location.href).pathname
+      ) {
+        // Preserve intercept context from the current history entry so that
+        // popstate uses the correct cache key (:intercept suffix) and restores
+        // the right full-page vs modal semantics.
+        const currentHistoryState = window.history.state;
+        const isIntercept = currentHistoryState?.intercept === true;
+        const interceptSourceUrl = isIntercept
+          ? currentHistoryState?.sourceUrl
+          : undefined;
+
+        const historyKey = generateHistoryKey(url, { intercept: isIntercept });
+
+        // Copy current segments to the new history key so back/forward restores instantly
+        const currentKey = store.getHistoryKey();
+        const currentCache = store.getCachedSegments(currentKey);
+        if (currentCache?.segments) {
+          const currentHandleData = eventController.getHandleState().data;
+          store.cacheSegmentsForHistory(
+            historyKey,
+            currentCache.segments,
+            currentHandleData,
+          );
+        }
+
+        // Save current scroll position before changing URL
+        handleNavigationStart();
+
+        // Snapshot old state before pushState/replaceState overwrites it
+        const oldState = window.history.state;
+
+        // Update browser URL (carry intercept context into history state)
+        const historyState = buildHistoryState(
+          resolvedState,
+          {
+            intercept: isIntercept || undefined,
+            sourceUrl: interceptSourceUrl,
+          },
+          {},
+        );
+        if (options.replace) {
+          window.history.replaceState(historyState, "", url);
+        } else {
+          window.history.pushState(historyState, "", url);
+        }
+
+        // Ensure new history entry has a scroll restoration key
+        ensureHistoryKey();
+
+        // Notify useLocationState() hooks when state changes
+        const hasOldState =
+          oldState &&
+          typeof oldState === "object" &&
+          ("state" in oldState ||
+            Object.keys(oldState).some((k) => k.startsWith("__rsc_ls_")));
+        const hasNewState =
+          historyState &&
+          ("state" in historyState ||
+            Object.keys(historyState).some((k) => k.startsWith("__rsc_ls_")));
+        if (hasOldState || hasNewState) {
+          window.dispatchEvent(new Event("__rsc_locationstate"));
+        }
+
+        // Update store history key so future navigations reference the right cache
+        store.setHistoryKey(historyKey);
+        store.setCurrentUrl(url);
+
+        // Notify hooks — location updates, state stays idle
+        eventController.setLocation(targetUrl);
+
+        // Handle post-navigation scroll
+        handleNavigationEnd({ scroll: options.scroll });
+        return;
+      }
+
       // Only abort pending requests when navigating to a different route
       // Same-route navigation (e.g., /todos -> /todos) should not cancel in-flight actions
       const currentPath = new URL(window.location.href).pathname;
@@ -181,18 +261,24 @@ export function createNavigationBridge(
       // 2. routes that CAN be intercepted - we don't know if this navigation will intercept
       // 3. when leaving intercept - we need fresh non-intercept segments from server
       // 4. redirect-with-state - force re-render so hooks read fresh state
+      // 5. stale cache - server action invalidated it, need fresh data with loading state
       const hasUsableCache =
         cachedSegments &&
         cachedSegments.length > 0 &&
         !isInterceptOnlyCache(cachedSegments) &&
         !hasInterceptCache &&
         !isLeavingIntercept &&
+        !cached?.stale &&
         !options?._skipCache;
 
+      // Forward navigations always await fetchPartialUpdate before rendering,
+      // so useNavigation should always report "loading". skipLoadingState is
+      // only used for popstate background revalidation (line ~526) where
+      // cached content renders instantly without a network wait.
       const tx = createNavigationTransaction(store, eventController, url, {
         ...options,
         state: resolvedState,
-        skipLoadingState: hasUsableCache,
+        skipLoadingState: false,
       });
 
       // REVALIDATE: Fetch fresh data from server
@@ -200,7 +286,7 @@ export function createNavigationBridge(
         await fetchPartialUpdate(
           url,
           hasUsableCache
-            ? getNonLoaderSegmentIds(cachedSegments!)
+            ? cachedSegments!.map((s) => s.id)
             : options?._skipCache
               ? [] // Action redirect: send no segments so server renders everything fresh
               : undefined,
@@ -332,6 +418,15 @@ export function createNavigationBridge(
         eventController.abortAllActions();
       }
 
+      // Popstate that exits an intercept to a non-intercept destination. The
+      // fallback fetch path below needs `leave-intercept` mode so it filters
+      // the cached @modal segment from the request and forces a re-render —
+      // otherwise a cache-miss popstate whose server response has an empty
+      // diff hits the "no changes" branch in partial-update and the modal
+      // stays on screen.
+      const isLeavingIntercept =
+        !isIntercept && currentInterceptSource !== null;
+
       // Compute history key from URL (with intercept suffix if applicable)
       const historyKey = generateHistoryKey(url, { intercept: isIntercept });
 
@@ -368,6 +463,12 @@ export function createNavigationBridge(
         store.setCurrentUrl(url);
         store.setPath(new URL(url).pathname);
 
+        // Restore router identity from cache so subsequent navigations
+        // don't falsely detect an app switch.
+        if (cached?.routerId) {
+          store.setRouterId?.(cached.routerId);
+        }
+
         // Render from cache - force await to skip loading fallbacks
         try {
           const root = await renderSegments(cachedSegments, {
@@ -393,6 +494,7 @@ export function createNavigationBridge(
               cachedHandleData,
               params: cachedParams,
             },
+            scroll: { restore: true, isStreaming },
           };
           const hasTransition = cachedSegments.some((s) => s.transition);
           if (hasTransition) {
@@ -406,14 +508,11 @@ export function createNavigationBridge(
             onUpdate(popstateUpdate);
           }
 
-          // Restore scroll position for back/forward navigation
-          handleNavigationEnd({ restore: true, isStreaming });
-
           // SWR: If stale, trigger background revalidation
           if (isStale) {
             debugLog("[Browser] Cache is stale, background revalidating...");
             // Background revalidation - don't await, just fire and forget
-            const segmentIds = getNonLoaderSegmentIds(cachedSegments);
+            const segmentIds = cachedSegments.map((s) => s.id);
 
             const tx = createNavigationTransaction(
               store,
@@ -478,7 +577,11 @@ export function createNavigationBridge(
             intercept: isIntercept,
             interceptSourceUrl,
           }),
-          isIntercept ? { type: "navigate", interceptSourceUrl } : undefined,
+          isIntercept
+            ? { type: "navigate", interceptSourceUrl }
+            : isLeavingIntercept
+              ? { type: "leave-intercept" }
+              : undefined,
         );
         // Restore scroll position after fetch completes
         handleNavigationEnd({ restore: true, isStreaming });
@@ -555,6 +658,12 @@ export function createNavigationBridge(
         window.removeEventListener("pageshow", handlePageShow);
       };
     },
+
+    updateVersion(newVersion: string): void {
+      version = newVersion;
+      setAppVersion(newVersion);
+      store.clearHistoryCache();
+    },
   };
 }