@adriansteffan/reactive 0.1.2 → 0.1.3

package/dist/{web-DmsP-pmx.js → web-CWqttxrD.js}

@@ -1,4 +1,4 @@
-import { W as e } from "./mod-Bb_FAy0j.js";
+import { W as e } from "./mod-DRCLdWzq.js";
 class s extends e {
   async enable() {
     console.log("Immersive mode is only available on Android");

package/dist/{web-BfWhpr9p.js → web-N9H86cSP.js}

@@ -1,4 +1,4 @@
-import { W as P, b as x, E } from "./mod-Bb_FAy0j.js";
+import { W as P, b as x, E } from "./mod-DRCLdWzq.js";
 function m(w) {
   const e = w.split("/").filter((t) => t !== "."), r = [];
   return e.forEach((t) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adriansteffan/reactive",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "type": "module",
   "scripts": {
     "dev": "vite",
@@ -40,9 +40,16 @@
     "@capacitor/filesystem": "^7.0.0",
     "@capacitor/share": "^7.0.0",
     "@capacitor/status-bar": "^7.0.0",
+    "@stdlib/random-base-mt19937": "^0.2.3",
+    "@stdlib/random-base-normal": "^0.2.2",
+    "@stdlib/random-base-poisson": "^0.2.2",
+    "@stdlib/random-base-uniform": "^0.2.3",
+    "@stdlib/stats-base-dists-normal-quantile": "^0.3.1",
+    "@stdlib/stats-base-dists-poisson-quantile": "^0.2.3",
     "@tanstack/react-query": "^5.61.3",
     "@tanstack/react-query-devtools": "^5.61.3",
     "@zip.js/zip.js": "^2.7.53",
+    "halton": "^1.0.0",
     "motion": "^12.38.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",

package/src/components/canvasblock.tsx

@@ -16,6 +16,7 @@ import {
 import { BaseComponentProps, isFullscreen, now } from '../utils/common';
 import { registerSimulation, ParticipantState } from '../utils/simulation';
 import { registerFlattener, arrayFlattener } from '../utils/upload';
+import { uniform } from '../utils/distributions';
 
 registerFlattener('CanvasBlock', 'canvas', arrayFlattener);
 
@@ -557,12 +558,12 @@ registerSimulation('CanvasBlock', (trialProps, experimentState, simulators, part
   respondToSlide: (slide: any, participant: any) => {
     const keys = slide.allowedKeys;
     if (keys === true) {
-      return { key: ' ', reactionTime: 200 + Math.random() * 600, participantState: participant };
+      return { key: ' ', reactionTime: uniform(200, 800), participantState: participant };
     }
     if (Array.isArray(keys) && keys.length > 0) {
       return {
-        key: keys[Math.floor(Math.random() * keys.length)],
-        reactionTime: 200 + Math.random() * 600,
+        key: keys[Math.floor(uniform(0, keys.length))],
+        reactionTime: uniform(200, 800),
         participantState: participant,
       };
     }

package/src/components/plaininput.tsx

@@ -2,12 +2,13 @@ import { BaseComponentProps } from '../mod';
 import { useState } from 'react';
 import { registerSimulation } from '../utils/simulation';
 import { registerFlattener } from '../utils/upload';
+import { uniform } from '../utils/distributions';
 
 registerFlattener('PlainInput', 'session');
 
 registerSimulation('PlainInput', (trialProps, _experimentState, simulators, participant) => {
   const result = simulators.respond(trialProps, participant);
-  const typingDuration = String(result.value).length * (50 + Math.random() * 100);
+  const typingDuration = String(result.value).length * uniform(50, 150);
   return {
     responseData: { value: result.value },
     participantState: result.participantState,

package/src/components/quest.tsx

@@ -5,6 +5,7 @@ import { ContrastLight } from 'survey-core/themes';
 import 'survey-core/survey-core.min.css';
 import { registerSimulation } from '../utils/simulation';
 import { registerFlattener } from '../utils/upload';
+import { uniform } from '../utils/distributions';
 
 registerFlattener('Quest', 'session');
 
@@ -28,21 +29,21 @@ registerSimulation('Quest', (trialProps, _experimentState, simulators, participa
     switch (question.type) {
       case 'rating': {
         const min = question.rateMin ?? 1, max = question.rateMax ?? 5;
-        value = min + Math.floor(Math.random() * (max - min + 1));
+        value = min + Math.floor(uniform(0, max - min + 1));
         break;
       }
-      case 'boolean': value = Math.random() > 0.5; break;
+      case 'boolean': value = uniform(0, 1) > 0.5; break;
       case 'text': case 'comment': value = 'simulated_response'; break;
       case 'radiogroup': case 'dropdown': {
-        const c = question.choices?.[Math.floor(Math.random() * (question.choices?.length || 0))];
+        const c = question.choices?.[Math.floor(uniform(0, question.choices?.length || 0))];
         value = c !== undefined ? (typeof c === 'object' ? c.value : c) : null;
         break;
       }
       case 'checkbox': {
         if (question.choices?.length) {
-          const n = 1 + Math.floor(Math.random() * question.choices.length);
+          const n = 1 + Math.floor(uniform(0, question.choices.length));
           value = [...question.choices]
-            .sort(() => Math.random() - 0.5).slice(0, n)
+            .sort(() => uniform(0, 1) - 0.5).slice(0, n)
             .map((c: any) => typeof c === 'object' ? c.value : c);
         }
         break;
@@ -51,7 +52,7 @@ registerSimulation('Quest', (trialProps, _experimentState, simulators, participa
         if (question.rows?.length && question.columns?.length) {
           value = Object.fromEntries(
             question.rows.map((r: any) => {
-              const col = question.columns[Math.floor(Math.random() * question.columns.length)];
+              const col = question.columns[Math.floor(uniform(0, question.columns.length))];
               return [typeof r === 'object' ? r.value : r, typeof col === 'object' ? col.value : col];
             }),
           );
@@ -60,7 +61,7 @@ registerSimulation('Quest', (trialProps, _experimentState, simulators, participa
       }
       default: value = null;
     }
-    return { value, participantState: participant, duration: 1000 + Math.random() * 4000 };
+    return { value, participantState: participant, duration: uniform(1000, 5000) };
   },
 });
 

package/src/components/randomdotkinetogram.tsx

@@ -11,6 +11,7 @@ import type { CSSProperties } from 'react';
 import { BaseComponentProps, shuffle } from '../mod';
 import { registerSimulation } from '../utils/simulation';
 import { registerFlattener } from '../utils/upload';
+import { uniform } from '../utils/distributions';
 
 registerFlattener('RandomDotKinematogram', 'rdk');
 
@@ -63,10 +64,10 @@ registerSimulation('RandomDotKinematogram', (trialProps, _experimentState, simul
 }, {
   respond: (trialProps: any, participant: any) => {
     const merged = { ...RDK_DEFAULTS, ...trialProps };
-    const rawRt = 200 + Math.random() * 600;
+    const rawRt = uniform(200, 800);
     const maxRt = merged.duration ?? RDK_DEFAULTS.duration;
     const responded = merged.validKeys.length > 0 && rawRt <= maxRt;
-    const key = responded ? merged.validKeys[Math.floor(Math.random() * merged.validKeys.length)] : null;
+    const key = responded ? merged.validKeys[Math.floor(uniform(0, merged.validKeys.length))] : null;
     const rt = responded ? rawRt : null;
     const correctKeys = Array.isArray(merged.correctResponse)
       ? merged.correctResponse.map((c: string) => c.toLowerCase())

package/src/components/text.tsx

@@ -2,6 +2,7 @@ import React, { useEffect, useRef } from 'react';
 import { BaseComponentProps, now } from '../mod';
 import { registerSimulation } from '../utils/simulation';
 import { registerFlattener } from '../utils/upload';
+import { uniform } from '../utils/distributions';
 
 registerFlattener('Text', 'text');
 
@@ -10,7 +11,7 @@ registerSimulation('Text', (trialProps, _experimentState, simulators, participan
   return { responseData: result.value, participantState: result.participantState, duration: result.value.reactionTime };
 }, {
   respond: (_input: any, participant: any) => ({
-    value: { key: 'button', reactionTime: 500 + Math.random() * 1500 },
+    value: { key: 'button', reactionTime: uniform(500, 2000) },
     participantState: participant,
   }),
 });

package/src/components/upload.tsx

@@ -16,9 +16,10 @@ import { BlobWriter, TextReader, ZipWriter } from '@zip.js/zip.js';
 import { Filesystem, Directory, Encoding } from '@capacitor/filesystem';
 import { buildUploadFiles, convertArrayOfObjectsToCSV } from '../utils/upload';
 import { registerSimulation, getBackendUrl, getInitialParticipant } from '../utils/simulation';
+import { uniform } from '../utils/distributions';
 
 registerSimulation('Upload', async (trialProps, experimentState, _simulators, participant) => {
-  const sessionID = trialProps.sessionID || `sim_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+  const sessionID = trialProps.sessionID || `sim_${Date.now()}_${Math.floor(uniform(0, 36 ** 6)).toString(36)}`;
   const files = buildUploadFiles({
     sessionID,
     data: experimentState.data || [],

package/src/mod.tsx

@@ -6,6 +6,8 @@ export * from './utils/array';
 export * from './utils/common';
 export * from './utils/simulation';
 export { registerFlattener, arrayFlattener } from './utils/upload';
+export { normal, poisson, uniform, seedDistributions, sobol, halton, sampleParticipants } from './utils/distributions';
+export type { DimensionSpec, UniformSpec, NormalSpec, PoissonSpec, SamplingMethod } from './utils/distributions';
 export * from './components';
 
 export * from 'react-toastify';

package/src/utils/array.ts

@@ -1,3 +1,5 @@
+import { uniform } from './distributions';
+
 declare global {
   interface Array<T> {
     /**
@@ -36,7 +38,7 @@ export function sample<T>(array: T[], n: number = 1): T[] {
   }
   
   for (let i = 0; i < n; i++) {
-    const randomIndex = Math.floor(Math.random() * array.length);
+    const randomIndex = Math.floor(uniform(0, 1) * array.length);
     result.push(array[randomIndex]);
   }
   
@@ -50,7 +52,7 @@ export function shuffle<T>(array: T[]): T[] {
   const result = [...array];
   
   for (let i = result.length - 1; i >= 0; i--) {
-    const j = Math.floor(Math.random() * (i + 1));
+    const j = Math.floor(uniform(0, 1) * (i + 1));
     [result[i], result[j]] = [result[j], result[i]];
   }
   return result;

package/src/utils/distributions.test.ts

@@ -0,0 +1,209 @@
+import { describe, it, expect } from 'vitest';
+import { sobol, halton, seedDistributions, normal, uniform, poisson, sampleParticipants } from './distributions';
+
+// Known Sobol sequence values (1D, Van der Corput base 2, skipping the zero point)
+// Reference: https://en.wikipedia.org/wiki/Van_der_Corput_sequence
+const SOBOL_1D_EXPECTED = [0.5, 0.75, 0.25, 0.375, 0.875, 0.625, 0.125, 0.1875];
+
+// Known Halton sequence values (base 2 and 3, skipping the zero point)
+// Reference: https://en.wikipedia.org/wiki/Halton_sequence
+const HALTON_2D_EXPECTED = [
+  [0.5, 1 / 3],
+  [0.25, 2 / 3],
+  [0.75, 1 / 9],
+  [0.125, 4 / 9],
+  [0.625, 7 / 9],
+];
+
+describe('sobol', () => {
+  it('produces known 1D Van der Corput values', () => {
+    const result = sobol(8, [{ distribution: 'uniform', min: 0, max: 1 }]) as number[];
+    expect(result).toHaveLength(8);
+    for (let i = 0; i < SOBOL_1D_EXPECTED.length; i++) {
+      expect(result[i]).toBeCloseTo(SOBOL_1D_EXPECTED[i], 10);
+    }
+  });
+
+  it('produces known 2D values', () => {
+    const result = sobol(4, [
+      { distribution: 'uniform', min: 0, max: 1 },
+      { distribution: 'uniform', min: 0, max: 1 },
+    ]) as number[][];
+    // First 2D Sobol points (after skipping zero): [0.5, 0.5], [0.75, 0.25], [0.25, 0.75]
+    expect(result[0]).toEqual([expect.closeTo(0.5, 10), expect.closeTo(0.5, 10)]);
+    expect(result[1]).toEqual([expect.closeTo(0.75, 10), expect.closeTo(0.25, 10)]);
+    expect(result[2]).toEqual([expect.closeTo(0.25, 10), expect.closeTo(0.75, 10)]);
+  });
+
+  it('scales uniform dimensions correctly', () => {
+    const result = sobol(3, [{ distribution: 'uniform', min: 200, max: 800 }]) as number[];
+    // 0.5 * 600 + 200 = 500, 0.75 * 600 + 200 = 650, 0.25 * 600 + 200 = 350
+    expect(result[0]).toBeCloseTo(500, 10);
+    expect(result[1]).toBeCloseTo(650, 10);
+    expect(result[2]).toBeCloseTo(350, 10);
+  });
+
+  it('produces correct count of points', () => {
+    const result = sobol(100, [{ distribution: 'uniform', min: 0, max: 1 }]) as number[];
+    expect(result).toHaveLength(100);
+  });
+
+  it('returns flat array for 1D, nested for multi-D', () => {
+    const r1 = sobol(3, [{ distribution: 'uniform', min: 0, max: 1 }]);
+    expect(typeof r1[0]).toBe('number');
+
+    const r2 = sobol(3, [
+      { distribution: 'uniform', min: 0, max: 1 },
+      { distribution: 'uniform', min: 0, max: 1 },
+    ]);
+    expect(Array.isArray(r2[0])).toBe(true);
+  });
+
+  it('all 1D values are in [0, 1] for unit range', () => {
+    const result = sobol(1000, [{ distribution: 'uniform', min: 0, max: 1 }]) as number[];
+    for (const v of result) {
+      expect(v).toBeGreaterThanOrEqual(0);
+      expect(v).toBeLessThan(1);
+    }
+  });
+
+  it('produces no duplicate points in 2D', () => {
+    const result = sobol(100, [
+      { distribution: 'uniform', min: 0, max: 1 },
+      { distribution: 'uniform', min: 0, max: 1 },
+    ]) as number[][];
+    const keys = new Set(result.map(([a, b]) => `${a},${b}`));
+    expect(keys.size).toBe(100);
+  });
+
+  it('is deterministic (same call twice gives same result)', () => {
+    const a = sobol(50, [{ distribution: 'uniform', min: 0, max: 1 }]);
+    const b = sobol(50, [{ distribution: 'uniform', min: 0, max: 1 }]);
+    expect(a).toEqual(b);
+  });
+
+  it('throws for dimensions > 21', () => {
+    const specs = Array.from({ length: 22 }, () => ({ distribution: 'uniform' as const, min: 0, max: 1 }));
+    expect(() => sobol(10, specs)).toThrow('1-21 dimensions');
+  });
+});
+
+describe('halton', () => {
+  it('produces known 2D values (bases 2, 3)', () => {
+    const result = halton(5, [
+      { distribution: 'uniform', min: 0, max: 1 },
+      { distribution: 'uniform', min: 0, max: 1 },
+    ]) as number[][];
+    for (let i = 0; i < HALTON_2D_EXPECTED.length; i++) {
+      expect(result[i][0]).toBeCloseTo(HALTON_2D_EXPECTED[i][0], 10);
+      expect(result[i][1]).toBeCloseTo(HALTON_2D_EXPECTED[i][1], 10);
+    }
+  });
+
+  it('is deterministic', () => {
+    const a = halton(50, [{ distribution: 'uniform', min: 0, max: 1 }]);
+    const b = halton(50, [{ distribution: 'uniform', min: 0, max: 1 }]);
+    expect(a).toEqual(b);
+  });
+});
+
+describe('normal distribution spec', () => {
+  it('produces values centered around the mean', () => {
+    const result = sobol(1000, [{ distribution: 'normal', mean: 500, sd: 100 }]) as number[];
+    const avg = result.reduce((a, b) => a + b, 0) / result.length;
+    expect(avg).toBeCloseTo(500, 0);
+  });
+
+  it('median is close to mean (symmetric distribution)', () => {
+    const result = sobol(1000, [{ distribution: 'normal', mean: 500, sd: 100 }]) as number[];
+    const sorted = [...result].sort((a, b) => a - b);
+    const median = sorted[500];
+    expect(median).toBeCloseTo(500, 0);
+  });
+});
+
+describe('poisson distribution spec', () => {
+  it('produces non-negative integers', () => {
+    const result = sobol(100, [{ distribution: 'poisson', mean: 5 }]) as number[];
+    for (const v of result) {
+      expect(v).toBeGreaterThanOrEqual(0);
+      expect(Number.isInteger(v)).toBe(true);
+    }
+  });
+
+  it('mean is close to lambda', () => {
+    const result = sobol(1000, [{ distribution: 'poisson', mean: 5 }]) as number[];
+    const avg = result.reduce((a, b) => a + b, 0) / result.length;
+    expect(avg).toBeCloseTo(5, 0);
+  });
+});
+
+describe('sampleParticipants', () => {
+  it('returns objects with the correct keys', () => {
+    const result = sampleParticipants('sobol', 5, {
+      rtMean: { distribution: 'normal', mean: 500, sd: 100 },
+      threshold: { distribution: 'uniform', min: 0.3, max: 0.7 },
+    });
+    expect(result).toHaveLength(5);
+    for (const p of result) {
+      expect(p).toHaveProperty('rtMean');
+      expect(p).toHaveProperty('threshold');
+      expect(typeof p.rtMean).toBe('number');
+      expect(typeof p.threshold).toBe('number');
+    }
+  });
+
+  it('sobol produces deterministic results', () => {
+    const a = sampleParticipants('sobol', 10, { x: { distribution: 'uniform', min: 0, max: 1 } });
+    const b = sampleParticipants('sobol', 10, { x: { distribution: 'uniform', min: 0, max: 1 } });
+    expect(a).toEqual(b);
+  });
+
+  it('halton produces deterministic results', () => {
+    const a = sampleParticipants('halton', 10, { x: { distribution: 'uniform', min: 0, max: 1 } });
+    const b = sampleParticipants('halton', 10, { x: { distribution: 'uniform', min: 0, max: 1 } });
+    expect(a).toEqual(b);
+  });
+
+  it('random method produces valid values', () => {
+    const result = sampleParticipants('random', 50, {
+      score: { distribution: 'poisson', mean: 5 },
+    });
+    expect(result).toHaveLength(50);
+    for (const p of result) {
+      expect(Number.isInteger(p.score)).toBe(true);
+      expect(p.score).toBeGreaterThanOrEqual(0);
+    }
+  });
+
+  it('works with a single dimension', () => {
+    const result = sampleParticipants('sobol', 3, {
+      rt: { distribution: 'uniform', min: 200, max: 800 },
+    });
+    expect(result[0].rt).toBeCloseTo(500, 10);
+    expect(result[1].rt).toBeCloseTo(650, 10);
+    expect(result[2].rt).toBeCloseTo(350, 10);
+  });
+});
+
+describe('seedDistributions', () => {
+  it('makes pseudorandom samplers reproducible', () => {
+    seedDistributions(42);
+    const a = [normal(0, 1), uniform(0, 10), poisson(5)];
+
+    seedDistributions(42);
+    const b = [normal(0, 1), uniform(0, 10), poisson(5)];
+
+    expect(a).toEqual(b);
+  });
+
+  it('different seeds produce different sequences', () => {
+    seedDistributions(1);
+    const a = normal(0, 1);
+
+    seedDistributions(2);
+    const b = normal(0, 1);
+
+    expect(a).not.toBe(b);
+  });
+});

package/src/utils/distributions.ts

@@ -0,0 +1,191 @@
+import mt19937 from '@stdlib/random-base-mt19937';
+import normalFactory from '@stdlib/random-base-normal';
+import poissonFactory from '@stdlib/random-base-poisson';
+import uniformFactory from '@stdlib/random-base-uniform';
+import normalQuantile from '@stdlib/stats-base-dists-normal-quantile';
+import poissonQuantile from '@stdlib/stats-base-dists-poisson-quantile';
+import generateHalton from 'halton';
+
+// --- Pseudorandom samplers (seedable) ---
+
+let normal: (mu: number, sigma: number) => number = normalFactory;
+let poisson: (lambda: number) => number = poissonFactory;
+let uniform: (min: number, max: number) => number = uniformFactory;
+
+interface StdlibPRNG {
+  normalized: () => number;
+}
+
+function seedDistributions(seed: number): void {
+  const prng = mt19937.factory({ seed }) as unknown as StdlibPRNG;
+  normal = normalFactory.factory({ prng: prng.normalized });
+  poisson = poissonFactory.factory({ prng: prng.normalized });
+  uniform = uniformFactory.factory({ prng: prng.normalized });
+  Math.random = () => uniform(0, 1);
+}
+
+// --- QMC dimension specs ---
+// Inverse CDF transform: https://en.wikipedia.org/wiki/Inverse_transform_sampling
+
+type UniformSpec = { distribution: 'uniform'; min: number; max: number };
+type NormalSpec = { distribution: 'normal'; mean: number; sd: number };
+type PoissonSpec = { distribution: 'poisson'; mean: number };
+type DimensionSpec = UniformSpec | NormalSpec | PoissonSpec;
+
+// Inverse CDFs return +-Infinity at exactly 0 or 1, so clamp to open interval (0, 1).
+function clampUnit(value: number): number {
+  return Math.max(1e-10, Math.min(1 - 1e-10, value));
+}
+
+function resolveTransform(spec: DimensionSpec): (unitValue: number) => number {
+  switch (spec.distribution) {
+    case 'uniform':
+      return (u) => spec.min + u * (spec.max - spec.min);
+    case 'normal':
+      return (u) => normalQuantile(clampUnit(u), spec.mean, spec.sd);
+    case 'poisson':
+      // QMC variance reduction is less effective on discrete distributions
+      // due to integer clumping at quantile boundaries.
+      return (u) => poissonQuantile(clampUnit(u), spec.mean);
+  }
+}
+
+function transformPoints(unitPoints: number[][], specs: DimensionSpec[]): number[] | number[][] {
+  const transforms = specs.map(resolveTransform);
+  if (specs.length === 1) {
+    return unitPoints.map((point) => transforms[0](point[0]));
+  }
+  return unitPoints.map((point) =>
+    point.map((unitValue, dim) => transforms[dim](unitValue)),
+  );
+}
+
+// --- Sobol sequence (browser-compatible implementation as existing packages want to use fs) ---
+// Algorithm: Bratley & Fox (1988), https://doi.org/10.1145/42288.214372
+// Joe-Kuo direction numbers for dimensions 2-21 (dimension 1 uses Van der Corput base 2).
+// Each entry is [degree, polynomialCoefficients, initialDirectionNumbers].
+// Direction numbers: Joe & Kuo (2008), https://doi.org/10.1137/070709359
+// Data: https://web.maths.unsw.edu.au/~fkuo/sobol/joe-kuo-old.1111
+const JOE_KUO: [number, number, number[]][] = [
+  [1, 0, [1]],                          // dim 2
+  [2, 1, [1, 1]],                       // dim 3
+  [3, 1, [1, 3, 7]],                    // dim 4
+  [3, 2, [1, 1, 5]],                    // dim 5
+  [4, 1, [1, 3, 1, 1]],                 // dim 6
+  [4, 4, [1, 1, 3, 7]],                 // dim 7
+  [5, 2, [1, 3, 3, 9, 9]],              // dim 8
+  [5, 13, [1, 3, 7, 13, 3]],            // dim 9
+  [5, 7, [1, 1, 5, 11, 27]],            // dim 10
+  [5, 14, [1, 3, 5, 1, 15]],            // dim 11
+  [5, 11, [1, 1, 7, 3, 29]],            // dim 12
+  [5, 4, [1, 3, 7, 7, 21]],             // dim 13
+  [6, 1, [1, 1, 1, 9, 23, 37]],         // dim 14
+  [6, 16, [1, 3, 3, 5, 19, 33]],        // dim 15
+  [6, 13, [1, 1, 3, 13, 11, 7]],        // dim 16
+  [6, 22, [1, 1, 7, 13, 25, 5]],        // dim 17
+  [6, 19, [1, 3, 5, 11, 7, 11]],        // dim 18
+  [6, 25, [1, 1, 1, 3, 13, 39]],        // dim 19
+  [7, 1, [1, 3, 1, 15, 17, 63, 13]],    // dim 20
+  [7, 32, [1, 1, 5, 5, 1, 59, 33]],     // dim 21
+];
+
+const BITS = 32;
+const SCALE = 2 ** BITS;
+
+function buildDirectionNumbers(dimension: number): Uint32Array {
+  const directions = new Uint32Array(BITS);
+  if (dimension === 0) {
+    for (let i = 0; i < BITS; i++) directions[i] = 1 << (BITS - 1 - i);
+    return directions;
+  }
+  const [degree, coefficients, initial] = JOE_KUO[dimension - 1];
+  for (let i = 0; i < degree; i++) directions[i] = initial[i] << (BITS - 1 - i);
+  for (let i = degree; i < BITS; i++) {
+    directions[i] = directions[i - degree] ^ (directions[i - degree] >>> degree);
+    for (let j = 1; j < degree; j++) {
+      if ((coefficients >>> (degree - 1 - j)) & 1) directions[i] ^= directions[i - j];
+    }
+  }
+  return directions;
+}
+
+function generateSobol(count: number, dimensions: number): number[][] {
+  if (dimensions < 1 || dimensions > 21) {
+    throw new RangeError('sobol() supports 1-21 dimensions');
+  }
+  const allDirections = Array.from({ length: dimensions }, (_, dim) => buildDirectionNumbers(dim));
+  const state = new Uint32Array(dimensions);
+  const points: number[][] = [new Array<number>(dimensions).fill(0)];
+  for (let index = 1; index < count; index++) {
+    // Find the position of the rightmost zero bit
+    let rightmostZero = 0;
+    let bits = index - 1;
+    while ((bits & 1) === 1) { bits >>>= 1; rightmostZero++; }
+    for (let dim = 0; dim < dimensions; dim++) state[dim] ^= allDirections[dim][rightmostZero];
+    points.push(Array.from(state, (value) => value / SCALE));
+  }
+  return points;
+}
+
+// --- Halton sequence ---
+// Halton (1960), https://doi.org/10.1007/BF01386213
+const PRIMES = [2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59, 61, 67, 71, 73];
+const HALTON_MAX_EFFECTIVE_DIMS = 6;
+
+function sobol(count: number, specs: DimensionSpec[]): number[] | number[][] {
+  // Generate count+1 and skip the first point (always zero in every dimension)
+  const unitPoints = generateSobol(count + 1, specs.length).slice(1);
+  return transformPoints(unitPoints, specs);
+}
+
+function halton(count: number, specs: DimensionSpec[]): number[] | number[][] {
+  if (specs.length > HALTON_MAX_EFFECTIVE_DIMS) {
+    console.warn(`Halton sequence quality degrades above ${HALTON_MAX_EFFECTIVE_DIMS} dimensions. Consider using sobol() instead.`);
+  }
+  const bases = PRIMES.slice(0, specs.length);
+  // Generate count+1 and skip the first point (always zero in every dimension)
+  const unitPoints = (generateHalton(count + 1, bases) as number[][]).slice(1);
+  return transformPoints(unitPoints, specs);
+}
+
+type SamplingMethod = 'sobol' | 'halton' | 'random';
+
+function sampleParticipants<T extends Record<string, DimensionSpec>>(
+  method: SamplingMethod,
+  count: number,
+  specs: T,
+): Array<{ [K in keyof T]: number }> {
+  const keys = Object.keys(specs) as (keyof T & string)[];
+  const dimSpecs = keys.map((k) => specs[k]);
+
+  let points: number[] | number[][];
+  switch (method) {
+    case 'sobol':
+      points = sobol(count, dimSpecs);
+      break;
+    case 'halton':
+      points = halton(count, dimSpecs);
+      break;
+    case 'random':
+      points = randomPoints(count, dimSpecs);
+      break;
+  }
+
+  return Array.from({ length: count }, (_, i) => {
+    const row = keys.length === 1 ? [points[i] as number] : (points[i] as number[]);
+    return Object.fromEntries(keys.map((k, d) => [k, row[d]])) as { [K in keyof T]: number };
+  });
+}
+
+function randomPoints(count: number, specs: DimensionSpec[]): number[] | number[][] {
+  const transforms = specs.map(resolveTransform);
+  if (specs.length === 1) {
+    return Array.from({ length: count }, () => transforms[0](uniform(0, 1)));
+  }
+  return Array.from({ length: count }, () =>
+    transforms.map((t) => t(uniform(0, 1))),
+  );
+}
+
+export { normal, poisson, uniform, seedDistributions, sobol, halton, sampleParticipants };
+export type { DimensionSpec, UniformSpec, NormalSpec, PoissonSpec, SamplingMethod };

package/src/utils/simulation.ts

@@ -151,7 +151,9 @@ export async function simulateParticipant(
 
 
 export interface RunSimulationConfig {
-  participants: ParticipantState[] | { generator: (index: number) => ParticipantState; count: number };
+  participants: ParticipantState[] | { generator: (index: number) => ParticipantState; count: number } | (() => ParticipantState[]);
+  /** Seed for reproducible simulations. Each participant gets seed + workerIndex. */
+  seed?: number;
   backendPort?: number;
   concurrency?: number;
 }
@@ -162,9 +164,11 @@ export async function orchestrateSimulation(config: RunSimulationConfig, scriptP
   const port = config.backendPort ?? 8001;
   const backendUrl = `http://localhost:${port}/backend`;
 
-  const participantCount = Array.isArray(config.participants)
-    ? config.participants.length
-    : config.participants.count;
+  const participantCount = typeof config.participants === 'function'
+    ? config.participants().length
+    : Array.isArray(config.participants)
+      ? config.participants.length
+      : config.participants.count;
 
   const backend = spawn('npx', ['tsx', 'src/backend.ts'], {
     cwd: './backend',
@@ -212,6 +216,7 @@ export async function orchestrateSimulation(config: RunSimulationConfig, scriptP
           ...process.env,
           _REACTIVE_WORKER_INDEX: String(i),
           _REACTIVE_BACKEND_URL: backendUrl,
+          ...(config.seed !== undefined ? { _REACTIVE_SIMULATION_SEED: String(config.seed) } : {}),
         },
         stdio: ['ignore', 'pipe', 'pipe'],
       });