@rangojs/router 0.0.0-experimental.54a3dc6a → 0.0.0-experimental.56

package/skills/cache-guide/SKILL.md

@@ -162,6 +162,38 @@ middleware(async (ctx, next) => {
 });
 ```
 
+## Context Variable Cache Safety
+
+Context variables created with `createVar()` are cacheable by default and can
+be read freely inside `cache()` and `"use cache"` scopes. Non-cacheable vars
+throw at read time to prevent request-specific data from being captured.
+
+There are two ways to mark a value as non-cacheable:
+
+```typescript
+// Var-level policy — inherently request-specific data
+const Session = createVar<SessionData>({ cache: false });
+
+// Write-level escalation — this specific write is non-cacheable
+ctx.set(Theme, derivedTheme, { cache: false });
+```
+
+"Least cacheable wins": if either the var definition or the `ctx.set()` call
+specifies `cache: false`, the value is non-cacheable.
+
+**Behavior inside cache scopes:**
+
+| Operation                           | Inside `cache()` / `"use cache"` |
+| ----------------------------------- | -------------------------------- |
+| `ctx.get(cacheableVar)`             | Allowed                          |
+| `ctx.get(nonCacheableVar)`          | Throws                           |
+| `ctx.set(var, value)` (cacheable)   | Allowed                          |
+| `ctx.header()`, `ctx.cookie()`, etc | Throws (response side effects)   |
+
+Write is dumb — `ctx.set()` stores the cache metadata but does not enforce.
+Enforcement happens at read time (`ctx.get()`), where ALS detects the cache
+scope and rejects non-cacheable reads.
+
 ## Loaders Are Always Fresh
 
 Loaders are **never cached** by route-level `cache()`. Even on a full cache hit

package/skills/caching/SKILL.md

@@ -173,6 +173,14 @@ const router = createRouter<AppBindings>({
 KV entries require `expirationTtl >= 60s`. Short-lived entries (< 60s total TTL)
 are only cached in L1.
 
+## Context Variables Inside Cache Boundaries
+
+Context variables (`createVar`) are cacheable by default and can be read and
+written inside `cache()` scopes. Variables marked with `{ cache: false }` (at
+the var level or write level) throw when read inside a cache scope. Response
+side effects (`ctx.header()`, `ctx.cookie()`) always throw inside cache
+boundaries. See `/cache-guide` for the full cache safety table.
+
 ## Nested Cache Boundaries
 
 Override cache settings for specific sections:

package/skills/links/SKILL.md

@@ -139,7 +139,9 @@ function GlobalNav() {
 }
 ```
 
-`href()` is an identity function at runtime but provides compile-time validation via `ValidPaths` type. Paths are validated against registered route patterns using `PatternToPath`.
+`href()` provides compile-time validation via `ValidPaths` type. Paths are validated against registered route patterns using `PatternToPath`.
+
+`href()` is a raw path helper — it is **not** basename-aware. It returns the path as-is (or with the include mount prefix via `useHref()`). For basename-aware navigation, use `Link`, `useRouter().push()`, or `reverse()`, which auto-prefix root-relative paths with the router's basename.
 
 ## Client: useHref()
 

package/skills/loader/SKILL.md

@@ -65,24 +65,10 @@ export const urlpatterns = urls(({ path, loader }) => [
 
 ## Consuming Loader Data
 
-Loaders are the **live data layer** — they resolve fresh on every request.
-The way you consume them depends on whether you're in a server component
-(route handler) or a client component.
-
-> **IMPORTANT: Prefer consuming loaders in client components.** Keeping data
-> fetching in loaders and consumption in client components creates a clean
-> separation: the server-side handler renders static markup that can be
-> freely cached with `cache()`, while loader data stays fresh on every
-> request. When you consume loaders in server handlers via `ctx.use()`, the
-> handler output depends on the loader data, which means caching the handler
-> also caches the data — defeating the purpose of the live data layer.
-
-### In Client Components (Preferred)
-
-Client components use `useLoader()` from `@rangojs/router/client`.
-The loader **must** be registered with `loader()` in the route's DSL
-segments so the framework knows to resolve it during SSR and stream
-the data to the client:
+Register loaders with `loader()` in the DSL and consume them in client
+components with `useLoader()`. This is the recommended pattern — it keeps
+data fetching on the server and consumption on the client, with a clean
+separation that works correctly with `cache()`.
 
 ```typescript
 "use client";
@@ -96,40 +82,60 @@ function ProductDetails() {
 ```
 
 ```typescript
-// Route definition — loader() registration required for client consumption
+// Route definition — loader() registration required
 path("/product/:slug", ProductPage, { name: "product" }, () => [
-  loader(ProductLoader), // Required for useLoader() in client components
+  loader(ProductLoader),
 ]);
 ```
 
-### In Route Handlers (Server Components)
+DSL loaders are the **live data layer** — they resolve fresh on every
+request, even when the route is inside a `cache()` boundary. The router
+excludes them from the segment cache at storage time and re-resolves them
+on retrieval. This means `cache()` gives you cached UI + fresh data by
+default.
 
-In server components, use `ctx.use(Loader)` directly in the route handler.
-This doesn't require `loader()` registration in the DSL — it works
-standalone. **However**, prefer client-side consumption when possible (see
-note above).
+### Cache safety
 
-```typescript
-import { ProductLoader } from "./loaders/product";
+DSL loaders can safely read `createVar({ cache: false })` variables
+because they are always resolved fresh. The read guard is bypassed for
+loader functions — they never produce stale data.
+
+### ctx.use(Loader) — escape hatch
+
+For cases where you need loader data in the server handler itself (e.g.,
+to set ctx variables or make routing decisions), use `ctx.use(Loader)`:
 
-// Route handler — server component
+```typescript
 path("/product/:slug", async (ctx) => {
   const { product } = await ctx.use(ProductLoader);
-  return <h1>{product.name}</h1>;
-}, { name: "product" })
+  ctx.set(Product, product); // make available to children
+  return <ProductPage />;
+}, { name: "product" }, () => [
+  loader(ProductLoader), // still register for client consumption
+])
 ```
 
-When you do register with `loader()` in the DSL, `ctx.use()` returns the
+When you register with `loader()` in the DSL, `ctx.use()` returns the
 same memoized result — loaders never run twice per request.
 
+**Limitations of ctx.use(Loader):**
+
+- The handler output depends on the loader data. If the route is inside
+  `cache()`, the handler is cached with the loader result baked in —
+  defeating the live data guarantee.
+- Non-cacheable variable reads (`createVar({ cache: false })`) inside the
+  handler still throw, even if the data came from a loader.
+- Prefer DSL `loader()` + client `useLoader()` for data that depends on
+  non-cacheable context variables.
+
 **Never use `useLoader()` in server components** — it is a client-only API.
 
 ### Summary
 
-| Context                      | API                 | `loader()` DSL required? |
-| ---------------------------- | ------------------- | ------------------------ |
-| Client component (preferred) | `useLoader(Loader)` | **Yes**                  |
-| Route handler (server)       | `ctx.use(Loader)`   | No                       |
+| Pattern                | API                 | Cache-safe | Recommended |
+| ---------------------- | ------------------- | ---------- | ----------- |
+| DSL + client component | `useLoader(Loader)` | Yes        | Yes         |
+| Handler escape hatch   | `ctx.use(Loader)`   | No         | When needed |
 
 ## Loader Context
 
@@ -548,7 +554,7 @@ export const ProductLoader = createLoader(async (ctx) => {
     .first();
 
   if (!product) {
-    throw new Response("Product not found", { status: 404 });
+    notFound("Product not found");
   }
 
   return { product };
@@ -564,10 +570,9 @@ export const CartLoader = createLoader(async (ctx) => {
   return { cart };
 });
 
-// urls.tsx
+// urls.tsx — register loaders in the DSL
 export const urlpatterns = urls(({ path, layout, loader, loading, cache, revalidate }) => [
   layout(<ShopLayout />, () => [
-    // Shared cart loader for all shop routes
     loader(CartLoader, () => [
       revalidate(({ actionId }) => actionId?.includes("Cart") ?? false),
     ]),
@@ -579,17 +584,22 @@ export const urlpatterns = urls(({ path, layout, loader, loading, cache, revalid
   ]),
 ]);
 
-// pages/product.tsx — server component (route handler)
+// components/ProductDetails.tsx — consume in client component
+"use client";
+import { useLoader } from "@rangojs/router/client";
 import { ProductLoader, CartLoader } from "./loaders/shop";
 
-async function ProductPage(ctx) {
-  const { product } = await ctx.use(ProductLoader);
-  const { cart } = await ctx.use(CartLoader);
+function ProductDetails() {
+  const { data: { product } } = useLoader(ProductLoader);
+  const { data: { cart } } = useLoader(CartLoader);
 
   return (
     <div>
       <h1>{product.name}</h1>
-      <AddToCartButton productId={product.id} inCart={cart?.items.includes(product.id)} />
+      <AddToCartButton
+        productId={product.id}
+        inCart={cart?.items.includes(product.id)}
+      />
     </div>
   );
 }

package/skills/middleware/SKILL.md

@@ -26,6 +26,8 @@ const router = createRouter<AppEnv>({})
   .routes(urlpatterns);
 ```
 
+When the router has a `basename`, pattern-scoped `.use()` patterns are automatically prefixed. For example, with `basename: "/app"`, `.use("/admin/*", mw)` matches `/app/admin/*`.
+
 ### Route middleware (`middleware()` in `urls()`)
 
 Registered inside `urls()` callback. Wraps **rendering only** -- it does NOT wrap server action execution. Actions run before route middleware, so when route middleware executes during post-action revalidation, it can observe state that the action set (cookies, context variables, headers).

package/skills/parallel/SKILL.md

@@ -92,6 +92,73 @@ path("/dashboard/:id", (ctx) => {
 ])
 ```
 
+## Setting Handles (Meta, Breadcrumbs)
+
+Parallel slot handlers can call `ctx.use(Meta)` or `ctx.use(Breadcrumbs)` to
+push handle data. The data is associated with the **parent** layout or route
+segment, not the parallel segment itself. This is because parallels execute
+after their parent handler and inherit its segment scope.
+
+This works well for document-level metadata — the handle data follows the
+parent's lifecycle (appears when the parent is mounted, removed when it
+unmounts).
+
+```typescript
+parallel({
+  "@meta": (ctx) => {
+    const meta = ctx.use(Meta);
+    meta({ title: "Product Detail" });
+    meta({ name: "description", content: "..." });
+    return null; // UI-less slot, only sets metadata
+  },
+  "@sidebar": (ctx) => <Sidebar />,
+})
+```
+
+Multiple parallels on the same parent can each push handle data — they all
+accumulate under the parent segment ID.
+
+### Pattern: `@meta` slot for per-route metadata overrides
+
+A dedicated `@meta` parallel slot lets routes define metadata separately from
+their handler logic. The layout sets defaults via a title template, and each
+route overrides via its own `@meta` slot. Since child segments push after
+parents and `collectMeta` uses last-wins deduplication, overrides work
+naturally.
+
+```typescript
+// Layout sets defaults
+layout((ctx) => {
+  ctx.use(Meta)({ title: { template: "%s | Store", default: "Store" } });
+  return <StoreLayout />;
+}, () => [
+  // Route with @meta override — decoupled from handler rendering
+  path("/:slug", ProductPage, { name: "product" }, () => [
+    parallel({
+      "@meta": async (ctx) => {
+        const product = await ctx.use(ProductLoader);
+        const meta = ctx.use(Meta);
+        meta({ title: product.name });
+        meta({ name: "description", content: product.description });
+        meta({
+          "script:ld+json": {
+            "@context": "https://schema.org",
+            "@type": "Product",
+            name: product.name,
+            description: product.description,
+          },
+        });
+        return null; // UI-less slot
+      },
+    }),
+  ]),
+])
+```
+
+This keeps the route handler focused on rendering UI while metadata
+(title, description, Open Graph, JSON-LD) lives in a composable slot that
+can be added, removed, or swapped per route without touching the handler.
+
 ## Parallel Routes with Loaders
 
 Add loaders and loading states to parallel routes:

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

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

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/navigation-bridge.ts

@@ -4,6 +4,7 @@ import type {
   NavigateOptionsInternal,
   ResolvedSegment,
 } from "./types.js";
+import { setAppVersion } from "./app-version.js";
 import * as React from "react";
 import { startTransition } from "react";
 import {
@@ -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 {
@@ -447,6 +448,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, {
@@ -632,6 +639,12 @@ export function createNavigationBridge(
         window.removeEventListener("pageshow", handlePageShow);
       };
     },
+
+    updateVersion(newVersion: string): void {
+      version = newVersion;
+      setAppVersion(newVersion);
+      store.clearHistoryCache();
+    },
   };
 }