@illuma-ai/code-sandbox 1.3.0 → 1.4.0

package/dist/types.d.ts

@@ -114,6 +114,12 @@ export interface RuntimeState {
      * Missing keys should be treated as "unchanged".
      */
     fileChanges: Record<string, FileChangeStatus>;
+    /**
+     * Monotonically increasing counter that triggers an iframe reload
+     * without restarting the server process. Incremented when only
+     * hot-reloadable files change (CSS, HTML, static assets).
+     */
+    previewReloadKey: number;
     /** Error message if status is 'error' */
     error: string | null;
     /**
@@ -293,6 +299,12 @@ export interface PreviewProps {
     onRefresh?: () => void;
     /** Called when a JavaScript error occurs inside the preview iframe */
     onBrowserError?: (error: SandboxError) => void;
+    /**
+     * Monotonically increasing counter. When this changes, the iframe
+     * is soft-reloaded (location.reload) without restarting the server.
+     * Used for hot-reloading static asset changes (CSS, HTML, images).
+     */
+    reloadKey?: number;
 }
 export interface BootOverlayProps {
     progress: BootProgress;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@illuma-ai/code-sandbox",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Illuma AI (https://github.com/illuma-ai)",

package/src/components/Preview.tsx

@@ -123,11 +123,22 @@ let browserErrorCounter = 0;
  * After the iframe loads, an error-capture script is injected so that
  * runtime errors inside the preview are surfaced to the AI agent.
  */
-export function Preview({ url, className = "", onBrowserError }: PreviewProps) {
+export function Preview({
+  url,
+  className = "",
+  onBrowserError,
+  reloadKey = 0,
+}: PreviewProps) {
   const iframeRef = useRef<HTMLIFrameElement>(null);
   const onBrowserErrorRef = useRef(onBrowserError);
   onBrowserErrorRef.current = onBrowserError;
 
+  /**
+   * Track the previous reloadKey so we only reload on actual changes,
+   * not on initial mount or unrelated re-renders.
+   */
+  const prevReloadKeyRef = useRef(reloadKey);
+
   /**
    * Inject the error-capture script into the iframe's contentWindow.
    *
@@ -207,6 +218,24 @@ export function Preview({ url, className = "", onBrowserError }: PreviewProps) {
     }
   }, [url]);
 
+  // Hot reload: soft-refresh the iframe when reloadKey changes.
+  // This avoids a full server restart for static asset changes (CSS, HTML).
+  useEffect(() => {
+    if (reloadKey !== prevReloadKeyRef.current) {
+      prevReloadKeyRef.current = reloadKey;
+      const iframe = iframeRef.current;
+      if (iframe && url) {
+        try {
+          // Try same-origin reload first (preserves scroll position)
+          iframe.contentWindow?.location.reload();
+        } catch {
+          // Cross-origin fallback — re-assign src
+          iframe.src = url;
+        }
+      }
+    }
+  }, [reloadKey, url]);
+
   return (
     <div className={`h-full w-full bg-white ${className}`}>
       {url ? (

package/src/components/Workbench.tsx

@@ -183,6 +183,7 @@ export const CodeSandbox = forwardRef<CodeSandboxHandle, CodeSandboxProps>(
             <Preview
               url={state.previewUrl}
               onBrowserError={handleBrowserError}
+              reloadKey={state.previewReloadKey}
             />
           </motion.div>
         </div>

package/src/hooks/useRuntime.ts

@@ -29,6 +29,38 @@ import type {
 /** 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.
  *
@@ -115,6 +147,7 @@ export function useRuntime(props: CodeSandboxProps) {
     files: {},
     originalFiles: {},
     fileChanges: {},
+    previewReloadKey: 0,
     error: null,
     errors: [],
   });
@@ -340,12 +373,14 @@ export function useRuntime(props: CodeSandboxProps) {
       // 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);
@@ -356,25 +391,54 @@ export function useRuntime(props: CodeSandboxProps) {
       // Compute change status — "original" is what we had before this update
       const fileChanges = computeFileChanges(currentFiles, newFiles);
 
-      // Update React state with new file set + diff info
-      setState((prev) => ({
-        ...prev,
-        originalFiles: currentFiles,
-        files: newFiles,
-        fileChanges,
-      }));
+      // 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);
 
-      // Restart server if any files changed
       if (changed && shouldRestart) {
-        console.log(
-          DBG,
-          `files changed — restarting server (${Object.keys(fileChanges).length} files differ)`,
-        );
-        try {
-          await runtime.restart();
-        } catch (err) {
-          console.error(DBG, "restart failed:", err);
+        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

package/src/types.ts

@@ -150,6 +150,12 @@ export interface RuntimeState {
    * Missing keys should be treated as "unchanged".
    */
   fileChanges: Record<string, FileChangeStatus>;
+  /**
+   * Monotonically increasing counter that triggers an iframe reload
+   * without restarting the server process. Incremented when only
+   * hot-reloadable files change (CSS, HTML, static assets).
+   */
+  previewReloadKey: number;
   /** Error message if status is 'error' */
   error: string | null;
   /**
@@ -355,6 +361,12 @@ export interface PreviewProps {
   onRefresh?: () => void;
   /** Called when a JavaScript error occurs inside the preview iframe */
   onBrowserError?: (error: SandboxError) => void;
+  /**
+   * Monotonically increasing counter. When this changes, the iframe
+   * is soft-reloaded (location.reload) without restarting the server.
+   * Used for hot-reloading static asset changes (CSS, HTML, images).
+   */
+  reloadKey?: number;
 }
 
 export interface BootOverlayProps {