Skip to content

WebView bridge

Each WebView has its own bridge. The page uses the global revo object, while the client script uses its WebView instance.

Direction Events Requests
Page → client revo.emit() → view.on() revo.fetch() → view.onRequest()
Client → page view.emit() → revo.on() view.fetch() → revo.onRequest()

Events deliver arguments to listeners. Use a request when the caller needs a result or an error. A request handler can return a value or a promise.

This example reads the local player’s health and armor once when the page starts. Put these files under ui/ in the client resource bundle, as described in Create a WebView.

Create ui/status.html:

ui/status.html
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>Player status</title>
<style>
body { margin: 24px; color: white; background: transparent; font: 18px sans-serif; }
</style>
</head>
<body>
<p id="status">Loading player status...</p>
<script type="module" src="./status.js"></script>
</body>
</html>

Create the WebView and register its request handler in the client script:

Client
// @ts-check
/// <reference types="@revomp/types-client" />
import * as revo from 'revo-client';
const view = new revo.WebView('resources://ui/status.html');
view.onRequest('player:status', () => {
const player = revo.Player.local;
return { health: player.health, armor: player.armor };
});

In ui/status.js, call the handler and use its result:

WebView · ui/status.js
// @ts-check
/// <reference types="@revomp/types-webview" />
const output = document.getElementById('status');
if (!output) throw new Error('Missing status element');
try {
/** @type {{ health: number, armor: number }} */
const status = await revo.fetch('player:status');
output.textContent = `Health: ${status.health}, armor: ${status.armor}`;
} catch (error) {
output.textContent = 'Could not load player status.';
console.error('Player status request failed:', error);
}

Arguments after the request name are passed to the handler in order. For example, revo.fetch('inventory:page', 2) calls the client handler with 2.

For requests in the other direction, register revo.onRequest() in the page and call view.fetch() from the client. Register the page’s handlers before sending an application-ready event. view.waitForReady() waits for the bridge, so the page may still be initializing its own handlers when it resolves. See Readiness.

To obtain server data, a client request handler can call revo.fetchServer() and return its promise. The corresponding server handler receives the requesting player from the connection. Use that player when looking up account or inventory data.

Arguments and results are serialized as JSON. Send plain objects, arrays, strings, numbers, booleans and null. Pass selected entity properties or IDs instead of entity objects. BigInt and cyclic values fail serialization. A handler that returns undefined produces null as its response.

The serialized argument array and each response can contain up to 255 KiB of UTF-8 JSON. Names must contain 1–64 ASCII letters, digits or the characters ., :, _ and -. A prefix such as inventory: helps group related names.

Requests reject when the handler is missing, throws or returns a rejected promise. Invalid data, a closed document, unavailable bridge or full request queue can also reject a request. Catch failures at the call site, as shown in the example.

Each request has a 15-second timeout. The timeout passed to waitForReady() only controls readiness waiting. It leaves the request timeout unchanged.

A timeout or navigation can happen after the handler has started work. That work is not rolled back. For operations such as purchases, pass an application request ID so the server can recognize retries.

Only one request handler can be registered for a name on each side of a WebView. Registering the same name again throws. Remove it with offRequest(name) before replacing it.

Event listeners use off(name, handler) with the same function passed to on(). The page also provides revo.once() for a listener that removes itself after its first event. Unsubscribe component listeners when those components are removed from a page that stays loaded.

Navigation creates a new page context and clears its handlers. Client-side handlers attached to the WebView instance remain registered. Pending requests belong to the old document and cannot deliver a result to the new one. Register the new page’s handlers and repeat its ready notification after navigation.

Hiding a WebView keeps its document and bridge active. Destroying it closes the browser and removes its client-side handlers. For keyboard and mouse input, see Cursor and UI focus.

WebView · Browser bridge