Add optional Web Worker support for runtime execution

- Add IRuntime interface for polymorphism between sync/async runtimes
- Add VFS snapshot/restore for transferring file system to worker
- Add VFS event emitter for change/delete notifications
- Add WorkerRuntime class that executes code in a Web Worker
- Add createRuntime() factory with useWorker option
- Maintain full backward compatibility (Runtime.execute() stays sync)
- Add comlink dependency for worker communication
- Add comprehensive tests for worker runtime and VFS snapshots

Usage:
  // Main thread (default, backward compatible)
  const runtime = await createRuntime(vfs, { useWorker: false });

  // Worker mode (opt-in for better UI responsiveness)
  const runtime = await createRuntime(vfs, { useWorker: true });

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: petrbrzek

package-lock.json

@@ -47,6 +47,7 @@
     "@webcontainer/api": "^1.6.1",
     "brotli": "^1.3.3",
     "brotli-wasm": "^3.0.1",
+    "comlink": "^4.4.2",
     "just-bash": "^2.7.0",
     "pako": "^2.1.0",
     "resolve.exports": "^2.0.3",

package.json

@@ -0,0 +1,108 @@
+/**
+ * Runtime Factory - Create main-thread or worker runtime based on configuration
+ *
+ * Usage:
+ *   // Main thread (default)
+ *   const runtime = await createRuntime(vfs, { useWorker: false });
+ *
+ *   // Worker mode
+ *   const runtime = await createRuntime(vfs, { useWorker: true });
+ *
+ *   // Auto-detect
+ *   const runtime = await createRuntime(vfs, { useWorker: 'auto' });
+ */
+
+import { Runtime } from './runtime';
+import { WorkerRuntime } from './worker-runtime';
+import type { VirtualFS } from './virtual-fs';
+import type { IRuntime, IExecuteResult, CreateRuntimeOptions, IRuntimeOptions } from './runtime-interface';
+
+/**
+ * Check if Web Workers are available in the current environment
+ */
+function isWorkerAvailable(): boolean {
+  return typeof Worker !== 'undefined';
+}
+
+/**
+ * Wrapper that makes the synchronous Runtime conform to the async IRuntime interface
+ */
+class AsyncRuntimeWrapper implements IRuntime {
+  private runtime: Runtime;
+
+  constructor(vfs: VirtualFS, options: IRuntimeOptions = {}) {
+    this.runtime = new Runtime(vfs, options);
+  }
+
+  async execute(code: string, filename?: string): Promise<IExecuteResult> {
+    return Promise.resolve(this.runtime.execute(code, filename));
+  }
+
+  async runFile(filename: string): Promise<IExecuteResult> {
+    return Promise.resolve(this.runtime.runFile(filename));
+  }
+
+  clearCache(): void {
+    this.runtime.clearCache();
+  }
+
+  getVFS(): VirtualFS {
+    return this.runtime.getVFS();
+  }
+
+  /**
+   * Get the underlying sync Runtime for direct access to sync methods
+   */
+  getSyncRuntime(): Runtime {
+    return this.runtime;
+  }
+}
+
+/**
+ * Create a runtime instance based on configuration
+ *
+ * @param vfs - Virtual file system instance
+ * @param options - Runtime options including useWorker flag
+ * @returns Promise resolving to IRuntime instance
+ */
+export async function createRuntime(
+  vfs: VirtualFS,
+  options: CreateRuntimeOptions = {}
+): Promise<IRuntime> {
+  const { useWorker = false, ...runtimeOptions } = options;
+
+  // Determine if we should use a worker
+  let shouldUseWorker = false;
+
+  if (useWorker === true) {
+    shouldUseWorker = isWorkerAvailable();
+    if (!shouldUseWorker) {
+      console.warn('[createRuntime] Worker requested but not available, falling back to main thread');
+    }
+  } else if (useWorker === 'auto') {
+    shouldUseWorker = isWorkerAvailable();
+    console.log(`[createRuntime] Auto mode: using ${shouldUseWorker ? 'worker' : 'main thread'}`);
+  }
+
+  if (shouldUseWorker) {
+    console.log('[createRuntime] Creating WorkerRuntime');
+    const workerRuntime = new WorkerRuntime(vfs, runtimeOptions);
+    // Wait for worker to be ready by executing a simple command
+    await workerRuntime.execute('/* worker ready check */', '/__worker_init__.js');
+    return workerRuntime;
+  }
+
+  console.log('[createRuntime] Creating main-thread Runtime');
+  return new AsyncRuntimeWrapper(vfs, runtimeOptions);
+}
+
+// Re-export types and classes for convenience
+export { Runtime } from './runtime';
+export { WorkerRuntime } from './worker-runtime';
+export type {
+  IRuntime,
+  IExecuteResult,
+  IRuntimeOptions,
+  CreateRuntimeOptions,
+  VFSSnapshot,
+} from './runtime-interface';

src/create-runtime.ts

@@ -0,0 +1,81 @@
+/**
+ * Runtime Interface - Common interface for main-thread and worker runtimes
+ */
+
+import type { VirtualFS } from './virtual-fs';
+
+export interface IRuntimeOptions {
+  cwd?: string;
+  env?: Record<string, string>;
+  onConsole?: (method: string, args: unknown[]) => void;
+}
+
+export interface IModule {
+  id: string;
+  filename: string;
+  exports: unknown;
+  loaded: boolean;
+  children: IModule[];
+  paths: string[];
+}
+
+export interface IExecuteResult {
+  exports: unknown;
+  module: IModule;
+}
+
+/**
+ * Common runtime interface implemented by both MainThreadRuntime and WorkerRuntime
+ */
+export interface IRuntime {
+  /**
+   * Execute code as a module
+   */
+  execute(code: string, filename?: string): Promise<IExecuteResult>;
+
+  /**
+   * Run a file from the virtual file system
+   */
+  runFile(filename: string): Promise<IExecuteResult>;
+
+  /**
+   * Clear the module cache
+   */
+  clearCache(): void;
+
+  /**
+   * Get the virtual file system (only available on main thread runtime)
+   */
+  getVFS?(): VirtualFS;
+
+  /**
+   * Terminate the runtime (only applicable to worker runtime)
+   */
+  terminate?(): void;
+}
+
+/**
+ * Options for creating a runtime
+ */
+export interface CreateRuntimeOptions extends IRuntimeOptions {
+  /**
+   * Whether to use a Web Worker for code execution
+   * - false (default): Execute on main thread
+   * - true: Execute in a Web Worker
+   * - 'auto': Use worker if available, fallback to main thread
+   */
+  useWorker?: boolean | 'auto';
+}
+
+/**
+ * VFS snapshot for transferring to worker
+ */
+export interface VFSSnapshot {
+  files: VFSFileEntry[];
+}
+
+export interface VFSFileEntry {
+  path: string;
+  type: 'file' | 'directory';
+  content?: string; // base64 encoded for binary files
+}

src/runtime-interface.ts

@@ -6,6 +6,7 @@
  */
 
 import { VirtualFS } from './virtual-fs';
+import type { IRuntime, IExecuteResult, IRuntimeOptions } from './runtime-interface';
 import { createFsShim, FsShim } from './shims/fs';
 import * as pathShim from './shims/path';
 import { createProcess, Process } from './shims/process';
@@ -769,6 +770,8 @@ function createConsoleWrapper(
 
 /**
  * Runtime class for executing code in virtual environment
+ * Note: This class has sync methods for backward compatibility.
+ * Use createRuntime() factory for IRuntime interface compliance.
  */
 export class Runtime {
   private vfs: VirtualFS;
@@ -886,7 +889,7 @@ export class Runtime {
   }
 
   /**
-   * Execute code as a module
+   * Execute code as a module (synchronous - backward compatible)
    */
   execute(
     code: string,
@@ -968,13 +971,41 @@ ${code}
   }
 
   /**
-   * Run a file from the virtual file system
+   * Execute code as a module (async version for IRuntime interface)
+   * Alias: executeSync() is the same as execute() for backward compatibility
+   */
+  executeSync = this.execute;
+
+  /**
+   * Execute code as a module (async - for IRuntime interface)
+   */
+  async executeAsync(
+    code: string,
+    filename: string = '/index.js'
+  ): Promise<IExecuteResult> {
+    return Promise.resolve(this.execute(code, filename));
+  }
+
+  /**
+   * Run a file from the virtual file system (synchronous - backward compatible)
    */
   runFile(filename: string): { exports: unknown; module: Module } {
     const code = this.vfs.readFileSync(filename, 'utf8');
     return this.execute(code, filename);
   }
 
+  /**
+   * Alias for runFile (backward compatibility)
+   */
+  runFileSync = this.runFile;
+
+  /**
+   * Run a file from the virtual file system (async - for IRuntime interface)
+   */
+  async runFileAsync(filename: string): Promise<IExecuteResult> {
+    return Promise.resolve(this.runFile(filename));
+  }
+
   /**
    * Clear the module cache
    */
@@ -998,7 +1029,7 @@ ${code}
 }
 
 /**
- * Create and execute code in a new runtime
+ * Create and execute code in a new runtime (synchronous - backward compatible)
  */
 export function execute(
   code: string,
@@ -1009,4 +1040,7 @@ export function execute(
   return runtime.execute(code);
 }
 
+// Re-export types
+export type { IRuntime, IExecuteResult, IRuntimeOptions } from './runtime-interface';
+
 export default Runtime;