pi-design-deck 0.1.1 → 0.2.0

package/README.md

@@ -6,7 +6,7 @@
 
 A tool for [Pi coding agent](https://github.com/badlogic/pi-mono/) that presents multi-slide visual decision decks in the browser. Each slide shows 2-4 high-fidelity previews — code diffs, architecture diagrams, UI mockups — and you pick one per slide. The agent gets back a clean selection map and moves on to implementation.
 
-https://github.com/user-attachments/assets/aff1bac6-8bc2-461a-8828-f588ce655f7f
+<img width="1340" alt="Design Deck screenshot" src="https://github.com/user-attachments/assets/20864ac6-9223-4e2e-ba3c-db3eaae0abd8" />
 
 ## Usage
 
@@ -42,6 +42,8 @@ Restart pi to load the extension and the bundled `design-deck` skill.
 **Requirements:**
 - pi-agent v0.35.0 or later (extensions API)
 
+https://github.com/user-attachments/assets/aff1bac6-8bc2-461a-8828-f588ce655f7f
+
 ## Quick Start
 
 The agent builds slides as JSON. Each slide is one decision, each option is one approach:
@@ -178,7 +180,7 @@ The browser shows the new option with an entry animation. The tool blocks again,
 
 ### Model Override
 
-The deck shows a model dropdown when 2+ models are available. Users pick which model generates new options. When a model other than the current one is selected, the generate-more result instructs the agent to delegate to a subagent with that model.
+The deck shows a model dropdown when 2+ models are available. Users pick which model generates new options. When a model other than the current one is selected, the generate-more result instructs the agent to use the built-in `deck_generate` tool, which spawns pi headlessly with that model.
 
 The default model can be set in the UI (saved to settings) or in `settings.json`:
 
@@ -286,6 +288,7 @@ Three modes of invocation:
 pi-design-deck/
 ├── index.ts             # Tool registration, module-level state, lifecycle
 ├── generate-prompts.ts  # Prompt builders for generate-more / regenerate
+├── model-runner.ts      # Headless pi spawner for deck_generate tool
 ├── deck-schema.ts       # TypeScript types and validation (no dependencies)
 ├── deck-server.ts       # HTTP server, SSE, asset serving, snapshots
 ├── server-utils.ts      # Shared HTTP/session utilities

package/deck-server.ts

@@ -173,16 +173,16 @@ export interface DeckServerOptions {
 }
 
 export interface DeckServerCallbacks {
-	onSubmit: (selections: Record<string, string>) => void;
+	onSubmit: (selections: Record<string, string>, notes?: Record<string, string>, finalNotes?: string) => void;
 	onCancel: (reason?: "user" | "stale" | "aborted") => void;
-	onGenerateMore: (slideId: string, prompt?: string, model?: string, thinking?: string) => void;
+	onGenerateMore: (slideId: string, prompt?: string, model?: string, thinking?: string, count?: number) => void;
 	onRegenerateSlide: (slideId: string, prompt?: string, model?: string, thinking?: string) => void;
 }
 
 export interface DeckServerHandle {
 	url: string;
 	port: number;
-	close: () => void;
+	close: (reason?: string) => void;
 	pushOption: (slideId: string, option: DeckOption) => void;
 	cancelGenerate: () => void;
 	replaceSlideOptions: (slideId: string, options: DeckOption[]) => void;
@@ -414,12 +414,14 @@ export async function startDeckServer(
 					return;
 				}
 
-				const payload = body as { selections?: unknown };
+				const payload = body as { selections?: unknown; notes?: unknown; finalNotes?: unknown };
 				const selections = toStringMap(payload.selections);
 				if (!selections) {
 					sendJson(res, 400, { ok: false, error: "Invalid selections payload" });
 					return;
 				}
+				const notes = toStringMap(payload.notes) ?? undefined;
+				const finalNotes = typeof payload.finalNotes === "string" ? payload.finalNotes.trim() : undefined;
 
 				touchHeartbeat();
 				if (autoSaveOnSubmit !== false) {
@@ -431,7 +433,7 @@ export async function startDeckServer(
 				unregisterSession(sessionId);
 				pushEvent("deck-close", { reason: "submitted" });
 				sendJson(res, 200, { ok: true });
-				setImmediate(() => callbacks.onSubmit(selections));
+				setImmediate(() => callbacks.onSubmit(selections, notes, finalNotes || undefined));
 				return;
 			}
 
@@ -492,7 +494,7 @@ export async function startDeckServer(
 					return;
 				}
 
-				const payload = body as { slideId?: string; prompt?: string; model?: string; thinking?: string };
+				const payload = body as { slideId?: string; prompt?: string; model?: string; thinking?: string; count?: number };
 				if (typeof payload.slideId !== "string" || payload.slideId.trim() === "") {
 					sendJson(res, 400, { ok: false, error: "slideId is required" });
 					return;
@@ -509,12 +511,13 @@ export async function startDeckServer(
 				const prompt = typeof payload.prompt === "string" ? payload.prompt.trim() || undefined : undefined;
 				const model = typeof payload.model === "string" ? (payload.model.trim() || "") : undefined;
 				const thinking = typeof payload.thinking === "string" ? payload.thinking.trim() || undefined : undefined;
+				const count = typeof payload.count === "number" && payload.count >= 1 && payload.count <= 5 ? payload.count : 1;
 
 				setPendingGenerate(payload.slideId as string, false);
 				touchHeartbeat();
 				sendJson(res, 200, { ok: true });
 				setImmediate(() => {
-					callbacks.onGenerateMore(payload.slideId as string, prompt, model, thinking);
+					callbacks.onGenerateMore(payload.slideId as string, prompt, model, thinking, count);
 				});
 				return;
 			}
@@ -603,11 +606,11 @@ export async function startDeckServer(
 			resolve({
 				url,
 				port: addr.port,
-				close: () => {
+				close: (reason?: string) => {
 					if (!completed) {
 						markCompleted();
 						unregisterSession(sessionId);
-						pushEvent("deck-close", { reason: "closed" });
+						pushEvent("deck-close", { reason: reason || "closed" });
 					}
 					try {
 						server.close();

package/form/css/controls.css

@@ -27,6 +27,30 @@
 }
 .btn-gen-more:disabled { opacity: 0.3; cursor: not-allowed; }
 
+.gen-group { display: flex; align-items: center; gap: 6px; }
+
+.gen-count {
+  appearance: none;
+  -webkit-appearance: none;
+  background: rgba(var(--dk-ink),0.12);
+  border: 1px solid rgba(var(--dk-ink),0.15);
+  border-radius: 4px;
+  padding: 4px 8px;
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--dk-accent-text);
+  cursor: pointer;
+  text-align: center;
+  min-width: 32px;
+}
+.gen-count:focus { outline: none; border-color: rgba(138,190,183,0.4); background: rgba(138,190,183,0.1); }
+.gen-count:disabled { opacity: 0.4; cursor: not-allowed; }
+
+.gen-count-label {
+  font-size: 12px;
+  color: var(--dk-text-dim);
+}
+
 .btn-regen {
   display: inline-flex; align-items: center; gap: 6px;
   padding: 8px 14px; border-radius: 8px;
@@ -120,6 +144,102 @@
 }
 @keyframes skel-shimmer { 0%{background-position:200% 0} 100%{background-position:-200% 0} }
 
+/* Regeneration overlay - covers options grid during regenerate-all */
+.regen-overlay {
+  position: absolute;
+  inset: 0;
+  display: grid;
+  gap: 20px;
+  padding: 0;
+  z-index: 10;
+  animation: regen-fade-in 0.3s ease-out;
+}
+.regen-overlay.cols-3 { grid-template-columns: repeat(3, 1fr); }
+.regen-overlay.cols-2 { grid-template-columns: repeat(2, 1fr); }
+.regen-overlay.cols-1 { grid-template-columns: 1fr; }
+
+@keyframes regen-fade-in {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+.regen-skeleton {
+  border: 2px dashed rgba(138,190,183,0.15);
+  border-radius: 12px;
+  background: var(--dk-surface);
+  min-height: 280px;
+  position: relative;
+  overflow: hidden;
+}
+.regen-skeleton::before {
+  content: '';
+  position: absolute;
+  top: 0; left: 0; right: 0;
+  height: 44px;
+  background: linear-gradient(110deg, rgba(var(--dk-ink),0.03) 30%, rgba(var(--dk-ink),0.07) 50%, rgba(var(--dk-ink),0.03) 70%);
+  background-size: 200% 100%;
+  animation: skel-shimmer 1.5s ease-in-out infinite;
+  border-bottom: 1px solid rgba(var(--dk-ink),0.06);
+}
+.regen-skeleton::after {
+  content: '';
+  position: absolute;
+  top: 45px; left: 0; right: 0; bottom: 0;
+  background: linear-gradient(110deg, var(--dk-surface) 30%, var(--dk-surface-shimmer) 50%, var(--dk-surface) 70%);
+  background-size: 200% 100%;
+  animation: skel-shimmer 1.5s ease-in-out infinite;
+  animation-delay: 0.1s;
+}
+.regen-skeleton:nth-child(2)::before,
+.regen-skeleton:nth-child(2)::after { animation-delay: 0.2s; }
+.regen-skeleton:nth-child(3)::before,
+.regen-skeleton:nth-child(3)::after { animation-delay: 0.3s; }
+.regen-skeleton:nth-child(4)::before,
+.regen-skeleton:nth-child(4)::after { animation-delay: 0.4s; }
+
+/* Regeneration status text */
+.regen-status {
+  position: absolute;
+  bottom: 16px; left: 50%;
+  transform: translateX(-50%);
+  font-family: var(--dk-font-mono);
+  font-size: 11px;
+  color: var(--dk-accent-text);
+  letter-spacing: 0.3px;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+.regen-status::before {
+  content: '';
+  width: 14px; height: 14px;
+  border: 2px solid rgba(138,190,183,0.2);
+  border-top-color: var(--dk-accent);
+  border-radius: 50%;
+  animation: spin 0.8s linear infinite;
+}
+
+/* Options grid regenerating state */
+.options.regenerating {
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 0.25s ease-out;
+}
+
+/* Regenerated options entry animation */
+.option-regenerated {
+  animation: opt-regen-appear 0.4s cubic-bezier(0.16, 1, 0.3, 1) forwards;
+  opacity: 0;
+}
+.option-regenerated:nth-child(1) { animation-delay: 0.05s; }
+.option-regenerated:nth-child(2) { animation-delay: 0.1s; }
+.option-regenerated:nth-child(3) { animation-delay: 0.15s; }
+.option-regenerated:nth-child(4) { animation-delay: 0.2s; }
+@keyframes opt-regen-appear {
+  0% { opacity: 0; transform: translateY(12px) scale(0.96); }
+  100% { opacity: 1; transform: translateY(0) scale(1); }
+}
+
 /* ─────────────────────────────────────────────────────────────
    MODEL BAR
    ───────────────────────────────────────────────────────────── */

package/form/css/layout.css

@@ -268,6 +268,21 @@ body {
   color: var(--dk-text-secondary); font-family: var(--dk-font-mono);
   font-style: italic;
 }
+.summary-notes {
+  margin-top: 10px; padding: 8px 10px;
+  font-size: 11px; line-height: 1.5;
+  color: var(--dk-accent-text);
+  background: rgba(138,190,183,0.08);
+  border-radius: 4px;
+  border-left: 2px solid rgba(138,190,183,0.3);
+}
+.summary-notes-label {
+  font-weight: 600;
+  font-size: 9px;
+  text-transform: uppercase;
+  letter-spacing: 0.3px;
+  opacity: 0.8;
+}
 .summary-preview {
   margin-top: 12px; border-radius: 6px; overflow: hidden;
   border: 1px solid rgba(var(--dk-ink),0.12); max-height: 120px;
@@ -288,6 +303,47 @@ body {
 }
 .summary-mermaid svg { max-width: 100%; max-height: 100%; }
 
+/* Final notes input on summary slide */
+.final-notes {
+  width: 100%;
+  max-width: 560px;
+  margin-top: 24px;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+.final-notes-label {
+  font-size: 11px;
+  font-weight: 500;
+  color: var(--dk-text-dim);
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+}
+.final-notes-input {
+  width: 100%;
+  padding: 12px 14px;
+  border-radius: 8px;
+  border: 1px solid rgba(var(--dk-ink),0.12);
+  background: rgba(var(--dk-ink),0.04);
+  font-size: 13px;
+  font-family: inherit;
+  color: var(--dk-text);
+  resize: vertical;
+  min-height: 60px;
+  max-height: 120px;
+  transition: border-color 0.2s, background 0.2s, box-shadow 0.2s;
+}
+.final-notes-input::placeholder {
+  color: var(--dk-text-placeholder);
+  font-style: italic;
+}
+.final-notes-input:focus {
+  outline: none;
+  border-color: rgba(138,190,183,0.4);
+  background: rgba(var(--dk-ink),0.06);
+  box-shadow: 0 0 0 3px rgba(138,190,183,0.1);
+}
+
 .btn-generate {
   display: inline-flex; align-items: center; justify-content: center; gap: 8px;
   padding: 14px 48px; border-radius: 10px; font-size: 14px; font-weight: 600;

package/form/css/preview.css

@@ -59,17 +59,71 @@ code[class*="language-"], pre[class*="language-"] {
    OPTION ASIDE
    ───────────────────────────────────────────────────────────── */
 
-.option-aside {
-  margin: 0 14px 14px;
+/* Option footer - contains aside + notes */
+.option-footer {
   padding: 12px 14px;
-  border-left: 2px solid rgba(138,190,183,0.25);
-  border-radius: 0 6px 6px 0;
-  background: rgba(var(--dk-ink),0.04);
-  font-size: 12px; line-height: 1.7;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.option-aside {
+  padding: 8px 10px;
+  border-left: 2px solid rgba(138,190,183,0.2);
+  background: rgba(var(--dk-ink),0.02);
+  font-size: 11px; line-height: 1.55;
   color: var(--dk-text-aside);
   font-family: var(--dk-font-mono);
   font-style: italic;
   letter-spacing: -0.01em;
+  border-radius: 0 4px 4px 0;
+}
+
+/* Option notes input */
+.option-notes {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+.option-notes-label {
+  font-size: 9px;
+  font-weight: 500;
+  color: var(--dk-text-hint);
+  text-transform: uppercase;
+  letter-spacing: 0.3px;
+  white-space: nowrap;
+  opacity: 0.6;
+}
+.option-notes-input {
+  flex: 1;
+  padding: 5px 8px;
+  border-radius: 4px;
+  border: 1px dashed rgba(var(--dk-ink),0.12);
+  background: transparent;
+  font-size: 11px;
+  font-family: var(--dk-font-mono);
+  color: var(--dk-text);
+  resize: none;
+  min-height: 24px;
+  transition: border-color 0.2s, background 0.2s;
+}
+.option-notes-input::placeholder {
+  color: var(--dk-text-placeholder);
+  opacity: 0.4;
+  font-size: 10px;
+}
+.option-notes-input:focus {
+  outline: none;
+  border-style: solid;
+  border-color: rgba(138,190,183,0.3);
+  background: rgba(var(--dk-ink),0.02);
+}
+.option.selected .option-notes-input {
+  border-color: rgba(138,190,183,0.2);
+}
+.option-notes-input:disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
 }
 
 /* ─────────────────────────────────────────────────────────────

package/form/js/deck-core.js

@@ -23,6 +23,8 @@ let isClosed = false;
 let isSubmitting = false;
 
 const selections = {};
+const optionNotes = {};
+let finalNotes = "";
 const pendingGenerate = new Map();
 let selectedModel = "";
 let selectedThinking = "off";
@@ -184,13 +186,23 @@ function initTheme() {
 const SELECTIONS_KEY = `pi-deck-${typeof deckData.sessionId === "string" ? deckData.sessionId : "unknown"}`;
 
 function saveSelectionsToStorage() {
-	try { localStorage.setItem(SELECTIONS_KEY, JSON.stringify(selections)); } catch {}
+	try { 
+		const data = { selections, optionNotes };
+		if (finalNotes) data.finalNotes = finalNotes;
+		localStorage.setItem(SELECTIONS_KEY, JSON.stringify(data)); 
+	} catch {}
 }
 
 function loadSelectionsFromStorage() {
 	try {
 		const saved = localStorage.getItem(SELECTIONS_KEY);
-		return saved ? JSON.parse(saved) : null;
+		if (!saved) return null;
+		const parsed = JSON.parse(saved);
+		// Handle both old format (just selections) and new format ({ selections, optionNotes })
+		if (parsed && typeof parsed === "object" && !parsed.selections) {
+			return { selections: parsed, optionNotes: {} };
+		}
+		return parsed;
 	} catch { return null; }
 }
 

package/form/js/deck-interact.js

@@ -1,8 +1,8 @@
 // ─── SELECTION ───────────────────────────────────────────────
 
-function applySavedSelections(saved) {
-	if (!saved || typeof saved !== "object") return;
-	for (const [slideId, label] of Object.entries(saved)) {
+function applySavedSelections(savedSelections, savedNotes) {
+	if (!savedSelections || typeof savedSelections !== "object") return;
+	for (const [slideId, label] of Object.entries(savedSelections)) {
 		if (typeof label !== "string") continue;
 		const slideEl = document.querySelector(`.slide[data-id="${CSS.escape(slideId)}"]`);
 		if (!slideEl) continue;
@@ -13,16 +13,35 @@ function applySavedSelections(saved) {
 			}
 		}
 	}
+	// Restore notes
+	if (savedNotes && typeof savedNotes === "object") {
+		for (const [slideId, noteData] of Object.entries(savedNotes)) {
+			if (noteData && typeof noteData === "object" && noteData.label && noteData.notes) {
+				optionNotes[slideId] = noteData;
+				// Find and populate the textarea
+				const input = document.querySelector(`.option-notes-input[data-slide-id="${CSS.escape(slideId)}"][data-option-label="${CSS.escape(noteData.label)}"]`);
+				if (input) input.value = noteData.notes;
+			}
+		}
+	}
 }
 
 function restoreSelections() {
 	const serverSaved = deckData.savedSelections;
 	if (serverSaved && typeof serverSaved === "object" && Object.keys(serverSaved).length > 0) {
-		applySavedSelections(serverSaved);
+		applySavedSelections(serverSaved, null);
 		return;
 	}
 	const stored = loadSelectionsFromStorage();
-	if (stored) applySavedSelections(stored);
+	if (stored) {
+		applySavedSelections(stored.selections || stored, stored.optionNotes);
+		// Restore final notes if present
+		if (stored.finalNotes) {
+			finalNotes = stored.finalNotes;
+			const input = document.getElementById("final-notes-input");
+			if (input) input.value = stored.finalNotes;
+		}
+	}
 }
 
 function applySelectionClasses(slideElement, selectedElement) {
@@ -337,7 +356,8 @@ function initModelBar(modelsData) {
 	}
 
 	function syncDefaultCheck() {
-		defaultCheck.checked = modelsData.defaultModel != null && selectedModel === modelsData.defaultModel;
+		const effectiveModel = selectedModel || modelsData.current;
+		defaultCheck.checked = modelsData.defaultModel != null && effectiveModel === modelsData.defaultModel;
 	}
 
 	function activateProvider(provider) {
@@ -369,12 +389,18 @@ function initModelBar(modelsData) {
 	});
 
 	defaultCheck.addEventListener("change", async () => {
-		if (defaultCheck.checked && !selectedModel) { defaultCheck.checked = false; return; }
-		const model = defaultCheck.checked ? selectedModel : null;
+		// Use selectedModel, or fall back to current model when on "Current" pill
+		const modelToSave = selectedModel || modelsData.current;
+		if (defaultCheck.checked && !modelToSave) { defaultCheck.checked = false; return; }
+		const model = defaultCheck.checked ? modelToSave : null;
 		try {
 			await postJson("/save-model-default", { token: sessionToken, model });
 			modelsData.defaultModel = model;
-		} catch {}
+		} catch (err) {
+			console.error("Failed to save default model:", err);
+			// Revert checkbox to match actual state
+			syncDefaultCheck();
+		}
 	});
 
 	if (modelsData.defaultModel) {

package/form/js/deck-render.js

@@ -114,6 +114,10 @@ function applyPreviewHtml(preview, previewHtml) {
 		if (dataset.fonts) {
 			preview.dataset.fonts = dataset.fonts;
 		}
+		// Copy inline styles from source preview div
+		if (first.style.cssText) {
+			preview.style.cssText = first.style.cssText;
+		}
 		preview.innerHTML = first.innerHTML;
 		return;
 	}
@@ -186,11 +190,47 @@ function createOptionCard(option, slideId, generatedBy) {
 		el.tabIndex = -1;
 	});
 
+	// Footer contains aside (optional) + notes input
+	const footer = createElement("div", "option-footer");
+
 	if (option.aside) {
 		const aside = createElement("div", "option-aside");
-		aside.innerHTML = escapeHtml(option.aside).replace(/\n/g, "<br>");
-		card.appendChild(aside);
+		// Handle both actual newlines and literal \n sequences
+		aside.innerHTML = escapeHtml(option.aside).replace(/\\n/g, "<br>").replace(/\n/g, "<br>");
+		footer.appendChild(aside);
+	}
+
+	// Notes input for user instructions
+	const notesContainer = createElement("div", "option-notes");
+	const notesLabel = createElement("label", "option-notes-label", "Your notes (optional)");
+	const notesInput = createElement("textarea", "option-notes-input");
+	notesInput.placeholder = "Add notes...";
+	notesInput.rows = 1;
+	notesInput.dataset.slideId = slideId;
+	notesInput.dataset.optionLabel = option.label;
+	
+	// Restore saved notes if this option was previously selected with notes
+	if (optionNotes[slideId]?.label === option.label && optionNotes[slideId]?.notes) {
+		notesInput.value = optionNotes[slideId].notes;
 	}
+	
+	notesInput.addEventListener("input", (e) => {
+		const value = e.target.value.trim();
+		if (value) {
+			optionNotes[slideId] = { label: option.label, notes: value };
+		} else if (optionNotes[slideId]?.label === option.label) {
+			delete optionNotes[slideId];
+		}
+		saveSelectionsToStorage();
+	});
+	
+	// Prevent click from bubbling to card (which would select it)
+	notesInput.addEventListener("click", (e) => e.stopPropagation());
+	
+	notesContainer.appendChild(notesLabel);
+	notesContainer.appendChild(notesInput);
+	footer.appendChild(notesContainer);
+	card.appendChild(footer);
 
 	if (option.description) {
 		card.setAttribute("title", option.description);
@@ -207,10 +247,33 @@ function createGenerateBar(slideId) {
 	const bar = createElement("div", "gen-bar");
 
 	const row = createElement("div", "gen-row");
+	
+	// Generate button with separate count selector
+	const genGroup = createElement("div", "gen-group");
 	const button = createElement("button", "btn-gen-more");
 	button.type = "button";
 	button.appendChild(createElement("span", "btn-gen-plus", "+"));
-	button.appendChild(document.createTextNode(" Generate another option"));
+	button.appendChild(document.createTextNode("Generate"));
+	
+	const countSelect = document.createElement("select");
+	countSelect.className = "gen-count";
+	countSelect.setAttribute("aria-label", "Number of options to generate");
+	[1, 2, 3].forEach((n) => {
+		const opt = document.createElement("option");
+		opt.value = n;
+		opt.textContent = n;
+		countSelect.appendChild(opt);
+	});
+	
+	const countLabel = createElement("span", "gen-count-label", "option");
+	countSelect.addEventListener("change", () => {
+		const count = parseInt(countSelect.value, 10);
+		countLabel.textContent = count === 1 ? "option" : "options";
+	});
+	
+	genGroup.appendChild(button);
+	genGroup.appendChild(countSelect);
+	genGroup.appendChild(countLabel);
 
 	const regenButton = createElement("button", "btn-regen");
 	regenButton.type = "button";
@@ -231,8 +294,8 @@ function createGenerateBar(slideId) {
 		e.stopPropagation();
 	});
 
-	button.addEventListener("click", () => generateMore(button, slideId, input));
-	row.appendChild(button);
+	button.addEventListener("click", () => generateMore(button, slideId, input, countSelect));
+	row.appendChild(genGroup);
 	row.appendChild(regenButton);
 	row.appendChild(input);
 	bar.appendChild(row);
@@ -301,6 +364,22 @@ function createSummarySlide(index) {
 	summaryGrid.id = "summary-grid";
 	section.appendChild(summaryGrid);
 
+	// Final instructions textarea
+	const finalNotesContainer = createElement("div", "final-notes");
+	const finalNotesLabel = createElement("label", "final-notes-label", "Additional instructions (optional)");
+	finalNotesLabel.setAttribute("for", "final-notes-input");
+	const finalNotesInput = createElement("textarea", "final-notes-input");
+	finalNotesInput.id = "final-notes-input";
+	finalNotesInput.placeholder = "Add any final notes or instructions for implementation...";
+	finalNotesInput.rows = 2;
+	finalNotesInput.addEventListener("input", (e) => {
+		finalNotes = e.target.value.trim();
+		saveSelectionsToStorage();
+	});
+	finalNotesContainer.appendChild(finalNotesLabel);
+	finalNotesContainer.appendChild(finalNotesInput);
+	section.appendChild(finalNotesContainer);
+
 	const submitButton = createElement("button", "btn-generate", "Submit Selections");
 	submitButton.type = "button";
 	submitButton.id = "btn-generate";
@@ -382,10 +461,18 @@ function createSummaryCard(slide) {
 				const text = selectedOption.aside.length > 120
 					? selectedOption.aside.slice(0, 120).trimEnd() + "..."
 					: selectedOption.aside;
-				aside.textContent = text;
+				aside.innerHTML = escapeHtml(text).replace(/\\n/g, "<br>").replace(/\n/g, "<br>");
 				card.appendChild(aside);
 			}
 		}
+
+		// Show user notes if present
+		const noteData = optionNotes[slide.id];
+		if (noteData && noteData.label === selectedLabel && noteData.notes) {
+			const notesDisplay = createElement("div", "summary-notes");
+			notesDisplay.innerHTML = `<span class="summary-notes-label">Your notes:</span> ${escapeHtml(noteData.notes)}`;
+			card.appendChild(notesDisplay);
+		}
 	}
 
 	return card;

package/form/js/deck-session.js

@@ -74,7 +74,7 @@ function disableDeckInteractions() {
 	document.querySelectorAll(".btn-gen-more, .btn-regen").forEach((button) => {
 		button.disabled = true;
 	});
-	document.querySelectorAll(".gen-prompt").forEach((input) => {
+	document.querySelectorAll(".gen-prompt, .gen-count").forEach((input) => {
 		input.disabled = true;
 	});
 	document.querySelectorAll(".model-pill, .model-list-item, .model-default-check").forEach((el) => {
@@ -98,7 +98,16 @@ async function submitDeck() {
 	}
 
 	try {
-		await postJson("/submit", { token: sessionToken, selections });
+		// Build notes object with only notes for selected options
+		const notes = {};
+		for (const [slideId, noteData] of Object.entries(optionNotes)) {
+			if (noteData && selections[slideId] === noteData.label && noteData.notes) {
+				notes[slideId] = noteData.notes;
+			}
+		}
+		const payload = { token: sessionToken, selections, notes };
+		if (finalNotes) payload.finalNotes = finalNotes;
+		await postJson("/submit", payload);
 		clearSelectionsStorage();
 		isClosed = true;
 		if (submitButton) {
@@ -242,16 +251,22 @@ function restoreGenerateButton(slideId) {
 	const pending = pendingGenerate.get(slideId);
 	if (!pending || pending.isRegen) return;
 
-	if (pending.skeleton && pending.skeleton.parentElement) {
-		pending.skeleton.remove();
+	// Clear timeout if any
+	if (pending.timeoutId) clearTimeout(pending.timeoutId);
+
+	// Remove all skeletons from DOM (query directly, don't rely on array)
+	const slideElement = document.querySelector(`.slide[data-id="${CSS.escape(slideId)}"]`);
+	if (slideElement) {
+		slideElement.querySelectorAll(".option-skeleton").forEach((skel) => skel.remove());
 	}
+	
 	pending.button.classList.remove("loading");
 	const plus = pending.button.querySelector(".btn-gen-plus");
 	if (plus) plus.textContent = "+";
-	if (pending.button.childNodes[1]) {
-		pending.button.childNodes[1].textContent = pending.originalText;
-	}
+	pending.button.lastChild.textContent = "Generate";
+	
 	if (pending.input && !isClosed) pending.input.disabled = false;
+	if (pending.countSelect && !isClosed) pending.countSelect.disabled = false;
 
 	pendingGenerate.delete(slideId);
 }
@@ -301,6 +316,7 @@ function replaceSlideOptions(slideId, newOptions) {
 	slide.options = newOptions;
 
 	delete selections[slideId];
+	delete optionNotes[slideId];
 	saveSelectionsToStorage();
 
 	const slideElement = document.querySelector(`.slide[data-id="${CSS.escape(slideId)}"]`);
@@ -309,16 +325,28 @@ function replaceSlideOptions(slideId, newOptions) {
 	const optionsGrid = slideElement.querySelector(".options");
 	if (!optionsGrid) return;
 
+	// Remove regeneration overlay and state
+	const overlay = optionsGrid.querySelector(".regen-overlay");
+	if (overlay) overlay.remove();
+	optionsGrid.classList.remove("regenerating");
+	optionsGrid.style.position = "";
+
 	optionsGrid.innerHTML = "";
-	optionsGrid.style.opacity = "";
-	optionsGrid.style.pointerEvents = "";
 	optionsGrid.className = `options ${optionCountClass(newOptions.length, slide.columns)}`;
 
 	newOptions.forEach((option) => {
 		const card = createOptionCard(option, slideId, false);
+		card.classList.add("option-regenerated");
 		optionsGrid.appendChild(card);
 	});
 
+	// Remove animation class after animation completes
+	setTimeout(() => {
+		optionsGrid.querySelectorAll(".option-regenerated").forEach((el) => {
+			el.classList.remove("option-regenerated");
+		});
+	}, 500);
+
 	equalizeBlockHeights(slideElement);
 
 	const pick = slideElement.querySelector(".slide-pick");
@@ -343,9 +371,37 @@ function connectEvents() {
 		if (!payload || typeof payload.slideId !== "string" || !payload.option) {
 			return;
 		}
-		const model = pendingGenerate.get(payload.slideId)?.model || null;
-		restoreGenerateButton(payload.slideId);
+		const pending = pendingGenerate.get(payload.slideId);
+		const model = pending?.model || null;
+		
+		// Remove one skeleton
+		if (pending?.skeletons?.length > 0) {
+			const skel = pending.skeletons.shift();
+			if (skel.parentElement) skel.remove();
+		}
+		
 		insertGeneratedOption(payload.slideId, payload.option, model);
+		
+		// Track received count and restore button when all received
+		if (pending) {
+			pending.receivedCount = (pending.receivedCount || 0) + 1;
+			if (pending.receivedCount >= (pending.expectedCount || 1)) {
+				restoreGenerateButton(payload.slideId);
+			} else {
+				// Reset timeout for next option
+				if (pending.timeoutId) clearTimeout(pending.timeoutId);
+				pending.timeoutId = setTimeout(() => {
+					const current = pendingGenerate.get(payload.slideId);
+					if (!current || current.isRegen) return;
+					const received = current.receivedCount || 0;
+					const expected = current.expectedCount || 1;
+					restoreGenerateButton(payload.slideId);
+					if (received < expected) {
+						showSaveToast(`Generated ${received} of ${expected} options`, true);
+					}
+				}, 30000);
+			}
+		}
 	});
 
 	events.addEventListener("generate-failed", (event) => {
@@ -359,6 +415,8 @@ function connectEvents() {
 			restoreGenerateButton(payload.slideId);
 			if (payload.reason === "timeout") {
 				showSaveToast("Generation timed out — try again", true);
+			} else {
+				showSaveToast("Generation failed", true);
 			}
 		}
 	});
@@ -388,6 +446,8 @@ function connectEvents() {
 			restoreRegenButton(payload.slideId);
 			if (payload.reason === "timeout") {
 				showSaveToast("Regeneration timed out — try again", true);
+			} else {
+				showSaveToast("Regeneration failed", true);
 			}
 		}
 	});
@@ -415,7 +475,7 @@ function connectEvents() {
 	});
 }
 
-async function generateMore(button, slideId, input) {
+async function generateMore(button, slideId, input, countSelect) {
 	if (isClosed || pendingGenerate.size > 0) return;
 
 	const slideElement = document.querySelector(`.slide[data-id="${CSS.escape(slideId)}"]`);
@@ -428,21 +488,42 @@ async function generateMore(button, slideId, input) {
 
 	const prompt = input ? input.value.trim() : "";
 	if (input) input.value = "";
+	
+	const count = countSelect ? parseInt(countSelect.value, 10) || 1 : 1;
+
+	// Create skeletons for each option being generated
+	const skeletons = [];
+	for (let i = 0; i < count; i++) {
+		const skeleton = createElement("div", "option-skeleton");
+		optionsGrid.appendChild(skeleton);
+		skeletons.push(skeleton);
+	}
 
-	const skeleton = createElement("div", "option-skeleton");
-	optionsGrid.appendChild(skeleton);
-
-	const originalText = button.childNodes[1] ? button.childNodes[1].textContent || "" : "";
 	button.classList.add("loading");
 	const plus = button.querySelector(".btn-gen-plus");
 	if (plus) plus.textContent = "";
-	if (button.childNodes[1]) button.childNodes[1].textContent = " Generating...";
+	button.lastChild.textContent = "Generating...";
 	if (input) input.disabled = true;
+	if (countSelect) countSelect.disabled = true;
+
+	// Set timeout for generation (30s per option)
+	const timeoutId = setTimeout(() => {
+		const pending = pendingGenerate.get(slideId);
+		if (pending && !pending.isRegen) {
+			const received = pending.receivedCount || 0;
+			restoreGenerateButton(slideId);
+			if (received === 0) {
+				showSaveToast("Generation timed out — try again", true);
+			} else {
+				showSaveToast(`Generated ${received} of ${count} options`, true);
+			}
+		}
+	}, 30000 * count);
 
-	pendingGenerate.set(slideId, { button, skeleton, originalText, input, model: selectedModel || null });
+	pendingGenerate.set(slideId, { button, skeletons, input, countSelect, model: selectedModel || null, expectedCount: count, receivedCount: 0, timeoutId });
 
 	try {
-		const body = { token: sessionToken, slideId };
+		const body = { token: sessionToken, slideId, count };
 		if (prompt) body.prompt = prompt;
 		if (hasModelBar) {
 			body.model = selectedModel;
@@ -470,8 +551,21 @@ async function regenerateSlide(button, slideId) {
 	const prompt = input ? input.value.trim() : "";
 	if (input) input.value = "";
 
-	optionsGrid.style.opacity = "0.4";
-	optionsGrid.style.pointerEvents = "none";
+	// Create skeleton overlay
+	const optionCount = slide.options?.length || 2;
+	const colClass = optionsGrid.classList.contains("cols-3") ? "cols-3" :
+	                 optionsGrid.classList.contains("cols-1") ? "cols-1" : "cols-2";
+	const overlay = createElement("div", `regen-overlay ${colClass}`);
+	for (let i = 0; i < optionCount; i++) {
+		overlay.appendChild(createElement("div", "regen-skeleton"));
+	}
+	const status = createElement("div", "regen-status", "Regenerating options...");
+	overlay.appendChild(status);
+
+	// Position overlay relative to options grid
+	optionsGrid.style.position = "relative";
+	optionsGrid.classList.add("regenerating");
+	optionsGrid.appendChild(overlay);
 
 	const originalText = button.textContent || "";
 	button.classList.add("loading");
@@ -482,7 +576,7 @@ async function regenerateSlide(button, slideId) {
 	const genMoreBtn = slideElement.querySelector(".btn-gen-more");
 	if (genMoreBtn) genMoreBtn.disabled = true;
 
-	pendingGenerate.set(slideId, { button, originalText, input, isRegen: true, optionsGrid, genMoreBtn });
+	pendingGenerate.set(slideId, { button, originalText, input, isRegen: true, optionsGrid, genMoreBtn, overlay });
 
 	try {
 		const body = { token: sessionToken, slideId };
@@ -502,7 +596,7 @@ function restoreRegenButton(slideId) {
 	if (!pending || !pending.isRegen) return;
 	pendingGenerate.delete(slideId);
 
-	const { button, originalText, input, optionsGrid, genMoreBtn } = pending;
+	const { button, originalText, input, optionsGrid, genMoreBtn, overlay } = pending;
 	if (button) {
 		button.classList.remove("loading");
 		button.disabled = false;
@@ -510,8 +604,11 @@ function restoreRegenButton(slideId) {
 	}
 	if (input) input.disabled = false;
 	if (optionsGrid) {
-		optionsGrid.style.opacity = "";
-		optionsGrid.style.pointerEvents = "";
+		optionsGrid.classList.remove("regenerating");
+		optionsGrid.style.position = "";
+	}
+	if (overlay && overlay.parentElement) {
+		overlay.remove();
 	}
 	if (genMoreBtn) genMoreBtn.disabled = false;
 }

package/generate-prompts.ts

@@ -36,7 +36,7 @@ function modelHints(generateModel?: string, thinking?: string, action?: string):
 	return hint;
 }
 
-export function buildGenerateMoreResult(slideId: string, slide: DeckSlide | undefined, prompt?: string, generateModel?: string, thinking?: string): string {
+export function buildGenerateMoreResult(slideId: string, slide: DeckSlide | undefined, prompt?: string, generateModel?: string, thinking?: string, count: number = 1): string {
 	const title = slide?.title ?? slideId;
 	const context = slide?.context ? `\nContext: ${slide.context}` : "";
 
@@ -54,15 +54,22 @@ export function buildGenerateMoreResult(slideId: string, slide: DeckSlide | unde
 	const { hasBlocks, formatHint } = formatHintForSlide(slide);
 	const template = optionTemplate(hasBlocks);
 	const userInstructions = prompt ? `\nUser instructions: "${prompt}"` : "";
+	
+	const optionWord = count === 1 ? "option" : "options";
+	const callInstructions = count === 1
+		? `YOU MUST generate one distinctive additional option and call design_deck with add-option.`
+		: `YOU MUST generate ${count} distinctive additional options. Call design_deck with add-option ${count} times (once per option).`;
 
 	return (
-		"The design deck is still open.\n\n" +
-		`User requested another option for slide \"${title}\".${context}${userInstructions}\n\n` +
+		"The design deck is still open and waiting for your response.\n\n" +
+		`User clicked "Generate ${count} ${optionWord}" for slide \"${title}\".${context}${userInstructions}\n\n` +
 		`Existing options:\n${existingText}\n\n` +
-		`Generate one distinctive additional option and call design_deck again:${modelHints(generateModel, thinking, "add-option")}\n\n` +
+		`${callInstructions} ` +
+		`Do not skip this step or decide the user has enough options — they explicitly requested ${count === 1 ? "another one" : `${count} more`}.${modelHints(generateModel, thinking, "add-option")}\n\n` +
 		`design_deck({\"action\":\"add-option\",\"slideId\":\"${slideId}\",\"option\":${JSON.stringify(template)}})\n\n` +
 		`The option field must be a JSON string with: label, optional description, optional aside (explanatory notes below preview), and optional recommended.\n` +
-		`${formatHint}`
+		`${formatHint}` +
+		(count > 1 ? `\n\nRemember: Call add-option ${count} times, each with a different option. Make each option distinctive.` : "")
 	);
 }
 
@@ -75,9 +82,10 @@ export function buildRegenerateResult(slideId: string, slide: DeckSlide | undefi
 	const userInstructions = prompt ? `\nUser instructions: "${prompt}"` : "";
 
 	return (
-		"The design deck is still open.\n\n" +
-		`User requested ALL options be regenerated for slide \"${title}\".${context}${userInstructions}\n\n` +
-		`Generate ${optionCount} fresh, distinctive options and call design_deck to replace all existing options:${modelHints(generateModel, thinking, "replace-options")}\n\n` +
+		"The design deck is still open and waiting for your response.\n\n" +
+		`User clicked "Regenerate all" for slide \"${title}\".${context}${userInstructions}\n\n` +
+		`YOU MUST generate ${optionCount} fresh, distinctive options and call design_deck with replace-options. ` +
+		`Do not skip this step — the user explicitly requested regeneration.${modelHints(generateModel, thinking, "replace-options")}\n\n` +
 		`design_deck({\"action\":\"replace-options\",\"slideId\":\"${slideId}\",\"options\":\"[${template}, ...]\"})` +
 		`\n\nThe options field must be a JSON string containing an array of ${optionCount} option objects.\n` +
 		`Each option needs: label, optional description, optional aside, optional recommended, and either previewHtml or previewBlocks.\n` +

package/index.ts

@@ -42,6 +42,8 @@ interface DeckDetails {
 	status: "completed" | "cancelled" | "generate-more" | "aborted" | "error";
 	url: string;
 	selections?: Record<string, string>;
+	notes?: Record<string, string>;
+	finalNotes?: string;
 	slideId?: string;
 	reason?: string;
 }
@@ -118,7 +120,7 @@ function clearDeckIdleTimer(): void {
 	}
 }
 
-function cleanupActiveDeck(): void {
+function cleanupActiveDeck(reason?: string): void {
 	clearDeckIdleTimer();
 	if (restoreDeckThinking) {
 		restoreDeckThinking();
@@ -126,20 +128,23 @@ function cleanupActiveDeck(): void {
 	}
 	if (!activeDeckServer) return;
 	try {
-		activeDeckServer.handle.close();
+		activeDeckServer.handle.close(reason);
 	} catch {}
 	activeDeckServer = null;
 }
 
 function cleanupActiveDeckAndStoreResult(result: DeckToolResult): void {
 	if (!activeDeckServer) return;
+	// Extract close reason from result details
+	const details = result.details as DeckDetails | undefined;
+	const closeReason = details?.status === "aborted" ? "aborted" : details?.reason;
 	if (activeDeckServer.currentResolve) {
 		const resolve = activeDeckServer.currentResolve;
-		cleanupActiveDeck();
+		cleanupActiveDeck(closeReason);
 		resolve(result);
 	} else {
 		pendingDeckResult = result;
-		cleanupActiveDeck();
+		cleanupActiveDeck(closeReason);
 	}
 }
 
@@ -181,10 +186,16 @@ function attachDeckAbortHandler(signal: AbortSignal | undefined): void {
 	signal.addEventListener("abort", abortHandler, { once: true });
 }
 
-function formatDeckSelections(selections: Record<string, string>): string {
+function formatDeckSelections(selections: Record<string, string>, notes?: Record<string, string>): string {
 	const entries = Object.entries(selections);
 	if (entries.length === 0) return "(none)";
-	return entries.map(([key, value]) => `- ${key}: ${value}`).join("\n");
+	return entries.map(([key, value]) => {
+		const note = notes?.[key];
+		if (note) {
+			return `- ${key}: ${value}\n  Notes: ${note}`;
+		}
+		return `- ${key}: ${value}`;
+	}).join("\n");
 }
 
 export default function (pi: ExtensionAPI) {
@@ -274,17 +285,8 @@ export default function (pi: ExtensionAPI) {
 					};
 				}
 
-				if (activeDeckServer.currentResolve !== null) {
-					return {
-						content: [
-							{
-								type: "text",
-								text: "Design deck is not waiting for a generated option right now.",
-							},
-						],
-						details: { status: "error", url: activeDeckServer.handle.url },
-					};
-				}
+				// Note: We don't check currentResolve here because multiple parallel
+				// add-option calls are valid (e.g., user requests 3 options at once)
 
 				const slideId = p.slideId as string;
 				const option = p.option as string;
@@ -320,14 +322,14 @@ export default function (pi: ExtensionAPI) {
 					};
 				}
 
-				if (onUpdate) {
-					onUpdate({
-						content: [{ type: "text", text: `Pushed new option to slide ${slideId}.` }],
-						details: { status: "generate-more", url: activeDeckServer.handle.url, slideId },
-					});
-				}
-				attachDeckAbortHandler(signal);
-				return blockOnDeck();
+				// For add-option, return immediately without blocking.
+				// This allows parallel add-option calls to all succeed.
+				// The deck stays open and will send a new prompt when the user
+				// clicks generate-more again or submits.
+				return {
+					content: [{ type: "text", text: `Pushed option "${parsedOption.label}" to slide ${slideId}.` }],
+					details: { status: "generate-more", url: activeDeckServer.handle.url, slideId },
+				};
 			}
 
 			if (p.action === "replace-options") {
@@ -472,17 +474,28 @@ export default function (pi: ExtensionAPI) {
 				};
 			}
 
-			const handleSubmit = (selections: Record<string, string>) => {
+			const handleSubmit = (selections: Record<string, string>, notes?: Record<string, string>, finalNotes?: string) => {
 				if (!activeDeckServer) return;
 				const url = activeDeckServer.handle.url;
+				const hasNotes = notes && Object.keys(notes).length > 0;
+				const textParts = [`Design deck completed.\n\nSelections:\n${formatDeckSelections(selections, notes)}`];
+				if (finalNotes) {
+					textParts.push(`\nAdditional instructions:\n${finalNotes}`);
+				}
 				cleanupActiveDeckAndStoreResult({
 					content: [
 						{
 							type: "text",
-							text: `Design deck completed.\n\nSelections:\n${formatDeckSelections(selections)}`,
+							text: textParts.join(""),
 						},
 					],
-					details: { status: "completed", url, selections },
+					details: { 
+						status: "completed", 
+						url, 
+						selections, 
+						...(hasNotes ? { notes } : {}),
+						...(finalNotes ? { finalNotes } : {}),
+					},
 				});
 			};
 
@@ -503,8 +516,12 @@ export default function (pi: ExtensionAPI) {
 				});
 			};
 
-			const handleGenerateMore = (slideId: string, prompt?: string, model?: string, thinking?: string) => {
-				if (!activeDeckServer?.currentResolve) return;
+			const handleGenerateMore = (slideId: string, prompt?: string, model?: string, thinking?: string, count?: number) => {
+				if (!activeDeckServer?.currentResolve) {
+					// Agent is no longer listening - close the deck
+					cleanupActiveDeck("stale");
+					return;
+				}
 				const resolve = activeDeckServer.currentResolve;
 				activeDeckServer.currentResolve = null;
 				armDeckIdleTimer();
@@ -513,8 +530,9 @@ export default function (pi: ExtensionAPI) {
 				if (thinking && !effectiveModel) {
 					pi.setThinkingLevel(thinking as "off" | "minimal" | "low" | "medium" | "high" | "xhigh");
 				}
+				const effectiveCount = count && count >= 1 && count <= 5 ? count : 1;
 				resolve({
-					content: [{ type: "text", text: buildGenerateMoreResult(slideId, slide, prompt, effectiveModel, thinking) }],
+					content: [{ type: "text", text: buildGenerateMoreResult(slideId, slide, prompt, effectiveModel, thinking, effectiveCount) }],
 					details: {
 						status: "generate-more",
 						url: activeDeckServer.handle.url,
@@ -524,7 +542,11 @@ export default function (pi: ExtensionAPI) {
 			};
 
 			const handleRegenerateSlide = (slideId: string, prompt?: string, model?: string, thinking?: string) => {
-				if (!activeDeckServer?.currentResolve) return;
+				if (!activeDeckServer?.currentResolve) {
+					// Agent is no longer listening - close the deck
+					cleanupActiveDeck("stale");
+					return;
+				}
 				const resolve = activeDeckServer.currentResolve;
 				activeDeckServer.currentResolve = null;
 				armDeckIdleTimer();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-design-deck",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Visual design deck for presenting multi-slide options with high-fidelity previews",
   "author": "Nico Bailon",
   "license": "MIT",