@rangojs/router 0.13.0 → 0.15.0

package/README.md

@@ -207,7 +207,6 @@ stock lives in the database:
 import { createLoader } from "@rangojs/router";
 
 export const StockLoader = createLoader(async (ctx) => {
-  "use server";
   return db.stockFor(ctx.params.slug);
 });
 ```

package/dist/types/route-content-wrapper.d.ts

@@ -23,15 +23,35 @@ import type { ResolvedSegment } from "./types.js";
  */
 export declare class StreamedLoaderErrorBoundary extends Component<{
     children: ReactNode;
+    resetKey?: string;
 }, {
     error: unknown;
+    resetKey?: string;
 }> {
     state: {
         error: unknown;
+        resetKey?: string;
     };
     static getDerivedStateFromError(error: unknown): {
         error: unknown;
     };
+    /**
+     * A caught marker (redirect, notFound, error fallback) belongs to ONE route
+     * + params. Group-keyed segments (ResolvedSegment.clientGroup) keep this
+     * instance alive across in-group navigations, so the error must clear when
+     * the route or params change — otherwise a redirect caught for /legacy
+     * keeps rendering LoaderRedirect for /state. `resetKey` is the segment's
+     * id-params identity, the cadence the per-route remount used to provide.
+     */
+    static getDerivedStateFromProps(props: {
+        resetKey?: string;
+    }, state: {
+        error: unknown;
+        resetKey?: string;
+    }): {
+        error: unknown;
+        resetKey?: string;
+    } | null;
     render(): ReactNode;
 }
 /**

package/dist/types/server/context.d.ts

@@ -48,6 +48,8 @@ export type EntryPropCommon = {
     cache?: EntryCacheConfig;
     /** URL prefix from include() scope, used for MountContext on client */
     mountPath?: string;
+    /** clientUrls() group key (PathOptions.clientGroup); route entries only. */
+    clientGroup?: string;
 };
 /**
  * Attachments resolved by walking the parent chain, not owned by the entry:

package/dist/types/types/loader-types.d.ts

@@ -19,14 +19,12 @@ import type { RequestScope } from "./request-scope.js";
  * @example
  * ```typescript
  * const CartLoader = createLoader(async (ctx) => {
- *   "use server";
  *   const user = ctx.get("user");  // From auth middleware
  *   return await db.cart.get(user.id);
  * });
  *
  * // With typed params:
  * const ProductLoader = createLoader<Product, { slug: string }>(async (ctx) => {
- *   "use server";
  *   const { slug } = ctx.params;  // slug is typed as string
  *   return await db.products.findBySlug(slug);
  * });
@@ -69,7 +67,6 @@ export type LoaderContext<TParams = Record<string, string | undefined>, TEnv = D
      * @example
      * ```typescript
      * export const ProductLoader = createLoader(async (ctx) => {
-     *   "use server";
      *   const product = await getProduct(ctx.params.slug);
      *   ctx.use(Meta)({ title: product.name });
      *   ctx.use(Breadcrumbs)({ label: product.name });
@@ -95,7 +92,6 @@ export type LoaderContext<TParams = Record<string, string | undefined>, TEnv = D
      * @example
      * ```typescript
      * const PricesLoader = createLoader(async (ctx) => {
-     *   "use server";
      *   await ctx.rendered();
      *   const products = ctx.get(Products); // reads handle data
      *   return pricing.getLive(products.map(p => p.id));
@@ -204,7 +200,8 @@ export type LoadOptions = {
  * Loader definition object
  *
  * Created via createLoader(). Contains the loader name and function.
- * On client builds, the fn is stripped by the bundler (via "use server" directive).
+ * On client builds, the fn is stripped by the router's loader transform; the
+ * definition must not carry a "use server" directive (the Vite plugin rejects it).
  *
  * @template T - The return type of the loader
  * @template TParams - Route params type (for type-safe params access)
@@ -213,13 +210,11 @@ export type LoadOptions = {
  * ```typescript
  * // Definition (same file works on server and client)
  * export const CartLoader = createLoader(async (ctx) => {
- *   "use server";
  *   return await db.cart.get(ctx.get("user").id);
  * });
  *
  * // With typed params:
  * export const ProductLoader = createLoader<Product, { slug: string }>(async (ctx) => {
- *   "use server";
  *   const { slug } = ctx.params;  // slug is typed as string
  *   return await db.products.findBySlug(slug);
  * });

package/dist/types/types/segments.d.ts

@@ -163,6 +163,9 @@ export interface ResolvedSegment {
     error?: ErrorInfo;
     notFoundInfo?: NotFoundInfo;
     mountPath?: string;
+    /** clientUrls() group key (the include mount), shared by every route
+     *  segment of one group; see the group-route branch in segment-system.tsx. */
+    clientGroup?: string;
     /**
      * @internal Server-side marker: true when the segment's handler actually ran
      * this request (not skipped via the revalidate cache path). Used by

package/dist/types/urls/pattern-types.d.ts

@@ -102,6 +102,9 @@ export interface PathOptions<TName extends string = string, TSearch extends Sear
     trailingSlash?: TrailingSlashMode;
     /** Response type marker (set by path.json(), etc.) */
     [RESPONSE_TYPE]?: string;
+    /** @internal clientUrls() group key stamped by server-projection.ts; see
+     *  ResolvedSegment.clientGroup. */
+    clientGroup?: string;
 }
 /**
  * Result of urls() - contains the route definitions

package/dist/types/vite/plugins/expose-ids/loader-transform.d.ts

@@ -6,3 +6,17 @@ export declare function generateClientLoaderStubs(bindings: CreateExportBinding[
     map?: undefined;
 } | null;
 export declare function transformLoaders(bindings: CreateExportBinding[], s: MagicString, filePath: string, isBuild: boolean): boolean;
+export interface LoaderServerDirective {
+    line: number;
+}
+/**
+ * Locate an inline `"use server"` directive at the top of a createLoader()
+ * callback body. Only top-level `const X = createLoader(...)` bindings (bare
+ * or exported) are checked — the same shapes the loader transform registers.
+ * Loaders are never client-callable, and the directive makes plugin-rsc
+ * hoist the body and `registerServerReference` it, so the loader body
+ * becomes a public action reachable with caller-supplied arguments (verified
+ * against a production build: a POST to `?_rsc_action=<id>` ran a loader body
+ * with a forged ctx). The guard plugin throws on the first hit.
+ */
+export declare function findLoaderServerDirective(code: string, fnNames: readonly string[], program: any): LoaderServerDirective | null;

package/dist/types/vite/plugins/expose-internal-ids.d.ts

@@ -11,6 +11,13 @@ export type { ExposeInternalIdsApi } from "./expose-ids/types.js";
  * validation rather than being hidden behind an opaque scan stub.
  */
 export declare function createLoaderScanStubPlugin(): Plugin;
+/**
+ * Refuse an inline `"use server"` directive inside a createLoader() callback.
+ * Runs `pre` so it sees the raw source before plugin-rsc's directive transform
+ * hoists the body into a registered server reference. See
+ * findLoaderServerDirective for why that registration is a problem.
+ */
+export declare function createLoaderDirectiveGuardPlugin(): Plugin;
 export declare function exposeInternalIds(options?: {
     forceBuild?: boolean;
 }): Plugin;

package/dist/vite/index.js

@@ -2242,6 +2242,7 @@ function buildUnsupportedShapeWarning(filePath, fnName, sites = []) {
 }
 
 // src/vite/plugins/expose-ids/loader-transform.ts
+import { hasDirective } from "@vitejs/plugin-rsc/transforms";
 function hasCreateLoaderImport(code) {
   return /import\s*\{[^}]*\bcreateLoader\b[^}]*\}\s*from\s*["']@rangojs\/router(?:\/server)?["']/.test(
     code
@@ -2276,6 +2277,27 @@ ${binding.localName}.$$id = "${loaderId}";`;
   }
   return hasChanges;
 }
+function loaderCallback(node, names) {
+  if (node?.type !== "CallExpression" || node.callee?.type !== "Identifier" || !names.has(node.callee.name)) {
+    return void 0;
+  }
+  const fn = node.arguments?.[0];
+  return (fn?.type === "ArrowFunctionExpression" || fn?.type === "FunctionExpression") && fn.body?.type === "BlockStatement" ? fn : void 0;
+}
+function findLoaderServerDirective(code, fnNames, program) {
+  const names = new Set(fnNames);
+  for (const statement of program.body ?? []) {
+    const declaration = statement.type === "ExportNamedDeclaration" ? statement.declaration : statement;
+    if (declaration?.type !== "VariableDeclaration") continue;
+    for (const declarator of declaration.declarations) {
+      const fn = loaderCallback(declarator.init, names);
+      if (fn && hasDirective(fn.body.body, "use server")) {
+        return { line: offsetToLineColumn(code, fn.body.body[0].start).line };
+      }
+    }
+  }
+  return null;
+}
 
 // src/vite/plugins/expose-ids/handler-transform.ts
 function transformHandles(bindings, s, filePath, isBuild) {
@@ -2499,6 +2521,33 @@ function createLoaderScanStubPlugin() {
     }
   };
 }
+function createLoaderDirectiveGuardPlugin() {
+  return {
+    name: "@rangojs/router:loader-directive-guard",
+    enforce: "pre",
+    transform(code, id) {
+      if (id.includes("/node_modules/") || !code.includes("use server") || !code.includes("createLoader") || !hasCreateLoaderImport(code)) {
+        return;
+      }
+      const cleanId = id.split("?", 1)[0];
+      let program;
+      try {
+        program = parseAst2(code, { lang: "tsx" });
+      } catch {
+        return;
+      }
+      const hit = findLoaderServerDirective(
+        code,
+        getImportedFnNames(code, "createLoader"),
+        program
+      );
+      if (!hit) return;
+      throw new Error(
+        `[rango] createLoader() body at ${cleanId}:${hit.line} carries a "use server" directive. Loader bodies already run only on the server; the directive would register the body as a client-callable server reference (reachable through the action endpoint with caller-supplied arguments). Remove the directive.`
+      );
+    }
+  };
+}
 function exposeInternalIds(options) {
   let config;
   let isBuild = false;
@@ -3037,7 +3086,7 @@ function useCacheTransform() {
           }
         }
         const {
-          hasDirective,
+          hasDirective: hasDirective2,
           transformWrapExport,
           transformHoistInlineDirective
         } = rscTransforms;
@@ -3051,7 +3100,7 @@ function useCacheTransform() {
         stripNullDirectiveFields(ast);
         const filePath = normalizePath(path5.relative(projectRoot, id));
         const isLayoutOrTemplate = LAYOUT_TEMPLATE_PATTERN.test(id);
-        if (hasDirective(ast.body, "use cache")) {
+        if (hasDirective2(ast.body, "use cache")) {
           return transformFileLevelUseCache(
             code,
             ast,
@@ -3060,7 +3109,7 @@ function useCacheTransform() {
             isBuild,
             isLayoutOrTemplate,
             transformWrapExport,
-            hasDirective
+            hasDirective2
           );
         }
         const functionResult = transformFunctionLevelUseCache(
@@ -3079,7 +3128,7 @@ function useCacheTransform() {
     }
   };
 }
-function transformFileLevelUseCache(code, ast, filePath, sourceId, isBuild, isLayoutOrTemplate, transformWrapExport, hasDirective) {
+function transformFileLevelUseCache(code, ast, filePath, sourceId, isBuild, isLayoutOrTemplate, transformWrapExport, hasDirective2) {
   const unconfirmedExports = [];
   const { exportNames, output } = transformWrapExport(code, ast, {
     runtime: (value, name) => {
@@ -3091,7 +3140,7 @@ function transformFileLevelUseCache(code, ast, filePath, sourceId, isBuild, isLa
       if (name === "default" && isLayoutOrTemplate) return false;
       if (name.startsWith("$$hoist_")) return false;
       if (isHoistedServerReferenceRebind(meta.valueNode)) return false;
-      if (functionHasUseServerDirective(meta.valueNode, hasDirective)) {
+      if (functionHasUseServerDirective(meta.valueNode, hasDirective2)) {
         return false;
       }
       if (meta.isFunction !== true) {
@@ -3184,13 +3233,13 @@ function isHoistedServerReferenceRebind(valueNode) {
   const first = valueNode.arguments[0];
   return first !== void 0 && first.type === "Identifier" && first.name.startsWith("$$hoist_");
 }
-function functionHasUseServerDirective(valueNode, hasDirective) {
+function functionHasUseServerDirective(valueNode, hasDirective2) {
   if (!valueNode || !("body" in valueNode)) return false;
   const { body } = valueNode;
   if (!body || Array.isArray(body) || body.type !== "BlockStatement") {
     return false;
   }
-  return hasDirective(
+  return hasDirective2(
     body.body,
     "use server"
   );
@@ -3746,7 +3795,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.13.0",
+  version: "0.15.0",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -12304,6 +12353,7 @@ If this is a multi-app host router, export a createHostRouter() instance and set
       }
     }
   });
+  plugins.push(createLoaderDirectiveGuardPlugin());
   plugins.push(createLoaderScanStubPlugin());
   plugins.push(exposeActionId());
   plugins.push(useCacheTransform());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/breadcrumbs/SKILL.md

@@ -67,7 +67,6 @@ consumption, `clientUrls()` groups) still build trails:
 
 ```typescript
 export const ProductLoader = createLoader(async (ctx) => {
-  "use server";
   const product = await getProduct(ctx.params.slug);
 
   const pushCrumb = ctx.use(Breadcrumbs);

package/skills/client-urls/SKILL.md

@@ -54,9 +54,10 @@ Consequences you will hit:
   `path("/x", <HomePage />)` and not an inline arrow — the projection stores a
   component reference, and an anonymous value throws
   (`clientUrls() path() expects a named client component value`).
-- **Loaders must be `createLoader()` definitions** whose bodies are
-  `"use server"` — they execute on the server, addressed by id; the client
-  module only imports the definition object.
+- **Loaders must be `createLoader()` definitions.** They execute on the
+  server, addressed by id; the client module only imports the definition
+  object. Do NOT put a `"use server"` directive in the body — it is not
+  needed, and the build rejects it (see `/loader` → "Creating a Loader").
 - **Everything in the definition must be JSON-projectable.** That is why the
   unsupported helpers below are rejected rather than silently dropped.
 
@@ -130,7 +131,7 @@ typing work exactly as for server routes (`/typesafety`).
 | `loader()`     | `loader(Def, use?)` or `loader(Def, { ssr: false }, use?)` — see below                                                                                         |
 | `loading()`    | Route-level boundary around the optimistic render; inline `<Suspense>` at read sites keeps the destination's chrome visible while only the reads wait          |
 | `revalidate()` | Valid **inside a loader() use callback only**; runs in the browser                                                                                             |
-| `transition()` | Data-only ViewTransition config — no `when` (that is a server-executed predicate)                                                                              |
+| `transition()` | Data-only ViewTransition animation config — no `when`; same-route navs in a group already hold previous content without it                                     |
 | `intercept()`  | Dot-local named target in the SAME definition; use may contain `loader()`/`loading()`                                                                          |
 
 `include`, `parallel`, `cache`, `middleware`, `errorBoundary`,
@@ -230,7 +231,6 @@ is server code either way.
 
 ```ts
 export const ProductLoader = createLoader(async (ctx) => {
-  "use server";
   const moved = LEGACY_SLUGS[ctx.params.slug];
   if (moved) throw redirect(`/shop/product/${moved}`);
   if (!(await exists(ctx.params.slug))) notFound(`No "${ctx.params.slug}"`);

package/skills/hooks/data.md

@@ -270,8 +270,6 @@ Server-side loader for the upload:
 import { createLoader } from "@rangojs/router";
 
 export const FileUploadLoader = createLoader(async (ctx) => {
-  "use server";
-
   const file = ctx.formData?.get("file") as File | null;
   if (file && file.size > 0) {
     // Process file (save to R2, D1, etc.)

package/skills/loader/SKILL.md

@@ -24,8 +24,6 @@ flow is _action mutates → loader re-reads → UI updates_.
 import { createLoader } from "@rangojs/router";
 
 export const ProductLoader = createLoader(async (ctx) => {
-  "use server";
-
   const product = await ctx.env.DB.prepare(
     "SELECT * FROM products WHERE slug = ?",
   )
@@ -36,6 +34,15 @@ export const ProductLoader = createLoader(async (ctx) => {
 });
 ```
 
+Loader bodies already run only on the server — never add a `"use server"`
+directive inside the callback. `"use server"` means "expose this function to
+the client as a callable server reference", not "server only": the directive
+would hoist the body into a registered server reference that anyone can invoke
+through the action endpoint with caller-supplied arguments. The Vite plugin
+rejects it at transform time (`createLoader() body at <file>:<line> carries a
+"use server" directive`). For a build-time guarantee that a module never
+reaches the client graph, use `import "server-only"` instead.
+
 ### Supported export patterns
 
 All of the following are equivalent and fully supported by the Vite transform:
@@ -194,8 +201,6 @@ Loaders receive the same context shape as route handlers.
 
 ```typescript
 export const ProductLoader = createLoader(async (ctx) => {
-  "use server";
-
   // URL params (may include client-provided overrides for fetchable loaders)
   const { slug } = ctx.params;
 
@@ -242,8 +247,6 @@ or resource scoping:
 
 ```typescript
 export const OrderLoader = createLoader(async (ctx) => {
-  "use server";
-
   // Use routeParams for auth checks — client cannot spoof the URL-matched ID
   const { orderId } = ctx.routeParams;
   const user = ctx.get("user");
@@ -674,7 +677,6 @@ signal instead of re-checking existence at each read site:
 import { createLoader, notFound, redirect } from "@rangojs/router";
 
 export const ProductLoader = createLoader(async (ctx) => {
-  "use server";
   const moved = LEGACY_SLUGS[ctx.params.slug];
   if (moved) throw redirect(`/shop/product/${moved}`);
 
@@ -708,7 +710,6 @@ where the data lives:
 import { Meta, Breadcrumbs } from "./handles";
 
 export const ProductLoader = createLoader(async (ctx) => {
-  "use server";
   const product = await getProduct(ctx.params.slug);
 
   ctx.use(Meta)({ title: `${product.name} — Shop` });
@@ -799,8 +800,6 @@ via `useFetchLoader()` and `load()`:
 import { createLoader } from "@rangojs/router";
 
 export const SearchLoader = createLoader(async (ctx) => {
-  "use server";
-
   const query = ctx.params.query ?? "";
   const results = await ctx.env.DB.prepare(
     "SELECT * FROM products WHERE name LIKE ?",
@@ -812,6 +811,13 @@ export const SearchLoader = createLoader(async (ctx) => {
 }, true); // true = fetchable
 ```
 
+`true` attaches an EMPTY middleware list, and the fetch lane never runs route
+`middleware()` (see `/middleware` → "Request flow"). A fetchable loader that
+reads a var set by route middleware (`ctx.get(CurrentUser)`) therefore sees
+`undefined` on `useFetchLoader()` / `load()` / `useRefreshLoaders()` unless it
+passes that middleware itself: `createLoader(fn, { middleware: [loadSession,
+requireAuth] })` (next section).
+
 > **No registration needed — and no worker-entry import.** A fetchable loader
 > does not have to be registered with `loader()` in the route DSL, and it does
 > not have to be imported by any server module. Importing it into the client
@@ -835,8 +841,6 @@ import { rateLimitMiddleware } from "../middleware/rate-limit";
 
 export const ProtectedLoader = createLoader(
   async (ctx) => {
-    "use server";
-
     const user = ctx.get("user");
     return { orders: await db.orders.list(user.id) };
   },
@@ -847,6 +851,12 @@ export const ProtectedLoader = createLoader(
 The middleware uses the same `MiddlewareFn` signature as route/app middleware,
 so you can reuse existing middleware functions directly.
 
+A `redirect()` thrown by per-loader middleware becomes a real 3xx on the fetch
+lane, so the browser's `fetch` follows it and `useFetchLoader()` receives the
+login page's HTML instead of loader data. Reserve redirects for document and
+navigation requests; on the fetch lane return a 401 (or a structured error
+payload) and let the caller decide.
+
 Fetchable loaders support both GET and POST (PUT, PATCH, DELETE) from the client.
 The `load()` function auto-detects the body type:
 
@@ -860,8 +870,6 @@ includes additional fields depending on the body type:
 
 ```typescript
 export const MutationLoader = createLoader(async (ctx) => {
-  "use server";
-
   // JSON body — available as ctx.body (parsed object)
   const data = ctx.body as { name: string; email: string };
 
@@ -883,8 +891,6 @@ export const MutationLoader = createLoader(async (ctx) => {
 import { createLoader } from "@rangojs/router";
 
 export const FileUploadLoader = createLoader(async (ctx) => {
-  "use server";
-
   const file = ctx.formData?.get("file") as File | null;
   if (file && file.size > 0) {
     // Save to R2, D1, etc.
@@ -911,8 +917,6 @@ Client usage — see `/hooks useFetchLoader` for the full client-side pattern.
 import { createLoader } from "@rangojs/router";
 
 export const ProductLoader = createLoader(async (ctx) => {
-  "use server";
-
   const product = await ctx.env.DB
     .prepare("SELECT * FROM products WHERE slug = ?")
     .bind(ctx.params.slug)
@@ -926,8 +930,6 @@ export const ProductLoader = createLoader(async (ctx) => {
 });
 
 export const CartLoader = createLoader(async (ctx) => {
-  "use server";
-
   const user = ctx.get("user");
   if (!user) return { cart: null };
 

package/skills/middleware/SKILL.md

@@ -38,6 +38,9 @@ Request flow (with action):
 Request flow (no action):
   global mw -> route mw -> render pass
 
+Fetchable loader request (_rsc_loader: useFetchLoader / load / useRefreshLoaders):
+  global mw -> per-loader { middleware } list -> loader   (route mw does NOT run)
+
 Progressive enhancement (no-JS form POST):
   global mw -> action executes -> route mw -> full page re-render
 ```

package/skills/migrate-nextjs/SKILL.md

@@ -737,7 +737,6 @@ maps to a Meta push from the LOADER that owns the data, plus
 // Rango: push from the loader; the flag makes the document render await it,
 // so the title is in the SSR'd <head> like generateMetadata guarantees.
 export const ProductLoader = createLoader(async (ctx) => {
-  "use server";
   const product = await getProduct(ctx.params.slug);
   ctx.use(Meta)({ title: product.name });
   return product;

package/skills/router-setup/SKILL.md

@@ -356,7 +356,6 @@ path("/product/:slug", async (ctx) => {
 
 // In a loader — data-dependent authority lives with the data
 export const ProductLoader = createLoader(async (ctx) => {
-  "use server";
   if (!(await exists(ctx.params.slug))) notFound("Product not found");
   return getProduct(ctx.params.slug);
 });

package/skills/shell-manifest/SKILL.md

@@ -92,7 +92,6 @@ import { createLoader } from "@rangojs/router";
 import { RenderedProducts } from "../handles/rendered-products";
 
 export const PriceLoader = createLoader(async (ctx) => {
-  "use server";
   await ctx.rendered();
   const ids = ctx.get(RenderedProducts);
   return db.pricesFor(ids); // Map<string, number> keyed by product id

package/src/browser/partial-update.ts

@@ -614,7 +614,7 @@ export function createPartialUpdater(
             scroll: scrollPayload,
           });
         });
-      } else if (fullyPrefetched || isSameStructureNav) {
+      } else if (fullyPrefetched || isSameStructureNav || optimisticPresented) {
         // Content-hold commit, two triggers. Fully-prefetched nav: the payload
         // is fully resolved (forceAwait above), so the transition commits
         // synchronously — no fallback flash. Same-structure nav: the re-run
@@ -633,7 +633,10 @@ export function createPartialUpdater(
         // instead of revealing that boundary's fallback; its render happens
         // pre-commit inside the transition, so userland effects cannot run
         // first. Boundaries newly mounted by this nav still reveal their
-        // fallbacks (React shows new boundaries inside transitions).
+        // fallbacks (React shows new boundaries inside transitions). An
+        // optimistic clientUrls() presentation commits here too: the group
+        // segment reconciles in place (clientGroup key), so a read that still
+        // suspends must hold the presented content, not flash a fallback.
         startTransition(() => {
           if (optimisticPresented && addTransitionType) {
             addTransitionType(OPTIMISTIC_COMMIT_TRANSITION_TYPE);

package/src/cache/segment-codec.ts

@@ -215,6 +215,7 @@ export async function serializeSegments(
           loaderIds: segment.loaderIds,
           transition: segment.transition,
           mountPath: segment.mountPath,
+          clientGroup: segment.clientGroup,
         },
       };
     }),

package/src/client-urls/client-root.tsx

@@ -174,13 +174,17 @@ export function ClientUrlsRoot({
     [optimisticRoute, presented],
   );
 
+  // The wrapper chain below is IDENTICAL in the optimistic and the canonical
+  // render (only prop values change): together with the group-keyed segment
+  // (segment-system.tsx, ResolvedSegment.clientGroup) that is what lets the
+  // destination instance survive the canonical commit.
   let content: ReactNode = createElement(route.component, { key: route.id });
-  if (optimisticRoute && optimisticRoute.loading !== undefined) {
-    // loading() is the route-level boundary around the optimistic render;
-    // presence mirrors the projection's hasLoading (a falsy-but-valid node
-    // like loading("") is still a configured fallback).
+  if (route.loading !== undefined) {
+    // loading() is the route-level boundary for group routes (segment-system
+    // places no LoaderBoundary around them); presence mirrors the
+    // projection's hasLoading (loading("") is still a configured fallback).
     content = createElement(Suspense, {
-      fallback: optimisticRoute.loading,
+      fallback: route.loading,
       children: content,
     });
   }
@@ -195,19 +199,15 @@ export function ClientUrlsRoot({
     });
   }
 
-  if (optimistic) {
-    content = createElement(OutletProvider, {
-      content: null,
-      loaderStreams: optimistic.streams,
-      pending,
-      children: createElement(OptimisticLocationContext.Provider, {
-        value: optimistic.location,
-        children: content,
-      }),
-    });
-  }
-
-  return content;
+  return createElement(OutletProvider, {
+    content: null,
+    loaderStreams: optimistic?.streams,
+    pending,
+    children: createElement(OptimisticLocationContext.Provider, {
+      value: optimistic?.location ?? null,
+      children: content,
+    }),
+  });
 }
 
 export function ClientUrlsLoading({

package/src/client-urls/server-projection.ts

@@ -481,8 +481,12 @@ function createLoaderStub(id: string): LoaderDefinition<unknown> {
   };
 }
 
-function materializedPathOptions(route: ClientUrlProjectionRoute): PathOptions {
+function materializedPathOptions(
+  route: ClientUrlProjectionRoute,
+  clientGroup: string,
+): PathOptions {
   return {
+    clientGroup,
     ...(route.name === null ? {} : { name: route.name }),
     ...(route.options.search ? { search: { ...route.options.search } } : {}),
     ...(route.options.trailingSlash
@@ -517,6 +521,9 @@ function materializeRouteItems(
   // route-name prefix is available here. ClientUrlsRoot needs it to compose
   // canonical names for intercept-target coordination in the browser.
   const namePrefix = getNamePrefix();
+  // One key per group MOUNT (the include's URL prefix): renderSegments keys
+  // every route segment of the group by it (ResolvedSegment.clientGroup).
+  const clientGroup = getUrlPrefix() || "/";
 
   // Helper calls attach to the CURRENT ctx.parent as they execute, so these
   // builders must run where the items belong: at the module top level for the
@@ -533,7 +540,7 @@ function materializeRouteItems(
               routeId: route.id,
               namePrefix,
             }),
-          materializedPathOptions(route),
+          materializedPathOptions(route, clientGroup),
           () => [
             ...route.loaderIds.map((id, loaderIndex) =>
               loader(

package/src/route-content-wrapper.tsx

@@ -32,15 +32,36 @@ import { LoaderRedirect } from "./loader-redirect.js";
  * Errors without any marker rethrow to the app's own boundaries.
  */
 export class StreamedLoaderErrorBoundary extends Component<
-  { children: ReactNode },
-  { error: unknown }
+  { children: ReactNode; resetKey?: string },
+  { error: unknown; resetKey?: string }
 > {
-  state: { error: unknown } = { error: null };
+  state: { error: unknown; resetKey?: string } = {
+    error: null,
+    resetKey: this.props.resetKey,
+  };
 
   static getDerivedStateFromError(error: unknown): { error: unknown } {
     return { error };
   }
 
+  /**
+   * A caught marker (redirect, notFound, error fallback) belongs to ONE route
+   * + params. Group-keyed segments (ResolvedSegment.clientGroup) keep this
+   * instance alive across in-group navigations, so the error must clear when
+   * the route or params change — otherwise a redirect caught for /legacy
+   * keeps rendering LoaderRedirect for /state. `resetKey` is the segment's
+   * id-params identity, the cadence the per-route remount used to provide.
+   */
+  static getDerivedStateFromProps(
+    props: { resetKey?: string },
+    state: { error: unknown; resetKey?: string },
+  ): { error: unknown; resetKey?: string } | null {
+    if (props.resetKey !== state.resetKey) {
+      return { error: null, resetKey: props.resetKey };
+    }
+    return null;
+  }
+
   render(): ReactNode {
     const { error } = this.state;
     if (error !== null && error !== undefined) {

package/src/router/segment-resolution/fresh.ts

@@ -468,6 +468,7 @@ export async function resolveSegment<TEnv>(
       ),
       params,
       belongsToRoute: true,
+      ...(entry.clientGroup ? { clientGroup: entry.clientGroup } : {}),
       ...(entry.mountPath ? { mountPath: entry.mountPath } : {}),
     });
   } else {

package/src/router/segment-resolution/revalidation.ts

@@ -907,6 +907,7 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
     ),
     params,
     belongsToRoute,
+    ...(entry.clientGroup ? { clientGroup: entry.clientGroup } : {}),
     ...(entry.type === "layout" || entry.type === "cache"
       ? { layoutName: entry.id }
       : {}),

package/src/segment-system.tsx

@@ -350,6 +350,13 @@ export async function renderSegments(
       `Expected layout, route, error, or notFound segment, got ${node.segment.type}`,
     );
     const { component, id, params, loading } = node.segment;
+    // clientUrls() group routes: ONE React key and ONE wrapper shape per group
+    // mount (no LoaderBoundary/RouteContentWrapper — ClientUrlsRoot renders
+    // loading() itself), so an in-group navigation reconciles the mounted
+    // ClientUrlsRoot: the optimistic destination keeps its instance across the
+    // commit and same-route param navs hold instead of remounting. The
+    // server-side loading value still drives PPR masking and SSR.
+    const clientGroup = node.segment.clientGroup;
     const segNodeStart = segDebug ? performance.now() : 0;
 
     // Param-agnostic keys are opt-in via the transition() DSL (see
@@ -385,7 +392,10 @@ export async function renderSegments(
             .map(([k, v]) => `${k}=${v}`)
             .join(",")
         : "";
-    const key = paramStr ? `${id}-${paramStr}` : id;
+    // Route identity the per-route remount used to provide; group routes key
+    // by the group instead and pass it to the error boundary as its resetKey.
+    const idParamsKey = paramStr ? `${id}-${paramStr}` : id;
+    const key = clientGroup ? `cg:${clientGroup}` : idParamsKey;
 
     const loaderEntries = node.loaders.filter(
       (loader) => loader.loaderId && loader.loaderData !== undefined,
@@ -403,7 +413,7 @@ export async function renderSegments(
     }
 
     let nodeContent: ReactNode = null;
-    if (isRenderableLoading(loading)) {
+    if (!clientGroup && isRenderableLoading(loading)) {
       // forceAwait (popstate, stale-revalidation, fully-prefetched nav) renders a
       // loading() route with the route content ALREADY resolved, so its
       // RouteContentWrapper Suspender does not suspend for a microtask and flash
@@ -499,13 +509,14 @@ export async function renderSegments(
     // escaping to app boundaries. Wrapped UNCONDITIONALLY on loader presence
     // — streams and forceAwait lanes must produce the same tree shape or
     // lane changes remount the subtree (docs/tree-structure.md).
-    if (loaderEntries.length > 0) {
+    if (loaderEntries.length > 0 || clientGroup) {
       nodeContent = createElement(StreamedLoaderErrorBoundary, {
+        resetKey: idParamsKey,
         children: nodeContent,
       });
     }
 
-    if (loading !== undefined && loading !== null) {
+    if (!clientGroup && loading !== undefined && loading !== null) {
       const loaderDataPromise = getMemoizedLoaderPromise(loaderEntries);
       let boundaryLoaderData: Promise<any[]> | any[] = loaderDataPromise;
       // SPIKE (streaming useLoader): per-loader streams for the boundary's

package/src/server/context.ts

@@ -69,6 +69,8 @@ export type EntryPropCommon = {
   cache?: EntryCacheConfig;
   /** URL prefix from include() scope, used for MountContext on client */
   mountPath?: string;
+  /** clientUrls() group key (PathOptions.clientGroup); route entries only. */
+  clientGroup?: string;
 };
 
 /**

package/src/types/loader-types.ts

@@ -24,14 +24,12 @@ import type { RequestScope } from "./request-scope.js";
  * @example
  * ```typescript
  * const CartLoader = createLoader(async (ctx) => {
- *   "use server";
  *   const user = ctx.get("user");  // From auth middleware
  *   return await db.cart.get(user.id);
  * });
  *
  * // With typed params:
  * const ProductLoader = createLoader<Product, { slug: string }>(async (ctx) => {
- *   "use server";
  *   const { slug } = ctx.params;  // slug is typed as string
  *   return await db.products.findBySlug(slug);
  * });
@@ -81,7 +79,6 @@ export type LoaderContext<
    * @example
    * ```typescript
    * export const ProductLoader = createLoader(async (ctx) => {
-   *   "use server";
    *   const product = await getProduct(ctx.params.slug);
    *   ctx.use(Meta)({ title: product.name });
    *   ctx.use(Breadcrumbs)({ label: product.name });
@@ -111,7 +108,6 @@ export type LoaderContext<
    * @example
    * ```typescript
    * const PricesLoader = createLoader(async (ctx) => {
-   *   "use server";
    *   await ctx.rendered();
    *   const products = ctx.get(Products); // reads handle data
    *   return pricing.getLive(products.map(p => p.id));
@@ -234,7 +230,8 @@ export type LoadOptions =
  * Loader definition object
  *
  * Created via createLoader(). Contains the loader name and function.
- * On client builds, the fn is stripped by the bundler (via "use server" directive).
+ * On client builds, the fn is stripped by the router's loader transform; the
+ * definition must not carry a "use server" directive (the Vite plugin rejects it).
  *
  * @template T - The return type of the loader
  * @template TParams - Route params type (for type-safe params access)
@@ -243,13 +240,11 @@ export type LoadOptions =
  * ```typescript
  * // Definition (same file works on server and client)
  * export const CartLoader = createLoader(async (ctx) => {
- *   "use server";
  *   return await db.cart.get(ctx.get("user").id);
  * });
  *
  * // With typed params:
  * export const ProductLoader = createLoader<Product, { slug: string }>(async (ctx) => {
- *   "use server";
  *   const { slug } = ctx.params;  // slug is typed as string
  *   return await db.products.findBySlug(slug);
  * });

package/src/types/segments.ts

@@ -193,6 +193,9 @@ export interface ResolvedSegment {
   notFoundInfo?: NotFoundInfo; // For notFound segments: the not found information
   // Mount path from include() scope, used for MountContext.Provider wrapping
   mountPath?: string;
+  /** clientUrls() group key (the include mount), shared by every route
+   *  segment of one group; see the group-route branch in segment-system.tsx. */
+  clientGroup?: string;
   /**
    * @internal Server-side marker: true when the segment's handler actually ran
    * this request (not skipped via the revalidate cache path). Used by

package/src/urls/path-helper.ts

@@ -154,6 +154,7 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
       handler: wrappedHandler,
       pattern: prefixedPattern,
       ...(urlPrefix ? { mountPath: urlPrefix } : {}),
+      ...(options?.clientGroup ? { clientGroup: options.clientGroup } : {}),
       ...(isPassthroughHandler(handler)
         ? {
             isPrerender: true as const,

package/src/urls/pattern-types.ts

@@ -112,6 +112,9 @@ export interface PathOptions<
   trailingSlash?: TrailingSlashMode;
   /** Response type marker (set by path.json(), etc.) */
   [RESPONSE_TYPE]?: string;
+  /** @internal clientUrls() group key stamped by server-projection.ts; see
+   *  ResolvedSegment.clientGroup. */
+  clientGroup?: string;
 }
 
 /**

package/src/vite/plugins/expose-ids/loader-transform.ts

@@ -1,7 +1,8 @@
 import type MagicString from "magic-string";
 import { makeStubId } from "../expose-id-utils.js";
 import type { CreateExportBinding } from "./types.js";
-import { isExportOnlyFile } from "./export-analysis.js";
+import { hasDirective } from "@vitejs/plugin-rsc/transforms";
+import { isExportOnlyFile, offsetToLineColumn } from "./export-analysis.js";
 
 export function hasCreateLoaderImport(code: string): boolean {
   return /import\s*\{[^}]*\bcreateLoader\b[^}]*\}\s*from\s*["']@rangojs\/router(?:\/server)?["']/.test(
@@ -62,3 +63,55 @@ export function transformLoaders(
 
   return hasChanges;
 }
+
+export interface LoaderServerDirective {
+  line: number;
+}
+
+function loaderCallback(node: any, names: Set<string>): any {
+  if (
+    node?.type !== "CallExpression" ||
+    node.callee?.type !== "Identifier" ||
+    !names.has(node.callee.name)
+  ) {
+    return undefined;
+  }
+  const fn = node.arguments?.[0];
+  return (fn?.type === "ArrowFunctionExpression" ||
+    fn?.type === "FunctionExpression") &&
+    fn.body?.type === "BlockStatement"
+    ? fn
+    : undefined;
+}
+
+/**
+ * Locate an inline `"use server"` directive at the top of a createLoader()
+ * callback body. Only top-level `const X = createLoader(...)` bindings (bare
+ * or exported) are checked — the same shapes the loader transform registers.
+ * Loaders are never client-callable, and the directive makes plugin-rsc
+ * hoist the body and `registerServerReference` it, so the loader body
+ * becomes a public action reachable with caller-supplied arguments (verified
+ * against a production build: a POST to `?_rsc_action=<id>` ran a loader body
+ * with a forged ctx). The guard plugin throws on the first hit.
+ */
+export function findLoaderServerDirective(
+  code: string,
+  fnNames: readonly string[],
+  program: any,
+): LoaderServerDirective | null {
+  const names = new Set(fnNames);
+  for (const statement of program.body ?? []) {
+    const declaration =
+      statement.type === "ExportNamedDeclaration"
+        ? statement.declaration
+        : statement;
+    if (declaration?.type !== "VariableDeclaration") continue;
+    for (const declarator of declaration.declarations) {
+      const fn = loaderCallback(declarator.init, names);
+      if (fn && hasDirective(fn.body.body, "use server")) {
+        return { line: offsetToLineColumn(code, fn.body.body[0].start).line };
+      }
+    }
+  }
+  return null;
+}

package/src/vite/plugins/expose-internal-ids.ts

@@ -35,6 +35,7 @@ import {
   hasCreateLoaderImport,
   generateClientLoaderStubs,
   transformLoaders,
+  findLoaderServerDirective,
 } from "./expose-ids/loader-transform.js";
 import {
   transformHandles,
@@ -114,6 +115,51 @@ export function createLoaderScanStubPlugin(): Plugin {
   };
 }
 
+/**
+ * Refuse an inline `"use server"` directive inside a createLoader() callback.
+ * Runs `pre` so it sees the raw source before plugin-rsc's directive transform
+ * hoists the body into a registered server reference. See
+ * findLoaderServerDirective for why that registration is a problem.
+ */
+export function createLoaderDirectiveGuardPlugin(): Plugin {
+  return {
+    name: "@rangojs/router:loader-directive-guard",
+    enforce: "pre",
+    transform(code, id) {
+      if (
+        id.includes("/node_modules/") ||
+        !code.includes("use server") ||
+        !code.includes("createLoader") ||
+        !hasCreateLoaderImport(code)
+      ) {
+        return;
+      }
+
+      const cleanId = id.split("?", 1)[0];
+      let program: any;
+      try {
+        program = parseAst(code, { lang: "tsx" });
+      } catch {
+        return;
+      }
+
+      const hit = findLoaderServerDirective(
+        code,
+        getImportedFnNames(code, "createLoader"),
+        program,
+      );
+      if (!hit) return;
+
+      throw new Error(
+        `[rango] createLoader() body at ${cleanId}:${hit.line} carries a "use server" directive. ` +
+          `Loader bodies already run only on the server; the directive would register the body as a ` +
+          `client-callable server reference (reachable through the action endpoint with caller-supplied ` +
+          `arguments). Remove the directive.`,
+      );
+    },
+  };
+}
+
 export function exposeInternalIds(options?: { forceBuild?: boolean }): Plugin {
   let config: ResolvedConfig;
   let isBuild = false;

package/src/vite/rango.ts

@@ -4,6 +4,7 @@ import { resolve } from "node:path";
 import { exposeActionId } from "./plugins/expose-action-id.js";
 import { defineEncryptionKeyExpr } from "./encryption-key.js";
 import {
+  createLoaderDirectiveGuardPlugin,
   createLoaderScanStubPlugin,
   exposeInternalIds,
   exposeRouterId,
@@ -561,6 +562,7 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
     },
   });
 
+  plugins.push(createLoaderDirectiveGuardPlugin());
   plugins.push(createLoaderScanStubPlugin());
   plugins.push(exposeActionId());
   plugins.push(useCacheTransform());