@rangojs/router 0.0.0-experimental.96 → 0.0.0-experimental.96fbd4b7

package/README.md

@@ -10,6 +10,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
@@ -482,6 +483,70 @@ const urlpatterns = urls(({ path, loader }) => [
 ]);
 ```
 
+## 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.
+
+```tsx
+// app/actions/cart.ts
+"use server";
+
+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
+// Client form with progressive enhancement + pending state
+"use client";
+import { useActionState } from "react";
+import { saveProfile } from "../actions/profile";
+
+export function ProfileForm() {
+  const [state, action, pending] = useActionState(saveProfile, null);
+  return (
+    <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>
+  );
+}
+```
+
+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)

package/dist/vite/index.js

@@ -2040,7 +2040,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.96",
+  version: "0.0.0-experimental.96fbd4b7",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.96",
+  "version": "0.0.0-experimental.96fbd4b7",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/hooks/SKILL.md

@@ -323,6 +323,11 @@ RSC serialization strips the `collect` function via `toJSON()`. On the client,
 
 ## Action Hooks
 
+For the full server-action guide (defining actions, `useActionState`,
+`useOptimistic`, validation, revalidation, error handling, file uploads),
+see `/server-actions`. `useAction()` below is a Rango-specific hook for
+tracking actions called outside a `<form action={...}>` flow.
+
 ### useAction()
 
 Track state of server action invocations:

package/skills/links/SKILL.md

@@ -187,6 +187,8 @@ export async function getProductUrl(slug: string) {
 }
 ```
 
+See `/server-actions` for the full action surface (`getRequestContext()` is the same context middleware and handlers use).
+
 For static path strings (not named routes), client components can use `href()` — see below.
 
 ## Client: href()

package/skills/loader/SKILL.md

@@ -6,7 +6,10 @@ argument-hint: [loader]
 
 # Data Loaders with loader()
 
-Loaders fetch data on the server and stream it to the client.
+Loaders fetch data on the server and stream it to the client. For mutations
+(writes triggered by forms or buttons), use server actions instead — see
+`/server-actions`. Loaders re-resolve after an action runs, so the typical
+flow is _action mutates → loader re-reads → UI updates_.
 
 ## Creating a Loader
 

package/skills/middleware/SKILL.md

@@ -32,6 +32,8 @@ When the router has a `basename`, pattern-scoped `.use()` patterns are automatic
 
 Registered inside `urls()` callback. Wraps **rendering only** -- it does NOT wrap server action execution. Actions run before route middleware, so when route middleware executes during post-action revalidation, it can observe state that the action set (cookies, context variables, headers).
 
+> **Implication for auth:** route middleware cannot guard server actions. Use `router.use("/admin/*", requireAuth)` (global, scoped) for action protection, or check inside the action body. See `/server-actions` for action-side auth patterns.
+
 ```
 Request flow (with action):
   global mw -> action executes -> route mw -> layout -> handler -> loaders

package/skills/migrate-nextjs/SKILL.md

@@ -225,7 +225,7 @@ Loaders are Rango's live data layer. Use them when you need:
 
 - **Client-side data refresh** — `useLoader()` in client components for reactive data
 - **Per-loader caching** — opt in with `loader(MyLoader, () => [cache({ ttl: 60 })])`; loaders stay live by default
-- **Revalidation control** — `revalidate()` targets specific loaders after actions
+- **Revalidation control** — `revalidate()` targets specific segments and loaders after actions
 - **Loading skeletons** — `loading()` shows a Suspense fallback while loaders resolve
 
 ```typescript
@@ -463,6 +463,8 @@ Server actions work the same way — `"use server"` directive, `useActionState`,
 
 Key difference: in Rango, route middleware does NOT wrap action execution. Actions only see global middleware context. Use `getRequestContext()` in actions to access `ctx.set()`/`ctx.get()`.
 
+Next.js's `revalidatePath()` / `revalidateTag()` have no direct equivalent — Rango partially re-renders matched route segments (path/layout/parallel/intercept) and re-resolves their loaders, and you scope re-runs by attaching a `revalidate(({ actionId }) => ...)` rule to any segment or loader registration. See `/server-actions` for the full pattern (validation, error handling, file uploads) and `/loader` for revalidation rule semantics.
+
 ## 8. Metadata / Head
 
 Rango uses the `Meta` handle + `<MetaTags />` client component:

package/skills/migrate-react-router/SKILL.md

@@ -483,6 +483,10 @@ Since Rango uses RSC server actions, all React action patterns work:
 `useActionState`, `useOptimistic`, `useTransition`, `startTransition`,
 and plain `<form action={serverAction}>`. No framework-specific hook needed.
 
+For the full guide — defining actions, validation with Zod, error handling,
+revalidation rules, file uploads, and progressive enhancement — see
+`/server-actions`.
+
 ### clientLoader / clientAction (framework mode)
 
 RR7 framework mode's `clientLoader` and `clientAction` run in the browser.

package/skills/rango/SKILL.md

@@ -16,6 +16,7 @@ Django-inspired RSC router with composable URL patterns, type-safe href, and ser
 | `/route`                | Define routes with `urls()` and `path()`                                   |
 | `/layout`               | Layouts that wrap child routes                                             |
 | `/loader`               | Data loaders with `createLoader()`                                         |
+| `/server-actions`       | Mutations with `"use server"`, useActionState, validation, revalidation    |
 | `/middleware`           | Request processing and authentication                                      |
 | `/intercept`            | Modal/slide-over patterns for soft navigation                              |
 | `/parallel`             | Multi-column layouts and sidebars                                          |

package/skills/server-actions/SKILL.md

@@ -0,0 +1,739 @@
+---
+name: server-actions
+description: Define and call server actions (`"use server"`) — forms, useActionState, useOptimistic, validation, error handling, redirects, revalidation
+argument-hint: "[action]"
+---
+
+# Server Actions with `"use server"`
+
+Server actions are async functions that run on the server and are callable from
+the client. They are React's RSC mutation primitive — Rango uses them as-is
+with no framework wrapper. All standard React hooks (`useActionState`,
+`useFormStatus`, `useOptimistic`, `useTransition`) work directly.
+
+## When to Use Actions vs Loaders
+
+| Need                               | Use                                          |
+| ---------------------------------- | -------------------------------------------- |
+| Mutate state and revalidate UI     | Server action                                |
+| Read live data on every navigation | `createLoader()` + `useLoader()`             |
+| Read on demand from the client     | Fetchable loader + `useFetchLoader()`        |
+| Submit a form and show the result  | Action + `useActionState`                    |
+| File upload                        | Action with `FormData` (or fetchable loader) |
+
+Use loaders and route handlers for reads. Use actions for writes. After an
+action runs, the matched route tree can partially re-render so handlers and
+loaders that opt into revalidation see the new state — see "Revalidation"
+below.
+
+## Revalidation Model
+
+Actions mutate state; route handlers and loaders read the latest state. After
+an action finishes, Rango performs a server-side revalidation render for the
+matched route so the UI receives fresh segment output and loader data.
+
+The main control point is `revalidate(({ actionId }) => ...)` on the segment
+that owns the data. This applies to `path()` handlers, `layout()` handlers,
+`parallel()` slots, `intercept()` routes, and loader registrations:
+
+```typescript
+// urls.tsx — path/layout/parallel/intercept/loader/revalidate are passed in by urls()
+import { urls } from "@rangojs/router";
+
+export const urlpatterns = urls(({ path, loader, revalidate }) => [
+  // The loader belongs to the route that consumes its data — nest it inside
+  // the owning path() so the segment owns its data dependency.
+  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 module-level `"use server"` files, the `actionId` passed to every
+server-side `revalidate()` predicate is path-bearing in the server/RSC
+environment in both dev and production: `src/actions/cart.ts#addToCart`. This
+is intentional so path, layout, parallel, intercept, and loader revalidation
+predicates can filter by action file, directory, or export name.
+
+Actions and the follow-up revalidation render share one request context.
+Values written in the action with `ctx.set(MyVar, value)` or `ctx.set("key",
+value)` are visible to downstream route middleware, handlers, loaders, and
+`revalidate()` callbacks through `context.get(MyVar)` / `context.get("key")`:
+
+```typescript
+// app/context.ts
+import { createVar } from "@rangojs/router";
+
+export const ChangedTenant = createVar<string>();
+```
+
+```typescript
+// app/actions/tenant.ts
+"use server";
+
+import { getRequestContext } from "@rangojs/router";
+import { ChangedTenant } from "../context";
+
+export async function switchTenant(tenantId: string) {
+  const ctx = getRequestContext();
+  ctx.set(ChangedTenant, tenantId);
+  await db.tenants.touch(tenantId);
+}
+```
+
+```typescript
+// urls.tsx
+import { urls } from "@rangojs/router";
+import { ChangedTenant } from "./context";
+
+export const urlpatterns = urls(({ path, revalidate }) => [
+  path("/dashboard/:tenantId", DashboardPage, { name: "dashboard" }, () => [
+    revalidate(
+      ({ actionId, context }) =>
+        actionId?.startsWith("src/actions/tenant.ts#") &&
+        context.get(ChangedTenant) === context.params.tenantId,
+    ),
+  ]),
+]);
+```
+
+Client and SSR-facing action references keep hashed IDs in production for
+security and hydration compatibility. Do path matching inside server-side
+`revalidate()` predicates, not from client action metadata. Inline actions
+declared inside RSC components also keep hashed IDs; if you need path-based
+revalidation, export the action from a module-level `"use server"` file.
+
+## Defining an Action
+
+Two equivalent patterns. Prefer the file-level form for anything reusable.
+
+### File-level (`"use server"` at the top of a module)
+
+Every exported async function becomes a callable server action.
+
+```typescript
+// app/actions/cart.ts
+"use server";
+
+import { cookies } from "@rangojs/router";
+
+export async function addToCart(productId: string): Promise<void> {
+  const userId = cookies().get("user-id")?.value;
+  await db.cart.insert({ userId, productId });
+}
+
+export async function removeFromCart(productId: string): Promise<void> {
+  const userId = cookies().get("user-id")?.value;
+  await db.cart.delete({ userId, productId });
+}
+```
+
+### Inline (`"use server"` inside a server component)
+
+Define a one-off action where it is used. Captured variables are serialized,
+so keep them small and serializable.
+
+```tsx
+// Server component (handler)
+import type { Handler } from "@rangojs/router";
+
+const SettingsPage: Handler<"settings"> = (ctx) => {
+  const userId = ctx.get("user").id;
+
+  async function updateName(formData: FormData) {
+    "use server";
+    await db.users.update(userId, { name: formData.get("name") as string });
+  }
+
+  return (
+    <form action={updateName}>
+      <input name="name" />
+      <button type="submit">Save</button>
+    </form>
+  );
+};
+```
+
+## Calling Actions from the Client
+
+Three patterns, in order of how much state you need to preserve:
+
+### 1. Plain `<form action={...}>` — fire-and-forget
+
+Submits as `FormData`. Works without JavaScript (progressive enhancement).
+The page revalidates after the action returns.
+
+```tsx
+"use client";
+import { addToCart } from "../actions/cart";
+
+export function AddToCartForm({ productId }: { productId: string }) {
+  return (
+    <form action={addToCart.bind(null, productId)}>
+      <button type="submit">Add to cart</button>
+    </form>
+  );
+}
+```
+
+### 2. `useActionState` — preserve return value + pending state
+
+Standard React 19 hook. The action receives `(prevState, formData)` and its
+return value becomes the new `state`. The form input values are preserved by
+the browser on validation errors as long as you re-render the same form
+element with `defaultValue` (not `value`).
+
+Define the state shape next to the action so the client and server share
+one type:
+
+```typescript
+// app/actions/profile.ts
+"use server";
+
+export type ProfileFormState = {
+  errors?: Record<string, string>;
+  values?: { name: string };
+} | null;
+
+export async function saveProfile(
+  _prev: ProfileFormState,
+  formData: FormData,
+): Promise<ProfileFormState> {
+  const name = (formData.get("name") as string)?.trim() ?? "";
+  if (!name) {
+    return { errors: { name: "Name is required" }, values: { name } };
+  }
+  await db.users.update({ name });
+  return null; // success
+}
+```
+
+```tsx
+"use client";
+import { useActionState } from "react";
+import { saveProfile, type ProfileFormState } from "../actions/profile";
+
+export function ProfileForm({ initial }: { initial: { name: string } }) {
+  const [state, formAction, isPending] = useActionState<
+    ProfileFormState,
+    FormData
+  >(saveProfile, null);
+
+  return (
+    <form action={formAction}>
+      <input
+        name="name"
+        defaultValue={state?.values?.name ?? initial.name}
+        aria-invalid={!!state?.errors?.name}
+      />
+      {state?.errors?.name && <p role="alert">{state.errors.name}</p>}
+      <button type="submit" disabled={isPending}>
+        {isPending ? "Saving…" : "Save"}
+      </button>
+    </form>
+  );
+}
+```
+
+**Why `defaultValue`, not `value`** — on validation error the form re-renders.
+With `value` the inputs reset; with `defaultValue` (and a stable form key) the
+browser keeps user input. Re-echo the submitted values in `state.values` so
+they survive a full no-JS re-render too.
+
+### 3. `useOptimistic` — instant UI before the action settles
+
+For reactive UI like quantity controls, like buttons, or todo toggles.
+Combine with `startTransition` so the optimistic update is part of the same
+transition as the action call.
+
+```tsx
+"use client";
+import { useOptimistic, startTransition } from "react";
+import { updateQuantity } from "../actions/cart";
+
+export function QuantityControl({
+  productId,
+  initialQuantity,
+}: {
+  productId: string;
+  initialQuantity: number;
+}) {
+  const [optimistic, setOptimistic] = useOptimistic(
+    initialQuantity,
+    (_current, next: number) => next,
+  );
+
+  function change(delta: number) {
+    const next = Math.max(0, optimistic + delta);
+    startTransition(async () => {
+      setOptimistic(next);
+      await updateQuantity(productId, delta);
+    });
+  }
+
+  return (
+    <div>
+      <button onClick={() => change(-1)}>-</button>
+      <span>{optimistic}</span>
+      <button onClick={() => change(1)}>+</button>
+    </div>
+  );
+}
+```
+
+`useOptimistic` resets to the real value once the surrounding transition
+settles and React re-renders with the post-action loader data.
+
+### `useFormStatus` — pending state in nested children
+
+When the submit button is in a separate component from the form, use
+`useFormStatus()` instead of threading `isPending` down via props.
+
+```tsx
+"use client";
+import { useFormStatus } from "react-dom";
+
+export function SubmitButton({ children }: { children: React.ReactNode }) {
+  const { pending } = useFormStatus();
+  return (
+    <button type="submit" disabled={pending}>
+      {pending ? "Working…" : children}
+    </button>
+  );
+}
+```
+
+`useFormStatus` only reports the form it is rendered inside — it does not
+observe other forms.
+
+## Validation with Zod
+
+Validate on the server, return structured errors via `useActionState`. Keep
+the schema next to the action so client and server agree on the shape.
+
+```typescript
+// app/actions/signup.ts
+"use server";
+
+import { z } from "zod";
+import { redirect } from "@rangojs/router";
+
+const SignupSchema = z.object({
+  email: z.string().email("Enter a valid email"),
+  password: z.string().min(8, "At least 8 characters"),
+  name: z.string().min(1, "Required"),
+});
+
+export type SignupState = {
+  errors?: Partial<Record<keyof z.infer<typeof SignupSchema>, string>>;
+  values?: Partial<z.infer<typeof SignupSchema>>;
+} | null;
+
+export async function signup(
+  _prev: SignupState,
+  formData: FormData,
+): Promise<SignupState> {
+  const raw = {
+    email: formData.get("email") as string,
+    password: formData.get("password") as string,
+    name: formData.get("name") as string,
+  };
+
+  const parsed = SignupSchema.safeParse(raw);
+  if (!parsed.success) {
+    const errors: Record<string, string> = {};
+    for (const issue of parsed.error.issues) {
+      const key = String(issue.path[0]);
+      errors[key] ??= issue.message; // first error per field
+    }
+    // Echo back values (omit password) so the form preserves user input.
+    const { password: _drop, ...safeValues } = raw;
+    return { errors, values: safeValues };
+  }
+
+  await db.users.create(parsed.data);
+  throw redirect("/welcome");
+}
+```
+
+The form reads `state.errors` field-by-field and re-uses `state.values` as
+`defaultValue`s (see `useActionState` example above). Never echo back
+secrets like passwords.
+
+For schemas shared with a `useFetchLoader()` JSON body, parse the same way:
+
+```typescript
+const parsed = SignupSchema.safeParse(ctx.body);
+```
+
+## Revalidation After an Action
+
+When an action mutates data, the matched route tree may need to partially
+re-render so the UI updates. Rango runs the action, then evaluates
+`revalidate()` on matched segments and loaders. Each path, layout, parallel,
+intercept, or loader rule decides whether that piece re-renders/re-resolves.
+
+The `actionId` arrives as part of the revalidation context — match it to
+scope re-runs to specific actions.
+
+```typescript
+// urls.tsx — inside the urls() callback. Nest each loader inside the path(),
+// layout(), or parallel() that owns its data so the route tree mirrors the
+// data dependencies.
+urls(({ path, loader, revalidate }) => [
+  path("/", HomePage, { name: "home" }, () => [
+    // Loader data re-runs by default after any action. Opt out with revalidate(() => false).
+    loader(StaticHomepageLoader, () => [revalidate(() => false)]),
+  ]),
+
+  // Re-render the cart page handler AND re-resolve its loader after cart actions
+  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,
+      ),
+    ]),
+  ]),
+
+  // Re-run after any action under src/actions/account/
+  path("/account", AccountPage, { name: "account" }, () => [
+    loader(AccountLoader, () => [
+      revalidate(
+        ({ actionId }) => actionId?.startsWith("src/actions/account/") ?? false,
+      ),
+    ]),
+  ]),
+]);
+```
+
+`actionId` is stable per action. For actions exported from a module-level
+`"use server"` file, the ID is prefixed with the source file path
+(`src/actions/cart.ts#addToCart`), so substring matching by file path is the
+recommended scope. **Inline `"use server"` actions** (declared inside an RSC
+component) intentionally keep their hashed IDs — file paths are withheld
+from the client for security. If you need file-path-based revalidation
+predicates, define the action in a module-level `"use server"` file rather
+than inline. See `/loader` for the full revalidation contract (deferred
+returns, soft suggestions).
+
+### Cross-segment dependencies
+
+If a loader reads `ctx.get()` data set by an outer layout/handler, that
+outer segment must also re-run after the action — otherwise the loader sees
+stale context. Share the same `revalidate` predicate on both producer and
+consumer:
+
+```typescript
+const revalidateCart = ({ actionId }) =>
+  actionId?.startsWith("src/actions/cart.ts#") ?? false;
+
+urls(({ path, layout, loader, revalidate }) => [
+  layout(CartLayout, () => [
+    revalidate(revalidateCart), // producer reruns
+    path("/cart", CartPage, { name: "cart" }, () => [
+      loader(CartItemsLoader, () => [revalidate(revalidateCart)]), // consumer reruns
+    ]),
+  ]),
+]);
+```
+
+See `/middleware` for the full cross-segment revalidation contract.
+
+## Redirects
+
+`redirect()` works inside actions. Both `return redirect(...)` and
+`throw redirect(...)` are supported and behave the same way for the
+client. Throwing is clearer when the redirect is conditional.
+
+```typescript
+"use server";
+
+import { redirect, cookies } from "@rangojs/router";
+import { FlashMessage } from "../location-states";
+
+export async function login(_prev: unknown, formData: FormData) {
+  const email = formData.get("email") as string;
+  const session = await authenticate(email);
+  if (!session) return { error: "Invalid credentials" };
+
+  cookies().set("session", session.token, { httpOnly: true, path: "/" });
+  throw redirect("/dashboard", {
+    state: FlashMessage({ text: "Welcome back!" }),
+  });
+}
+```
+
+Redirects from actions render the **target** route tree's matched segments
+(paths, layouts, parallels, intercepts) and re-resolve its loaders, not the
+source page's — the target is what the user sees next. See `/hooks
+useLocationState` for reading flash state on the target page.
+
+## Error Handling
+
+### Validation errors — return them as state
+
+Recoverable errors (form validation, business rules) should be returned via
+`useActionState`. The form re-renders with the error and the user can fix
+it. Throwing for a validation error escalates to an error boundary, which
+is usually too aggressive.
+
+### Unexpected errors — let them throw
+
+Throw for genuinely exceptional conditions (network failure, DB outage,
+auth violation). The nearest `errorBoundary()` in the route tree catches
+them.
+
+```typescript
+import { errorBoundary } from "@rangojs/router";
+
+layout(CheckoutLayout, () => [
+  errorBoundary(({ error, reset }) => (
+    <div>
+      <p>Checkout failed: {error.message}</p>
+      <button onClick={reset}>Try again</button>
+    </div>
+  )),
+  path("/checkout", CheckoutPage, { name: "checkout" }),
+]);
+```
+
+### Not found from an action
+
+```typescript
+import { notFound } from "@rangojs/router";
+
+export async function deletePost(id: string): Promise<void> {
+  "use server";
+  const post = await db.posts.find(id);
+  if (!post) notFound("Post not found"); // hits notFoundBoundary
+  await db.posts.delete(id);
+}
+```
+
+### Authorization in actions
+
+Route middleware does **not** wrap action execution — only global
+middleware (`router.use()`) does. Auth checks must therefore live in
+`router.use()` or inside the action itself. Don't rely on a route-level
+`middleware()` to gate action access.
+
+```typescript
+// router.tsx — global guard wraps action + render
+const router = createRouter()
+  .use(authInit)
+  .use("/admin/*", requireAdmin) // protects actions on /admin too
+  .routes(urlpatterns);
+```
+
+```typescript
+// Or check inside the action body
+"use server";
+import { getRequestContext, redirect, notFound } from "@rangojs/router";
+
+export class ForbiddenError extends Error {
+  constructor() {
+    super("You do not have permission to perform this action.");
+    this.name = "ForbiddenError";
+  }
+}
+
+export async function deleteOrder(orderId: string) {
+  const ctx = getRequestContext();
+  const user = ctx.get("user");
+  if (!user) throw redirect("/login"); // unauthenticated → bounce to login
+
+  const order = await db.orders.get(orderId);
+  if (!order) notFound("Order not found"); // → notFoundBoundary
+  if (order.userId !== user.id) throw new ForbiddenError(); // → errorBoundary
+
+  await db.orders.delete(orderId);
+}
+```
+
+> **Don't `throw new Response("Unauthorized", { status: 401 })`** — non-redirect
+> Responses thrown from actions are treated as errors and routed to the nearest
+> `errorBoundary()`, not returned as real HTTP responses (the dev build warns
+> when you do this). Use `redirect()` to send unauthenticated users to a login
+> page, `notFound()` for missing resources, and a domain error class for
+> forbidden access so the boundary can render an appropriate UI. For
+> recoverable cases, return `{ error: "..." }` via `useActionState` instead of
+> throwing.
+
+## Action Context
+
+Actions can read the request context with `getRequestContext()`. This gives
+the same context-variable, header, and reverse APIs that handlers and
+middleware use.
+
+```typescript
+"use server";
+import { getRequestContext, cookies, headers } from "@rangojs/router";
+
+export async function trackEvent(name: string) {
+  const ctx = getRequestContext();
+  const user = ctx.get("user"); // set by global middleware
+  const ua = headers().get("user-agent");
+  const url = ctx.reverse("dashboard"); // type-safe URL by route name
+  await analytics.record({ name, userId: user?.id, ua, url });
+}
+```
+
+State written via `ctx.set(...)` or `cookies().set(...)` during an action
+is visible to downstream route middleware, segment handlers (path/layout/
+parallel/intercept), loaders, and `revalidate()` callbacks during the
+post-action revalidation render — actions and revalidation share the same
+request scope.
+
+### Constraints
+
+| Constraint                                               | Why                                                                                                                                                                                                                     |
+| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Actions cannot return or throw a non-redirect `Response` | Return values go through RSC Flight serialization. A thrown non-redirect `Response` is treated as a regular error and hits the nearest `errorBoundary()` (dev warns). Use `redirect()`, `notFound()`, or domain errors. |
+| Route DSL `middleware()` does not wrap actions           | Actions execute before route middleware. Only global `router.use()` middleware (and its scoped variants) wrap action execution.                                                                                         |
+| `useFetchLoader()` is for reads, not writes              | Actions are the mutation primitive; loaders are for data fetching.                                                                                                                                                      |
+
+Cookies/headers set in **global** `router.use()` middleware DO propagate to
+action responses (the same merge path as a normal render). The constraint
+specific to **per-fetchable-loader** middleware (`createLoader(fn, {
+middleware })` on a POST request) is that it cannot set cookies — set them
+in the loader body instead. See `/middleware` for the full middleware
+contract.
+
+## File Uploads
+
+Forms with `enctype="multipart/form-data"` (or any file input) submit to
+actions as `FormData`. Stream the file directly — don't buffer if the
+runtime supports streaming.
+
+Write the action with the `(prevState, formData) => newState` signature so
+it can be passed straight to `<form action={uploadAvatar}>` (PE-compatible)
+**and** to `useActionState` without a client-side wrapper:
+
+```typescript
+// app/actions/avatar.ts
+"use server";
+
+import { getRequestContext } from "@rangojs/router";
+
+export type AvatarUploadState = { url?: string; error?: string } | null;
+
+export async function uploadAvatar(
+  _prev: AvatarUploadState,
+  formData: FormData,
+): Promise<AvatarUploadState> {
+  const file = formData.get("avatar") as File | null;
+  if (!file || file.size === 0) return { error: "No file selected" };
+  if (file.size > 5_000_000) return { error: "File too large (max 5MB)" };
+
+  const ctx = getRequestContext();
+  const key = `avatars/${crypto.randomUUID()}-${file.name}`;
+  await ctx.env.BUCKET.put(key, file.stream());
+  return { url: `/r2/${key}` };
+}
+```
+
+```tsx
+"use client";
+import { useActionState } from "react";
+import { uploadAvatar, type AvatarUploadState } from "../actions/avatar";
+
+export function AvatarUpload() {
+  const [state, action, pending] = useActionState<AvatarUploadState, FormData>(
+    uploadAvatar,
+    null,
+  );
+  return (
+    <form action={action}>
+      <input type="file" name="avatar" accept="image/*" />
+      <button disabled={pending}>{pending ? "Uploading…" : "Upload"}</button>
+      {state?.error && <p role="alert">{state.error}</p>}
+      {state?.url && <img src={state.url} alt="" />}
+    </form>
+  );
+}
+```
+
+Wrapping the action in a client-side inline function (`useActionState(async
+(_prev, fd) => uploadAvatar(fd), null)`) breaks PE: that closure isn't a
+server reference, so the form has no real `action` URL when JS hasn't
+loaded. Keep the action's signature `(_prev, formData)` and pass it
+directly.
+
+For client-side upload progress or cancellation, use a fetchable loader
+with `useFetchLoader()` instead — see `/hooks useFetchLoader`.
+
+## Tracking Action State Without `useActionState`
+
+Use `useAction()` from `@rangojs/router/client` to track an action's
+state from outside a form (e.g. an action triggered by `onClick`).
+
+```tsx
+"use client";
+import { useAction } from "@rangojs/router/client";
+import { addToCart } from "../actions/cart";
+
+function AddButton({ productId }: { productId: string }) {
+  const { state, error } = useAction(addToCart);
+  return (
+    <>
+      <button
+        onClick={() => addToCart(productId)}
+        disabled={state === "loading"}
+      >
+        {state === "loading" ? "Adding…" : "Add"}
+      </button>
+      {error && <p role="alert">{error.message}</p>}
+    </>
+  );
+}
+```
+
+`useActionState` and `useAction` are complementary — use `useActionState`
+for `<form action={...}>` flows, `useAction` for imperative button clicks
+or to observe an action triggered elsewhere on the page.
+
+## Progressive Enhancement
+
+`<form action={serverAction}>` works without JavaScript: the form posts as a
+normal HTTP request, the action runs, and the page re-renders server-side.
+For PE to work, write actions that accept `FormData` directly (not curried
+or wrapped):
+
+```tsx
+// Works with no-JS submission
+<form action={submitName}>
+  <input name="name" />
+  <button>Submit</button>
+</form>
+```
+
+```typescript
+"use server";
+export async function submitName(formData: FormData) {
+  const name = formData.get("name") as string;
+  await db.entries.add({ name });
+}
+```
+
+`useActionState` and `useOptimistic` only enhance the experience once JS is
+loaded — without JS, the underlying action still runs and the page still
+re-renders. Don't rely on client-only state for required form behavior.
+
+## Cross-references
+
+- `/hooks` — `useAction`, `useFetchLoader`, `useLocationState` (flash state)
+- `/loader` — read patterns, fetchable loaders, revalidation rule semantics
+- `/middleware` — action vs render scope, revalidation contracts
+- `/links` — `ctx.reverse()` and `getRequestContext().reverse()` from actions
+- `/migrate-react-router` — `action()` → `"use server"` mapping
+- `/migrate-nextjs` — Next.js server action parity

package/src/router/pattern-matching.ts

@@ -188,6 +188,20 @@ export function compilePattern(pattern: string): CompiledPattern {
     regexPattern = "/";
   }
 
+  // Patterns of only optional segments (e.g. `/:locale?`, `/:a?/:b?`) need
+  // an explicit `/` alternative so a bare `/` matches the absent form. The
+  // optional template `(?:/X)?` matches `/X` or empty string, but pathnames
+  // are never empty. Arises from `include("/:locale?", routes)` + inner
+  // `path("/")`. Skip when an explicit trailing slash already anchors the
+  // match.
+  const hasOnlyOptionalSegments =
+    !hasTrailingSlash &&
+    segments.length > 0 &&
+    segments.every((segment) => segment.type === "param" && segment.optional);
+  if (hasOnlyOptionalSegments) {
+    regexPattern = `(?:/|${regexPattern})`;
+  }
+
   // Add trailing slash to regex if pattern has one
   if (hasTrailingSlash) {
     regexPattern += "/";
@@ -205,7 +219,9 @@ export function compilePattern(pattern: string): CompiledPattern {
 /**
  * Validate decoded params against a compiled pattern's constraints.
  * Returns false if any constrained param has a non-empty value not in the
- * allowed list (empty-string = absent optional, which is allowed).
+ * allowed list. Absent optionals (key missing or `undefined`) are allowed;
+ * `""` is also tolerated as "absent" so user-provided params or fixtures
+ * that pass empty strings explicitly behave the same way.
  */
 function satisfiesConstraints(
   params: Record<string, string>,
@@ -232,6 +248,27 @@ function escapeRegex(str: string): string {
   return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
+/**
+ * Build the named-params record from a regex match. Optional segments that
+ * didn't capture leave the corresponding group `undefined`; we skip those
+ * keys so `ctx.params.<name>` reads as `undefined` rather than `""`. This
+ * keeps the runtime aligned with the `ExtractParams` type and matches the
+ * trie matcher's contract (see `trie-matching.ts:validateAndBuild`).
+ */
+function buildParamsFromMatch(
+  match: RegExpExecArray,
+  paramNames: string[],
+): Record<string, string> {
+  const params: Record<string, string> = {};
+  paramNames.forEach((name, index) => {
+    const captured = match[index + 1];
+    if (captured !== undefined) {
+      params[name] = safeDecodeURIComponent(captured);
+    }
+  });
+  return params;
+}
+
 /**
  * Extract the static prefix from a route pattern.
  * Returns everything before the first param/wildcard.
@@ -283,8 +320,10 @@ export function extractStaticPrefix(pattern: string): string {
 /**
  * Match a pathname against registered routes
  *
- * Note: Optional params that are absent in the path will have empty string value.
- * Use the pattern definition to determine if a param is optional.
+ * Note: Optional params that are absent in the path are omitted from the
+ * returned `params` (read as `undefined`), matching the trie matcher and
+ * the `ExtractParams<"/:locale?/...">` type. Use the pattern definition or
+ * `optionalParams` to determine which keys are optional.
  *
  * Trailing slash handling (priority order):
  * 1. Per-route `trailingSlash` config from route()
@@ -451,10 +490,7 @@ export function findMatch<TEnv>(
       // Try exact match first
       const match = regex.exec(pathname);
       if (match) {
-        const params: Record<string, string> = {};
-        paramNames.forEach((name, index) => {
-          params[name] = safeDecodeURIComponent(match[index + 1] ?? "");
-        });
+        const params = buildParamsFromMatch(match, paramNames);
 
         // Validate constraints against decoded values; a failure falls
         // through to the next route so other patterns can still match.
@@ -512,10 +548,7 @@ export function findMatch<TEnv>(
       // Try alternate pathname (opposite trailing slash)
       const altMatch = regex.exec(alternatePathname);
       if (altMatch) {
-        const params: Record<string, string> = {};
-        paramNames.forEach((name, index) => {
-          params[name] = safeDecodeURIComponent(altMatch[index + 1] ?? "");
-        });
+        const params = buildParamsFromMatch(altMatch, paramNames);
 
         if (!satisfiesConstraints(params, constraints)) {
           continue;

package/src/router/trie-matching.ts

@@ -15,7 +15,9 @@ export interface TrieMatchResult {
   sp: string;
   /** Matched route params */
   params: Record<string, string>;
-  /** Optional param names (absent params have empty string value) */
+  /** Optional param names declared on the route. Absent params are omitted
+   * from `params` (read as `undefined`), matching the
+   * `ExtractParams<"/:locale?/...">` type. */
   optionalParams?: string[];
   /** Ancestry shortCodes for layout pruning */
   ancestry: string[];
@@ -203,14 +205,11 @@ function validateAndBuild(
     }
   }
 
-  // Fill in empty strings for optional params that weren't matched
-  if (leaf.op) {
-    for (const name of leaf.op) {
-      if (!(name in params)) {
-        params[name] = "";
-      }
-    }
-  }
+  // Optional params that weren't matched are left absent from `params` so
+  // `ctx.params.locale` reads as `undefined`, matching the
+  // `ExtractParams<"/:locale?/...">` type (`{ locale?: string }`). Both
+  // internal consumers — the constraint check above and `reverse()` —
+  // already treat missing/undefined as the absent form.
 
   // Trailing slash handling
   const tsMode = leaf.ts as "never" | "always" | "ignore" | undefined;