1# Quickstart: WebKit2GTK Native Browser Backend
2
3**Feature**: Native WebKit Browser Backend  
4**Date**: 2025-01-21  
5**Status**: Ready for implementation
6
7## Prerequisites
8
9### System Dependencies
10```bash
11# Install WebKit2GTK development libraries
12sudo pacman -S webkit2gtk-4.0 gtk3
13
14# Clone WebKit2GTK reference repository
15mkdir -p /home/brice/dev/clone
16cd /home/brice/dev/clone
17git clone https://github.com/WebKit/webkit.git webkit2gtk-reference
18
19# Verify CGO is available
20go env CGO_ENABLED  # Should output: 1
21```
22
23### Development Environment
24```bash
25# Ensure Go version compatibility
26go version  # Should be Go 1.21+
27
28# Install WebKit2GTK pkg-config
29pkg-config --cflags webkit2gtk-4.0  # Should output compiler flags
30pkg-config --libs webkit2gtk-4.0    # Should output linker flags
31```
32
33## Quick Validation
34
35### Step 1: Verify Current State
36```bash
37# Check current browser works with Wails
38./dumber-browser
39# Expected: Browser opens with homepage, keyboard shortcuts work
40
41# Note current performance baseline
42time ./dumber-browser &
43# Expected: Browser starts within 500ms
44```
45
46### Step 2: Basic WebKit Integration Test
47```bash
48# Create minimal WebKit test (after pkg/webkit implementation)
49cd tests/integration
50go test -v ./webkit_basic_test.go
51# Expected: WebView creates, loads google.fr, closes cleanly
52```
53
54### Step 3: Feature Parity Validation  
55```bash
56# Test keyboard shortcuts
57# Expected: Alt+Left/Right = navigation, Ctrl+Shift+C = copy URL
58
59# Test zoom functionality  
60# Expected: Ctrl++/Ctrl+-/Ctrl+0 zoom in/out/reset
61
62# Test script injection
63# Expected: Global keyboard shortcuts work on external sites
64```
65
66### Step 4: Performance Validation
67```bash
68# Startup time test
69time ./dumber-browser &
70# Target: <500ms (same as Wails baseline)
71
72# Memory usage test  
73ps aux | grep dumber-browser
74# Target: <100MB baseline + WebKit overhead
75
76# Navigation performance
77# Target: Page loads equivalent to current Wails performance
78```
79
80### Step 5: Data Preservation Test
81```bash
82# Backup current database
83cp ~/.config/dumber/browser.db ~/.config/dumber/browser.db.backup
84
85# Run WebKit version, browse some sites, adjust zoom
86# Close browser, restart
87
88# Verify data preserved
89sqlite3 ~/.config/dumber/browser.db "SELECT COUNT(*) FROM history;"
90# Expected: Same or increased count, no data loss
91
92# Verify zoom settings preserved  
93# Expected: Previously set zoom levels maintained
94```
95
96## Success Criteria Checklist
97
98### Basic Functionality ✓
99- [ ] Browser window opens and displays correctly
100- [ ] Can navigate to google.fr successfully  
101- [ ] Page renders with full HTML5/CSS3/JavaScript support
102- [ ] Browser window closes cleanly without errors
103
104### Keyboard Shortcuts ✓
105- [ ] Alt+Left arrow navigates back
106- [ ] Alt+Right arrow navigates forward  
107- [ ] Ctrl+Shift+C copies current URL to clipboard
108- [ ] Ctrl+Plus/Equals zooms in
109- [ ] Ctrl+Minus zooms out
110- [ ] Ctrl+0 resets zoom to 100%
111
112### Data Preservation ✓
113- [ ] Existing browser history maintained
114- [ ] Zoom settings per domain preserved
115- [ ] No database schema changes required
116- [ ] All SQLC queries work without modification
117
118### Performance Standards ✓  
119- [ ] Startup time <500ms (constitution requirement)
120- [ ] Memory usage <100MB baseline (constitution requirement)
121- [ ] Navigation speed equivalent to Wails baseline
122- [ ] Keyboard shortcut response time <100ms
123
124### Advanced Features ✓
125- [ ] JavaScript injection works on external sites
126- [ ] Developer tools accessible (F12)
127- [ ] Error handling graceful (no crashes)
128- [ ] Multiple page navigation works correctly
129
130## Troubleshooting Common Issues
131
132### WebKit Initialization Fails
133```bash
134# Check WebKit2GTK installation
135pkg-config --exists webkit2gtk-4.0 && echo "WebKit2GTK found" || echo "WebKit2GTK missing"
136
137# Check GTK installation
138pkg-config --exists gtk+-3.0 && echo "GTK3 found" || echo "GTK3 missing"
139```
140
141### CGO Compilation Errors
142```bash
143# Verify CGO configuration
144go env CGO_ENABLED CGO_CFLAGS CGO_LDFLAGS
145
146# Test basic CGO compilation
147echo 'package main; import "C"; func main() {}' | go run -x -
148```
149
150### Performance Regression
151```bash
152# Compare memory usage
153# Wails version: ps aux | grep dumber-browser (baseline)  
154# WebKit version: ps aux | grep dumber-browser (should be similar)
155
156# Compare startup time  
157time ./dumber-browser-wails &
158time ./dumber-browser-webkit &
159# WebKit should be equal or faster
160```
161
162### Keyboard Shortcuts Not Working
163```bash
164# Test GTK event handling in isolation
165# Check that GTK application receives key events
166# Verify WebKit UserContentManager script injection
167
168# Test on different sites
169# google.fr - should work
170# Local file - should work  
171# HTTPS site with CSP - may need handling
172```
173
174## Migration Strategy
175
176### Phase 1: Parallel Implementation
177- Keep existing Wails code intact
178- Develop pkg/webkit alongside current implementation
179- Use feature flags or separate binary for testing
180
181### Phase 2: Feature Parity
182- Achieve 100% functional equivalence with Wails version
183- Pass all existing tests with WebKit implementation
184- Validate performance meets constitutional requirements
185
186### Phase 3: Full Migration  
187- Switch default implementation to WebKit
188- Remove Wails dependencies from go.mod
189- Remove frontend TypeScript build system
190- Update documentation to remove Wails references
191
192### Phase 4: Cleanup
193- Remove deprecated Wails code
194- Optimize pkg/webkit for production use
195- Prepare pkg/webkit for potential repository extraction
196
197---
198
199**Quickstart Status**: ✅ Ready - All validation steps defined, implementation can begin