@rangojs/router 0.0.0-experimental.ede38110 → 0.0.0-experimental.f2d1a2f1

package/dist/vite/plugins/cloudflare-protocol-loader-hook.mjs

@@ -0,0 +1,76 @@
+// Node ESM loader hook that resolves `cloudflare:*` imports to the same
+// stub ESM the Vite transform produces for rewritten specifiers.
+//
+// Why both? The Vite transform (cloudflare-protocol-stub.ts) catches
+// imports in modules that flow through Vite's plugin pipeline — covers
+// user source and any node_modules package Vite fetches and transforms.
+// But Vite/Rollup externalize certain packages (e.g. `partyserver`,
+// which has `import { DurableObject, env } from "cloudflare:workers"`
+// at its top level, and similar "workerd-native" libraries). Externalized
+// modules bypass the transform: Rollup hands their resolution to Node's
+// native ESM loader, which rejects URL-scheme specifiers. This loader
+// hook registers via `module.register()` from `createTempRscServer` and
+// intercepts `cloudflare:*` at Node's resolve layer — before the default
+// loader throws ERR_UNSUPPORTED_ESM_URL_SCHEME.
+//
+// Lifecycle: the hook runs in a dedicated worker thread (Node ESM loader
+// architecture) with its own globalThis. It cannot see the main thread's
+// `__rango_build_env__` bridge, so the `env` export here is always `{}`.
+// That's fine in practice — externalized libraries don't typically touch
+// `env` at module top level; they read it at request time in workerd
+// where the real module exists. Build-time prerender handlers in user
+// source DO read `env`, but they flow through the Vite transform (which
+// does bridge `env` from `getPlatformProxy()`), not through this loader.
+//
+// Keep STUBS in sync with cloudflare-protocol-stub.ts — both paths need
+// to hand out the same base classes.
+
+const CF_PREFIX = "cloudflare:";
+
+const STUBS = {
+  "cloudflare:workers": `
+export class DurableObject { constructor(_ctx, _env) {} }
+export class WorkerEntrypoint { constructor(_ctx, _env) {} }
+export class WorkflowEntrypoint { constructor(_ctx, _env) {} }
+export class RpcTarget {}
+export const env = {};
+export default {};
+`,
+  "cloudflare:email": `
+export class EmailMessage { constructor(_from, _to, _raw) {} }
+export default {};
+`,
+  "cloudflare:sockets": `
+export function connect() { return {}; }
+export default {};
+`,
+  "cloudflare:workflows": `
+export class NonRetryableError extends Error {
+  constructor(message, name) { super(message); this.name = name ?? "NonRetryableError"; }
+}
+export default {};
+`,
+};
+
+// Policy: unknown `cloudflare:*` specifiers resolve permissively to an
+// empty default export rather than throwing. Same reasoning as
+// cloudflare-protocol-stub.ts's FALLBACK_STUB — we prioritize
+// dependency-graph resilience over strict validation, because third-party
+// packages can pull `cloudflare:*` modules we haven't curated.
+const FALLBACK_STUB = `export default {};\n`;
+
+function dataUrlFor(specifier) {
+  const body = STUBS[specifier] ?? FALLBACK_STUB;
+  return "data:text/javascript;base64," + Buffer.from(body).toString("base64");
+}
+
+export async function resolve(specifier, context, nextResolve) {
+  if (specifier.startsWith(CF_PREFIX)) {
+    return {
+      shortCircuit: true,
+      url: dataUrlFor(specifier),
+      format: "module",
+    };
+  }
+  return nextResolve(specifier, context);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.ede38110",
+  "version": "0.0.0-experimental.f2d1a2f1",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -133,9 +133,9 @@
     "tag": "experimental"
   },
   "scripts": {
-    "build": "pnpm dlx esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && pnpm dlx esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
+    "build": "pnpm dlx esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm dlx esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
     "prepublishOnly": "pnpm build",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit",
     "test": "playwright test",
     "test:ui": "playwright test --ui",
     "test:unit": "vitest run",
@@ -143,12 +143,14 @@
   },
   "dependencies": {
     "@vitejs/plugin-rsc": "^0.5.23",
+    "debug": "^4.4.1",
     "magic-string": "^0.30.17",
     "picomatch": "^4.0.3",
     "rsc-html-stream": "^0.0.7"
   },
   "devDependencies": {
     "@playwright/test": "^1.49.1",
+    "@types/debug": "^4.1.12",
     "@types/node": "^24.10.1",
     "@types/react": "catalog:",
     "@types/react-dom": "catalog:",

package/skills/breadcrumbs/SKILL.md

@@ -141,9 +141,11 @@ path("/dashboard", (ctx) => {
   breadcrumb({ label: "Dashboard", href: "/dashboard" });
   return <DashboardNav handle={Breadcrumbs} />;
 });
+```
 
+```tsx
 // Client component
-("use client");
+"use client";
 import { useHandle, type Breadcrumbs } from "@rangojs/router/client";
 
 function DashboardNav({ handle }: { handle: typeof Breadcrumbs }) {

package/skills/hooks/SKILL.md

@@ -298,9 +298,11 @@ path("/dashboard", (ctx) => {
   push({ label: "Dashboard", href: "/dashboard" });
   return <DashboardNav handle={Breadcrumbs} />;
 });
+```
 
+```tsx
 // Client component — typeof infers the full Handle<T> type
-("use client");
+"use client";
 import { useHandle, type Breadcrumbs } from "@rangojs/router/client";
 
 function DashboardNav({ handle }: { handle: typeof Breadcrumbs }) {
@@ -593,6 +595,12 @@ function ProductPage() {
   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);
@@ -600,7 +608,7 @@ function ProductId() {
 }
 ```
 
-Returns merged params from all matched route segments. Updates on navigation commit (not during pending navigation).
+Returns merged params from all matched route segments as a `Readonly<T>` map. Updates on navigation commit (not during pending navigation).
 
 ### usePathname()
 
@@ -681,24 +689,24 @@ function MountInfo() {
 }
 ```
 
-See `/links` for full URL generation guide including server-side `ctx.reverse`.
+See `/links` for full URL generation guide. The default server API is `ctx.reverse()`; in client components, receive URLs as props, loader data, or server-action return values — `reverse()` is not available in the browser.
 
 ## Hook Summary
 
-| Hook                 | Purpose                           | Returns                                         |
-| -------------------- | --------------------------------- | ----------------------------------------------- |
-| `useParams()`        | Route params                      | `Record<string, string>` or selected value      |
-| `usePathname()`      | Current pathname                  | `string`                                        |
-| `useSearchParams()`  | URL search params                 | `ReadonlyURLSearchParams`                       |
-| `useHref()`          | Mount-aware href                  | `(path) => string`                              |
-| `useMount()`         | Current include() mount path      | `string`                                        |
-| `useNavigation()`    | Reactive navigation state         | state, location, isStreaming                    |
-| `useRouter()`        | Stable router actions             | push, replace, refresh, prefetch, back, forward |
-| `useSegments()`      | URL path & segment IDs            | path, segmentIds, location                      |
-| `useLinkStatus()`    | Link pending state                | { pending }                                     |
-| `useLoader()`        | Loader data (strict)              | data, isLoading, error                          |
-| `useFetchLoader()`   | Loader with on-demand fetch       | data, load, isLoading                           |
-| `useHandle()`        | Accumulated handle data           | T (handle type)                                 |
-| `useAction()`        | Server action state               | state, error, result                            |
-| `useLocationState()` | History state (persists or flash) | T \| undefined                                  |
-| `useClientCache()`   | Cache control                     | { clear }                                       |
+| Hook                 | Purpose                           | Returns                                                            |
+| -------------------- | --------------------------------- | ------------------------------------------------------------------ |
+| `useParams()`        | Route params                      | `Readonly<T>` (default `Record<string, string>`) or selected value |
+| `usePathname()`      | Current pathname                  | `string`                                                           |
+| `useSearchParams()`  | URL search params                 | `ReadonlyURLSearchParams`                                          |
+| `useHref()`          | Mount-aware href                  | `(path) => string`                                                 |
+| `useMount()`         | Current include() mount path      | `string`                                                           |
+| `useNavigation()`    | Reactive navigation state         | state, location, isStreaming                                       |
+| `useRouter()`        | Stable router actions             | push, replace, refresh, prefetch, back, forward                    |
+| `useSegments()`      | URL path & segment IDs            | path, segmentIds, location                                         |
+| `useLinkStatus()`    | Link pending state                | { pending }                                                        |
+| `useLoader()`        | Loader data (strict)              | data, isLoading, error                                             |
+| `useFetchLoader()`   | Loader with on-demand fetch       | data, load, isLoading                                              |
+| `useHandle()`        | Accumulated handle data           | T (handle type)                                                    |
+| `useAction()`        | Server action state               | state, error, result                                               |
+| `useLocationState()` | History state (persists or flash) | T \| undefined                                                     |
+| `useClientCache()`   | Cache control                     | { clear }                                                          |

package/skills/links/SKILL.md

@@ -1,16 +1,20 @@
 ---
 name: links
-description: URL generation with ctx.reverse (server), href (client), useHref (mounted), useMount, and scopedReverse
-argument-hint: [href|useHref|useMount|scopedReverse]
+description: URL generation with ctx.reverse (server default), href (client), useHref (mounted), useMount, and scopedReverse
+argument-hint: [ctx.reverse|href|useHref|useMount|scopedReverse]
 ---
 
 # Links & URL Generation
 
 @rangojs/router provides different href APIs for server and client contexts.
 
+**Default server API: `ctx.reverse()`.** Generate URLs from the handler context — it's typed, auto-fills mount params, and resolves local (`.name`) and absolute (`name.sub`) names.
+
+**`reverse()` is server-only.** It depends on the route manifest and handler context, neither of which are available in the browser. Client components receive URLs as props, loader data, or server-action return values — they never call `reverse` directly.
+
 ## Server: ctx.reverse()
 
-Available in route handlers via HandlerContext. Resolves named routes using the full route map.
+Available in route handlers via HandlerContext. Resolves named routes using the full route map. This is the default way to generate URLs on the server.
 
 ```typescript
 import { urls, scopedReverse } from "@rangojs/router";
@@ -103,7 +107,7 @@ path("/search", (ctx) => {
 
 ### scopedReverse() - type-safe ctx.reverse
 
-Wraps `ctx.reverse` with local route type information for autocomplete and validation:
+Wraps `ctx.reverse` with local route type information for autocomplete and validation. Runtime behavior is identical to `ctx.reverse` — `scopedReverse` is a type-only cast. The same dot-prefix rule applies: local names use `.name`, global names use `name.sub`.
 
 ```typescript
 import { scopedReverse } from "@rangojs/router";
@@ -111,18 +115,83 @@ import { scopedReverse } from "@rangojs/router";
 path("/product/:slug", (ctx) => {
   const reverse = scopedReverse<typeof shopPatterns>(ctx.reverse);
 
-  reverse("cart");                        // Type-safe local name
-  reverse("product", { slug: "widget" }); // Type-safe with params
-  reverse("blog.post");                   // Absolute names (dot notation) always allowed
-  reverse("/about");                      // Path-based always allowed
+  reverse(".cart");                        // Local name (dot-prefixed) — resolves in include scope
+  reverse(".product", { slug: "widget" }); // Local name with params
+  reverse("blog.post", { slug: "hi" });    // Global name (dotted) — full route map
 
   return <ProductPage slug={ctx.params.slug} />;
 }, { name: "product" })
 ```
 
+`reverse()` does not accept raw path strings (`"/about"`). For static paths in client components, use `href("/about")`; on the server, look up the route by name.
+
+## Client components: receive URLs as props
+
+`reverse()` is not available inside `"use client"` modules — there is no handler context and no route manifest in the browser bundle. Generate the URL on the server and hand it to the client component.
+
+Three patterns, in order of preference:
+
+1. Pass as a prop from a server component:
+
+```tsx
+// server
+function BlogPostPage(ctx: HandlerContext) {
+  return <ShareButton url={ctx.reverse(".post", { slug: ctx.params.slug })} />;
+}
+```
+
+```tsx
+"use client";
+
+export function ShareButton({ url }: { url: string }) {
+  return (
+    <button onClick={() => navigator.clipboard.writeText(url)}>Share</button>
+  );
+}
+```
+
+2. Return from a loader (attached to the route via the DSL):
+
+```tsx
+// server — loaders/nav.ts
+export const NavLoader = createLoader((ctx) => ({
+  home: ctx.reverse("home"),
+  blog: ctx.reverse("blog.index"),
+}));
+
+// server — urls.tsx: attach the loader so useLoader has data in context
+const urlpatterns = urls(({ path, loader }) => [
+  path("/", HomePage, { name: "home" }, () => [loader(NavLoader)]),
+]);
+```
+
+```tsx
+"use client";
+
+function Nav() {
+  const { data } = useLoader(NavLoader);
+  return <Link to={data.home}>Home</Link>;
+}
+```
+
+`useLoader()` requires the loader to be attached to an active route. If you need on-demand fetching instead, use `useFetchLoader()`.
+
+3. Return from a server action:
+
+```tsx
+"use server";
+
+export async function getProductUrl(slug: string) {
+  const ctx = getRequestContext();
+  return ctx.reverse("product", { slug });
+}
+```
+
+For static path strings (not named routes), client components can use `href()` — see below.
+
 ## Client: href()
 
-Plain function for absolute path-based URLs. No hook needed - works anywhere.
+Plain function for absolute path-based URLs. No hook needed - works anywhere in client components. `href()` validates paths at compile time, but does **not** resolve named routes — for named routes, use one of the patterns above.
 
 ```typescript
 "use client";
@@ -187,13 +256,16 @@ function MountInfo() {
 
 ## When to use what
 
-| Context          | API                             | Resolves                        | Use for                             |
-| ---------------- | ------------------------------- | ------------------------------- | ----------------------------------- |
-| Server handler   | `ctx.reverse("name")`           | Named routes (local + absolute) | Server-side URL generation          |
-| Server handler   | `scopedReverse<T>(ctx.reverse)` | Same, with type safety          | Type-safe server URLs               |
-| Client component | `href("/path")`                 | Absolute paths                  | Global navigation                   |
-| Client component | `useHref()`                     | Mount-prefixed paths            | Local navigation inside `include()` |
-| Client component | `useMount()`                    | Raw mount path                  | Custom mount-aware logic            |
+| Context          | API                                                | Resolves                        | Use for                                                          |
+| ---------------- | -------------------------------------------------- | ------------------------------- | ---------------------------------------------------------------- |
+| Server handler   | `ctx.reverse("name")`                              | Named routes (local + absolute) | **Default** server-side URL generation                           |
+| Server handler   | `scopedReverse<T>(ctx.reverse)`                    | Same, with type safety          | Type-safe server URLs                                            |
+| Client component | (URL passed as prop / loader data / action return) | Named routes                    | Any URL derived from a named route — generate on server, pass in |
+| Client component | `href("/path")`                                    | Absolute paths (static strings) | Static navigation where no named-route lookup is needed          |
+| Client component | `useHref()`                                        | Mount-prefixed paths            | Local navigation inside `include()`                              |
+| Client component | `useMount()`                                       | Raw mount path                  | Custom mount-aware logic                                         |
+
+> `reverse()` is server-only. Client components never import or call it — they receive the already-resolved string.
 
 ## Complete example: mounted module
 

package/skills/loader/SKILL.md

@@ -139,7 +139,29 @@ same memoized result — loaders never run twice per request.
 
 ## Loader Context
 
-Loaders receive the same context as route handlers:
+Loaders receive the same context shape as route handlers.
+
+### Full field surface
+
+| Field          | Type                           | Notes                                                                                               |
+| -------------- | ------------------------------ | --------------------------------------------------------------------------------------------------- |
+| `params`       | `TParams`                      | Merged route + explicit loader params; overridable by fetchable `load({ params })`.                 |
+| `routeParams`  | `Record<string, string>`       | Server-trusted route params from URL pattern matching; cannot be overridden.                        |
+| `request`      | `Request`                      | The incoming `Request` (headers, method, body, `signal` for abort).                                 |
+| `url`          | `URL`                          | Parsed request URL.                                                                                 |
+| `pathname`     | `string`                       | URL pathname (shortcut for `ctx.url.pathname`).                                                     |
+| `searchParams` | `URLSearchParams`              | Shortcut for `ctx.url.searchParams`.                                                                |
+| `search`       | `ResolveSearchSchema<TSearch>` | Typed query params when a search schema is declared on the route; `{}` otherwise.                   |
+| `env`          | `TEnv`                         | Plain bindings from `createRouter<TEnv>()` (DB, KV, secrets, etc.).                                 |
+| `get`          | `(key \| ContextVar) => value` | Reads variables/context-vars set by middleware.                                                     |
+| `use`          | `(loader \| handle) => T`      | Access another loader's data (Promise) or a handle's collected data (after `await ctx.rendered()`). |
+| `rendered`     | `() => Promise<void>`          | **Experimental.** DSL loaders only — waits for non-loader segments before reading handle data.      |
+| `method`       | `string`                       | HTTP method. `"GET"` for SSR loader runs; reflects real method for fetchable loaders.               |
+| `body`         | `TBody \| undefined`           | Parsed request body for fetchable POST/PUT/PATCH/DELETE calls.                                      |
+| `formData`     | `FormData \| undefined`        | Present when a fetchable loader is invoked via form submission.                                     |
+| `reverse`      | `ScopedReverseFunction`        | Generate type-checked URLs from route names (same scoped semantics as route handlers).              |
+
+### Example
 
 ```typescript
 export const ProductLoader = createLoader(async (ctx) => {
@@ -163,10 +185,21 @@ export const ProductLoader = createLoader(async (ctx) => {
   // Variables set by middleware (from RSCRouter.Vars augmentation)
   const user = ctx.get("user");
 
-  return { product: await fetchProduct(slug) };
+  // Type-checked URLs for payloads. `.name` resolves within the current
+  // include() scope; a bare `name` resolves globally. See /route and
+  // /typesafety for scope rules and route-name autocomplete.
+  const detailUrl = ctx.reverse(".detail", { slug });
+
+  return {
+    product: await fetchProduct(slug),
+    links: { self: detailUrl },
+  };
 });
 ```
 
+See `/route` for the full handler-context contract (shared with loaders) and
+`/typesafety` for route-name typing that powers `ctx.reverse` autocomplete.
+
 ### params vs routeParams
 
 - `ctx.params` — merged route params + explicit loader params. For fetchable

package/skills/migrate-react-router/SKILL.md

@@ -635,6 +635,7 @@ layout(<ShopLayout />, () => [
 | `useLocation().pathname`                  | `usePathname()` from `@rangojs/router/client`                                    |
 | `useSearchParams()`                       | `useSearchParams()` from `@rangojs/router/client`                                |
 | `useParams()`                             | `useParams()` from `@rangojs/router/client` (or `ctx.params` in server handlers) |
+| `useParams<T>()`                          | `useParams<T>()` — same generic annotation pattern                               |
 | `<NavLink>`                               | `<Link>` with `usePathname()` for active state                                   |
 
 ### useNavigate → useRouter

package/skills/response-routes/SKILL.md

@@ -400,6 +400,14 @@ path(
 Multiple response types can share the same URL pattern. See `/mime-routes` for the
 full content negotiation API (Accept header matching, Vary: Accept, multi-variant routes).
 
+## Long-Lived Responses (SSE / WebSocket)
+
+For Server-Sent Events (`path.stream`) and WebSocket upgrades (`path.any`
+returning a 101 / `webSocket` Response), see `/streams-and-websockets`.
+Upgrade responses flow through without reconstruction; `Vary` and
+`Server-Timing` are skipped, and stub headers are applied in place on a
+best-effort basis.
+
 ## How It Works
 
 1. `path.json()` tags the route at the trie level with a MIME type