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

package/src/vite/plugins/expose-internal-ids.ts

@@ -28,6 +28,7 @@ import {
   getImportedFnNames,
   collectCreateExportBindings,
   buildUnsupportedShapeWarning,
+  findUnsupportedCreateCallSites,
   isExportOnlyFile,
 } from "./expose-ids/export-analysis.js";
 import {
@@ -39,7 +40,6 @@ import {
   transformHandles,
   transformLocationState,
   generateWholeFileStubs,
-  generateExprStubs,
   stubHandlerExprs,
   transformHandlerIds,
 } from "./expose-ids/handler-transform.js";
@@ -184,6 +184,16 @@ ${lazyImports.join(",\n")}
     async buildStart() {
       if (!isBuild) return;
 
+      // The loader pre-scan walks and reads the entire project, but the
+      // loaderRegistry it populates is consumed only by the RSC loader-manifest
+      // virtual module (and the transform hook already gates its registry writes
+      // with isRscEnv). plugin-rsc runs ~5 build passes (rsc-scan, ssr-scan, rsc,
+      // client, ssr) over this single shared plugin instance; without this gate
+      // the full-tree I/O ran on every pass with no consumer on the non-RSC
+      // ones. Skip only when the environment is known and not RSC, so an
+      // unavailable environment still falls through (no empty registry).
+      if (this.environment && this.environment.name !== "rsc") return;
+
       const fs = await import("node:fs/promises");
 
       const SKIP_DIRS = new Set(["node_modules", "dist", "build", "coverage"]);
@@ -335,7 +345,7 @@ ${lazyImports.join(",\n")}
           }
           if (_cachedAst !== undefined || _astParseFailed) return _cachedAst;
           try {
-            _cachedAst = parseAst(code, { jsx: true });
+            _cachedAst = parseAst(code, { lang: "tsx" });
           } catch {
             _astParseFailed = true;
           }
@@ -371,14 +381,21 @@ ${lazyImports.join(",\n")}
           if (!hasCode) continue;
 
           const fnNames = getFnNames(cfg.fnName);
-          const totalCalls = countCreateCallsForNames(code, fnNames);
-          const supportedBindings = getBindings(code, fnNames).length;
-          if (totalCalls <= supportedBindings) continue;
+          // Locate the real (comment/string-free) create* calls not covered by
+          // a supported, id-injectable export shape. Empty means every call is
+          // fine — in particular, a create*() token in a comment or string no
+          // longer trips a spurious warning.
+          const sites = findUnsupportedCreateCallSites(
+            code,
+            fnNames,
+            getBindings(code, fnNames),
+          );
+          if (sites.length === 0) continue;
 
           const warnKey = `${id}::${cfg.fnName}`;
           if (unsupportedShapeWarnings.has(warnKey)) continue;
           unsupportedShapeWarnings.add(warnKey);
-          this.warn(buildUnsupportedShapeWarning(filePath, cfg.fnName));
+          this.warn(buildUnsupportedShapeWarning(filePath, cfg.fnName, sites));
         }
 
         // --- Loader: track for manifest (RSC env only) ---
@@ -424,17 +441,6 @@ ${lazyImports.join(",\n")}
           if (wholeFile) return wholeFile;
         }
 
-        // --- PrerenderHandler: RSC build module tracking ---
-        if (hasPrerenderHandlerCode && isRscEnv && isBuild) {
-          const fnNames = getFnNames(PRERENDER_CONFIG.fnName);
-          const exportNames = getBindings(code, fnNames).map(
-            (b) => b.exportNames[0],
-          );
-          if (exportNames.length > 0) {
-            prerenderHandlerModules.set(id, exportNames);
-          }
-        }
-
         // --- Inline handler extraction to virtual modules ---
         // Runs before stubs/tracking so inline calls become imports, then
         // the existing regex fast path handles both the original file's
@@ -710,14 +716,27 @@ ${lazyImports.join(",\n")}
           }
         }
 
-        // --- StaticHandler: RSC build module tracking ---
-        if (hasStaticHandlerCode && isRscEnv && isBuild) {
-          const fnNames = getFnNames(STATIC_CONFIG.fnName);
-          const exportNames = getBindings(code, fnNames).map(
-            (b) => b.exportNames[0],
-          );
-          if (exportNames.length > 0) {
-            staticHandlerModules.set(id, exportNames);
+        // RSC build module tracking (prerender + static), consumed via the
+        // plugin API for prerender freezing. Export-binding sets are invariant
+        // across the inline-extraction loop, so tracking both here is equivalent
+        // to the pre-extraction prerender tracking this replaces.
+        if (isRscEnv && isBuild) {
+          const trackTypes: Array<
+            [boolean, HandlerTransformConfig, Map<string, string[]>]
+          > = [
+            [
+              hasPrerenderHandlerCode,
+              PRERENDER_CONFIG,
+              prerenderHandlerModules,
+            ],
+            [hasStaticHandlerCode, STATIC_CONFIG, staticHandlerModules],
+          ];
+          for (const [has, cfg, trackMap] of trackTypes) {
+            if (!has) continue;
+            const exportNames = getBindings(code, getFnNames(cfg.fnName)).map(
+              (b) => b.exportNames[0],
+            );
+            if (exportNames.length > 0) trackMap.set(id, exportNames);
           }
         }
 
@@ -758,48 +777,19 @@ ${lazyImports.join(",\n")}
               isBuild,
             ) || changed;
         }
-        if (hasPrerenderHandlerCode) {
-          const fnNames = getFnNames(PRERENDER_CONFIG.fnName);
-          const bindings = getBindings(code, fnNames);
-          if (isRscEnv) {
-            changed =
-              transformHandlerIds(
-                PRERENDER_CONFIG,
-                bindings,
-                s,
-                filePath,
-                isBuild,
-              ) || changed;
-          } else {
-            // Non-RSC mixed-export file: replace Prerender() calls with stubs
-            // on the shared MagicString so sourcemaps stay accurate.
-            changed =
-              stubHandlerExprs(
-                PRERENDER_CONFIG,
-                bindings,
-                s,
-                filePath,
-                isBuild,
-              ) || changed;
-          }
-        }
-        if (hasStaticHandlerCode) {
-          const fnNames = getFnNames(STATIC_CONFIG.fnName);
-          const bindings = getBindings(code, fnNames);
-          if (isRscEnv) {
-            changed =
-              transformHandlerIds(
-                STATIC_CONFIG,
-                bindings,
-                s,
-                filePath,
-                isBuild,
-              ) || changed;
-          } else {
-            changed =
-              stubHandlerExprs(STATIC_CONFIG, bindings, s, filePath, isBuild) ||
-              changed;
-          }
+        // Prerender + Static share the RSC inject-id vs non-RSC stub dispatch.
+        // Call sites are disjoint (distinct fnNames), so loop order is irrelevant.
+        const finalHandlerConfigs = [
+          hasPrerenderHandlerCode && PRERENDER_CONFIG,
+          hasStaticHandlerCode && STATIC_CONFIG,
+        ].filter((c): c is HandlerTransformConfig => !!c);
+        for (const cfg of finalHandlerConfigs) {
+          const bindings = getBindings(code, getFnNames(cfg.fnName));
+          changed =
+            (isRscEnv
+              ? transformHandlerIds(cfg, bindings, s, filePath, isBuild)
+              : stubHandlerExprs(cfg, bindings, s, filePath, isBuild)) ||
+            changed;
         }
 
         if (!changed) return;

package/src/vite/plugins/performance-tracks.ts

@@ -48,25 +48,18 @@ export function patchRsdwClientDebugInfoRecovery(code: string): {
 
 export function performanceTracksOptimizeDepsPlugin(): {
   name: string;
-  setup(build: any): void;
+  load(id: string): Promise<{ code: string } | null>;
 } {
+  const RSDW_CLIENT_RE =
+    /react-server-dom-webpack-client\.browser\.(development|production)\.js$/;
   return {
     name: "@rangojs/router:performance-tracks-optimize-deps",
-    setup(build: any): void {
-      build.onLoad(
-        {
-          filter:
-            /react-server-dom-webpack-client\.browser\.(development|production)\.js$/,
-        },
-        async (args: { path: string }) => {
-          const code = await readFile(args.path, "utf8");
-          const patched = patchRsdwClientDebugInfoRecovery(code);
-          return {
-            contents: patched.code,
-            loader: "js",
-          };
-        },
-      );
+    async load(id: string): Promise<{ code: string } | null> {
+      const cleanId = id.split("?")[0] ?? id;
+      if (!RSDW_CLIENT_RE.test(cleanId)) return null;
+      const code = await readFile(cleanId, "utf8");
+      const patched = patchRsdwClientDebugInfoRecovery(code);
+      return { code: patched.code };
     },
   };
 }

package/src/vite/plugins/refresh-cmd.ts

@@ -20,7 +20,7 @@ import type { Plugin } from "vite";
  */
 export function poke(): Plugin {
   return {
-    name: "vite-plugin-poke",
+    name: "@rangojs/router:poke",
     apply: "serve",
 
     configureServer(server) {

package/src/vite/plugins/use-cache-transform.ts

@@ -30,6 +30,8 @@ const CACHE_RUNTIME_IMPORT = "@rangojs/router/cache-runtime";
 // and should not be wrapped (children can't be cache-keyed).
 const LAYOUT_TEMPLATE_PATTERN = /\/(layout|template)\.(tsx?|jsx?)$/;
 
+export const USE_CACHE_DIRECTIVE_RE: RegExp = /^use cache(:\s*[\w-]+)?$/;
+
 export function useCacheTransform(): Plugin {
   let projectRoot = "";
   let isBuild = false;
@@ -65,7 +67,6 @@ export function useCacheTransform(): Plugin {
 
       const start = counter ? performance.now() : 0;
       try {
-        // Lazy-load transform helpers
         if (!rscTransforms) {
           try {
             rscTransforms = await import("@vitejs/plugin-rsc/transforms");
@@ -80,11 +81,10 @@ export function useCacheTransform(): Plugin {
           transformHoistInlineDirective,
         } = rscTransforms;
 
-        // Parse AST
         let ast: any;
         try {
           const { parseAst } = await import("vite");
-          ast = parseAst(code);
+          ast = parseAst(code, { lang: "tsx" });
         } catch {
           return;
         }
@@ -92,7 +92,6 @@ export function useCacheTransform(): Plugin {
         const filePath = normalizePath(path.relative(projectRoot, id));
         const isLayoutOrTemplate = LAYOUT_TEMPLATE_PATTERN.test(id);
 
-        // Check for file-level "use cache"
         if (hasDirective(ast.body, "use cache")) {
           return transformFileLevelUseCache(
             code,
@@ -105,8 +104,6 @@ export function useCacheTransform(): Plugin {
           );
         }
 
-        // Check for function-level "use cache" / "use cache: profileName"
-        // (only if there's no file-level directive but code still contains the string)
         const functionResult = transformFunctionLevelUseCache(
           code,
           ast,
@@ -116,9 +113,6 @@ export function useCacheTransform(): Plugin {
           transformHoistInlineDirective,
         );
 
-        // Always check for near-miss directives, even when valid directives
-        // exist. A file may contain both valid and invalid "use cache" directives
-        // in different functions — the invalid ones should still warn.
         warnOnNearMissDirectives(ast, id, this.warn.bind(this));
 
         if (functionResult) return functionResult;
@@ -138,8 +132,7 @@ function transformFileLevelUseCache(
   isLayoutOrTemplate: boolean,
   transformWrapExport: (typeof import("@vitejs/plugin-rsc/transforms"))["transformWrapExport"],
 ) {
-  // Collect non-function exports to report after wrapping
-  const nonFunctionExports: string[] = [];
+  const unconfirmedExports: string[] = [];
 
   const { exportNames, output } = transformWrapExport(code, ast, {
     runtime: (value: string, name: string) => {
@@ -148,30 +141,38 @@ function transformFileLevelUseCache(
     },
     rejectNonAsyncFunction: false,
     filter: (name: string, meta: { isFunction?: boolean }) => {
-      // Skip default export of layout/template files (they receive children)
       if (name === "default" && isLayoutOrTemplate) return false;
-      // Non-function exports cannot be wrapped with registerCachedFunction
-      if (meta.isFunction === false) {
-        nonFunctionExports.push(name);
+      // isFunction is boolean | undefined: true = confirmed function, false =
+      // confirmed non-function, undefined = cannot tell statically (e.g. a
+      // factory/HOF initializer `const x = makeCached(fn)`). Deliberate policy:
+      // require a confirmed function and reject everything else, including
+      // indeterminate initializers that may be functions at runtime -- rewrite
+      // those as direct async functions. (Pre-#1246 plugin-rsc reported false,
+      // not undefined, here, so === false would wrongly wrap them post-bump.)
+      if (meta.isFunction !== true) {
+        unconfirmedExports.push(name);
         return false;
       }
       return true;
     },
   });
 
-  if (nonFunctionExports.length > 0) {
+  if (unconfirmedExports.length > 0) {
+    const plural = unconfirmedExports.length > 1;
     throw new Error(
-      `[rango:use-cache] File-level "use cache" in ${sourceId} cannot wrap ` +
-        `non-function export${nonFunctionExports.length > 1 ? "s" : ""}: ` +
-        `${nonFunctionExports.map((n) => `"${n}"`).join(", ")}. ` +
-        `Only function exports can be cached. Either remove "use cache" from ` +
-        `the file level and add it inside individual functions, or move the ` +
-        `non-function exports to a separate module.`,
+      `[rango:use-cache] File-level "use cache" in ${sourceId} only wraps ` +
+        `exports that are statically-confirmed functions. ` +
+        `${plural ? "These exports are" : "This export is"} not: ` +
+        `${unconfirmedExports.map((n) => `"${n}"`).join(", ")}. ` +
+        `Declare them directly (export async function foo() {} or ` +
+        `export const foo = async () => {}). A factory or otherwise ` +
+        `statically-indeterminate initializer (export const foo = makeCached(fn)) ` +
+        `is rejected even if it returns a function at runtime -- rewrite it as a ` +
+        `direct async function, or move non-function exports to a separate module.`,
     );
   }
 
   if (exportNames.length === 0) {
-    // Even if no exports were wrapped, strip the directive
     const s = new MagicString(code);
     const directive = findFileLevelDirective(ast);
     if (directive) {
@@ -188,12 +189,10 @@ function transformFileLevelUseCache(
     return;
   }
 
-  // Prepend the import
   output.prepend(
     `import { registerCachedFunction as __rango_registerCachedFunction } from ${JSON.stringify(CACHE_RUNTIME_IMPORT)};\n`,
   );
 
-  // Replace the directive with a comment
   const directive = findFileLevelDirective(ast);
   if (directive) {
     output.overwrite(
@@ -219,7 +218,7 @@ function transformFunctionLevelUseCache(
 ) {
   try {
     const { output, names } = transformHoistInlineDirective(code, ast, {
-      directive: /^use cache(:\s*[\w-]+)?$/,
+      directive: USE_CACHE_DIRECTIVE_RE,
       runtime: (
         value: string,
         name: string,
@@ -237,9 +236,6 @@ function transformFunctionLevelUseCache(
 
     if (names.length === 0) return;
 
-    // Use a top-level import instead of await import() — the hoisted wrapper
-    // may be placed in a non-async context (e.g., inside a synchronous
-    // urls() callback) where await is not allowed.
     output.prepend(
       `import { registerCachedFunction as __rango_registerCachedFunction } from ${JSON.stringify(CACHE_RUNTIME_IMPORT)};\n`,
     );
@@ -254,9 +250,6 @@ function transformFunctionLevelUseCache(
   }
 }
 
-/**
- * Find the file-level "use cache" directive AST node for removal.
- */
 function findFileLevelDirective(
   ast: any,
 ): { start: number; end: number } | null {
@@ -273,23 +266,8 @@ function findFileLevelDirective(
   return null;
 }
 
-/**
- * The valid directive regex (must stay in sync with transformFunctionLevelUseCache).
- */
-const VALID_DIRECTIVE_RE = /^use cache(:\s*[\w-]+)?$/;
-
-/**
- * Regex for near-miss: starts with "use cache:" but has invalid tokens.
- */
 const NEAR_MISS_RE = /^use cache:\s*.+$/;
 
-/**
- * Walk the AST looking for string literals that look like malformed
- * "use cache" directives and emit a Vite warning for each.
- *
- * This catches cases like `"use cache: bad.name"` or `"use cache: "`
- * that the transform regex silently ignores.
- */
 function warnOnNearMissDirectives(
   ast: any,
   fileId: string,
@@ -307,7 +285,7 @@ function warnOnNearMissDirectives(
       if (
         value.startsWith("use cache") &&
         NEAR_MISS_RE.test(value) &&
-        !VALID_DIRECTIVE_RE.test(value)
+        !USE_CACHE_DIRECTIVE_RE.test(value)
       ) {
         const profilePart = value.slice("use cache:".length).trim();
         warn(
@@ -317,7 +295,6 @@ function warnOnNearMissDirectives(
       }
     }
 
-    // Walk into function bodies where directives appear
     for (const key of Object.keys(node)) {
       const child = node[key];
       if (Array.isArray(child)) {

package/src/vite/plugins/vercel-output.ts

@@ -0,0 +1,258 @@
+/**
+ * Vercel Build Output (Build Output API v3) emitter for `preset: "vercel"`.
+ *
+ * After the full app build, restructures dist/ into .vercel/output:
+ *
+ *   .vercel/output/
+ *     config.json                       routing: static first, else the function
+ *     static/                           dist/client (browser assets, served at /)
+ *     functions/<name>.func/
+ *       .vc-config.json                 Node serverless, response streaming
+ *       index.mjs                       bundled launcher (srvx + @vercel/functions)
+ *       rsc/                            dist/rsc (self-contained RSC server bundle)
+ *       ssr/                            dist/ssr (rsc imports ../ssr/index.js)
+ *
+ * A prebuilt .vercel/output gets no `npm install`, so everything the function
+ * imports must physically live inside the .func directory. This relies on two
+ * things the vercel preset arranges (each is a failure only a real deploy — or
+ * the isolated smoke test — catches, since a local in-place run is masked by the
+ * app's own package.json + node_modules up the tree):
+ *
+ *   1. The rsc/ssr builds are fully bundled (`resolve.noExternal`, set in
+ *      rango.ts for this preset). The node default externalizes node_modules
+ *      deps, which works under `vite preview` but leaves bare imports
+ *      (@vercel/functions, react-dom/server.edge, ...) that have no node_modules
+ *      to resolve against on Vercel.
+ *   2. A `package.json` with `"type": "module"` is written into the .func dir.
+ *      The rsc/ssr bundles are ESM but use a `.js` extension; without a
+ *      type:module in scope the deployed (isolated) function loads them as
+ *      CommonJS and fails on the first `import`.
+ *
+ * The launcher is bundled with srvx (the Web->Node streaming bridge, a
+ * @rangojs/router dependency) and @vercel/functions (resolved from the app)
+ * inlined, keeping the RSC bundle a runtime-relative external.
+ *
+ * Timing: this runs in the `buildApp` hook (order "post"), which fires once
+ * after every environment has built, so dist/{client,rsc,ssr} all exist.
+ * closeBundle is unusable here — it fires per environment, and twice for ssr
+ * (the server-reference scan and the real build), so it would run before
+ * dist/client exists. rango's own prerender/static emitters hardcode dist/rsc,
+ * so we build to dist/ and restructure here rather than retargeting outDir.
+ */
+
+import type { Plugin } from "vite";
+import { rm, mkdir, cp, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+import type { RangoVercelOptions } from "../plugin-types.js";
+
+// Minimal structural types for the esbuild API we use, resolved dynamically from
+// the app so @rangojs/router does not depend on esbuild's type package.
+interface EsbuildPluginBuild {
+  onResolve(
+    options: { filter: RegExp },
+    callback: () => { path: string; external: boolean },
+  ): void;
+}
+type EsbuildBuild = (options: Record<string, unknown>) => Promise<unknown>;
+interface EsbuildModule {
+  build?: EsbuildBuild;
+  default?: { build?: EsbuildBuild };
+}
+
+const LAUNCHER_SOURCE = `import { toNodeHandler } from "srvx/node";
+import { waitUntil } from "@vercel/functions";
+import rscHandler from "./rsc/index.js";
+
+// The Vercel Node launcher invokes a Node (req, res) handler, not a Web fetch
+// handler. srvx's toNodeHandler bridges the Rango Web fetch handler and pipes
+// the streamed Response to the Node response (set supportsResponseStreaming).
+const onVercel = Boolean(process.env.VERCEL);
+
+const fetchHandler = (request) =>
+  rscHandler(request, {
+    env: process.env,
+    // Forward Vercel's waitUntil so cache writes / revalidation run off the
+    // response path. Omitted off-platform so those writes settle inline.
+    ctx: onVercel ? { waitUntil } : undefined,
+  });
+
+export default toNodeHandler(fetchHandler);
+`;
+
+async function assemble(
+  root: string,
+  options: RangoVercelOptions,
+): Promise<void> {
+  const dist = join(root, "dist");
+  for (const dir of ["client", "rsc", "ssr"]) {
+    if (!existsSync(join(dist, dir))) {
+      throw new Error(
+        `[rango] preset "vercel": missing dist/${dir}. Run the production build first.`,
+      );
+    }
+  }
+
+  const vercel = options.vercel ?? {};
+  const functionName = vercel.functionName ?? "index";
+  const out = join(root, ".vercel", "output");
+  const funcDir = join(out, "functions", `${functionName}.func`);
+
+  await rm(out, { recursive: true, force: true });
+  await mkdir(funcDir, { recursive: true });
+
+  // 1. Static client assets -> served from the CDN at the root.
+  await cp(join(dist, "client"), join(out, "static"), { recursive: true });
+
+  // 2. Server bundle into the function. Preserve the rsc -> ../ssr/index.js
+  //    relative import by mirroring the dist/{rsc,ssr} layout inside the func.
+  await cp(join(dist, "rsc"), join(funcDir, "rsc"), { recursive: true });
+  await cp(join(dist, "ssr"), join(funcDir, "ssr"), { recursive: true });
+
+  // Prerender/static payload manifests (present only when routes are prerendered).
+  if (existsSync(join(dist, "static"))) {
+    await cp(join(dist, "static"), join(funcDir, "static"), {
+      recursive: true,
+    });
+  }
+
+  // 3. Bundle the Node launcher. srvx (a @rangojs/router dependency) is aliased
+  //    to its resolved path; @vercel/functions resolves from the app; the RSC
+  //    server bundle stays a runtime-relative external.
+  const rangoRequire = createRequire(import.meta.url);
+  let srvxNodePath: string;
+  try {
+    srvxNodePath = rangoRequire.resolve("srvx/node");
+  } catch {
+    throw new Error(
+      '[rango] preset "vercel" requires "srvx" (a dependency of @rangojs/router). Reinstall dependencies.',
+    );
+  }
+
+  // esbuild ships with Vite; resolve it from the app so we never add it as a
+  // @rangojs/router dependency. Minimal structural types avoid coupling to
+  // esbuild's type package at compile time.
+  const appRequire = createRequire(join(root, "package.json"));
+  let esbuildModule: EsbuildModule;
+  try {
+    esbuildModule = (await import(
+      pathToFileURL(appRequire.resolve("esbuild")).href
+    )) as EsbuildModule;
+  } catch {
+    throw new Error(
+      '[rango] preset "vercel" requires "esbuild" to bundle the function launcher. It ships with Vite; reinstall dependencies.',
+    );
+  }
+  const esbuildBuild = esbuildModule.build ?? esbuildModule.default?.build;
+  if (typeof esbuildBuild !== "function") {
+    throw new Error('[rango] preset "vercel": could not load esbuild.build.');
+  }
+
+  try {
+    await esbuildBuild({
+      stdin: {
+        contents: LAUNCHER_SOURCE,
+        resolveDir: root,
+        sourcefile: "func-entry.mjs",
+        loader: "js",
+      },
+      outfile: join(funcDir, "index.mjs"),
+      bundle: true,
+      format: "esm",
+      platform: "node",
+      target: "node18",
+      alias: { "srvx/node": srvxNodePath },
+      plugins: [
+        {
+          name: "external-rsc-entry",
+          setup(b: EsbuildPluginBuild) {
+            b.onResolve({ filter: /^\.\/rsc\/index\.js$/ }, () => ({
+              path: "./rsc/index.js",
+              external: true,
+            }));
+          },
+        },
+      ],
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (/@vercel\/functions/.test(message)) {
+      throw new Error(
+        '[rango] preset "vercel": could not resolve "@vercel/functions". Add it to your app dependencies (it also backs VercelCacheStore).\n' +
+          message,
+      );
+    }
+    throw error;
+  }
+
+  // 3b. Mark the function as ESM. The rsc/ssr bundles are .js ESM files with no
+  //     package.json in scope on the deployed function (it is isolated at
+  //     /var/task), so Node would load them as CommonJS and fail on `import`.
+  //     Locally this is masked because the func inherits the app's
+  //     "type": "module" up the tree; the deployed func has nothing above it.
+  await writeFile(
+    join(funcDir, "package.json"),
+    JSON.stringify({ type: "module" }, null, 2) + "\n",
+  );
+
+  // 4. Function config: Node serverless with response streaming.
+  const vcConfig: Record<string, unknown> = {
+    runtime: vercel.runtime ?? "nodejs22.x",
+    handler: "index.mjs",
+    launcherType: "Nodejs",
+    shouldAddHelpers: false,
+    supportsResponseStreaming: true,
+    maxDuration: vercel.maxDuration ?? 30,
+  };
+  if (vercel.memory != null) vcConfig.memory = vercel.memory;
+  if (vercel.regions != null) vcConfig.regions = vercel.regions;
+  await writeFile(
+    join(funcDir, ".vc-config.json"),
+    JSON.stringify(vcConfig, null, 2) + "\n",
+  );
+
+  // 5. Routing: filesystem (static/) first, then everything to the function.
+  await writeFile(
+    join(out, "config.json"),
+    JSON.stringify(
+      {
+        version: 3,
+        routes: [
+          { handle: "filesystem" },
+          { src: "/(.*)", dest: `/${functionName}` },
+        ],
+      },
+      null,
+      2,
+    ) + "\n",
+  );
+
+  console.log(
+    `[rango] assembled .vercel/output (function: ${functionName}.func)`,
+  );
+}
+
+export function createVercelOutputPlugin(options: RangoVercelOptions): Plugin {
+  let root = process.cwd();
+  let isBuild = false;
+  return {
+    name: "@rangojs/router:vercel-output",
+    configResolved(config) {
+      root = resolve(config.root);
+      isBuild = config.command === "build";
+    },
+    // buildApp runs once after the whole multi-environment build (rsc, client,
+    // ssr), so dist/ is complete here. closeBundle is unusable for this: it
+    // fires per environment, and twice for ssr (the server-reference scan and
+    // the real build), so it would run before dist/client exists.
+    buildApp: {
+      order: "post",
+      async handler() {
+        if (!isBuild) return;
+        await assemble(root, options);
+      },
+    },
+  };
+}