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.
Request data from the client
Section titled “Request data from the client”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:
<!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:
// @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:
// @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.
Data and limits
Section titled “Data and limits”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.
Errors and timeouts
Section titled “Errors and timeouts”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.
Handlers and navigation
Section titled “Handlers and navigation”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.