@rangojs/router 0.0.0-experimental.259 → 0.0.0-experimental.25dbaac3

package/skills/streams-and-websockets/SKILL.md

@@ -0,0 +1,283 @@
+---
+name: streams-and-websockets
+description: Long-lived Response handlers — Server-Sent Events (SSE) via path.stream and WebSocket upgrades via path.any on Cloudflare Workers, including middleware interaction and runtime caveats.
+argument-hint: "[sse | websocket | agents]"
+---
+
+# Streams and WebSockets
+
+Response routes can return long-lived responses — SSE streams and WebSocket
+upgrades. Both require a `Response` that the router must forward through the
+middleware chain without reconstruction.
+
+## When each fits
+
+| Shape       | Tag             | Status | Body                            | Runtime                          |
+| ----------- | --------------- | ------ | ------------------------------- | -------------------------------- |
+| Server-Sent | `path.stream()` | 200    | `ReadableStream` (event-stream) | any runtime (Node, workerd, bun) |
+| WebSocket   | `path.any()`    | 101    | `null` + `webSocket` property   | Cloudflare Workers (workerd)     |
+
+- **SSE** is a regular 200 response with `content-type: text/event-stream`
+  and a `ReadableStream` body. Works everywhere, flows through middleware
+  normally.
+- **WebSocket upgrades** produce a status-101 response with a non-standard
+  `webSocket` property (Cloudflare). The router detects these and forwards
+  them without reconstruction; `Vary` and `Server-Timing` are skipped, and
+  stub headers are merged in place on a best-effort basis.
+
+## Server-Sent Events (SSE)
+
+Use `path.stream()` (or `path.any()` if you need full control) to return a
+`ReadableStream`. Each chunk is an `event-stream` frame:
+
+```typescript
+import { urls } from "@rangojs/router";
+
+export const urlpatterns = urls(({ path }) => [
+  path.stream(
+    "/events/ticks",
+    (ctx) => {
+      const encoder = new TextEncoder();
+
+      const stream = new ReadableStream({
+        async start(controller) {
+          let count = 0;
+          const interval = setInterval(() => {
+            controller.enqueue(
+              encoder.encode(`event: tick\ndata: ${++count}\n\n`),
+            );
+          }, 1000);
+
+          // Honor client disconnect — signal comes from ctx.request.signal
+          ctx.request.signal.addEventListener("abort", () => {
+            clearInterval(interval);
+            controller.close();
+          });
+        },
+      });
+
+      return new Response(stream, {
+        headers: {
+          "content-type": "text/event-stream",
+          "cache-control": "no-store",
+          // Disable proxy buffering on Nginx/Traefik deployments
+          "x-accel-buffering": "no",
+        },
+      });
+    },
+    { name: "ticks" },
+  ),
+]);
+```
+
+### Client
+
+```typescript
+"use client";
+const source = new EventSource("/events/ticks");
+source.addEventListener("tick", (e) => console.log("tick", e.data));
+```
+
+### SSE caveats
+
+- **Never wrap SSE routes in `cache()`** — a cached `ReadableStream` is read
+  once and would replay an empty body on the next hit. `path.stream` is
+  already excluded from response-route caching, but don't layer a custom
+  cache() middleware on top.
+- **Middleware is fine.** Global/route middleware rewraps the SSE `Response`
+  as `new Response(response.body, { status, headers })` to merge stub headers.
+  The `ReadableStream` body is passed by reference, not consumed, so the
+  client sees the stream unchanged. (WebSocket upgrades are the exception —
+  those bypass rewrap entirely; see below.)
+- **Honor `ctx.request.signal`.** Without wiring abort to your source
+  (timer, DB cursor, upstream fetch), the stream leaks when the client
+  disconnects.
+- **Disable Nginx/CDN buffering** via `x-accel-buffering: no` and ensure
+  no intermediate proxy rebuffers. On Cloudflare Workers this is a non-issue.
+
+## WebSockets (Cloudflare Workers)
+
+WebSocket upgrades on workerd produce a response with `status: 101` and a
+non-standard `webSocket` property. The router detects this shape and forwards
+the `Response` without reconstruction — the 101 status and the `webSocket`
+property are preserved. `Vary` and `Server-Timing` writes are skipped, and
+stub-header merging (cookies/custom headers set via `ctx.header()` or
+`cookies().set()`) is best-effort: the router attempts to apply them in
+place, but silently skips any write rejected by a runtime that exposes
+immutable upgrade headers.
+
+### Minimal upgrade handler
+
+```typescript
+import { urls } from "@rangojs/router";
+
+export const urlpatterns = urls(({ path }) => [
+  path.any(
+    "/ws",
+    (ctx) => {
+      // Manual WebSocketPair on workerd
+      const upgrade = ctx.request.headers.get("upgrade");
+      if (upgrade !== "websocket") {
+        return new Response("expected upgrade: websocket", { status: 426 });
+      }
+
+      const { 0: client, 1: server } = new WebSocketPair();
+      server.accept();
+      server.addEventListener("message", (e) => {
+        server.send(`echo: ${e.data}`);
+      });
+
+      return new Response(null, {
+        status: 101,
+        webSocket: client,
+      } as ResponseInit);
+    },
+    { name: "ws" },
+  ),
+]);
+```
+
+### Durable Object pattern
+
+Route into a Durable Object that owns the connection:
+
+```typescript
+export const urlpatterns = urls(({ path }) => [
+  path.any(
+    "/rooms/:roomId",
+    async (ctx) => {
+      const id = ctx.env.ROOMS.idFromName(ctx.params.roomId);
+      const stub = ctx.env.ROOMS.get(id);
+      // The DO's fetch handler calls handleWebSocketUpgrade(request)
+      // and returns the 101 Response. We forward it unchanged.
+      return stub.fetch(ctx.request);
+    },
+    { name: "room" },
+  ),
+]);
+```
+
+### Using the `agents` library
+
+`routeAgentRequest` from `agents` returns a 101 `Response` targeted at a
+Durable Object. Return it directly from `path.any()`:
+
+```typescript
+import { routeAgentRequest } from "agents";
+import { urls } from "@rangojs/router";
+
+export const urlpatterns = urls(({ path }) => [
+  path.any("/agents/*", async (ctx) => {
+    const response = await routeAgentRequest(ctx.request, ctx.env);
+    if (!response) {
+      return new Response("not found", { status: 404 });
+    }
+    return response;
+  }),
+]);
+```
+
+## Middleware interaction
+
+### Forwarded, not reconstructed
+
+When a middleware is matched for the upgrade URL, the middleware still runs
+**before** `next()` — but the Response from `next()` is forwarded as-is
+rather than re-wrapped. This preserves:
+
+- The 101 status (which would otherwise throw `RangeError: Responses may
+only be constructed with status codes in the range 200 to 599, inclusive`
+  on standards-compliant runtimes).
+- The Cloudflare `webSocket` property (which would otherwise be silently
+  dropped by `new Response(body, ...)` on workerd).
+
+```typescript
+// This works — logger runs, but the 101 flows through unchanged.
+router.use(async (ctx, next) => {
+  console.log("ws request", ctx.url.pathname);
+  return next();
+});
+```
+
+### Don't try to set cookies on an upgrade
+
+Stub cookie/header writes made before `await next()` are applied to the
+upgrade response on a best-effort basis — the router attempts an in-place
+merge and skips any write rejected by runtimes that expose immutable 101
+headers. Either way, a browser completing a WS handshake never reads them.
+Do not rely on this for auth or state propagation: set cookies via a prior
+HTTP request instead (e.g. during login), then read them at upgrade time
+via `ctx.request.headers.get("cookie")`.
+
+```typescript
+// Avoid: this cookie may not land on the upgrade response, and the client
+// never reads it during the handshake regardless.
+router.use(async (ctx, next) => {
+  cookies().set("last-ws-at", Date.now().toString());
+  return next();
+});
+
+// Prefer: authenticate by reading a cookie set on a prior HTTP request.
+path.any("/ws", (ctx) => {
+  const session = parseCookie(ctx.request.headers.get("cookie"))?.session;
+  if (!verify(session)) return new Response("unauthorized", { status: 401 });
+  // ...upgrade
+});
+```
+
+### Short-circuit before upgrade
+
+Middleware can return a non-101 Response to deny the upgrade outright:
+
+```typescript
+router.use(async (ctx, next) => {
+  if (!isAllowed(ctx.request)) {
+    return new Response("forbidden", { status: 403 });
+  }
+  return next();
+});
+```
+
+## Caching
+
+- **SSE** — do not combine with `cache()` (streams can't be replayed).
+- **WebSocket** — `cache()` is inert because only `status === 200` is cacheable.
+
+## Runtime caveats
+
+| Runtime                                | SSE | WebSocket upgrade (101)                              |
+| -------------------------------------- | --- | ---------------------------------------------------- |
+| Cloudflare Workers (workerd)           | OK  | OK (native `WebSocketPair`, DO, `agents`)            |
+| Node (undici fetch)                    | OK  | N/A — Node's HTTP server must upgrade                |
+| Bun                                    | OK  | Bun's native `upgrade()` — not a Response-based path |
+| Dev (Vite + `@cloudflare/vite-plugin`) | OK  | OK via workerd emulation                             |
+
+When running in pure Node without workerd, a `status: 101` Response cannot
+even be constructed (`new Response(null, { status: 101 })` throws). For
+tests, fabricate upgrade-style responses by overriding `.status` on a real
+Response instance:
+
+```typescript
+const upgrade = new Response(null, { status: 200 });
+Object.defineProperty(upgrade, "status", { value: 101, configurable: true });
+// optional: attach a webSocket stub
+Object.defineProperty(upgrade, "webSocket", {
+  value: { stub: "ws" },
+  configurable: true,
+  enumerable: true,
+});
+```
+
+## Testing
+
+- Unit tests: `isWebSocketUpgradeResponse` and `executeMiddleware` passthrough
+  cases live in `src/rsc/__tests__/helpers.test.ts` and
+  `src/router/middleware.test.ts`.
+- E2E: cover both dev and production modes against a workerd target. SSE
+  can be tested on any runtime; WS upgrades need workerd (use
+  `@cloudflare/vite-plugin` or `wrangler dev`).
+
+## See also
+
+- `response-routes` — the parent skill for `path.json/text/html/stream/any`.
+- `middleware` — how global and route-level middleware compose with handlers.

package/skills/theme/SKILL.md

@@ -36,20 +36,21 @@ const router = createRouter<Env>({
 ## Server (in loaders/middleware)
 
 ```typescript
-import { createLoader, createMiddleware } from "@rangojs/router";
+import { createLoader } from "@rangojs/router";
+import type { Middleware } from "@rangojs/router";
 
 // In a loader
-export const SettingsLoader = createLoader("settings", async (ctx) => {
+export const SettingsLoader = createLoader(async (ctx) => {
   const currentTheme = ctx.theme; // read from cookie
   return { theme: currentTheme };
 });
 
 // In middleware
-export const themeMiddleware = createMiddleware(async (ctx, next) => {
+export const themeMiddleware: Middleware = async (ctx, next) => {
   // Set theme based on user preference
   ctx.setTheme("dark");
   await next();
-});
+};
 ```
 
 ## Client

package/skills/typesafety/SKILL.md

@@ -17,8 +17,7 @@ import { urlpatterns } from "./urls";
 
 const router = createRouter<AppBindings>({
   document: Document,
-  urls: urlpatterns,
-});
+}).routes(urlpatterns);
 
 // Server-side named-route reverse (type-safe via routeMap)
 export const reverse = router.reverse;
@@ -26,6 +25,39 @@ export const reverse = router.reverse;
 export default router;
 ```
 
+### Which global type should I use?
+
+Use the generated route map by default. Manual `RegisteredRoutes` augmentation
+is only needed when you want the richer `typeof router.routeMap` shape
+available globally.
+
+- `GeneratedRouteMap` — auto-registered by `router.named-routes.gen.ts`
+  Use for `Handler<"name">`, `Prerender<"name">`, server `ctx.reverse()`,
+  and named-route param/search inference.
+- `typeof router.routeMap` — the real merged route map from your router
+  instance, including response-route metadata such as `{ path, response }`.
+- `RegisteredRoutes` — manual global hook for exposing `typeof router.routeMap`
+  to utilities like `href()`, `ValidPaths`, and `PathResponse`.
+
+Recommended setup:
+
+```typescript
+// router.tsx
+import { createRouter } from "@rangojs/router";
+import { urlpatterns } from "./urls";
+import type { AppBindings, AppVars } from "./env";
+
+export const router = createRouter<AppBindings>({}).routes(urlpatterns);
+
+declare global {
+  namespace RSCRouter {
+    interface Env extends AppBindings {}
+    interface Vars extends AppVars {}
+    interface RegisteredRoutes extends typeof router.routeMap {}
+  }
+}
+```
+
 ## Route Definition with Type-Safe Names
 
 ```typescript
@@ -95,6 +127,17 @@ function ShopNav() {
 }
 ```
 
+`href()` and path-based response utilities read from `RegisteredRoutes`, so if
+you want them typed globally you should augment:
+
+```typescript
+declare global {
+  namespace RSCRouter {
+    interface RegisteredRoutes extends typeof router.routeMap {}
+  }
+}
+```
+
 See `/links` for full URL generation guide.
 
 ## Environment Type Setup
@@ -128,8 +171,7 @@ import type { AppBindings, AppVariables } from "./env";
 
 const router = createRouter<AppBindings>({
   document: Document,
-  urls: urlpatterns,
-});
+}).routes(urlpatterns);
 
 // Register bindings and variables globally for implicit typing
 declare global {
@@ -140,19 +182,19 @@ declare global {
 }
 
 // middleware - typed via ctx.set / ctx.get
-import { createMiddleware } from "@rangojs/router";
+import type { Middleware } from "@rangojs/router";
 
-export const authMiddleware = createMiddleware(async (ctx, next) => {
+export const authMiddleware: Middleware = async (ctx, next) => {
   ctx.set("user", {
     id: "123",
     email: "user@example.com",
     role: "admin",
   });
   await next();
-});
+};
 
 // loaders - typed context
-export const UserLoader = createLoader("user", async (ctx) => {
+export const UserLoader = createLoader(async (ctx) => {
   const db = ctx.env.DB; // D1Database (plain bindings)
   const userId = ctx.get("user")?.id; // from RSCRouter.Vars
   return db.prepare("SELECT * FROM users WHERE id = ?").bind(userId).first();
@@ -177,7 +219,7 @@ Now handlers have typed context without explicit imports:
 
 ```typescript
 // In loaders
-export const DashboardLoader = createLoader("dashboard", async (ctx) => {
+export const DashboardLoader = createLoader(async (ctx) => {
   // ctx.env.DB is typed from global RSCRouter.Env
   // ctx.get("user") is typed from global RSCRouter.Vars
   const user = ctx.get("user");
@@ -239,7 +281,7 @@ import type { RouteSearchParams, RouteParams } from "@rangojs/router";
 
 // RouteSearchParams<"name"> resolves the search schema to a typed object
 type SP = RouteSearchParams<"search">;
-// { q: string; page?: number; sort?: string }
+// { q: string | undefined; page?: number; sort?: string }
 
 // RouteParams<"name"> resolves URL params from the route pattern
 type P = RouteParams<"blogPost">;
@@ -283,7 +325,7 @@ Loaders have typed return values:
 
 ```typescript
 // loaders/product.ts
-export const ProductLoader = createLoader("product", async (ctx) => {
+export const ProductLoader = createLoader(async (ctx) => {
   return {
     id: ctx.params.slug,
     name: "Widget",
@@ -292,7 +334,7 @@ export const ProductLoader = createLoader("product", async (ctx) => {
 });
 
 // In server component - type is inferred
-import { useLoader } from "@rangojs/router";
+import { useLoader } from "@rangojs/router/client";
 
 async function ProductPage() {
   const product = await useLoader(ProductLoader);
@@ -302,11 +344,12 @@ async function ProductPage() {
 
 // In client component - same type
 "use client";
-import { useLoaderData } from "@rangojs/router/client";
+import { useLoader } from "@rangojs/router/client";
 
 function ProductPrice() {
-  const { product } = useLoaderData(ProductLoader);
-  // product: { id: string; name: string; price: number }
+  const { data } = useLoader(ProductLoader);
+  // data: { id: string; name: string; price: number }
+  const product = data;
   return <span>${product.price}</span>;
 }
 ```
@@ -326,8 +369,18 @@ interface PaginationData {
   perPage: number;
 }
 export const Pagination = createVar<PaginationData>();
+
+// Non-cacheable var — reading inside cache() or "use cache" throws at runtime
+const Session = createVar<SessionData>({ cache: false });
 ```
 
+`createVar` accepts an optional options object. The `cache` option (default
+`true`) controls whether the var's values can be read inside cache scopes.
+Write-level escalation is also supported: `ctx.set(Var, value, { cache: false })`
+marks a specific write as non-cacheable even if the var itself is cacheable.
+"Least cacheable wins" — if either says `cache: false`, the value throws on
+read inside `cache()` or `"use cache"`.
+
 ### Producer (handler or middleware)
 
 ```typescript
@@ -371,26 +424,30 @@ Both approaches coexist: `ctx.get("user")` (global via Vars) and
 Handles have typed data:
 
 ```typescript
-// handles/breadcrumbs.ts
-import { createHandle } from "@rangojs/router";
-
-// All export patterns work: export const, const + export { X }, export { X as Y }
-export const Breadcrumbs = createHandle<{ label: string; href: string }>();
-
-// In route definition - use handle() DSL
-import { urls } from "@rangojs/router";
-
-export const urlpatterns = urls(({ path, handle }) => [
-  path("/shop/product/:slug", ProductPage, { name: "product" }, () => [
-    handle(Breadcrumbs, { label: "Products", href: "/shop/products" }),
-  ]),
-]);
-
-// In client - typed array
+// Built-in Breadcrumbs handle — import from "@rangojs/router"
+import { Breadcrumbs } from "@rangojs/router";
+// Type: Handle<BreadcrumbItem, BreadcrumbItem[]>
+// BreadcrumbItem: { label: string; href: string; content?: ReactNode | Promise<ReactNode> }
+
+// In route handler — push is fully typed
+path("/shop/product/:slug", (ctx) => {
+  const breadcrumb = ctx.use(Breadcrumbs);
+  breadcrumb({ label: "Products", href: "/shop/products" });
+  return <ProductPage />;
+}, { name: "product" });
+
+// In client — typed array
+import { useHandle, Breadcrumbs } from "@rangojs/router/client";
 function BreadcrumbNav() {
   const crumbs = useHandle(Breadcrumbs);
-  // crumbs: Array<{ label: string; href: string }>
+  // crumbs: BreadcrumbItem[]
 }
+
+// Custom handles also work the same way
+import { createHandle } from "@rangojs/router";
+export const PageTitle = createHandle<string, string>(
+  (segments) => segments.flat().at(-1) ?? "Default Title"
+);
 ```
 
 ## Ref Prop Type Safety (Loaders & Handles)
@@ -404,14 +461,14 @@ export const ProductLoader = createLoader(async (ctx) => {
   return { product: await fetchProduct(ctx.params.slug) };
 });
 
-// handles.ts
-export const Breadcrumbs = createHandle<{ label: string; href: string }>();
+// Built-in Breadcrumbs — or any custom handle created with createHandle()
+```
 
+```tsx
 // Client component — typeof infers all generics
-("use client");
-import { useLoader, useHandle } from "@rangojs/router/client";
+"use client";
+import { useLoader, useHandle, type Breadcrumbs } from "@rangojs/router/client";
 import type { ProductLoader } from "../loaders";
-import type { Breadcrumbs } from "../handles";
 
 function MyComponent({
   loader,
@@ -559,7 +616,7 @@ export default router;
 //    No manual RegisteredRoutes declaration needed.
 
 // 5. loaders/*.ts - Type-safe loaders
-export const ProductLoader = createLoader("product", async (ctx) => {
+export const ProductLoader = createLoader(async (ctx) => {
   // ctx.params: { slug: string }
   // ctx.get("user"): User | undefined  (from RSCRouter.Vars)
   // ctx.env.DB: D1Database  (plain bindings from RSCRouter.Env)

package/skills/use-cache/SKILL.md

@@ -102,14 +102,28 @@ export async function getProductData(ctx) {
 // On hit: return value restored, breadcrumb replayed.
 ```
 
-## ctx Side-Effect Guards
+## Request-Scoped Guards
+
+### Read Guards
+
+`cookies()` and `headers()` **throw** inside a `"use cache"` function because
+per-request values (cookies, headers) are not reflected in the cache key. Without
+this guard, one user's data would be served to another.
+
+Extract the value before the cached function and pass it as an argument:
+
+```typescript
+const locale = cookies().get("locale")?.value ?? "en";
+const data = await getCachedData(locale); // locale is now in the cache key
+```
+
+### Side-Effect Guards
 
 These ctx methods **throw** inside a `"use cache"` function because their effects
 are lost on cache hit (the function body is skipped):
 
 - `ctx.set()` / `ctx.get()` for passing values to children
 - `ctx.header()`
-- `ctx.setCookie()` / `ctx.deleteCookie()`
 - `ctx.setTheme()`
 - `ctx.setLocationState()`
 - `ctx.onResponse()`

package/src/__internal.ts

@@ -160,10 +160,102 @@ export type {
 /**
  * @internal
  * Internal handler context with additional props for router internals.
- * Includes `_originalRequest` and `_currentSegmentId`.
+ * Includes `_currentSegmentId` and `_responseType`.
  */
 export type { InternalHandlerContext } from "./types.js";
 
+// ============================================================================
+// Rendering (Internal)
+// ============================================================================
+
+/**
+ * @internal
+ * Builds React element trees from route segments.
+ */
+export { renderSegments } from "./segment-system.js";
+
+// ============================================================================
+// Error Utilities (Internal)
+// ============================================================================
+
+/**
+ * @internal
+ * Error sanitization and network error utilities.
+ */
+export { sanitizeError, NetworkError, isNetworkError } from "./errors.js";
+
+// ============================================================================
+// Type Utilities (Internal)
+// ============================================================================
+
+/**
+ * @internal
+ * Scoped view of GeneratedRouteMap for Handler<"localName", ScopedRouteMap<"prefix">>.
+ */
+export type { ScopedRouteMap } from "./types.js";
+
+/**
+ * @internal
+ * Type-level utilities for reverse URL generation.
+ */
+export type { MergeRoutes, SanitizePrefix } from "./reverse.js";
+
+/**
+ * @internal
+ * Individual telemetry event types.
+ */
+export type {
+  RequestStartEvent,
+  RequestEndEvent,
+  RequestErrorEvent,
+  RequestTimeoutEvent,
+  LoaderStartEvent,
+  LoaderEndEvent,
+  LoaderErrorEvent,
+  HandlerErrorEvent,
+  CacheDecisionEvent,
+  RevalidationDecisionEvent,
+} from "./router/telemetry.js";
+
+// ============================================================================
+// Pre-render / Static Handler Guards (Internal)
+// ============================================================================
+
+/**
+ * @internal
+ * Type guard for prerender handler definitions.
+ */
+export { isPrerenderHandler, isPassthroughHandler } from "./prerender.js";
+
+/**
+ * @internal
+ * Type guard for static handler definitions.
+ */
+export { isStaticHandler } from "./static-handler.js";
+
+// ============================================================================
+// URL Pattern Internals
+// ============================================================================
+
+/**
+ * @internal
+ * Sentinel used to tag response-type route entries.
+ */
+export { RESPONSE_TYPE } from "./urls.js";
+
+// ============================================================================
+// Route Match Debug (Internal)
+// ============================================================================
+
+/**
+ * @internal
+ * Debug utilities for route matching performance analysis.
+ */
+export {
+  enableMatchDebug,
+  getMatchDebugStats,
+} from "./router/pattern-matching.js";
+
 // ============================================================================
 // Debug Utilities (Internal)
 // ============================================================================