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+L** | Open Omnibox | URL/search input with history |
45| **Ctrl+F** | Find in Page | Search text within current page |
46| **Ctrl+=** | Zoom In | Firefox-compatible zoom levels |
47| **Ctrl++** | Zoom In | Alternative plus key |
48| **Ctrl+-** | Zoom Out | Works across keyboard layouts |
49| **Ctrl+0** | Reset Zoom | Return to 100% zoom |
50| **Ctrl+Shift+C** | Copy URL | Copy current URL to clipboard with toast |
51| **Ctrl+Shift+P** | Print Page | Open native print dialog |
52| **Ctrl+R** / **F5** | Reload Page | Refresh current page |
53| **Ctrl+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+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### Configuration
176The pane system is fully configurable via `config.json`:
177```json
178"workspace": {
179  "enable_zellij_controls": true,
180  "pane_mode": {
181    "activation_shortcut": "ctrl+p",
182    "timeout_ms": 3000,
183    "action_bindings": {
184      "arrowright": "split-right",
185      "r": "split-right",
186      "x": "close-pane",
187      // ... full key mappings
188    }
189  },
190  "popups": {
191    "placement": "right",
192    "open_in_new_pane": true
193  },
194  "styling": {
195    "border_width": 2,
196    "border_color": "@theme_selected_bg_color",
197    "transition_duration": 120
198  }
199}
200```
201
202## Configuration
203
204Dumber follows the XDG Base Directory spec:
205- Config: `~/.config/dumber/config.json`
206- Data:   `~/.local/share/dumber`
207- State:  `~/.local/state/dumber` (default DB lives here)
208
209A default `config.json` is created on first run. Config changes are watched and applied at runtime when possible.
210
211### How Configuration Works
212
213- **Config file**: `~/.config/dumber/config.json` (supports `.yaml` and `.toml` too)
214- **Format**: JSON/YAML/TOML - auto-detected
215- **JSON Schema**: Auto-generated for IDE autocompletion and validation
216- **Live reload**: Changes are automatically applied without restarting
217- **Environment variables**: Override any setting with `DUMB_BROWSER_*` or `DUMBER_*` prefix
218- **Default values**: Sensible defaults for all settings
219
220### Quick Examples
221
222```json
223{
224  "default_zoom": 1.2,
225  "rendering_mode": "gpu",
226  "search_shortcuts": {
227    "g": { "url": "https://google.com/search?q=%s", "description": "Google" }
228  },
229  "workspace": {
230    "enable_zellij_controls": true,
231    "popups": { "behavior": "split" }
232  }
233}
234```
235
236Environment variable override:
237```bash
238DUMBER_RENDERING_MODE=cpu dumber
239DUMB_BROWSER_LOGGING_LEVEL=debug dumber
240```
241
242**📖 Complete documentation**: See [docs/CONFIG.md](docs/CONFIG.md) for all available settings, defaults, and valid values.
243
244
245## Building With WebKitGTK 6 (GTK4)
246- The GUI requires building with `-tags=webkit_cgo` and CGO enabled.
247- Ensure WebKitGTK 6 and GTK4 dev headers are installed (see prerequisites).
248- Make targets handle both frontend and Go build steps:
249  - `make build-gui` (CGO enabled)
250  - `make build` (CGO enabled by default in the Makefile’s main build)
251
252Without the native tag, a stub backend is used: you can still run CLI flows and see logs, but no native window is displayed.
253
254## Media (GStreamer) & Hardware Acceleration
255
256WebKitGTK uses GStreamer for media playback. Dumber includes automatic hardware video acceleration support that detects your GPU and configures the appropriate drivers.
257
258**Hardware Acceleration Features:**
259- Automatic GPU detection (AMD, NVIDIA, Intel)
260- VA-API and VDPAU driver configuration
261- Support for H.264, HEVC, VP9, and AV1 codecs
262- Significantly reduced CPU usage during video streaming
263
264**Required packages:**
265- Arch Linux:
266  - `sudo pacman -S gst-plugins-base gst-plugins-good gst-plugins-bad gst-plugins-ugly gst-libav gst-plugin-pipewire pipewire pipewire-pulse`
267  - Hardware accel: `gstreamer-vaapi mesa` (AMD), `libva-nvidia-driver` (NVIDIA), `libva-intel-driver intel-media-driver` (Intel)
268- Debian/Ubuntu:
269  - `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`
270  - Hardware accel: `gstreamer1.0-vaapi va-driver-all` (covers most GPUs)
271
272## Contribute
273I will gladly accept contributions, especially related to UI/UX enhancements. Feel free to open an issue and let's discuss it!
274
275## Security & Privacy
276- History and zoom settings are stored locally in SQLite under XDG state.
277- The `tmp/` directory is ignored by Git and kept out of history.
278
279## Roadmap
280- ✅ WebKitGTK 6 (GTK4) migration (GPU/Vulkan path complete)
281- ✅ GPU rendering (Vulkan via GTK4 renderer) with graceful CPU fallback
282- ✅ Zellij-inspired pane management with binary tree layout and keyboard-driven workflow
283- 🚧 UBlock-based content filtering (early stage - network blocking works, cosmetic filtering needs work)
284- Full Vim-style motion and keyboard navigation across pages and UI
285- Tab management system (browser tabs in addition to panes)
286- Performance work: faster startup, lower memory, snappier UI
287- Other shiny things I'm not yet aware of
288
289## License
290This project is licensed under the MIT License. See `LICENSE` for details.