Package

purescript-hylograph-wasm-kernel

Repository
afcondon/purescript-hylograph-wasm-kernel
License
MIT AND ISC
Uploaded by
pacchettibotti
Published on
2026-11-19T10:14:46Z

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.

Use

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 KernelModule decodes the module this package carries, instantiates it, and gives back the initialised kernel, as hylograph-simulation's opaque KernelModule. No network request is made. The kernel is instantiated once per JavaScript realm; later calls give back the same one.
  • install :: Aff Unit is load followed by hylograph-simulation's installKernel, after which engine: WASM, Stepped.Rust and Hylograph.ForceEngine.Setup.WASM work. If a kernel is already installed (by install or by initWasm), the one already there stays.

It needs hylograph-simulation 1.1.0 or later, which is where installKernel and KernelModule were added.

Size

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.

Regenerating, and checking it against the source

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 source

generate.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.

Tests

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 bundle

The 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.mjs runs them in one process after install, with nothing served, and in another after initWasm with the URL of a fresh wasm-pack build of the commit the header names (or KERNEL_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 with Object.is.
  • test/browser.mjs bundles a page with esbuild (no warnings allowed), serves it from a local server and loads it in headless Chrome (CHROME overrides 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; and runSimulation with engine: WASM runs to completion on the installed kernel.

What changed from 0.1.0

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.

What has not been done or shown

  • 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.

Licence

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.

Modules
Hylograph.Kernel.WASM
Dependencies