@rangojs/router 0.0.0-experimental.14 → 0.0.0-experimental.141

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

@@ -1,9 +1,5 @@
 import type MagicString from "magic-string";
-import { hashInlineId, buildExportMap } from "./expose-id-utils.ts";
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
+import { hashInlineId, buildExportMap } from "../plugins/expose-id-utils.js";
 
 /** Minimal ESTree Program node — avoids importing from `rollup` (not a direct dep). */
 interface ProgramNode {
@@ -27,14 +23,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"
   );
 }
 
@@ -48,7 +44,7 @@ function findImportInsertionPos(
 ): number {
   let program: ProgramNode;
   try {
-    program = parseAst(code, { jsx: true });
+    program = parseAst(code, { lang: "tsx" });
   } catch {
     return 0;
   }
@@ -70,10 +66,6 @@ function findImportInsertionPos(
   return insertionPos;
 }
 
-// ---------------------------------------------------------------------------
-// AST walking helper
-// ---------------------------------------------------------------------------
-
 /**
  * Recursively walk an ESTree AST node, calling `enter` on each node.
  * Parent is passed for context.
@@ -99,7 +91,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);
     }
   }
@@ -107,10 +103,6 @@ function walkNode(
   ancestors.pop();
 }
 
-// ---------------------------------------------------------------------------
-// AST analysis
-// ---------------------------------------------------------------------------
-
 /**
  * Parse the file with Vite's parseAst and find all calls to `fnName`.
  * Distinguishes between `export const X = fnName(...)` (exportInfo set)
@@ -123,7 +115,7 @@ export function findHandlerCalls(
 ): HandlerCallSite[] {
   let program: ProgramNode;
   try {
-    program = parseAst(code, { jsx: true });
+    program = parseAst(code, { lang: "tsx" });
   } catch {
     return [];
   }
@@ -158,8 +150,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" &&
@@ -233,7 +227,7 @@ export function getImportedLocalNames(
   parseAst: (code: string, options?: any) => ProgramNode,
 ): Set<string> {
   try {
-    const program = parseAst(code, { jsx: true });
+    const program = parseAst(code, { lang: "tsx" });
     return getImportedLocalNamesFromProgram(program, importedName);
   } catch {
     return new Set<string>();
@@ -250,7 +244,7 @@ export function extractImportDeclarations(
 ): string[] {
   let program: ProgramNode;
   try {
-    program = parseAst(code, { jsx: true });
+    program = parseAst(code, { lang: "tsx" });
   } catch {
     return [];
   }
@@ -264,9 +258,168 @@ export function extractImportDeclarations(
   return imports;
 }
 
-// ---------------------------------------------------------------------------
-// Transform
-// ---------------------------------------------------------------------------
+/**
+ * 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) => {
+        // A spread inside an object (`{ ...x }`) is inert iff `x` is inert.
+        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":
+      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, { lang: "tsx" });
+  } 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 inline handler calls by extracting them into virtual modules.
@@ -295,19 +448,30 @@ export function transformInlineHandlers(
 
   const imports = extractImportDeclarations(code, parseAst);
 
-  // Track line occurrences for same-line collision handling
-  const lineCounts = new Map<number, number>();
+  // 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,
+  );
 
   // Collect all import statements to prepend
   const importStatements: string[] = [];
 
-  for (const site of inlineSites) {
-    const lineCount = lineCounts.get(site.lineNumber) ?? 0;
-    lineCounts.set(site.lineNumber, lineCount + 1);
-
-    const hash = hashInlineId(filePath, site.lineNumber, lineCount);
+  for (const [siteIndex, site] of inlineSites.entries()) {
+    // Key the extracted handler on its source-order index (per fnName), NOT its
+    // line number. The id flows into BOTH the export name and the virtual module
+    // path (which hashId hashes for the runtime $$id), and line numbers shift
+    // between the prerender and production build contexts. The index is invariant
+    // to those shifts, keeping the prerender manifest key == the runtime id.
+    const hash = hashInlineId(filePath, fnName, siteIndex);
     const exportName = `__sh_${hash}`;
-    const virtualId = `\0${virtualPrefix}${filePath}:${site.lineNumber}${lineCount > 0 ? `:${lineCount}` : ""}`;
+    const idSuffix = `${filePath}:${fnName}:${siteIndex}`;
+    const virtualId = `\0${virtualPrefix}${idSuffix}`;
 
     // Extract the full handler call expression text
     const handlerCode = code.slice(site.callStart, site.callEnd);
@@ -316,6 +480,7 @@ export function transformInlineHandlers(
     virtualRegistry.set(virtualId, {
       originalModuleId: moduleId,
       imports,
+      declarations,
       handlerCode,
       exportName,
     });
@@ -324,10 +489,8 @@ export function transformInlineHandlers(
     s.overwrite(site.callStart, site.callEnd, exportName);
 
     // Build the import specifier for this virtual module
-    const importId = `${virtualPrefix}${filePath}:${site.lineNumber}${lineCount > 0 ? `:${lineCount}` : ""}`;
-    importStatements.push(
-      `import { ${exportName} } from "${importId}";`,
-    );
+    const importId = `${virtualPrefix}${idSuffix}`;
+    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";
+
+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,132 @@
+import {
+  skipStringOrComment,
+  escapeRegExp,
+} from "../plugins/expose-id-utils.js";
+
+/**
+ * Find matching close paren in bundled code using depth counting.
+ * Uses skipStringOrComment to correctly handle template literals, comments, and nested strings.
+ * @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 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|let|var)\\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); // !0 is minified true
+          }
+        }
+      }
+      handlers.push({ name, handlerId: match[1], passthrough: isPassthrough });
+    }
+  }
+
+  return handlers;
+}
+
+/**
+ * Evict handler code from a bundled chunk, replacing full call expressions with stubs.
+ * 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);
+    // Match const/let/var: Rolldown (Vite 8) emits top-level bindings in the
+    // non-minified RSC bundle as `var`, whereas Rollup used `const`.
+    const callStartRe = new RegExp(
+      `(?:const|let|var)\\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;
+
+    let rangeEnd = closePos;
+    while (rangeEnd < modified.length && /\s/.test(modified[rangeEnd]))
+      rangeEnd++;
+    if (modified[rangeEnd] === ";") rangeEnd++;
+
+    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);
+
+    modified = modified.replace(
+      new RegExp(`\\n${eName}\\.\\$\\$id\\s*=\\s*"[^"]+";`),
+      "",
+    );
+  }
+
+  if (modified === code) return null;
+  return {
+    code: modified,
+    savedBytes: originalSize - Buffer.byteLength(modified),
+  };
+}