@seantalts/stanli 0.1.0

package/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Sean Talts
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,47 @@
+# 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/>.
+
+```js
+import { sample } from "@seantalts/stanli";
+
+const fit = await sample({
+  code: `
+    data { int N; array[N] real y; }
+    parameters { real mu; real<lower=0> sigma; }
+    model { y ~ normal(mu, sigma); }`,
+  data: { N: 3, y: [1.1, 0.4, 2.2] },
+  seed: 1,
+  onProgress: (s) => console.log(s),
+});
+
+fit.columns["mu"];     // Float64Array, one entry per draw
+fit.names;             // every CSV column CmdStan would write
+fit.ms;                // {stanc, lower, sample, total} in milliseconds
+```
+
+Columns cover the full CmdStan CSV: constrained parameters, transformed
+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 and the user's first `sample()` begins at full
+speed instead of paying the fetch and parse on their click; an app that ships a fixed model can precompile
+it at build time (`stanc --debug-transformed-mir model.stan`) and pass
+`mir` instead of `code`, and the runtime alone is ~1.5 MB gzipped. 118 of 119 posteriordb corpus models
+verify against CmdStan's log density, gradients, and write_array values
+from inside this WASM build; see the
+[repository](https://github.com/seantalts/stanli) for the verification
+policy and numbers.
+
+Not yet here: variational inference, optimization, multi-chain
+threading. `wasm32` caps memory at 4 GB, which one 79,000-parameter
+corpus model exceeds; everything typical fits.

package/index.mjs

@@ -0,0 +1,146 @@
+// 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.
+//
+//   import { compile, sample } from "@seantalts/stanli";
+//   const { mir } = await compile({ code });
+//   const fits = await Promise.all([1, 2, 3, 4].map((c) =>
+//       sample({ mir, data, seed: c })));
+//
+// 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
+// entirely, if the model was precompiled at build time with
+// stanc --debug-transformed-mir).
+
+const pool = [];
+const waiters = [];
+const MAX_WORKERS = Math.max(
+    2, Math.min(8, ((typeof navigator !== "undefined" &&
+                     navigator.hardwareConcurrency) || 4)));
+
+function acquire() {
+  let slot = pool.find((s) => !s.busy);
+  if (!slot && pool.length < MAX_WORKERS) {
+    slot = { worker: new Worker(new URL("./worker.js", import.meta.url)),
+             busy: false };
+    pool.push(slot);
+  }
+  if (slot) {
+    slot.busy = true;
+    return Promise.resolve(slot);
+  }
+  return new Promise((res) => waiters.push(res));
+}
+
+function release(slot) {
+  const next = waiters.shift();
+  if (next) next(slot);  // handed over still busy
+  else slot.busy = false;
+}
+
+function request(msg, opts) {
+  return acquire().then((slot) => {
+    const w = slot.worker;
+    return new Promise((resolve, reject) => {
+      w.onmessage = (e) => {
+        const m = e.data;
+        if (m.status) {
+          if (opts.onProgress) opts.onProgress(m.status);
+          return;
+        }
+        if (m.liveMeta || m.live) {
+          if (opts.onLive) opts.onLive(m);
+          return;
+        }
+        if (m.error) reject(new Error(m.error));
+        else resolve(m.done);
+      };
+      w.onerror = (e) => {
+        reject(new Error("stanli worker: " + (e.message ||
+                                              "failed to load")));
+      };
+      w.postMessage(msg);
+    }).finally(() => {
+      w.onmessage = null;
+      w.onerror = null;
+      release(slot);
+    });
+  });
+}
+
+/** Load the heavy artifacts before they are needed. Resolves when one
+ * worker holds the parsed stanc3 compiler and `chains - 1` more hold the
+ * instantiated wasm runtime, so a later compile() or sample() starts at
+ * full speed instead of paying the fetch+parse on the user's click.
+ * Safe to call more than once; the pool reuses warmed workers.
+ * @param {object} [opts]
+ * @param {number} [opts.chains=2] Workers to warm (first gets stanc3).
+ * @param {function} [opts.onProgress]
+ */
+export function preload(opts) {
+  const o = opts || {};
+  const n = Math.max(1, Math.min(MAX_WORKERS, o.chains || 2));
+  const jobs = [request({ cmd: "preload", stanc: true }, o)];
+  for (let k = 1; k < n; ++k)
+    jobs.push(request({ cmd: "preload", stanc: false }, o));
+  return Promise.all(jobs);
+}
+
+/** Compile Stan source to transformed MIR (one worker loads stanc3).
+ * @returns {Promise<{mir: string, ms: {stanc: number}}>} */
+export function compile(opts) {
+  return request({ cmd: "compile", code: opts.code }, opts);
+}
+
+/** Compile (unless `mir` is given) and draw from the posterior.
+ *
+ * @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 transformed MIR (from
+ *   `compile()` here, or `stanc --debug-transformed-mir` at build time).
+ *   When given, the 2.8 MB compiler never loads: the runtime alone is
+ *   ~1.3 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]
+ * @param {number} [opts.samples=1000]
+ * @param {number} [opts.delta=0.8]    Adaptation target acceptance.
+ * @param {function(string)} [opts.onProgress]  Stage announcements.
+ * @param {function(Object)} [opts.onLive]  Streaming draws while NUTS
+ *   runs: {liveMeta: {names, warmup, samples}} once per call, then
+ *   {live: {phase: "warmup"|"sampling", i, nCon?, rows?}} where rows is
+ *   a transferred ArrayBuffer of constrained draws, nCon wide.
+ * @returns {Promise<{names: string[], samples: number,
+ *                    columns: Object<string, Float64Array>,
+ *                    exactLp: boolean,
+ *                    ms: {stanc: number, lower: number, sample: number,
+ *                         total: number}}>}
+ *   One column per CSV column CmdStan would write: constrained
+ *   parameters, transformed parameters, and generated quantities.
+ */
+export function sample(opts) {
+  return request({
+    cmd: "run",
+    code: opts.code,
+    mir: opts.mir,
+    live: !!opts.onLive,
+    dataJson: typeof opts.data === "string"
+        ? opts.data
+        : JSON.stringify(opts.data || {}),
+    seed: opts.seed == null ? 1 : opts.seed,
+    warmup: opts.warmup == null ? 1000 : opts.warmup,
+    samples: opts.samples == null ? 1000 : opts.samples,
+    delta: opts.delta == null ? 0.8 : opts.delta,
+  }, opts).then((done) => {
+    const { names, samples, ms, exactLp } = done;
+    const flat = new Float64Array(done.columns);
+    const columns = {};
+    names.forEach((name, i) => {
+      columns[name] = flat.subarray(i * samples, (i + 1) * samples);
+    });
+    return { names, samples, columns, ms, exactLp };
+  });
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@seantalts/stanli",
+  "version": "0.1.0",
+  "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",
+  "exports": {
+    ".": "./index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "worker.js",
+    "stanli.js",
+    "stanli.wasm",
+    "stancjs.bc.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/seantalts/stanli.git"
+  },
+  "homepage": "https://seantalts.github.io/stanli/",
+  "license": "BSD-3-Clause",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "stan",
+    "bayesian",
+    "mcmc",
+    "nuts",
+    "statistics",
+    "wasm",
+    "webassembly"
+  ]
+}