@rangojs/router 0.0.0-experimental.111 → 0.0.0-experimental.113

package/src/types/handler-context.ts

@@ -567,8 +567,11 @@ export type ShouldRevalidateFn<TParams = GenericParams, TEnv = any> = (args: {
 
   // ── Segment metadata (which segment is being evaluated) ──────────────
 
-  /** The type of segment being revalidated. */
-  segmentType: "layout" | "route" | "parallel";
+  /**
+   * The type of segment being revalidated. `"loader"` is passed to revalidate
+   * functions attached to a `loader(Fn, () => [revalidate(...)])` registration.
+   */
+  segmentType: "layout" | "route" | "parallel" | "loader";
   /** Layout name (e.g., `"root"`, `"shop"`, `"auth"`). Only set for layout segments. */
   layoutName?: string;
   /** Slot name (e.g., `"@sidebar"`, `"@modal"`). Only set for parallel segments. */

package/src/use-loader.tsx

@@ -187,17 +187,20 @@ export interface UseLoaderOptions {
    */
   key?: string;
   /**
-   * Cross-loader refresh group. Tag reads of DIFFERENT loaders with the same
-   * `refreshGroup` name, then call `useRefreshLoaders(name)()` to refresh the
-   * whole group at once. Each member is refreshed with a plain GET against the
-   * current route URL — no params, no body, no mutation methods — because a
-   * group spans heterogeneous loaders with different param/return shapes.
+   * Cross-loader refresh group tag(s). Tag reads of DIFFERENT loaders with a
+   * shared name, then call `useRefreshLoaders()(name)` to refresh the whole group
+   * at once. Pass an array to tag one read into several groups — it is refreshed
+   * when ANY of its groups is refreshed, so a coarse tag can cover the whole set
+   * while a finer tag targets a subset. Each member is refreshed with a plain GET
+   * against the current route URL — no params, no body, no mutation methods —
+   * because a group spans heterogeneous loaders with different param/return
+   * shapes.
    *
    * For parameterized sharing of a SINGLE loader, use `key` instead; group
    * members should be registered or non-parameterized-keyed reads (a plain-GET
    * group refresh would drop any per-call params).
    */
-  refreshGroup?: string;
+  refreshGroup?: string | string[];
 }
 
 /**
@@ -254,29 +257,42 @@ function useLoaderInternal<T>(
   // only hooks with the same `key` refresh together. Default (no key) keeps the
   // historical behavior: one bucket per loader id.
   const key = options?.key;
-  const refreshGroup = options?.refreshGroup;
+  // Normalize the refresh-group tag(s) to a stable, deduped, sorted list. The
+  // joined `groupKey` string is the subscribe effect's dependency, so passing an
+  // inline array literal (`refreshGroup={["a", "b"]}`) does not force a
+  // resubscribe on every render. An empty list means "no groups" — identical to
+  // omitting the option (`hasGroups` stays false, no private bucket is created).
+  const refreshGroupOption = options?.refreshGroup;
+  const groupKey =
+    refreshGroupOption === undefined
+      ? ""
+      : JSON.stringify(
+          typeof refreshGroupOption === "string"
+            ? [refreshGroupOption]
+            : [...new Set(refreshGroupOption)].sort(),
+        );
+  const groupList = useMemo<string[]>(
+    () => (groupKey === "" ? [] : (JSON.parse(groupKey) as string[])),
+    [groupKey],
+  );
+  const hasGroups = groupList.length > 0;
   // A grouped reader with no explicit key gets a private per-hook bucket so a
   // cross-loader group refresh cannot leak into the bare `loader.$$id` bucket
   // shared by unrelated unkeyed readers. Sharing within a group is opt-in via
   // an explicit `key`.
   const privateBucketIdRef = useRef<string | null>(null);
-  if (
-    refreshGroup !== undefined &&
-    key === undefined &&
-    privateBucketIdRef.current === null
-  ) {
+  if (hasGroups && key === undefined && privateBucketIdRef.current === null) {
     privateBucketIdRef.current = `__rg${privateGroupBucketSeq++}`;
   }
   const effectiveKey =
-    key ??
-    (refreshGroup !== undefined ? privateBucketIdRef.current! : undefined);
+    key ?? (hasGroups ? privateBucketIdRef.current! : undefined);
   const bucketKey =
     effectiveKey === undefined ? loaderId : `${loaderId}::${effectiveKey}`;
 
   // Plain-GET refresh thunk registered with the store for cross-loader group
   // refresh (useRefreshLoaders). Always shares into this hook's bucket, never
   // touches lastSharedRequestIdRef (so a group refresh never render-throws —
-  // errors surface via `error` and reject the refreshGroup() promise instead),
+  // errors surface via `error` and reject the refreshGroups() promise instead),
   // and sends no params/body. Stable across navigations (depends only on
   // loaderId + bucketKey), so the store keeps one current thunk per bucket.
   const groupRefetch = useCallback(async (): Promise<void> => {
@@ -340,16 +356,17 @@ function useLoaderInternal<T>(
       {
         loaderId,
         ephemeral: !hasContextData,
-        group: refreshGroup,
-        refetch: refreshGroup !== undefined ? groupRefetch : undefined,
+        group: hasGroups ? groupList : undefined,
+        refetch: hasGroups ? groupRefetch : undefined,
       },
     );
     // eslint-disable-next-line react-hooks/exhaustive-deps -- intentional:
     // sharedSnapshot is captured for the one-shot init sync; we don't want
     // to re-subscribe on every snapshot change. bucketKey, hasContextData,
-    // refreshGroup, and groupRefetch are the only inputs that require a fresh
-    // subscription (groupRefetch is stable per bucketKey).
-  }, [bucketKey, hasContextData, refreshGroup, groupRefetch]);
+    // groupKey, and groupRefetch are the only inputs that require a fresh
+    // subscription (groupList is memoized on groupKey; groupRefetch is stable
+    // per bucketKey).
+  }, [bucketKey, hasContextData, groupKey, groupRefetch]);
 
   // Local state holds the result of:
   //   - parameterized / mutation `load()` calls (load({ params }), POST,
@@ -360,9 +377,13 @@ function useLoaderInternal<T>(
   //     prevents two unrelated components from accidentally sharing data
   //     through the global store just because they reference the same
   //     loader id.
-  const [localFetchedData, setLocalFetchedData] = useState<T | undefined>(
-    undefined,
-  );
+  // `has` distinguishes a committed local result (including `null`/`undefined`)
+  // from "no local load yet", so a load() that resolves to a falsy value is not
+  // discarded in favor of the shared snapshot or the seeded context.
+  const [localFetchedData, setLocalFetchedData] = useState<{
+    has: boolean;
+    value: T | undefined;
+  }>({ has: false, value: undefined });
   const [localIsLoading, setLocalIsLoading] = useState(false);
   const [localError, setLocalError] = useState<Error | null>(null);
 
@@ -385,7 +406,7 @@ function useLoaderInternal<T>(
   const prevContextDataRef = useRef(contextData);
   useEffect(() => {
     if (prevContextDataRef.current !== contextData) {
-      setLocalFetchedData(undefined);
+      setLocalFetchedData({ has: false, value: undefined });
       setLocalIsLoading(false);
       setLocalError(null);
       lastSharedRequestIdRef.current = null;
@@ -396,10 +417,14 @@ function useLoaderInternal<T>(
     }
   }, [contextData, loaderId]);
 
-  // Read priority: a parameterized load() result overrides the shared
-  // snapshot; the shared snapshot overrides the server-seeded context.
-  const data =
-    localFetchedData ?? (sharedSnapshot.value as T | undefined) ?? contextData;
+  // Read priority: a committed parameterized load() result overrides the shared
+  // snapshot; a committed shared snapshot overrides the server-seeded context.
+  // `has`/`hasValue` gate each level so a committed falsy value is not skipped.
+  const data = localFetchedData.has
+    ? localFetchedData.value
+    : sharedSnapshot.hasValue
+      ? (sharedSnapshot.value as T | undefined)
+      : contextData;
   const isLoading = localIsLoading || sharedSnapshot.isLoading;
   const error = localError ?? sharedSnapshot.error;
 
@@ -553,7 +578,7 @@ function useLoaderInternal<T>(
           // if a newer load() was issued from this hook before this one
           // resolved, drop the stale result.
           startTransition(() => {
-            setLocalFetchedData(result);
+            setLocalFetchedData({ has: true, value: result });
             setLocalIsLoading(false);
           });
         }
@@ -712,14 +737,21 @@ export function useFetchLoader<T>(
 }
 
 /**
- * Refresh every loader tagged with a shared `refreshGroup` name.
+ * Get a stable function that refreshes loaders by cross-loader group tag.
  *
- * Returns a stable async function that refreshes all currently-mounted reads
- * in the group with a plain GET against the current route URL. This is the
- * cross-loader counterpart to the single-loader `key`: use it to refresh a set
- * of DIFFERENT loaders together (e.g. profile + orders after an account
- * switch). Members are tagged via `useLoader(Loader, { refreshGroup })` /
- * `useFetchLoader(Loader, { refreshGroup })`.
+ * The returned `refresh(groups)` takes one group name or an array of names and
+ * re-runs every currently-mounted read tagged with ANY of them, with a plain GET
+ * against the current route URL. This is the cross-loader counterpart to the
+ * single-loader `key`: use it to refresh a set of DIFFERENT loaders together
+ * (e.g. profile + orders after an account switch). Members are tagged via
+ * `useLoader(Loader, { refreshGroup })` / `useFetchLoader(Loader, { refreshGroup })`,
+ * where `refreshGroup` is one name or several.
+ *
+ * Passing the group(s) to the returned function rather than to the hook lets a
+ * single `useRefreshLoaders()` instance refresh different groups depending on
+ * context, and lets one call refresh several groups at once — their members are
+ * unioned and deduped, so a loader tagged into two of the named groups is fetched
+ * exactly once.
  *
  * Group refresh never render-throws: a failing member surfaces its error via
  * that read's `error` state, and the returned promise rejects with an
@@ -736,15 +768,30 @@ export function useFetchLoader<T>(
  *   return <span>{data.name}</span>;
  * }
  * function Orders() {
- *   const { data } = useLoader(OrdersLoader, { key: userId, refreshGroup: "account" });
+ *   // Tagged into two groups: refreshed by "account" (the whole set) or "orders".
+ *   const { data } = useLoader(OrdersLoader, {
+ *     key: userId,
+ *     refreshGroup: ["account", "orders"],
+ *   });
  *   return <span>{data.count} orders</span>;
  * }
- * function RefreshButton() {
- *   const refreshAccount = useRefreshLoaders("account");
- *   return <button onClick={() => refreshAccount()}>Refresh</button>;
+ * function RefreshButtons() {
+ *   const refresh = useRefreshLoaders();
+ *   return (
+ *     <>
+ *       <button onClick={() => refresh("account")}>Refresh account</button>
+ *       <button onClick={() => refresh("orders")}>Refresh orders</button>
+ *       <button onClick={() => refresh(["account", "orders"])}>Refresh both</button>
+ *     </>
+ *   );
  * }
  * ```
  */
-export function useRefreshLoaders(group: string): () => Promise<void> {
-  return useCallback(() => loaderStore.refreshGroup(group), [group]);
+export function useRefreshLoaders(): (
+  groups: string | string[],
+) => Promise<void> {
+  return useCallback(
+    (groups: string | string[]) => loaderStore.refreshGroups(groups),
+    [],
+  );
 }

package/src/vite/discovery/discover-routers.ts

@@ -292,18 +292,16 @@ export async function discoverRouters(
         }
       }
 
+      // buildRouteTrie reads these via ?.has / ?.[] — empty is observationally
+      // identical to undefined, so no empty->undefined coercion is needed.
       newMergedRouteTrie = buildRouteTrie(
         newMergedRouteManifest,
         mergedRouteAncestry,
         routeToStaticPrefix,
-        Object.keys(mergedRouteTrailingSlash).length > 0
-          ? mergedRouteTrailingSlash
-          : undefined,
-        prerenderRouteNames.size > 0 ? prerenderRouteNames : undefined,
-        passthroughRouteNames.size > 0 ? passthroughRouteNames : undefined,
-        Object.keys(mergedResponseTypeRoutes).length > 0
-          ? mergedResponseTypeRoutes
-          : undefined,
+        mergedRouteTrailingSlash,
+        prerenderRouteNames,
+        passthroughRouteNames,
+        mergedResponseTypeRoutes,
       );
 
       // Build per-router tries for multi-router isolation.
@@ -330,20 +328,10 @@ export async function discoverRouters(
           manifest.routeManifest,
           manifest._routeAncestry,
           perRouterStaticPrefix,
-          manifest.routeTrailingSlash &&
-            Object.keys(manifest.routeTrailingSlash).length > 0
-            ? manifest.routeTrailingSlash
-            : undefined,
-          perRouterPrerenderNames && perRouterPrerenderNames.size > 0
-            ? perRouterPrerenderNames
-            : undefined,
-          perRouterPassthroughNames && perRouterPassthroughNames.size > 0
-            ? perRouterPassthroughNames
-            : undefined,
-          manifest.responseTypeRoutes &&
-            Object.keys(manifest.responseTypeRoutes).length > 0
-            ? manifest.responseTypeRoutes
-            : undefined,
+          manifest.routeTrailingSlash,
+          perRouterPrerenderNames,
+          perRouterPassthroughNames,
+          manifest.responseTypeRoutes,
         );
         newPerRouterTrieMap.set(id, perRouterTrie);
       }

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),
+  });
 }
 
 /**
@@ -128,34 +117,16 @@ export function writeRouteTypesFiles(state: DiscoveryState): void {
       );
     }
 
-    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(`[rango] 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/plugins/cjs-to-esm.ts

@@ -12,13 +12,10 @@ 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"
@@ -33,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;

package/src/vite/plugins/expose-ids/handler-transform.ts

@@ -1,5 +1,5 @@
 import MagicString from "magic-string";
-import { hashId } from "../expose-id-utils.js";
+import { makeStubId } from "../expose-id-utils.js";
 import type { HandlerTransformConfig, CreateExportBinding } from "./types.js";
 import { isExportOnlyFile } from "./export-analysis.js";
 
@@ -28,9 +28,7 @@ export function transformHandles(
       binding.callCloseParenPos,
     );
 
-    const handleId = isBuild
-      ? hashId(filePath, exportName)
-      : `${filePath}#${exportName}`;
+    const handleId = makeStubId(filePath, exportName, isBuild);
 
     let paramInjection: string;
     if (!args.hasArgs) {
@@ -58,9 +56,7 @@ export function transformLocationState(
   for (const binding of bindings) {
     const exportName = binding.exportNames[0];
 
-    const stateKey = isBuild
-      ? hashId(filePath, exportName)
-      : `${filePath}#${exportName}`;
+    const stateKey = makeStubId(filePath, exportName, isBuild);
 
     // Key is injected as a property assignment (not as a function argument).
     // This allows createLocationState to accept options like { flash: true }
@@ -88,7 +84,7 @@ export function generateWholeFileStubs(
 
   const exportNames = bindings.flatMap((b) => b.exportNames);
   const stubs = exportNames.map((name) => {
-    const handlerId = isBuild ? hashId(filePath, name) : `${filePath}#${name}`;
+    const handlerId = makeStubId(filePath, name, isBuild);
     return `export const ${name} = { __brand: "${cfg.brand}", $$id: "${handlerId}" };`;
   });
 
@@ -96,53 +92,8 @@ export function generateWholeFileStubs(
 }
 
 /**
- * Replace handler call expressions with lightweight stub objects in non-RSC
- * environments. Other exports, imports, and module-level code remain untouched.
- */
-export function generateExprStubs(
-  cfg: HandlerTransformConfig,
-  bindings: CreateExportBinding[],
-  code: string,
-  filePath: string,
-  sourceId: string,
-  isBuild: boolean,
-): { code: string; map: ReturnType<MagicString["generateMap"]> } | null {
-  if (bindings.length === 0) return null;
-
-  const s = new MagicString(code);
-  let hasChanges = false;
-
-  for (const binding of bindings) {
-    const exportName = binding.exportNames[0];
-    const handlerId = isBuild
-      ? hashId(filePath, exportName)
-      : `${filePath}#${exportName}`;
-
-    s.overwrite(
-      binding.callExprStart,
-      binding.callCloseParenPos + 1,
-      `{ __brand: "${cfg.brand}", $$id: "${handlerId}" }`,
-    );
-    hasChanges = true;
-  }
-
-  if (!hasChanges) return null;
-
-  return {
-    code: s.toString(),
-    map: s.generateMap({
-      source: sourceId,
-      includeContent: true,
-      hires: "boundary",
-    }),
-  };
-}
-
-/**
- * Replace handler call expressions with lightweight stub objects on an
- * existing MagicString. Unlike generateExprStubs (which creates its own
- * MagicString and returns the full result), this integrates into the
- * unified transform pipeline so all transforms share one sourcemap.
+ * Replace handler call expressions with lightweight stub objects on the shared
+ * unified-pipeline MagicString so all transforms share one sourcemap.
  */
 export function stubHandlerExprs(
   cfg: HandlerTransformConfig,
@@ -154,9 +105,7 @@ export function stubHandlerExprs(
   let hasChanges = false;
   for (const binding of bindings) {
     const exportName = binding.exportNames[0];
-    const handlerId = isBuild
-      ? hashId(filePath, exportName)
-      : `${filePath}#${exportName}`;
+    const handlerId = makeStubId(filePath, exportName, isBuild);
 
     s.overwrite(
       binding.callExprStart,
@@ -182,9 +131,7 @@ export function transformHandlerIds(
   for (const binding of bindings) {
     const exportName = binding.exportNames[0];
 
-    const handlerId = isBuild
-      ? hashId(filePath, exportName)
-      : `${filePath}#${exportName}`;
+    const handlerId = makeStubId(filePath, exportName, isBuild);
 
     // Injection strategy matches the runtime overload signatures:
     //   0 args                              -> inject undefined, "id"

package/src/vite/plugins/expose-ids/loader-transform.ts

@@ -1,5 +1,5 @@
 import type MagicString from "magic-string";
-import { hashId } from "../expose-id-utils.js";
+import { makeStubId } from "../expose-id-utils.js";
 import type { CreateExportBinding } from "./types.js";
 import { isExportOnlyFile } from "./export-analysis.js";
 
@@ -33,7 +33,7 @@ export function generateClientLoaderStubs(
 
   for (const binding of bindings) {
     for (const name of binding.exportNames) {
-      const loaderId = isBuild ? hashId(filePath, name) : `${filePath}#${name}`;
+      const loaderId = makeStubId(filePath, name, isBuild);
       lines.push(
         `export const ${name} = { __brand: "loader", $$id: "${loaderId}" };`,
       );
@@ -54,9 +54,7 @@ export function transformLoaders(
   for (const binding of bindings) {
     const exportName = binding.exportNames[0];
 
-    const loaderId = isBuild
-      ? hashId(filePath, exportName)
-      : `${filePath}#${exportName}`;
+    const loaderId = makeStubId(filePath, exportName, isBuild);
 
     // Inject $$id as hidden third parameter.
     // createLoader(fn) -> createLoader(fn, undefined, "id")