@illuma-ai/code-sandbox 1.4.0 → 1.5.0

package/src/types.ts

@@ -1,375 +0,0 @@
-/**
- * @illuma-ai/code-sandbox — Type definitions
- *
- * Core types for the browser-native code sandbox.
- * Covers file maps, runtime states, imperative handle, and component props.
- */
-
-// ---------------------------------------------------------------------------
-// File System
-// ---------------------------------------------------------------------------
-
-/** A flat map of file paths to their string contents */
-export type FileMap = Record<string, string>;
-
-/** Represents a single file or directory node in the tree */
-export interface FileNode {
-  name: string;
-  path: string;
-  type: "file" | "directory";
-  children?: FileNode[];
-}
-
-/**
- * Change status for a file relative to the baseline (original) snapshot.
- *
- * - `new`: File exists in current but not in original
- * - `modified`: File exists in both but content differs
- * - `deleted`: File exists in original but not in current
- * - `unchanged`: File content is identical
- */
-export type FileChangeStatus = "new" | "modified" | "deleted" | "unchanged";
-
-// ---------------------------------------------------------------------------
-// Errors (structured error types for AI agent consumption)
-// ---------------------------------------------------------------------------
-
-/**
- * Categories of errors that can occur in the sandbox.
- *
- * - `process-stderr`: Output written to stderr by the Node.js process
- * - `process-exit`: Process exited with a non-zero code
- * - `runtime-exception`: Uncaught exception in the Node.js runtime (Nodepod)
- * - `browser-error`: JavaScript error in the preview iframe (window.onerror)
- * - `browser-unhandled-rejection`: Unhandled promise rejection in the iframe
- * - `browser-console-error`: console.error() calls in the iframe
- * - `compilation`: Syntax/import errors detected at module load time
- * - `network`: Failed HTTP requests from the preview (fetch/XHR errors)
- * - `boot`: Error during Nodepod boot, file writing, or dependency install
- */
-export type SandboxErrorCategory =
-  | "process-stderr"
-  | "process-exit"
-  | "runtime-exception"
-  | "browser-error"
-  | "browser-unhandled-rejection"
-  | "browser-console-error"
-  | "compilation"
-  | "network"
-  | "boot";
-
-/**
- * A structured error emitted by the sandbox.
- *
- * Designed for AI agent consumption — includes enough context for the
- * agent to construct a targeted fix prompt (file path, line number,
- * surrounding code, stack trace).
- *
- * @see Ranger's auto-fix: client/src/components/Artifacts/Artifacts.tsx
- */
-export interface SandboxError {
-  /** Unique ID for deduplication */
-  id: string;
-  /** Error category — determines how the agent should interpret it */
-  category: SandboxErrorCategory;
-  /** Human-readable error message (the "what") */
-  message: string;
-  /** Full stack trace if available */
-  stack?: string;
-  /** File path where the error occurred (relative to workdir) */
-  filePath?: string;
-  /** Line number in the file (1-indexed) */
-  line?: number;
-  /** Column number in the file (1-indexed) */
-  column?: number;
-  /** ISO 8601 timestamp */
-  timestamp: string;
-  /**
-   * Surrounding source code lines for context.
-   * Format: "lineNum: content" per line (e.g., "42: const x = foo();")
-   * Typically ~10 lines centered on the error line.
-   */
-  sourceContext?: string;
-}
-
-// ---------------------------------------------------------------------------
-// Runtime (Nodepod lifecycle)
-// ---------------------------------------------------------------------------
-
-/** Boot stages shown during the loading animation */
-export type BootStage =
-  | "initializing" // Nodepod.boot() in progress
-  | "writing-files" // Writing project files to virtual FS
-  | "installing" // npm install running
-  | "starting" // Entry command executing (e.g., node server.js)
-  | "ready" // Server is listening, preview iframe can load
-  | "error"; // Something failed
-
-export interface BootProgress {
-  stage: BootStage;
-  message: string;
-  /** 0-100 percent, approximate */
-  percent: number;
-}
-
-/** Configuration for the Nodepod runtime */
-export interface RuntimeConfig {
-  /** Project files to write into the virtual filesystem */
-  files: FileMap;
-  /** Command to start the dev server, e.g. "node server.js" */
-  entryCommand: string;
-  /** Working directory inside Nodepod (default: "/app") */
-  workdir?: string;
-  /** Environment variables passed to processes */
-  env?: Record<string, string>;
-  /** Port to watch for server readiness (default: 3000) */
-  port?: number;
-}
-
-/** State exposed by the runtime to UI components */
-export interface RuntimeState {
-  status: BootStage;
-  progress: BootProgress;
-  /** URL for the preview iframe once server is ready, e.g. "/__virtual__/3000/" */
-  previewUrl: string | null;
-  /** All terminal output lines (stdout + stderr) */
-  terminalOutput: string[];
-  /** Current files in the virtual FS (may differ from original after edits) */
-  files: FileMap;
-  /**
-   * Baseline file snapshot — the files as they were before the latest
-   * update (via updateFiles). Used by the diff viewer to show what changed.
-   * Empty on first load (everything is "new"), populated after the first
-   * file update.
-   */
-  originalFiles: FileMap;
-  /**
-   * Per-file change status relative to originalFiles.
-   *
-   * Only includes files that have a non-"unchanged" status.
-   * 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;
-  /**
-   * All structured errors collected during this session.
-   * New errors are appended — the array grows monotonically.
-   * Use `errors[errors.length - 1]` to get the latest.
-   */
-  errors: SandboxError[];
-}
-
-// ---------------------------------------------------------------------------
-// Imperative Handle
-// ---------------------------------------------------------------------------
-
-/**
- * Imperative handle exposed by CodeSandbox via React.forwardRef.
- *
- * This is the primary API for host applications (like Ranger) to
- * control the sandbox programmatically. The sandbox is a "dumb renderer"
- * — the host pushes files in and reads state out.
- *
- * @example
- * ```tsx
- * const ref = useRef<CodeSandboxHandle>(null);
- *
- * // Push files from any source
- * ref.current?.updateFiles(fileMap);
- *
- * // Push a single file (e.g., agent modified one file)
- * ref.current?.updateFile('server.js', newContent);
- *
- * // Read current state
- * const files = ref.current?.getFiles();
- * const changes = ref.current?.getChangedFiles();
- * const errors = ref.current?.getErrors();
- * ```
- */
-export interface CodeSandboxHandle {
-  /**
-   * Replace the entire file set. Diffs against current files, writes only
-   * changed files to Nodepod FS, and restarts the server if anything changed.
-   *
-   * The previous file set becomes `originalFiles` for diff tracking.
-   *
-   * @param files - Complete new file set
-   * @param options - Optional: restartServer (default true)
-   */
-  updateFiles: (
-    files: FileMap,
-    options?: { restartServer?: boolean },
-  ) => Promise<void>;
-
-  /**
-   * Update a single file. Writes to Nodepod FS and updates state.
-   * Does NOT restart the server — call `restart()` manually if needed,
-   * or use `updateFiles()` for bulk updates with auto-restart.
-   *
-   * @param path - File path (e.g., "server.js", "public/index.html")
-   * @param content - New file content
-   */
-  updateFile: (path: string, content: string) => Promise<void>;
-
-  /**
-   * Force restart the server process. Kills the current process
-   * and re-runs the entry command.
-   */
-  restart: () => Promise<void>;
-
-  /**
-   * Get the current file map (all files including edits).
-   */
-  getFiles: () => FileMap;
-
-  /**
-   * Get only files that have been modified relative to originalFiles.
-   * Returns a FileMap containing only the changed files.
-   */
-  getChangedFiles: () => FileMap;
-
-  /**
-   * Get the per-file change status map (new/modified/deleted).
-   * Missing keys should be treated as "unchanged".
-   */
-  getFileChanges: () => Record<string, FileChangeStatus>;
-
-  /**
-   * Get all structured errors collected during this session.
-   */
-  getErrors: () => SandboxError[];
-
-  /**
-   * Get the current runtime state snapshot.
-   */
-  getState: () => RuntimeState;
-}
-
-// ---------------------------------------------------------------------------
-// Component Props
-// ---------------------------------------------------------------------------
-
-/**
- * Props for the CodeSandbox component.
- *
- * The sandbox is a pure renderer — it receives files via props and
- * exposes an imperative handle for programmatic updates. It does NOT
- * interact with any storage backend directly.
- *
- * File sources (for initial load, pick ONE):
- * - `files` — pass a FileMap directly
- * - `template` — use a built-in template name (e.g., "fullstack-starter")
- *
- * For live updates after mount, use the imperative handle:
- * ```tsx
- * const ref = useRef<CodeSandboxHandle>(null);
- * <CodeSandbox ref={ref} files={initialFiles} />
- * // Later:
- * ref.current.updateFiles(newFiles);
- * ```
- */
-export interface CodeSandboxProps {
-  /** Pass files directly (from any source) */
-  files?: FileMap;
-  /** OR use a built-in template name */
-  template?: string;
-  /** Command to start the dev server (default inferred from package.json or template) */
-  entryCommand?: string;
-  /** Port the server listens on (default: 3000) */
-  port?: number;
-  /** Environment variables */
-  env?: Record<string, string>;
-
-  // Callbacks
-  /** Fires when a file is modified in the editor by the user */
-  onFileChange?: (path: string, content: string) => void;
-  /** Fires when the dev server is ready (initial boot or after restart) */
-  onServerReady?: (port: number, url: string) => void;
-  /** Fires on boot progress changes */
-  onProgress?: (progress: BootProgress) => void;
-  /** Fires on errors (legacy — simple string message) */
-  onError?: (error: string) => void;
-  /**
-   * Fires when a structured error is detected.
-   *
-   * This is the primary error channel for AI agent integration.
-   * Errors include file path, line number, source context, and category
-   * so the agent can construct a targeted fix prompt.
-   *
-   * Max 2 auto-fix attempts per error is recommended (see Ranger pattern).
-   */
-  onSandboxError?: (error: SandboxError) => void;
-  /**
-   * Fires after updateFiles() completes (files written + server restarted).
-   * Useful for the host to know when the sandbox has finished processing
-   * a file push.
-   */
-  onFilesUpdated?: (fileChanges: Record<string, FileChangeStatus>) => void;
-
-  // Layout
-  /** CSS class name for the root element */
-  className?: string;
-  /** Height of the sandbox (default: '100vh') */
-  height?: string;
-}
-
-export interface FileTreeProps {
-  files: FileNode[];
-  selectedFile: string | null;
-  onSelectFile: (path: string) => void;
-  /** Per-file change status for visual indicators (colored dots) */
-  fileChanges?: Record<string, FileChangeStatus>;
-  onCreateFile?: (path: string) => void;
-  onCreateFolder?: (path: string) => void;
-  onDeleteFile?: (path: string) => void;
-  onRenameFile?: (oldPath: string, newPath: string) => void;
-}
-
-export interface CodeEditorProps {
-  files: FileMap;
-  /** Baseline files for diff comparison (empty = no diff available) */
-  originalFiles: FileMap;
-  /** Per-file change status for tab indicators */
-  fileChanges: Record<string, FileChangeStatus>;
-  activeFile: string | null;
-  openFiles: string[];
-  onSelectFile: (path: string) => void;
-  onCloseFile: (path: string) => void;
-  onFileChange: (path: string, content: string) => void;
-  readOnly?: boolean;
-}
-
-export interface TerminalProps {
-  output: string[];
-  className?: string;
-  /** Whether the terminal is collapsed to just its header bar */
-  minimized?: boolean;
-  /** Called when the user clicks the minimize/expand toggle */
-  onToggleMinimize?: () => void;
-}
-
-export interface PreviewProps {
-  url: string | null;
-  className?: string;
-  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;
-  className?: string;
-}