create-interview-cockpit 0.4.0 → 0.6.0

package/template/server/src/index.ts

@@ -24,41 +24,88 @@ 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";
+import {
+  getInfraRun,
+  listInfraRuns,
+  runInfraAction,
+  streamInfraCommand,
+} from "./infra-runner.js";
 
 const app = express();
 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/")) {
-      cb(null, true);
+    // Block only clearly non-text binary formats (executables, archives, etc.)
+    const blockedExt =
+      /\.(exe|dll|so|dylib|bin|zip|tar|gz|bz2|rar|7z|dmg|iso|mp3|mp4|avi|mov|wmv|flac|wav|class|pyc|wasm)$/i;
+    if (blockedExt.test(file.originalname)) {
+      cb(new Error(`Unsupported file type: ${file.originalname}`));
     } else {
-      cb(new Error("Unsupported file type"));
+      // Accept everything else — extractText handles unknown extensions gracefully
+      cb(null, true);
     }
   },
 });
 
-// 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 || "";
 
@@ -185,12 +232,24 @@ app.post("/api/workspaces/:id/drive-subfolders", async (req, res) => {
   const { name } = req.body as { name?: string };
   if (!name?.trim()) return res.status(400).json({ error: "name required" });
   try {
+    if (!(await googleDrive.isExportAuthed())) {
+      return res.json({
+        needsAuth: true,
+        authUrl: googleDrive.getExportAuthUrl(),
+      });
+    }
     const folder = await googleDrive.createDriveSubfolder(
       req.params.id,
       name.trim(),
     );
     res.json(folder);
   } catch (err: any) {
+    if (err?.needsReauth) {
+      return res.json({
+        needsAuth: true,
+        authUrl: googleDrive.getExportAuthUrl(),
+      });
+    }
     res.status(500).json({ error: err?.message || "Failed to create folder" });
   }
 });
@@ -322,30 +381,104 @@ app.patch("/api/topics/:id", async (req, res) => {
   const topic = topics.find((t) => t.id === req.params.id);
   if (!topic) return res.status(404).json({ error: "Not found" });
   if (typeof req.body.name === "string") topic.name = req.body.name;
+  if (typeof req.body.systemContext === "string")
+    topic.systemContext = req.body.systemContext;
   await storage.saveTopic(topic);
   res.json(topic);
 });
 
-// ─── Topic Context Files ─────────────────────────────────
+// ─── Workspace Context Files ─────────────────────────────
 
-app.post(
-  "/api/topics/:topicId/context-files",
-  upload.array("files", 20),
-  async (req, res) => {
+app.get("/api/workspace/context-files", async (_req, res) => {
+  const files = await storage.getWorkspaceContextFiles();
+  res.json(files);
+});
+
+app.post("/api/workspace/context-files", upload.any(), 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);
-      const cf = await storage.saveContextFile(
-        req.params.topicId as string,
-        randomUUID(),
+      // 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.any(),
+  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);
+        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" });
+    }
   },
 );
 
@@ -354,6 +487,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) => {
@@ -391,12 +554,45 @@ app.patch("/api/questions/:id", async (req, res) => {
   if (req.body.systemContext !== undefined)
     q.systemContext = req.body.systemContext;
   if (req.body.title !== undefined) q.title = req.body.title;
-  if (req.body.parentQuestionId !== undefined)
-    q.parentQuestionId = req.body.parentQuestionId;
+  if (req.body.parentQuestionId !== undefined) {
+    const nextParentId = req.body.parentQuestionId as string | null;
+    if (nextParentId === q.id) {
+      return res.status(400).json({ error: "A question cannot parent itself" });
+    }
+    if (nextParentId != null) {
+      const allInTopic = await storage.getQuestionsByTopic(q.topicId);
+      const parentExists = allInTopic.some(
+        (candidate) => candidate.id === nextParentId,
+      );
+      if (!parentExists) {
+        return res
+          .status(400)
+          .json({ error: "Selected parent question was not found" });
+      }
+      const descendantIds = new Set<string>();
+      const visit = (parentId: string) => {
+        for (const candidate of allInTopic) {
+          if (candidate.parentQuestionId !== parentId) continue;
+          if (descendantIds.has(candidate.id)) continue;
+          descendantIds.add(candidate.id);
+          visit(candidate.id);
+        }
+      };
+      visit(q.id);
+      if (descendantIds.has(nextParentId)) {
+        return res.status(400).json({
+          error: "A question cannot be moved under one of its descendants",
+        });
+      }
+    }
+    q.parentQuestionId = nextParentId ?? undefined;
+  }
   if (req.body.messages !== undefined) q.messages = req.body.messages;
   if (req.body.annotations !== undefined) q.annotations = req.body.annotations;
   if (req.body.readingBookmark !== undefined)
     q.readingBookmark = req.body.readingBookmark;
+  if (req.body.linkedConversationIds !== undefined)
+    q.linkedConversationIds = req.body.linkedConversationIds;
   await storage.saveQuestion(q);
   res.json(q);
 });
@@ -404,35 +600,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),
+  upload.any(),
   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,150 +684,798 @@ app.delete(
   },
 );
 
-// ─── AI Settings ────────────────────────────────────────────
-
-app.get("/api/settings", async (_req, res) => {
-  const settings = await storage.getAiSettings();
-  res.json(settings);
-});
-
-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,
+// 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" | "infra" | "react" | "nextjs";
   };
-  await storage.saveAiSettings(updated);
-  res.json(updated);
+  if (typeof code !== "string" || !code.trim()) {
+    return res.status(400).json({ error: "code is required" });
+  }
+  if (
+    origin !== "user" &&
+    origin !== "ai" &&
+    origin !== "sandbox" &&
+    origin !== "infra" &&
+    origin !== "react" &&
+    origin !== "nextjs"
+  ) {
+    return res.status(400).json({
+      error:
+        "origin must be 'user', 'ai', 'sandbox', 'infra', 'react', or 'nextjs'",
+    });
+  }
+  try {
+    const id = randomUUID();
+    const safeLabel = (label || "snippet").replace(/[/\\:*?"<>|]/g, "-").trim();
+    const ext =
+      language === "typescript"
+        ? "ts"
+        : language === "javascript"
+          ? "js"
+          : language === "infra"
+            ? "infra.json"
+            : "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" });
+  }
 });
 
-// ─── Chat ────────────────────────────────────────────────
-
-app.post("/api/chat", async (req, res) => {
-  const {
-    messages,
-    questionId,
-    topicId,
-    topicTitle,
-    questionTitle,
-    codeContextFiles,
-    codeSnippets,
-    systemContext,
-    responseLength,
-  } = req.body;
-
-  const aiSettings = await storage.getAiSettings();
-  const { responseProfiles, vizGuide } = aiSettings;
-  const selectedResponseProfile = responseProfiles[responseLength] ??
-    responseProfiles["normal"] ?? { maxOutputTokens: 3000, maxSteps: 5 };
-
-  let system = aiSettings.systemPrompt;
+// 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" });
+    }
+  },
+);
 
-  if (topicTitle || questionTitle) {
-    system += `\n\n--- Current Context ---`;
-    if (topicTitle) system += `\nTopic: ${topicTitle}`;
-    if (questionTitle) system += `\nQuestion: ${questionTitle}`;
-  }
+// 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" });
+    }
+  },
+);
 
-  if (systemContext) {
-    system += `\n\n--- Additional Context ---\n${systemContext}`;
+// 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" });
   }
+});
 
-  // Build a file registry: id → { label, reader }
-  // The model sees the list of file names and can call readFile(id) for any of them.
-  const fileRegistry = new Map<
-    string,
-    { label: string; reader: () => Promise<string> }
-  >();
-
-  // Topic-level uploaded files
-  if (topicId) {
-    const topics = await storage.getTopics();
-    const topic = topics.find((t) => 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),
-        });
-      }
-    }
+// 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",
+    });
   }
 
-  // Question-level uploaded files
-  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),
-        });
-      }
+  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,
+      });
     }
   }
 
-  // Code-context files from the project directory
-  if (codeContextFiles?.length && CODE_CONTEXT_DIR) {
-    for (const filePath of codeContextFiles as string[]) {
-      const fullPath = path.join(CODE_CONTEXT_DIR, filePath);
-      const resolved = path.resolve(fullPath);
-      if (!resolved.startsWith(path.resolve(CODE_CONTEXT_DIR))) continue;
-      fileRegistry.set(`code:${filePath}`, {
-        label: `[code] ${filePath}`,
-        reader: () => fs.readFile(resolved, "utf-8"),
+  // 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,
       });
     }
   }
 
-  // Tell the model what files are available
-  if (fileRegistry.size > 0) {
-    // collect just the code-context file paths for linking instructions
-    const codeFilePaths: string[] = [];
-    for (const [id, { label }] of fileRegistry) {
-      if (id.startsWith("code:")) codeFilePaths.push(id.slice("code:".length));
-    }
+  // 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;
+  });
 
-    system += `\n\n--- Available Reference Files ---
-The 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 — you do not need to read them all.
+  res.json(deduped);
+});
 
-`;
-    for (const [id, { label }] of fileRegistry) {
-      system += `• ${label}  (id: "${id}")\n`;
-    }
+app.post("/api/infra/run", async (req, res) => {
+  const { questionId, fileId, label, action, workspace } = req.body as {
+    questionId?: string;
+    fileId?: string;
+    label?: string;
+    action?: "validate" | "plan";
+    workspace?: unknown;
+  };
 
-    if (codeFilePaths.length > 0) {
-      system += `
---- Linking Code Files in Your Response ---
-When you mention or reference one of the **[code]** files above in your response text, format it as a clickable link so the user can open it directly:
+  if (action !== "validate" && action !== "plan") {
+    return res
+      .status(400)
+      .json({ error: "action must be 'validate' or 'plan'" });
+  }
 
-  [DisplayText](coderef://relative/path/to/file)
+  try {
+    const run = await runInfraAction({
+      questionId,
+      fileId,
+      label,
+      action,
+      workspace,
+    });
+    res.json(run);
+  } catch (err: any) {
+    res
+      .status(400)
+      .json({ error: err?.message || "Failed to run infra action" });
+  }
+});
 
-Examples:
-  [EmployeesController](coderef://src/Controllers/EmployeesController.cs)
-  [SettleDeferredPaymentCaseRequest](coderef://src/Requests/SettleDeferredPaymentCaseRequest.cs)
+// ─── Infra Lab AI Ask (streaming) ───────────────────────────────────────────
+app.post("/api/infra/ask", async (req, res) => {
+  const { messages, workspace, questionId } = req.body as {
+    messages?: Array<{ role: "user" | "assistant"; content: string }>;
+    workspace?: Record<string, string>; // { "main.tf": "..." }
+    questionId?: string;
+  };
 
-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.`;
-    }
+  if (!Array.isArray(messages) || messages.length === 0) {
+    return res.status(400).json({ error: "messages is required" });
   }
 
-  // Code snippets hand-picked by the user from the file viewer
-  if (Array.isArray(codeSnippets) && codeSnippets.length > 0) {
+  const isGoogle = ["google", "gemini"].includes(
+    (process.env.AI_PROVIDER || "openai").toLowerCase(),
+  );
+  const aiSettings = await storage.getAiSettings();
+
+  // Build workspace context block
+  let workspaceBlock = "";
+  if (workspace && typeof workspace === "object") {
+    const entries = Object.entries(workspace).filter(
+      ([k, v]) => typeof k === "string" && typeof v === "string",
+    );
+    if (entries.length > 0) {
+      workspaceBlock = "\n\n--- Workspace Files ---\n";
+      for (const [name, content] of entries) {
+        workspaceBlock += `\n### ${name}\n\`\`\`hcl\n${content}\n\`\`\`\n`;
+      }
+    }
+  }
+
+  const system =
+    `You are a senior infrastructure engineer and Terraform expert acting as a coding assistant inside an Infrastructure Lab.\n` +
+    `The user is editing a Terraform workspace. Answer questions about their code clearly and accurately.\n` +
+    `When suggesting edits, show the changed HCL as a fenced \`\`\`hcl code block.\n` +
+    `Be concise unless the user asks for a deeper explanation.` +
+    workspaceBlock;
+
+  try {
+    const result = streamText({
+      model: getModel(),
+      maxOutputTokens: 2000,
+      ...(isGoogle && {
+        providerOptions: {
+          google: {
+            thinkingConfig: { thinkingBudget: aiSettings.thinkingBudget ?? 0 },
+          },
+        },
+      }),
+      system,
+      messages: messages.map((m) => ({ role: m.role, content: m.content })),
+    });
+
+    result.pipeUIMessageStreamToResponse(res);
+  } catch (err: any) {
+    console.error("infra/ask error:", err?.message || err);
+    if (!res.headersSent) {
+      res
+        .status(500)
+        .json({ error: err?.message || "Failed to generate response" });
+    }
+  }
+});
+
+app.post("/api/notes/ask", async (req, res) => {
+  const { messages, noteContent, noteName } = req.body as {
+    messages?: Array<{ role: "user" | "assistant"; content: string }>;
+    noteContent?: string;
+    noteName?: string;
+  };
+
+  if (!Array.isArray(messages) || messages.length === 0) {
+    return res.status(400).json({ error: "messages is required" });
+  }
+
+  const isGoogle = ["google", "gemini"].includes(
+    (process.env.AI_PROVIDER || "openai").toLowerCase(),
+  );
+  const aiSettings = await storage.getAiSettings();
+
+  const noteBlock = noteContent?.trim()
+    ? `\n\n--- Note: ${noteName || "Untitled"} ---\n${noteContent}\n---`
+    : "";
+
+  const system =
+    `You are a knowledgeable study assistant helping the user understand and improve their notes.\n` +
+    `Answer questions about the note content clearly. Help the user expand on ideas, clarify concepts, or drill deeper.\n` +
+    `Be concise unless the user asks for a deeper explanation.` +
+    noteBlock;
+
+  try {
+    const result = streamText({
+      model: getModel(),
+      maxOutputTokens: 2000,
+      ...(isGoogle && {
+        providerOptions: {
+          google: {
+            thinkingConfig: { thinkingBudget: aiSettings.thinkingBudget ?? 0 },
+          },
+        },
+      }),
+      system,
+      messages: messages.map((m) => ({ role: m.role, content: m.content })),
+    });
+
+    result.pipeUIMessageStreamToResponse(res);
+  } catch (err: any) {
+    console.error("notes/ask error:", err?.message || err);
+    if (!res.headersSent) {
+      res
+        .status(500)
+        .json({ error: err?.message || "Failed to generate response" });
+    }
+  }
+});
+
+app.post("/api/frontend-lab/ask", async (req, res) => {
+  const { messages, workspace, labType, questionId } = req.body as {
+    messages?: Array<{ role: "user" | "assistant"; content: string }>;
+    workspace?: Record<string, string>;
+    labType?: "react" | "nextjs";
+    questionId?: string;
+  };
+
+  if (!Array.isArray(messages) || messages.length === 0) {
+    return res.status(400).json({ error: "messages is required" });
+  }
+
+  const isGoogle = ["google", "gemini"].includes(
+    (process.env.AI_PROVIDER || "openai").toLowerCase(),
+  );
+  const aiSettings = await storage.getAiSettings();
+
+  const typeLabel =
+    labType === "nextjs" ? "Next.js App Router" : "React + TypeScript";
+
+  let workspaceBlock = "";
+  if (workspace && typeof workspace === "object") {
+    const entries = Object.entries(workspace).filter(
+      ([k, v]) => typeof k === "string" && typeof v === "string",
+    );
+    if (entries.length > 0) {
+      workspaceBlock = "\n\n--- Workspace Files ---\n";
+      for (const [name, content] of entries) {
+        workspaceBlock += `\n### ${name}\n\`\`\`tsx\n${content}\n\`\`\`\n`;
+      }
+    }
+  }
+
+  const system =
+    `You are an expert ${typeLabel} tutor acting as a coding assistant inside a hands-on lab.\n` +
+    `The user is practising ${typeLabel} concepts. Help them understand their code, fix bugs, and learn best practices.\n` +
+    `When suggesting code changes, use fenced TypeScript/TSX code blocks.\n` +
+    `Be concise unless the user asks for deeper explanation.` +
+    workspaceBlock;
+
+  try {
+    const result = streamText({
+      model: getModel(),
+      maxOutputTokens: 2000,
+      ...(isGoogle && {
+        providerOptions: {
+          google: {
+            thinkingConfig: { thinkingBudget: aiSettings.thinkingBudget ?? 0 },
+          },
+        },
+      }),
+      system,
+      messages: messages.map((m) => ({ role: m.role, content: m.content })),
+    });
+
+    result.pipeUIMessageStreamToResponse(res);
+  } catch (err: any) {
+    console.error("frontend-lab/ask error:", err?.message || err);
+    if (!res.headersSent) {
+      res
+        .status(500)
+        .json({ error: err?.message || "Failed to generate response" });
+    }
+  }
+});
+
+app.post("/api/infra/command-stream", async (req, res) => {
+  const { questionId, fileId, label, command, workspace } = req.body as {
+    questionId?: string;
+    fileId?: string;
+    label?: string;
+    command?: string;
+    workspace?: unknown;
+  };
+
+  res.setHeader("Content-Type", "text/event-stream");
+  res.setHeader("Cache-Control", "no-cache");
+  res.setHeader("Connection", "keep-alive");
+  res.flushHeaders();
+
+  const send = (payload: unknown) => {
+    res.write(`data: ${JSON.stringify(payload)}\n\n`);
+  };
+
+  if (typeof command !== "string" || !command.trim()) {
+    send({ type: "error", error: "command is required" });
+    res.end();
+    return;
+  }
+
+  try {
+    const run = await streamInfraCommand({
+      questionId,
+      fileId,
+      label,
+      command,
+      workspace,
+      onMessage: send,
+    });
+    send({ type: "complete", run });
+  } catch (err: any) {
+    send({
+      type: "error",
+      error: err?.message || "Failed to run infra command",
+    });
+  }
+
+  res.end();
+});
+
+app.get("/api/infra/runs", async (req, res) => {
+  const fileId =
+    typeof req.query.fileId === "string" ? req.query.fileId : undefined;
+  const questionId =
+    typeof req.query.questionId === "string" ? req.query.questionId : undefined;
+
+  try {
+    const runs = await listInfraRuns({ fileId, questionId });
+    res.json(runs);
+  } catch (err: any) {
+    res
+      .status(500)
+      .json({ error: err?.message || "Failed to list infra runs" });
+  }
+});
+
+app.get("/api/infra/runs/:runId", async (req, res) => {
+  try {
+    const run = await getInfraRun(req.params.runId);
+    res.json(run);
+  } catch {
+    res.status(404).json({ error: "Infra run not found" });
+  }
+});
+
+// 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,
+    plotGuide:
+      typeof req.body.plotGuide === "string"
+        ? req.body.plotGuide
+        : current.plotGuide,
+    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) => {
+  const {
+    messages,
+    questionId,
+    topicId,
+    topicTitle,
+    questionTitle,
+    codeContextFiles,
+    codeSnippets,
+    systemContext,
+    responseLength,
+    linkedConversationIds,
+  } = req.body;
+
+  const aiSettings = await storage.getAiSettings();
+  const { responseProfiles, vizGuide, plotGuide } = aiSettings;
+  const selectedResponseProfile = responseProfiles[responseLength] ??
+    responseProfiles["normal"] ?? { maxOutputTokens: 3000, maxSteps: 5 };
+
+  let system = aiSettings.systemPrompt;
+
+  if (topicTitle || questionTitle) {
+    system += `\n\n--- Current Context ---`;
+    if (topicTitle) system += `\nTopic: ${topicTitle}`;
+    if (questionTitle) system += `\nQuestion: ${questionTitle}`;
+  }
+
+  if (systemContext) {
+    system += `\n\n--- Additional Context ---\n${systemContext}`;
+  }
+  if (
+    Array.isArray(linkedConversationIds) &&
+    linkedConversationIds.length > 0
+  ) {
+    const linkedQuestions = await Promise.all(
+      linkedConversationIds.map((id: string) => storage.getQuestion(id)),
+    );
+    const valid = linkedQuestions.filter(
+      (q) => q && q.messages && q.messages.length > 0,
+    ) as storage.Question[];
+    if (valid.length > 0) {
+      system += `\n\n--- Linked Conversation${valid.length > 1 ? "s" : ""} (read-only reference) ---\nThe user has linked the following conversation${valid.length > 1 ? "s" : ""} from this topic as background context. Do not treat them as the current conversation — they are reference material only.\n`;
+      for (const lq of valid) {
+        system += `\n### "${lq.title}"\n`;
+        for (const msg of lq.messages) {
+          const role = msg.role === "user" ? "User" : "Assistant";
+          const text =
+            typeof msg.content === "string"
+              ? msg.content
+              : (msg.parts
+                  ?.filter((p: any) => p.type === "text")
+                  .map((p: any) => p.text)
+                  .join("") ?? "");
+          system += `**${role}:** ${text.slice(0, 2000)}${text.length > 2000 ? "…" : ""}\n\n`;
+        }
+      }
+    }
+  }
+
+  // Build a file registry: id → { label, reader }
+  // The model sees the list of file names and can call readFile(id) for any of them.
+  const fileRegistry = new Map<
+    string,
+    { 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 + topic-wide system prompt
+  if (topicId) {
+    const topics = await storage.getTopics();
+    const topic = topics.find((t) => t.id === topicId);
+    if (topic?.systemContext?.trim()) {
+      system += `\n\n--- Topic-Wide System Context ---\n${topic.systemContext.trim()}`;
+    }
+    if (topic?.contextFiles?.length) {
+      for (const cf of topic.contextFiles) {
+        fileRegistry.set(cf.id, {
+          label: `[topic] ${cf.originalName}`,
+          reader: () => storage.readContextFileContent(cf.id),
+        });
+      }
+    }
+  }
+
+  // Question-level uploaded files
+  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),
+        });
+      }
+    }
+  }
+
+  // Code-context files from the project directory
+  if (codeContextFiles?.length && CODE_CONTEXT_DIR) {
+    for (const filePath of codeContextFiles as string[]) {
+      const fullPath = path.join(CODE_CONTEXT_DIR, filePath);
+      const resolved = path.resolve(fullPath);
+      if (!resolved.startsWith(path.resolve(CODE_CONTEXT_DIR))) continue;
+      fileRegistry.set(`code:${filePath}`, {
+        label: `[code] ${filePath}`,
+        reader: () => fs.readFile(resolved, "utf-8"),
+      });
+    }
+  }
+
+  // Tell the model what files are available
+  if (fileRegistry.size > 0) {
+    // collect just the code-context file paths for linking instructions
+    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 ---
+The 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 — you do not need to read them all.
+
+`;
+    for (const [id, { label }] of fileRegistry) {
+      system += `• ${label}  (id: "${id}")\n`;
+    }
+
+    if (codeFilePaths.length > 0) {
+      system += `
+--- Linking Code Files in Your Response ---
+When you mention or reference one of the **[code]** files above in your response text, format it as a clickable link so the user can open it directly:
+
+  [DisplayText](coderef://relative/path/to/file)
+
+Examples:
+  [EmployeesController](coderef://src/Controllers/EmployeesController.cs)
+  [SettleDeferredPaymentCaseRequest](coderef://src/Requests/SettleDeferredPaymentCaseRequest.cs)
+
+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
+  if (Array.isArray(codeSnippets) && codeSnippets.length > 0) {
     system += `\n\n--- Code Snippets (highlighted by user) ---\nThe user has selected these specific sections of code as focus areas for this conversation:\n\n`;
     for (const snippet of codeSnippets as Array<{
       fileName: string;
@@ -625,7 +1510,9 @@ 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,
@@ -637,6 +1524,12 @@ Only use coderef:// for [code] files. Do not use it for uploaded documents.`;
           inputSchema: z.object({}),
           execute: async () => ({ guide: vizGuide }),
         }),
+        getPlotGuide: tool({
+          description:
+            "Get the full plotting spec reference. Call this before writing a ```plot block so you use the supported schema for graphs, curves, and charts.",
+          inputSchema: z.object({}),
+          execute: async () => ({ guide: plotGuide }),
+        }),
         ...(fileRegistry.size > 0
           ? {
               readFile: tool({
@@ -795,33 +1688,204 @@ async function walkDir(dir: string, prefix = ""): Promise<string[]> {
   return files;
 }
 
-app.get("/api/code-context/tree", async (_req, res) => {
-  if (!CODE_CONTEXT_DIR) return res.json([]);
-  try {
-    const files = await walkDir(CODE_CONTEXT_DIR);
-    res.json(files);
-  } catch {
-    res.json([]);
-  }
-});
+app.get("/api/code-context/tree", async (_req, res) => {
+  if (!CODE_CONTEXT_DIR) return res.json([]);
+  try {
+    const files = await walkDir(CODE_CONTEXT_DIR);
+    res.json(files);
+  } catch {
+    res.json([]);
+  }
+});
+
+app.get("/api/code-context/file", async (req, res) => {
+  if (!CODE_CONTEXT_DIR)
+    return res.status(400).json({ error: "No code context directory" });
+  const filePath = req.query.path as string;
+  if (!filePath) return res.status(400).json({ error: "Path required" });
+
+  const fullPath = path.join(CODE_CONTEXT_DIR, filePath);
+  const resolved = path.resolve(fullPath);
+  if (!resolved.startsWith(path.resolve(CODE_CONTEXT_DIR))) {
+    return res.status(403).json({ error: "Access denied" });
+  }
+
+  try {
+    const content = await fs.readFile(resolved, "utf-8");
+    res.json({ path: filePath, content });
+  } catch {
+    res.status(404).json({ error: "File not found" });
+  }
+});
+
+// ─── 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`;
+      }
 
-app.get("/api/code-context/file", async (req, res) => {
-  if (!CODE_CONTEXT_DIR)
-    return res.status(400).json({ error: "No code context directory" });
-  const filePath = req.query.path as string;
-  if (!filePath) return res.status(400).json({ error: "Path required" });
+      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.`;
+      }
+    }
 
-  const fullPath = path.join(CODE_CONTEXT_DIR, filePath);
-  const resolved = path.resolve(fullPath);
-  if (!resolved.startsWith(path.resolve(CODE_CONTEXT_DIR))) {
-    return res.status(403).json({ error: "Access denied" });
-  }
+    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`;
+      }
+    }
 
-  try {
-    const content = await fs.readFile(resolved, "utf-8");
-    res.json({ path: filePath, content });
-  } catch {
-    res.status(404).json({ error: "File not found" });
+    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" });
   }
 });
 
@@ -837,6 +1901,7 @@ app.post("/api/inline-ask", async (req, res) => {
     responseLength,
     responseStyle,
     responseAudience,
+    preferenceSuffix,
   } = req.body;
   if (typeof selectedText !== "string" || typeof prompt !== "string") {
     return res
@@ -849,6 +1914,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) {
@@ -884,13 +1951,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"),
@@ -927,13 +2003,13 @@ app.post("/api/fix-viz", async (req, res) => {
 
     const { text } = await generateText({
       model: getModel(),
-      maxOutputTokens: 1200,
+      maxOutputTokens: 8000,
       ...(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- 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- 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}`,
+      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.\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.\n- YAML string quoting: ALWAYS use double quotes for ALL string values — NEVER single quotes. Single-quoted YAML values (e.g. fill: '#fff') cause "Flow map must end with a }" parse errors in yaml v2. Every string in the spec must use double quotes. Wrong: fill: '#1e40af'  Correct: fill: "#1e40af"\n- Inline flow maps must be single-line: any node written as { id: foo, x: 1, ... } MUST have its opening { and closing } on the SAME line with no line breaks inside. The yaml v2 parser throws "Flow map must end with a }" when a flow map spans multiple lines. If a flow map is too long to fit on one line, convert it to block style (indented key: value pairs), but NEVER split a single { ... } across lines.\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
@@ -949,6 +2025,107 @@ app.post("/api/fix-viz", async (req, res) => {
   }
 });
 
+// ─── Fix Plot ───────────────────────────────────────────
+
+app.post("/api/fix-plot", 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 { plotGuide } = await storage.getAiSettings();
+    const isGoogle = ["google", "gemini"].includes(
+      (process.env.AI_PROVIDER || "openai").toLowerCase(),
+    );
+
+    const { text } = await generateText({
+      model: getModel(),
+      maxOutputTokens: 4000,
+      ...(isGoogle && {
+        providerOptions: {
+          google: { thinkingConfig: { thinkingBudget: 0 } },
+        },
+      }),
+      prompt: `The following plot spec failed to render.${renderError ? `\n\nRender error:\n${renderError}` : ""}${plotGuide ? `\n\nSupported plotting guide:\n${plotGuide}` : ""}\n\nFix the spec so it renders correctly as a Vega-Lite plot.\nRules:\n- Return ONLY the corrected JSON or YAML spec with no explanation and no markdown fences\n- The spec must describe a valid Vega-Lite chart\n- Prefer simple, valid encodings over clever transforms\n- Ensure x and y encodings include valid field/type definitions when needed\n- If the chart represents a mathematical curve, provide concrete sampled data points instead of symbolic expressions\n- Keep the dark-theme friendly defaults implicit; do not add custom JS callbacks or unsupported runtime code\n\nFailed spec:\n${spec}`,
+    });
+
+    const fixed = text
+      .replace(/^```(?:plot|vega|vega-lite|json|yaml)?\s*/i, "")
+      .replace(/```\s*$/, "")
+      .trim();
+
+    res.json({ spec: fixed });
+  } catch (err: any) {
+    console.error("fix-plot error:", err?.message || err);
+    res.status(500).json({ error: err?.message || "Failed to fix plot" });
+  }
+});
+
+// ─── 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: 8000,
+      ...(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) => {
@@ -987,6 +2164,531 @@ 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().replace(/\x1b\[[0-9;]*[A-Za-z]/g, ""));
+    });
+    child.stderr.on("data", (chunk: Buffer) => {
+      stderrLines.push(chunk.toString().replace(/\x1b\[[0-9;]*[A-Za-z]/g, ""));
+    });
+    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");
+
+// ── Next.js real-server sandboxes ────────────────────────────────────────────
+// We symlink node_modules from the pre-installed npx cache so there's
+// zero npm-install cost per sandbox.
+interface NextSandboxEntry {
+  child: ReturnType<typeof spawn>;
+  port: number;
+  dir: string;
+  logs: string[];
+  ready: boolean;
+}
+const nextSandboxes = new Map<string, NextSandboxEntry>();
+const NEXT_NPX_DIR = path.join(os.homedir(), ".npm/_npx/8b377f6eec906bc4");
+const NEXT_MODULES_DIR = path.join(NEXT_NPX_DIR, "node_modules");
+// Sandboxes live INSIDE the npx cache dir so Next.js finds node_modules by
+// walking up the directory tree — no symlinks needed, no Turbopack restrictions.
+const NEXT_SANDBOX_BASE = path.join(NEXT_NPX_DIR, ".sandboxes");
+
+/** Write all user files and necessary config into a sandbox directory. */
+async function writeNextSandboxFiles(
+  dir: string,
+  files: Record<string, string>,
+) {
+  // package.json — needed so Next.js can resolve its own packages
+  await fs.writeFile(
+    path.join(dir, "package.json"),
+    JSON.stringify(
+      {
+        name: "nextjs-lab",
+        private: true,
+        type: "module",
+        dependencies: {
+          next: "^16.2.4",
+          react: "^19.0.0",
+          "react-dom": "^19.0.0",
+        },
+      },
+      null,
+      2,
+    ),
+  );
+  // next.config.ts — set turbopack.root to the NPX cache dir (parent of both
+  // node_modules and .sandboxes). This lets Turbopack find next/package.json
+  // in node_modules while watching files within the sandbox subdirectory.
+  // Setting it to the sandbox dir itself would block node_modules resolution
+  // since node_modules sits above the sandbox root boundary.
+  await fs.writeFile(
+    path.join(dir, "next.config.ts"),
+    `import type { NextConfig } from "next";
+const c: NextConfig = {
+  turbopack: { root: ${JSON.stringify(NEXT_NPX_DIR)} },
+  async headers() {
+    return [{ source: "/(.*)", headers: [{ key: "X-Frame-Options", value: "ALLOWALL" }] }];
+  },
+};
+export default c;\n`,
+  );
+  // tsconfig so Next.js TypeScript support works
+  await fs.writeFile(
+    path.join(dir, "tsconfig.json"),
+    JSON.stringify(
+      {
+        compilerOptions: {
+          lib: ["dom", "dom.iterable", "esnext"],
+          allowJs: true,
+          skipLibCheck: true,
+          strict: false,
+          noEmit: true,
+          esModuleInterop: true,
+          module: "esnext",
+          moduleResolution: "bundler",
+          resolveJsonModule: true,
+          isolatedModules: true,
+          jsx: "preserve",
+          incremental: true,
+          plugins: [{ name: "next" }],
+          baseUrl: ".",
+        },
+        include: ["**/*.ts", "**/*.tsx"],
+        exclude: ["node_modules"],
+      },
+      null,
+      2,
+    ),
+  );
+  // User files
+  for (const [filePath, content] of Object.entries(files)) {
+    const fullPath = path.join(dir, filePath);
+    await fs.mkdir(path.dirname(fullPath), { recursive: true });
+    await fs.writeFile(fullPath, content, "utf8");
+  }
+}
+
+app.post("/api/nextjs/start", async (req, res) => {
+  const { files } = req.body as { files: Record<string, string> };
+  if (!files || typeof files !== "object") {
+    return res.status(400).json({ error: "files is required" });
+  }
+
+  // Use the actual file path (not the .bin symlink) so Node's __filename resolves
+  // correctly and internal require("../server/require-hook") works.
+  const nextBin = path.join(NEXT_MODULES_DIR, "next", "dist", "bin", "next");
+  const nextExists = await fs
+    .access(nextBin)
+    .then(() => true)
+    .catch(() => false);
+  if (!nextExists) {
+    return res.status(503).json({
+      error:
+        "Next.js is not available in the npx cache. Run `npx next --version` once to install it.",
+    });
+  }
+
+  const id = randomUUID();
+  const dir = path.join(NEXT_SANDBOX_BASE, id);
+  await fs.mkdir(dir, { recursive: true });
+
+  await writeNextSandboxFiles(dir, files);
+
+  const port = await getFreePort();
+  const logs: string[] = [];
+  // Run via `node <actual-bin>` — sandbox dir is inside the npx cache so
+  // node_modules is resolved naturally two levels up; no symlinks required.
+  const child = spawn(
+    process.execPath,
+    [nextBin, "dev", "--port", String(port)],
+    {
+      cwd: dir,
+      env: {
+        ...process.env,
+        NEXT_TELEMETRY_DISABLED: "1",
+        NODE_NO_WARNINGS: "1",
+      },
+    },
+  );
+
+  const entry: NextSandboxEntry = {
+    child,
+    port,
+    dir,
+    logs,
+    ready: false,
+  };
+  nextSandboxes.set(id, entry);
+
+  const markReady = (text: string) => {
+    if (!entry.ready && /ready|started server on|Local:/i.test(text)) {
+      entry.ready = true;
+    }
+  };
+  child.stdout.on("data", (chunk: Buffer) => {
+    const t = chunk.toString().replace(/\x1b\[[0-9;]*[A-Za-z]/g, "");
+    logs.push(t);
+    markReady(t);
+  });
+  child.stderr.on("data", (chunk: Buffer) => {
+    const t = chunk.toString().replace(/\x1b\[[0-9;]*[A-Za-z]/g, "");
+    logs.push(t);
+    markReady(t);
+  });
+  child.on("exit", () => {
+    nextSandboxes.delete(id);
+    fs.rm(dir, { recursive: true, force: true }).catch(() => {});
+  });
+
+  // Wait up to 30 s for Next.js to be ready
+  const deadline = Date.now() + 30_000;
+  while (!entry.ready && Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 400));
+    if (!nextSandboxes.has(id)) {
+      return res
+        .status(500)
+        .json({ error: logs.join("").trim() || "Next.js server exited" });
+    }
+  }
+  if (!entry.ready) {
+    return res
+      .status(504)
+      .json({ error: "Next.js did not start in time", logs });
+  }
+
+  res.json({ id, port, url: `http://localhost:${port}` });
+});
+
+app.post("/api/nextjs/:id/update-files", async (req, res) => {
+  const sb = nextSandboxes.get(req.params.id);
+  if (!sb) return res.status(404).json({ error: "Sandbox not found" });
+  const { files } = req.body as { files: Record<string, string> };
+  if (!files) return res.status(400).json({ error: "files is required" });
+  for (const [filePath, content] of Object.entries(files)) {
+    const fullPath = path.join(sb.dir, filePath);
+    await fs.mkdir(path.dirname(fullPath), { recursive: true });
+    await fs.writeFile(fullPath, content, "utf8");
+  }
+  res.json({ ok: true });
+});
+
+app.get("/api/nextjs/:id/status", (req, res) => {
+  const sb = nextSandboxes.get(req.params.id);
+  if (!sb) return res.json({ running: false });
+  res.json({
+    running: true,
+    ready: sb.ready,
+    port: sb.port,
+    logs: sb.logs.slice(-30),
+  });
+});
+
+app.delete("/api/nextjs/:id", async (req, res) => {
+  const sb = nextSandboxes.get(req.params.id);
+  if (sb) {
+    sb.child.kill("SIGTERM");
+    nextSandboxes.delete(req.params.id);
+    await fs.rm(sb.dir, { recursive: true, force: true }).catch(() => {});
+  }
+  res.json({ ok: true });
+});
+
+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().replace(/\x1b\[[0-9;]*[A-Za-z]/g, "")),
+  );
+  child.stderr.on("data", (chunk: Buffer) =>
+    logs.push(chunk.toString().replace(/\x1b\[[0-9;]*[A-Za-z]/g, "")),
+  );
+  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 () => {