Development

Development

Build it, test it, bench it, debug it, release it.

Build

git clone https://github.com/slabbdev/navette && cd navette
cargo build --release
./target/release/navette --version

• macOS: fully shipped (WKWebView via raw objc2).
• Windows: WebView2 backend (rustup-msvc + VS Build Tools with the C++ linker; WebView2 runtime preinstalled on Win10/11).
• Linux: WebKitGTK backend — sudo apt install libwebkit2gtk-4.1-dev libgtk-3-dev glib-networking (Ubuntu 24.04); run under xvfb headless.
• Other targets: backend_stub.rs placeholder compiles against the same kit contract — a backend missing a primitive won't build (Architecture).

Quick smoke:

./target/release/navette serve --port 8791 &        # scratch port — never assume 8765 is free
curl -s http://127.0.0.1:8791/health                # {"ok":true,"name":"navette","engine":"…"}
./target/release/navette serve --port 8792 &        # second daemon for isolation tests
curl -s -X POST http://127.0.0.1:8791/navigate -H 'Content-Type: application/json' \
     -d '{"url":"file:///…/test/page.html","with_content":true}'

test/page.html and test/smoke-page.html are the local fixtures.

Repo layout

src/              the daemon + MCP adapter + backends (see Architecture)
sites/            per-site memory: recipe.md + pages/ (see Site Recipes)
demo/             live-run demos with committed artifacts (see Demos)
bench/            benches + datasets: bench.py, cdp_raw.py, tollbooth.py, navbench.py, recipe/
integrations/     n8n community node (zero dependencies)
plugins/          local chat plugin + local marketplace manifest
docker/           container image + entrypoint
docs/             SECURITY.md, debug-vm.md, mcp-registry.md, site sources
test/             page fixtures

Conventions

• Repo artifacts are 100% English — docs, commits, scripts, quoted strings included.
• Claims are measured or they don't ship: benchmarks get tables, gaps get issues (Roadmap and Known Gaps).
• A pass that teaches navette something new ends with the recipe updated and committed — an uncommitted update is a lost pass (Site Recipes).
• The n8n node keeps its dependencies object empty on purpose.

CI

Workflows in .github/workflows/:

Workflow	What it does
ci.yml	build + test on all three OSes (macOS/WKWebView, Windows/WebView2, Linux/WebKitGTK) — includes the session-isolation assertion: a cross-session cookie leak fails the build
bench.yml	cross-engine medians (bench/bench.py, 30-page corpus, warm loop) — re-run with gh workflow run bench
ci-race.yml	the cold-runner race: navette (built from source, 4-min cold-boot window) vs Playwright on fresh Actions runners; per-failure forensics
docker.yml	builds/publishes ghcr.io/slabbdev/navette (amd64 + arm64)
release.yml	native per-arch release binaries
debug.yml / debug-auto.yml	crash-diagnosis runs for the non-macOS backends

CI lessons baked into the codebase: 38 s cold boots are the known constant (issue #9 — release assets freeze before the listener binds; CI builds from source); never issue two navigations back to back on the wry event loop (issue #10); the language-install form's synthetic submit click doesn't fire on runners — go straight to ?step=1.

Debugging native crashes (VM kit)

docs/debug-vm.md is the kit for the two remaining native crashes — Linux GTK/WebKit segfault ~10 s after boot, Windows WebView2 crash during navigation:

# Linux (Ubuntu 24.04): gdb, stop on SIGSEGV, backtrace names the guilty frame
gdb -ex 'handle SIGSEGV stop nopass' -ex run -ex bt --args \
  ./target/release/navette serve --port 8765
# trigger: serve a local corpus page, navigate, sleep 12 — the backtrace is the fix-identifying data

Windows: RUST_BACKTRACE=1 navette.exe serve --port 8765 > serve.log 2>&1 + navigate/read from a second terminal — the create_session breadcrumbs in serve.log show the last step reached. What to look for: the frame inside libwebkit2gtk/libgtk (WebKit side) or WebView2Loader/msedgewebview2 (COM side). Each backtrace becomes an issue with the exact data.

Benching

python3 bench/bench.py          # same-machine medians (static / JS-heavy / SPA)
python3 bench/cdp_raw.py        # zero-bias raw-CDP probe
python3 bench/tollbooth.py      # walled-web dataset (CC BY 4.0)
bash bench/recipe/bench-notifications.sh   # recipe-vs-cold replay, one shot

Protocol: same machine, same page set, medians over repeated runs; RAM = peak of the whole process tree. Numbers land in Benchmarks or they don't exist.

Releasing

1. Bump Cargo.toml and server.json (same value).
2. Tag → release.yml builds native per-arch binaries; docker.yml publishes the image.
3. MCP registry: mcp-publisher publish (authenticated as the repo owner; see docs/mcp-registry.md).
4. Release notes carry the honest table: what shipped, what didn't, what got measured.