@rangojs/router 0.22.1 → 0.23.0

package/src/vite/plugins/transition-when-hoist.ts

@@ -2,8 +2,36 @@ import type { Plugin } from "vite";
 import { normalizePath, parseAst } from "vite";
 import MagicString from "magic-string";
 import { builtinModules } from "node:module";
-import { readFile } from "node:fs/promises";
+import { hasDirective } from "@vitejs/plugin-rsc/transforms";
+import { offsetToLineColumn } from "./expose-ids/export-analysis.js";
 import { TransitionWhenError } from "../../transition-when-ref.js";
+import {
+  analyzeScopes,
+  collectImports,
+  type ImportBinding,
+  type Node,
+  type Scope,
+} from "./hoist/scope.js";
+import {
+  collectFreeReferences,
+  directivePrologueEnd,
+  emitImports,
+  findHelperCalls,
+  findLexicalCapture,
+  isFunctionLiteral,
+  parseLang,
+  propertyKeyIs,
+  unwrapExpression,
+  type LexicalCaptureMessages,
+} from "./hoist/literal.js";
+import {
+  loadEmittedOrDisk,
+  readSource,
+  recordEmitted,
+  resolveSourceTarget,
+  SOURCE_FILE_RE,
+  type EmittedEntry,
+} from "./hoist/source.js";
 
 /**
  * Inline transition({ when }) in urls(): the build hoists the function
@@ -51,397 +79,6 @@ const TRANSITION_WHEN_QUERY = "rango-when";
 const EXPORT_NAME = "__rango_when";
 const LOCAL_PREFIX = "__rango_when_";
 
-type Node = any;
-
-interface ImportBinding {
-  readonly source: string;
-  /** "default", "*", or the imported name. */
-  readonly imported: string;
-  readonly typeOnly: boolean;
-}
-
-class Scope {
-  readonly declarations = new Set<string>();
-  constructor(
-    readonly parent: Scope | null,
-    readonly isFunction: boolean,
-    readonly node: Node,
-  ) {}
-  nearestFunction(): Scope {
-    return this.isFunction || !this.parent
-      ? this
-      : this.parent.nearestFunction();
-  }
-  lookup(name: string): Scope | null {
-    if (this.declarations.has(name)) return this;
-    return this.parent ? this.parent.lookup(name) : null;
-  }
-}
-
-interface Reference {
-  readonly node: Node;
-  readonly scope: Scope;
-  readonly typeOnly: boolean;
-}
-
-const TYPE_KEYS = new Set([
-  "typeAnnotation",
-  "returnType",
-  "typeParameters",
-  "typeArguments",
-  "superTypeArguments",
-  "implements",
-]);
-
-/**
- * The identifier a JSX element name refers to: a component (`<Local />`) or
- * the root of a member name (`<ui.Badge />`). Lowercase and dashed names are
- * intrinsic tags, not references; `<this.X />` is checked as `this`.
- */
-function jsxNameReference(name: Node): Node | null {
-  if (name?.type === "JSXIdentifier") {
-    return /^[a-z]/.test(name.name) || name.name.includes("-") ? null : name;
-  }
-  let root = name;
-  while (root?.type === "JSXMemberExpression") root = root.object;
-  return root?.type === "JSXIdentifier" && root.name !== "this" ? root : null;
-}
-
-function patternNames(pattern: Node, names: string[] = []): string[] {
-  if (!pattern) return names;
-  switch (pattern.type) {
-    case "Identifier":
-      names.push(pattern.name);
-      break;
-    case "ObjectPattern":
-      for (const prop of pattern.properties) {
-        patternNames(prop.type === "RestElement" ? prop : prop.value, names);
-      }
-      break;
-    case "ArrayPattern":
-      for (const element of pattern.elements) patternNames(element, names);
-      break;
-    case "RestElement":
-      patternNames(pattern.argument, names);
-      break;
-    case "AssignmentPattern":
-      patternNames(pattern.left, names);
-      break;
-    case "TSParameterProperty":
-      patternNames(pattern.parameter, names);
-      break;
-  }
-  return names;
-}
-
-/**
- * Scope tree and every identifier reference of a module, TS type positions
- * flagged. Enough of ES scoping for free-variable analysis of one literal:
- * var hoists to the function scope, let/const/class to the block, function
- * declarations to their block.
- */
-function analyzeScopes(program: Node): {
-  moduleScope: Scope;
-  references: Reference[];
-  scopeOf: Map<Node, Scope>;
-} {
-  const moduleScope = new Scope(null, true, program);
-  const scopeOf = new Map<Node, Scope>([[program, moduleScope]]);
-  const references: Reference[] = [];
-
-  const declarePattern = (pattern: Node, scope: Scope): void => {
-    for (const name of patternNames(pattern)) scope.declarations.add(name);
-  };
-
-  // Binding patterns: identifiers declare; defaults and computed keys refer.
-  const walkPattern = (pattern: Node, scope: Scope, typeOnly: boolean) => {
-    if (!pattern) return;
-    switch (pattern.type) {
-      case "Identifier":
-        if (pattern.typeAnnotation) walk(pattern.typeAnnotation, scope, true);
-        return;
-      case "ObjectPattern":
-        for (const prop of pattern.properties) {
-          if (prop.type === "RestElement") {
-            walkPattern(prop.argument, scope, typeOnly);
-          } else {
-            if (prop.computed) walk(prop.key, scope, typeOnly);
-            walkPattern(prop.value, scope, typeOnly);
-          }
-        }
-        if (pattern.typeAnnotation) walk(pattern.typeAnnotation, scope, true);
-        return;
-      case "ArrayPattern":
-        for (const element of pattern.elements) {
-          walkPattern(element, scope, typeOnly);
-        }
-        if (pattern.typeAnnotation) walk(pattern.typeAnnotation, scope, true);
-        return;
-      case "RestElement":
-        walkPattern(pattern.argument, scope, typeOnly);
-        return;
-      case "AssignmentPattern":
-        walkPattern(pattern.left, scope, typeOnly);
-        walk(pattern.right, scope, typeOnly);
-        return;
-      case "TSParameterProperty":
-        walkPattern(pattern.parameter, scope, typeOnly);
-        return;
-      default:
-        walk(pattern, scope, typeOnly);
-    }
-  };
-
-  // Hoist function-scoped and block-scoped declarations of a body before its
-  // statements are walked, so a reference ahead of its declaration resolves.
-  const hoistDeclarations = (statements: Node[], scope: Scope): void => {
-    for (const statement of statements) {
-      const node =
-        statement.type === "ExportNamedDeclaration" ||
-        statement.type === "ExportDefaultDeclaration"
-          ? statement.declaration
-          : statement;
-      if (!node) continue;
-      switch (node.type) {
-        case "ImportDeclaration":
-          for (const spec of node.specifiers) {
-            scope.declarations.add(spec.local.name);
-          }
-          break;
-        case "FunctionDeclaration":
-        case "ClassDeclaration":
-        case "TSEnumDeclaration":
-        case "TSTypeAliasDeclaration":
-        case "TSInterfaceDeclaration":
-        case "TSModuleDeclaration":
-          if (node.id?.type === "Identifier") {
-            scope.declarations.add(node.id.name);
-          }
-          break;
-        case "VariableDeclaration":
-          for (const declarator of node.declarations) {
-            declarePattern(
-              declarator.id,
-              node.kind === "var" ? scope.nearestFunction() : scope,
-            );
-          }
-          break;
-      }
-    }
-  };
-
-  const walk = (node: Node, scope: Scope, typeOnly: boolean): void => {
-    if (!node || typeof node !== "object") return;
-    if (Array.isArray(node)) {
-      for (const item of node) walk(item, scope, typeOnly);
-      return;
-    }
-    if (typeof node.type !== "string") return;
-
-    switch (node.type) {
-      case "Identifier":
-        references.push({ node, scope, typeOnly });
-        if (node.typeAnnotation) walk(node.typeAnnotation, scope, true);
-        return;
-      case "ImportDeclaration":
-      case "ExportAllDeclaration":
-        return;
-      case "ExportNamedDeclaration":
-        if (node.declaration) walk(node.declaration, scope, typeOnly);
-        else if (!node.source) {
-          for (const spec of node.specifiers) {
-            walk(spec.local, scope, typeOnly || node.exportKind === "type");
-          }
-        }
-        return;
-      case "MemberExpression":
-        walk(node.object, scope, typeOnly);
-        if (node.computed) walk(node.property, scope, typeOnly);
-        return;
-      case "Property":
-      case "MethodDefinition":
-      case "PropertyDefinition":
-      case "TSPropertySignature":
-      case "TSMethodSignature":
-        if (node.computed) walk(node.key, scope, typeOnly);
-        walk(node.value, scope, typeOnly);
-        if (node.typeAnnotation) walk(node.typeAnnotation, scope, true);
-        return;
-      case "LabeledStatement":
-        walk(node.body, scope, typeOnly);
-        return;
-      case "BreakStatement":
-      case "ContinueStatement":
-      case "MetaProperty":
-        return;
-      case "JSXOpeningElement":
-      case "JSXClosingElement": {
-        const ref = jsxNameReference(node.name);
-        if (ref) references.push({ node: ref, scope, typeOnly });
-        walk(node.typeArguments, scope, true);
-        walk(node.attributes, scope, typeOnly);
-        return;
-      }
-      case "TSQualifiedName":
-        walk(node.left, scope, typeOnly);
-        return;
-      case "TSEnumMember":
-        walk(node.initializer, scope, typeOnly);
-        return;
-      case "TSTypeAliasDeclaration":
-      case "TSInterfaceDeclaration":
-        walk(node.typeParameters, scope, true);
-        walk(node.typeAnnotation ?? node.body, scope, true);
-        walk(node.extends, scope, true);
-        return;
-      case "VariableDeclarator":
-        walkPattern(node.id, scope, typeOnly);
-        walk(node.init, scope, typeOnly);
-        return;
-      case "FunctionDeclaration":
-      case "FunctionExpression":
-      case "ArrowFunctionExpression": {
-        const fnScope = new Scope(scope, true, node);
-        scopeOf.set(node, fnScope);
-        if (node.type === "FunctionExpression" && node.id) {
-          fnScope.declarations.add(node.id.name);
-        }
-        for (const param of node.params) declarePattern(param, fnScope);
-        walk(node.typeParameters, fnScope, true);
-        for (const param of node.params) walkPattern(param, fnScope, typeOnly);
-        walk(node.returnType, fnScope, true);
-        if (node.body?.type === "BlockStatement") {
-          hoistDeclarations(node.body.body, fnScope);
-          walk(node.body.body, fnScope, typeOnly);
-        } else {
-          walk(node.body, fnScope, typeOnly);
-        }
-        return;
-      }
-      case "ClassDeclaration":
-      case "ClassExpression": {
-        let classScope = scope;
-        if (node.type === "ClassExpression" && node.id) {
-          classScope = new Scope(scope, false, node);
-          classScope.declarations.add(node.id.name);
-          scopeOf.set(node, classScope);
-        }
-        walk(node.superClass, classScope, typeOnly);
-        walk(node.superTypeArguments, classScope, true);
-        walk(node.typeParameters, classScope, true);
-        walk(node.implements, classScope, true);
-        walk(node.body, classScope, typeOnly);
-        return;
-      }
-      case "BlockStatement":
-      case "StaticBlock": {
-        const blockScope = new Scope(scope, false, node);
-        scopeOf.set(node, blockScope);
-        hoistDeclarations(node.body, blockScope);
-        walk(node.body, blockScope, typeOnly);
-        return;
-      }
-      case "ForStatement":
-      case "ForInStatement":
-      case "ForOfStatement": {
-        const loopScope = new Scope(scope, false, node);
-        scopeOf.set(node, loopScope);
-        const head = node.type === "ForStatement" ? node.init : node.left;
-        if (head?.type === "VariableDeclaration") {
-          hoistDeclarations([head], loopScope);
-        }
-        for (const key of ["init", "left", "right", "test", "update", "body"]) {
-          walk(node[key], loopScope, typeOnly);
-        }
-        return;
-      }
-      case "SwitchStatement": {
-        walk(node.discriminant, scope, typeOnly);
-        const switchScope = new Scope(scope, false, node);
-        scopeOf.set(node, switchScope);
-        hoistDeclarations(
-          node.cases.flatMap((c: Node) => c.consequent),
-          switchScope,
-        );
-        for (const c of node.cases) {
-          walk(c.test, switchScope, typeOnly);
-          walk(c.consequent, switchScope, typeOnly);
-        }
-        return;
-      }
-      case "CatchClause": {
-        const catchScope = new Scope(scope, false, node);
-        scopeOf.set(node, catchScope);
-        if (node.param) {
-          declarePattern(node.param, catchScope);
-          walkPattern(node.param, catchScope, typeOnly);
-        }
-        walk(node.body, catchScope, typeOnly);
-        return;
-      }
-    }
-
-    for (const key of Object.keys(node)) {
-      if (key === "type" || key === "start" || key === "end") continue;
-      walk(node[key], scope, typeOnly || TYPE_KEYS.has(key));
-    }
-  };
-
-  hoistDeclarations(program.body, moduleScope);
-  walk(program.body, moduleScope, false);
-  return { moduleScope, references, scopeOf };
-}
-
-function collectImports(program: Node): Map<string, ImportBinding> {
-  const imports = new Map<string, ImportBinding>();
-  for (const statement of program.body) {
-    if (statement.type !== "ImportDeclaration") continue;
-    const declTypeOnly = statement.importKind === "type";
-    for (const spec of statement.specifiers) {
-      imports.set(spec.local.name, {
-        source: statement.source.value,
-        imported:
-          spec.type === "ImportDefaultSpecifier"
-            ? "default"
-            : spec.type === "ImportNamespaceSpecifier"
-              ? "*"
-              : spec.imported.type === "Identifier"
-                ? spec.imported.name
-                : String(spec.imported.value),
-        typeOnly: declTypeOnly || spec.importKind === "type",
-      });
-    }
-  }
-  return imports;
-}
-
-function hasUseClientDirective(program: Node): boolean {
-  for (const statement of program.body) {
-    if (
-      statement.type !== "ExpressionStatement" ||
-      typeof statement.directive !== "string"
-    ) {
-      return false;
-    }
-    if (statement.directive === "use client") return true;
-  }
-  return false;
-}
-
-function lineColumn(code: string, offset: number): string {
-  let line = 1;
-  let column = 1;
-  for (let i = 0; i < offset && i < code.length; i++) {
-    if (code[i] === "\n") {
-      line++;
-      column = 1;
-    } else {
-      column++;
-    }
-  }
-  return `${line}:${column}`;
-}
-
 /**
  * A `when` site: the `when` property of a router transition() config, and its
  * value with TS wrappers dropped (a function literal, an identifier, ...).
@@ -452,44 +89,7 @@ interface WhenSite {
   readonly scope: Scope;
 }
 
-const ROUTER_SOURCE = "@rangojs/router";
-
-const EXPRESSION_WRAPPERS = new Set([
-  "TSAsExpression",
-  "TSSatisfiesExpression",
-  "TSNonNullExpression",
-  "TSTypeAssertion",
-  "ParenthesizedExpression",
-]);
-
-function unwrapExpression(node: Node): Node {
-  while (node && EXPRESSION_WRAPPERS.has(node.type)) node = node.expression;
-  return node;
-}
-
-function isFunctionLiteral(node: Node): boolean {
-  return (
-    node?.type === "ArrowFunctionExpression" ||
-    node?.type === "FunctionExpression"
-  );
-}
-
-function propertyKeyIs(prop: Node, name: string): boolean {
-  return (
-    prop?.type === "Property" &&
-    !prop.computed &&
-    ((prop.key.type === "Identifier" && prop.key.name === name) ||
-      (prop.key.type === "Literal" && prop.key.value === name))
-  );
-}
-
-/** What a urls() callback's first parameter binds the transition helper to. */
-interface HelperBindings {
-  /** `({ transition })`, `({ transition: t })`. */
-  readonly transitions: Set<string>;
-  /** `(helpers) => helpers.transition(...)`. */
-  readonly objects: Set<string>;
-}
+const ROUTER_SOURCES: ReadonlySet<string> = new Set(["@rangojs/router"]);
 
 function findWhenSites(
   program: Node,
@@ -498,244 +98,52 @@ function findWhenSites(
   imports: Map<string, ImportBinding>,
 ): WhenSite[] {
   const sites: WhenSite[] = [];
-  const helpers = new Map<Scope, HelperBindings>();
-
-  // The router export a callee names: `urls`, `transition as t`, `Rango.urls`.
-  const routerExport = (callee: Node, scope: Scope): string | null => {
-    const routerImport = (id: Node): ImportBinding | null => {
-      if (id?.type !== "Identifier") return null;
-      if (scope.lookup(id.name) !== moduleScope) return null;
-      const binding = imports.get(id.name);
-      return binding?.source === ROUTER_SOURCE && !binding.typeOnly
-        ? binding
-        : null;
-    };
-    if (callee.type === "Identifier") {
-      const imported = routerImport(callee)?.imported;
-      return imported && imported !== "*" && imported !== "default"
-        ? imported
-        : null;
-    }
-    if (
-      callee.type === "MemberExpression" &&
-      !callee.computed &&
-      callee.property.type === "Identifier" &&
-      routerImport(callee.object)?.imported === "*"
-    ) {
-      return callee.property.name;
-    }
-    return null;
-  };
-
-  const registerUrlsCallback = (callback: Node): void => {
-    const fnScope = scopeOf.get(callback);
-    let param = callback.params[0];
-    if (param?.type === "AssignmentPattern") param = param.left;
-    if (!fnScope || !param) return;
-    const bindings: HelperBindings = {
-      transitions: new Set(),
-      objects: new Set(),
-    };
-    if (param.type === "Identifier") bindings.objects.add(param.name);
-    if (param.type === "ObjectPattern") {
-      for (const prop of param.properties) {
-        if (!propertyKeyIs(prop, "transition")) continue;
-        const target =
-          prop.value.type === "AssignmentPattern"
-            ? prop.value.left
-            : prop.value;
-        if (target.type === "Identifier") bindings.transitions.add(target.name);
-      }
-    }
-    helpers.set(fnScope, bindings);
-  };
-
-  const isRouterTransition = (callee: Node, scope: Scope): boolean => {
-    if (routerExport(callee, scope) === "transition") return true;
-    if (callee.type === "Identifier") {
-      const decl = scope.lookup(callee.name);
-      return !!decl && !!helpers.get(decl)?.transitions.has(callee.name);
-    }
-    if (
-      callee.type === "MemberExpression" &&
-      !callee.computed &&
-      callee.property.type === "Identifier" &&
-      callee.property.name === "transition" &&
-      callee.object.type === "Identifier"
-    ) {
-      const decl = scope.lookup(callee.object.name);
-      return !!decl && !!helpers.get(decl)?.objects.has(callee.object.name);
-    }
-    return false;
-  };
-
-  const visit = (node: Node, scope: Scope): void => {
-    if (!node || typeof node !== "object") return;
-    if (Array.isArray(node)) {
-      for (const item of node) visit(item, scope);
-      return;
-    }
-    if (typeof node.type !== "string") return;
-    const own = scopeOf.get(node) ?? scope;
-    if (node.type === "CallExpression") {
-      // Registered before the callback body is visited, which is where its
-      // transition() calls are.
-      const callback = node.arguments[0];
-      if (
-        isFunctionLiteral(callback) &&
-        routerExport(node.callee, own) === "urls"
-      ) {
-        registerUrlsCallback(callback);
-      }
-      if (
-        node.arguments[0]?.type === "ObjectExpression" &&
-        isRouterTransition(node.callee, own)
-      ) {
-        for (const prop of node.arguments[0].properties) {
-          if (propertyKeyIs(prop, "when")) {
-            sites.push({
-              prop,
-              value: unwrapExpression(prop.value),
-              scope: own,
-            });
-          }
-        }
+  for (const { call, scope } of findHelperCalls(
+    program,
+    scopeOf,
+    moduleScope,
+    imports,
+    {
+      sources: ROUTER_SOURCES,
+      builder: "urls",
+      helper: "transition",
+      directImport: true,
+    },
+  )) {
+    if (call.arguments[0]?.type !== "ObjectExpression") continue;
+    for (const prop of call.arguments[0].properties) {
+      if (propertyKeyIs(prop, "when")) {
+        sites.push({ prop, value: unwrapExpression(prop.value), scope });
       }
     }
-    for (const key of Object.keys(node)) {
-      if (key === "type" || key === "start" || key === "end") continue;
-      visit(node[key], own);
-    }
-  };
-  visit(program.body, moduleScope);
+  }
   return sites;
 }
 
 /** Why a lexical-context use in a literal is a capture, by construct. */
-const LEXICAL_CAPTURE: Record<string, string> = {
-  this: "`this` in an arrow is the enclosing server function's `this`.",
-  arguments:
-    "`arguments` in an arrow is the enclosing server function's `arguments`.",
-  super: "`super` refers to the enclosing server object.",
-  "new.target": "`new.target` in an arrow is the enclosing server function's.",
+const WHEN_CAPTURE_MESSAGES: LexicalCaptureMessages = {
+  lexical: {
+    this: "`this` in an arrow is the enclosing server function's `this`.",
+    arguments:
+      "`arguments` in an arrow is the enclosing server function's `arguments`.",
+    super: "`super` refers to the enclosing server object.",
+    "new.target":
+      "`new.target` in an arrow is the enclosing server function's.",
+  },
+  captureHint:
+    "Read what you need from `to.params`/`to.state`, or export the " +
+    'predicate from a "use client" module.',
+  loadsHint:
+    "Import client-safe modules statically, or export the predicate from a " +
+    '"use client" module.',
+  importMetaWhy: "is the server module's.",
+  importMetaMemberWhy:
+    "is resolved against the server module; only `import.meta.env` is " +
+    "available to an inline predicate.",
+  dynamicImportWhy:
+    "loads a module at run time, which the build cannot check is client-safe.",
 };
 
-/**
- * The first use in a literal of a lexical context it would lose when hoisted
- * (`this`, `arguments`, `super`, `new.target` of an enclosing server function
- * or object), or of a module-loading expression the build cannot check
- * (`import()`, `import.meta` other than `import.meta.env`). A nested
- * non-arrow function (or class body) owns its `this`/`arguments`, so uses
- * inside one are fine; a method literal owns them too, but its `super`
- * loses the object it was defined on.
- */
-function findLexicalCapture(
-  literal: Node,
-  references: readonly Reference[],
-  code: string,
-): { node: Node; detail: string } | null {
-  const ownArguments: Node[] = [];
-  let found: { node: Node; detail: string } | null = null;
-  const capture = (node: Node, what: string): void => {
-    found = {
-      node,
-      detail:
-        `${LEXICAL_CAPTURE[what]} Read what you need from ` +
-        '`to.params`/`to.state`, or export the predicate from a "use client" ' +
-        "module.",
-    };
-  };
-  const loads = (node: Node, expression: string, why: string): void => {
-    found = {
-      node,
-      detail:
-        `\`${expression}\` ${why} Import client-safe modules statically, ` +
-        'or export the predicate from a "use client" module.',
-    };
-  };
-
-  const visit = (node: Node, boundary: Node | null): void => {
-    if (found || !node || typeof node !== "object") return;
-    if (Array.isArray(node)) {
-      for (const item of node) visit(item, boundary);
-      return;
-    }
-    if (typeof node.type !== "string") return;
-    switch (node.type) {
-      case "FunctionExpression":
-      case "FunctionDeclaration":
-        ownArguments.push(node);
-        boundary = node;
-        break;
-      case "ClassBody":
-        boundary = node;
-        break;
-      case "ThisExpression":
-        if (!boundary) capture(node, "this");
-        return;
-      case "Super":
-        if (!boundary || boundary === literal) capture(node, "super");
-        return;
-      case "JSXMemberExpression": {
-        let root = node;
-        while (root.type === "JSXMemberExpression") root = root.object;
-        if (root.name === "this" && !boundary) capture(root, "this");
-        return;
-      }
-      case "MetaProperty":
-        if (node.meta.name === "import") {
-          loads(node, "import.meta", "is the server module's.");
-        } else if (!boundary) {
-          capture(node, "new.target");
-        }
-        return;
-      case "MemberExpression":
-        if (node.object?.type === "MetaProperty") {
-          if (node.object.meta.name !== "import") break;
-          if (!node.computed && node.property.name === "env") return;
-          loads(
-            node,
-            node.computed
-              ? "import.meta[...]"
-              : `import.meta.${node.property.name}`,
-            "is resolved against the server module; only `import.meta.env` " +
-              "is available to an inline predicate.",
-          );
-          return;
-        }
-        break;
-      case "ImportExpression":
-        loads(
-          node,
-          `import(${code.slice(node.source.start, node.source.end)})`,
-          "loads a module at run time, which the build cannot check is " +
-            "client-safe.",
-        );
-        return;
-    }
-    for (const key of Object.keys(node)) {
-      if (key === "type" || key === "start" || key === "end") continue;
-      if (TYPE_KEYS.has(key)) continue;
-      visit(node[key], boundary);
-    }
-  };
-  visit(literal, null);
-  if (found) return found;
-
-  for (const ref of references) {
-    if (ref.typeOnly || ref.node.name !== "arguments") continue;
-    if (ref.node.start < literal.start || ref.node.end > literal.end) continue;
-    const owned = ownArguments.some(
-      (fn) => fn.start <= ref.node.start && ref.node.end <= fn.end,
-    );
-    if (!owned) {
-      capture(ref.node, "arguments");
-      return found;
-    }
-  }
-  return null;
-}
-
 const NODE_BUILTINS = new Set(builtinModules);
 
 /** Specifiers that can never load in the browser. */
@@ -748,7 +156,7 @@ export function isServerOnlySpecifier(source: string): boolean {
   );
 }
 
-export interface HoistTransitionWhenDeps {
+interface HoistTransitionWhenDeps {
   /**
    * Whether an import the literal re-emits is server-only beyond its
    * specifier (the plugin resolves it and looks for `import "server-only"`).
@@ -756,7 +164,7 @@ export interface HoistTransitionWhenDeps {
   isServerOnlyImport?(source: string): Promise<boolean> | boolean;
 }
 
-export interface HoistTransitionWhenResult {
+interface HoistTransitionWhenResult {
   readonly code: string;
   readonly map: ReturnType<MagicString["generateMap"]>;
   /** Virtual module source per hoisted literal, by index. */
@@ -771,16 +179,10 @@ export interface HoistTransitionWhenResult {
 const ROUTER_IMPORT_RE = /["']@rangojs\/router["']/;
 const WHEN_RE = /\bwhen\b/;
 
-function parseLang(file: string): "ts" | "tsx" | "jsx" {
-  // A .ts file parses as ts: tsx would reject `<T>expr` and `<T>(x) => x`.
-  if (/\.[cm]?ts$/.test(file)) return "ts";
-  if (/\.[cm]?jsx?$/.test(file)) return "jsx";
-  return "tsx";
-}
-
 function whenError(file: string, code: string, node: Node, detail: string) {
+  const { line, column } = offsetToLineColumn(code, node.start);
   return new TransitionWhenError(
-    `[rango] transition({ when }) at ${file}:${lineColumn(code, node.start)}: ` +
+    `[rango] transition({ when }) at ${file}:${line}:${column}: ` +
       `\`when\` runs in the browser; ${detail}`,
   );
 }
@@ -804,7 +206,7 @@ export async function hoistTransitionWhens(
   } catch {
     return null;
   }
-  if (hasUseClientDirective(program)) return null;
+  if (hasDirective(program.body, "use client")) return null;
 
   const { moduleScope, references, scopeOf } = analyzeScopes(program);
   const imports = collectImports(program);
@@ -841,78 +243,46 @@ export async function hoistTransitionWhens(
     }
     if (!isFunctionLiteral(value)) continue;
 
-    const lexical = findLexicalCapture(value, references, code);
+    const lexical = findLexicalCapture(
+      value,
+      references,
+      code,
+      WHEN_CAPTURE_MESSAGES,
+    );
     if (lexical) throw whenError(file, code, lexical.node, lexical.detail);
 
-    // Free references of the literal: everything declared outside it.
-    const used = new Map<string, boolean>(); // import local name -> value use
-    for (const ref of references) {
-      if (ref.node.start < value.start || ref.node.end > value.end) continue;
-      const decl = ref.scope.lookup(ref.node.name);
-      if (!decl) continue; // a global (window, URL, console, ...)
-      if (
-        decl.node.start >= value.start &&
-        decl.node.end <= value.end &&
-        decl !== moduleScope
-      ) {
-        continue; // declared inside the literal
-      }
-      if (decl === moduleScope && imports.has(ref.node.name)) {
-        const valueUse = !ref.typeOnly && !imports.get(ref.node.name)!.typeOnly;
-        used.set(ref.node.name, (used.get(ref.node.name) ?? false) || valueUse);
-        continue;
-      }
-      if (ref.typeOnly) continue; // a local type: erased
+    const free = collectFreeReferences(value, references, moduleScope, imports);
+    const binding = free.bindings[0];
+    if (binding) {
       throw whenError(
         file,
         code,
-        ref.node,
-        `\`${ref.node.name}\` is a server-module binding. Read it from ` +
+        binding.node,
+        `\`${binding.node.name}\` is a server-module binding. Read it from ` +
           "`to.params`/`to.state`, or export the predicate from a " +
           '"use client" module.',
       );
     }
 
-    // Re-emit the referenced imports, grouped per source.
-    const bySource = new Map<string, string[]>();
-    for (const [local, valueUse] of used) {
-      const binding = imports.get(local)!;
-      if (valueUse) {
+    const importLines = await emitImports(
+      free.imports,
+      imports,
+      async (local, imported) => {
         if (
-          isServerOnlySpecifier(binding.source) ||
-          (await deps.isServerOnlyImport?.(binding.source))
+          isServerOnlySpecifier(imported.source) ||
+          (await deps.isServerOnlyImport?.(imported.source))
         ) {
           throw whenError(
             file,
             code,
             value,
-            `\`${local}\` is imported from "${binding.source}", a server-only ` +
+            `\`${local}\` is imported from "${imported.source}", a server-only ` +
               "module. Import only client-safe modules into an inline " +
               'predicate, or export it from a "use client" module.',
           );
         }
-      }
-      const lines = bySource.get(binding.source) ?? [];
-      const typePrefix = valueUse ? "" : "type ";
-      if (binding.imported === "*") {
-        lines.push(
-          `import ${typePrefix}* as ${local} from ${JSON.stringify(binding.source)};`,
-        );
-      } else if (binding.imported === "default") {
-        lines.push(
-          `import ${typePrefix}${local} from ${JSON.stringify(binding.source)};`,
-        );
-      } else {
-        const spec =
-          binding.imported === local
-            ? local
-            : `${JSON.stringify(binding.imported)} as ${local}`;
-        lines.push(
-          `import ${typePrefix}{ ${spec} } from ${JSON.stringify(binding.source)};`,
-        );
-      }
-      bySource.set(binding.source, lines);
-    }
+      },
+    );
 
     // A method's FunctionExpression spans from its type parameters or
     // parameters; the async/generator markers sit on the property.
@@ -924,7 +294,7 @@ export async function hoistTransitionWhens(
     modules.push(
       [
         `"use client";`,
-        ...[...bySource.values()].flat(),
+        ...importLines,
         `export const ${EXPORT_NAME} = ${source};`,
         "",
       ].join("\n"),
@@ -946,16 +316,7 @@ export async function hoistTransitionWhens(
   if (modules.length === 0) return null;
 
   // After the directive prologue, so a "use server"/"use strict" stays first.
-  let insertAt = 0;
-  for (const statement of program.body) {
-    if (
-      statement.type !== "ExpressionStatement" ||
-      typeof statement.directive !== "string"
-    ) {
-      break;
-    }
-    insertAt = statement.end;
-  }
+  const insertAt = directivePrologueEnd(program);
   s.appendLeft(insertAt, `${insertAt ? "\n" : ""}${header.join("\n")}\n`);
 
   return {
@@ -964,7 +325,6 @@ export async function hoistTransitionWhens(
     modules,
   };
 }
-
 /** The hoisted module index a `?rango-when=N` id names, or null. */
 export function parseHoistedWhenId(
   id: string,
@@ -979,37 +339,19 @@ export function parseHoistedWhenId(
 
 const SERVER_ONLY_IMPORT_RE = /\bimport\s+["']server-only["']/;
 
-async function readSource(file: string): Promise<string | null> {
-  try {
-    return await readFile(file, "utf-8");
-  } catch {
-    return null;
-  }
-}
-
-/** What the RSC transform emitted for a urls file, and the disk source it saw. */
-interface EmittedWhens {
-  readonly disk: string | null;
-  readonly modules: readonly string[];
-}
-
 /**
  * The plugin: hoists in the RSC environment (where urls() modules are
  * evaluated) and serves the `?rango-when=N` modules in every environment
  * (RSC, SSR and client all load them).
  *
- * `load` serves the modules the transform emitted, not a re-hoist of the file
- * on disk: the transform hoists the pipeline code, which an earlier plugin
- * may have changed, so re-hoisting the disk source can number the literals
- * differently and serve the wrong one for index N. The disk source is the
- * fallback only when the transform has not seen the current file: an
- * environment loading before the RSC transform ran (the order environments
- * ask in is not fixed), or an edit the RSC environment has not re-transformed
- * yet (serving the last transform would then be stale). The map is per
- * plugin instance, so every environment of one dev server or build shares it.
+ * `load` serves the modules the transform emitted (loadEmittedOrDisk), not a
+ * re-hoist of the file on disk: re-hoisting a disk source an earlier plugin
+ * changed can number the literals differently and serve the wrong one for
+ * index N. The map is per plugin instance, so every environment of one dev
+ * server or build shares it.
  */
 export function transitionWhenHoistPlugin(): Plugin {
-  const emitted = new Map<string, EmittedWhens>();
+  const emitted = new Map<string, EmittedEntry<readonly string[]>>();
   return {
     name: "@rangojs/router:transition-when-hoist",
     enforce: "pre",
@@ -1017,15 +359,12 @@ export function transitionWhenHoistPlugin(): Plugin {
     async load(id) {
       const hoisted = parseHoistedWhenId(id);
       if (!hoisted) return;
-      const file = normalizePath(hoisted.file);
-      const disk = await readSource(hoisted.file);
-      const entry = emitted.get(file);
-      const modules =
-        entry && (disk === null || entry.disk === disk)
-          ? entry.modules
-          : disk === null
-            ? undefined
-            : (await hoistTransitionWhens(disk, hoisted.file))?.modules;
+      const modules = await loadEmittedOrDisk(
+        emitted,
+        hoisted.file,
+        async (disk) =>
+          (await hoistTransitionWhens(disk, hoisted.file))?.modules,
+      );
       const module = modules?.[hoisted.index];
       if (module === undefined) {
         throw new TransitionWhenError(
@@ -1039,25 +378,20 @@ export function transitionWhenHoistPlugin(): Plugin {
       if (this.environment?.name !== "rsc") return;
       if (id.includes("/node_modules/") || parseHoistedWhenId(id)) return;
       const file = normalizePath(id.split("?", 1)[0]!);
-      if (!/\.[cm]?[jt]sx?$/.test(file)) return;
+      if (!SOURCE_FILE_RE.test(file)) return;
       emitted.delete(file);
       const result = await hoistTransitionWhens(code, id, {
         isServerOnlyImport: async (source) => {
-          const resolved = await this.resolve(source, id);
-          if (!resolved || resolved.external) return false;
-          const target = resolved.id.split("?", 1)[0]!;
-          if (target.includes("/node_modules/") || target.startsWith("\0")) {
-            return false;
-          }
+          const target = await resolveSourceTarget(this, source, id, {
+            skipNodeModules: true,
+          });
+          if (target === null) return false;
           const text = await readSource(target);
           return text !== null && SERVER_ONLY_IMPORT_RE.test(text);
         },
       });
       if (!result) return;
-      emitted.set(file, {
-        disk: await readSource(file),
-        modules: result.modules,
-      });
+      await recordEmitted(emitted, file, result.modules);
       return { code: result.code, map: result.map };
     },
   };