docs: refresh README with simplified quick start and development section
- commit
- bf39c2565733043119e39ab4638ff5f99d68fce3
- author
- brice · · 2025-12-31 05:54 UTC
- parent
- fc8669a
- signature
- GPG Verified
CD88F9E564E0102646FB6077A1A07C7C7C3E349D· arch-gpg Verified for the committer email
1 file · +59 -54
M README.md +59 -54
| @@ -21,18 +21,28 @@ A dumb browser that works like your favorite terminal multiplexer. | |||
| 21 | 21 | - **Launcher integration**: dmenu-style with rofi/fuzzel support, shows favicons and history. | |
| 22 | 22 | - **Search shortcuts**: Quick search via bangs (e.g., `!g golang` for Google, `!gi cats` for Google Images). | |
| 23 | 23 | - **Customizable themes**: Light and dark palettes with semantic color tokens. | |
| 24 | - | - **Persistent storage**: SQLite for history, zoom levels, and settings. | |
| 24 | + | - **Persistent storage**: SQLite for history, favorites, per-domain zoom levels, and sessions. | |
| 25 | 25 | - **Live configuration**: Single config file with hot reload when possible. | |
| 26 | 26 | - **Session management**: Zellij-style session save/restore with automatic snapshots and resurrection. | |
| 27 | 27 | ||
| 28 | 28 | ## Status | |
| 29 | - | Dumber recently completed a full rewrite in pure Go using the `puregotk` and `puregotk-webkit` libraries. | |
| 29 | + | Dumber is almost feature-complete. Next steps will focus on stability, performance, and bug fixing. | |
| 30 | 30 | ||
| 31 | - | The project is now structured around clean architecture, which makes it much easier to iterate on features and improve testability. | |
| 31 | + | Core features work well for daily use but expect some rough edges. Some features are still alpha/experimental (notably consume-or-expel panes) and may change behavior between releases. | |
| 32 | 32 | ||
| 33 | - | Early development with regular releases. Core features work well for daily use but expect some rough edges. | |
| 33 | + | ## Quick Start | |
| 34 | + | ||
| 35 | + | ```bash | |
| 36 | + | # Download and install | |
| 37 | + | wget https://github.com/bnema/dumber/releases/latest/download/dumber_linux_x86_64.tar.gz | |
| 38 | + | tar -xzf dumber_linux_x86_64.tar.gz | |
| 39 | + | mkdir -p ~/.local/bin && install -m 755 dumber_*/dumber ~/.local/bin/ | |
| 34 | 40 | ||
| 35 | - | Some features are very alpha/experimental (notably consume-or-expel panes) and may change behavior between releases. | |
| 41 | + | # Run | |
| 42 | + | dumber browse https://example.com | |
| 43 | + | ``` | |
| 44 | + | ||
| 45 | + | See [Install](#install) for AUR, Flatpak, building from source, and runtime dependencies. | |
| 36 | 46 | ||
| 37 | 47 | ## Controls & Shortcuts | |
| 38 | 48 | ||
| @@ -129,49 +139,6 @@ Some features are very alpha/experimental (notably consume-or-expel panes) and m | |||
| 129 | 139 | ||
| 130 | 140 | All zoom changes are automatically persisted per-domain and restored on next visit. | |
| 131 | 141 | ||
| 132 | - | ## Quick Start | |
| 133 | - | ||
| 134 | - | **Option 1: Use Pre-built Binaries (Recommended)** | |
| 135 | - | ||
| 136 | - | Download the latest release from the [releases page](https://github.com/bnema/dumber/releases): | |
| 137 | - | ```bash | |
| 138 | - | # Download latest release | |
| 139 | - | wget https://github.com/bnema/dumber/releases/latest/download/dumber_linux_x86_64.tar.gz | |
| 140 | - | ||
| 141 | - | # Extract and install to ~/.local/bin (enables auto-updates) | |
| 142 | - | tar -xzf dumber_linux_x86_64.tar.gz | |
| 143 | - | mkdir -p ~/.local/bin | |
| 144 | - | install -m 755 dumber_*/dumber ~/.local/bin/ | |
| 145 | - | ||
| 146 | - | # Ensure ~/.local/bin is in your PATH (add to ~/.bashrc or ~/.zshrc if needed) | |
| 147 | - | # export PATH="$HOME/.local/bin:$PATH" | |
| 148 | - | ``` | |
| 149 | - | ||
| 150 | - | Then install runtime dependencies (see [Dependencies](#dependencies) section below). | |
| 151 | - | ||
| 152 | - | **Option 2: Build From Source** | |
| 153 | - | ||
| 154 | - | Prerequisites: | |
| 155 | - | - Go 1.25+ | |
| 156 | - | - Node.js 20+ and npm (for building the embedded TypeScript frontend) | |
| 157 | - | - For GUI build: WebKitGTK 6 and GTK4 dev packages (examples) | |
| 158 | - | - Minimum runtime versions: WebKitGTK 6.0 >= `2.50`, GTK4 >= `4.20`, GLib >= `2.84` | |
| 159 | - | - Debian/Ubuntu: `libwebkitgtk-6.0-dev libgtk-4-dev build-essential` | |
| 160 | - | - Arch: `webkitgtk-6.0 gtk4 base-devel` | |
| 161 | - | - Verify your system with: `dumber doctor` (or configure `runtime.prefix` for `/opt` installs) | |
| 162 | - | ||
| 163 | - | Build options: | |
| 164 | - | - Default (recommended): | |
| 165 | - | - `make build` # builds frontend + Go (pure Go; CGO off) | |
| 166 | - | - Run: `./dist/dumber` # run the app | |
| 167 | - | - Quick (no frontend rebuild): | |
| 168 | - | - `make build-quick` | |
| 169 | - | - Run: `./dist/dumber` | |
| 170 | - | ||
| 171 | - | Development: | |
| 172 | - | - `make dev` runs `go run ./cmd/dumber` | |
| 173 | - | - `make test` runs tests; `make lint` runs golangci‑lint | |
| 174 | - | ||
| 175 | 142 | ## Install | |
| 176 | 143 | ||
| 177 | 144 | ### Pre-built Binaries (Recommended) | |
| @@ -384,12 +351,50 @@ A default config is created on first run. Changes are applied automatically (hot | |||
| 384 | 351 | **Full documentation**: [docs/CONFIG.md](docs/CONFIG.md) - Complete reference for all settings, workspace controls, shortcuts, styling, and more. | |
| 385 | 352 | ||
| 386 | 353 | ||
| 387 | - | ## Building With WebKitGTK 6 (GTK4) | |
| 388 | - | - Dumber uses pure-Go bindings (no CGO). | |
| 389 | - | - You still need the system GTK4/WebKitGTK runtime libraries installed to run the GUI. | |
| 390 | - | - Build targets: | |
| 391 | - | - `make build` (builds frontend + binary) | |
| 392 | - | - `make build-quick` (binary only; skips frontend build) | |
| 354 | + | ## Development | |
| 355 | + | ||
| 356 | + | Dumber uses pure-Go bindings (no CGO) but requires GTK4/WebKitGTK runtime libraries for the GUI. | |
| 357 | + | ||
| 358 | + | ### Environment | |
| 359 | + | ||
| 360 | + | Set `ENV=dev` to use a local `.dev/dumber/` directory for config, data, state, and cache instead of XDG paths. Useful for testing without affecting your real browser data. | |
| 361 | + | ||
| 362 | + | ### Make Targets | |
| 363 | + | ||
| 364 | + | | Target | Description | | |
| 365 | + | |--------|-------------| | |
| 366 | + | | `make build` | Build frontend + binary (recommended) | | |
| 367 | + | | `make build-quick` | Build binary only (faster for backend work) | | |
| 368 | + | | `make build-frontend` | Build webui pages (homepage, error, config) | | |
| 369 | + | | `make dev` | Run with `go run` | | |
| 370 | + | | `make test` | Run tests | | |
| 371 | + | | `make test-race` | Run tests with race detection | | |
| 372 | + | | `make test-cover` | Run tests with coverage report | | |
| 373 | + | | `make lint` | Run golangci-lint | | |
| 374 | + | | `make lint-fix` | Run golangci-lint with auto-fix | | |
| 375 | + | | `make fmt` | Format Go code | | |
| 376 | + | | `make generate` | Generate SQLC code | | |
| 377 | + | | `make mocks` | Generate mock implementations | | |
| 378 | + | | `make install-tools` | Install dev tools (sqlc, golangci-lint) | | |
| 379 | + | | `make check` | Verify tools, build, and tests work | | |
| 380 | + | | `make clean` | Remove build artifacts | | |
| 381 | + | ||
| 382 | + | ### Flatpak | |
| 383 | + | ||
| 384 | + | | Target | Description | | |
| 385 | + | |--------|-------------| | |
| 386 | + | | `make flatpak-deps` | Install Flatpak build dependencies | | |
| 387 | + | | `make flatpak-build` | Build Flatpak bundle | | |
| 388 | + | | `make flatpak-install` | Install Flatpak locally for testing | | |
| 389 | + | | `make flatpak-run` | Run the installed Flatpak | | |
| 390 | + | | `make flatpak-clean` | Clean Flatpak build artifacts | | |
| 391 | + | ||
| 392 | + | ### Release | |
| 393 | + | ||
| 394 | + | | Target | Description | | |
| 395 | + | |--------|-------------| | |
| 396 | + | | `make release-snapshot` | Build snapshot with goreleaser | | |
| 397 | + | | `make release` | Create full release with goreleaser | | |
| 393 | 398 | ||
| 394 | 399 | ## Media (GStreamer) & Hardware Acceleration | |
| 395 | 400 | ||
| @@ -21,18 +21,28 @@ A dumb browser that works like your favorite terminal multiplexer. | |||||
| 21 | - **Launcher integration**: dmenu-style with rofi/fuzzel support, shows favicons and history. | 21 | - **Launcher integration**: dmenu-style with rofi/fuzzel support, shows favicons and history. | ||
| 22 | - **Search shortcuts**: Quick search via bangs (e.g., `!g golang` for Google, `!gi cats` for Google Images). | 22 | - **Search shortcuts**: Quick search via bangs (e.g., `!g golang` for Google, `!gi cats` for Google Images). | ||
| 23 | - **Customizable themes**: Light and dark palettes with semantic color tokens. | 23 | - **Customizable themes**: Light and dark palettes with semantic color tokens. | ||
| 24 | - | - **Persistent storage**: SQLite for history, zoom levels, and settings. | 24 | + | - **Persistent storage**: SQLite for history, favorites, per-domain zoom levels, and sessions. |
| 25 | - **Live configuration**: Single config file with hot reload when possible. | 25 | - **Live configuration**: Single config file with hot reload when possible. | ||
| 26 | - **Session management**: Zellij-style session save/restore with automatic snapshots and resurrection. | 26 | - **Session management**: Zellij-style session save/restore with automatic snapshots and resurrection. | ||
| 27 | 27 | ||||
| 28 | ## Status | 28 | ## Status | ||
| 29 | - | Dumber recently completed a full rewrite in pure Go using the `puregotk` and `puregotk-webkit` libraries. | 29 | + | Dumber is almost feature-complete. Next steps will focus on stability, performance, and bug fixing. |
| 30 | 30 | ||||
| 31 | - | The project is now structured around clean architecture, which makes it much easier to iterate on features and improve testability. | 31 | + | Core features work well for daily use but expect some rough edges. Some features are still alpha/experimental (notably consume-or-expel panes) and may change behavior between releases. |
| 32 | 32 | ||||
| 33 | - | Early development with regular releases. Core features work well for daily use but expect some rough edges. | 33 | + | ## Quick Start |
| 34 | + | ||||
| 35 | + | ```bash | |||
| 36 | + | # Download and install | |||
| 37 | + | wget https://github.com/bnema/dumber/releases/latest/download/dumber_linux_x86_64.tar.gz | |||
| 38 | + | tar -xzf dumber_linux_x86_64.tar.gz | |||
| 39 | + | mkdir -p ~/.local/bin && install -m 755 dumber_*/dumber ~/.local/bin/ | |||
| 34 | 40 | ||||
| 35 | - | Some features are very alpha/experimental (notably consume-or-expel panes) and may change behavior between releases. | 41 | + | # Run |
| 42 | + | dumber browse https://example.com | |||
| 43 | + | ``` | |||
| 44 | + | ||||
| 45 | + | See [Install](#install) for AUR, Flatpak, building from source, and runtime dependencies. | |||
| 36 | 46 | ||||
| 37 | ## Controls & Shortcuts | 47 | ## Controls & Shortcuts | ||
| 38 | 48 | ||||
| @@ -129,49 +139,6 @@ Some features are very alpha/experimental (notably consume-or-expel panes) and m | |||||
| 129 | 139 | ||||
| 130 | All zoom changes are automatically persisted per-domain and restored on next visit. | 140 | All zoom changes are automatically persisted per-domain and restored on next visit. | ||
| 131 | 141 | ||||
| 132 | - | ## Quick Start | |||
| 133 | - | ||||
| 134 | - | **Option 1: Use Pre-built Binaries (Recommended)** | |||
| 135 | - | ||||
| 136 | - | Download the latest release from the [releases page](https://github.com/bnema/dumber/releases): | |||
| 137 | - | ```bash | |||
| 138 | - | # Download latest release | |||
| 139 | - | wget https://github.com/bnema/dumber/releases/latest/download/dumber_linux_x86_64.tar.gz | |||
| 140 | - | ||||
| 141 | - | # Extract and install to ~/.local/bin (enables auto-updates) | |||
| 142 | - | tar -xzf dumber_linux_x86_64.tar.gz | |||
| 143 | - | mkdir -p ~/.local/bin | |||
| 144 | - | install -m 755 dumber_*/dumber ~/.local/bin/ | |||
| 145 | - | ||||
| 146 | - | # Ensure ~/.local/bin is in your PATH (add to ~/.bashrc or ~/.zshrc if needed) | |||
| 147 | - | # export PATH="$HOME/.local/bin:$PATH" | |||
| 148 | - | ``` | |||
| 149 | - | ||||
| 150 | - | Then install runtime dependencies (see [Dependencies](#dependencies) section below). | |||
| 151 | - | ||||
| 152 | - | **Option 2: Build From Source** | |||
| 153 | - | ||||
| 154 | - | Prerequisites: | |||
| 155 | - | - Go 1.25+ | |||
| 156 | - | - Node.js 20+ and npm (for building the embedded TypeScript frontend) | |||
| 157 | - | - For GUI build: WebKitGTK 6 and GTK4 dev packages (examples) | |||
| 158 | - | - Minimum runtime versions: WebKitGTK 6.0 >= `2.50`, GTK4 >= `4.20`, GLib >= `2.84` | |||
| 159 | - | - Debian/Ubuntu: `libwebkitgtk-6.0-dev libgtk-4-dev build-essential` | |||
| 160 | - | - Arch: `webkitgtk-6.0 gtk4 base-devel` | |||
| 161 | - | - Verify your system with: `dumber doctor` (or configure `runtime.prefix` for `/opt` installs) | |||
| 162 | - | ||||
| 163 | - | Build options: | |||
| 164 | - | - Default (recommended): | |||
| 165 | - | - `make build` # builds frontend + Go (pure Go; CGO off) | |||
| 166 | - | - Run: `./dist/dumber` # run the app | |||
| 167 | - | - Quick (no frontend rebuild): | |||
| 168 | - | - `make build-quick` | |||
| 169 | - | - Run: `./dist/dumber` | |||
| 170 | - | ||||
| 171 | - | Development: | |||
| 172 | - | - `make dev` runs `go run ./cmd/dumber` | |||
| 173 | - | - `make test` runs tests; `make lint` runs golangci‑lint | |||
| 174 | - | ||||
| 175 | ## Install | 142 | ## Install | ||
| 176 | 143 | ||||
| 177 | ### Pre-built Binaries (Recommended) | 144 | ### Pre-built Binaries (Recommended) | ||
| @@ -384,12 +351,50 @@ A default config is created on first run. Changes are applied automatically (hot | |||||
| 384 | **Full documentation**: [docs/CONFIG.md](docs/CONFIG.md) - Complete reference for all settings, workspace controls, shortcuts, styling, and more. | 351 | **Full documentation**: [docs/CONFIG.md](docs/CONFIG.md) - Complete reference for all settings, workspace controls, shortcuts, styling, and more. | ||
| 385 | 352 | ||||
| 386 | 353 | ||||
| 387 | - | ## Building With WebKitGTK 6 (GTK4) | 354 | + | ## Development |
| 388 | - | - Dumber uses pure-Go bindings (no CGO). | 355 | + | |
| 389 | - | - You still need the system GTK4/WebKitGTK runtime libraries installed to run the GUI. | 356 | + | Dumber uses pure-Go bindings (no CGO) but requires GTK4/WebKitGTK runtime libraries for the GUI. |
| 390 | - | - Build targets: | 357 | + | |
| 391 | - | - `make build` (builds frontend + binary) | 358 | + | ### Environment |
| 392 | - | - `make build-quick` (binary only; skips frontend build) | 359 | + | |
| 360 | + | Set `ENV=dev` to use a local `.dev/dumber/` directory for config, data, state, and cache instead of XDG paths. Useful for testing without affecting your real browser data. | |||
| 361 | + | ||||
| 362 | + | ### Make Targets | |||
| 363 | + | ||||
| 364 | + | | Target | Description | | |||
| 365 | + | |--------|-------------| | |||
| 366 | + | | `make build` | Build frontend + binary (recommended) | | |||
| 367 | + | | `make build-quick` | Build binary only (faster for backend work) | | |||
| 368 | + | | `make build-frontend` | Build webui pages (homepage, error, config) | | |||
| 369 | + | | `make dev` | Run with `go run` | | |||
| 370 | + | | `make test` | Run tests | | |||
| 371 | + | | `make test-race` | Run tests with race detection | | |||
| 372 | + | | `make test-cover` | Run tests with coverage report | | |||
| 373 | + | | `make lint` | Run golangci-lint | | |||
| 374 | + | | `make lint-fix` | Run golangci-lint with auto-fix | | |||
| 375 | + | | `make fmt` | Format Go code | | |||
| 376 | + | | `make generate` | Generate SQLC code | | |||
| 377 | + | | `make mocks` | Generate mock implementations | | |||
| 378 | + | | `make install-tools` | Install dev tools (sqlc, golangci-lint) | | |||
| 379 | + | | `make check` | Verify tools, build, and tests work | | |||
| 380 | + | | `make clean` | Remove build artifacts | | |||
| 381 | + | ||||
| 382 | + | ### Flatpak | |||
| 383 | + | ||||
| 384 | + | | Target | Description | | |||
| 385 | + | |--------|-------------| | |||
| 386 | + | | `make flatpak-deps` | Install Flatpak build dependencies | | |||
| 387 | + | | `make flatpak-build` | Build Flatpak bundle | | |||
| 388 | + | | `make flatpak-install` | Install Flatpak locally for testing | | |||
| 389 | + | | `make flatpak-run` | Run the installed Flatpak | | |||
| 390 | + | | `make flatpak-clean` | Clean Flatpak build artifacts | | |||
| 391 | + | ||||
| 392 | + | ### Release | |||
| 393 | + | ||||
| 394 | + | | Target | Description | | |||
| 395 | + | |--------|-------------| | |||
| 396 | + | | `make release-snapshot` | Build snapshot with goreleaser | | |||
| 397 | + | | `make release` | Create full release with goreleaser | | |||
| 393 | 398 | ||||
| 394 | ## Media (GStreamer) & Hardware Acceleration | 399 | ## Media (GStreamer) & Hardware Acceleration | ||
| 395 | 400 | ||||