create-interview-cockpit 0.3.0 → 0.5.0

package/template/server/src/index.ts

@@ -24,6 +24,10 @@ import { createGoogleGenerativeAI } from "@ai-sdk/google";
 import { createAnthropic } from "@ai-sdk/anthropic";
 import { randomUUID } from "crypto";
 import fs from "fs/promises";
+import os from "os";
+import { spawn } from "child_process";
+import net from "net";
+import ts from "typescript";
 import * as storage from "./storage.js";
 import * as googleDrive from "./google-drive.js";
 
@@ -32,11 +36,13 @@ app.use(cors());
 app.use(express.json({ limit: "25mb" }));
 
 const upload = multer({
-  limits: { fileSize: 10 * 1024 * 1024 }, // 10MB max
+  limits: { fileSize: 20 * 1024 * 1024 }, // 20MB max
   fileFilter: (_req, file, cb) => {
-    const allowed =
-      /\.(txt|md|ts|tsx|js|jsx|json|css|scss|html|xml|yaml|yml|csv|py|java|cs|go|rs|sql|sh|env|cfg|conf|toml|ini|log|pdf|docx)$/i;
-    if (allowed.test(file.originalname) || file.mimetype.startsWith("text/")) {
+    const allowedExt =
+      /\.(txt|md|ts|tsx|js|jsx|json|css|scss|html|xml|yaml|yml|csv|py|java|cs|go|rs|sql|sh|env|cfg|conf|toml|ini|log|pdf|docx|png|jpg|jpeg|gif|webp|svg)$/i;
+    const allowedMime =
+      file.mimetype.startsWith("text/") || file.mimetype.startsWith("image/");
+    if (allowedExt.test(file.originalname) || allowedMime) {
       cb(null, true);
     } else {
       cb(new Error("Unsupported file type"));
@@ -44,21 +50,56 @@ const upload = multer({
   },
 });
 
-// Extract text from uploaded files (docx, pdf, or plain text)
+// Extract text from uploaded files (docx, pdf, plain text, or images)
 async function extractText(buffer: Buffer, filename: string): Promise<string> {
   const ext = filename.split(".").pop()?.toLowerCase();
   if (ext === "docx") {
-    const result = await mammoth.extractRawText({ buffer });
-    return result.value;
+    try {
+      const result = await mammoth.extractRawText({ buffer });
+      return result.value;
+    } catch (e: any) {
+      return `[DOCX extraction failed: ${e?.message ?? "unknown error"}]`;
+    }
   }
   if (ext === "pdf") {
-    const parser = new PDFParse({ data: buffer });
-    const result = await parser.getText();
-    return result.text;
+    try {
+      const parser = new PDFParse({ data: buffer });
+      const result = await parser.getText();
+      return result.text ?? "";
+    } catch (e: any) {
+      return `[PDF extraction failed: ${e?.message ?? "unknown error"}. The original file is stored and can be downloaded.]`;
+    }
+  }
+  const imageExts = new Set(["png", "jpg", "jpeg", "gif", "webp", "svg"]);
+  if (ext && imageExts.has(ext)) {
+    // Images can't be read as text; store original for download.
+    // Return a descriptor so the LLM knows the file exists.
+    return `[Image file: ${filename} — the original is stored and available for download, but cannot be read as text by the AI.]`;
   }
   return buffer.toString("utf-8");
 }
 
+function mimeForFilename(filename: string): string {
+  const ext = filename.split(".").pop()?.toLowerCase() ?? "";
+  const map: Record<string, string> = {
+    pdf: "application/pdf",
+    docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    doc: "application/msword",
+    json: "application/json",
+    csv: "text/csv",
+    html: "text/html; charset=utf-8",
+    xml: "application/xml",
+    zip: "application/zip",
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    webp: "image/webp",
+    svg: "image/svg+xml",
+  };
+  return map[ext] ?? "application/octet-stream";
+}
+
 const PORT = process.env.PORT || 3001;
 const CODE_CONTEXT_DIR = process.env.CODE_CONTEXT_DIR || "";
 
@@ -326,26 +367,102 @@ app.patch("/api/topics/:id", async (req, res) => {
   res.json(topic);
 });
 
+// ─── Workspace Context Files ─────────────────────────────
+
+app.get("/api/workspace/context-files", async (_req, res) => {
+  const files = await storage.getWorkspaceContextFiles();
+  res.json(files);
+});
+
+app.post(
+  "/api/workspace/context-files",
+  upload.array("files", 20),
+  async (req, res) => {
+    try {
+      const files = req.files as Express.Multer.File[];
+      if (!files?.length) return res.status(400).json({ error: "No files" });
+      const results: storage.ContextFile[] = [];
+      for (const file of files) {
+        const id = randomUUID();
+        const text = await extractText(file.buffer, file.originalname);
+        // Store original bytes for download; extracted text for the LLM
+        await storage.writeOriginalBlob(id, file.buffer);
+        const cf = await storage.saveWorkspaceContextFile(
+          id,
+          file.originalname,
+          Buffer.from(text, "utf-8"),
+        );
+        results.push(cf);
+      }
+      res.json(results);
+    } catch (err: any) {
+      console.error("workspace upload error:", err?.message || err);
+      res.status(500).json({ error: err?.message || "Upload failed" });
+    }
+  },
+);
+
+app.delete("/api/workspace/context-files/:fileId", async (req, res) => {
+  await storage.deleteWorkspaceContextFile(req.params.fileId);
+  res.json({ ok: true });
+});
+
+app.get("/api/workspace/context-files/:fileId/download", async (req, res) => {
+  const files = await storage.getWorkspaceContextFiles();
+  const cf = files.find((f) => f.id === req.params.fileId);
+  if (!cf) return res.status(404).json({ error: "File not found" });
+  try {
+    const original = await storage.readOriginalBlob(req.params.fileId);
+    if (original) {
+      res.setHeader("Content-Type", mimeForFilename(cf.originalName));
+      res.setHeader(
+        "Content-Disposition",
+        `attachment; filename="${encodeURIComponent(cf.originalName)}"`,
+      );
+      return res.send(original);
+    }
+    // Fallback for files uploaded before original storage was added
+    const content = await storage.readWorkspaceContextFileContent(
+      req.params.fileId,
+    );
+    res.setHeader("Content-Type", "text/plain; charset=utf-8");
+    res.setHeader(
+      "Content-Disposition",
+      `attachment; filename="${encodeURIComponent(cf.originalName)}.txt"`,
+    );
+    res.send(content);
+  } catch {
+    res.status(404).json({ error: "File not found" });
+  }
+});
+
 // ─── Topic Context Files ─────────────────────────────────
 
 app.post(
   "/api/topics/:topicId/context-files",
   upload.array("files", 20),
   async (req, res) => {
-    const files = req.files as Express.Multer.File[];
-    if (!files?.length) return res.status(400).json({ error: "No files" });
-    const results: storage.ContextFile[] = [];
-    for (const file of files) {
-      const text = await extractText(file.buffer, file.originalname);
-      const cf = await storage.saveContextFile(
-        req.params.topicId as string,
-        randomUUID(),
-        file.originalname,
-        Buffer.from(text, "utf-8"),
-      );
-      results.push(cf);
+    try {
+      const files = req.files as Express.Multer.File[];
+      if (!files?.length) return res.status(400).json({ error: "No files" });
+      const results: storage.ContextFile[] = [];
+      for (const file of files) {
+        const id = randomUUID();
+        const text = await extractText(file.buffer, file.originalname);
+        await storage.writeOriginalBlob(id, file.buffer);
+        const cf = await storage.saveContextFile(
+          req.params.topicId as string,
+          id,
+          file.originalname,
+          Buffer.from(text, "utf-8"),
+        );
+        results.push(cf);
+      }
+      res.json(results);
+    } catch (err: any) {
+      console.error("topic upload error:", err?.message || err);
+      res.status(500).json({ error: err?.message || "Upload failed" });
     }
-    res.json(results);
   },
 );
 
@@ -354,6 +471,36 @@ app.delete("/api/topics/:topicId/context-files/:fileId", async (req, res) => {
   res.json({ ok: true });
 });
 
+app.get(
+  "/api/topics/:topicId/context-files/:fileId/download",
+  async (req, res) => {
+    const topics = await storage.getTopics();
+    const topic = topics.find((t) => t.id === req.params.topicId);
+    const cf = topic?.contextFiles?.find((f) => f.id === req.params.fileId);
+    if (!cf) return res.status(404).json({ error: "File not found" });
+    try {
+      const original = await storage.readOriginalBlob(req.params.fileId);
+      if (original) {
+        res.setHeader("Content-Type", mimeForFilename(cf.originalName));
+        res.setHeader(
+          "Content-Disposition",
+          `attachment; filename="${encodeURIComponent(cf.originalName)}"`,
+        );
+        return res.send(original);
+      }
+      const content = await storage.readContextFileContent(req.params.fileId);
+      res.setHeader("Content-Type", "text/plain; charset=utf-8");
+      res.setHeader(
+        "Content-Disposition",
+        `attachment; filename="${encodeURIComponent(cf.originalName)}.txt"`,
+      );
+      res.send(content);
+    } catch {
+      res.status(404).json({ error: "File not found" });
+    }
+  },
+);
+
 // ─── Questions ───────────────────────────────────────────
 
 app.get("/api/topics/:topicId/questions", async (req, res) => {
@@ -404,35 +551,76 @@ app.patch("/api/questions/:id", async (req, res) => {
 app.delete("/api/questions/:id", async (req, res) => {
   const q = await storage.getQuestion(req.params.id);
   if (q) {
-    // Cascade: delete children that point to this question
-    const siblings = await storage.getQuestionsByTopic(q.topicId);
-    const children = siblings.filter((c) => c.parentQuestionId === q.id);
-    await Promise.all(children.map((c) => storage.deleteQuestion(c.id)));
+    // Cascade: recursively delete all descendants (not just direct children)
+    const allInTopic = await storage.getQuestionsByTopic(q.topicId);
+    const collectDescendants = (parentId: string): string[] => {
+      const direct = allInTopic.filter((c) => c.parentQuestionId === parentId);
+      return direct.flatMap((c) => [c.id, ...collectDescendants(c.id)]);
+    };
+    const descendants = collectDescendants(q.id);
+    await Promise.all(descendants.map((id) => storage.deleteQuestion(id)));
   }
   await storage.deleteQuestion(req.params.id);
   res.json({ ok: true });
 });
 
+// ─── Code-line Annotations ─────────────────────────────
+
+app.get("/api/questions/:id/code-annotations", async (req, res) => {
+  const q = await storage.getQuestion(req.params.id);
+  if (!q) return res.status(404).json({ error: "Not found" });
+  const filePath = req.query.filePath as string;
+  if (!filePath) return res.json({ annotations: [] });
+  const annotations = q.codeAnnotations?.[filePath] ?? [];
+  res.json({ annotations });
+});
+
+app.patch("/api/questions/:id/code-annotations", async (req, res) => {
+  const { filePath, annotations } = req.body;
+  if (typeof filePath !== "string" || !filePath.trim()) {
+    return res.status(400).json({ error: "filePath is required" });
+  }
+  try {
+    await storage.updateCodeAnnotationsForFile(
+      req.params.id,
+      filePath,
+      Array.isArray(annotations) ? annotations : [],
+    );
+    res.json({ ok: true });
+  } catch (err: any) {
+    res
+      .status(500)
+      .json({ error: err?.message || "Failed to save annotations" });
+  }
+});
+
 // ─── Question Context Files ─────────────────────────────
 
 app.post(
   "/api/questions/:questionId/context-files",
   upload.array("files", 20),
   async (req, res) => {
-    const files = req.files as Express.Multer.File[];
-    if (!files?.length) return res.status(400).json({ error: "No files" });
-    const results: storage.ContextFile[] = [];
-    for (const file of files) {
-      const text = await extractText(file.buffer, file.originalname);
-      const cf = await storage.saveQuestionContextFile(
-        req.params.questionId as string,
-        randomUUID(),
-        file.originalname,
-        Buffer.from(text, "utf-8"),
-      );
-      results.push(cf);
+    try {
+      const files = req.files as Express.Multer.File[];
+      if (!files?.length) return res.status(400).json({ error: "No files" });
+      const results: storage.ContextFile[] = [];
+      for (const file of files) {
+        const id = randomUUID();
+        const text = await extractText(file.buffer, file.originalname);
+        await storage.writeOriginalBlob(id, file.buffer);
+        const cf = await storage.saveQuestionContextFile(
+          req.params.questionId as string,
+          id,
+          file.originalname,
+          Buffer.from(text, "utf-8"),
+        );
+        results.push(cf);
+      }
+      res.json(results);
+    } catch (err: any) {
+      console.error("question upload error:", err?.message || err);
+      res.status(500).json({ error: err?.message || "Upload failed" });
     }
-    res.json(results);
   },
 );
 
@@ -447,6 +635,292 @@ app.delete(
   },
 );
 
+// Save a code snippet (from Code Runner or AI response) as a question context file
+app.post("/api/questions/:questionId/save-code-snippet", async (req, res) => {
+  const { code, language, label, origin } = req.body as {
+    code: string;
+    language: string;
+    label: string;
+    origin: "user" | "ai" | "sandbox";
+  };
+  if (typeof code !== "string" || !code.trim()) {
+    return res.status(400).json({ error: "code is required" });
+  }
+  if (origin !== "user" && origin !== "ai" && origin !== "sandbox") {
+    return res
+      .status(400)
+      .json({ error: "origin must be 'user', 'ai', or 'sandbox'" });
+  }
+  try {
+    const id = randomUUID();
+    const safeLabel = (label || "snippet").replace(/[/\\:*?"<>|]/g, "-").trim();
+    const ext =
+      language === "typescript"
+        ? "ts"
+        : language === "javascript"
+          ? "js"
+          : "txt";
+    const fileName = `${safeLabel}.${ext}`;
+    const cf = await storage.saveQuestionContextFile(
+      req.params.questionId,
+      id,
+      fileName,
+      Buffer.from(code, "utf-8"),
+      { origin, language, label: safeLabel },
+    );
+    res.json(cf);
+  } catch (err: any) {
+    res.status(500).json({ error: err?.message || "Failed to save snippet" });
+  }
+});
+
+// Overwrite the content blob of an existing sandbox context file
+app.put(
+  "/api/questions/:questionId/context-files/:fileId/content",
+  async (req, res) => {
+    const { code } = req.body as { code: string };
+    if (typeof code !== "string") {
+      return res.status(400).json({ error: "code is required" });
+    }
+    try {
+      await storage.overwriteQuestionContextFileContent(
+        req.params.questionId,
+        req.params.fileId,
+        Buffer.from(code, "utf-8"),
+      );
+      res.json({ ok: true });
+    } catch (err: any) {
+      res.status(500).json({ error: err?.message || "Failed to overwrite" });
+    }
+  },
+);
+
+// Rename the label of an existing question context file
+app.patch(
+  "/api/questions/:questionId/context-files/:fileId",
+  async (req, res) => {
+    const { label } = req.body as { label: string };
+    if (typeof label !== "string" || !label.trim()) {
+      return res.status(400).json({ error: "label is required" });
+    }
+    try {
+      const cf = await storage.renameQuestionContextFile(
+        req.params.questionId,
+        req.params.fileId,
+        label.trim(),
+      );
+      res.json(cf);
+    } catch (err: any) {
+      res.status(500).json({ error: err?.message || "Failed to rename" });
+    }
+  },
+);
+
+// Unified content-read endpoint — used by DocRefModal to show extracted text
+// All context files (workspace / topic / question) share the same on-disk dir
+// per workspace, so a single reader covers every scope.
+app.get("/api/context-files/:fileId/content", async (req, res) => {
+  try {
+    const content = await storage.readContextFileContent(req.params.fileId);
+    res.json({ content });
+  } catch {
+    res.status(404).json({ error: "File not found" });
+  }
+});
+
+// List every uploaded file across workspace, topics, and questions.
+// Used by the file picker so users can link an existing file instead of re-uploading.
+app.get("/api/context-files/all", async (_req, res) => {
+  const entries: Array<{
+    fileId: string;
+    originalName: string;
+    source: "workspace" | "topic" | "question";
+    sourceName: string;
+  }> = [];
+
+  const wsFiles = await storage.getWorkspaceContextFiles();
+  for (const f of wsFiles) {
+    entries.push({
+      fileId: f.id,
+      originalName: f.originalName,
+      source: "workspace",
+      sourceName: "Workspace",
+    });
+  }
+
+  const topics = await storage.getTopics();
+  for (const t of topics) {
+    for (const f of t.contextFiles || []) {
+      entries.push({
+        fileId: f.id,
+        originalName: f.originalName,
+        source: "topic",
+        sourceName: t.name,
+      });
+    }
+  }
+
+  // Scan question files via the questions directory
+  const questions = await storage.getAllQuestions();
+  for (const q of questions) {
+    for (const f of q.contextFiles || []) {
+      entries.push({
+        fileId: f.id,
+        originalName: f.originalName,
+        source: "question",
+        sourceName: q.title,
+      });
+    }
+  }
+
+  // Deduplicate by fileId — keep the first occurrence (workspace > topic > question)
+  const seen = new Set<string>();
+  const deduped = entries.filter((e) => {
+    if (seen.has(e.fileId)) return false;
+    seen.add(e.fileId);
+    return true;
+  });
+
+  res.json(deduped);
+});
+
+// Link an existing file to a topic without re-uploading
+app.post("/api/topics/:topicId/context-files/link", async (req, res) => {
+  const { fileId, originalName } = req.body as {
+    fileId?: string;
+    originalName?: string;
+  };
+  if (!fileId || !originalName)
+    return res.status(400).json({ error: "fileId and originalName required" });
+  const cf = await storage.linkContextFileToTopic(
+    req.params.topicId,
+    fileId,
+    originalName,
+  );
+  res.json(cf);
+});
+
+// Link an existing file to a question without re-uploading
+app.post("/api/questions/:questionId/context-files/link", async (req, res) => {
+  const { fileId, originalName } = req.body as {
+    fileId?: string;
+    originalName?: string;
+  };
+  if (!fileId || !originalName)
+    return res.status(400).json({ error: "fileId and originalName required" });
+  const cf = await storage.linkContextFileToQuestion(
+    req.params.questionId,
+    fileId,
+    originalName,
+  );
+  res.json(cf);
+});
+
+// Unified inline-download endpoint — serves the original binary with Content-Disposition: inline
+// so browsers can render PDFs/images directly inside an <iframe> or <img>.
+// Pass ?name=originalFilename.pdf so Content-Type and filename are set correctly.
+app.get("/api/context-files/:fileId/view", async (req, res) => {
+  const name = typeof req.query.name === "string" ? req.query.name : "file";
+  try {
+    const original = await storage.readOriginalBlob(req.params.fileId);
+    if (original) {
+      res.setHeader("Content-Type", mimeForFilename(name));
+      res.setHeader(
+        "Content-Disposition",
+        `inline; filename="${encodeURIComponent(name)}"`,
+      );
+      return res.send(original);
+    }
+    // Fallback: serve extracted text as plain text
+    const content = await storage.readContextFileContent(req.params.fileId);
+    res.setHeader("Content-Type", "text/plain; charset=utf-8");
+    res.setHeader(
+      "Content-Disposition",
+      `inline; filename="${encodeURIComponent(name)}.txt"`,
+    );
+    res.send(content);
+  } catch {
+    res.status(404).json({ error: "File not found" });
+  }
+});
+
+app.get(
+  "/api/questions/:questionId/context-files/:fileId/download",
+  async (req, res) => {
+    const question = await storage.getQuestion(req.params.questionId);
+    const cf = question?.contextFiles?.find((f) => f.id === req.params.fileId);
+    if (!cf) return res.status(404).json({ error: "File not found" });
+    try {
+      const original = await storage.readOriginalBlob(req.params.fileId);
+      if (original) {
+        res.setHeader("Content-Type", mimeForFilename(cf.originalName));
+        res.setHeader(
+          "Content-Disposition",
+          `attachment; filename="${encodeURIComponent(cf.originalName)}"`,
+        );
+        return res.send(original);
+      }
+      const content = await storage.readContextFileContent(req.params.fileId);
+      res.setHeader("Content-Type", "text/plain; charset=utf-8");
+      res.setHeader(
+        "Content-Disposition",
+        `attachment; filename="${encodeURIComponent(cf.originalName)}.txt"`,
+      );
+      res.send(content);
+    } catch {
+      res.status(404).json({ error: "File not found" });
+    }
+  },
+);
+
+// ─── AI Settings ────────────────────────────────────────────
+
+app.get("/api/settings", async (_req, res) => {
+  const settings = await storage.getAiSettings();
+  res.json({
+    ...settings,
+    // Expose current provider/model from env so client can conditionally show thinking controls
+    provider: (process.env.AI_PROVIDER || "openai").toLowerCase(),
+    model: process.env.AI_MODEL || "",
+  });
+});
+
+app.patch("/api/settings", async (req, res) => {
+  const current = await storage.getAiSettings();
+  const updated: storage.AiSettings = {
+    systemPrompt:
+      typeof req.body.systemPrompt === "string"
+        ? req.body.systemPrompt
+        : current.systemPrompt,
+    responseProfiles:
+      req.body.responseProfiles != null
+        ? req.body.responseProfiles
+        : current.responseProfiles,
+    vizGuide:
+      typeof req.body.vizGuide === "string"
+        ? req.body.vizGuide
+        : current.vizGuide,
+    promptGroups:
+      req.body.promptGroups != null
+        ? req.body.promptGroups
+        : current.promptGroups,
+    thinkingBudget:
+      typeof req.body.thinkingBudget === "number"
+        ? req.body.thinkingBudget
+        : current.thinkingBudget,
+    alwaysSendPrefsDefault:
+      typeof req.body.alwaysSendPrefsDefault === "boolean"
+        ? req.body.alwaysSendPrefsDefault
+        : current.alwaysSendPrefsDefault,
+  };
+  await storage.saveAiSettings(updated);
+  res.json({
+    ...updated,
+    provider: (process.env.AI_PROVIDER || "openai").toLowerCase(),
+    model: process.env.AI_MODEL || "",
+  });
+});
+
 // ─── Chat ────────────────────────────────────────────────
 
 app.post("/api/chat", async (req, res) => {
@@ -462,38 +936,12 @@ app.post("/api/chat", async (req, res) => {
     responseLength,
   } = req.body;
 
-  const responseProfiles: Record<
-    string,
-    { maxOutputTokens: number; maxSteps: number }
-  > = {
-    concise: {
-      maxOutputTokens: 1000,
-      maxSteps: 3,
-    },
-    moderate: {
-      maxOutputTokens: 1000,
-      maxSteps: 5,
-    },
-    normal: {
-      maxOutputTokens: 3000,
-      maxSteps: 5,
-    },
-  };
-  const selectedResponseProfile =
-    responseProfiles[responseLength] || responseProfiles.normal;
-
-  let system = `You are a senior engineering interview coach.
-
-Highest priority: follow the user's explicit response preferences and current conversation context. If they conflict with your default teaching behavior, the user's preference wins.
-Explain clearly, accurately, and practically.
-Only include Mermaid diagrams, code blocks, or tables when the user explicitly asks for them or when they materially improve the answer.
-If you show code, use a fenced code block with the correct language.
+  const aiSettings = await storage.getAiSettings();
+  const { responseProfiles, vizGuide } = aiSettings;
+  const selectedResponseProfile = responseProfiles[responseLength] ??
+    responseProfiles["normal"] ?? { maxOutputTokens: 3000, maxSteps: 5 };
 
-Mermaid syntax rules (follow strictly):
-- Wrap node labels in quotes when they contain special characters: A["Microservice A (Producer)"]
-- Edge labels use |text| syntax: A -->|sends message| B
-- Never put parentheses or brackets inside [] without quoting the label
-- Use simple node IDs (letters/numbers) and put descriptive text in the label`;
+  let system = aiSettings.systemPrompt;
 
   if (topicTitle || questionTitle) {
     system += `\n\n--- Current Context ---`;
@@ -512,6 +960,15 @@ Mermaid syntax rules (follow strictly):
     { label: string; reader: () => Promise<string> }
   >();
 
+  // Workspace-level uploaded files (apply to all topics)
+  const workspaceFiles = await storage.getWorkspaceContextFiles();
+  for (const cf of workspaceFiles) {
+    fileRegistry.set(cf.id, {
+      label: `[workspace] ${cf.originalName}`,
+      reader: () => storage.readWorkspaceContextFileContent(cf.id),
+    });
+  }
+
   // Topic-level uploaded files
   if (topicId) {
     const topics = await storage.getTopics();
@@ -582,6 +1039,62 @@ Examples:
 Use this for class names, method names, or any mention of a specific file from the code context. The display text should be the class, file, or concept name — not the raw path.
 Only use coderef:// for [code] files. Do not use it for uploaded documents.`;
     }
+
+    // Always add the inline code block instruction
+    system += `
+
+--- Writing Code Blocks the User Can Explore ---
+When you write a fenced code block that the user might want to open in the interactive code viewer (to annotate it, ask questions line-by-line, or use it as context), add a reference label as the FIRST line of the block using a comment in the language's native syntax:
+
+  // @ref: some-unique-label        ← JavaScript / TypeScript / Java / C# / Go etc.
+  # @ref: some-unique-label         ← Python / Ruby / Shell
+  -- @ref: some-unique-label        ← SQL / Lua
+
+Then anywhere in your response text where you want a clickable link back to that block:
+
+  [Descriptive Label](inlineref://some-unique-label)
+
+Example:
+\`\`\`typescript
+// @ref: user-service
+export class UserService {
+  async getUser(id: string) { ... }
+}
+\`\`\`
+
+The implementation is in [UserService](inlineref://user-service).
+
+Rules:
+- The label must be a short unique slug within your response.
+- The @ref comment line is stripped from the displayed code — the user never sees it.
+- You only need @ref when you want to create an explicit link in prose. A plain code block without @ref still gets a pop-out button the user can click.
+- Never put @ref on any line other than the very first line of the block.`;
+
+    // Collect non-code document file IDs for docref linking instructions
+    const docFileEntries: Array<{ id: string; label: string }> = [];
+    for (const [id, { label }] of fileRegistry) {
+      if (!id.startsWith("code:")) docFileEntries.push({ id, label });
+    }
+
+    if (docFileEntries.length > 0) {
+      system += `
+
+--- Quoting From Uploaded Documents ---
+When you quote or reference a specific passage from one of the **[workspace]**, **[topic]**, or **[question]** documents above, format the quoted text as a clickable link so the user can see it highlighted in the original document:
+
+  [the exact passage you are citing](docref://{id}?n={encodedFileName})
+
+Rules:
+- The link text MUST be the verbatim passage you are quoting (a sentence, phrase, or term from the document).
+- {id} is the file id shown in the list above (e.g. "abc123").
+- {encodedFileName} is the file's original name, percent-encoded (spaces → %20, etc.).
+- Only use docref:// for uploaded document files. Do not use it for code files.
+
+Examples (illustrative only — use real ids and names from the list above):
+  [The system shall validate all inputs before processing](docref://abc123?n=Requirements.pdf)
+  [O(n log n) average-case complexity](docref://def456?n=Algorithm%20Notes.docx)
+`;
+    }
   }
 
   // Code snippets hand-picked by the user from the file viewer
@@ -620,13 +1133,21 @@ Only use coderef:// for [code] files. Do not use it for uploaded documents.`;
       maxOutputTokens: selectedResponseProfile.maxOutputTokens,
       ...(isGoogle && {
         providerOptions: {
-          google: { thinkingConfig: { thinkingBudget: 0 } },
+          google: {
+            thinkingConfig: { thinkingBudget: aiSettings.thinkingBudget ?? 0 },
+          },
         },
       }),
       system,
       messages: modelMessages,
-      tools:
-        fileRegistry.size > 0
+      tools: {
+        getVizGuide: tool({
+          description:
+            "Get the full viz diagram spec reference. Call this before writing a ```viz block so you have the correct schema, rules, and examples.",
+          inputSchema: z.object({}),
+          execute: async () => ({ guide: vizGuide }),
+        }),
+        ...(fileRegistry.size > 0
           ? {
               readFile: tool({
                 description:
@@ -650,7 +1171,8 @@ Only use coderef:// for [code] files. Do not use it for uploaded documents.`;
                 },
               }),
             }
-          : undefined,
+          : {}),
+      },
       stopWhen: stepCountIs(selectedResponseProfile.maxSteps),
     });
 
@@ -666,6 +1188,7 @@ Only use coderef:// for [code] files. Do not use it for uploaded documents.`;
             id: message.id || randomUUID(),
             role: message.role,
             content: getTextFromUIMessage(message),
+            ...(Array.isArray(message.parts) ? { parts: message.parts } : {}),
           }));
 
           await storage.updateQuestionMessages(questionId, normalized);
@@ -812,6 +1335,177 @@ app.get("/api/code-context/file", async (req, res) => {
   }
 });
 
+// ─── Code Line Ask ──────────────────────────────────────
+
+app.post("/api/code-line-ask", async (req, res) => {
+  const {
+    filePath,
+    selectedCode,
+    prompt,
+    questionId,
+    topicId,
+    codeContextFiles,
+    codeSnippets,
+    preferenceSuffix,
+  } = req.body;
+  if (typeof prompt !== "string" || !prompt.trim()) {
+    return res.status(400).json({ error: "prompt is required" });
+  }
+  if (typeof selectedCode !== "string" || !selectedCode.trim()) {
+    return res.status(400).json({ error: "selectedCode is required" });
+  }
+
+  try {
+    const isGoogle = ["google", "gemini"].includes(
+      (process.env.AI_PROVIDER || "openai").toLowerCase(),
+    );
+    const aiSettings = await storage.getAiSettings();
+
+    // Build a file registry identical to /api/chat so the model has the same context
+    const fileRegistry = new Map<
+      string,
+      { label: string; reader: () => Promise<string> }
+    >();
+
+    const workspaceFiles = await storage.getWorkspaceContextFiles();
+    for (const cf of workspaceFiles) {
+      fileRegistry.set(cf.id, {
+        label: `[workspace] ${cf.originalName}`,
+        reader: () => storage.readWorkspaceContextFileContent(cf.id),
+      });
+    }
+
+    if (topicId) {
+      const topics = await storage.getTopics();
+      const topic = topics.find((t: any) => t.id === topicId);
+      if (topic?.contextFiles?.length) {
+        for (const cf of topic.contextFiles) {
+          fileRegistry.set(cf.id, {
+            label: `[topic] ${cf.originalName}`,
+            reader: () => storage.readContextFileContent(cf.id),
+          });
+        }
+      }
+    }
+
+    if (questionId) {
+      const question = await storage.getQuestion(questionId);
+      if (question?.contextFiles?.length) {
+        for (const cf of question.contextFiles) {
+          fileRegistry.set(cf.id, {
+            label: `[question] ${cf.originalName}`,
+            reader: () => storage.readContextFileContent(cf.id),
+          });
+        }
+      }
+    }
+
+    if (codeContextFiles?.length && CODE_CONTEXT_DIR) {
+      for (const fp of codeContextFiles as string[]) {
+        const fullPath = path.join(CODE_CONTEXT_DIR, fp);
+        const resolved = path.resolve(fullPath);
+        if (!resolved.startsWith(path.resolve(CODE_CONTEXT_DIR))) continue;
+        fileRegistry.set(`code:${fp}`, {
+          label: `[code] ${fp}`,
+          reader: () => fs.readFile(resolved, "utf-8"),
+        });
+      }
+    }
+
+    let system =
+      "You are a senior software engineer and interview coach. Answer questions about the highlighted code lines. Be concise, accurate, and practical. Use markdown formatting for code references.";
+
+    // Apply the user's active response preferences (LENGTH / STYLE / AUDIENCE / etc.)
+    if (
+      preferenceSuffix &&
+      typeof preferenceSuffix === "string" &&
+      preferenceSuffix.trim()
+    ) {
+      system += `\n\n${preferenceSuffix.trim()}`;
+    }
+
+    if (fileRegistry.size > 0) {
+      const codeFilePaths: string[] = [];
+      for (const [id, { label }] of fileRegistry) {
+        if (id.startsWith("code:"))
+          codeFilePaths.push(id.slice("code:".length));
+      }
+
+      system += `\n\n--- Available Reference Files ---\nThe following files are available to you. Use the readFile tool to retrieve a file's content when it would help answer the question. Only read files that are relevant.\n\n`;
+      for (const [id, { label }] of fileRegistry) {
+        system += `• ${label}  (id: "${id}")\n`;
+      }
+
+      if (codeFilePaths.length > 0) {
+        system += `\n--- Linking Code Files in Your Response ---\nWhen you mention a [code] file, format it as a clickable link:\n  [DisplayText](coderef://relative/path/to/file)\nOnly use coderef:// for [code] files.`;
+      }
+    }
+
+    if (Array.isArray(codeSnippets) && codeSnippets.length > 0) {
+      system += `\n\n--- Code Snippets (pinned by user) ---\n`;
+      for (const snippet of codeSnippets as Array<{
+        fileName: string;
+        filePath: string;
+        startLine: number;
+        endLine: number;
+        code: string;
+      }>) {
+        const lineLabel =
+          snippet.startLine === snippet.endLine
+            ? `line ${snippet.startLine}`
+            : `lines ${snippet.startLine}–${snippet.endLine}`;
+        system += `**${snippet.fileName}** (${lineLabel}):\n\`\`\`\n${snippet.code}\n\`\`\`\n\n`;
+      }
+    }
+
+    const { text } = await generateText({
+      model: getModel(),
+      maxOutputTokens: 1200,
+      ...(isGoogle && {
+        providerOptions: {
+          google: {
+            thinkingConfig: { thinkingBudget: aiSettings.thinkingBudget ?? 0 },
+          },
+        },
+      }),
+      system,
+      prompt: `File: ${filePath || "unknown"}\n\nHighlighted code:\n\`\`\`\n${selectedCode}\n\`\`\`\n\nQuestion: ${prompt.trim()}`,
+      tools:
+        fileRegistry.size > 0
+          ? {
+              readFile: tool({
+                description:
+                  "Read the content of an available reference file. Use this to get file contents when relevant to the question.",
+                inputSchema: z.object({
+                  fileId: z
+                    .string()
+                    .describe(
+                      "The id of the file to read, from the available files list.",
+                    ),
+                }),
+                execute: async ({ fileId }) => {
+                  const entry = fileRegistry.get(fileId);
+                  if (!entry) return { error: "File not found" };
+                  try {
+                    const content = await entry.reader();
+                    return { fileName: entry.label, content };
+                  } catch {
+                    return { error: "Could not read file" };
+                  }
+                },
+              }),
+            }
+          : undefined,
+      stopWhen: stepCountIs(4),
+    });
+
+    res.json({ response: text });
+  } catch (err: any) {
+    console.error("code-line-ask error:", err?.message || err);
+    res.status(500).json({ error: err?.message || "Failed to get response" });
+  }
+});
+
 // ─── Inline Ask ─────────────────────────────────────────
 
 app.post("/api/inline-ask", async (req, res) => {
@@ -824,6 +1518,7 @@ app.post("/api/inline-ask", async (req, res) => {
     responseLength,
     responseStyle,
     responseAudience,
+    preferenceSuffix,
   } = req.body;
   if (typeof selectedText !== "string" || typeof prompt !== "string") {
     return res
@@ -836,6 +1531,8 @@ app.post("/api/inline-ask", async (req, res) => {
       (process.env.AI_PROVIDER || "openai").toLowerCase(),
     );
 
+    const aiSettings = await storage.getAiSettings();
+
     // Build conversation thread context for follow-ups
     let threadContext = "";
     if (priorResponse) {
@@ -871,13 +1568,22 @@ app.post("/api/inline-ask", async (req, res) => {
       systemLines.push(styleHints[responseStyle]);
     if (responseAudience && audienceHints[responseAudience])
       systemLines.push(audienceHints[responseAudience]);
+    // preferenceSuffix carries ALL current group selections as pre-built text
+    if (
+      preferenceSuffix &&
+      typeof preferenceSuffix === "string" &&
+      preferenceSuffix.trim()
+    )
+      systemLines.push(preferenceSuffix.trim());
 
     const { text } = await generateText({
       model: getModel(),
       maxOutputTokens: 800,
       ...(isGoogle && {
         providerOptions: {
-          google: { thinkingConfig: { thinkingBudget: 0 } },
+          google: {
+            thinkingConfig: { thinkingBudget: aiSettings.thinkingBudget ?? 0 },
+          },
         },
       }),
       system: systemLines.join("\n"),
@@ -899,6 +1605,107 @@ Their question: "${prompt}"`,
   }
 });
 
+// ─── Fix Viz ────────────────────────────────────────────
+
+app.post("/api/fix-viz", async (req, res) => {
+  const { spec, error: renderError } = req.body;
+  if (typeof spec !== "string" || !spec.trim()) {
+    return res.status(400).json({ error: "spec is required" });
+  }
+
+  try {
+    const isGoogle = ["google", "gemini"].includes(
+      (process.env.AI_PROVIDER || "openai").toLowerCase(),
+    );
+
+    const { text } = await generateText({
+      model: getModel(),
+      maxOutputTokens: 2500,
+      ...(isGoogle && {
+        providerOptions: {
+          google: { thinkingConfig: { thinkingBudget: 0 } },
+        },
+      }),
+      prompt: `The following viz diagram spec failed to render.${renderError ? `\n\nRender error:\n${renderError}` : ""}\n\nFix the spec so it renders correctly. Common issues to check:\n- x/y coordinates must be numbers, not strings\n- node ids must be kebab-case with no spaces\n- Truncated spec: if the spec looks cut off mid-label or mid-step, complete all missing steps before returning — output the full corrected spec.\n- Signal chain direction: a chain [A, B] animates along the edge FROM A TO B. That directed edge (from: A, to: B) MUST exist in the edges section. If you want to show data flowing from B to A but only have the edge A→B, either flip the chain to [A, B] (showing the reverse path) or add a new reverse edge. Never use a chain direction that has no matching directed edge.\n- chain arrays in autoSignals/signals must reference valid node ids\n- YAML flow sequences ([a, b]) must be correctly indented and closed\n- Do NOT mix autoSignals and steps in the same spec\n- Typography: replace en-dashes (–, U+2013) and em-dashes (—, U+2014) with a plain ASCII hyphen (-). Replace curly/smart quotes with straight ASCII quotes. These typographic Unicode characters cause the YAML parser to fail with "Missing closing quote" errors.\n- YAML string quoting: if a label or value contains special characters (hyphens like --, colons, brackets, slashes, or leading/trailing spaces), wrap the ENTIRE value in double quotes. Do NOT use single quotes — single-quoted YAML strings must be self-contained; trailing words after the closing quote cause parse errors. Example of wrong: label: 'update-index --skip-worktree' changes file metadata  Example of correct: label: "update-index --skip-worktree changes file metadata"\n- Never split a label across multiple YAML lines unless using a literal block scalar (| or >)\n\nReturn ONLY the corrected YAML (or JSON) spec with no explanation and no markdown fences — just the raw spec.\n\nFailed spec:\n${spec}`,
+    });
+
+    // Strip any fences the model might have added
+    const fixed = text
+      .replace(/^```(?:yaml|json|viz)?\s*/i, "")
+      .replace(/```\s*$/, "")
+      .trim();
+
+    res.json({ spec: fixed });
+  } catch (err: any) {
+    console.error("fix-viz error:", err?.message || err);
+    res.status(500).json({ error: err?.message || "Failed to fix viz" });
+  }
+});
+
+// ─── Refine Viz ─────────────────────────────────────────
+
+app.post("/api/refine-viz", async (req, res) => {
+  const { spec, prompt: userPrompt, history } = req.body;
+  if (typeof spec !== "string" || !spec.trim()) {
+    return res.status(400).json({ error: "spec is required" });
+  }
+  if (typeof userPrompt !== "string" || !userPrompt.trim()) {
+    return res.status(400).json({ error: "prompt is required" });
+  }
+
+  try {
+    const { vizGuide } = await storage.getAiSettings();
+    const isGoogle = ["google", "gemini"].includes(
+      (process.env.AI_PROVIDER || "openai").toLowerCase(),
+    );
+
+    const historyContext =
+      Array.isArray(history) && history.length
+        ? history
+            .map(
+              (h: { prompt: string; spec: string }, i: number) =>
+                `[Refinement ${i + 1}] User asked: "${h.prompt}"\nResulting spec:\n${h.spec}`,
+            )
+            .join("\n\n---\n\n") + "\n\n---\n\n"
+        : "";
+
+    const prompt = `You are editing a VizCraft diagram spec.${vizGuide ? `\n\n${vizGuide}` : ""}${historyContext ? `\nPrior refinements applied to this diagram:\n\n${historyContext}` : ""}
+Current spec:
+${spec}
+
+User instruction: ${userPrompt}
+
+Apply the user's instruction to the spec. Return ONLY the updated YAML (or JSON) spec with no explanation and no markdown fences — just the raw spec.
+Rules:
+- Preserve all existing structure unless the user explicitly asks to remove something
+- If adding nodes, pick sensible x/y coordinates that fit the existing layout
+- YAML string quoting: wrap values with special characters (hyphens like --, colons, brackets) in double quotes, never single quotes
+- Node ids must be kebab-case with no spaces
+- Return the same format as the input (YAML or JSON)`;
+
+    const { text } = await generateText({
+      model: getModel(),
+      maxOutputTokens: 1600,
+      ...(isGoogle && {
+        providerOptions: {
+          google: { thinkingConfig: { thinkingBudget: 0 } },
+        },
+      }),
+      prompt,
+    });
+
+    const refined = text
+      .replace(/^```(?:yaml|json|viz)?\s*/i, "")
+      .replace(/```\s*$/, "")
+      .trim();
+
+    res.json({ spec: refined });
+  } catch (err: any) {
+    console.error("refine-viz error:", err?.message || err);
+    res.status(500).json({ error: err?.message || "Failed to refine viz" });
+  }
+});
+
 // ─── Fix Diagram ────────────────────────────────────────
 
 app.post("/api/fix-diagram", async (req, res) => {
@@ -937,6 +1744,310 @@ app.post("/api/fix-diagram", async (req, res) => {
   }
 });
 
+// ─── Code Runner ────────────────────────────────────────────
+
+const RUN_TIMEOUT_MS = 10_000;
+
+app.post("/api/run-code", async (req, res) => {
+  const { code, language = "typescript" } = req.body as {
+    code: string;
+    language?: string;
+  };
+
+  if (typeof code !== "string" || code.trim().length === 0) {
+    return res.status(400).json({ error: "No code provided" });
+  }
+
+  // Transpile TS → JS if needed (ts.transpileModule is a zero-cost in-process call)
+  let jsCode: string;
+  try {
+    if (language === "typescript") {
+      const result = ts.transpileModule(code, {
+        compilerOptions: {
+          target: ts.ScriptTarget.ESNext,
+          module: ts.ModuleKind.ESNext,
+          strict: false,
+          esModuleInterop: true,
+        },
+      });
+      jsCode = result.outputText;
+    } else {
+      jsCode = code;
+    }
+  } catch (transpileErr: any) {
+    return res.json({
+      stdout: "",
+      stderr: String(transpileErr?.message ?? transpileErr),
+      durationMs: 0,
+      timedOut: false,
+    });
+  }
+
+  // Write to a temp .mjs file and run it as a child process
+  const tmpFile = path.join(os.tmpdir(), `runner-${randomUUID()}.mjs`);
+  try {
+    await fs.writeFile(tmpFile, jsCode, "utf8");
+  } catch {
+    return res.status(500).json({ error: "Failed to write temp file" });
+  }
+
+  const stdoutLines: string[] = [];
+  const stderrLines: string[] = [];
+  let timedOut = false;
+  const start = Date.now();
+
+  await new Promise<void>((resolve) => {
+    const child = spawn(process.execPath, [tmpFile], {
+      timeout: RUN_TIMEOUT_MS,
+      env: { ...process.env, NODE_NO_WARNINGS: "1" },
+    });
+
+    const killTimer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGKILL");
+      resolve();
+    }, RUN_TIMEOUT_MS);
+
+    child.stdout.on("data", (chunk: Buffer) => {
+      stdoutLines.push(chunk.toString());
+    });
+    child.stderr.on("data", (chunk: Buffer) => {
+      stderrLines.push(chunk.toString());
+    });
+    child.on("close", () => {
+      clearTimeout(killTimer);
+      resolve();
+    });
+  });
+
+  // Clean up temp file (best-effort)
+  fs.unlink(tmpFile).catch(() => {});
+
+  res.json({
+    stdout: stdoutLines.join(""),
+    stderr: stderrLines.join(""),
+    durationMs: Date.now() - start,
+    timedOut,
+  });
+});
+
+// ─── Sandbox: persistent server + client runner ────────────
+
+interface SandboxEntry {
+  child: import("child_process").ChildProcess;
+  port: number;
+  tmpFile: string;
+  logs: string[];
+}
+
+const sandboxes = new Map<string, SandboxEntry>();
+const SANDBOX_DIR = path.join(__dirname, "..", ".sandbox-tmp");
+
+async function getFreePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const srv = net.createServer();
+    srv.listen(0, "127.0.0.1", () => {
+      const addr = srv.address() as net.AddressInfo;
+      srv.close(() => resolve(addr.port));
+    });
+    srv.on("error", reject);
+  });
+}
+
+function transpileToJs(code: string, language: string): string {
+  if (language === "typescript") {
+    return ts.transpileModule(code, {
+      compilerOptions: {
+        target: ts.ScriptTarget.ESNext,
+        module: ts.ModuleKind.ESNext,
+        strict: false,
+        esModuleInterop: true,
+      },
+    }).outputText;
+  }
+  return code;
+}
+
+app.post("/api/sandbox/start", async (req, res) => {
+  const { serverCode, language = "typescript" } = req.body as {
+    serverCode: string;
+    language?: string;
+  };
+  if (typeof serverCode !== "string" || !serverCode.trim()) {
+    return res.status(400).json({ error: "serverCode is required" });
+  }
+  let jsCode: string;
+  try {
+    jsCode = transpileToJs(serverCode, language);
+  } catch (err: any) {
+    return res.status(400).json({ error: err?.message ?? String(err) });
+  }
+
+  const port = await getFreePort();
+  const id = randomUUID();
+  await fs.mkdir(SANDBOX_DIR, { recursive: true });
+  const tmpFile = path.join(SANDBOX_DIR, `${id}.mjs`);
+  await fs.writeFile(tmpFile, jsCode, "utf8");
+
+  const logs: string[] = [];
+  const child = spawn(process.execPath, [tmpFile], {
+    env: { ...process.env, PORT: String(port), NODE_NO_WARNINGS: "1" },
+  });
+  child.stdout.on("data", (chunk: Buffer) => logs.push(chunk.toString()));
+  child.stderr.on("data", (chunk: Buffer) => logs.push(chunk.toString()));
+  child.on("exit", () => {
+    sandboxes.delete(id);
+    fs.unlink(tmpFile).catch(() => {});
+  });
+  sandboxes.set(id, { child, port, tmpFile, logs });
+
+  // Give the server a moment to bind (or fail)
+  await new Promise((r) => setTimeout(r, 900));
+  if (!sandboxes.has(id)) {
+    return res.status(500).json({
+      error: logs.join("").trim() || "Server exited immediately",
+    });
+  }
+  res.json({ sandboxId: id, port, sandboxUrl: `http://localhost:${port}` });
+});
+
+app.get("/api/sandbox/:id/status", (req, res) => {
+  const sb = sandboxes.get(req.params.id);
+  if (!sb) return res.json({ running: false, logs: [] });
+  res.json({ running: true, port: sb.port, logs: sb.logs });
+});
+
+app.delete("/api/sandbox/:id", (req, res) => {
+  const sb = sandboxes.get(req.params.id);
+  if (sb) {
+    sb.child.kill("SIGTERM");
+    sandboxes.delete(req.params.id);
+    fs.unlink(sb.tmpFile).catch(() => {});
+  }
+  res.json({ ok: true });
+});
+
+app.post("/api/sandbox/run-client", async (req, res) => {
+  const {
+    code,
+    language = "javascript",
+    sandboxUrl,
+  } = req.body as {
+    code: string;
+    language?: string;
+    sandboxUrl: string;
+  };
+  if (typeof code !== "string" || !code.trim()) {
+    return res.status(400).json({ error: "code is required" });
+  }
+  const eventSourcePolyfill = `
+if (typeof EventSource === 'undefined') {
+  const { default: _http } = await import('http');
+  const { default: _https } = await import('https');
+  const { EventEmitter: _EE } = await import('events');
+  globalThis.EventSource = class EventSource extends _EE {
+    constructor(url) {
+      super();
+      // Resolve relative URLs against SANDBOX_URL (e.g. '/api/foo' → 'http://localhost:PORT/api/foo')
+      const _resolved = (url.startsWith('http://') || url.startsWith('https://'))
+        ? url
+        : SANDBOX_URL + (url.startsWith('/') ? url : '/' + url);
+      this.url = _resolved; this.readyState = 0;
+      const _mod = _resolved.startsWith('https') ? _https : _http;
+      this._req = _mod.get(_resolved, { headers: { Accept: 'text/event-stream', 'Cache-Control': 'no-cache' } }, (res) => {
+        this.readyState = 1;
+        let _buf = '';
+        res.on('data', (chunk) => {
+          _buf += chunk.toString();
+          const _msgs = _buf.split('\\n\\n');
+          _buf = _msgs.pop() ?? '';
+          for (const _b of _msgs) {
+            if (!_b.trim()) continue;
+            let _data = '', _type = 'message';
+            for (const _l of _b.split('\\n')) {
+              if (_l.startsWith('data:')) _data += (_data ? '\\n' : '') + _l.slice(5).trimStart();
+              else if (_l.startsWith('event:')) _type = _l.slice(6).trimStart();
+            }
+            const _e = { type: _type, data: _data };
+            if (_type === 'message' && this.onmessage) this.onmessage(_e);
+            this.emit(_type, _e);
+          }
+        });
+        res.on('end', () => { this.readyState = 2; });
+      });
+      this._req.on('error', () => { this.readyState = 2; });
+    }
+    close() { try { this._req?.destroy(); } catch {} this.readyState = 2; }
+    addEventListener(t, fn) { this.on(t, fn); }
+    removeEventListener(t, fn) { this.off(t, fn); }
+  };
+}`;
+  const wrapped = `const SANDBOX_URL = ${JSON.stringify(sandboxUrl ?? "")};
+${eventSourcePolyfill}
+${code}`;
+  let jsCode: string;
+  try {
+    jsCode = transpileToJs(wrapped, language);
+  } catch (err: any) {
+    return res.json({
+      stdout: "",
+      stderr: String(err?.message ?? err),
+      durationMs: 0,
+      timedOut: false,
+    });
+  }
+
+  // Switch to SSE streaming so each log line reaches the browser immediately
+  res.setHeader("Content-Type", "text/event-stream");
+  res.setHeader("Cache-Control", "no-cache");
+  res.setHeader("Connection", "keep-alive");
+  res.flushHeaders();
+
+  const sendEvent = (kind: string, text: string) => {
+    res.write(`data: ${JSON.stringify({ kind, text })}\n\n`);
+  };
+
+  const tmpFile = path.join(os.tmpdir(), `sandbox-client-${randomUUID()}.mjs`);
+  await fs.writeFile(tmpFile, jsCode, "utf8");
+
+  let timedOut = false;
+  const start = Date.now();
+
+  await new Promise<void>((resolve) => {
+    const child = spawn(process.execPath, [tmpFile], {
+      env: { ...process.env, NODE_NO_WARNINGS: "1" },
+    });
+    const killTimer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGKILL");
+      resolve();
+    }, RUN_TIMEOUT_MS);
+
+    // Stream each chunk as it arrives — split on newlines so each log line is its own event
+    const pushChunks = (chunk: Buffer, kind: "stdout" | "stderr") => {
+      chunk
+        .toString()
+        .split("\n")
+        .forEach((line) => {
+          if (line !== "") sendEvent(kind, line);
+        });
+    };
+    child.stdout.on("data", (chunk: Buffer) => pushChunks(chunk, "stdout"));
+    child.stderr.on("data", (chunk: Buffer) => pushChunks(chunk, "stderr"));
+    child.on("close", (code) => {
+      clearTimeout(killTimer);
+      resolve();
+    });
+  });
+
+  fs.unlink(tmpFile).catch(() => {});
+  sendEvent(
+    "done",
+    JSON.stringify({ timedOut, durationMs: Date.now() - start }),
+  );
+  res.end();
+});
+
 // ─── Start ───────────────────────────────────────────────
 
 (async () => {