pi-design-deck 0.1.1 → 0.3.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:
@@ -97,7 +99,9 @@ The browser opens, the user picks "JWT + Refresh Tokens", and the agent receives
 - **Slide columns**: `columns` property (1, 2, or 3) per slide. Auto-detected from option count if omitted.
 - **Smart rebalancing**: Grid layout recalculates after generate-more adds options to minimize orphans.
 - **Option aside**: Explanatory text rendered below the preview. Supports `\n` for line breaks.
-- **Save/load snapshots**: `Cmd+S` saves the deck to disk. Pass a file path to `slides` to reload a saved deck with selections pre-populated.
+- **Save/load snapshots**: `Cmd+S` saves the deck to disk. Use `action: "list"` to enumerate saved decks, `action: "open"` to reopen one by deck ID, or pass a file path to `slides`.
+- **Notes persistence**: Saved decks include selected-option notes and summary-slide final instructions, and reopening restores both from disk.
+- **Standalone HTML export**: `action: "export"` writes a read-only `export.html` next to the saved deck snapshot.
 - **Light/dark/auto theme**: Full theme toggle with `Cmd+Shift+L` (configurable). Persists in localStorage.
 - **Heartbeat watchdog**: Server detects lost browser connections (60s grace) and cleans up.
 - **Idle timeout**: 5-minute inactivity timer after generate-more. Closes the deck if the agent doesn't respond.
@@ -108,7 +112,7 @@ The browser opens, the user picks "JWT + Refresh Tokens", and the agent receives
 
 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
+3. Optionally clicks "Generate N options" — agent generates and pushes via `add-options`, deck stays open
 4. User submits — selections returned to agent as `{ slideId: "selected label" }`
 
 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.
@@ -164,21 +168,21 @@ The slide ID `"summary"` is reserved for the built-in summary slide that appears
 
 ## Generate-More Loop
 
-When the user clicks "Generate another option," the tool resolves with a structured prompt telling the agent which slide needs a new option, what options already exist, and what format to use. The agent generates one new option and pushes it:
+When the user clicks "Generate N options," the tool resolves with a structured prompt telling the agent which slide needs options, how many, what options already exist, and what format to use. The agent generates the requested options and pushes them all at once:
 
 ```typescript
 design_deck({
-  action: "add-option",
+  action: "add-options",
   slideId: "arch",
-  option: '{"label": "Serverless", "previewBlocks": [{"type": "code", "code": "...", "lang": "ts"}]}'
+  options: '[{"label": "Serverless", "previewBlocks": [...]}, {"label": "Edge", "previewBlocks": [...]}]'
 })
 ```
 
-The browser shows the new option with an entry animation. The tool blocks again, waiting for the next user action (submit, cancel, or another generate-more).
+The browser shows the new options with entry animations. The `add-options` call blocks until the next user action (submit, cancel, or another generate-more).
 
 ### 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`:
 
@@ -211,6 +215,21 @@ design_deck({ slides: "~/.pi/deck-snapshots/api-design-myapp-main-2026-02-22-143
 
 The deck opens with selections pre-populated and image paths resolved relative to the snapshot directory.
 
+**Listing saved decks:**
+```typescript
+design_deck({ action: "list" })
+```
+
+**Opening by deck ID:**
+```typescript
+design_deck({ action: "open", deckId: "api-design-myapp-main-2026-02-22-143000-submitted" })
+```
+
+**Exporting standalone HTML:**
+```typescript
+design_deck({ action: "export", deckId: "api-design-myapp-main-2026-02-22-143000-submitted", format: "html" })
+```
+
 **Snapshot structure:**
 ```
 ~/.pi/deck-snapshots/
@@ -270,15 +289,20 @@ The agent handles these when you use the slash commands or ask in natural langua
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `slides` | string | JSON string of deck config, or file path to a saved deck |
-| `action` | `"add-option"` \| `"replace-options"` | Push or replace options in a running deck |
+| `action` | `"add-options"` \| `"add-option"` \| `"replace-options"` \| `"list"` \| `"open"` \| `"export"` | Push/replace options, list saved decks, reopen a saved deck, or export one |
 | `slideId` | string | Target slide ID (required with actions) |
 | `option` | string | JSON string of one option (required with `add-option`) |
-| `options` | string | JSON string of option array (required with `replace-options`) |
+| `options` | string | JSON string of option array (required with `add-options` or `replace-options`) |
+| `deckId` | string | Saved deck ID from `action: "list"` (required with `open` / `export`) |
+| `format` | string | Export format for `action: "export"` (`"html"` currently supported) |
 
-Three modes of invocation:
+Six modes of invocation:
 1. **Start a new deck:** `design_deck({ slides: "<JSON>" })`
-2. **Add option to running deck:** `design_deck({ action: "add-option", slideId: "...", option: "<JSON>" })`
-3. **Replace all options on a slide:** `design_deck({ action: "replace-options", slideId: "...", options: "<JSON array>" })`
+2. **Add options to running deck:** `design_deck({ action: "add-options", slideId: "...", options: "<JSON array>" })` — blocks until next user action
+3. **Add single option (non-blocking):** `design_deck({ action: "add-option", slideId: "...", option: "<JSON>" })`
+4. **Replace all options on a slide:** `design_deck({ action: "replace-options", slideId: "...", options: "<JSON array>" })`
+5. **List saved decks:** `design_deck({ action: "list" })`
+6. **Open or export a saved deck:** `design_deck({ action: "open" | "export", deckId: "..." })`
 
 ## File Structure
 
@@ -286,6 +310,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
@@ -310,6 +335,18 @@ The extension includes a `design-deck` skill at `skills/design-deck/SKILL.md` th
 
 The skill is declared in `package.json` under `pi.skills` and is automatically discovered when the extension is installed. No manual copying needed.
 
+### Component Gallery Reference
+
+The skill includes a reference library for 60 UI components with best practices, common layouts, and aliases. Each component links to [component.gallery](https://component.gallery) where the agent can browse real screenshots when needed.
+
+**Before:** "Show me collapse options" → agent might not connect that to accordion, or know what components are available for the use case.
+
+**After:** Agent has 60 components to suggest from. Knows *collapse = accordion = disclosure = expander*. Knows *Blueprint = dense, dark-native; Ant = clean, blue primary.* Can browse [100+ real implementations](https://component.gallery/components/accordion/) when it needs concrete references.
+
+The reference enables discovery (find/suggest components), cross-referencing (connect related terms), and design vocabulary (know what systems look like) — plus guidance on *when* to show distinct design systems vs variations of one style.
+
+A separate vocabulary lookup (`LOOKUP.md`) resolves ambiguous user terms to canonical components. When a user says "dropdown" (Select? Combobox? Dropdown menu?) or "popup" (Modal? Popover? Tooltip?) or describes intent ("I need something that expands"), the agent can consult the lookup to understand what they mean and ask the right clarifying questions when needed.
+
 ## Limitations
 
 - Only one deck can be active at a time. Complete or cancel before starting another.
@@ -317,3 +354,7 @@ The skill is declared in `package.json` under `pi.skills` and is automatically d
 - The `summary` slide ID is reserved and cannot be used for custom slides.
 - Mermaid diagrams load from CDN — requires internet on first load.
 - macOS tested primarily; Linux and Windows support is best-effort.
+
+## Credits
+
+UI component reference data sourced from [component.gallery](https://component.gallery) by Iain Bean.

package/deck-schema.ts

@@ -229,6 +229,11 @@ export interface SavedDeckData {
 	config: DeckConfig;
 	selections: Record<string, string>;
 	savedAt: string;
+	id?: string;
+	status?: "submitted" | "in-progress" | "cancelled";
+	modifiedAt?: string;
+	notes?: Record<string, string>;
+	finalNotes?: string;
 	savedFrom?: {
 		cwd: string;
 		branch: string | null;
@@ -236,6 +241,14 @@ export interface SavedDeckData {
 	};
 }
 
+export type SavedDeckStatus = NonNullable<SavedDeckData["status"]>;
+
+export function deriveDeckStatusFromFolderName(folderName: string): SavedDeckStatus {
+	if (folderName.endsWith("-submitted")) return "submitted";
+	if (folderName.endsWith("-cancelled")) return "cancelled";
+	return "in-progress";
+}
+
 export function validateSavedDeck(data: unknown): SavedDeckData {
 	if (!data || typeof data !== "object" || Array.isArray(data)) {
 		throw new Error("Invalid saved deck: must be an object");
@@ -251,10 +264,27 @@ export function validateSavedDeck(data: unknown): SavedDeckData {
 		}
 	}
 
+	const notes: Record<string, string> = {};
+	if (obj.notes && typeof obj.notes === "object" && !Array.isArray(obj.notes)) {
+		for (const [key, val] of Object.entries(obj.notes as Record<string, unknown>)) {
+			if (typeof val === "string") notes[key] = val;
+		}
+	}
+
+	const status =
+		obj.status === "submitted" || obj.status === "in-progress" || obj.status === "cancelled"
+			? obj.status
+			: undefined;
+
 	return {
 		config,
 		selections,
 		savedAt: typeof obj.savedAt === "string" ? obj.savedAt : new Date().toISOString(),
+		id: typeof obj.id === "string" && obj.id.trim() !== "" ? obj.id : undefined,
+		status,
+		modifiedAt: typeof obj.modifiedAt === "string" ? obj.modifiedAt : undefined,
+		notes: Object.keys(notes).length > 0 ? notes : undefined,
+		finalNotes: typeof obj.finalNotes === "string" ? obj.finalNotes : undefined,
 		savedFrom: obj.savedFrom && typeof obj.savedFrom === "object"
 			? obj.savedFrom as SavedDeckData["savedFrom"]
 			: undefined,

package/deck-server.ts

@@ -66,6 +66,10 @@ const ABANDONED_GRACE_MS = 60000;
 const WATCHDOG_INTERVAL_MS = 5000;
 const GENERATE_TIMEOUT_MS = 90_000;
 
+export function getDefaultSnapshotDir(): string {
+	return join(homedir(), ".pi", "deck-snapshots");
+}
+
 function toStringMap(value: unknown): Record<string, string> | null {
 	if (!value || typeof value !== "object" || Array.isArray(value)) {
 		return null;
@@ -100,7 +104,7 @@ function processOptionAssets(option: DeckOption, assetsDir: string): DeckOption
 	return { ...option, previewBlocks: processImageBlocks(option.previewBlocks, assetsDir) };
 }
 
-const DECK_SNAPSHOTS_DIR = join(homedir(), ".pi", "deck-snapshots");
+const DECK_SNAPSHOTS_DIR = getDefaultSnapshotDir();
 
 function sanitizeForFilename(value: string): string {
 	return value.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 40).replace(/_+$/, "") || "unknown";
@@ -114,17 +118,30 @@ function saveDeckSnapshot(
 	gitBranch: string | null,
 	sessionId: string,
 	baseDir: string,
-	suffix?: string
+	options?: {
+		status?: "submitted" | "in-progress" | "cancelled";
+		notes?: Record<string, string>;
+		finalNotes?: string;
+	}
 ): { path: string; relativePath: string } {
 	const now = new Date();
+	const nowIso = now.toISOString();
 	const date = now.toISOString().slice(0, 10);
 	const time = now.toTimeString().slice(0, 8).replace(/:/g, "");
 	const titleSlug = sanitizeForFilename(config.title || "deck");
 	const project = sanitizeForFilename(basename(normalizedCwd) || "unknown");
 	const branch = sanitizeForFilename(gitBranch || "nogit");
+	const suffix = options?.status === "submitted" || options?.status === "cancelled" ? options.status : undefined;
 	const safeSuffix = suffix ? `-${suffix}` : "";
-	const folderName = `${titleSlug}-${project}-${branch}-${date}-${time}${safeSuffix}`;
-	const snapshotPath = join(baseDir, folderName);
+	const baseFolderName = `${titleSlug}-${project}-${branch}-${date}-${time}${safeSuffix}`;
+	let folderName = baseFolderName;
+	let snapshotPath = join(baseDir, folderName);
+	let collisionIndex = 2;
+	while (existsSync(snapshotPath)) {
+		folderName = `${baseFolderName}-${collisionIndex}`;
+		snapshotPath = join(baseDir, folderName);
+		collisionIndex += 1;
+	}
 	const imagesPath = join(snapshotPath, "images");
 
 	mkdirSync(snapshotPath, { recursive: true });
@@ -149,7 +166,12 @@ function saveDeckSnapshot(
 	const data = {
 		config: saved,
 		selections,
-		savedAt: now.toISOString(),
+		savedAt: nowIso,
+		id: folderName,
+		status: options?.status,
+		modifiedAt: nowIso,
+		notes: options?.notes && Object.keys(options.notes).length > 0 ? options.notes : undefined,
+		finalNotes: options?.finalNotes ? options.finalNotes : undefined,
 		savedFrom: { cwd: normalizedCwd, branch: gitBranch, sessionId },
 	};
 	writeFileSync(join(snapshotPath, "deck.json"), JSON.stringify(data, null, 2));
@@ -167,22 +189,24 @@ export interface DeckServerOptions {
 	port?: number;
 	theme?: { mode?: string; toggleHotkey?: string };
 	savedSelections?: Record<string, string>;
+	savedNotes?: Record<string, { label: string; notes: string }>;
+	savedFinalNotes?: string;
 	snapshotDir?: string;
 	autoSaveOnSubmit?: boolean;
 	models?: ModelsPayload;
 }
 
 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;
@@ -192,7 +216,19 @@ export async function startDeckServer(
 	options: DeckServerOptions,
 	callbacks: DeckServerCallbacks
 ): Promise<DeckServerHandle> {
-	const { config, sessionToken, sessionId, cwd, port, theme, savedSelections, snapshotDir, autoSaveOnSubmit } = options;
+	const {
+		config,
+		sessionToken,
+		sessionId,
+		cwd,
+		port,
+		theme,
+		savedSelections,
+		savedNotes,
+		savedFinalNotes,
+		snapshotDir,
+		autoSaveOnSubmit,
+	} = options;
 	const normalizedCwd = normalizePath(cwd);
 	const gitBranch = getGitBranch(cwd);
 
@@ -293,6 +329,8 @@ export async function startDeckServer(
 					gitBranch,
 					theme,
 					savedSelections,
+					savedNotes,
+					savedFinalNotes,
 				});
 				const title = config.title ? `${config.title} — Design Deck` : "Design Deck";
 				const html = DECK_TEMPLATE
@@ -414,24 +452,30 @@ 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) {
 					try {
-						saveDeckSnapshot(config, selections, assetsDir, normalizedCwd, gitBranch, sessionId, snapshotDir || DECK_SNAPSHOTS_DIR, "submitted");
+						saveDeckSnapshot(config, selections, assetsDir, normalizedCwd, gitBranch, sessionId, snapshotDir || DECK_SNAPSHOTS_DIR, {
+							status: "submitted",
+							notes,
+							finalNotes: finalNotes || undefined,
+						});
 					} catch {}
 				}
 				markCompleted();
 				unregisterSession(sessionId);
 				pushEvent("deck-close", { reason: "submitted" });
 				sendJson(res, 200, { ok: true });
-				setImmediate(() => callbacks.onSubmit(selections));
+				setImmediate(() => callbacks.onSubmit(selections, notes, finalNotes || undefined));
 				return;
 			}
 
@@ -439,12 +483,22 @@ export async function startDeckServer(
 				const body = await safeParseBody(req, res);
 				if (!body) return;
 				if (!validateTokenBody(body, sessionToken, res)) return;
+				if (completed) {
+					sendJson(res, 409, { ok: false, error: "Session closed" });
+					return;
+				}
 
-				const payload = body as { selections?: unknown };
+				const payload = body as { selections?: unknown; notes?: unknown; finalNotes?: unknown };
 				const selections = toStringMap(payload.selections) ?? {};
+				const notes = toStringMap(payload.notes) ?? undefined;
+				const finalNotes = typeof payload.finalNotes === "string" ? payload.finalNotes.trim() : undefined;
 
 				try {
-					const result = saveDeckSnapshot(config, selections, assetsDir, normalizedCwd, gitBranch, sessionId, snapshotDir || DECK_SNAPSHOTS_DIR);
+					const result = saveDeckSnapshot(config, selections, assetsDir, normalizedCwd, gitBranch, sessionId, snapshotDir || DECK_SNAPSHOTS_DIR, {
+						status: "in-progress",
+						notes,
+						finalNotes: finalNotes || undefined,
+					});
 					sendJson(res, 200, { ok: true, path: result.path, relativePath: result.relativePath });
 				} catch (err) {
 					const message = err instanceof Error ? err.message : "Save failed";
@@ -471,7 +525,9 @@ export async function startDeckServer(
 				const cancelSelections = toStringMap(payload.selections);
 				if (cancelSelections && Object.keys(cancelSelections).length > 0) {
 					try {
-						saveDeckSnapshot(config, cancelSelections, assetsDir, normalizedCwd, gitBranch, sessionId, snapshotDir || DECK_SNAPSHOTS_DIR, "cancelled");
+						saveDeckSnapshot(config, cancelSelections, assetsDir, normalizedCwd, gitBranch, sessionId, snapshotDir || DECK_SNAPSHOTS_DIR, {
+							status: "cancelled",
+						});
 					} catch {}
 				}
 
@@ -492,7 +548,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 +565,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 +660,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();