tasks.md Raw History Folder

Tasks: Browser Controls UI

Input: Design documents from /home/brice/dev/projects/dumb-browser/specs/002-browser-controls-ui/ Prerequisites: plan.md, research.md, data-model.md, contracts/browser-controls-api.yaml

Feature Summary

Implement keyboard and mouse navigation controls for the Wails-based browser: zoom in/out with Ctrl+/-, back/forward navigation with mouse buttons, URL copying with Ctrl+Shift+C, and dynamic window title updates with SQLite persistence.

Path Conventions

Single project structure (desktop application):

Source: src/models/, src/services/, src/cli/, src/lib/
Tests: tests/contract/, tests/integration/, tests/unit/
Frontend: frontend/src/
Database: SQLite with SQLC generated queries

Phase 3.1: Setup

T001 Create zoom_levels database table with SQLite schema migration in src/db/migrations/003_add_zoom_levels.sql
T002 Generate SQLC queries for zoom level operations in src/db/queries/zoom_levels.sql
T003 [P] Add frontend JavaScript event handlers in frontend/src/events/keyboard.js
T004 [P] Add frontend mouse event handlers in frontend/src/events/mouse.js

Phase 3.2: Tests First (TDD) ⚠️ MUST COMPLETE BEFORE 3.3

CRITICAL: These tests MUST be written and MUST FAIL before ANY implementation

Contract Tests [P]

T005 [P] Contract test POST /zoom/in endpoint in tests/contract/zoom_in_test.go
T006 [P] Contract test POST /zoom/out endpoint in tests/contract/zoom_out_test.go
T007 [P] Contract test POST /navigation/back endpoint in tests/contract/navigation_back_test.go
T008 [P] Contract test POST /navigation/forward endpoint in tests/contract/navigation_forward_test.go
T009 [P] Contract test POST /clipboard/copy-url endpoint in tests/contract/clipboard_copy_test.go
T010 [P] Contract test GET /zoom/get-level endpoint in tests/contract/zoom_get_test.go

Integration Tests [P]

T011 [P] Integration test zoom persistence across domains in tests/integration/zoom_persistence_test.go
T012 [P] Integration test keyboard event handling in tests/integration/keyboard_events_test.go
T013 [P] Integration test mouse navigation in tests/integration/mouse_navigation_test.go
T014 [P] Integration test clipboard tool fallback chain in tests/integration/clipboard_fallback_test.go
T015 [P] Integration test window title updates in tests/integration/window_title_test.go

Phase 3.3: Core Implementation (ONLY after tests are failing)

Data Models [P]

T016 [P] ZoomLevel model with validation in src/models/zoom_level.go
T017 [P] BrowserState model extensions in src/models/browser_state.go
T018 [P] KeyboardEvent model for event processing in src/models/keyboard_event.go
T019 [P] MouseEvent model for navigation in src/models/mouse_event.go

Core Services [P]

T020 [P] ZoomService with Firefox zoom levels in src/services/zoom_service.go
T021 [P] NavigationService with history management in src/services/navigation_service.go
T022 [P] ClipboardService with tool fallback in src/services/clipboard_service.go
T023 [P] WindowTitleService for dynamic updates in src/services/window_title_service.go

Wails Service Layer

T024 BrowserControlService main service in src/services/browser_control_service.go
T025 ZoomIn method implementation with domain persistence
T026 ZoomOut method implementation with bounds checking
T027 NavigateBack method with history validation
T028 NavigateForward method with forward history
T029 CopyCurrentURL method with clipboard tool detection
T030 GetZoomLevel method for domain lookup

Database Layer

T031 ZoomLevelRepository with SQLC integration in src/repositories/zoom_level_repository.go
T032 Database transaction management for zoom operations
T033 Cleanup job for old zoom level entries

Phase 3.4: Integration

Frontend Integration

T034 Wire keyboard events to Wails backend calls in frontend/src/events/keyboard.js
T035 Wire mouse events to navigation methods in frontend/src/events/mouse.js
T036 CSS zoom application with visual feedback in frontend/src/styles/zoom.css
T037 Window title update integration with page changes

Backend Integration

T038 Register BrowserControlService with Wails context in src/app.go
T039 Database migration execution on startup
T040 Error handling and logging for all service methods
T041 Service method validation and bounds checking

Phase 3.5: Polish

Unit Tests [P]

T042 [P] Unit tests for Firefox zoom level validation in tests/unit/zoom_levels_test.go
T043 [P] Unit tests for clipboard tool detection in tests/unit/clipboard_tools_test.go
T044 [P] Unit tests for navigation history bounds in tests/unit/navigation_bounds_test.go
T045 [P] Unit tests for domain validation in tests/unit/domain_validation_test.go

Performance & Documentation

T046 Performance test: zoom operations < 100ms response in tests/performance/zoom_perf_test.go
T047 Performance test: navigation < 200ms response in tests/performance/nav_perf_test.go
T048 Memory usage test: < 10MB additional usage over 10 minutes
T049 Update README with new keyboard shortcuts and features
T050 Run quickstart.md validation scenarios

Dependencies

Critical Dependencies:

Database setup (T001-T002) blocks all repository tasks (T031-T033)
All tests (T005-T015) MUST complete and FAIL before implementation (T016-T041)
Models (T016-T019) block services (T020-T023)
Services block Wails integration (T024-T030)
Core implementation blocks frontend integration (T034-T041)

Parallel Groups:

Setup frontend events: T003, T004
Contract tests: T005-T010
Integration tests: T011-T015
Data models: T016-T019
Core services: T020-T023
Unit tests: T042-T045

Parallel Execution Examples

# Phase 3.1 Setup (parallel frontend)
Task: "Add frontend JavaScript event handlers in frontend/src/events/keyboard.js"
Task: "Add frontend mouse event handlers in frontend/src/events/mouse.js"

# Phase 3.2 Contract Tests (all parallel)
Task: "Contract test POST /zoom/in endpoint in tests/contract/zoom_in_test.go"
Task: "Contract test POST /zoom/out endpoint in tests/contract/zoom_out_test.go" 
Task: "Contract test POST /navigation/back endpoint in tests/contract/navigation_back_test.go"
Task: "Contract test POST /navigation/forward endpoint in tests/contract/navigation_forward_test.go"
Task: "Contract test POST /clipboard/copy-url endpoint in tests/contract/clipboard_copy_test.go"
Task: "Contract test GET /zoom/get-level endpoint in tests/contract/zoom_get_test.go"

# Phase 3.2 Integration Tests (all parallel)
Task: "Integration test zoom persistence across domains in tests/integration/zoom_persistence_test.go"
Task: "Integration test keyboard event handling in tests/integration/keyboard_events_test.go"
Task: "Integration test mouse navigation in tests/integration/mouse_navigation_test.go"
Task: "Integration test clipboard tool fallback chain in tests/integration/clipboard_fallback_test.go"
Task: "Integration test window title updates in tests/integration/window_title_test.go"

# Phase 3.3 Data Models (all parallel)
Task: "ZoomLevel model with validation in src/models/zoom_level.go"
Task: "BrowserState model extensions in src/models/browser_state.go"
Task: "KeyboardEvent model for event processing in src/models/keyboard_event.go"
Task: "MouseEvent model for navigation in src/models/mouse_event.go"

# Phase 3.3 Core Services (all parallel)
Task: "ZoomService with Firefox zoom levels in src/services/zoom_service.go"
Task: "NavigationService with history management in src/services/navigation_service.go"
Task: "ClipboardService with tool fallback in src/services/clipboard_service.go"
Task: "WindowTitleService for dynamic updates in src/services/window_title_service.go"

Firefox Zoom Levels Reference

Standard zoom progression: 30%, 50%, 67%, 80%, 90%, 100%, 110%, 120%, 133%, 150%, 170%, 200%, 240%, 300%, 400%, 500%

Clipboard Tool Fallback Chain

wlcopy (Wayland native)
xclip (X11 primary)
xsel (X11 fallback)

Database Schema

CREATE TABLE zoom_levels (
    domain TEXT PRIMARY KEY,
    zoom_factor REAL NOT NULL DEFAULT 1.0 CHECK(zoom_factor >= 0.3 AND zoom_factor <= 5.0),
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
CREATE INDEX idx_zoom_levels_updated_at ON zoom_levels(updated_at);

Validation Checklist

All contracts have corresponding tests (T005-T010)
All entities have model tasks (T016-T019)
All tests come before implementation (Phase 3.2 before 3.3)
Parallel tasks truly independent (different files)
Each task specifies exact file path
No task modifies same file as another [P] task

Success Criteria

All quickstart.md test scenarios pass
Performance targets met (< 100ms zoom, < 200ms navigation)
Memory usage within constitutional limits (< 10MB additional)
Cross-platform clipboard compatibility maintained
No regressions in existing browser functionality

Total Tasks: 50 tasks across 5 phases Estimated Completion: 2-3 days with parallel execution Critical Path: Database setup → Tests → Models → Services → Integration

source

1# Tasks: Browser Controls UI
2
3**Input**: Design documents from `/home/brice/dev/projects/dumb-browser/specs/002-browser-controls-ui/`
4**Prerequisites**: plan.md, research.md, data-model.md, contracts/browser-controls-api.yaml
5
6## Feature Summary
7Implement keyboard and mouse navigation controls for the Wails-based browser: zoom in/out with Ctrl+/-, back/forward navigation with mouse buttons, URL copying with Ctrl+Shift+C, and dynamic window title updates with SQLite persistence.
8
9## Path Conventions
10Single project structure (desktop application):
11- **Source**: `src/models/`, `src/services/`, `src/cli/`, `src/lib/`
12- **Tests**: `tests/contract/`, `tests/integration/`, `tests/unit/`
13- **Frontend**: `frontend/src/`
14- **Database**: SQLite with SQLC generated queries
15
16## Phase 3.1: Setup
17
18- [ ] T001 Create zoom_levels database table with SQLite schema migration in `src/db/migrations/003_add_zoom_levels.sql`
19- [ ] T002 Generate SQLC queries for zoom level operations in `src/db/queries/zoom_levels.sql`  
20- [ ] T003 [P] Add frontend JavaScript event handlers in `frontend/src/events/keyboard.js`
21- [ ] T004 [P] Add frontend mouse event handlers in `frontend/src/events/mouse.js`
22
23## Phase 3.2: Tests First (TDD) ⚠️ MUST COMPLETE BEFORE 3.3
24
25**CRITICAL: These tests MUST be written and MUST FAIL before ANY implementation**
26
27### Contract Tests [P]
28- [ ] T005 [P] Contract test POST /zoom/in endpoint in `tests/contract/zoom_in_test.go`
29- [ ] T006 [P] Contract test POST /zoom/out endpoint in `tests/contract/zoom_out_test.go`
30- [ ] T007 [P] Contract test POST /navigation/back endpoint in `tests/contract/navigation_back_test.go`
31- [ ] T008 [P] Contract test POST /navigation/forward endpoint in `tests/contract/navigation_forward_test.go`
32- [ ] T009 [P] Contract test POST /clipboard/copy-url endpoint in `tests/contract/clipboard_copy_test.go`
33- [ ] T010 [P] Contract test GET /zoom/get-level endpoint in `tests/contract/zoom_get_test.go`
34
35### Integration Tests [P]
36- [ ] T011 [P] Integration test zoom persistence across domains in `tests/integration/zoom_persistence_test.go`
37- [ ] T012 [P] Integration test keyboard event handling in `tests/integration/keyboard_events_test.go`
38- [ ] T013 [P] Integration test mouse navigation in `tests/integration/mouse_navigation_test.go`
39- [ ] T014 [P] Integration test clipboard tool fallback chain in `tests/integration/clipboard_fallback_test.go`
40- [ ] T015 [P] Integration test window title updates in `tests/integration/window_title_test.go`
41
42## Phase 3.3: Core Implementation (ONLY after tests are failing)
43
44### Data Models [P]
45- [ ] T016 [P] ZoomLevel model with validation in `src/models/zoom_level.go`
46- [ ] T017 [P] BrowserState model extensions in `src/models/browser_state.go`
47- [ ] T018 [P] KeyboardEvent model for event processing in `src/models/keyboard_event.go`
48- [ ] T019 [P] MouseEvent model for navigation in `src/models/mouse_event.go`
49
50### Core Services [P]
51- [ ] T020 [P] ZoomService with Firefox zoom levels in `src/services/zoom_service.go`
52- [ ] T021 [P] NavigationService with history management in `src/services/navigation_service.go`
53- [ ] T022 [P] ClipboardService with tool fallback in `src/services/clipboard_service.go`
54- [ ] T023 [P] WindowTitleService for dynamic updates in `src/services/window_title_service.go`
55
56### Wails Service Layer
57- [ ] T024 BrowserControlService main service in `src/services/browser_control_service.go`
58- [ ] T025 ZoomIn method implementation with domain persistence
59- [ ] T026 ZoomOut method implementation with bounds checking
60- [ ] T027 NavigateBack method with history validation
61- [ ] T028 NavigateForward method with forward history
62- [ ] T029 CopyCurrentURL method with clipboard tool detection
63- [ ] T030 GetZoomLevel method for domain lookup
64
65### Database Layer
66- [ ] T031 ZoomLevelRepository with SQLC integration in `src/repositories/zoom_level_repository.go`
67- [ ] T032 Database transaction management for zoom operations
68- [ ] T033 Cleanup job for old zoom level entries
69
70## Phase 3.4: Integration
71
72### Frontend Integration
73- [ ] T034 Wire keyboard events to Wails backend calls in `frontend/src/events/keyboard.js`
74- [ ] T035 Wire mouse events to navigation methods in `frontend/src/events/mouse.js`
75- [ ] T036 CSS zoom application with visual feedback in `frontend/src/styles/zoom.css`
76- [ ] T037 Window title update integration with page changes
77
78### Backend Integration
79- [ ] T038 Register BrowserControlService with Wails context in `src/app.go`
80- [ ] T039 Database migration execution on startup
81- [ ] T040 Error handling and logging for all service methods
82- [ ] T041 Service method validation and bounds checking
83
84## Phase 3.5: Polish
85
86### Unit Tests [P]
87- [ ] T042 [P] Unit tests for Firefox zoom level validation in `tests/unit/zoom_levels_test.go`
88- [ ] T043 [P] Unit tests for clipboard tool detection in `tests/unit/clipboard_tools_test.go`
89- [ ] T044 [P] Unit tests for navigation history bounds in `tests/unit/navigation_bounds_test.go`
90- [ ] T045 [P] Unit tests for domain validation in `tests/unit/domain_validation_test.go`
91
92### Performance & Documentation
93- [ ] T046 Performance test: zoom operations < 100ms response in `tests/performance/zoom_perf_test.go`
94- [ ] T047 Performance test: navigation < 200ms response in `tests/performance/nav_perf_test.go`
95- [ ] T048 Memory usage test: < 10MB additional usage over 10 minutes
96- [ ] T049 Update README with new keyboard shortcuts and features
97- [ ] T050 Run quickstart.md validation scenarios
98
99## Dependencies
100
101**Critical Dependencies:**
102- Database setup (T001-T002) blocks all repository tasks (T031-T033)
103- All tests (T005-T015) MUST complete and FAIL before implementation (T016-T041)
104- Models (T016-T019) block services (T020-T023)
105- Services block Wails integration (T024-T030)
106- Core implementation blocks frontend integration (T034-T041)
107
108**Parallel Groups:**
109- Setup frontend events: T003, T004
110- Contract tests: T005-T010
111- Integration tests: T011-T015
112- Data models: T016-T019
113- Core services: T020-T023
114- Unit tests: T042-T045
115
116## Parallel Execution Examples
117
118```bash
119# Phase 3.1 Setup (parallel frontend)
120Task: "Add frontend JavaScript event handlers in frontend/src/events/keyboard.js"
121Task: "Add frontend mouse event handlers in frontend/src/events/mouse.js"
122
123# Phase 3.2 Contract Tests (all parallel)
124Task: "Contract test POST /zoom/in endpoint in tests/contract/zoom_in_test.go"
125Task: "Contract test POST /zoom/out endpoint in tests/contract/zoom_out_test.go" 
126Task: "Contract test POST /navigation/back endpoint in tests/contract/navigation_back_test.go"
127Task: "Contract test POST /navigation/forward endpoint in tests/contract/navigation_forward_test.go"
128Task: "Contract test POST /clipboard/copy-url endpoint in tests/contract/clipboard_copy_test.go"
129Task: "Contract test GET /zoom/get-level endpoint in tests/contract/zoom_get_test.go"
130
131# Phase 3.2 Integration Tests (all parallel)
132Task: "Integration test zoom persistence across domains in tests/integration/zoom_persistence_test.go"
133Task: "Integration test keyboard event handling in tests/integration/keyboard_events_test.go"
134Task: "Integration test mouse navigation in tests/integration/mouse_navigation_test.go"
135Task: "Integration test clipboard tool fallback chain in tests/integration/clipboard_fallback_test.go"
136Task: "Integration test window title updates in tests/integration/window_title_test.go"
137
138# Phase 3.3 Data Models (all parallel)
139Task: "ZoomLevel model with validation in src/models/zoom_level.go"
140Task: "BrowserState model extensions in src/models/browser_state.go"
141Task: "KeyboardEvent model for event processing in src/models/keyboard_event.go"
142Task: "MouseEvent model for navigation in src/models/mouse_event.go"
143
144# Phase 3.3 Core Services (all parallel)
145Task: "ZoomService with Firefox zoom levels in src/services/zoom_service.go"
146Task: "NavigationService with history management in src/services/navigation_service.go"
147Task: "ClipboardService with tool fallback in src/services/clipboard_service.go"
148Task: "WindowTitleService for dynamic updates in src/services/window_title_service.go"
149```
150
151## Firefox Zoom Levels Reference
152Standard zoom progression: 30%, 50%, 67%, 80%, 90%, 100%, 110%, 120%, 133%, 150%, 170%, 200%, 240%, 300%, 400%, 500%
153
154## Clipboard Tool Fallback Chain
1551. `wlcopy` (Wayland native)
1562. `xclip` (X11 primary)
1573. `xsel` (X11 fallback)
158
159## Database Schema
160```sql
161CREATE TABLE zoom_levels (
162    domain TEXT PRIMARY KEY,
163    zoom_factor REAL NOT NULL DEFAULT 1.0 CHECK(zoom_factor >= 0.3 AND zoom_factor <= 5.0),
164    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
165);
166CREATE INDEX idx_zoom_levels_updated_at ON zoom_levels(updated_at);
167```
168
169## Validation Checklist
170- [x] All contracts have corresponding tests (T005-T010)
171- [x] All entities have model tasks (T016-T019)  
172- [x] All tests come before implementation (Phase 3.2 before 3.3)
173- [x] Parallel tasks truly independent (different files)
174- [x] Each task specifies exact file path
175- [x] No task modifies same file as another [P] task
176
177## Success Criteria
178- All quickstart.md test scenarios pass
179- Performance targets met (< 100ms zoom, < 200ms navigation)
180- Memory usage within constitutional limits (< 10MB additional)
181- Cross-platform clipboard compatibility maintained
182- No regressions in existing browser functionality
183
184**Total Tasks**: 50 tasks across 5 phases
185**Estimated Completion**: 2-3 days with parallel execution
186**Critical Path**: Database setup → Tests → Models → Services → Integration

tasks.md RawHistoryFolder