browser

Creates an offscreen Chromium browser and returns a Browser handle. The config table accepts width (default 800), height (default 600), url (default "about:blank"), and optionally html to load an inline HTML string instead of fetching a URL. The page renders into an internal BGRA pixel buffer that you read with get_pixels.

use plugin browser::{Browser}

let b = Browser.new(#{ width: 1280, height: 720, url: "https://example.com" })
print("created: {b.get_url()}")

Static method that pumps the CEF message loop once. Chromium does network, layout, and paint work inside this loop, so call it regularly (typically once per frame) or the page will never load or repaint.

use plugin browser::{Browser}

let b = Browser.new(#{ url: "https://example.com" })
while b.is_loading() {
  Browser.pump_messages()
}
print("loaded: {b.get_url()}")

Navigates the browser's main frame to url. Navigation is asynchronous — keep pumping messages and check is_loading to know when it finishes.

use plugin browser::{Browser}

let b = Browser.new(#{ width: 800, height: 600 })
b.load_url("https://zolo-lang.dev")

Reuse a single browser to visit several pages in sequence, draining the load between each:

use plugin browser::{Browser}

let b = Browser.new(#{ width: 1024, height: 768 })
for url in ["https://example.com", "https://zolo-lang.dev"] {
  b.load_url(url)
  while b.is_loading() {
    Browser.pump_messages()
  }
  print("loaded: {b.get_url()}")
}

Loads an HTML string directly into the main frame (internally encoded as a data:text/html URL). Useful for rendering generated UI without a web server.

use plugin browser::{Browser}

let b = Browser.new(#{ width: 640, height: 480 })
b.load_html("<h1 style='color: teal'>Hello from Zolo</h1>")

Returns the URL currently loaded in the main frame, or an empty string if no page is loaded yet.

use plugin browser::{Browser}

let b = Browser.new(#{ url: "https://example.com" })
print("current: {b.get_url()}")

Returns the current page title. Title tracking is not fully implemented yet, so this currently returns an empty string.

Goes back one entry in the browser's navigation history, if possible.

use plugin browser::{Browser}

let b = Browser.new(#{ url: "https://example.com" })
b.load_url("https://example.com/page2")
if b.can_navigate_back() {
  b.navigate_back()
}

Goes forward one entry in the navigation history, if possible.

Returns true if there is a previous entry in the navigation history.

Returns true if there is a next entry in the navigation history.

Reloads the current page.

use plugin browser::{Browser}

let b = Browser.new(#{ url: "https://example.com" })
b.reload()

Stops loading the current page, like pressing the browser's stop button.

Returns true while the page is still loading. Combine with pump_messages to wait for a page to finish.

use plugin browser::{Browser}

let b = Browser.new(#{ url: "https://example.com" })
while b.is_loading() {
  Browser.pump_messages()
}
print("done loading")

Pumps the message loop and returns the most recent rendered frame as raw BGRA bytes (width * height * 4), or nil if no frame has been painted yet. Upload the buffer to a GPU texture for offscreen rendering.

use plugin browser::{Browser}

let b = Browser.new(#{ width: 800, height: 600, url: "https://example.com" })
while b.is_loading() {
  Browser.pump_messages()
}
let pixels = b.get_pixels()
if pixels != nil {
  print("got frame: {pixels.len()} bytes")
}

After a resize, pump a few times so Chromium relayouts and repaints before reading the new-sized frame:

use plugin browser::{Browser}

let b = Browser.new(#{ width: 800, height: 600, url: "https://example.com" })
b.resize(1920, 1080)
for _ in 0..5 {
  Browser.pump_messages()
}
let frame = b.get_pixels()
print("hi-res frame: {frame.len()} bytes")

Returns the current viewport size as a table with width and height fields.

use plugin browser::{Browser}

let b = Browser.new(#{ width: 1024, height: 768 })
let size = b.get_size()
print("{size["width"]}x{size["height"]}")

Resizes the browser viewport. The page relayouts and subsequent get_pixels frames use the new dimensions.

use plugin browser::{Browser}

let b = Browser.new(#{ width: 800, height: 600 })
b.resize(1920, 1080)

Pauses or resumes offscreen rendering. While paused, new frames are not produced — useful to save CPU when the browser content is not visible.

use plugin browser::{Browser}

let b = Browser.new(#{ url: "https://example.com" })
b.set_rendering_paused(true)
print("paused: {b.is_rendering_paused()}")
b.set_rendering_paused(false)

Returns true if offscreen rendering is currently paused.

Executes a JavaScript string in the page's main frame. Fire-and-forget: the return value of the script is not propagated back to Zolo.

use plugin browser::{Browser}

let b = Browser.new(#{ url: "https://example.com" })
b.execute_js("document.body.style.background = 'black'")

Injects a mouse move event at viewport coordinates (x, y). Held buttons and modifier keys from previous inject calls are carried along, so move events during a press become drags.

use plugin browser::{Browser}

let b = Browser.new(#{ url: "https://example.com" })
b.inject_mouse_move(200, 150)

Injects a mouse button press at (x, y). button is "left", "right", or "middle" (defaults to "left"). The button stays held until a matching inject_mouse_up.

use plugin browser::{Browser}

let b = Browser.new(#{ url: "https://example.com" })
b.inject_mouse_down(200, 150, "left")
b.inject_mouse_up(200, 150, "left")

Injects a mouse button release at (x, y), completing a click started with inject_mouse_down.

Injects a mouse wheel event at (x, y) with horizontal delta dx and vertical delta dy (positive dy scrolls up).

use plugin browser::{Browser}

let b = Browser.new(#{ url: "https://example.com" })
b.inject_mouse_wheel(400, 300, 0, -120)

Injects a key press. key accepts winit-style names ("A", "Enter", "ArrowDown", "F5", "Shift", ...). Modifier keys (Shift, Control, Alt) stay held for subsequent events until released. Pressing "F12" is intercepted and toggles DevTools instead.

use plugin browser::{Browser}

let b = Browser.new(#{ url: "https://example.com" })
b.focus()
b.inject_key_down("Enter")
b.inject_key_up("Enter")

Modifier keys stay held until released, so you can build chords like Ctrl+A. Press the modifier first, the target key, then release in reverse order:

use plugin browser::{Browser}

let b = Browser.new(#{ url: "https://example.com" })
b.focus()
b.inject_key_down("Control")
b.inject_key_down("A")
b.inject_key_up("A")
b.inject_key_up("Control")

Injects a key release for key, clearing any modifier state it was holding.

Injects a character event for text input fields. For typing visible characters, send this between key down and key up, or use inject_text for whole strings.

use plugin browser::{Browser}

let b = Browser.new(#{ url: "https://example.com" })
b.focus()
b.inject_key_char("z")

Inserts an entire text string into the focused element via an IME commit. The simplest way to type into input fields.

use plugin browser::{Browser}

let b = Browser.new(#{ url: "https://example.com" })
b.focus()
b.inject_text("hello from zolo")

Gives keyboard focus to the browser so injected key and text events reach the page.

Returns true if the browser currently has focus (set via focus).

Mutes or unmutes all audio playing in the page.

use plugin browser::{Browser}

let b = Browser.new(#{ url: "https://example.com" })
b.set_muted(true)

Sets the page zoom level. 0.0 is the default zoom; each unit is roughly a 20% step (Chromium zoom-level semantics), so 1.0 zooms in and -1.0 zooms out.

use plugin browser::{Browser}

let b = Browser.new(#{ url: "https://example.com" })
b.set_zoom_level(1.0)
print("zoom: {b.get_zoom_level()}")

Negative levels zoom out, and 0.0 resets to the default — handy for fitting more content into a fixed-size offscreen surface:

use plugin browser::{Browser}

let b = Browser.new(#{ url: "https://example.com" })
b.set_zoom_level(-2.0)
print("zoomed out to {b.get_zoom_level()}")
b.set_zoom_level(0.0)

Returns the current zoom level (0.0 is the default).

Opens the Chromium DevTools in a separate window attached to this browser.

use plugin browser::{Browser}

let b = Browser.new(#{ url: "https://example.com" })
b.open_devtools()

Closes the DevTools window if it is open.

Opens DevTools if closed, closes it if open. Equivalent to injecting an "F12" key press.

Returns true if a DevTools window is currently open for this browser.

use plugin browser::{Browser}

let b = Browser.new(#{ url: "https://example.com" })
b.toggle_devtools()
print("devtools open: {b.has_devtools()}")

Destroys the browser instance and releases its handle. The handle becomes invalid; any further method calls on it will error. Browsers are also cleaned up automatically when garbage collected.

use plugin browser::{Browser}

let b = Browser.new(#{ url: "https://example.com" })
b.close()