1# Implementation Plan: Native WebKit Browser Backend
2
3**Branch**: `003-webkit2gtk-migration` | **Date**: 2025-01-21 | **Spec**: [spec.md](spec.md)
4**Input**: Feature specification from `/home/brice/dev/projects/dumb-browser/specs/003-webkit2gtk-migration/spec.md`
5
6## Execution Flow (/plan command scope)
7```
81. Load feature spec from Input path
9   → If not found: ERROR "No feature spec at {path}"
102. Fill Technical Context (scan for NEEDS CLARIFICATION)
11   → Detect Project Type from context (web=frontend+backend, mobile=app+api)
12   → Set Structure Decision based on project type
133. Evaluate Constitution Check section below
14   → If violations exist: Document in Complexity Tracking
15   → If no justification possible: ERROR "Simplify approach first"
16   → Update Progress Tracking: Initial Constitution Check
174. Execute Phase 0 → research.md
18   → If NEEDS CLARIFICATION remain: ERROR "Resolve unknowns"
195. Execute Phase 1 → contracts, data-model.md, quickstart.md, agent-specific template file (e.g., `CLAUDE.md` for Claude Code, `.github/copilot-instructions.md` for GitHub Copilot, or `GEMINI.md` for Gemini CLI).
206. Re-evaluate Constitution Check section
21   → If new violations: Refactor design, return to Phase 1
22   → Update Progress Tracking: Post-Design Constitution Check
237. Plan Phase 2 → Describe task generation approach (DO NOT create tasks.md)
248. STOP - Ready for /tasks command
25```
26
27**IMPORTANT**: The /plan command STOPS at step 7. Phases 2-4 are executed by other commands:
28- Phase 2: /tasks command creates tasks.md
29- Phase 3-4: Implementation execution (manual or via tools)
30
31## Summary
32Replace Wails framework with direct WebKit2GTK bindings to gain full control over browser engine capabilities, maintain all existing functionality while removing framework limitations, and create custom C Go bindings in a pkg/ package for potential future extraction.
33
34## Technical Context
35**Language/Version**: Go 1.25.1 + C bindings for WebKit2GTK  
36**Primary Dependencies**: WebKit2GTK, GTK3, CGO for C bindings  
37**Storage**: SQLite (maintain existing database schema and data)  
38**Testing**: Go testing + WebKit integration tests  
39**Target Platform**: Linux (Wayland/X11) - focus on GTK-based systems
40**Project Type**: single - native desktop application  
41**Performance Goals**: <500ms startup time, <100MB baseline memory, maintain existing performance  
42**Constraints**: Remove all Wails dependencies, preserve user data, maintain keyboard shortcuts and browser features  
43**Scale/Scope**: Single browser window, existing CLI functionality, WebKit2GTK reference clone for development
44
45## Constitution Check
46*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
47
48**Simplicity**:
49- Projects: 1 (single native browser application)
50- Using framework directly? ✅ (Direct WebKit2GTK, removing Wails wrapper)
51- Single data model? ✅ (Maintain existing SQLite schema)
52- Avoiding patterns? ✅ (Direct C bindings, no unnecessary abstraction layers)
53
54**Architecture**:
55- EVERY feature as library? ✅ (pkg/ package for WebKit bindings, reusable)
56- Libraries listed: pkg/webkit (WebKit2GTK Go bindings), existing internal packages
57- CLI per library: Maintain existing CLI, add webkit package testing commands
58- Library docs: llms.txt format planned for pkg/webkit
59
60**Testing (NON-NEGOTIABLE)**:
61- RED-GREEN-Refactor cycle enforced? ✅ (Contract tests for WebKit bindings first)
62- Git commits show tests before implementation? ✅ (Will create failing WebKit tests)
63- Order: Contract→Integration→E2E→Unit strictly followed? ✅ 
64- Real dependencies used? ✅ (Real WebKit2GTK, actual browser engine)
65- Integration tests for: WebKit bindings, browser functionality, keyboard shortcuts
66- FORBIDDEN: Implementation before test, skipping RED phase
67
68**Observability**:
69- Structured logging included? ✅ (Continue using slog)
70- Frontend logs → backend? ✅ (WebKit console logs to Go backend)
71- Error context sufficient? ✅ (WebKit error propagation to Go)
72
73**Versioning**:
74- Version number assigned? Next version after current (maintain semver)
75- BUILD increments on every change? ✅ 
76- Breaking changes handled? ✅ (Migration from Wails to native, preserve user data)
77
78## Project Structure
79
80### Documentation (this feature)
81```
82specs/[###-feature]/
83├── plan.md              # This file (/plan command output)
84├── research.md          # Phase 0 output (/plan command)
85├── data-model.md        # Phase 1 output (/plan command)
86├── quickstart.md        # Phase 1 output (/plan command)
87├── contracts/           # Phase 1 output (/plan command)
88└── tasks.md             # Phase 2 output (/tasks command - NOT created by /plan)
89```
90
91### Source Code (repository root)
92```
93# Option 1: Single project (DEFAULT)
94src/
95├── models/
96├── services/
97├── cli/
98└── lib/
99
100tests/
101├── contract/
102├── integration/
103└── unit/
104
105# Option 2: Web application (when "frontend" + "backend" detected)
106backend/
107├── src/
108│   ├── models/
109│   ├── services/
110│   └── api/
111└── tests/
112
113frontend/
114├── src/
115│   ├── components/
116│   ├── pages/
117│   └── services/
118└── tests/
119
120# Option 3: Mobile + API (when "iOS/Android" detected)
121api/
122└── [same as backend above]
123
124ios/ or android/
125└── [platform-specific structure]
126```
127
128**Structure Decision**: Option 1 (Single project) - Native desktop application with pkg/ for WebKit bindings
129
130## Phase 0: Outline & Research
1311. **Extract unknowns from Technical Context** above:
132   - For each NEEDS CLARIFICATION → research task
133   - For each dependency → best practices task
134   - For each integration → patterns task
135
1362. **Generate and dispatch research agents**:
137   ```
138   For each unknown in Technical Context:
139     Task: "Research {unknown} for {feature context}"
140   For each technology choice:
141     Task: "Find best practices for {tech} in {domain}"
142   ```
143
1443. **Consolidate findings** in `research.md` using format:
145   - Decision: [what was chosen]
146   - Rationale: [why chosen]
147   - Alternatives considered: [what else evaluated]
148
149**Output**: research.md with all NEEDS CLARIFICATION resolved
150
151## Phase 1: Design & Contracts
152*Prerequisites: research.md complete*
153
1541. **Extract entities from feature spec** → `data-model.md`:
155   - Entity name, fields, relationships
156   - Validation rules from requirements
157   - State transitions if applicable
158
1592. **Generate API contracts** from functional requirements:
160   - For each user action → endpoint
161   - Use standard REST/GraphQL patterns
162   - Output OpenAPI/GraphQL schema to `/contracts/`
163
1643. **Generate contract tests** from contracts:
165   - One test file per endpoint
166   - Assert request/response schemas
167   - Tests must fail (no implementation yet)
168
1694. **Extract test scenarios** from user stories:
170   - Each story → integration test scenario
171   - Quickstart test = story validation steps
172
1735. **Update agent file incrementally** (O(1) operation):
174   - Run `/scripts/update-agent-context.sh [claude|gemini|copilot]` for your AI assistant
175   - If exists: Add only NEW tech from current plan
176   - Preserve manual additions between markers
177   - Update recent changes (keep last 3)
178   - Keep under 150 lines for token efficiency
179   - Output to repository root
180
181**Output**: data-model.md, /contracts/*, failing tests, quickstart.md, agent-specific file
182
183## Phase 2: Task Planning Approach
184*This section describes what the /tasks command will do - DO NOT execute during /plan*
185
186**Task Generation Strategy**:
187- Load `/templates/tasks-template.md` as base
188- Generate tasks from WebKit bindings contract (webkit-bindings-api.yaml)
189- Create pkg/webkit package structure and CGO bridge tasks [P]
190- WebKit2GTK reference repository setup and analysis tasks
191- Contract tests for each WebKit API function [P]
192- Integration tests for browser features (navigation, zoom, shortcuts)
193- Migration tasks to remove Wails dependencies sequentially
194- Performance validation and data preservation verification tasks
195
196**Ordering Strategy**:
197- TDD order: Contract tests before WebKit bindings implementation
198- Dependency order: CGO bridge → WebKit API → Browser integration → Wails removal
199- Parallel tasks: Independent WebKit functions, separate test files [P]
200- Sequential migration: Preserve existing functionality throughout transition
201
202**Estimated Output**: 30-35 numbered, ordered tasks focusing on WebKit migration in tasks.md
203
204**IMPORTANT**: This phase is executed by the /tasks command, NOT by /plan
205
206## Phase 3+: Future Implementation
207*These phases are beyond the scope of the /plan command*
208
209**Phase 3**: Task execution (/tasks command creates tasks.md)  
210**Phase 4**: Implementation (execute tasks.md following constitutional principles)  
211**Phase 5**: Validation (run tests, execute quickstart.md, performance validation)
212
213## Complexity Tracking
214*Fill ONLY if Constitution Check has violations that must be justified*
215
216| Violation | Why Needed | Simpler Alternative Rejected Because |
217|-----------|------------|-------------------------------------|
218| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
219| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |
220
221
222## Progress Tracking
223*This checklist is updated during execution flow*
224
225**Phase Status**:
226- [x] Phase 0: Research complete (/plan command)
227- [x] Phase 1: Design complete (/plan command)
228- [x] Phase 2: Task planning complete (/plan command - describe approach only)
229- [ ] Phase 3: Tasks generated (/tasks command)
230- [ ] Phase 4: Implementation complete
231- [ ] Phase 5: Validation passed
232
233**Gate Status**:
234- [x] Initial Constitution Check: PASS
235- [x] Post-Design Constitution Check: PASS  
236- [x] All NEEDS CLARIFICATION resolved
237- [x] Complexity deviations documented (none required)
238
239---
240*Based on Constitution v2.1.1 - See `/memory/constitution.md`*