Electrobun WGPU Tag

<electrobun-wgpu> places a native WGPU surface at an element’s bounds. Use the host document for layout and controls while a Zig, Rust, Go, Odin, Bun, or Cottontail main process renders directly to the native surface.

Import electrobun/view once to register the element and its TypeScript DOM types.

<div class="toolbar">GPU controls</div>
<electrobun-wgpu
  id="scene"
  style="display: block; width: 100%; height: 480px"
></electrobun-wgpu>

import type { WgpuTagElement } from "electrobun/view";
import "electrobun/view";

const surface = document.querySelector("electrobun-wgpu");
if (!surface) throw new Error("The WGPU surface was not found");

surface.on("ready", (event) => {
  const { id } = event.detail as { id: number };
  console.log("Native WGPU view ready", id);
});

const typedSurface: WgpuTagElement = surface;
void typedSurface;

The ready event reports the native wgpuViewId. Send that ID to the main process through your application’s RPC schema, then initialize the renderer for that view.

Attributes

Attribute	Value	Purpose
transparent	boolean attribute	Starts the native surface transparent.
passthrough	boolean attribute	Starts with pointer input passing through to the host page.
hidden	boolean attribute	Starts the native surface hidden.
masks	comma-separated selectors	Cuts holes for matching host elements.

<div class="toolbar">Host controls rendered over the surface</div>
<electrobun-wgpu
  transparent
  passthrough
  masks=".toolbar, .popover"
></electrobun-wgpu>

Boolean attributes configure the initial native view. Use the toggle methods for runtime changes.

Visibility And Input

Each toggle accepts an explicit state. Omit the argument to invert the current state.

import "electrobun/view";

const surface = document.querySelector("electrobun-wgpu");
if (!surface) throw new Error("The WGPU surface was not found");

surface.toggleTransparent(true);
surface.togglePassthrough(false);
surface.toggleHidden(false);
surface.syncDimensions(true);

console.log({
  transparent: surface.transparent,
  passthrough: surface.passthroughEnabled,
  hidden: surface.hidden,
});

Normal layout changes are synchronized automatically. Call syncDimensions(true) when application code needs an immediate update.

Masks

The WGPU surface is a native layer above the host webview. Host elements cannot cross that layer with z-index; masks cut rectangular holes so the matching host elements can render and receive input.

import "electrobun/view";

const surface = document.querySelector("electrobun-wgpu");
if (!surface) throw new Error("The WGPU surface was not found");

surface.addMaskSelector(".context-menu");
surface.removeMaskSelector(".context-menu");

On Linux, passthrough and masks are unavailable inside transparent BrowserWindows because the transparent CEF host is rendered offscreen while the WGPU surface is a native child window. Use a non-transparent parent or keep interactive HTML outside the surface for that composition.

Main-Process Surface

In a Bun or Cottontail main process, the tag-created native view is available through WGPUView. getById normally finds it; adoptExisting attaches a wrapper when it was created outside the current SDK object map.

import { WGPUView, webgpu } from "electrobun/main";

export function createEmbeddedGpuContext(
  id: number,
  windowId: number,
  width: number,
  height: number,
) {
  const view =
    WGPUView.getById(id) ??
    WGPUView.adoptExisting(id, {
      windowId,
      autoResize: false,
      frame: { x: 0, y: 0, width, height },
    });

  if (!view) throw new Error(`WGPU view ${id} is unavailable`);
  return webgpu.createContext(view);
}

The native Zig, Rust, Go, and Odin SDKs receive the same view ID and expose their own WGPU surface bridge. Start from the corresponding WGPU template for a complete renderer with lifecycle and resize handling.

Lifecycle

Removing the element destroys its native view. A later insertion creates a new ID, so stop resources tied to the old surface and initialize them again on the next ready event. Reconfigure the WebGPU context and recreate size-dependent textures when dimensions change.

The runTest() method invokes Electrobun’s native diagnostic renderer. It is intended for framework and platform verification rather than application render loops.

Properties And Methods

Member	Type	Purpose
wgpuViewId	number | null	Native view ID after initialization.
transparent	boolean	Current transparency state.
passthroughEnabled	boolean	Current input passthrough state.
hidden	boolean	Current native visibility state.
toggleTransparent(value?)	method	Sets or toggles transparency.
togglePassthrough(value?)	method	Sets or toggles input passthrough.
toggleHidden(value?)	method	Sets or toggles visibility.
syncDimensions(force?)	method	Synchronizes geometry and masks.
addMaskSelector(selector)	method	Adds a host-page mask selector.
removeMaskSelector(selector)	method	Removes a mask selector.
on("ready", listener)	method	Subscribes to initialization.
off("ready", listener)	method	Removes the exact listener.
runTest()	method	Runs the native diagnostic renderer.