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