pi-design-deck 0.2.0 → 0.3.1

package/README.md

@@ -96,10 +96,12 @@ The browser opens, the user picks "JWT + Refresh Tokens", and the agent receives
 - **Generate-more loop**: Users click "Generate another option" and the agent pushes a new option into the live deck via SSE. No page reload.
 - **Model selector**: Dropdown to pick which model generates new options. Save as default, or override per-request.
 - **Thinking level**: Adjust reasoning effort for option generation when the selected model supports it.
-- **Slide columns**: `columns` property (1, 2, or 3) per slide. Auto-detected from option count if omitted.
+- **Slide columns**: `columns` property (1, 2, 3, or 4) 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.
@@ -110,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.
@@ -154,7 +156,7 @@ Image blocks reference absolute file paths. The server copies each file into a t
 
 ### Columns
 
-Each slide supports `columns: 1 | 2 | 3` to control the grid layout. Omit it and the deck auto-detects based on option count. Use `columns: 1` for wide architecture diagrams, `columns: 2` for side-by-side comparisons.
+Each slide supports `columns: 1 | 2 | 3 | 4` to control the grid layout. Omit it and the deck auto-detects based on option count. Use `columns: 1` for wide architecture diagrams, `columns: 2` for side-by-side comparisons, `columns: 4` for many small items.
 
 ### Aside
 
@@ -166,17 +168,17 @@ 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
 
@@ -213,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/
@@ -272,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
 
@@ -313,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.
@@ -320,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

@@ -17,7 +17,7 @@ export interface DeckSlide {
 	id: string;
 	title: string;
 	context?: string;
-	columns?: 1 | 2 | 3;
+	columns?: 1 | 2 | 3 | 4;
 	options: DeckOption[];
 }
 
@@ -155,8 +155,8 @@ function validateDeckSlide(slide: unknown, index: number): DeckSlide {
 	}
 
 	if (obj.columns !== undefined) {
-		if (obj.columns !== 1 && obj.columns !== 2 && obj.columns !== 3) {
-			throw new Error(`Slide "${obj.id}": columns must be 1, 2, or 3`);
+		if (obj.columns !== 1 && obj.columns !== 2 && obj.columns !== 3 && obj.columns !== 4) {
+			throw new Error(`Slide "${obj.id}": columns must be 1, 2, 3, or 4`);
 		}
 	}
 
@@ -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,6 +189,8 @@ 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;
@@ -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
@@ -426,7 +464,11 @@ export async function startDeckServer(
 				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();
@@ -441,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";
@@ -473,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 {}
 				}