Three layers, each doing its own job
On top is Electron's web UI, in the middle a Node.js native extension, underneath the C++ engine. UI work belongs to the web page, playback work belongs to the engine, and the middle layer connects the two.
The C++ interface first gets its scripting-language wrappers generated by a tool, then a build description specifies the source files and library paths, and everything compiles into a .node binary. The first pitfall is here: an extension built for Electron must be rebuilt against the Node ABI that the current Electron ships with — reuse a binary compiled against plain Node and the runtime reports a Node version mismatch. The reason is that what runs inside Electron is not the Node installed on the system but its own bundled copy; when the two Node versions differ, the binary interfaces do not line up. The fix is to point the rebuild target at the Electron version in use and to match the headers to the copy Electron ships.

The player lives in the main process; renderers only send messages
The player instance lives in the main process. Renderer processes are pure web pages that never touch the engine directly; actions travel over IPC: start, stop, switch hardware decoding, switch data source, set watermark, set filter parameters. The main process receives them and applies them to the engine.
Commands and state travel on two channels. Commands originate in the page with the main process answering, one entry point per action; state and position are notifications initiated on the engine side and pushed to the page, throttled before pushing — position changes every frame, and pushing it in full would drown the inter-process channel. The two pages (the main window's UI and the container window's video layer) never talk to each other directly; each deals only with the main process.
The reasons for this split are practical. The engine object is held in exactly one place, so there is no worrying about several web contexts fighting over the same handle. A page refresh or reopen does not touch the engine's life — a renderer process can crash, the engine survives, and reconnecting restores the state. The isolation works the other way too: the engine runs on its own threads and takes no share of the renderer's frame budget, so dropped frames in the page do not slow decoding, and a busy decoder does not stall the UI.
Keeping the command surface narrow is deliberate: the page can do only those few actions, each command entry does parameter validation plus forwarding, and the engine object never leaves the main process's file. Spreading the engine's fine-grained interface straight onto the web layer would amount to dismantling the thread boundary — anyone could touch it at any moment.
There is an ordering to the wrapper generation as well: the interface is fixed first in a public header, the tool produces the scripting-language wrappers from it, then a build description accompanies them — source file list, header paths, libraries to link, all in that description. Change the interface, rerun the generation; the build description follows the interface, not the caller.
Frames into the page: a road that does not work
The first plan was the most direct one, and the idea seemed obvious: the UI is all web pages, so the picture should be an element in the page too, with layout, rounded corners and stacking already provided. The approach: once the engine finishes rendering, the texture in GPU memory is handed to the browser through a shared handle, the browser imports it with WebGPU or WebGL, and draws it into a canvas.
The conclusion after digging: the browser side has no such import interface. While researching I came across a version of the plan described in confident detail — a DX11 shared handle imported through WebGPU for rendering, interface name included; I went through that stretch of API and the interface simply does not exist. Falling back to reading the picture back to the CPU and passing it to the page would move, but it defeats hardware decoding — the GPU layer exists precisely to skip the CPU copy. This road is written down as impassable because it is.
One more thing was left out of the accounting: beyond the picture, subtitles and UI elements are drawn on the engine's presentation. Going the canvas route, the page receives only a video frame and subtitles would need a whole separate system on the web side — redoing, by hand, something already done right.

The way around: a native window floating where the page points
Electron's window object can hand over the current platform's window handle. With a handle, the swap chain and the picture can be built through the native-window flow — the surface creation and presentation described in the render-layering article apply here unchanged.
Concretely, I open a second window to serve as the playback container: it attaches as a child of the main window, frameless and transparent, and its window handle goes to the engine; the container floats inside the main window, over the spot the page reserves for the picture. The handle is a small buffer read off the window object, interpreted as an integer in little-endian order before being handed over; on the engine side the render window follows the native-window flow — create the window, pass the handle, attach the render window to the player instance, three steps. Transparency must be on, otherwise the rendered picture underneath is covered by the web layer and nothing is visible. The container is itself a web page, and the control bar layered over the picture is drawn by it.
The remaining work is following along: watch the main window's move and resize events, add the video region reported by the page, recompute, and move the container's bounds there, position and size given in one shot. When the page reports matters too: once after layout completes, again on window resize and page content changes; the main process combines the two sources into the rectangle the container should occupy. Misaligned by a little and a corner of the picture peeks out or drifts off the page, so this step needs watching.
The cost, to be fair: a transparent window takes a different composition path, the moment the picture stacks onto the page is done by the system compositor, and fullscreen-exclusive-style optimizations are out of reach; the trade buys a UI and a picture that are written separately and stay out of each other's way. Across the whole integration the engine never learns that Electron exists: hand it a handle and it treats it as a native window — the same handle contract as the Avalonia and Flutter articles that follow.
The engine avox is open source on GitHub: github.com/xxxzhou/avox, where the native-window setup and this integration live.