docs(readme): refresh project overview

commit: d7f16ad420136acb31c9365a24233ea896172404
author: brice · 4mo ago · 2026-05-28 03:32 UTC
parent: 3c51b4f
signature: GPG VerifiedCD88F9E564E0102646FB6077A1A07C7C7C3E349D · arch-gpg Verified for the committer email

1 file · +133 -65

M README.md +133 -65


@@ -2,50 +2,81 @@
2	2
3	3		[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Go Report Card](https://goreportcard.com/badge/github.com/bnema/dumber)](https://goreportcard.com/report/github.com/bnema/dumber)
4	4
5		-	A TTY-inspired web browser multiplexer for tiling window managers.
	5	+	Dumber is a keyboard-driven web browser for Wayland compositors, built around panes, workspaces, and modal controls.
6	6
7		-	- Website: [dumber.bnema.dev](https://dumber.bnema.dev)
8		-	- Documentation: [dumber.bnema.dev/docs](https://dumber.bnema.dev/docs)
	7	+	The page is the interface. There are no permanent tab bars, bookmark bars, or browser chrome around the content. Navigation and browser commands appear when you ask for them with the keyboard.
9	8
10		-	---
	9	+	Tabs contain workspaces. Workspaces contain panes. Panes can be split, stacked, moved, resized, and closed from the keyboard.
11	10
12		-	## What is Dumber?
	11	+	The layout model is inspired by terminal multiplexers such as Zellij and tmux, but applied to browsing on tiling Wayland compositors.
13	12
14		-	Dumber is a web browser that works like your terminal multiplexer. Tabs hold workspaces. Workspaces hold panes. Panes split and stack like Zellij.
	13	+	[Website](https://dumber.bnema.dev) · [Documentation](https://dumber.bnema.dev/docs) · [Keybindings](https://dumber.bnema.dev/docs/reference/keybindings)
	14	+
	15	+	## Demo
15	16
16	17		https://github.com/user-attachments/assets/232822af-08e4-4a74-9416-87f79c96b118
17	18
	19	+	The demo shows split panes, stacked panes, modal navigation, and workspace switching.
	20	+
	21	+	## Overview
	22	+
	23	+	Dumber uses three layout levels:
	24	+
	25	+	- Tabs group separate browser contexts.
	26	+	- Workspaces hold a layout of panes.
	27	+	- Panes display web pages and can be split, stacked, moved, resized, or closed.
	28	+
	29	+	Most browser-management actions are exposed through modal keybindings. Enter a mode, run one or more commands, then leave the mode. The default modes cover pane management, tabs, resizing, and session commands.
	30	+
	31	+	The browser chrome stays out of the way by default. Open the omnibox when you want to navigate; otherwise the pane is just the page or web app you are using. This makes Dumber work well as a side pane next to an editor, terminal, or another desktop application.
	32	+
	33	+	## Features
18	34
	35	+	### Content-first browsing
19	36
20		-	Features:
21		-	- Zellij-style panes with modal keyboard navigation
22		-	- Floating workspace pane with profile shortcuts
23		-	- Wayland native (Sway, Hyprland, River, Niri)
24		-	- Session resurrection with auto-snapshots
25		-	- Built-in ad blocking (uBlock-based)
26		-	- GPU accelerated video (VA-API/VDPAU)
27		-	- Launcher integration (rofi/fuzzel/dmenu)
28		-	- Search bangs (!g, !gi, !ddg)
29		-	- Single config.toml with hot reload
	37	+	- No permanent tab bar, bookmark bar, or toolbar around the page
	38	+	- Omnibox and browser commands appear through keyboard shortcuts
	39	+	- Web apps can feel closer to desktop applications because the browser frame is not always visible
	40	+	- Works well as a narrow side pane next to an editor, terminal, or other application
30	41
31		-	## Documentation
	42	+	### Pane-based browsing
32	43
33		-	Full documentation is available at [dumber.bnema.dev](https://dumber.bnema.dev)
	44	+	- Split panes horizontally or vertically
	45	+	- Stack panes in the same area
	46	+	- Move, resize, and close panes with modal keybindings
	47	+	- Keep related pages together in a workspace
34	48
35		-	- [Documentation](https://dumber.bnema.dev/docs) - Installation, configuration, CLI reference
36		-	- [Keybindings](https://dumber.bnema.dev/docs/reference/keybindings) - Keyboard shortcuts
	49	+	### Keyboard workflow
37	50
38		-	## Quick Start
	51	+	- Pane, tab, resize, and session modes
	52	+	- Vim/Zellij-style navigation patterns
	53	+	- Search bangs such as `!g`, `!gi`, and `!ddg`
	54	+	- Launcher integration for `rofi`, `fuzzel`, and `dmenu`
	55	+
	56	+	### Desktop integration
	57	+
	58	+	- Wayland-native on Sway, Hyprland, River, Niri, and similar compositors
	59	+	- Floating pane with configurable profile shortcuts
	60	+	- Single `config.toml` file with hot reload
	61	+
	62	+	### Browser features
	63	+
	64	+	- Chromium Embedded Framework backend by default
	65	+	- WebKit backend available as a fallback
	66	+	- Built-in ad blocking based on uBlock filter lists
	67	+	- GPU-accelerated video through VA-API/VDPAU where supported
	68	+	- Snapshot-based restoration of tabs, workspaces, and pane layout
	69	+
	70	+	## Installation
	71	+
	72	+	### Install script
39	73
40	74		```bash
41		-	# Install
42	75		curl -fsSL https://dumber.bnema.dev/install \| sh
43		-
44		-	# Launch
45	76		dumber browse
46	77		```
47	78
48		-	### Arch Linux (AUR)
	79	+	### Arch Linux
49	80
50	81		```bash
51	82		yay -S dumber-browser-bin # Pre-built binary

@@ -60,25 +91,49 @@ flatpak install --user dumber.flatpak
60	91		flatpak run dev.bnema.Dumber browse
61	92		```
62	93
63		-	### Dependencies
	94	+	For dependencies, distribution notes, and troubleshooting, see the [installation documentation](https://dumber.bnema.dev/docs).
64	95
65		-	Arch Linux:
	96	+	## Keyboard modes
66	97
67		-	```bash
68		-	sudo pacman -S cef webkitgtk-6.0 gtk4 gst-plugins-base gst-plugins-good gst-plugins-bad gst-plugin-va
69		-	```
	98	+	Dumber uses modal keybindings for browser management.
70	99
71		-	Debian/Ubuntu:
	100	+	\| Mode \| Default key \| Used for \|
	101	+	\|------\|-------------\|----------\|
	102	+	\| Pane \| `Ctrl+P` \| Split, stack, close, and move panes \|
	103	+	\| Tab \| `Ctrl+T` \| Create, close, switch, and rename tabs \|
	104	+	\| Resize \| `Ctrl+N` \| Resize panes with `hjkl` or arrow keys \|
	105	+	\| Session \| `Ctrl+O` \| Snapshot, restore, and browse sessions \|
72	106
73		-	```bash
74		-	sudo apt install libwebkitgtk-6.0-4 libgtk-4-1 gstreamer1.0-plugins-base gstreamer1.0-plugins-good gstreamer1.0-plugins-bad
	107	+	## Floating pane
	108	+
	109	+	The floating pane is a temporary browser pane that can be toggled without changing the main workspace layout.
	110	+
	111	+	- `Alt+F` toggles the floating pane and preserves its state while hidden.
	112	+	- `Ctrl+W` closes the active pane; if the floating pane is active, it is fully released for a fresh next open.
	113	+	- Profile shortcuts such as `Alt+G` are optional and configured under `workspace.floating_pane.profiles`.
	114	+	- Some `Alt+<key>` bindings may conflict with WebKit shortcuts or desktop-level handlers.
	115	+
	116	+	See the [floating pane reference](https://dumber.bnema.dev/docs/reference/floating-pane) for setup and behavior details.
	117	+
	118	+	## Configuration
	119	+
	120	+	Dumber is configured with a single TOML file.
	121	+
	122	+	```toml
	123	+	[engine]
	124	+	type = "cef"
	125	+
	126	+	[workspace.floating_pane]
	127	+	enabled = true
75	128		```
76	129
77		-	> ⚠️ Ubuntu 24.04 ships GLib 2.80, but Dumber requires GLib 2.84+. Use Arch, Fedora 41+, or the Flatpak.
	130	+	The config reloads while Dumber is running. See the [configuration documentation](https://dumber.bnema.dev/docs) for all options.
	131	+
	132	+	## Browser engine
78	133
79		-	### Browser engine
	134	+	Dumber uses Chromium Embedded Framework by default. WebKitGTK is available as a fallback backend.
80	135
81		-	Dumber uses the Chromium Embedded Framework engine by default. On Arch, install the CEF runtime with:
	136	+	On Arch Linux, install the CEF runtime with:
82	137
83	138		```bash
84	139		sudo pacman -S cef

@@ -86,7 +141,13 @@ sudo pacman -S cef
86	141
87	142		For hardware video decoding, `cef-vaapi` is also available from the AUR as an optional CEF build.
88	143
89		-	CEF runtime precedence is deterministic: `CEF_DIR` wins first, then `engine.cef.cef_dir`, then `/usr/lib/cef`, then `~/.local/share/cef`.
	144	+	CEF runtime lookup order:
	145	+
	146	+	1. `CEF_DIR`
	147	+	2. `engine.cef.cef_dir`
	148	+	3. `/usr/lib/cef`
	149	+	4. `~/.local/share/cef`
	150	+
90	151		Set `engine.cef.cef_dir` in config when `CEF_DIR` is unset:
91	152
92	153		```toml

@@ -100,51 +161,58 @@ Or set the higher-precedence `CEF_DIR` environment variable:
100	161		CEF_DIR=/custom/path dumber browse
101	162		```
102	163
103		-	WebKit remains available as a fallback:
	164	+	WebKit can be selected explicitly:
104	165
105	166		```toml
106	167		[engine]
107	168		type = "webkit"
108	169		```
109	170
	171	+	### Rendering notes
	172	+
110	173		CEF uses Dumber's GPU-first Wayland render stack by default: GDK DMABUF presentation with ANGLE/GSK Vulkan. For driver compatibility, switch to the EGL/OpenGL stack with `engine.cef.render_stack = "egl"`; the default is `"vulkan"`.
111	174
112		-	CEF OSR frame rate adapts to the active Wayland monitor refresh rate when both `engine.cef.adaptive_windowless_frame_rate = true` and `engine.cef.windowless_frame_rate = 0` (the defaults). Adaptive mode is capped by `engine.cef.windowless_frame_rate_max = 240`. Setting `engine.cef.windowless_frame_rate` to a positive value forces a fixed rate instead. This adaptive polling path is Wayland-specific; other platforms fall back to the configured fixed/default CEF behavior.
	175	+	CEF OSR frame rate adapts to the active Wayland monitor refresh rate when both `engine.cef.adaptive_windowless_frame_rate = true` and `engine.cef.windowless_frame_rate = 0` are set, which are the defaults. Adaptive mode is capped by `engine.cef.windowless_frame_rate_max = 240`. Setting `engine.cef.windowless_frame_rate` to a positive value forces a fixed rate instead. This adaptive polling path is Wayland-specific; other platforms fall back to the configured fixed/default CEF behavior.
113	176
114		-	## Keyboard-Driven
	177	+	## Platform notes
115	178
116		-	Four modal modes. Enter a mode, act, escape out. Vim and Zellij users already know this pattern.
	179	+	### Dependencies
117	180
118		-	\| Mode \| Key \| Actions \|
119		-	\|------\|-----\|---------\|
120		-	\| Pane \| `Ctrl+P` \| Split · Stack · Close · Move \|
121		-	\| Tab \| `Ctrl+T` \| New · Close · Switch · Rename \|
122		-	\| Resize \| `Ctrl+N` \| Grow · Shrink · hjkl/arrows \|
123		-	\| Session \| `Ctrl+O` \| Save · Restore · Browse \|
	181	+	Arch Linux:
124	182
125		-	## Floating Pane
	183	+	```bash
	184	+	sudo pacman -S cef webkitgtk-6.0 gtk4 gst-plugins-base gst-plugins-good gst-plugins-bad gst-plugin-va
	185	+	```
126	186
127		-	- `Alt+F` toggles the floating pane and preserves its state while hidden.
128		-	- `Ctrl+W` closes the active pane; if the floating pane is active, it is fully released for a fresh next open.
129		-	- Profile shortcuts like `Alt+G` are optional and configured under `workspace.floating_pane.profiles`.
130		-	- Some `Alt+<key>` bindings may conflict with default WebKit shortcuts or desktop-level handlers.
	187	+	Debian/Ubuntu:
131	188
132		-	See [Floating Pane Reference](https://dumber.bnema.dev/docs/reference/floating-pane) for setup and behavior details.
	189	+	```bash
	190	+	sudo apt install libwebkitgtk-6.0-4 libgtk-4-1 gstreamer1.0-plugins-base gstreamer1.0-plugins-good gstreamer1.0-plugins-bad
	191	+	```
133	192
134		-	## Development
	193	+	> Ubuntu 24.04 ships GLib 2.80, but Dumber requires GLib 2.84+. Use Arch, Fedora 41+, or the Flatpak.
135	194
136		-	Dumber uses pure-Go bindings (no CGO) but requires GTK4/WebKitGTK runtime libraries for the GUI.
	195	+	## Status
137	196
138		-	### Environment
	197	+	Dumber is usable for regular web browsing on Wayland compositors, with the main focus on panes, keyboard control, floating workflows, and desktop integration.
139	198
140		-	Set `ENV=dev` to use `.dev/dumber/` for config/data instead of XDG paths.
	199	+	It is not a drop-in replacement for every mainstream browser workflow. Extension compatibility, engine behavior, and media support depend on the selected backend and system libraries.
141	200
142		-	### Build From Source
	201	+	Bug reports and reproducible Wayland/backend issues are welcome.
	202	+
	203	+	## Development
	204	+
	205	+	Dumber uses pure-Go bindings and requires GTK4/WebKitGTK runtime libraries for the GUI.
	206	+
	207	+	Set `ENV=dev` to use `.dev/dumber/` for config and data instead of XDG paths.
	208	+
	209	+	### Build from source
143	210
144	211		Prerequisites:
	212	+
145	213		- Go 1.25+
146		-	- Node.js 20+ (for frontend assets)
147		-	- WebKitGTK 6.0 and GTK4 dev packages
	214	+	- Node.js 20+ for frontend assets
	215	+	- WebKitGTK 6.0 and GTK4 development packages
148	216
149	217		```bash
150	218		git clone https://github.com/bnema/dumber

@@ -153,12 +221,12 @@ make build
153	221		./dist/dumber browse
154	222		```
155	223
156		-	### Make Targets
	224	+	### Make targets
157	225
158	226		\| Target \| Description \|
159	227		\|--------\|-------------\|
160		-	\| `make build` \| Build frontend + binary \|
161		-	\| `make build-quick` \| Build binary only (skip frontend) \|
	228	+	\| `make build` \| Build frontend and binary \|
	229	+	\| `make build-quick` \| Build binary only, skipping frontend \|
162	230		\| `make dev` \| Run with `go run` \|
163	231		\| `make test` \| Run tests \|
164	232		\| `make lint` \| Run golangci-lint \|

@@ -166,9 +234,9 @@ make build
166	234
167	235		## Contributing
168	236
169		-	We welcome bug fixes, performance/stability improvements, and WebUI/UX enhancements. We're not accepting new feature PRs.
	237	+	Dumber is currently focused on stability, performance, browser-engine behavior, and core UI/UX polish.
170	238
171		-	All PRs must target the `next` branch. We test there first before releasing to `main`.
	239	+	Bug fixes, documentation improvements, packaging fixes, and targeted UX improvements are welcome. Larger feature ideas should start as issues before PRs.
172	240
173	241		See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
174	242


@@ -2,50 +2,81 @@
2			2
3		[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Go Report Card](https://goreportcard.com/badge/github.com/bnema/dumber)](https://goreportcard.com/report/github.com/bnema/dumber)	3		[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Go Report Card](https://goreportcard.com/badge/github.com/bnema/dumber)](https://goreportcard.com/report/github.com/bnema/dumber)
4			4
5	-	A TTY-inspired web browser multiplexer for tiling window managers.	5	+	Dumber is a keyboard-driven web browser for Wayland compositors, built around panes, workspaces, and modal controls.
6			6
7	-	- Website: [dumber.bnema.dev](https://dumber.bnema.dev)	7	+	The page is the interface. There are no permanent tab bars, bookmark bars, or browser chrome around the content. Navigation and browser commands appear when you ask for them with the keyboard.
8	-	- Documentation: [dumber.bnema.dev/docs](https://dumber.bnema.dev/docs)
9			8
10	-	---	9	+	Tabs contain workspaces. Workspaces contain panes. Panes can be split, stacked, moved, resized, and closed from the keyboard.
11			10
12	-	## What is Dumber?	11	+	The layout model is inspired by terminal multiplexers such as Zellij and tmux, but applied to browsing on tiling Wayland compositors.
13			12
14	-	Dumber is a web browser that works like your terminal multiplexer. Tabs hold workspaces. Workspaces hold panes. Panes split and stack like Zellij.	13	+	[Website](https://dumber.bnema.dev) · [Documentation](https://dumber.bnema.dev/docs) · [Keybindings](https://dumber.bnema.dev/docs/reference/keybindings)
			14	+
			15	+	## Demo
15			16
16		https://github.com/user-attachments/assets/232822af-08e4-4a74-9416-87f79c96b118	17		https://github.com/user-attachments/assets/232822af-08e4-4a74-9416-87f79c96b118
17			18
			19	+	The demo shows split panes, stacked panes, modal navigation, and workspace switching.
			20	+
			21	+	## Overview
			22	+
			23	+	Dumber uses three layout levels:
			24	+
			25	+	- Tabs group separate browser contexts.
			26	+	- Workspaces hold a layout of panes.
			27	+	- Panes display web pages and can be split, stacked, moved, resized, or closed.
			28	+
			29	+	Most browser-management actions are exposed through modal keybindings. Enter a mode, run one or more commands, then leave the mode. The default modes cover pane management, tabs, resizing, and session commands.
			30	+
			31	+	The browser chrome stays out of the way by default. Open the omnibox when you want to navigate; otherwise the pane is just the page or web app you are using. This makes Dumber work well as a side pane next to an editor, terminal, or another desktop application.
			32	+
			33	+	## Features
18			34
			35	+	### Content-first browsing
19			36
20	-	Features:	37	+	- No permanent tab bar, bookmark bar, or toolbar around the page
21	-	- Zellij-style panes with modal keyboard navigation	38	+	- Omnibox and browser commands appear through keyboard shortcuts
22	-	- Floating workspace pane with profile shortcuts	39	+	- Web apps can feel closer to desktop applications because the browser frame is not always visible
23	-	- Wayland native (Sway, Hyprland, River, Niri)	40	+	- Works well as a narrow side pane next to an editor, terminal, or other application
24	-	- Session resurrection with auto-snapshots
25	-	- Built-in ad blocking (uBlock-based)
26	-	- GPU accelerated video (VA-API/VDPAU)
27	-	- Launcher integration (rofi/fuzzel/dmenu)
28	-	- Search bangs (!g, !gi, !ddg)
29	-	- Single config.toml with hot reload
30			41
31	-	## Documentation	42	+	### Pane-based browsing
32			43
33	-	Full documentation is available at [dumber.bnema.dev](https://dumber.bnema.dev)	44	+	- Split panes horizontally or vertically
			45	+	- Stack panes in the same area
			46	+	- Move, resize, and close panes with modal keybindings
			47	+	- Keep related pages together in a workspace
34			48
35	-	- [Documentation](https://dumber.bnema.dev/docs) - Installation, configuration, CLI reference	49	+	### Keyboard workflow
36	-	- [Keybindings](https://dumber.bnema.dev/docs/reference/keybindings) - Keyboard shortcuts
37			50
38	-	## Quick Start	51	+	- Pane, tab, resize, and session modes
			52	+	- Vim/Zellij-style navigation patterns
			53	+	- Search bangs such as `!g`, `!gi`, and `!ddg`
			54	+	- Launcher integration for `rofi`, `fuzzel`, and `dmenu`
			55	+
			56	+	### Desktop integration
			57	+
			58	+	- Wayland-native on Sway, Hyprland, River, Niri, and similar compositors
			59	+	- Floating pane with configurable profile shortcuts
			60	+	- Single `config.toml` file with hot reload
			61	+
			62	+	### Browser features
			63	+
			64	+	- Chromium Embedded Framework backend by default
			65	+	- WebKit backend available as a fallback
			66	+	- Built-in ad blocking based on uBlock filter lists
			67	+	- GPU-accelerated video through VA-API/VDPAU where supported
			68	+	- Snapshot-based restoration of tabs, workspaces, and pane layout
			69	+
			70	+	## Installation
			71	+
			72	+	### Install script
39			73
40		```bash	74		```bash
41	-	# Install
42		curl -fsSL https://dumber.bnema.dev/install \| sh	75		curl -fsSL https://dumber.bnema.dev/install \| sh
43	-
44	-	# Launch
45		dumber browse	76		dumber browse
46		```	77		```
47			78
48	-	### Arch Linux (AUR)	79	+	### Arch Linux
49			80
50		```bash	81		```bash
51		yay -S dumber-browser-bin # Pre-built binary	82		yay -S dumber-browser-bin # Pre-built binary

@@ -60,25 +91,49 @@ flatpak install --user dumber.flatpak
60		flatpak run dev.bnema.Dumber browse	91		flatpak run dev.bnema.Dumber browse
61		```	92		```
62			93
63	-	### Dependencies	94	+	For dependencies, distribution notes, and troubleshooting, see the [installation documentation](https://dumber.bnema.dev/docs).
64			95
65	-	Arch Linux:	96	+	## Keyboard modes
66			97
67	-	```bash	98	+	Dumber uses modal keybindings for browser management.
68	-	sudo pacman -S cef webkitgtk-6.0 gtk4 gst-plugins-base gst-plugins-good gst-plugins-bad gst-plugin-va
69	-	```
70			99
71	-	Debian/Ubuntu:	100	+	\| Mode \| Default key \| Used for \|
			101	+	\|------\|-------------\|----------\|
			102	+	\| Pane \| `Ctrl+P` \| Split, stack, close, and move panes \|
			103	+	\| Tab \| `Ctrl+T` \| Create, close, switch, and rename tabs \|
			104	+	\| Resize \| `Ctrl+N` \| Resize panes with `hjkl` or arrow keys \|
			105	+	\| Session \| `Ctrl+O` \| Snapshot, restore, and browse sessions \|
72			106
73	-	```bash	107	+	## Floating pane
74	-	sudo apt install libwebkitgtk-6.0-4 libgtk-4-1 gstreamer1.0-plugins-base gstreamer1.0-plugins-good gstreamer1.0-plugins-bad	108	+
			109	+	The floating pane is a temporary browser pane that can be toggled without changing the main workspace layout.
			110	+
			111	+	- `Alt+F` toggles the floating pane and preserves its state while hidden.
			112	+	- `Ctrl+W` closes the active pane; if the floating pane is active, it is fully released for a fresh next open.
			113	+	- Profile shortcuts such as `Alt+G` are optional and configured under `workspace.floating_pane.profiles`.
			114	+	- Some `Alt+<key>` bindings may conflict with WebKit shortcuts or desktop-level handlers.
			115	+
			116	+	See the [floating pane reference](https://dumber.bnema.dev/docs/reference/floating-pane) for setup and behavior details.
			117	+
			118	+	## Configuration
			119	+
			120	+	Dumber is configured with a single TOML file.
			121	+
			122	+	```toml
			123	+	[engine]
			124	+	type = "cef"
			125	+
			126	+	[workspace.floating_pane]
			127	+	enabled = true
75		```	128		```
76			129
77	-	> ⚠️ Ubuntu 24.04 ships GLib 2.80, but Dumber requires GLib 2.84+. Use Arch, Fedora 41+, or the Flatpak.	130	+	The config reloads while Dumber is running. See the [configuration documentation](https://dumber.bnema.dev/docs) for all options.
			131	+
			132	+	## Browser engine
78			133
79	-	### Browser engine	134	+	Dumber uses Chromium Embedded Framework by default. WebKitGTK is available as a fallback backend.
80			135
81	-	Dumber uses the Chromium Embedded Framework engine by default. On Arch, install the CEF runtime with:	136	+	On Arch Linux, install the CEF runtime with:
82			137
83		```bash	138		```bash
84		sudo pacman -S cef	139		sudo pacman -S cef

@@ -86,7 +141,13 @@ sudo pacman -S cef
86			141
87		For hardware video decoding, `cef-vaapi` is also available from the AUR as an optional CEF build.	142		For hardware video decoding, `cef-vaapi` is also available from the AUR as an optional CEF build.
88			143
89	-	CEF runtime precedence is deterministic: `CEF_DIR` wins first, then `engine.cef.cef_dir`, then `/usr/lib/cef`, then `~/.local/share/cef`.	144	+	CEF runtime lookup order:
			145	+
			146	+	1. `CEF_DIR`
			147	+	2. `engine.cef.cef_dir`
			148	+	3. `/usr/lib/cef`
			149	+	4. `~/.local/share/cef`
			150	+
90		Set `engine.cef.cef_dir` in config when `CEF_DIR` is unset:	151		Set `engine.cef.cef_dir` in config when `CEF_DIR` is unset:
91			152
92		```toml	153		```toml

@@ -100,51 +161,58 @@ Or set the higher-precedence `CEF_DIR` environment variable:
100		CEF_DIR=/custom/path dumber browse	161		CEF_DIR=/custom/path dumber browse
101		```	162		```
102			163
103	-	WebKit remains available as a fallback:	164	+	WebKit can be selected explicitly:
104			165
105		```toml	166		```toml
106		[engine]	167		[engine]
107		type = "webkit"	168		type = "webkit"
108		```	169		```
109			170
			171	+	### Rendering notes
			172	+
110		CEF uses Dumber's GPU-first Wayland render stack by default: GDK DMABUF presentation with ANGLE/GSK Vulkan. For driver compatibility, switch to the EGL/OpenGL stack with `engine.cef.render_stack = "egl"`; the default is `"vulkan"`.	173		CEF uses Dumber's GPU-first Wayland render stack by default: GDK DMABUF presentation with ANGLE/GSK Vulkan. For driver compatibility, switch to the EGL/OpenGL stack with `engine.cef.render_stack = "egl"`; the default is `"vulkan"`.
111			174
112	-	CEF OSR frame rate adapts to the active Wayland monitor refresh rate when both `engine.cef.adaptive_windowless_frame_rate = true` and `engine.cef.windowless_frame_rate = 0` (the defaults). Adaptive mode is capped by `engine.cef.windowless_frame_rate_max = 240`. Setting `engine.cef.windowless_frame_rate` to a positive value forces a fixed rate instead. This adaptive polling path is Wayland-specific; other platforms fall back to the configured fixed/default CEF behavior.	175	+	CEF OSR frame rate adapts to the active Wayland monitor refresh rate when both `engine.cef.adaptive_windowless_frame_rate = true` and `engine.cef.windowless_frame_rate = 0` are set, which are the defaults. Adaptive mode is capped by `engine.cef.windowless_frame_rate_max = 240`. Setting `engine.cef.windowless_frame_rate` to a positive value forces a fixed rate instead. This adaptive polling path is Wayland-specific; other platforms fall back to the configured fixed/default CEF behavior.
113			176
114	-	## Keyboard-Driven	177	+	## Platform notes
115			178
116	-	Four modal modes. Enter a mode, act, escape out. Vim and Zellij users already know this pattern.	179	+	### Dependencies
117			180
118	-	\| Mode \| Key \| Actions \|	181	+	Arch Linux:
119	-	\|------\|-----\|---------\|
120	-	\| Pane \| `Ctrl+P` \| Split · Stack · Close · Move \|
121	-	\| Tab \| `Ctrl+T` \| New · Close · Switch · Rename \|
122	-	\| Resize \| `Ctrl+N` \| Grow · Shrink · hjkl/arrows \|
123	-	\| Session \| `Ctrl+O` \| Save · Restore · Browse \|
124			182
125	-	## Floating Pane	183	+	```bash
			184	+	sudo pacman -S cef webkitgtk-6.0 gtk4 gst-plugins-base gst-plugins-good gst-plugins-bad gst-plugin-va
			185	+	```
126			186
127	-	- `Alt+F` toggles the floating pane and preserves its state while hidden.	187	+	Debian/Ubuntu:
128	-	- `Ctrl+W` closes the active pane; if the floating pane is active, it is fully released for a fresh next open.
129	-	- Profile shortcuts like `Alt+G` are optional and configured under `workspace.floating_pane.profiles`.
130	-	- Some `Alt+<key>` bindings may conflict with default WebKit shortcuts or desktop-level handlers.
131			188
132	-	See [Floating Pane Reference](https://dumber.bnema.dev/docs/reference/floating-pane) for setup and behavior details.	189	+	```bash
			190	+	sudo apt install libwebkitgtk-6.0-4 libgtk-4-1 gstreamer1.0-plugins-base gstreamer1.0-plugins-good gstreamer1.0-plugins-bad
			191	+	```
133			192
134	-	## Development	193	+	> Ubuntu 24.04 ships GLib 2.80, but Dumber requires GLib 2.84+. Use Arch, Fedora 41+, or the Flatpak.
135			194
136	-	Dumber uses pure-Go bindings (no CGO) but requires GTK4/WebKitGTK runtime libraries for the GUI.	195	+	## Status
137			196
138	-	### Environment	197	+	Dumber is usable for regular web browsing on Wayland compositors, with the main focus on panes, keyboard control, floating workflows, and desktop integration.
139			198
140	-	Set `ENV=dev` to use `.dev/dumber/` for config/data instead of XDG paths.	199	+	It is not a drop-in replacement for every mainstream browser workflow. Extension compatibility, engine behavior, and media support depend on the selected backend and system libraries.
141			200
142	-	### Build From Source	201	+	Bug reports and reproducible Wayland/backend issues are welcome.
			202	+
			203	+	## Development
			204	+
			205	+	Dumber uses pure-Go bindings and requires GTK4/WebKitGTK runtime libraries for the GUI.
			206	+
			207	+	Set `ENV=dev` to use `.dev/dumber/` for config and data instead of XDG paths.
			208	+
			209	+	### Build from source
143			210
144		Prerequisites:	211		Prerequisites:
			212	+
145		- Go 1.25+	213		- Go 1.25+
146	-	- Node.js 20+ (for frontend assets)	214	+	- Node.js 20+ for frontend assets
147	-	- WebKitGTK 6.0 and GTK4 dev packages	215	+	- WebKitGTK 6.0 and GTK4 development packages
148			216
149		```bash	217		```bash
150		git clone https://github.com/bnema/dumber	218		git clone https://github.com/bnema/dumber

@@ -153,12 +221,12 @@ make build
153		./dist/dumber browse	221		./dist/dumber browse
154		```	222		```
155			223
156	-	### Make Targets	224	+	### Make targets
157			225
158		\| Target \| Description \|	226		\| Target \| Description \|
159		\|--------\|-------------\|	227		\|--------\|-------------\|
160	-	\| `make build` \| Build frontend + binary \|	228	+	\| `make build` \| Build frontend and binary \|
161	-	\| `make build-quick` \| Build binary only (skip frontend) \|	229	+	\| `make build-quick` \| Build binary only, skipping frontend \|
162		\| `make dev` \| Run with `go run` \|	230		\| `make dev` \| Run with `go run` \|
163		\| `make test` \| Run tests \|	231		\| `make test` \| Run tests \|
164		\| `make lint` \| Run golangci-lint \|	232		\| `make lint` \| Run golangci-lint \|

@@ -166,9 +234,9 @@ make build
166			234
167		## Contributing	235		## Contributing
168			236
169	-	We welcome bug fixes, performance/stability improvements, and WebUI/UX enhancements. We're not accepting new feature PRs.	237	+	Dumber is currently focused on stability, performance, browser-engine behavior, and core UI/UX polish.
170			238
171	-	All PRs must target the `next` branch. We test there first before releasing to `main`.	239	+	Bug fixes, documentation improvements, packaging fixes, and targeted UX improvements are welcome. Larger feature ideas should start as issues before PRs.
172			240
173		See [CONTRIBUTING.md](CONTRIBUTING.md) for details.	241		See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
174			242