Skip to content

Drop in a screenshot and convert it to clean code (HTML/Tailwind/React/Vue)

Python

Consolidate design documentation into concise variant system doc

Abi Rajaab90aeee8fb1
diff --git a/VARIANT_EXPANSION_PLAN.md b/VARIANT_EXPANSION_PLAN.md
deleted file mode 100644
index 278e47c0..00000000
--- a/VARIANT_EXPANSION_PLAN.md
+++ /dev/null
@@ -1,234 +0,0 @@
-# Plan: Support Generic Number of Variants (Default: 3)
-
-## Current System Analysis
-
-**Current State:**
-
-- Fixed `NUM_VARIANTS = 2` in config
-- Hard-coded 2-variant grid layout (`grid-cols-2`)
-- Fixed 2-variant model selection logic
-- Hard-coded 2-variant initialization in frontend
-
-## Implementation Plan
-
-### Phase 1: Backend Configuration & Model Selection
-
-**1.1 Generic Variant Count Support**
-
-- Change `NUM_VARIANTS = 3` in backend config (default)
-- Design system to work with any NUM_VARIANTS value (2, 3, 4, 5, etc.)
-- Frontend learns variant count from backend response
-
-**1.2 Dynamic Model Selection Strategy**
-
-```python
-# Generic model selection that scales with NUM_VARIANTS:
-def get_variant_models(generation_type, num_variants, openai_api_key, anthropic_api_key):
- if anthropic_api_key:
- # Claude models (preferred)
- claude_models = [
- Llm.CLAUDE_3_7_SONNET_2025_02_19, # Primary
- Llm.CLAUDE_3_5_SONNET_2024_10_22, # Alternative 1
- Llm.CLAUDE_3_5_SONNET_2024_06_20, # Alternative 2
- Llm.CLAUDE_4_SONNET_2025_05_14, # Alternative 3
- Llm.CLAUDE_4_OPUS_2025_05_14, # Alternative 4
- ]
-
- if generation_type == "create":
- # Reorder for creation (3.7 first)
- preferred_order = [0, 1, 2, 3, 4] # Keep same order
- else:
- # Reorder for updates (3.5 first)
- preferred_order = [2, 1, 0, 3, 4] # 3.5 first, then others
-
- selected_models = [claude_models[i] for i in preferred_order[:num_variants]]
-
- # If we need more models than available, cycle through them
- while len(selected_models) < num_variants:
- selected_models.extend(claude_models)
-
- return selected_models[:num_variants]
-
- elif openai_api_key:
- # OpenAI models fallback
- openai_models = [
- Llm.GPT_4O_2024_11_20,
- Llm.GPT_4_1_NANO_2025_04_14,
- Llm.GPT_4_1_MINI_2025_04_14,
- Llm.O1_2024_12_17,
- Llm.GPT_4_1_2025_04_14,
- ]
-
- # Cycle through models if we need more than available
- selected_models = []
- for i in range(num_variants):
- selected_models.append(openai_models[i % len(openai_models)])
-
- return selected_models
-```
-
-### Phase 2: Frontend UI Adaptation
-
-**2.1 Fully Dynamic Grid Layout**
-
-```tsx
-// Generic grid layout that works for any number of variants:
-const getGridClass = (variantCount: number) => {
- if (variantCount <= 2) {
- return "grid grid-cols-2 gap-2";
- } else if (variantCount === 3) {
- return "grid grid-cols-3 gap-2";
- } else if (variantCount === 4) {
- return "grid grid-cols-2 gap-2"; // 2x2 grid
- } else if (variantCount <= 6) {
- return "grid grid-cols-3 gap-2"; // 3x2 grid
- } else {
- return "grid grid-cols-4 gap-2"; // 4x? grid for larger counts
- }
-};
-
-// Alternative: responsive grid that adapts to content
-const getResponsiveGridClass = (variantCount: number) => {
- return `grid gap-2 grid-cols-${Math.min(variantCount, 4)}`;
-};
-```
-
-**2.2 Backend-Driven Variant Count Discovery**
-
-```tsx
-// Frontend automatically discovers variant count from backend:
-const variantCount = commit.variants.length; // Dynamic discovery
-const gridClass = getGridClass(variantCount);
-
-// All variant-related UI scales automatically:
-// - Grid layout
-// - Keyboard shortcuts (1-9 supported)
-// - Status indicators
-// - Error handling
-```
-
-**2.3 Generic Commit Initialization**
-
-```tsx
-// Frontend creates commits based on backend-provided variant count:
-// Backend includes NUM_VARIANTS in response or sends initial variants array
-const baseCommitObject = {
- variants: Array(variantCount)
- .fill(null)
- .map(() => ({ code: "" })),
-};
-```
-
-### Phase 3: Enhanced UX for Any Number of Variants
-
-**3.1 Scalable Keyboard Shortcuts**
-
-- Support keys 1-9 for variant switching (covers up to 9 variants)
-- Visual indicators show appropriate numbers (1, 2, 3, ..., N)
-- Keyboard shortcuts work regardless of variant count
-
-**3.2 Responsive Grid Layouts**
-
-- 2 variants: 2-column layout
-- 3 variants: 3-column layout
-- 4 variants: 2x2 grid
-- 5-6 variants: 3x2 grid
-- 7+ variants: 4-column grid with wrapping
-
-**3.3 Scalable Performance**
-
-- Design handles any reasonable number of variants (2-10)
-- Memory management scales with variant count
-- Error handling works for N variants
-- WebSocket message handling scales automatically
-
-## Implementation Priority
-
-### High Priority (MVP for generic variant support)
-
-1. ✅ Backend: Change NUM_VARIANTS to 3 (default)
-2. ✅ Backend: Generic model selection that scales with NUM_VARIANTS
-3. ✅ Frontend: Fully dynamic grid layout for any variant count
-4. ✅ Frontend: Backend-driven variant count discovery
-5. ✅ Frontend: Generic commit initialization
-
-### Medium Priority (UX improvements)
-
-6. ✅ Scalable keyboard shortcuts (1-9)
-7. ✅ Responsive grid layouts for different variant counts
-8. ✅ Performance testing with variable variant counts
-
-## Technical Considerations
-
-**Memory Usage:**
-
-- Memory usage scales linearly with variant count (N variants = N×base usage)
-- Monitor memory consumption with variable parallel generations
-- Current streaming architecture should handle this well
-
-**API Costs:**
-
-- API costs scale linearly with variant count (N variants = N×base cost)
-- Using Claude models keeps costs predictable across variant counts
-- Easy to control costs by adjusting NUM_VARIANTS constant
-
-**Performance:**
-
-- Parallel generation should handle any reasonable variant count (2-10)
-- Monitor WebSocket message throughput with higher variant counts
-- Existing error handling scales naturally
-
-**Error Handling:**
-
-- More variants = higher chance of partial failures
-- Current error handling system designed to handle N variants
-- Test graceful degradation with various variant counts
-
-## Success Metrics
-
-1. **Flexibility:** System works seamlessly with NUM_VARIANTS = 2, 3, 4, 5, etc.
-2. **User Experience:** UI adapts beautifully to any variant count
-3. **Performance:** Generation time scales reasonably with variant count
-4. **System Stability:** Error rates remain stable across variant counts
-
-## Implementation Checklist
-
-### Backend Changes
-
-- [ ] Change `NUM_VARIANTS = 3` in config.py (default)
-- [ ] Create generic `get_variant_models()` function
-- [ ] Update `ModelSelectionStage` to use generic model selection
-- [ ] Ensure `StatusBroadcastMiddleware` uses NUM_VARIANTS dynamically
-- [ ] Test with NUM_VARIANTS = 2, 3, 4, 5
-
-### Frontend Changes
-
-- [ ] Update App.tsx to create variants dynamically from backend count
-- [ ] Modify Variants.tsx for fully dynamic grid layout
-- [ ] Ensure keyboard shortcuts support 1-9 keys
-- [ ] Add responsive grid layouts for different variant counts
-- [ ] Test variant switching with various counts (2, 3, 4, 5)
-
-### Testing & QA
-
-- [ ] Test NUM_VARIANTS = 2 (backward compatibility)
-- [ ] Test NUM_VARIANTS = 3 (new default)
-- [ ] Test NUM_VARIANTS = 4 (2x2 grid)
-- [ ] Test NUM_VARIANTS = 5 (stress test)
-- [ ] Verify UI layouts for all variant counts
-- [ ] Performance testing with various variant counts
-
-## Notes
-
-- Design for maximum flexibility: changing NUM_VARIANTS should "just work"
-- Frontend automatically adapts to any backend variant count
-- No user settings needed - backend NUM_VARIANTS constant controls everything
-- Focus on making grid layouts look good for common variant counts (2, 3, 4)
-- System should gracefully handle edge cases (1 variant, 10+ variants)
-
-## Abi's Notes
-
-- [DONE] Let's set up a number of models that we want. And it will just cycle through those and repeat them. If models are [A, B], then if num = 5, it will be [A, B, A, B, A] and so on.
-
-1. [DONE] With 3 options, it looks too squished on the front-end.
-2. [DONE] We need to change hotkey to Option + 1, 2, 3, etc because when focused on textbox, the 1, 2, 3 keys are captured by the textbox. Fixed using event.code for cross-platform compatibility.
diff --git a/design-docs.md b/design-docs.md
deleted file mode 100644
index eb381198..00000000
--- a/design-docs.md
+++ /dev/null
@@ -1,5 +0,0 @@
-## Version History
-
-Version history is stored as a tree on the client-side.
-
-![Screenshot to Code](https://github.com/abi/screenshot-to-code/assets/23818/e35644aa-b90a-4aa7-8027-b8732796fd7c)
diff --git a/docs/commits-and-variants.md b/design-docs/commits-and-variants.md
similarity index 100%
rename from docs/commits-and-variants.md
rename to design-docs/commits-and-variants.md
diff --git a/design-docs/variant-system.md b/design-docs/variant-system.md
new file mode 100644
index 00000000..d5761ecc
--- /dev/null
+++ b/design-docs/variant-system.md
@@ -0,0 +1,79 @@
+# Variant System
+
+## Overview
+
+The variant system generates multiple code options in parallel, allowing users to compare different AI-generated implementations. The system defaults to 3 variants and scales automatically by changing `NUM_VARIANTS` in config.
+
+## Configuration
+
+**Key Setting:** `NUM_VARIANTS = 3` in `backend/config.py`
+
+Changing this value automatically scales the entire system to support any number of variants.
+
+## Model Selection
+
+Models cycle based on available API keys:
+
+```python
+# Both API keys present
+models = [claude_model, Llm.GPT_4_1_NANO_2025_04_14]
+
+# Claude only
+models = [claude_model, Llm.CLAUDE_3_5_SONNET_2024_06_20]
+
+# OpenAI only
+models = [Llm.GPT_4O_2024_11_20]
+```
+
+**Cycling:** If models = [A, B] and NUM_VARIANTS = 5, result is [A, B, A, B, A]
+
+**Generation Type:**
+- **Create**: Primary model is Claude 3.7 Sonnet
+- **Update**: Primary model is Claude 3.5 Sonnet
+
+## Frontend
+
+### Grid Layouts
+- **2 variants**: 2-column
+- **3 variants**: 2-column (third wraps below - prevents squishing)
+- **4 variants**: 2x2 grid
+- **5-6 variants**: 3-column
+- **7+ variants**: 4-column
+
+### Keyboard Shortcuts
+- **Option/Alt + 1, 2, 3...**: Switch variants
+- Works globally, even in text fields
+- Uses `event.code` for cross-platform compatibility
+- Visual indicators show ⌥1, ⌥2, ⌥3
+
+## Architecture
+
+### Backend
+- `StatusBroadcastMiddleware` sends `variantCount` to frontend
+- `ModelSelectionStage` cycles through available models
+- Pipeline generates variants in parallel via WebSocket
+
+### Frontend
+- Learns variant count from backend dynamically
+- `resizeVariants()` adapts UI to backend count
+- Error handling per variant with status display
+
+## WebSocket Messages
+
+```typescript
+"variantCount" | "chunk" | "status" | "setCode" | "variantComplete" | "variantError"
+```
+
+## Implementation Notes
+
+✅ **Scalable**: Change `NUM_VARIANTS` and everything adapts
+✅ **Cross-platform**: Keyboard shortcuts work Mac/Windows
+✅ **Responsive**: Grid layouts adapt to count
+✅ **Simple**: Model cycling handles any variant count
+
+## Key Files
+
+- `backend/config.py` - NUM_VARIANTS setting
+- `backend/routes/generate_code.py` - Model selection pipeline
+- `frontend/src/components/variants/Variants.tsx` - UI and shortcuts
+- `frontend/src/store/project-store.ts` - State management