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//! | [`manifest`] | Optional TOML app manifests (name, version, declared permissions) |
50//! | [`media_capture`] | Camera, microphone, and screen capture with permission prompts |
51//! | [`rtc`] | WebRTC peer connections, data channels, media tracks, and signaling |
52//! | [`websocket`] | WebSocket client connections (text/binary frames, ready-state polling) |
53//! | [`worker`] | Background WASM workers with isolated fuel/memory and message passing |
54//! | [`midi`] | MIDI input/output device enumeration and I/O (CoreMIDI on macOS) |
55//! | [`navigation`] | Browser history stack with back/forward traversal |
56//! | [`permissions`] | Per-origin grants for sensitive APIs (camera, microphone, geolocation, screen capture) |
57//! | [`bookmarks`] | Persistent bookmark storage backed by sled |
58//! | [`url`] | WHATWG-compliant URL parsing with Oxide-specific schemes |
59//! | [`ui`] | GPUI desktop shell (toolbar, canvas, console, tabs) |
60//!
61//! ## Which API do I need?
62//!
63//! | You are building… | Use this crate | Notes |
64//! |---|---|---|
65//! | A **guest** `.wasm` app (canvas, fetch, widgets) | **`oxide-sdk` only** | Import `oxide::*` via the SDK; you never link `oxide-browser`. |
66//! | The **stock desktop browser** binary | **`cargo run -p oxide-browser`** | The `oxide` binary wires [`runtime::BrowserHost`] to [`ui::run_browser`]. |
67//! | 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. |
68//! | **GPU/UI work** next to Oxide (panels, overlays, devtools) | [`gpui`] | Re-export of [GPUI](https://www.gpui.rs/); version matches this crate’s dependency. |
69//!
70//! ### Relationship between GPUI and the SDK
71//!
72//! Guest `.wasm` modules cannot link GPUI directly (it requires native GPU
73//! access). Instead, the `oxide-sdk` crate provides drawing functions that
74//! the host translates into GPUI primitives each frame:
75//!
76//! - `canvas_rect` → `Window::paint_quad` with `gpui::fill`
77//! - `canvas_circle` → `Window::paint_path` with polygon approximation
78//! - `canvas_text` → GPU text shaping via `Window::text_system().shape_line`
79//! - `canvas_line` → `Window::paint_path` with `PathBuilder::stroke`
80//! - `canvas_image` → `Window::paint_image` with `RenderImage` texture cache
81//!
82//! The `oxide_sdk::draw` module provides higher-level types (`Canvas`,
83//! `Color`, `Rect`, `Point2D`) modelled after GPUI conventions.
84//!
85//! ### Host entrypoints (Rust)
86//!
87//! - **[`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`].
88//! - **`gpui`** — Full GPUI API for native code that ships beside the browser (not available inside guest wasm).
89//!
90//! ## Security Model
91//!
92//! Every guest `.wasm` module runs in a strict sandbox:
93//!
94//! - **No filesystem access** — guests cannot read or write host files
95//! - **No environment variables** — guests cannot inspect the host environment
96//! - **No raw sockets** — all network access is mediated through `fetch`
97//! - **Bounded memory** — 256 MB (4096 pages) hard limit
98//! - **Fuel metering** — 500M instruction budget prevents infinite loops
99//! - **Capability-based I/O** — only explicitly provided `oxide::*` functions
100//!   are available to the guest
101
102pub mod audio_format;
103pub mod bookmarks;
104pub mod capabilities;
105pub mod download;
106pub mod engine;
107pub mod events;
108pub mod fetch;
109pub mod file_picker;
110pub mod forge;
111pub mod forge_config;
112pub mod gpu;
113pub mod history;
114pub mod manifest;
115pub mod media_capture;
116pub mod midi;
117pub mod navigation;
118pub mod permissions;
119pub mod rtc;
120pub mod runtime;
121pub mod subtitle;
122pub mod ui;
123pub mod url;
124pub mod video;
125pub mod video_format;
126pub mod websocket;
127pub mod worker;
128
129/// GPU-accelerated UI framework used by the desktop shell (see [GPUI](https://www.gpui.rs/)).
130///
131/// Depend on `oxide-browser` and `use oxide_browser::gpui` so your native tooling stays on the same
132/// GPUI version as the browser. Guest WebAssembly modules cannot use this crate; they use the
133/// [`oxide-sdk`](https://docs.rs/oxide-sdk) crate instead.
134pub use gpui;
oxide_browser/lib.rs

oxide_browser/
lib.rs
