1# Data Model: WebKitGTK 6.0 Migration
2
3## Configuration Model
4
5### RenderingConfig
6```go
7type RenderingMode string
8
9const (
10    RenderingModeAuto RenderingMode = "auto"  // Detect GPU availability
11    RenderingModeGPU  RenderingMode = "gpu"   // Force GPU acceleration
12    RenderingModeCPU  RenderingMode = "cpu"   // Force software rendering
13)
14
15type RenderingConfig struct {
16    Mode                    RenderingMode // Default: auto
17    Enable2DCanvas          bool         // Default: true
18    EnableWebGL             bool         // Default: true
19    DrawCompositingIndicators bool       // Default: false (debug only)
20}
21```
22
23### Updated WebKit Config
24```go
25type Config struct {
26    // Existing fields
27    InitialURL            string
28    UserAgent            string
29    EnableDeveloperExtras bool
30    ZoomDefault          float64
31    DataDir              string
32    CacheDir             string
33    DefaultSansFont      string
34    DefaultSerifFont     string
35    DefaultMonospaceFont string
36    DefaultFontSize      int
37    
38    // New GPU rendering fields
39    Rendering RenderingConfig
40}
41```
42
43## API Mapping Model
44
45### Core WebView APIs
46| Component | WebKit2GTK 4.0 | WebKitGTK 6.0 | Status |
47|-----------|---------------|---------------|---------|
48| WebView Creation | `webkit_web_view_new_with_context()` | `g_object_new(WEBKIT_TYPE_WEB_VIEW, ...)` | Breaking |
49| Context | `WebKitWebContext` | `WebKitNetworkSession` | Breaking |
50| Settings | `WebKitSettings` | `WebKitSettings` (expanded) | Compatible |
51| UserContentManager | Same | Same | Compatible |
52| JavaScript | `webkit_web_view_run_javascript()` | Same (async only) | Compatible |
53
54### GTK Widget APIs
55| Component | GTK3 | GTK4 | Status |
56|-----------|------|------|---------|
57| Window | `gtk_window_new(GTK_WINDOW_TOPLEVEL)` | `gtk_window_new()` | Breaking |
58| Container | `gtk_container_add()` | `gtk_window_set_child()` | Breaking |
59| Events | `GdkEventKey*` | `GtkEventController` | Breaking |
60| Show/Hide | `gtk_widget_show()` | Same | Compatible |
61| Destroy | `gtk_widget_destroy()` | `gtk_window_destroy()` | Breaking |
62
63### Hardware Acceleration APIs
64```go
65// New acceleration policy enum
66type HardwareAccelerationPolicy int
67
68const (
69    PolicyOnDemand HardwareAccelerationPolicy = iota  // Auto-detect
70    PolicyAlways                                      // Force GPU
71    PolicyNever                                       // Force CPU
72)
73
74// Mapping to WebKit constants
75var policyMap = map[RenderingMode]HardwareAccelerationPolicy{
76    RenderingModeAuto: PolicyOnDemand,
77    RenderingModeGPU:  PolicyAlways,
78    RenderingModeCPU:  PolicyNever,
79}
80```
81
82## Migration States
83
84### File Migration Status
85```go
86type MigrationStatus string
87
88const (
89    StatusPending   MigrationStatus = "pending"
90    StatusInProgress MigrationStatus = "in_progress"
91    StatusComplete  MigrationStatus = "complete"
92    StatusTested    MigrationStatus = "tested"
93)
94
95type FileMigration struct {
96    Path     string
97    Status   MigrationStatus
98    Changes  []string  // List of API changes made
99    Tests    []string  // Associated test files
100}
101```
102
103## Error Handling Model
104
105### GPU Fallback Errors
106```go
107type GPUError struct {
108    Type    string  // "initialization", "driver", "memory"
109    Message string
110    Fallback bool   // Whether CPU fallback was successful
111}
112
113type RenderingStatus struct {
114    Mode      RenderingMode
115    GPUActive bool
116    Errors    []GPUError
117    Performance struct {
118        FPS        float64
119        CPUUsage   float64
120        GPUUsage   float64
121        MemoryMB   int
122    }
123}
124```
125
126## Build Configuration
127
128### Package Config Changes
129```makefile
130# Old build flags
131WEBKIT_PKG = webkit2gtk-4.0
132GTK_PKG = gtk+-3.0
133JS_PKG = javascriptcoregtk-4.0
134
135# New build flags
136WEBKIT_PKG = webkitgtk-6.0
137GTK_PKG = gtk4
138JS_PKG = javascriptcoregtk-6.0
139```
140
141## Validation Rules
142
143### Rendering Mode Validation
144- If GPU forced but unavailable → Error with suggestion to use auto
145- If CPU forced → Warn about performance impact
146- If auto → Log detected mode at startup
147
148### Performance Thresholds
149- Startup time must remain < 500ms
150- GPU memory usage < 500MB
151- CPU usage reduction > 20% when GPU active
152- FPS improvement > 30% for animations
153
154## State Transitions
155
156### Rendering Mode State Machine
157```
158┌─────┐ Check GPU ┌──────┐ Success ┌─────┐
159│Auto │────────────→│Detect│────────→│GPU  │
160└─────┘            └──────┘         └─────┘
161                       │ Fail           │ Error
162                       ↓                ↓
163                   ┌─────┐         ┌─────┐
164                   │CPU  │←─────────│Retry│
165                   └─────┘ Fallback └─────┘
166```
167
168## Data Persistence
169
170No changes to existing SQLite schema required. Rendering mode stored in config file only.