docs: add Go install, Wayland-first note, early-stage status, and roadmap; add LICENSE
- commit
- 7e4d1cba0bd293e833ac987abc681884688c4d97
- author
- bamen · · 2025-09-09 20:43 UTC
- parent
- 458970b
- signature
- unsigned
2 files · +158 -0
A LICENSE +22 -0
| @@ -0,0 +1,22 @@ | |||
| 1 | + | MIT License | |
| 2 | + | ||
| 3 | + | Copyright (c) 2025 bnema | |
| 4 | + | ||
| 5 | + | Permission is hereby granted, free of charge, to any person obtaining a copy | |
| 6 | + | of this software and associated documentation files (the "Software"), to deal | |
| 7 | + | in the Software without restriction, including without limitation the rights | |
| 8 | + | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell | |
| 9 | + | copies of the Software, and to permit persons to whom the Software is | |
| 10 | + | furnished to do so, subject to the following conditions: | |
| 11 | + | ||
| 12 | + | The above copyright notice and this permission notice shall be included in all | |
| 13 | + | copies or substantial portions of the Software. | |
| 14 | + | ||
| 15 | + | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR | |
| 16 | + | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, | |
| 17 | + | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE | |
| 18 | + | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER | |
| 19 | + | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, | |
| 20 | + | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE | |
| 21 | + | SOFTWARE. | |
| 22 | + | ||
| @@ -0,0 +1,22 @@ | |||||
| 1 | + | MIT License | |||
| 2 | + | ||||
| 3 | + | Copyright (c) 2025 bnema | |||
| 4 | + | ||||
| 5 | + | Permission is hereby granted, free of charge, to any person obtaining a copy | |||
| 6 | + | of this software and associated documentation files (the "Software"), to deal | |||
| 7 | + | in the Software without restriction, including without limitation the rights | |||
| 8 | + | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell | |||
| 9 | + | copies of the Software, and to permit persons to whom the Software is | |||
| 10 | + | furnished to do so, subject to the following conditions: | |||
| 11 | + | ||||
| 12 | + | The above copyright notice and this permission notice shall be included in all | |||
| 13 | + | copies or substantial portions of the Software. | |||
| 14 | + | ||||
| 15 | + | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR | |||
| 16 | + | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, | |||
| 17 | + | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE | |||
| 18 | + | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER | |||
| 19 | + | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, | |||
| 20 | + | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE | |||
| 21 | + | SOFTWARE. | |||
| 22 | + | ||||
A README.md +136 -0
| @@ -0,0 +1,136 @@ | |||
| 1 | + | # Dumber — a tiny, dumb browser for Wayland | |
| 2 | + | ||
| 3 | + | Dumber is a minimalist browser and launcher companion focused on speed and simplicity. It ships a built‑in WebKit2GTK window for navigation and a CLI with dmenu‑style launcher integration (rofi, fuzzel). | |
| 4 | + | ||
| 5 | + | - Native GUI via WebKit2GTK (CGO) with an embedded homepage UI. | |
| 6 | + | - CLI that parses URLs, supports search shortcuts (e.g., `g:query`), and integrates with rofi/dmenu. | |
| 7 | + | - Persistent history and per‑domain zoom levels (SQLite, XDG locations). | |
| 8 | + | - Configurable via `config.json` and environment variables, with live reload. | |
| 9 | + | ||
| 10 | + | ## Wayland‑First | |
| 11 | + | - Dumb on purpose, designed for Wayland window managers (Sway, Hyprland, River, Niri, etc..) — a tiny companion that plays nicely with your launcher. | |
| 12 | + | - Uses a native WebKit2GTK window; no external browser required and no X11/XWayland dependency. | |
| 13 | + | - Optimized for dmenu‑style launchers (rofi, fuzzel, wofi) and keyboard‑driven workflows. | |
| 14 | + | ||
| 15 | + | ## Status | |
| 16 | + | - Very early stage — expect sharp edges and breaking changes, but it works well enough to browse and play with the launcher flows. | |
| 17 | + | ||
| 18 | + | ## Features | |
| 19 | + | - Built‑in browser window (no external browser needed) | |
| 20 | + | - Custom `dumb://` scheme serving embedded frontend assets | |
| 21 | + | - Keyboard shortcuts: DevTools (F12), Omnibox toggle (Ctrl/Cmd+L), Zoom In/Out/Reset | |
| 22 | + | - Persistent history with search and stats | |
| 23 | + | - Per‑domain zoom persistence | |
| 24 | + | - dmenu‑style launcher integration (rofi, fuzzel) with history and shortcut suggestions | |
| 25 | + | ||
| 26 | + | ## Quick Start | |
| 27 | + | Prerequisites: | |
| 28 | + | - Go 1.25+ | |
| 29 | + | - Node.js 20+ (for building the embedded frontend) | |
| 30 | + | - For GUI build: WebKit2GTK and GTK dev packages (examples) | |
| 31 | + | - Debian/Ubuntu: `libwebkit2gtk-4.1-dev libgtk-3-dev build-essential` | |
| 32 | + | - Arch: `webkit2gtk gtk3 base-devel` | |
| 33 | + | ||
| 34 | + | Build options: | |
| 35 | + | - GUI (recommended): | |
| 36 | + | - `make build-gui` # builds with `-tags=webkit_cgo` | |
| 37 | + | - Run: `./dist/dumber` # opens the embedded homepage | |
| 38 | + | - CLI‑only (no GUI, CGO disabled): | |
| 39 | + | - `make build-static` | |
| 40 | + | - Run: `./dist/dumber-static version` | |
| 41 | + | - Full build pipeline (frontend + Go): | |
| 42 | + | - `make build` | |
| 43 | + | ||
| 44 | + | Development: | |
| 45 | + | - `make dev` runs `go run .` (non‑CGO; GUI stubs log to console) | |
| 46 | + | - `make test` runs tests; `make lint` runs golangci‑lint | |
| 47 | + | ||
| 48 | + | ## Install | |
| 49 | + | - CLI‑only (no native window): | |
| 50 | + | - `go install github.com/bnema/dumber@latest` | |
| 51 | + | - Useful everywhere; runs the CLI and non‑CGO flows. In this mode the GUI code is stubbed (no native window shown). | |
| 52 | + | - GUI build (Wayland + WebKit2GTK via CGO): | |
| 53 | + | - Ensure WebKit2GTK/GTK dev packages are installed (see prerequisites) and CGO is enabled in your environment. | |
| 54 | + | - `go install -tags webkit_cgo github.com/bnema/dumber@latest` | |
| 55 | + | - If pkg‑config can’t find headers, set `PKG_CONFIG_PATH` appropriately or prefer `make build-gui`. | |
| 56 | + | ||
| 57 | + | ## Usage | |
| 58 | + | - Open a URL or search: | |
| 59 | + | - `dumber browse https://example.com` | |
| 60 | + | - `dumber browse example.com` # scheme auto‑added | |
| 61 | + | - `dumber browse g:golang` # Google search via shortcut | |
| 62 | + | - Launch the GUI directly: | |
| 63 | + | - `dumber` # no args → opens GUI homepage | |
| 64 | + | - Launcher integration (dmenu‑style examples): | |
| 65 | + | - rofi: `dumber dmenu | rofi -dmenu -p "Browse: " | dumber dmenu --select` | |
| 66 | + | - fuzzel: `dumber dmenu | fuzzel --dmenu -p "Browse: " | dumber dmenu --select` | |
| 67 | + | ||
| 68 | + | ### Dmenu mode invocation | |
| 69 | + | You can invoke dmenu mode in two ways: | |
| 70 | + | - Subcommand (recommended): `dumber dmenu` … and `dumber dmenu --select` | |
| 71 | + | - Root flag (generate options only): `dumber --dmenu` | |
| 72 | + | ||
| 73 | + | Note: The root flag path only generates options; for processing a selection (`--select`), use the `dmenu` subcommand as the receiving command. | |
| 74 | + | ||
| 75 | + | In GUI mode the app serves an embedded homepage via `dumb://homepage`, and frontend assets under `dumb://app/...`. | |
| 76 | + | ||
| 77 | + | ## Configuration | |
| 78 | + | Dumber follows the XDG Base Directory spec: | |
| 79 | + | - Config: `~/.config/dumber/config.json` | |
| 80 | + | - Data: `~/.local/share/dumber` | |
| 81 | + | - State: `~/.local/state/dumber` (default DB lives here) | |
| 82 | + | ||
| 83 | + | A default `config.json` is created on first run. Key fields: | |
| 84 | + | - `database.path`: SQLite database path (defaults to XDG state dir `history.db`) | |
| 85 | + | - `search_shortcuts`: map of search shortcuts, e.g. | |
| 86 | + | ```json | |
| 87 | + | { | |
| 88 | + | "g": { "url": "https://www.google.com/search?q=%s", "description": "Google" }, | |
| 89 | + | "gh": { "url": "https://github.com/search?q=%s", "description": "GitHub" } | |
| 90 | + | } | |
| 91 | + | ``` | |
| 92 | + | - `appearance`: default fonts and base font size for pages without specified fonts | |
| 93 | + | - `dmenu`: options for launcher integration (history count, prefixes, etc.) | |
| 94 | + | ||
| 95 | + | Environment variables use the `DUMB_BROWSER_` prefix (managed by Viper). Examples: | |
| 96 | + | - `DUMB_BROWSER_DATABASE_PATH=...` | |
| 97 | + | - `DUMB_BROWSER_DMENU_MAX_HISTORY_ITEMS=50` | |
| 98 | + | ||
| 99 | + | Config changes are watched and applied at runtime when possible. | |
| 100 | + | ||
| 101 | + | ## Data Model | |
| 102 | + | SQLite tables (created automatically): | |
| 103 | + | - `history(id, url, title, visit_count, last_visited, created_at)` | |
| 104 | + | - `shortcuts(shortcut, url_template, description, created_at)` | |
| 105 | + | - `zoom_levels(domain PRIMARY KEY, zoom_factor, updated_at)` | |
| 106 | + | ||
| 107 | + | ## Building With WebKit2GTK | |
| 108 | + | - The GUI requires building with `-tags=webkit_cgo` and CGO enabled. | |
| 109 | + | - Ensure WebKit2GTK and GTK dev headers are installed (see prerequisites). | |
| 110 | + | - Make targets handle both frontend and Go build steps: | |
| 111 | + | - `make build-gui` (CGO enabled) | |
| 112 | + | - `make build` (CGO enabled by default in the Makefile’s main build) | |
| 113 | + | ||
| 114 | + | Without the native tag, a stub backend is used: you can still run CLI flows and see logs, but no native window is displayed. | |
| 115 | + | ||
| 116 | + | ## Project Structure | |
| 117 | + | - `main.go`: CLI/GUI entrypoint, `dumb://` scheme, service wiring | |
| 118 | + | - `internal/cli`: Cobra commands (`browse`, `dmenu`, `version`) | |
| 119 | + | - `internal/config`: Viper‑backed config, XDG helpers, defaults | |
| 120 | + | - `internal/db`: SQLite schema init and sqlc‑generated queries | |
| 121 | + | - `services`: app services (parser/history/config/browser) | |
| 122 | + | - `pkg/webkit`: WebKit2GTK bindings (CGO and stub implementations) | |
| 123 | + | - `frontend`: TypeScript homepage UI bundled into the binary | |
| 124 | + | ||
| 125 | + | ## Security & Privacy | |
| 126 | + | - History and zoom settings are stored locally in SQLite under XDG state. | |
| 127 | + | - The `tmp/` directory is ignored by Git and kept out of history. | |
| 128 | + | ||
| 129 | + | ## Roadmap | |
| 130 | + | - Full Vim-style motion and keyboard navigation across pages and UI. | |
| 131 | + | - Performance work: faster startup, lower memory, snappier UI. | |
| 132 | + | - Basic ad-block extension — because fuck ads. | |
| 133 | + | - Other shiny things I’m not yet aware of. | |
| 134 | + | ||
| 135 | + | ## License | |
| 136 | + | This project is licensed under the MIT License. See `LICENSE` for details. | |
| @@ -0,0 +1,136 @@ | |||||
| 1 | + | # Dumber — a tiny, dumb browser for Wayland | |||
| 2 | + | ||||
| 3 | + | Dumber is a minimalist browser and launcher companion focused on speed and simplicity. It ships a built‑in WebKit2GTK window for navigation and a CLI with dmenu‑style launcher integration (rofi, fuzzel). | |||
| 4 | + | ||||
| 5 | + | - Native GUI via WebKit2GTK (CGO) with an embedded homepage UI. | |||
| 6 | + | - CLI that parses URLs, supports search shortcuts (e.g., `g:query`), and integrates with rofi/dmenu. | |||
| 7 | + | - Persistent history and per‑domain zoom levels (SQLite, XDG locations). | |||
| 8 | + | - Configurable via `config.json` and environment variables, with live reload. | |||
| 9 | + | ||||
| 10 | + | ## Wayland‑First | |||
| 11 | + | - Dumb on purpose, designed for Wayland window managers (Sway, Hyprland, River, Niri, etc..) — a tiny companion that plays nicely with your launcher. | |||
| 12 | + | - Uses a native WebKit2GTK window; no external browser required and no X11/XWayland dependency. | |||
| 13 | + | - Optimized for dmenu‑style launchers (rofi, fuzzel, wofi) and keyboard‑driven workflows. | |||
| 14 | + | ||||
| 15 | + | ## Status | |||
| 16 | + | - Very early stage — expect sharp edges and breaking changes, but it works well enough to browse and play with the launcher flows. | |||
| 17 | + | ||||
| 18 | + | ## Features | |||
| 19 | + | - Built‑in browser window (no external browser needed) | |||
| 20 | + | - Custom `dumb://` scheme serving embedded frontend assets | |||
| 21 | + | - Keyboard shortcuts: DevTools (F12), Omnibox toggle (Ctrl/Cmd+L), Zoom In/Out/Reset | |||
| 22 | + | - Persistent history with search and stats | |||
| 23 | + | - Per‑domain zoom persistence | |||
| 24 | + | - dmenu‑style launcher integration (rofi, fuzzel) with history and shortcut suggestions | |||
| 25 | + | ||||
| 26 | + | ## Quick Start | |||
| 27 | + | Prerequisites: | |||
| 28 | + | - Go 1.25+ | |||
| 29 | + | - Node.js 20+ (for building the embedded frontend) | |||
| 30 | + | - For GUI build: WebKit2GTK and GTK dev packages (examples) | |||
| 31 | + | - Debian/Ubuntu: `libwebkit2gtk-4.1-dev libgtk-3-dev build-essential` | |||
| 32 | + | - Arch: `webkit2gtk gtk3 base-devel` | |||
| 33 | + | ||||
| 34 | + | Build options: | |||
| 35 | + | - GUI (recommended): | |||
| 36 | + | - `make build-gui` # builds with `-tags=webkit_cgo` | |||
| 37 | + | - Run: `./dist/dumber` # opens the embedded homepage | |||
| 38 | + | - CLI‑only (no GUI, CGO disabled): | |||
| 39 | + | - `make build-static` | |||
| 40 | + | - Run: `./dist/dumber-static version` | |||
| 41 | + | - Full build pipeline (frontend + Go): | |||
| 42 | + | - `make build` | |||
| 43 | + | ||||
| 44 | + | Development: | |||
| 45 | + | - `make dev` runs `go run .` (non‑CGO; GUI stubs log to console) | |||
| 46 | + | - `make test` runs tests; `make lint` runs golangci‑lint | |||
| 47 | + | ||||
| 48 | + | ## Install | |||
| 49 | + | - CLI‑only (no native window): | |||
| 50 | + | - `go install github.com/bnema/dumber@latest` | |||
| 51 | + | - Useful everywhere; runs the CLI and non‑CGO flows. In this mode the GUI code is stubbed (no native window shown). | |||
| 52 | + | - GUI build (Wayland + WebKit2GTK via CGO): | |||
| 53 | + | - Ensure WebKit2GTK/GTK dev packages are installed (see prerequisites) and CGO is enabled in your environment. | |||
| 54 | + | - `go install -tags webkit_cgo github.com/bnema/dumber@latest` | |||
| 55 | + | - If pkg‑config can’t find headers, set `PKG_CONFIG_PATH` appropriately or prefer `make build-gui`. | |||
| 56 | + | ||||
| 57 | + | ## Usage | |||
| 58 | + | - Open a URL or search: | |||
| 59 | + | - `dumber browse https://example.com` | |||
| 60 | + | - `dumber browse example.com` # scheme auto‑added | |||
| 61 | + | - `dumber browse g:golang` # Google search via shortcut | |||
| 62 | + | - Launch the GUI directly: | |||
| 63 | + | - `dumber` # no args → opens GUI homepage | |||
| 64 | + | - Launcher integration (dmenu‑style examples): | |||
| 65 | + | - rofi: `dumber dmenu | rofi -dmenu -p "Browse: " | dumber dmenu --select` | |||
| 66 | + | - fuzzel: `dumber dmenu | fuzzel --dmenu -p "Browse: " | dumber dmenu --select` | |||
| 67 | + | ||||
| 68 | + | ### Dmenu mode invocation | |||
| 69 | + | You can invoke dmenu mode in two ways: | |||
| 70 | + | - Subcommand (recommended): `dumber dmenu` … and `dumber dmenu --select` | |||
| 71 | + | - Root flag (generate options only): `dumber --dmenu` | |||
| 72 | + | ||||
| 73 | + | Note: The root flag path only generates options; for processing a selection (`--select`), use the `dmenu` subcommand as the receiving command. | |||
| 74 | + | ||||
| 75 | + | In GUI mode the app serves an embedded homepage via `dumb://homepage`, and frontend assets under `dumb://app/...`. | |||
| 76 | + | ||||
| 77 | + | ## Configuration | |||
| 78 | + | Dumber follows the XDG Base Directory spec: | |||
| 79 | + | - Config: `~/.config/dumber/config.json` | |||
| 80 | + | - Data: `~/.local/share/dumber` | |||
| 81 | + | - State: `~/.local/state/dumber` (default DB lives here) | |||
| 82 | + | ||||
| 83 | + | A default `config.json` is created on first run. Key fields: | |||
| 84 | + | - `database.path`: SQLite database path (defaults to XDG state dir `history.db`) | |||
| 85 | + | - `search_shortcuts`: map of search shortcuts, e.g. | |||
| 86 | + | ```json | |||
| 87 | + | { | |||
| 88 | + | "g": { "url": "https://www.google.com/search?q=%s", "description": "Google" }, | |||
| 89 | + | "gh": { "url": "https://github.com/search?q=%s", "description": "GitHub" } | |||
| 90 | + | } | |||
| 91 | + | ``` | |||
| 92 | + | - `appearance`: default fonts and base font size for pages without specified fonts | |||
| 93 | + | - `dmenu`: options for launcher integration (history count, prefixes, etc.) | |||
| 94 | + | ||||
| 95 | + | Environment variables use the `DUMB_BROWSER_` prefix (managed by Viper). Examples: | |||
| 96 | + | - `DUMB_BROWSER_DATABASE_PATH=...` | |||
| 97 | + | - `DUMB_BROWSER_DMENU_MAX_HISTORY_ITEMS=50` | |||
| 98 | + | ||||
| 99 | + | Config changes are watched and applied at runtime when possible. | |||
| 100 | + | ||||
| 101 | + | ## Data Model | |||
| 102 | + | SQLite tables (created automatically): | |||
| 103 | + | - `history(id, url, title, visit_count, last_visited, created_at)` | |||
| 104 | + | - `shortcuts(shortcut, url_template, description, created_at)` | |||
| 105 | + | - `zoom_levels(domain PRIMARY KEY, zoom_factor, updated_at)` | |||
| 106 | + | ||||
| 107 | + | ## Building With WebKit2GTK | |||
| 108 | + | - The GUI requires building with `-tags=webkit_cgo` and CGO enabled. | |||
| 109 | + | - Ensure WebKit2GTK and GTK dev headers are installed (see prerequisites). | |||
| 110 | + | - Make targets handle both frontend and Go build steps: | |||
| 111 | + | - `make build-gui` (CGO enabled) | |||
| 112 | + | - `make build` (CGO enabled by default in the Makefile’s main build) | |||
| 113 | + | ||||
| 114 | + | Without the native tag, a stub backend is used: you can still run CLI flows and see logs, but no native window is displayed. | |||
| 115 | + | ||||
| 116 | + | ## Project Structure | |||
| 117 | + | - `main.go`: CLI/GUI entrypoint, `dumb://` scheme, service wiring | |||
| 118 | + | - `internal/cli`: Cobra commands (`browse`, `dmenu`, `version`) | |||
| 119 | + | - `internal/config`: Viper‑backed config, XDG helpers, defaults | |||
| 120 | + | - `internal/db`: SQLite schema init and sqlc‑generated queries | |||
| 121 | + | - `services`: app services (parser/history/config/browser) | |||
| 122 | + | - `pkg/webkit`: WebKit2GTK bindings (CGO and stub implementations) | |||
| 123 | + | - `frontend`: TypeScript homepage UI bundled into the binary | |||
| 124 | + | ||||
| 125 | + | ## Security & Privacy | |||
| 126 | + | - History and zoom settings are stored locally in SQLite under XDG state. | |||
| 127 | + | - The `tmp/` directory is ignored by Git and kept out of history. | |||
| 128 | + | ||||
| 129 | + | ## Roadmap | |||
| 130 | + | - Full Vim-style motion and keyboard navigation across pages and UI. | |||
| 131 | + | - Performance work: faster startup, lower memory, snappier UI. | |||
| 132 | + | - Basic ad-block extension — because fuck ads. | |||
| 133 | + | - Other shiny things I’m not yet aware of. | |||
| 134 | + | ||||
| 135 | + | ## License | |||
| 136 | + | This project is licensed under the MIT License. See `LICENSE` for details. | |||