@rangojs/router 0.0.0-experimental.bd6e11bc → 0.0.0-experimental.bdaf10aa

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:
 ---
 
@@ -33,6 +33,48 @@ export default {
 };
 ```
 
+## Deploying: Cloudflare vs node/vercel
+
+How a host router is _served_ depends on the preset, because the preset decides who owns the server entry.
+
+| Preset            | Who owns the entry          | What the host module exports                                                                                |
+| ----------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `cloudflare`      | You (your `worker.rsc.tsx`) | `export default { fetch(request, env, ctx) { return router.match(request, { env, ctx }); } }`               |
+| `node` / `vercel` | rango (generated RSC entry) | `export default router;` (the `HostRouter` instance itself), or a named `export const hostRouter`/`router`. |
+
+On `node`/`vercel`, rango generates the served RSC entry, so it needs the `HostRouter` **instance** to call `hostRouter.match()` for you. Export the instance, not a `{ fetch }` object:
+
+```typescript
+// src/worker.rsc.tsx  (node / vercel)
+import { createHostRouter } from "@rangojs/router/host";
+
+export const hostRouter = createHostRouter();
+hostRouter.host(["admin.*"]).lazy(() => import("./apps/admin/handler.js"));
+hostRouter.host(["."]).lazy(() => import("./apps/site/handler.js"));
+
+// Export the instance — the generated entry serves it via hostRouter.match().
+export default hostRouter;
+```
+
+Each sub-app exports a handler exactly as on Cloudflare (no change):
+
+```typescript
+// src/apps/admin/handler.ts
+import { router } from "./router.js";
+export default (request: Request, input: any) => router.fetch(request, input);
+```
+
+Selecting the host entry — a host app has several `createRouter()` sub-apps, so single-router auto-discovery can't pick one. Either let rango auto-detect the lone `createHostRouter()` file, or point at it explicitly:
+
+```typescript
+// vite.config.ts
+rango({ preset: "vercel", hostRouter: "./src/worker.rsc.tsx" });
+```
+
+On Vercel this is a single function running `hostRouter.match()` for every request (mirrors the Cloudflare single-worker model); `{ env, ctx }` (`process.env` + `{ waitUntil }`) is threaded unchanged to each matched sub-app's handler and `cache(env, ctx)` factory. See the `vercel` skill.
+
+Unmatched hosts on node/vercel: because rango owns the generated entry (you have no worker `try/catch`), it catches `NoRouteMatchError` and returns **404** by default — so you do **not** need a catch-all host route. If you want different behavior (a branded 404, a redirect, a default app), register a catch-all mount as the **last** route, e.g. `host(["**"]).lazy(() => import("./apps/site/handler.js"))` — it matches any host, so the built-in 404 only fires when nothing matched at all. (Note `fallback()` is for cookie-override errors, not general unmatched hosts.)
+
 ## Inline handlers (`.map`) vs lazy mounts (`.lazy`)
 
 A host pattern maps to one of two things, and you pick the method by intent:
@@ -66,7 +108,7 @@ Why two methods instead of one overloaded `.map()`:
 | `.` or `*`        | Any apex domain (`example.com`)                |
 | `**`              | Any domain (apex + all subdomains)             |
 | `*.`              | Any single-level subdomain (`www.example.com`) |
-| `**. `            | Any multi-level subdomain (`a.b.example.com`)  |
+| `**.`             | Any multi-level subdomain (`a.b.example.com`)  |
 | `example.com`     | Exact domain                                   |
 | `*.com`           | Any apex `.com` domain                         |
 | `*.example.com`   | Single subdomain of `example.com`              |
@@ -134,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;
@@ -189,12 +231,26 @@ Logs pattern matching, route registration, and cookie override decisions to cons
 ## Testing
 
 ```typescript
-import { createTestRequest, testPattern } from "@rangojs/router/host/testing";
+import {
+  createTestRequest,
+  testPattern,
+  matchesHost,
+} from "@rangojs/router/host/testing";
 
-// Test pattern matching
+// Test pattern matching (host-only)
 testPattern("admin.*", "admin.example.com"); // true
 testPattern([".", "www.*"], "example.com"); // true
 
+// Path-based patterns need the third pathname arg (defaults to "/", so a
+// host-only pattern still works with two args):
+testPattern("**.workers.dev/admin", "foo.workers.dev", "/admin"); // true
+
+// Or match a pattern against a real Request (hostname + pathname from the URL):
+matchesHost(
+  "**.workers.dev/admin",
+  new Request("https://foo.workers.dev/admin"),
+); // true
+
 // Create requests for integration tests
 const request = createTestRequest({
   host: "admin.example.com",
@@ -241,3 +297,24 @@ export default regional;
 // host-router.ts
 router.host(["**.regional.example.com"]).lazy(() => import("./apps/regional"));
 ```
+
+## Cross-app navigation is a full document load
+
+A client-side navigation that crosses an app boundary (e.g. a `<Link>` or
+intercepted `<a>` from the app at `/` into an app mounted at `/shop`) is a **hard
+document navigation**, not a soft in-tree swap. When the server sees a partial
+(SPA) request whose router id doesn't match the matched app, it returns
+`X-RSC-Reload` and the client does a real document navigation to the target.
+
+Why a reload rather than a soft swap: a soft swap can't faithfully re-establish
+the target app's **document-level** state. Stylesheets shared across apps are
+dropped by React 19's by-`href` resource dedup; and theme, warmup, and
+prefetch-TTL are document-lifetime (captured once at load — see
+`browser/app-shell.ts`), so the target app's config would never take effect. A
+full document load re-establishes the target app's entire document — CSS, theme,
+meta, everything — by construction. So you do **not** need to coordinate
+stylesheet `href`s, `precedence`, theme config, etc. across independently-authored
+apps; each app owns its own document.
+
+**Within-app** navigation is unchanged — a normal soft SPA update (the document
+stays mounted). Only crossing an app boundary triggers the reload.

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
@@ -23,7 +30,7 @@ function ShopLayout() {
   );
 }
 
-export const urlpatterns = urls(({ path, layout, intercept, loader }) => [
+export const urlpatterns = urls(({ path, layout, intercept, loader, loading }) => [
   layout(<ShopLayout />, () => [
     // Intercept product detail - shows modal during soft navigation
     intercept(
@@ -107,8 +114,10 @@ Use named revalidation contracts on both the outer producer and the intercept
 consumer when they share `ctx.set()` data:
 
 ```typescript
-export const revalidateProductShell = ({ actionId }) =>
-  actionId?.includes("src/actions/product.ts#") || undefined;
+import * as ProductActions from "./actions/product";
+
+export const revalidateProductShell = (ctx) =>
+  ctx.isAction(ProductActions) || undefined;
 
 layout(ProductLayout, () => [
   revalidate(revalidateProductShell), // producer reruns
@@ -140,18 +149,41 @@ layout(ProductLayout, () => [
 ]);
 ```
 
-## Conditional Intercept with when()
+## Conditional Intercept with the `when` config
 
-Only intercept based on navigation context:
+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),
+  ]
+)
+```
+
+`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),
   ]
 )
@@ -240,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)],
+  ),
 ])
 ```
 
@@ -251,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:
 
@@ -303,7 +338,6 @@ export const shopPatterns = urls(({
   intercept,
   loader,
   loading,
-  when,
 }) => [
   layout(<ShopLayout />, () => [
     parallel({
@@ -315,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()]),
@@ -336,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) => {