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

package/skills/response-routes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: response-routes
-description: Response routes (path.json, path.text, etc.) for non-RSC endpoints with typed responses
+description: Response routes (path.json, path.text, etc.) for non-RSC endpoints with typed responses. Use when building a JSON/text API endpoint alongside your pages, or asking how to return raw JSON instead of RSC from a route.
 argument-hint: [json|text|html|xml|md|image|stream]
 ---
 
@@ -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,20 +241,23 @@ 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 }[]
 ```
 
+`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.
+
 ### 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
-`ResponseEnvelope<never>`:
+has no response payload metadata, so response routes resolve to `never`:
 
 ```typescript
 // router.tsx
@@ -261,11 +275,11 @@ 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 = Rango.PathResponse<"/api/health">;
-// = ResponseEnvelope<{ status: string; timestamp: number }>
+// = { status: string; timestamp: number }
 
-// RSC routes return ResponseEnvelope<never>
+// RSC routes (no JSON payload) return never
 type Home = Rango.PathResponse<"/">;
-// = ResponseEnvelope<never>
+// = never
 ```
 
 `Rango.PathResponse` also accepts a **concrete path**, so it types a `fetch`
@@ -280,7 +294,7 @@ async function get<T extends Rango.Path>(
   return fetch(href(path)).then((r) => r.json());
 }
 
-const product = await get("/api/products/42"); // ResponseEnvelope<Product>
+const product = await get("/api/products/42"); // Product (bare value)
 ```
 
 Pattern keys (`/:id`) match exactly; a concrete path under a _nested_ dynamic
@@ -288,7 +302,7 @@ 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 `ResponseEnvelope<{ createdAt: string }>`. This
+`{ 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
@@ -302,7 +316,7 @@ the response payload straight from the `urls()` patterns and needs no
 ### 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">;
@@ -404,21 +418,35 @@ export const urlpatterns = urls(({ path, include }) => [
 ]);
 ```
 
+A heavy module like this is a good code-split candidate. Pass an async provider
+and the module — its handlers, response serializers, and any nested
+`include()`s — loads on the first request under the prefix instead of at startup:
+
+```typescript
+// blog/urls.tsx: `export default blogPatterns`
+include("/blog", () => import("./blog/urls"), { name: "blog" }),
+```
+
+Named routes and response types still resolve through the split: `TRoutes` and
+the `_responses` phantom are inferred from the resolved `urls()` value, so
+`Rango.PathResponse<"/blog/api/stats">` and `ctx.reverse` are unchanged. See
+`/composability`.
+
 ### Type safety after mounting
 
 ```typescript
 import type { RouteResponse } from "@rangojs/router";
-import type { ParamsFor } from "@rangojs/router/client";
+import type { ParamsFor } from "@rangojs/router";
 
 // 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.
 // Rango.PathResponse needs `RegisteredRoutes extends typeof router.routeMap` (see above),
-// otherwise it resolves to ResponseEnvelope<never>.
+// otherwise it resolves to never.
 type BlogStats = Rango.PathResponse<"/blog/api/stats">;
-// = ResponseEnvelope<{ views: number; visitors: number }>
+// = { views: number; visitors: number }
 
 // Params work through nested includes
 type LikesParams = ParamsFor<"blog.api.likes">;
@@ -462,7 +490,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

@@ -1,6 +1,6 @@
 ---
 name: route
-description: Define routes with path() in @rangojs/router
+description: Define routes with path() in @rangojs/router. Use when creating a new page or route, or asking how to define a URL path and its handler.
 argument-hint: [pattern]
 ---
 
@@ -53,6 +53,49 @@ For the common pattern of an optional locale prefix
 locale detection, fallback chains, URL generation with absent locale —
 see `/i18n`.
 
+### Named catch-all params (`:name+` / `:name*`)
+
+A catch-all consumes the **rest of the path** and exposes it as a single
+decoded string at `ctx.params.<name>`, with the internal `/` separators kept.
+It must be the **last** segment of the pattern.
+
+- `:name+` — **one-or-more** segments (Next `[...name]`, React-Router splat).
+  `/docs/:slug+` matches `/docs/a` and `/docs/a/b/c`, but **not** the bare
+  `/docs`.
+- `:name*` — **zero-or-more** segments (Next `[[...name]]`). `/docs/:slug*`
+  additionally matches the bare `/docs`, binding `ctx.params.slug` to `""`.
+
+```typescript
+urls(({ path }) => [
+  // /shop/electronics/phones -> ctx.params.path === "electronics/phones"
+  path("/shop/:path+", ShopCatchAll, { name: "shopCatchAll" }),
+
+  // /docs         -> ctx.params.slug === ""
+  // /docs/intro   -> ctx.params.slug === "intro"
+  // /docs/a/b     -> ctx.params.slug === "a/b"
+  path("/docs/:slug*", (ctx) => {
+    const parts = ctx.params.slug === "" ? [] : ctx.params.slug.split("/");
+    return <Docs segments={parts} />;
+  }, { name: "docs" }),
+]);
+```
+
+`ctx.params.<name>` is always a `string` for a catch-all (never `undefined`) —
+`:name*` binds `""` for the empty case, so read it directly. `reverse()` /
+`ctx.reverse()` rebuild the URL with separators preserved:
+`reverse("docs", { slug: "a/b" })` -> `/docs/a/b`.
+
+The value is the URL-decoded remainder. `split("/")` recovers the segments in the
+common case, but note that a segment containing an encoded slash (`%2F`) decodes
+to a literal `/` and is therefore indistinguishable from a separator — the same
+trade-off the bare `*` splat has. If you need to distinguish those, match on the
+raw pathname instead.
+
+The bare unnamed wildcard `path("/files/*", …)` still works and is read at
+`ctx.params["*"]`; prefer a named catch-all when you want a typed param key.
+Combining a modifier with `?`, a literal suffix, or a constraint
+(`:slug*?`, `:slug*.html`, `:slug(a|b)+`) is rejected at build time.
+
 ## Route Handler Patterns
 
 ### Component Function
@@ -154,6 +197,13 @@ first. Use `ctx.set(key, value)` to share data with children, who read it
 via `ctx.get(key)`. Caching wraps all segments together, so either all run
 or none do.
 
+This pattern is also safe under partial action revalidation: on an action,
+the route entry re-runs as a unit by default — route segment, loaders, and
+`belongsToRoute` children (orphan layouts, entry parallels) all seed
+revalidate-true, with handler-first ordering preserved. Handler-set data
+stays consistent with no configuration. See `/rango` → "Passing data down
+the tree" for the safest-first ladder.
+
 ### Typed context variables with createVar
 
 Use `createVar<T>()` to create a typed token for `ctx.set()`/`ctx.get()`.
@@ -240,16 +290,27 @@ Cacheable vars (the default) can be read freely inside cache scopes.
 > 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.
+With no `revalidate()` configured, an entry needs no contract: on an action
+the route handler and its children re-run together by default, so handler
+data stays consistent on its own. Contracts matter in two cases:
+
+1. **You narrow the entry's revalidation** with a predicate that can return a
+   hard `false` (e.g. bare `ctx.isAction(X)`). A hard `false` on one side of a
+   producer/consumer pair desyncs it — the child re-runs by default and reads
+   `undefined`, or vice versa. Put the same named contract on the route and
+   its dependent children so they narrow together.
+2. **The producer is an outer entry** (a standalone `layout()` above this
+   route). Outer entries skip action revalidation by default, so the shared
+   contract is mandatory — see `/layout` → "Revalidation Contracts".
 
 ```typescript
 // revalidation-contracts.ts
+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 = ({ actionId }) =>
-  actionId?.includes("src/actions/checkout.ts#") || undefined;
+export const revalidateCheckoutData = (ctx) =>
+  ctx.isAction(CheckoutActions) || undefined;
 
 path("/checkout", CheckoutPage, { name: "checkout" }, () => [
   revalidate(revalidateCheckoutData), // producer (route handler) reruns
@@ -294,6 +355,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):
@@ -338,6 +405,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 />;
@@ -408,6 +479,14 @@ urls(({ path, layout }) => [
 ])
 ```
 
+For composing whole route MODULES, reach for `include()` — and prefer the
+code-split form `include("/shop", () => import("./shop-patterns"))` for any
+group that is a natural unit: it keeps the group off the cold-start path, and
+measured first-hit cost scales with routes-per-chunk, so many small groups
+beat one giant one. Sizing rules and the numbers behind them:
+[skills/composability](../composability/SKILL.md) → "Sizing async include
+groups (measured)".
+
 ## View Transitions
 
 A route can configure its own `transition()` — the wrap goes around the route's component itself (routes are leaves; they have no separate default outlet channel). If the route component renders a `<ParallelOutlet />` directly, that slot remains inside the route's VT subtree, so prefer mounting parallel slots in a layout when combining intercept modals with route-level transitions. See [skills/view-transitions](../view-transitions/SKILL.md) for examples and the wrap-location rules across layouts, routes, and slots.

package/skills/router-setup/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: router-setup
-description: Create and configure the RSC router with createRouter
+description: Create and configure the RSC router with createRouter. Use when bootstrapping a new Rango app, or configuring top-level router options like base path, cache store, or environment.
 argument-hint: [option]
 ---
 
@@ -60,8 +60,10 @@ urls(
     cache, // Configure caching
     middleware, // Add middleware
     revalidate, // Control revalidation
-    intercept, // Intercept routes for modals
-    when, // Conditional rendering
+    intercept, // Intercept routes for modals (conditional via intercept(..., { when }))
+    errorBoundary, // Add an error boundary
+    notFoundBoundary, // Add a not-found boundary
+    transition, // Configure view transitions
   }) => [
     // Route definitions here
   ],
@@ -396,6 +398,18 @@ export const urlpatterns = urls(({ path, include }) => [
 ]);
 ```
 
+`include()` also accepts an async provider to code-split that group into its own
+chunk, imported on the first request reaching the prefix instead of at startup:
+
+```typescript
+// urls/shop.tsx: `export default shopPatterns`
+include("/shop", () => import("./urls/shop"), { name: "shop" }),
+```
+
+Build-time discovery still `await`s the provider, so route types, `href()`, and
+prerender see every route in the split group. Reach for it when a group is a
+large, independently-loadable unit — see `/composability`.
+
 ## Environment Types
 
 ```typescript
@@ -469,14 +483,35 @@ 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.
+// On Vercel (Node runtime) use createVercelTracing() from @rangojs/router/vercel.
+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. Use when adding Google Tag Manager, an analytics snippet, or a third-party widget script to the page.
+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`.