@rangojs/router 0.0.0-experimental.132 → 0.0.0-experimental.133

package/src/testing/flight.ts

@@ -43,6 +43,10 @@ import {
 } from "../server/request-context.js";
 import { seedVariables, type VarsInit } from "./internal/seed-vars.js";
 import { normalizeFlight } from "./flight-normalize.js";
+import { resolveThemeConfig } from "../theme/constants.js";
+import type { ThemeConfig } from "../theme/types.js";
+import type { SegmentCacheStore } from "../cache/types.js";
+import type { CacheProfile } from "../cache/profile-registry.js";
 import type { RscPayload } from "../rsc/types.js";
 import type { ResolvedSegment } from "../types.js";
 
@@ -86,6 +90,23 @@ export interface RenderToFlightStringOptions {
    * Object form (`{ user }`) or `[key, value]` tuples (`[[userVar, u]]`).
    */
   vars?: VarsInit;
+  /**
+   * Theme config in the same shape `createRouter({ theme })` takes (e.g. `true`
+   * or `{ themes: [...] }`). Without it `getRequestContext().theme` is `undefined`
+   * and `ctx.setTheme` is inert — pass one to render a server component that
+   * reads `ctx.theme`. Threaded into the SAME createRequestContext renderHandler
+   * uses, so the two Flight primitives expose theme identically.
+   */
+  theme?: ThemeConfig | true;
+  /**
+   * Cache store backing a `"use cache"` function the rendered server tree
+   * invokes. Without it, `registerCachedFunction` takes the uncached bypass and
+   * the cached path is NOT exercised. Pair with `cacheProfiles` so a
+   * `"use cache: profileName"` directive resolves its profile.
+   */
+  cacheStore?: SegmentCacheStore;
+  /** Cache profiles in the `createRouter({ cacheProfiles })` shape. */
+  cacheProfiles?: Record<string, CacheProfile>;
 }
 
 const DEFAULT_URL = "http://localhost/";
@@ -191,6 +212,10 @@ export async function serializeToFlightString(
     request,
     url,
     variables: seedVariables({}, opts.vars),
+    themeConfig:
+      opts.theme === undefined ? undefined : resolveThemeConfig(opts.theme),
+    cacheStore: opts.cacheStore,
+    cacheProfiles: opts.cacheProfiles,
   });
 
   return runWithRequestContext(ctx, () => {

package/src/testing/internal/context.ts

@@ -12,6 +12,7 @@ import {
   runWithRequestContext,
   type RequestContext,
 } from "../../server/request-context.js";
+import { drainOnResponseCallbacks } from "../../rsc/helpers.js";
 import { resolveLocationStateEntries } from "../../browser/react/location-state-shared.js";
 import { createReverseFunction } from "../../router/handler-context.js";
 import { normalizeBasename } from "../../router/basename.js";
@@ -259,6 +260,7 @@ export function buildRunResponse<TEnv>(
   thrown: unknown,
 ): Response {
   const stub = ctx.res;
+  let response: Response;
   if (thrown instanceof Response) {
     const headers = new Headers(thrown.headers);
     for (const cookie of stub.headers.getSetCookie()) {
@@ -268,9 +270,30 @@ export function buildRunResponse<TEnv>(
       if (name.toLowerCase() === "set-cookie") return;
       if (!headers.has(name)) headers.set(name, value);
     });
-    return new Response(null, { status: thrown.status, headers });
+    response = new Response(null, { status: thrown.status, headers });
+  } else {
+    response = new Response(null, {
+      status: stub.status,
+      headers: stub.headers,
+    });
   }
-  return new Response(null, { status: stub.status, headers: stub.headers });
+  // Mirror production response finalization: every response-finalization path
+  // drains ctx.onResponse() callbacks (createResponseWithMergedHeaders /
+  // finalizeResponse). buildRunResponse runs AFTER runWithRequestContext has
+  // exited, so _getRequestContext() (and finalizeResponse) would no-op — drain
+  // ctx._onResponseCallbacks explicitly. Reuses the SAME production drain
+  // (swap-before-iterate + external-redirect brand preservation) so a callback's
+  // header mutations / returned replacement Response are reflected on the result
+  // the harness surfaces. rsc/helpers is plugin-rsc-free on its eager graph
+  // (dispatch.ts in this same testing barrel already statically imports from it).
+  // drainOnResponseCallbacks is typed against the default-env RequestContext (it
+  // touches only the env-agnostic _onResponseCallbacks); the harness ctx is
+  // RequestContext<TEnv> — assignable in the router's own tsc but not when a
+  // consumer pins a concrete Env, so cast to the param type.
+  return drainOnResponseCallbacks(
+    ctx as Parameters<typeof drainOnResponseCallbacks>[0],
+    response,
+  );
 }
 
 export function buildRunSnapshot<TEnv>(

package/src/testing/render-handler.ts

@@ -276,7 +276,9 @@ export async function renderHandler<TEnv = any>(
           handlePushes.set(handle, pushed);
         });
       }
-      if (loaderSeeds.has(item)) return loaderSeeds.get(item);
+      // Production ctx.use(Loader) ALWAYS returns a Promise (the cached loader
+      // promise); wrap the seed so a handler composing on the result matches.
+      if (loaderSeeds.has(item)) return Promise.resolve(loaderSeeds.get(item));
       throw new RenderHandlerSetupError(
         `renderHandler: ctx.use(loader) was not seeded. Pass ` +
           `{ loaders: [[YourLoader, data]] } for each loader the handler reads.`,

package/src/testing/render-route.tsx

@@ -250,6 +250,20 @@ export interface RenderRouteOptions {
    * component.
    */
   theme?: ThemeConfig | true;
+  /**
+   * CSP nonce to seed via NonceContext, so a component calling `useNonce()`
+   * (e.g. an analytics/GTM head-script component) sees this value — mirroring
+   * what the SSR renderer provides per request. Defaults to undefined (the
+   * browser default), matching production client behavior.
+   *
+   * @example
+   * const { getByTestId } = await renderRoute(
+   *   [{ path: "/", Component: NonceProbe }],
+   *   { nonce: "test-nonce" },
+   * );
+   * expect(getByTestId("nonce").textContent).toBe("test-nonce");
+   */
+  nonce?: string;
 }
 
 /**
@@ -536,6 +550,7 @@ export async function renderRoute(
         themeConfig={
           options.theme === undefined ? null : resolveThemeConfig(options.theme)
         }
+        nonce={options.nonce}
       />,
     );
   });

package/src/testing/run-loader.ts

@@ -106,7 +106,9 @@ export interface RunLoaderOptions<TEnv = any> {
   basename?: string;
   /**
    * Theme config in the same shape `createRouter({ theme })` takes (e.g. `true`
-   * or `{ themes: [...] }`). Without it `ctx.theme`/`ctx.setTheme` are inert.
+   * or `{ themes: [...] }`). Seeds the request's theme config so nested handler
+   * or cache contexts created from this loader observe it. Loaders themselves do
+   * not expose `ctx.theme`/`ctx.setTheme` (those are handler/middleware-only).
    */
   theme?: ThemeConfig | true;
   /** Environment bindings surfaced as `ctx.env`. */
@@ -284,8 +286,13 @@ function runWithLoaderContext<R>(
         }
         if (handleSeeds.has(dep)) return handleSeeds.get(dep);
         if (isHandle(dep)) return collectHandle(dep, []);
-        if (loaderSeeds.has(dep)) return loaderSeeds.get(dep);
-        if (opts.use) return opts.use(dep as LoaderDefinition<any, any>);
+        // Production ctx.use(Loader) ALWAYS returns a Promise (the cached loader
+        // promise). The seeded path must match, so a consumer composing on the
+        // result (ctx.use(Dep).then(...), Promise.race, etc.) works the same as
+        // production and the real-fn delegate path below.
+        if (loaderSeeds.has(dep)) return Promise.resolve(loaderSeeds.get(dep));
+        if (opts.use)
+          return Promise.resolve(opts.use(dep as LoaderDefinition<any, any>));
         return reqCtx.use(dep as LoaderDefinition<any, any>);
       }) as LoaderContext<any, any>["use"],
       method: opts.method ?? "GET",

package/src/theme/ThemeProvider.tsx

@@ -26,7 +26,7 @@ import type {
   ThemeContextValue,
   ThemeProviderProps,
 } from "./types.js";
-import { THEME_COOKIE } from "./constants.js";
+import { THEME_COOKIE, isValidTheme, warnInvalidTheme } from "./constants.js";
 
 function getSystemTheme(): ResolvedTheme {
   if (typeof window !== "undefined" && window.matchMedia) {
@@ -152,6 +152,15 @@ export function ThemeProvider({
 
   const setTheme = useCallback(
     (newTheme: Theme) => {
+      // Shared guard (isValidTheme) used by the server ctx.setTheme too: reject
+      // any value not in the configured theme set, AND reject "system" when
+      // system detection is off (applyThemeToDocument would write a bogus
+      // class="system"). Keeps the cookie from holding a value the server would
+      // reinterpret as defaultTheme on the next SSR (desyncing markup).
+      if (!isValidTheme(newTheme, config)) {
+        warnInvalidTheme(newTheme, config);
+        return;
+      }
       setThemeState(newTheme);
       writeThemeToCookie(config.storageKey, newTheme);
       writeThemeToStorage(config.storageKey, newTheme);
@@ -191,11 +200,16 @@ export function ThemeProvider({
       const newTheme = e.newValue;
       if (!newTheme) return;
 
-      // Validate and apply
-      if (newTheme === "system" || config.themes.includes(newTheme)) {
-        setThemeState(newTheme as Theme);
-        applyThemeToDocument(newTheme as Theme, config);
-      }
+      // A cross-tab storage event can carry any value (another tab, or stale
+      // localStorage). Reuse the shared validity rule: reject anything not a
+      // configured theme, AND reject "system" when system detection is off (it
+      // would apply a bogus class="system"). An invalid received value falls back
+      // to defaultTheme rather than applying as-is.
+      const applied: Theme = isValidTheme(newTheme, config)
+        ? (newTheme as Theme)
+        : config.defaultTheme;
+      setThemeState(applied);
+      applyThemeToDocument(applied, config);
     };
 
     window.addEventListener("storage", handleStorageChange);

package/src/theme/ThemeScript.tsx

@@ -8,17 +8,21 @@
  *
  * Must be placed in the <head> element of your document, before any stylesheets.
  *
+ * Note: when theme is enabled in the router config, `<MetaTags />` ALREADY
+ * renders this FOUC script. Use `<ThemeScript />` only if you do NOT render
+ * `<MetaTags />`. 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
+ * // In your document component. Use ThemeScript only when you do not render MetaTags.
  * import { ThemeScript } from "@rangojs/router/theme";
  *
  * export function Document({ children }) {
  *   return (
  *     <html lang="en" suppressHydrationWarning>
  *       <head>
- *         <ThemeScript />
- *         <MetaTags />
+ *         <ThemeScript config={config} />
  *       </head>
  *       <body>{children}</body>
  *     </html>

package/src/theme/constants.ts

@@ -2,7 +2,7 @@
  * Default values for theme configuration
  */
 
-import type { ResolvedThemeConfig, ThemeConfig } from "./types.js";
+import type { ResolvedThemeConfig, Theme, ThemeConfig } from "./types.js";
 
 export const THEME_DEFAULTS = {
   defaultTheme: "system",
@@ -23,6 +23,45 @@ export const THEME_COOKIE: {
   sameSite: "lax",
 };
 
+/**
+ * Single owner of the setTheme validity rule, shared by the client
+ * (ThemeProvider) and server (ctx.setTheme) guards so they cannot drift.
+ *
+ * A theme is valid when it is one of the configured concrete themes, OR
+ * "system" but only while system detection is enabled. Rejecting "system" when
+ * `enableSystem` is false is load-bearing: applyThemeToDocument would otherwise
+ * leave "system" unresolved and write a bogus class="system" / colorScheme
+ * ="system" on <html> (the same bogus value resolveThemeConfig coerces away for
+ * the default).
+ */
+export function isValidTheme(
+  theme: string,
+  config: Pick<ResolvedThemeConfig, "themes" | "enableSystem">,
+): boolean {
+  if (theme === "system") return config.enableSystem;
+  return config.themes.includes(theme);
+}
+
+/**
+ * Emit the shared "[Theme] Invalid theme value" warning. One owner of the
+ * message string so the client and server guards stay byte-identical.
+ *
+ * The valid-values list mirrors isValidTheme: "system" is only listed when
+ * enableSystem is true, otherwise the message would advertise a value the guard
+ * itself rejects.
+ */
+export function warnInvalidTheme(
+  theme: string,
+  config: Pick<ResolvedThemeConfig, "themes" | "enableSystem">,
+): void {
+  const validValues = config.enableSystem
+    ? ["system", ...config.themes]
+    : config.themes;
+  console.warn(
+    `[Theme] Invalid theme value: "${theme}". Valid values: ${validValues.join(", ")}`,
+  );
+}
+
 export function resolveThemeConfig(
   config: ThemeConfig | true,
 ): ResolvedThemeConfig {
@@ -37,12 +76,24 @@ export function resolveThemeConfig(
     value[theme] = config.value?.[theme] ?? theme;
   }
 
+  const enableSystem = config.enableSystem ?? THEME_DEFAULTS.enableSystem;
+
+  // When system detection is disabled, "system" is not a valid resolved theme.
+  // Coerce both the unset default and an explicit defaultTheme:"system" to the
+  // first concrete theme, so the FOUC script / ThemeProvider never apply a bogus
+  // class="system" / colorScheme="system" on <html>.
+  const requestedDefault = config.defaultTheme ?? THEME_DEFAULTS.defaultTheme;
+  const defaultTheme =
+    !enableSystem && requestedDefault === "system"
+      ? (themes[0] as Theme)
+      : requestedDefault;
+
   return {
-    defaultTheme: config.defaultTheme ?? THEME_DEFAULTS.defaultTheme,
+    defaultTheme,
     themes,
     attribute: config.attribute ?? THEME_DEFAULTS.attribute,
     storageKey: config.storageKey ?? THEME_DEFAULTS.storageKey,
-    enableSystem: config.enableSystem ?? THEME_DEFAULTS.enableSystem,
+    enableSystem,
     enableColorScheme:
       config.enableColorScheme ?? THEME_DEFAULTS.enableColorScheme,
     value,

package/src/theme/theme-script.ts

@@ -11,6 +11,7 @@
  */
 
 import type { ResolvedThemeConfig } from "./types.js";
+import { escapeJsonForScript } from "../escape-script.js";
 
 /**
  * Generate the inline script for theme initialization
@@ -24,13 +25,13 @@ import type { ResolvedThemeConfig } from "./types.js";
 export function generateThemeScript(config: ResolvedThemeConfig): string {
   const script = `
 (function() {
-  var storageKey = ${JSON.stringify(config.storageKey)};
-  var defaultTheme = ${JSON.stringify(config.defaultTheme)};
-  var attribute = ${JSON.stringify(config.attribute)};
+  var storageKey = ${escapeJsonForScript(JSON.stringify(config.storageKey))};
+  var defaultTheme = ${escapeJsonForScript(JSON.stringify(config.defaultTheme))};
+  var attribute = ${escapeJsonForScript(JSON.stringify(config.attribute))};
   var enableSystem = ${config.enableSystem};
   var enableColorScheme = ${config.enableColorScheme};
-  var valueMap = ${JSON.stringify(config.value)};
-  var themes = ${JSON.stringify(config.themes)};
+  var valueMap = ${escapeJsonForScript(JSON.stringify(config.value))};
+  var themes = ${escapeJsonForScript(JSON.stringify(config.themes))};
 
   function getStoredTheme() {
     var cookies = document.cookie.split(';');
@@ -83,13 +84,26 @@ export function generateThemeScript(config: ResolvedThemeConfig): string {
   }
 
   var stored = getStoredTheme();
-  var theme = stored && (stored === 'system' || themes.indexOf(stored) !== -1)
+  // A stored value is valid when it is a configured theme, OR "system" but only
+  // while system detection is enabled. A stored "system" with enableSystem=false
+  // (an old cookie/localStorage, or a value pushed cross-tab) must fall back to
+  // defaultTheme — otherwise resolveTheme returns "system" unresolved and
+  // applyTheme writes a bogus class="system" / colorScheme="system" on <html>.
+  // Same rule as isValidTheme (constants.ts), inlined since this is a string.
+  var systemAllowed = stored === 'system' && enableSystem;
+  var theme = stored && (systemAllowed || themes.indexOf(stored) !== -1)
     ? stored
     : defaultTheme;
 
   applyTheme(theme);
 
-  if (enableSystem && typeof window !== 'undefined' && window.matchMedia) {
+  // Idempotency guard: MetaTags auto-injects this script when theme is enabled,
+  // and ThemeScript is also a public component for the same job. If a consumer
+  // renders both, the IIFE runs twice; without this guard the second run would
+  // register a SECOND, never-removed matchMedia('change') listener (a leak).
+  // The flag is keyed by storageKey so independent theme configs don't collide.
+  var flagKey = '__rangoThemeListener_' + storageKey;
+  if (enableSystem && typeof window !== 'undefined' && window.matchMedia && !window[flagKey]) {
     try {
       window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', function() {
         var current = getStoredTheme() || defaultTheme;
@@ -97,6 +111,7 @@ export function generateThemeScript(config: ResolvedThemeConfig): string {
           applyTheme('system');
         }
       });
+      window[flagKey] = true;
     } catch (e) {
       // Older browsers may not support addEventListener on MediaQueryList
     }

package/src/types/request-scope.ts

@@ -25,9 +25,14 @@ export interface ExecutionContext {
  * of inventing its own fallback policy.
  */
 export function fireAndForgetWaitUntil(fn: () => Promise<void>): void {
-  fn().catch((err) =>
-    console.error("[waitUntil] Background task failed:", err),
-  );
+  // Defer fn() invocation to a microtask so a SYNCHRONOUS throw in a non-async
+  // callback (e.g. `() => { somethingThatThrows(); return p; }`) becomes a
+  // rejected promise we catch here, not an exception that escapes into the
+  // request flow. waitUntil is fire-and-forget: a background-task failure must
+  // never break the response.
+  Promise.resolve()
+    .then(fn)
+    .catch((err) => console.error("[waitUntil] Background task failed:", err));
 }
 
 /**

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

@@ -8,14 +8,21 @@ const debug = createRangoDebugger(NS.transform);
  * The react-server-dom vendor files are shipped as CJS which doesn't work in browsers.
  */
 export function createCjsToEsmPlugin(): Plugin {
+  // Picked from Vite's resolved mode, not process.env.NODE_ENV, so the dev vs
+  // production vendor variant tracks the build mode the user actually ran.
+  let isProduction = false;
+
   return {
     name: "@rangojs/router:cjs-to-esm",
     enforce: "pre",
+    configResolved(config) {
+      isProduction = config.isProduction;
+    },
     transform(code, id) {
       const cleanId = id.split("?")[0].replaceAll("\\", "/");
 
       if (cleanId.includes("vendor/react-server-dom/client.browser.js")) {
-        const isProd = process.env.NODE_ENV === "production";
+        const isProd = isProduction;
         const cjsFile = isProd
           ? "./cjs/react-server-dom-webpack-client.browser.production.js"
           : "./cjs/react-server-dom-webpack-client.browser.development.js";

package/src/vite/plugins/expose-id-utils.ts

@@ -210,7 +210,16 @@ export function countArgs(
   while (i < endPos) {
     const skipped = skipStringOrComment(code, i);
     if (skipped > i) {
-      hasContent = true;
+      // A comment is transparent: `createHandle(/* meta */)` has ZERO real
+      // arguments, so a comment-only region must NOT set hasContent (else the
+      // fallback path would count it as 1 arg and inject `, "id"` over an elided
+      // first slot — a syntax error). A string/template literal IS content.
+      const ch = code[i];
+      const isComment =
+        ch === "/" &&
+        i + 1 < code.length &&
+        (code[i + 1] === "/" || code[i + 1] === "*");
+      if (!isComment) hasContent = true;
       i = skipped;
       continue;
     }

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

@@ -3,35 +3,24 @@ import { makeStubId } from "../expose-id-utils.js";
 import type { HandlerTransformConfig, CreateExportBinding } from "./types.js";
 import { isExportOnlyFile } from "./export-analysis.js";
 
-function analyzeCreateHandleArgs(
-  code: string,
-  startPos: number,
-  endPos: number,
-): { hasArgs: boolean } {
-  const content = code.slice(startPos, endPos).trim();
-  return { hasArgs: content.length > 0 };
-}
-
 export function transformHandles(
   bindings: CreateExportBinding[],
   s: MagicString,
-  code: string,
   filePath: string,
   isBuild: boolean,
 ): boolean {
   let hasChanges = false;
   for (const binding of bindings) {
     const exportName = binding.exportNames[0];
-    const args = analyzeCreateHandleArgs(
-      code,
-      binding.callOpenParenPos + 1,
-      binding.callCloseParenPos,
-    );
 
     const handleId = makeStubId(filePath, exportName, isBuild);
 
+    // Branch on the AST-derived argCount, not a string-trim of the raw arg
+    // slice. A comment-only arg list (`createHandle(/* meta */)`) trims to
+    // non-empty but is zero real arguments; injecting `, "id"` would emit
+    // `createHandle(/* meta */, "id")` — an elided first arg / syntax error.
     let paramInjection: string;
-    if (!args.hasArgs) {
+    if (binding.argCount === 0) {
       paramInjection = `undefined, "${handleId}"`;
     } else {
       paramInjection = `, "${handleId}"`;

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

@@ -20,11 +20,18 @@ export function generateClientLoaderStubs(
   const lines: string[] = [];
 
   for (const binding of bindings) {
-    for (const name of binding.exportNames) {
-      const loaderId = makeStubId(filePath, name, isBuild);
-      lines.push(
-        `export const ${name} = { __brand: "loader", $$id: "${loaderId}" };`,
-      );
+    // Aliases share the primary export's id (matches the server side, which
+    // registers only exportNames[0] in the loader registry, and the mixed-type
+    // whole-file path). Emitting a distinct makeStubId per alias would make a
+    // client component importing the alias fetch an id absent from the server
+    // registry, so the fetchable-loader request would 404.
+    const primaryName = binding.exportNames[0];
+    const loaderId = makeStubId(filePath, primaryName, isBuild);
+    lines.push(
+      `export const ${primaryName} = { __brand: "loader", $$id: "${loaderId}" };`,
+    );
+    for (const alias of binding.exportNames.slice(1)) {
+      lines.push(`export const ${alias} = ${primaryName};`);
     }
   }
 

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

@@ -90,7 +90,12 @@ export function transformRouter(
     const closeParen = findMatchingParen(code, parenPos + 1);
     const callArgs = code.slice(parenPos + 1, closeParen);
 
-    if (callArgs.includes("$$id")) continue;
+    // Skip ONLY a call we already injected into. The injected marker is the
+    // unique `$$routeNames: <var>` property; a bare `$$id` substring check
+    // would also match a user value/comment that merely contains the text
+    // "$$id" (e.g. `createRouter({ meta: { note: "see $$id docs" } })`),
+    // silently dropping named-route wiring for a legitimate config.
+    if (callArgs.includes(`$$routeNames: ${routeNamesVar}`)) continue;
 
     const sourceFilePath = absolutePath ?? filePath;
     const lineNumber = code.slice(0, callStart).split("\n").length;

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

@@ -762,7 +762,6 @@ ${lazyImports.join(",\n")}
             transformHandles(
               getBindings(code, fnNames),
               s,
-              code,
               filePath,
               isBuild,
             ) || changed;

package/src/vite/plugins/version-plugin.ts

@@ -1,5 +1,6 @@
 import { parseAst, type Plugin } from "vite";
 import { VIRTUAL_IDS, getVirtualVersionContent } from "./virtual-entries.js";
+import { hasUseClientDirective } from "../utils/directive-prologue.js";
 
 interface ClientModuleSignature {
   key: string;
@@ -16,6 +17,10 @@ function normalizeModuleId(id: string): string {
 function getClientModuleSignature(
   source: string,
 ): ClientModuleSignature | undefined {
+  // Same leading-directive sniff the rango HMR plugin uses (shared helper, so the
+  // two agree on what counts as a client module). A parse failure yields false.
+  if (!hasUseClientDirective(source)) return undefined;
+
   let program: any;
   try {
     program = parseAst(source, { lang: "tsx" });
@@ -23,23 +28,6 @@ function getClientModuleSignature(
     return undefined;
   }
 
-  let isUseClient = false;
-  for (const node of program.body ?? []) {
-    if (
-      node?.type === "ExpressionStatement" &&
-      node.expression?.type === "Literal" &&
-      typeof node.expression.value === "string"
-    ) {
-      if (node.expression.value === "use client") {
-        isUseClient = true;
-      }
-      continue;
-    }
-    break;
-  }
-
-  if (!isUseClient) return undefined;
-
   const exports = new Set<string>();
   let hasDefault = false;
   let hasExportAll = false;

package/src/vite/plugins/virtual-entries.ts

@@ -20,11 +20,16 @@ async function initializeApp() {
     createTemporaryReferenceSet,
   };
 
-  await initBrowserApp({ rscStream, deps });
+  // initBrowserApp resolves the initial payload and returns the browser app
+  // context, including strictMode (default true) from createRouter. StrictMode
+  // is the default; createRouter({ strictMode: false }) ships the opt-out in the
+  // payload metadata. StrictMode emits no DOM, so toggling never changes markup.
+  const { strictMode } = await initBrowserApp({ rscStream, deps });
 
+  const app = createElement(Rango);
   hydrateRoot(
     document,
-    createElement(StrictMode, null, createElement(Rango))
+    strictMode === false ? app : createElement(StrictMode, null, app)
   );
 }
 
@@ -79,6 +84,11 @@ export default function handler(request, env) {
     _handler = createRSCHandler({
       router,
       version: VERSION,
+      // Forward the router's CSP nonce provider. createRSCHandler reads the
+      // provider only from options.nonce; without this, createRouter({ nonce })
+      // is silently dropped on the Node preset (the Cloudflare path wires it via
+      // router.fetch). router.nonce is undefined when unconfigured, a safe no-op.
+      nonce: router.nonce,
       deps: {
         renderToReadableStream,
         decodeReply,

package/src/vite/rango.ts

@@ -1,4 +1,4 @@
-import type { PluginOption } from "vite";
+import { type PluginOption } from "vite";
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { exposeActionId } from "./plugins/expose-action-id.js";
@@ -37,6 +37,13 @@ import { createRangoDebugger, NS } from "./debug.js";
 
 const debugConfig = createRangoDebugger(NS.config);
 
+// The leading-directive 'use client' sniff is shared with version-plugin's
+// getClientModuleSignature so the two cannot drift. Imported for local use by the
+// HMR transform below and re-exported because the E8 sniff test imports it from
+// this module.
+import { hasUseClientDirective } from "./utils/directive-prologue.js";
+export { hasUseClientDirective };
+
 /**
  * Vite plugin for @rangojs/router.
  *
@@ -335,6 +342,12 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
                     "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge",
                   ),
                 ],
+                // Vite 8 does not propagate the top-level optimizeDeps.exclude
+                // (set in config()) to non-client envs, so the rsc env must set
+                // it explicitly — mirroring the node ssr env and the cloudflare
+                // rsc env. Without it a strict-pnpm npm-installed app can try to
+                // pre-bundle the router's own subpath entries and fail.
+                exclude: excludeDeps,
                 rolldownOptions: sharedRolldownOptions,
               },
             },
@@ -396,11 +409,7 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
 
       try {
         const source = readFileSync(file, "utf-8");
-        const trimmed = source.trimStart();
-        if (
-          trimmed.startsWith('"use client"') ||
-          trimmed.startsWith("'use client'")
-        ) {
+        if (hasUseClientDirective(source)) {
           return [];
         }
       } catch {}