buffr

Vim-inspired browser. Native, GPU-accelerated. Rust + CEF.

Modal browser built on Chromium Embedded Framework via the cef Rust crate. Vim keybindings powered by hjkl-engine.

Status

Pre-1.0, tagged releases on every version bump — the current version is whatever the latest release says. Multi-tab browsing; popup windows (window.open, OAuth) render in dedicated buffr windows with read-only address bars and preserve window.opener; target="_blank" and Ctrl+click open in tabs; two-finger horizontal swipe navigates browser history; vim modal engine (hjkl-engine) wired for page-mode dispatch and insert-mode text editing; history / downloads / bookmarks / permissions / zoom data layers wired and persisted to SQLite. See CHANGELOG.md.

Supported platforms

Each release publishes binary artifacts for:

OS	Architecture	Format
Linux	x86_64, aarch64	.deb, .rpm, .tar.gz
macOS	arm64 (Apple Silicon)	.dmg
Windows	x64, arm64	.msi (per-user)

Linux requires a Wayland session. X11 is not supported. GNOME 45+, KDE 6, Sway, Hyprland, and other modern compositors all run Wayland by default. buffr will exit with a clear error if XDG_SESSION_TYPE is not wayland.

Why no Intel Mac (x86_64-apple-darwin)?

We dropped Intel Mac builds in 0.1.14. Apple stopped selling Intel Macs in 2023, and the GitHub Actions macos-13 runner pool is heavily contended — release tags routinely queued for 1–2 hours waiting on a slot, blocking the entire publish pipeline (publish-github-release in .github/workflows/ci.yml gates on every binary leg). The cost wasn't paying for the user count, so we cut it.

If you're on an Intel Mac and want to run buffr, build from source on your own machine — the workspace builds clean against x86_64-apple-darwin, the support is just absent from the release pipeline, not from the code.

Apps

Binary	Role
buffr	Supervisor / entrypoint. Spawns buffr-app, restarts it on crash or UI hang.
buffr-app	The browser itself. Owns the window, CEF lifecycle, chrome, keymap, stores.
buffr-helper	CEF subprocess helper (renderer / GPU / utility processes).

Crates

Crate	Role
buffr-engine	BrowserEngine trait, engine routing, internal buffr:// server.
buffr-cef	CEF integration: BrowserHost, multi-tab host, OSR, handlers, IPC.
buffr-core	Engine-agnostic core: hints, edit mode, updates, crash reporter, …
buffr-modal	Vim page-mode FSM, keymap trie, hjkl-engine edit-mode bridge.
buffr-ui	Statusline, tab strip, input bar, permission / confirm prompts.
buffr-config	TOML config loader, validator, hot-reload watcher.
buffr-store	Shared SQLite open/tune + migration runner behind the five stores.
buffr-history	SQLite-backed browsing history (frecency search).
buffr-bookmarks	SQLite-backed bookmark store with tags + Netscape import.
buffr-downloads	SQLite-backed download tracking; CEF handler integration.
buffr-permissions	SQLite-backed per-origin permission store (camera, mic, geo, …).
buffr-zoom	SQLite-backed per-domain zoom-level persistence.
buffr-view-source	Syntax highlighting + HTML rendering for buffr-src: pages.

All members set publish = false — nothing here goes to crates.io, and the buffr name on the registry is yanked. Consume via path dep inside the workspace, or a git dep from outside it.

Experimental, outside the workspace. crates/buffr-webkit (a WPE WebKit backend) and apps/buffr-poc (a Wayland subsurface-embedding proof of concept on top of it) are in the exclude list in the root Cargo.toml. They are Linux-only, need wpewebkit-2.0 system packages, and are not built by CI. Build them standalone:

cargo build --manifest-path crates/buffr-webkit/Cargo.toml
cargo build --manifest-path apps/buffr-poc/Cargo.toml

Install

macOS (Homebrew)

brew install --cask kryptic-sh/tap/buffr

Arch Linux (AUR)

paru -S buffr-bin

Pre-built packages on every tag, on the releases page:

Platform	Asset	Arches
macOS	.dmg	arm64
Windows	.msi	x64, arm64
Debian / Ubuntu	.deb	amd64, arm64
Fedora / RHEL	.rpm	x86_64, aarch64
Linux (generic)	.tar.gz	x86_64, aarch64
Snap	.snap	amd64, arm64
Flatpak	.flatpak	amd64, arm64

Heads-up: cargo install buffr is not a supported install path — see the note in Build below.

Build

# Vendor the CEF binary distribution (~500 MB extracted).
cargo xtask fetch-cef

# Build the workspace. `default-members` covers all three binaries
# (buffr, buffr-app, buffr-helper), which the next step needs.
cargo build

# Run. The workspace has three binaries, so bare `cargo run` is
# ambiguous ("could not determine which binary to run") — name one.
# `buffr` is the supervisor; it finds `buffr-app` next to itself.
cargo run --bin buffr

# Or skip supervision and run the browser directly:
cargo run --bin buffr-app

Heads-up: cargo install buffr is not a supported install path. Every workspace member sets publish = false and the buffr name on crates.io is yanked, so there is nothing for cargo install to fetch. A CEF app also needs a large runtime payload next to the binary (libcef, .pak resources, locales, the sandbox helper) that cargo install has no way to place. Grab a prebuilt release from github.com/kryptic-sh/buffr/releases, or build from source as shown above.

See docs/site/dev.md for full prerequisites, platform matrix, and CEF path overrides.

Known limitations

• Image / multimedia clipboard paste is unsupported. Ctrl+V text paste works, but pasting images or other non-text clipboard content into web pages is a no-op. This is a CEF off-screen-rendering (OSR) limitation, not specific to buffr's implementation. Tracked in #19.

Contributing

There is no CONTRIBUTING.md yet — open an issue or a PR. Local gates before you push: cargo fmt --all, cargo clippy --all-targets -- -D warnings, cargo test. See docs/site/dev.md.

License

MIT. See LICENSE.