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: 256MB 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//! │ │ GPU/WebGPU-style resource management │ │
31//! │ └────────────────────┬───────────────────────┘ │
32//! │ │ │
33//! │ ┌────────────────────▼───────────────────────┐ │
34//! │ │ Guest .wasm Module │ │
35//! │ │ exports: start_app(), on_frame(dt_ms) │ │
36//! │ │ imports: oxide::* │ │
37//! │ └────────────────────────────────────────────┘ │
38//! └──────────────────────────────────────────────────┘
39//! ```
40//!
41//! ## Modules
42//!
43//! | Module | Purpose |
44//! |--------|---------|
45//! | [`engine`] | Wasmtime engine configuration, sandbox policy, memory bounds |
46//! | [`runtime`] | Module fetching, compilation, execution lifecycle |
47//! | [`capabilities`] | All host-imported functions exposed to guest wasm modules |
48//! | [`gpu`] | WebGPU-style GPU resource management (buffers, textures, shaders, pipelines) |
49//! | [`media_capture`] | Camera, microphone, and screen capture with permission prompts |
50//! | [`rtc`] | WebRTC peer connections, data channels, media tracks, and signaling |
51//! | [`websocket`] | WebSocket client connections (text/binary frames, ready-state polling) |
52//! | [`midi`] | MIDI input/output device enumeration and I/O (CoreMIDI on macOS) |
53//! | [`navigation`] | Browser history stack with back/forward traversal |
54//! | [`bookmarks`] | Persistent bookmark storage backed by sled |
55//! | [`url`] | WHATWG-compliant URL parsing with Oxide-specific schemes |
56//! | [`ui`] | GPUI desktop shell (toolbar, canvas, console, tabs) |
57//!
58//! ## Which API do I need?
59//!
60//! | You are building… | Use this crate | Notes |
61//! |---|---|---|
62//! | A **guest** `.wasm` app (canvas, fetch, widgets) | **`oxide-sdk` only** | Import `oxide::*` via the SDK; you never link `oxide-browser`. |
63//! | The **stock desktop browser** binary | **`cargo run -p oxide-browser`** | The `oxide` binary wires [`runtime::BrowserHost`] to [`ui::run_browser`]. |
64//! | A **custom native shell** (alternate windowing, tests, automation) | [`ui::run_browser`] + [`runtime::BrowserHost`] | Same [`capabilities::HostState`] pipeline; swap or wrap the GPUI window if needed. |
65//! | **GPU/UI work** next to Oxide (panels, overlays, devtools) | [`gpui`] | Re-export of [GPUI](https://www.gpui.rs/); version matches this crate’s dependency. |
66//!
67//! ### Relationship between GPUI and the SDK
68//!
69//! Guest `.wasm` modules cannot link GPUI directly (it requires native GPU
70//! access). Instead, the `oxide-sdk` crate provides drawing functions that
71//! the host translates into GPUI primitives each frame:
72//!
73//! - `canvas_rect` → `Window::paint_quad` with `gpui::fill`
74//! - `canvas_circle` → `Window::paint_path` with polygon approximation
75//! - `canvas_text` → GPU text shaping via `Window::text_system().shape_line`
76//! - `canvas_line` → `Window::paint_path` with `PathBuilder::stroke`
77//! - `canvas_image` → `Window::paint_image` with `RenderImage` texture cache
78//!
79//! The `oxide_sdk::draw` module provides higher-level types (`Canvas`,
80//! `Color`, `Rect`, `Point2D`) modelled after GPUI conventions.
81//!
82//! ### Host entrypoints (Rust)
83//!
84//! - **[`ui::run_browser`]** — Blocks on the GPUI event loop and opens the main Oxide window. Pass the shared [`capabilities::HostState`] and [`runtime::PageStatus`] from a [`runtime::BrowserHost`].
85//! - **`gpui`** — Full GPUI API for native code that ships beside the browser (not available inside guest wasm).
86//!
87//! ## Security Model
88//!
89//! Every guest `.wasm` module runs in a strict sandbox:
90//!
91//! - **No filesystem access** — guests cannot read or write host files
92//! - **No environment variables** — guests cannot inspect the host environment
93//! - **No raw sockets** — all network access is mediated through `fetch`
94//! - **Bounded memory** — 256 MB (4096 pages) hard limit
95//! - **Fuel metering** — 500M instruction budget prevents infinite loops
96//! - **Capability-based I/O** — only explicitly provided `oxide::*` functions
97//! are available to the guest
98
99pub mod audio_format;
100pub mod bookmarks;
101pub mod capabilities;
102pub mod download;
103pub mod engine;
104pub mod events;
105pub mod fetch;
106pub mod file_picker;
107pub mod forge;
108pub mod forge_config;
109pub mod gpu;
110pub mod history;
111pub mod media_capture;
112pub mod midi;
113pub mod navigation;
114pub mod rtc;
115pub mod runtime;
116pub mod subtitle;
117pub mod ui;
118pub mod url;
119pub mod video;
120pub mod video_format;
121pub mod websocket;
122
123/// GPU-accelerated UI framework used by the desktop shell (see [GPUI](https://www.gpui.rs/)).
124///
125/// Depend on `oxide-browser` and `use oxide_browser::gpui` so your native tooling stays on the same
126/// GPUI version as the browser. Guest WebAssembly modules cannot use this crate; they use the
127/// [`oxide-sdk`](https://docs.rs/oxide-sdk) crate instead.
128pub use gpui;