@illuma-ai/code-sandbox 1.0.0 → 1.2.0

package/src/services/runtime.ts

@@ -9,7 +9,14 @@
 
 import { Nodepod } from "@illuma-ai/nodepod";
 import type { NodepodProcess } from "@illuma-ai/nodepod";
-import type { BootProgress, BootStage, FileMap, RuntimeConfig } from "../types";
+import type {
+  BootProgress,
+  BootStage,
+  FileMap,
+  RuntimeConfig,
+  SandboxError,
+  SandboxErrorCategory,
+} from "../types";
 
 /** Callback type for progress updates */
 type ProgressCallback = (progress: BootProgress) => void;
@@ -17,6 +24,8 @@ type ProgressCallback = (progress: BootProgress) => void;
 type OutputCallback = (line: string) => void;
 /** Callback type for server ready */
 type ServerReadyCallback = (port: number, url: string) => void;
+/** Callback type for structured errors */
+type ErrorCallback = (error: SandboxError) => void;
 
 /** Debug log prefix for easy filtering in DevTools console */
 const DBG = "[CodeSandbox:Runtime]";
@@ -42,11 +51,14 @@ export class NodepodRuntime {
   private status: BootStage = "initializing";
   private error: string | null = null;
   private previewUrl: string | null = null;
+  private errors: SandboxError[] = [];
+  private errorIdCounter = 0;
 
   // Callbacks
   private onProgress: ProgressCallback | null = null;
   private onOutput: OutputCallback | null = null;
   private onServerReady: ServerReadyCallback | null = null;
+  private onSandboxError: ErrorCallback | null = null;
 
   constructor(config: RuntimeConfig) {
     this.config = {
@@ -78,6 +90,11 @@ export class NodepodRuntime {
     this.onServerReady = cb;
   }
 
+  /** Register a structured error callback */
+  setErrorCallback(cb: ErrorCallback): void {
+    this.onSandboxError = cb;
+  }
+
   /** Get the current preview URL (null if server not ready) */
   getPreviewUrl(): string | null {
     return this.previewUrl;
@@ -119,6 +136,31 @@ export class NodepodRuntime {
     return this.error;
   }
 
+  /** Get all structured errors collected during this session */
+  getErrors(): SandboxError[] {
+    return [...this.errors];
+  }
+
+  /**
+   * Report an external error (e.g., from the preview iframe).
+   *
+   * This is the public entry point for errors that originate outside
+   * the runtime — browser console errors, unhandled rejections, etc.
+   * The runtime enriches them with source context from the virtual FS
+   * and emits them via the onSandboxError callback.
+   */
+  async reportError(error: SandboxError): Promise<void> {
+    // Enrich with source context if we have a file path and line number
+    if (error.filePath && error.line && !error.sourceContext) {
+      error.sourceContext = await this.getSourceContext(
+        error.filePath,
+        error.line,
+      );
+    }
+    this.errors.push(error);
+    this.onSandboxError?.(error);
+  }
+
   // -------------------------------------------------------------------------
   // Lifecycle
   // -------------------------------------------------------------------------
@@ -287,9 +329,11 @@ export class NodepodRuntime {
       }
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
+      const stack = err instanceof Error ? err.stack : undefined;
       console.error(DBG, "boot: FATAL ERROR:", err);
       this.error = message;
       this.emitProgress("error", `Error: ${message}`, 0);
+      this.emitError("boot", message, { stack });
       throw err;
     }
   }
@@ -506,6 +550,12 @@ export class NodepodRuntime {
 
     this.serverProcess.on("error", (chunk: string) => {
       this.appendOutput(`[stderr] ${chunk}`);
+      // Emit structured error for stderr output.
+      // Filter out noise: skip empty lines and common non-error warnings.
+      const trimmed = chunk.trim();
+      if (trimmed && !this.isStderrNoise(trimmed)) {
+        this.emitError("process-stderr", trimmed);
+      }
     });
 
     this.serverProcess.on("exit", (code: number) => {
@@ -513,6 +563,11 @@ export class NodepodRuntime {
       if (code !== 0 && this.status !== "ready") {
         this.error = `Process exited with code ${code}`;
         this.emitProgress("error", `Process exited with code ${code}`, 0);
+        // Emit structured error for non-zero exit
+        this.emitError("process-exit", `Process exited with code ${code}`, {
+          // Include last 20 lines of terminal output for context
+          stack: this.terminalOutput.slice(-20).join("\n"),
+        });
       }
     });
   }
@@ -533,4 +588,188 @@ export class NodepodRuntime {
     this.terminalOutput.push(line);
     this.onOutput?.(line);
   }
+
+  // -------------------------------------------------------------------------
+  // Error helpers
+  // -------------------------------------------------------------------------
+
+  /** Generate a unique error ID */
+  private nextErrorId(): string {
+    return `err_${++this.errorIdCounter}_${Date.now()}`;
+  }
+
+  /**
+   * Create and record a structured error from a process or boot event.
+   *
+   * Parses the error message to extract file path and line number when
+   * possible, then enriches with surrounding source context.
+   */
+  private async emitError(
+    category: SandboxErrorCategory,
+    message: string,
+    extra?: Partial<SandboxError>,
+  ): Promise<void> {
+    // Parse file/line from common Node.js error formats:
+    // - "/app/server.js:42"
+    // - "at Object.<anonymous> (/app/routes/api.js:15:8)"
+    // - "SyntaxError: /app/server.js: Unexpected token (12:5)"
+    let filePath = extra?.filePath;
+    let line = extra?.line;
+    let column = extra?.column;
+
+    if (!filePath) {
+      const parsed = this.parseErrorLocation(message + (extra?.stack ?? ""));
+      filePath = parsed.filePath;
+      line = parsed.line ?? line;
+      column = parsed.column ?? column;
+    }
+
+    let sourceContext = extra?.sourceContext;
+    if (filePath && line && !sourceContext) {
+      sourceContext = await this.getSourceContext(filePath, line);
+    }
+
+    const error: SandboxError = {
+      id: this.nextErrorId(),
+      category,
+      message,
+      timestamp: new Date().toISOString(),
+      ...extra,
+      filePath,
+      line,
+      column,
+      sourceContext,
+    };
+
+    this.errors.push(error);
+    this.onSandboxError?.(error);
+  }
+
+  /**
+   * Filter out common non-error stderr output.
+   *
+   * Many Node.js tools write informational messages to stderr
+   * (deprecation warnings, experimental feature notices, etc.).
+   * We don't want to flood the agent with these.
+   */
+  private isStderrNoise(text: string): boolean {
+    const noisePatterns = [
+      /^DeprecationWarning:/,
+      /^ExperimentalWarning:/,
+      /^\(node:\d+\) /,
+      /^npm WARN /,
+      /^warn /i,
+      /^Debugger listening/,
+      /^Debugger attached/,
+      /^Waiting for the debugger/,
+    ];
+    return noisePatterns.some((p) => p.test(text));
+  }
+
+  /**
+   * Parse file path and line/column from common error message formats.
+   *
+   * Handles:
+   * - Node.js stack frames: "at func (/app/file.js:12:5)"
+   * - Direct references: "/app/file.js:12:5"
+   * - SyntaxError: "/app/file.js: Unexpected token (12:5)"
+   */
+  private parseErrorLocation(text: string): {
+    filePath?: string;
+    line?: number;
+    column?: number;
+  } {
+    const workdir = this.config.workdir ?? "/app";
+
+    // Pattern 1: "at ... (/app/path/file.js:LINE:COL)"
+    const stackMatch = text.match(/\(?(\/[^:)]+):(\d+):(\d+)\)?/);
+    if (stackMatch) {
+      const absPath = stackMatch[1];
+      const relativePath = absPath.startsWith(workdir + "/")
+        ? absPath.slice(workdir.length + 1)
+        : absPath;
+      return {
+        filePath: relativePath,
+        line: parseInt(stackMatch[2], 10),
+        column: parseInt(stackMatch[3], 10),
+      };
+    }
+
+    // Pattern 2: "file.js:LINE" (no column)
+    const simpleMatch = text.match(/\(?(\/[^:)]+):(\d+)\)?/);
+    if (simpleMatch) {
+      const absPath = simpleMatch[1];
+      const relativePath = absPath.startsWith(workdir + "/")
+        ? absPath.slice(workdir.length + 1)
+        : absPath;
+      return {
+        filePath: relativePath,
+        line: parseInt(simpleMatch[2], 10),
+      };
+    }
+
+    // Pattern 3: "Unexpected token (LINE:COL)" with a file path earlier
+    const syntaxMatch = text.match(/(\/[^\s:]+)\s*:\s*[^(]*\((\d+):(\d+)\)/);
+    if (syntaxMatch) {
+      const absPath = syntaxMatch[1];
+      const relativePath = absPath.startsWith(workdir + "/")
+        ? absPath.slice(workdir.length + 1)
+        : absPath;
+      return {
+        filePath: relativePath,
+        line: parseInt(syntaxMatch[2], 10),
+        column: parseInt(syntaxMatch[3], 10),
+      };
+    }
+
+    return {};
+  }
+
+  /**
+   * Get surrounding source code lines from the virtual filesystem.
+   *
+   * Returns ~10 lines centered on the target line, formatted as
+   * "lineNum: content" for each line. This gives the AI agent enough
+   * context to construct a surgical fix.
+   */
+  private async getSourceContext(
+    filePath: string,
+    targetLine: number,
+    windowSize = 5,
+  ): Promise<string | undefined> {
+    try {
+      const content = this.currentFiles[filePath];
+      if (!content) {
+        // Try reading from the FS directly (file might have been written
+        // outside of our tracking, e.g., by npm install)
+        if (!this.nodepod) return undefined;
+        const fullPath = this.resolvePath(filePath);
+        const exists = await this.nodepod.fs.exists(fullPath);
+        if (!exists) return undefined;
+        const fsContent = await this.nodepod.fs.readFile(fullPath, "utf-8");
+        return this.formatSourceContext(fsContent, targetLine, windowSize);
+      }
+      return this.formatSourceContext(content, targetLine, windowSize);
+    } catch {
+      return undefined;
+    }
+  }
+
+  /**
+   * Format source code lines centered on a target line.
+   * Output: "lineNum: content\n" for each line in the window.
+   */
+  private formatSourceContext(
+    content: string,
+    targetLine: number,
+    windowSize: number,
+  ): string {
+    const lines = content.split("\n");
+    const start = Math.max(0, targetLine - windowSize - 1);
+    const end = Math.min(lines.length, targetLine + windowSize);
+    return lines
+      .slice(start, end)
+      .map((l, i) => `${start + i + 1}: ${l}`)
+      .join("\n");
+  }
 }

package/src/styles.css

@@ -22,3 +22,99 @@
   --sb-warning: #cca700;
   --sb-error: #f44747;
 }
+
+/*
+ * Ranger Theme Variables — bridged from ranger/client/src/style.css.
+ *
+ * These are injected into the sandbox shell so consumers can apply Ranger's
+ * design tokens to both the sandbox chrome and the preview iframe's content.
+ * HSL values are stored WITHOUT the hsl() wrapper (e.g. "12 76% 61%")
+ * and consumed as: color: hsl(var(--chart-1));
+ *
+ * Light mode (default) and dark mode (.dark) variants are provided.
+ */
+
+/* --- Light mode --------------------------------------------------------- */
+:root {
+  /* Ranger text */
+  --text-primary: #1a1a1a;
+  --text-secondary: #565869;
+  --text-tertiary: #8e8ea0;
+
+  /* Ranger surfaces */
+  --surface-primary: #ffffff;
+  --surface-secondary: #f9fafb;
+  --surface-tertiary: #f3f4f6;
+
+  /* Ranger borders */
+  --border-light: #e5e7eb;
+  --border-medium: #d1d5db;
+  --border-heavy: #9ca3af;
+
+  /* shadcn / chart HSL tokens (light) */
+  --background: 0 0% 100%;
+  --foreground: 0 0% 3.9%;
+  --card: 0 0% 100%;
+  --card-foreground: 0 0% 3.9%;
+  --primary: 0 0% 9%;
+  --primary-foreground: 0 0% 98%;
+  --secondary: 0 0% 96.1%;
+  --secondary-foreground: 0 0% 9%;
+  --muted: 0 0% 96.1%;
+  --muted-foreground: 0 0% 45.1%;
+  --accent: 0 0% 96.1%;
+  --accent-foreground: 0 0% 9%;
+  --destructive: 0 84.2% 60.2%;
+  --destructive-foreground: 0 0% 98%;
+  --border: 0 0% 89.8%;
+  --input: 0 0% 89.8%;
+  --ring: 0 0% 3.9%;
+  --radius: 0.5rem;
+  --chart-1: 12 76% 61%;
+  --chart-2: 173 58% 39%;
+  --chart-3: 197 37% 24%;
+  --chart-4: 43 74% 66%;
+  --chart-5: 27 87% 67%;
+}
+
+/* --- Dark mode ---------------------------------------------------------- */
+.dark {
+  /* Ranger text */
+  --text-primary: #f3f4f6;
+  --text-secondary: #d1d5db;
+  --text-tertiary: #6b7280;
+
+  /* Ranger surfaces */
+  --surface-primary: #111827;
+  --surface-secondary: #1f2937;
+  --surface-tertiary: #374151;
+
+  /* Ranger borders */
+  --border-light: #3a3a3b;
+  --border-medium: #4b5563;
+  --border-heavy: #6b7280;
+
+  /* shadcn / chart HSL tokens (dark) */
+  --background: 0 0% 7%;
+  --foreground: 0 0% 98%;
+  --card: 0 0% 3.9%;
+  --card-foreground: 0 0% 98%;
+  --primary: 0 0% 98%;
+  --primary-foreground: 0 0% 9%;
+  --secondary: 0 0% 14.9%;
+  --secondary-foreground: 0 0% 98%;
+  --muted: 0 0% 14.9%;
+  --muted-foreground: 0 0% 63.9%;
+  --accent: 0 0% 14.9%;
+  --accent-foreground: 0 0% 98%;
+  --destructive: 0 62.8% 40.6%;
+  --destructive-foreground: 0 0% 98%;
+  --border: 0 0% 14.9%;
+  --input: 0 0% 14.9%;
+  --ring: 0 0% 83.1%;
+  --chart-1: 220 70% 50%;
+  --chart-2: 160 60% 45%;
+  --chart-3: 30 80% 55%;
+  --chart-4: 280 65% 60%;
+  --chart-5: 340 75% 55%;
+}

package/src/templates/fullstack-starter.ts

@@ -1400,6 +1400,7 @@ const INDEX_HTML = `<!DOCTYPE html>
   <script src="https://unpkg.com/@remix-run/router@1.21.0/dist/router.umd.min.js"><\/script>
   <script src="https://unpkg.com/react-router@6.28.0/dist/umd/react-router.production.min.js"><\/script>
   <script src="https://unpkg.com/react-router-dom@6.28.0/dist/umd/react-router-dom.production.min.js"><\/script>
+  <script src="https://unpkg.com/chart.js@4.4.0/dist/chart.umd.js"><\/script>
   <link rel="stylesheet" href="/styles.css">
 </head>
 <body class="bg-gray-50 min-h-screen antialiased">
@@ -1417,6 +1418,7 @@ const INDEX_HTML = `<!DOCTYPE html>
   <script src="/components/Navbar.js"><\/script>
   <script src="/components/ItemCard.js"><\/script>
   <script src="/components/ItemForm.js"><\/script>
+  <script src="/components/StatsChart.js"><\/script>
 
   <!-- Pages -->
   <script src="/pages/WelcomePage.js"><\/script>
@@ -1433,7 +1435,84 @@ const INDEX_HTML = `<!DOCTYPE html>
 // public/styles.css
 // ---------------------------------------------------------------------------
 
-const STYLES_CSS = `.fade-in {
+const STYLES_CSS = `/*
+ * Ranger Theme Variables — chart colors and design tokens.
+ * HSL values stored WITHOUT hsl() wrapper; consume as: color: hsl(var(--chart-1));
+ */
+
+/* --- Light mode (default) ----------------------------------------------- */
+:root {
+  --text-primary: #1a1a1a;
+  --text-secondary: #565869;
+  --text-tertiary: #8e8ea0;
+  --surface-primary: #ffffff;
+  --surface-secondary: #f9fafb;
+  --surface-tertiary: #f3f4f6;
+  --border-light: #e5e7eb;
+  --border-medium: #d1d5db;
+  --border-heavy: #9ca3af;
+  --background: 0 0% 100%;
+  --foreground: 0 0% 3.9%;
+  --card: 0 0% 100%;
+  --card-foreground: 0 0% 3.9%;
+  --primary: 0 0% 9%;
+  --primary-foreground: 0 0% 98%;
+  --secondary: 0 0% 96.1%;
+  --secondary-foreground: 0 0% 9%;
+  --muted: 0 0% 96.1%;
+  --muted-foreground: 0 0% 45.1%;
+  --accent: 0 0% 96.1%;
+  --accent-foreground: 0 0% 9%;
+  --destructive: 0 84.2% 60.2%;
+  --destructive-foreground: 0 0% 98%;
+  --border: 0 0% 89.8%;
+  --input: 0 0% 89.8%;
+  --ring: 0 0% 3.9%;
+  --radius: 0.5rem;
+  --chart-1: 12 76% 61%;
+  --chart-2: 173 58% 39%;
+  --chart-3: 197 37% 24%;
+  --chart-4: 43 74% 66%;
+  --chart-5: 27 87% 67%;
+}
+
+/* --- Dark mode ---------------------------------------------------------- */
+.dark {
+  --text-primary: #f3f4f6;
+  --text-secondary: #d1d5db;
+  --text-tertiary: #6b7280;
+  --surface-primary: #111827;
+  --surface-secondary: #1f2937;
+  --surface-tertiary: #374151;
+  --border-light: #3a3a3b;
+  --border-medium: #4b5563;
+  --border-heavy: #6b7280;
+  --background: 0 0% 7%;
+  --foreground: 0 0% 98%;
+  --card: 0 0% 3.9%;
+  --card-foreground: 0 0% 98%;
+  --primary: 0 0% 98%;
+  --primary-foreground: 0 0% 9%;
+  --secondary: 0 0% 14.9%;
+  --secondary-foreground: 0 0% 98%;
+  --muted: 0 0% 14.9%;
+  --muted-foreground: 0 0% 63.9%;
+  --accent: 0 0% 14.9%;
+  --accent-foreground: 0 0% 98%;
+  --destructive: 0 62.8% 40.6%;
+  --destructive-foreground: 0 0% 98%;
+  --border: 0 0% 14.9%;
+  --input: 0 0% 14.9%;
+  --ring: 0 0% 83.1%;
+  --chart-1: 220 70% 50%;
+  --chart-2: 160 60% 45%;
+  --chart-3: 30 80% 55%;
+  --chart-4: 280 65% 60%;
+  --chart-5: 340 75% 55%;
+}
+
+/* --- Animations --------------------------------------------------------- */
+.fade-in {
   animation: fadeIn 0.3s ease-out;
 }
 @keyframes fadeIn {
@@ -2431,6 +2510,131 @@ window.RegisterPage = function RegisterPage() {
 };
 `;
 
+// ---------------------------------------------------------------------------
+// public/components/StatsChart.js
+// ---------------------------------------------------------------------------
+
+const STATS_CHART_JS = `var h = React.createElement;
+
+/**
+ * StatsChart — Renders a doughnut chart of item status distribution
+ * using Chart.js with Ranger theme CSS variables (--chart-1 through --chart-5).
+ *
+ * Props:
+ *   stats  — { total, byStatus: { todo, in_progress, done }, byPriority: { low, medium, high } }
+ *
+ * Uses the global Chart class from chart.js UMD CDN.
+ */
+window.StatsChart = function StatsChart(props) {
+  var stats = props.stats || { total: 0, byStatus: {}, byPriority: {} };
+  var canvasRef = React.useRef(null);
+  var chartRef = React.useRef(null);
+
+  /**
+   * Read a CSS custom property value from :root and convert to usable color.
+   * Ranger stores HSL values without the hsl() wrapper (e.g. "12 76% 61%"),
+   * so we wrap them: hsl(12 76% 61%).
+   */
+  function getChartColor(varName, fallback) {
+    var raw = getComputedStyle(document.documentElement)
+      .getPropertyValue(varName)
+      .trim();
+    if (!raw) return fallback;
+    if (raw.startsWith('#') || raw.startsWith('rgb') || raw.startsWith('hsl(')) {
+      return raw;
+    }
+    return 'hsl(' + raw + ')';
+  }
+
+  React.useEffect(function () {
+    if (!canvasRef.current) return;
+
+    if (chartRef.current) {
+      chartRef.current.destroy();
+      chartRef.current = null;
+    }
+
+    var todo = (stats.byStatus && stats.byStatus.todo) || 0;
+    var inProgress = (stats.byStatus && stats.byStatus.in_progress) || 0;
+    var done = (stats.byStatus && stats.byStatus.done) || 0;
+
+    if (todo + inProgress + done === 0) return;
+
+    var colors = [
+      getChartColor('--chart-1', 'hsl(12 76% 61%)'),
+      getChartColor('--chart-2', 'hsl(173 58% 39%)'),
+      getChartColor('--chart-3', 'hsl(197 37% 24%)'),
+    ];
+
+    chartRef.current = new Chart(canvasRef.current, {
+      type: 'doughnut',
+      data: {
+        labels: ['To Do', 'In Progress', 'Done'],
+        datasets: [
+          {
+            data: [todo, inProgress, done],
+            backgroundColor: colors,
+            borderWidth: 0,
+            hoverOffset: 6,
+          },
+        ],
+      },
+      options: {
+        responsive: true,
+        maintainAspectRatio: false,
+        cutout: '65%',
+        plugins: {
+          legend: {
+            position: 'bottom',
+            labels: {
+              padding: 16,
+              usePointStyle: true,
+              pointStyleWidth: 8,
+              font: { size: 12 },
+              color: getChartColor('--text-secondary', '#565869'),
+            },
+          },
+          tooltip: {
+            backgroundColor: 'rgba(0,0,0,0.8)',
+            titleFont: { size: 13 },
+            bodyFont: { size: 12 },
+            padding: 10,
+            cornerRadius: 8,
+          },
+        },
+      },
+    });
+
+    return function () {
+      if (chartRef.current) {
+        chartRef.current.destroy();
+        chartRef.current = null;
+      }
+    };
+  }, [stats.byStatus && stats.byStatus.todo,
+      stats.byStatus && stats.byStatus.in_progress,
+      stats.byStatus && stats.byStatus.done]);
+
+  var hasData =
+    ((stats.byStatus && stats.byStatus.todo) || 0) +
+    ((stats.byStatus && stats.byStatus.in_progress) || 0) +
+    ((stats.byStatus && stats.byStatus.done) || 0) > 0;
+
+  return h(
+    'div',
+    { className: 'bg-white rounded-lg border border-gray-200 p-4 card-hover' },
+    h('h3', { className: 'text-sm font-semibold text-gray-700 mb-3' }, 'Status Distribution'),
+    hasData
+      ? h('div', { style: { height: '200px', position: 'relative' } },
+          h('canvas', { ref: canvasRef })
+        )
+      : h('div', { className: 'flex items-center justify-center h-48 text-gray-400 text-sm' },
+          'No data to display'
+        )
+  );
+};
+`;
+
 // ---------------------------------------------------------------------------
 // public/pages/DashboardPage.js
 // ---------------------------------------------------------------------------
@@ -2527,6 +2731,11 @@ window.DashboardPage = function DashboardPage() {
       _statCard('Done', stats.byStatus.done || 0, 'bg-emerald-50')
     ),
 
+    // Chart — doughnut showing status distribution
+    h('div', { className: 'mb-6' },
+      h(window.StatsChart, { stats: stats })
+    ),
+
     // Filters
     h('div', { className: 'flex gap-2 mb-4' },
       _filterSelect('Status', app.filters.status, ['todo', 'in_progress', 'done'],
@@ -3288,6 +3497,7 @@ export const fullstackStarterTemplate = {
     "public/components/Navbar.js": NAVBAR_JS,
     "public/components/ItemCard.js": ITEM_CARD_JS,
     "public/components/ItemForm.js": ITEM_FORM_JS,
+    "public/components/StatsChart.js": STATS_CHART_JS,
     "public/pages/WelcomePage.js": WELCOME_PAGE_JS,
     "public/pages/LoginPage.js": LOGIN_PAGE_JS,
     "public/pages/RegisterPage.js": REGISTER_PAGE_JS,