@rangojs/router 0.14.0 → 0.15.1

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/decode-loader-results.d.ts

@@ -14,7 +14,10 @@ import type { ReactNode } from "react";
  * decodeLoaderResults runs during the SERVER tree build on forceAwait/action
  * lanes, where a throw would collapse the whole payload — it routes signals
  * through the errorFallback slot instead (same visual: the slot replaces the
- * children under OutletProvider).
+ * children under OutletProvider). The document lane's `{ ssr: false }`
+ * results take the same non-throwing route (segment-system
+ * buildLoaderStreams): they are settled before the tree is built, and the
+ * read-site throw would land in the Fizz shell with no boundary to absorb it.
  */
 export declare const LOADER_NOT_FOUND_FALLBACK: unique symbol;
 export declare const LOADER_REDIRECT: unique symbol;

package/dist/types/rsc/shell-capture.d.ts

@@ -78,7 +78,6 @@ declare const REFUSED_CAPTURE_MAX_MS = 60000;
  * docs/design/ppr-shell-resume.md ("Refused-capture backoff").
  */
 declare const REFUSED_CAPTURE_DEV_MAX_MS = 2000;
-/** True iff `key` is still inside its (exponential) backoff window. */
 declare function isCaptureBackedOff(key: string): boolean;
 /**
  * Record a refused/failed capture, escalating the backoff window exponentially up

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/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.14.0",
+  version: "0.15.1",
   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.14.0",
+  "version": "0.15.1",
   "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.
 
@@ -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}`);
 
@@ -693,6 +695,15 @@ Semantics by lane:
 | `notFound()` | Not-found UI resolves server-side (nearest `notFoundBoundary` → router option → default) and rides the envelope; the 404 STATUS is **opportunistic** — real only if the rejection beats Response construction. `ssr: false` (below) makes it deterministic. | 404 UI swaps in, URL preserved, payload stays 200 |
 | `redirect()` | 200 document, then a client-side replace to the target — **no document-lane 302 from loaders**; pre-stream redirect authority belongs to middleware                                                                                                         | Redirect envelope navigates to the target         |
 
+With `loader(Def, { ssr: false })` the result is settled BEFORE the document
+flushes, so both signals are resolved server-side while the tree is built:
+`redirect()` replaces the whole page with the redirect carrier (still a 200
+document, the client replaces to the target on hydration) and `notFound()`
+renders the not-found UI at the owning segment with a real 404. No read site
+runs, so a `useLoader` in a layout above every Suspense boundary is safe.
+(Before this was fixed, the flagged read threw inside the Fizz shell and
+500ed the document.)
+
 Session/auth gates belong in middleware (they are request-shaped, not
 data-shaped, and middleware CAN emit a real pre-stream 302). Data-dependent
 "this slug moved / does not exist" belongs in the loader.
@@ -708,7 +719,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 +809,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 +820,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 +850,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 +860,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 +879,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 +900,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 +926,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 +939,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/decode-loader-results.ts

@@ -18,7 +18,10 @@ import { LoaderRedirect } from "./loader-redirect.js";
  * decodeLoaderResults runs during the SERVER tree build on forceAwait/action
  * lanes, where a throw would collapse the whole payload — it routes signals
  * through the errorFallback slot instead (same visual: the slot replaces the
- * children under OutletProvider).
+ * children under OutletProvider). The document lane's `{ ssr: false }`
+ * results take the same non-throwing route (segment-system
+ * buildLoaderStreams): they are settled before the tree is built, and the
+ * read-site throw would land in the Fizz shell with no boundary to absorb it.
  */
 export const LOADER_NOT_FOUND_FALLBACK: unique symbol = Symbol(
   "rango.loaderNotFound",

package/src/rsc/shell-capture.ts

@@ -17,6 +17,7 @@
  */
 
 import React from "react";
+import { isLoaderDataResult } from "../types.js";
 import { bufferToBase64 } from "../cache/cf/cf-base64.js";
 import { reportCacheError } from "../cache/cache-error.js";
 import { runBackground } from "../cache/background-task.js";
@@ -311,6 +312,14 @@ function refusedCaptureCeilingMs(): number {
 const refusedCaptures = new Map<string, { failures: number; until: number }>();
 
 /** True iff `key` is still inside its (exponential) backoff window. */
+function isSettledLoaderSignal(value: unknown): boolean {
+  return (
+    isLoaderDataResult(value) &&
+    !value.ok &&
+    (value.redirect !== undefined || value.notFound === true)
+  );
+}
+
 function isCaptureBackedOff(key: string): boolean {
   const entry = refusedCaptures.get(key);
   if (entry === undefined) return false;
@@ -1936,6 +1945,19 @@ async function captureAndStoreShell(
         // The container itself never settled: it is a hole (under an ancestor
         // boundary) or the trivial-prelude gate already fired. Omit — no pin.
         if (isLoaderHoleMarker(elided.value)) continue;
+        // redirect()/notFound() RESOLVE as ok:false envelopes
+        // (wrapLoaderWithErrorHandling), so the rejection check above never
+        // sees them; the tree builder resolves them to LoaderRedirect / the
+        // not-found UI (segment-system buildLoaderStreams), which must not
+        // bake into a shell every visitor shares.
+        if (isSettledLoaderSignal(elided.value)) {
+          warnCaptureRefusedOnce(
+            capture.key,
+            `the loader for segment "${segmentKey}" settled with redirect()/notFound() during capture; a request-specific signal must not bake into the shared shell. ` +
+              "Give its entry a loading() boundary so it stays on the live lane, or move the decision into middleware.",
+          );
+          return "refused";
+        }
         // Past the hole check: this container settled with real material that
         // bakes into the shell prelude (independent of the snapshot pin below).
         bakedLoaderMaterial = true;

package/src/segment-system.tsx

@@ -1,10 +1,16 @@
 import * as React from "react";
-import { createElement, type ReactNode, type ComponentType } from "react";
+import {
+  createElement,
+  type ReactNode,
+  type ComponentType,
+  isValidElement,
+} from "react";
 import { OutletProvider } from "./outlet-provider.js";
 import { withOptimisticCommitNone } from "./browser/optimistic-commit.js";
 import { MountContextProvider } from "./browser/react/mount-context.js";
 import type { ResolvedSegment, RootLayoutProps } from "./types.js";
 import { decodeLoaderResults } from "./decode-loader-results.js";
+import { LoaderRedirect } from "./loader-redirect.js";
 import { invariant } from "./errors.js";
 import {
   RouteContentWrapper,
@@ -203,20 +209,43 @@ function wrapDefaultOutletContent(
  * SSR-completeness contract must not depend on. Unflagged siblings keep the
  * promise (deliberate streaming). Flagged ids are collected as input for the
  * dev SSR-suspension diagnostic (ssr-suspension-warning.ts).
+ *
+ * The settled results also go through decodeLoaderResults here: a settled
+ * redirect()/notFound() (or an error with an errorBoundary() fallback) must
+ * be resolved to its node while the tree is built, exactly as the
+ * forceAwait/action lanes do, because the read-site throw has no boundary on
+ * the document lane — flagged content renders without Suspense and a layout
+ * reader sits above every boundary, so the throw is a Fizz shell error (500).
+ * `settledFallback` is that node; the caller plants it and, for a redirect,
+ * replaces the whole page (an ancestor reading the loader would still throw).
  */
 async function buildLoaderStreams(loaders: ResolvedSegment[]): Promise<{
   streams: Record<string, unknown>;
   awaitedIds: string[] | undefined;
+  settledFallback: ReactNode | undefined;
 }> {
   const streams: Record<string, unknown> = {};
   let awaitedIds: string[] | undefined;
+  let awaitedValues: unknown[] | undefined;
   for (const l of loaders) {
-    streams[l.loaderId!] = l.awaitBeforeFlush
-      ? await l.loaderData
-      : l.loaderData;
-    if (l.awaitBeforeFlush) (awaitedIds ??= []).push(l.loaderId!);
+    if (l.awaitBeforeFlush) {
+      const value = await l.loaderData;
+      streams[l.loaderId!] = value;
+      (awaitedIds ??= []).push(l.loaderId!);
+      (awaitedValues ??= []).push(value);
+    } else {
+      streams[l.loaderId!] = l.loaderData;
+    }
   }
-  return { streams, awaitedIds };
+  const settledFallback = awaitedIds
+    ? (decodeLoaderResults(awaitedValues!, awaitedIds).errorFallback ??
+      undefined)
+    : undefined;
+  return { streams, awaitedIds, settledFallback };
+}
+
+function isLoaderRedirectNode(node: ReactNode): boolean {
+  return isValidElement(node) && node.type === LoaderRedirect;
 }
 
 /**
@@ -539,10 +568,19 @@ export async function renderSegments(
           });
         }
       } else if (loaderEntries.length > 0) {
+        let settledFallback: ReactNode | undefined;
         ({
           streams: boundaryLoaderStreams,
           awaitedIds: boundaryAwaitedLoaderIds,
+          settledFallback,
         } = await buildLoaderStreams(loaderEntries));
+        if (settledFallback !== undefined) {
+          if (isLoaderRedirectNode(settledFallback)) {
+            content = settledFallback;
+            break;
+          }
+          nodeContent = settledFallback;
+        }
         if (segDebug) {
           segDebugLog(
             `segment ${id}: per-loader streams via LoaderBoundary (read-site suspense)`,
@@ -614,8 +652,19 @@ export async function renderSegments(
           }
         }
       } else if (layoutLoaders.length > 0) {
-        ({ streams: loaderStreams, awaitedIds: awaitedLoaderIds } =
-          await buildLoaderStreams(layoutLoaders));
+        let settledFallback: ReactNode | undefined;
+        ({
+          streams: loaderStreams,
+          awaitedIds: awaitedLoaderIds,
+          settledFallback,
+        } = await buildLoaderStreams(layoutLoaders));
+        if (settledFallback !== undefined) {
+          if (isLoaderRedirectNode(settledFallback)) {
+            content = settledFallback;
+            break;
+          }
+          errorFallback = settledFallback;
+        }
         if (segDebug) {
           segDebugLog(
             `segment ${id}: layout loaders streaming to read sites (no loading())`,

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/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());