@rangojs/router 0.15.1 → 0.17.0

package/src/testing/vitest.ts

@@ -78,6 +78,10 @@
 
 import { createRequire } from "node:module";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import {
+  isUseCacheCandidate,
+  transformUseCache,
+} from "../vite/plugins/use-cache-transform.js";
 
 /** A single Vite/Vitest resolve alias entry. Structurally a Vite `Alias`. */
 export interface TestAlias {
@@ -262,6 +266,7 @@ interface FlightTransformPlugin {
  * import { defineConfig } from "vitest/config";
  * import {
  *   rangoUseClientTransform,
+ *   rangoUseCacheTransform,
  *   rangoTestAliases,
  *   rangoInlineDeps,
  * } from "@rangojs/router/testing/vitest";
@@ -271,7 +276,7 @@ interface FlightTransformPlugin {
  * process.env.NODE_ENV = "production";
  *
  * export default defineConfig({
- *   plugins: [rangoUseClientTransform()],
+ *   plugins: [rangoUseClientTransform(), rangoUseCacheTransform()],
  *   resolve: {
  *     conditions: ["react-server"],
  *     // Bare `@rangojs/router` -> its react-server build, so a handler/component
@@ -340,3 +345,59 @@ export function rangoUseClientTransform(): FlightTransformPlugin {
     },
   };
 }
+
+/** The Vite plugin shape {@link rangoUseCacheTransform} returns. */
+interface UseCacheTransformPlugin {
+  name: string;
+  enforce: "post";
+  configResolved(config: { root: string }): void;
+  transform(
+    this: { warn(message: string): void },
+    code: string,
+    id: string,
+  ): Promise<{ code: string; map: unknown } | undefined>;
+}
+
+/**
+ * A Vite plugin that applies the rango plugin's `"use cache"` transform in a
+ * Vitest project, so a function written with the directive is wrapped with
+ * `registerCachedFunction` as in dev and a build. `rango()` runs that transform
+ * only in its `rsc` environment and Vitest transforms in `ssr`, so without this
+ * plugin the directive is an inert string and the function runs on every call.
+ *
+ * Add it to the react-server project next to {@link rangoUseClientTransform}
+ * (see that function's config). There, with a seeded `cacheStore`,
+ * `renderHandler` / `runLoader` observe real hits. In the node project the
+ * wrap applies too, but the stubbed Flight serializer cannot write an entry.
+ *
+ * Ids are the ones `vite dev` emits: `<path relative to the Vitest root>#<name>`
+ * (a function-level directive gives `src/data.ts#$$hoist_0_getData`), not the
+ * build's hashed path, so store keys stay readable. `configResolved` sets that
+ * root. If `@vitejs/plugin-rsc/transforms` fails to load, the transform throws
+ * instead of leaving the module unwrapped (which the rango plugin does).
+ */
+export function rangoUseCacheTransform(): UseCacheTransformPlugin {
+  let root = process.cwd();
+  return {
+    name: "rango:testing-use-cache",
+    enforce: "post",
+    configResolved(config) {
+      root = config.root;
+    },
+    async transform(code, id) {
+      if (!isUseCacheCandidate(code, id)) return undefined;
+      return transformUseCache(code, id, {
+        root,
+        isBuild: false,
+        warn: (message) => this.warn(message),
+        onTransformsError: (error) => {
+          throw new Error(
+            `rangoUseCacheTransform: @vitejs/plugin-rsc/transforms failed to ` +
+              `load, so "use cache" functions in ${id} would run unwrapped.`,
+            { cause: error },
+          );
+        },
+      });
+    },
+  };
+}

package/src/theme/ThemeProvider.tsx

@@ -114,8 +114,6 @@ export function ThemeProvider({
   initialTheme,
   children,
 }: ThemeProviderProps): React.ReactNode {
-  const [mounted, setMounted] = useState(false);
-
   // HYDRATION PARITY: this initializer is the server (SSR/resume) render AND
   // the client's hydration render — both must produce the same value. It must
   // NEVER read cookie/localStorage: whenever the payload's initialTheme
@@ -132,7 +130,6 @@ export function ThemeProvider({
   const [systemTheme, setSystemTheme] = useState<ResolvedTheme>("light");
 
   useEffect(() => {
-    setMounted(true);
     setSystemTheme(getSystemTheme());
     // Re-sync state from an EXPLICITLY stored theme after mount. initialTheme
     // comes from the payload and can legitimately differ from the visitor's
@@ -229,18 +226,16 @@ export function ThemeProvider({
     };
   }, [config]);
 
+  // No pre-mount special case: `theme` and `systemTheme` ("light" until the
+  // mount effect) are identical on the server and in the hydration render, so
+  // this is hydration-safe, and a concrete defaultTheme without an initialTheme
+  // no longer flips at mount.
   const resolvedTheme: ResolvedTheme = useMemo(() => {
-    if (!mounted) {
-      if (initialTheme && initialTheme !== "system") {
-        return initialTheme as ResolvedTheme;
-      }
-      return "light";
-    }
     if (theme === "system" && config.enableSystem) {
       return systemTheme;
     }
     return theme as ResolvedTheme;
-  }, [theme, systemTheme, config.enableSystem, mounted, initialTheme]);
+  }, [theme, systemTheme, config.enableSystem]);
 
   const themes = useMemo(() => {
     if (config.enableSystem) {
@@ -249,16 +244,23 @@ export function ThemeProvider({
     return config.themes;
   }, [config.themes, config.enableSystem]);
 
+  // Keyed on the exposed field values only: a NEW context object with
+  // unchanged fields propagates into every dehydrated Suspense boundary still
+  // streaming in (React cannot see their consumers) and makes React
+  // client-render those boundaries instead of adopting the server HTML their
+  // $RC script delivers. A field that genuinely changes at mount (dark system
+  // theme, stored override) must still publish; that case stays open
+  // (CHANGELOG).
   const contextValue: ThemeContextValue = useMemo(
     () => ({
       theme,
       setTheme,
       resolvedTheme,
-      systemTheme: mounted ? systemTheme : "light",
+      systemTheme,
       themes,
       config,
     }),
-    [theme, setTheme, resolvedTheme, systemTheme, themes, config, mounted],
+    [theme, setTheme, resolvedTheme, systemTheme, themes, config],
   );
 
   return (

package/src/theme/ThemeScript.tsx

@@ -8,14 +8,14 @@
  *
  * Must be placed in the <head> element of your document, before any stylesheets.
  *
- * Note: when theme is enabled in the router config, `<MetaTags />` ALREADY
+ * Note: when theme is enabled in the router config, `<Html.Meta />` ALREADY
  * renders this FOUC script. Use `<ThemeScript />` only if you do NOT render
- * `<MetaTags />`. Rendering both is safe — the inline script guards the
+ * `<Html.Meta />`. Rendering both is safe — the inline script guards the
  * matchMedia listener registration against double-running — but it is redundant.
  *
  * @example
  * ```tsx
- * // In your document component. Use ThemeScript only when you do not render MetaTags.
+ * // In your document component. Use ThemeScript only when you do not render Html.Meta.
  * import { ThemeScript } from "@rangojs/router/theme";
  *
  * export function Document({ children }) {

package/src/thenable-status.ts

@@ -0,0 +1,16 @@
+/**
+ * Thenable statuses React's `use()` unwraps without suspending: React's
+ * re-check after `.then()` handles "fulfilled", and Flight chunks in the
+ * resolved_* states initialize synchronously inside that same call. Anything
+ * else (pending, blocked, an unstamped native promise) suspends at least once.
+ * Shared by the dev SSR-suspension diagnostic and the held-navigation
+ * isLoading registration (loader-store.ts), which must agree on "settled".
+ */
+export function unwrapsSynchronously(stream: Promise<unknown>): boolean {
+  const status = (stream as { status?: string }).status;
+  return (
+    status === "fulfilled" ||
+    status === "resolved_model" ||
+    status === "resolved_module"
+  );
+}

package/src/types/cache-types.ts

@@ -1,12 +1,13 @@
 /**
- * Context passed to cache condition/key/tags functions.
+ * Context passed to cache condition/key/tags functions (the full
+ * RequestContext).
  *
- * This is a subset of RequestContext that's guaranteed to be available
- * during cache key generation (before middleware runs).
- *
- * Note: While the full RequestContext is passed, middleware-set variables
- * read via `ctx.get()` may not be populated yet since cache lookup happens
- * before middleware execution.
+ * Ordering: global middleware wraps the whole request, and on RSC routes route
+ * middleware wraps the match/render pipeline (rsc/handler.ts executeRender), so
+ * variables they set before `next()` are readable via `ctx.get()`. On response
+ * routes the cache lookup runs BEFORE route middleware, which wraps only the
+ * handler run on a miss (rsc/response-route-handler.ts); only global-middleware
+ * variables are populated there.
  */
 export type { RequestContext as CacheContext } from "../server/request-context.js";
 
@@ -109,7 +110,8 @@ export interface CacheOptions<TEnv = unknown> {
    * Return false to skip cache for this request (always fetch fresh).
    *
    * Has access to full RequestContext including env, request, params, cookies, etc.
-   * Note: Middleware-set variables read via `ctx.get()` may not be populated yet.
+   * Runs after global and route middleware on RSC routes; on response routes,
+   * before route middleware (see CacheContext).
    *
    * @example
    * ```typescript
@@ -131,7 +133,8 @@ export interface CacheOptions<TEnv = unknown> {
    * Bypasses default key generation AND store's keyGenerator.
    *
    * Has access to full RequestContext including env, request, params, cookies, etc.
-   * Note: Middleware-set variables read via `ctx.get()` may not be populated yet.
+   * Runs after global and route middleware on RSC routes; on response routes,
+   * before route middleware (see CacheContext).
    *
    * @example
    * ```typescript
@@ -153,7 +156,8 @@ export interface CacheOptions<TEnv = unknown> {
    * Tags for cache invalidation.
    * Can be a static array or a function that returns tags.
    *
-   * The built-in `MemorySegmentCacheStore` and `CFCacheStore` index by tag.
+   * The built-in `MemorySegmentCacheStore`, `CFCacheStore`, and
+   * `VercelCacheStore` index by tag.
    * Invalidate on demand with `updateTag(...tags)` (awaitable, read-your-own-writes;
    * for server actions) or `revalidateTag(...tags)` (background hard-purge, not
    * awaited; for route handlers / webhooks). For `CFCacheStore`, distributed

package/src/types/handler-context.ts

@@ -455,6 +455,20 @@ export type InternalHandlerContext<
    * table (so a loader cannot await its own in-flight memoized promise).
    */
   _loaderCacheOriginalUse?: (item: any) => any;
+  /**
+   * @internal A loader-cache HIT asks before replaying a loader's recorded
+   * pushes: true when that loader has not run in this request and no other
+   * replay delivered it; its later run then replaces the replayed values
+   * (HandleStore.pushReplayed). One copy per loader per request. See
+   * setupLoaderAccess.
+   */
+  _claimLoaderPushes?: (loaderId: string) => boolean;
+  /**
+   * @internal Run a loader on a fresh executor (own memo map): a loader-cache
+   * stale refresh, whose diverted pushes must not take a dependency's run
+   * from the page. See setupLoaderAccess.
+   */
+  _runLoaderIsolated?: (loader: any) => Promise<any>;
 };
 
 /**

package/src/types/loader-types.ts

@@ -28,9 +28,10 @@ import type { RequestScope } from "./request-scope.js";
  *   return await db.cart.get(user.id);
  * });
  *
- * // With typed params:
- * const ProductLoader = createLoader<Product, { slug: string }>(async (ctx) => {
- *   const { slug } = ctx.params;  // slug is typed as string
+ * // createLoader's one type parameter is the data type; params are
+ * // Record<string, string | undefined>:
+ * const ProductLoader = createLoader<Product>(async (ctx) => {
+ *   const { slug } = ctx.params;  // string | undefined
  *   return await db.products.findBySlug(slug);
  * });
  * ```
@@ -243,9 +244,10 @@ export type LoadOptions =
  *   return await db.cart.get(ctx.get("user").id);
  * });
  *
- * // With typed params:
- * export const ProductLoader = createLoader<Product, { slug: string }>(async (ctx) => {
- *   const { slug } = ctx.params;  // slug is typed as string
+ * // createLoader's one type parameter is the data type; params are
+ * // Record<string, string | undefined>:
+ * export const ProductLoader = createLoader<Product>(async (ctx) => {
+ *   const { slug } = ctx.params;  // string | undefined
  *   return await db.products.findBySlug(slug);
  * });
  *

package/src/urls/response-types.ts

@@ -1,5 +1,5 @@
 import type { ContextVar } from "../context-var.js";
-import type { ReverseFunction } from "../reverse.js";
+import type { GlobalReverseFunction } from "../reverse.js";
 import type {
   DefaultReverseRouteMap,
   DefaultVars,
@@ -7,27 +7,6 @@ import type {
 import type { UseItems, ResponseRouteUseItem } from "../route-types.js";
 import type { RequestScope } from "../types/request-scope.js";
 
-/**
- * Reverse function for response handler contexts.
- * Global names get autocomplete and param validation from the generated route map.
- * Local `.name` calls are accepted but not validated (scope unknown at type level).
- */
-type ResponseReverseFunction = [DefaultReverseRouteMap] extends [
-  Record<string, string>,
-]
-  ? (
-      name: string,
-      params?: Record<string, string>,
-      search?: Record<string, unknown>,
-    ) => string
-  : ReverseFunction<DefaultReverseRouteMap> & {
-      (
-        name: `.${string}`,
-        params?: Record<string, string>,
-        search?: Record<string, unknown>,
-      ): string;
-    };
-
 /**
  * Symbol marking a route as a response route (non-RSC).
  * Stored on PathOptions and UrlPatterns to signal the trie to short-circuit.
@@ -99,7 +78,8 @@ export interface ResponseHandlerContext<
   params: TParams;
   /** @internal Phantom property for params type invariance. Prevents mounting handlers on wrong routes. */
   readonly _paramCheck?: (params: TParams) => TParams;
-  reverse: ResponseReverseFunction;
+  /** Global route names only; see {@link GlobalReverseFunction}. */
+  reverse: GlobalReverseFunction<DefaultReverseRouteMap>;
   /** Read a variable set by middleware via ctx.set(key, value) or ctx.set(ContextVar, value). */
   get: {
     <T>(contextVar: ContextVar<T>): T | undefined;

package/src/use-loader.tsx

@@ -8,6 +8,7 @@ import {
   useContext,
   useEffect,
   useMemo,
+  useOptimistic,
   useRef,
   useState,
   type ReactNode,
@@ -116,6 +117,14 @@ export type LoadFunction<T> = (options?: LoadOptions) => Promise<T>;
 
 export interface UseLoaderResult<T> {
   data: T;
+  /**
+   * True while this loader family (`loader.$$id`) is in flight: a `load()` /
+   * group refresh, or a held navigation still streaming a re-run of this
+   * loader. Family-keyed, not segment-keyed: a layout `useLoader` of the same
+   * `createLoader` the child route is re-running also reports true, even if
+   * the layout copy is not replaced. Not used for the initial streamed read
+   * (that suspends).
+   */
   isLoading: boolean;
   error: Error | null;
   load: LoadFunction<T>;
@@ -124,6 +133,7 @@ export interface UseLoaderResult<T> {
 
 export interface UseFetchLoaderResult<T> {
   data: T | undefined;
+  /** Same family-keyed contract as {@link UseLoaderResult.isLoading}. */
   isLoading: boolean;
   error: Error | null;
   load: LoadFunction<T>;
@@ -261,6 +271,13 @@ function useLoaderInternal<T>(
     }
   }, [loaderId, bucketKey]);
 
+  // Held-navigation pin: a transition commit whose stream for this loader is
+  // still pending announces it (loader-store.ts announcePendingStreams, which
+  // documents the lane discipline); this optimistic update renders urgently
+  // on the held content and React reverts it when that transition commits,
+  // i.e. together with the new data.
+  const [streamPending, setStreamPending] = useOptimistic(false);
+
   const [sharedState, setSharedState] = useState<{
     bucketKey: string;
     snapshot: LoaderEntry;
@@ -295,6 +312,9 @@ function useLoaderInternal<T>(
         ephemeral: !hasContextData,
         group: hasGroups ? groupList : undefined,
         refetch: hasGroups ? groupRefetch : undefined,
+        onStreamPending: hasContextData
+          ? () => startTransition(() => setStreamPending(true))
+          : undefined,
       },
     );
     // eslint-disable-next-line react-hooks/exhaustive-deps -- intentional:
@@ -362,7 +382,7 @@ function useLoaderInternal<T>(
     : sharedSnapshot.hasValue
       ? (sharedSnapshot.value as T | undefined)
       : contextData;
-  const isLoading = localIsLoading || sharedSnapshot.isLoading;
+  const isLoading = localIsLoading || sharedSnapshot.isLoading || streamPending;
   const error = localError ?? sharedSnapshot.error;
 
   const throwOnError = options?.throwOnError ?? true;
@@ -549,7 +569,7 @@ function useLoaderInternal<T>(
  * @example Basic usage - accessing route loader data
  * ```tsx
  * "use client";
- * import { useLoader } from "rsc-router/client";
+ * import { useLoader } from "@rangojs/router/client";
  * import { CartLoader } from "../loaders/cart";
  *
  * // In route definition: loader(CartLoader)
@@ -597,7 +617,7 @@ export function useLoader<T>(
  * @example On-demand fetching
  * ```tsx
  * "use client";
- * import { useFetchLoader } from "rsc-router/client";
+ * import { useFetchLoader } from "@rangojs/router/client";
  * import { SearchLoader } from "../loaders/search";
  *
  * export function SearchResults() {
@@ -659,7 +679,7 @@ export function useFetchLoader<T>(
  * @example
  * ```tsx
  * "use client";
- * import { useLoader, useRefreshLoaders } from "rsc-router/client";
+ * import { useLoader, useRefreshLoaders } from "@rangojs/router/client";
  *
  * function Profile() {
  *   const { data } = useLoader(ProfileLoader, { key: userId, refreshGroup: "account" });

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

@@ -16,14 +16,18 @@
  * - transformHoistInlineDirective() for function-level hoisting
  */
 
-import type { Plugin } from "vite";
+import type { Plugin, Rollup } from "vite";
 import type { ModuleExportMeta } from "@vitejs/plugin-rsc/transforms";
 import path from "node:path";
-import MagicString from "magic-string";
 import { normalizePath, hashId } from "./expose-id-utils.js";
-import { createRangoDebugger, createCounter, NS } from "../debug.js";
+import type { Counter } from "../debug.js";
 
-const debug = createRangoDebugger(NS.transform);
+// No static import of `magic-string` or `../debug.js` (the `debug` package):
+// `rangoUseCacheTransform()` bundles this module into `dist/testing/vitest.js`,
+// whose static imports are node builtins only, and every package it needs
+// loads lazily, as `rangoUseClientTransform()`'s `vite` and plugin-rsc
+// imports do. src/__tests__/installed-vitest-config.test.ts loads that file
+// from a fixture holding only `package.json` and `dist/`.
 
 const CACHE_RUNTIME_IMPORT = "@rangojs/router/cache-runtime";
 
@@ -33,12 +37,13 @@ const LAYOUT_TEMPLATE_PATTERN = /\/(layout|template)\.(tsx?|jsx?)$/;
 
 export const USE_CACHE_DIRECTIVE_RE: RegExp = /^use cache(:\s*[\w-]+)?$/;
 
-export function useCacheTransform(): Plugin {
+/**
+ * @param counter `rango:transform` timing counter, created by `rango()`
+ *   (`createCounter` in ../debug.js); omitted when debugging is off.
+ */
+export function useCacheTransform(counter?: Counter): Plugin {
   let projectRoot = "";
   let isBuild = false;
-  let rscTransforms: typeof import("@vitejs/plugin-rsc/transforms") | null =
-    null;
-  const counter = createCounter(debug, "use-cache");
 
   return {
     name: "@rangojs/router:use-cache",
@@ -56,75 +61,15 @@ export function useCacheTransform(): Plugin {
     async transform(code, id) {
       // Only process in RSC environment
       if (this.environment?.name !== "rsc") return;
-
-      // Quick bail: no "use cache" in source
-      if (!code.includes("use cache")) return;
-
-      // Skip node_modules and virtual modules
-      if (id.includes("/node_modules/") || id.startsWith("\0")) return;
-
-      // Only JS/TS files
-      if (!/\.(tsx?|jsx?|mjs)$/.test(id)) return;
+      if (!isUseCacheCandidate(code, id)) return;
 
       const start = counter ? performance.now() : 0;
       try {
-        if (!rscTransforms) {
-          try {
-            rscTransforms = await import("@vitejs/plugin-rsc/transforms");
-          } catch {
-            return;
-          }
-        }
-
-        const {
-          hasDirective,
-          transformWrapExport,
-          transformHoistInlineDirective,
-        } = rscTransforms;
-
-        let ast: any;
-        try {
-          const { parseAst } = await import("vite");
-          ast = parseAst(code, { lang: "tsx" });
-        } catch {
-          return;
-        }
-
-        // plugin-rsc 0.5.34 `matchDirective` does `stmt.directive.match(...)`
-        // after `"directive" in node`. Vite/oxc parseAst now emits
-        // `directive: null` on ordinary ExpressionStatements, so a file that
-        // mixes a `"use cache"` function with a sibling handler whose first
-        // statement is an expression throws and the wrap is dropped.
-        stripNullDirectiveFields(ast);
-
-        const filePath = normalizePath(path.relative(projectRoot, id));
-        const isLayoutOrTemplate = LAYOUT_TEMPLATE_PATTERN.test(id);
-
-        if (hasDirective(ast.body, "use cache")) {
-          return transformFileLevelUseCache(
-            code,
-            ast,
-            filePath,
-            id,
-            isBuild,
-            isLayoutOrTemplate,
-            transformWrapExport,
-            hasDirective,
-          );
-        }
-
-        const functionResult = transformFunctionLevelUseCache(
-          code,
-          ast,
-          filePath,
-          id,
+        return await transformUseCache(code, id, {
+          root: projectRoot,
           isBuild,
-          transformHoistInlineDirective,
-        );
-
-        warnOnNearMissDirectives(ast, id, this.warn.bind(this));
-
-        if (functionResult) return functionResult;
+          warn: (message) => this.warn(message),
+        });
       } finally {
         counter?.record(id, performance.now() - start);
       }
@@ -132,7 +77,105 @@ export function useCacheTransform(): Plugin {
   };
 }
 
-function transformFileLevelUseCache(
+/** Options for {@link transformUseCache}. */
+export interface UseCacheTransformOptions {
+  /** Root the ids are relative to (Vite's `config.root`). */
+  root: string;
+  /** Build ids hash the path (`hashId`); dev ids are `<path>#<export>`. */
+  isBuild: boolean;
+  /** Sink for the near-miss directive warning. */
+  warn: (message: string) => void;
+  /**
+   * Called when `@vitejs/plugin-rsc/transforms` fails to load; the module is
+   * then left unwrapped. The rango plugin omits it (skip silently).
+   */
+  onTransformsError?: (error: unknown) => void;
+}
+
+/** Whether a module may carry a `"use cache"` directive the transform wraps. */
+export function isUseCacheCandidate(code: string, id: string): boolean {
+  return (
+    // Quick bail: no "use cache" in source
+    code.includes("use cache") &&
+    // Skip node_modules and virtual modules
+    !id.includes("/node_modules/") &&
+    !id.startsWith("\0") &&
+    // Only JS/TS files
+    /\.(tsx?|jsx?|mjs)$/.test(id)
+  );
+}
+
+let rscTransforms: typeof import("@vitejs/plugin-rsc/transforms") | null = null;
+
+/**
+ * Wrap a module's `"use cache"` functions with `registerCachedFunction`. The
+ * rango plugin runs it in the rsc environment; `rangoUseCacheTransform()`
+ * (testing/vitest.ts) runs it in a Vitest project, whose environment is `ssr`.
+ * Call it only for an {@link isUseCacheCandidate} module.
+ */
+export async function transformUseCache(
+  code: string,
+  id: string,
+  options: UseCacheTransformOptions,
+): Promise<{ code: string; map: Rollup.ExistingRawSourceMap } | undefined> {
+  if (!rscTransforms) {
+    try {
+      rscTransforms = await import("@vitejs/plugin-rsc/transforms");
+    } catch (error) {
+      options.onTransformsError?.(error);
+      return;
+    }
+  }
+
+  const { hasDirective, transformWrapExport, transformHoistInlineDirective } =
+    rscTransforms;
+
+  let ast: any;
+  try {
+    const { parseAst } = await import("vite");
+    ast = parseAst(code, { lang: "tsx" });
+  } catch {
+    return;
+  }
+
+  // plugin-rsc 0.5.34 `matchDirective` does `stmt.directive.match(...)`
+  // after `"directive" in node`. Vite/oxc parseAst now emits
+  // `directive: null` on ordinary ExpressionStatements, so a file that
+  // mixes a `"use cache"` function with a sibling handler whose first
+  // statement is an expression throws and the wrap is dropped.
+  stripNullDirectiveFields(ast);
+
+  const filePath = normalizePath(path.relative(options.root, id));
+  const isLayoutOrTemplate = LAYOUT_TEMPLATE_PATTERN.test(id);
+
+  if (hasDirective(ast.body, "use cache")) {
+    return transformFileLevelUseCache(
+      code,
+      ast,
+      filePath,
+      id,
+      options.isBuild,
+      isLayoutOrTemplate,
+      transformWrapExport,
+      hasDirective,
+    );
+  }
+
+  const functionResult = transformFunctionLevelUseCache(
+    code,
+    ast,
+    filePath,
+    id,
+    options.isBuild,
+    transformHoistInlineDirective,
+  );
+
+  warnOnNearMissDirectives(ast, id, options.warn);
+
+  if (functionResult) return functionResult;
+}
+
+async function transformFileLevelUseCache(
   code: string,
   ast: any,
   filePath: string,
@@ -193,6 +236,7 @@ function transformFileLevelUseCache(
   }
 
   if (exportNames.length === 0) {
+    const { default: MagicString } = await import("magic-string");
     const s = new MagicString(code);
     const directive = findFileLevelDirective(ast);
     if (directive) {