Plugins

Generated from the plugin implementations. Follow the plugin tutorial to install a bundled plugin or connect page JavaScript to a host callback.

brimp.plugins

Explicit JavaScript plugins. Handlers run on a session's managed dispatcher.

Plugin dataclass

Plugin(name: str, source: str, handlers: dict = dict(), options: dict = dict(), setup: object = None)

JavaScript installer plus synchronous host handlers and per-session setup.

The installer receives global, host and options. It may return a Promise and a disposer. Host handlers receive HostContext followed by copied values.

handlers class-attribute instance-attribute

handlers: dict = field(default_factory=dict)

name instance-attribute

name: str

options class-attribute instance-attribute

options: dict = field(default_factory=dict)

setup class-attribute instance-attribute

setup: object = None

source instance-attribute

source: str

from_file classmethod

from_file(path, *, name, handlers=None, options=None, setup=None)
Source code in brimp/plugins.py
72
73
74
75
76
77
78
79
80
81
82
83
@classmethod
def from_file(cls, path, *, name, handlers=None, options=None, setup=None):
    from pathlib import Path

    path = Path(path).resolve()
    return cls(
        name,
        path.read_text() + f"\n//# sourceURL={path.as_uri()}\n",
        handlers or {},
        options or {},
        setup,
    )

HostContext

HostContext(inner)

Realm-bound notification sender; late results are discarded after cancellation.

Source code in brimp/plugins.py
19
20
def __init__(self, inner):
    self._inner = inner

cancelled property

cancelled

origin property

origin

page_id property

page_id

realm_id property

realm_id

session_id property

session_id

url property

url

emit

emit(channel, value)
Source code in brimp/plugins.py
54
55
def emit(self, channel, value):
    self._inner.emit(channel, json.dumps(_encode(value), allow_nan=False))

function

function(name)
Source code in brimp/plugins.py
46
47
def function(self, name):
    return HostFunction(name)

catalog

catalog()

Return host-side capability/options metadata, without installing plugins.

Source code in brimp/plugins.py
225
226
227
228
229
def catalog():
    """Return host-side capability/options metadata, without installing plugins."""
    from pathlib import Path

    return json.loads((Path(__file__).parent / "bundled/catalog.json").read_text())

browser

browser()

Fresh default browser subsystem descriptors; excludes host storage and extraction.

Source code in brimp/plugins.py
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
def browser():
    """Fresh default browser subsystem descriptors; excludes host storage and extraction."""
    return [
        _bundled(name, {})
        for name in (
            "environment",
            "permissions",
            "devices",
            "media",
            "workers",
            "trusted-types",
            "canvas",
            "graphics",
            "audio",
            "rtc",
        )
    ]

host_storage

host_storage(*, backend_factory=_MemoryStorageBackend)

Explicit async hostStorage API, partitioned by native origin.

A backend provides synchronous transaction(origin, operations) and optional close(). It must atomically commit/rollback batches, including across sessions if the supplied backend shares durable state. The default is session memory.

Source code in brimp/plugins.py
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
def host_storage(*, backend_factory=_MemoryStorageBackend):
    """Explicit async hostStorage API, partitioned by native origin.

    A backend provides synchronous transaction(origin, operations) and optional
    close(). It must atomically commit/rollback batches, including across sessions
    if the supplied backend shares durable state. The default is session memory.
    """

    def setup():
        backend = backend_factory()
        if not callable(getattr(backend, "transaction", None)):
            raise TypeError("backend requires transaction(origin, operations)")
        lock = threading.RLock()

        def transaction(context, operations):
            if context.origin is None:
                raise ValueError("Host storage requires a non-opaque origin")
            if not isinstance(operations, list):
                raise TypeError("transaction requires an operation array")
            for op in operations:
                if (
                    not isinstance(op, dict)
                    or op.get("type") not in ("get", "set", "delete", "clear")
                    or (op["type"] != "clear" and not isinstance(op.get("key"), str))
                    or (op["type"] == "set" and "value" not in op)
                ):
                    raise TypeError("invalid storage operation")
            with lock:
                if context.cancelled:
                    raise RuntimeError("Storage request cancelled")
                return backend.transaction(context.origin, operations)

        def dispose():
            with lock:
                close = getattr(backend, "close", None)
                if close:
                    close()

        return {"handlers": {"transaction": transaction}, "dispose": dispose}

    return Plugin("host-storage", _bundled("host-storage").source, setup=setup)

extraction

extraction()

Explicit Defuddle article extraction using DOM-only heuristics.

Source code in brimp/plugins.py
185
186
187
def extraction():
    """Explicit Defuddle article extraction using DOM-only heuristics."""
    return _bundled("extraction")

canvas

canvas(*, rgba=None, character_width=None)

Painted Canvas state with profile font metrics and a real PNG encoder.

Source code in brimp/plugins.py
140
141
142
143
144
145
146
147
def canvas(*, rgba=None, character_width=None):
    """Painted Canvas state with profile font metrics and a real PNG encoder."""
    options = {}
    if rgba is not None:
        options["rgba"] = list(rgba)
    if character_width is not None:
        options["characterWidth"] = character_width
    return _bundled("canvas", options)

environment

environment(**options)

Explicit core navigator overrides; Configured connection values.

Source code in brimp/plugins.py
150
151
152
def environment(**options):
    """Explicit core navigator overrides; Configured connection values."""
    return _bundled("environment", options)

permissions

permissions(**options)

Notification and permission mocks; Credential placeholders.

Source code in brimp/plugins.py
155
156
157
def permissions(**options):
    """Notification and permission mocks; Credential placeholders."""
    return _bundled("permissions", options)

devices

devices(**options)

Bluetooth availability; Clipboard, geolocation, wake lock and sharing placeholders.

Source code in brimp/plugins.py
160
161
162
def devices(**options):
    """Bluetooth availability; Clipboard, geolocation, wake lock and sharing placeholders."""
    return _bundled("devices", options)

media

media(**options)

Media devices, streams and source-buffer placeholders; Media session state and encrypted-media event payloads.

Source code in brimp/plugins.py
165
166
167
def media(**options):
    """Media devices, streams and source-buffer placeholders; Media session state and encrypted-media event payloads."""
    return _bundled("media", options)

workers

workers(**options)

Worker and service-worker placeholders.

Source code in brimp/plugins.py
170
171
172
def workers(**options):
    """Worker and service-worker placeholders."""
    return _bundled("workers", options)

trusted_types

trusted_types(**options)

Trusted Types placeholders.

Source code in brimp/plugins.py
175
176
177
def trusted_types(**options):
    """Trusted Types placeholders."""
    return _bundled("trusted-types", options)

rtc

rtc()

Local WebRTC shapes and legacy placeholders; no network/media transport.

Source code in brimp/plugins.py
180
181
182
def rtc():
    """Local WebRTC shapes and legacy placeholders; no network/media transport."""
    return _bundled("rtc")

graphics

graphics(*, rgba=None, renderer=None, webgpu=False, handlers=None)

WebGL state/readback with profile identity and opt-in WebGPU buffer mocks.

Source code in brimp/plugins.py
207
208
209
210
211
212
213
214
215
def graphics(*, rgba=None, renderer=None, webgpu=False, handlers=None):
    """WebGL state/readback with profile identity and opt-in WebGPU buffer mocks."""
    options = {"webgpu": webgpu}
    if rgba is not None:
        options["rgba"] = list(rgba)
    if renderer is not None:
        options["renderer"] = renderer
    plugin = _bundled("graphics", options)
    return Plugin(plugin.name, plugin.source, handlers or {})

audio

audio(*, sample_rate=None, handlers=None)

Audio graph/buffer state with profile rate; silent analysis, no decoding.

Source code in brimp/plugins.py
218
219
220
221
222
def audio(*, sample_rate=None, handlers=None):
    """Audio graph/buffer state with profile rate; silent analysis, no decoding."""
    options = {} if sample_rate is None else {"sampleRate": sample_rate}
    plugin = _bundled("audio", options)
    return Plugin(plugin.name, plugin.source, handlers or {})