pi-design-deck 0.1.0 → 0.2.0

package/README.md

@@ -6,6 +6,8 @@
 
 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.
 
+<img width="1340" alt="Design Deck screenshot" src="https://github.com/user-attachments/assets/20864ac6-9223-4e2e-ba3c-db3eaae0abd8" />
+
 ## Usage
 
 Just ask. The agent reaches for the design deck when visual comparison makes sense.
@@ -40,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:
@@ -104,24 +108,12 @@ The browser opens, the user picks "JWT + Refresh Tokens", and the agent receives
 
 ## How It Works
 
-```
-┌─────────┐      ┌────────────────────────────────────────────┐      ┌─────────┐
-│  Agent   │      │             Browser Deck                   │      │  Agent   │
-│ invokes  ├─────►│                                            ├─────►│ receives │
-│design_   │      │  pick → pick → generate more → pick → submit     │selections│
-│  deck    │      │   ↑              ↑                         │      └─────────┘
-└─────────┘      │   │    SSE push ─┘   heartbeat ────────────┤
-                 └────────────────────────────────────────────┘
-```
-
-**Lifecycle:**
 1. Agent calls `design_deck()` with slides JSON — local HTTP server starts, browser opens
 2. User navigates slides, picks one option per slide
 3. Optionally clicks "Generate another option" — agent generates and pushes via `add-option`, deck stays open
 4. User submits — selections returned to agent as `{ slideId: "selected label" }`
-5. Tab auto-closes, thinking level restored to pre-deck value
 
-The server persists across tool re-invocations. When generate-more fires, the tool resolves with instructions for the agent to create a new option and call `design_deck({ action: "add-option", slideId: "...", option: "..." })`. The browser shows a skeleton placeholder with shimmer animation until the new option arrives via SSE.
+The server persists across tool re-invocations. When generate-more fires, the tool resolves with instructions for the agent to create a new option. The browser shows a skeleton placeholder with shimmer animation until the new option arrives via SSE.
 
 ## Slides
 
@@ -188,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`:
 
@@ -296,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;
@@ -87,6 +111,7 @@
   background: rgba(16,185,129,0.12); color: var(--dk-status-success);
   margin-left: auto;
 }
+.badge-generated + .option-num { margin-left: 6px; }
 
 /* Skeleton shimmer placeholder */
 .option-skeleton {
@@ -119,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

@@ -177,12 +177,6 @@ body {
   background: rgba(138,190,183,0.08);
   border-bottom-color: rgba(138,190,183,0.12);
 }
-.option.dimmed { opacity: 0.55; }
-.option.dimmed:hover {
-  opacity: 0.8;
-  border-color: rgba(var(--dk-ink),0.15);
-  transform: translateY(-1px);
-}
 
 .option-header {
   display: flex; align-items: center; gap: 8px;
@@ -205,8 +199,6 @@ body {
 .option:hover .option-radio { border-color: rgba(var(--dk-ink),0.35); }
 .option.selected .option-radio { border-color: var(--dk-accent); background: var(--dk-accent); }
 .option.selected .option-radio::after { background: #fff; }
-.option.dimmed .option-radio { border-color: rgba(var(--dk-ink),0.14); }
-.option.dimmed:hover .option-radio { border-color: rgba(var(--dk-ink),0.2); }
 
 .option-label { font-size: 13px; font-weight: 600; color: var(--dk-text-label); }
 
@@ -276,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;
@@ -296,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,30 +13,44 @@ 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) {
 	slideElement.querySelectorAll(".option").forEach((optionEl) => {
-		optionEl.classList.remove("selected", "dimmed");
+		optionEl.classList.remove("selected");
 		optionEl.setAttribute("aria-checked", "false");
 	});
 	selectedElement.classList.add("selected");
 	selectedElement.setAttribute("aria-checked", "true");
-	slideElement.querySelectorAll(".option").forEach((optionEl) => {
-		if (optionEl !== selectedElement) {
-			optionEl.classList.add("dimmed");
-		}
-	});
 }
 
 function selectOption(optionElement) {
@@ -342,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) {
@@ -374,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) {