Implement Rendervid Studio: Web-based Preview & Development Environment

**Parent Issue:** #24 (Feature Parity Analysis)

---

## Overview

Create a web-based development environment for Rendervid templates inspired by Remotion Studio, featuring real-time preview, hot module replacement (HMR), and intuitive editing tools. This addresses one of the most critical gaps identified in the feature parity analysis - the lack of dedicated developer tooling for rapid iteration and visual template development.

**Current State:** Developers must rebuild/re-render to preview changes, leading to slow iteration cycles.

**Goal:** Provide a browser-based GUI with live preview, timeline editor, property inspector, and instant feedback during template development.

---

## Research Summary

Comprehensive research has been completed on Remotion Studio's architecture and capabilities. Key findings:

- **Architecture:** Web-based (not Electron), runs on Node.js development server
- **Bundler:** Uses Webpack 5 (we'll use Vite for faster builds)
- **HMR:** WebSocket-based hot module replacement with state preservation
- **UI Components:**
  - Composition sidebar for switching between templates
  - Canvas preview with zoom and pan controls
  - Properties panel with Zod-based schema validation
  - Timeline with frame-accurate scrubbing
- **Timeline Modes:**
  - Simple mode: Basic scrubbing and frame navigation
  - Rich mode: Layer visualization, thumbnails, audio waveforms
- **Hot Reload:** Preserves playback position, zoom level, and selection during updates
- **Render Queue:** Export multiple videos with different configurations

---

## Proposed Architecture

```
rendervid-studio/
├── packages/
│   ├── studio-cli/           # Dev server, bundler, HMR engine
│   ├── studio/               # Enhanced editor UI (React app)
│   └── studio-types/         # Shared TypeScript types
```

### Technology Stack

- **Dev Server:** Vite (faster than Webpack, better DX)
- **UI Framework:** React 19
- **State Management:** Zustand (already used in Rendervid)
- **Styling:** Tailwind CSS (already used in Rendervid)
- **UI Components:** Radix UI for accessible primitives
- **Command Palette:** cmdk (Cmd+K quick switcher)
- **Animations:** Framer Motion
- **Virtual Lists:** react-window (for performance)

---

## Core Features

### Phase 1: MVP (6 weeks)

- [ ] **Development Server with HMR**
  - Vite-based dev server with WebSocket HMR
  - Watch template files and auto-reload on changes
  - Error overlay for parse failures
  - State preservation during reload

- [ ] **Basic Studio UI Layout**
  - Three-panel layout: sidebar, canvas, properties
  - Responsive design for different screen sizes
  - Dark mode support

- [ ] **Simple Timeline with Scrubbing**
  - Frame-accurate playhead scrubbing
  - Click-to-seek functionality
  - Zoom controls (10%, 25%, 50%, 100%, 200%)
  - Frame markers and time indicators
  - Play/pause controls

- [ ] **Composition Sidebar**
  - List all available templates/compositions
  - Quick switching between templates
  - Search/filter compositions
  - Display composition metadata (duration, FPS, resolution)

- [ ] **Basic Property Editor**
  - Display template input properties
  - Edit values with immediate preview
  - Type-appropriate controls (text, number, color)
  - Reset to default values

- [ ] **Keyboard Shortcuts**
  - Space: Play/pause
  - Left/Right arrows: Frame navigation
  - J/K/L: Shuttle controls
  - Home/End: Jump to start/end
  - +/-: Zoom timeline

- [ ] **Export Single Video**
  - Export current composition with current props
  - Progress indicator
  - Format selection (MP4, WebM, MOV)
  - Quality settings

### Phase 2: Enhanced (4 weeks)

- [ ] **Zod Schema Property Editor**
  - Auto-generate UI controls from Zod schemas
  - `z.string()` → Text input
  - `z.number()` → Number input/slider
  - `z.boolean()` → Checkbox/toggle
  - `z.enum()` → Select dropdown
  - `z.object()` → Nested property group
  - `z.array()` → Dynamic list with add/remove
  - Validation feedback and error messages

- [ ] **Render Queue System**
  - Queue multiple render jobs
  - Batch rendering with different prop values
  - Priority management
  - Retry failed renders
  - Download rendered videos
  - Job history

- [ ] **Quick Switcher (Cmd+K)**
  - Fuzzy search for compositions
  - Navigate to specific frames
  - Execute commands
  - Recent compositions

- [ ] **Better Error Handling**
  - Detailed error overlay with stack traces
  - JSON schema validation errors
  - Component render errors
  - Network errors
  - Actionable error messages

- [ ] **Performance Optimizations**
  - Lazy load compositions
  - Optimize canvas rendering
  - Debounce property updates
  - Virtual scrolling for long timelines

### Phase 3: Advanced (4 weeks)

- [ ] **Rich Timeline Mode**
  - Layer tracks for visual hierarchy
  - Video thumbnails for each frame
  - Audio waveforms for audio tracks
  - Fade in/out handles
  - Layer selection and reordering
  - Collapsed/expanded layer view

- [ ] **Advanced Render Options**
  - Custom output dimensions
  - Frame range selection
  - Quality presets (draft, standard, high)
  - Codec configuration
  - Audio settings
  - Watermark overlay

- [ ] **Multi-selection and Batch Operations**
  - Select multiple layers
  - Bulk property editing
  - Copy/paste properties
  - Group operations

### Phase 4: Polish (2 weeks)

- [ ] **Documentation**
  - Getting started guide
  - Studio interface overview
  - Keyboard shortcuts reference
  - Zod schema tutorial for property generation
  - Performance optimization guide
  - Troubleshooting common issues

- [ ] **Example Templates**
  - Starter templates showcasing features
  - Complex examples with animations
  - Best practices demonstrations

- [ ] **Bug Fixes**
  - Address issues discovered during beta testing
  - Performance profiling and fixes
  - Cross-browser compatibility

- [ ] **Performance Tuning**
  - Optimize bundle size
  - Reduce memory footprint
  - Improve render performance
  - Faster HMR updates

---

## Implementation Details

### Development Server Configuration

```typescript
interface ServerConfig {
  port: number;              // Default: 3000
  host: string;              // Default: 'localhost'
  open: boolean;             // Auto-open browser
  hmr: boolean;              // Enable HMR (default: true)
  strictMode: boolean;       // React strict mode
  clearScreen: boolean;      // Clear terminal on reload
}
```

### HMR Implementation Strategy

1. **File Watching:**
   - Use chokidar to watch template JSON files
   - Monitor component changes in real-time

2. **Vite Integration:**
   - Implement custom Vite plugin with `handleHotUpdate` hook
   - Parse changed templates and validate
   - Send update events via WebSocket

3. **State Preservation:**
   - Store current frame position in Zustand
   - Preserve zoom level and pan offset
   - Maintain selected layers/properties
   - Restore state after reload

4. **Error Handling:**
   - Show error overlay for parse failures
   - Display JSON schema validation errors
   - Provide helpful error messages with line numbers

### Timeline Features

#### Simple Mode (Default)
- **Click to Seek:** Click anywhere on timeline to jump to frame
- **Drag Playhead:** Smooth scrubbing with visual feedback
- **Zoom Controls:** Buttons for 10%, 25%, 50%, 100%, 200% zoom
- **Frame Markers:** Visual indicators every 1 second
- **Time Display:** Current time and total duration
- **Keyboard Navigation:** Arrow keys for frame-by-frame navigation

#### Rich Mode (Experimental)
- **Layer Tracks:** Each component/layer on separate track
- **Video Thumbnails:** Generated thumbnails for visual reference
- **Audio Waveforms:** Visualize audio amplitude over time
- **Fade Handles:** Drag handles to adjust opacity transitions
- **Layer Controls:** Visibility toggles, lock, solo
- **Performance:** Virtual scrolling for 50+ layers

### Zod Property Editor Auto-generation

Map Zod schema types to UI controls:

```typescript
const schemaToControl = {
  'z.string()': TextInput,
  'z.number()': NumberInput,
  'z.number().min(0).max(100)': Slider,
  'z.boolean()': Checkbox,
  'z.enum()': SelectDropdown,
  'z.object()': NestedPropertyGroup,
  'z.array()': DynamicList,
  'z.union()': UnionSelector,
  'z.literal()': ReadOnlyDisplay,
};
```

**Features:**
- Automatic label generation from property names
- Help text from `.describe()` metadata
- Default values from `.default()`
- Validation with immediate feedback
- Nested object drilling
- Array item add/remove

---

## Success Metrics

- **Time to First Preview:** < 5 seconds from `npx rendervid dev`
- **HMR Update Speed:** < 200ms from file save to preview update
- **Preview Frame Rate:** 30+ FPS during playback
- **Memory Usage:** < 500MB for typical project (10 templates)
- **Developer Satisfaction:** Positive feedback from early adopters
- **Bundle Size:** Studio UI < 1MB gzipped

---

## Technical Challenges

### 1. Template Format Differences

**Challenge:** Rendervid uses JSON templates, Remotion uses React components.

**Solution:**
- Auto-generate React compositions from JSON templates
- Use dynamic imports for component loading
- Create adapter layer between JSON and React

### 2. HMR for JSON Files

**Challenge:** Vite's HMR is designed for JavaScript modules, not JSON templates.

**Solution:**
- Manual file watching with chokidar
- Custom Vite plugin to handle JSON updates
- Implement own hot update protocol via WebSocket
- Parse and validate JSON before sending update

### 3. Rich Timeline Performance

**Challenge:** Rendering thumbnails and waveforms is expensive with many layers.

**Solution:**
- Virtual scrolling to render only visible tracks
- Web Worker for thumbnail generation
- IndexedDB cache for generated thumbnails
- Lazy load waveforms on demand
- Debounce timeline updates during scrubbing

### 4. State Synchronization

**Challenge:** Keep preview in sync with property editor changes.

**Solution:**
- Centralized Zustand store for all state
- Optimistic updates with rollback on error
- Debounce rapid property changes
- Queue updates during animation playback

---

## Documentation Requirements

### Getting Started Guide
- Installation instructions
- First project setup
- Basic workflow walkthrough
- Common operations tutorial

### Studio Interface Overview
- UI component reference
- Panel descriptions
- Toolbar buttons
- Status indicators

### Keyboard Shortcuts Reference
- Complete shortcut list organized by category
- Printable cheat sheet
- Customization options

### Zod Schema Tutorial
- How to define input schemas
- Schema-to-UI control mapping
- Advanced validation patterns
- Custom control registration

### Performance Optimization Guide
- Best practices for large projects
- Memory management tips
- Render optimization strategies
- Profiling tools

---

## Dependencies

```json
{
  "dependencies": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    "zustand": "^4.5.0",
    "zod": "^3.22.4",
    "framer-motion": "^11.0.0",
    "@radix-ui/react-dialog": "^1.0.5",
    "@radix-ui/react-select": "^2.0.0",
    "@radix-ui/react-slider": "^1.1.2",
    "@radix-ui/react-switch": "^1.0.3",
    "cmdk": "^0.2.0",
    "react-window": "^1.8.10"
  },
  "devDependencies": {
    "vite": "^5.0.0",
    "@vitejs/plugin-react": "^4.2.0",
    "chokidar": "^3.5.3",
    "typescript": "^5.3.3",
    "@types/react": "^19.0.0",
    "@types/react-dom": "^19.0.0"
  }
}
```

---

## Estimated Timeline

**Total: 14-16 weeks (3.5-4 months)**

| Phase | Duration | Deliverable |
|-------|----------|-------------|
| Phase 1: MVP | 6 weeks | Basic functional studio with preview and HMR |
| Phase 2: Enhanced | 4 weeks | Zod property editor, render queue, quick switcher |
| Phase 3: Advanced | 4 weeks | Rich timeline, advanced render options |
| Phase 4: Polish | 2 weeks | Documentation, examples, bug fixes |

**Milestones:**
- Week 6: MVP demo-ready
- Week 10: Beta release for early adopters
- Week 14: Production-ready 1.0 release
- Week 16: Polish and launch

---

## References

- Parent Issue: #24 (Feature Parity Analysis)
- [Remotion Studio Documentation](https://www.remotion.dev/docs/studio)
- Full technical specification available in research document
- Remotion GitHub: https://github.com/remotion-dev/remotion

---

## Next Steps

1. Review and approve technical architecture
2. Create detailed task breakdown for Phase 1
3. Set up `studio-cli`, `studio`, and `studio-types` package structure
4. Begin development server implementation
5. Design UI mockups for Studio interface

---

🤖 Generated with Claude Code

Phase	Duration	Deliverable
Phase 1: MVP	6 weeks	Basic functional studio with preview and HMR
Phase 2: Enhanced	4 weeks	Zod property editor, render queue, quick switcher
Phase 3: Advanced	4 weeks	Rich timeline, advanced render options
Phase 4: Polish	2 weeks	Documentation, examples, bug fixes

Implement Rendervid Studio: Web-based Preview & Development Environment #28

Description

Overview

Research Summary

Proposed Architecture

Technology Stack

Core Features

Phase 1: MVP (6 weeks)

Phase 2: Enhanced (4 weeks)

Phase 3: Advanced (4 weeks)

Phase 4: Polish (2 weeks)

Implementation Details

Development Server Configuration

HMR Implementation Strategy

Timeline Features

Simple Mode (Default)

Rich Mode (Experimental)

Zod Property Editor Auto-generation

Success Metrics

Technical Challenges

1. Template Format Differences

2. HMR for JSON Files

3. Rich Timeline Performance

4. State Synchronization

Documentation Requirements

Getting Started Guide

Studio Interface Overview

Keyboard Shortcuts Reference

Zod Schema Tutorial

Performance Optimization Guide

Dependencies

Estimated Timeline

References

Next Steps

Metadata

Metadata

Assignees

Labels

Type

Fields

Projects

Milestone

Relationships

Development

Issue actions