v0.1 bf7c821

quickstart.md RawHistoryFolder

Quickstart: Browser Controls UI

Quick Validation Steps

Prerequisites

  • Dumber browser built and running
  • SQLite database initialized
  • WebView displaying a webpage
  • Linux system with clipboard tools (wlcopy/xclip/xsel)

Test Scenario 1: Zoom Controls (FR-001, FR-002, FR-007, FR-008)

Goal: Verify zoom in/out functionality with visual feedback

  1. Setup: Navigate to any webpage (e.g., dumber browse github.com)
  2. Test Zoom In:
    • Press Ctrl + + (plus key)
    • Expected: Page content becomes larger, visual feedback shown
    • Verify: Zoom level increases from 100% to 110%
  3. Test Zoom Out:
    • Press Ctrl + - (minus key)
    • Expected: Page content becomes smaller
    • Verify: Zoom level decreases to 100%
  4. Test Zoom Limits:
    • Press Ctrl + - repeatedly until 30% reached
    • Press Ctrl + - again
    • Expected: No further zoom reduction, remains at 30%
    • Repeat for upper limit (500%)

Pass Criteria: ✅ Zoom changes are visible and bounded correctly

Test Scenario 2: Navigation Controls (FR-003, FR-004, FR-010)

Goal: Verify mouse back/forward button functionality

  1. Setup: Navigate to multiple pages to build history:
    • dumber browse github.com
    • Navigate to github.com/bnema
    • Navigate to any repository page
  2. Test Back Navigation:
    • Click mouse button 4 (back button)
    • Expected: Browser navigates to previous page
    • Verify: URL changes to previous page in history
  3. Test Forward Navigation:
    • Click mouse button 5 (forward button)
    • Expected: Browser navigates forward in history
    • Verify: URL changes to next page
  4. Test Empty History Edge Cases:
    • Navigate back to beginning of history
    • Click back button again
    • Expected: No navigation occurs, no error shown

Pass Criteria: ✅ Navigation works and handles edge cases gracefully

Test Scenario 3: URL Copy (FR-005, FR-006, FR-011)

Goal: Verify URL copying with clipboard tool fallbacks

  1. Setup: Ensure at least one clipboard tool is available: 
    which wlcopy || which xclip || which xsel
  2. Test URL Copy:
    • Navigate to any webpage
    • Press Ctrl + Shift + C
    • Expected: Current URL copied to clipboard
  3. Test Clipboard Content: 
    # Wayland
wl-paste
# X11
xclip -o -selection clipboard
    • Verify: Output matches current browser URL
  4. Test Fallback Chain (if multiple tools available):
    • Temporarily rename wlcopy to test fallback
    • Repeat copy operation
    • Expected: Falls back to xclip or xsel

Pass Criteria: ✅ URL copying works with proper fallback behavior

Test Scenario 4: Zoom Persistence (FR-009)

Goal: Verify per-domain zoom level persistence

  1. Setup: Clear any existing zoom preferences
  2. Test Domain Persistence:
    • Navigate to github.com
    • Set zoom to 120% (Ctrl + + twice from 100%)
    • Navigate away to stackoverflow.com
    • Set zoom to 80% (Ctrl + - twice from 100%)
    • Navigate back to github.com
    • Expected: Zoom automatically restores to 120%
  3. Test Session Persistence:
    • Close and restart browser
    • Navigate to github.com
    • Expected: Zoom level still at 120%

Pass Criteria: ✅ Zoom levels persist per-domain across sessions

Test Scenario 5: Window Title Updates (FR-012)

Goal: Verify dynamic window title updates

  1. Setup: Browser window visible with title bar
  2. Test Title Updates:
    • Navigate to github.com
    • Expected: Window title shows "Dumber - GitHub"
    • Navigate to a specific repository
    • Expected: Window title updates to show repository name
    • Navigate to stackoverflow.com
    • Expected: Window title shows "Dumber - Stack Overflow"

Pass Criteria: ✅ Window title dynamically reflects current page

Integration Test Checklist

Database Integration

  • Zoom levels stored in zoom_levels table
  • Domain-based lookups work correctly
  • Old zoom preferences cleaned up periodically
  • Database transactions complete successfully

WebView Integration

  • Keyboard events captured from WebView
  • Mouse events captured and processed
  • CSS zoom applied correctly
  • Navigation history maintained

System Integration

  • Clipboard tools detected correctly
  • Fallback chain executes in order
  • Error handling for missing tools
  • No system dependencies beyond WebKit2GTK

Performance Verification

Response Time Tests

  1. Zoom Operations:
    • Measure time from keypress to visual change
    • Target: < 100ms response time
  2. Navigation Operations:
    • Measure time from mouse click to page load
    • Target: < 200ms for local history navigation
  3. Database Operations:
    • Measure zoom level persistence write time
    • Target: < 50ms for database writes

Memory Usage Tests

  1. Baseline: Measure memory before feature use
  2. After Usage: Use all features extensively for 10 minutes
  3. Memory Growth: Should be < 10MB additional usage
  4. No Leaks: Memory should stabilize, not continuously grow

Troubleshooting

Common Issues

  1. Zoom not working: Check JavaScript console for errors
  2. Mouse buttons not responding: Verify WebView focus state
  3. Clipboard copy failing: Check available clipboard tools
  4. Database errors: Verify SQLite file permissions
  5. Title not updating: Check UpdatePageTitle service calls

Debug Commands

# Check clipboard tools
which wlcopy xclip xsel

# Verify database schema
sqlite3 ~/.config/dumber/browser.db ".schema zoom_levels"

# Check zoom level data
sqlite3 ~/.config/dumber/browser.db "SELECT * FROM zoom_levels;"

# Monitor application logs
dumber --debug

Success Criteria

All test scenarios must pass with:

  • ✅ No crashes or error dialogs
  • ✅ Responsive UI (< 100ms feedback)
  • ✅ Data persistence working correctly
  • ✅ Graceful error handling
  • ✅ Cross-platform clipboard compatibility
  • ✅ Memory usage within constitutional limits

Ready for Production: All scenarios pass consistently across test runs

source
1# Quickstart: Browser Controls UI
2
3## Quick Validation Steps
4
5### Prerequisites
6- Dumber browser built and running
7- SQLite database initialized
8- WebView displaying a webpage
9- Linux system with clipboard tools (wlcopy/xclip/xsel)
10
11### Test Scenario 1: Zoom Controls (FR-001, FR-002, FR-007, FR-008)
12**Goal**: Verify zoom in/out functionality with visual feedback
13
141. **Setup**: Navigate to any webpage (e.g., `dumber browse github.com`)
152. **Test Zoom In**:
16   - Press `Ctrl` + `+` (plus key)
17   - **Expected**: Page content becomes larger, visual feedback shown
18   - **Verify**: Zoom level increases from 100% to 110%
193. **Test Zoom Out**:
20   - Press `Ctrl` + `-` (minus key)  
21   - **Expected**: Page content becomes smaller
22   - **Verify**: Zoom level decreases to 100%
234. **Test Zoom Limits**:
24   - Press `Ctrl` + `-` repeatedly until 30% reached
25   - Press `Ctrl` + `-` again
26   - **Expected**: No further zoom reduction, remains at 30%
27   - Repeat for upper limit (500%)
28
29**Pass Criteria**: ✅ Zoom changes are visible and bounded correctly
30
31### Test Scenario 2: Navigation Controls (FR-003, FR-004, FR-010)
32**Goal**: Verify mouse back/forward button functionality
33
341. **Setup**: Navigate to multiple pages to build history:
35   - `dumber browse github.com` 
36   - Navigate to `github.com/bnema`
37   - Navigate to any repository page
382. **Test Back Navigation**:
39   - Click mouse button 4 (back button)
40   - **Expected**: Browser navigates to previous page
41   - **Verify**: URL changes to previous page in history
423. **Test Forward Navigation**:
43   - Click mouse button 5 (forward button) 
44   - **Expected**: Browser navigates forward in history
45   - **Verify**: URL changes to next page
464. **Test Empty History Edge Cases**:
47   - Navigate back to beginning of history
48   - Click back button again
49   - **Expected**: No navigation occurs, no error shown
50
51**Pass Criteria**: ✅ Navigation works and handles edge cases gracefully
52
53### Test Scenario 3: URL Copy (FR-005, FR-006, FR-011)
54**Goal**: Verify URL copying with clipboard tool fallbacks
55
561. **Setup**: Ensure at least one clipboard tool is available:
57   ```bash
58   which wlcopy || which xclip || which xsel
59   ```
602. **Test URL Copy**:
61   - Navigate to any webpage
62   - Press `Ctrl` + `Shift` + `C`
63   - **Expected**: Current URL copied to clipboard
643. **Test Clipboard Content**:
65   ```bash
66   # Wayland
67   wl-paste
68   # X11
69   xclip -o -selection clipboard
70   ```
71   - **Verify**: Output matches current browser URL
724. **Test Fallback Chain** (if multiple tools available):
73   - Temporarily rename `wlcopy` to test fallback
74   - Repeat copy operation
75   - **Expected**: Falls back to `xclip` or `xsel`
76
77**Pass Criteria**: ✅ URL copying works with proper fallback behavior
78
79### Test Scenario 4: Zoom Persistence (FR-009)
80**Goal**: Verify per-domain zoom level persistence
81
821. **Setup**: Clear any existing zoom preferences
832. **Test Domain Persistence**:
84   - Navigate to `github.com`
85   - Set zoom to 120% (Ctrl + + twice from 100%)
86   - Navigate away to `stackoverflow.com`
87   - Set zoom to 80% (Ctrl + - twice from 100%)  
88   - Navigate back to `github.com`
89   - **Expected**: Zoom automatically restores to 120%
903. **Test Session Persistence**:
91   - Close and restart browser
92   - Navigate to `github.com`
93   - **Expected**: Zoom level still at 120%
94
95**Pass Criteria**: ✅ Zoom levels persist per-domain across sessions
96
97### Test Scenario 5: Window Title Updates (FR-012)
98**Goal**: Verify dynamic window title updates
99
1001. **Setup**: Browser window visible with title bar
1012. **Test Title Updates**:
102   - Navigate to `github.com`
103   - **Expected**: Window title shows "Dumber - GitHub"
104   - Navigate to a specific repository
105   - **Expected**: Window title updates to show repository name
106   - Navigate to `stackoverflow.com`
107   - **Expected**: Window title shows "Dumber - Stack Overflow"
108
109**Pass Criteria**: ✅ Window title dynamically reflects current page
110
111## Integration Test Checklist
112
113### Database Integration
114- [ ] Zoom levels stored in `zoom_levels` table
115- [ ] Domain-based lookups work correctly
116- [ ] Old zoom preferences cleaned up periodically
117- [ ] Database transactions complete successfully
118
119### WebView Integration  
120- [ ] Keyboard events captured from WebView
121- [ ] Mouse events captured and processed
122- [ ] CSS zoom applied correctly
123- [ ] Navigation history maintained
124
125### System Integration
126- [ ] Clipboard tools detected correctly
127- [ ] Fallback chain executes in order
128- [ ] Error handling for missing tools
129- [ ] No system dependencies beyond WebKit2GTK
130
131## Performance Verification
132
133### Response Time Tests
1341. **Zoom Operations**: 
135   - Measure time from keypress to visual change
136   - **Target**: < 100ms response time
1372. **Navigation Operations**:
138   - Measure time from mouse click to page load
139   - **Target**: < 200ms for local history navigation
1403. **Database Operations**:
141   - Measure zoom level persistence write time
142   - **Target**: < 50ms for database writes
143
144### Memory Usage Tests
1451. **Baseline**: Measure memory before feature use
1462. **After Usage**: Use all features extensively for 10 minutes  
1473. **Memory Growth**: Should be < 10MB additional usage
1484. **No Leaks**: Memory should stabilize, not continuously grow
149
150## Troubleshooting
151
152### Common Issues
1531. **Zoom not working**: Check JavaScript console for errors
1542. **Mouse buttons not responding**: Verify WebView focus state
1553. **Clipboard copy failing**: Check available clipboard tools
1564. **Database errors**: Verify SQLite file permissions
1575. **Title not updating**: Check UpdatePageTitle service calls
158
159### Debug Commands
160```bash
161# Check clipboard tools
162which wlcopy xclip xsel
163
164# Verify database schema
165sqlite3 ~/.config/dumber/browser.db ".schema zoom_levels"
166
167# Check zoom level data
168sqlite3 ~/.config/dumber/browser.db "SELECT * FROM zoom_levels;"
169
170# Monitor application logs
171dumber --debug
172```
173
174## Success Criteria
175
176All test scenarios must pass with:
177- ✅ No crashes or error dialogs
178- ✅ Responsive UI (< 100ms feedback)
179- ✅ Data persistence working correctly  
180- ✅ Graceful error handling
181- ✅ Cross-platform clipboard compatibility
182- ✅ Memory usage within constitutional limits
183
184**Ready for Production**: All scenarios pass consistently across test runs

Keyboard shortcuts

Single-key shortcuts are on. ctrl k and esc work whatever this says.

ctrl k :
go to a section, branch, tag, file or repository
?
this list
j k
move the row cursor down / up
enter
open the row under the cursor; on Files, a directory opens or closes in place
↑ ↓ ← → home end
in the file tree (focus on a row): previous / next row, close / open a directory or go to its parent / first entry, first / last row. They never open a file
l h
on Files: open a directory or a file / close a directory or go up to its parent, then to the parent page. Elsewhere: into the side panel (on a merge request, its files) / back to the content; there j k move between its controls
g g G
first / last row
/
filter the list; on Files, find a file anywhere in the repository (esc clears, enter opens the best match)
b
switch branch or tag
g s g f g c g b g m g i g r g a
tabs: summary, files, commits, branches & tags, merge requests, issues, releases, actions (when available)
g h
home
w
wide mode: use the whole width of the screen, or not (remembered)
y
copy a permalink pinned to the commit
d u x
diff: split / unified / collapse or expand all
e E
diff: the whole file in view / every file, with the lines the hunks hide
n
merge request: next note in the diff
esc
close a dialog, leave a field

Branches 8

Tags 42

↑↓ moveenter openesc close