1# Data Model: Browser Controls UI
2
3## Entities
4
5### 1. ZoomLevel
6Represents domain-specific zoom preferences for persistent user experience.
7
8**Fields**:
9- `Domain` (string, primary key): Website domain (e.g., "github.com", "stackoverflow.com")
10- `ZoomFactor` (float64): Zoom multiplier (0.3 to 5.0 range, default 1.0)
11- `UpdatedAt` (time.Time): Timestamp of last zoom level change
12
13**Validation Rules**:
14- Domain must be valid hostname format
15- ZoomFactor must be within Firefox range: 0.30 ≤ zoom ≤ 5.00
16- ZoomFactor must match standard Firefox zoom levels (30%, 50%, 67%, 80%, 90%, 100%, 110%, 120%, 133%, 150%, 170%, 200%, 240%, 300%, 400%, 500%)
17- UpdatedAt automatically set on creation/update
18
19**Relationships**:
20- One-to-one with website domains
21- No foreign key relationships (standalone entity)
22
23### 2. BrowserState (Extended)
24Existing entity extended with zoom and navigation state management.
25
26**New Fields**:
27- `CurrentZoomLevel` (float64): Active zoom level for current page
28- `NavigationHistory` ([]HistoryEntry): Back/forward navigation stack
29- `HistoryIndex` (int): Current position in navigation history
30
31**State Transitions**:
32- Zoom In: CurrentZoomLevel → Next higher Firefox zoom level
33- Zoom Out: CurrentZoomLevel → Next lower Firefox zoom level  
34- Navigate Back: HistoryIndex decrements (if > 0)
35- Navigate Forward: HistoryIndex increments (if < len(NavigationHistory)-1)
36- URL Change: Update CurrentZoomLevel from ZoomLevel persistence
37
38**Validation Rules**:
39- CurrentZoomLevel follows same rules as ZoomLevel.ZoomFactor
40- HistoryIndex must be valid array index (0 ≤ index < len(NavigationHistory))
41- NavigationHistory maintained as bounded array (configurable max size)
42
43### 3. KeyboardEvent (Transient)
44Represents keyboard input events for processing.
45
46**Fields**:
47- `Key` (string): Key identifier ("=", "-", "c")
48- `Modifiers` ([]string): Active modifier keys (["ctrl"], ["ctrl", "shift"])
49- `Timestamp` (time.Time): Event occurrence time
50
51**Validation Rules**:
52- Key must be non-empty string
53- Modifiers must be valid modifier keys ("ctrl", "shift", "alt", "meta")
54- Timestamp must be recent (within reasonable event processing window)
55
56**State Transitions**:
57- Ctrl+Plus → ZoomIn action
58- Ctrl+Minus → ZoomOut action  
59- Ctrl+Shift+C → CopyURL action
60
61### 4. MouseEvent (Transient)
62Represents mouse button events for navigation.
63
64**Fields**:
65- `Button` (int): Mouse button identifier (3=back, 4=forward)
66- `EventType` (string): Event type ("mousedown", "mouseup")
67- `Timestamp` (time.Time): Event occurrence time
68
69**Validation Rules**:
70- Button must be 3 (back) or 4 (forward)
71- EventType must be valid mouse event type
72- Only "mousedown" events trigger navigation actions
73
74**State Transitions**:
75- Button 3 mousedown → NavigateBack action
76- Button 4 mousedown → NavigateForward action
77
78## Database Schema Changes
79
80### New Table: zoom_levels
81```sql
82CREATE TABLE zoom_levels (
83    domain TEXT PRIMARY KEY,
84    zoom_factor REAL NOT NULL DEFAULT 1.0 CHECK(zoom_factor >= 0.3 AND zoom_factor <= 5.0),
85    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
86);
87
88CREATE INDEX idx_zoom_levels_updated_at ON zoom_levels(updated_at);
89```
90
91### SQLC Queries
92```sql
93-- name: GetZoomLevel :one
94SELECT zoom_factor FROM zoom_levels WHERE domain = ?;
95
96-- name: SetZoomLevel :exec
97INSERT OR REPLACE INTO zoom_levels (domain, zoom_factor, updated_at)
98VALUES (?, ?, CURRENT_TIMESTAMP);
99
100-- name: CleanupOldZoomLevels :exec
101DELETE FROM zoom_levels WHERE updated_at < date('now', '-30 days');
102```
103
104## Data Flow
105
106### Zoom Operations
1071. User triggers zoom event → JavaScript captures keyboard event
1082. Frontend calls backend `ZoomIn()` or `ZoomOut()` method
1093. Backend calculates next valid Firefox zoom level
1104. Backend updates BrowserState.CurrentZoomLevel
1115. Backend persists to database via `SetZoomLevel`
1126. Frontend applies CSS zoom styling
1137. Optional: Visual feedback notification
114
115### Navigation Operations  
1161. User triggers mouse back/forward → JavaScript captures mouse event
1172. Frontend calls backend `NavigateBack()` or `NavigateForward()` method
1183. Backend validates navigation history bounds
1194. Backend updates BrowserState.HistoryIndex
1205. Backend returns target URL from history
1216. Frontend navigates WebView to target URL
122
123### URL Copy Operation
1241. User triggers Ctrl+Shift+C → JavaScript captures keyboard event
1252. Frontend calls backend `CopyCurrentURL()` method  
1263. Backend retrieves current URL from BrowserState
1274. Backend executes clipboard tool chain (wlcopy → xclip → xsel)
1285. Backend returns success/failure status
1296. Optional: Visual feedback notification
130
131## Validation Strategy
132
133### Input Validation
134- All user inputs validated at service layer entry points
135- Zoom levels constrained to Firefox standard values
136- Navigation bounds checking prevents array index errors
137- URL validation for copy operations
138
139### Data Integrity
140- SQLite constraints enforce zoom level ranges
141- Database transactions for atomic state updates
142- Error handling for clipboard tool failures
143- Graceful degradation when tools unavailable
144
145### Performance Considerations
146- Zoom level persistence debounced to prevent excessive DB writes
147- Navigation history bounded to prevent memory growth
148- Database cleanup for old zoom preferences
149- Prepared statements for repeated queries
150
151## Error Handling
152
153### Domain Errors
154- Invalid zoom level → clamp to nearest valid value
155- Empty navigation history → silent no-op
156- Invalid clipboard tool → try next in fallback chain
157- Malformed URL → log error, return failure status
158
159### System Errors
160- Database unavailable → continue with in-memory state only
161- Clipboard tools unavailable → user notification, graceful degradation
162- WebView navigation failure → restore previous state
163- Event processing errors → log and continue
164
165All data models maintain constitutional principles of simplicity and performance while providing robust user experience for browser control operations.