@rangojs/router 0.0.0-experimental.14 → 0.0.0-experimental.140

package/skills/composability/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: composability
+description: Reusable composition patterns with globally importable route helpers in @rangojs/router
+argument-hint: "pattern-name"
+---
+
+# Composability
+
+Route helpers can be imported directly from `@rangojs/router` and used to build reusable composition factories. This enables sharing common route configurations across multiple routes and modules.
+
+## Globally Importable Helpers
+
+These helpers can be imported and called outside the `urls()` callback parameter:
+
+```typescript
+import {
+  layout,
+  cache,
+  middleware,
+  revalidate,
+  loader,
+  loading,
+  parallel,
+  intercept,
+  errorBoundary,
+  notFoundBoundary,
+} from "@rangojs/router";
+```
+
+They work because they use AsyncLocalStorage internally and resolve context at call time, not import time.
+
+## Why path() and include() Are Not Global
+
+`path()` and `include()` remain exclusive to the `urls()` callback:
+
+```typescript
+urls(({ path, include }) => [
+  path("/blog", BlogPage, { name: "blog" }),
+  include("/shop", shopPatterns, { name: "shop" }),
+]);
+```
+
+They define the route structure -- the URL patterns and how modules compose. Keeping them in the `urls()` callback makes the route tree readable at a glance. When scanning a URL file, `path()` and `include()` calls show what renders where. Moving them into factories would hide the routing structure and make it harder to understand which URLs exist and how they nest.
+
+The globally importable helpers (`cache`, `middleware`, `loading`, etc.) are configuration -- they modify behavior of routes but don't define routes themselves. Extracting them into factories doesn't obscure the route structure.
+
+## Composition Factories
+
+Define reusable factories that return arrays of use items:
+
+```typescript
+import { cache, revalidate, loading, errorBoundary, middleware } from "@rangojs/router";
+
+// Shared caching configuration
+const withCaching = () => [
+  cache({ ttl: 600_000 }),
+  // Defer on navigation (|| undefined) so each route keeps its own param/search
+  // revalidation default; only force a re-run when an action ran.
+  revalidate(({ actionId }) => (actionId ? true : undefined)),
+];
+
+// Shared loading and error handling
+const withLoadingAndError = (skeleton: ReactNode) => [
+  loading(skeleton),
+  errorBoundary(() => <div>Something went wrong</div>),
+];
+
+// Shared auth middleware
+const withAuth = () => [
+  middleware(authMiddleware),
+  middleware(loggingMiddleware),
+];
+```
+
+> **Factories compose logic, not just values.** A `revalidate()` predicate in a
+> shared factory applies its logic to _every_ route that composes it, so a
+> footgun here is amplified across the app. Two rules:
+>
+> 1. Use `|| undefined` (defer), not `?? false` (hard short-circuit), in shared
+>    predicates — a hard `false` ends the chain and overrides each consuming
+>    route's own default, and a downstream revalidator never runs. See `/loader`
+>    → "`|| undefined` (defer) vs `?? false` (hard)".
+> 2. Match actions with `ctx.isAction(Action)`, not an inline
+>    `actionId.includes("…")` buried in a factory: it resolves the action from an
+>    imported reference, so a rename is a compile error in one place instead of
+>    silent drift across every consumer.
+>
+> Remember the axis: a factory's `revalidate()` controls client-update
+> selection, while its `cache()` controls stored-value freshness. They are
+> independent even when bundled in the same factory (`/cache-guide` → "Two axes").
+
+> **Keep factories small and intention-named.** The anti-pattern that kills
+> readability is over-bundling — a `withDefaults()` that secretly adds five
+> things — and factory-of-factories nesting (leaning on `.flat(3)`). Surprising
+> config stays inline; extract only the boring, repeated parts; compose by
+> _naming concerns_ (`withAuth()`, `withCaching()`), not by hiding them.
+
+## Using Factories in Routes
+
+Place factory calls inside `path()` or `layout()` use callbacks. The returned arrays are flattened automatically (up to 3 levels):
+
+```typescript
+import { urls } from "@rangojs/router";
+import { withCaching, withLoadingAndError, withAuth } from "./route-config";
+
+export const urlpatterns = urls(({ path, layout }) => [
+  layout(<AppLayout />, () => [
+    withAuth(),
+
+    path("/blog", BlogIndex, { name: "blog" }, () => [
+      withCaching(),
+      withLoadingAndError(<BlogSkeleton />),
+    ]),
+
+    path("/shop", ShopIndex, { name: "shop" }, () => [
+      withCaching(),
+      withLoadingAndError(<ShopSkeleton />),
+    ]),
+  ]),
+]);
+```
+
+## Sharing Across Modules
+
+Factories can be defined in shared modules and reused across separate `urls()` definitions:
+
+```typescript
+// src/route-config.ts
+import { cache, revalidate, middleware } from "@rangojs/router";
+import { authMiddleware } from "./middleware/auth";
+
+export const withPublicDefaults = () => [
+  cache({ ttl: 300 }),
+  revalidate(({ actionId }) => (actionId ? true : undefined)),
+];
+
+export const withProtectedDefaults = () => [
+  middleware(authMiddleware),
+  cache({ ttl: 60 }),
+];
+```
+
+```typescript
+// src/urls/blog.ts
+import { urls } from "@rangojs/router";
+import { withPublicDefaults } from "../route-config";
+
+export const blogPatterns = urls(({ path }) => [
+  path("/", BlogIndex, { name: "index" }, () => [withPublicDefaults()]),
+]);
+```
+
+```typescript
+// src/urls/admin.ts
+import { urls } from "@rangojs/router";
+import { withProtectedDefaults } from "../route-config";
+
+export const adminPatterns = urls(({ path }) => [
+  path("/", AdminDashboard, { name: "index" }, () => [withProtectedDefaults()]),
+]);
+```
+
+## Code-splitting a route group with async include()
+
+`include()` takes a route module two ways. Eager — the module is already in the
+graph:
+
+```typescript
+import { shopPatterns } from "./shop-patterns";
+
+urls(({ include }) => [include("/shop", shopPatterns, { name: "shop" })]);
+```
+
+Async — the module is code-split behind a `() => import()` thunk. It becomes its
+own chunk that is NOT evaluated at startup; the router imports it on the first
+request that reaches the prefix, then caches it:
+
+```typescript
+urls(({ include }) => [
+  include("/shop", () => import("./shop-patterns"), { name: "shop" }),
+]);
+```
+
+The split module exposes its `urls()` value as the default export (convention):
+
+```typescript
+// src/shop-patterns.ts
+import { urls } from "@rangojs/router";
+
+export const shopPatterns = urls(({ path, include }) => [
+  path("/", ShopHome, { name: "home" }),
+  include("/product", productPatterns, { name: "product" }), // nesting is fine
+]);
+
+export default shopPatterns; // async include() resolves this
+```
+
+**Prefer the async form** for any route group that is a natural,
+independently-loadable unit (a localized section, an admin area, an API surface
+with heavy handlers) — it trims the eagerly-parsed entry bundle and keeps that
+subgraph off the cold-start path. The **eager form is still fully valid** (not
+deprecated): keep it for small groups, or ones that share most of their module
+graph with the entry (the bundler keeps shared modules common regardless, so
+splitting a thin group buys little). Both match identically at runtime — only the
+module's runtime evaluation timing differs.
+
+What you do NOT lose by splitting: build-time discovery `await`s the provider, so
+`href()`, `reverse()`, generated route types, and prerender still see every route
+in the group — including nested `include()`s inside the split module. Only the
+module's runtime evaluation defers. `rango generate` resolves the `() => import()`
+the same way, so a code-split group is still fully typed.
+
+## Composition Types
+
+For typed factories, import the composition types:
+
+```typescript
+import type { RouteUseItem, LayoutUseItem, UseItems } from "@rangojs/router";
+
+// Factory for path() use callbacks
+const withCaching = (): RouteUseItem[] => [
+  cache({ ttl: 600_000 }),
+];
+
+// Factory for layout() use callbacks
+const withAuth = (): LayoutUseItem[] => [
+  middleware(authMiddleware),
+];
+
+// Factory that nests other factories (use UseItems for nested arrays)
+const withEverything = (): UseItems<RouteUseItem> => [
+  withCaching(),
+  loading(<Skeleton />),
+];
+```
+
+- `RouteUseItem[]` -- flat array for `path()` use callbacks
+- `LayoutUseItem[]` -- flat array for `layout()` use callbacks
+- `UseItems<T>` -- allows nested arrays from composing factories together
+
+## Rules
+
+- Helpers execute lazily -- factory functions are defined anywhere, but only called inside a `urls()` context (within `path()` or `layout()` use callbacks)
+- Calling helpers outside a `urls()` context throws an error
+- Nested arrays from factories are flattened automatically via `.flat(3)`
+- `path()` and `include()` cannot be used in factories -- they define route structure and must remain visible in the `urls()` callback

package/skills/css/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: css
+description: Import and apply CSS in a Rango app. Render document/app stylesheets in the Document `<head>` with Vite's `?url` import plus a `precedence`-managed `<link rel="stylesheet">` (React 19 resource model — deduped, ordered, loaded before paint). Use when wiring global/app CSS or a Document `<head>` stylesheet, or when deciding between `?url` + `<link>` and side-effect imports. Cross-app (host-router) navigation is a full document load, so each app's document CSS is always re-established by its own load.
+argument-hint:
+---
+
+# CSS imports
+
+Document/app CSS in Rango lives in the Document `<head>`, loaded with Vite's
+`?url` import and a `precedence`-managed `<link rel="stylesheet">`. This page is
+the why and the one cross-app caveat; `/tailwind` is the concrete setup, `/theme`
+is dark mode, `/fonts` is fonts.
+
+## The pattern
+
+```tsx
+// document.tsx
+"use client";
+
+import type { ReactNode } from "react";
+import { MetaTags } from "@rangojs/router/client";
+import styles from "./index.css?url";
+
+export function Document({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <link rel="preload" href={styles} as="style" precedence="default" />
+        <link rel="stylesheet" href={styles} precedence="default" />
+        <MetaTags />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+- **`?url`** returns the processed file's hashed URL instead of injecting it as a
+  side effect, giving a stable asset path that works in dev and production.
+- **`precedence`** opts the `<link rel="stylesheet">` into React 19's managed
+  stylesheet model: React de-duplicates it by `href`, orders it by precedence
+  (any string value — it only decides cascade order relative to other managed
+  sheets), and loads it **before paint**, so there is no flash of unstyled
+  content. This is the recommended way to render a stylesheet link.
+
+## Cross-app (host-router) navigation
+
+You do **not** need to coordinate CSS across apps mounted under one host router.
+A client-side navigation that crosses an app boundary is a **full document load**
+(the server returns `X-RSC-Reload` on an app switch — see `/host-router`), so the
+target app's entire document — its stylesheets, theme, meta — is re-established
+by the target app's own load. Each app owns its document; how one app renders a
+stylesheet has no effect on another.
+
+(This replaced an earlier soft cross-app swap. Under it, a stylesheet shared
+across apps by `href` — classically every app's `@import "tailwindcss"` compiling
+to one hashed asset — could be silently dropped by React's by-`href` resource
+dedup when the apps disagreed on `precedence` (one unmanaged, one managed). The
+full reload removes that footgun entirely, which is the main reason cross-app
+navigation is a hard boundary.)
+
+## Side-effect imports vs `?url`
+
+A bare `import "./index.css"` (no `?url`, no `<link>`) also produces _managed_ CSS
+— `@vitejs/plugin-rsc` collects it via `import.meta.viteRsc.loadCss` and injects
+it with a precedence. It is fine for **component-local** CSS that loads with its
+client chunk. For **document-level** CSS, prefer the `?url` + `<link precedence>`
+form above: a side-effect import is not guaranteed to be in the initial streamed
+`<head>` (an SSR-streaming caveat), whereas the explicit `<link>` is.
+
+## Related
+
+- `/tailwind` — Tailwind v4 setup using this pattern.
+- `/host-router` — multi-app routing; why cross-app navigation is a full reload.
+- `/theme` — dark mode / theme attribute.
+- `/fonts` — self-hosted fonts via `@fontsource`.

package/skills/debug-manifest/SKILL.md

@@ -11,11 +11,12 @@ Inspect the route manifest to verify parent relationships, shortCodes, and route
 ## Quick Access
 
 In development, visit:
+
 ```
-http://localhost:PORT/__debug_manifest
+http://localhost:PORT/?__debug_manifest
 ```
 
-Returns formatted JSON with all routes and layouts.
+Returns formatted JSON. The HTTP endpoint shape is `{ routerId, routeManifest, routeAncestry, routeTrie, precomputedEntries }` (see below for the programmatic API shape).
 
 ## Programmatic Access
 
@@ -31,6 +32,8 @@ if (process.env.NODE_ENV !== "production") {
 
 ## Manifest Structure
 
+The programmatic `router.debugManifest()` call returns `{ routes, layouts, totalRoutes, totalLayouts }`:
+
 ```json
 {
   "routes": {
@@ -62,13 +65,13 @@ if (process.env.NODE_ENV !== "production") {
 
 ## ShortCode Format
 
-| Prefix | Meaning |
-|--------|---------|
-| **M** | Mount index (multiple `.routes()` calls) |
-| **L** | Layout |
-| **C** | Cache boundary |
-| **R** | Route |
-| **P** | Parallel slot |
+| Prefix | Meaning                                  |
+| ------ | ---------------------------------------- |
+| **M**  | Mount index (multiple `.routes()` calls) |
+| **L**  | Layout                                   |
+| **C**  | Cache boundary                           |
+| **R**  | Route                                    |
+| **P**  | Parallel slot                            |
 
 Example: `M0L0L1C0R0` = Mount 0 → Root Layout → Nested Layout → Cache → Route
 
@@ -85,7 +88,7 @@ Example: `M0L0L1C0R0` = Mount 0 → Root Layout → Nested Layout → Cache →
 import {
   serializeManifest,
   compareManifests,
-  formatManifestDiff
+  formatManifestDiff,
 } from "@rangojs/router/__internal";
 
 const oldManifest = await router.debugManifest();
@@ -99,10 +102,13 @@ console.log(formatManifestDiff(diff));
 ## Common Issues
 
 ### Routes have `parentShortCode: null`
+
 Routes should have a layout parent. Check that `urls()` handler is being wrapped in root layout.
 
 ### Missing layouts in hierarchy
+
 Verify `layout()` calls wrap child routes correctly.
 
 ### Wrong mount index
+
 Multiple `.routes()` calls create separate mounts (M0, M1, etc.). Use `include()` to share context.

package/skills/document-cache/SKILL.md

@@ -10,73 +10,82 @@ Caches complete HTTP responses (HTML/RSC) at the edge based on Cache-Control hea
 
 ## Setup
 
-Configure document cache in router:
+Document caching is a middleware. Add `createDocumentCacheMiddleware()` to the
+router with `.use()`. The cache store it reads from is the app-level store you
+configure on `createRouter({ cache })` (available on the request context as
+`requestCtx._cacheStore`), not a store passed to the middleware.
 
 ```typescript
 import { createRouter } from "@rangojs/router";
-import { CFCacheStore } from "@rangojs/router/cache/cf";
+import {
+  createDocumentCacheMiddleware,
+  CFCacheStore,
+} from "@rangojs/router/cache";
 import { urlpatterns } from "./urls";
 
-const router = createRouter<AppEnv>({
+const router = createRouter<AppBindings>({
   document: Document,
   urls: urlpatterns,
-  documentCache: (env) => ({
-    store: new CFCacheStore({ ctx: env.ctx }),
+  // App-level cache store. The document cache middleware uses this store's
+  // getResponse/putResponse methods.
+  cache: (_env, ctx) => ({ store: new CFCacheStore({ ctx: ctx! }) }),
+});
+
+router.use(
+  createDocumentCacheMiddleware({
     skipPaths: ["/api", "/admin"],
     debug: process.env.NODE_ENV === "development",
   }),
-});
+);
 
 export default router;
 ```
 
-## Route Opt-In with cache()
+## Route Opt-In with Cache-Control
 
-Routes opt-in to document caching using the `cache()` DSL with `documentCache` option:
+Routes opt-in to document caching by setting a `Cache-Control` response header
+with `s-maxage`. The middleware caches responses whose `Cache-Control` includes
+`s-maxage`; `stale-while-revalidate` enables background revalidation (SWR).
 
 ```typescript
-import { urls } from "@rangojs/router";
-
-export const urlpatterns = urls(({ path, cache }) => [
-  // Cache full page for 5 min, serve stale for 1 hour
-  cache({ documentCache: { sMaxAge: 300, swr: 3600 } }, () => [
-    path("/blog", BlogIndex, { name: "blog" }),
-  ]),
-
-  // Long cache for individual posts
-  cache({ documentCache: { sMaxAge: 3600, swr: 86400 } }, () => [
-    path("/blog/:slug", BlogPost, { name: "blogPost" }),
-  ]),
-
-  // No cache for dashboard (no documentCache option)
-  path("/dashboard", Dashboard, { name: "dashboard" }),
-]);
+// Cache full page for 5 min, serve stale for 1 hour
+function BlogIndexHandler(ctx) {
+  ctx.headers.set("Cache-Control", "s-maxage=300, stale-while-revalidate=3600");
+  return <BlogIndex />;
+}
+
+// Long cache for individual posts
+function BlogPostHandler(ctx) {
+  ctx.headers.set("Cache-Control", "s-maxage=3600, stale-while-revalidate=86400");
+  return <BlogPost />;
+}
+
+// Dashboard sets no Cache-Control header, so it is never document-cached.
 ```
 
 ## Document Cache Options
 
-```typescript
-createRouter({
-  // ...
-  documentCache: (env) => ({
-    // Cache store (required)
-    store: new CFCacheStore({ ctx: env.ctx }),
+`createDocumentCacheMiddleware(options?)` accepts:
 
-    // Skip specific paths
-    skipPaths: ["/api", "/admin"],
+```typescript
+createDocumentCacheMiddleware({
+  // Skip specific paths (matched by pathname prefix)
+  skipPaths: ["/api", "/admin"],
 
-    // Custom cache key
-    keyGenerator: (url) => url.pathname,
+  // Custom cache key generator
+  keyGenerator: (url) => url.pathname,
 
-    // Conditional caching
-    isEnabled: (ctx) => !ctx.request.headers.has("x-preview"),
+  // Conditional caching, evaluated per request
+  isEnabled: (ctx) => !ctx.request.headers.has("x-preview"),
 
-    // Debug logging
-    debug: true,
-  }),
+  // Debug logging (HIT, MISS, STALE, REVALIDATED)
+  debug: true,
 });
 ```
 
+The cache store is not a middleware option — it comes from the app-level
+`createRouter({ cache })` store.
+
 ## How It Works
 
 ```
@@ -89,7 +98,7 @@ Request → Check Cache
     ↓             ↓
   Fresh?      Run handler
     │             │
-   Yes → Return   Has documentCache?
+   Yes → Return   Has s-maxage?
     │             │
    No (stale)    Yes → Cache + Return
     │             │
@@ -102,6 +111,7 @@ Request → Check Cache
 ## Cache Status Header
 
 Response includes `x-document-cache-status`:
+
 - `HIT` - Fresh cache hit
 - `STALE` - Served stale, revalidating in background
 - `MISS` - Cache miss, response was generated fresh
@@ -109,6 +119,7 @@ Response includes `x-document-cache-status`:
 ## Cache Key Generation
 
 Default keys differentiate:
+
 - HTML requests: `{pathname}:html`
 - RSC partials: `{pathname}:{segmentHash}:rsc`
 
@@ -118,13 +129,14 @@ Segment hash ensures different cached responses for navigations from different s
 
 - Full HTML responses (document requests)
 - RSC payloads (client navigation)
-- Only 200 OK responses with documentCache enabled
+- Only 200 OK responses whose `Cache-Control` includes `s-maxage`
 
 ## What's NOT Cached
 
 - Server actions (`_rsc_action`)
 - Loader requests (`_rsc_loader`)
-- Routes without `documentCache` option
+- Non-GET requests
+- Responses without an `s-maxage` `Cache-Control` directive
 - Non-200 responses
 
 ## Complete Example
@@ -132,49 +144,62 @@ Segment hash ensures different cached responses for navigations from different s
 ```typescript
 // router.tsx
 import { createRouter } from "@rangojs/router";
-import { CFCacheStore } from "@rangojs/router/cache/cf";
+import { createDocumentCacheMiddleware, CFCacheStore } from "@rangojs/router/cache";
 import { urlpatterns } from "./urls";
 
-const router = createRouter<AppEnv>({
+const router = createRouter<AppBindings>({
   document: Document,
   urls: urlpatterns,
-  documentCache: (env) => ({
-    store: new CFCacheStore({ ctx: env.ctx }),
+  cache: (_env, ctx) => ({ store: new CFCacheStore({ ctx: ctx! }) }),
+});
+
+router.use(
+  createDocumentCacheMiddleware({
     skipPaths: ["/api"],
     debug: process.env.NODE_ENV === "development",
   }),
-});
+);
 
 export default router;
 
 // urls.tsx
 import { urls } from "@rangojs/router";
 
-export const urlpatterns = urls(({ path, layout, cache, loader }) => [
-  // Blog with document caching
-  cache({ documentCache: { sMaxAge: 300, swr: 3600 } }, () => [
-    layout(<BlogLayout />, () => [
-      path("/blog", BlogIndex, { name: "blog" }),
-      path("/blog/:slug", BlogPost, { name: "blogPost" }, () => [
-        loader(BlogPostLoader),
-      ]),
+export const urlpatterns = urls(({ path, layout, loader }) => [
+  // Blog pages opt into document caching via Cache-Control headers set in
+  // their handlers (see BlogIndex / BlogPost below).
+  layout(<BlogLayout />, () => [
+    path("/blog", BlogIndex, { name: "blog" }),
+    path("/blog/:slug", BlogPost, { name: "blogPost" }, () => [
+      loader(BlogPostLoader),
     ]),
   ]),
 
-  // Dashboard - no document cache (dynamic content)
+  // Dashboard sets no Cache-Control header, so it is never document-cached.
   layout(<DashboardLayout />, () => [
     path("/dashboard", Dashboard, { name: "dashboard" }),
   ]),
 ]);
+
+// Blog handlers set s-maxage to opt into the document cache.
+function BlogIndex(ctx) {
+  ctx.headers.set("Cache-Control", "s-maxage=300, stale-while-revalidate=3600");
+  return <BlogIndexPage />;
+}
+
+function BlogPost(ctx) {
+  ctx.headers.set("Cache-Control", "s-maxage=300, stale-while-revalidate=3600");
+  return <BlogPostPage />;
+}
 ```
 
 ## Document Cache vs Segment Cache
 
-| Feature | Document Cache | Segment Cache |
-|---------|---------------|---------------|
-| Granularity | Full response | Individual segments |
-| Opt-in | `documentCache` in cache() | `cache({ ttl, swr })` |
-| Use case | Static pages | Dynamic compositions |
-| Key includes | URL + segment hash | Route params |
+| Feature      | Document Cache             | Segment Cache         |
+| ------------ | -------------------------- | --------------------- |
+| Granularity  | Full response              | Individual segments   |
+| Opt-in       | `Cache-Control` `s-maxage` | `cache({ ttl, swr })` |
+| Use case     | Static pages               | Dynamic compositions  |
+| Key includes | URL + segment hash         | Route params          |
 
 Use document cache for mostly-static pages. Use segment cache when different parts of a page have different cache requirements.

package/skills/fonts/SKILL.md

@@ -24,7 +24,11 @@ export function Document({ children }: { children: ReactNode }) {
       <head>
         {/* Preconnect to Google Fonts */}
         <link rel="preconnect" href="https://fonts.googleapis.com" />
-        <link rel="preconnect" href="https://fonts.gstatic.com" crossOrigin="anonymous" />
+        <link
+          rel="preconnect"
+          href="https://fonts.gstatic.com"
+          crossOrigin="anonymous"
+        />
 
         {/* Load font stylesheet */}
         <link
@@ -37,9 +41,7 @@ export function Document({ children }: { children: ReactNode }) {
         <link rel="stylesheet" href={styles} />
         <MetaTags />
       </head>
-      <body>
-        {children}
-      </body>
+      <body>{children}</body>
     </html>
   );
 }