Skip to content
Documentation menu

webFrame

Renderer-process API for zooming, injecting CSS, and evaluating script in the current Bunmaska page - a partial drop-in for Electron's webFrame.

Customize the rendering of the current web page from the renderer process. Bunmaska’s webFrame is a renderer-side object you use from the preload, which runs in an isolated world on macOS and Linux (the page world on Windows). That world shares the DOM with the page, so its zoom and CSS mutations affect what you see. It covers the day-to-day subset of Electron’s WebFrame: zoom, CSS injection, and script evaluation - but it does not yet model the frame-hierarchy tree (top/parent/firstChild), spellcheck, or resource accounting.

Process: Renderer (preload)

import { webFrame } from 'bunmaska/renderer';

// Zoom the current page to 200%.
webFrame.setZoomFactor(2);

Note on zoom backing: this renderer-local webFrame implements zoom via WebKit’s non-standard CSS zoom on the document element - a layout-zoom approximation, not the native WKWebView magnification (macOS) or WebKitGTK zoom_level (Linux). Bunmaska’s main process does expose a native page zoom on the window/webContents side, but the renderer webFrame here is deliberately renderer-local and does not call into it.

Methods

webFrame.setZoomFactor(factor)

setZoomFactor(factor: number): void

Changes the zoom factor to the specified factor. Zoom factor is zoom percent divided by 100, so 300% = 3.0. The factor must be greater than 0.0; non-finite or <= 0 values are ignored (matching Electron’s “must be greater than 0.0” rule, just without throwing).

import { webFrame } from 'bunmaska/renderer';

webFrame.setZoomFactor(1.5); // 150%

webFrame.getZoomFactor()

getZoomFactor(): number

Returns the current zoom factor. If no zoom has been applied (or the underlying value is invalid), it returns 1.

import { webFrame } from 'bunmaska/renderer';

webFrame.setZoomFactor(2);
console.log(webFrame.getZoomFactor()); // 2

webFrame.setZoomLevel(level)

setZoomLevel(level: number): void

Changes the zoom level to the specified level. The original size is 0, and each increment above or below multiplies the zoom factor by 1.2 (so level 1 ≈ 120%, level -1 ≈ 83%). Implemented in terms of setZoomFactor(1.2 ** level).

import { webFrame } from 'bunmaska/renderer';

webFrame.setZoomLevel(1); // ≈ 120%

Unlike Chromium/Electron, Bunmaska does not enforce the ±300%/50% clamp or the same-origin zoom-propagation policy. The level is a pure mathematical inverse of the factor and is applied to this frame only.

webFrame.getZoomLevel()

getZoomLevel(): number

Returns the current zoom level, derived from the current factor (log(factor) / log(1.2)). With no zoom applied this is 0.

import { webFrame } from 'bunmaska/renderer';

webFrame.setZoomFactor(1.2);
console.log(Math.round(webFrame.getZoomLevel())); // 1

webFrame.insertCSS(css)

insertCSS(css: string): string

Injects CSS into the current web page by appending a <style> element (to <head> if present, otherwise the document element) and returns a unique key. Use that key with removeInsertedCSS to remove the stylesheet later.

import { webFrame } from 'bunmaska/renderer';

const key = webFrame.insertCSS('body { background: rebeccapurple; }');
// ...later
webFrame.removeInsertedCSS(key);

Note: Electron’s insertCSS(css, options) accepts a cssOrigin: 'user' | 'author' option. Bunmaska’s signature takes the CSS string only - every insertion behaves like an author-origin stylesheet.

webFrame.removeInsertedCSS(key)

removeInsertedCSS(key: string): void

Removes a previously inserted stylesheet, identified by the key returned from insertCSS. An unknown or already-removed key is a no-op.

import { webFrame } from 'bunmaska/renderer';

const key = webFrame.insertCSS('a { color: hotpink; }');
webFrame.removeInsertedCSS(key); // safe to call once
webFrame.removeInsertedCSS(key); // calling again does nothing

webFrame.executeJavaScript(code)

executeJavaScript(code: string): Promise<unknown>

Evaluates code in the caller’s world via indirect global eval, and returns a Promise that resolves with the result or rejects if evaluation throws. Called from a preload on macOS or Linux, that is the isolated preload world: the code sees the shared DOM but none of the page’s own globals. To run code among the page’s globals, use webContents.executeJavaScript from the main process.

import { webFrame } from 'bunmaska/renderer';

const title = await webFrame.executeJavaScript('document.title');
console.log(title);

Differences from Electron: this is the renderer-side evaluator, not the main-side webContents.executeJavaScript. It does not accept Electron’s userGesture argument or a legacy callback parameter - it is Promise-only. There is no executeJavaScriptInIsolatedWorld.

Properties

This webFrame exposes no instance properties. The frame-hierarchy and identity properties from Electron (top, opener, parent, firstChild, nextSibling, routingId, frameToken) are not modeled - see below.

Not in Bunmaska (yet)

The following Electron webFrame members are intentionally absent from this module:

  • setVisualZoomLevelLimits(min, max) - no pinch-to-zoom limit control; zoom here is CSS layout-zoom only.
  • setSpellCheckProvider, isWordMisspelled, getWordSuggestions - no spellchecker integration.
  • insertText(text) - no programmatic insertion into the focused element.
  • executeJavaScriptInIsolatedWorld / setIsolatedWorldInfo - script runs in the current world only; there is no separate isolated-world evaluator or world configuration.
  • getResourceUsage() / clearCache() - no access to Blink-style memory caches (there is no Blink here; rendering is WebKit).
  • Frame-tree navigation: getFrameForSelector, findFrameByName, findFrameByToken, findFrameByRoutingId - no API for resolving sub-frames.
  • Properties top, opener, parent, firstChild, nextSibling, routingId, frameToken - the frame hierarchy is not exposed; webFrame represents the current frame only, with no links to relatives.
  • insertCSS cssOrigin option, executeJavaScript userGesture/callback arguments - the implemented methods exist but with the trimmed signatures noted above.

Native-backed page zoom (WKWebView magnification on macOS / WebKitGTK zoom_level on Linux) does exist in Bunmaska’s main process, but this renderer webFrame does not route through it; a native-backed renderer zoom is a possible future enhancement.