@rangojs/router 0.0.0-experimental.132 → 0.0.0-experimental.133

package/dist/vite/index.js

@@ -165,7 +165,9 @@ function countArgs(code, startPos, endPos) {
   while (i < endPos) {
     const skipped = skipStringOrComment(code, i);
     if (skipped > i) {
-      hasContent = true;
+      const ch = code[i];
+      const isComment = ch === "/" && i + 1 < code.length && (code[i + 1] === "/" || code[i + 1] === "*");
+      if (!isComment) hasContent = true;
       i = skipped;
       continue;
     }
@@ -530,10 +532,10 @@ import path4 from "node:path";
 function isDirectivePrologueStatement(node) {
   return node?.type === "ExpressionStatement" && typeof node.directive === "string";
 }
-function findImportInsertionPos(code, parseAst4) {
+function findImportInsertionPos(code, parseAst5) {
   let program;
   try {
-    program = parseAst4(code, { lang: "tsx" });
+    program = parseAst5(code, { lang: "tsx" });
   } catch {
     return 0;
   }
@@ -570,10 +572,10 @@ function walkNode(node, parent, ancestors, enter) {
   }
   ancestors.pop();
 }
-function findHandlerCalls(code, fnName, parseAst4) {
+function findHandlerCalls(code, fnName, parseAst5) {
   let program;
   try {
-    program = parseAst4(code, { lang: "tsx" });
+    program = parseAst5(code, { lang: "tsx" });
   } catch {
     return [];
   }
@@ -645,18 +647,18 @@ function getImportedLocalNamesFromProgram(program, importedName) {
   }
   return localNames;
 }
-function getImportedLocalNames(code, importedName, parseAst4) {
+function getImportedLocalNames(code, importedName, parseAst5) {
   try {
-    const program = parseAst4(code, { lang: "tsx" });
+    const program = parseAst5(code, { lang: "tsx" });
     return getImportedLocalNamesFromProgram(program, importedName);
   } catch {
     return /* @__PURE__ */ new Set();
   }
 }
-function extractImportDeclarations(code, parseAst4) {
+function extractImportDeclarations(code, parseAst5) {
   let program;
   try {
-    program = parseAst4(code, { lang: "tsx" });
+    program = parseAst5(code, { lang: "tsx" });
   } catch {
     return [];
   }
@@ -680,13 +682,18 @@ function isInertExpression(node) {
         (e) => e === null || isInertExpression(e)
       );
     case "ObjectExpression":
-      return (node.properties ?? []).every(
-        (p) => p.type === "Property" && (!p.computed || isInertExpression(p.key)) && isInertExpression(p.value)
-      );
+      return (node.properties ?? []).every((p) => {
+        if (p.type === "SpreadElement" || p.type === "RestElement") {
+          return isInertExpression(p.argument);
+        }
+        return p.type === "Property" && (!p.computed || isInertExpression(p.key)) && isInertExpression(p.value);
+      });
     case "UnaryExpression":
       return isInertExpression(node.argument);
     case "BinaryExpression":
       return isInertExpression(node.left) && isInertExpression(node.right);
+    case "LogicalExpression":
+      return isInertExpression(node.left) && isInertExpression(node.right);
     case "ConditionalExpression":
       return isInertExpression(node.test) && isInertExpression(node.consequent) && isInertExpression(node.alternate);
     case "SpreadElement":
@@ -708,10 +715,10 @@ function isSafeVariableDeclaration(node, handlerNames) {
     (d) => isSafeDeclaratorInit(d.init) && !(d.init?.type === "CallExpression" && d.init.callee?.type === "Identifier" && handlerNames.has(d.init.callee.name))
   );
 }
-function extractModuleLevelDeclarations(code, parseAst4, handlerNames) {
+function extractModuleLevelDeclarations(code, parseAst5, handlerNames) {
   let program;
   try {
-    program = parseAst4(code, { lang: "tsx" });
+    program = parseAst5(code, { lang: "tsx" });
   } catch {
     return [];
   }
@@ -742,17 +749,17 @@ function extractModuleLevelDeclarations(code, parseAst4, handlerNames) {
   }
   return declarations;
 }
-function transformInlineHandlers(fnName, virtualPrefix, s, code, filePath, virtualRegistry, moduleId, parseAst4) {
-  const sites = findHandlerCalls(code, fnName, parseAst4);
+function transformInlineHandlers(fnName, virtualPrefix, s, code, filePath, virtualRegistry, moduleId, parseAst5) {
+  const sites = findHandlerCalls(code, fnName, parseAst5);
   const inlineSites = sites.filter((site) => site.exportInfo === null);
   if (inlineSites.length === 0) return false;
-  const imports = extractImportDeclarations(code, parseAst4);
-  const staticNames = getImportedLocalNames(code, "Static", parseAst4);
-  const prerenderNames = getImportedLocalNames(code, "Prerender", parseAst4);
+  const imports = extractImportDeclarations(code, parseAst5);
+  const staticNames = getImportedLocalNames(code, "Static", parseAst5);
+  const prerenderNames = getImportedLocalNames(code, "Prerender", parseAst5);
   const handlerNames = /* @__PURE__ */ new Set([...staticNames, ...prerenderNames]);
   const declarations = extractModuleLevelDeclarations(
     code,
-    parseAst4,
+    parseAst5,
     handlerNames
   );
   const importStatements = [];
@@ -775,7 +782,7 @@ function transformInlineHandlers(fnName, virtualPrefix, s, code, filePath, virtu
   }
   if (importStatements.length > 0) {
     const importBlock = importStatements.join("\n") + "\n";
-    const insertionPos = findImportInsertionPos(code, parseAst4);
+    const insertionPos = findImportInsertionPos(code, parseAst5);
     if (insertionPos === 0) {
       s.prepend(importBlock);
     } else {
@@ -808,25 +815,55 @@ function isLineTerminator(ch) {
   const c = ch.charCodeAt(0);
   return c === 10 || c === 13 || c === 8232 || c === 8233;
 }
+var REGEX_PRECEDING_KEYWORDS = /* @__PURE__ */ new Set([
+  "return",
+  "typeof",
+  "instanceof",
+  "in",
+  "of",
+  "new",
+  "delete",
+  "void",
+  "do",
+  "else",
+  "yield",
+  "await",
+  "case",
+  "throw"
+]);
+function isRegexPositionAt(code, slashPos, prevChar) {
+  if (prevChar === void 0) return true;
+  if (prevChar === ")" || prevChar === "]" || prevChar === "}") return false;
+  if (!/[\w$]/.test(prevChar)) return true;
+  let k = slashPos - 1;
+  while (k >= 0 && /\s/.test(code[k])) k--;
+  const wordEnd = k + 1;
+  while (k >= 0 && /[\w$]/.test(code[k])) k--;
+  return REGEX_PRECEDING_KEYWORDS.has(code.slice(k + 1, wordEnd));
+}
 function makeCodeClassifier(code) {
   const n = code.length;
   let i = 0;
   let skipStart = -1;
   let skipEnd = -1;
+  let lastSig;
   return (q) => {
     if (q >= skipStart && q < skipEnd) return false;
     while (i < n && i <= q) {
       const c = code[i];
       const d = i + 1 < n ? code[i + 1] : "";
       let end = -1;
+      let transparent = false;
       if (c === "/" && d === "/") {
         let j = i + 2;
         while (j < n && !isLineTerminator(code[j])) j++;
         end = j;
+        transparent = true;
       } else if (c === "/" && d === "*") {
         let j = i + 2;
         while (j < n && !(code[j] === "*" && code[j + 1] === "/")) j++;
         end = Math.min(n, j + 2);
+        transparent = true;
       } else if (c === '"' || c === "'" || c === "`") {
         let j = i + 1;
         while (j < n) {
@@ -841,6 +878,29 @@ function makeCodeClassifier(code) {
           j++;
         }
         end = j;
+      } else if (c === "/" && d !== "/" && d !== "*" && isRegexPositionAt(code, i, lastSig)) {
+        let j = i + 1;
+        let inClass = false;
+        let closed = false;
+        while (j < n && !isLineTerminator(code[j])) {
+          const r = code[j];
+          if (r === "\\") {
+            j += 2;
+            continue;
+          }
+          if (r === "[") inClass = true;
+          else if (r === "]") inClass = false;
+          else if (r === "/" && !inClass) {
+            j++;
+            closed = true;
+            break;
+          }
+          j++;
+        }
+        if (closed) {
+          while (j < n && /[a-z]/.test(code[j])) j++;
+          end = j;
+        }
       }
       if (end >= 0) {
         if (q < end) {
@@ -849,7 +909,9 @@ function makeCodeClassifier(code) {
           return false;
         }
         i = end;
+        if (!transparent) lastSig = "x";
       } else {
+        if (!/\s/.test(c)) lastSig = c;
         i++;
       }
     }
@@ -1134,11 +1196,13 @@ function generateClientLoaderStubs(bindings, code, filePath, isBuild) {
   if (!isExportOnlyFile(code, bindings)) return null;
   const lines = [];
   for (const binding of bindings) {
-    for (const name of binding.exportNames) {
-      const loaderId = makeStubId(filePath, name, isBuild);
-      lines.push(
-        `export const ${name} = { __brand: "loader", $$id: "${loaderId}" };`
-      );
+    const primaryName = binding.exportNames[0];
+    const loaderId = makeStubId(filePath, primaryName, isBuild);
+    lines.push(
+      `export const ${primaryName} = { __brand: "loader", $$id: "${loaderId}" };`
+    );
+    for (const alias of binding.exportNames.slice(1)) {
+      lines.push(`export const ${alias} = ${primaryName};`);
     }
   }
   return { code: lines.join("\n") + "\n" };
@@ -1159,22 +1223,13 @@ ${binding.localName}.$$id = "${loaderId}";`;
 }
 
 // src/vite/plugins/expose-ids/handler-transform.ts
-function analyzeCreateHandleArgs(code, startPos, endPos) {
-  const content = code.slice(startPos, endPos).trim();
-  return { hasArgs: content.length > 0 };
-}
-function transformHandles(bindings, s, code, filePath, isBuild) {
+function transformHandles(bindings, s, filePath, isBuild) {
   let hasChanges = false;
   for (const binding of bindings) {
     const exportName = binding.exportNames[0];
-    const args = analyzeCreateHandleArgs(
-      code,
-      binding.callOpenParenPos + 1,
-      binding.callCloseParenPos
-    );
     const handleId = makeStubId(filePath, exportName, isBuild);
     let paramInjection;
-    if (!args.hasArgs) {
+    if (binding.argCount === 0) {
       paramInjection = `undefined, "${handleId}"`;
     } else {
       paramInjection = `, "${handleId}"`;
@@ -1287,7 +1342,7 @@ function transformRouter(code, filePath, routerFnNames, absolutePath, warn) {
     if (parenPos === -1) continue;
     const closeParen = findMatchingParen(code, parenPos + 1);
     const callArgs = code.slice(parenPos + 1, closeParen);
-    if (callArgs.includes("$$id")) continue;
+    if (callArgs.includes(`$$routeNames: ${routeNamesVar}`)) continue;
     const sourceFilePath = absolutePath ?? filePath;
     const lineNumber = code.slice(0, callStart).split("\n").length;
     const hash = createHash("sha256").update(`${filePath}:${lineNumber}`).digest("hex").slice(0, 8);
@@ -1831,7 +1886,6 @@ ${lazyImports.join(",\n")}
           changed = transformHandles(
             getBindings(code, fnNames),
             s,
-            code,
             filePath,
             isBuild
           ) || changed;
@@ -1908,8 +1962,8 @@ function useCacheTransform() {
         } = rscTransforms;
         let ast;
         try {
-          const { parseAst: parseAst4 } = await import("vite");
-          ast = parseAst4(code, { lang: "tsx" });
+          const { parseAst: parseAst5 } = await import("vite");
+          ast = parseAst5(code, { lang: "tsx" });
         } catch {
           return;
         }
@@ -2141,11 +2195,16 @@ async function initializeApp() {
     createTemporaryReferenceSet,
   };
 
-  await initBrowserApp({ rscStream, deps });
+  // initBrowserApp resolves the initial payload and returns the browser app
+  // context, including strictMode (default true) from createRouter. StrictMode
+  // is the default; createRouter({ strictMode: false }) ships the opt-out in the
+  // payload metadata. StrictMode emits no DOM, so toggling never changes markup.
+  const { strictMode } = await initBrowserApp({ rscStream, deps });
 
+  const app = createElement(Rango);
   hydrateRoot(
     document,
-    createElement(StrictMode, null, createElement(Rango))
+    strictMode === false ? app : createElement(StrictMode, null, app)
   );
 }
 
@@ -2198,6 +2257,11 @@ export default function handler(request, env) {
     _handler = createRSCHandler({
       router,
       version: VERSION,
+      // Forward the router's CSP nonce provider. createRSCHandler reads the
+      // provider only from options.nonce; without this, createRouter({ nonce })
+      // is silently dropped on the Node preset (the Cloudflare path wires it via
+      // router.fetch). router.nonce is undefined when unconfigured, a safe no-op.
+      nonce: router.nonce,
       deps: {
         renderToReadableStream,
         decodeReply,
@@ -2232,7 +2296,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.132",
+  version: "0.0.0-experimental.133",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -2785,7 +2849,7 @@ function extractIncludesWithDiagnostics(code, sourceFileArg) {
   return { resolved, unresolvable };
 }
 function resolveImportedVariable(code, localName) {
-  const importRegex = /import\s*\{([^}]+)\}\s*from\s*["']([^"']+)["']/g;
+  const importRegex = /import\s*(?:[\w$]+\s*,\s*)?\{([^}]+)\}\s*from\s*["']([^"']+)["']/g;
   let match;
   while ((match = importRegex.exec(code)) !== null) {
     const imports = match[1];
@@ -3313,7 +3377,28 @@ function writeCombinedRouteTypes(root, knownRouterFiles, opts) {
 }
 
 // src/vite/plugins/version-plugin.ts
+import { parseAst as parseAst4 } from "vite";
+
+// src/vite/utils/directive-prologue.ts
 import { parseAst as parseAst3 } from "vite";
+function hasUseClientDirective(source) {
+  let program;
+  try {
+    program = parseAst3(source, { lang: "tsx" });
+  } catch {
+    return false;
+  }
+  for (const node of program.body ?? []) {
+    if (node?.type === "ExpressionStatement" && node.expression?.type === "Literal" && typeof node.expression.value === "string") {
+      if (node.expression.value === "use client") return true;
+      continue;
+    }
+    break;
+  }
+  return false;
+}
+
+// src/vite/plugins/version-plugin.ts
 function isCodeModule(id) {
   return /\.(tsx?|jsx?)($|\?)/.test(id);
 }
@@ -3321,23 +3406,13 @@ function normalizeModuleId(id) {
   return id.split("?", 1)[0];
 }
 function getClientModuleSignature(source) {
+  if (!hasUseClientDirective(source)) return void 0;
   let program;
   try {
-    program = parseAst3(source, { lang: "tsx" });
+    program = parseAst4(source, { lang: "tsx" });
   } catch {
     return void 0;
   }
-  let isUseClient = false;
-  for (const node of program.body ?? []) {
-    if (node?.type === "ExpressionStatement" && node.expression?.type === "Literal" && typeof node.expression.value === "string") {
-      if (node.expression.value === "use client") {
-        isUseClient = true;
-      }
-      continue;
-    }
-    break;
-  }
-  if (!isUseClient) return void 0;
   const exports = /* @__PURE__ */ new Set();
   let hasDefault = false;
   let hasExportAll = false;
@@ -3890,13 +3965,17 @@ function createVersionInjectorPlugin(rscEntryPath) {
 // src/vite/plugins/cjs-to-esm.ts
 var debug8 = createRangoDebugger(NS.transform);
 function createCjsToEsmPlugin() {
+  let isProduction = false;
   return {
     name: "@rangojs/router:cjs-to-esm",
     enforce: "pre",
+    configResolved(config) {
+      isProduction = config.isProduction;
+    },
     transform(code, id) {
       const cleanId = id.split("?")[0].replaceAll("\\", "/");
       if (cleanId.includes("vendor/react-server-dom/client.browser.js")) {
-        const isProd = process.env.NODE_ENV === "production";
+        const isProd = isProduction;
         const cjsFile = isProd ? "./cjs/react-server-dom-webpack-client.browser.production.js" : "./cjs/react-server-dom-webpack-client.browser.development.js";
         debug8?.("cjs-to-esm entry redirect %s", id);
         return {
@@ -4353,6 +4432,9 @@ function sortSuffixParams(node) {
       sorted[suffix] = node.xp[suffix];
     }
     node.xp = sorted;
+    for (const child of Object.values(node.xp)) {
+      sortSuffixParams(child.c);
+    }
   }
   if (node.s) {
     for (const child of Object.values(node.s)) {
@@ -4362,11 +4444,6 @@ function sortSuffixParams(node) {
   if (node.p) {
     sortSuffixParams(node.p.c);
   }
-  if (node.xp) {
-    for (const child of Object.values(node.xp)) {
-      sortSuffixParams(child.c);
-    }
-  }
 }
 function buildPerRouterTrie(manifest) {
   const ancestry = manifest._routeAncestry;
@@ -4405,12 +4482,15 @@ function insertRoute(node, segments, index, leaf) {
   };
   insertSegments(node, segments, index, leafBase, []);
 }
+function toVariant(leaf, responseType) {
+  return leaf.pa ? { routeKey: leaf.n, responseType, pa: leaf.pa } : { routeKey: leaf.n, responseType };
+}
 function mergeLeaves(existing, leaf) {
   if (!existing) return leaf;
   if (existing.rt && leaf.rt) {
     const merged = leaf;
     merged.nv = existing.nv || [];
-    merged.nv.push({ routeKey: existing.n, responseType: existing.rt });
+    merged.nv.push(toVariant(existing, existing.rt));
     return merged;
   }
   if (leaf.rt && !existing.rt) {
@@ -4418,13 +4498,13 @@ function mergeLeaves(existing, leaf) {
       existing.nv = [];
       existing.rf = true;
     }
-    existing.nv.push({ routeKey: leaf.n, responseType: leaf.rt });
+    existing.nv.push(toVariant(leaf, leaf.rt));
     return existing;
   }
   if (!leaf.rt && existing.rt) {
     if (!leaf.nv) leaf.nv = [];
     if (existing.nv) leaf.nv.push(...existing.nv);
-    leaf.nv.push({ routeKey: existing.n, responseType: existing.rt });
+    leaf.nv.push(toVariant(existing, existing.rt));
     return leaf;
   }
   return leaf;
@@ -4621,13 +4701,24 @@ async function runWithConcurrency(items, concurrency, fn) {
     return;
   }
   let nextIndex = 0;
+  let firstError;
+  let failed = false;
   async function worker() {
-    while (nextIndex < items.length) {
+    while (nextIndex < items.length && !failed) {
       const idx = nextIndex++;
-      await fn(items[idx]);
+      try {
+        await fn(items[idx]);
+      } catch (err) {
+        if (!failed) {
+          failed = true;
+          firstError = err;
+        }
+        return;
+      }
     }
   }
   await Promise.all(Array.from({ length: limit }, () => worker()));
+  if (failed) throw firstError;
 }
 function groupByConcurrency(entries) {
   const map = /* @__PURE__ */ new Map();
@@ -7151,6 +7242,12 @@ ${list}`);
                     "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge"
                   )
                 ],
+                // Vite 8 does not propagate the top-level optimizeDeps.exclude
+                // (set in config()) to non-client envs, so the rsc env must set
+                // it explicitly — mirroring the node ssr env and the cloudflare
+                // rsc env. Without it a strict-pnpm npm-installed app can try to
+                // pre-bundle the router's own subpath entries and fail.
+                exclude: excludeDeps,
                 rolldownOptions: sharedRolldownOptions
               }
             }
@@ -7193,8 +7290,7 @@ ${list}`);
         return;
       try {
         const source = readFileSync7(file, "utf-8");
-        const trimmed = source.trimStart();
-        if (trimmed.startsWith('"use client"') || trimmed.startsWith("'use client'")) {
+        if (hasUseClientDirective(source)) {
           return [];
         }
       } catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.132",
+  "version": "0.0.0-experimental.133",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -162,6 +162,17 @@
     "access": "public",
     "tag": "experimental"
   },
+  "scripts": {
+    "build": "pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
+    "prepublishOnly": "pnpm build",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
+    "test": "playwright test",
+    "test:ui": "playwright test --ui",
+    "test:hmr-local": "playwright test --project=dev-warmup --project=hmr-routes --project=hmr-basename --project=hmr-prerender --no-deps --workers=1",
+    "test:unit": "vitest run",
+    "test:unit:watch": "vitest",
+    "test:unit:rsc": "vitest run --config vitest.rsc.config.ts"
+  },
   "dependencies": {
     "@types/debug": "^4.1.12",
     "@vitejs/plugin-rsc": "^0.5.26",
@@ -173,19 +184,19 @@
   },
   "devDependencies": {
     "@playwright/test": "^1.49.1",
+    "@shared/e2e": "workspace:*",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/node": "^24.10.1",
-    "@types/react": "^19.2.7",
-    "@types/react-dom": "^19.2.3",
+    "@types/react": "catalog:",
+    "@types/react-dom": "catalog:",
     "esbuild": "^0.27.0",
     "happy-dom": "^20.10.1",
     "jiti": "^2.6.1",
-    "react": "^19.2.6",
-    "react-dom": "^19.2.6",
+    "react": "catalog:",
+    "react-dom": "catalog:",
     "typescript": "^5.3.0",
-    "vitest": "^4.0.0",
-    "@shared/e2e": "0.0.1"
+    "vitest": "^4.0.0"
   },
   "peerDependencies": {
     "@cloudflare/vite-plugin": "^1.38.0",
@@ -216,15 +227,5 @@
   },
   "engines": {
     "node": "^20.19.0 || >=22.12.0"
-  },
-  "scripts": {
-    "build": "pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
-    "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
-    "test": "playwright test",
-    "test:ui": "playwright test --ui",
-    "test:hmr-local": "playwright test --project=dev-warmup --project=hmr-routes --project=hmr-basename --project=hmr-prerender --no-deps --workers=1",
-    "test:unit": "vitest run",
-    "test:unit:watch": "vitest",
-    "test:unit:rsc": "vitest run --config vitest.rsc.config.ts"
   }
-}
+}

package/skills/breadcrumbs/SKILL.md

@@ -206,7 +206,7 @@ path("/dashboard", (ctx) => {
 ```tsx
 // Client component
 "use client";
-import { useHandle, type Breadcrumbs } from "@rangojs/router/client";
+import { useHandle, Breadcrumbs } from "@rangojs/router/client";
 
 function DashboardNav({ handle }: { handle: typeof Breadcrumbs }) {
   const crumbs = useHandle(handle);

package/skills/bundle-analysis/SKILL.md

@@ -41,7 +41,7 @@ import { join } from "node:path";
 // ... your other imports ...
 
 function analyze(): PluginOption[] {
-  if (!process.env.ANALYZE) return [];
+  if (!process.env.RANGO_ANALYZE) return [];
   return (["client", "ssr", "rsc"] as const).map((envName) => {
     const inner = visualizer({
       filename: join("bundle-stats", `${envName}.html`),
@@ -79,7 +79,7 @@ Add `bundle-stats/` to your `.gitignore`.
 ## Step 3: Build with the analyzer enabled
 
 ```bash
-ANALYZE=1 pnpm exec vite build
+RANGO_ANALYZE=1 pnpm exec vite build
 ```
 
 You'll get three HTML reports in `bundle-stats/`:

package/skills/cache-guide/SKILL.md

@@ -424,7 +424,7 @@ subsequent siblings. Everything below the cache boundary is cached as one unit:
 
 ```typescript
 path("/dashboard", DashboardPage, { name: "dashboard" }, () => [
-  cache("long"),
+  cache({ ttl: 300 }),
   layout(DashboardSidebar, () => [
     parallel("@stats", StatsPanel),
     parallel("@activity", ActivityFeed),
@@ -444,7 +444,7 @@ boundary are not cached and always re-render:
 layout(RootLayout, () => [
   // RootLayout is NOT cached — runs every request
   path("/products/:slug", ProductPage, { name: "product" }, () => [
-    cache("long"),
+    cache({ ttl: 300 }),
     layout(ProductSidebar),
     parallel("@reviews", ReviewsPanel),
     parallel("@related", RelatedProducts),

package/skills/caching/SKILL.md

@@ -153,10 +153,11 @@ Purge-by-tag is available on all plans (since April 2025), subject to per-plan
 rate limits, so the batched single call matters. With a purge wired, `tagCacheTtl`
 becomes a pure read-cost reducer + fallback window.
 
-## Named Profile Shorthand
+## Named Cache Profiles
 
-Use a named cache profile string instead of an options object. The profile must be
-defined in `createRouter({ cacheProfiles })`. Unknown names throw at boot time.
+Define named profiles in `createRouter({ cacheProfiles })` so the same TTL/SWR
+values can be shared across the DSL and `"use cache"` functions without repetition.
+Unknown names throw at boot time.
 
 ```typescript
 // Define profiles in router
@@ -167,19 +168,25 @@ createRouter({
     long: { ttl: 3600, swr: 7200 },
   },
 });
+```
+
+In the DSL, pass the profile's options directly to `cache()`:
 
-// Use by name in urls
+```typescript
 export const urlpatterns = urls(({ path, cache }) => [
-  cache("long", () => [path("/blog", BlogIndex, { name: "blog" })]),
+  cache({ ttl: 3600, swr: 7200 }, () => [
+    path("/blog", BlogIndex, { name: "blog" }),
+  ]),
 
-  // Also works without children (orphan cache boundary)
-  cache("short"),
+  // Orphan cache boundary (covers subsequent siblings)
+  cache({ ttl: 60, swr: 120 }),
   path("/feed", FeedPage, { name: "feed" }),
 ]);
 ```
 
-These profile names are shared with the `"use cache: <name>"` directive. See
-`/use-cache` for function-level caching.
+The DSL `cache()` helper does NOT accept a string profile name — strings are only
+valid in the `"use cache: <name>"` directive inside server functions. See
+`/use-cache` for function-level caching with named profiles.
 
 ## Loader-Level Caching