@illuma-ai/code-sandbox 1.0.0

package/dist/services/git.d.ts

@@ -0,0 +1,57 @@
+/**
+ * GitService — GitHub API integration for loading and saving project files.
+ *
+ * Flow:
+ * - Clone: GET repo tree → GET file contents → return FileMap
+ * - Commit: POST branch → PUT files → POST PR
+ *
+ * All operations use the GitHub REST API (no git CLI needed).
+ * Works entirely in the browser — no server required.
+ */
+import type { FileMap, GitCommitRequest, GitHubRepo, GitPRRequest, GitPRResult } from "../types";
+/**
+ * GitHub API service for cloning repos and creating PRs.
+ *
+ * @example
+ * ```ts
+ * const git = new GitService('ghp_xxxxx');
+ * const files = await git.cloneRepo({ owner: 'user', repo: 'my-app' });
+ * // ... user edits files ...
+ * const pr = await git.createPR({
+ *   owner: 'user', repo: 'my-app',
+ *   branch: 'sandbox/changes', changes: editedFiles,
+ *   message: 'Update from sandbox', title: 'Sandbox changes',
+ * });
+ * ```
+ */
+export declare class GitService {
+    private token;
+    constructor(token: string);
+    /**
+     * Clone a GitHub repository into a flat file map.
+     *
+     * Uses the Git Trees API for a single request to get the full file listing,
+     * then fetches text file contents in parallel batches.
+     *
+     * @param repo - GitHub repository coordinates
+     * @param onProgress - Optional progress callback (0-100)
+     * @returns FileMap of path → content
+     */
+    cloneRepo(repo: GitHubRepo, onProgress?: (percent: number, message: string) => void): Promise<FileMap>;
+    /**
+     * Create a new branch with file changes and open a pull request.
+     *
+     * Steps:
+     * 1. Get the base branch's HEAD SHA
+     * 2. Create a new branch from that SHA
+     * 3. For each changed file, update its contents on the new branch
+     * 4. Create a pull request
+     */
+    createPR(request: GitPRRequest): Promise<GitPRResult>;
+    /**
+     * Commit changes without creating a PR.
+     */
+    commit(request: GitCommitRequest): Promise<string>;
+    /** Fetch with auth headers */
+    private fetch;
+}

package/dist/services/runtime.d.ts

@@ -0,0 +1,119 @@
+/**
+ * NodepodRuntime — Manages the full lifecycle of a Nodepod sandbox.
+ *
+ * Flow: boot → write files → npm install → run entry command → track changes
+ *
+ * This is the core service that bridges project files and the browser runtime.
+ * It is framework-agnostic (no React) — consumed by the useRuntime hook.
+ */
+import { Nodepod } from "@illuma-ai/nodepod";
+import type { BootProgress, BootStage, FileMap, RuntimeConfig } from "../types";
+/** Callback type for progress updates */
+type ProgressCallback = (progress: BootProgress) => void;
+/** Callback type for terminal output lines */
+type OutputCallback = (line: string) => void;
+/** Callback type for server ready */
+type ServerReadyCallback = (port: number, url: string) => void;
+/**
+ * Manages the Nodepod runtime lifecycle.
+ *
+ * Responsibilities:
+ * - Boot Nodepod with COOP/COEP-compatible service worker
+ * - Write project files into the virtual filesystem
+ * - Install npm dependencies from package.json
+ * - Start the entry command (e.g., "node server.js")
+ * - Track file modifications for git diffing
+ * - Provide preview URL for the iframe
+ */
+export declare class NodepodRuntime {
+    private nodepod;
+    private serverProcess;
+    private config;
+    private originalFiles;
+    private currentFiles;
+    private terminalOutput;
+    private status;
+    private error;
+    private previewUrl;
+    private onProgress;
+    private onOutput;
+    private onServerReady;
+    constructor(config: RuntimeConfig);
+    /** Register a progress callback */
+    setProgressCallback(cb: ProgressCallback): void;
+    /** Register a terminal output callback */
+    setOutputCallback(cb: OutputCallback): void;
+    /** Register a server ready callback */
+    setServerReadyCallback(cb: ServerReadyCallback): void;
+    /** Get the current preview URL (null if server not ready) */
+    getPreviewUrl(): string | null;
+    /** Get current status */
+    getStatus(): BootStage;
+    /** Get all terminal output */
+    getTerminalOutput(): string[];
+    /** Get current files (with edits applied) */
+    getCurrentFiles(): FileMap;
+    /** Get the original files (as loaded, before any edits) */
+    getOriginalFiles(): FileMap;
+    /** Get only the files that have been modified since loading */
+    getChangedFiles(): FileMap;
+    /** Get the error message if status is 'error' */
+    getError(): string | null;
+    /**
+     * Boot the runtime: initialize Nodepod → write files → install → start server.
+     *
+     * This is the main entry point. Call this once.
+     * The progress callback will fire at each stage.
+     */
+    boot(): Promise<void>;
+    /**
+     * Write a single file to the virtual filesystem.
+     * Used for editor changes after boot.
+     */
+    writeFile(path: string, content: string): Promise<void>;
+    /**
+     * Read a file from the virtual filesystem.
+     */
+    readFile(path: string): Promise<string>;
+    /**
+     * Restart the server process.
+     * Kills the current process and re-runs the entry command.
+     */
+    restart(): Promise<void>;
+    /**
+     * Tear down the runtime.
+     * Kills all processes and releases resources.
+     */
+    teardown(): void;
+    /** Get raw Nodepod instance for advanced usage */
+    getNodepod(): Nodepod | null;
+    /**
+     * Rewrite a Nodepod virtual server URL to use /__preview__/ instead of /__virtual__/.
+     *
+     * WHY: Nodepod's serverUrl() returns /__virtual__/{port} URLs, but the
+     * Service Worker only tracks iframe client IDs for /__preview__/{port}
+     * navigations. Without client tracking, subresource requests (JS, CSS,
+     * API calls) from the preview iframe are NOT intercepted by the SW —
+     * they fall through to the real dev server and 404.
+     */
+    private rewritePreviewUrl;
+    /** Resolve a relative path against the workdir */
+    private resolvePath;
+    /** Write all project files to the virtual filesystem */
+    private writeFiles;
+    /**
+     * Install npm dependencies by spawning `npm install` in Nodepod.
+     *
+     * Nodepod's DependencyInstaller handles this internally via its
+     * package registry. We spawn `node -e` with a require to trigger it,
+     * or use the built-in npm install mechanism.
+     */
+    private installDependencies;
+    /** Start the entry command (e.g., "node server.js") */
+    private startServer;
+    /** Emit a progress update */
+    private emitProgress;
+    /** Append a line to terminal output */
+    private appendOutput;
+}
+export {};

package/dist/templates/fullstack-starter.d.ts

@@ -0,0 +1,38 @@
+/**
+ * fullstack-starter — Production-equivalent full-stack starter template.
+ *
+ * A properly structured Express + React application with:
+ * - sql.js (SQLite WASM) as a true relational DB — same schemas work on Postgres
+ * - React Router v6 for client-side routing
+ * - React Context for auth + app state management
+ * - JWT authentication with role-based access
+ * - .ranger manifest for AI agent context
+ *
+ * Architecture:
+ * ┌─────────────────────────────────────────────────────┐
+ * │  server.js              — Entry, middleware chain    │
+ * │  config.js              — Environment / .env config  │
+ * │  db/database.js         — sql.js init + migrations   │
+ * │  db/migrations/001.js   — Schema definitions (typed) │
+ * │  db/repositories/       — CRUD repos over SQL        │
+ * │  middleware/             — Auth, errors, static       │
+ * │  routes/                — Express route definitions   │
+ * │  public/                — React SPA (CDN-loaded)      │
+ * │  public/store/          — React Context providers     │
+ * │  public/pages/          — Route-level components      │
+ * │  public/components/     — Reusable UI components      │
+ * │  .ranger                — AI agent instruction file   │
+ * │  .env.example           — Env var documentation       │
+ * └─────────────────────────────────────────────────────┘
+ *
+ * DATABASE:
+ * Uses sql.js (SQLite compiled to WASM) — runs in the browser.
+ * Schemas use standard SQL types (INTEGER, TEXT, REAL, BOOLEAN, TIMESTAMP).
+ * To migrate to Postgres: change db/database.js to use 'pg', keep same schemas.
+ * The repository layer abstracts all SQL — swap the query runner, not the repos.
+ */
+export declare const fullstackStarterTemplate: {
+    entryCommand: string;
+    port: number;
+    files: Record<string, string>;
+};

package/dist/templates/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Template registry — built-in project templates.
+ *
+ * The "express-react" template is a proper full-stack app:
+ * - Express backend with API routes that proxy JSONPlaceholder
+ * - React frontend as separate component files under public/
+ * - Express serves static files via fs.readFileSync (Nodepod doesn't support
+ *   res.sendFile or express.static)
+ * - React + Tailwind loaded from CDN — no build step needed
+ *
+ * WHY THIS ARCHITECTURE:
+ * Nodepod can't run Vite/Next.js/Webpack. But Express works perfectly.
+ * By loading React/Tailwind from CDN and splitting the React app into
+ * separate script files, we get a realistic full-stack project structure
+ * that users can explore and edit in the code sandbox.
+ */
+import type { FileMap } from "../types";
+/**
+ * Template registry — maps template names to file maps.
+ */
+export declare const templates: Record<string, {
+    files: FileMap;
+    entryCommand: string;
+    port: number;
+}>;
+/**
+ * Get a project template by name.
+ *
+ * @param name - Template name (e.g., 'express-react')
+ * @returns Template config or null if not found
+ */
+export declare function getTemplate(name: string): {
+    files: FileMap;
+    entryCommand: string;
+    port: number;
+} | null;
+/** List available template names */
+export declare function listTemplates(): string[];

package/dist/types.d.ts

@@ -0,0 +1,137 @@
+/**
+ * @illuma-ai/code-sandbox — Type definitions
+ *
+ * Core types for the browser-native code sandbox.
+ * Covers file maps, runtime states, git operations, and component props.
+ */
+/** 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[];
+}
+/** Boot stages shown during the loading animation */
+export type BootStage = "initializing" | "writing-files" | "installing" | "starting" | "ready" | "error";
+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;
+    /** Error message if status is 'error' */
+    error: string | null;
+}
+export interface GitHubRepo {
+    owner: string;
+    repo: string;
+    branch?: string;
+    path?: string;
+}
+export interface GitCommitRequest {
+    owner: string;
+    repo: string;
+    /** Branch to create for the commit */
+    branch: string;
+    /** Base branch to fork from (default: 'main') */
+    baseBranch?: string;
+    /** Map of file paths to new contents (only changed files) */
+    changes: FileMap;
+    /** Commit message */
+    message: string;
+}
+export interface GitPRRequest extends GitCommitRequest {
+    /** PR title */
+    title: string;
+    /** PR body/description */
+    body?: string;
+}
+export interface GitPRResult {
+    number: number;
+    url: string;
+    branch: string;
+}
+export interface CodeSandboxProps {
+    /** Pass files directly */
+    files?: FileMap;
+    /** OR load from GitHub */
+    github?: GitHubRepo;
+    /** GitHub personal access token (for private repos and write-back) */
+    gitToken?: string;
+    /** 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>;
+    /** Fires when a file is modified in the editor */
+    onFileChange?: (path: string, content: string) => void;
+    /** Fires when the dev server is ready */
+    onServerReady?: (port: number, url: string) => void;
+    /** Fires on boot progress changes */
+    onProgress?: (progress: BootProgress) => void;
+    /** Fires on errors */
+    onError?: (error: string) => void;
+    /** 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;
+    onCreateFile?: (path: string) => void;
+    onCreateFolder?: (path: string) => void;
+    onDeleteFile?: (path: string) => void;
+    onRenameFile?: (oldPath: string, newPath: string) => void;
+}
+export interface CodeEditorProps {
+    files: FileMap;
+    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;
+}
+export interface PreviewProps {
+    url: string | null;
+    className?: string;
+    onRefresh?: () => void;
+}
+export interface BootOverlayProps {
+    progress: BootProgress;
+    className?: string;
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@illuma-ai/code-sandbox",
+  "version": "1.0.0",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "Illuma AI (https://github.com/illuma-ai)",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/illuma-ai/code-sandbox.git"
+  },
+  "description": "Browser-native code sandbox with file tree, editor, terminal, and live preview powered by Nodepod",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./styles.css": "./dist/styles.css"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build && tsc --emitDeclarationOnly",
+    "preview": "vite preview",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest"
+  },
+  "dependencies": {
+    "@illuma-ai/nodepod": "^1.0.1",
+    "allotment": "^1.20.2",
+    "framer-motion": "^12.35.2"
+  },
+  "peerDependencies": {
+    "@monaco-editor/react": "^4.6.0",
+    "@xterm/addon-fit": "^0.11.0",
+    "@xterm/xterm": "^5.5.0 || ^6.0.0",
+    "lucide-react": ">=0.300.0",
+    "monaco-editor": ">=0.40.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@monaco-editor/react": "^4.7.0",
+    "@types/react": "^18.2.11",
+    "@types/react-dom": "^18.2.4",
+    "@vitejs/plugin-react": "^4.3.4",
+    "@xterm/addon-fit": "^0.11.0",
+    "@xterm/xterm": "^5.5.0",
+    "autoprefixer": "^10.4.20",
+    "lucide-react": "^0.575.0",
+    "monaco-editor": "^0.55.1",
+    "postcss": "^8.4.31",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "tailwindcss": "^3.4.1",
+    "typescript": "^5.3.3",
+    "vite": "^6.4.1",
+    "vitest": "^3.2.1"
+  }
+}

package/src/components/BootOverlay.tsx

@@ -0,0 +1,145 @@
+/**
+ * BootOverlay — Loading animation displayed while Nodepod boots.
+ *
+ * Shows staged progress: initializing → writing files → installing → starting → ready.
+ * Includes a progress bar and stage-specific messaging with a pulsing animation.
+ */
+
+import React from "react";
+import type { BootOverlayProps } from "../types";
+
+/** Stage display configuration */
+const STAGE_CONFIG: Record<
+  string,
+  { icon: string; label: string; color: string }
+> = {
+  initializing: {
+    icon: "⚡",
+    label: "Initializing Runtime",
+    color: "text-blue-400",
+  },
+  "writing-files": {
+    icon: "📁",
+    label: "Writing Project Files",
+    color: "text-yellow-400",
+  },
+  installing: {
+    icon: "📦",
+    label: "Installing Dependencies",
+    color: "text-purple-400",
+  },
+  starting: {
+    icon: "🚀",
+    label: "Starting Application",
+    color: "text-green-400",
+  },
+  ready: { icon: "✅", label: "Application Ready", color: "text-green-400" },
+  error: { icon: "❌", label: "Error", color: "text-red-400" },
+};
+
+/**
+ * Full-screen loading overlay with staged boot progress.
+ *
+ * Renders over the workbench while Nodepod boots. Shows:
+ * - Current stage icon + label
+ * - Progress bar with percentage
+ * - Descriptive message of what's happening
+ * - Pulsing dots animation
+ */
+export function BootOverlay({ progress, className = "" }: BootOverlayProps) {
+  const config = STAGE_CONFIG[progress.stage] || STAGE_CONFIG.initializing;
+
+  if (progress.stage === "ready") {
+    return null;
+  }
+
+  return (
+    <div
+      className={`absolute inset-0 z-50 flex items-center justify-center bg-sb-bg/95 backdrop-blur-sm ${className}`}
+    >
+      <div className="flex flex-col items-center gap-6 max-w-md px-8">
+        {/* Animated icon */}
+        <div className="text-5xl animate-bounce">{config.icon}</div>
+
+        {/* Stage label */}
+        <h2 className={`text-xl font-semibold ${config.color}`}>
+          {config.label}
+          {progress.stage !== "error" && <PulsingDots />}
+        </h2>
+
+        {/* Progress bar */}
+        <div className="w-64 h-2 bg-sb-bg-active rounded-full overflow-hidden">
+          <div
+            className="h-full bg-sb-accent rounded-full transition-all duration-500 ease-out"
+            style={{ width: `${progress.percent}%` }}
+          />
+        </div>
+
+        {/* Message */}
+        <p className="text-sm text-sb-text-muted text-center">
+          {progress.message}
+        </p>
+
+        {/* Stage indicators */}
+        <div className="flex items-center gap-2 mt-4">
+          {["initializing", "writing-files", "installing", "starting"].map(
+            (stage, i) => {
+              const isCompleted = getStageOrder(progress.stage) > i;
+              const isCurrent = progress.stage === stage;
+
+              return (
+                <React.Fragment key={stage}>
+                  <div
+                    className={`w-3 h-3 rounded-full transition-colors duration-300 ${
+                      isCompleted
+                        ? "bg-sb-success"
+                        : isCurrent
+                          ? "bg-sb-accent animate-pulse"
+                          : "bg-sb-bg-active"
+                    }`}
+                  />
+                  {i < 3 && (
+                    <div
+                      className={`w-8 h-0.5 transition-colors duration-300 ${
+                        isCompleted ? "bg-sb-success" : "bg-sb-bg-active"
+                      }`}
+                    />
+                  )}
+                </React.Fragment>
+              );
+            },
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+/** Get numeric order of a boot stage for progress indicators */
+function getStageOrder(stage: string): number {
+  const order = [
+    "initializing",
+    "writing-files",
+    "installing",
+    "starting",
+    "ready",
+  ];
+  return order.indexOf(stage);
+}
+
+/** Animated "..." dots */
+function PulsingDots() {
+  return (
+    <span className="inline-flex ml-1">
+      <span className="animate-pulse" style={{ animationDelay: "0ms" }}>
+        .
+      </span>
+      <span className="animate-pulse" style={{ animationDelay: "200ms" }}>
+        .
+      </span>
+      <span className="animate-pulse" style={{ animationDelay: "400ms" }}>
+        .
+      </span>
+    </span>
+  );
+}