veryfront 0.0.84 → 0.0.88

package/src/src/transforms/esm/http-bundler.ts

@@ -156,47 +156,137 @@ export function createHTTPPlugin(): Plugin {
 }
 
 /**
- * Ensure esm.sh URLs have ?external=react for SSR.
- * This makes them import React as a bare specifier, which deno.json resolves.
+ * Ensure esm.sh URLs have external=react,react-dom for SSR.
+ * This makes them import React as bare specifiers, which the import map resolves.
  *
  * Uses two esm.sh features:
- * - `external=react` - Don't bundle React, let import map resolve it
+ * - `external=react,react-dom` - Don't bundle React/ReactDOM, let import map resolve them
  * - `deps=react@X,react-dom@X` - Pin dependency versions to prevent mismatches
+ *
+ * Logic for external handling:
+ * 1. If no `external=` param → add `external=react,react-dom`
+ * 2. If `external=X` exists but no `react` → append `,react,react-dom`
+ * 3. If has `react` but no `react-dom` → append `,react-dom`
+ * 4. If has both `react` AND `react-dom` → leave alone
+ *
+ * @param code - Source code to process
+ * @param _cacheDir - Unused (kept for API compatibility)
+ * @param hash - Hash for logging
+ * @param reactVersion - React version for deps param (defaults to REACT_VERSION)
  */
 export function bundleHttpImports(
   code: string,
   _cacheDir: string,
   hash: string,
+  reactVersion?: string,
 ): string | Promise<string> {
   const has = hasHttpImports(code);
   logger.debug(`${LOG_PREFIX} Check: hasHttp=${has}, hash=${hash.slice(0, 8)}`);
   if (!has) return code;
 
+  const version = reactVersion ?? REACT_VERSION;
+
   return replaceSpecifiers(code, (specifier) => {
+    // Handle relative esm.sh paths like "/react-dom?target=es2022" or "/hoist-non-react-statics@..."
+    // These are returned by esm.sh stub modules and need to be converted to full URLs
+    if (specifier.startsWith("/") && !specifier.startsWith("//")) {
+      const fullUrl = `https://esm.sh${specifier}`;
+      // Recursively process as full URL (will add external params if needed)
+      const isReactPackage = /^\/react(-dom)?(@|\/|\?|$)/.test(specifier);
+      if (isReactPackage) {
+        // React packages - just ensure target and return full URL
+        if (!specifier.includes("target=")) {
+          const joiner = specifier.includes("?") ? "&" : "?";
+          return `${fullUrl}${joiner}target=es2022`;
+        }
+        return fullUrl;
+      }
+      // Non-React packages - add external params
+      const params: string[] = [];
+      if (!specifier.includes("target=")) params.push("target=es2022");
+      if (!specifier.includes("external=")) params.push("external=react,react-dom");
+      if (!specifier.includes("deps=")) params.push(`deps=react@${version},react-dom@${version}`);
+      if (params.length === 0) return fullUrl;
+      const joiner = specifier.includes("?") ? "&" : "?";
+      return `${fullUrl}${joiner}${params.join("&")}`;
+    }
+
     const isEsmSh = specifier.startsWith("https://esm.sh/") ||
       specifier.startsWith("http://esm.sh/");
     const isVfEsm = specifier.startsWith("https://esm.veryfront.com/");
     if (!isEsmSh && !isVfEsm) return null;
 
+    // Don't modify React/ReactDOM package URLs themselves
     const isReactPackage = /\/react(-dom)?(@|\/|$)/.test(specifier);
+    if (isReactPackage) {
+      // Just ensure target is set for React packages
+      if (!specifier.includes("target=")) {
+        const joiner = specifier.includes("?") ? "&" : "?";
+        return `${specifier}${joiner}target=es2022`;
+      }
+      return null;
+    }
 
+    // For non-React packages: ensure external=react,react-dom and deps
     const params: string[] = [];
 
     if (!specifier.includes("target=")) {
       params.push("target=es2022");
     }
 
-    // Only add external and deps to non-React packages
-    // Use external=react to not bundle React (let import map resolve it)
-    // Use deps=react@X,react-dom@X to pin dependency versions
-    if (!isReactPackage) {
-      if (!specifier.includes("external=react")) {
-        params.push("external=react");
+    // Handle external param - ensure both react AND react-dom are externalized
+    const hasExternal = specifier.includes("external=");
+    const hasReactExternal = specifier.includes("external=react") ||
+      /external=[^&]*\breact\b/.test(specifier);
+    const hasReactDomExternal = /external=[^&]*react-dom/.test(specifier);
+
+    if (!hasExternal) {
+      // No external param - add both
+      params.push("external=react,react-dom");
+    } else if (!hasReactExternal) {
+      // Has external but no react - append react,react-dom
+      // This requires modifying existing param, so we'll use URL parsing
+      try {
+        const url = new URL(specifier);
+        const existing = url.searchParams.get("external") || "";
+        url.searchParams.set("external", `${existing},react,react-dom`);
+        // Return full modified URL and skip other param additions
+        if (!specifier.includes("target=")) {
+          url.searchParams.set("target", "es2022");
+        }
+        if (!specifier.includes("deps=")) {
+          url.searchParams.set("deps", `react@${version},react-dom@${version}`);
+        }
+        logger.debug(`${LOG_PREFIX} ${specifier} -> ${url.toString()}`);
+        return url.toString();
+      } catch {
+        // Fallback: just add as new param (may create duplicate)
+        params.push("external=react,react-dom");
       }
-      if (!specifier.includes("deps=")) {
-        params.push(`deps=react@${REACT_VERSION},react-dom@${REACT_VERSION}`);
+    } else if (!hasReactDomExternal) {
+      // Has react but not react-dom - append react-dom
+      try {
+        const url = new URL(specifier);
+        const existing = url.searchParams.get("external") || "";
+        url.searchParams.set("external", `${existing},react-dom`);
+        if (!specifier.includes("target=")) {
+          url.searchParams.set("target", "es2022");
+        }
+        if (!specifier.includes("deps=")) {
+          url.searchParams.set("deps", `react@${version},react-dom@${version}`);
+        }
+        logger.debug(`${LOG_PREFIX} ${specifier} -> ${url.toString()}`);
+        return url.toString();
+      } catch {
+        // Fallback
+        params.push("external=react-dom");
       }
     }
+    // else: has both react and react-dom - no external changes needed
+
+    if (!specifier.includes("deps=")) {
+      params.push(`deps=react@${version},react-dom@${version}`);
+    }
 
     if (params.length === 0) return null;
 

package/src/src/transforms/esm/http-cache.ts

@@ -12,6 +12,7 @@ import * as dntShim from "../../../_dnt.shims.js";
 import { createFileSystem, exists } from "../../platform/compat/fs.js";
 import { isAbsolute, join } from "../../platform/compat/path/index.js";
 import { cwd } from "../../platform/compat/process.js";
+import { isDeno } from "../../platform/compat/runtime.js";
 import { rendererLogger as logger } from "../../utils/index.js";
 import { simpleHash } from "../../utils/hash-utils.js";
 import { LRUCache } from "../../utils/lru-wrapper.js";
@@ -19,8 +20,7 @@ import { withSpan } from "../../observability/tracing/otlp-setup.js";
 import { SpanNames } from "../../observability/tracing/span-names.js";
 import { resolveImport } from "../../modules/import-map/resolver.js";
 import type { ImportMapConfig } from "../../modules/import-map/types.js";
-import { isDeno } from "../../platform/compat/runtime.js";
-import { getDenoNpmReactMap, getReactImportMap, REACT_VERSION } from "./package-registry.js";
+import { getReactImportMap, REACT_VERSION } from "./package-registry.js";
 import { parseImports, replaceSpecifiers } from "./lexer.js";
 import { CacheBackends, createDistributedCacheAccessor } from "../../cache/backend.js";
 import {
@@ -34,9 +34,6 @@ const getDistributedCache = createDistributedCacheAccessor(
   "HTTP-CACHE",
 );
 
-/** TTL for cached modules in distributed cache (uses centralized config) */
-const DISTRIBUTED_CACHE_TTL_SECONDS = HTTP_MODULE_DISTRIBUTED_TTL_SEC;
-
 type CacheOptions = {
   cacheDir: string;
   importMap: ImportMapConfig;
@@ -47,6 +44,12 @@ type CacheOptions = {
 const cachedPaths = new LRUCache<string, string>({ maxEntries: HTTP_MODULE_CACHE_MAX_ENTRIES });
 const processingStack = new Set<string>();
 
+/** Tracks last TTL refresh per hash. Refresh every 4h to keep 20h+ remaining (24h total). */
+const lastDistributedRefresh = new LRUCache<string, number>({
+  maxEntries: HTTP_MODULE_CACHE_MAX_ENTRIES,
+});
+const DISTRIBUTED_REFRESH_INTERVAL_MS = 4 * 60 * 60 * 1000;
+
 function ensureAbsoluteDir(path: string): string {
   return isAbsolute(path) ? path : join(cwd(), path);
 }
@@ -58,13 +61,23 @@ function isHttpUrl(specifier: string): boolean {
 /**
  * Check if a URL is for React core packages.
  *
- * Previously, React modules were NOT cached to prevent multiple React instances.
- * Now with npm: specifiers for Deno (which auto-deduplicate) and consistent
- * esm.sh URLs with external=react for other runtimes, all code uses the same
- * React instance.
+ * React core modules (react, react-dom) must NOT be cached/bundled.
+ * Instead, all packages use external=react and import from the same esm.sh URL.
+ * This prevents multiple React instances which causes "useContext is null" errors.
  */
-function isReactCoreUrl(_url: string): boolean {
-  return false;
+function isReactCoreUrl(url: string): boolean {
+  try {
+    const parsed = new URL(url);
+    if (!parsed.hostname.includes("esm.sh")) return false;
+
+    // Extract package name from esm.sh pathname
+    // Formats: /react@version, /v150/react@version, /stable/react@version
+    const pathname = parsed.pathname.replace(/^\/(v\d+|stable)\//, "/");
+    const match = pathname.match(/^\/(react|react-dom)(@[\d.]+)?(?:\/|$|\?)/);
+    return match !== null;
+  } catch {
+    return false;
+  }
 }
 
 function isExternalScheme(specifier: string): boolean {
@@ -132,26 +145,8 @@ function resolveBareSpecifier(
   importMap: ImportMapConfig,
   reactVersion: string = REACT_VERSION,
 ): string {
-  // For Deno SSR: Resolve React to npm: specifiers for automatic deduplication.
-  // Deno's native npm resolution ensures all modules share the same React instance.
-  // See: https://deno.com/blog/not-using-npm-specifiers-doing-it-wrong
-  if (isDeno) {
-    const denoReactMap = getDenoNpmReactMap(reactVersion);
-    const denoMatch = denoReactMap[specifier];
-    if (denoMatch) return denoMatch;
-
-    // For unknown react/* or react-dom/* subpaths, construct npm: specifiers
-    if (specifier.startsWith("react/") && !specifier.startsWith("react-dom")) {
-      const subpath = specifier.slice("react/".length);
-      return `npm:react@${reactVersion}/${subpath}`;
-    }
-    if (specifier.startsWith("react-dom/")) {
-      const subpath = specifier.slice("react-dom/".length);
-      return `npm:react-dom@${reactVersion}/${subpath}`;
-    }
-  }
-
-  // For non-Deno runtimes: Use esm.sh URLs with consistent versioning.
+  // Use esm.sh URLs for React - NO npm: specifiers per plan requirements.
+  // All packages use external=react to share the same React instance.
   const reactMap = getReactImportMap(reactVersion);
   const reactMapped = reactMap[specifier];
   if (reactMapped) return reactMapped;
@@ -194,22 +189,28 @@ async function cacheHttpModule(url: string, options: CacheOptions): Promise<stri
   if (await exists(cachePath)) {
     cachedPaths.set(cacheKey, cachePath);
 
-    // Synchronously ensure code:{hash} exists in distributed cache for cross-pod recovery
-    // This backfills bundles created before code:{hash} storage was added
-    // Synchronous to guarantee data is stored before other pods need it
+    // Refresh distributed cache TTL so bundles outlive transforms that reference them.
+    // Without this, bundles expire (24h) while SSR transforms (6h) are still valid.
     const distributed = await getDistributedCache();
     if (distributed) {
       const hash = simpleHash(normalizedUrl);
-      try {
-        const hasCode = await distributed.get(`code:${hash}`);
-        if (!hasCode) {
+      const hashStr = String(hash);
+      const now = Date.now();
+      const lastRefresh = lastDistributedRefresh.get(hashStr);
+      const needsRefresh = !lastRefresh || (now - lastRefresh > DISTRIBUTED_REFRESH_INTERVAL_MS);
+
+      if (needsRefresh) {
+        try {
           const code = await fs.readTextFile(cachePath);
-          await distributed.set(`code:${hash}`, code, DISTRIBUTED_CACHE_TTL_SECONDS);
-          logger.info("[HTTP-CACHE] Backfilled code:{hash} for existing bundle", { hash });
+          await Promise.all([
+            distributed.set(`code:${hash}`, code, HTTP_MODULE_DISTRIBUTED_TTL_SEC),
+            distributed.set(`hash:${hash}`, normalizedUrl, HTTP_MODULE_DISTRIBUTED_TTL_SEC),
+          ]);
+          lastDistributedRefresh.set(hashStr, now);
+          logger.debug("[HTTP-CACHE] Refreshed distributed cache TTL", { hash });
+        } catch (error) {
+          logger.debug("[HTTP-CACHE] Distributed cache refresh failed", { hash, error });
         }
-      } catch (error) {
-        // Log but don't fail - backfill is best-effort
-        logger.debug("[HTTP-CACHE] Backfill failed, continuing", { hash, error });
       }
     }
 
@@ -288,9 +289,9 @@ async function cacheHttpModule(url: string, options: CacheOptions): Promise<stri
     const hash = simpleHash(normalizedUrl);
     try {
       await Promise.all([
-        distributed.set(normalizedUrl, code, DISTRIBUTED_CACHE_TTL_SECONDS),
-        distributed.set(`code:${hash}`, code, DISTRIBUTED_CACHE_TTL_SECONDS),
-        distributed.set(`hash:${hash}`, normalizedUrl, DISTRIBUTED_CACHE_TTL_SECONDS),
+        distributed.set(normalizedUrl, code, HTTP_MODULE_DISTRIBUTED_TTL_SEC),
+        distributed.set(`code:${hash}`, code, HTTP_MODULE_DISTRIBUTED_TTL_SEC),
+        distributed.set(`hash:${hash}`, normalizedUrl, HTTP_MODULE_DISTRIBUTED_TTL_SEC),
       ]);
     } catch (error) {
       logger.debug("[HTTP-CACHE] Distributed cache set failed", { url: normalizedUrl, error });
@@ -327,6 +328,13 @@ async function resolveSpecifier(
     if (!baseUrl || !isHttpUrl(baseUrl)) return null;
 
     const resolved = new URL(specifier, baseUrl).toString();
+
+    // For React core URLs: return the full esm.sh URL (not cached, to prevent multiple instances)
+    // This transforms relative paths like "/react-dom?..." to "https://esm.sh/react-dom?..."
+    if (isReactCoreUrl(resolved)) {
+      return normalizeHttpUrl(resolved);
+    }
+
     const cached = await cacheHttpModule(resolved, options);
     return cached ? `file://${cached}` : null;
   }

package/src/src/transforms/esm/import-rewriter.ts

@@ -51,9 +51,11 @@ function normalizeVersionedSpecifier(specifier: string): string {
 
 const REACT_IMPORT_MAP: Record<string, string> = {
   react: `https://esm.sh/react@${REACT_DEFAULT_VERSION}?target=es2022`,
-  "react-dom": `https://esm.sh/react-dom@${REACT_DEFAULT_VERSION}?target=es2022`,
-  "react-dom/client": `https://esm.sh/react-dom@${REACT_DEFAULT_VERSION}/client?target=es2022`,
-  "react-dom/server": `https://esm.sh/react-dom@${REACT_DEFAULT_VERSION}/server?target=es2022`,
+  "react-dom": `https://esm.sh/react-dom@${REACT_DEFAULT_VERSION}?external=react&target=es2022`,
+  "react-dom/client":
+    `https://esm.sh/react-dom@${REACT_DEFAULT_VERSION}/client?external=react&target=es2022`,
+  "react-dom/server":
+    `https://esm.sh/react-dom@${REACT_DEFAULT_VERSION}/server?external=react&target=es2022`,
   "react/jsx-runtime": `https://esm.sh/react@${REACT_DEFAULT_VERSION}/jsx-runtime?target=es2022`,
   "react/jsx-dev-runtime":
     `https://esm.sh/react@${REACT_DEFAULT_VERSION}/jsx-dev-runtime?target=es2022`,

package/src/src/transforms/esm/package-registry.ts

@@ -9,23 +9,35 @@
 export const DEFAULT_REACT_VERSION = "19.1.1";
 export const TAILWIND_VERSION = "4.1.8";
 
-/** Cached React version from project config */
-let configuredReactVersion: string | null = null;
+/**
+ * Validate React version format (semver: X.Y.Z).
+ * Returns true if valid, false otherwise.
+ */
+export function isValidReactVersion(version: string): boolean {
+  return /^\d+\.\d+\.\d+$/.test(version);
+}
 
 /**
- * Set the React version from project configuration.
- * Call this during project initialization if a custom version is specified.
+ * Validate and normalize React version.
+ * Returns the version if valid, or DEFAULT_REACT_VERSION if invalid.
+ * Logs a warning if the version is invalid.
  */
-export function setReactVersion(version: string): void {
-  configuredReactVersion = version;
+export function normalizeReactVersion(version: string | undefined): string {
+  if (!version) return DEFAULT_REACT_VERSION;
+  if (isValidReactVersion(version)) return version;
+  console.warn(
+    `[VERYFRONT] Invalid React version format "${version}" (expected X.Y.Z). Using default: ${DEFAULT_REACT_VERSION}`,
+  );
+  return DEFAULT_REACT_VERSION;
 }
 
 /**
- * Get the current React version.
- * Returns configured version if set, otherwise the default.
+ * @deprecated Global React version is no longer supported.
+ * Use config.react.version passed through TransformOptions instead.
+ * This function now always returns DEFAULT_REACT_VERSION.
  */
 export function getReactVersion(): string {
-  return configuredReactVersion ?? DEFAULT_REACT_VERSION;
+  return DEFAULT_REACT_VERSION;
 }
 
 /** @deprecated Use DEFAULT_REACT_VERSION or getReactVersion() */
@@ -50,8 +62,15 @@ export const REACT_VERSION = DEFAULT_REACT_VERSION;
  */
 export const TRANSFORM_CACHE_VERSION = 12;
 
-function esmSh(pkg: string, version: string, path = "", query = "target=es2022"): string {
-  return `https://esm.sh/${pkg}@${version}${path}?${query}`;
+/** csstype version - must match deno.json for type consistency */
+const CSSTYPE_VERSION = "3.2.3";
+
+/** Build esm.sh URL with deps=csstype for React packages (ensures type consistency) */
+function esmShReact(pkg: string, version: string, path = "", external = false): string {
+  const params = external
+    ? [`external=react`, `target=es2022`, `deps=csstype@${CSSTYPE_VERSION}`]
+    : [`target=es2022`, `deps=csstype@${CSSTYPE_VERSION}`];
+  return `https://esm.sh/${pkg}@${version}${path}?${params.join("&")}`;
 }
 
 /**
@@ -78,12 +97,12 @@ export function getEsmShUrl(pkg: string, version: string, external?: readonly st
 export function getReactUrls(version?: string): Record<string, string> {
   const v = version ?? getReactVersion();
   return {
-    react: esmSh("react", v),
-    "react-dom": esmSh("react-dom", v, "", "external=react&target=es2022"),
-    "react-dom/client": esmSh("react-dom", v, "/client", "external=react&target=es2022"),
-    "react-dom/server": esmSh("react-dom", v, "/server", "external=react&target=es2022"),
-    "react/jsx-runtime": esmSh("react", v, "/jsx-runtime", "external=react&target=es2022"),
-    "react/jsx-dev-runtime": esmSh("react", v, "/jsx-dev-runtime", "external=react&target=es2022"),
+    react: esmShReact("react", v),
+    "react-dom": esmShReact("react-dom", v, "", true),
+    "react-dom/client": esmShReact("react-dom", v, "/client", true),
+    "react-dom/server": esmShReact("react-dom", v, "/server", true),
+    "react/jsx-runtime": esmShReact("react", v, "/jsx-runtime", true),
+    "react/jsx-dev-runtime": esmShReact("react", v, "/jsx-dev-runtime", true),
   };
 }
 
@@ -102,30 +121,25 @@ export function getReactImportMap(version?: string): Record<string, string> {
   return {
     ...getReactUrls(v),
     // Prefix match for any react/* subpath imports
-    "react/": esmSh("react", v, "/", "external=react&target=es2022"),
+    "react/": esmShReact("react", v, "/", true),
   };
 }
 
 /**
- * Get React npm specifiers for Deno SSR.
- * Uses npm: protocol which Deno handles natively with automatic deduplication.
- * See: https://deno.com/blog/not-using-npm-specifiers-doing-it-wrong
- *
- * Benefits over esm.sh:
- * - Automatic semantic version deduplication (like Node's node_modules)
- * - No manual external= flags or shared-*.ts wrapper files needed
- * - Native support in Deno 2+
+ * Get React esm.sh URLs for Deno SSR.
+ * Uses esm.sh for both SSR and browser to ensure identical React instances.
+ * All sub-packages use external=react to share the same React instance.
  *
  * @param version - React version to use (defaults to REACT_VERSION)
  */
 export function getDenoNpmReactMap(version?: string): Record<string, string> {
   const v = version ?? getReactVersion();
   return {
-    "react": `npm:react@${v}`,
-    "react-dom": `npm:react-dom@${v}`,
-    "react-dom/client": `npm:react-dom@${v}/client`,
-    "react-dom/server": `npm:react-dom@${v}/server`,
-    "react/jsx-runtime": `npm:react@${v}/jsx-runtime`,
-    "react/jsx-dev-runtime": `npm:react@${v}/jsx-dev-runtime`,
+    "react": esmShReact("react", v),
+    "react-dom": esmShReact("react-dom", v, "", true),
+    "react-dom/client": esmShReact("react-dom", v, "/client", true),
+    "react-dom/server": esmShReact("react-dom", v, "/server", true),
+    "react/jsx-runtime": esmShReact("react", v, "/jsx-runtime", true),
+    "react/jsx-dev-runtime": esmShReact("react", v, "/jsx-dev-runtime", true),
   };
 }

package/src/src/transforms/esm/react-imports.ts

@@ -1,7 +1,5 @@
 import { replaceSpecifiers } from "./lexer.js";
-import { getDenoNpmReactMap, getReactImportMap, REACT_VERSION } from "./package-registry.js";
-import { isDeno } from "../../platform/compat/runtime.js";
-import { getLocalReactPaths } from "../../platform/compat/react-paths.js";
+import { getReactImportMap, REACT_VERSION } from "./package-registry.js";
 
 const srcDir = new URL(".", import.meta.url).pathname.replace(
   /\/(build|src)\/transforms\/esm\/?$/,
@@ -28,12 +26,10 @@ export async function resolveReactImports(
     return replaceSpecifiers(code, (specifier) => reactImports[specifier] ?? null);
   }
 
-  // For Deno SSR: Use npm: specifiers (auto-deduplicated by Deno's npm cache)
-  // For Node/Bun SSR: Use local node_modules paths (auto-deduplicated by Node)
-  // See: https://deno.com/blog/not-using-npm-specifiers-doing-it-wrong
+  // For SSR: Use esm.sh URLs consistently (NO npm: specifiers per plan requirements)
   const ssrImports: Record<string, string> = {
     ...getVeryfrontModulePaths(),
-    ...(isDeno ? getDenoNpmReactMap(reactVersion) : getLocalReactPaths()),
+    ...reactImports,
   };
 
   return replaceSpecifiers(code, (specifier) => ssrImports[specifier] ?? null);

package/src/src/transforms/esm/types.ts

@@ -9,6 +9,8 @@ export interface TransformOptions {
   ssr?: boolean;
   apiBaseUrl?: string;
   studioEmbed?: boolean;
+  /** React version for transforms (from project config, defaults to DEFAULT_REACT_VERSION) */
+  reactVersion?: string;
 }
 
 export interface TransformContext {

package/src/src/transforms/mdx/esm-module-loader/cache/index.ts

@@ -14,6 +14,7 @@ import {
   type FileSystem,
   isNotFoundError,
 } from "../../../../platform/compat/fs.js";
+import { TRANSFORM_CACHE_VERSION } from "../../../esm/package-registry.js";
 import { LOG_PREFIX_MDX_LOADER } from "../constants.js";
 
 // Local filesystem for cache operations (not project's FSAdapter which may be remote/read-only)
@@ -150,3 +151,86 @@ export async function clearESMDiskCache(): Promise<void> {
     }
   }
 }
+
+/**
+ * Convert a project-relative file path to MDX-ESM cache key format.
+ *
+ * @param filePath - Project-relative path like "lib/ChatContext.tsx" or absolute path
+ * @param projectDir - Project directory to strip from absolute paths
+ * @returns Cache key like "v10:_vf_modules/lib/ChatContext.js"
+ */
+function toMdxEsmCacheKey(filePath: string, projectDir?: string): string {
+  // Strip project directory prefix if present
+  let relativePath = filePath;
+  if (projectDir && filePath.startsWith(projectDir)) {
+    relativePath = filePath.slice(projectDir.length).replace(/^\/+/, "");
+  }
+  // Strip leading slashes
+  relativePath = relativePath.replace(/^\/+/, "");
+
+  // Convert extension to .js
+  const jsPath = relativePath.replace(/\.(tsx?|jsx|mdx)$/, ".js");
+
+  // Build the versioned key in MDX-ESM format
+  return `v${TRANSFORM_CACHE_VERSION}:_vf_modules/${jsPath}`;
+}
+
+/**
+ * Look up a module in the MDX-ESM cache.
+ *
+ * This allows other loaders (like SSR loader) to reuse modules that
+ * MDX-ESM has already transformed and cached, preventing duplicate
+ * module instances (which breaks React context, etc.).
+ *
+ * @param filePath - Project-relative file path like "lib/ChatContext.tsx"
+ * @param cacheDir - The MDX-ESM cache directory for this project/contentSource
+ * @param projectDir - Project directory to strip from absolute paths
+ * @param contentHash - Optional content hash to validate cached file freshness
+ * @returns The cached file path if found and valid, null otherwise
+ */
+export async function lookupMdxEsmCache(
+  filePath: string,
+  cacheDir: string,
+  projectDir?: string,
+  contentHash?: string,
+): Promise<string | null> {
+  const cache = await getModulePathCache(cacheDir);
+  const cacheKey = toMdxEsmCacheKey(filePath, projectDir);
+
+  const cachedPath = cache.get(cacheKey);
+  if (!cachedPath) {
+    return null;
+  }
+
+  // Verify the cached file still exists
+  try {
+    const stat = await getLocalFs().stat(cachedPath);
+    if (!stat?.isFile) {
+      cache.delete(cacheKey);
+      return null;
+    }
+
+    // If contentHash provided, validate the cached file contains matching hash
+    // The cached filename includes the content hash (e.g., module.abc123.js)
+    if (contentHash) {
+      const filename = cachedPath.split("/").pop() ?? "";
+      if (!filename.includes(contentHash.slice(0, 8))) {
+        logger.debug(
+          `${LOG_PREFIX_MDX_LOADER} Cache hash mismatch, invalidating: ${filePath}`,
+        );
+        cache.delete(cacheKey);
+        return null;
+      }
+    }
+
+    logger.debug(
+      `${LOG_PREFIX_MDX_LOADER} SSR reusing MDX-ESM cache: ${filePath} -> ${cachedPath}`,
+    );
+    return cachedPath;
+  } catch {
+    // File no longer exists, remove stale entry
+    cache.delete(cacheKey);
+  }
+
+  return null;
+}

package/src/src/transforms/mdx/esm-module-loader/loader.ts

@@ -8,7 +8,7 @@
  */
 
 import { join } from "../../../../deps/deno.land/std@0.220.0/path/mod.js";
-import React from "react";
+import React from "../../../../deps/esm.sh/react@19.1.1.js";
 import { rendererLogger as logger } from "../../../utils/index.js";
 import { withSpan } from "../../../observability/tracing/otlp-setup.js";
 import { SpanNames } from "../../../observability/tracing/span-names.js";
@@ -201,6 +201,7 @@ async function processVfModuleImports(
     adapter,
     projectDir,
     context.projectId,
+    { reactVersion: context.reactVersion },
   );
 
   const fetchStart = performance.now();

package/src/src/transforms/mdx/esm-module-loader/module-fetcher/index.ts

@@ -568,6 +568,7 @@ async function doFetchAndCacheModule(
           projectId,
           dev: true,
           ssr: true,
+          reactVersion: context.reactVersion,
         });
       } catch (transformError) {
         logger.error(`${LOG_PREFIX_MDX_LOADER} Transform failed for module`, {
@@ -685,7 +686,7 @@ export function createModuleFetcherContext(
   adapter: RuntimeAdapter,
   projectDir: string,
   projectId: string,
-  options?: { isLocalDev?: boolean; projectSlug?: string },
+  options?: { isLocalDev?: boolean; projectSlug?: string; reactVersion?: string },
 ): ModuleFetcherContext {
   return {
     esmCacheDir,

package/src/src/transforms/mdx/esm-module-loader/types.ts

@@ -10,6 +10,8 @@ export interface ESMLoaderContext {
   projectDir?: string;
   projectSlug?: string;
   contentSourceId?: string;
+  /** React version for transforms (from project config) */
+  reactVersion?: string;
 }
 
 export interface FSAdapter {
@@ -51,6 +53,8 @@ export interface ModuleFetcherContext {
    * This prevents infinite recursion when A imports B which imports A.
    */
   inFlightModules?: Map<string, Promise<string | null>>;
+  /** React version for transforms (from project config) */
+  reactVersion?: string;
 }
 
 export interface JSXTransform {

package/src/src/transforms/mdx/index.ts

@@ -1,7 +1,7 @@
 import { rendererLogger as logger } from "../../utils/index.js";
 import { LRUCache } from "../../utils/lru-wrapper.js";
 import { MDX_RENDERER_MAX_ENTRIES, MDX_RENDERER_TTL_MS } from "../../utils/constants/cache.js";
-import React from "react";
+import React from "../../../deps/esm.sh/react@19.1.1.js";
 import { type ESMLoaderContext, loadModuleESM } from "./esm-module-loader/index.js";
 import { type ParsedMDX, parseMDXCode } from "./parser.js";
 import type { MDXComponents, MDXFrontmatter, MDXGlobals, MDXModule } from "./types.js";