# buffr

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

[![CI](https://github.com/kryptic-sh/buffr/actions/workflows/ci.yml/badge.svg)](https://github.com/kryptic-sh/buffr/actions/workflows/ci.yml)
[![release](https://img.shields.io/github/v/release/kryptic-sh/buffr)](https://github.com/kryptic-sh/buffr/releases)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Website](https://img.shields.io/badge/website-kryptic.sh%2Fbuffr-7ee787)](https://www.kryptic.sh/buffr/)

Modal browser built on
[Chromium Embedded Framework](https://bitbucket.org/chromiumembedded/cef) via
the [`cef`](https://crates.io/crates/cef) Rust crate. Vim keybindings powered by
[hjkl-engine](https://crates.io/crates/hjkl-engine).

## Status

Pre-1.0, tagged releases on every version bump — the current version is whatever
the [latest release](https://github.com/kryptic-sh/buffr/releases/latest) 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](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:

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

## Install

**macOS (Homebrew)**

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

**Arch Linux (AUR)**

```bash
paru -S buffr-bin
```

Pre-built packages on every tag, on the
[releases page](https://github.com/kryptic-sh/buffr/releases):

| 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](#build) below.

## Build

```bash
# 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](https://github.com/kryptic-sh/buffr/releases),
> or build from source as shown above.

See [`docs/site/dev.md`](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](https://github.com/kryptic-sh/buffr/issues/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`](docs/site/dev.md).

## License

MIT. See [LICENSE](LICENSE).
