@rangojs/router 0.0.0-experimental.13 → 0.0.0-experimental.135c6902

package/src/vite/{ast-handler-extract.ts → utils/ast-handler-extract.ts}

@@ -1,5 +1,5 @@
 import type MagicString from "magic-string";
-import { hashInlineId, buildExportMap } from "./expose-id-utils.ts";
+import { hashInlineId, buildExportMap } from "../plugins/expose-id-utils.js";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -27,14 +27,14 @@ export interface HandlerCallSite {
 export interface VirtualHandlerEntry {
   originalModuleId: string;
   imports: string[];
+  declarations: string[];
   handlerCode: string;
   exportName: string;
 }
 
 function isDirectivePrologueStatement(node: any): boolean {
   return (
-    node?.type === "ExpressionStatement" &&
-    typeof node.directive === "string"
+    node?.type === "ExpressionStatement" && typeof node.directive === "string"
   );
 }
 
@@ -99,7 +99,11 @@ function walkNode(
           walkNode(item, node, ancestors, enter);
         }
       }
-    } else if (child && typeof child === "object" && typeof child.type === "string") {
+    } else if (
+      child &&
+      typeof child === "object" &&
+      typeof child.type === "string"
+    ) {
       walkNode(child, node, ancestors, enter);
     }
   }
@@ -158,8 +162,10 @@ export function findHandlerCalls(
 
     if (parent?.type === "VariableDeclarator" && parent.init === node) {
       // ancestors: [..., ExportNamedDecl, VarDecl, VarDeclarator, CallExpr]
-      const grandParent = ancestors.length >= 3 ? ancestors[ancestors.length - 3] : null;
-      const greatGrandParent = ancestors.length >= 4 ? ancestors[ancestors.length - 4] : null;
+      const grandParent =
+        ancestors.length >= 3 ? ancestors[ancestors.length - 3] : null;
+      const greatGrandParent =
+        ancestors.length >= 4 ? ancestors[ancestors.length - 4] : null;
 
       if (
         grandParent?.type === "VariableDeclaration" &&
@@ -264,6 +270,162 @@ export function extractImportDeclarations(
   return imports;
 }
 
+/**
+ * Check if an expression AST subtree is "inert" -- safe to evaluate eagerly
+ * without referencing import bindings. Inert expressions contain only literals,
+ * arrays/objects of inert values, template literals with inert expressions,
+ * and unary/binary operators on inert operands.
+ *
+ * Function/arrow expressions are NOT inert (they're lazy -- handled separately).
+ * Identifiers and member expressions are NOT inert (may reference imports).
+ *
+ * This check prevents TDZ errors when declarations are moved to virtual
+ * modules that end up in separate Rollup chunks with circular dependencies.
+ */
+function isInertExpression(node: any): boolean {
+  if (!node) return false;
+  switch (node.type) {
+    case "Literal":
+      return true;
+    case "TemplateLiteral":
+      return (node.expressions ?? []).every((e: any) => isInertExpression(e));
+    case "ArrayExpression":
+      return (node.elements ?? []).every(
+        (e: any) => e === null || isInertExpression(e),
+      );
+    case "ObjectExpression":
+      return (node.properties ?? []).every(
+        (p: any) =>
+          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 "ConditionalExpression":
+      return (
+        isInertExpression(node.test) &&
+        isInertExpression(node.consequent) &&
+        isInertExpression(node.alternate)
+      );
+    case "SpreadElement":
+      return isInertExpression(node.argument);
+    default:
+      return false;
+  }
+}
+
+/**
+ * Check if a variable declarator's init is safe for inclusion in a virtual
+ * module. Safe initializers are:
+ *   1. Function/arrow expressions (body is lazy, no TDZ risk)
+ *   2. Inert expressions (no identifier references, no TDZ risk)
+ *
+ * Declarations that reference identifiers at the top level (e.g.
+ * `const VT = React.Fragment`) are NOT safe -- when the virtual module
+ * is bundled into a separate Rollup chunk, circular chunk dependencies
+ * can cause "Cannot access X before initialization" TDZ errors.
+ */
+function isSafeDeclaratorInit(init: any): boolean {
+  if (!init) return true; // `let x;` with no init is safe
+  if (
+    init.type === "ArrowFunctionExpression" ||
+    init.type === "FunctionExpression"
+  ) {
+    return true;
+  }
+  return isInertExpression(init);
+}
+
+/**
+ * Check if all declarators in a VariableDeclaration have safe initializers
+ * and none is a handler call (Static/Prerender).
+ */
+function isSafeVariableDeclaration(
+  node: any,
+  handlerNames: Set<string>,
+): boolean {
+  if (node.type !== "VariableDeclaration") return false;
+  return node.declarations.every(
+    (d: any) =>
+      isSafeDeclaratorInit(d.init) &&
+      !(
+        d.init?.type === "CallExpression" &&
+        d.init.callee?.type === "Identifier" &&
+        handlerNames.has(d.init.callee.name)
+      ),
+  );
+}
+
+/**
+ * Extract module-level declarations that are safe for inclusion in virtual
+ * modules. "Safe" means the declaration can be eagerly evaluated without
+ * referencing import bindings, preventing TDZ errors in separate chunks.
+ *
+ * Included: function declarations, arrow/function expression inits, and
+ * variable inits that are inert (pure literals, arrays, objects).
+ * Excluded: declarations that reference identifiers at init time (may
+ * reference imports causing TDZ), handler call declarations (circular),
+ * class declarations (field initializers can reference imports).
+ *
+ * Strips export keywords so declarations work as plain locals.
+ * Rollup tree-shakes unused declarations from virtual modules.
+ */
+export function extractModuleLevelDeclarations(
+  code: string,
+  parseAst: (code: string, options?: any) => ProgramNode,
+  handlerNames: Set<string>,
+): string[] {
+  let program: ProgramNode;
+  try {
+    program = parseAst(code, { jsx: true });
+  } catch {
+    return [];
+  }
+
+  const declarations: string[] = [];
+  for (const node of program.body as any[]) {
+    // Skip imports (handled by extractImportDeclarations)
+    if (node.type === "ImportDeclaration") continue;
+
+    // VariableDeclaration -- include only if all declarators are safe
+    if (node.type === "VariableDeclaration") {
+      if (isSafeVariableDeclaration(node, handlerNames)) {
+        declarations.push(code.slice(node.start, node.end));
+      }
+      continue;
+    }
+
+    // FunctionDeclaration -- always safe (body is lazy)
+    if (node.type === "FunctionDeclaration") {
+      declarations.push(code.slice(node.start, node.end));
+      continue;
+    }
+
+    // ExportNamedDeclaration with a declaration inside -- strip the export
+    if (node.type === "ExportNamedDeclaration" && node.declaration) {
+      const decl = node.declaration;
+      if (decl.type === "VariableDeclaration") {
+        if (isSafeVariableDeclaration(decl, handlerNames)) {
+          declarations.push(code.slice(decl.start, decl.end));
+        }
+      } else if (decl.type === "FunctionDeclaration") {
+        declarations.push(code.slice(decl.start, decl.end));
+      }
+      continue;
+    }
+
+    // Skip: ClassDeclaration (field initializers can reference imports),
+    // ExportDefaultDeclaration, ExportAllDeclaration,
+    // ExportNamedDeclaration without declaration (re-exports),
+    // ExpressionStatement (side effects), etc.
+  }
+
+  return declarations;
+}
+
 // ---------------------------------------------------------------------------
 // Transform
 // ---------------------------------------------------------------------------
@@ -295,6 +457,17 @@ export function transformInlineHandlers(
 
   const imports = extractImportDeclarations(code, parseAst);
 
+  // Collect local names for both Static and Prerender to exclude their
+  // declarations from virtual modules (avoids circular extraction).
+  const staticNames = getImportedLocalNames(code, "Static", parseAst);
+  const prerenderNames = getImportedLocalNames(code, "Prerender", parseAst);
+  const handlerNames = new Set([...staticNames, ...prerenderNames]);
+  const declarations = extractModuleLevelDeclarations(
+    code,
+    parseAst,
+    handlerNames,
+  );
+
   // Track line occurrences for same-line collision handling
   const lineCounts = new Map<number, number>();
 
@@ -316,6 +489,7 @@ export function transformInlineHandlers(
     virtualRegistry.set(virtualId, {
       originalModuleId: moduleId,
       imports,
+      declarations,
       handlerCode,
       exportName,
     });
@@ -325,9 +499,7 @@ export function transformInlineHandlers(
 
     // Build the import specifier for this virtual module
     const importId = `${virtualPrefix}${filePath}:${site.lineNumber}${lineCount > 0 ? `:${lineCount}` : ""}`;
-    importStatements.push(
-      `import { ${exportName} } from "${importId}";`,
-    );
+    importStatements.push(`import { ${exportName} } from "${importId}";`);
   }
 
   // Insert imports after directive prologue + existing import block

package/src/vite/utils/banner.ts

@@ -0,0 +1,36 @@
+import packageJson from "../../../package.json" with { type: "json" };
+
+export const rangoVersion: string = packageJson.version;
+
+let _bannerPrinted = false;
+
+export function printBanner(
+  mode: "dev" | "build" | "preview",
+  preset: string,
+  version: string,
+): void {
+  if (_bannerPrinted) return;
+  _bannerPrinted = true;
+
+  // ANSI codes
+  const dim = "\x1b[2m";
+  const bold = "\x1b[1m";
+  const reset = "\x1b[0m";
+
+  const banner = `
+${dim}  ✦        ✦          ✧.           .          .${reset}
+${dim} ╱${reset}    ${bold}╔═╗${reset}${dim}      *      ╱                   ✦             *${reset}
+${dim}      ${reset}${bold}║ ║${reset} ${bold}╔═╗${reset}${dim}                    *                ✧.   ╱${reset}
+${dim}   ${reset}${bold}╔╗ ║ ║ ║ ║${reset}${dim}                          *               ╱${reset}
+${dim}   ${reset}${bold}║║ ║ ║ ║ ║  ╦═╗╔═╗╔╗╔╔═╗╔═╗${reset}${dim}             ✧              ✦${reset}
+${dim}   ${reset}${bold}║║ ║ ╠═╝ ║  ╠╦╝╠═╣║║║║ ╦║ ║${reset}${dim}        *           ✧${reset}
+${dim}   ${reset}${bold}║╚═╝ ╔═══╝  ╩╚═╩ ╩╝╚╝╚═╝╚═╝${reset}${dim}            ✦          .      *${reset}
+${dim}   ${reset}${bold}╚══╗ ║${reset}${dim} *      RSC Wrangler         ✧                ✦${reset}
+${dim}  *   ${reset}${bold}║ ║${reset}${dim}                          *            ✧.    ╱${reset}
+${dim}   ${reset}${bold}═══╝ ╚════${reset}${dim}                           ✦            *${reset}
+
+   v${version} · ${preset} · ${mode}
+`;
+
+  console.log(banner);
+}

package/src/vite/utils/bundle-analysis.ts

@@ -0,0 +1,137 @@
+import {
+  skipStringOrComment,
+  escapeRegExp,
+} from "../plugins/expose-id-utils.js";
+
+/**
+ * Find matching close paren in bundled code using depth counting.
+ * Uses skipStringOrComment from expose-id-utils to correctly handle
+ * template literal ${...} expressions, comments, and nested strings.
+ * Returns the position after the closing paren, or -1 if unmatched.
+ * @internal Exported for testing only.
+ */
+export function findMatchingParenInBundle(
+  code: string,
+  openParenPos: number,
+): number {
+  let depth = 1;
+  let pos = openParenPos;
+  while (pos < code.length && depth > 0) {
+    const skipped = skipStringOrComment(code, pos);
+    if (skipped > pos) {
+      pos = skipped;
+      continue;
+    }
+    if (code[pos] === "(") depth++;
+    else if (code[pos] === ")") depth--;
+    pos++;
+  }
+  return depth === 0 ? pos : -1;
+}
+
+/**
+ * Scan a bundled chunk for handler exports of a given type and extract
+ * their names + $$id values. Optionally detects passthrough flag.
+ * @internal Exported for testing only.
+ */
+export function extractHandlerExportsFromChunk(
+  chunkCode: string,
+  handlerModules: Map<string, string[]>,
+  fnName: string,
+  detectPassthrough: boolean,
+): Array<{ name: string; handlerId: string; passthrough: boolean }> {
+  const handlers: Array<{
+    name: string;
+    handlerId: string;
+    passthrough: boolean;
+  }> = [];
+
+  for (const [, handlerNames] of handlerModules) {
+    for (const name of handlerNames) {
+      const eName = escapeRegExp(name);
+      const idPattern = new RegExp(
+        `(?<![a-zA-Z0-9_])${eName}\\.\\$\\$id\\s*=\\s*"([^"]+)"`,
+      );
+      const match = chunkCode.match(idPattern);
+      if (!match) continue;
+
+      let isPassthrough = false;
+      if (detectPassthrough) {
+        const eFnName = escapeRegExp(fnName);
+        const callStartRe = new RegExp(
+          `const\\s+${eName}\\s*=\\s*${eFnName}\\s*(?:<[^>]*>)?\\s*\\(`,
+        );
+        const callStart = callStartRe.exec(chunkCode);
+        if (callStart) {
+          const afterOpen = callStart.index + callStart[0].length;
+          const closePos = findMatchingParenInBundle(chunkCode, afterOpen);
+          if (closePos !== -1) {
+            const callBody = chunkCode.slice(callStart.index, closePos);
+            isPassthrough = /passthrough\s*:\s*(!0|true)/.test(callBody);
+          }
+        }
+      }
+      handlers.push({ name, handlerId: match[1], passthrough: isPassthrough });
+    }
+  }
+
+  return handlers;
+}
+
+/**
+ * Evict handler code from a bundled chunk, replacing full handler call
+ * expressions with lightweight stub objects. Returns the modified code
+ * and bytes saved, or null if no changes were made.
+ * @internal Exported for testing only.
+ */
+export function evictHandlerCode(
+  code: string,
+  exports: Array<{ name: string; handlerId: string; passthrough?: boolean }>,
+  fnName: string,
+  brand: string,
+): { code: string; savedBytes: number } | null {
+  const originalSize = Buffer.byteLength(code);
+  let modified = code;
+
+  const eFnName = escapeRegExp(fnName);
+  for (const { name, handlerId, passthrough } of exports) {
+    if (passthrough) continue;
+
+    const eName = escapeRegExp(name);
+    const callStartRe = new RegExp(
+      `const\\s+${eName}\\s*=\\s*${eFnName}\\s*(?:<[^>]*>)?\\s*\\(`,
+    );
+    const startMatch = callStartRe.exec(modified);
+    if (!startMatch) continue;
+
+    const afterOpen = startMatch.index + startMatch[0].length;
+    const closePos = findMatchingParenInBundle(modified, afterOpen);
+    if (closePos === -1) continue;
+
+    // Skip trailing whitespace and optional semicolon
+    let rangeEnd = closePos;
+    while (rangeEnd < modified.length && /\s/.test(modified[rangeEnd]))
+      rangeEnd++;
+    if (modified[rangeEnd] === ";") rangeEnd++;
+
+    // Validate: matched range must contain the expected handlerId
+    const matched = modified.slice(startMatch.index, rangeEnd);
+    if (!matched.includes(handlerId)) continue;
+
+    const stub = `const ${name} = { __brand: "${brand}", $$id: "${handlerId}" };`;
+    modified =
+      modified.slice(0, startMatch.index) + stub + modified.slice(rangeEnd);
+
+    // Remove the now-redundant $$id assignment line.
+    modified = modified.replace(
+      new RegExp(`\\n${eName}\\.\\$\\$id\\s*=\\s*"[^"]+";`),
+      "",
+    );
+  }
+
+  if (modified === code) return null;
+  return {
+    code: modified,
+    savedBytes: originalSize - Buffer.byteLength(modified),
+  };
+}

package/src/vite/utils/manifest-utils.ts

@@ -0,0 +1,70 @@
+/**
+ * Flatten prefix tree leaf nodes into precomputed route entries.
+ * Leaf nodes have no children (no nested includes), so their routes can be
+ * used directly by evaluateLazyEntry() without running the handler.
+ * Non-leaf nodes are skipped because they have nested lazy includes that
+ * require the handler to run for discovery.
+ */
+export function flattenLeafEntries(
+  prefixTree: Record<string, any>,
+  routeManifest: Record<string, string>,
+  result: Array<{ staticPrefix: string; routes: Record<string, string> }>,
+): void {
+  function visit(node: any): void {
+    const children = node.children || {};
+    if (
+      Object.keys(children).length === 0 &&
+      node.routes &&
+      node.routes.length > 0
+    ) {
+      // Leaf node: collect its routes from the manifest
+      const routes: Record<string, string> = {};
+      for (const name of node.routes) {
+        if (name in routeManifest) {
+          routes[name] = routeManifest[name];
+        }
+      }
+      result.push({ staticPrefix: node.staticPrefix, routes });
+    } else {
+      // Non-leaf: recurse into children
+      for (const child of Object.values(children)) {
+        visit(child);
+      }
+    }
+  }
+  for (const node of Object.values(prefixTree)) {
+    visit(node);
+  }
+}
+
+/**
+ * Walk prefix tree to map each route name to its scope's staticPrefix.
+ */
+export function buildRouteToStaticPrefix(
+  prefixTree: Record<string, any>,
+  result: Record<string, string>,
+): void {
+  function visit(node: any): void {
+    const sp = node.staticPrefix || "";
+    for (const name of node.routes || []) {
+      result[name] = sp;
+    }
+    for (const child of Object.values(node.children || {})) {
+      visit(child);
+    }
+  }
+  for (const node of Object.values(prefixTree)) {
+    visit(node);
+  }
+}
+
+/**
+ * Wrap a value as `JSON.parse('...')` instead of a JS object literal.
+ * V8's JSON parser is significantly faster than its full JS parser for large
+ * objects, so this improves startup time for big route manifests.
+ */
+export function jsonParseExpression(value: unknown): string {
+  const json = JSON.stringify(value);
+  const escaped = json.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+  return `JSON.parse('${escaped}')`;
+}

package/src/vite/{package-resolution.ts → utils/package-resolution.ts}

@@ -7,7 +7,7 @@
 
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
-import packageJson from "../../package.json" with { type: "json" };
+import packageJson from "../../../package.json" with { type: "json" };
 
 /**
  * The canonical name used in virtual entries (without scope)
@@ -46,21 +46,26 @@ export function isWorkspaceDevelopment(): boolean {
 }
 
 /**
- * Subpaths that need to be excluded from Vite's dependency optimization
- * and potentially aliased
+ * Subpaths derived from package.json exports that use TypeScript source.
+ * These must be excluded from Vite's dependency optimization (they ship
+ * as .ts/.tsx, not compiled JS) and aliased when installed from npm.
+ *
+ * Derived automatically from the exports field to prevent drift.
  */
-const PACKAGE_SUBPATHS = [
-  "",
-  "/browser",
-  "/client",
-  "/server",
-  "/rsc",
-  "/ssr",
-  "/internal/deps/browser",
-  "/internal/deps/html-stream-client",
-  "/internal/deps/ssr",
-  "/internal/deps/rsc",
-] as const;
+const SOURCE_EXPORT_SUBPATHS = Object.keys(packageJson.exports)
+  .filter((key) => {
+    const entry = (
+      packageJson.exports as Record<string, Record<string, string>>
+    )[key];
+    // Include if any non-types condition points to TypeScript source
+    return Object.entries(entry).some(
+      ([condition, path]) =>
+        condition !== "types" &&
+        typeof path === "string" &&
+        /\.tsx?$/.test(path),
+    );
+  })
+  .map((key) => key.replace(/^\./, ""));
 
 /**
  * Generate the list of modules to exclude from Vite's dependency optimization.
@@ -72,7 +77,7 @@ export function getExcludeDeps(): string[] {
   const packageName = getPublishedPackageName();
   const excludes: string[] = [];
 
-  for (const subpath of PACKAGE_SUBPATHS) {
+  for (const subpath of SOURCE_EXPORT_SUBPATHS) {
     // Add scoped package paths
     excludes.push(`${packageName}${subpath}`);
     // Add virtual/aliased paths (before alias resolution)
@@ -85,20 +90,11 @@ export function getExcludeDeps(): string[] {
 }
 
 /**
- * Subpaths that need aliasing (subset of PACKAGE_SUBPATHS)
+ * Subpaths that need aliasing — same as SOURCE_EXPORT_SUBPATHS.
+ * When installed from npm, virtual entries may use a different package name
+ * than the published one; aliases bridge them.
  */
-const ALIAS_SUBPATHS = [
-  "/internal/deps/browser",
-  "/internal/deps/ssr",
-  "/internal/deps/rsc",
-  "/internal/deps/html-stream-client",
-  "/internal/deps/html-stream-server",
-  "/browser",
-  "/client",
-  "/server",
-  "/rsc",
-  "/ssr",
-] as const;
+const ALIAS_SUBPATHS = SOURCE_EXPORT_SUBPATHS;
 
 /**
  * Generate aliases to map virtual package paths to the actual published package.