@rangojs/router 0.0.0-experimental.29 → 0.0.0-experimental.2c0cb8a1

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/typesafety/SKILL.md

@@ -287,6 +287,12 @@ type SP = RouteSearchParams<"search">;
 type P = RouteParams<"blogPost">;
 // { slug: string }
 
+// Optional URL params (`:slug?`) resolve to `string | undefined`
+// because absent segments are omitted from `ctx.params` at runtime.
+type C = RouteParams<"checkout">;
+// { step?: string }
+// → ctx.params.step is `string | undefined`; use `?? "default"` to coalesce.
+
 // Use in component props
 interface SearchResultsProps {
   params: RouteSearchParams<"search">;
@@ -369,8 +375,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
@@ -414,26 +430,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)
@@ -447,14 +467,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,

package/skills/view-transitions/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: view-transitions
+description: Configure React View Transitions on layouts, routes, and parallel slots in @rangojs/router
+argument-hint: [layout|route|parallel|intercept]
+---
+
+# View Transitions
+
+Rango wires React's experimental `<ViewTransition>` into the segment tree via the `transition()` helper. Each segment can declare its own transition config; rango wraps it at the right tree position so navigations morph the right pieces and modals do not.
+
+> Requires React experimental (the build that exports `<ViewTransition>` and `addTransitionType`). With stable React, `transition()` is a no-op — your routes still render, just without view-transition wrappers.
+
+## What `transition()` does
+
+`transition(config)` attaches a [`TransitionConfig`](#transitionconfig) to the surrounding entry. Where the wrap actually lands in the rendered React tree depends on the segment type:
+
+| Segment type                      | Wrap location                                                                                                                                                                                                                                                                                                                     |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `layout()`                        | Around the layout's **default outlet content** (what the layout's `<Outlet />` renders), recursively pushed past nested layouts. Parallel slots (`<ParallelOutlet />`) are siblings of the wrap, not subtree members.                                                                                                             |
+| `path()` / `route()`              | Around the **route's component itself** (the leaf content).                                                                                                                                                                                                                                                                       |
+| `parallel()` / `intercept()` slot | `transition()` is accepted by the DSL today, but slot-level rendering does not currently apply a `<ViewTransition>` wrapper. Mount intercept slots in layouts so layout transitions stay scoped to the default outlet. For modal-specific morphs today, use an element-level React `<ViewTransition>` inside the modal component. |
+
+The layout case is the important one: stacking a layout transition does **not** wrap the layout chrome (header, sidebar, modal slot); it only morphs whatever flows through that layout's `<Outlet />`.
+
+## Basic Usage
+
+A simple cross-fade between pages that share a layout:
+
+```tsx
+import { urls } from "@rangojs/router";
+import { Outlet } from "@rangojs/router/client";
+
+function ShopShell({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="shop">
+      <NavBar />
+      <main>
+        <Outlet /> {/* fade applies HERE */}
+      </main>
+      <Footer />
+    </div>
+  );
+}
+
+export const urlpatterns = urls(({ layout, path, transition }) => [
+  layout(<ShopShell />, () => [
+    transition({ default: "page-fade" }),
+    path("/", ShopIndex, { name: "index" }),
+    path("/about", AboutPage, { name: "about" }),
+    path("/contact", ContactPage, { name: "contact" }),
+  ]),
+]);
+```
+
+```css
+::view-transition-old(root) {
+  animation: fade-out 200ms ease both;
+}
+::view-transition-new(root) {
+  animation: fade-in 200ms ease both;
+}
+.page-fade {
+  /* class hooks per phase */
+}
+```
+
+Navigating between `/`, `/about`, and `/contact` morphs the `<Outlet />` content with the `page-fade` class. The shell (NavBar, Footer) does not morph because the wrap sits inside the shell, not around it.
+
+## Direction-aware transitions
+
+`ViewTransitionClass` accepts an object form keyed by transition type. Rango tags forward navigations as `"navigation"` and back/forward popstate as `"navigation-back"`:
+
+```tsx
+layout(<ShopShell />, () => [
+  transition({
+    default: {
+      navigation: "slide-left",
+      "navigation-back": "slide-right",
+    },
+  }),
+  path("/", ShopIndex, { name: "index" }),
+  path("/about", AboutPage, { name: "about" }),
+]);
+```
+
+```css
+.slide-left {
+  animation-name: slide-from-right;
+}
+.slide-right {
+  animation-name: slide-from-left;
+}
+```
+
+> Note: `"action"` is only tagged on partial-update action/refetch paths today; ordinary `server-action-bridge` commits (`useAction` / `useActionState` revalidations) are not currently tagged. Don't rely on an `action`-keyed class to fire on every form action.
+
+## Wrapper form: applying transition to a group of routes
+
+`transition(config, () => [...])` creates a transparent layout that applies the config to its children — useful when you want a transition without authoring a real layout component:
+
+```tsx
+urls(({ path, transition }) => [
+  // No layout component, but every route inside gets the fade.
+  transition({ default: "fade" }, () => [
+    path("/", HomePage, { name: "home" }),
+    path("/about", AboutPage, { name: "about" }),
+  ]),
+  // Outside the wrapper — no transition applied.
+  path("/admin", AdminPage, { name: "admin" }),
+]);
+```
+
+## Intercept (modal) interaction
+
+This is where the rango-specific behavior pays off. A common shape:
+
+```tsx
+import { urls } from "@rangojs/router";
+import { Outlet, ParallelOutlet } from "@rangojs/router/client";
+
+function GalleryShell() {
+  return (
+    <>
+      <NavBar />
+      <main>
+        <Outlet /> {/* page transition lands here */}
+      </main>
+      <ParallelOutlet name="@modal" />{" "}
+      {/* modal mounts here — sibling of the VT */}
+    </>
+  );
+}
+
+export const urlpatterns = urls(
+  ({ layout, path, intercept, transition, loader, loading }) => [
+    layout(<GalleryShell />, () => [
+      transition({ default: "fade" }),
+
+      path("/", GalleryFeed, { name: "feed" }),
+      path("/photos/:id", PhotoPage, { name: "photo" }),
+
+      intercept("@modal", "photo", <PhotoModal />, () => [
+        loader(PhotoLoader),
+        loading(<PhotoModalSkeleton />),
+      ]),
+    ]),
+  ],
+);
+```
+
+| Action                                          | What fires                                                                                                                     |
+| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| Navigate `/` ↔ `/about` (within `GalleryShell`) | Layout transition fires; `<Outlet />` content cross-fades                                                                      |
+| Click `<Link to="/photos/42" />` from `/`       | Soft navigation opens `<PhotoModal />` in `@modal`; **no** view transition fires on the underlying feed                        |
+| Submit a form action inside `<PhotoModal />`    | Revalidation commits without firing the layout VT; modal subtree identity is preserved (no remount, `useActionState` survives) |
+| Close modal via `router.back()`                 | Underlying page is restored; **no** view transition fires                                                                      |
+| Direct URL load `/photos/42`                    | Renders the full `<PhotoPage />` with no modal; the layout transition applies on subsequent in-layout navs                     |
+
+The "no VT on modal open" guarantee holds at any depth — if the layout that owns `@modal` is itself nested inside another transitioned layout, the outer transition is pushed past the inner layout into its default outlet content, so the modal slot ends up outside both VTs.
+
+## Per-route transition
+
+Routes are leaves: their `transition()` wraps the route component itself.
+
+```tsx
+urls(({ path, transition }) => [
+  path("/checkout", CheckoutPage, { name: "checkout" }, () => [
+    transition({ default: "fade-in" }),
+  ]),
+]);
+```
+
+This is the right level for one-off route-specific morphs that should not propagate to siblings.
+
+## TransitionConfig
+
+`transition()` accepts the props of React's `<ViewTransition>` (minus `children`/refs). Each phase prop accepts either a plain class string or an object keyed by transition type:
+
+```ts
+import type { TransitionConfig } from "@rangojs/router";
+
+interface TransitionConfig {
+  enter?: string | Record<string, string>;
+  exit?: string | Record<string, string>;
+  update?: string | Record<string, string>;
+  share?: string | Record<string, string>;
+  default?: string | Record<string, string>; // fallback for any phase
+  name?: string; // explicit view-transition-name
+}
+```
+
+- `default` is the catch-all if a phase-specific prop is unset.
+- The object form keys are React transition types tagged by rango: `"navigation"` (forward navigations), `"navigation-back"` (popstate cache restores), and `"action"` (partial-update action/refetch paths only — see the caveat in "Direction-aware transitions").
+- `name` lets you participate in cross-page morphs by name (advanced; you usually don't need this on a layout/route-level wrap).
+
+## Recommendations
+
+**Put `<ParallelOutlet />` in layouts, not routes.** A route-level `transition` wraps the route component itself, so a `<ParallelOutlet />` rendered directly inside that route component remains inside the route VT subtree — modal opens on a route with a parallel outlet _will_ trigger the route's VT walker. The narrowing fix only applies at layout boundaries. If you combine intercept modals with route-level transitions, mount the slot one level up in a layout.
+
+**Don't stack `transition()` on every layout level.** When ancestor and descendant layouts both configure transitions, both wraps end up nested around the deepest default outlet content. Two VTs fire on every nav within the inner layout. That's usually not what you want — pick the level where the morph belongs and apply it once.
+
+**Need a modal-only morph?** Per-slot `transition()` is currently a no-op at render time, so use an element-level React `<ViewTransition>` inside the modal component (or a CSS animation) for the modal-entrance effect.
+
+**Action revalidation inside a modal is safe.** Server-action submits inside an open modal don't fire the underlying layout VT. Modal subtree identity is preserved across revalidation — so `useActionState`, focus, and scroll all survive the round-trip.
+
+## Notes
+
+- `transition()` is part of the route DSL. The allow-list table in [skills/handler-use](../handler-use/SKILL.md) permits it inside `layout()`, `path()`/`route()`, `parallel()` (per-slot or shared), and `intercept()`. At render time, only the layout and route wraps actually take effect today; `parallel()`/`intercept()` slot-level rendering does not currently apply the wrap.
+- Wrap location for layouts: rango walks the rendered tree past `MountContextProvider`/`OutletProvider`/`LoaderBoundary` for layout segments and applies the wrap at the first non-layout target ([segment-system.tsx](../../src/segment-system.tsx) — `wrapDefaultOutletContent`). This is what keeps parallel slots out of the VT subtree.
+- Tree consistency: the wrapper structure is identical across normal commits, intercept-active commits, and action revalidations — React never sees an element-type swap, so layout/modal subtrees are not remounted across these transitions.
+- Element-level `<ViewTransition>` (importing it directly from React and using `name`/`share` to morph specific elements across pages) composes with rango's segment-level wraps as usual; rango doesn't intercept those.
+- See also: [skills/intercept](../intercept/SKILL.md), [skills/parallel](../parallel/SKILL.md), [skills/layout](../layout/SKILL.md).