@seantalts/stanli 0.9.1 → 0.9.3

package/README.md

@@ -1,11 +1,12 @@
 # stanli
 
 Full [Stan](https://mc-stan.org) in the browser. stanc3 (the real Stan
-compiler, compiled to JavaScript) turns Stan source into its
-intermediate representation; a WebAssembly build of the stanli runtime
-lowers it to an op graph over precompiled stan-math kernels and samples
-with NUTS. No server, no C++ toolchain, everything in the tab. Live
-demo: <https://seantalts.github.io/stanli/>.
+compiler, compiled to JavaScript) parses, typechecks, and optimizes the
+model; the shared stanli OCaml pipeline encodes its typed MIR into portable
+MIR. A WebAssembly build of the stanli runtime lowers that to an op graph over
+precompiled stan-math kernels and samples with NUTS. No server, no C++
+toolchain, everything in the tab. Live demo:
+<https://seantalts.github.io/stanli/>.
 
 ```js
 import { sample } from "@seantalts/stanli";
@@ -30,13 +31,27 @@ parameters, and generated quantities (RNG draws stream from `seed`).
 The heavy work runs in a worker the package owns, so the page never
 blocks; calls queue and run one at a time.
 
-The payload is ~9 MB installed, ~1.9 MB over the wire with gzip: the
-WASM runtime plus the stanc3 compiler. The compiler loads lazily, only
-when a call passes Stan source. `preload()` starts both loads in the
-background; call it at page idle so the first `sample()` skips the
-fetch and parse. An app that ships a fixed model can precompile it at
-build time (`stanc --O1 --debug-optimized-mir model.stan`) and pass `mir`
-instead of `code`; the runtime alone is ~1.5 MB gzipped.
+The preferred compiler, `stanli-compiler.js`, is 2,990,736 bytes raw and
+425,026 bytes gzipped in the current measured build. For one rollback cycle
+the package also contains stock `stancjs.bc.js` (2,971,677 bytes raw, 418,847
+bytes gzipped). The worker loads the stock compiler only if the portable
+compiler is unavailable; its O1 legacy MIR remains accepted by the runtime.
+Carrying both temporarily doubles the compiler portion of the installed and
+downloaded package.
+
+The compiler loads lazily, only when a call passes Stan source. `preload()`
+starts the compiler and WASM loads in the background; call it at page idle so
+the first `sample()` skips the fetch and parse. An app that ships a fixed model
+can precompile it at build time (`stanc --O1 --debug-optimized-mir model.stan`)
+and pass `mir` instead of `code`; neither browser compiler loads, and the WASM
+runtime alone is ~1.5 MB gzipped.
+
+On Eight Schools, compact portable MIR is 6,932 bytes (1,793 gzipped), compared
+with 33,320 bytes (2,000 gzipped) for legacy MIR. Across 51 fresh processes on
+the same Apple arm64 release build, median decoder parsing was 0.074 ms versus
+0.293 ms, and complete preparation was 0.278 ms versus 0.682 ms. These are
+one-time preparation measurements; source compilation still dominates that
+path.
 
 118 of 119 posteriordb corpus models verify against CmdStan's log
 density, gradients, and write_array values from inside this WASM build;

package/index.mjs

@@ -1,7 +1,7 @@
-// stanli: full Stan in the browser. stanc3 (compiled to JS) turns Stan
-// source into MIR, and a WASM build of the stanli runtime lowers it to an
-// op graph and runs NUTS. Everything happens client side, off the main
-// thread, in workers this module owns.
+// stanli: full Stan in the browser. The custom stanc3 build (compiled to JS)
+// turns Stan source into portable MIR, and a WASM build of the stanli runtime
+// lowers it to an op graph and runs NUTS. Everything happens client side, off
+// the main thread, in workers this module owns.
 //
 //   import { compile, sample } from "@seantalts/stanli";
 //   const { mir } = await compile({ code });
@@ -10,9 +10,10 @@
 //
 // Workers pool up to the hardware's concurrency, so independent calls --
 // one chain each -- run simultaneously. Compiling once and passing `mir`
-// keeps the 2.8 MB compiler in a single worker (or out of the page
+// keeps the 3.0 MB preferred compiler in a single worker (or out of the page
 // entirely, if the model was precompiled at build time with
-// stanc --O1 --debug-optimized-mir).
+// stanc --O1 --debug-optimized-mir). The package carries stock stancjs for one
+// rollback cycle, but the worker loads it only if the portable compiler fails.
 
 const pool = [];
 const waiters = [];
@@ -88,7 +89,7 @@ export function preload(opts) {
   return Promise.all(jobs);
 }
 
-/** Compile Stan source to transformed MIR (one worker loads stanc3).
+/** Compile Stan source to portable MIR (one worker loads stanc3).
  * @returns {Promise<{mir: string, ms: {stanc: number}}>} */
 export function compile(opts) {
   return request({ cmd: "compile", code: opts.code }, opts);
@@ -99,10 +100,9 @@ export function compile(opts) {
  * @param {Object} opts
  * @param {string} [opts.code]     Stan source (compiled in the worker by
  *   stanc3, which loads lazily on first use).
- * @param {string} [opts.mir]      Precompiled MIR (from `compile()`
- *   here, or `stanc --O1 --debug-optimized-mir` at build time).
- *   When given, the 2.8 MB compiler never loads: the runtime alone is
- *   ~1.3 MB gzipped.
+ * @param {string} [opts.mir]      Precompiled MIR (from `compile()` here, or
+ *   `stanc --O1 --debug-optimized-mir` at build time). When given, neither
+ *   browser compiler loads: the runtime alone is ~1.5 MB gzipped.
  * @param {Object|string} [opts.data]  Data as an object or JSON text.
  * @param {number} [opts.seed=1]       Chain seed (sampler and GQ RNG).
  * @param {number} [opts.warmup=1000]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seantalts/stanli",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "Full Stan in the browser: stanc3 compiles the model in JS, a WASM runtime lowers it to an op graph and runs NUTS. No server, no C++ toolchain.",
   "type": "module",
   "main": "index.mjs",
@@ -12,6 +12,7 @@
     "worker.js",
     "stanli.js",
     "stanli.wasm",
+    "stanli-compiler.js",
     "stancjs.bc.js",
     "README.md",
     "LICENSE"