@rangojs/router 0.23.0 → 0.24.1

package/dist/vite/index.js

@@ -119,7 +119,7 @@ __export(client_ref_hashing_exports, {
   hashRefKey: () => hashRefKey,
   transformClientRefs: () => transformClientRefs
 });
-import { relative as relative3 } from "node:path";
+import { relative as relative4 } from "node:path";
 import { createHash as createHash3 } from "node:crypto";
 function hashRefKey(relativeId) {
   return createHash3("sha256").update(relativeId).digest("hex").slice(0, 12);
@@ -132,10 +132,10 @@ function computeProductionHash(projectRoot, refKey) {
     const absPath = decodeURIComponent(
       refKey.slice(CLIENT_IN_SERVER_PKG_PROXY_PREFIX.length)
     );
-    toHash = relative3(projectRoot, absPath).replaceAll("\\", "/");
+    toHash = relative4(projectRoot, absPath).replaceAll("\\", "/");
   } else if (refKey.startsWith(FS_PREFIX)) {
     const absPath = refKey.slice(FS_PREFIX.length - 1);
-    toHash = relative3(projectRoot, absPath).replaceAll("\\", "/");
+    toHash = relative4(projectRoot, absPath).replaceAll("\\", "/");
   } else if (refKey.startsWith("/")) {
     toHash = refKey.slice(1);
   } else {
@@ -1903,6 +1903,70 @@ function transformInlineHandlers(fnName, virtualPrefix, s, code, filePath, virtu
   return true;
 }
 
+// src/build/route-types/scan-filter.ts
+import { isAbsolute, join, relative } from "node:path";
+import { readdirSync } from "node:fs";
+import picomatch from "picomatch";
+var DEFAULT_EXCLUDE_PATTERNS = [
+  "**/__tests__/**",
+  "**/__mocks__/**",
+  "**/dist/**",
+  "**/coverage/**",
+  "**/*.test.{ts,tsx,js,jsx}",
+  "**/*.spec.{ts,tsx,js,jsx}"
+];
+function createScanFilter(root, opts) {
+  const { include, exclude } = opts;
+  const hasInclude = include && include.length > 0;
+  const hasCustomExclude = exclude !== void 0;
+  if (!hasInclude && !hasCustomExclude) return void 0;
+  const effectiveExclude = exclude ?? DEFAULT_EXCLUDE_PATTERNS;
+  const includeMatcher = hasInclude ? picomatch(include) : null;
+  const excludeMatcher = effectiveExclude.length > 0 ? picomatch(effectiveExclude) : null;
+  return (absolutePath) => {
+    const rel = relative(root, absolutePath);
+    if (excludeMatcher && excludeMatcher(rel)) return false;
+    if (includeMatcher) return includeMatcher(rel);
+    return true;
+  };
+}
+function isUniversallySkippedScanDir(name) {
+  return name === "node_modules" || name === "dist" || name === "coverage" || name.startsWith(".");
+}
+function isInSkippedScanDir(root, absolutePath) {
+  const rel = relative(root, absolutePath);
+  if (isAbsolute(rel)) return false;
+  const dirs = rel.split(/[\\/]/).slice(0, -1);
+  if (dirs[0] === "..") return false;
+  return dirs.some(isUniversallySkippedScanDir);
+}
+function isSkippedSourceScanDir(name) {
+  return isUniversallySkippedScanDir(name) || name === "build";
+}
+function findTsFiles(dir, filter) {
+  const results = [];
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch (err) {
+    console.warn(
+      `[rango] Failed to scan directory ${dir}: ${err.message}`
+    );
+    return results;
+  }
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (isSkippedSourceScanDir(entry.name)) continue;
+      results.push(...findTsFiles(fullPath, filter));
+    } else if ((entry.name.endsWith(".ts") || entry.name.endsWith(".tsx") || entry.name.endsWith(".js") || entry.name.endsWith(".jsx")) && !entry.name.includes(".gen.")) {
+      if (filter && !filter(fullPath)) continue;
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+
 // src/vite/plugins/expose-ids/types.ts
 var PRERENDER_CONFIG = {
   fnName: "Prerender",
@@ -2443,8 +2507,14 @@ function compareStrings(a, b) {
 // src/vite/discovery/state.ts
 var VIRTUAL_ROUTES_MANIFEST_ID = "virtual:rsc-router/routes-manifest";
 var VIRTUAL_LOADER_MANIFEST_ID = "virtual:rsc-router/loader-manifest";
-function canRefreshRuntimeDiscovery(state, hasMainRunner) {
-  return state.perRouterManifests.length > 0 || hasMainRunner && !!state.lastDiscoveryError;
+function recordDiscoveryFailure(state, err) {
+  state.lastDiscoveryError = {
+    message: err?.message ?? String(err),
+    at: Date.now()
+  };
+}
+function canRefreshRuntimeDiscovery(state) {
+  return state.perRouterManifests.length > 0 || !!state.lastDiscoveryError;
 }
 function createDiscoveryState(entryPath, opts) {
   return {
@@ -2746,7 +2816,6 @@ ${lazyImports.join(",\n")}
       if (!isBuild) return;
       if (this.environment && this.environment.name !== "rsc") return;
       const fs2 = await import("node:fs/promises");
-      const SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", "dist", "build", "coverage"]);
       async function scanDir(dir) {
         const results = [];
         try {
@@ -2754,7 +2823,7 @@ ${lazyImports.join(",\n")}
           for (const entry of entries) {
             const fullPath = path4.join(dir, entry.name);
             if (entry.isDirectory()) {
-              if (!SKIP_DIRS.has(entry.name) && !entry.name.startsWith(".")) {
+              if (!isSkippedSourceScanDir(entry.name)) {
                 results.push(...await scanDir(fullPath));
               }
             } else if (/\.(ts|tsx|js|jsx)$/.test(entry.name)) {
@@ -4234,7 +4303,7 @@ function transitionWhenHoistPlugin() {
 import { normalizePath as normalizePath4, parseAst as parseAst5 } from "vite";
 import MagicString5 from "magic-string";
 import { createHash as createHash2 } from "node:crypto";
-import { relative } from "node:path";
+import { relative as relative2 } from "node:path";
 import { hasDirective as hasDirective3 } from "@vitejs/plugin-rsc/transforms";
 
 // src/client-urls/hoisted-revalidate.ts
@@ -4379,7 +4448,7 @@ async function hoistClientUrlsRevalidates(code, id, deps) {
     directImport: false
   });
   if (calls.length === 0) return null;
-  const relativeFile = normalizePath4(relative(deps.root, file));
+  const relativeFile = normalizePath4(relative2(deps.root, file));
   const s = new MagicString5(code);
   const used = /* @__PURE__ */ new Map();
   const entries = /* @__PURE__ */ new Map();
@@ -4600,7 +4669,7 @@ import ${JSON.stringify(`${file}?${CLIENT_URLS_REVALIDATE_QUERY}`)};
 // src/vite/plugins/client-ref-dedup.ts
 init_debug();
 import { existsSync, readFileSync } from "node:fs";
-import { isAbsolute, join, normalize, relative as relative2 } from "node:path";
+import { isAbsolute as isAbsolute2, join as join2, normalize, relative as relative3 } from "node:path";
 var debug4 = createRangoDebugger(NS.transform);
 var CLIENT_IN_SERVER_PROXY_PREFIX = "virtual:vite-rsc/client-in-server-package-proxy/";
 var DEDUP_PREFIX = "\0rango:dedup/";
@@ -4633,7 +4702,7 @@ function readPackageMetadata(source, cache3) {
   if (!root) return;
   const cached = cache3.get(root);
   if (cached !== void 0) return cached ?? void 0;
-  const packageJsonPath = join(root, "package.json");
+  const packageJsonPath = join2(root, "package.json");
   if (!existsSync(packageJsonPath)) {
     cache3.set(root, null);
     return;
@@ -4686,8 +4755,8 @@ function getPublicSpecifierCandidates(metadata, packageSpecifier, source) {
     return [];
   }
   const candidates = /* @__PURE__ */ new Set();
-  const sourceRelative = `./${relative2(metadata.root, source).replaceAll("\\", "/")}`;
-  if (sourceRelative.startsWith("./../") || isAbsolute(sourceRelative.slice(2))) {
+  const sourceRelative = `./${relative3(metadata.root, source).replaceAll("\\", "/")}`;
+  if (sourceRelative.startsWith("./../") || isAbsolute2(sourceRelative.slice(2))) {
     return [];
   }
   for (const [exportKey, target] of Object.entries(metadata.exports)) {
@@ -4774,7 +4843,7 @@ function clientRefDedup() {
     configResolved(config) {
       const clientEnv = config.environments?.["client"];
       clientExclude = clientEnv?.optimizeDeps?.exclude ?? config.optimizeDeps?.exclude ?? [];
-      rootImporter = join(config.root, "index.html");
+      rootImporter = join2(config.root, "index.html");
       resolvePackage = config.createResolver({ scan: true });
     },
     buildEnd() {
@@ -4848,7 +4917,7 @@ import { parseAst as parseAst6 } from "vite";
 // src/vite/discovery/build-versions.ts
 import { createHash as createHash4 } from "node:crypto";
 import { isBuiltin } from "node:module";
-import { posix, relative as relative4 } from "node:path";
+import { posix, relative as relative5 } from "node:path";
 
 // src/router-versions.ts
 var DEFAULT_ROUTER_VERSIONS_KEY = "*";
@@ -5443,7 +5512,7 @@ function portableModuleId(id, projectRoot) {
     return path6.slice(nodeModules + 1).replace(PNPM_PEER_SUFFIX, "$1");
   }
   if (isAbsolutePath(path6)) {
-    return relative4(projectRoot, path6).replaceAll("\\", "/");
+    return relative5(projectRoot, path6).replaceAll("\\", "/");
   }
   return withoutWorkingDirectory(path6).replace(
     /([?&][^=&]+=)([^&]+)/g,
@@ -5860,7 +5929,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.23.0",
+  version: "0.24.1",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -6319,69 +6388,6 @@ declare global {
 `;
 }
 
-// src/build/route-types/scan-filter.ts
-import { isAbsolute as isAbsolute2, join as join2, relative as relative5 } from "node:path";
-import { readdirSync } from "node:fs";
-import picomatch from "picomatch";
-var DEFAULT_EXCLUDE_PATTERNS = [
-  "**/__tests__/**",
-  "**/__mocks__/**",
-  "**/dist/**",
-  "**/coverage/**",
-  "**/*.test.{ts,tsx,js,jsx}",
-  "**/*.spec.{ts,tsx,js,jsx}"
-];
-function createScanFilter(root, opts) {
-  const { include, exclude } = opts;
-  const hasInclude = include && include.length > 0;
-  const hasCustomExclude = exclude !== void 0;
-  if (!hasInclude && !hasCustomExclude) return void 0;
-  const effectiveExclude = exclude ?? DEFAULT_EXCLUDE_PATTERNS;
-  const includeMatcher = hasInclude ? picomatch(include) : null;
-  const excludeMatcher = effectiveExclude.length > 0 ? picomatch(effectiveExclude) : null;
-  return (absolutePath) => {
-    const rel = relative5(root, absolutePath);
-    if (excludeMatcher && excludeMatcher(rel)) return false;
-    if (includeMatcher) return includeMatcher(rel);
-    return true;
-  };
-}
-function isUniversallySkippedScanDir(name) {
-  return name === "node_modules" || name === "dist" || name === "coverage" || name.startsWith(".");
-}
-function isInSkippedScanDir(root, absolutePath) {
-  const rel = relative5(root, absolutePath);
-  if (isAbsolute2(rel)) return false;
-  const dirs = rel.split(/[\\/]/).slice(0, -1);
-  if (dirs[0] === "..") return false;
-  return dirs.some(isUniversallySkippedScanDir);
-}
-function findTsFiles(dir, filter) {
-  const results = [];
-  let entries;
-  try {
-    entries = readdirSync(dir, { withFileTypes: true });
-  } catch (err) {
-    console.warn(
-      `[rango] Failed to scan directory ${dir}: ${err.message}`
-    );
-    return results;
-  }
-  for (const entry of entries) {
-    const fullPath = join2(dir, entry.name);
-    if (entry.isDirectory()) {
-      if (isUniversallySkippedScanDir(entry.name) || entry.name === "build") {
-        continue;
-      }
-      results.push(...findTsFiles(fullPath, filter));
-    } else if ((entry.name.endsWith(".ts") || entry.name.endsWith(".tsx") || entry.name.endsWith(".js") || entry.name.endsWith(".jsx")) && !entry.name.includes(".gen.")) {
-      if (filter && !filter(fullPath)) continue;
-      results.push(fullPath);
-    }
-  }
-  return results;
-}
-
 // src/build/route-types/per-module-writer.ts
 import ts4 from "typescript";
 
@@ -8684,7 +8690,7 @@ function insertSegments(node, segments, index, leafBase, paramNames) {
   }
   const segment = segments[index];
   if (segment.type === "static") {
-    if (!node.s) node.s = {};
+    if (!node.s) node.s = /* @__PURE__ */ Object.create(null);
     if (!node.s[segment.value]) node.s[segment.value] = {};
     insertSegments(
       node.s[segment.value],
@@ -8984,6 +8990,13 @@ function jsonParseExpression(value) {
 }
 
 // src/context-var.ts
+function createVar(options) {
+  return {
+    __brand: "context-var",
+    key: /* @__PURE__ */ Symbol(),
+    cache: options?.cache !== false
+  };
+}
 function hasContextVars(variables) {
   return Object.keys(variables).length > 0 || Object.getOwnPropertySymbols(variables).length > 0;
 }
@@ -8996,7 +9009,11 @@ function getNonCacheableKeys(variables) {
   }
   return variables[NON_CACHEABLE_KEYS];
 }
-var FORBIDDEN_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+var FORBIDDEN_KEYS = /* @__PURE__ */ new Set([
+  "__proto__",
+  "constructor",
+  "prototype"
+]);
 function contextSet(variables, keyOrVar, value, options) {
   if (typeof keyOrVar === "string") {
     if (FORBIDDEN_KEYS.has(keyOrVar)) {
@@ -10084,6 +10101,14 @@ function getAppVersion() {
   return currentVersion2;
 }
 
+// src/router/basename.ts
+function prefixBasename(path6, basename2) {
+  if (!basename2 || !path6.startsWith("/") || path6 === basename2 || path6.startsWith(basename2 + "/") || path6.startsWith(basename2 + "?") || path6.startsWith(basename2 + "#")) {
+    return path6;
+  }
+  return path6 === "/" ? basename2 : basename2 + path6;
+}
+
 // src/loader-redirect.tsx
 init_validate_redirect_origin();
 init_redirect_origin();
@@ -10493,13 +10518,10 @@ var Link = forwardRef(function Link2({
 }, ref) {
   const ctx = useContext15(NavigationStoreContext);
   const isExternal = isExternalUrl(to, ctx?.origin);
-  const resolvedTo = useMemo8(() => {
-    if (isExternal) return to;
-    const bn = ctx?.basename;
-    if (!bn || !to.startsWith("/") || to.startsWith(bn + "/") || to === bn)
-      return to;
-    return to === "/" ? bn : bn + to;
-  }, [to, isExternal, ctx?.basename]);
+  const resolvedTo = useMemo8(
+    () => isExternal ? to : prefixBasename(to, ctx?.basename),
+    [to, isExternal, ctx?.basename]
+  );
   const configuredStrategy = prefetch ?? ctx?.defaultPrefetch ?? ENVIRONMENT_DEFAULT_PREFETCH;
   const internalRef = useRef13(null);
   const setRef = useCallback5(
@@ -10756,6 +10778,19 @@ var ALL_USE_ITEM_TYPES = new Set(
 
 // src/server/request-context.ts
 import { AsyncLocalStorage as AsyncLocalStorage5 } from "node:async_hooks";
+
+// src/server/slot-accessors.ts
+function slotAccessor(slot, enumerable) {
+  return {
+    get() {
+      return this[slot]();
+    },
+    enumerable,
+    configurable: true
+  };
+}
+
+// src/server/request-context.ts
 init_cookie_name();
 
 // src/router/segment-resolution/mask-nested.ts
@@ -10823,12 +10858,38 @@ var THEME_READ = {
 // src/router/segment-resolution/prefetch-deferral.ts
 init_prefetch_markers();
 
+// src/cache/document-cache-policy.ts
+init_cookie_name();
+
+// src/server/rewrite-trail.ts
+var REWRITE_TRAIL = createVar();
+
 // src/cache/invalidation-order.ts
 var order = globalThis[/* @__PURE__ */ Symbol.for("rangojs-router:tag-invalidation-order")] ??= { seq: 0, tags: /* @__PURE__ */ new Map(), forgotten: 0 };
 var responseStarts = globalThis[/* @__PURE__ */ Symbol.for("rangojs-router:response-execution-start")] ??= /* @__PURE__ */ new WeakMap();
 
 // src/server/request-context.ts
 var requestContextStorage = new AsyncLocalStorage5();
+var RES_SLOT = /* @__PURE__ */ Symbol("rango.requestContext.res");
+var RENDER_BARRIER_SLOT = /* @__PURE__ */ Symbol(
+  "rango.requestContext.renderBarrier"
+);
+var RES_DESCRIPTOR = {
+  ...slotAccessor(RES_SLOT, true),
+  set(_) {
+    throw new Error(
+      "ctx.res is read-only. Use ctx.header() to set response headers, or cookies() for cookie mutations."
+    );
+  }
+};
+var RENDER_BARRIER_DESCRIPTOR = slotAccessor(
+  RENDER_BARRIER_SLOT,
+  true
+);
+var DERIVED_RENDER_BARRIER_DESCRIPTOR = {
+  ...RENDER_BARRIER_DESCRIPTOR,
+  enumerable: false
+};
 
 // src/route-definition/redirect.ts
 init_redirect_origin();
@@ -13213,12 +13274,18 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
               "acquireBuildEnv",
               () => acquireBuildEnv(s, viteCommand, viteMode)
             );
-            tempRscEnv = (await timed(
+            const temp = await timed(
               debugDiscovery,
               "getOrCreateTempServer",
               () => getOrCreateTempServer()
-            )).env;
-            if (tempRscEnv) {
+            );
+            tempRscEnv = temp.env;
+            if (!tempRscEnv) {
+              recordDiscoveryFailure(
+                s,
+                temp.error ?? "temp runner unavailable for discovery"
+              );
+            } else {
               optimizerHashBefore2 = tempRscEnv.depsOptimizer?.metadata?.browserHash;
               await timed(
                 debugDiscovery,
@@ -13236,6 +13303,7 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
               );
             }
           } catch (err) {
+            recordDiscoveryFailure(s, err);
             emitDiscoveryFailure(
               err,
               optimizerHashBefore2,
@@ -13277,10 +13345,7 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
             () => propagateDiscoveryState(rscEnv)
           );
         } catch (err) {
-          s.lastDiscoveryError = {
-            message: err?.message ?? String(err),
-            at: Date.now()
-          };
+          recordDiscoveryFailure(s, err);
           emitDiscoveryFailure(
             err,
             optimizerHashBefore,
@@ -13685,7 +13750,6 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
         const refreshRuntimeDiscovery = async () => {
           const rscEnv = server.environments?.rsc;
           const hasMainRunner = !!rscEnv?.runner;
-          if (!hasMainRunner && s.perRouterManifests.length === 0) return;
           let previousRouteShape = routeShapeSignature();
           await gate.runRefreshCycle(async () => {
             const hmrStart = performance.now();
@@ -13756,10 +13820,7 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
                 forceCloudflareWorkerReload(rscEnv, expectedEpoch);
               }
             } catch (err) {
-              s.lastDiscoveryError = {
-                message: err?.message ?? String(err),
-                at: Date.now()
-              };
+              recordDiscoveryFailure(s, err);
               const whenError2 = showTransitionWhenError(err);
               if (whenError2) {
                 console.error(whenError2.message);
@@ -13879,7 +13940,7 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
               "watcher: regenerated gen files (%sms)",
               (performance.now() - regenStart).toFixed(1)
             );
-            if (canRefreshRuntimeDiscovery(s, !!rscEnv?.runner)) {
+            if (canRefreshRuntimeDiscovery(s)) {
               refreshRuntimeDiscovery().catch((err) => {
                 console.warn(
                   `[rango] Runtime re-discovery error: ${err.message}`
@@ -14003,7 +14064,7 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
               }
               s.cachedRouterFiles = void 0;
             }
-            if (canRefreshRuntimeDiscovery(s, !!mainRscEnv?.runner)) {
+            if (canRefreshRuntimeDiscovery(s)) {
               gate.noteRouteEvent();
             }
             scheduleRouteRegeneration();

package/package.json

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

package/skills/caching/SKILL.md

@@ -881,10 +881,22 @@ another, request-scoped APIs are guarded inside a cache scope:
 | Response writes: `ctx.headers.set()`, `setCookie()`, `setStatus()`, `onResponse()` | **throws** — response side effects lost on a hit           |
 | `ctx.get(var)` where the var is `{ cache: false }`                                 | **throws** on read                                         |
 | `ctx.theme`, `getRequestContext().theme`                                           | **throws** — the theme is the visitor's cookie             |
+| `ctx.rewrittenFrom` (any ctx, `getRequestContext().rewrittenFrom`)                 | **throws** — the visitor's URL of a rewritten request      |
 | `ctx.set(var, value)` for a cacheable var                                          | allowed (children are cached too)                          |
 | Any of the above **inside a registered loader** (`loader(...)`)                    | **allowed** — loaders always run fresh                     |
 | Any read in the boundary's own `key()`, `keyGenerator`, `condition()` or `tags()`  | **allowed** — it picks or labels the entry, never rendered |
 
+`ctx.rewrittenFrom` (the visitor's URL when middleware rewrote the request,
+`/middleware` → "Rewrite") throws on every read inside a `cache()` boundary
+or a `"use cache"` function, on a request nothing rewrote too, like
+`cookies()`: the entry would hold whichever URL the first caller came from,
+and a read that worked only on direct visits would break the first time a
+rewritten request reached it. A PPR shell capture and a render the document
+cache stores read it as `undefined` instead of throwing: those renders are
+the target page as a direct visit renders it, and the rewritten visitor's
+own render (outside them) still sees its URL. A response route under
+`cache()` whose handler read it is not stored.
+
 A loader body invoked from a handler with `await ctx.use(Loader)` may read
 `cookies()`/`headers()`/`ctx.request.headers`, but its response writes still throw: on a hit the
 handler is skipped, so that loader never runs.

package/skills/catalog.json

@@ -143,7 +143,7 @@
     },
     {
       "name": "middleware",
-      "description": "Define global (router.use) and route (middleware()) middleware in @rangojs/router — auth gates, logging, response headers, context variables, redirects. Use when gating routes behind auth checks, logging requests, setting headers or ctx variables before a handler runs, or deciding whether middleware wraps server actions.",
+      "description": "Define global (router.use) and route (middleware()) middleware in @rangojs/router — auth gates, logging, response headers, context variables, redirects, rewrites (throw rewrite() renders another route at the same URL). Use when gating routes behind auth checks, logging requests, setting headers or ctx variables before a handler runs, showing a maintenance page at the visitor's URL, or deciding whether middleware wraps server actions.",
       "argumentHint": "[middleware-name]",
       "path": "skills/middleware/SKILL.md"
     },

package/skills/client-urls/SKILL.md

@@ -287,6 +287,80 @@ Two scars worth copying:
   actions (`isAction(CartActions)`) while product/related loaders hold —
   three freshness outcomes in a single commit, decided per loader.
 
+## After an action: what the server decides
+
+The browser sends the action with the ids of the segments the page holds.
+Everything after that is decided on the server, while it handles that request:
+
+- **The action** runs there, and its return value is what the call resolves
+  with (`await action()`, `useActionState`).
+- **Which loaders rerun.** Each group loader's own `revalidate()` answers, with
+  the action's `actionResult` and `formData` (above). A loader that holds keeps
+  the data the page shows.
+- **The browser's caches.** When the response arrives the browser marks its
+  history cache stale and drops its prefetches, unless the action called
+  `keepClientCache()` (`/server-actions` → "Client Cache After an Action").
+- **A loader that fails on its rerun** reaches your `onError` on the server and
+  the page as an error, below.
+
+A form's React state survives an action's revalidation in a group, as on a
+`urls()` route: the commit renders into the mounted page instead of remounting
+it, so a controlled input keeps what the user typed.
+
+### A loader that fails on its rerun
+
+The action has already run when its loaders rerun, so a loader that throws
+there does not undo it. Where the error lands decides what the user sees:
+
+| The route                                                  | Called directly (`await action()`)                                                                                                                                                             | From `<form action>`, `useActionState` or `useTransition`                                                                                             |
+| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A group route, or a `urls()` route without `loading()`     | The call rejects with the loader's error (`"An error occurred"` in a build), although the action returned. Nothing of that revalidation commits: the page keeps its data and its React state.  | React hands the rejection to the nearest React error boundary above the form. With none of yours, the router's root error boundary replaces the page. |
+| A `urls()` route with `loading()`                          | The call resolves with the action's result. The commit renders, the loader's read throws, and the nearest React error boundary catches it; with none of yours, the root one replaces the page. | The same.                                                                                                                                             |
+| Under an `errorBoundary()` (for a group, around the mount) | Its fallback replaces the route: the page and its form state unmount.                                                                                                                          | The same.                                                                                                                                             |
+
+A group route's `loading()` does not change the first row. For a failure the
+user can retry (a flaky upstream, a rate limit), return it as data instead of
+throwing, and render it where the data goes:
+
+```tsx
+// stock.loader.ts
+export const StockLoader = createLoader(async (ctx) => {
+  try {
+    return { ok: true as const, stock: await inventory.count(ctx.params.sku) };
+  } catch {
+    return { ok: false as const, reason: "Stock is unavailable. Try again." };
+  }
+});
+
+// in the group's "use client" module
+function Stock() {
+  const { data } = useLoader(StockLoader);
+  return data.ok ? (
+    <p>{data.stock} in stock</p>
+  ) : (
+    <p role="status">{data.reason}</p>
+  );
+}
+```
+
+The action resolves with its result, the page and its form state stay, and the
+next action or navigation that reruns the loader replaces the message. Keep
+throwing for a failure that should stop the page, with an `errorBoundary()`
+around the mount for it.
+
+A failure returned as data is an ordinary value, so whatever stores the
+loader's value stores it too: a `cache()` on the loader serves it for its TTL,
+a `ppr` shell bakes an `ssr: false` loader's value, and a prerender stores it
+at build time. A thrown error is never stored (a stale entry keeps serving).
+To cache the expensive part, cache the call the loader makes (`"use cache"` on
+that function: a call that throws stores nothing) and turn the throw into
+data in a loader that is not cached itself.
+
+Pinned by dev + production e2e in the router repository (a group, its `urls()`
+twin, each with and without `loading()`, and the group under an
+`errorBoundary()`), and by a `serveShellRequest({ action })` test of the
+response.
+
 ## Loaders are full citizens: signals and handles
 
 Everything a DSL loader can do in the server tree works here — the loader body
@@ -373,6 +447,16 @@ need it, not the route.
 
 Pinned end to end by dev + production e2e in the router repository.
 
+**Without JavaScript.** A boundary that is not complete at the first flush
+ships its fallback and swaps the content in with a script, which a browser
+without JavaScript never runs. That includes a client component a loader's
+answer draws under an inline `<Suspense>`: a fast loader's answer usually
+makes the first flush, and `ssr: false` guarantees the loader's data does. It
+does not cover the client component's module: the first document a build's
+fresh server renders can still be waiting for it. The dev server matches a
+build here: when the shell is ready, it waits for the client components the
+payload has named and that are still loading, and for nothing else.
+
 ## `prefetch: false` — keep a loader out of prefetches
 
 A `<Link>` prefetch of a group route runs its loaders. Flag the expensive one
@@ -442,7 +526,8 @@ a hard load of the target URL renders the full route.
   reconciles instead of remounting. The canonical commit runs in a
   `startTransition` when no new segments mount, and the wrapping layout sees
   `useOutlet().pending === true` for the held window; a route-level
-  `loading()` does not re-flash there. `transition()` is not needed for the
+  `loading()` does not re-flash there. Across different routes, a `layout()`
+  keeps its instance while the navigation stays under it. `transition()` is not needed for the
   hold; it adds the view-transition animation. Inline `<Suspense>` above each
   `useLoader` read is still the finer-grained tool when different reads on
   one route should wait independently.

package/skills/hooks/SKILL.md

@@ -112,12 +112,17 @@ cannot mismatch its server HTML.
 - Navigation state, params and action state: the component shows the live
   value right after it hydrates.
 - Handle data a loader pushed late, and the entry's location state: both wait
-  until the whole document has streamed and been revealed. Location state
-  lands in the barrier commit (one transition that also hydrates every
-  boundary still dehydrated); handle data lands in the release notification
-  right after that commit. `useLocationState` readers re-render when the
-  entry's state object changes; `useHandle` readers when their selection
-  changes.
+  until the whole document has streamed and been revealed, and every boundary
+  has hydrated, including any boundary still suspended on the client (a lazy
+  chunk, a deferred-hydration gate; that wait has no upper bound). Then
+  location state lands in a transition and handle data in the release
+  notification. `useLocationState` readers re-render when the entry's
+  state object changes; `useHandle` readers when their selection changes.
+- State set before then by a commit that renders no new page (a shallow
+  navigation with `revalidate: false`, Back/Forward or a revalidation that
+  keeps every segment, an action's location state) waits the same way: readers
+  keep `undefined` until every boundary has hydrated, then show the latest
+  entry's state.
 - A navigation that commits before then mounts its page with the live values
   from its first render. A boundary of the document that persists across that
   navigation and has not hydrated yet then hydrates against the live values;

package/skills/hooks/data.md

@@ -146,7 +146,9 @@ clears the shared error.
 **`load()` calls that stay local** (no broadcast, per-hook state, same
 semantics as the old per-component `useState`):
 
-- `load({ params: { ... } })` — explicit params.
+- `load({ params: { ... } })` — explicit params. They are string values; a
+  `__proto__`, `constructor` or `prototype` key or a non-string value is
+  rejected and `load()` fails with `Invalid loader params`.
 - `load({ method: "POST", body })` — mutations.
 - Any `load()` on a `useFetchLoader(loader)` whose loader is **not**
   registered on the current route. Two unrelated components calling