1# Research: WebKitGTK 6.0 Migration
2
3## API Migration Research
4
5### Decision: WebKitGTK 6.0 with GTK4
6**Rationale**: 
7- GTK4 provides native Vulkan renderer support
8- WebKitGTK 6.0 is the only actively maintained version for GTK4
9- Enables hardware-accelerated rendering via modern GPU APIs
10- Better Wayland support and performance
11
12**Alternatives considered**:
13- Staying on WebKit2GTK 4.0: No Vulkan support, limited to OpenGL
14- Using WebKit2GTK 4.1: Still GTK3, no Vulkan renderer
15- Custom Vulkan implementation: Too complex, maintenance burden
16
17### GTK3 to GTK4 Migration Patterns
18
19**Key Changes**:
201. **Event handling**: GdkEvent parameter removed from signals
212. **Widget construction**: Direct use of g_object_new() instead of specific constructors
223. **Drawing**: No more GtkDrawingArea draw signal, use GtkSnapshot
234. **CSS**: GTK4 uses standard CSS, removed custom properties
245. **Layout**: New layout managers replace containers
25
26**CGO Binding Updates**:
27- pkg-config: `webkit2gtk-4.0` → `webkitgtk-6.0`
28- pkg-config: `gtk+-3.0` → `gtk4`
29- Header: `gtk/gtk.h` remains same
30- Header: `webkit2/webkit2.h` → `webkit/webkit.h`
31
32### Vulkan Renderer Configuration
33
34**Decision: Hardware Acceleration Policy**
35**Rationale**: Provides user control over GPU vs CPU rendering
36
37**Configuration Options**:
381. `WEBKIT_HARDWARE_ACCELERATION_POLICY_ALWAYS`: Force GPU
392. `WEBKIT_HARDWARE_ACCELERATION_POLICY_NEVER`: Force CPU
403. `WEBKIT_HARDWARE_ACCELERATION_POLICY_ON_DEMAND`: Auto-detect (default)
41
42**New Settings in WebKitGTK 6.0**:
43- `webkit_settings_set_hardware_acceleration_policy()`
44- `webkit_settings_set_enable_2d_canvas_acceleration()`
45- `webkit_settings_set_enable_webgl()`
46- `webkit_settings_set_draw_compositing_indicators()` (debugging)
47
48### Deprecated APIs to Replace
49
50| WebKit2GTK 4.0 API | WebKitGTK 6.0 Replacement |
51|-------------------|---------------------------|
52| `webkit_web_view_new_with_context()` | `g_object_new()` with properties |
53| `webkit_web_context_set_sandbox_enabled()` | Always enabled, use `add_path_to_sandbox()` |
54| `WebKitWebContext` | `WebKitNetworkSession` for networking |
55| `webkit_web_view_run_javascript()` | Same, but async only |
56| Process swap property | Always enabled |
57
58### Build System Changes
59
60**pkg-config flags**:
61```bash
62# Old (WebKit2GTK 4.0)
63pkg-config --cflags --libs webkit2gtk-4.0 gtk+-3.0 javascriptcoregtk-4.0
64
65# New (WebKitGTK 6.0)
66pkg-config --cflags --libs webkitgtk-6.0 gtk4 javascriptcoregtk-6.0
67```
68
69### Performance Considerations
70
71**GPU Rendering Benefits**:
72- Vulkan backend via GTK4's unified GPU renderer
73- Hardware-accelerated 2D canvas
74- Improved WebGL performance
75- Reduced CPU usage for compositing
76- Better multi-threaded rendering
77
78**Fallback Strategy**:
79- Detect GPU capabilities at runtime
80- Use `ON_DEMAND` policy for automatic selection
81- Provide config flag for manual override
82- Monitor performance metrics
83
84### Global Rendering Configuration
85
86**Decision: Add RenderingMode to config**
87**Rationale**: User control over CPU/GPU rendering with smart defaults
88
89**Implementation**:
90```go
91type RenderingMode string
92
93const (
94    RenderingModeAuto RenderingMode = "auto"  // Default, detect at runtime
95    RenderingModeGPU  RenderingMode = "gpu"   // Force GPU acceleration
96    RenderingModeCPU  RenderingMode = "cpu"   // Force software rendering
97)
98```
99
100**Config Integration**:
101- Add to `internal/config/config.go`
102- Default to "auto" (GPU if available)
103- CLI flag: `--rendering-mode=[auto|gpu|cpu]`
104- Environment variable: `DUMBER_RENDERING_MODE`
105
106## Summary
107
108The migration to WebKitGTK 6.0 requires:
1091. Complete GTK3 → GTK4 widget/event migration
1102. Update all WebKit API calls to new versions
1113. Implement hardware acceleration configuration
1124. Add global rendering mode configuration
1135. Test Vulkan renderer activation and fallback
114
115All technical questions have been resolved through research.