1# Dumber, fully unfeatured unbloated browser for tiling WMs
2
3<p align="center">
4  <img src="assets/logo.svg" alt="Dumber Logo" width="256" height="256" />
5</p>
6
7Dumber is a minimalist browser and launcher companion focused on speed and simplicity. It ships a built‑in WebKitGTK (GTK4) window for navigation and a CLI with dmenu‑style launcher integration (rofi, fuzzel).
8
9- Native GUI via WebKitGTK 6 (GTK4, CGO) with an embedded homepage UI.
10- CLI that parses URLs, supports search shortcuts (e.g., `g:query`), and integrates with rofi/dmenu.
11- Persistent history and per‑domain zoom levels (SQLite, XDG locations).
12- Configurable via `config.json` and environment variables, with live reload.
13
14## Wayland‑First
15- Dumb on purpose, designed for Wayland window managers (Sway, Hyprland, River, Niri, etc..) it's a tiny companion that interact nicely with your launcher.
16- Uses a native Wayland WebKitGTK-6.0 window; no external browser required and no X11/XWayland dependency.
17- Optimized for dmenu‑style launchers (rofi, fuzzel, wofi) and keyboard‑driven workflows.
18
19## Status
20- Early development stage with regular releases. The workspace management system is fully functional and the browser works well for daily use. Expect some rough edges but core features are stable.
21
22## Features
23- **Complete workspace management**: Zellij-inspired pane splitting with binary tree layout, stacked panes with title bars, focus tracking, and modal keyboard controls
24- **Multi-pane WebView architecture**: Independent browsing sessions per pane with proper lifecycle management
25- **Advanced popup handling**: Intelligent popup management for tiling WMs - OAuth flows, window.open(), and popup deduplication
26- **Window-level global shortcuts**: Centralized shortcut handling to prevent conflicts between multiple WebView instances
27- **GPU rendering and hardware video acceleration**: Automatic GPU detection with VA-API/VDPAU support
28- **Built-in ad blocker**: UBlock-based content filtering (network blocking functional, cosmetic filtering in progress)
29- **Configurable color palettes**: Customizable light and dark themes with semantic color tokens injected as CSS custom properties
30- **Terminal-style UI design**: Monospace fonts, sharp corners, dashed borders with configurable appearance settings
31- **dmenu‑style launcher integration**: rofi, fuzzel integration with favicon display, history and search shortcut suggestions
32- **Comprehensive keyboard controls**: Complete keyboard-driven workflow with shortcuts and gestures
33- **Persistent history and zoom**: SQLite-based history with configurable default zoom and per‑domain zoom persistence
34- **Fully configurable**: Single config file with live reload and environment variable overrides
35
36## Controls & Shortcuts
37
38### Keyboard Shortcuts
39
40#### Browser Controls
41| Shortcut | Action | Notes |
42|----------|--------|-------|
43| **F12** | Open Developer Tools | WebKit inspector |
44| **Ctrl/Cmd+L** | Open Omnibox | URL/search input with history |
45| **Ctrl/Cmd+F** | Find in Page | Search text within current page |
46| **Ctrl/Cmd+=** | Zoom In | Firefox-compatible zoom levels |
47| **Ctrl/Cmd++** | Zoom In | Alternative plus key |
48| **Ctrl/Cmd+-** | Zoom Out | Works across keyboard layouts |
49| **Ctrl/Cmd+0** | Reset Zoom | Return to 100% zoom |
50| **Ctrl/Cmd+Shift+C** | Copy URL | Copy current URL to clipboard with toast |
51| **Ctrl/Cmd+Shift+P** | Print Page | Open native print dialog |
52| **Ctrl/Cmd+R** / **F5** | Reload Page | Refresh current page |
53| **Ctrl/Cmd+Shift+R** | Hard Reload | Refresh ignoring cache |
54| **Ctrl+←** / **Ctrl+→** | Navigate Back/Forward | Browser history navigation |
55
56#### Zellij-Inspired Pane Management
57| Shortcut | Action | Notes |
58|----------|--------|-------|
59| **Ctrl/Cmd+P** | Enter Pane Mode | Modal mode for pane operations |
60| **→** / **R** (in pane mode) | Split Right | Create new pane to the right |
61| **←** / **L** (in pane mode) | Split Left | Create new pane to the left |
62| **↑** / **U** (in pane mode) | Split Up | Create new pane above |
63| **↓** / **D** (in pane mode) | Split Down | Create new pane below |
64| **S** (in pane mode) | Stack Pane | Create stacked pane (Zellij-style) |
65| **X** (in pane mode) | Close Pane | Close current pane |
66| **Enter** (in pane mode) | Confirm Action | Confirm pane operation |
67| **Escape** (in pane mode) | Exit Pane Mode | Return to normal navigation |
68| **Alt+Arrow Keys** | Navigate Panes | Move focus between panes |
69| **Alt+Up/Down** | Navigate Stack | Navigate between stacked panes |
70
71### Mouse Controls
72| Action | Result | Notes |
73|--------|---------|-------|
74| **Ctrl+Scroll Up** | Zoom In | Smooth zoom control |
75| **Ctrl+Scroll Down** | Zoom Out | Smooth zoom control |
76| **Mouse Button 8** | Navigate Back | Side button (back) |
77| **Mouse Button 9** | Navigate Forward | Side button (forward) |
78| **Two-finger Swipe** | Back/Forward | When supported by touchpad |
79
80### Omnibox/Find Mode (when active)
81| Shortcut | Action | Notes |
82|----------|--------|-------|
83| **Escape** | Close overlay | Exit omnibox or find mode |
84| **Enter** | Execute/Navigate | Navigate to URL or jump to match |
85| **Shift+Enter** | Previous Match | Find mode: go to previous match |
86| **Alt+Enter** | Center Match | Find mode: center on match, keep open |
87| **↑/↓ Arrow** | Navigate Results | Browse suggestions/matches |
88
89All zoom changes are automatically persisted per-domain and restored on next visit.
90
91## Quick Start
92Prerequisites:
93- Go 1.25+
94- Node.js 20+ and npm (for building the embedded TypeScript frontend)
95- For GUI build: WebKitGTK 6 and GTK4 dev packages (examples)
96  - Debian/Ubuntu: `libwebkitgtk-6.0-dev libgtk-4-dev build-essential`
97  - Arch: `webkitgtk-6.0 gtk4 base-devel`
98
99Build options:
100- GUI (default, recommended):
101  - `make build`          # builds frontend + Go with `-tags=webkit_cgo`
102  - Run: `./dist/dumber`  # opens the embedded homepage
103- CLI‑only (no GUI, CGO disabled):
104  - `make build-no-gui`
105  - Run: `./dist/dumber-no-gui version`
106
107Development:
108- `make dev` runs `go run .` (non‑CGO; GUI stubs log to console)
109- `make test` runs tests; `make lint` runs golangci‑lint
110
111## Install
112**Note**: `go install` will not work for this project because the frontend assets must be built first and embedded into the binary. Use the build commands instead:
113
114- GUI build (default, recommended):
115  - Ensure WebKit2GTK/GTK dev packages are installed (see prerequisites)
116  - Clone the repo and run `make build` (builds frontend first, then Go with GUI support)
117  - The resulting `./dist/dumber` binary includes the native GUI window
118- CLI‑only (no native window):
119  - Clone the repo and run `make build-no-gui`
120  - The resulting `./dist/dumber-no-gui` binary runs CLI flows with GUI code stubbed
121
122## Usage
123- Open a URL or search:
124  - `dumber browse https://example.com`
125  - `dumber browse example.com`        # scheme auto‑added
126  - `dumber browse g:golang`           # Google search via shortcut
127- Launch the GUI directly:
128  - `dumber`                           # no args → opens GUI homepage
129- Show version information:
130  - `dumber version`                   # display version, commit, and build date
131- Launcher integration (dmenu‑style examples):
132  - rofi:   `dumber dmenu | rofi -dmenu -p "Browse: " | dumber dmenu --select`
133  - fuzzel: `dumber dmenu | fuzzel --dmenu -p "Browse: " | dumber dmenu --select`
134- Manage browsing history:
135  - `dumber history`                   # list recent history (default: 20 entries)
136  - `dumber history list -n 50`       # list 50 recent entries
137  - `dumber history search golang`    # search history for "golang"
138  - `dumber history stats`            # show history statistics
139  - `dumber history clear`            # clear all history (with confirmation)
140  - `dumber history clear --force`    # clear all history (no confirmation)
141- Clean up data and cache:
142  - `dumber purge`                        # purge all data (with confirmation)
143  - `dumber purge --force`                # purge all data (no confirmation)
144  - `dumber purge -d -H -c`               # purge database and both caches
145  - `dumber purge --browser-data`         # purge WebKit data (cookies, etc.)
146- Manage logs:
147  - `dumber logs list`                    # list available log files
148  - `dumber logs tail`                    # tail current log file
149  - `dumber logs clean`                   # clean up old log files
150
151### Dmenu mode invocation
152You can invoke dmenu mode in two ways:
153- Subcommand (recommended): `dumber dmenu` … and `dumber dmenu --select`
154- Root flag (generate options only): `dumber --dmenu`
155
156Note: The root flag path only generates options; for processing a selection (`--select`), use the `dmenu` subcommand as the receiving command.
157
158In GUI mode the app serves an embedded homepage via `dumb://homepage`, and frontend assets under `dumb://app/...`.
159
160## Pane Management (Zellij-Inspired)
161
162Dumber features a Zellij-inspired pane management system that allows you to split your browser window into multiple panes, each running independent web sessions.
163
164### How it Works
1651. **Enter Pane Mode**: Press `Ctrl+P` to enter pane mode (modal interface with timeout)
1662. **Split or Stack Panes**: Use arrow keys or letter shortcuts:
167   - `→` or `R` - Split right
168   - `←` or `L` - Split left
169   - `↑` or `U` - Split up
170   - `↓` or `D` - Split down
171   - `S` - Stack panes (Zellij-style, shows title bars for collapsed panes)
1723. **Navigate**: Use `Alt+Arrow Keys` to move focus between split panes, or `Alt+Up/Down` to navigate within stacked panes
1734. **Close**: Press `X` in pane mode to close the current pane
174
175### Features
176- **Binary tree layout**: Panes are organized in a binary tree structure for optimal space usage
177- **Stacked panes**: Zellij-style stacking with collapsed title bars showing "Page Title - domain" for inactive panes
178- **Focus management**: Visual borders, hover-to-focus, and enhanced focus throttling (100ms) for intuitive navigation
179- **Independent sessions**: Each pane maintains its own browsing session, history, and zoom level
180- **Advanced popup handling**: Intelligent popup vs tab detection, OAuth auto-close, and popup deduplication with SHA256 fingerprinting
181- **Cross-WebView communication**: localStorage-based parent-popup bridge enabling proper `window.opener` functionality
182- **WebView identity tracking**: Unique WebView ID system for precise popup targeting and enhanced debugging
183- **Keyboard-driven**: All operations accessible via keyboard shortcuts with modal pane mode
184
185### Configuration
186The pane system is fully configurable via `config.json`:
187```json
188"workspace": {
189  "enable_zellij_controls": true,
190  "pane_mode": {
191    "activation_shortcut": "cmdorctrl+p",
192    "timeout_ms": 3000,
193    "action_bindings": {
194      "arrowright": "split-right",
195      "r": "split-right",
196      "x": "close-pane",
197      // ... full key mappings
198    }
199  },
200  "popups": {
201    "placement": "right",
202    "open_in_new_pane": true
203  },
204  "styling": {
205    "border_width": 2,
206    "border_color": "@theme_selected_bg_color",
207    "transition_duration": 120
208  }
209}
210```
211
212## Configuration
213
214Dumber follows the XDG Base Directory spec:
215- Config: `~/.config/dumber/config.json`
216- Data:   `~/.local/share/dumber`
217- State:  `~/.local/state/dumber` (default DB lives here)
218
219A default `config.json` is created on first run. Config changes are watched and applied at runtime when possible.
220
221### Complete Configuration Reference
222
223#### Database Configuration
224```json
225"database": {
226  "path": "~/.local/state/dumber/history.db",
227  "max_connections": 1,
228  "max_idle_time": "5m0s",
229  "query_timeout": "30s"
230}
231```
232
233#### History Management
234```json
235"history": {
236  "max_entries": 10000,
237  "retention_period_days": 365,
238  "cleanup_interval_days": 1
239}
240```
241
242#### Search Shortcuts
243```json
244"search_shortcuts": {
245  "g":   { "url": "https://www.google.com/search?q=%s", "description": "Google search" },
246  "gh":  { "url": "https://github.com/search?q=%s", "description": "GitHub search" },
247  "yt":  { "url": "https://www.youtube.com/results?search_query=%s", "description": "YouTube search" },
248  "w":   { "url": "https://en.wikipedia.org/wiki/%s", "description": "Wikipedia search" },
249  "ddg": { "url": "https://duckduckgo.com/?q=%s", "description": "DuckDuckGo search" },
250  "so":  { "url": "https://stackoverflow.com/search?q=%s", "description": "Stack Overflow search" },
251  "r":   { "url": "https://www.reddit.com/search?q=%s", "description": "Reddit search" },
252  "npm": { "url": "https://www.npmjs.com/search?q=%s", "description": "npm package search" },
253  "go":  { "url": "https://pkg.go.dev/search?q=%s", "description": "Go package search" },
254  "mdn": { "url": "https://developer.mozilla.org/en-US/search?q=%s", "description": "MDN Web Docs search" }
255}
256```
257
258#### Dmenu Integration
259```json
260"dmenu": {
261  "max_history_items": 20,
262  "show_visit_count": true,
263  "show_last_visited": true,
264  "history_prefix": "🕒",
265  "shortcut_prefix": "🔍",
266  "url_prefix": "🌐",
267  "date_format": "2006-01-02 15:04",
268  "sort_by_visit_count": true
269}
270```
271
272#### Logging Configuration
273```json
274"logging": {
275  "level": "info",
276  "format": "text",
277  "filename": "",
278  "max_size": 100,
279  "max_backups": 3,
280  "max_age": 7,
281  "compress": true
282}
283```
284
285#### Appearance Settings
286```json
287"appearance": {
288  "sans_font": "Fira Sans",
289  "serif_font": "Fira Sans",
290  "monospace_font": "Fira Code",
291  "default_font_size": 16,
292  "default_zoom": 1.2,
293  "color_palette": {
294    "light": {
295      "background": "#ffffff",
296      "surface": "#f5f5f5",
297      "text": "#1a1a1a",
298      "text_muted": "#6b7280",
299      "accent": "#3b82f6",
300      "border": "#e5e7eb"
301    },
302    "dark": {
303      "background": "#0a0a0a",
304      "surface": "#1a1a1a",
305      "text": "#e5e7eb",
306      "text_muted": "#9ca3af",
307      "accent": "#60a5fa",
308      "border": "#374151"
309    }
310  }
311}
312```
313
314#### Rendering Mode (GPU/CPU)
315```json
316"rendering_mode": "auto"
317```
318- `auto`: Detect GPU availability and use GPU when available (default)
319- `gpu`: Force GPU acceleration (Vulkan/OpenGL via GTK4)
320- `cpu`: Force software rendering
321
322### Environment Variables
323All config values can be overridden with environment variables using the `DUMB_BROWSER_` prefix:
324
325```bash
326# Database
327DUMB_BROWSER_DATABASE_PATH="./browser.db"
328DUMB_BROWSER_DATABASE_MAX_CONNECTIONS=5
329
330# Rendering mode (special variable name)
331DUMBER_RENDERING_MODE="gpu"
332
333# Dmenu settings
334DUMB_BROWSER_DMENU_MAX_HISTORY_ITEMS=50
335DUMB_BROWSER_DMENU_SHOW_VISIT_COUNT=false
336
337# Logging
338DUMB_BROWSER_LOGGING_LEVEL="debug"
339DUMB_BROWSER_LOGGING_FORMAT="json"
340```
341
342### CLI Flags
343The browse command supports additional runtime flags:
344```bash
345dumber browse --rendering-mode=gpu https://example.com
346```
347
348
349## Building With WebKitGTK 6 (GTK4)
350- The GUI requires building with `-tags=webkit_cgo` and CGO enabled.
351- Ensure WebKitGTK 6 and GTK4 dev headers are installed (see prerequisites).
352- Make targets handle both frontend and Go build steps:
353  - `make build-gui` (CGO enabled)
354  - `make build` (CGO enabled by default in the Makefile’s main build)
355
356Without the native tag, a stub backend is used: you can still run CLI flows and see logs, but no native window is displayed.
357
358## Media (GStreamer) & Hardware Acceleration
359
360WebKitGTK uses GStreamer for media playback. Dumber includes automatic hardware video acceleration support that detects your GPU and configures the appropriate drivers.
361
362**Hardware Acceleration Features:**
363- Automatic GPU detection (AMD, NVIDIA, Intel)
364- VA-API and VDPAU driver configuration
365- Support for H.264, HEVC, VP9, and AV1 codecs
366- Significantly reduced CPU usage during video streaming
367
368**Required packages:**
369- Arch Linux:
370  - `sudo pacman -S gst-plugins-base gst-plugins-good gst-plugins-bad gst-plugins-ugly gst-libav gst-plugin-pipewire pipewire pipewire-pulse`
371  - Hardware accel: `gstreamer-vaapi mesa` (AMD), `libva-nvidia-driver` (NVIDIA), `libva-intel-driver intel-media-driver` (Intel)
372- Debian/Ubuntu:
373  - `sudo apt install gstreamer1.0-tools gstreamer1.0-plugins-base gstreamer1.0-plugins-good gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly gstreamer1.0-libav gstreamer1.0-pipewire`
374  - Hardware accel: `gstreamer1.0-vaapi va-driver-all` (covers most GPUs)
375
376## Theme and Runtime Updates
377- The homepage and pages respect your system’s light/dark preference.
378- The app updates color‑scheme live when your GTK theme changes (no relaunch needed).
379
380## Project Structure
381- `main.go`: Entry point with CLI/GUI routing
382- `internal/app/cli`: CLI application logic and Cobra commands
383- `internal/app/browser`: Browser application logic and WebKit integration
384- `internal/cli`: Cobra commands (`browse`, `dmenu`, `version`)
385- `internal/config`: Viper‑backed config, XDG helpers, defaults
386- `internal/db`: SQLite schema init and sqlc‑generated queries
387- `internal/logging`: Structured logging system with file rotation
388- `services`: Application services (parser/history/config/browser)
389- `pkg/webkit`: WebKit2GTK bindings (CGO and stub implementations)
390- `pkg/clipboard`: Cross-platform clipboard operations
391- `frontend`: TypeScript homepage UI bundled into the binary
392
393## Security & Privacy
394- History and zoom settings are stored locally in SQLite under XDG state.
395- The `tmp/` directory is ignored by Git and kept out of history.
396
397## Roadmap
398- ✅ WebKitGTK 6 (GTK4) migration (GPU/Vulkan path complete)
399- ✅ GPU rendering (Vulkan via GTK4 renderer) with graceful CPU fallback
400- ✅ Zellij-inspired pane management with binary tree layout and keyboard-driven workflow
401- 🚧 UBlock-based content filtering (early stage - network blocking works, cosmetic filtering needs work)
402- Full Vim-style motion and keyboard navigation across pages and UI
403- Tab management system (browser tabs in addition to panes)
404- Performance work: faster startup, lower memory, snappier UI
405- Other shiny things I'm not yet aware of
406
407## License
408This project is licensed under the MIT License. See `LICENSE` for details.