pi-interview 0.3.1 → 0.4.0

package/README.md

@@ -32,6 +32,7 @@ The tool is automatically discovered on next pi session. No build step required.
 - **Multi-Agent Support**: Queue detection prevents focus stealing when multiple agents run interviews
 - **Queue Toast Switcher**: Active interviews show a top-right toast with a dropdown to open queued sessions
 - **Session Recovery**: Abandoned/timed-out interviews save questions for later retry
+- **Save Snapshots**: Save interview state to HTML for later review or revival
 - **Session Status Bar**: Shows project path, git branch, and session ID for identification
 - **Image Support**: Drag & drop anywhere on question, file picker, paste image or path
 - **Path Normalization**: Handles shell-escaped paths (`\ `) and macOS screenshot filenames (narrow no-break space before AM/PM)
@@ -205,6 +206,8 @@ Settings in `~/.pi/agent/settings.json`:
   "interview": {
     "timeout": 600,
     "port": 19847,
+    "snapshotDir": "~/.pi/interview-snapshots/",
+    "autoSaveOnSubmit": true,
     "theme": {
       "mode": "auto",
       "name": "default",
@@ -218,6 +221,10 @@ Settings in `~/.pi/agent/settings.json`:
 
 **Timeout precedence**: params > settings > default (600s)
 
+**Snapshot settings:**
+- `snapshotDir`: Directory for saved interview snapshots (default: `~/.pi/interview-snapshots/`)
+- `autoSaveOnSubmit`: Automatically save snapshot on successful submit (default: `true`)
+
 **Port setting**: Set a fixed `port` (e.g., `19847`) to use a consistent port across sessions.
 
 **Theme notes:**
@@ -338,6 +345,45 @@ If an interview times out or is abandoned (tab closed, lost connection), the que
 interview({ questions: "~/.pi/interview-recovery/2026-01-02_093000_myproject_main_65bec3f4.json" })
 ```
 
+## Saving Interviews
+
+Save a snapshot of your interview at any time for later review or to resume.
+
+**Manual Save:**
+- Click the Save button (header or footer)
+- Saves to `~/.pi/interview-snapshots/` by default
+- Creates folder with `index.html` + `images/` subfolder
+
+**Auto-save on Submit:**
+- Enabled by default (`autoSaveOnSubmit: true` in settings)
+- Automatically saves after successful submission
+- Folder name includes `-submitted` suffix
+
+**Reviving a Saved Interview:**
+```javascript
+interview({ questions: "~/.pi/interview-snapshots/project-setup-myapp-main-2026-01-20-141523/index.html" })
+```
+The form opens with answers pre-populated. Edit and submit as normal.
+
+**Configuration:**
+```json
+{
+  "interview": {
+    "snapshotDir": "~/.pi/interview-snapshots/",
+    "autoSaveOnSubmit": true
+  }
+}
+```
+
+**Snapshot Structure:**
+```
+~/.pi/interview-snapshots/
+  {title}-{project}-{branch}-{timestamp}[-submitted]/
+    index.html          # Human-readable + embedded JSON for revival
+    images/
+      mockup.png        # Uploaded images (relative paths in HTML)
+```
+
 ## Limits
 
 - Max 12 images total per submission

package/form/index.html

@@ -17,6 +17,7 @@
     <header class="interview-header">
       <div class="header-row">
         <h1 id="form-title"></h1>
+        <button type="button" class="save-btn-header" id="save-btn-header" title="Save snapshot">Save</button>
       </div>
       <p id="form-description"></p>
     </header>
@@ -27,6 +28,7 @@
       <div id="error-container" aria-live="polite" class="error-message hidden"></div>
 
       <footer class="form-footer">
+        <button type="button" id="save-btn-footer" class="btn-secondary">Save</button>
         <button type="submit" id="submit-btn" class="btn-primary">Submit</button>
       </footer>
     </form>
@@ -109,6 +111,8 @@
         </div>
       </div>
     </div>
+
+    <div id="save-toast" class="save-toast hidden" aria-live="polite"></div>
   </main>
 
   <script>

package/form/script.js

@@ -323,7 +323,8 @@
   function sendCancelBeacon(reason) {
     if (session.cancelSent || session.ended) return;
     session.cancelSent = true;
-    const payload = JSON.stringify({ token: sessionToken, reason });
+    const responses = collectResponses();
+    const payload = JSON.stringify({ token: sessionToken, reason, responses });
     if (navigator.sendBeacon) {
       const blob = new Blob([payload], { type: "application/json" });
       navigator.sendBeacon("/cancel", blob);
@@ -343,11 +344,12 @@
     session.cancelSent = true;
     stopHeartbeat();
     stopQueuePolling();
+    const responses = collectResponses();
     try {
       await fetch("/cancel", {
         method: "POST",
         headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ token: sessionToken, reason }),
+        body: JSON.stringify({ token: sessionToken, reason, responses }),
       });
     } catch (_err) {}
   }
@@ -1968,6 +1970,65 @@
     }
   }
 
+  // Set storage key without loading (for revival from saved interview)
+  async function initStorageKeyOnly() {
+    try {
+      const hash = await hashQuestions();
+      session.storageKey = `pi-interview-${hash}`;
+    } catch (_err) {
+      session.storageKey = null;
+    }
+  }
+
+  // Pre-populate form from saved interview answers
+  function populateFromSavedAnswers(savedAnswers) {
+    // Convert ResponseItem[] to Record for existing populateForm()
+    const valueMap = {};
+    savedAnswers.forEach((ans) => {
+      const question = questions.find((q) => q.id === ans.id);
+      if (question?.type !== "image") {
+        valueMap[ans.id] = ans.value;
+      }
+    });
+    populateForm(valueMap);
+
+    // Restore attachments to attachPathState
+    savedAnswers.forEach((ans) => {
+      if (ans.attachments && ans.attachments.length > 0) {
+        attachPathState.set(ans.id, [...ans.attachments]);
+        attachments.render(ans.id);
+        const panel = document.querySelector(
+          `[data-attach-inline-for="${escapeSelector(ans.id)}"]`
+        );
+        if (panel) panel.classList.remove("hidden");
+        const btn = document.querySelector(
+          `.attach-btn[data-question-id="${escapeSelector(ans.id)}"]`
+        );
+        if (btn) btn.classList.add("has-attachment");
+      }
+    });
+
+    // Restore image paths for image-type questions
+    savedAnswers.forEach((ans) => {
+      const question = questions.find((q) => q.id === ans.id);
+      if (question?.type === "image" && ans.value) {
+        const paths = Array.isArray(ans.value) ? ans.value : [ans.value];
+        const validPaths = paths.filter((p) => typeof p === "string" && p);
+        if (validPaths.length > 0) {
+          imagePathState.set(ans.id, validPaths);
+          questionImages.render(ans.id);
+        }
+      }
+    });
+
+    // Update done states for multi-select
+    questions.forEach((q) => {
+      if (q.type === "multi") {
+        updateDoneState(q.id);
+      }
+    });
+  }
+
   function readFileBase64(file) {
     return new Promise((resolve, reject) => {
       const reader = new FileReader();
@@ -2020,6 +2081,54 @@
     return { responses, images };
   }
 
+  // Save interview snapshot
+  async function saveInterview(options = {}) {
+    const { submitted = false } = options;
+
+    try {
+      const payload = await buildPayload();
+      const response = await fetch("/save", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          token: sessionToken,
+          responses: payload.responses,
+          images: payload.images,
+          submitted,
+        }),
+      });
+      const result = await response.json();
+      if (result.ok) {
+        showSaveSuccess(result.relativePath);
+        return true;
+      } else {
+        if (!submitted) showSaveError(result.error);
+        return false;
+      }
+    } catch (err) {
+      if (!submitted) {
+        showSaveError("Failed to save interview");
+      }
+      return false;
+    }
+  }
+
+  function showSaveSuccess(savePath) {
+    const toast = document.getElementById("save-toast");
+    if (!toast) return;
+    toast.textContent = `Saved to ${savePath}`;
+    toast.className = "save-toast success";
+    setTimeout(() => toast.classList.add("hidden"), 3000);
+  }
+
+  function showSaveError(message) {
+    const toast = document.getElementById("save-toast");
+    if (!toast) return;
+    toast.textContent = message || "Save failed";
+    toast.className = "save-toast error";
+    setTimeout(() => toast.classList.add("hidden"), 3000);
+  }
+
   async function submitForm(event) {
     event.preventDefault();
     clearGlobalError();
@@ -2035,18 +2144,24 @@
         body: JSON.stringify({ token: sessionToken, ...payload }),
       });
 
-      const data = await response.json().catch(() => ({ ok: false, error: "Invalid server response" }));
+      const result = await response.json().catch(() => ({ ok: false, error: "Invalid server response" }));
 
-      if (!response.ok || !data.ok) {
-        if (data.field) {
-          setFieldError(data.field, data.error || "Invalid input");
+      if (!response.ok || !result.ok) {
+        if (result.field) {
+          setFieldError(result.field, result.error || "Invalid input");
         } else {
-          showGlobalError(data.error || "Submission failed.");
+          showGlobalError(result.error || "Submission failed.");
         }
         submitBtn.disabled = false;
         return;
       }
 
+      // Auto-save on successful submit (fire-and-forget)
+      // Note: data is window.__INTERVIEW_DATA__, result is server response
+      if (data.autoSaveOnSubmit !== false) {
+        saveInterview({ submitted: true });
+      }
+
       clearProgress();
       stopHeartbeat();
       stopQueuePolling();
@@ -2096,11 +2211,28 @@
       containerEl.appendChild(createQuestionCard(question, index));
     });
 
-    initStorage();
+    // Pre-populate: savedAnswers takes precedence over localStorage
+    if (data.savedAnswers && Array.isArray(data.savedAnswers)) {
+      populateFromSavedAnswers(data.savedAnswers);
+      initStorageKeyOnly();
+    } else {
+      initStorage();
+    }
+
     startHeartbeat();
     startQueuePolling();
 
     formEl.addEventListener("submit", submitForm);
+
+    // Wire up save buttons
+    const saveBtnHeader = document.getElementById("save-btn-header");
+    const saveBtnFooter = document.getElementById("save-btn-footer");
+    if (saveBtnHeader) {
+      saveBtnHeader.addEventListener("click", () => saveInterview());
+    }
+    if (saveBtnFooter) {
+      saveBtnFooter.addEventListener("click", () => saveInterview());
+    }
     if (queueToastClose) {
       queueToastClose.addEventListener("click", () => {
         queueState.dismissed = true;

package/form/styles.css

@@ -1409,3 +1409,62 @@ button {
   margin-bottom: 1rem;
 }
 
+/* Save button in header */
+.save-btn-header {
+  background: transparent;
+  border: 1px solid var(--border-muted);
+  color: var(--fg-muted);
+  padding: 4px 8px;
+  font-size: 11px;
+  border-radius: var(--radius);
+  cursor: pointer;
+  transition: border-color 150ms ease, color 150ms ease;
+  font-family: var(--font-ui);
+}
+
+.save-btn-header:hover {
+  border-color: var(--fg-dim);
+  color: var(--fg);
+}
+
+.save-btn-header:focus {
+  outline: none;
+  border-color: var(--border-focus);
+}
+
+/* Save toast notification */
+.save-toast {
+  position: fixed;
+  bottom: 80px;
+  left: 50%;
+  transform: translateX(-50%);
+  background: var(--bg-elevated);
+  border: 1px solid var(--border-muted);
+  border-radius: var(--radius);
+  padding: 10px 16px;
+  font-size: 12px;
+  z-index: 150;
+  animation: toast-in 200ms ease-out;
+}
+
+.save-toast.success {
+  border-color: var(--success);
+  color: var(--success);
+}
+
+.save-toast.error {
+  border-color: var(--error);
+  color: var(--error);
+}
+
+@keyframes toast-in {
+  from {
+    opacity: 0;
+    transform: translateX(-50%) translateY(10px);
+  }
+  to {
+    opacity: 1;
+    transform: translateX(-50%) translateY(0);
+  }
+}
+

package/index.ts

@@ -54,8 +54,22 @@ interface InterviewDetails {
 	queuedMessage?: string;
 }
 
+// Types for saved interviews
+interface SavedFromMeta {
+	cwd: string;
+	branch: string | null;
+	sessionId: string;
+}
+
+interface SavedQuestionsFile extends QuestionsFile {
+	savedAnswers?: ResponseItem[];
+	savedAt?: string;
+	wasSubmitted?: boolean;
+	savedFrom?: SavedFromMeta;
+}
+
 const InterviewParams = Type.Object({
-	questions: Type.String({ description: "Path to questions JSON file" }),
+	questions: Type.String({ description: "Path to questions JSON or saved interview HTML file" }),
 	timeout: Type.Optional(
 		Type.Number({ description: "Seconds before auto-timeout", default: 600 })
 	),
@@ -63,7 +77,7 @@ const InterviewParams = Type.Object({
 	theme: Type.Optional(
 		Type.Object(
 			{
-				mode: Type.Optional(Type.Union([Type.Literal("auto"), Type.Literal("light"), Type.Literal("dark")])),
+				mode: Type.Optional(Type.String({ description: "Theme mode: 'auto', 'light', or 'dark'" })),
 				name: Type.Optional(Type.String()),
 				lightPath: Type.Optional(Type.String()),
 				darkPath: Type.Optional(Type.String()),
@@ -75,7 +89,11 @@ const InterviewParams = Type.Object({
 });
 
 function expandHome(value: string): string {
-	if (value.startsWith("~" + path.sep)) {
+	if (value === "~") {
+		return os.homedir();
+	}
+	// Handle both Unix (/) and Windows (\) separators for user convenience
+	if (value.startsWith("~/") || value.startsWith("~\\")) {
 		return path.join(os.homedir(), value.slice(2));
 	}
 	return value;
@@ -103,18 +121,27 @@ function mergeThemeConfig(
 	};
 }
 
-function loadQuestions(questionsPath: string, cwd: string): QuestionsFile {
-	const absolutePath = path.isAbsolute(questionsPath)
-		? questionsPath
-		: path.join(cwd, questionsPath);
+function loadQuestions(questionsPath: string, cwd: string): SavedQuestionsFile {
+	// Expand ~ first, then check if absolute
+	const expanded = expandHome(questionsPath);
+	const absolutePath = path.isAbsolute(expanded)
+		? expanded
+		: path.join(cwd, questionsPath); // Use original if relative (no ~)
 
 	if (!fs.existsSync(absolutePath)) {
 		throw new Error(`Questions file not found: ${absolutePath}`);
 	}
 
+	const content = fs.readFileSync(absolutePath, "utf-8");
+
+	// Handle HTML files (saved interviews)
+	if (absolutePath.endsWith(".html") || absolutePath.endsWith(".htm")) {
+		return loadSavedInterview(content, absolutePath);
+	}
+
+	// Original JSON handling
 	let data: unknown;
 	try {
-		const content = fs.readFileSync(absolutePath, "utf-8");
 		data = JSON.parse(content);
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
@@ -124,6 +151,81 @@ function loadQuestions(questionsPath: string, cwd: string): QuestionsFile {
 	return validateQuestions(data);
 }
 
+function loadSavedInterview(html: string, filePath: string): SavedQuestionsFile {
+	// Extract JSON from <script id="pi-interview-data">
+	const match = html.match(/<script[^>]+id=["']pi-interview-data["'][^>]*>([\s\S]*?)<\/script>/i);
+	if (!match) {
+		throw new Error("Invalid saved interview: missing embedded data");
+	}
+
+	let data: unknown;
+	try {
+		data = JSON.parse(match[1]);
+	} catch {
+		throw new Error("Invalid saved interview: malformed JSON");
+	}
+
+	const raw = data as Record<string, unknown>;
+	const validated = validateQuestions(data);
+
+	// Resolve relative image paths to absolute based on HTML file location
+	const snapshotDir = path.dirname(filePath);
+	const savedAnswers = Array.isArray(raw.savedAnswers)
+		? resolveAnswerPaths(raw.savedAnswers as ResponseItem[], snapshotDir)
+		: undefined;
+
+	// Validate savedFrom if present
+	let savedFrom: SavedFromMeta | undefined;
+	if (raw.savedFrom && typeof raw.savedFrom === "object") {
+		const sf = raw.savedFrom as Record<string, unknown>;
+		if (typeof sf.cwd === "string" && typeof sf.sessionId === "string") {
+			savedFrom = {
+				cwd: sf.cwd,
+				branch: typeof sf.branch === "string" ? sf.branch : null,
+				sessionId: sf.sessionId,
+			};
+		}
+	}
+
+	// Return validated questions plus saved interview metadata
+	return {
+		...validated,
+		savedAnswers,
+		savedAt: typeof raw.savedAt === "string" ? raw.savedAt : undefined,
+		wasSubmitted: typeof raw.wasSubmitted === "boolean" ? raw.wasSubmitted : undefined,
+		savedFrom,
+	};
+}
+
+function resolveAnswerPaths(answers: ResponseItem[], baseDir: string): ResponseItem[] {
+	return answers.map((ans) => ({
+		...ans,
+		value: resolvePathValue(ans.value, baseDir),
+		attachments: ans.attachments?.map((p) => resolveImagePath(p, baseDir)),
+	}));
+}
+
+function resolveImagePath(p: string, baseDir: string): string {
+	if (!p) return p;
+	// Skip URLs
+	if (p.includes("://")) return p;
+	// Expand ~ first
+	const expanded = expandHome(p);
+	// Don't resolve if already absolute (cross-platform check)
+	if (path.isAbsolute(expanded)) {
+		return expanded;
+	}
+	// Resolve relative path against snapshot directory
+	return path.join(baseDir, p);
+}
+
+function resolvePathValue(value: string | string[], baseDir: string): string | string[] {
+	if (Array.isArray(value)) {
+		return value.map((v) => resolveImagePath(v, baseDir));
+	}
+	return typeof value === "string" && value ? resolveImagePath(value, baseDir) : value;
+}
+
 function formatResponses(responses: ResponseItem[]): string {
 	if (responses.length === 0) return "(none)";
 	return responses
@@ -138,6 +240,28 @@ function formatResponses(responses: ResponseItem[]): string {
 		.join("\n");
 }
 
+function hasAnyAnswers(responses: ResponseItem[]): boolean {
+	if (!responses || responses.length === 0) return false;
+	return responses.some((resp) => {
+		if (!resp || resp.value == null) return false;
+		if (Array.isArray(resp.value)) {
+			return resp.value.some((v) => typeof v === "string" && v.trim() !== "");
+		}
+		return typeof resp.value === "string" && resp.value.trim() !== "";
+	});
+}
+
+function filterAnsweredResponses(responses: ResponseItem[]): ResponseItem[] {
+	if (!responses) return [];
+	return responses.filter((resp) => {
+		if (!resp || resp.value == null) return false;
+		if (Array.isArray(resp.value)) {
+			return resp.value.some((v) => typeof v === "string" && v.trim() !== "");
+		}
+		return typeof resp.value === "string" && resp.value.trim() !== "";
+	});
+}
+
 export default function (pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "interview",
@@ -180,6 +304,11 @@ export default function (pi: ExtensionAPI) {
 			const themeConfig = mergeThemeConfig(settings.theme, theme, ctx.cwd);
 			const questionsData = loadQuestions(questions, ctx.cwd);
 
+			// Expand ~ in snapshotDir if present
+			const snapshotDir = settings.snapshotDir
+				? expandHome(settings.snapshotDir)
+				: undefined; // Server will use default
+
 			if (signal?.aborted) {
 				return {
 					content: [{ type: "text", text: "Interview was aborted." }],
@@ -217,11 +346,19 @@ export default function (pi: ExtensionAPI) {
 						if (cancelReason === "stale") {
 							text =
 								"Interview session ended due to lost heartbeat.\n\nQuestions saved to: ~/.pi/interview-recovery/";
+						} else if (hasAnyAnswers(responses)) {
+							const answered = filterAnsweredResponses(responses);
+							text = `User cancelled the interview with partial responses:\n${formatResponses(answered)}\n\nProceed with these inputs and use your best judgment for unanswered questions.`;
 						} else {
-							text = "User cancelled the interview form.";
+							text = "User skipped the interview without providing answers. Proceed with your best judgment - use recommended options where specified, make reasonable choices elsewhere. Don't ask for clarification unless absolutely necessary.";
 						}
 					} else if (status === "timeout") {
-						text = `Interview form timed out after ${timeoutSeconds} seconds.\n\nQuestions saved to: ~/.pi/interview-recovery/`;
+						if (hasAnyAnswers(responses)) {
+							const answered = filterAnsweredResponses(responses);
+							text = `Interview form timed out after ${timeoutSeconds} seconds.\n\nPartial responses before timeout:\n${formatResponses(answered)}\n\nQuestions saved to: ~/.pi/interview-recovery/\n\nProceed with these inputs and use your best judgment for unanswered questions.`;
+						} else {
+							text = `Interview form timed out after ${timeoutSeconds} seconds.\n\nQuestions saved to: ~/.pi/interview-recovery/`;
+						}
 					} else {
 						text = "Interview was aborted.";
 					}
@@ -245,11 +382,16 @@ export default function (pi: ExtensionAPI) {
 						port: settings.port,
 						verbose,
 						theme: themeConfig,
+						snapshotDir,
+						autoSaveOnSubmit: settings.autoSaveOnSubmit ?? true,
+						savedAnswers: questionsData.savedAnswers,
 					},
 					{
 						onSubmit: (responses) => finish("completed", responses),
-						onCancel: (reason) =>
-							reason === "timeout" ? finish("timeout") : finish("cancelled", [], reason),
+						onCancel: (reason, partialResponses) =>
+							reason === "timeout"
+								? finish("timeout", partialResponses ?? [])
+								: finish("cancelled", partialResponses ?? [], reason),
 					}
 				)
 					.then(async (handle) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-interview",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Interactive interview form extension for pi coding agent",
   "author": "Nico Bailon",
   "license": "MIT",

package/server.ts

@@ -46,6 +46,7 @@ interface SessionsFile {
 
 const SESSIONS_FILE = join(homedir(), ".pi", "interview-sessions.json");
 const RECOVERY_DIR = join(homedir(), ".pi", "interview-recovery");
+const SNAPSHOTS_DIR = join(homedir(), ".pi", "interview-snapshots");
 const STALE_THRESHOLD_MS = 30000;
 const STALE_PRUNE_MS = 60000;
 const RECOVERY_MAX_AGE_DAYS = 7;
@@ -192,11 +193,14 @@ export interface InterviewServerOptions {
 	port?: number;
 	verbose?: boolean;
 	theme?: InterviewThemeConfig;
+	snapshotDir?: string;
+	autoSaveOnSubmit?: boolean;
+	savedAnswers?: ResponseItem[];
 }
 
 export interface InterviewServerCallbacks {
 	onSubmit: (responses: ResponseItem[]) => void;
-	onCancel: (reason?: "timeout" | "user" | "stale") => void;
+	onCancel: (reason?: "timeout" | "user" | "stale", partialResponses?: ResponseItem[]) => void;
 }
 
 export interface InterviewServerHandle {
@@ -310,7 +314,8 @@ async function parseJSONBody(req: IncomingMessage): Promise<unknown> {
 
 async function handleImageUpload(
 	image: { id: string; filename: string; mimeType: string; data: string },
-	sessionId: string
+	sessionId: string,
+	targetDir?: string
 ): Promise<string> {
 	if (!ALLOWED_TYPES.includes(image.mimeType)) {
 		throw new Error(`Invalid image type: ${image.mimeType}`);
@@ -322,7 +327,7 @@ async function handleImageUpload(
 	}
 
 	const sanitized = image.filename.replace(/[^a-zA-Z0-9._-]/g, "_");
-	const basename = sanitized.split(/[/\\]/).pop() || `image_${randomUUID()}`;
+	const fileBasename = sanitized.split(/[/\\]/).pop() || `image_${randomUUID()}`;
 	const extMap: Record<string, string> = {
 		"image/png": ".png",
 		"image/jpeg": ".jpg",
@@ -330,12 +335,12 @@ async function handleImageUpload(
 		"image/webp": ".webp",
 	};
 	const ext = extMap[image.mimeType] ?? "";
-	const filename = basename.includes(".") ? basename : `${basename}${ext}`;
+	const filename = fileBasename.includes(".") ? fileBasename : `${fileBasename}${ext}`;
 
-	const tempDir = join(tmpdir(), `pi-interview-${sessionId}`);
-	await mkdir(tempDir, { recursive: true });
+	const dir = targetDir ?? join(tmpdir(), `pi-interview-${sessionId}`);
+	await mkdir(dir, { recursive: true });
 
-	const filepath = join(tempDir, filename);
+	const filepath = join(dir, filename);
 	await writeFile(filepath, buffer);
 
 	return filepath;
@@ -374,6 +379,223 @@ function ensureQuestionId(
 	return { ok: true, question };
 }
 
+// HTML generation for saved interviews
+interface SavedFromMeta {
+	cwd: string;
+	branch: string | null;
+	sessionId: string;
+}
+
+interface SavedInterviewMeta {
+	savedAt: string;
+	wasSubmitted: boolean;
+	savedFrom: SavedFromMeta;
+}
+
+function escapeHtml(str: string): string {
+	return str
+		.replace(/&/g, "&amp;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;")
+		.replace(/"/g, "&quot;");
+}
+
+function renderQuestionsHtml(questionsList: Question[], answers: ResponseItem[]): string {
+	const answerMap = new Map(answers.map((a) => [a.id, a]));
+	return questionsList
+		.map((q, i) => {
+			const ans = answerMap.get(q.id);
+			const value = ans?.value;
+			const attachments = ans?.attachments ?? [];
+
+			// Format answer based on question type
+			let answerHtml: string;
+			if (!value || (Array.isArray(value) && value.length === 0)) {
+				answerHtml = '<div class="saved-answer empty">(no answer)</div>';
+			} else if (q.type === "image") {
+				const paths = Array.isArray(value) ? value : [value];
+				answerHtml = `<div class="saved-images">${paths
+					.map((p) => `<img src="${escapeHtml(p)}" alt="uploaded image">`)
+					.join("")}</div>`;
+			} else if (q.type === "multi") {
+				const items = Array.isArray(value) ? value : [value];
+				answerHtml = `<div class="saved-answer"><ul>${items
+					.map((v) => `<li>${escapeHtml(String(v))}</li>`)
+					.join("")}</ul></div>`;
+			} else {
+				answerHtml = `<div class="saved-answer">${escapeHtml(String(value))}</div>`;
+			}
+
+			// Render code block if present
+			const codeHtml = q.codeBlock
+				? `<pre class="saved-code"><code>${escapeHtml(q.codeBlock.code)}</code></pre>`
+				: "";
+
+			// Render attachments if any
+			const attachHtml =
+				attachments.length > 0
+					? `<div class="saved-attachments">${attachments
+							.map((p) => `<img src="${escapeHtml(p)}" alt="attachment">`)
+							.join("")}</div>`
+					: "";
+
+			return `
+      <div class="saved-question">
+        <h2>${i + 1}. ${escapeHtml(q.question)}</h2>
+        ${codeHtml}
+        ${answerHtml}
+        ${attachHtml}
+      </div>
+    `;
+		})
+		.join("\n");
+}
+
+const SAVED_VIEW_STYLES = `
+.saved-interview {
+  max-width: 680px;
+  margin: 0 auto;
+  padding: var(--spacing);
+}
+.saved-header {
+  margin-bottom: 24px;
+  padding-bottom: 16px;
+  border-bottom: 1px solid var(--border-muted);
+}
+.saved-header h1 {
+  margin: 0 0 8px;
+  font-size: 20px;
+}
+.saved-meta {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 16px;
+  font-size: 12px;
+  color: var(--fg-muted);
+}
+.saved-status {
+  padding: 2px 8px;
+  border-radius: var(--radius);
+  background: var(--bg-elevated);
+}
+.saved-status.submitted {
+  color: var(--success);
+  border: 1px solid var(--success);
+}
+.saved-status.draft {
+  color: var(--warning);
+  border: 1px solid var(--warning);
+}
+.saved-question {
+  margin-bottom: 20px;
+  padding: 16px;
+  background: var(--bg-elevated);
+  border: 1px solid var(--border-muted);
+  border-radius: var(--radius);
+}
+.saved-question h2 {
+  margin: 0 0 12px;
+  font-size: 14px;
+  font-weight: 500;
+}
+.saved-code {
+  margin: 12px 0;
+  padding: 12px;
+  background: var(--bg-body);
+  border-radius: var(--radius);
+  overflow-x: auto;
+  font-size: 13px;
+}
+.saved-answer {
+  color: var(--fg);
+  padding: 8px 12px;
+  background: var(--bg-body);
+  border-radius: var(--radius);
+  white-space: pre-wrap;
+}
+.saved-answer.empty {
+  color: var(--fg-dim);
+  font-style: italic;
+}
+.saved-answer ul {
+  margin: 0;
+  padding-left: 20px;
+}
+.saved-images, .saved-attachments {
+  margin-top: 12px;
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+}
+.saved-images img, .saved-attachments img {
+  max-width: 200px;
+  max-height: 150px;
+  border-radius: var(--radius);
+  border: 1px solid var(--border-muted);
+}
+`;
+
+function generateSavedHtml(options: {
+	questions: QuestionsFile;
+	answers: ResponseItem[];
+	meta: SavedInterviewMeta;
+	baseStyles: string;
+	themeCss: string;
+}): string {
+	const { questions: questionsData, answers, meta, baseStyles, themeCss } = options;
+	const title = questionsData.title || "Interview";
+
+	// Build the data object for embedding
+	const dataForEmbedding = {
+		title: questionsData.title,
+		description: questionsData.description,
+		questions: questionsData.questions,
+		savedAnswers: answers,
+		savedAt: meta.savedAt,
+		wasSubmitted: meta.wasSubmitted,
+		savedFrom: meta.savedFrom,
+	};
+
+	const embeddedJson = safeInlineJSON(dataForEmbedding);
+	const questionsHtml = renderQuestionsHtml(questionsData.questions, answers);
+	const savedDate = new Date(meta.savedAt).toLocaleString();
+	const statusClass = meta.wasSubmitted ? "submitted" : "draft";
+	const statusText = meta.wasSubmitted ? "Submitted" : "Draft";
+
+	return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${escapeHtml(title)} - Saved Interview</title>
+  <style>
+${baseStyles}
+${themeCss}
+${SAVED_VIEW_STYLES}
+  </style>
+</head>
+<body>
+  <main class="saved-interview">
+    <header class="saved-header">
+      <h1>${escapeHtml(title)}</h1>
+      <div class="saved-meta">
+        <span>Saved: ${escapeHtml(savedDate)}</span>
+        <span>Project: ${escapeHtml(meta.savedFrom.cwd)}</span>
+        ${meta.savedFrom.branch ? `<span>Branch: ${escapeHtml(meta.savedFrom.branch)}</span>` : ""}
+        <span class="saved-status ${statusClass}">${statusText}</span>
+      </div>
+    </header>
+    <div class="saved-questions">
+${questionsHtml}
+    </div>
+  </main>
+  <script type="application/json" id="pi-interview-data">
+${embeddedJson}
+  </script>
+</body>
+</html>`;
+}
+
 export async function startInterviewServer(
 	options: InterviewServerOptions,
 	callbacks: InterviewServerCallbacks
@@ -468,6 +690,8 @@ export async function startInterviewServer(
 						mode: themeMode,
 						toggleHotkey: themeConfig.toggleHotkey,
 					},
+					savedAnswers: options.savedAnswers,
+					autoSaveOnSubmit: options.autoSaveOnSubmit ?? true,
 				});
 				const html = TEMPLATE
 					.replace("/* __INTERVIEW_DATA_PLACEHOLDER__ */", inlineData)
@@ -563,7 +787,8 @@ export async function startInterviewServer(
 					sendJson(res, 200, { ok: true });
 					return;
 				}
-				const reason = (body as { reason?: string }).reason;
+				const payload = body as { reason?: string; responses?: ResponseItem[] };
+				const reason = payload.reason;
 				if (reason === "timeout" || reason === "stale") {
 					const recoveryPath = saveToRecovery(questions, cwd, gitBranch, sessionId);
 					const label = reason === "timeout" ? "timed out" : "stale";
@@ -572,7 +797,8 @@ export async function startInterviewServer(
 				markCompleted();
 				unregisterSession(sessionId);
 				sendJson(res, 200, { ok: true });
-				setImmediate(() => callbacks.onCancel(reason));
+				const partialResponses = Array.isArray(payload.responses) ? payload.responses : undefined;
+				setImmediate(() => callbacks.onCancel(reason as "timeout" | "user" | "stale" | undefined, partialResponses));
 				return;
 			}
 
@@ -705,6 +931,123 @@ export async function startInterviewServer(
 				return;
 			}
 
+			if (method === "POST" && url.pathname === "/save") {
+				const body = await parseJSONBody(req).catch((err) => {
+					if (err instanceof BodyTooLargeError) {
+						sendJson(res, err.statusCode, { ok: false, error: err.message });
+						return null;
+					}
+					sendJson(res, 400, { ok: false, error: err.message });
+					return null;
+				});
+				if (!body) return;
+				if (!validateTokenBody(body, sessionToken, res)) return;
+				// Note: don't check `completed` - allow save after submit
+
+				const payload = body as {
+					responses?: ResponseItem[];
+					images?: Array<{
+						id: string;
+						filename: string;
+						mimeType: string;
+						data: string;
+						isAttachment?: boolean;
+					}>;
+					submitted?: boolean;
+				};
+
+				const responsesInput = Array.isArray(payload.responses) ? payload.responses : [];
+				const imagesInput = Array.isArray(payload.images) ? payload.images : [];
+				const submitted = payload.submitted === true;
+
+				const snapshotBaseDir = options.snapshotDir ?? SNAPSHOTS_DIR;
+
+				// Build folder name: {title}-{project}-{branch}-{timestamp}[-submitted]
+				const now = new Date();
+				const date = now.toISOString().slice(0, 10);
+				const time = now.toTimeString().slice(0, 8).replace(/:/g, "");
+				const timestamp = `${date}-${time}`;
+				const project = sanitizeForFilename(basename(cwd) || "unknown");
+				const branch = sanitizeForFilename(gitBranch || "nogit");
+				const titleSlug = sanitizeForFilename(questions.title || "interview");
+				const suffix = submitted ? "-submitted" : "";
+				const folderName = `${titleSlug}-${project}-${branch}-${timestamp}${suffix}`;
+				const snapshotPath = join(snapshotBaseDir, folderName);
+				const imagesPath = join(snapshotPath, "images");
+
+				await mkdir(snapshotPath, { recursive: true });
+
+				// Process responses - make a deep copy to avoid mutating input
+				const savedResponses: ResponseItem[] = responsesInput.map((r) => ({
+					...r,
+					value: Array.isArray(r.value) ? [...r.value] : r.value,
+					attachments: r.attachments ? [...r.attachments] : undefined,
+				}));
+
+				// Process uploaded images - save to images/ subfolder
+				if (imagesInput.length > 0) {
+					await mkdir(imagesPath, { recursive: true });
+					for (const image of imagesInput) {
+						if (!image || typeof image.id !== "string") continue;
+
+						try {
+							const absPath = await handleImageUpload(image, sessionId, imagesPath);
+							const relPath = "images/" + basename(absPath);
+
+							const existing = savedResponses.find((r) => r.id === image.id);
+							if (image.isAttachment) {
+								if (existing) {
+									existing.attachments = existing.attachments || [];
+									existing.attachments.push(relPath);
+								} else {
+									savedResponses.push({ id: image.id, value: "", attachments: [relPath] });
+								}
+							} else {
+								if (existing) {
+									if (Array.isArray(existing.value)) {
+										existing.value.push(relPath);
+									} else if (existing.value === "") {
+										existing.value = relPath;
+									} else {
+										existing.value = [existing.value, relPath];
+									}
+								} else {
+									savedResponses.push({ id: image.id, value: relPath });
+								}
+							}
+						} catch (err) {
+							const message = err instanceof Error ? err.message : "Image upload failed";
+							sendJson(res, 400, { ok: false, error: message, field: image.id });
+							return;
+						}
+					}
+				}
+
+				// Generate HTML with embedded data
+				const meta: SavedInterviewMeta = {
+					savedAt: new Date().toISOString(),
+					wasSubmitted: submitted,
+					savedFrom: { cwd: normalizedCwd, branch: gitBranch, sessionId },
+				};
+				const themeCss = themeMode === "light" ? themeLightCss : themeDarkCss;
+				const html = generateSavedHtml({
+					questions,
+					answers: savedResponses,
+					meta,
+					baseStyles: STYLES,
+					themeCss,
+				});
+
+				await writeFile(join(snapshotPath, "index.html"), html);
+
+				sendJson(res, 200, {
+					ok: true,
+					path: snapshotPath,
+					relativePath: normalizePath(snapshotPath),
+				});
+				return;
+			}
+
 			sendText(res, 404, "Not found");
 		} catch (err) {
 			const message = err instanceof Error ? err.message : "Server error";

package/settings.ts

@@ -17,6 +17,8 @@ export interface InterviewSettings {
 	timeout?: number;
 	port?: number;
 	theme?: InterviewThemeSettings;
+	snapshotDir?: string;      // Default: ~/.pi/interview-snapshots/
+	autoSaveOnSubmit?: boolean; // Default: true
 }
 
 export function loadSettings(): InterviewSettings {