@illuma-ai/code-sandbox 1.0.0

package/src/components/Workbench.tsx

@@ -0,0 +1,301 @@
+/**
+ * Workbench — Main layout component for the code sandbox.
+ *
+ * Two full-width views toggled via a pill slider in the toolbar:
+ * - Code: FileTree (left) + Editor (top-right) + Terminal (bottom-right)
+ * - Preview: Full-width browser iframe with URL bar
+ *
+ * The toggle lives inside a compact toolbar row shared with the URL bar.
+ * Both views are full-width — Preview has no file tree, Code has no iframe.
+ *
+ * Responsive: works from ~320px up. On narrow screens the file tree
+ * collapses to a smaller width, and the allotment handles overflow.
+ *
+ * @see bolt.diy: app/components/workbench/Workbench.client.tsx (reference)
+ */
+
+import React, {
+  useMemo,
+  useState,
+  useEffect,
+  useCallback,
+  useRef,
+} from "react";
+import { Allotment } from "allotment";
+import { motion, AnimatePresence } from "framer-motion";
+import "allotment/dist/style.css";
+
+import { buildFileTree, FileTree } from "./FileTree";
+import { CodeEditor } from "./CodeEditor";
+import { Terminal } from "./Terminal";
+import { Preview } from "./Preview";
+import { BootOverlay } from "./BootOverlay";
+import { ViewSlider, type WorkbenchView } from "./ViewSlider";
+import { useRuntime } from "../hooks/useRuntime";
+import type { CodeSandboxProps } from "../types";
+
+/** Transition for view crossfade */
+const VIEW_TRANSITION = {
+  duration: 0.2,
+  ease: [0.4, 0, 0.2, 1] as [number, number, number, number],
+};
+
+/**
+ * CodeSandbox — The main entrypoint component.
+ *
+ * Renders a complete IDE-like workbench with two full-width views:
+ * - Code: file tree + editor + terminal (split panes)
+ * - Preview: full-width browser iframe
+ *
+ * A compact toolbar row contains the view toggle and (in preview mode)
+ * a URL bar with refresh button.
+ */
+export function CodeSandbox(props: CodeSandboxProps) {
+  const { className = "", height = "100vh", port = 3000 } = props;
+
+  const {
+    state,
+    selectedFile,
+    openFiles,
+    handleFileChange,
+    handleSelectFile,
+    handleCloseFile,
+    restart,
+  } = useRuntime(props);
+
+  const fileTree = useMemo(() => buildFileTree(state.files), [state.files]);
+  const isBooting = state.status !== "ready" && state.status !== "error";
+
+  // Active view: code or preview
+  const [activeView, setActiveView] = useState<WorkbenchView>("code");
+
+  // Auto-switch to preview when server becomes ready
+  const hasPreview = !!state.previewUrl;
+  useEffect(() => {
+    if (hasPreview) {
+      setActiveView("preview");
+    }
+  }, [hasPreview]);
+
+  // Switch to code view when a file is selected from the tree
+  const onFileSelect = useCallback(
+    (path: string) => {
+      handleSelectFile(path);
+      setActiveView("code");
+    },
+    [handleSelectFile],
+  );
+
+  return (
+    <div
+      className={`sb-root relative w-full bg-sb-bg text-sb-text overflow-hidden flex flex-col ${className}`}
+      style={{ height }}
+    >
+      {/* Boot overlay */}
+      {isBooting && <BootOverlay progress={state.progress} />}
+
+      {/* Toolbar — compact row with view toggle + URL bar */}
+      <Toolbar
+        activeView={activeView}
+        onViewChange={setActiveView}
+        previewUrl={state.previewUrl}
+        port={port}
+        onRefresh={restart}
+      />
+
+      {/* Views — full width, toggled */}
+      <div className="flex-1 relative overflow-hidden min-h-0">
+        {/* Code view */}
+        <motion.div
+          className="absolute inset-0"
+          initial={false}
+          animate={{
+            opacity: activeView === "code" ? 1 : 0,
+            pointerEvents: activeView === "code" ? "auto" : "none",
+          }}
+          transition={{ duration: 0.15 }}
+        >
+          <CodeView
+            fileTree={fileTree}
+            files={state.files}
+            selectedFile={selectedFile}
+            openFiles={openFiles}
+            terminalOutput={state.terminalOutput}
+            onSelectFile={onFileSelect}
+            onCloseFile={handleCloseFile}
+            onFileChange={handleFileChange}
+          />
+        </motion.div>
+
+        {/* Preview view */}
+        <motion.div
+          className="absolute inset-0"
+          initial={false}
+          animate={{
+            opacity: activeView === "preview" ? 1 : 0,
+            pointerEvents: activeView === "preview" ? "auto" : "none",
+          }}
+          transition={{ duration: 0.15 }}
+        >
+          <Preview url={state.previewUrl} />
+        </motion.div>
+      </div>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Toolbar
+// ---------------------------------------------------------------------------
+
+interface ToolbarProps {
+  activeView: WorkbenchView;
+  onViewChange: (view: WorkbenchView) => void;
+  previewUrl: string | null;
+  port: number;
+  onRefresh?: () => void;
+}
+
+/**
+ * Formats the internal preview URL into a friendly display URL.
+ *
+ * The actual preview URL is something like `https://host/__preview__/3000/path`
+ * (a Service Worker proxy URL). This is meaningless to the user — the app runs
+ * entirely in their browser. We show `localhost:{port}/path` instead, which
+ * matches what they'd see from a real local dev server.
+ */
+function formatDisplayUrl(previewUrl: string | null, port: number): string {
+  if (!previewUrl) return "";
+
+  // Extract the path portion after /__preview__/PORT or /__virtual__/PORT
+  const match = previewUrl.match(/\/__(?:preview|virtual)__\/\d+(\/.*)?$/);
+  const path = match?.[1] ?? "/";
+  return `localhost:${port}${path}`;
+}
+
+/**
+ * Toolbar — single compact row with view toggle + URL bar.
+ * URL bar only shows in preview mode. In code mode the space is
+ * used for a subtle status label.
+ */
+function Toolbar({
+  activeView,
+  onViewChange,
+  previewUrl,
+  port,
+  onRefresh,
+}: ToolbarProps) {
+  const displayUrl = formatDisplayUrl(previewUrl, port);
+
+  return (
+    <div className="flex items-center gap-2 px-2 py-1 bg-sb-bg-alt border-b border-sb-border min-h-[36px] shrink-0">
+      {/* View toggle — always visible */}
+      <ViewSlider selected={activeView} onSelect={onViewChange} />
+
+      {/* Right side: URL bar in preview mode, status in code mode */}
+      <div className="flex-1 min-w-0">
+        {activeView === "preview" ? (
+          <div className="flex items-center gap-1.5">
+            <button
+              className="shrink-0 p-1 rounded text-sb-text-muted hover:text-sb-text-active hover:bg-sb-bg-hover transition-colors text-xs"
+              onClick={onRefresh}
+              title="Refresh preview"
+            >
+              <RefreshIcon />
+            </button>
+            <div className="flex-1 min-w-0 bg-sb-bg rounded px-2 py-0.5 text-xs text-sb-text-muted font-mono truncate">
+              {previewUrl ? displayUrl : "Waiting for server..."}
+            </div>
+          </div>
+        ) : (
+          <div className="text-xs text-sb-text-muted px-1 truncate">Editor</div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+/** Small inline refresh icon (SVG) */
+function RefreshIcon() {
+  return (
+    <svg
+      width="14"
+      height="14"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <polyline points="23 4 23 10 17 10" />
+      <path d="M20.49 15a9 9 0 1 1-2.12-9.36L23 10" />
+    </svg>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// CodeView — full-width code editing layout
+// ---------------------------------------------------------------------------
+
+interface CodeViewProps {
+  fileTree: ReturnType<typeof buildFileTree>;
+  files: Record<string, string>;
+  selectedFile: string | null;
+  openFiles: string[];
+  terminalOutput: string[];
+  onSelectFile: (path: string) => void;
+  onCloseFile: (path: string) => void;
+  onFileChange: (path: string, content: string) => void;
+}
+
+/**
+ * CodeView — FileTree (left) + Editor (top-right) + Terminal (bottom-right).
+ * Uses Allotment for resizable split panes.
+ * Responsive: file tree shrinks on narrow containers.
+ */
+function CodeView({
+  fileTree,
+  files,
+  selectedFile,
+  openFiles,
+  terminalOutput,
+  onSelectFile,
+  onCloseFile,
+  onFileChange,
+}: CodeViewProps) {
+  return (
+    <div className="h-full w-full">
+      <Allotment>
+        {/* File tree — left */}
+        <Allotment.Pane preferredSize={200} minSize={120} maxSize={350}>
+          <FileTree
+            files={fileTree}
+            selectedFile={selectedFile}
+            onSelectFile={onSelectFile}
+          />
+        </Allotment.Pane>
+
+        {/* Editor + Terminal — right */}
+        <Allotment.Pane>
+          <Allotment vertical>
+            <Allotment.Pane preferredSize="70%">
+              <CodeEditor
+                files={files}
+                activeFile={selectedFile}
+                openFiles={openFiles}
+                onSelectFile={onSelectFile}
+                onCloseFile={onCloseFile}
+                onFileChange={onFileChange}
+              />
+            </Allotment.Pane>
+
+            <Allotment.Pane preferredSize="30%" minSize={60}>
+              <Terminal output={terminalOutput} />
+            </Allotment.Pane>
+          </Allotment>
+        </Allotment.Pane>
+      </Allotment>
+    </div>
+  );
+}

package/src/hooks/useRuntime.ts

@@ -0,0 +1,236 @@
+/**
+ * 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).
+ */
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { NodepodRuntime } from "../services/runtime";
+import { getTemplate } from "../templates";
+import type {
+  BootProgress,
+  CodeSandboxProps,
+  FileMap,
+  RuntimeState,
+} from "../types";
+
+/**
+ * Hook that manages the full Nodepod runtime lifecycle.
+ *
+ * @param props - CodeSandbox component props
+ * @returns Reactive runtime state + control functions
+ */
+export function useRuntime(props: CodeSandboxProps) {
+  const {
+    files: propFiles,
+    template,
+    entryCommand: propEntryCommand,
+    port: propPort,
+    env,
+    onFileChange,
+    onServerReady,
+    onProgress,
+    onError,
+  } = props;
+
+  const runtimeRef = useRef<NodepodRuntime | null>(null);
+  const bootedRef = useRef(false);
+
+  const [state, setState] = useState<RuntimeState>({
+    status: "initializing",
+    progress: { stage: "initializing", message: "Preparing...", percent: 0 },
+    previewUrl: null,
+    terminalOutput: [],
+    files: {},
+    error: null,
+  });
+
+  const [selectedFile, setSelectedFile] = useState<string | null>(null);
+  const [openFiles, setOpenFiles] = useState<string[]>([]);
+
+  // Resolve files + entry command from props or template
+  const resolvedConfig = useCallback(() => {
+    if (propFiles) {
+      return {
+        files: propFiles,
+        entryCommand: propEntryCommand || "node server.js",
+        port: propPort || 3000,
+      };
+    }
+
+    if (template) {
+      const tpl = getTemplate(template);
+      if (tpl) {
+        return {
+          files: tpl.files,
+          entryCommand: propEntryCommand || tpl.entryCommand,
+          port: propPort || tpl.port,
+        };
+      }
+    }
+
+    // Default: empty project
+    return {
+      files: {},
+      entryCommand: propEntryCommand || "node server.js",
+      port: propPort || 3000,
+    };
+  }, [propFiles, template, propEntryCommand, propPort]);
+
+  // Boot the runtime on mount
+  useEffect(() => {
+    if (bootedRef.current) {
+      return;
+    }
+    bootedRef.current = true;
+
+    const config = resolvedConfig();
+    if (Object.keys(config.files).length === 0) {
+      return;
+    }
+
+    const runtime = new NodepodRuntime({
+      files: config.files,
+      entryCommand: config.entryCommand,
+      port: config.port,
+      env,
+    });
+
+    runtimeRef.current = runtime;
+
+    // Set initial files state + open the first file
+    setState((prev) => ({
+      ...prev,
+      files: config.files,
+    }));
+
+    const fileNames = Object.keys(config.files);
+    // Auto-select entry file or first file
+    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 callbacks
+    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);
+      }
+    });
+
+    runtime.setOutputCallback((line: string) => {
+      setState((prev) => ({
+        ...prev,
+        terminalOutput: [...prev.terminalOutput, line],
+      }));
+    });
+
+    runtime.setServerReadyCallback((port: number, url: string) => {
+      setState((prev) => ({
+        ...prev,
+        previewUrl: url,
+        status: "ready",
+      }));
+      onServerReady?.(port, url);
+    });
+
+    // Boot
+    runtime.boot().catch((err) => {
+      const msg = err instanceof Error ? err.message : String(err);
+      onError?.(msg);
+    });
+
+    // Cleanup on unmount
+    return () => {
+      runtime.teardown();
+      runtimeRef.current = null;
+    };
+  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // File change handler
+  const handleFileChange = useCallback(
+    async (path: string, content: string) => {
+      const runtime = runtimeRef.current;
+      if (!runtime) {
+        return;
+      }
+
+      // Write to Nodepod FS
+      try {
+        await runtime.writeFile(path, content);
+      } catch (err) {
+        console.error(`Failed to write file ${path}:`, err);
+      }
+
+      // Update state
+      setState((prev) => ({
+        ...prev,
+        files: { ...prev.files, [path]: content },
+      }));
+
+      onFileChange?.(path, content);
+    },
+    [onFileChange],
+  );
+
+  // Select a file
+  const handleSelectFile = useCallback((path: string) => {
+    setSelectedFile(path);
+    setOpenFiles((prev) => (prev.includes(path) ? prev : [...prev, path]));
+  }, []);
+
+  // Close a file tab
+  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],
+  );
+
+  // Restart the server
+  const restart = useCallback(async () => {
+    const runtime = runtimeRef.current;
+    if (!runtime) {
+      return;
+    }
+    await runtime.restart();
+  }, []);
+
+  // Get changed files for git operations
+  const getChangedFiles = useCallback((): FileMap => {
+    return runtimeRef.current?.getChangedFiles() ?? {};
+  }, []);
+
+  return {
+    state,
+    selectedFile,
+    openFiles,
+    handleFileChange,
+    handleSelectFile,
+    handleCloseFile,
+    restart,
+    getChangedFiles,
+    runtime: runtimeRef,
+  };
+}

package/src/index.ts

@@ -0,0 +1,48 @@
+/**
+ * @illuma-ai/code-sandbox — Public API
+ *
+ * This is the main entry point for the library.
+ * Consumers import from here.
+ */
+
+// 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";
+export { GitService } from "./services/git";
+
+// Hooks
+export { useRuntime } from "./hooks/useRuntime";
+
+// Templates
+export { getTemplate, listTemplates } from "./templates";
+
+// Types
+export type {
+  FileMap,
+  FileNode,
+  BootStage,
+  BootProgress,
+  RuntimeConfig,
+  RuntimeState,
+  GitHubRepo,
+  GitCommitRequest,
+  GitPRRequest,
+  GitPRResult,
+  CodeSandboxProps,
+  FileTreeProps,
+  CodeEditorProps,
+  TerminalProps,
+  PreviewProps,
+  BootOverlayProps,
+} from "./types";