1# dumb-browser Development Guidelines
2
3Auto-generated from all feature plans. Last updated: 2025-01-21
4
5## Active Technologies  
6- Go 1.25.1 + WebKitGTK 6.0 (GTK4), Cobra, Viper, SQLite3 (004-migrate-to-webkitgtk)
7- CGO bindings for WebKitGTK 6.0 C API integration
8- GPU rendering via Vulkan/OpenGL with configurable modes
9
10## Project Structure
11```
12pkg/
13└── webkit/       # WebKit2GTK Go bindings (extractable)
14
15src/
16├── models/       # Data models and entities
17├── services/     # Business logic services  
18├── cli/         # Command line interface
19└── lib/         # Shared libraries
20
21tests/
22├── contract/    # Contract tests for WebKit bindings
23├── integration/ # Integration tests with WebKit2GTK
24└── unit/        # Unit tests
25```
26
27## Commands
28```bash
29# Testing and linting
30make test
31make lint
32
33# Build application
34make build
35
36# Development
37make dev
38
39# Generate code (SQLC)
40make generate
41
42# Database operations
43sqlite3 ~/.config/dumber/browser.db
44```
45
46## Code Style
47Go 1.25.1: Follow standard Go conventions with gofmt
48- Use structured logging (slog)
49- Proper error handling (no panics)
50- SQLC for type-safe database queries  
51- CGO memory management with Go finalizers
52- Constitutional simplicity principles
53
54## Recent Changes
55- 004-migrate-to-webkitgtk: Migrating to WebKitGTK 6.0 (GTK4) for Vulkan GPU rendering support (UCM restored, GTK4 input, persistent cookies/cache)
56- 003-webkit2gtk-migration: Migrated from Wails to native WebKit2GTK with custom CGO bindings
57- 002-browser-controls-ui: Added keyboard/mouse controls, zoom persistence, clipboard integration
58
59## WebKitGTK 6.0 Integration
60- pkg/webkit: Reusable WebKitGTK 6.0 Go bindings (GTK4)
61- Hardware acceleration via Vulkan/OpenGL with configurable rendering modes
62- Direct GTK4 event handling with GtkEventController
63- WebKitNetworkSession replaces WebKitWebContext
64- Rendering modes: auto (default), gpu, cpu via --rendering-mode flag
65
66<!-- MANUAL ADDITIONS START -->
67### Migration Status (004-migrate-to-webkitgtk)
68- WebView construction via `g_object_new(WEBKIT_TYPE_WEB_VIEW, …)` (GTK4).
69- Native UCM messaging (script-message-received::dumber) replaces fallback bridge.
70- Persistent storage: cookies (SQLite) and cache via `WebKitNetworkSession`.
71- Runtime theme sync: listens to GTK `gtk-application-prefer-dark-theme` and updates page color-scheme live.
72- Native zoom shortcuts + GTK4 key/mouse controllers (including AZERTY fix for zoom-out).
73- Media: GStreamer required; default “safe” startup demotes VAAPI and uses a safe sink to avoid crashes (can be disabled).
74
75### GPU Rendering
76- GTK4 renderer can use Vulkan; WebKit settings map `auto|gpu|cpu` to the appropriate hardware acceleration policy where available.
77- Status endpoint: `dumb://homepage/api/rendering/status` reports current configured mode.
78
79### Next
80- Expose cookie policy/media mode toggles in config/CLI.
81- “Clear browsing data” surfaced via CookieManager/WebsiteDataManager.
82<!-- MANUAL ADDITIONS END -->