1# Implementation Plan: Migrate to WebKitGTK 6.0
2
3**Branch**: `004-migrate-to-webkitgtk` | **Date**: 2025-01-21 | **Spec**: [spec.md](./spec.md)
4**Input**: Feature specification from `/specs/004-migrate-to-webkitgtk/spec.md`
5
6## Execution Flow (/plan command scope)
7```
81. Load feature spec from Input path
9   → Successfully loaded spec for WebKitGTK 6.0 migration
102. Fill Technical Context (scan for NEEDS CLARIFICATION)
11   → Project Type: Single (Go browser application)
12   → Structure Decision: Option 1 (single project)
13   → Open clarifications remain in spec (FR-008, FR-011, FR-012)
143. Evaluate Constitution Check section below
15   → Adjust for remaining clarifications; document deviations
16   → Update Progress Tracking: Initial Constitution Check
174. Execute Phase 0 → research.md (complete)
18   → Research WebKit API differences and migration path
195. Execute Phase 1 → contracts, data-model.md, quickstart.md (complete)
206. Re-evaluate Constitution Check section
21   → Design aligned with constitution principles; clarifications still pending
22   → Update Progress Tracking: Post-Design Constitution Check
237. Plan Phase 2 → Describe task generation approach (DO NOT create tasks.md) (complete)
248. Generate tasks via /tasks (exists: tasks.md)
259. Track Phase 4 implementation progress (in progress)
26```
27
28## Summary
29Migrate the dumber browser from WebKit2GTK 4.0 (GTK3) to WebKitGTK 6.0 (GTK4) to enable GPU rendering through Vulkan layer. The migration will involve incrementally updating the pkg/webkit package files while maintaining browser functionality. A global rendering configuration will be added to allow users to choose between CPU and GPU rendering, with GPU enabled by default when supported.
30
31## Technical Context
32**Language/Version**: Go 1.25.1  
33**Primary Dependencies**: WebKitGTK 6.0, GTK4, libsoup3, SQLite3  
34**Storage**: SQLite3 for history/settings, WebKitWebsiteDataManager for browser data  
35**Testing**: Go tests, contract tests for WebKit bindings  
36**Target Platform**: Linux (Wayland-first, X11 compatible)  
37**Project Type**: single - Go browser application  
38**Performance Goals**: < 500ms startup, improved GPU rendering performance  
39**Constraints**: Maintain all existing functionality, graceful fallback for non-Vulkan systems  
40**Scale/Scope**: ~15 files in pkg/webkit to migrate, ~3000 LOC
41
42**User-Provided Context**: No TDD for this, we will start by checking the WebKit API differences and migrate pkg/webkit files one by one
43
44## Current Snapshot (repo state)
45- Build flags already target GTK4/WebKitGTK 6.0 in `pkg/webkit/*_cgo.go` ✓
46- Core files present: `webview_cgo.go`, `window_cgo.go`, `script_cgo.go`, `scheme_cgo.go`, `zoom_cgo.go`, `keyboard_cgo.go`, `devtools_cgo.go`, `loop_cgo.go`, plus Go wrappers (`*.go`) ✓
47- Migration underway in `webview_cgo.go` (GTK4 APIs, evaluate_javascript) ✓
48- Spec still has [NEEDS CLARIFICATION] for performance targets and timeline ✗
49
50## Constitution Check
51*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
52
53**Simplicity**:
54- Projects: 1 (single Go browser project) ✓
55- Using framework directly? YES (direct CGO bindings to WebKitGTK) ✓
56- Single data model? YES (existing models unchanged) ✓
57- Avoiding patterns? YES (no unnecessary abstractions) ✓
58
59**Architecture**:
60- EVERY feature as library? pkg/webkit is already a library ✓
61- Libraries listed: pkg/webkit (WebKit2GTK Go bindings)
62- CLI per library: Browser CLI with browse, history, dmenu commands ✓
63- Library docs: Will update with new API documentation
64
65**Testing (Modified per user request)**:
66- User specified: "No TDD for this" - migration-focused approach
67- Will add tests after migration for regression prevention
68- Contract tests for new WebKit bindings
69- Integration tests for browser functionality
70
71**Observability**:
72- Structured logging included? YES (slog) ✓
73- Frontend logs → backend? N/A (native application)
74- Error context sufficient? YES ✓
75
76**Versioning**:
77- Version number assigned? Will increment after migration
78- BUILD increments on every change? YES ✓
79- Breaking changes handled? API compatibility layer during migration
80
81## Project Structure
82
83### Documentation (this feature)
84```
85specs/004-migrate-to-webkitgtk/
86├── plan.md              # This file (/plan command output)
87├── research.md          # Phase 0 output (/plan command)
88├── data-model.md        # Phase 1 output (/plan command)
89├── quickstart.md        # Phase 1 output (/plan command)
90├── contracts/           # Phase 1 output (/plan command)
91└── tasks.md             # Phase 2 output (/tasks command - NOT created by /plan)
92```
93
94### Source Code (repository root)
95```
96# Option 1: Single project (SELECTED)
97pkg/
98└── webkit/              # WebKitGTK Go bindings (migration target)
99    ├── webview_cgo.go   # WebView implementation (GTK4/WebKit 6)
100    ├── window_cgo.go    # Window management (GTK4)
101    ├── script_cgo.go    # JavaScript evaluation/injection
102    ├── scheme_cgo.go    # Custom URI scheme handler
103    ├── zoom_cgo.go      # Zoom control
104    ├── keyboard_cgo.go  # Keyboard handling (controllers)
105    ├── devtools_cgo.go  # Inspector
106    ├── loop_cgo.go      # Main loop helpers
107    ├── settings.go      # High-level settings glue
108    └── *.go             # Non-CGO wrappers (window.go, zoom.go, script.go, ...)
109
110internal/
111├── cli/                 # CLI entry points (browse, history, dmenu)
112├── config/              # App config (extend for rendering)
113└── db/                  # SQLite persistence
114
115tests/
116├── contract/            # Contract tests for WebKit bindings
117├── integration/         # End-to-end validation
118└── unit/                # Unit tests
119```
120
121**Structure Decision**: Option 1 (Single project) - maintaining existing structure
122
123## Phase 0: Outline & Research
1241. **Extract unknowns from Technical Context**:
125   - WebKitGTK 6.0 API changes from 4.0
126   - GTK4 migration requirements
127   - Vulkan renderer configuration
128   - CGO binding updates needed
129   - Build system changes (pkg-config)
130
1312. **Generate and dispatch research agents**:
132   ```
133   Task: "Research WebKitGTK 6.0 API breaking changes"
134   Task: "Find GTK3 to GTK4 migration patterns for CGO"
135   Task: "Research Vulkan enablement in WebKitGTK 6.0"
136   Task: "Identify deprecated WebKit2GTK 4.0 APIs"
137   ```
138
1393. **Consolidate findings** in `research.md`
140
141**Output**: research.md with migration path defined
142
143## Phase 1: Design & Contracts
144*Prerequisites: research.md complete*
145
1461. **API Mapping** → `data-model.md`:
147   - Map WebKit2GTK 4.0 APIs to WebKitGTK 6.0 equivalents
148   - Document removed/replaced functions
149   - Identify new required APIs
150
1512. **Generate migration contracts**:
152   - Define compatibility layer interfaces
153   - Create migration checkpoints
154   - Output to `/contracts/`
155
1563. **Migration test scenarios**:
157   - Test each webkit file migration
158   - Verify GPU acceleration
159   - Fallback testing
160
1614. **Create quickstart guide**:
162   - Build requirements for GTK4/WebKitGTK 6.0
163   - Verification steps
164   - Performance testing
165
1665. **Update CLAUDE.md**:
167   - Add WebKitGTK 6.0 context
168   - GTK4 migration notes
169   - Recent changes
170
171**Output**: data-model.md, /contracts/*, quickstart.md, CLAUDE.md updates
172
173## File‑By‑File Migration Plan (grounded in repo)
174- `pkg/webkit/build_flags_cgo.go` / `build_cgo_stub.go` / `build_flags_stub.go`: ensure pkg-config switched to `webkitgtk-6.0 gtk4 javascriptcoregtk-6.0` (present; verify includes and tags)
175- `pkg/webkit/webview_cgo.go`: use `g_object_new` patterns as needed; ensure `webkit_web_view_evaluate_javascript` (async) usage; connect notify signals via GTK4; migrate any deprecated UCM message handlers.
176- `pkg/webkit/window_cgo.go`: use `gtk_window_new()`, `gtk_window_set_child()`, and `gtk_window_destroy()`; remove `gtk_container_add()` remnants.
177- `pkg/webkit/keyboard_cgo.go`: replace GdkEvent handlers with `GtkEventControllerKey` (key-pressed) and gestures for mouse input.
178- `pkg/webkit/zoom_cgo.go` / `zoom.go`: confirm zoom ranges and GTK4 APIs for zoom if used; keep high-level validation in Go.
179- `pkg/webkit/script_cgo.go` / `script.go`: standardize JS evaluation via `webkit_web_view_evaluate_javascript`.
180- `pkg/webkit/scheme_cgo.go`: verify `WebKitURISchemeRequest` handling and memory ownership semantics on GTK4/WebKit 6.
181- `pkg/webkit/devtools_cgo.go`: validate inspector APIs on WebKit 6.
182- `pkg/webkit/loop_cgo.go`: update any deprecated main-loop helpers.
183- `internal/config/*`: add `RenderingConfig` and `RenderingMode` with env/flag wiring.
184- `internal/cli/browse.go`: add `--rendering-mode`, `--disable-gpu`, `--debug-gpu`.
185- `services/*`: plumb rendering config into WebView creation.
186
187## Phase 2: Task Planning Approach
188*This section describes what the /tasks command will do - DO NOT execute during /plan*
189
190**Task Generation Strategy**:
191- Analyze each file in pkg/webkit for required changes
192- Create migration task for each file
193- Order by dependency (build files first, then core, then features)
194- Add verification tasks after each major component
195
196**Ordering Strategy**:
1971. Build configuration (pkg-config, CGO flags)
1982. Core types and structures
1993. Window and WebView creation
2004. Feature-specific files (zoom, script, keyboard)
2015. Integration testing
2026. Performance verification
203
204**Estimated Output**: 20-25 migration tasks in tasks.md
205
206**IMPORTANT**: This phase is executed by the /tasks command, NOT by /plan
207
208## Phase 3+: Future Implementation
209*These phases are beyond the scope of the /plan command*
210
211**Phase 3**: Task execution (/tasks command creates tasks.md)  
212**Phase 4**: Implementation (execute migration tasks)  
213**Phase 5**: Validation (verify GPU acceleration, run performance tests)
214
215## Risks & Mitigations
216- Driver variability: prefer ON_DEMAND policy by default; expose override flags; add CPU fallback on init failures.
217- API drift: adhere to contracts in `contracts/webkit-api.yaml`; gate changes behind compile tags where helpful.
218- Performance regressions: provide quickstart validation and capture metrics; keep rollback point per task.
219
220## Complexity Tracking
221*Fill ONLY if Constitution Check has violations that must be justified*
222
223| Violation | Why Needed | Simpler Alternative Rejected Because |
224|-----------|------------|-------------------------------------|
225| No TDD for migration | User-specified approach | TDD would slow down API exploration during migration |
226
227## Progress Tracking
228*This checklist is updated during execution flow*
229
230**Phase Status**:
231- [x] Phase 0: Research complete (/plan command)
232- [x] Phase 1: Design complete (/plan command)
233- [x] Phase 2: Task planning complete (/plan command - describe approach only)
234- [x] Phase 3: Tasks generated (/tasks command)
235- [ ] Phase 4: Implementation in progress
236- [ ] Phase 5: Validation passed
237
238**Gate Status**:
239- [x] Initial Constitution Check: PASS
240- [x] Post-Design Constitution Check: PASS (performance targets pending)
241- [ ] All NEEDS CLARIFICATION resolved (see spec FR-008, FR-011, FR-012)
242- [x] Complexity deviations documented
243
244## Next Actions
245- Verify and finalize build flags and includes across `pkg/webkit/*_cgo.go`.
246- Align `internal/config` and `internal/cli` with `RenderingConfig` and flags.
247- Complete event/gesture migration in `keyboard_cgo.go` and related handlers.
248- Add hardware acceleration policy mapping during WebView initialization.
249
250---
251*Based on Constitution v1.0.0 - See `/memory/constitution.md`*