guise/
webview.rs

1//! `WebView` — a native web view embedded in a gpui window (stateful entity).
2//!
3//! Backed by [`wry`](https://crates.io/crates/wry), which parents a real OS
4//! web view (WKWebView on macOS, WebView2 on Windows, WebKitGTK on Linux) as a
5//! child of the gpui window. The native view is positioned every frame to track
6//! the bounds of this component, so it composes inside normal `guise` layout.
7//!
8//! Create with `cx.new(|cx| WebView::new(cx).url("https://example.com"))` and
9//! subscribe for [`WebViewEvent`]s. Because the underlying view owns OS
10//! resources, it is built lazily on first render (when a window handle exists).
11//!
12//! The native backend lives behind the default-on `webview` feature. Disable it
13//! (`default-features = false`) for headless or docs-only builds; the component
14//! then renders a themed placeholder while keeping the same public API.
15
16use gpui::prelude::*;
17use gpui::{div, px, Context, EventEmitter, FocusHandle, IntoElement, SharedString, Window};
18
19use crate::devtools::Probed;
20use crate::theme::{theme, Size};
21
22#[cfg(feature = "webview")]
23use {
24  gpui::{canvas, Bounds, Pixels},
25  std::{cell::RefCell, rc::Rc, time::Duration},
26  wry::{
27    dpi::{LogicalPosition, LogicalSize},
28    PageLoadEvent, Rect, WebViewBuilder,
29  },
30};
31
32/// Emitted as the embedded page loads and changes.
33#[derive(Debug, Clone)]
34pub enum WebViewEvent {
35  /// The document title changed. Carries the new title.
36  TitleChanged(SharedString),
37  /// The view navigated to a new URL. Carries the destination.
38  UrlChanged(SharedString),
39  /// A page began loading.
40  LoadStarted,
41  /// A page finished loading.
42  LoadFinished,
43  /// The page posted a message to the host via `window.ipc.postMessage(...)`.
44  /// Carries the raw string payload; the host decides how to interpret it.
45  Message(SharedString),
46}
47
48/// What the view should display.
49#[derive(Clone)]
50enum Source {
51  /// Nothing requested yet.
52  Empty,
53  /// Load a remote or local URL.
54  Url(SharedString),
55  /// Load an inline HTML string.
56  Html(SharedString),
57}
58
59/// A native web view. Create with `cx.new(|cx| WebView::new(cx))`.
60pub struct WebView {
61  source: Source,
62  focus: FocusHandle,
63  radius: Option<Size>,
64  bordered: bool,
65  transparent: bool,
66  width: Option<f32>,
67  height: Option<f32>,
68  /// JavaScript injected at document start (before page scripts run). Hosts
69  /// use it to expose a native API the page can call via
70  /// `window.ipc.postMessage(...)`. Only applied when the `webview` feature is
71  /// on; the placeholder ignores it.
72  #[cfg_attr(not(feature = "webview"), allow(dead_code))]
73  init_script: Option<SharedString>,
74  /// A directory served over an internal `guise://` origin (see [`WebView::serve`]).
75  #[cfg_attr(not(feature = "webview"), allow(dead_code))]
76  serve_dir: Option<std::path::PathBuf>,
77
78  #[cfg(feature = "webview")]
79  inner: Option<Rc<wry::WebView>>,
80  #[cfg(feature = "webview")]
81  queue: Rc<RefCell<Vec<WebViewEvent>>>,
82  #[cfg(feature = "webview")]
83  draining: bool,
84}
85
86impl EventEmitter<WebViewEvent> for WebView {}
87
88impl WebView {
89  pub fn new(cx: &mut Context<Self>) -> Self {
90    WebView {
91      source: Source::Empty,
92      focus: cx.focus_handle(),
93      radius: None,
94      bordered: true,
95      transparent: false,
96      width: None,
97      height: None,
98      init_script: None,
99      serve_dir: None,
100
101      #[cfg(feature = "webview")]
102      inner: None,
103      #[cfg(feature = "webview")]
104      queue: Rc::new(RefCell::new(Vec::new())),
105      #[cfg(feature = "webview")]
106      draining: false,
107    }
108  }
109
110  /// Inject JavaScript that runs at document start, before the page's own
111  /// scripts. Combined with [`WebViewEvent::Message`] (delivered when the page
112  /// calls `window.ipc.postMessage(str)`), this lets a host expose a native
113  /// API to the embedded page. No-op under the placeholder build.
114  pub fn init_script(mut self, js: impl Into<SharedString>) -> Self {
115    self.init_script = Some(js.into());
116    self
117  }
118
119  /// Load a URL (`https://…`, `file://…`, etc.).
120  pub fn url(mut self, url: impl Into<SharedString>) -> Self {
121    self.source = Source::Url(url.into());
122    self
123  }
124
125  /// Load an inline HTML document.
126  pub fn html(mut self, html: impl Into<SharedString>) -> Self {
127    self.source = Source::Html(html.into());
128    self
129  }
130
131  /// Serve files from `dir` over an internal `guise://localhost/` origin and
132  /// load `entry` from it. Prefer this over a `file://` [`WebView::url`] for
133  /// local content: `file://` pages are treated as an opaque/null origin, so
134  /// the JS bridge (`window.ipc.postMessage`) is dropped and ES modules /
135  /// `fetch` are blocked. A real origin fixes both.
136  pub fn serve(mut self, dir: impl Into<std::path::PathBuf>, entry: impl AsRef<str>) -> Self {
137    self.serve_dir = Some(dir.into());
138    self.source = Source::Url(
139      format!(
140        "guise://localhost/{}",
141        entry.as_ref().trim_start_matches('/')
142      )
143      .into(),
144    );
145    self
146  }
147
148  /// Override the corner radius (defaults to the theme radius).
149  pub fn radius(mut self, radius: Size) -> Self {
150    self.radius = Some(radius);
151    self
152  }
153
154  /// Draw a border + rounded frame around the view (default `true`).
155  pub fn bordered(mut self, bordered: bool) -> Self {
156    self.bordered = bordered;
157    self
158  }
159
160  /// Let the page background show through (default `false`).
161  pub fn transparent(mut self, transparent: bool) -> Self {
162    self.transparent = transparent;
163    self
164  }
165
166  /// Fix the width in pixels. Defaults to filling the parent.
167  pub fn width(mut self, width: f32) -> Self {
168    self.width = Some(width);
169    self
170  }
171
172  /// Fix the height in pixels. Defaults to filling the parent.
173  pub fn height(mut self, height: f32) -> Self {
174    self.height = Some(height);
175    self
176  }
177
178  /// Navigate the live view to `url`, updating the stored source.
179  pub fn load_url(&mut self, url: impl Into<SharedString>, cx: &mut Context<Self>) {
180    let url = url.into();
181    #[cfg(feature = "webview")]
182    if let Some(inner) = &self.inner {
183      let _ = inner.load_url(&url);
184    }
185    self.source = Source::Url(url);
186    cx.notify();
187  }
188
189  /// Replace the live view with inline HTML, updating the stored source.
190  pub fn load_html(&mut self, html: impl Into<SharedString>, cx: &mut Context<Self>) {
191    let html = html.into();
192    #[cfg(feature = "webview")]
193    if let Some(inner) = &self.inner {
194      let _ = inner.load_html(&html);
195    }
196    self.source = Source::Html(html);
197    cx.notify();
198  }
199
200  /// Run JavaScript in the live view. No-op until the view exists.
201  pub fn evaluate_script(&self, _js: &str) {
202    #[cfg(feature = "webview")]
203    if let Some(inner) = &self.inner {
204      let _ = inner.evaluate_script(_js);
205    }
206  }
207
208  /// Show or hide the native surface. The surface tracks its layout bounds only
209  /// while it is painted, so a host that stops rendering this view (e.g. a
210  /// collapsed drawer or a hidden tab) must hide it explicitly — otherwise the
211  /// OS view lingers on screen at its last position. A painted view re-shows
212  /// itself. No-op until the view exists.
213  pub fn set_visible(&mut self, _visible: bool) {
214    #[cfg(feature = "webview")]
215    if let Some(inner) = &self.inner {
216      let _ = inner.set_visible(_visible);
217    }
218  }
219
220  /// Build the native view once a window handle is available, then start the
221  /// loop that drains events from the wry handlers back onto the entity.
222  #[cfg(feature = "webview")]
223  fn ensure_view(&mut self, window: &mut Window, cx: &mut Context<Self>, bounds: Bounds<Pixels>) {
224    if self.inner.is_some() {
225      return;
226    }
227
228    let queue = self.queue.clone();
229    let (q_title, q_nav, q_load, q_ipc) =
230      (queue.clone(), queue.clone(), queue.clone(), queue.clone());
231
232    let mut builder = WebViewBuilder::new()
233      .with_bounds(rect_from(bounds))
234      .with_transparent(self.transparent)
235      .with_document_title_changed_handler(move |title| {
236        q_title
237          .borrow_mut()
238          .push(WebViewEvent::TitleChanged(title.into()));
239      })
240      .with_navigation_handler(move |url| {
241        q_nav
242          .borrow_mut()
243          .push(WebViewEvent::UrlChanged(url.into()));
244        true
245      })
246      .with_on_page_load_handler(move |event, _url| {
247        q_load.borrow_mut().push(match event {
248          PageLoadEvent::Started => WebViewEvent::LoadStarted,
249          PageLoadEvent::Finished => WebViewEvent::LoadFinished,
250        });
251      })
252      // JS -> native: `window.ipc.postMessage(str)` in the page lands here.
253      .with_ipc_handler(move |req| {
254        q_ipc
255          .borrow_mut()
256          .push(WebViewEvent::Message(req.into_body().into()));
257      });
258
259    if let Some(js) = &self.init_script {
260      builder = builder.with_initialization_script(js.to_string());
261    }
262
263    // Serve `serve_dir` over the `guise://` scheme used by `WebView::serve`.
264    if let Some(dir) = self.serve_dir.clone() {
265      builder = builder.with_custom_protocol("guise".to_string(), move |_id, request| {
266        serve_local(&dir, request.uri().path())
267      });
268    }
269
270    builder = match &self.source {
271      Source::Url(url) => builder.with_url(url.as_ref()),
272      Source::Html(html) => builder.with_html(html.as_ref()),
273      Source::Empty => builder,
274    };
275
276    match builder.build_as_child(&*window) {
277      Ok(view) => self.inner = Some(Rc::new(view)),
278      Err(err) => {
279        eprintln!("guise: failed to create webview: {err}");
280        return;
281      }
282    }
283
284    if !self.draining {
285      self.draining = true;
286      cx.spawn(async move |this, cx| loop {
287        cx.background_executor()
288          .timer(Duration::from_millis(40))
289          .await;
290        let drained: Vec<WebViewEvent> = queue.borrow_mut().drain(..).collect();
291        let pushed = this.update(cx, |_this, cx| {
292          let any = !drained.is_empty();
293          for event in drained {
294            cx.emit(event);
295          }
296          if any {
297            cx.notify();
298          }
299        });
300        if pushed.is_err() {
301          break;
302        }
303      })
304      .detach();
305    }
306  }
307}
308
309#[cfg(feature = "webview")]
310fn rect_from(bounds: Bounds<Pixels>) -> Rect {
311  Rect {
312    position: LogicalPosition::new(bounds.origin.x.to_f64(), bounds.origin.y.to_f64()).into(),
313    size: LogicalSize::new(bounds.size.width.to_f64(), bounds.size.height.to_f64()).into(),
314  }
315}
316
317impl Render for WebView {
318  #[cfg(feature = "webview")]
319  fn render(&mut self, window: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
320    // Build the native view on the first frame that has a window handle.
321    // It is created at a best-guess size; the `canvas` paint below snaps it
322    // to the real layout bounds on this same frame.
323    if self.inner.is_none() {
324      let w = self.width.unwrap_or(800.0);
325      let h = self.height.unwrap_or(600.0);
326      let initial = Bounds {
327        origin: gpui::point(px(0.0), px(0.0)),
328        size: gpui::size(px(w), px(h)),
329      };
330      self.ensure_view(window, cx, initial);
331    }
332
333    let t = theme(cx);
334    let radius = t.radius(self.radius.unwrap_or(t.default_radius));
335    let border = t.border().hsla();
336    let bg = t.surface().hsla();
337
338    // Sized region the native view tracks. `canvas` hands us the painted
339    // bounds in window coordinates each frame; we forward them to wry.
340    let view = self.inner.clone();
341    let surface = canvas(
342      move |_bounds, _window, _app| {},
343      move |bounds, _state, _window, _app| {
344        if let Some(view) = &view {
345          let _ = view.set_bounds(rect_from(bounds));
346          // Being painted means we're on screen; re-assert visibility so
347          // a view that was hidden while unmounted shows again.
348          let _ = view.set_visible(true);
349        }
350      },
351    )
352    .size_full();
353
354    frame(self.bordered, radius, border, bg, self.width, self.height)
355      .track_focus(&self.focus)
356      .child(surface)
357      .probe("WebView")
358  }
359
360  #[cfg(not(feature = "webview"))]
361  fn render(&mut self, _window: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
362    let t = theme(cx);
363    let radius = t.radius(self.radius.unwrap_or(t.default_radius));
364    let border = t.border().hsla();
365    let bg = t.surface().hsla();
366    let dimmed = t.dimmed().hsla();
367    let label = match &self.source {
368      Source::Url(url) => url.clone(),
369      Source::Html(html) => SharedString::from(format!("inline HTML ({} bytes)", html.len())),
370      Source::Empty => SharedString::from("no source"),
371    };
372
373    frame(self.bordered, radius, border, bg, self.width, self.height)
374      .track_focus(&self.focus)
375      .items_center()
376      .justify_center()
377      .text_color(dimmed)
378      .child(SharedString::from(format!("WebView (disabled): {label}")))
379      .probe("WebView")
380      .attr("source", label)
381  }
382}
383
384/// The themed container shared by both render paths.
385fn frame(
386  bordered: bool,
387  radius: f32,
388  border: gpui::Hsla,
389  bg: gpui::Hsla,
390  width: Option<f32>,
391  height: Option<f32>,
392) -> gpui::Stateful<gpui::Div> {
393  let mut root = div().id("guise-webview").flex().overflow_hidden().bg(bg);
394  root = match width {
395    Some(w) => root.w(px(w)),
396    None => root.w_full(),
397  };
398  root = match height {
399    Some(h) => root.h(px(h)),
400    None => root.h_full(),
401  };
402  if bordered {
403    root = root.border_1().border_color(border).rounded(px(radius));
404  }
405  root
406}
407
408/// Serve a file from `dir` for a `guise://localhost/<path>` request. Rejects
409/// paths that try to escape `dir`; unknown files return 404.
410#[cfg(feature = "webview")]
411fn serve_local(
412  dir: &std::path::Path,
413  url_path: &str,
414) -> wry::http::Response<std::borrow::Cow<'static, [u8]>> {
415  use std::borrow::Cow;
416  use wry::http::{Response, StatusCode};
417
418  // Built by hand rather than through `Response::builder().….unwrap()`:
419  // this runs on wry's request thread, where a panic takes the process with
420  // it, and there is no reason for serving a static 404 to be fallible.
421  let not_found = || {
422    let mut response = Response::new(Cow::Borrowed(&b"not found"[..]));
423    *response.status_mut() = StatusCode::NOT_FOUND;
424    response
425  };
426
427  let rel = url_path.trim_start_matches('/');
428  let rel = if rel.is_empty() { "index.html" } else { rel };
429  // No traversal or absolute escapes; only simple forward paths.
430  if rel
431    .split('/')
432    .any(|c| c.is_empty() || c == "." || c == "..")
433  {
434    return not_found();
435  }
436  match std::fs::read(dir.join(rel)) {
437    Ok(bytes) => {
438      let mut response = Response::new(Cow::Owned(bytes));
439      // Both header values are crate constants, so neither can fail to
440      // parse; inserting them directly keeps that fact local.
441      let headers = response.headers_mut();
442      headers.insert(
443        wry::http::header::CONTENT_TYPE,
444        wry::http::HeaderValue::from_static(content_type(rel)),
445      );
446      headers.insert(
447        wry::http::header::ACCESS_CONTROL_ALLOW_ORIGIN,
448        wry::http::HeaderValue::from_static("*"),
449      );
450      response
451    }
452    Err(_) => not_found(),
453  }
454}
455
456/// A best-effort content type from a file's extension.
457#[cfg(feature = "webview")]
458fn content_type(rel: &str) -> &'static str {
459  match rel.rsplit('.').next() {
460    Some("html" | "htm") => "text/html; charset=utf-8",
461    Some("js" | "mjs") => "text/javascript; charset=utf-8",
462    Some("css") => "text/css; charset=utf-8",
463    Some("json") => "application/json; charset=utf-8",
464    Some("svg") => "image/svg+xml",
465    Some("png") => "image/png",
466    Some("jpg" | "jpeg") => "image/jpeg",
467    Some("gif") => "image/gif",
468    Some("webp") => "image/webp",
469    Some("ico") => "image/x-icon",
470    Some("woff2") => "font/woff2",
471    Some("woff") => "font/woff",
472    Some("ttf") => "font/ttf",
473    Some("wasm") => "application/wasm",
474    Some("map") => "application/json; charset=utf-8",
475    _ => "application/octet-stream",
476  }
477}
guise/webview.rs

guise/
webview.rs
