oxide_browser/lib.rs
1//! # Oxide Browser — Host Runtime
2//!
3//! `oxide-browser` is the native desktop host application for the
4//! [Oxide browser](https://github.com/niklabh/oxide), a **binary-first browser**
5//! that fetches and executes `.wasm` (WebAssembly) modules instead of
6//! HTML/JavaScript.
7//!
8//! ## Architecture
9//!
10//! ```text
11//! ┌──────────────────────────────────────────────────┐
12//! │ Oxide Browser │
13//! │ ┌──────────┐ ┌────────────┐ ┌──────────────┐ │
14//! │ │ URL Bar │ │ Canvas │ │ Console │ │
15//! │ └────┬─────┘ └──────┬─────┘ └──────┬───────┘ │
16//! │ │ │ │ │
17//! │ ┌────▼───────────────▼───────────────▼───────┐ │
18//! │ │ Host Runtime │ │
19//! │ │ wasmtime engine + sandbox policy │ │
20//! │ │ fuel limit: 500M │ memory: 16MB max │ │
21//! │ └────────────────────┬───────────────────────┘ │
22//! │ │ │
23//! │ ┌────────────────────▼───────────────────────┐ │
24//! │ │ Capability Provider │ │
25//! │ │ "oxide" import module │ │
26//! │ │ canvas, console, storage, clipboard, │ │
27//! │ │ fetch, images, crypto, base64, protobuf, │ │
28//! │ │ dynamic module loading, audio, timers, │ │
29//! │ │ navigation, widgets, input, hyperlinks │ │
30//! │ └────────────────────┬───────────────────────┘ │
31//! │ │ │
32//! │ ┌────────────────────▼───────────────────────┐ │
33//! │ │ Guest .wasm Module │ │
34//! │ │ exports: start_app(), on_frame(dt_ms) │ │
35//! │ │ imports: oxide::* │ │
36//! │ └────────────────────────────────────────────┘ │
37//! └──────────────────────────────────────────────────┘
38//! ```
39//!
40//! ## Modules
41//!
42//! | Module | Purpose |
43//! |--------|---------|
44//! | [`engine`] | Wasmtime engine configuration, sandbox policy, memory bounds |
45//! | [`runtime`] | Module fetching, compilation, execution lifecycle |
46//! | [`capabilities`] | All host-imported functions exposed to guest wasm modules |
47//! | [`navigation`] | Browser history stack with back/forward traversal |
48//! | [`bookmarks`] | Persistent bookmark storage backed by sled |
49//! | [`url`] | WHATWG-compliant URL parsing with Oxide-specific schemes |
50//! | [`ui`] | egui/eframe desktop UI (toolbar, canvas, console, tabs) |
51//!
52//! ## Security Model
53//!
54//! Every guest `.wasm` module runs in a strict sandbox:
55//!
56//! - **No filesystem access** — guests cannot read or write host files
57//! - **No environment variables** — guests cannot inspect the host environment
58//! - **No raw sockets** — all network access is mediated through `fetch`
59//! - **Bounded memory** — 16 MB (256 pages) hard limit
60//! - **Fuel metering** — 500M instruction budget prevents infinite loops
61//! - **Capability-based I/O** — only explicitly provided `oxide::*` functions
62//! are available to the guest
63
64pub mod bookmarks;
65pub mod capabilities;
66pub mod engine;
67pub mod navigation;
68pub mod runtime;
69pub mod ui;
70pub mod url;