@rangojs/router 0.0.0-experimental.e9c0b2f2 → 0.0.0-experimental.ea9f40f2

package/skills/hooks/state.md

@@ -0,0 +1,228 @@
+# State and Cache Control Hooks
+
+## State Hooks
+
+### useLocationState()
+
+Read type-safe state from history:
+
+```tsx
+"use client";
+import { useLocationState, createLocationState } from "@rangojs/router/client";
+
+// Define typed state (all export patterns supported)
+// Keys are auto-injected by the Vite plugin -- no manual key needed.
+export const ProductState = createLocationState<{
+  name: string;
+  price: number;
+}>();
+
+// Also valid: const ProductState = createLocationState<...>();
+//             export { ProductState };
+// Also valid: export { ProductState as MyState };
+
+function ProductHeader() {
+  const state = useLocationState(ProductState);
+  // { name: string; price: number } | undefined
+
+  if (state) {
+    return (
+      <h1>
+        {state.name} - ${state.price}
+      </h1>
+    );
+  }
+  return <h1>Loading...</h1>;
+}
+```
+
+Pass state through Link:
+
+```tsx
+import { Link } from "@rangojs/router/client";
+import { ProductState } from "./state";
+
+<Link to="/product/123" state={[ProductState({ name: "Widget", price: 99 })]}>
+  View Product
+</Link>;
+```
+
+Pass typed state just in time (getter evaluated at click time, not render time):
+
+```tsx
+"use client"; // JIT state requires a client component (getter can't cross RSC boundary)
+
+import { Link } from "@rangojs/router/client";
+import { ProductState } from "./state";
+
+// The getter is stored lazily and only called when the user clicks the link.
+// This is useful for capturing values that change after render (e.g., scroll
+// position, form state, ref values).
+<Link
+  to="/product/123"
+  state={[ProductState(() => ({ name: product.name, price: product.price }))]}
+>
+  View Product
+</Link>;
+```
+
+Plain state can also be evaluated just in time (also requires a client component):
+
+```tsx
+<Link to="/product/123" state={() => ({ from: window.location.pathname })}>
+  View Product
+</Link>
+```
+
+### Flash State (read-once)
+
+Create a location state with `{ flash: true }` for read-once state that
+auto-clears after first render. Ideal for flash messages (success/error
+notifications after redirect):
+
+```tsx
+// location-states.ts
+import { createLocationState } from "@rangojs/router";
+
+export const FlashMessage = createLocationState<{ text: string }>({
+  flash: true,
+});
+```
+
+Read flash state with `useLocationState` (same hook as persistent state):
+
+```tsx
+"use client";
+import { useLocationState } from "@rangojs/router/client";
+import { FlashMessage } from "../location-states";
+
+function FlashBanner() {
+  const flash = useLocationState(FlashMessage);
+  // { text: string } | undefined
+
+  if (!flash) return null;
+  return <div className="flash">{flash.text}</div>;
+}
+```
+
+Flash behavior is determined by the definition (`{ flash: true }`), not by which
+hook reads it. `useLocationState` reads the value synchronously during render,
+then clears it from `history.state` via `replaceState` in a `useEffect`.
+Multiple components reading the same flash definition all see the value.
+Pressing back/forward will not re-show the flash since it was cleared.
+
+Set flash state from the server via `redirect()` with state:
+
+```tsx
+// In a route handler
+import { redirect, createLocationState } from "@rangojs/router";
+
+export const FlashMessage = createLocationState<{ text: string }>({
+  flash: true,
+});
+
+// Handler
+(ctx) => {
+  return redirect("/dashboard", {
+    state: [FlashMessage({ text: "Item saved!" })],
+  });
+};
+```
+
+Or via `ctx.setLocationState()` on any response:
+
+```tsx
+(ctx) => {
+  ctx.setLocationState(FlashMessage({ text: "Welcome back!" }));
+  return <Dashboard />;
+};
+```
+
+### .read() (non-hook access)
+
+Read current location state outside React components (client-side only):
+
+```tsx
+import { FlashMessage, ProductState } from "../location-states";
+
+// Returns TState | undefined. Returns undefined during SSR.
+const flash = FlashMessage.read();
+const product = ProductState.read();
+```
+
+> **Hydration:** `.read()` returns `undefined` on the server but may return
+> a real value on the first client render (history state survives reload).
+> Do not call `.read()` directly during the initial render of a component;
+> call it from an event handler or inside a `useEffect` post-mount. For
+> reactive hydration-safe access, use `useLocationState()` instead.
+
+### .write() / .delete() (static, non-reactive)
+
+Static counterparts to `.read()`. Both mutate the current history entry's
+`history.state` via `replaceState`, preserving any other keys (router
+bookkeeping, other location state slots). Both are client-only; they throw
+when called on the server.
+
+Neither dispatches an event, so components reading via `useLocationState`
+will NOT re-render until the next navigation/popstate. Pair with `.read()`
+(or a fresh mount via back/forward/reload) instead.
+
+```tsx
+"use client";
+import { ProductState } from "./state";
+
+// Persisted across hard refresh and back/forward of this entry.
+ProductState.write({ name: "Widget", price: 9.99 });
+
+// Read later (or on next mount).
+const current = ProductState.read();
+
+// Manually clear the slot. Idempotent if it isn't set.
+ProductState.delete();
+```
+
+| Method      | Updates `history.state` | Fires `useLocationState` rerender | SSR behavior        |
+| ----------- | ----------------------- | --------------------------------- | ------------------- |
+| `.read()`   | no                      | n/a (returns snapshot)            | returns `undefined` |
+| `.write()`  | yes (replace this slot) | no                                | throws              |
+| `.delete()` | yes (remove this slot)  | no                                | throws              |
+
+## Cache Control
+
+### invalidateClientCache()
+
+Force the client's caches to miss after a mutation the router can't see (a REST
+call, a WebSocket push, a login). It is a plain function, not a hook, so it works
+from module-level callbacks too. Imported from the root entry `@rangojs/router`,
+it is selected by export conditions: in a client component it marks the caches
+stale immediately; from a handler/server component it writes a rotated
+`Set-Cookie` for the responding client.
+
+```tsx
+"use client";
+import { invalidateClientCache } from "@rangojs/router";
+
+function SaveButton() {
+  const handleSave = async () => {
+    await fetch("/api/data", {
+      method: "POST",
+      body: JSON.stringify(data),
+    });
+
+    // Invalidate the client's caches after the mutation
+    invalidateClientCache();
+  };
+
+  return <button onClick={handleSave}>Save</button>;
+}
+```
+
+A module-level subscription works the same way (no component needed):
+
+```ts
+import { invalidateClientCache } from "@rangojs/router";
+
+socket.on("catalog-updated", () => invalidateClientCache());
+```
+
+**Use cases**: REST API mutations, WebSocket updates, non-RSC data changes.

package/skills/hooks/urls.md

@@ -0,0 +1,135 @@
+# URL Hooks
+
+### useParams()
+
+Access route params from the current URL:
+
+```tsx
+"use client";
+import { useParams } from "@rangojs/router/client";
+
+// Route: /product/:productId
+function ProductPage() {
+  const params = useParams();
+  // { productId: "123" }
+
+  return <h1>Product {params.productId}</h1>;
+}
+
+// Annotate the expected shape via a generic
+function ProductPageTyped() {
+  const { productId } = useParams<{ productId: string }>();
+  return <h1>Product {productId}</h1>;
+}
+
+// With selector for performance (re-renders only when selected value changes)
+function ProductId() {
+  const productId = useParams((p) => p.productId);
+  return <span>ID: {productId}</span>;
+}
+```
+
+Returns merged params from all matched route segments as a `Readonly<T>` map. Updates on navigation commit (not during pending navigation).
+
+### usePathname()
+
+Access the current URL pathname:
+
+```tsx
+"use client";
+import { usePathname } from "@rangojs/router/client";
+
+function CurrentPage() {
+  const pathname = usePathname();
+  // "/product/123" (no search params)
+
+  return <span>Current path: {pathname}</span>;
+}
+```
+
+Returns the pathname string without search params or hash. Updates on navigation commit.
+
+### useSearchParams()
+
+Access the current URL search params:
+
+```tsx
+"use client";
+import { useSearchParams } from "@rangojs/router/client";
+
+function SearchResults() {
+  const searchParams = useSearchParams();
+  const query = searchParams.get("q"); // "react"
+  const page = searchParams.get("page"); // "2"
+
+  return (
+    <div>
+      Searching for: {query}, page {page}
+    </div>
+  );
+}
+```
+
+Returns a `ReadonlyURLSearchParams` (URLSearchParams without mutation methods). During SSR, returns empty params and syncs from the browser URL on mount.
+
+### useHref()
+
+Mount-aware href for client components inside `include()` scopes:
+
+```tsx
+"use client";
+import { useHref, href, Link } from "@rangojs/router/client";
+
+// Inside include("/shop", shopPatterns)
+function ShopNav() {
+  const href = useHref();
+
+  return (
+    <>
+      {/* Local paths - auto-prefixed with /shop */}
+      <Link to={href("/cart")}>Cart</Link>
+      <Link to={href("/product/widget")}>Widget</Link>
+    </>
+  );
+}
+```
+
+Use `useHref()` for local navigation. Use the bare `href()` function for absolute paths.
+
+### useMount()
+
+Returns the current `include()` mount path:
+
+```tsx
+"use client";
+import { useMount } from "@rangojs/router/client";
+
+function MountInfo() {
+  const mount = useMount(); // "/shop" inside include("/shop", ...)
+  return <span>Mounted at: {mount}</span>;
+}
+```
+
+### useReverse(routes)
+
+Mount-aware local reverse for client components. Import the generated `routes` map from a `urls()` module's `.gen.ts` and call `reverse("name", params?)` — the leading dot is optional. Auto-fills params from `useParams()`; explicit params override.
+
+> Per-module `*.gen.ts` files are **CLI opt-in and not Vite-watched** — run `rango generate <urls-file>` (or wire it into `predev`) and re-run it whenever the module's routes change. See `/links` for the full generated-file setup and exposure-boundary rules.
+
+```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 (
+    <nav>
+      <Link to={reverse("index")}>Blog</Link>
+      <Link to={reverse("post", { postId: "hello" })}>Post</Link>
+    </nav>
+  );
+}
+```
+
+See `/links` for the full URL generation guide. `ctx.reverse()` is server-only; on the client, prefer `useReverse(routes)` for in-module names and pass URLs as props for cross-module ones.

package/skills/host-router/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: host-router
-description: Multi-app host routing with domain/subdomain patterns
+description: Multi-app host routing with domain/subdomain patterns. Use when running multiple apps behind one domain or across subdomains, or routing requests to different apps based on hostname.
 argument-hint:
 ---
 
@@ -176,17 +176,17 @@ router.fallback().map((request) => {
 });
 ```
 
-For unmatched hosts without `hostOverride`, catch `NoRouteMatchError` in your worker fetch:
+For unmatched hosts without `hostOverride`, catch `NoRouteMatchError` in your worker fetch. Use the `isNoRouteMatchError()` guard rather than a bare `instanceof`: a workspace with a duplicated `@rangojs/router` copy can throw the error with a different class identity, and `instanceof` would then turn the 404 into an opaque 500.
 
 ```typescript
-import { NoRouteMatchError } from "@rangojs/router/host";
+import { isNoRouteMatchError } from "@rangojs/router/host";
 
 export default {
   async fetch(request: Request, env: Env, ctx: ExecutionContext) {
     try {
       return await router.match(request, { env, ctx });
     } catch (err) {
-      if (err instanceof NoRouteMatchError) {
+      if (isNoRouteMatchError(err)) {
         return new Response("Not Found", { status: 404 });
       }
       throw err;

package/skills/i18n/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: i18n
-description: Locale-aware routing with `include("/:locale?", ...)`, locale resolution chains, and react-intl integration
+description: Locale-aware routing with `include("/:locale?", ...)`, locale resolution chains, and react-intl integration. Use when building a multi-language app, routes need a locale segment, or wiring up react-intl translations.
 argument-hint: "[topic]"
 ---
 

package/skills/intercept/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: intercept
-description: Define intercept routes for modals, slide-overs, and soft navigation patterns in @rangojs/router
+description: Define intercept routes for modals, slide-overs, and soft navigation patterns in @rangojs/router. Use when opening a route as a modal/overlay on top of the current page while keeping the URL shareable, or asking "how do I show this page in a modal".
 argument-hint: [@slot-name] [route-to-intercept]
 ---
 
@@ -8,6 +8,13 @@ argument-hint: [@slot-name] [route-to-intercept]
 
 Intercept routes render a different component during soft navigation (client-side) while preserving the background route. Hard navigation (direct URL) shows the full page.
 
+## Not this skill if…
+
+- You want a slot that ALWAYS renders alongside the page (sidebar, multi-column
+  layout) — that is a permanent `parallel()` slot: see `/parallel`.
+- You want the same component regardless of soft vs hard navigation —
+  intercepts only swap on soft navigation; see `/parallel`.
+
 ## Basic Intercept
 
 ```typescript
@@ -142,18 +149,41 @@ layout(ProductLayout, () => [
 ]);
 ```
 
-## Conditional Intercept with when()
+## Conditional Intercept with the `when` config
+
+Only intercept based on navigation context. `when` is the 4th argument
+(an `InterceptConfig` object); the other use-items go in the 5th-argument
+callback.
+
+```typescript
+intercept(
+  "@modal",
+  "product",
+  <ProductModal />,
+  // Only intercept when coming from a different section
+  { when: ({ from }) => !from.pathname.startsWith("/shop/product/") },
+  () => [
+    loader(ProductLoader),
+  ]
+)
+```
 
-Only intercept based on navigation context:
+`when` is a match-time selector receiving `{ from, to, params, segments, ... }`.
+Pass an array of predicates for AND logic (all must return true). Omit `when`
+entirely and the intercept always activates.
 
 ```typescript
 intercept(
   "@modal",
   "product",
   <ProductModal />,
+  {
+    when: [
+      ({ from }) => from.pathname.startsWith("/shop"),
+      ({ params }) => params.slug !== "featured",
+    ],
+  },
   () => [
-    // Only intercept when coming from a different section
-    when(({ from }) => !from.pathname.startsWith("/shop/product/")),
     loader(ProductLoader),
   ]
 )
@@ -242,10 +272,13 @@ layout(ShopLayout, () => [
   ]),
 
   // This intercept is also pre-rendered at build time
-  intercept("@modal", ".detail", <ProductModal />, () => [
-    when(({ from }) => from.pathname.startsWith("/shop")),
-    loader(ProductLoader),
-  ]),
+  intercept(
+    "@modal",
+    ".detail",
+    <ProductModal />,
+    { when: ({ from }) => from.pathname.startsWith("/shop") },
+    () => [loader(ProductLoader)],
+  ),
 ])
 ```
 
@@ -253,8 +286,8 @@ Build-time behavior:
 
 - The intercept handler (`<ProductModal />`) is resolved with BuildContext
 - Result is stored under the key `"detail/paramHash/i"` (intercept variant)
-- `when()` conditions are skipped at build time (all intercepts pre-rendered unconditionally)
-- `when()` is still evaluated at runtime by the intercept-resolution middleware
+- `when` config conditions are skipped at build time (all intercepts pre-rendered unconditionally)
+- `when` is still evaluated at runtime by the intercept-resolution middleware
 
 Runtime behavior:
 
@@ -305,7 +338,6 @@ export const shopPatterns = urls(({
   intercept,
   loader,
   loading,
-  when,
 }) => [
   layout(<ShopLayout />, () => [
     parallel({
@@ -317,8 +349,8 @@ export const shopPatterns = urls(({
       "@modal",
       "product",  // Route name (without prefix)
       <ProductModalContent />,
+      { when: ({ from }) => !from.pathname.startsWith("/shop/product/") },
       () => [
-        when(({ from }) => !from.pathname.startsWith("/shop/product/")),
         layout(<ModalWrapper />),
         loading(<ProductModalSkeleton />),
         loader(ProductLoader, () => [cache()]),
@@ -338,7 +370,7 @@ export const shopPatterns = urls(({
 
 ## Handler-attached `.use`
 
-Intercept handlers can carry their own middleware, loaders, loading state, error/notFound boundaries, and even nested `layout`/`route`/`when` defaults via `.use` — useful for self-contained modal components that travel with their own data and chrome.
+Intercept handlers can carry their own middleware, loaders, loading state, error/notFound boundaries, and even nested `layout`/`route` defaults via `.use` — useful for self-contained modal components that travel with their own data and chrome. (Conditional activation is set via the `when` config on the mount-site `intercept()` call, not inside `.use`.)
 
 ```typescript
 const QuickViewModal: Handler = async (ctx) => {

package/skills/layout/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: layout
-description: Define layout routes that wrap child routes in @rangojs/router
+description: Define layout routes that wrap child routes in @rangojs/router. Use when sharing a persistent UI shell (nav, sidebar) across nested routes, or asking how to wrap child pages with a common layout.
 argument-hint: [component]
 ---
 
@@ -147,12 +147,21 @@ A layout as a child of `path()` wraps the route content and can read
 data set by the route handler via `ctx.get()`. The handler always
 executes before its children.
 
-This handler-first guarantee applies to a single full render pass
-(initial render, prerender, or full HTML re-render). During partial
-action revalidation, only the segments that revalidate are recomputed.
-If an orphan layout depends on data established by an outer handler or
-layout, that outer segment must also revalidate, or the orphan must
-guard/reload the data independently.
+This is the recommended way to pass handler data downward, and it is
+safe under partial action revalidation with zero configuration: orphan
+layouts (and their parallels) belong to the route entry, and on an
+action the whole entry re-runs together by default — route segment,
+loaders, and `belongsToRoute` children all seed revalidate-true, with
+handler-first ordering preserved. Producer and consumer cannot desync
+unless you narrow one side with a predicate that returns a hard `false`
+(then put the same contract on both — see "Revalidation Contracts").
+
+Data from an **outer** handler or layout entry is the opposite case:
+outer entries do not revalidate on actions by default (parent-chain
+skip). If an orphan layout depends on data established above its own
+route entry, that outer segment must share a revalidation contract, or
+the orphan must guard/reload the data independently. See `/rango` →
+"Passing data down the tree" for the full safest-first ladder.
 
 ```typescript
 import { Outlet, ParallelOutlet } from "@rangojs/router/client";
@@ -191,7 +200,10 @@ orphan layouts to read them.
 
 ## Layout Revalidation
 
-Layouts don't revalidate by default. Control with `revalidate()`:
+Standalone `layout()` entries don't revalidate by default — on an action,
+parent-chain segments are skipped unless a `revalidate()` opts them in.
+(Orphan layouts inside a `path()` are the opposite: they ride along with
+the route entry by default.) Control with `revalidate()`:
 
 ```typescript
 layout(<ShopLayout />, () => [
@@ -218,8 +230,13 @@ their `ctx.set()` state.
 
 ### Revalidation Contracts
 
-For shared upstream data, define named revalidation functions and reuse
-them on both producer and consumer segments:
+Contracts are the tool for cross-entry sharing — the bottom rung of the
+data-passing ladder (`/rango` → "Passing data down the tree"). Before
+writing one, check whether the producer can move down a rung: into the
+consumer's own entry as an orphan layout, into middleware, or into a
+loader. When the data genuinely must flow from an outer entry, define
+named revalidation functions and reuse them on both producer and
+consumer segments:
 
 ```typescript
 // revalidation-contracts.ts

package/skills/links/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: links
-description: URL generation with ctx.reverse (server default), href (client), useHref (mounted), useMount, useReverse, and scopedReverse
+description: URL generation with ctx.reverse (server default), href (client), useHref (mounted), useMount, useReverse, and scopedReverse. Use when generating a link to a route by name instead of hardcoding a path, or a link breaks after routes move or get mounted elsewhere.
 argument-hint: [ctx.reverse|href|useHref|useMount|useReverse|scopedReverse]
 ---
 

package/skills/loader/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: loader
-description: Define data loaders for fetching data in routes with createLoader
+description: Define data loaders for fetching data in routes with createLoader. Use when pages need per-request data that stays fresh, data should stream while the page renders, or client components need reactive server data.
 argument-hint: [loader]
 ---
 
@@ -11,6 +11,13 @@ Loaders fetch data on the server and stream it to the client. For mutations
 `/server-actions`. Loaders re-resolve after an action runs, so the typical
 flow is _action mutates → loader re-reads → UI updates_.
 
+## Not this skill if…
+
+- You want to mutate state — mutations are `"use server"` actions: see
+  `/server-actions`. Loaders read per-request live data.
+- You want to cache a function's return value — loaders are fresh every request
+  by default; caching one function is `"use cache"`: see `/use-cache`.
+
 ## Creating a Loader
 
 ```typescript
@@ -140,6 +147,11 @@ same memoized result — loaders never run twice per request.
 - 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.
+- The same holds under a PPR shell capture (`/ppr`): handler consumption is
+  the BAKED lane — the loader executes at capture (identity reads permitted)
+  and the rendered value is a capture-time copy; `useLoader` client-side is
+  the live lane. One rule across `cache()`, `"use cache"`, and PPR: the
+  consumption-lane rule (`/rango` → Invariants).
 - 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
@@ -671,6 +683,16 @@ export const SearchLoader = createLoader(async (ctx) => {
 }, true); // true = fetchable
 ```
 
+> **No registration needed — and no worker-entry import.** A fetchable loader
+> does not have to be registered with `loader()` in the route DSL, and it does
+> not have to be imported by any server module. Importing it into the client
+> component that calls `useFetchLoader()` / `load()` is enough. Rango discovers
+> every `createLoader(fn, true)` at build time and registers it for the
+> `_rsc_loader` endpoint, so a loader reachable only through a client component
+> still resolves in production — on both the generated entry and a hand-written
+> worker entry (e.g. a Cloudflare `worker.rsc.tsx`). You do **not** need to
+> force-import the loader in your worker entry to make it resolve.
+
 ### Fetchable Loader with Middleware
 
 Pass an options object instead of `true` to attach per-loader middleware.

package/skills/middleware/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: middleware
-description: Define middleware for authentication, logging, and request processing in @rangojs/router
+description: Define middleware for authentication, logging, and request processing in @rangojs/router. Use when gating routes behind auth checks, logging requests, or running shared logic before a handler runs.
 argument-hint: [middleware-name]
 ---
 
@@ -60,8 +60,12 @@ data itself.
 ### Revalidation Contracts with Middleware-Backed Trees
 
 Middleware can establish request-level context (`ctx.set`) for segments that
-execute in the current render pass. It does not change partial revalidation
-boundaries between handler/layout/parallel segments.
+execute in the current render pass. Because route middleware wraps **every**
+render pass — normal renders, post-action revalidation, PE re-renders — its
+variables are never stale: middleware is the safest `ctx.set` rung on the
+data-passing ladder (`/rango` → "Passing data down the tree"). But it does
+not change partial revalidation boundaries between handler/layout/parallel
+segments.
 
 For shared segment data, use named revalidation contracts on both the producer
 and consumer segments, even when middleware is present in the chain.