1# Research: Browser Controls UI
2
3## Research Tasks
4
5### 1. Wails v3 Keyboard Event Handling
6**Task**: Research keyboard event handling in Wails v3-alpha for desktop applications
7
8**Decision**: Use Wails context menu and event system with JavaScript frontend integration
9**Rationale**: 
10- Wails v3 provides native keyboard event handling through WebView2/WebKit integration
11- Frontend JavaScript can capture keyboard events and call backend Go methods via context
12- Maintains separation between UI (JavaScript) and business logic (Go services)
13- No additional dependencies required beyond existing Wails framework
14
15**Alternatives considered**:
16- Direct GTK keyboard hooks: Rejected due to complexity and Wails abstraction
17- OS-level global hotkeys: Rejected as not needed (app-specific shortcuts only)
18- Third-party hotkey libraries: Rejected to maintain constitution's simplicity principle
19
20### 2. Mouse Button Event Handling (Back/Forward)
21**Task**: Research mouse button 4/5 (back/forward) event handling in WebView context
22
23**Decision**: Use JavaScript mouse event listeners with event.button detection
24**Rationale**:
25- Standard web platform approach using addEventListener('mousedown')
26- event.button === 3 (back) and event.button === 4 (forward) detection
27- Works consistently across WebKit2GTK implementations
28- No platform-specific code required
29
30**Alternatives considered**:
31- GTK mouse event capture: Rejected due to Wails abstraction layer
32- X11/Wayland direct event handling: Rejected as breaks single-binary principle
33
34### 3. Zoom Level Management and Persistence
35**Task**: Research zoom level implementation patterns and domain-based persistence
36
37**Decision**: Use WebView zoom API with SQLite domain-based storage
38**Rationale**:
39- WebView provides native zoom functionality (setZoomFactor)
40- Firefox zoom levels provide proven UX pattern (30%-500% range)
41- SQLite table for domain → zoom_level mapping enables per-site persistence
42- Existing database infrastructure can be extended
43
44**Alternatives considered**:
45- CSS transform scaling: Rejected due to layout issues and non-standard behavior
46- Browser-level zoom only: Rejected as doesn't persist per-domain
47- Configuration file storage: Rejected as database is faster for lookups
48
49### 4. Linux Clipboard Integration (wlcopy fallback chain)
50**Task**: Research Linux clipboard tool availability and fallback patterns
51
52**Decision**: Implement command execution chain: wlcopy → xclip → xsel
53**Rationale**:
54- wlcopy is Wayland-native (primary target environment)
55- xclip and xsel provide X11 compatibility
56- exec.Command provides clean abstraction for tool detection
57- Graceful degradation maintains usability across Linux variants
58
59**Alternatives considered**:
60- Go clipboard libraries: Rejected due to additional dependencies
61- D-Bus clipboard access: Rejected as complex and not universally available
62- Only wlcopy support: Rejected as limits platform compatibility
63
64### 5. WebView Zoom API Integration
65**Task**: Research WebView zoom control APIs in Wails v3 context
66
67**Decision**: Use frontend JavaScript with backend coordination for zoom state
68**Rationale**:
69- document.body.style.zoom CSS property for immediate visual feedback
70- Backend Go service manages zoom level persistence and bounds checking
71- Maintains constitutional separation between UI and business logic
72- No direct WebView API dependency required
73
74**Alternatives considered**:
75- Direct WebView SetZoom API: Not available in Wails v3-alpha abstraction
76- Pure CSS zoom transforms: Rejected due to layout calculation issues
77
78## Key Technical Findings
79
80### Firefox Zoom Levels
81Standard zoom progression: 30%, 50%, 67%, 80%, 90%, 100%, 110%, 120%, 133%, 150%, 170%, 200%, 240%, 300%, 400%, 500%
82
83### Event Handling Architecture
84```
85Frontend (JavaScript) → Wails Context → Backend (Go) → Services → Database
86     ↑                                                              ↓
87  UI Events                                              State Persistence
88```
89
90### Clipboard Tool Detection Pattern
91```go
92var clipboardTools = []string{"wlcopy", "xclip", "xsel"}
93for _, tool := range clipboardTools {
94    if _, err := exec.LookPath(tool); err == nil {
95        // Use this tool
96        break
97    }
98}
99```
100
101### Database Schema Extension
102New table: `zoom_levels`
103```sql
104CREATE TABLE zoom_levels (
105    domain TEXT PRIMARY KEY,
106    zoom_factor REAL NOT NULL DEFAULT 1.0,
107    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
108);
109```
110
111## Risks and Mitigation
112
1131. **Risk**: WebView zoom behavior inconsistency across platforms
114   **Mitigation**: Use CSS zoom with bounds checking, test on target platforms
115
1162. **Risk**: Mouse button events not captured in WebView
117   **Mitigation**: Implement JavaScript event delegation on document level
118
1193. **Risk**: Clipboard tools unavailable on target system
120   **Mitigation**: Graceful degradation with user notification
121
1224. **Risk**: Zoom persistence performance impact
123   **Mitigation**: Debounce zoom level saves, use SQLite prepared statements
124
125## Implementation Dependencies
126
127- No new external dependencies required
128- Leverage existing: Wails v3, SQLite, standard Go library
129- Frontend JavaScript for event capture
130- Backend Go services for state management
131- Database schema extension for zoom persistence
132
133All research findings support constitutional principles of speed, simplicity, and single-binary architecture.