@rangojs/router 0.0.0-experimental.d20dd405 → 0.0.0-experimental.d5d3070a

package/skills/response-routes/SKILL.md

@@ -68,16 +68,16 @@ export const urlpatterns = urls(({ path, layout, include }) => [
 
 ## Available Tags
 
-| Tag      | Usage           | Handler returns    | Auto-wrap                |
-| -------- | --------------- | ------------------ | ------------------------ |
-| `json`   | `path.json()`   | plain object/array | `{ data: T }` envelope   |
-| `text`   | `path.text()`   | string             | text/plain Response      |
-| `html`   | `path.html()`   | string             | text/html Response       |
-| `xml`    | `path.xml()`    | string             | application/xml Response |
-| `md`     | `path.md()`     | string             | text/markdown Response   |
-| `image`  | `path.image()`  | Response           | pass-through             |
-| `stream` | `path.stream()` | Response           | pass-through             |
-| `any`    | `path.any()`    | Response           | pass-through             |
+| Tag      | Usage           | Handler returns    | Auto-wrap                     |
+| -------- | --------------- | ------------------ | ----------------------------- |
+| `json`   | `path.json()`   | plain object/array | bare JSON value (no envelope) |
+| `text`   | `path.text()`   | string             | text/plain Response           |
+| `html`   | `path.html()`   | string             | text/html Response            |
+| `xml`    | `path.xml()`    | string             | application/xml Response      |
+| `md`     | `path.md()`     | string             | text/markdown Response        |
+| `image`  | `path.image()`  | Response           | pass-through                  |
+| `stream` | `path.stream()` | Response           | pass-through                  |
+| `any`    | `path.any()`    | Response           | pass-through                  |
 
 ## ResponseHandlerContext
 
@@ -139,22 +139,31 @@ path.json(
 );
 ```
 
-## JSON Envelope
+## JSON Wire Shape
 
-`path.json()` handlers return plain data. The framework auto-wraps it
-in a `ResponseEnvelope<T>` discriminated union:
+`path.json()` handlers return plain data. The framework serializes the handler's
+return value **verbatim** (no envelope) on success, and an RFC 9457 `problem+json`
+body on error. Discriminate with `res.ok` / the HTTP status — there is no in-body
+`data`/`error` union:
 
 ```typescript
-// Success: HTTP 200
-{ "data": { "status": "ok", "timestamp": 1700000000 } }
-
-// Error: HTTP 404 (or whatever status RouterError specifies)
-{ "error": { "message": "Product 999 not found", "code": "NOT_FOUND" } }
+// Success: HTTP 200, content-type application/json
+{ "status": "ok", "timestamp": 1700000000 }
+
+// Error: HTTP 404 (or whatever status RouterError specifies),
+//        content-type application/problem+json
+{
+  "title": "Not Found",
+  "status": 404,
+  "detail": "Product 999 not found",
+  "code": "NOT_FOUND"
+  // "stack": included in development only
+}
 ```
 
 ### Error Handling with RouterError
 
-Throw `RouterError` to return structured error envelopes:
+Throw `RouterError` to return a structured `problem+json` body:
 
 ```typescript
 import { RouterError } from "@rangojs/router";
@@ -199,25 +208,27 @@ path.json(
 
 ## Client-Side Type Safety
 
-### ResponseEnvelope and isResponseError
+### Discriminating success vs. error with res.ok
+
+Success bodies are the bare value; error bodies are RFC 9457 `ProblemDetails`.
+Branch on `res.ok` (or the HTTP status) — not an in-body union:
 
 ```typescript
 "use client";
-import type { ResponseEnvelope, ResponseError } from "@rangojs/router/client";
-import { isResponseError } from "@rangojs/router/client";
+import type { ProblemDetails } from "@rangojs/router";
 
 // Fetch a typed response
 const res = await fetch("/api/products/1");
-const result: ResponseEnvelope<Product> = await res.json();
 
-if (isResponseError(result)) {
-  // result.error: ResponseError  (message, code?, type?)
-  // result.data: undefined
-  console.error(result.error.message);
+if (!res.ok) {
+  // Error body: application/problem+json
+  const problem: ProblemDetails = await res.json();
+  // problem.detail: string, problem.code: string, problem.status: number
+  console.error(problem.code, problem.detail);
 } else {
-  // result.data: Product
-  // result.error: undefined
-  console.log(result.data.name);
+  // Success body: the bare value (no envelope)
+  const product: Product = await res.json();
+  console.log(product.name);
 }
 ```
 
@@ -230,32 +241,82 @@ import type { RouteResponse } from "@rangojs/router";
 
 // From the apiPatterns module (before include)
 type HealthData = RouteResponse<typeof apiPatterns, "health">;
-// = ResponseEnvelope<{ status: string; timestamp: number }>
+// = { status: string; timestamp: number }
 
 type ProductsData = RouteResponse<typeof apiPatterns, "products">;
-// = ResponseEnvelope<{ id: string; name: string; price: number }[]>
+// = { id: string; name: string; price: number }[]
 ```
 
-### PathResponse (global lookup by URL pattern)
+`RouteResponse` is the bare success payload (the JSON wire shape) — the same value
+a `fetch().then(r => r.json())` yields on a 2xx. Error bodies are `ProblemDetails`,
+keyed off `res.ok` at runtime, not part of this type.
 
-Look up response type from the merged route map by URL pattern:
+### Rango.PathResponse (global lookup by URL pattern or concrete path)
+
+`Rango.PathResponse` is ambient (no import) and reads from `RegisteredRoutes`,
+which carries response payload metadata. That surface is **not** auto-wired —
+without the augmentation below, `Rango.PathResponse` falls back to the generated
+path/search map, or to a permissive map when nothing is generated. Either way, it
+has no response payload metadata, so response routes resolve to `never`:
 
 ```typescript
-import type { PathResponse } from "@rangojs/router/client";
+// router.tsx
+export const router = createRouter({ document: Document }).routes(urlpatterns);
 
+declare global {
+  namespace Rango {
+    interface RegisteredRoutes extends typeof router.routeMap {}
+  }
+}
+```
+
+With that in place, look up the response type by URL pattern (ambient, no import):
+
+```typescript
 // After include("/api", apiPatterns) in main urls
-type Health = PathResponse<"/api/health">;
-// = ResponseEnvelope<{ status: string; timestamp: number }>
+type Health = Rango.PathResponse<"/api/health">;
+// = { status: string; timestamp: number }
 
-// RSC routes return ResponseEnvelope<never>
-type Home = PathResponse<"/">;
-// = ResponseEnvelope<never>
+// RSC routes (no JSON payload) return never
+type Home = Rango.PathResponse<"/">;
+// = never
 ```
 
+`Rango.PathResponse` also accepts a **concrete path**, so it types a `fetch`
+wrapper whose response is inferred from the path you pass:
+
+```typescript
+import { href } from "@rangojs/router/client";
+
+async function get<T extends Rango.Path>(
+  path: T,
+): Promise<Rango.PathResponse<T>> {
+  return fetch(href(path)).then((r) => r.json());
+}
+
+const product = await get("/api/products/42"); // Product (bare value)
+```
+
+Pattern keys (`/:id`) match exactly; a concrete path under a _nested_ dynamic
+route can match several patterns and union their responses.
+
+`Rango.PathResponse` reports the JSON **wire** shape, not the handler's raw
+return: `path.json()` serializes with `JSON.stringify`, so a handler returning
+`{ createdAt: Date }` resolves to the bare `{ createdAt: string }`. This
+runs through the ambient `Rango.JsonSerialize<T>` transform (`Date -> string`,
+honors `toJSON()`, drops functions/`undefined`, `bigint -> never`). The
+`RouteResponse` surface below applies the same `Rango.JsonSerialize` transform, so
+both response lookups report the identical wire shape.
+
+For local/scoped response typing without global augmentation, prefer
+`RouteResponse<typeof patterns, "routeName">` (see the section above) — it reads
+the response payload straight from the `urls()` patterns and needs no
+`RegisteredRoutes` wiring.
+
 ### ParamsFor with Response Routes
 
 ```typescript
-import type { ParamsFor } from "@rangojs/router/client";
+import type { ParamsFor } from "@rangojs/router";
 
 // Works for both RSC and response routes
 type ProductParams = ParamsFor<"api.productDetail">;
@@ -361,15 +422,17 @@ export const urlpatterns = urls(({ path, include }) => [
 
 ```typescript
 import type { RouteResponse } from "@rangojs/router";
-import type { PathResponse, ParamsFor } from "@rangojs/router/client";
+import type { ParamsFor } from "@rangojs/router";
 
-// Scoped (before mount) -- use the module directly
+// Scoped (before mount) -- use the module directly, no global wiring needed
 type Stats = RouteResponse<typeof blogApiPatterns, "stats">;
-// = ResponseEnvelope<{ views: number; visitors: number }>
+// = { views: number; visitors: number }
 
-// After mounting -- names get prefixed
-type BlogStats = PathResponse<"/blog/api/stats">;
-// = ResponseEnvelope<{ views: number; visitors: number }>
+// After mounting -- names get prefixed.
+// Rango.PathResponse needs `RegisteredRoutes extends typeof router.routeMap` (see above),
+// otherwise it resolves to never.
+type BlogStats = Rango.PathResponse<"/blog/api/stats">;
+// = { views: number; visitors: number }
 
 // Params work through nested includes
 type LikesParams = ParamsFor<"blog.api.likes">;
@@ -413,7 +476,11 @@ best-effort basis.
 1. `path.json()` tags the route at the trie level with a MIME type
 2. `coreRequestHandler()` checks the tag before the RSC pipeline
 3. Tagged routes short-circuit: handler runs, Response is returned directly
-4. JSON routes auto-wrap return values in `{ data }` / `{ error }` envelope
+4. JSON routes serialize the return value verbatim (bare) on success; a thrown error becomes an RFC 9457 `problem+json` body (`application/problem+json`)
 5. Client-side navigation to response routes gets `X-RSC-Reload` header, triggering hard navigation
 6. Response types flow through `_responses` phantom type on `UrlPatterns`, propagated by `include()`
 7. When multiple routes share a URL pattern, the trie merges them for content negotiation (see `/mime-routes`)
+
+## Consuming response routes
+
+To call your own response-route JSON APIs from first-party TypeScript with a typed client (typed params, typed payloads inferred from the handler, no `.data`, typed `ProblemDetails` errors), see `/api-client` — a copy-paste recipe over `RouteResponse` + `ExtractParams` + a client-safe path builder. External/third-party consumers use the plain wire directly: bare JSON on success, `application/problem+json` on error.

package/skills/route/SKILL.md

@@ -234,14 +234,24 @@ Cacheable vars (the default) can be read freely inside cache scopes.
 
 ### Revalidation Contracts for Handler Data
 
+> **Scope: `revalidate()` is a partial-render concern, not a cache concern.**
+> It decides whether this segment re-runs and streams to the client on a
+> navigation or action — never whether a cached value is stale. The cache
+> decides hit/miss/ttl/swr independently and never reads `revalidate()`. See
+> `/cache-guide` → "Two axes" and `/rango` → "The shape of rango".
+
 Handler-first guarantees apply within a single full render pass. For partial
 action revalidation, define named revalidation contracts and reuse them on both
 the producer route and the consumer child segments.
 
 ```typescript
 // revalidation-contracts.ts
-export const revalidateCheckoutData = ({ actionId }) =>
-  actionId?.includes("src/actions/checkout.ts#") ?? false;
+import * as CheckoutActions from "./actions/checkout";
+
+// Defer (|| undefined), not ?? false: a hard `false` short-circuits the chain,
+// so when the same segment composes multiple contracts the later ones never run.
+export const revalidateCheckoutData = (ctx) =>
+  ctx.isAction(CheckoutActions) || undefined;
 
 path("/checkout", CheckoutPage, { name: "checkout" }, () => [
   revalidate(revalidateCheckoutData), // producer (route handler) reruns
@@ -270,9 +280,6 @@ path("/checkout", CheckoutPage, { name: "checkout" }, () => [
 ]);
 ```
 
-For scope/revalidation guarantees and non-guarantees, see:
-[docs/execution-model.md](../../docs/internal/execution-model.md)
-
 ## Redirects
 
 ### Basic redirect
@@ -289,6 +296,12 @@ path("/old-page", () => redirect("/new-page"), { name: "oldPage" });
 path("/moved", () => redirect("/new-location", 301), { name: "moved" });
 ```
 
+> **Redirecting from a route with `loading()`:** an `async` handler that returns
+> a `Response`/`redirect()` on a route that also declares `loading()` is streamed,
+> so the redirect is rendered into the RSC stream instead of becoming an HTTP
+> redirect. Issue the redirect from `middleware`, a loader, or a **synchronous**
+> handler return instead. (Dev logs a warning if this is hit.)
+
 ### Redirect with location state
 
 Carry typed state through redirects (e.g. flash messages):
@@ -333,6 +346,10 @@ state persists on back/forward. See `/hooks` for details.
 Attach location state to any server response (not just redirects):
 
 ```typescript
+import { createLocationState } from "@rangojs/router";
+
+const ServerInfo = createLocationState<{ data: string }>();
+
 path("/dashboard", (ctx) => {
   ctx.setLocationState(ServerInfo({ data: "welcome" }));
   return <Dashboard />;

package/skills/router-setup/SKILL.md

@@ -62,6 +62,9 @@ urls(
     revalidate, // Control revalidation
     intercept, // Intercept routes for modals
     when, // Conditional rendering
+    errorBoundary, // Add an error boundary
+    notFoundBoundary, // Add a not-found boundary
+    transition, // Configure view transitions
   }) => [
     // Route definitions here
   ],
@@ -71,7 +74,7 @@ urls(
 ## Router Options
 
 ```typescript
-interface RSCRouterOptions<TEnv> {
+interface RangoOptions<TEnv> {
   // URL patterns from urls() function
   urls: UrlPatterns;
 
@@ -405,7 +408,7 @@ interface AppBindings {
   KV: KVNamespace;
 }
 
-// Variables declared via module augmentation
+// Variables declared via global namespace augmentation
 interface AppVariables {
   user?: { id: string; name: string };
 }
@@ -417,7 +420,7 @@ const router = createRouter<AppBindings>({
 
 // Register types globally for implicit typing
 declare global {
-  namespace RSCRouter {
+  namespace Rango {
     interface Env extends AppBindings {}
     interface Vars extends AppVariables {}
   }
@@ -469,14 +472,34 @@ const router = createRouter({
 ```
 
 ```typescript
-// OpenTelemetry for production
-import { createRouter, createOTelSink } from "@rangojs/router";
+// OpenTelemetry for production: phase spans via the tracing slot,
+// discrete-fact spans via the telemetry sink.
+import {
+  createRouter,
+  createOTelTracing,
+  createOTelSink,
+} from "@rangojs/router";
 import { trace } from "@opentelemetry/api";
 
+const tracer = trace.getTracer("my-app");
+
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  tracing: createOTelTracing(tracer),
+  telemetry: createOTelSink(tracer),
+});
+```
+
+```typescript
+// On Cloudflare Workers, swap the tracing factory for native custom spans
+// (no @opentelemetry/api dependency); the telemetry slot is unchanged.
+import { createCloudflareTracing } from "@rangojs/router/cloudflare";
+
 const router = createRouter({
   document: Document,
   urls: urlpatterns,
-  telemetry: createOTelSink(trace.getTracer("my-app")),
+  tracing: createCloudflareTracing(), // { spans: { ssr: false } } to toggle phases
 });
 ```
 

package/skills/scripts/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: scripts
+description: Inject third-party scripts (GTM, analytics, widgets) into the document head/body via the Script handle
+argument-hint: "[vendor]"
+---
+
+# Scripts
+
+Inject `<script>` tags into the document the idiomatic Rango way: push a config
+from a **server** route/layout handler with `ctx.use(Script)(config)`, and render
+them with the built-in **`<Scripts />`** component (the `Meta` / `<MetaTags>`
+pair, but for scripts). The request CSP **nonce is applied automatically to
+document-rendered scripts** — you never read or pass it. (The one exception is an
+async script first encountered on a soft navigation; see the nonce caveat under
+"Execution contract".)
+
+## Setup
+
+`<Scripts />` is a client component; place it in your Document (which is
+`"use client"`). The default Document already includes both sites; a custom one
+adds them next to `<MetaTags />`:
+
+```tsx
+// document.tsx ("use client")
+import { MetaTags, Scripts } from "@rangojs/router/client";
+
+export function Document({ children }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <MetaTags />
+        <Scripts /> {/* renders position: "head" scripts (the default) */}
+      </head>
+      <body>
+        <Scripts position="body" /> {/* renders position: "body" scripts */}
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+
+## Push from a handler
+
+`ScriptConfig` is a discriminated union — exactly one of three shapes, so invalid
+combinations are compile errors:
+
+```ts
+import { Script } from "@rangojs/router";
+
+// 1. External ASYNC — a React resource. Loads once when first encountered,
+//    including after a soft navigation, deduped by src. The fire-and-forget case.
+ctx.use(Script)({ id: "stripe", src: "https://js.stripe.com/v3", async: true });
+
+// 2. External ORDERED — in-place, optional `defer`. Document-load (see below).
+ctx.use(Script)({
+  id: "plausible",
+  src: "https://plausible.io/js/script.js",
+  defer: true,
+  attributes: { "data-domain": "example.com" },
+});
+
+// 3. INLINE — `id` REQUIRED, raw JS body (escaped against </script> by <Scripts>).
+//    For GTM/GA4/Segment let the body self-inject its loader (see below).
+ctx.use(Script)({ id: "gtm", children: gtmBootstrap("GTM-XXXX") });
+```
+
+| Shape            | Required             | Optional                                        | Forbidden               |
+| ---------------- | -------------------- | ----------------------------------------------- | ----------------------- |
+| Inline           | `id`, `children`     | `position`, `type`, `attributes`                | `src`, `async`, `defer` |
+| External async   | `src`, `async: true` | `id`, `position`, `type`, `attributes`          | `children`, `defer`     |
+| External ordered | `src`                | `defer`, `id`, `position`, `type`, `attributes` | `children`, `async`     |
+
+- `id` — dedup key (last-push-wins), and rendered as the script's DOM `id` (for
+  vendors that target `<script id="…">`). Required for inline (React never dedups
+  inline scripts); for ordered external it falls back to `src`. Async externals
+  dedup by `src` (matching React), so there `id` is the DOM id only.
+- `position` — `"head"` (default) or `"body"`. An async script is hoisted to
+  `<head>` by React regardless.
+- `type` — free string: `"module"`, `"application/ld+json"`, `"text/partytown"`, …
+- `attributes` — React-cased (`crossOrigin`, not `crossorigin`) and React-typed
+  (`data-*`, `integrity`, `referrerPolicy`, …). Excluded: the fields the handle
+  manages (`id`/`src`/`async`/`defer`/`type`/`children`/`nonce`) and all `on*`
+  handlers (`onLoad`/`onError`/… — a config is serialized to the client, so a
+  function can't survive; use a `"use client"` component for callbacks).
+
+## Execution contract (read this)
+
+React makes a `<script>` it mounts on the client INERT (it creates the element via
+innerHTML, which the HTML spec never executes). So:
+
+| Script                           | Runs on hard load              | Runs on soft (`<Link>`) navigation                    |
+| -------------------------------- | ------------------------------ | ----------------------------------------------------- |
+| Inline (`children`)              | Yes (it's in the initial HTML) | **No** — it is document-load only                     |
+| External ordered (`defer`/plain) | Yes                            | **No** — document-load only                           |
+| External `async`                 | Yes                            | **Yes** — React loads the resource on first encounter |
+
+`<Scripts>` enforces this honestly: after hydration it **freezes** the inline +
+ordered set to what was in the initial HTML, so a navigation never inserts an
+inert (silently dead) `<script>`. Async configs stay reactive. Reusing an `id`
+shapes the INITIAL document output (last-push-wins) — it does not re-run a script
+during navigation.
+
+**Nonce caveat for soft-nav async.** The "nonce is applied automatically" claim
+holds for DOCUMENT-RENDERED scripts (they carry the nonce in the SSR HTML). An
+async script first encountered on a soft navigation is injected by React on the
+client, where `useNonce()` is `undefined` by design (the router does not serialize
+the nonce to the client — that would weaken CSP), so it has no nonce attribute. It
+still loads under `'strict-dynamic'` (React's nonced runtime injects it, so the
+trust propagates) — which is the recommended policy — or if your `script-src`
+allows the host. A nonce-only policy without `'strict-dynamic'` would block it.
+
+**Per-navigation behavior belongs in a client component or hook**, not in a
+re-pushed inline script. The GTM demo does exactly this: a root-layout `Script`
+bootstrap fires the first page_view on document load, and a `"use client"`
+`<GtmPageViews>` component fires a page_view on every subsequent soft navigation.
+
+## The inline-self-inject rule (GTM/GA4/Segment)
+
+If an inline bootstrap must run **before** an external loader, do NOT push the
+loader as a separate `{ src, async }` config: React 19 hoists a declarative
+`<script async src>` to the **top** of `<head>`, above your inline bootstrap, so
+the loader could run before the bootstrap. Instead let the bootstrap inject its
+own loader (Google's snippet does exactly this):
+
+```ts
+function gtmBootstrap(id: string): string {
+  return [
+    "window.dataLayer=window.dataLayer||[];",
+    'window.dataLayer.push({"gtm.start":new Date().getTime(),event:"gtm.js"});',
+    `(function(d,s,i){var j=d.createElement(s);j.async=true;j.src="https://www.googletagmanager.com/gtm.js?id="+encodeURIComponent(i);var f=d.getElementsByTagName(s)[0];f.parentNode.insertBefore(j,f);})(document,"script",${JSON.stringify(id)});`,
+  ].join("");
+}
+```
+
+Under a `'strict-dynamic'` CSP the nonced inline script vouches for the loader it
+creates, so the injected loader needs no nonce of its own.
+
+### Per-route tagging on the first render
+
+A route can **override** a layout's bootstrap by reusing the `id`, baking
+per-route data into the FIRST (hard-load) page_view server-side — the Script
+handle is collected after handlers run (parent → child, last-wins):
+
+```ts
+// root layout: generic bootstrap
+ctx.use(Script)({ id: "gtm", children: gtmBootstrap("GTM-XXXX") });
+// a route: same id, with content_group baked in
+ctx.use(Script)({
+  id: "gtm",
+  children: gtmBootstrapWith({ content_group: "blog" }),
+});
+```
+
+## CSP
+
+The nonce is automatic for document-rendered scripts. Include `'strict-dynamic'`
+in `script-src` (recommended): besides letting a nonced loader vouch for the
+scripts it injects, it also covers the one nonce-less case — an async script first
+loaded on a soft navigation is injected client-side without a nonce (see the
+caveat above), and `'strict-dynamic'` trusts it via React's nonced runtime.
+Otherwise allow the vendor hosts. For GTM/GA4 (Google's wildcards): `script-src
+'self' 'nonce-…' 'strict-dynamic' https://*.googletagmanager.com`, plus `img-src`
+/ `connect-src` for `*.google-analytics.com` / `*.analytics.google.com`, and
+`frame-src https://*.googletagmanager.com` for the GTM `<noscript>` iframe. See
+[Google's CSP guide](https://developers.google.com/tag-platform/security/guides/csp).
+
+## Not covered (do it yourself)
+
+- **`onLoad` / `onReady` / `onError`** — callbacks can't cross the server handle
+  boundary. Render your own `"use client"` component with a load listener keyed
+  off the script id.
+- **`<noscript>` fallbacks** (e.g. the GTM body iframe) — not a `<script>`;
+  render it directly in your Document `<body>`.
+- **Partytown / web-worker offloading** — push the worker config with
+  `type: "text/partytown"` and wire Partytown's own nonce config manually.
+
+A full GTM + GA4-style integration (page_view on first render + soft nav, nonce,
+ecommerce events) lives in `tests/vite-rsc-demo`.