The Rust/WebAssembly force kernel of hylograph-simulation, carried inside a PureScript package. Depend on this package and the fast engine works: there is no npm package to install, no module to build from Rust, and no file to serve beside your page.
hylograph-simulation does not depend on this package. Its default engine
is pure PureScript and loads nothing; only a program that wants the fast
engine takes this package, and pays for it.
import Hylograph.Kernel.WASM as Kernel
main = launchAff_ do
Kernel.install -- decode the embedded module and hand it to hylograph-simulation
-- now: runSimulation { engine: WASM, .. }, or Stepped.create Stepped.Rust ..The module Hylograph.Kernel.WASM has two functions:
load :: Aff KernelModuledecodes the module this package carries, instantiates it, and gives back the initialised kernel, ashylograph-simulation's opaqueKernelModule. No network request is made. The kernel is instantiated once per JavaScript realm; later calls give back the same one.install :: Aff Unitisloadfollowed byhylograph-simulation'sinstallKernel, after whichengine: WASM,Stepped.RustandHylograph.ForceEngine.Setup.WASMwork. If a kernel is already installed (byinstallor byinitWasm), the one already there stays.
It needs hylograph-simulation 1.1.0 or later, which is where
installKernel and KernelModule were added.
The module is carried as base64 in the module's foreign file,
src/Hylograph/Kernel/WASM.js, after wasm-bindgen's loader. Measured on the
file as committed:
| bytes | |
|---|---|
| the WebAssembly module | 136,414 |
| the same as base64 | 181,888 |
| the whole foreign file (header, loader, base64, the foreign function) | 225,775 |
What it adds to an esbuild bundle (esbuild 0.28, --bundle --format=iife),
measured as the difference between a page that uses Stepped.Rust after
initWasm "<url>" and the same page using install instead:
| by URL | embedded | added | |
|---|---|---|---|
| unminified | 317,688 | 541,429 | 223,741 |
| minified | 127,000 | 320,408 | 193,408 |
| minified, then gzip -9 | 28,762 | 104,401 | 75,639 |
(These bundle figures were measured before the build's paths were remapped, which made the module 24 bytes smaller; they have not been re-measured.)
The page that loads by URL fetches the rest at run time instead: the 136,438-byte module and the 42,363-byte loader, 61,782 bytes together under gzip -9 (52,829 and 8,953). Base64 does not compress back to the module's own gzip size, so carried this way the kernel costs a gzip-served page about 14 KB more than serving the two files beside it, and saves the two requests.
The foreign file is generated, and committed. Its header names the commit of
hylograph-force-kernel
it was built from and the rustc, wasm-pack and wasm-bindgen versions. You
need Rust with the wasm32-unknown-unknown target and wasm-pack (the
kernel's README has the steps); ~/.cargo/bin is put first on the path.
FORCE_KERNEL=<checkout of hylograph-force-kernel> node generate.mjs # write src/Hylograph/Kernel/WASM.js
FORCE_KERNEL=<the same checkout> node check.mjs # prove it corresponds to the sourcegenerate.mjs runs the kernel README's wasm-pack build --target web into
build/ (the checkout is only read, and must have no uncommitted changes),
removes the loader's exports and the default branch that would look for the
module beside the loader through import.meta.url (never taken here, and
bundlers warn about it), and writes loader, base64 and the one foreign
function into the file.
check.mjs requires the checkout to be at the commit the header names,
rebuilds the module from scratch in an empty cargo target directory, and
requires byte equality: of the module against the embedded bytes, and of
the whole file against what generate.mjs would write. Byte equality is the
check because two builds of the same source were byte-identical here (each
in its own empty cargo target directory, so the target path does not reach
the module either). The build remaps two paths to fixed names (--remap-path-prefix for
cargo's home and for the kernel checkout), because Rust puts source paths in
panic messages: without that the module carried the builder's home
directory, and its bytes depended on where things were. With it, a clone of
the kernel at a different path gave the same bytes. It has been shown on one
machine and one toolchain only (macOS, rustc 1.92.0, wasm-pack 0.13.1,
wasm-bindgen 0.2.106, wasm-opt 117): another toolchain version may well give
different bytes while behaving identically, and the check would then fail
and say so. A one-character change to the embedded base64 was confirmed
to fail the check.
npm install # esbuild and puppeteer-core, for the tests only
spago test # install, then run the scenarios on it
node test/run.mjs # the embedded kernel against the kernel loaded by URL
node test/browser.mjs # the embedded kernel in Chrome, from an esbuild bundleThe scenarios (test/Test/Scenario.purs) are six simulations run through
Hylograph.Simulation.Stepped on the Rust engine: all seven of d3-force's
forces together, and many-body with towards, rectangle collision and links,
each at 10, 100 and 500 nodes, for 300, 300 and 200 ticks.
test/run.mjsruns them in one process afterinstall, with nothing served, and in another afterinitWasmwith the URL of a freshwasm-packbuild of the commit the header names (orKERNEL_PKG). The embedded run makes no fetch and resolves no kernel file; the probes that show this do see the other run fetch the module and import the loader. All 4,880 numbers (x, y, vx, vy of every node) are equal withObject.is.test/browser.mjsbundles a page with esbuild (no warnings allowed), serves it from a local server and loads it in headless Chrome (CHROMEoverrides the path). The only requests are for the page and the bundle; nothing is logged as an error or thrown; the six simulations give exactly the numbers Node gives; andrunSimulationwithengine: WASMruns to completion on the installed kernel.
Everything. 0.1.0 was a separate, older binding (Hylograph.Kernel.WASM.Engine,
.Simulation, .FFI, .Events, .Halogen, over hylograph-simulation-core)
to an older build of the kernel, which you had to build and serve yourself.
Those modules are gone. hylograph-simulation has carried its own, current
bindings since before 1.0.0, and they are what to use:
| 0.1.0 | instead |
|---|---|
Hylograph.Kernel.WASM.Engine |
Hylograph.ForceEngine.WASMEngine (the same export names) or Hylograph.Simulation.Stepped with Rust |
Hylograph.Kernel.WASM.FFI |
Hylograph.ForceEngine.WASM |
Hylograph.Kernel.WASM.Simulation, .Events |
Hylograph.Simulation.runSimulation with engine: WASM, and its event emitter |
Hylograph.Kernel.WASM.Halogen |
hylograph-simulation-halogen |
initWasm "./pkg/force_kernel.js" |
Hylograph.Kernel.WASM.install (or keep initWasm, which still works) |
all in hylograph-simulation, except the last row and the Halogen package.
- Byte-identical builds have been shown on one machine and one toolchain only (above).
- Tried with esbuild only; not with webpack, Rollup, Vite or Parcel. Run in Node 22 and headless Chrome only; not in Firefox, Safari or Deno.
- Not tried under a Content-Security-Policy.
- The time to decode the base64 and compile the module was not measured.
- Only the JavaScript backend; the foreign file is JavaScript.
MIT AND ISC: the kernel's own code is MIT, and the parts of it ported from
d3-force and d3-quadtree carry their ISC notice. LICENSE is the kernel's.