@rangojs/router 0.0.0-experimental.d7eeaa75 → 0.0.0-experimental.d98a8e9d

package/src/vite/discovery/route-types-writer.ts

@@ -5,13 +5,15 @@
  * from discovered router manifests and static source parsing.
  */
 
-import { dirname, basename, join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { readFileSync, writeFileSync, existsSync, unlinkSync } from "node:fs";
 import {
   generateRouteTypesSource,
   writeCombinedRouteTypes,
   findRouterFiles,
   buildCombinedRouteMapForRouterFile,
+  genFileTsPath,
+  resolveSearchSchemas,
 } from "../../build/generate-route-types.js";
 import type { DiscoveryState } from "./state.js";
 import { markSelfGenWrite } from "./self-gen-tracking.js";
@@ -35,6 +37,22 @@ function filterUserNamedRoutes(
   return filtered;
 }
 
+// Write a gen file only when content changed, marking the write as
+// self-generated BEFORE writeFileSync so the watcher distinguishes it from a
+// manual edit (the HMR self-gen-loop guard).
+function writeGenFileIfChanged(
+  state: DiscoveryState,
+  outPath: string,
+  source: string,
+  opts?: { log?: boolean },
+): void {
+  const existing = existsSync(outPath) ? readFileSync(outPath, "utf-8") : null;
+  if (existing === source) return;
+  markSelfGenWrite(state, outPath, source);
+  writeFileSync(outPath, source);
+  if (opts?.log) console.log(`[rango] Generated route types -> ${outPath}`);
+}
+
 /**
  * Write combined route types for all router files.
  * Only writes when content has changed to avoid triggering HMR loops.
@@ -48,45 +66,16 @@ export function writeCombinedRouteTypesWithTracking(
     findRouterFiles(state.projectRoot, state.scanFilter);
   state.cachedRouterFiles = routerFiles;
 
-  // Snapshot pre-write content to detect which files actually change.
-  const preContent = new Map<string, string>();
-  for (const routerFilePath of routerFiles) {
-    const routerDir = dirname(routerFilePath);
-    const routerBasename = basename(routerFilePath).replace(
-      /\.(tsx?|jsx?)$/,
-      "",
-    );
-    const outPath = join(routerDir, `${routerBasename}.named-routes.gen.ts`);
-    try {
-      preContent.set(outPath, readFileSync(outPath, "utf-8"));
-    } catch {
-      // File doesn't exist yet — any write is a real change.
-    }
-  }
-
-  writeCombinedRouteTypes(state.projectRoot, routerFiles, opts);
-
-  // Mark only files that were actually written so the watcher can
-  // distinguish self-triggered change events from manual edits.
-  // Marking unchanged files creates stale entries that interfere with
-  // multi-server setups (e.g. shared webServer + isolated HMR server).
-  for (const routerFilePath of routerFiles) {
-    const routerDir = dirname(routerFilePath);
-    const routerBasename = basename(routerFilePath).replace(
-      /\.(tsx?|jsx?)$/,
-      "",
-    );
-    const outPath = join(routerDir, `${routerBasename}.named-routes.gen.ts`);
-    if (!existsSync(outPath)) continue;
-    try {
-      const content = readFileSync(outPath, "utf-8");
-      if (content !== preContent.get(outPath)) {
-        markSelfGenWrite(state, outPath, content);
-      }
-    } catch {
-      // Ignore transient fs errors while files are being rewritten.
-    }
-  }
+  // Mark each gen file as self-generated BEFORE it is written, via the onWrite
+  // callback fired at every writeFileSync site, so the watcher distinguishes
+  // self-triggered change events from manual edits. The callback fires only
+  // for files actually written, so unchanged files are never marked (stale
+  // entries interfere with multi-server setups such as a shared webServer plus
+  // an isolated HMR server).
+  writeCombinedRouteTypes(state.projectRoot, routerFiles, {
+    ...opts,
+    onWrite: (outPath, content) => markSelfGenWrite(state, outPath, content),
+  });
 }
 
 /**
@@ -104,7 +93,7 @@ export function writeRouteTypesFiles(state: DiscoveryState): void {
     if (existsSync(oldCombinedPath)) {
       unlinkSync(oldCombinedPath);
       console.log(
-        `[rsc-router] Removed stale combined route types: ${oldCombinedPath}`,
+        `[rango] Removed stale combined route types: ${oldCombinedPath}`,
       );
     }
   } catch {}
@@ -122,40 +111,22 @@ export function writeRouteTypesFiles(state: DiscoveryState): void {
     // the wrong location, causing non-deterministic type resolution.
     if (sourceFile.includes("node_modules")) {
       throw new Error(
-        `[rsc-router] Router "${id}" has sourceFile inside node_modules: ${sourceFile}\n` +
+        `[rango] Router "${id}" has sourceFile inside node_modules: ${sourceFile}\n` +
           `This means createRouter() stack trace parsing matched a Vite internal frame.\n` +
           `Set an explicit \`id\` on createRouter() or check the call site.`,
       );
     }
 
-    const routerDir = dirname(sourceFile);
-    const routerBasename = basename(sourceFile).replace(/\.(tsx?|jsx?)$/, "");
-    const outPath = join(routerDir, `${routerBasename}.named-routes.gen.ts`);
+    const outPath = genFileTsPath(sourceFile);
 
     // Filter out auto-generated route names (e.g. "$path____debug_reverse-test")
     // to match the static parser's output and prevent HMR oscillation.
     const userRoutes = filterUserNamedRoutes(routeManifest);
-    let effectiveSearchSchemas = routeSearchSchemas;
-
-    // Runtime manifest may omit search schema metadata in some module-runner
-    // flows. Fall back to static source parsing from the router file.
-    if (
-      (!effectiveSearchSchemas ||
-        Object.keys(effectiveSearchSchemas).length === 0) &&
-      sourceFile
-    ) {
-      const staticParsed = buildCombinedRouteMapForRouterFile(sourceFile);
-      if (Object.keys(staticParsed.searchSchemas).length > 0) {
-        const filtered: Record<string, Record<string, string>> = {};
-        for (const name of Object.keys(userRoutes)) {
-          const schema = staticParsed.searchSchemas[name];
-          if (schema) filtered[name] = schema;
-        }
-        if (Object.keys(filtered).length > 0) {
-          effectiveSearchSchemas = filtered;
-        }
-      }
-    }
+    const effectiveSearchSchemas = resolveSearchSchemas(
+      Object.keys(userRoutes),
+      routeSearchSchemas,
+      sourceFile,
+    );
 
     const source = generateRouteTypesSource(
       userRoutes,
@@ -163,14 +134,7 @@ export function writeRouteTypesFiles(state: DiscoveryState): void {
         ? effectiveSearchSchemas
         : undefined,
     );
-    const existing = existsSync(outPath)
-      ? readFileSync(outPath, "utf-8")
-      : null;
-    if (existing !== source) {
-      markSelfGenWrite(state, outPath, source);
-      writeFileSync(outPath, source);
-      console.log(`[rsc-router] Generated route types -> ${outPath}`);
-    }
+    writeGenFileIfChanged(state, outPath, source, { log: true });
   }
 }
 
@@ -236,22 +200,14 @@ export function supplementGenFilesWithRuntimeRoutes(
       }
     }
 
-    const routerDir = dirname(sourceFile);
-    const routerBasename = basename(sourceFile).replace(/\.(tsx?|jsx?)$/, "");
-    const outPath = join(routerDir, `${routerBasename}.named-routes.gen.ts`);
+    const outPath = genFileTsPath(sourceFile);
     const source = generateRouteTypesSource(
       mergedRoutes,
       Object.keys(mergedSearchSchemas).length > 0
         ? mergedSearchSchemas
         : undefined,
     );
-    const existing = existsSync(outPath)
-      ? readFileSync(outPath, "utf-8")
-      : null;
-    if (existing !== source) {
-      markSelfGenWrite(state, outPath, source);
-      writeFileSync(outPath, source);
-    }
+    writeGenFileIfChanged(state, outPath, source);
   }
   // No manual manifest update needed: the virtual module imports the gen
   // file, so Vite's HMR automatically re-evaluates it with fresh data.

package/src/vite/discovery/self-gen-tracking.ts

@@ -22,6 +22,32 @@ export function markSelfGenWrite(
 export function consumeSelfGenWrite(
   state: DiscoveryState,
   filePath: string,
+): boolean {
+  return checkSelfGenWrite(state, filePath, true);
+}
+
+/**
+ * Non-consuming variant. Used by the `handleHotUpdate` plugin hook to
+ * suppress vite's HMR cascade for our own gen-file writes WITHOUT
+ * consuming the entry — `consumeSelfGenWrite` (called later from the
+ * chokidar `change` handler in `handleRouteFileChange`) still needs to
+ * see and consume the same entry to short-circuit our regen path.
+ *
+ * Both hooks fire for the same file change event:
+ *   - `handleHotUpdate` runs first (vite's HMR pipeline).
+ *   - chokidar `change` callback runs after (filesystem watcher).
+ */
+export function peekSelfGenWrite(
+  state: DiscoveryState,
+  filePath: string,
+): boolean {
+  return checkSelfGenWrite(state, filePath, false);
+}
+
+function checkSelfGenWrite(
+  state: DiscoveryState,
+  filePath: string,
+  consume: boolean,
 ): boolean {
   const info = state.selfWrittenGenFiles.get(filePath);
   if (!info) return false;
@@ -33,7 +59,7 @@ export function consumeSelfGenWrite(
     const current = readFileSync(filePath, "utf-8");
     const currentHash = createHash("sha256").update(current).digest("hex");
     if (currentHash === info.hash) {
-      state.selfWrittenGenFiles.delete(filePath);
+      if (consume) state.selfWrittenGenFiles.delete(filePath);
       return true;
     }
     // Hash mismatch: file was changed externally. Keep the entry so a

package/src/vite/discovery/state.ts

@@ -20,6 +20,13 @@ export interface PluginOptions {
   buildEnv?: import("../plugin-types.js").BuildEnvOption;
   /** Deployment preset (needed for buildEnv "auto" resolution). */
   preset?: "node" | "cloudflare";
+  /**
+   * Shared context the built-in clientChunks strategy reads. Discovery populates
+   * it (registered fallback hashes + single-router name) before the client build
+   * invokes the strategy. Present only when the built-in strategy is active
+   * (`clientChunks: true`/default); undefined for `false` or a custom function.
+   */
+  clientChunkCtx?: import("../utils/client-chunks.js").ClientChunkContext;
 }
 
 export interface PrecomputedEntry {
@@ -45,6 +52,21 @@ export interface DiscoveryState {
   projectRoot: string;
   isBuildMode: boolean;
   userResolveAlias: any;
+  /**
+   * Data-only slice of the user's resolved config (resolve.* incl. native
+   * tsconfigPaths, define, oxc) mirrored into the discovery temp server so it
+   * resolves and transforms modules the same way the real environment does.
+   * See `utils/forward-user-plugins.ts`.
+   */
+  userRunnerConfig:
+    | import("../utils/forward-user-plugins.js").ForwardedRunnerConfig
+    | undefined;
+  /**
+   * User resolution plugins (resolveId/load), stripped to their resolution
+   * surface, forwarded into the discovery temp server. Lets third-party
+   * resolvers such as vite-tsconfig-paths participate in discovery.
+   */
+  userResolvePlugins: import("vite").Plugin[];
   scanFilter: ScanFilter | undefined;
   cachedRouterFiles: string[] | undefined;
   opts: PluginOptions | undefined;
@@ -76,6 +98,14 @@ export interface DiscoveryState {
   resolvedBuildEnv?: Record<string, unknown>;
   /** Cleanup function for build-time env resources (e.g., miniflare). */
   buildEnvDispose?: (() => Promise<void> | void) | null;
+
+  /**
+   * Set when the most recent HMR re-discovery threw. Cleared on the next
+   * successful discovery. Surfaced via debug logs so we can detect "manifest
+   * frozen at last-good after error → user fix in non-route file → no
+   * rediscovery trigger" scenarios.
+   */
+  lastDiscoveryError?: { message: string; at: number } | null;
 }
 
 export function createDiscoveryState(
@@ -87,6 +117,8 @@ export function createDiscoveryState(
     projectRoot: "",
     isBuildMode: false,
     userResolveAlias: undefined,
+    userRunnerConfig: undefined,
+    userResolvePlugins: [],
     scanFilter: undefined,
     cachedRouterFiles: undefined,
     opts,
@@ -113,5 +145,6 @@ export function createDiscoveryState(
     devServer: null,
     selfWrittenGenFiles: new Map(),
     SELF_WRITE_WINDOW_MS: 5_000,
+    lastDiscoveryError: null,
   };
 }

package/src/vite/discovery/virtual-module-codegen.ts

@@ -58,7 +58,7 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
     }
 
     const lines = [
-      `import { setCachedManifest, setPrecomputedEntries, setRouteTrie, setRouterManifest, registerRouterManifestLoader, clearAllRouterData } from "@rangojs/router/server";`,
+      `import { setCachedManifest, setRouterManifest, registerRouterManifestLoader, clearAllRouterData } from "@rangojs/router/server";`,
       ...genFileImports,
       // Clear stale per-router cached data (manifest, trie, precomputed entries)
       // before re-populating. In Cloudflare dev mode, program reloads re-evaluate
@@ -101,28 +101,18 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
       }
     }
 
-    // In dev mode, skip trie and precomputed entries injection. These are
-    // computed once during initial discovery and become stale after route
-    // changes. A stale trie would incorrectly match removed routes. The
-    // handler falls back to Phase 2 regex matching against the live
-    // router.urlpatterns, which is always correct after a program reload.
-    // In build mode, the trie is always fresh (built from the final route
-    // tree) so it's safe to inject.
-    if (state.isBuildMode) {
-      if (
-        state.mergedPrecomputedEntries &&
-        state.mergedPrecomputedEntries.length > 0
-      ) {
-        lines.push(
-          `setPrecomputedEntries(${jsonParseExpression(state.mergedPrecomputedEntries)});`,
-        );
-      }
-      if (state.mergedRouteTrie) {
-        lines.push(
-          `setRouteTrie(${jsonParseExpression(state.mergedRouteTrie)});`,
-        );
-      }
-    }
+    // Per-router trie and precomputedEntries are NOT inlined eagerly.
+    // They live in the per-router lazy chunks (generatePerRouterModule) and
+    // are loaded via ensureRouterManifest(routerId), which is awaited before
+    // every request in router.fetch() and before findMatch is reached.
+    // Inlining the merged versions here would duplicate the per-router data
+    // (the merged trie/precomputedEntries equal the per-router data for
+    // single-router apps; for multi-router, the merged trie is dead code
+    // because find-match.ts only consumes per-router tries).
+    //
+    // In dev mode, the handler also falls back to Phase 2 regex matching
+    // against live router.urlpatterns, which is always correct after a
+    // program reload.
 
     // Register lazy loaders for per-router manifest modules.
     // Each import() uses a static string literal so Rollup creates separate chunks.

package/src/vite/index.ts

@@ -13,6 +13,8 @@ export type {
   RangoNodeOptions,
   RangoCloudflareOptions,
   RangoOptions,
+  ClientChunks,
+  ClientChunkMeta,
   BuildEnvOption,
   BuildEnvFactory,
   BuildEnvFactoryContext,

package/src/vite/plugin-types.ts

@@ -47,6 +47,64 @@ export type BuildEnvOption =
   | Record<string, unknown>
   | BuildEnvFactory;
 
+// -- Client chunking --------------------------------------------------------
+
+/**
+ * Metadata for one client ("use client") module, passed to a {@link ClientChunks}
+ * function. Mirrors the shape `@vitejs/plugin-rsc` passes to its own
+ * `clientChunks` option.
+ */
+export interface ClientChunkMeta {
+  /** Absolute module id of the "use client" file. */
+  id: string;
+  /** Normalized (posix) module id — convenient for path-based matching. */
+  normalizedId: string;
+  /**
+   * The RSC/server chunk that statically imports this client reference. This is
+   * the key used for the default grouping when no override is supplied: a single
+   * router that statically imports every route yields ONE `serverChunk`, hence
+   * one client chunk for all routes.
+   */
+  serverChunk: string;
+}
+
+/**
+ * Controls how client ("use client") components are grouped into browser
+ * chunks, i.e. per-route / per-feature code splitting of the client bundle.
+ *
+ * Without splitting, a single router ships ONE client chunk containing every
+ * route's client components (and their CSS) — navigating to one route downloads
+ * every other route's client code. (Host sub-apps loaded via a dynamic `import()`
+ * are the exception: each forms its own chunk.) This option controls how that
+ * monolith is split.
+ *
+ * Behavior branches:
+ * - `true` / omitted (**default**, pre-1.0): Rango's built-in **directory
+ *   strategy**. It splits app `"use client"` modules by **route id** — the segment
+ *   after a route-root directory (`routes`, `app`, `pages`, `features`, `handlers`,
+ *   …) — so `routes/dashboard/**` becomes `app-dashboard` at any nesting depth.
+ *   Where it finds NO route structure (a flat `src/components/`, or host sub-apps
+ *   already split by a dynamic `import()`), it inherits the default grouping
+ *   unchanged — so the shared `src/components` chunk stays shared and host apps do
+ *   not leak across each other. Shared runtime (React, the router, `node_modules`)
+ *   is never split.
+ * - `false`: opt out — inherit `@vitejs/plugin-rsc`'s default grouping everywhere
+ *   (one chunk per router / per host sub-app).
+ * - function: full override. Return a chunk group name, or `undefined` to fall
+ *   back to the default grouping for that one module. Forwarded directly to
+ *   `@vitejs/plugin-rsc`'s `clientChunks`.
+ *
+ * Every module maps to exactly one group, so there is no byte duplication: a
+ * component used by two routes lives in one group and is fetched whenever it
+ * renders. Put genuinely shared client components OUTSIDE route directories so
+ * they land in the shared group rather than one route's chunk.
+ *
+ * @default true
+ */
+export type ClientChunks =
+  | boolean
+  | ((meta: ClientChunkMeta) => string | undefined);
+
 // -- Plugin options ---------------------------------------------------------
 
 /**
@@ -59,6 +117,15 @@ interface RangoBaseOptions {
    */
   banner?: boolean;
 
+  /**
+   * Group client ("use client") components into browser chunks for per-route /
+   * per-feature code splitting. On by default (pre-1.0); pass `false` to opt out.
+   * See {@link ClientChunks}.
+   *
+   * @default true
+   */
+  clientChunks?: ClientChunks;
+
   /**
    * Environment bindings available to Prerender and Static handlers at build
    * time via `ctx.env`. Applies to both production build and dev on-demand

package/src/vite/plugins/cjs-to-esm.ts

@@ -1,4 +1,7 @@
 import type { Plugin } from "vite";
+import { createRangoDebugger, NS } from "../debug.js";
+
+const debug = createRangoDebugger(NS.transform);
 
 /**
  * Transform CJS vendor files from @vitejs/plugin-rsc to ESM for browser compatibility.
@@ -9,18 +12,16 @@ export function createCjsToEsmPlugin(): Plugin {
     name: "@rangojs/router:cjs-to-esm",
     enforce: "pre",
     transform(code, id) {
-      const cleanId = id.split("?")[0];
+      const cleanId = id.split("?")[0].replaceAll("\\", "/");
 
       // Transform the client.browser.js entry point to re-export from CJS
-      if (
-        cleanId.includes("vendor/react-server-dom/client.browser.js") ||
-        cleanId.includes("vendor\\react-server-dom\\client.browser.js")
-      ) {
+      if (cleanId.includes("vendor/react-server-dom/client.browser.js")) {
         const isProd = process.env.NODE_ENV === "production";
         const cjsFile = isProd
           ? "./cjs/react-server-dom-webpack-client.browser.production.js"
           : "./cjs/react-server-dom-webpack-client.browser.development.js";
 
+        debug?.("cjs-to-esm entry redirect %s", id);
         return {
           code: `export * from "${cjsFile}";`,
           map: null,
@@ -29,8 +30,7 @@ export function createCjsToEsmPlugin(): Plugin {
 
       // Transform the actual CJS files to ESM
       if (
-        (cleanId.includes("vendor/react-server-dom/cjs/") ||
-          cleanId.includes("vendor\\react-server-dom\\cjs\\")) &&
+        cleanId.includes("vendor/react-server-dom/cjs/") &&
         cleanId.includes("client.browser")
       ) {
         let transformed = code;
@@ -81,6 +81,7 @@ export function createCjsToEsmPlugin(): Plugin {
         // Reconstruct with license at the top
         transformed = license + "\n" + transformed;
 
+        debug?.("cjs-to-esm body rewrite %s", id);
         return {
           code: transformed,
           map: null,

package/src/vite/plugins/client-ref-dedup.ts

@@ -1,4 +1,7 @@
 import type { Plugin, ResolvedConfig } from "vite";
+import { createRangoDebugger, NS } from "../debug.js";
+
+const debug = createRangoDebugger(NS.transform);
 
 const CLIENT_IN_SERVER_PROXY_PREFIX =
   "virtual:vite-rsc/client-in-server-package-proxy/";
@@ -62,6 +65,7 @@ export function extractPackageName(absolutePath: string): string | null {
  */
 export function clientRefDedup(): Plugin {
   let clientExclude: string[] = [];
+  const dedupedPackages = new Set<string>();
 
   return {
     name: "@rangojs/router:client-ref-dedup",
@@ -76,6 +80,16 @@ export function clientRefDedup(): Plugin {
         clientEnv?.optimizeDeps?.exclude ?? config.optimizeDeps?.exclude ?? [];
     },
 
+    buildEnd() {
+      if (debug && dedupedPackages.size > 0) {
+        debug(
+          "client-ref-dedup: redirected %d package(s) (%s)",
+          dedupedPackages.size,
+          [...dedupedPackages].join(","),
+        );
+      }
+    },
+
     resolveId(source, importer, options) {
       // Only intercept in the client environment
       if (this.environment?.name !== "client") return;
@@ -95,6 +109,8 @@ export function clientRefDedup(): Plugin {
       // Don't redirect packages that are excluded from optimization
       if (clientExclude.includes(packageName)) return;
 
+      if (debug) dedupedPackages.add(packageName);
+
       // Return a virtual module that re-exports via bare specifier
       return `\0rango:dedup/${packageName}`;
     },

package/src/vite/plugins/client-ref-hashing.ts

@@ -1,6 +1,9 @@
 import type { Plugin } from "vite";
 import { relative } from "node:path";
 import { createHash } from "node:crypto";
+import { createRangoDebugger, createCounter, NS } from "../debug.js";
+
+const debug = createRangoDebugger(NS.transform);
 
 // Dev-mode client-reference key prefixes emitted by @vitejs/plugin-rsc
 const CLIENT_PKG_PROXY_PREFIX =
@@ -19,6 +22,17 @@ const FS_PREFIX = "/@fs/";
  * Returns the input unchanged if it doesn't match a known dev-mode pattern
  * (e.g., already a production hash).
  */
+/**
+ * The production client-reference key hash: `sha256(relativeId).slice(0,12)`,
+ * matching @vitejs/plugin-rsc's `hashString`. Exported so the client-chunks
+ * strategy can hash a `clientChunks` callback's `meta.normalizedId` (already the
+ * project-root-relative id) and compare it against fallback hashes collected
+ * during discovery.
+ */
+export function hashRefKey(relativeId: string): string {
+  return createHash("sha256").update(relativeId).digest("hex").slice(0, 12);
+}
+
 export function computeProductionHash(
   projectRoot: string,
   refKey: string,
@@ -46,7 +60,7 @@ export function computeProductionHash(
     return refKey;
   }
 
-  return createHash("sha256").update(toHash).digest("hex").slice(0, 12);
+  return hashRefKey(toHash);
 }
 
 // Regex to match registerClientReference() calls as emitted by @vitejs/plugin-rsc.
@@ -89,6 +103,7 @@ export function transformClientRefs(
  * regex replacement of Flight payloads.
  */
 export function hashClientRefs(projectRoot: string): Plugin {
+  const counter = createCounter(debug, "hash-client-refs");
   return {
     name: "@rangojs/router:hash-client-refs",
     // Run after the RSC plugin's transform (default enforce is normal)
@@ -96,10 +111,18 @@ export function hashClientRefs(projectRoot: string): Plugin {
     applyToEnvironment(env) {
       return env.name === "rsc";
     },
-    transform(code, _id) {
-      const result = transformClientRefs(code, projectRoot);
-      if (result === null) return;
-      return { code: result, map: null };
+    buildEnd() {
+      counter?.flush();
+    },
+    transform(code, id) {
+      const start = counter ? performance.now() : 0;
+      try {
+        const result = transformClientRefs(code, projectRoot);
+        if (result === null) return;
+        return { code: result, map: null };
+      } finally {
+        counter?.record(id, performance.now() - start);
+      }
     },
   };
 }

package/src/vite/plugins/cloudflare-protocol-loader-hook.d.mts

@@ -0,0 +1,23 @@
+export interface LoaderResolveContext {
+  parentURL?: string;
+  conditions?: readonly string[];
+  importAttributes?: Record<string, string>;
+}
+
+export interface LoaderResolveResult {
+  shortCircuit?: boolean;
+  url: string;
+  format?: "module" | "commonjs" | "json" | "wasm" | null;
+  importAttributes?: Record<string, string>;
+}
+
+export type NextResolve = (
+  specifier: string,
+  context?: LoaderResolveContext,
+) => Promise<LoaderResolveResult>;
+
+export function resolve(
+  specifier: string,
+  context: LoaderResolveContext,
+  nextResolve: NextResolve,
+): Promise<LoaderResolveResult>;