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

package/AGENTS.md

@@ -7,3 +7,11 @@ Run `/rango` to understand the API. Detailed guides for each feature are in the
 ## Development rules
 
 - Always commit generated files (e.g. `*.gen.ts`) alongside the source changes that produced them.
+
+## Repo-wide rules (read before pushing)
+
+This package inherits the repo-wide conventions in the root [`AGENTS.md`](../../AGENTS.md) and [`CLAUDE.md`](../../CLAUDE.md). The ones a package-scoped reader is most likely to miss:
+
+- **Pre-push gate** — before EVERY push, run all of the following from the **repo root** and fix any failures: `pnpm run typecheck`, `pnpm run test:unit:all`, `pnpm run lint`, `pnpm run format`.
+- **`test:unit:all` is recursive** — it runs the unit AND Flight/RSC suites for every package and consumer app (cloudflare-basic, mini, vite-rsc-demo, ...), not just `@rangojs/router`. A change can pass this package's own tests while breaking a consumer app's `@rangojs/router/testing` dogfood suite, so do not run only `pnpm --filter @rangojs/router test:unit`.
+- **Dev + prod e2e parity is mandatory** — every e2e test must cover BOTH dev and production modes; never add a dev-only test without its production counterpart. See the dev/prod bucketing convention in the root `AGENTS.md`.

package/README.md

@@ -1,6 +1,8 @@
-# @rangojs/router
+# Rango
 
-Named-route RSC router with structural composability and type-safe partial rendering for Vite.
+React RSC Route Wrangler
+
+A code-first, type-safe React Server Components router
 
 > **Experimental:** This package is under active development. APIs may change between releases. Install with `@experimental` tag.
 
@@ -10,6 +12,7 @@ Named-route RSC router with structural composability and type-safe partial rende
 - **Structural composability** — Attach routes, loaders, middleware, handles, caching, prerendering, and static generation without hiding the route tree
 - **Composable URL patterns** — Django-style `urls()` DSL with `path`, `layout`, `include`
 - **Data loaders** — `createLoader()` with automatic streaming and Suspense integration
+- **Server actions** — `"use server"` mutations with `useActionState`, `useOptimistic`, and per-segment + per-loader `revalidate()` rules
 - **Live data layer** — Pre-render or cache the UI shell while loaders stay live by default at request time
 - **Layouts & nesting** — Nested layouts with `<Outlet />` and parallel routes
 - **Segment-level caching** — `cache()` DSL with TTL/SWR and pluggable cache stores
@@ -91,24 +94,29 @@ This file is a server/RSC module and should import router construction APIs from
 
 ```tsx
 // src/router.tsx
-import { createRouter, urls } from "@rangojs/router";
-import { Document } from "./document";
+import { createRouter } from "@rangojs/router";
 
-const blogPatterns = urls(({ path }) => [
-  path("/", BlogIndexPage, { name: "index" }),
-  path("/:slug", BlogPostPage, { name: "post" }),
+export const router = createRouter().routes(({ path }) => [
+  path("/", HomePage, { name: "home" }),
+  path("/about", AboutPage, { name: "about" }),
 ]);
 
+export const reverse = router.reverse;
+// reverse("home") -> "/"
+```
+
+For larger apps, extract route modules with `urls()` and compose with `include()`:
+
+```tsx
+import { createRouter, urls } from "@rangojs/router";
+import { blogPatterns } from "./urls/blog";
+
 const urlpatterns = urls(({ path, include }) => [
   path("/", HomePage, { name: "home" }),
   include("/blog", blogPatterns, { name: "blog" }),
 ]);
 
-export const router = createRouter({ document: Document }).routes(urlpatterns);
-
-// Export typed reverse function for URL generation by route name
-export const reverse = router.reverse;
-
+export const router = createRouter().routes(urlpatterns);
 // reverse("blog.post", { slug: "hello-world" }) -> "/blog/hello-world"
 ```
 
@@ -119,20 +127,29 @@ export const reverse = router.reverse;
 "use client";
 
 import type { ReactNode } from "react";
-import { MetaTags } from "@rangojs/router/client";
+import { MetaTags, Scripts } from "@rangojs/router/client";
 
 export function Document({ children }: { children: ReactNode }) {
   return (
     <html lang="en">
       <head>
         <MetaTags />
+        <Scripts />
       </head>
-      <body>{children}</body>
+      <body>
+        <Scripts position="body" />
+        {children}
+      </body>
     </html>
   );
 }
 ```
 
+`<MetaTags />` and `<Scripts />` render the tags collected by the built-in `Meta`
+and `Script` handles (see [Meta Tags](#meta-tags) and [Scripts](#scripts)). The
+built-in `DefaultDocument` already includes all three sites, so this is only
+needed for a custom document.
+
 ## Defining Routes
 
 Rango is a named-route router first.
@@ -156,13 +173,18 @@ const urlpatterns = urls(({ path }) => [
 ]);
 ```
 
-Use `reverse()` as the default way to link to routes:
+Use `ctx.reverse()` from handler context as the default way to link to routes from server code:
 
 ```tsx
-router.reverse("product", { slug: "widget" }); // "/product/widget"
-router.reverse("search", undefined, { q: "rsc" }); // "/search?q=rsc"
+const ProductPage: Handler<"product"> = (ctx) => {
+  const url = ctx.reverse("product", { slug: "widget" }); // "/product/widget"
+  const searchUrl = ctx.reverse("search", undefined, { q: "rsc" }); // "/search?q=rsc"
+  return <Link to={url}>Widget</Link>;
+};
 ```
 
+`router.reverse()` (exported from the router module) is the same function without a handler context, useful in scripts or tests. In request code, prefer `ctx.reverse()` — it auto-fills mount params from the current match.
+
 ### Composable URL Modules
 
 Local route names compose cleanly with `include(..., { name })`:
@@ -472,41 +494,130 @@ const urlpatterns = urls(({ path, loader }) => [
 ]);
 ```
 
-## Navigation & Links
+## Server Actions
+
+Server actions are React's RSC mutation primitive. Define them with the
+`"use server"` directive — Rango uses standard React 19 hooks
+(`useActionState`, `useFormStatus`, `useOptimistic`) with no framework wrapper.
 
-### Named Routes with `reverse()` (Server Components)
+```tsx
+// app/actions/cart.ts
+"use server";
 
-In server components, use `reverse()` to generate URLs by route name:
+import { getRequestContext } from "@rangojs/router";
+
+export async function addToCart(productId: string): Promise<void> {
+  const ctx = getRequestContext();
+  const userId = ctx.get("user").id;
+  await db.cart.insert({ userId, productId });
+}
+```
 
 ```tsx
-import { Link } from "@rangojs/router/client";
-import { reverse } from "./router";
+// Client form with progressive enhancement + pending state
+"use client";
+import { useActionState } from "react";
+import { saveProfile } from "../actions/profile";
 
-function BlogIndex() {
+export function ProfileForm() {
+  const [state, action, pending] = useActionState(saveProfile, null);
   return (
-    <nav>
-      <Link to={reverse("home")}>Home</Link>
-      <Link to={reverse("blogPost", { slug: "my-post" })}>My Post</Link>
-      <Link to={reverse("about")}>About</Link>
-    </nav>
+    <form action={action}>
+      <input name="name" defaultValue={state?.values?.name} />
+      {state?.errors?.name && <p role="alert">{state.errors.name}</p>}
+      <button disabled={pending}>{pending ? "Saving…" : "Save"}</button>
+    </form>
   );
 }
 ```
 
-`reverse()` is type-safe — route names and required params are checked at compile time. Included routes use dotted names: `reverse("api.health")`.
+After an action runs, matched route segments (path/layout/parallel/intercept)
+and loaders can re-render/re-resolve so the UI reflects the new state.
+Attach a `revalidate(({ actionId }) => ...)` rule on any segment or loader
+that owns data the action touched:
+
+```tsx
+urls(({ path, loader, revalidate }) => [
+  // Segment-level: re-render the cart page handler after cart actions.
+  // Nest loaders that belong to this route inside the same path() so the
+  // segment owns its data dependencies.
+  path("/cart", CartPage, { name: "cart" }, () => [
+    revalidate(
+      ({ actionId }) => actionId?.startsWith("src/actions/cart.ts#") ?? false,
+    ),
+    loader(CartLoader, () => [
+      revalidate(
+        ({ actionId }) => actionId?.startsWith("src/actions/cart.ts#") ?? false,
+      ),
+    ]),
+  ]),
+]);
+```
+
+For the full guide — validation with Zod, error handling, file uploads,
+`useOptimistic`, redirects, and progressive enhancement — see the
+`/server-actions` skill.
+
+## Navigation & Links
+
+### Named Routes with `ctx.reverse()` (Server)
 
-Handlers also have `ctx.reverse()` directly on the context:
+In server components and handlers, use `ctx.reverse()` to generate URLs by route name. This is the default — it is typed, auto-fills mount params from the current match, and resolves both local (`.name`) and absolute (`name.sub`) names:
 
 ```tsx
+import { Link } from "@rangojs/router/client";
+import type { Handler } from "@rangojs/router";
+
 const BlogPostPage: Handler<"blogPost"> = (ctx) => {
   const backUrl = ctx.reverse("blog");
   return <Link to={backUrl}>Back to blog</Link>;
 };
 ```
 
+`reverse()` is type-safe — route names and required params are checked at compile time. Included routes use dotted names: `ctx.reverse("api.health")`.
+
+For scripts, tests, or other code without a handler context, import the router-level `reverse`:
+
+```tsx
+import { reverse } from "./router";
+reverse("blogPost", { slug: "my-post" });
+```
+
+### Client Components
+
+**`reverse()` is server-only.** It depends on the route manifest and handler context — neither is available in the browser bundle. Client components receive URLs as props, loader data, or server-action return values:
+
+```tsx
+// server
+function BlogIndex(ctx: HandlerContext) {
+  return (
+    <Nav
+      home={ctx.reverse("home")}
+      post={ctx.reverse("blogPost", { slug: "my-post" })}
+    />
+  );
+}
+```
+
+```tsx
+"use client";
+import { Link } from "@rangojs/router/client";
+
+export function Nav({ home, post }: { home: string; post: string }) {
+  return (
+    <nav>
+      <Link to={home}>Home</Link>
+      <Link to={post}>My Post</Link>
+    </nav>
+  );
+}
+```
+
+For client-side navigation to static paths (no named-route lookup), use `href()` — see below. For URLs tied to named routes, you have two options: import the per-module generated `routes` map and use `useReverse(routes)` for in-module names (see [`/links` skill](./skills/links/SKILL.md)), or generate the URL on the server and pass the string in for cross-module URLs.
+
 ### `href()` for Path Validation (Client Components)
 
-In client components, use `href()` for compile-time path validation:
+In client components, use `href()` for compile-time path validation on static path strings:
 
 ```tsx
 "use client";
@@ -711,10 +822,12 @@ export const BlogPost = Prerender(
 
 ### Passthrough for Unknown Params
 
+Wrap a `Prerender` definition with `Passthrough()` to add a live handler for unknown params at runtime. The build handler runs at build time, the live handler runs at request time for params not in the prerender cache.
+
 ```tsx
-import { Prerender } from "@rangojs/router";
+import { Prerender, Passthrough } from "@rangojs/router";
 
-export const ProductPage = Prerender(
+export const ProductPageDef = Prerender(
   async () => {
     const featured = await db.getFeaturedProducts();
     return featured.map((p) => ({ id: p.id }));
@@ -723,16 +836,22 @@ export const ProductPage = Prerender(
     const product = await db.getProduct(ctx.params.id);
     return <Product data={product} />;
   },
-  { passthrough: true },
 );
-```
 
-With `passthrough: true`, known params are served from the build-time cache and unknown params fall through to live rendering.
+// In route definition:
+path(
+  "/products/:id",
+  Passthrough(ProductPageDef, async (ctx) => {
+    const product = await ctx.env.DB.getProduct(ctx.params.id);
+    return <Product data={product} />;
+  }),
+);
+```
 
-Handlers can also skip individual param sets with `ctx.passthrough()`, deferring them to the live handler at runtime:
+Build handlers can also skip individual param sets with `ctx.passthrough()`, deferring them to the live handler:
 
 ```tsx
-export const ProductPage = Prerender(
+export const ProductPageDef = Prerender(
   async () => {
     const all = await db.getAllProducts();
     return all.map((p) => ({ id: p.id }));
@@ -742,10 +861,55 @@ export const ProductPage = Prerender(
     if (!product.published) return ctx.passthrough();
     return <Product data={product} />;
   },
-  { passthrough: true },
 );
 ```
 
+### Build-Time Environment Bindings
+
+Prerender handlers can access platform bindings (KV, D1, R2) at build time when `buildEnv` is configured in the Vite plugin:
+
+```ts
+// vite.config.ts
+import { rango } from "@rangojs/router/vite";
+
+rango({ preset: "cloudflare", buildEnv: "auto" });
+```
+
+With `buildEnv: "auto"`, the plugin calls `wrangler.getPlatformProxy()` to provide local bindings. Handlers then access `ctx.env` during build:
+
+```tsx
+export const BlogPosts = Prerender<{ slug: string }>(
+  async (ctx) => {
+    const rows = await ctx.env.DB.prepare("SELECT slug FROM posts").all();
+    return rows.map((r) => ({ slug: r.slug }));
+  },
+  async (ctx) => {
+    const post = await ctx.env.DB.prepare("SELECT * FROM posts WHERE slug = ?")
+      .bind(ctx.params.slug)
+      .first();
+    return <BlogPost post={post} />;
+  },
+);
+```
+
+`buildEnv` also accepts a factory function or plain object:
+
+```ts
+// Custom factory
+rango({
+  buildEnv: async (ctx) => {
+    const { getPlatformProxy } = await import("wrangler");
+    const proxy = await getPlatformProxy();
+    return { env: proxy.env, dispose: proxy.dispose };
+  },
+});
+
+// Plain object (Node.js)
+rango({ buildEnv: { DATABASE_URL: process.env.DATABASE_URL } });
+```
+
+Build-time env applies to both production builds and dev on-demand prerender. Without `buildEnv`, accessing `ctx.env` in a Prerender handler throws with a clear error.
+
 ## Theme
 
 ### Router Configuration
@@ -790,9 +954,9 @@ import { createHostRouter } from "@rangojs/router/host";
 
 const hostRouter = createHostRouter();
 
-hostRouter.host(["*.localhost"]).map(() => import("./apps/admin/handler.js"));
-hostRouter.host(["localhost"]).map(() => import("./apps/site/handler.js"));
-hostRouter.fallback().map(() => import("./apps/site/handler.js"));
+hostRouter.host(["*.localhost"]).lazy(() => import("./apps/admin/handler.js"));
+hostRouter.host(["localhost"]).lazy(() => import("./apps/site/handler.js"));
+hostRouter.fallback().lazy(() => import("./apps/site/handler.js"));
 
 export default {
   async fetch(request, env, ctx) {
@@ -801,7 +965,7 @@ export default {
 };
 ```
 
-Each sub-app has its own `createRouter()` and `urls()`. The host router lazily imports the matched app's handler. Patterns are matched in registration order — register more specific patterns (subdomains) before catch-alls.
+Use `.lazy(() => import("./sub-app"))` to mount a lazily-imported sub-app (a module whose `default` export is a handler or nested host router), and `.map((request) => Response)` for an inline request handler. Only `.lazy()` mounts are imported during build-time discovery; `.map(() => import(...))` is a type error. Each sub-app has its own `createRouter()` and `urls()`. Patterns are matched in registration order — register more specific patterns (subdomains) before catch-alls.
 
 ## Meta Tags
 
@@ -823,6 +987,38 @@ export function BlogPostPage(ctx: HandlerContext) {
 
 Render collected tags in the document with `<MetaTags />` from `@rangojs/router/client`.
 
+## Scripts
+
+Inject `<script>` tags (analytics, GTM, widgets) the same way, using the built-in
+`Script` handle — push a config from a handler, render with `<Scripts />`:
+
+```tsx
+import { Script } from "@rangojs/router";
+import type { HandlerContext } from "@rangojs/router";
+import { Outlet } from "@rangojs/router/client";
+
+export function RootLayout(ctx: HandlerContext) {
+  // Inline bootstrap (GTM/GA4/Segment) — rendered with the request CSP nonce.
+  ctx.use(Script)({ id: "gtm", children: gtmBootstrap("GTM-XXXX") });
+  // External async resource (loads on first encounter, deduped by src).
+  ctx.use(Script)({
+    id: "plausible",
+    src: "https://plausible.io/js/script.js",
+    async: true,
+    attributes: { "data-domain": "example.com" },
+  });
+  return <Outlet />;
+}
+```
+
+Render with `<Scripts />` (head) and `<Scripts position="body" />` (body) from
+`@rangojs/router/client` (both are wired in `DefaultDocument`). The request CSP
+nonce is applied automatically to document-rendered scripts. `ScriptConfig` is a
+discriminated union (inline / external-async / external-ordered), and inline +
+ordered scripts are document-load while async externals are React resources — see
+the [`/scripts` skill](./skills/scripts/SKILL.md) for the full execution contract
+and CSP guidance.
+
 ## CLI: `rango generate`
 
 Route types are generated automatically by the Vite plugin. The CLI is a manual fallback for generating types outside the dev server (e.g. in CI or for IDE support before first `pnpm dev`):
@@ -840,16 +1036,16 @@ Auto-detects file type:
 
 ## Type Safety
 
-The Vite plugin automatically generates a `router.named-routes.gen.ts` file that globally registers route names, patterns, and search schemas via `RSCRouter.GeneratedRouteMap`. This powers server-side named-route typing such as `Handler<"name">`, `ctx.reverse()`, `getRequestContext().reverse()`, and `RouteParams<"name">` without any manual route registration. The gen file is updated on dev server startup, HMR, and production builds.
+The Vite plugin automatically generates a `router.named-routes.gen.ts` file that globally registers route names, patterns, and search schemas via `Rango.GeneratedRouteMap`. This powers server-side named-route typing such as `Handler<"name">`, `ctx.reverse()`, `getRequestContext().reverse()`, and `RouteParams<"name">` without any manual route registration. The gen file is updated on dev server startup, HMR, and production builds.
 
-Use the generated map by default. Augment `RSCRouter.RegisteredRoutes` only when you need the richer `typeof router.routeMap` shape globally, especially for response-aware and path-based utilities.
+Use the generated map by default. Augment `Rango.RegisteredRoutes` only when you need the richer `typeof router.routeMap` shape globally, especially for response-aware and path-based utilities.
 
 ```typescript
 // router.tsx
 const router = createRouter<AppBindings>({}).routes(urlpatterns);
 
 declare global {
-  namespace RSCRouter {
+  namespace Rango {
     interface Env extends AppEnv {}
     interface Vars extends AppVars {}
     interface RegisteredRoutes extends typeof router.routeMap {}
@@ -861,7 +1057,7 @@ Quick rule of thumb:
 
 - `GeneratedRouteMap` (auto-generated) — use for server-side named-route typing: `Handler<"name">`, `ctx.reverse()`, `Prerender<"name">`
 - `typeof router.routeMap` — use when you need route entries with response metadata
-- `RegisteredRoutes` (manual augmentation) — use to expose `typeof router.routeMap` globally for `href()`, `PathResponse`, `ValidPaths`, and other path/response-aware utilities
+- `RegisteredRoutes` (manual augmentation) — use to expose `typeof router.routeMap` globally for `href()`, `Rango.Path`, `Rango.PathResponse`, and other path/response-aware utilities
 
 For extracted reusable loaders or middleware, prefer global dotted names on
 `ctx.reverse()` by default. If you want type-safe local names for a specific
@@ -889,9 +1085,9 @@ APIs, use their dedicated subpaths.
 
 ## Examples
 
-See the `examples/` directory for full working applications:
+See the example and demo apps for full working applications:
 
-- [`cloudflare-basic`](../../examples/cloudflare-basic) — Cloudflare Workers with caching, loaders, theme, and pre-rendering
+- [`cloudflare-basic`](../../tests/cloudflare-basic) — Cloudflare Workers with caching, loaders, theme, and pre-rendering
 - [`cloudflare-multi-router`](../../examples/cloudflare-multi-router) — Multi-app host routing
 
 ## License