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
7
8https://github.com/user-attachments/assets/394f5f7e-a475-42da-b483-5a58b2ea2f51
9
10
11
12A dumb browser that works like your favorite terminal multiplexer.
13
14## Features
15- **Wayland native**: No X11/XWayland dependency, works with Sway, Hyprland, River, Niri, etc.
16- **Tabs and workspaces**: Each tab holds a workspace with split or stacked panes.
17- **Keyboard-driven**: Complete keyboard workflow inspired by Zellij.
18- **Smart popup handling**: OAuth flows, window.open(), and popup deduplication for tiling WMs.
19- **GPU rendering**: Hardware video acceleration with automatic VA-API/VDPAU detection.
20- **Built-in ad blocking**: UBlock-based network filtering (cosmetic filtering in progress).
21- **Launcher integration**: dmenu-style with rofi/fuzzel support, shows favicons and history.
22- **Search shortcuts**: Quick search via aliases (e.g., `g:golang` for Google).
23- **Customizable themes**: Light and dark palettes with semantic color tokens.
24- **Persistent storage**: SQLite for history, zoom levels, and settings.
25- **Live configuration**: Single config file with hot reload when possible.
26
27## Status
28Early development with regular releases. Core features work well for daily use but expect some rough edges.
29
30## Controls & Shortcuts
31
32### Keyboard Shortcuts
33
34#### Browser Controls
35| Shortcut | Action | Notes |
36|----------|--------|-------|
37| **F12** | Open Developer Tools | WebKit inspector |
38| **Ctrl+L** | Open Omnibox | URL/search input with history |
39| **Ctrl+F** | Find in Page | Search text within current page |
40| **Ctrl+=** | Zoom In | Firefox-compatible zoom levels |
41| **Ctrl++** | Zoom In | Alternative plus key |
42| **Ctrl+-** | Zoom Out | Works across keyboard layouts |
43| **Ctrl+0** | Reset Zoom | Return to 100% zoom |
44| **Ctrl+Shift+C** | Copy URL | Copy current URL to clipboard with toast |
45| **Ctrl+Shift+P** | Print Page | Open native print dialog |
46| **Ctrl+R** / **F5** | Reload Page | Refresh current page |
47| **Ctrl+Shift+R** | Hard Reload | Refresh ignoring cache |
48| **Ctrl+←** / **Ctrl+→** | Navigate Back/Forward | Browser history navigation |
49
50#### Tab Management
51| Shortcut | Action | Notes |
52|----------|--------|-------|
53| **Ctrl+T** | Enter Tab Mode | Modal mode for tab operations |
54| **Ctrl+Tab** | Next Tab | Quick tab switching |
55| **Ctrl+Shift+Tab** | Previous Tab | Quick tab switching |
56| **Ctrl+W** | Close Tab | Close current tab |
57| **N** / **C** (in tab mode) | New Tab | Create new tab |
58| **X** (in tab mode) | Close Tab | Close current tab |
59| **L** / **Tab** (in tab mode) | Next Tab | Navigate to next tab |
60| **H** / **Shift+Tab** (in tab mode) | Previous Tab | Navigate to previous tab |
61| **R** (in tab mode) | Rename Tab | Rename current tab |
62| **Escape** (in tab mode) | Exit Tab Mode | Return to normal navigation |
63
64#### Pane Management
65| Shortcut | Action | Notes |
66|----------|--------|-------|
67| **Ctrl+P** | Enter Pane Mode | Modal mode for pane operations |
68| **→** / **R** (in pane mode) | Split Right | Create new pane to the right |
69| **←** / **L** (in pane mode) | Split Left | Create new pane to the left |
70| **↑** / **U** (in pane mode) | Split Up | Create new pane above |
71| **↓** / **D** (in pane mode) | Split Down | Create new pane below |
72| **S** (in pane mode) | Stack Pane | Create stacked pane (Zellij-style) |
73| **X** (in pane mode) | Close Pane | Close current pane |
74| **Enter** (in pane mode) | Confirm Action | Confirm pane operation |
75| **Escape** (in pane mode) | Exit Pane Mode | Return to normal navigation |
76| **Alt+Arrow Keys** | Navigate Panes | Move focus between panes |
77| **Alt+Up/Down** | Navigate Stack | Navigate between stacked panes |
78
79### Mouse Controls
80| Action | Result | Notes |
81|--------|---------|-------|
82| **Ctrl+Scroll Up** | Zoom In | Smooth zoom control |
83| **Ctrl+Scroll Down** | Zoom Out | Smooth zoom control |
84| **Mouse Button 8** | Navigate Back | Side button (back) |
85| **Mouse Button 9** | Navigate Forward | Side button (forward) |
86| **Two-finger Swipe** | Back/Forward | When supported by touchpad |
87
88### Omnibox/Find Mode (when active)
89| Shortcut | Action | Notes |
90|----------|--------|-------|
91| **Escape** | Close/Clear | Clear input if text present, close if empty |
92| **Enter** | Execute/Navigate | Navigate to URL or jump to match |
93| **Shift+Enter** | Previous Match | Find mode: go to previous match |
94| **Alt+Enter** | Center Match | Find mode: center on match, keep open |
95| **Tab** | Toggle View | Omnibox mode: switch between history and favorites |
96| **Space** | Toggle Favorite | Omnibox mode: favorite/unfavorite selected item |
97| **Ctrl+1-9, 0** | Quick Navigate | Jump to result by number (1-10) |
98| **↑/↓ Arrow** | Navigate Results | Browse suggestions/matches |
99
100All zoom changes are automatically persisted per-domain and restored on next visit.
101
102## Quick Start
103
104**Option 1: Use Pre-built Binaries (Recommended)**
105
106Download the latest release from the [releases page](https://github.com/bnema/dumber/releases):
107```bash
108wget https://github.com/bnema/dumber/releases/latest/download/dumber_<version>_linux_x86_64.tar.gz
109tar -xzf dumber_<version>_linux_x86_64.tar.gz
110sudo install -m 755 dumber /usr/local/bin/
111```
112
113Then install runtime dependencies (see [Install](#install) section for details).
114
115**Option 2: Build From Source**
116
117Prerequisites:
118- Go 1.25+
119- Node.js 20+ and npm (for building the embedded TypeScript frontend)
120- For GUI build: WebKitGTK 6 and GTK4 dev packages (examples)
121  - Debian/Ubuntu: `libwebkitgtk-6.0-dev libgtk-4-dev build-essential`
122  - Arch: `webkitgtk-6.0 gtk4 base-devel`
123
124Build options:
125- GUI (default, recommended):
126  - `make build`          # builds frontend + Go with `-tags=webkit_cgo`
127  - Run: `./dist/dumber`  # to see all available commands.
128- CLI‑only (no GUI, CGO disabled):
129  - `make build-no-gui`
130  - Run: `./dist/dumber-no-gui version`
131
132Development:
133- `make dev` runs `go run .` (non‑CGO; GUI stubs log to console)
134- `make test` runs tests; `make lint` runs golangci‑lint
135
136## Install
137
138### Pre-built Binaries (Recommended)
139
140Pre-built binaries are available for Linux (x86_64/amd64) in the [releases page](https://github.com/bnema/dumber/releases). These include all frontend assets and are ready to use:
141
142```bash
143# Download and install latest release
144wget https://github.com/bnema/dumber/releases/latest/download/dumber_<version>_linux_x86_64.tar.gz
145tar -xzf dumber_<version>_linux_x86_64.tar.gz
146sudo install -m 755 dumber /usr/local/bin/
147```
148
149Replace `<version>` with the desired version (e.g., `0.14.1`), or use the direct link from the releases page.
150
151**Dependencies** (required for both pre-built binaries and source builds):
152
153**Arch Linux:**
154```bash
155# Core WebKitGTK 6.0 and GTK4
156sudo pacman -S webkitgtk-6.0 gtk4
157
158# GStreamer for media playback
159sudo pacman -S gst-plugins-base gst-plugins-good gst-plugins-bad gst-plugins-ugly gst-libav gst-plugin-pipewire pipewire pipewire-pulse
160
161# Hardware acceleration (choose based on your GPU)
162# AMD: sudo pacman -S gstreamer-vaapi mesa
163# NVIDIA: sudo pacman -S gstreamer-vaapi libva-nvidia-driver
164# Intel: sudo pacman -S gstreamer-vaapi libva-intel-driver intel-media-driver
165```
166
167**Debian/Ubuntu:**
168```bash
169# Core WebKitGTK and GTK4
170sudo apt install libwebkitgtk-6.0-4 libgtk-4-1
171
172# GStreamer for media playback
173sudo 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
174
175# Hardware acceleration
176sudo apt install gstreamer1.0-vaapi va-driver-all
177```
178
179### Build From Source
180
181**Note**: `go install` will not work for this project because the frontend assets must be built first and embedded into the binary.
182
183**Prerequisites:**
184- Go 1.25+
185- Node.js 20+ and npm (for building the embedded TypeScript frontend)
186- WebKitGTK 6 and GTK4 dev packages:
187  - Debian/Ubuntu: `libwebkitgtk-6.0-dev libgtk-4-dev build-essential`
188  - Arch: `webkitgtk-6.0 gtk4 base-devel`
189
190**Build options:**
191- GUI build (default, recommended):
192  - Clone the repo and run `make build` (builds frontend first, then Go with GUI support)
193  - The resulting `./dist/dumber` binary includes the native GUI window
194- CLI‑only (no native window):
195  - Clone the repo and run `make build-no-gui`
196  - The resulting `./dist/dumber-no-gui` binary runs CLI flows with GUI code stubbed
197
198## Usage
199- Open a URL or search:
200  - `dumber browse https://example.com`
201  - `dumber browse example.com`        # scheme auto‑added
202  - `dumber browse dumb://home`        # built-in homepage with stats
203  - `dumber browse g:golang`           # Google search via shortcut
204- Show version information:
205  - `dumber version`                   # display version, commit, and build date
206- Launcher integration (dmenu‑style examples):
207  - rofi:   `dumber dmenu | rofi -dmenu -p "🔍 " | dumber dmenu --select`
208  - fuzzel: `dumber dmenu | fuzzel --dmenu -p "🔍 " | dumber dmenu --select`
209- Manage browsing history:
210  - `dumber history`                  # list recent history (default: 20 entries)
211  - `dumber history list -n 50`       # list 50 recent entries
212  - `dumber history search golang`    # search history for "golang"
213  - `dumber history stats`            # show history statistics
214  - `dumber history clear`            # clear all history (with confirmation)
215  - `dumber history clear --force`    # clear all history (no confirmation)
216- Clean up data and cache:
217  - `dumber purge`                        # purge all data (with confirmation)
218  - `dumber purge --force`                # purge all data (no confirmation)
219  - `dumber purge -d -H -c`               # purge database and both caches
220  - `dumber purge --browser-data`         # purge WebKit data (cookies, etc.)
221- Manage logs:
222  - `dumber logs list`                    # list available log files
223  - `dumber logs tail`                    # tail current log file
224  - `dumber logs clean`                   # clean up old log files
225
226### Dmenu mode invocation
227You can invoke dmenu mode in two ways:
228- Subcommand (recommended): `dumber dmenu` … and `dumber dmenu --select`
229- Root flag (generate options only): `dumber --dmenu`
230
231Note: The root flag path only generates options; for processing a selection (`--select`), use the `dmenu` subcommand as the receiving command.
232
233In GUI mode the app serves an embedded homepage via `dumb://homepage`, and frontend assets under `dumb://app/...`.
234
235## Tab Management
236
237Each tab holds its own workspace. Each workspace can contain multiple panes (split or stacked). Switch between tabs to switch between independent workspaces.
238
239### How it Works
2401. **Enter Tab Mode**: Press `Ctrl+T` to enter tab mode (modal interface with timeout)
2412. **Create/Close Tabs**: Use keyboard shortcuts:
242   - `N` or `C` - New tab
243   - `X` - Close current tab
244   - `R` - Rename tab
2453. **Navigate**: Use `Ctrl+Tab` / `Ctrl+Shift+Tab` for quick tab switching, or `L`/`H` in tab mode
2464. **Exit**: Press `Escape` to exit tab mode or wait for timeout
247
248Tab mode provides visual feedback with an orange border indicator.
249
250## Pane Management
251
252Split your browser window into multiple panes, each running independent web sessions.
253
254### How it Works
2551. **Enter Pane Mode**: Press `Ctrl+P` to enter pane mode (modal interface with timeout)
2562. **Split or Stack Panes**: Use arrow keys or letter shortcuts:
257   - `→` or `R` - Split right
258   - `←` or `L` - Split left
259   - `↑` or `U` - Split up
260   - `↓` or `D` - Split down
261   - `S` - Stack panes (Zellij-style, shows title bars for collapsed panes)
2623. **Navigate**: Use `Alt+Arrow Keys` to move focus between split panes, or `Alt+Up/Down` to navigate within stacked panes
2634. **Close**: Press `X` in pane mode to close the current pane
264
265## Configuration
266
267Configuration file: `~/.config/dumber/config.toml` (supports TOML, JSON, YAML)
268
269A default config is created on first run. Changes are applied automatically (hot reload). Override any setting with `DUMB_BROWSER_*` or `DUMBER_*` environment variables.
270
271**Full documentation**: [docs/CONFIG.md](docs/CONFIG.md) - Complete reference for all settings, workspace controls, shortcuts, styling, and more.
272
273
274## Building With WebKitGTK 6 (GTK4)
275- The GUI requires building with `-tags=webkit_cgo` and CGO enabled.
276- Ensure WebKitGTK 6 and GTK4 dev headers are installed (see prerequisites).
277- Make targets handle both frontend and Go build steps:
278  - `make build-gui` (CGO enabled)
279  - `make build` (CGO enabled by default in the Makefile’s main build)
280
281Without the native tag, a stub backend is used: you can still run CLI flows and see logs, but no native window is displayed.
282
283## Media (GStreamer) & Hardware Acceleration
284
285WebKitGTK uses GStreamer for media playback. Dumber includes automatic hardware video acceleration support that detects your GPU and configures the appropriate drivers.
286
287**Hardware Acceleration Features:**
288- Automatic GPU detection (AMD, NVIDIA, Intel)
289- VA-API and VDPAU driver configuration
290- Support for H.264, HEVC, VP9, and AV1 codecs
291- Significantly reduced CPU usage during video streaming
292
293**Required packages:**
294- Arch Linux:
295  - `sudo pacman -S gst-plugins-base gst-plugins-good gst-plugins-bad gst-plugins-ugly gst-libav gst-plugin-pipewire pipewire pipewire-pulse`
296  - Hardware accel: `gstreamer-vaapi mesa` (AMD), `libva-nvidia-driver` (NVIDIA), `libva-intel-driver intel-media-driver` (Intel)
297- Debian/Ubuntu:
298  - `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`
299  - Hardware accel: `gstreamer1.0-vaapi va-driver-all` (covers most GPUs)
300
301## Contribute
302I will gladly accept contributions, especially related to UI/UX enhancements. Feel free to open an issue and let's discuss it!
303
304## Security & Privacy
305- History and zoom settings are stored locally in SQLite under XDG state.
306- The `tmp/` directory is ignored by Git and kept out of history.
307
308## Roadmap
309- ✅ WebKitGTK 6 (GTK4) migration (GPU/Vulkan path complete)
310- ✅ GPU rendering (Vulkan via GTK4 renderer) with graceful CPU fallback
311- ✅ Modal pane management with binary tree layout and keyboard-driven workflow
312- ✅ Tab management system with modal controls
313- 🚧 UBlock-based content filtering (early stage - network blocking works, cosmetic filtering needs work)
314- Full Vim-style motion and keyboard navigation across pages and UI
315- Performance work: faster startup, lower memory, snappier UI
316- Other shiny things I'm not yet aware of
317
318## License
319This project is licensed under the MIT License. See `LICENSE` for details.