sandlot 0.2.1 → 0.2.3

package/src/browser/preset.ts

@@ -12,7 +12,11 @@ import {
 import {
   MainThreadExecutor,
   type MainThreadExecutorOptions,
-} from "./executor";
+} from "./main-thread-executor";
+import {
+  IframeExecutor,
+  type IframeExecutorOptions,
+} from "./iframe-executor";
 
 export interface CreateBrowserSandlotOptions
   extends Omit<SandlotOptions, "bundler" | "typechecker" | "typesResolver" | "executor"> {
@@ -42,11 +46,17 @@ export interface CreateBrowserSandlotOptions
   /**
    * Custom executor options, or a pre-configured executor instance.
    * Set to `false` to disable execution (sandbox.run() will throw).
+   * Set to `"iframe"` to use IframeExecutor with default options.
    * Defaults to MainThreadExecutor.
+   *
+   * Note: IframeExecutor does NOT support shared modules. Use MainThreadExecutor
+   * (the default) if you need shared modules like React.
    */
   executor?:
   | MainThreadExecutorOptions
+  | IframeExecutorOptions
   | SandlotOptions["executor"]
+  | "iframe"
   | false;
 }
 
@@ -121,11 +131,15 @@ export async function createBrowserSandlot(
   const executorInstance =
     executor === false
       ? undefined
-      : isExecutor(executor)
-        ? executor
-        : new MainThreadExecutor(
-          executor as MainThreadExecutorOptions | undefined
-        );
+      : executor === "iframe"
+        ? new IframeExecutor()
+        : isExecutor(executor)
+          ? executor
+          : isIframeExecutorOptions(executor)
+            ? new IframeExecutor(executor)
+            : new MainThreadExecutor(
+              executor as MainThreadExecutorOptions | undefined
+            );
 
   return createSandlot({
     ...rest,
@@ -177,3 +191,13 @@ function isExecutor(value: unknown): value is SandlotOptions["executor"] {
     typeof (value as { execute: unknown }).execute === "function"
   );
 }
+
+function isIframeExecutorOptions(value: unknown): value is IframeExecutorOptions {
+  // IframeExecutorOptions has "sandbox" or "container" properties
+  // MainThreadExecutorOptions only has "defaultTimeout"
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    ("sandbox" in value || "container" in value)
+  );
+}

package/src/core/bundler-utils.ts

@@ -7,6 +7,8 @@
 
 import type {
   ISharedModuleRegistry,
+  BundleOptions,
+  BundleResult,
   BundleWarning,
   BundleError,
   BundleLocation,
@@ -628,3 +630,149 @@ export function generateSharedModuleCode(
 
   return code;
 }
+
+// =============================================================================
+// Shared Bundle Execution
+// =============================================================================
+
+/**
+ * Minimal esbuild interface needed for bundling.
+ * Compatible with both esbuild and esbuild-wasm.
+ *
+ * Uses a loose `Record<string, unknown>` for build options to avoid
+ * type conflicts between the various esbuild module signatures.
+ */
+export interface EsbuildInstance {
+  build(options: Record<string, unknown>): Promise<{
+    outputFiles?: Array<{ text: string }>;
+    warnings: EsbuildMessage[];
+  }>;
+}
+
+/**
+ * Options for the shared bundle execution helper.
+ */
+export interface ExecuteBundleOptions {
+  /** The esbuild instance to use */
+  esbuild: EsbuildInstance;
+  /** Bundle options from the IBundler interface */
+  bundleOptions: BundleOptions;
+  /** Base URL for CDN imports */
+  cdnBaseUrl: string;
+  /**
+   * Whether to bundle CDN imports inline.
+   * - Browser: false (external) - browser can fetch at runtime
+   * - Node/Bun: true (bundle) - esbuild fetches during build
+   */
+  bundleCdnImports: boolean;
+}
+
+/**
+ * Execute a bundle using esbuild with the VFS plugin.
+ *
+ * This is the shared implementation used by both browser and node WASM bundlers.
+ * It handles entry point normalization, VFS plugin creation, and error handling.
+ *
+ * @param options - Bundle execution options
+ * @returns Bundle result with code or errors
+ */
+export async function executeBundleWithEsbuild(
+  options: ExecuteBundleOptions
+): Promise<BundleResult> {
+  const { esbuild, bundleOptions, cdnBaseUrl, bundleCdnImports } = options;
+
+  const {
+    fs,
+    entryPoint,
+    installedPackages = {},
+    sharedModules = [],
+    sharedModuleRegistry,
+    external = [],
+    format = "esm",
+    minify = false,
+    sourcemap = false,
+    target = ["es2020"],
+  } = bundleOptions;
+
+  // Normalize entry point to absolute path
+  const normalizedEntry = entryPoint.startsWith("/")
+    ? entryPoint
+    : `/${entryPoint}`;
+
+  // Verify entry point exists
+  if (!fs.exists(normalizedEntry)) {
+    return {
+      success: false,
+      errors: [{ text: `Entry point not found: ${normalizedEntry}` }],
+      warnings: [],
+    };
+  }
+
+  // Track files included in the bundle
+  const includedFiles = new Set<string>();
+
+  // Create the VFS plugin
+  const plugin = createVfsPlugin({
+    fs,
+    entryPoint: normalizedEntry,
+    installedPackages,
+    sharedModules: new Set(sharedModules),
+    sharedModuleRegistry: sharedModuleRegistry ?? null,
+    cdnBaseUrl,
+    includedFiles,
+    bundleCdnImports,
+  });
+
+  try {
+    // Run esbuild
+    const result = await esbuild.build({
+      entryPoints: [normalizedEntry],
+      bundle: true,
+      write: false,
+      format,
+      minify,
+      sourcemap: sourcemap ? "inline" : false,
+      target,
+      external,
+      plugins: [plugin],
+      jsx: "automatic",
+    });
+
+    const code = result.outputFiles?.[0]?.text ?? "";
+
+    // Convert esbuild warnings to our format
+    const warnings: BundleWarning[] = result.warnings.map((w) =>
+      convertEsbuildMessage(w)
+    );
+
+    return {
+      success: true,
+      code,
+      warnings,
+      includedFiles: Array.from(includedFiles),
+    };
+  } catch (err) {
+    // esbuild throws BuildFailure with .errors array
+    if (isEsbuildBuildFailure(err)) {
+      const errors: BundleError[] = err.errors.map((e) =>
+        convertEsbuildMessage(e)
+      );
+      const warnings: BundleWarning[] = err.warnings.map((w) =>
+        convertEsbuildMessage(w)
+      );
+      return {
+        success: false,
+        errors,
+        warnings,
+      };
+    }
+
+    // Unknown error - wrap it
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      success: false,
+      errors: [{ text: message }],
+      warnings: [],
+    };
+  }
+}

package/src/core/executor.ts

@@ -68,23 +68,18 @@ export function createBasicExecutor(
 
       const captureLog = (...args: unknown[]) => {
         logs.push(formatArgs(...args));
-        originalConsole.log.apply(console, args);
       };
       const captureWarn = (...args: unknown[]) => {
         logs.push(`[warn] ${formatArgs(...args)}`);
-        originalConsole.warn.apply(console, args);
       };
       const captureError = (...args: unknown[]) => {
         logs.push(`[error] ${formatArgs(...args)}`);
-        originalConsole.error.apply(console, args);
       };
       const captureInfo = (...args: unknown[]) => {
         logs.push(`[info] ${formatArgs(...args)}`);
-        originalConsole.info.apply(console, args);
       };
       const captureDebug = (...args: unknown[]) => {
         logs.push(`[debug] ${formatArgs(...args)}`);
-        originalConsole.debug.apply(console, args);
       };
 
       const restoreConsole = () => {
@@ -125,13 +120,19 @@ export function createBasicExecutor(
 
         // Execute with optional timeout
         if (timeout > 0) {
+          let timeoutId: ReturnType<typeof setTimeout> | undefined;
           const timeoutPromise = new Promise<never>((_, reject) => {
-            setTimeout(
+            timeoutId = setTimeout(
               () => reject(new Error(`Execution timed out after ${timeout}ms`)),
               timeout
             );
           });
-          await Promise.race([executeExport(), timeoutPromise]);
+          try {
+            await Promise.race([executeExport(), timeoutPromise]);
+          } finally {
+            // Clear the timeout to allow the process to exit
+            if (timeoutId) clearTimeout(timeoutId);
+          }
         } else {
           await executeExport();
         }

package/src/core/sandbox.ts

@@ -262,6 +262,88 @@ export async function createSandboxImpl(
     fs.writeFile(TSCONFIG_PATH, JSON.stringify(DEFAULT_TSCONFIG, null, 2));
   }
 
+  // ---------------------------------------------------------------------------
+  // Install types for shared modules (if both registry and resolver exist)
+  // ---------------------------------------------------------------------------
+
+  if (sharedModuleRegistry && typesResolver) {
+    const sharedModuleIds = sharedModuleRegistry.list();
+    
+    // Resolve types for all shared modules in parallel
+    const typesFetches = sharedModuleIds.map(async (moduleId) => {
+      try {
+        const typeFiles = await typesResolver.resolveTypes(moduleId);
+        return { moduleId, typeFiles, error: null };
+      } catch (err) {
+        // Log but don't fail - types are nice to have but not required
+        console.warn(`[sandlot] Failed to fetch types for shared module "${moduleId}":`, err);
+        return { moduleId, typeFiles: {}, error: err };
+      }
+    });
+
+    const results = await Promise.all(typesFetches);
+
+    // Write type files to the filesystem
+    for (const { moduleId, typeFiles } of results) {
+      if (Object.keys(typeFiles).length === 0) continue;
+
+      // Determine the package name (strip subpath for @types resolution)
+      // e.g., "react-dom/client" -> "react-dom"
+      let packageName = moduleId;
+      let subpath: string | undefined;
+      
+      if (moduleId.startsWith("@")) {
+        const parts = moduleId.split("/");
+        if (parts.length >= 2) {
+          packageName = `${parts[0]}/${parts[1]}`;
+          subpath = parts.length > 2 ? parts.slice(2).join("/") : undefined;
+        }
+      } else {
+        const slashIndex = moduleId.indexOf("/");
+        if (slashIndex !== -1) {
+          packageName = moduleId.slice(0, slashIndex);
+          subpath = moduleId.slice(slashIndex + 1);
+        }
+      }
+
+      const packageDir = `/node_modules/${packageName}`;
+      let typesEntry: string | null = null;
+      let fallbackEntry: string | null = null;
+
+      for (const [filePath, content] of Object.entries(typeFiles)) {
+        const fullPath = filePath.startsWith("/")
+          ? filePath
+          : `${packageDir}/${filePath}`;
+        const dir = fullPath.substring(0, fullPath.lastIndexOf("/"));
+        ensureDir(fs, dir);
+        fs.writeFile(fullPath, content);
+
+        // Track types entry: prefer index.d.ts, fallback to first top-level .d.ts
+        const relativePath = fullPath.replace(`${packageDir}/`, "");
+        if (relativePath === "index.d.ts") {
+          typesEntry = "index.d.ts";
+        } else if (!fallbackEntry && relativePath.endsWith(".d.ts") && !relativePath.includes("/")) {
+          fallbackEntry = relativePath;
+        }
+      }
+
+      // Use index.d.ts if found, otherwise use fallback
+      const finalTypesEntry = typesEntry ?? fallbackEntry ?? "index.d.ts";
+
+      // Create package.json if it doesn't exist yet
+      const pkgJsonPath = `${packageDir}/package.json`;
+      if (!fs.exists(pkgJsonPath)) {
+        const pkgJson = {
+          name: packageName,
+          version: "shared",
+          types: finalTypesEntry,
+          main: finalTypesEntry.replace(/\.d\.ts$/, ".js"),
+        };
+        fs.writeFile(pkgJsonPath, JSON.stringify(pkgJson, null, 2));
+      }
+    }
+  }
+
   // ---------------------------------------------------------------------------
   // Core Methods
   // ---------------------------------------------------------------------------

package/src/core/sandlot.ts

@@ -73,5 +73,12 @@ export function createSandlot(options: SandlotOptions): Sandlot {
     get sharedModules(): ISharedModuleRegistry | null {
       return sharedModuleRegistry;
     },
+
+    async dispose(): Promise<void> {
+      // Dispose of the bundler if it has a dispose method
+      if (bundler.dispose) {
+        await bundler.dispose();
+      }
+    },
   };
 }

package/src/node/bundler.ts

@@ -6,18 +6,8 @@
  */
 
 import type * as EsbuildTypes from "esbuild";
-import type {
-  IBundler,
-  BundleOptions,
-  BundleResult,
-  BundleWarning,
-  BundleError,
-} from "../types";
-import {
-  createVfsPlugin,
-  isEsbuildBuildFailure,
-  convertEsbuildMessage,
-} from "../core/bundler-utils";
+import type { IBundler, BundleOptions, BundleResult } from "../types";
+import { executeBundleWithEsbuild } from "../core/bundler-utils";
 
 export interface EsbuildNativeBundlerOptions {
   /**
@@ -76,111 +66,28 @@ export class EsbuildNativeBundler implements IBundler {
     return this.esbuild;
   }
 
-  async bundle(options: BundleOptions): Promise<BundleResult> {
-    await this.initialize();
-
-    const esbuild = this.getEsbuild();
-
-    const {
-      fs,
-      entryPoint,
-      installedPackages = {},
-      sharedModules = [],
-      sharedModuleRegistry,
-      external = [],
-      format = "esm",
-      minify = false,
-      sourcemap = false,
-      target = ["es2020"],
-    } = options;
-
-    // Normalize entry point to absolute path
-    const normalizedEntry = entryPoint.startsWith("/")
-      ? entryPoint
-      : `/${entryPoint}`;
-
-    // Verify entry point exists
-    if (!fs.exists(normalizedEntry)) {
-      return {
-        success: false,
-        errors: [{ text: `Entry point not found: ${normalizedEntry}` }],
-        warnings: [],
-      };
+  /**
+   * Dispose of the esbuild service.
+   * This stops the esbuild child process and allows the Node.js process to exit.
+   */
+  async dispose(): Promise<void> {
+    if (this.esbuild) {
+      await this.esbuild.stop();
+      this.esbuild = null;
     }
+  }
 
-    // Track files included in the bundle
-    const includedFiles = new Set<string>();
+  async bundle(options: BundleOptions): Promise<BundleResult> {
+    await this.initialize();
 
-    // Create the VFS plugin
-    // Note: bundleCdnImports is true for Node/Bun because they cannot
+    // bundleCdnImports is true for Node/Bun because they cannot
     // resolve HTTP imports at runtime - native esbuild will fetch and bundle them
-    const plugin = createVfsPlugin({
-      fs,
-      entryPoint: normalizedEntry,
-      installedPackages,
-      sharedModules: new Set(sharedModules),
-      sharedModuleRegistry: sharedModuleRegistry ?? null,
+    return executeBundleWithEsbuild({
+      esbuild: this.getEsbuild(),
+      bundleOptions: options,
       cdnBaseUrl: this.options.cdnBaseUrl!,
-      includedFiles,
       bundleCdnImports: true,
     });
-
-    try {
-      // Run esbuild
-      // Note: We do NOT mark http/https as external here because Node/Bun
-      // cannot resolve HTTP imports at runtime. Instead, bundleCdnImports: true
-      // tells the VFS plugin to let native esbuild fetch and bundle CDN imports.
-      const result = await esbuild.build({
-        entryPoints: [normalizedEntry],
-        bundle: true,
-        write: false,
-        format,
-        minify,
-        sourcemap: sourcemap ? "inline" : false,
-        target,
-        external,
-        // Cast to esbuild's Plugin type since our minimal interface is compatible
-        plugins: [plugin as EsbuildTypes.Plugin],
-        jsx: "automatic",
-      });
-
-      const code = result.outputFiles?.[0]?.text ?? "";
-
-      // Convert esbuild warnings to our format
-      const warnings: BundleWarning[] = result.warnings.map((w) =>
-        convertEsbuildMessage(w)
-      );
-
-      return {
-        success: true,
-        code,
-        warnings,
-        includedFiles: Array.from(includedFiles),
-      };
-    } catch (err) {
-      // esbuild throws BuildFailure with .errors array
-      if (isEsbuildBuildFailure(err)) {
-        const errors: BundleError[] = err.errors.map((e) =>
-          convertEsbuildMessage(e)
-        );
-        const warnings: BundleWarning[] = err.warnings.map((w) =>
-          convertEsbuildMessage(w)
-        );
-        return {
-          success: false,
-          errors,
-          warnings,
-        };
-      }
-
-      // Unknown error - wrap it
-      const message = err instanceof Error ? err.message : String(err);
-      return {
-        success: false,
-        errors: [{ text: message }],
-        warnings: [],
-      };
-    }
   }
 }
 

package/src/node/index.ts

@@ -17,6 +17,16 @@
 export { EsbuildNativeBundler, createEsbuildNativeBundler } from "./bundler";
 export type { EsbuildNativeBundlerOptions } from "./bundler";
 
+// -----------------------------------------------------------------------------
+// WASM Bundler (for testing consistency with browser bundler)
+// -----------------------------------------------------------------------------
+
+export {
+  EsbuildWasmNodeBundler,
+  createEsbuildWasmNodeBundler,
+} from "./wasm-bundler";
+export type { EsbuildWasmNodeBundlerOptions } from "./wasm-bundler";
+
 // -----------------------------------------------------------------------------
 // Typechecker (platform-agnostic: re-exported for convenience)
 // -----------------------------------------------------------------------------

package/src/node/preset.ts

@@ -5,6 +5,10 @@ import {
 } from "../core/esm-types-resolver";
 import type { Sandlot, SandlotOptions } from "../types";
 import { EsbuildNativeBundler, type EsbuildNativeBundlerOptions } from "./bundler";
+import {
+  EsbuildWasmNodeBundler,
+  type EsbuildWasmNodeBundlerOptions,
+} from "./wasm-bundler";
 import {
   Typechecker,
   type TypecheckerOptions,
@@ -18,8 +22,17 @@ export interface CreateNodeSandlotOptions
   extends Omit<SandlotOptions, "bundler" | "typechecker" | "typesResolver" | "executor"> {
   /**
    * Custom bundler options, or a pre-configured bundler instance.
+   *
+   * Set to `"wasm"` to use the WASM bundler (for testing consistency with browser).
+   * You can also pass `{ wasm: true, ...options }` for WASM bundler with custom options.
+   *
+   * @default EsbuildNativeBundler (fastest, uses native esbuild binary)
    */
-  bundler?: EsbuildNativeBundlerOptions | SandlotOptions["bundler"];
+  bundler?:
+    | EsbuildNativeBundlerOptions
+    | (EsbuildWasmNodeBundlerOptions & { wasm: true })
+    | SandlotOptions["bundler"]
+    | "wasm";
 
   /**
    * Custom typechecker options, or a pre-configured typechecker instance.
@@ -82,6 +95,13 @@ export interface CreateNodeSandlotOptions
  *   typechecker: false,
  * });
  * ```
+ *
+ * @example Use WASM bundler for testing consistency with browser
+ * ```ts
+ * const sandlot = await createNodeSandlot({
+ *   bundler: "wasm",
+ * });
+ * ```
  */
 export async function createNodeSandlot(
   options: CreateNodeSandlotOptions = {}
@@ -89,11 +109,9 @@ export async function createNodeSandlot(
   const { bundler, typechecker, typesResolver, executor, ...rest } = options;
 
   // Create or use provided bundler
-  const bundlerInstance = isBundler(bundler)
-    ? bundler
-    : new EsbuildNativeBundler(bundler as EsbuildNativeBundlerOptions | undefined);
+  const bundlerInstance = createBundlerInstance(bundler);
 
-  // Initialize bundler (loads native esbuild)
+  // Initialize bundler (loads native esbuild or WASM)
   await bundlerInstance.initialize();
 
   // Create or use provided typechecker
@@ -135,6 +153,42 @@ export async function createNodeSandlot(
   });
 }
 
+// Helper to create bundler instance based on options
+
+function createBundlerInstance(
+  bundler: CreateNodeSandlotOptions["bundler"]
+): (EsbuildNativeBundler | EsbuildWasmNodeBundler) & { initialize(): Promise<void> } {
+  // Already a bundler instance
+  if (isBundler(bundler)) {
+    return bundler as (EsbuildNativeBundler | EsbuildWasmNodeBundler) & { initialize(): Promise<void> };
+  }
+
+  // String shorthand for WASM bundler
+  if (bundler === "wasm") {
+    return new EsbuildWasmNodeBundler();
+  }
+
+  // Object with wasm: true flag
+  if (isWasmBundlerOptions(bundler)) {
+    const { wasm: _, ...wasmOptions } = bundler;
+    return new EsbuildWasmNodeBundler(wasmOptions);
+  }
+
+  // Default: native bundler (fastest)
+  return new EsbuildNativeBundler(bundler as EsbuildNativeBundlerOptions | undefined);
+}
+
+function isWasmBundlerOptions(
+  value: unknown
+): value is EsbuildWasmNodeBundlerOptions & { wasm: true } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "wasm" in value &&
+    (value as { wasm: unknown }).wasm === true
+  );
+}
+
 // Type guards for detecting pre-configured instances
 
 function isBundler(