1# Data Model: WebKit2GTK Native Browser Backend
2
3**Feature**: Native WebKit Browser Backend  
4**Date**: 2025-01-21  
5**Status**: Complete
6
7## Core Entities
8
9### WebKit Browser Instance
10**Purpose**: Main browser engine wrapper managing WebKitWebView and GTK window
11**Key Attributes**:
12- WebView: WebKitWebView instance for rendering
13- Window: GTK ApplicationWindow container  
14- Settings: WebKitSettings for browser configuration
15- UserContentManager: WebKitUserContentManager for JavaScript injection
16- KeybindingController: GTK event handler for keyboard shortcuts
17
18**Relationships**:
19- Contains one WebKitWebView instance
20- Manages one GTK ApplicationWindow
21- References shared HistoryManager and ZoomManager
22- Interfaces with existing SQLite database through unchanged schema
23
24### WebKit Bindings Interface  
25**Purpose**: CGO wrapper providing Go interface to WebKit2GTK C APIs
26**Key Attributes**:
27- WebViewHandle: C pointer to WebKitWebView
28- WindowHandle: C pointer to GtkApplicationWindow
29- SettingsHandle: C pointer to WebKitSettings  
30- CallbackRegistry: Go callback functions for WebKit signals
31- ErrorContext: Error propagation from C to Go
32
33**State Transitions**:
341. Uninitialized → C library loaded → GTK initialized → WebKit configured → Ready
352. Ready → Loading URL → Content loaded → Interactive
363. Interactive → Navigation event → Loading URL (cycle)
374. Any state → Error → Error handling → Recovery attempt
38
39### Migration State Manager
40**Purpose**: Manages transition from Wails to WebKit implementation  
41**Key Attributes**:
42- MigrationMode: Flag indicating Wails/WebKit/Dual mode
43- DataPreservation: User data backup and restore mechanisms
44- FeatureParity: Validation checklist for Wails feature equivalence
45- PerformanceMetrics: Comparison data between implementations
46
47**Validation Rules**:
48- All existing user data must be preserved during migration
49- Browser functionality must maintain 100% feature parity
50- Performance must meet or exceed Wails baseline metrics
51- Keyboard shortcuts must function identically to current implementation
52
53## Data Flow Architecture
54
55### Browser Lifecycle
56```
571. Application Start
58   ├── Load pkg/webkit bindings
59   ├── Initialize GTK application
60   ├── Create WebKitWebView instance  
61   ├── Configure browser settings
62   ├── Setup keyboard event handlers
63   └── Load initial URL or homepage
64
652. URL Navigation  
66   ├── Validate URL through existing parser service
67   ├── Load URL in WebKitWebView
68   ├── Update history database (unchanged schema)
69   ├── Configure zoom level from database
70   └── Inject global keyboard scripts via UserContentManager
71
723. Keyboard Events
73   ├── GTK captures key events
74   ├── Route to appropriate handler (navigation/zoom/copy)
75   ├── Execute WebKit operation or JavaScript injection
76   └── Update database if needed (zoom persistence)
77```
78
79### C/Go Interface Boundaries
80```
81Go Layer (pkg/webkit):
82├── WebView struct with Go methods
83├── Event handling with Go channels  
84├── Error handling with Go error types
85└── Memory management with Go finalizers
86
87CGO Bridge:
88├── C function wrappers for WebKit APIs
89├── Callback function registration
90├── Memory allocation/deallocation
91└── Type conversion (C ↔ Go)
92
93C Layer (WebKit2GTK):
94├── WebKitWebView widget management
95├── GTK event loop integration
96├── WebKit signals and callbacks
97└── Native browser engine operations
98```
99
100## Database Integration
101
102### Preserved Schema
103**Status**: No changes to existing SQLite schema
104- History table: Maintain current structure and data
105- Zoom settings table: Continue using domain-based zoom storage  
106- All SQLC generated queries: Unchanged interface
107- Database migrations: No new migrations required
108
109### New Database Interactions
110**WebKit-specific data**: Store as configuration, not database entities
111- WebKit settings: Managed through WebKitSettings API
112- User content scripts: Stored as embedded resources, not database
113- Browser state: Memory-only, restored through WebKit APIs
114
115## Error Handling Model
116
117### Error Propagation Chain
118```
119WebKit C Error → CGO Error Conversion → Go Error → User Notification
120
121Error Categories:
122├── Initialization Errors: WebKit library loading, GTK setup
123├── Navigation Errors: Invalid URLs, network failures, load timeouts
124├── Script Injection Errors: UserContentManager failures, CSP violations  
125├── Keyboard Binding Errors: GTK event registration, handler failures
126└── Performance Errors: Memory limits, CPU constraints, timeout violations
127```
128
129### Recovery Strategies
130- Initialization failures: Fallback error dialog, graceful exit
131- Navigation errors: Error page display, retry mechanisms
132- Script failures: Silent failure with logging, functionality degradation
133- Memory errors: Garbage collection, resource cleanup, restart recommendation
134
135## Performance Data Model
136
137### Metrics Collection
138**Startup Performance**:
139- Library loading time: WebKit2GTK and GTK initialization
140- WebView creation time: Widget setup and configuration
141- First paint time: Initial browser window display
142
143**Runtime Performance**:  
144- Memory usage: WebKit process + GTK overhead + Go runtime
145- Navigation speed: URL load time, DOM ready time
146- Event handling latency: Keyboard shortcut response time
147
148**Comparison Baseline**:
149- Current Wails metrics as performance targets
150- Performance regression detection through automated testing
151- Resource usage monitoring for constitutional compliance (<100MB baseline)
152
153---
154
155**Data Model Status**: ✅ Complete - All entities defined, ready for contract generation