@rangojs/router 0.0.0-experimental.98 → 0.0.0-experimental.98914650

package/src/vite/router-discovery.ts

@@ -16,7 +16,9 @@ import {
   formatNestedRouterConflictError,
   findNestedRouterConflict,
   findRouterFiles,
+  createScanFilter,
 } from "../build/generate-route-types.js";
+import { firstCodeMatchIndex } from "../build/route-types/source-scan.js";
 import { createVersionPlugin } from "./plugins/version-plugin.js";
 import { createVirtualStubPlugin } from "./plugins/virtual-stub-plugin.js";
 import {
@@ -52,6 +54,11 @@ import {
 import { postprocessBundle } from "./discovery/bundle-postprocess.js";
 import { createDiscoveryGate } from "./discovery/gate-state.js";
 import { resetStagedBuildAssets } from "./utils/prerender-utils.js";
+import { resolveRscEntryFromConfig } from "./utils/shared-utils.js";
+import {
+  pickForwardedRunnerConfig,
+  selectForwardableResolvePlugins,
+} from "./utils/forward-user-plugins.js";
 import { createRangoDebugger, timed, timedSync, NS } from "./debug.js";
 
 const debugDiscovery = createRangoDebugger(NS.discovery);
@@ -99,7 +106,7 @@ function ensureCloudflareProtocolLoaderRegistered(): void {
     // register() requires Node 18.19+ / 20.6+. Older Node still has the
     // Vite transform as primary defense.
     console.warn(
-      `[rsc-router] Could not register Node ESM loader hook for cloudflare:* imports (${err?.message ?? err}). Falling back to Vite transform only.`,
+      `[rango] Could not register Node ESM loader hook for cloudflare:* imports (${err?.message ?? err}). Falling back to Vite transform only.`,
     );
   }
 }
@@ -129,14 +136,26 @@ async function createTempRscServer(
   // instead of crashing Node's native loader.
   ensureCloudflareProtocolLoaderRegistered();
   const { default: rsc } = await import("@vitejs/plugin-rsc");
+  // Mirror the user's resolution config + plugins so discovery (and the
+  // prerender/static rendering that shares this runner) resolves modules the
+  // same way the real environment does. Falls back to the legacy alias-only
+  // behavior if configResolved hasn't populated the parity slice yet.
+  const runnerConfig = state.userRunnerConfig;
+  const resolveConfig = runnerConfig?.resolve ?? {
+    alias: state.userResolveAlias,
+  };
+  const oxcConfig = runnerConfig?.oxc ?? {
+    jsx: { runtime: "automatic", importSource: "react" },
+  };
   return createViteServer({
     root: state.projectRoot,
     configFile: false,
     server: { middlewareMode: true },
     appType: "custom",
     logLevel: "silent",
-    resolve: { alias: state.userResolveAlias },
-    esbuild: { jsx: "automatic", jsxImportSource: "react" },
+    resolve: resolveConfig,
+    ...(runnerConfig?.define ? { define: runnerConfig.define } : {}),
+    oxc: oxcConfig as any,
     ...(options.cacheDir && { cacheDir: options.cacheDir }),
     plugins: [
       rsc({
@@ -155,6 +174,10 @@ async function createTempRscServer(
       // runtime. forceBuild produces hashed IDs for production bundle consistency.
       exposeInternalIds(options.forceBuild ? { forceBuild: true } : undefined),
       exposeRouterId(),
+      // Forwarded user resolution plugins (e.g. vite-tsconfig-paths). Stripped
+      // to resolveId/load and placed last so framework resolution runs first;
+      // Vite re-sorts by `enforce`, so `enforce: "pre"` resolvers still lead.
+      ...state.userResolvePlugins,
     ],
   });
 }
@@ -182,7 +205,7 @@ async function resolveBuildEnv(
   if (option === "auto") {
     if (factoryCtx.preset !== "cloudflare") {
       throw new Error(
-        '[rsc-router] buildEnv: "auto" is only supported with preset: "cloudflare". ' +
+        '[rango] buildEnv: "auto" is only supported with preset: "cloudflare". ' +
           "Use a factory function or plain object for other presets.",
       );
     }
@@ -204,7 +227,7 @@ async function resolveBuildEnv(
       };
     } catch (err: any) {
       throw new Error(
-        '[rsc-router] buildEnv: "auto" requires wrangler to be installed.\n' +
+        '[rango] buildEnv: "auto" requires wrangler to be installed.\n' +
           `Install it with: pnpm add -D wrangler\n${err.message}`,
       );
     }
@@ -256,7 +279,7 @@ async function releaseBuildEnv(s: DiscoveryState): Promise<void> {
     try {
       await s.buildEnvDispose();
     } catch (err: any) {
-      console.warn(`[rsc-router] buildEnv dispose failed: ${err.message}`);
+      console.warn(`[rango] buildEnv dispose failed: ${err.message}`);
     }
     s.buildEnvDispose = null;
   }
@@ -304,28 +327,39 @@ export function createRouterDiscoveryPlugin(
 
     configResolved(config) {
       s.projectRoot = config.root;
+      // Compile the optional discovery scan filter (glob include/exclude) now
+      // that the project root is known. findRouterFiles() below — and the
+      // build/HMR rediscovery paths — honor s.scanFilter.
+      s.scanFilter = opts?.discovery
+        ? createScanFilter(s.projectRoot, opts.discovery)
+        : undefined;
       s.isBuildMode = config.command === "build";
       viteCommand = config.command as "serve" | "build";
       viteMode = config.mode;
       // Capture user's resolve aliases for the temp server
       s.userResolveAlias = config.resolve.alias;
+      // Capture the data-only resolution config (resolve.*, define, oxc) and
+      // the user's resolution plugins (resolveId/load) so the discovery temp
+      // server resolves modules the same way the real environment does.
+      // Without this, both flavors of user resolution are absent during
+      // discovery/prerender/static rendering even though they apply at request
+      // time: third-party resolvers (e.g. vite-tsconfig-paths, forwarded as
+      // plugins) and Vite 8's native resolve.tsconfigPaths (forwarded in the
+      // data slice). See utils/forward-user-plugins.ts.
+      s.userRunnerConfig = pickForwardedRunnerConfig(config);
+      s.userResolvePlugins = selectForwardableResolvePlugins(
+        config.plugins as any,
+      );
       // Node preset: pick up auto-discovered router path from the config() hook.
       // The auto-discover plugin runs in config() using Vite's resolved root,
       // populating the mutable ref before configResolved fires.
       if (!s.resolvedEntryPath && opts?.routerPathRef?.path) {
         s.resolvedEntryPath = opts.routerPathRef.path;
       }
-      // Cloudflare preset: read entry from resolved environment config.
-      // The @cloudflare/vite-plugin reads wrangler config (toml/json/jsonc)
-      // and sets optimizeDeps.entries on the RSC environment.
+      // Cloudflare preset: entry comes from the resolved RSC env config.
       if (!s.resolvedEntryPath) {
-        const rscEnvConfig = (config.environments as any)?.["rsc"];
-        const entries = rscEnvConfig?.optimizeDeps?.entries;
-        if (typeof entries === "string") {
-          s.resolvedEntryPath = entries;
-        } else if (Array.isArray(entries) && entries.length > 0) {
-          s.resolvedEntryPath = entries[0];
-        }
+        const entry = resolveRscEntryFromConfig(config);
+        if (entry) s.resolvedEntryPath = entry;
       }
       // Generate combined named-routes.gen.ts from static source parsing.
       // Runs before the dev server starts so the gen file exists immediately for IDE.
@@ -397,7 +431,8 @@ export function createRouterDiscoveryPlugin(
         releaseBuildEnv(s).catch(() => {});
       });
 
-      // Mirror the build-path contract (router-discovery.ts ~line 878):
+      // Mirror the build-path contract (the buildStart hook below, which sets
+      // __rscRouterDiscoveryActive before running user modules):
       // set __rscRouterDiscoveryActive before running user modules so any
       // module-level router.reverse() calls return a placeholder instead
       // of throwing. The temp Vite server's module runner has its own
@@ -512,9 +547,7 @@ export function createRouterDiscoveryPlugin(
             "getOrCreateTempServer: FAILED message=%s",
             err.message,
           );
-          console.warn(
-            `[rsc-router] Failed to create temp runner: ${err.message}`,
-          );
+          console.warn(`[rango] Failed to create temp runner: ${err.message}`);
         }
         return null;
       }
@@ -653,7 +686,7 @@ export function createRouterDiscoveryPlugin(
             }
           } catch (err: any) {
             console.warn(
-              `[rsc-router] Cloudflare dev discovery failed: ${err.message}\n${err.stack}`,
+              `[rango] Cloudflare dev discovery failed: ${err.message}\n${err.stack}`,
             );
           }
 
@@ -705,7 +738,7 @@ export function createRouterDiscoveryPlugin(
           );
         } catch (err: any) {
           console.warn(
-            `[rsc-router] Router discovery failed: ${err.message}\n${err.stack}`,
+            `[rango] Router discovery failed: ${err.message}\n${err.stack}`,
           );
         } finally {
           debugDiscovery?.(
@@ -764,20 +797,15 @@ export function createRouterDiscoveryPlugin(
         if (s.mergedRouteTrie && serverMod.setRouteTrie) {
           serverMod.setRouteTrie(s.mergedRouteTrie);
         }
-        if (serverMod.setRouterManifest) {
-          for (const [routerId, manifest] of s.perRouterManifestDataMap) {
-            serverMod.setRouterManifest(routerId, manifest);
-          }
-        }
-        if (serverMod.setRouterTrie) {
-          for (const [routerId, trie] of s.perRouterTrieMap) {
-            serverMod.setRouterTrie(routerId, trie);
-          }
-        }
-        if (serverMod.setRouterPrecomputedEntries) {
-          for (const [routerId, entries] of s.perRouterPrecomputedMap) {
-            serverMod.setRouterPrecomputedEntries(routerId, entries);
-          }
+        const perRouterSetters: Array<[Map<string, any>, string]> = [
+          [s.perRouterManifestDataMap, "setRouterManifest"],
+          [s.perRouterTrieMap, "setRouterTrie"],
+          [s.perRouterPrecomputedMap, "setRouterPrecomputedEntries"],
+        ];
+        for (const [map, fn] of perRouterSetters) {
+          const setter = serverMod[fn];
+          if (typeof setter !== "function") continue;
+          for (const [routerId, value] of map) setter(routerId, value);
         }
       };
 
@@ -820,7 +848,7 @@ export function createRouterDiscoveryPlugin(
             registry = serverMod.RouterRegistry ?? null;
           } catch (err: any) {
             console.warn(
-              `[rsc-router] Dev prerender module refresh failed: ${err.message}`,
+              `[rango] Dev prerender module refresh failed: ${err.message}`,
             );
             res.statusCode = 500;
             res.end(`Prerender handler error: ${err.message}`);
@@ -873,10 +901,9 @@ export function createRouterDiscoveryPlugin(
             if (wantIntercept && result.interceptSegments?.length) {
               payload = {
                 segments: [...result.segments, ...result.interceptSegments],
-                handles: {
-                  ...result.handles,
-                  ...(result.interceptHandles || {}),
-                },
+                // Pre-encoded MERGED handle string from the producer (handles are
+                // Flight-encoded so Promise/ReactNode values survive the wire).
+                handles: result.interceptHandles ?? "",
               };
             } else {
               payload = { segments: result.segments, handles: result.handles };
@@ -886,7 +913,7 @@ export function createRouterDiscoveryPlugin(
             return;
           } catch (err: any) {
             console.warn(
-              `[rsc-router] Dev prerender failed for ${pathname}: ${err.message}`,
+              `[rango] Dev prerender failed for ${pathname}: ${err.message}`,
             );
           }
         }
@@ -987,9 +1014,34 @@ export function createRouterDiscoveryPlugin(
                   writeRouteTypesFiles(s),
                 );
               }
+              if (s.lastDiscoveryError) {
+                debugDiscovery?.(
+                  "hmr: cleared lastDiscoveryError (%s) after successful rediscovery",
+                  s.lastDiscoveryError.message,
+                );
+                s.lastDiscoveryError = null;
+              }
+              // Cloudflare dev: on a successful cycle drop the workerd runner's
+              // cached worker-entry chain so the next request re-evaluates
+              // createRouter() with the new routes. Fired here in the work path
+              // (not the caller's .then()) so a queued follow-up cycle that
+              // succeeds after an earlier failed cycle still reloads:
+              // runRefreshCycle recurses queued work without awaiting it, so the
+              // original call already resolved on the failed cycle. A failed
+              // cycle throws above and never reaches here, so a broken edit
+              // never reloads the worker onto bad source.
+              if (rscEnv && !rscEnv.runner) forceCloudflareWorkerReload(rscEnv);
             } catch (err: any) {
+              s.lastDiscoveryError = {
+                message: err?.message ?? String(err),
+                at: Date.now(),
+              };
               console.warn(
-                `[rsc-router] Runtime re-discovery failed: ${err.message}`,
+                `[rango] Runtime re-discovery failed: ${err.message}`,
+              );
+              debugDiscovery?.(
+                "hmr: lastDiscoveryError set (%s) — manifest preserved at last-good; recovery mode active (any in-scan source change will trigger rediscovery)",
+                err?.message,
               );
             } finally {
               debugDiscovery?.(
@@ -1000,6 +1052,49 @@ export function createRouterDiscoveryPlugin(
           });
         };
 
+        // Cloudflare dev only. workerd serves every request through the
+        // runner-worker singleton, which re-resolves the worker entry per
+        // request via runner.import("virtual:cloudflare/worker-entry"). The
+        // route table lives in the user's createRouter() instance, captured
+        // when that entry chain (entry -> router -> urls) was last evaluated
+        // and then cached in the runner's evaluatedModules. The route-file
+        // watcher refreshes discovery + types on the Node side, but the worker
+        // keeps serving the cached (stale) router: route-definition modules
+        // have no import.meta.hot boundary, so Vite never sends the worker an
+        // HMR update for them and the entry chain is never evicted.
+        //
+        // Fix: after discovery completes, (1) invalidate the worker env's
+        // Node-side module graph, then (2) send a full-reload to the worker.
+        // Step (2) alone is insufficient: the full-reload handler clears the
+        // runner's evaluatedModules and re-imports entrypoints, but each
+        // re-import fetches the module back through this Node-side graph, which
+        // still holds the pre-edit transform of urls.tsx — so createRouter()
+        // rebuilds the stale route table and the new route 404s/hits the
+        // catch-all. Invalidating the graph forces a fresh transform on
+        // re-fetch (the same mechanism refreshTempRscEnv uses for discovery),
+        // so the re-import re-runs createRouter() with the new routes. This is
+        // the programmatic equivalent of the dev-server "r + enter" restart,
+        // scoped to the worker environment instead of tearing down the server.
+        const forceCloudflareWorkerReload = (rscEnv: any) => {
+          if (!rscEnv?.hot) return;
+          try {
+            const graph = rscEnv.moduleGraph;
+            if (graph?.invalidateAll) {
+              graph.invalidateAll();
+              debugDiscovery?.("hmr: invalidated workerd rsc module graph");
+            }
+            rscEnv.hot.send({ type: "full-reload" });
+            debugDiscovery?.(
+              "hmr: forced workerd rsc env reload (full-reload)",
+            );
+          } catch (err: any) {
+            debugDiscovery?.(
+              "hmr: workerd reload failed: %s",
+              err?.message ?? err,
+            );
+          }
+        };
+
         const scheduleRouteRegeneration = () => {
           clearTimeout(routeChangeTimer);
           routeChangeTimer = setTimeout(() => {
@@ -1028,9 +1123,7 @@ export function createRouterDiscoveryPlugin(
                 }
               }
             } catch (err: any) {
-              console.error(
-                `[rsc-router] Route regeneration error: ${err.message}`,
-              );
+              console.error(`[rango] Route regeneration error: ${err.message}`);
             }
             debugDiscovery?.(
               "watcher: regenerated gen files (%sms)",
@@ -1040,12 +1133,15 @@ export function createRouterDiscoveryPlugin(
             // routes that the static parser cannot resolve. Resolves the
             // discovery gate when complete.
             if (s.perRouterManifests.length > 0) {
+              // The cloudflare workerd reload fires inside refreshRuntimeDiscovery
+              // on the successful cycle (see forceCloudflareWorkerReload call
+              // there) so queued follow-up cycles also trigger it.
               refreshRuntimeDiscovery().catch((err: any) => {
                 console.warn(
-                  `[rsc-router] Runtime re-discovery error: ${err.message}`,
+                  `[rango] Runtime re-discovery error: ${err.message}`,
                 );
-                // Even on error, unblock the gate so workerd's reload
-                // doesn't hang indefinitely against the previous manifest.
+                // Even on error, unblock the gate so workerd's reload doesn't
+                // hang indefinitely against the previous manifest.
                 resolveDiscoveryGate();
               });
             }
@@ -1059,27 +1155,74 @@ export function createRouterDiscoveryPlugin(
             !filePath.endsWith(".tsx") &&
             !filePath.endsWith(".js") &&
             !filePath.endsWith(".jsx")
-          )
+          ) {
+            if (s.lastDiscoveryError) {
+              debugDiscovery?.(
+                "watcher: skip non-source %s [LASTERR %s]",
+                filePath,
+                s.lastDiscoveryError.message,
+              );
+            }
             return;
+          }
           // Apply scan filter as early-exit before reading file
-          if (s.scanFilter && !s.scanFilter(filePath)) return;
+          if (s.scanFilter && !s.scanFilter(filePath)) {
+            if (s.lastDiscoveryError) {
+              debugDiscovery?.(
+                "watcher: skip scan-filter %s [LASTERR %s]",
+                filePath,
+                s.lastDiscoveryError.message,
+              );
+            }
+            return;
+          }
+          // Recovery mode: when the previous HMR re-discovery failed, the
+          // import graph is incomplete and the manifest is stuck at the
+          // last-good state. The fix may land in a non-route file (e.g. a
+          // helper imported by the router, a missing module being created,
+          // or a "use client" component) that the narrow content sniff
+          // would otherwise filter out. While in recovery, treat any
+          // in-scan source change as a candidate for rediscovery; the
+          // tighter filter resumes once discovery succeeds again.
+          const inRecoveryMode = !!s.lastDiscoveryError;
           try {
             const source = readFileSync(filePath, "utf-8");
             const trimmed = source.trimStart();
-            if (
+            const isUseClient =
               trimmed.startsWith('"use client"') ||
-              trimmed.startsWith("'use client'")
-            )
-              return;
-            const hasUrls = source.includes("urls(");
-            const hasCreateRouter = /\bcreateRouter\s*[<(]/.test(source);
-            if (!hasUrls && !hasCreateRouter) return;
-            debugDiscovery?.(
-              "watcher: %s matches (urls=%s, router=%s)",
-              filePath,
-              hasUrls,
-              hasCreateRouter,
-            );
+              trimmed.startsWith("'use client'");
+            if (!inRecoveryMode && isUseClient) return;
+            // Cheap raw pre-check first; only when a candidate token is present
+            // do we confirm it occurs in real code (not a comment/string) via a
+            // single allocation-free code-region scan. Most saved files contain
+            // neither token and skip the scan entirely. This avoids a comment or
+            // string mention spuriously marking a file relevant and triggering an
+            // unnecessary re-discovery on save.
+            let hasUrls = source.includes("urls(");
+            let hasCreateRouter = /\bcreateRouter\s*[<(]/.test(source);
+            if (hasUrls) hasUrls = firstCodeMatchIndex(source, /urls\(/g) >= 0;
+            if (hasCreateRouter) {
+              hasCreateRouter =
+                firstCodeMatchIndex(source, /\bcreateRouter\s*[<(]/g) >= 0;
+            }
+            if (!inRecoveryMode && !hasUrls && !hasCreateRouter) return;
+            if (inRecoveryMode) {
+              debugDiscovery?.(
+                "watcher: recovery rediscovery for %s (urls=%s, router=%s, useClient=%s) [LASTERR %s]",
+                filePath,
+                hasUrls,
+                hasCreateRouter,
+                isUseClient,
+                s.lastDiscoveryError!.message,
+              );
+            } else {
+              debugDiscovery?.(
+                "watcher: %s matches (urls=%s, router=%s)",
+                filePath,
+                hasUrls,
+                hasCreateRouter,
+              );
+            }
             // Invalidate cache when a router file changes (new router added/removed)
             if (hasCreateRouter) {
               const nestedRouterConflict = findNestedRouterConflict([
@@ -1106,7 +1249,15 @@ export function createRouterDiscoveryPlugin(
               gate.noteRouteEvent();
             }
             scheduleRouteRegeneration();
-          } catch {
+          } catch (readErr: any) {
+            if (s.lastDiscoveryError) {
+              debugDiscovery?.(
+                "watcher: read error %s: %s [LASTERR %s]",
+                filePath,
+                readErr?.message,
+                s.lastDiscoveryError.message,
+              );
+            }
             // Ignore read errors for deleted/moved files
           }
         };
@@ -1169,7 +1320,7 @@ export function createRouterDiscoveryPlugin(
         const rscEnv = (tempServer.environments as any)?.rsc;
         if (!rscEnv?.runner) {
           console.warn(
-            "[rsc-router] RSC environment runner not available during build, skipping manifest generation",
+            "[rango] RSC environment runner not available during build, skipping manifest generation",
           );
           return;
         }
@@ -1212,7 +1363,8 @@ export function createRouterDiscoveryPlugin(
           .filter(Boolean)
           .join("\n");
         throw new Error(
-          `[rsc-router] Build-time router discovery failed:\n${details}`,
+          `[rango] Build-time router discovery failed:\n${details}`,
+          { cause: err },
         );
       } finally {
         delete (globalThis as any).__rscRouterDiscoveryActive;
@@ -1239,7 +1391,7 @@ export function createRouterDiscoveryPlugin(
     // `consumeSelfGenWrite` inside `maybeHandleGeneratedRouteFileMutation`),
     // AND vite's own HMR pipeline (which invalidates the gen file's
     // importers and triggers a second workerd full reload — visible to the
-    // user as a duplicate "[RSCRouter] HMR: version changed" on the client).
+    // user as a duplicate "[Rango] HMR: version changed" on the client).
     //
     // `peekSelfGenWrite` is the authoritative filter: its map only contains
     // paths that `markSelfGenWrite` has registered, so it natively works

package/src/vite/utils/ast-handler-extract.ts

@@ -1,10 +1,6 @@
 import type MagicString from "magic-string";
 import { hashInlineId, buildExportMap } from "../plugins/expose-id-utils.js";
 
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
 /** Minimal ESTree Program node — avoids importing from `rollup` (not a direct dep). */
 interface ProgramNode {
   type: "Program";
@@ -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.
@@ -111,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)
@@ -127,7 +115,7 @@ export function findHandlerCalls(
 ): HandlerCallSite[] {
   let program: ProgramNode;
   try {
-    program = parseAst(code, { jsx: true });
+    program = parseAst(code, { lang: "tsx" });
   } catch {
     return [];
   }
@@ -239,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>();
@@ -256,7 +244,7 @@ export function extractImportDeclarations(
 ): string[] {
   let program: ProgramNode;
   try {
-    program = parseAst(code, { jsx: true });
+    program = parseAst(code, { lang: "tsx" });
   } catch {
     return [];
   }
@@ -380,7 +368,7 @@ export function extractModuleLevelDeclarations(
 ): string[] {
   let program: ProgramNode;
   try {
-    program = parseAst(code, { jsx: true });
+    program = parseAst(code, { lang: "tsx" });
   } catch {
     return [];
   }
@@ -426,10 +414,6 @@ export function extractModuleLevelDeclarations(
   return declarations;
 }
 
-// ---------------------------------------------------------------------------
-// Transform
-// ---------------------------------------------------------------------------
-
 /**
  * Transform inline handler calls by extracting them into virtual modules.
  * Only processes inline calls (exportInfo === null); export const calls are
@@ -468,19 +452,19 @@ export function transformInlineHandlers(
     handlerNames,
   );
 
-  // Track line occurrences for same-line collision handling
-  const lineCounts = new Map<number, number>();
-
   // 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);
@@ -498,7 +482,7 @@ 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}` : ""}`;
+    const importId = `${virtualPrefix}${idSuffix}`;
     importStatements.push(`import { ${exportName} } from "${importId}";`);
   }