Skip to content

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

Python

Create commits-and-variants.md

Abi Raja7b8bbba25f34
diff --git a/docs/commits-and-variants.md b/docs/commits-and-variants.md
new file mode 100644
index 00000000..8630f9e1
--- /dev/null
+++ b/docs/commits-and-variants.md
@@ -0,0 +1,241 @@
+# Commits and Non-Blocking Variants
+
+This document explains how the commit system and non-blocking variant generation work in screenshot-to-code.
+
+## Commit System
+
+### What are Commits?
+
+Commits represent discrete versions in the application's history. Each commit contains:
+
+- **Hash**: Unique identifier (generated using `nanoid()`)
+- **Parent Hash**: Links to previous commit for history tracking
+- **Variants**: Multiple code generation options (typically 2)
+- **Selected Variant**: Which variant the user is currently viewing
+- **Status**: Whether the commit is still being edited (`isCommitted: false`) or finalized (`isCommitted: true`)
+
+### Commit Types
+
+```typescript
+type CommitType = "ai_create" | "ai_edit" | "code_create";
+```
+
+- **ai_create**: Initial generation from screenshot/video
+- **ai_edit**: Updates based on user instructions
+- **code_create**: Import from existing code
+
+### Data Structure
+
+```typescript
+type Commit = {
+ hash: CommitHash;
+ parentHash: CommitHash | null;
+ dateCreated: Date;
+ isCommitted: boolean;
+ variants: Variant[];
+ selectedVariantIndex: number;
+ type: CommitType;
+ inputs: any; // Type-specific inputs
+}
+
+type Variant = {
+ code: string;
+ status: VariantStatus;
+}
+
+type VariantStatus = "generating" | "complete" | "cancelled";
+```
+
+### Storage and Management
+
+Commits are stored in the project store as a flat record:
+
+```typescript
+commits: Record<CommitHash, Commit>
+head: CommitHash | null // Current active commit
+```
+
+The `head` pointer tracks which commit is currently active. History is reconstructed by following `parentHash` links.
+
+## Non-Blocking Variants
+
+### Traditional Variant Generation (Before)
+
+```
+Start Generation → Wait for ALL variants → Show results
+User Experience: [Loading...........................] → Ready
+```
+
+Problems:
+- Users wait for the slowest variant
+- No interaction until everything completes
+- Poor perceived performance
+
+### Non-Blocking Variant Generation (After)
+
+```
+Start Generation → Show results as each variant completes
+User Experience: [Loading.....] → Ready (Option 1)
+ [Loading..........] → Ready (Option 2)
+```
+
+Benefits:
+- Immediate interaction when first variant completes
+- Can switch between completed variants while others generate
+- Significantly improved perceived performance
+
+### Implementation Overview
+
+#### Frontend Changes
+
+**App.tsx**: Enhanced event handling
+```typescript
+// New WebSocket events
+onVariantComplete: (variantIndex) => {
+ updateVariantStatus(commit.hash, variantIndex, 'complete');
+}
+onVariantError: (variantIndex, error) => {
+ updateVariantStatus(commit.hash, variantIndex, 'cancelled');
+}
+```
+
+**Sidebar.tsx**: Dual-condition UI
+```typescript
+// Show update UI when either condition is true
+{(appState === AppState.CODE_READY || isSelectedVariantComplete) && (
+ <UpdateInterface />
+)}
+```
+
+**Variants.tsx**: Real-time status indicators
+- Green dot: Complete variants
+- Red dot: Cancelled variants
+- Spinner: Currently generating variants
+
+#### Backend Changes
+
+**generate_code.py**: Independent variant processing
+```python
+# Process each variant independently
+async def process_variant_completion(index: int, task: asyncio.Task):
+ completion = await task # Wait for THIS variant only
+
+ # Process images immediately
+ processed_html = await perform_image_generation(...)
+
+ # Send to frontend immediately
+ await send_message("setCode", processed_html, index)
+ await send_message("variantComplete", "Variant generation complete", index)
+```
+
+### State Management
+
+#### App State vs Variant Status
+
+The system uses a **hybrid state approach**:
+
+- **AppState**: Global generation status (`INITIAL` → `CODING` → `CODE_READY`)
+- **Variant Status**: Individual variant status (`generating` → `complete`/`cancelled`)
+
+#### UI Logic
+
+```typescript
+// UI shows update interface when either:
+const canUpdate =
+ appState === AppState.CODE_READY || // All variants done
+ isSelectedVariantComplete; // Selected variant done
+
+// User can interact immediately when their selected variant completes
+```
+
+### WebSocket Protocol
+
+#### Events from Backend
+
+```typescript
+type WebSocketResponse = {
+ type: "chunk" | "status" | "setCode" | "variantComplete" | "variantError";
+ value: string;
+ variantIndex: number;
+}
+```
+
+- **chunk**: Streaming code content during generation
+- **status**: Status updates (e.g., "Generating images...")
+- **setCode**: Final code for a variant
+- **variantComplete**: Variant finished successfully
+- **variantError**: Variant failed with error
+
+#### Event Flow
+
+```
+Backend: Generate Variant 1 → "setCode" → "variantComplete"
+Frontend: Update UI → Allow interaction
+
+Backend: Generate Variant 2 → "setCode" → "variantComplete"
+Frontend: Update UI → User can switch to this variant
+
+Backend: Generate Variant 3 → "variantError"
+Frontend: Show error → Mark as cancelled
+```
+
+### User Experience Flow
+
+1. **User starts generation**
+ - All variants marked as `status: "generating"`
+ - UI shows loading state with spinners
+
+2. **First variant completes**
+ - Receives `variantComplete` event
+ - Status updated to `"complete"`
+ - If this is the selected variant → UI immediately allows updates
+ - User can start editing while other variants generate
+
+3. **User switches variants**
+ - Can switch to any completed variant immediately
+ - Can switch to generating variants (will show loading until complete)
+
+4. **User starts update**
+ - Automatically cancels all other generating variants
+ - Prevents wasted computation
+
+### Benefits
+
+1. **Perceived Performance**: Users see results 2-3x faster
+2. **Parallel Processing**: Multiple models generate simultaneously
+3. **Flexible Interaction**: Switch between ready options while others work
+4. **Resource Efficiency**: Cancel unused variants when user makes changes
+5. **Graceful Degradation**: System works even if some variants fail
+
+### Technical Considerations
+
+#### Variant Cancellation
+
+When users start updates, other generating variants are cancelled:
+
+```typescript
+// Cancel generating variants when user updates
+currentCommit.variants.forEach((variant, index) => {
+ if (index !== selectedVariantIndex && variant.status === 'generating') {
+ wsRef.current.send(JSON.stringify({
+ type: "cancel_variant",
+ variantIndex: index
+ }));
+ }
+});
+```
+
+#### Error Handling
+
+Each variant handles errors independently:
+- Failed variants don't block successful ones
+- Users see specific error messages per variant
+- System remains functional if some variants fail
+
+#### WebSocket Lifecycle
+
+- New generations replace previous WebSocket connections
+- Previous connections are closed to prevent resource leaks
+- Backend handles connection state checking before sending messages
+
+This architecture enables a responsive, non-blocking user experience while maintaining system reliability and resource efficiency.