@rangojs/router 0.16.0 → 0.18.0

package/skills/typesafety/env-and-bindings.md

@@ -27,6 +27,7 @@ export interface AppVariables {
 
 ```typescript
 // router.tsx
+import { createRouter } from "@rangojs/router";
 import type { AppBindings, AppVariables } from "./env";
 
 const router = createRouter<AppBindings>({
@@ -40,7 +41,9 @@ declare global {
     interface Vars extends AppVariables {}
   }
 }
+```
 
+```typescript
 // middleware - typed via ctx.set / ctx.get
 import type { Middleware } from "@rangojs/router";
 
@@ -52,38 +55,35 @@ export const authMiddleware: Middleware = async (ctx, next) => {
   });
   await next();
 };
-
-// loaders - typed context
-export const UserLoader = createLoader(async (ctx) => {
-  const db = ctx.env.DB; // D1Database (plain bindings)
-  const userId = ctx.get("user")?.id; // from Rango.Vars
-  return db.prepare("SELECT * FROM users WHERE id = ?").bind(userId).first();
-});
 ```
 
 ## Global Environment Registration
 
-Register environment types globally for implicit typing:
+The `declare global` block above is what types the contexts. `createRouter<TEnv>()`
+types the router instance, but `urls()` modules, `Handler`, middleware, and
+response routes read `Rango.Env` / `Rango.Vars` — they cannot see the router's
+generic. Put the block in a file that is part of every TypeScript program that
+typechecks handlers (usually `router.tsx`, kept in via tsconfig `files`).
 
-```typescript
-// router.tsx
-declare global {
-  namespace Rango {
-    interface Env extends AppBindings {}
-    interface Vars extends AppVariables {}
-  }
-}
-```
+What each context sees:
 
-Now handlers have typed context without explicit imports:
+| Context                               | `ctx.env`                                 | `ctx.get("key")`                       |
+| ------------------------------------- | ----------------------------------------- | -------------------------------------- |
+| Handlers, middleware, response routes | `Rango.Env` (`unknown` if not registered) | `Rango.Vars` (`any` if not registered) |
+| Loaders (`createLoader`)              | `any` (not typed from `Rango.Env`)        | `Rango.Vars` (`any` if not registered) |
+
+An unregistered `Rango.Env` is deliberately `unknown`, so `ctx.env.DB` is a
+compile error rather than a silent `any`. An unregistered `Rango.Vars` falls
+back to `any` so string-key vars work with zero config.
 
 ```typescript
 // In loaders
+import { createLoader } from "@rangojs/router";
+
 export const DashboardLoader = createLoader(async (ctx) => {
-  // ctx.env.DB is typed from global Rango.Env
-  // ctx.get("user") is typed from global Rango.Vars
-  const user = ctx.get("user");
-  return { user };
+  const user = ctx.get("user"); // typed from global Rango.Vars
+  const db = ctx.env.DB as D1Database; // ctx.env is `any` in loaders
+  return { user, count: await countOrders(db, user?.id) };
 });
 ```
 
@@ -103,8 +103,12 @@ interface PaginationData {
 }
 export const Pagination = createVar<PaginationData>();
 
-// Non-cacheable var — reading inside cache() or "use cache" throws at runtime
-const Session = createVar<SessionData>({ cache: false });
+// Non-cacheable var — reading inside cache(), "use cache", or a PPR shell
+// capture throws at runtime
+interface SessionData {
+  userId: string;
+}
+export const Session = createVar<SessionData>({ cache: false });
 ```
 
 `createVar` accepts an optional options object. The `cache` option (default
@@ -112,11 +116,25 @@ const Session = createVar<SessionData>({ cache: false });
 Write-level escalation is also supported: `ctx.set(Var, value, { cache: false })`
 marks a specific write as non-cacheable even if the var itself is cacheable.
 "Least cacheable wins" — if either says `cache: false`, the value throws on
-read inside `cache()` or `"use cache"`.
-
-### Producer (handler or middleware)
+read inside `cache()` or `"use cache"`. On a `ppr` route the read also throws
+anywhere the shell capture waits for it (a handler, a promise it passes or
+pushes, an async server component, an `ssr: false` loader, a loader a handler
+awaits) and refuses the capture: the route keeps rendering without a shell,
+and a warning fires once per key. A loader without `ssr: false` that no
+handler awaits may read it, unless it is bound with its own `cache()` and no
+`key()`: that miss fails, since the entry is shared (`/loader` → "Cache
+Key").
+
+### Producer (handler, layout, or middleware)
+
+Write with `ctx.set()` from middleware, route handlers, or layout handlers;
+read with `ctx.get()` in the segments they wrap. A route handler runs before
+the layouts and parallels declared in its own use callback (handler-first), so
+those see the value; an outer layout wrapping the route renders first and
+does not. See `/route` for the full ordering.
 
 ```typescript
+import type { Handler } from "@rangojs/router";
 import { Pagination } from "../vars/pagination.js";
 
 const ArticleList: Handler<"articles.list"> = async (ctx) => {
@@ -132,15 +150,30 @@ const ArticleList: Handler<"articles.list"> = async (ctx) => {
 ### Consumer (layout, parallel, or any context with get)
 
 ```typescript
+import type { Handler } from "@rangojs/router";
+import { Outlet } from "@rangojs/router/client";
 import { Pagination } from "../vars/pagination.js";
 
-export function PaginationLayout(ctx: any) {
-  const pagination = ctx.get(Pagination);  // typed as PaginationData | undefined
-  if (!pagination) return <Outlet />;
-  return <nav>Page {pagination.current} of {pagination.total}</nav>;
-}
+// Mounted inside the producer's use callback:
+// path("/articles", ArticleList, { name: "articles.list" }, () => [layout(PaginationLayout)])
+export const PaginationLayout: Handler = (ctx) => {
+  const pagination = ctx.get(Pagination); // typed as PaginationData | undefined
+  return (
+    <>
+      <Outlet />
+      {pagination && (
+        <nav>
+          Page {pagination.current} of {pagination.total}
+        </nav>
+      )}
+    </>
+  );
+};
 ```
 
+Type the layout (`Handler`) rather than annotating `ctx: any`: with `any`,
+`ctx.get(Pagination)` is `any` too and the token contract is lost.
+
 ### Why not just use Rango.Vars?
 
 `Rango.Vars` (via global namespace augmentation) provides app-global typing for
@@ -154,7 +187,9 @@ Both approaches coexist: `ctx.get("user")` (global via Vars) and
 
 ## Handle Type Safety
 
-Handles have typed data:
+A handle is typed by two parameters: `Handle<TData, TAccumulated>`. `TData` is
+what each segment pushes; `TAccumulated` is what readers get after the collect
+function runs (default `TData[][]`, one array per segment).
 
 ```typescript
 // Built-in Breadcrumbs handle — import from "@rangojs/router"
@@ -168,18 +203,33 @@ path("/shop/product/:slug", (ctx) => {
   breadcrumb({ label: "Products", href: "/shop/products" });
   return <ProductPage />;
 }, { name: "product" });
+```
 
+```tsx
 // In client — typed array
+"use client";
 import { useHandle, Breadcrumbs } from "@rangojs/router/client";
+
 function BreadcrumbNav() {
-  const crumbs = useHandle(Breadcrumbs);
-  // crumbs: BreadcrumbItem[]
+  const crumbs = useHandle(Breadcrumbs); // crumbs: BreadcrumbItem[]
+  return (
+    <nav>
+      {crumbs.map((c) => (
+        <a key={c.href} href={c.href}>
+          {c.label}
+        </a>
+      ))}
+    </nav>
+  );
 }
+```
 
-// Custom handles also work the same way
+```typescript
+// Custom handle: give TAccumulated whenever collect changes the shape
 import { createHandle } from "@rangojs/router";
+
 export const PageTitle = createHandle<string, string>(
-  (segments) => segments.flat().at(-1) ?? "Default Title"
+  (segments) => segments.flat().at(-1) ?? "Default Title",
 );
 ```
 
@@ -190,11 +240,16 @@ Use `typeof` to get the full typed definition without manually specifying generi
 
 ```typescript
 // loaders.ts
+import { createLoader } from "@rangojs/router";
+
 export const ProductLoader = createLoader(async (ctx) => {
   return { product: await fetchProduct(ctx.params.slug) };
 });
 
-// Built-in Breadcrumbs — or any custom handle created with createHandle()
+// Server: pass the definitions as props
+path("/product/:slug", () => (
+  <MyComponent loader={ProductLoader} handle={Breadcrumbs} />
+), { name: "product" }, () => [loader(ProductLoader)]);
 ```
 
 ```tsx
@@ -208,20 +263,27 @@ function MyComponent({
   handle,
 }: {
   loader: typeof ProductLoader; // LoaderDefinition<{ product: Product }>
-  handle: typeof Breadcrumbs; // Handle<{ label: string; href: string }>
+  handle: typeof Breadcrumbs; // Handle<BreadcrumbItem, BreadcrumbItem[]>
 }) {
   const { data } = useLoader(loader); // data is typed
-  const crumbs = useHandle(handle); // crumbs is typed array
+  const crumbs = useHandle(handle); // crumbs: BreadcrumbItem[]
   // ...
 }
 ```
 
-RSC Flight serialization calls `toJSON()` on both loaders and handles,
-sending only `{ __brand, $$id }` to the client. The hooks recover the
-full functionality from module-level registries.
+Loader and handle definitions are plain `{ __brand, $$id }` objects — the
+loader function and the handle's collect function live in module-level
+registries keyed by `$$id` — so they cross the RSC boundary as-is and the
+hooks look the rest up by id. `useLoader()` still needs the loader registered
+on the route with `loader()` (or use `useFetchLoader()` for on-demand fetching).
 
 ## Location State Type Safety
 
+`createLocationState<T>()` returns a typed definition; the Vite plugin injects
+its key, so it must be exported from a module. Values are stored in
+`history.state`, so `T` must be structured-cloneable: functions, symbols,
+class constructors, React elements, and `unknown` are compile errors.
+
 ```typescript
 // location-states.ts
 import { createLocationState } from "@rangojs/router";
@@ -233,13 +295,28 @@ export const ProductPreview = createLocationState<{
   image: string;
 }>();
 
+// Flash state: cleared after the first read
+export const FlashMessage = createLocationState<{ text: string }>({
+  flash: true,
+});
+```
+
+```tsx
+"use client";
+import { Link, href, useLocationState } from "@rangojs/router/client";
+import { ProductPreview } from "./location-states";
+
 // Passing state through Link
-<Link
-  to={href("product", { slug: "widget" })}
-  state={[ProductPreview({ name: "Widget", price: 99, image: "/img.jpg" })]}
->
-  View Product
-</Link>
+function ProductCard() {
+  return (
+    <Link
+      to={href("/product/widget")}
+      state={[ProductPreview({ name: "Widget", price: 99, image: "/img.jpg" })]}
+    >
+      View Product
+    </Link>
+  );
+}
 
 // Reading state in component
 function ProductHeader() {
@@ -247,8 +324,18 @@ function ProductHeader() {
   // preview: { name: string; price: number; image: string } | undefined
 
   if (preview) {
-    return <h1>{preview.name} - ${preview.price}</h1>;
+    return (
+      <h1>
+        {preview.name} - ${preview.price}
+      </h1>
+    );
   }
   return <h1>Loading...</h1>;
 }
 ```
+
+Other entry points: pass a getter (`ProductPreview(() => ({ ... }))`) to compute
+the value at click time; `ctx.setLocationState(entry)` attaches state from a
+handler; `redirect(url, { state })` carries it through a redirect; and
+`ProductPreview.read()` / `.write(value)` / `.delete()` access the current
+history entry outside React (client-only, non-reactive).

package/skills/typesafety/generated-files-and-cli.md

@@ -5,23 +5,23 @@
 ```typescript
 // router.tsx
 import { createRouter } from "@rangojs/router";
+import { Document } from "./document";
 import { urlpatterns } from "./urls";
+import type { AppBindings } from "./env";
 
-const router = createRouter<AppBindings>({
+export const router = createRouter<AppBindings>({
   document: Document,
 }).routes(urlpatterns);
 
 // Server-side named-route reverse (type-safe via routeMap)
 export const reverse = router.reverse;
-
-export default router;
 ```
 
 ### Which global type should I use?
 
 Use the generated route map by default. Manual `RegisteredRoutes` augmentation
 is only needed when you want the richer `typeof router.routeMap` shape
-available globally.
+available globally — in practice, for `Rango.PathResponse`.
 
 - `GeneratedRouteMap` — auto-registered by `router.named-routes.gen.ts`
   Use for `Handler<"name">` (type annotation), `Prerender<"name">(...)` (function
@@ -95,19 +95,27 @@ instance in the same TypeScript program:
 }
 ```
 
-Then generate the route types from the router file:
+The Vite plugin writes `src/router.named-routes.gen.ts` (next to the router
+file) automatically: before the dev server starts, again when route files
+change, and during build. To produce it without starting Vite (a fresh clone,
+a CI typecheck step), run the CLI against the router file:
 
 ```bash
 npx rango generate src/router.tsx
 ```
 
-This creates `src/router.named-routes.gen.ts`, which augments
-`Rango.GeneratedRouteMap`. Keep that generated file committed with the router
+The file augments `Rango.GeneratedRouteMap`. Keep it committed with the router
 source. The `files` entry keeps `router.tsx` in the program even when nothing
 imports it directly, so `Rango.Env`, `Rango.Vars`, and optional
 `Rango.RegisteredRoutes` augmentation are visible to handlers, loaders, actions,
 and client helpers.
 
+CLI flags: the default mode fails (and writes nothing) when an `include()` cannot
+be resolved statically (factory functions, dynamic expressions); `--static`
+accepts partial output with warnings; `--runtime` uses Vite-based discovery for
+full coverage (needs `vite` and `@vitejs/plugin-rsc`, optional
+`--config <path>`). Passing a directory scans it for router and `urls()` files.
+
 ### Named Routes, `$$routeNames`, And `router.routeMap`
 
 There are two runtime/type surfaces with similar names:
@@ -299,7 +307,9 @@ export const urlpatterns = urls(({ path, layout, loader }) => [
 ]);
 
 // 3. router.tsx - Create router and export reverse
-const router = createRouter<AppBindings>({
+import { createRouter } from "@rangojs/router";
+
+export const router = createRouter<AppBindings>({
   document: Document,
 }).routes(urlpatterns);
 
@@ -312,10 +322,10 @@ declare global {
 }
 
 export const reverse = router.reverse;
-export default router;
 
-// 4. Run `npx rango generate src/router.tsx` to generate
-//    router.named-routes.gen.ts (auto-registers GeneratedRouteMap globally).
+// 4. router.named-routes.gen.ts is written by the Vite plugin (dev + build);
+//    run `npx rango generate src/router.tsx` to produce it without Vite.
+//    It auto-registers GeneratedRouteMap globally.
 //    No manual RegisteredRoutes declaration is needed for named-route handlers,
 //    ctx.reverse, prerender, href(), or Rango.Path. Add `RegisteredRoutes
 //    extends AppRoutes` (an alias of typeof router.routeMap) when global
@@ -323,10 +333,12 @@ export default router;
 //    router.routeMap metadata.
 
 // 5. loaders/*.ts - Type-safe loaders
+import { createLoader } from "@rangojs/router";
+
 export const ProductLoader = createLoader(async (ctx) => {
-  // ctx.params: { slug: string }
-  // ctx.get("user"): User | undefined  (from Rango.Vars)
-  // ctx.env.DB: D1Database  (plain bindings from Rango.Env)
+  // ctx.params.slug: string | undefined  (a loader is not bound to one route)
+  // ctx.get("user"): AppVariables["user"]  (from Rango.Vars)
+  // ctx.env: any  (createLoader does not apply Rango.Env; cast if you need types)
   return { product: await fetchProduct(ctx.params.slug) };
 });
 

package/skills/typesafety/params-and-search.md

@@ -22,12 +22,17 @@ global `GeneratedRouteMap` (the gen file). No explicit route map import needed:
 import type { Handler } from "@rangojs/router";
 
 export const SearchPage: Handler<"search"> = (ctx) => {
-  // ctx.search is typed: { q: string; page?: number; sort?: string }
-  const { q, page, sort } = ctx.search;
+  // ctx.search is typed: { q: string | undefined; page?: number; sort?: string }
+  const { q = "", page = 1, sort } = ctx.search;
   return <SearchResults q={q} page={page} sort={sort} />;
 };
 ```
 
+Required keys (no `?`) still resolve to `T | undefined` inside the handler:
+the schema tells callers (`ctx.reverse`, `useReverse`) what to send, but the
+server cannot trust the client to send it, so the handler must handle a
+missing value.
+
 This avoids circular references because `Handler` defaults to `GeneratedRouteMap`
 (from `router.named-routes.gen.ts`) instead of `RegisteredRoutes` (which depends on `router.tsx`).
 
@@ -48,8 +53,12 @@ Note the difference: `Handler<"search">` (no dot) resolves against the global
 `routes` for param/search inference and only uses it for local `ctx.reverse(".x")`.
 
 Supported types: `"string"`, `"number"`, `"boolean"`, with `?` suffix for optional.
-Values are automatically coerced from query string (e.g., `"2"` becomes `2` for numbers).
-Routes without a `search` schema keep the standard `URLSearchParams` behavior.
+Values are automatically coerced from the query string: numbers accept finite
+decimal values (`"2"` becomes `2`; `"0x10"`, `"Infinity"` or an empty value are
+treated as missing), and a present boolean is `true` for `"true"`/`"1"` and
+`false` otherwise. Absent keys are omitted, required or not. Routes without a
+`search` schema get `ctx.search` as an empty object; read the raw query from
+`ctx.searchParams` (a `URLSearchParams`).
 
 ### RouteSearchParams and RouteParams utility types
 
@@ -104,12 +113,15 @@ export const NamedRoutes = {
 } as const;
 ```
 
-You never open a `.gen.ts` by hand. Treat the generated types as call-site
-honesty checks, not modules to read:
+You never edit a `.gen.ts` by hand. Treat the generated types as call-site
+checks, not modules to read:
 
-- **Do not import `router.named-routes.gen.ts` directly**, and don't reach for
-  `Rango.GeneratedRouteMap`. It is the whole-app manifest, auto-wired
-  globally — `Handler<"name">` and `ctx.reverse("name")` already see it.
+- **You rarely need to import `router.named-routes.gen.ts`**, and you don't
+  need to reference `Rango.GeneratedRouteMap`. It is the whole-app manifest,
+  auto-wired globally — `Handler<"name">` and `ctx.reverse("name")` already
+  see it. Importing its `NamedRoutes` value is an escape hatch (global names
+  in `useReverse`, an absolute-path map for `/api-client`); on the client it
+  ships every route name and pattern in the app.
 - **Per-module `*.gen.ts` imports are fine** — they are the opt-in local-route
   pattern for `useReverse(routes)` and explicit local handler typing
   (`Handler<".name", routes>`). See `/links`.
@@ -119,35 +131,48 @@ smell — fix the call site (or regenerate), never edit the generated file.
 
 ## Loader Type Safety
 
-Loaders have typed return values:
+A loader's return type is inferred from its function and flows to every
+consumer. `createLoader` is not bound to one route, so `ctx.params` is
+`Record<string, string | undefined>`:
 
 ```typescript
 // loaders/product.ts
+import { createLoader } from "@rangojs/router";
+
 export const ProductLoader = createLoader(async (ctx) => {
   return {
-    id: ctx.params.slug,
+    id: ctx.params.slug ?? "",
     name: "Widget",
     price: 99,
   };
 });
+```
 
-// In server component - type is inferred
-import { useLoader } from "@rangojs/router/client";
+Server handler (escape hatch — reads the data in the handler itself):
 
-async function ProductPage() {
-  const product = await useLoader(ProductLoader);
+```typescript
+path("/product/:slug", async (ctx) => {
+  const product = await ctx.use(ProductLoader);
   // product: { id: string; name: string; price: number }
   return <h1>{product.name}</h1>;
-}
+}, { name: "product" }, () => [loader(ProductLoader)]);
+```
+
+Client component (the default consumption site):
 
-// In client component - same type
+```typescript
 "use client";
 import { useLoader } from "@rangojs/router/client";
+import { ProductLoader } from "../loaders/product";
 
 function ProductPrice() {
   const { data } = useLoader(ProductLoader);
   // data: { id: string; name: string; price: number }
-  const product = data;
-  return <span>${product.price}</span>;
+  return <span>${data.price}</span>;
 }
 ```
+
+`useLoader()` is a client hook — never call it in a server component.
+Client-side data is typed through `Rango.FlightSerialize<T>` (the RSC Flight
+boundary), so values Flight preserves (such as `Date`) keep their type. See
+`/loader` for when to use `ctx.use()` versus `useLoader()`.

package/skills/typesafety/route-types.md

@@ -1,12 +1,19 @@
 # Route Types
 
+Route names come from the `name` option on `path()`. Names are typed in two
+places: the `urls()` value itself (local names, patterns and response payloads
+as phantom types) and the generated `router.named-routes.gen.ts` (the global
+name map behind `Handler<"name">`, `ctx.reverse()` and `href()`). See
+[`./generated-files-and-cli.md`](./generated-files-and-cli.md) for which surface
+feeds which API.
+
 ## Route Definition with Type-Safe Names
 
 ```typescript
 // urls.tsx
 import { urls } from "@rangojs/router";
 
-export const urlpatterns = urls(({ path, layout }) => [
+export const urlpatterns = urls(({ path }) => [
   path("/", HomePage, { name: "home" }),
   path("/products", ProductsPage, { name: "products" }),
   path("/product/:slug", ProductPage, { name: "product" }),
@@ -17,7 +24,7 @@ export const urlpatterns = urls(({ path, layout }) => [
 // Route names are inferred from the { name } option
 ```
 
-## Type-Safe href()
+## Type-Safe URL Generation
 
 ### Server: ctx.reverse with route names
 
@@ -36,8 +43,15 @@ export const ProductHandler: Handler<"shop.product"> = (ctx) => {
 };
 ```
 
-For type-safe local names, generate a route types file with `npx rango generate urls/shop.tsx`
-and pass it as the second generic to `Handler` or `Prerender`:
+Without a local route map, `.name` calls accept any string (the include scope
+is only known at runtime). Middleware and response-route handlers are the
+exception: their `ctx.reverse` (`GlobalReverseFunction`) has no include scope,
+so it takes global names only and a `.name` call there is a type error. Global names are checked against the generated
+map once it exists. For type-safe local names, generate a route types file with
+`npx rango generate urls/shop.tsx` and pass its `routes` type as the second
+generic to `Handler` or `Prerender`. With a local map, local names also
+require their params (mount params such as `:tenantId` may still be passed as
+extras):
 
 ```typescript
 import type { Handler } from "@rangojs/router";
@@ -61,6 +75,7 @@ import { href, useHref, Link } from "@rangojs/router/client";
 // href() validates absolute paths via PatternToPath types
 href("/about");                        // Valid path
 href("/blog/hello");                   // Matches /blog/:slug
+href("/blog/hello?page=2#top");        // Query and hash suffixes are allowed
 
 // useHref() auto-prefixes with include() mount
 function ShopNav() {
@@ -69,6 +84,10 @@ function ShopNav() {
 }
 ```
 
+`href()` is compile-time only: at runtime it returns the path unchanged. It
+does not resolve route names. `useHref()` prepends the mount but its argument
+is typed as any `/${string}`, not checked against routes.
+
 `href()` and the `Rango.Path` type read from `RegisteredRoutes` when you augment
 it, otherwise from the auto-generated `GeneratedRouteMap` — so `rango generate`
 alone type-checks `href()` paths with no manual augmentation. The augmentation
@@ -76,6 +95,7 @@ below is only needed for **`Rango.PathResponse`** (response-payload inference),
 `GeneratedRouteMap` cannot provide:
 
 ```typescript
+// router.tsx, below `export const router = createRouter(...).routes(urlpatterns)`
 // The alias is required: an interface heritage clause cannot take a `typeof`
 // type query directly (TS1109).
 type AppRoutes = typeof router.routeMap;
@@ -200,15 +220,31 @@ a rename is a type error in one place instead of silent drift:
 ```ts
 import { addToCart, removeFromCart } from "./actions/cart";
 import * as CartActions from "./actions/cart";
-
-revalidate((ctx) => ctx.isAction(addToCart) || undefined); // one action
-revalidate((ctx) => ctx.isAction(addToCart, removeFromCart) || undefined); // several
-revalidate((ctx) => ctx.isAction(CartActions) || undefined); // any action in the module
-revalidate((ctx) => ctx.isAction({ addToCart, removeFromCart }) || undefined); // object form
+import * as OrderActions from "./actions/order";
+
+// On a loader: after an action, re-run only for cart actions; on navigation,
+// keep the default.
+revalidate((ctx) => (ctx.isAction() ? ctx.isAction(CartActions) : undefined));
+
+// Matcher forms (each returns a boolean):
+ctx.isAction(); // any action at all
+ctx.isAction(addToCart); // one action
+ctx.isAction(addToCart, removeFromCart); // several
+ctx.isAction(CartActions); // any action in the module
+ctx.isAction({ addToCart, removeFromCart }); // object form
+ctx.isAction({ Cart: CartActions, Order: OrderActions }); // grouped namespaces
 ```
 
-`ctx.isAction()` (only available on the revalidate predicate's context) returns a
-raw boolean — combine with `|| undefined` for the "revalidate on match, else
-defer" intent. It resolves the reference the same way the router derives
-`actionId` (`$id` in production, `$$id` in dev), so matching
-works in both modes. `actionId` stays available for advanced cases.
+`ctx.isAction()` (only available on the revalidate predicate's argument)
+returns a raw boolean and is `false` on plain navigation. Wrap it by what the
+segment's default already does: `|| undefined` adds a re-render on a parent
+layout or layout-level parallel (skipped after actions by default); on a loader
+or route segment, which already re-run after every action, `|| undefined`
+changes nothing, so narrow with the ternary above. Avoid a bare
+`ctx.isAction(X)`: it is a hard `false` on navigation too. See `/loader` →
+"`revalidate()` return shapes". It resolves
+the reference the same way the router derives `actionId` (`$id ?? $$id`: the
+file-path `$id` injected in a production RSC build, otherwise React's `$$id`),
+so matching works in dev and production. `actionId` stays available for
+advanced cases. In `clientUrls()` groups the predicate runs in the browser,
+where `actionId` is the hashed form (see `/client-urls`).