@illuma-ai/code-sandbox 1.4.0 → 1.5.0

package/src/hooks/useRuntime.ts

@@ -1,637 +0,0 @@
-/**
- * useRuntime — React hook wrapping NodepodRuntime lifecycle.
- *
- * Manages the Nodepod runtime instance and exposes reactive state
- * for all UI components (progress, files, terminal output, preview URL).
- *
- * The sandbox is a pure renderer — it receives files via props (initial
- * load) and via the imperative handle (updateFiles/updateFile for live
- * updates). It does NOT interact with any storage backend directly.
- *
- * Error exposure: wires the runtime's structured error system and the
- * preview iframe's browser error capture into a unified `errors[]` array
- * in state, and forwards each error to the `onSandboxError` callback
- * so the AI agent can auto-fix.
- */
-
-import { useCallback, useEffect, useRef, useState } from "react";
-import { NodepodRuntime } from "../services/runtime";
-import { getTemplate } from "../templates";
-import type {
-  BootProgress,
-  CodeSandboxProps,
-  FileChangeStatus,
-  FileMap,
-  RuntimeState,
-  SandboxError,
-} from "../types";
-
-/** Debug log prefix for easy filtering in DevTools */
-const DBG = "[CodeSandbox:useRuntime]";
-
-/**
- * File extensions that can be hot-reloaded (iframe refresh) without
- * restarting the Node.js server process. These are static assets
- * served by Express — changing them doesn't require a process restart.
- */
-const HOT_RELOAD_EXTENSIONS = new Set([
-  "css",
-  "html",
-  "htm",
-  "svg",
-  "png",
-  "jpg",
-  "jpeg",
-  "gif",
-  "webp",
-  "ico",
-  "woff",
-  "woff2",
-  "ttf",
-  "eot",
-]);
-
-/**
- * Check whether a file path is hot-reloadable (static asset that doesn't
- * require a server restart). Returns false for JS/TS/JSON and any file
- * without an extension.
- */
-function isHotReloadable(filePath: string): boolean {
-  const ext = filePath.split(".").pop()?.toLowerCase();
-  return ext ? HOT_RELOAD_EXTENSIONS.has(ext) : false;
-}
-
-/**
- * Compute per-file change statuses between an original and current file set.
- *
- * Returns only files with a non-"unchanged" status (new, modified, deleted).
- * Files that are identical are omitted — treat missing keys as "unchanged".
- */
-function computeFileChanges(
-  original: FileMap,
-  current: FileMap,
-): Record<string, FileChangeStatus> {
-  const changes: Record<string, FileChangeStatus> = {};
-
-  // Check current files against original
-  for (const path of Object.keys(current)) {
-    if (!(path in original)) {
-      changes[path] = "new";
-    } else if (original[path] !== current[path]) {
-      changes[path] = "modified";
-    }
-    // unchanged — omit
-  }
-
-  // Check for deleted files (in original but not in current)
-  for (const path of Object.keys(original)) {
-    if (!(path in current)) {
-      changes[path] = "deleted";
-    }
-  }
-
-  return changes;
-}
-
-/**
- * Hook that manages the full Nodepod runtime lifecycle.
- *
- * The sandbox is a pure renderer — it receives files via props or the
- * imperative handle. No polling, no storage backends.
- *
- * @param props - CodeSandbox component props
- * @returns Reactive runtime state + control functions + imperative methods
- *
- * @example
- * ```tsx
- * // Direct files (fetched from any source by the host app)
- * const runtime = useRuntime({ files: myFiles, entryCommand: 'node server.js' });
- *
- * // Later, push updated files from the host:
- * await runtime.updateFiles(newFiles);
- *
- * // Or update a single file:
- * await runtime.updateFile('server.js', newContent);
- * ```
- */
-export function useRuntime(props: CodeSandboxProps) {
-  const {
-    files: propFiles,
-    template,
-    entryCommand: propEntryCommand,
-    port: propPort,
-    env,
-    onFileChange,
-    onServerReady,
-    onProgress,
-    onError,
-    onSandboxError,
-    onFilesUpdated,
-  } = props;
-
-  const runtimeRef = useRef<NodepodRuntime | null>(null);
-  const bootedRef = useRef(false);
-  /** Ref for the latest onSandboxError callback (avoids stale closures) */
-  const onSandboxErrorRef = useRef(onSandboxError);
-  onSandboxErrorRef.current = onSandboxError;
-
-  /** Ref for latest onFilesUpdated callback */
-  const onFilesUpdatedRef = useRef(onFilesUpdated);
-  onFilesUpdatedRef.current = onFilesUpdated;
-
-  const [state, setState] = useState<RuntimeState>({
-    status: "initializing",
-    progress: { stage: "initializing", message: "Preparing...", percent: 0 },
-    previewUrl: null,
-    terminalOutput: [],
-    files: {},
-    originalFiles: {},
-    fileChanges: {},
-    previewReloadKey: 0,
-    error: null,
-    errors: [],
-  });
-
-  const [selectedFile, setSelectedFile] = useState<string | null>(null);
-  const [openFiles, setOpenFiles] = useState<string[]>([]);
-
-  // -------------------------------------------------------------------------
-  // Error handling — unified pipeline
-  // -------------------------------------------------------------------------
-
-  /**
-   * Handle a structured error from any source (runtime or browser).
-   *
-   * Appends to the errors array in state and forwards to onSandboxError.
-   * The runtime calls reportError for process errors; the Preview
-   * component calls handleBrowserError for iframe errors.
-   */
-  const handleSandboxError = useCallback((error: SandboxError) => {
-    setState((prev) => ({
-      ...prev,
-      errors: [...prev.errors, error],
-    }));
-    onSandboxErrorRef.current?.(error);
-  }, []);
-
-  /**
-   * Handle a browser error from the preview iframe.
-   *
-   * Called by the Preview component's onBrowserError callback.
-   * We enrich the error with source context from the runtime
-   * (if the file exists in our virtual FS) then record it.
-   */
-  const handleBrowserError = useCallback(
-    async (error: SandboxError) => {
-      const runtime = runtimeRef.current;
-      if (runtime) {
-        // reportError enriches with source context and records internally
-        await runtime.reportError(error);
-      }
-      // Also update React state
-      handleSandboxError(error);
-    },
-    [handleSandboxError],
-  );
-
-  // -------------------------------------------------------------------------
-  // Config resolution
-  // -------------------------------------------------------------------------
-
-  /**
-   * Resolve files + entry command from props or template.
-   */
-  const resolvedConfig = useCallback(() => {
-    if (propFiles && Object.keys(propFiles).length > 0) {
-      // Infer entry command from package.json if not provided
-      let entryCommand = propEntryCommand || "node server.js";
-      if (!propEntryCommand && propFiles["package.json"]) {
-        try {
-          const pkg = JSON.parse(propFiles["package.json"]);
-          if (pkg.scripts?.start) {
-            entryCommand = pkg.scripts.start;
-          }
-        } catch {
-          /* use default */
-        }
-      }
-      return {
-        files: propFiles,
-        entryCommand,
-        port: propPort || 3000,
-      };
-    }
-
-    if (template) {
-      const tpl = getTemplate(template);
-      if (tpl) {
-        return {
-          files: tpl.files,
-          entryCommand: propEntryCommand || tpl.entryCommand,
-          port: propPort || tpl.port,
-        };
-      }
-    }
-
-    // No files provided — return null (sandbox waits for updateFiles)
-    return null;
-  }, [propFiles, template, propEntryCommand, propPort]);
-
-  // -------------------------------------------------------------------------
-  // Boot helpers
-  // -------------------------------------------------------------------------
-
-  /**
-   * Boot the runtime with a resolved file set.
-   */
-  const bootWithFiles = useCallback(
-    (files: FileMap, entryCommand: string, port: number) => {
-      const runtime = new NodepodRuntime({
-        files,
-        entryCommand,
-        port,
-        env,
-      });
-
-      runtimeRef.current = runtime;
-
-      // Set initial files state + open the first file
-      setState((prev) => ({
-        ...prev,
-        files,
-      }));
-
-      const fileNames = Object.keys(files);
-      const entryFile =
-        fileNames.find((f) => f === "server.js") ||
-        fileNames.find((f) => f === "index.js") ||
-        fileNames.find((f) => f.endsWith(".js")) ||
-        fileNames[0];
-
-      if (entryFile) {
-        setSelectedFile(entryFile);
-        setOpenFiles([entryFile]);
-      }
-
-      // Wire progress callback
-      runtime.setProgressCallback((progress: BootProgress) => {
-        setState((prev) => ({
-          ...prev,
-          status: progress.stage,
-          progress,
-          previewUrl: runtime.getPreviewUrl(),
-          error: progress.stage === "error" ? progress.message : prev.error,
-        }));
-        onProgress?.(progress);
-        if (progress.stage === "error") {
-          onError?.(progress.message);
-        }
-      });
-
-      // Wire terminal output callback
-      runtime.setOutputCallback((line: string) => {
-        setState((prev) => ({
-          ...prev,
-          terminalOutput: [...prev.terminalOutput, line],
-        }));
-      });
-
-      // Wire server ready callback
-      runtime.setServerReadyCallback((readyPort: number, url: string) => {
-        setState((prev) => ({
-          ...prev,
-          previewUrl: url,
-          status: "ready",
-        }));
-        onServerReady?.(readyPort, url);
-      });
-
-      // Wire structured error callback
-      runtime.setErrorCallback(handleSandboxError);
-
-      // Boot
-      runtime.boot().catch((err) => {
-        const msg = err instanceof Error ? err.message : String(err);
-        onError?.(msg);
-      });
-
-      return runtime;
-    },
-    [env, onProgress, onError, onServerReady, handleSandboxError],
-  );
-
-  // -------------------------------------------------------------------------
-  // Imperative file update methods
-  // -------------------------------------------------------------------------
-
-  /**
-   * Push a complete new file set into the sandbox.
-   *
-   * Diffs against current files, writes only changed files to Nodepod FS,
-   * and restarts the server if anything changed (unless restartServer=false).
-   *
-   * The previous file set becomes `originalFiles` for diff tracking.
-   *
-   * Called by the imperative handle's updateFiles() method.
-   * Also usable as the initial boot path when files arrive asynchronously
-   * (e.g., host fetches from a remote source, then calls updateFiles).
-   */
-  const updateFiles = useCallback(
-    async (newFiles: FileMap, options?: { restartServer?: boolean }) => {
-      const shouldRestart = options?.restartServer !== false;
-      const runtime = runtimeRef.current;
-
-      // If runtime hasn't booted yet, boot with these files
-      if (!runtime) {
-        if (bootedRef.current) {
-          console.warn(
-            DBG,
-            "updateFiles called but runtime is gone (already torn down)",
-          );
-          return;
-        }
-        bootedRef.current = true;
-
-        // Infer entry command from package.json
-        let entryCommand = propEntryCommand || "node server.js";
-        if (!propEntryCommand && newFiles["package.json"]) {
-          try {
-            const pkg = JSON.parse(newFiles["package.json"]);
-            if (pkg.scripts?.start) {
-              entryCommand = pkg.scripts.start;
-            }
-          } catch {
-            /* use default */
-          }
-        }
-        const port = propPort || 3000;
-
-        bootWithFiles(newFiles, entryCommand, port);
-        return;
-      }
-
-      // Runtime exists — diff and write changed files
-      const currentFiles = runtime.getCurrentFiles();
-      let changed = false;
-      const changedPaths: string[] = [];
-
-      for (const [path, content] of Object.entries(newFiles)) {
-        if (currentFiles[path] !== content) {
-          try {
-            await runtime.writeFile(path, content);
-            changed = true;
-            changedPaths.push(path);
-            console.log(DBG, `updated file: ${path}`);
-          } catch (err) {
-            console.warn(DBG, `failed to write ${path}:`, err);
-          }
-        }
-      }
-
-      // Compute change status — "original" is what we had before this update
-      const fileChanges = computeFileChanges(currentFiles, newFiles);
-
-      // Decide: hot reload (iframe refresh) vs cold restart (kill + rerun server).
-      // Hot reload when ALL changed files are static assets (CSS, HTML, images).
-      // Cold restart when ANY changed file is JS/TS/JSON/etc. that affects the server.
-      const canHotReload =
-        changed &&
-        changedPaths.length > 0 &&
-        changedPaths.every(isHotReloadable);
-
-      if (changed && shouldRestart) {
-        if (canHotReload) {
-          // Hot reload — just bump the preview reload key to refresh the iframe
-          console.log(
-            DBG,
-            `hot reload: ${changedPaths.length} static file(s) changed — refreshing preview`,
-          );
-          setState((prev) => ({
-            ...prev,
-            originalFiles: currentFiles,
-            files: newFiles,
-            fileChanges,
-            previewReloadKey: prev.previewReloadKey + 1,
-          }));
-        } else {
-          // Cold restart — server code changed, need full process restart
-          console.log(
-            DBG,
-            `cold restart: ${changedPaths.length} file(s) changed — restarting server`,
-          );
-          setState((prev) => ({
-            ...prev,
-            originalFiles: currentFiles,
-            files: newFiles,
-            fileChanges,
-          }));
-          try {
-            await runtime.restart();
-          } catch (err) {
-            console.error(DBG, "restart failed:", err);
-          }
-        }
-      } else {
-        // No changes or restart disabled — just update state
-        setState((prev) => ({
-          ...prev,
-          originalFiles: currentFiles,
-          files: newFiles,
-          fileChanges,
-        }));
-      }
-
-      // Notify host that files have been processed
-      onFilesUpdatedRef.current?.(fileChanges);
-    },
-    [propEntryCommand, propPort, bootWithFiles],
-  );
-
-  /**
-   * Push a single file update into the sandbox.
-   *
-   * Writes to Nodepod FS and updates React state. Does NOT restart
-   * the server — use restart() if needed, or updateFiles() for bulk
-   * updates with auto-restart.
-   *
-   * This is the same path as editor edits, but callable imperatively
-   * (e.g., when the agent modifies a single file).
-   */
-  const updateFile = useCallback(async (path: string, content: string) => {
-    const runtime = runtimeRef.current;
-    if (!runtime) {
-      console.warn(
-        DBG,
-        "updateFile called but runtime not ready. Use updateFiles() for initial load.",
-      );
-      return;
-    }
-
-    try {
-      await runtime.writeFile(path, content);
-    } catch (err) {
-      console.error(`Failed to write file ${path}:`, err);
-    }
-
-    setState((prev) => {
-      const newFiles = { ...prev.files, [path]: content };
-      const newChanges = { ...prev.fileChanges };
-      if (!(path in prev.originalFiles)) {
-        newChanges[path] = "new";
-      } else if (prev.originalFiles[path] !== content) {
-        newChanges[path] = "modified";
-      } else {
-        // Reverted back to original — remove from changes
-        delete newChanges[path];
-      }
-      return {
-        ...prev,
-        files: newFiles,
-        fileChanges: newChanges,
-      };
-    });
-  }, []);
-
-  // -------------------------------------------------------------------------
-  // Boot on mount
-  // -------------------------------------------------------------------------
-
-  useEffect(() => {
-    if (bootedRef.current) return;
-
-    const config = resolvedConfig();
-
-    if (config) {
-      // Direct files or template — boot immediately
-      bootedRef.current = true;
-      if (Object.keys(config.files).length === 0) return;
-      bootWithFiles(config.files, config.entryCommand, config.port);
-    }
-    // If no config (no files, no template), sandbox waits for
-    // updateFiles() to be called via the imperative handle.
-
-    // Cleanup on unmount
-    return () => {
-      runtimeRef.current?.teardown();
-      runtimeRef.current = null;
-    };
-  }, []); // eslint-disable-line react-hooks/exhaustive-deps
-
-  // -------------------------------------------------------------------------
-  // File editing (from the CodeEditor UI)
-  // -------------------------------------------------------------------------
-
-  const handleFileChange = useCallback(
-    async (path: string, content: string) => {
-      const runtime = runtimeRef.current;
-      if (!runtime) return;
-
-      try {
-        await runtime.writeFile(path, content);
-      } catch (err) {
-        console.error(`Failed to write file ${path}:`, err);
-      }
-
-      setState((prev) => {
-        const newFiles = { ...prev.files, [path]: content };
-        // Recompute change status for this file against originalFiles.
-        // Only update this file's status — don't recompute everything.
-        const newChanges = { ...prev.fileChanges };
-        if (!(path in prev.originalFiles)) {
-          newChanges[path] = "new";
-        } else if (prev.originalFiles[path] !== content) {
-          newChanges[path] = "modified";
-        } else {
-          // Reverted back to original — remove from changes
-          delete newChanges[path];
-        }
-
-        return {
-          ...prev,
-          files: newFiles,
-          fileChanges: newChanges,
-        };
-      });
-
-      onFileChange?.(path, content);
-    },
-    [onFileChange],
-  );
-
-  // -------------------------------------------------------------------------
-  // File selection
-  // -------------------------------------------------------------------------
-
-  const handleSelectFile = useCallback((path: string) => {
-    setSelectedFile(path);
-    setOpenFiles((prev) => (prev.includes(path) ? prev : [...prev, path]));
-  }, []);
-
-  const handleCloseFile = useCallback(
-    (path: string) => {
-      setOpenFiles((prev) => {
-        const next = prev.filter((p) => p !== path);
-        if (selectedFile === path) {
-          setSelectedFile(next.length > 0 ? next[next.length - 1] : null);
-        }
-        return next;
-      });
-    },
-    [selectedFile],
-  );
-
-  // -------------------------------------------------------------------------
-  // Server control
-  // -------------------------------------------------------------------------
-
-  const restart = useCallback(async () => {
-    const runtime = runtimeRef.current;
-    if (!runtime) return;
-    await runtime.restart();
-  }, []);
-
-  // -------------------------------------------------------------------------
-  // State readers (for imperative handle)
-  // -------------------------------------------------------------------------
-
-  const getFiles = useCallback((): FileMap => {
-    return runtimeRef.current?.getCurrentFiles() ?? {};
-  }, []);
-
-  const getChangedFiles = useCallback((): FileMap => {
-    return runtimeRef.current?.getChangedFiles() ?? {};
-  }, []);
-
-  const getFileChanges = useCallback((): Record<string, FileChangeStatus> => {
-    // Read from React state since it's the source of truth for changes
-    return state.fileChanges;
-  }, [state.fileChanges]);
-
-  const getErrors = useCallback((): SandboxError[] => {
-    return state.errors;
-  }, [state.errors]);
-
-  const getState = useCallback((): RuntimeState => {
-    return state;
-  }, [state]);
-
-  return {
-    state,
-    selectedFile,
-    openFiles,
-    handleFileChange,
-    handleSelectFile,
-    handleCloseFile,
-    handleBrowserError,
-    restart,
-    // Imperative methods (exposed via handle)
-    updateFiles,
-    updateFile,
-    getFiles,
-    getChangedFiles,
-    getFileChanges,
-    getErrors,
-    getState,
-    runtime: runtimeRef,
-  };
-}

package/src/index.ts

@@ -1,51 +0,0 @@
-/**
- * @illuma-ai/code-sandbox — Public API
- *
- * This is the main entry point for the library.
- * Consumers import from here.
- */
-
-// Styles — imported here so Vite extracts them into the library CSS bundle.
-// Consumers must import: import "@illuma-ai/code-sandbox/styles.css";
-import "./styles.css";
-
-// Main component
-export { CodeSandbox } from "./components/Workbench";
-
-// Individual components (for custom layouts)
-export { FileTree, buildFileTree } from "./components/FileTree";
-export { CodeEditor } from "./components/CodeEditor";
-export { Terminal } from "./components/Terminal";
-export { Preview } from "./components/Preview";
-export { BootOverlay } from "./components/BootOverlay";
-export { ViewSlider } from "./components/ViewSlider";
-export type { WorkbenchView } from "./components/ViewSlider";
-
-// Services
-export { NodepodRuntime } from "./services/runtime";
-
-// Hooks
-export { useRuntime } from "./hooks/useRuntime";
-
-// Templates
-export { getTemplate, listTemplates } from "./templates";
-
-// Types
-export type {
-  FileMap,
-  FileNode,
-  FileChangeStatus,
-  SandboxError,
-  SandboxErrorCategory,
-  BootStage,
-  BootProgress,
-  RuntimeConfig,
-  RuntimeState,
-  CodeSandboxProps,
-  CodeSandboxHandle,
-  FileTreeProps,
-  CodeEditorProps,
-  TerminalProps,
-  PreviewProps,
-  BootOverlayProps,
-} from "./types";