Skip to content

README.md

Latest commit

 

History

History
341 lines (264 loc) · 13.5 KB

README.md

File metadata and controls

341 lines (264 loc) · 13.5 KB

Webview API

Ensure you set

export ALLOWED_EMBEDDING_ORIGINS="https://site-that-serves-the-page-using-the-webview.example.com https://other-site.you-will-embed.browserbox-on.com"
bbx stop
bbx setup -p 8888
bbx start
cat ~/.config/dosaygo/bbpro/login.link

before starting the self-hosted BrowserBox instance that will be embedded.

Embedding

<script src="browserbox-webview.js"></script>
<browserbox-webview
  id="bbx"
  login-link="https://example.com:9999/login?token=your_login_link"
  embedder-origin="https://app.example.com"
  ui-visible="false"
  allow-user-toggle-ui="false"
  width="100%"
  height="600">
</browserbox-webview>

Quick Start

const bbx = document.querySelector('browserbox-webview');
await bbx.whenReady();

// Navigate and inspect tabs
await bbx.page.navigate('https://example.com');
const tabs = await bbx.tabs.list();
const firstTab = tabs[0];
if (firstTab?.id) {
  await bbx.tabs.activate(firstTab.id);
}

// Automate
await bbx.click('a.my-link');
await bbx.waitForSelector('.result');
const title = await bbx.evaluate('document.title');

// Capture
const screenshot = await bbx.capture.frame({ format: 'jpeg', quality: 80 });

// Source-frame access
await bbx.frameCapture(true);
const frame = await bbx.getFrame();

// Reset the session and navigate fresh
await bbx.cleanSlate('https://example.com');

Use tab IDs from tabs.list() or the switchToTabById(targetId) / closeTabById(targetId) wrappers. Do not key tab state by positional index in an embedder.

Element Attributes

Attribute Required Default Description
login-link yes — Full BrowserBox login URL with auth token
width no "100%" CSS width (px if bare number)
height no "100%" CSS height (px if bare number)
embedder-origin no "*" Restrict postMessage origin
parent-origin no "*" Deprecated alias for embedder-origin
request-timeout-ms no 30000 API call timeout (ms)
ui-visible no true Show/hide BrowserBox chrome UI
allow-user-toggle-ui no true Allow user to toggle UI visibility
interaction-mode no "full" Policy preset: full, limited, view-only
policy no — Additional local policy restrictions; cannot widen server policy
chrome no "default" Chrome presentation hint: none, minimal, default, custom
augment-root no "open" Augment inspectability hint: open or closed
capture no "snapshot" Capture policy hint: off, snapshot, sampled

For custom host chrome, prefer ui-visible="false" and allow-user-toggle-ui="false". The legacy ui=false login-link parameter still works for backward compatibility, but the element attributes are the canonical controls.

Namespaced Session-Host API

The <browserbox-webview> element exposes a namespaced API for programmatic control.

Access via the element directly (bbx.tabs.list()) or via bbx.session facade.

session

Property / Method Returns Description
session.id string | null Routing machine ID
session.usable boolean Whether the session is currently usable
session.ready boolean Whether the API handshake has completed
session.transport string Transport mode: "modern", "legacy", or "unknown"
session.health() Promise<HealthReport> Probe the embedded browser and transport
session.capabilities() Promise<object> Query supported capabilities
session.disconnect() void Tear down the session
session.refresh() void Reload the embedded iframe

tabs

Method Returns Description
tabs.list() Promise<Tab[]> List all open tabs
tabs.getActive() Promise<Tab> Get the active tab's info
tabs.create({ url, active? }) Promise<Tab> Open a new tab
tabs.activate(tabId) Promise Switch to a tab by ID
tabs.close(tabId) Promise Close a tab by ID
tabs.closeAll() Promise Close all tabs

Tab object: { id, index, active, url, title, canGoBack, canGoForward, loading, hasFavicon, isDefaultFavicon, faviconDataURI }

page

Method Returns Description
page.navigate(url, opts?) Promise<NavResult> Navigate the active tab
page.url() Promise<string> Get the active tab's URL
page.title() Promise<string> Get the active tab's title
page.favicon() Promise<string | null> Get the favicon as a data URI
page.metrics() Promise<PageMetrics> Get normalized viewport/document dimensions
page.text(opts?) Promise<string> Extract page text ({ mainContentOnly?: boolean })
page.reload() Promise Reload the active tab
page.back() Promise<boolean> Navigate back
page.forward() Promise<boolean> Navigate forward
page.stop() Promise Stop loading

capture

Method Returns Description
capture.frame(opts?) Promise<string> Full-page screenshot as data URI
capture.viewport(opts?) Promise<string> Viewport-only screenshot as data URI
capture.enable(enabled?) Promise<boolean> Enable/disable single-slot source-frame capture
capture.next() Promise<FramePacket | null> Consume the latest captured source frame

Options: { format?: "jpeg" | "png", quality?: number }

FramePacket:

{
  seq,
  capturedAt,
  frameId,
  castSessionId,
  sessionId,
  targetId,
  width,
  height,
  mime,
  bytes: ArrayBuffer
}

policy

Method Returns Description
policy.get() Promise<object> Get current policy snapshot

policy.get() returns the merged effective policy snapshot. Server policy is authoritative and embedder attributes can only further restrict it.

augment (capability-gated)

Method Returns Description
augment(spec) Promise<AugmentHandle> Create an augmentation overlay
augment.update(id, patch) Promise Update an existing augmentation
augment.remove(id) Promise Remove an augmentation
augment.list() Promise<Augment[]> List all active augmentations

Preferred content shapes:

  • { type: "text", text }
  • { type: "html", html }
  • { type: "json", data }

Raw strings are still accepted as HTML shorthand.

select (capability-gated)

Method Returns Description
select({ prompt, intent }) Promise<SelectionHandle> Begin interactive selection

SelectionHandle: { getRaw(), generalize(), preview(), extract(opts?) }

  • getRaw() -> { selector, selectors, text, href, htmlSnippet }
  • preview() -> { selector, matches, sample? }
  • extract({ fields, limit }) -> { selector, items, count }

Automation Methods

Direct methods on the element for browser automation:

Method Returns Description
click(selector, opts?) Promise<{ result }> Click an element by CSS selector
type(selector, text, opts?) Promise<{ result }> Type text into an element
evaluate(expression, opts?) Promise<{ result }> Evaluate JavaScript in the page
waitForSelector(selector, opts?) Promise<boolean> Wait for a selector to appear
waitForNavigation(opts?) Promise Wait for a navigation to complete
frameCapture(enabled?) Promise<boolean> Enable/disable single-slot source-frame capture
getFrame() Promise<FramePacket | null> Consume the latest captured source frame
cleanSlate(url) Promise<{ ok, url, targetId, sessionId, warmed, ackBlastCount }> Reset browser state, open a fresh tab, navigate, and warm screencast

act(action) — Unified action dispatch

Action Example Description
navigate act({ navigate: "https://..." }) Navigate the active tab
click act({ click: { selector: "a" } }) Click an element
type act({ type: { selector: "input", text: "hello" } }) Type into an element
evaluate act({ evaluate: "document.title" }) Evaluate JS expression
waitForSelector act({ waitForSelector: { selector: "h1" } }) Wait for element
waitForNavigation act({ waitForNavigation: {} }) Wait for nav

Returns { ok, action, value }.

UI Controls

Method Returns Description
uiVisible(visible?) Promise<boolean> Show/hide BrowserBox chrome UI
allowUserToggleUI(allow?) Promise<boolean> Allow/deny user UI toggling

Event Helpers

Method Description
on(name, handler) Subscribe; returns unsubscribe function
off(name, handler) Unsubscribe
observe(config) Structured event observer; returns { id, config, on, off, unsubscribe }
events(config) Async iterator over events

events(config) yields { id, type, timestamp, sessionId, tabId?, detail }.

Events

Event Detail Description
ready { type } Legacy transport handshake completed
api-ready { methods: string[], policy?: PolicySnapshot } Modern API available and may include the current server policy snapshot
ready-timeout { timeoutMs, error } Ready handshake timed out
tab-created { index, id, url } New tab opened
tab-closed { index, id } Tab closed
tab-updated { id, url, title, faviconDataURI } Tab metadata updated
active-tab-changed { index, id } Active tab switched
did-start-loading { tabId, url } Page load started
did-stop-loading { tabId, url } Page load finished
did-navigate { tabId, url } Navigation committed
favicon-changed { tabId, faviconDataURI } Favicon updated
policy-denied { url, reason } Navigation blocked by policy
policy.changed { reason, policy, capabilities } Effective policy/capability set changed
usability-changed { usable: boolean } Browser usability state changed
sos { reasonCode, message, retryUrl } Fatal unusable signal
disconnected — Session ended

Canonical event aliases

Legacy event names continue to work. Dot-notation aliases are also emitted:

Legacy Canonical
api-ready api.ready
tab-created tab.created
tab-closed tab.closed
tab-updated tab.updated
active-tab-changed tab.activated
did-navigate page.navigated
did-start-loading page.load.started
did-stop-loading page.load.stopped
policy-denied policy.denied
policy.changed policy.changed
usability-changed session.usability.changed
disconnected session.disconnected

Policy Sync

Server policy is pushed to the embedder over the existing BrowserBox runtime/meta and iframe postMessage channels:

  1. The server emits policySnapshot meta when effective policy changes.
  2. The embedded BrowserBox client caches the latest snapshot.
  3. The iframe bridge includes policy in the initial bbx-api-ready handshake.
  4. Mid-session changes are forwarded as bbx-policy-sync.
  5. <browserbox-webview> merges server policy with local attribute policy and emits policy.changed if capabilities change.

The embedder never widens server policy.

Errors

Public API failures use stable BrowserBoxError codes:

  • ERR_NOT_READY
  • ERR_POLICY_DENIED
  • ERR_TIMEOUT
  • ERR_TRANSPORT
  • ERR_UNSUPPORTED
  • ERR_INVALID_ARGUMENT
  • ERR_NOT_FOUND
  • ERR_CONFLICT
  • ERR_INTERNAL

Errors may also include status and retriable.

Flat Methods (backward compatible)

All classic flat methods remain available:

whenReady(), callApi(), navigateTo(), navigateTab(), submitOmnibox(), getTabs(), getFavicons(), getTabCount(), getActiveTabIndex(), createTab(), createTabs(), closeTab(), closeTabById(), closeAllTabs(), switchToTab(), switchToTabById(), reload(), goBack(), goForward(), stop(), getScreenMetrics(), getTransportDiagnostics(), frameCapture(), getFrame(), cleanSlate(), health(), refresh(), updateIframe(), stopReconnectAttempts(), requestFrameRefresh(), reactivateActiveTab(), listApiMethods(), waitForNonDefaultFavicon(), waitForTabCount(), waitForTabUrl()

Visibility Reactivation

When a page hosting <browserbox-webview> is hidden (e.g. minimized, tab-switched) and later restored, the viewport may appear blank until a fresh frame is rendered.

Two methods handle this:

Method Returns Description
requestFrameRefresh(reason?) void Request an immediate frame from the server; no layout checks
reactivateActiveTab(reason?) Promise<boolean> Re-activate the current tab via switchToTabById, forcing a fresh frame without any clientWidth guard

The component already listens for visibilitychange, pageshow, and focus events internally and calls requestFrameRefresh. For embedders that wrap the webview inside custom window managers (minimize/restore), call reactivateActiveTab() explicitly on restore.

Test Status

55/55 tests passing (2026-03-09) — full coverage across session, tabs, page, navigation, automation (click, waitForSelector, evaluate, act), capture, diagnostics, policy, augment, events, and observer APIs.