@rangojs/router 0.0.0-experimental.ea6d5eec → 0.0.0-experimental.ea9f40f2

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
   ],
@@ -71,23 +73,28 @@ urls(
 ## Router Options
 
 ```typescript
-interface RSCRouterOptions<TEnv> {
+interface RangoOptions<TEnv> {
   // URL patterns from urls() function
   urls: UrlPatterns;
 
   // Document component wrapping entire app
   document?: ComponentType<{ children: ReactNode }>;
 
+  // URL prefix for sub-path deployments (e.g. "/admin")
+  // All routes, reverse(), href(), Link, redirect(), and router.use()
+  // patterns are automatically prefixed. Route names stay unprefixed.
+  basename?: string;
+
   // Enable per-request performance timeline (console waterfall + Server-Timing header)
   debugPerformance?: boolean;
 
   // Default error boundary
   defaultErrorBoundary?: ReactNode | ErrorBoundaryHandler;
 
-  // Default not-found boundary
+  // Default not-found boundary for notFound() thrown in handlers/loaders
   defaultNotFoundBoundary?: ReactNode | NotFoundBoundaryHandler;
 
-  // Component for 404 routes
+  // Component for 404 (no route match, or notFound() without a boundary)
   notFound?: ReactNode | ((props: { pathname: string }) => ReactNode);
 
   // Error logging callback
@@ -124,6 +131,36 @@ interface RSCRouterOptions<TEnv> {
 }
 ```
 
+## Basename (Sub-Path Deployment)
+
+When your app is served under a sub-path (e.g. `/admin` or `/v2`), set `basename`:
+
+```typescript
+const router = createRouter({
+  basename: "/admin",
+  document: Document,
+}).routes(({ path, include }) => [
+  path("/", Dashboard, { name: "home" }), // matches /admin
+  path("/users", Users, { name: "users" }), // matches /admin/users
+  include("/api", apiPatterns, { name: "api" }), // matches /admin/api/*
+]);
+
+router.reverse("home"); // "/admin"
+router.reverse("users"); // "/admin/users"
+```
+
+Router-owned APIs are basename-aware:
+
+- `reverse()` returns prefixed paths
+- `<Link to="/users">` renders `<a href="/admin/users">`
+- `redirect("/login")` redirects to `"/admin/login"`
+- `router.use("/users/*", mw)` matches `/admin/users/*`
+- `useRouter().push("/users")` navigates to `/admin/users`
+- Route names stay unprefixed (`"home"`, not `"admin.home"`)
+
+Note: `href()` is a raw path helper and does **not** auto-prefix with basename.
+Use `reverse()` or `<Link>` for basename-aware URLs.
+
 ## Using the Request Handler
 
 The router provides a `fetch` method to handle RSC requests:
@@ -290,6 +327,56 @@ const router = createRouter({
 export default router;
 ```
 
+## Not Found Handling
+
+Two distinct 404 scenarios:
+
+**1. No route matches the URL** — the router renders the `notFound` component from `createRouter()` config. This is automatic.
+
+**2. A handler/loader calls `notFound()`** — signals that the route matched but the data doesn't exist (e.g., invalid product ID).
+
+```typescript
+import { notFound } from "@rangojs/router";
+
+// In a handler or loader
+path("/product/:slug", async (ctx) => {
+  const product = await db.getProduct(ctx.params.slug);
+  if (!product) notFound("Product not found");
+  return <ProductPage product={product} />;
+});
+```
+
+### Fallback chain for `notFound()`
+
+When `notFound()` is thrown, the router looks for a fallback in this order:
+
+1. **`notFoundBoundary()`** — nearest boundary in the route tree (route-level)
+2. **`defaultNotFoundBoundary`** — from `createRouter()` config (app-level)
+3. **`notFound`** — from `createRouter()` config (same component used for no-route-match)
+4. **Default `<h1>Not Found</h1>`** — built-in fallback
+
+All cases set HTTP 404 status.
+
+### notFoundBoundary
+
+Wrap routes with `notFoundBoundary()` for route-specific not-found UI:
+
+```typescript
+urls(({ path, layout }) => [
+  layout(ShopLayout, () => [
+    notFoundBoundary(({ notFound: info }) => (
+      <div>
+        <h1>Not Found</h1>
+        <p>{info.message}</p>
+      </div>
+    )),
+    path("/product/:slug", ProductPage),
+  ]),
+]);
+```
+
+`notFoundBoundary` receives `{ notFound: NotFoundInfo }` where `NotFoundInfo` contains `message`, `segmentId`, `segmentType`, and `pathname`.
+
 ## Including Sub-patterns
 
 ```typescript
@@ -311,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
@@ -320,7 +419,7 @@ interface AppBindings {
   KV: KVNamespace;
 }
 
-// Variables declared via module augmentation
+// Variables declared via global namespace augmentation
 interface AppVariables {
   user?: { id: string; name: string };
 }
@@ -332,7 +431,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 {}
   }
@@ -384,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`.