sandlot 0.2.1 → 0.2.3

package/dist/browser/bundler.d.ts

@@ -62,6 +62,14 @@ export declare class EsbuildWasmBundler implements IBundler {
      * Get the initialized esbuild instance.
      */
     private getEsbuild;
+    /**
+     * Dispose of the esbuild WASM service.
+     * This stops the esbuild service and allows the process to exit.
+     *
+     * Note: Since esbuild-wasm uses a global singleton, this affects all
+     * instances. After dispose(), you'll need to create a new bundler.
+     */
+    dispose(): Promise<void>;
     private checkCrossOriginIsolation;
     bundle(options: BundleOptions): Promise<BundleResult>;
 }

package/dist/browser/bundler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bundler.d.ts","sourceRoot":"","sources":["../../src/browser/bundler.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EACV,QAAQ,EACR,aAAa,EACb,YAAY,EAGb,MAAM,UAAU,CAAC;AAuClB,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,kBAAmB,YAAW,QAAQ;IACjD,OAAO,CAAC,OAAO,CAA4B;gBAE/B,OAAO,GAAE,yBAA8B;IAWnD;;;;;;OAMG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;YAmBnB,YAAY;IA8B1B;;OAEG;IACH,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,yBAAyB;IAc3B,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;CAoG5D"}
+{"version":3,"file":"bundler.d.ts","sourceRoot":"","sources":["../../src/browser/bundler.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAmCtE,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,kBAAmB,YAAW,QAAQ;IACjD,OAAO,CAAC,OAAO,CAA4B;gBAE/B,OAAO,GAAE,yBAA8B;IAWnD;;;;;;OAMG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;YAmBnB,YAAY;IA8B1B;;OAEG;IACH,OAAO,CAAC,UAAU;IAQlB;;;;;;OAMG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAU9B,OAAO,CAAC,yBAAyB;IAc3B,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;CAU5D"}

package/dist/browser/iframe-executor.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Iframe executor for browser environments.
+ *
+ * This executor runs code in a sandboxed iframe, providing DOM isolation
+ * and configurable security policies via the sandbox attribute.
+ *
+ * Key characteristics:
+ * - Per-execution lifecycle: fresh iframe for each execute() call
+ * - Configurable sandbox attributes (default: allow-scripts only)
+ * - No shared module support (use MainThreadExecutor for that)
+ * - Communication via postMessage
+ */
+import type { IExecutor, ExecuteOptions, ExecuteResult } from "../types";
+/**
+ * Options for creating an IframeExecutor.
+ */
+export interface IframeExecutorOptions {
+    /**
+     * Sandbox attributes for the iframe.
+     * @default ["allow-scripts"]
+     *
+     * Common options:
+     * - "allow-scripts": Required for code execution
+     * - "allow-same-origin": Enables localStorage, cookies (reduces isolation)
+     * - "allow-modals": Enables alert/confirm/prompt
+     *
+     * Security note: "allow-scripts" + "allow-same-origin" together allows
+     * the iframe code to potentially remove the sandbox via script.
+     */
+    sandbox?: string[];
+    /**
+     * Default timeout in milliseconds.
+     * @default 30000
+     */
+    defaultTimeout?: number;
+    /**
+     * Container element for iframes.
+     * Iframes are created hidden (display: none).
+     * @default document.body
+     */
+    container?: HTMLElement;
+}
+/**
+ * Executor that runs code in a sandboxed iframe.
+ *
+ * Each execute() call creates a fresh iframe, runs the code, and destroys
+ * the iframe. This provides clean isolation between executions.
+ *
+ * Note: This executor does NOT support shared modules. The iframe runs
+ * in complete isolation. Use MainThreadExecutor if you need shared modules.
+ *
+ * @example
+ * ```ts
+ * // Default: strict sandboxing (allow-scripts only)
+ * const executor = createIframeExecutor();
+ *
+ * // With additional permissions
+ * const executor = createIframeExecutor({
+ *   sandbox: ["allow-scripts", "allow-same-origin"],
+ * });
+ *
+ * const result = await executor.execute(bundledCode, {
+ *   entryExport: 'main',
+ *   context: { args: ['--verbose'] },
+ *   timeout: 5000,
+ * });
+ * console.log(result.logs);
+ * ```
+ */
+export declare class IframeExecutor implements IExecutor {
+    private options;
+    constructor(options?: IframeExecutorOptions);
+    execute(code: string, options?: ExecuteOptions): Promise<ExecuteResult>;
+}
+/**
+ * Create an iframe executor.
+ *
+ * @param options - Executor options
+ * @returns A new IframeExecutor instance
+ */
+export declare function createIframeExecutor(options?: IframeExecutorOptions): IframeExecutor;
+//# sourceMappingURL=iframe-executor.d.ts.map

package/dist/browser/iframe-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"iframe-executor.d.ts","sourceRoot":"","sources":["../../src/browser/iframe-executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzE;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAEnB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;OAIG;IACH,SAAS,CAAC,EAAE,WAAW,CAAC;CACzB;AAmID;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,cAAe,YAAW,SAAS;IAC9C,OAAO,CAAC,OAAO,CAEb;gBAEU,OAAO,GAAE,qBAA0B;IAQzC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,aAAa,CAAC;CA2FlF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,CAAC,EAAE,qBAAqB,GAC9B,cAAc,CAEhB"}

package/dist/browser/index.d.ts

@@ -2,8 +2,10 @@ export { Typechecker, createTypechecker } from "../core/typechecker";
 export type { TypecheckerOptions } from "../core/typechecker";
 export { EsbuildWasmBundler } from "./bundler";
 export type { EsbuildWasmBundlerOptions } from "./bundler";
-export { MainThreadExecutor, createMainThreadExecutor } from "./executor";
-export type { MainThreadExecutorOptions } from "./executor";
+export { MainThreadExecutor, createMainThreadExecutor } from "./main-thread-executor";
+export type { MainThreadExecutorOptions } from "./main-thread-executor";
+export { IframeExecutor, createIframeExecutor } from "./iframe-executor";
+export type { IframeExecutorOptions } from "./iframe-executor";
 export { createBrowserSandlot } from "./preset";
 export type { CreateBrowserSandlotOptions } from "./preset";
 //# sourceMappingURL=index.d.ts.map

package/dist/browser/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"AAkCA,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACrE,YAAY,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAM9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC/C,YAAY,EAAE,yBAAyB,EAAE,MAAM,WAAW,CAAC;AAM3D,OAAO,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAC1E,YAAY,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAM5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAChD,YAAY,EAAE,2BAA2B,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"AAkCA,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACrE,YAAY,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAM9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC/C,YAAY,EAAE,yBAAyB,EAAE,MAAM,WAAW,CAAC;AAM3D,OAAO,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AACtF,YAAY,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAC;AAMxE,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzE,YAAY,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAM/D,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAChD,YAAY,EAAE,2BAA2B,EAAE,MAAM,UAAU,CAAC"}

package/dist/browser/index.js

@@ -649,6 +649,78 @@ function generateSharedModuleCode(moduleId, registry) {
   }
   return code;
 }
+async function executeBundleWithEsbuild(options) {
+  const { esbuild, bundleOptions, cdnBaseUrl, bundleCdnImports } = options;
+  const {
+    fs,
+    entryPoint,
+    installedPackages = {},
+    sharedModules = [],
+    sharedModuleRegistry,
+    external = [],
+    format = "esm",
+    minify = false,
+    sourcemap = false,
+    target = ["es2020"]
+  } = bundleOptions;
+  const normalizedEntry = entryPoint.startsWith("/") ? entryPoint : `/${entryPoint}`;
+  if (!fs.exists(normalizedEntry)) {
+    return {
+      success: false,
+      errors: [{ text: `Entry point not found: ${normalizedEntry}` }],
+      warnings: []
+    };
+  }
+  const includedFiles = new Set;
+  const plugin = createVfsPlugin({
+    fs,
+    entryPoint: normalizedEntry,
+    installedPackages,
+    sharedModules: new Set(sharedModules),
+    sharedModuleRegistry: sharedModuleRegistry ?? null,
+    cdnBaseUrl,
+    includedFiles,
+    bundleCdnImports
+  });
+  try {
+    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 ?? "";
+    const warnings = result.warnings.map((w) => convertEsbuildMessage(w));
+    return {
+      success: true,
+      code,
+      warnings,
+      includedFiles: Array.from(includedFiles)
+    };
+  } catch (err) {
+    if (isEsbuildBuildFailure(err)) {
+      const errors = err.errors.map((e) => convertEsbuildMessage(e));
+      const warnings = err.warnings.map((w) => convertEsbuildMessage(w));
+      return {
+        success: false,
+        errors,
+        warnings
+      };
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      success: false,
+      errors: [{ text: message }],
+      warnings: []
+    };
+  }
+}
 
 // src/browser/bundler.ts
 var ESBUILD_VERSION = "0.27.2";
@@ -708,6 +780,15 @@ class EsbuildWasmBundler {
     }
     return state.esbuild;
   }
+  async dispose() {
+    const state = getGlobalState();
+    if (state.esbuild) {
+      await state.esbuild.stop();
+      state.esbuild = null;
+      state.initialized = false;
+      state.initPromise = null;
+    }
+  }
   checkCrossOriginIsolation() {
     if (typeof window === "undefined")
       return;
@@ -720,75 +801,12 @@ To enable, add these headers to your server:
   }
   async bundle(options) {
     await this.initialize();
-    const esbuild = this.getEsbuild();
-    const {
-      fs,
-      entryPoint,
-      installedPackages = {},
-      sharedModules = [],
-      sharedModuleRegistry,
-      external = [],
-      format = "esm",
-      minify = false,
-      sourcemap = false,
-      target = ["es2020"]
-    } = options;
-    const normalizedEntry = entryPoint.startsWith("/") ? entryPoint : `/${entryPoint}`;
-    if (!fs.exists(normalizedEntry)) {
-      return {
-        success: false,
-        errors: [{ text: `Entry point not found: ${normalizedEntry}` }],
-        warnings: []
-      };
-    }
-    const includedFiles = new Set;
-    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: false
     });
-    try {
-      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 ?? "";
-      const warnings = result.warnings.map((w) => convertEsbuildMessage(w));
-      return {
-        success: true,
-        code,
-        warnings,
-        includedFiles: Array.from(includedFiles)
-      };
-    } catch (err) {
-      if (isEsbuildBuildFailure(err)) {
-        const errors = err.errors.map((e) => convertEsbuildMessage(e));
-        const warnings = err.warnings.map((w) => convertEsbuildMessage(w));
-        return {
-          success: false,
-          errors,
-          warnings
-        };
-      }
-      const message = err instanceof Error ? err.message : String(err);
-      return {
-        success: false,
-        errors: [{ text: message }],
-        warnings: []
-      };
-    }
   }
 }
 // src/core/executor.ts
@@ -813,23 +831,18 @@ function createBasicExecutor(loadModule, options = {}) {
       const formatArgs = (...args) => args.map((v) => typeof v === "object" ? JSON.stringify(v) : String(v)).join(" ");
       const captureLog = (...args) => {
         logs.push(formatArgs(...args));
-        originalConsole.log.apply(console, args);
       };
       const captureWarn = (...args) => {
         logs.push(`[warn] ${formatArgs(...args)}`);
-        originalConsole.warn.apply(console, args);
       };
       const captureError = (...args) => {
         logs.push(`[error] ${formatArgs(...args)}`);
-        originalConsole.error.apply(console, args);
       };
       const captureInfo = (...args) => {
         logs.push(`[info] ${formatArgs(...args)}`);
-        originalConsole.info.apply(console, args);
       };
       const captureDebug = (...args) => {
         logs.push(`[debug] ${formatArgs(...args)}`);
-        originalConsole.debug.apply(console, args);
       };
       const restoreConsole = () => {
         console.log = originalConsole.log;
@@ -856,10 +869,16 @@ function createBasicExecutor(loadModule, options = {}) {
           }
         };
         if (timeout > 0) {
+          let timeoutId;
           const timeoutPromise = new Promise((_, reject) => {
-            setTimeout(() => reject(new Error(`Execution timed out after ${timeout}ms`)), timeout);
+            timeoutId = setTimeout(() => reject(new Error(`Execution timed out after ${timeout}ms`)), timeout);
           });
-          await Promise.race([executeExport(), timeoutPromise]);
+          try {
+            await Promise.race([executeExport(), timeoutPromise]);
+          } finally {
+            if (timeoutId)
+              clearTimeout(timeoutId);
+          }
         } else {
           await executeExport();
         }
@@ -885,7 +904,7 @@ function createBasicExecutor(loadModule, options = {}) {
   };
 }
 
-// src/browser/executor.ts
+// src/browser/main-thread-executor.ts
 async function loadModuleFromBlobUrl(code) {
   const blob = new Blob([code], { type: "application/javascript" });
   const url = URL.createObjectURL(blob);
@@ -906,6 +925,182 @@ class MainThreadExecutor {
 function createMainThreadExecutor(options) {
   return new MainThreadExecutor(options);
 }
+// src/browser/iframe-executor.ts
+var BOOTSTRAP_HTML = `<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+</head>
+<body>
+<script type="module">
+// Capture console methods and forward to parent
+function formatArgs(...args) {
+  return args
+    .map(v => typeof v === "object" ? JSON.stringify(v) : String(v))
+    .join(" ");
+}
+
+function createLogger(level) {
+  return (...args) => {
+    parent.postMessage({ type: "log", level, args: formatArgs(...args) }, "*");
+  };
+}
+
+console.log = createLogger("log");
+console.warn = createLogger("warn");
+console.error = createLogger("error");
+console.info = createLogger("info");
+console.debug = createLogger("debug");
+
+// Handle unhandled promise rejections
+window.addEventListener("unhandledrejection", (event) => {
+  const message = event.reason instanceof Error 
+    ? event.reason.message 
+    : String(event.reason);
+  parent.postMessage({ 
+    type: "result", 
+    success: false, 
+    error: "Unhandled promise rejection: " + message 
+  }, "*");
+});
+
+// Handle uncaught errors
+window.addEventListener("error", (event) => {
+  parent.postMessage({ 
+    type: "result", 
+    success: false, 
+    error: event.message || "Unknown error" 
+  }, "*");
+});
+
+// Listen for execute messages from parent
+window.addEventListener("message", async (event) => {
+  if (event.data?.type !== "execute") return;
+
+  const { code, entryExport, context } = event.data;
+
+  try {
+    // Create Blob URL and import as ESM module
+    const blob = new Blob([code], { type: "application/javascript" });
+    const url = URL.createObjectURL(blob);
+    
+    let module;
+    try {
+      module = await import(url);
+    } finally {
+      URL.revokeObjectURL(url);
+    }
+
+    // Execute the appropriate export
+    let returnValue;
+
+    if (entryExport === "main" && typeof module.main === "function") {
+      returnValue = await module.main(context);
+    } else if (entryExport === "default" && typeof module.default === "function") {
+      returnValue = await module.default();
+    } else if (entryExport === "default" && module.default !== undefined) {
+      returnValue = module.default;
+    }
+    // If neither export exists, top-level code already ran on import
+
+    parent.postMessage({ type: "result", success: true, returnValue }, "*");
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    parent.postMessage({ type: "result", success: false, error: message }, "*");
+  }
+});
+
+// Signal that we're ready to receive code
+parent.postMessage({ type: "ready" }, "*");
+</script>
+</body>
+</html>`;
+
+class IframeExecutor {
+  options;
+  constructor(options = {}) {
+    this.options = {
+      sandbox: options.sandbox ?? ["allow-scripts"],
+      defaultTimeout: options.defaultTimeout ?? 30000,
+      container: options.container
+    };
+  }
+  async execute(code, options = {}) {
+    const {
+      entryExport = "main",
+      context = {},
+      timeout = this.options.defaultTimeout
+    } = options;
+    const startTime = performance.now();
+    const logs = [];
+    const container = this.options.container ?? document.body;
+    const iframe = document.createElement("iframe");
+    iframe.style.display = "none";
+    iframe.sandbox.add(...this.options.sandbox);
+    iframe.srcdoc = BOOTSTRAP_HTML;
+    let resolved = false;
+    return new Promise((resolve) => {
+      const cleanup = () => {
+        if (iframe.parentNode) {
+          iframe.parentNode.removeChild(iframe);
+        }
+        window.removeEventListener("message", handleMessage);
+        if (timeoutId)
+          clearTimeout(timeoutId);
+      };
+      const finish = (result) => {
+        if (resolved)
+          return;
+        resolved = true;
+        cleanup();
+        resolve(result);
+      };
+      const handleMessage = (event) => {
+        if (event.source !== iframe.contentWindow)
+          return;
+        const data = event.data;
+        if (data.type === "log") {
+          const prefix = data.level === "log" ? "" : `[${data.level}] `;
+          logs.push(prefix + data.args);
+        } else if (data.type === "result") {
+          const executionTimeMs = performance.now() - startTime;
+          finish({
+            success: data.success,
+            logs,
+            returnValue: data.returnValue,
+            error: data.error,
+            executionTimeMs
+          });
+        } else if (data.type === "ready") {
+          const message = {
+            type: "execute",
+            code,
+            entryExport,
+            context
+          };
+          iframe.contentWindow?.postMessage(message, "*");
+        }
+      };
+      let timeoutId;
+      if (timeout > 0) {
+        timeoutId = setTimeout(() => {
+          const executionTimeMs = performance.now() - startTime;
+          finish({
+            success: false,
+            logs,
+            error: `Execution timed out after ${timeout}ms`,
+            executionTimeMs
+          });
+        }, timeout);
+      }
+      window.addEventListener("message", handleMessage);
+      container.appendChild(iframe);
+    });
+  }
+}
+function createIframeExecutor(options) {
+  return new IframeExecutor(options);
+}
 // src/core/shared-module-registry.ts
 var instanceCounter = 0;
 function generateInstanceId() {
@@ -2183,6 +2378,64 @@ async function createSandboxImpl(fs, options, context) {
   if (!fs.exists(TSCONFIG_PATH)) {
     fs.writeFile(TSCONFIG_PATH, JSON.stringify(DEFAULT_TSCONFIG, null, 2));
   }
+  if (sharedModuleRegistry && typesResolver) {
+    const sharedModuleIds = sharedModuleRegistry.list();
+    const typesFetches = sharedModuleIds.map(async (moduleId) => {
+      try {
+        const typeFiles = await typesResolver.resolveTypes(moduleId);
+        return { moduleId, typeFiles, error: null };
+      } catch (err) {
+        console.warn(`[sandlot] Failed to fetch types for shared module "${moduleId}":`, err);
+        return { moduleId, typeFiles: {}, error: err };
+      }
+    });
+    const results = await Promise.all(typesFetches);
+    for (const { moduleId, typeFiles } of results) {
+      if (Object.keys(typeFiles).length === 0)
+        continue;
+      let packageName = moduleId;
+      let subpath;
+      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 = null;
+      let fallbackEntry = 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);
+        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;
+        }
+      }
+      const finalTypesEntry = typesEntry ?? fallbackEntry ?? "index.d.ts";
+      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));
+      }
+    }
+  }
   async function install(packageSpec) {
     const { name, version } = parsePackageSpec(packageSpec);
     let resolvedVersion = version ?? "latest";
@@ -2450,6 +2703,11 @@ function createSandlot(options) {
     },
     get sharedModules() {
       return sharedModuleRegistry;
+    },
+    async dispose() {
+      if (bundler.dispose) {
+        await bundler.dispose();
+      }
     }
   };
 }
@@ -2647,7 +2905,7 @@ async function createBrowserSandlot(options = {}) {
   await bundlerInstance.initialize();
   const typecheckerInstance = typechecker === false ? undefined : isTypechecker(typechecker) ? typechecker : new Typechecker(typechecker);
   const typesResolverInstance = typesResolver === false ? undefined : isTypesResolver(typesResolver) ? typesResolver : new EsmTypesResolver(typesResolver);
-  const executorInstance = executor === false ? undefined : isExecutor(executor) ? executor : new MainThreadExecutor(executor);
+  const executorInstance = executor === false ? undefined : executor === "iframe" ? new IframeExecutor : isExecutor(executor) ? executor : isIframeExecutorOptions(executor) ? new IframeExecutor(executor) : new MainThreadExecutor(executor);
   return createSandlot({
     ...rest,
     bundler: bundlerInstance,
@@ -2668,6 +2926,9 @@ function isTypesResolver(value) {
 function isExecutor(value) {
   return typeof value === "object" && value !== null && "execute" in value && typeof value.execute === "function";
 }
+function isIframeExecutorOptions(value) {
+  return typeof value === "object" && value !== null && (("sandbox" in value) || ("container" in value));
+}
 
 // src/browser/index.ts
 if (typeof window !== "undefined" && typeof globalThis.process === "undefined") {
@@ -2683,8 +2944,10 @@ if (typeof window !== "undefined" && typeof globalThis.process === "undefined")
 export {
   createTypechecker,
   createMainThreadExecutor,
+  createIframeExecutor,
   createBrowserSandlot,
   Typechecker,
   MainThreadExecutor,
+  IframeExecutor,
   EsbuildWasmBundler
 };

package/dist/browser/main-thread-executor.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Main thread executor for browser environments.
+ *
+ * This executor runs code directly in the main thread. It provides no
+ * isolation from the host environment - use only for trusted code.
+ *
+ * For untrusted code, consider using a Worker or iframe-based executor
+ * that provides proper sandboxing.
+ */
+import type { IExecutor } from "../types";
+import { type BasicExecutorOptions } from "../core/executor";
+/**
+ * Options for creating a MainThreadExecutor.
+ */
+export type MainThreadExecutorOptions = BasicExecutorOptions;
+/**
+ * Executor that runs code in the main browser thread.
+ *
+ * WARNING: This executor provides NO isolation. The executed code has
+ * full access to the page's DOM, global variables, and network.
+ * Only use for trusted code (e.g., code you're developing).
+ *
+ * @example
+ * ```ts
+ * const executor = createMainThreadExecutor();
+ * const result = await executor.execute(bundledCode, {
+ *   entryExport: 'main',
+ *   context: { args: ['--verbose'] },
+ *   timeout: 5000,
+ * });
+ * console.log(result.logs);
+ * ```
+ */
+export declare class MainThreadExecutor implements IExecutor {
+    private executor;
+    constructor(options?: MainThreadExecutorOptions);
+    execute: IExecutor["execute"];
+}
+/**
+ * Create a main thread executor.
+ *
+ * @param options - Executor options
+ * @returns A new MainThreadExecutor instance
+ */
+export declare function createMainThreadExecutor(options?: MainThreadExecutorOptions): MainThreadExecutor;
+//# sourceMappingURL=main-thread-executor.d.ts.map

package/dist/browser/main-thread-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main-thread-executor.d.ts","sourceRoot":"","sources":["../../src/browser/main-thread-executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,EAAuB,KAAK,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAElF;;GAEG;AACH,MAAM,MAAM,yBAAyB,GAAG,oBAAoB,CAAC;AAgB7D;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,kBAAmB,YAAW,SAAS;IAClD,OAAO,CAAC,QAAQ,CAAY;gBAEhB,OAAO,GAAE,yBAA8B;IAInD,OAAO,EAAE,SAAS,CAAC,SAAS,CAAC,CAA+C;CAC7E;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,CAAC,EAAE,yBAAyB,GAClC,kBAAkB,CAEpB"}