1# Research: WebKit2GTK Native Bindings Migration
2
3**Feature**: Native WebKit Browser Backend  
4**Date**: 2025-01-21  
5**Status**: Complete
6
7## WebKit2GTK Integration Patterns
8
9### Decision: CGO-based WebKit2GTK bindings
10**Rationale**: 
11- Direct access to WebKit2GTK C APIs provides full control over browser engine
12- CGO allows seamless integration of C libraries with Go code
13- Performance critical for <500ms startup requirement
14- Maintains compatibility with existing GTK-based Linux desktop environments
15
16**Alternatives considered**:
17- Keeping Wails: Rejected due to framework limitations and lack of direct engine control
18- gotk3/webkit2: Existing Go bindings but lack modern WebKit2GTK features needed
19- Embedding Chromium: Too heavyweight, violates constitution's speed-first principle
20
21## C Go Bindings Architecture
22
23### Decision: pkg/webkit package structure
24**Rationale**:
25- Isolates WebKit-specific code for future extraction as separate repository
26- Follows Go package conventions with clear API boundaries  
27- Enables independent testing and versioning of WebKit bindings
28- Supports constitution requirement for library-based architecture
29
30**Alternatives considered**:
31- Internal package only: Rejected, doesn't support future repo extraction goal
32- Multiple WebKit packages: Over-engineering, violates simplicity principle
33- Direct main package integration: Tight coupling, harder to test and maintain
34
35## WebKit2GTK Reference Implementation
36
37### Decision: Clone WebKit2GTK repository to /home/brice/dev/clone
38**Rationale**:
39- Provides official API documentation and examples for C bindings
40- Reference implementations for browser features (navigation, zoom, JS execution)
41- Understanding WebKit widget lifecycle and event handling patterns
42- Source of truth for WebKit signal/callback patterns needed for keyboard shortcuts
43
44**Research findings**:
45- WebKit2GTK provides WebKitWebView widget for rendering
46- WebKitSettings for browser configuration and feature toggles
47- WebKitUserContentManager for JavaScript injection (replaces current Wails script injection)
48- GTK key binding system for keyboard shortcuts (Alt+arrows, Ctrl+shortcuts)
49
50## Migration Strategy
51
52### Decision: Gradual replacement maintaining data compatibility
53**Rationale**:
54- Constitution requires preserving user data (history, bookmarks, zoom settings)
55- Existing SQLite schema and SQLC generated code can be maintained
56- Allows A/B testing of WebKit vs Wails implementations
57- Minimizes user disruption during migration
58
59**Migration approach**:
601. Create pkg/webkit with basic WebView rendering
612. Implement keyboard shortcuts through GTK event handling
623. Replace Wails window with GTK ApplicationWindow + WebKitWebView
634. Migrate script injection from Wails ExecJS to WebKit UserContentManager
645. Remove Wails dependencies and frontend build system
65
66## Performance Considerations
67
68### Decision: Direct WebKit widget integration
69**Rationale**:
70- WebKit2GTK designed for embedding in native applications
71- Eliminates JavaScript bridge overhead present in Wails
72- Direct GTK event loop integration for better responsiveness
73- Memory management handled by GObject reference counting
74
75**Performance expectations**:
76- Startup time improvement due to removing Wails initialization overhead
77- Memory reduction by eliminating embedded web frontend  
78- Better keyboard shortcut responsiveness through direct GTK events
79- Improved page loading performance with direct WebKit configuration
80
81## Documentation Sources
82
83### Decision: Multi-source documentation approach
84**Rationale**:
85- WebKit2GTK official docs: API reference and C examples
86- GNOME Web (Epiphany) source: Real-world WebKit2GTK usage patterns  
87- CGO best practices: Memory management and C/Go interface design
88- GTK documentation: Window management and keyboard event handling
89
90**Key resources identified**:
91- WebKit2GTK API Reference: https://webkitgtk.org/reference/webkit2gtk/stable/
92- Epiphany browser source: Example of WebKit2GTK browser implementation
93- CGO documentation: Memory safety and performance best practices
94- GTK4 migration guides: Future-proofing for eventual GTK4 support
95
96## Risk Mitigation
97
98### Decision: Incremental implementation with fallback plan
99**Rationale**:
100- Large architectural change requires careful validation
101- User data preservation is non-negotiable requirement
102- Performance regressions would violate constitution speed-first principle
103
104**Mitigation strategies**:
105- Maintain parallel Wails implementation during development
106- Comprehensive integration testing before removing Wails
107- Database migration scripts with rollback capability
108- Performance benchmarking against current Wails implementation
109- Feature parity validation through existing test suite
110
111---
112
113**Research Status**: ✅ Complete - All technical unknowns resolved, ready for Phase 1 design