@rangojs/router 0.0.0-experimental.10

package/CLAUDE.md

@@ -0,0 +1,43 @@
+# @rangojs/router
+
+Run `/rango` first to understand the API. Skills are in `node_modules/@rangojs/router/skills/`.
+
+## Tree-Structure-Critical Files (DO NOT MODIFY without understanding)
+
+The following files control the React tree structure. Changing the tree structure
+(element types, nesting depth, or keys at any position) between SSR, navigation,
+and action renders will cause React to remount components, destroying client state
+like `useActionState`, refs, and local state. This is extremely hard to debug.
+
+**Protected files:**
+
+- `src/segment-system.tsx` - `renderSegments()` builds the React tree from segments.
+  The `loading` property determines tree structure:
+  - `undefined` / `null` -> OutletProvider directly (no boundary)
+  - `false` -> LoaderBoundary + OutletProvider (boundary, no RouteContentWrapper)
+  - truthy (ReactNode) -> LoaderBoundary + OutletProvider + RouteContentWrapper
+
+- `src/route-content-wrapper.tsx` - `LoaderBoundary` and `RouteContentWrapper`.
+  These add structural depth (Suspense boundaries) to the React tree.
+
+- `src/browser/server-action-bridge.ts` - Merges server action segments with
+  cached segments. Must preserve cached `loading` values to prevent tree drift.
+
+- `src/browser/partial-update.ts` - Merges navigation segments with cached segments.
+
+**Rules:**
+
+1. Never change the conditional logic in `renderSegments()` that decides between
+   LoaderBoundary/RouteContentWrapper/OutletProvider without verifying all three
+   render paths (SSR, navigation, action) produce identical tree structures.
+
+2. Never add or remove wrapper elements (Suspense, div, Fragment) around segment
+   content without checking that the same wrappers exist in ALL render paths.
+
+3. When merging segments (action bridge, partial update), always preserve the
+   cached `loading` value if it differs from the server value. The server may
+   return different `loading` values based on `isSSR` context.
+
+4. Run `pnpm --filter @rangojs/router exec playwright test loader-behavior` after
+   any changes to these files. The skipSSR action tests specifically catch tree
+   structure regressions.

package/README.md

@@ -0,0 +1,19 @@
+# @rangojs/router
+
+> **Warning:** This package is experimental and under active development. APIs may change without notice.
+
+Type-safe RSC router with partial rendering support for Vite.
+
+## Installation
+
+```bash
+npm install @rangojs/router@experimental
+```
+
+## Status
+
+This package is in early experimental stages. It is not recommended for production use.
+
+## License
+
+MIT

package/dist/bin/rango.js

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+
+// src/bin/rango.ts
+import { resolve as resolve2 } from "node:path";
+
+// src/build/generate-route-types.ts
+import { readFileSync, writeFileSync, existsSync, readdirSync, unlinkSync } from "node:fs";
+import { join, dirname, resolve, relative, basename as pathBasename } from "node:path";
+import picomatch from "picomatch";
+function extractRoutesFromSource(code) {
+  const routes = [];
+  const regex = /\bpath(?:\.(?:json|text|html|xml|image|stream|any))?\s*\(/g;
+  let match;
+  while ((match = regex.exec(code)) !== null) {
+    const result = parsePathCall(code, match.index + match[0].length);
+    if (result) routes.push(result);
+  }
+  return routes;
+}
+function generatePerModuleTypesSource(routes) {
+  const valid = routes.filter(({ name }) => {
+    if (!name || /["'\\`\n\r]/.test(name)) {
+      console.warn(`[rsc-router] Skipping route with invalid name: ${JSON.stringify(name)}`);
+      return false;
+    }
+    return true;
+  });
+  const deduped = /* @__PURE__ */ new Map();
+  for (const { name, pattern } of valid) {
+    deduped.set(name, pattern);
+  }
+  const sorted = [...deduped.entries()].sort(([a], [b]) => a.localeCompare(b));
+  const body = sorted.map(([name, pattern]) => {
+    const key = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name) ? name : `"${name}"`;
+    return `  ${key}: "${pattern}",`;
+  }).join("\n");
+  return `// Auto-generated by @rangojs/router - do not edit
+export const routes = {
+${body}
+} as const;
+export type routes = typeof routes;
+`;
+}
+function isWhitespace(ch) {
+  return ch === " " || ch === "	" || ch === "\n" || ch === "\r";
+}
+function readString(code, pos) {
+  const quote = code[pos];
+  if (quote !== '"' && quote !== "'") return null;
+  let value = "";
+  pos++;
+  while (pos < code.length) {
+    if (code[pos] === "\\") {
+      pos++;
+      if (pos < code.length) {
+        value += code[pos];
+        pos++;
+      }
+      continue;
+    }
+    if (code[pos] === quote) {
+      return { value, end: pos + 1 };
+    }
+    value += code[pos];
+    pos++;
+  }
+  return null;
+}
+function skipStringLiteral(code, pos) {
+  const quote = code[pos];
+  if (quote === "`") {
+    pos++;
+    while (pos < code.length) {
+      if (code[pos] === "\\") {
+        pos += 2;
+        continue;
+      }
+      if (code[pos] === "`") return pos + 1;
+      if (code[pos] === "$" && pos + 1 < code.length && code[pos + 1] === "{") {
+        pos += 2;
+        let braceDepth = 1;
+        while (pos < code.length && braceDepth > 0) {
+          if (code[pos] === "{") braceDepth++;
+          else if (code[pos] === "}") braceDepth--;
+          else if (code[pos] === "\\") pos++;
+          else if (code[pos] === '"' || code[pos] === "'" || code[pos] === "`") {
+            pos = skipStringLiteral(code, pos);
+            continue;
+          }
+          if (braceDepth > 0) pos++;
+        }
+        continue;
+      }
+      pos++;
+    }
+    return pos;
+  }
+  pos++;
+  while (pos < code.length) {
+    if (code[pos] === "\\") {
+      pos += 2;
+      continue;
+    }
+    if (code[pos] === quote) return pos + 1;
+    pos++;
+  }
+  return pos;
+}
+function matchesNameColon(code, pos) {
+  if (code.slice(pos, pos + 4) !== "name") return false;
+  if (pos > 0 && /\w/.test(code[pos - 1])) return false;
+  const afterName = pos + 4;
+  if (afterName < code.length && /\w/.test(code[afterName])) return false;
+  let checkPos = afterName;
+  while (checkPos < code.length && isWhitespace(code[checkPos])) checkPos++;
+  return code[checkPos] === ":";
+}
+function extractNameValue(code, pos) {
+  pos += 4;
+  while (pos < code.length && isWhitespace(code[pos])) pos++;
+  pos++;
+  while (pos < code.length && isWhitespace(code[pos])) pos++;
+  return readString(code, pos);
+}
+function parsePathCall(code, pos) {
+  while (pos < code.length && isWhitespace(code[pos])) pos++;
+  const patternStr = readString(code, pos);
+  if (!patternStr) return null;
+  const pattern = patternStr.value;
+  pos = patternStr.end;
+  let depth = 1;
+  let name = null;
+  while (pos < code.length && depth > 0) {
+    const ch = code[pos];
+    if (isWhitespace(ch)) {
+      pos++;
+      continue;
+    }
+    if (ch === "/" && pos + 1 < code.length && code[pos + 1] === "/") {
+      pos += 2;
+      while (pos < code.length && code[pos] !== "\n") pos++;
+      continue;
+    }
+    if (ch === "/" && pos + 1 < code.length && code[pos + 1] === "*") {
+      pos += 2;
+      while (pos < code.length - 1 && !(code[pos] === "*" && code[pos + 1] === "/"))
+        pos++;
+      pos += 2;
+      continue;
+    }
+    if (depth === 2 && ch === "n" && matchesNameColon(code, pos)) {
+      const nameResult = extractNameValue(code, pos);
+      if (nameResult) {
+        name = nameResult.value;
+        pos = nameResult.end;
+        continue;
+      }
+    }
+    if (ch === '"' || ch === "`" || ch === "'" && (pos === 0 || !/\w/.test(code[pos - 1]))) {
+      pos = skipStringLiteral(code, pos);
+      continue;
+    }
+    if (ch === "(" || ch === "{" || ch === "[") depth++;
+    else if (ch === ")" || ch === "}" || ch === "]") depth--;
+    pos++;
+  }
+  if (name === null) return null;
+  return { name, pattern };
+}
+function findTsFiles(dir, filter) {
+  const results = [];
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch (err) {
+    console.warn(`[rsc-router] Failed to scan directory ${dir}: ${err.message}`);
+    return results;
+  }
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+      results.push(...findTsFiles(fullPath, filter));
+    } else if ((entry.name.endsWith(".ts") || entry.name.endsWith(".tsx")) && !entry.name.includes(".gen.")) {
+      if (filter && !filter(fullPath)) continue;
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+function writePerModuleRouteTypesForFile(filePath) {
+  try {
+    const source = readFileSync(filePath, "utf-8");
+    if (!source.includes("urls(")) return;
+    const routes = extractRoutesFromSource(source);
+    if (routes.length === 0) return;
+    const genPath = filePath.replace(/\.(tsx?)$/, ".gen.ts");
+    const genSource = generatePerModuleTypesSource(routes);
+    const existing = existsSync(genPath) ? readFileSync(genPath, "utf-8") : null;
+    if (existing !== genSource) {
+      writeFileSync(genPath, genSource);
+      console.log(`[rsc-router] Generated route types -> ${genPath}`);
+    }
+  } catch (err) {
+    console.warn(`[rsc-router] Failed to generate route types for ${filePath}: ${err.message}`);
+  }
+}
+
+// src/bin/rango.ts
+var [command, ...args] = process.argv.slice(2);
+if (command === "extract-names") {
+  const dir = args[0] ?? "./src";
+  const resolvedDir = resolve2(dir);
+  console.log(`[rango] Scanning ${resolvedDir} for url modules...`);
+  const files = findTsFiles(resolvedDir);
+  for (const filePath of files) {
+    writePerModuleRouteTypesForFile(filePath);
+  }
+  console.log(`[rango] Scanned ${files.length} file(s)`);
+  process.exit(0);
+} else {
+  console.log(`Usage: rango <command>
+
+Commands:
+  extract-names [dir]  Extract route names from url modules (default: ./src)`);
+  process.exit(command ? 1 : 0);
+}