@rangojs/router 0.0.0-experimental.1b930379 → 0.0.0-experimental.1db96a9e

package/skills/caching/SKILL.md

@@ -120,9 +120,9 @@ const store = new MemorySegmentCacheStore({
 });
 ```
 
-### Cloudflare KV Store
+### Cloudflare Edge Cache Store
 
-For distributed caching on Cloudflare Workers:
+For distributed caching on Cloudflare Workers using the Cache API:
 
 ```typescript
 import { CFCacheStore } from "@rangojs/router/cache";
@@ -132,14 +132,55 @@ const router = createRouter<AppBindings>({
   urls: urlpatterns,
   cache: (env, ctx) => ({
     store: new CFCacheStore({
-      kv: env.CACHE_KV,
-      waitUntil: (fn) => ctx!.waitUntil(fn),
+      ctx,
+      defaults: { ttl: 60, swr: 300 },
     }),
     enabled: true,
   }),
 });
 ```
 
+### With KV L2 Persistence
+
+Add a KV namespace for global cross-colo persistence. On Cache API miss, KV is
+checked and hits are promoted back to L1. Writes go to both layers.
+
+```typescript
+import { CFCacheStore } from "@rangojs/router/cache";
+
+const router = createRouter<AppBindings>({
+  document: Document,
+  urls: urlpatterns,
+  cache: (env, ctx) => ({
+    store: new CFCacheStore({
+      ctx,
+      kv: env.CACHE_KV, // optional KV namespace binding
+      defaults: { ttl: 60, swr: 300 },
+    }),
+    enabled: true,
+  }),
+});
+```
+
+**How the two layers work:**
+
+| Scenario     | L1 (Cache API) | L2 (KV) | Result                        |
+| ------------ | -------------- | ------- | ----------------------------- |
+| Hot request  | HIT            | —       | Serve from L1 (fast)          |
+| Cold colo    | MISS           | HIT     | Serve from KV, promote to L1  |
+| First render | MISS           | MISS    | Render, write to both L1 + KV |
+
+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:
@@ -109,6 +176,65 @@ parallel(
 )
 ```
 
+### Streaming Behavior
+
+Parallels with `loading()` are **independent streaming units**. They don't
+block the parent layout or sibling routes during SSR:
+
+- **With `loading()`**: The skeleton renders immediately. The loader runs
+  in the background and streams data to the client when ready. The rest
+  of the page (layout, route content, other parallels) renders without
+  waiting.
+- **Without `loading()`**: The parallel's loaders block the parent layout's
+  rendering. Use this when the data must be available before the page
+  paints (e.g., critical above-the-fold content).
+- **SPA navigation**: Parallel loaders resolve in the background. The
+  existing parallel UI stays visible — no skeleton flash on route changes
+  within the same layout.
+
+```typescript
+// Sidebar streams independently — page renders immediately
+parallel(
+  { "@sidebar": () => <Sidebar /> },
+  () => [loader(SlowSidebarLoader), loading(<SidebarSkeleton />)]
+)
+
+// Cart data blocks layout — must be ready before paint
+parallel(
+  { "@cartBadge": () => <CartBadge /> },
+  () => [loader(CartCountLoader)]  // No loading() = awaited
+)
+```
+
+## Slot Override Semantics
+
+When multiple `parallel()` calls define the same slot name, **the last
+definition wins**. Earlier definitions of that slot are removed. Other
+slots from the earlier call are preserved.
+
+This enables composition patterns where included routes override
+parent-defined slots:
+
+```typescript
+layout(DashboardLayout, () => [
+  // Base slots
+  parallel({
+    "@sidebar": () => <DefaultSidebar />,
+    "@footer": () => <Footer />,
+  }),
+
+  // Override just @sidebar — @footer is preserved
+  parallel({ "@sidebar": () => <CustomSidebar /> }),
+
+  path("/", DashboardIndex, { name: "index" }),
+])
+```
+
+After resolution, the layout has two parallel entries:
+
+- `{ "@footer": () => <Footer /> }` (first call, `@sidebar` removed)
+- `{ "@sidebar": () => <CustomSidebar /> }` (second call, wins)
+
 ## Multiple Parallel Slots
 
 ```typescript