@vune-ui/animation 0.1.20

package/dist/src/webgl/index.js

@@ -0,0 +1,94 @@
+import { FrameBatcher } from '../render/frame-batcher.js';
+
+function normalizeValues(input) {
+  return Array.isArray(input) ? input : [input];
+}
+
+function inferType(length) {
+  if (length === 1) return '1f';
+  if (length >= 2 && length <= 4) return `${length}fv`;
+  if (length === 16) return 'matrix4fv';
+  throw new RangeError('WebGL uniform bindings support 1, 2, 3, 4, or 16 scalar values.');
+}
+
+export class WebGLUniformBinder {
+  constructor(gl, program, bindings = [], {
+    autoUseProgram = true,
+    requestFrame,
+    cancelFrame,
+    flushInitial = true,
+  } = {}) {
+    if (!gl) throw new TypeError('WebGLUniformBinder requires a WebGL-like context.');
+    this.gl = gl;
+    this.program = program;
+    this.autoUseProgram = autoUseProgram;
+    this.entries = [];
+    this.unsubscribers = [];
+    this.dirtyCount = 0;
+    this.disposed = false;
+    this.batcher = new FrameBatcher(() => this.flush(), { requestFrame, cancelFrame });
+    for (const binding of bindings) this.add(binding);
+    if (flushInitial && this.entries.length) this.batcher.invalidate();
+  }
+
+  add({ name, location, values, value, type } = {}) {
+    const motions = normalizeValues(values ?? value);
+    if (motions.length === 0 || motions.some((motion) => !motion?.get)) throw new TypeError('WebGL uniform binding requires MotionValue-like values.');
+    const resolvedLocation = location ?? this.gl.getUniformLocation?.(this.program, name);
+    if (resolvedLocation == null) throw new Error(`WebGL uniform '${name ?? '<unnamed>'}' was not found.`);
+    const resolvedType = type ?? inferType(motions.length);
+    const data = new Float32Array(motions.length);
+    const entry = { name, location: resolvedLocation, values: motions, type: resolvedType, data, dirty: true };
+    this.entries.push(entry);
+    this.dirtyCount += 1;
+
+    motions.forEach((motion, index) => {
+      data[index] = Number(motion.get()) || 0;
+      const subscribe = motion.subscribeValue ?? motion.subscribe;
+      this.unsubscribers.push(subscribe.call(motion, (next) => {
+        data[index] = Number(next) || 0;
+        if (!entry.dirty) { entry.dirty = true; this.dirtyCount += 1; }
+        this.batcher.invalidate();
+      }, { emitCurrent: false }));
+    });
+    return this;
+  }
+
+  flush() {
+    if (this.disposed || this.dirtyCount === 0) return 0;
+    const gl = this.gl;
+    if (this.autoUseProgram && typeof gl.useProgram === 'function') gl.useProgram(this.program);
+    let writes = 0;
+    for (const entry of this.entries) {
+      if (!entry.dirty) continue;
+      switch (entry.type) {
+        case '1f': gl.uniform1f(entry.location, entry.data[0]); break;
+        case '2fv': gl.uniform2fv(entry.location, entry.data); break;
+        case '3fv': gl.uniform3fv(entry.location, entry.data); break;
+        case '4fv': gl.uniform4fv(entry.location, entry.data); break;
+        case 'matrix4fv': gl.uniformMatrix4fv(entry.location, false, entry.data); break;
+        default: throw new TypeError(`Unsupported WebGL uniform type '${entry.type}'.`);
+      }
+      entry.dirty = false;
+      writes += 1;
+    }
+    this.dirtyCount = 0;
+    return writes;
+  }
+
+  flushNow() { this.batcher.flushNow(); return this; }
+
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.batcher.dispose();
+    for (const unsubscribe of this.unsubscribers) unsubscribe?.();
+    this.unsubscribers.length = 0;
+    this.entries.length = 0;
+    this.dirtyCount = 0;
+  }
+}
+
+export function createWebGLUniformBinder(gl, program, bindings, options) {
+  return new WebGLUniformBinder(gl, program, bindings, options);
+}

package/dist/src/webgpu/index.d.ts

@@ -0,0 +1,35 @@
+import type { MotionValue } from '../../index.js';
+export class WebGPUSpringBatch {
+  constructor(device: unknown, capacity?: number);
+  static isSupported(device?: unknown): boolean;
+  static create(capacity?: number, device?: unknown): Promise<WebGPUSpringBatch>;
+  readonly kind: 'webgpu';
+  readonly variant: 'compute';
+  readonly capacity: number;
+  readonly positions: Float32Array;
+  readonly velocities: Float32Array;
+  readonly targets: Float32Array;
+  readonly omegas: Float32Array;
+  readonly dampingRatios: Float32Array;
+  ensureCapacity(required: number): void;
+  step(count: number, dtSeconds: number): never;
+  stepAsync(count: number, dtSeconds: number): Promise<void>;
+  copyInto(other: { positions: Float32Array; velocities: Float32Array; targets: Float32Array; omegas: Float32Array; dampingRatios: Float32Array }, count: number): void;
+  dispose(): void;
+}
+export type WebGPUValueBinding = MotionValue | { value: MotionValue; index?: number };
+export class WebGPUBufferBinder {
+  constructor(device: { queue: { writeBuffer(...args: any[]): void } }, buffer: unknown, bindings: WebGPUValueBinding[], options?: {
+    byteOffset?: number;
+    floatCount?: number;
+    requestFrame?: (callback: FrameRequestCallback) => any;
+    cancelFrame?: (id: any) => void;
+    flushInitial?: boolean;
+  });
+  readonly data: Float32Array;
+  readonly writes: number;
+  flush(): boolean;
+  flushNow(): this;
+  dispose(): void;
+}
+export function createWebGPUBufferBinder(device: ConstructorParameters<typeof WebGPUBufferBinder>[0], buffer: unknown, bindings: WebGPUValueBinding[], options?: ConstructorParameters<typeof WebGPUBufferBinder>[3]): WebGPUBufferBinder;

package/dist/src/webgpu/index.js

@@ -0,0 +1,73 @@
+import { FrameBatcher } from '../render/frame-batcher.js';
+export { WebGPUSpringBatch } from './spring-batch.js';
+
+function normalizeBinding(binding, fallbackIndex) {
+  if (binding?.get) return { value: binding, index: fallbackIndex };
+  if (binding?.value?.get) return { value: binding.value, index: Number.isInteger(binding.index) ? binding.index : fallbackIndex };
+  throw new TypeError('WebGPU binding requires a MotionValue or { value, index } entry.');
+}
+
+export class WebGPUBufferBinder {
+  constructor(device, buffer, bindings, {
+    byteOffset = 0,
+    floatCount,
+    requestFrame,
+    cancelFrame,
+    flushInitial = true,
+  } = {}) {
+    if (!device?.queue?.writeBuffer) throw new TypeError('WebGPUBufferBinder requires a GPUDevice-like object with queue.writeBuffer().');
+    if (!buffer) throw new TypeError('WebGPUBufferBinder requires a GPUBuffer-like target.');
+    if (!Array.isArray(bindings) || bindings.length === 0) throw new TypeError('WebGPUBufferBinder requires at least one binding.');
+    this.device = device;
+    this.buffer = buffer;
+    this.byteOffset = Math.max(0, Math.floor(Number(byteOffset) || 0));
+    this.bindings = bindings.map(normalizeBinding);
+    const required = this.bindings.reduce((max, entry) => Math.max(max, entry.index + 1), 0);
+    const count = floatCount == null ? required : Math.max(required, Math.floor(floatCount));
+    this.data = new Float32Array(count);
+    this.unsubscribers = [];
+    this.writes = 0;
+    this.disposed = false;
+    this.dirty = true;
+    this.batcher = new FrameBatcher(() => this.flush(), { requestFrame, cancelFrame });
+
+    for (const entry of this.bindings) {
+      this.data[entry.index] = Number(entry.value.get()) || 0;
+      const subscribe = entry.value.subscribeValue ?? entry.value.subscribe;
+      this.unsubscribers.push(subscribe.call(entry.value, (next) => {
+        this.data[entry.index] = Number(next) || 0;
+        this.dirty = true;
+        this.batcher.invalidate();
+      }, { emitCurrent: false }));
+    }
+    if (flushInitial) this.batcher.invalidate();
+  }
+
+  flush() {
+    if (this.disposed || !this.dirty) return false;
+    this.device.queue.writeBuffer(
+      this.buffer,
+      this.byteOffset,
+      this.data.buffer,
+      this.data.byteOffset,
+      this.data.byteLength,
+    );
+    this.dirty = false;
+    this.writes += 1;
+    return true;
+  }
+
+  flushNow() { this.batcher.flushNow(); return this; }
+
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.batcher.dispose();
+    for (const unsubscribe of this.unsubscribers) unsubscribe?.();
+    this.unsubscribers.length = 0;
+  }
+}
+
+export function createWebGPUBufferBinder(device, buffer, bindings, options) {
+  return new WebGPUBufferBinder(device, buffer, bindings, options);
+}

package/dist/src/webgpu/spring-batch.js

@@ -0,0 +1,218 @@
+const DEFAULT_WORKGROUP_SIZE = 64;
+const MAX_STEP_SECONDS = 1 / 240;
+const MAX_SUBSTEPS = 32;
+const FLOATS_PER_SPRING = 8;
+
+const BUFFER_USAGE = globalThis.GPUBufferUsage ?? {
+  MAP_READ: 1,
+  COPY_SRC: 4,
+  COPY_DST: 8,
+  STORAGE: 128,
+  UNIFORM: 64,
+};
+const MAP_MODE = globalThis.GPUMapMode ?? { READ: 1 };
+
+const SPRING_SHADER = /* wgsl */ `
+struct Spring {
+  state: vec4<f32>,
+  dynamics: vec4<f32>,
+};
+
+struct Params {
+  dt: f32,
+  count: u32,
+  _padding: vec2<u32>,
+};
+
+@group(0) @binding(0) var<storage, read_write> springs: array<Spring>;
+@group(0) @binding(1) var<uniform> params: Params;
+
+@compute @workgroup_size(64)
+fn step(@builtin(global_invocation_id) id: vec3<u32>) {
+  if (id.x >= params.count) { return; }
+
+  var spring = springs[id.x];
+  let x = spring.state.x;
+  let v = spring.state.y;
+  let target = spring.state.z;
+  let omega = spring.state.w;
+  let damping = spring.dynamics.x;
+  let acceleration = omega * omega * (target - x) - 2.0 * damping * omega * v;
+  let nextVelocity = v + acceleration * params.dt;
+  spring.state.x = x + nextVelocity * params.dt;
+  spring.state.y = nextVelocity;
+  springs[id.x] = spring;
+}
+`;
+
+function normalizeCapacity(capacity) {
+  const value = Math.floor(Number(capacity));
+  if (!Number.isFinite(value) || value < 1) throw new RangeError('WebGPU spring capacity must be a positive integer.');
+  return value;
+}
+
+function substepCount(dtSeconds) {
+  let steps = 1;
+  while (dtSeconds / steps > MAX_STEP_SECONDS && steps < MAX_SUBSTEPS) steps += 1;
+  return steps;
+}
+
+/**
+ * WebGPU compute backend for dense spring batches. The host arrays mirror the
+ * JS/WASM batch contract so MotionEngine can promote and demote without
+ * changing animation semantics. Frames are asynchronous because readback is
+ * required before values can be committed to MotionValue instances.
+ */
+export class WebGPUSpringBatch {
+  static isSupported(device) {
+    return Boolean(device?.createBuffer
+      && device?.createShaderModule
+      && device?.createComputePipeline
+      && device?.createBindGroup
+      && device?.createCommandEncoder
+      && device?.queue?.submit
+      && device?.queue?.writeBuffer);
+  }
+
+  static async create(capacity = 65536, device) {
+    if (capacity && typeof capacity === 'object') {
+      device = capacity;
+      capacity = 65536;
+    }
+    let resolvedDevice = device;
+    if (!resolvedDevice) {
+      const gpu = globalThis.navigator?.gpu ?? globalThis.gpu;
+      if (!gpu?.requestAdapter) throw new Error('WebGPU is unavailable in this environment.');
+      const adapter = await gpu.requestAdapter();
+      if (!adapter?.requestDevice) throw new Error('No WebGPU adapter is available.');
+      resolvedDevice = await adapter.requestDevice();
+    }
+    if (!WebGPUSpringBatch.isSupported(resolvedDevice)) throw new Error('The WebGPU device does not support compute buffers.');
+    return new WebGPUSpringBatch(resolvedDevice, capacity);
+  }
+
+  constructor(device, capacity = 65536) {
+    if (!WebGPUSpringBatch.isSupported(device)) throw new TypeError('WebGPUSpringBatch requires a GPUDevice-like object.');
+    this.kind = 'webgpu';
+    this.variant = 'compute';
+    this.device = device;
+    this.capacity = normalizeCapacity(capacity);
+    this.positions = new Float32Array(this.capacity);
+    this.velocities = new Float32Array(this.capacity);
+    this.targets = new Float32Array(this.capacity);
+    this.omegas = new Float32Array(this.capacity);
+    this.dampingRatios = new Float32Array(this.capacity);
+    this.packed = new Float32Array(this.capacity * FLOATS_PER_SPRING);
+    this.params = new Uint32Array(4);
+    this.paramsFloat = new Float32Array(this.params.buffer);
+    this.stepChain = Promise.resolve();
+    this.disposed = false;
+
+    const byteLength = this.packed.byteLength;
+    this.storageBuffer = device.createBuffer({
+      size: byteLength,
+      usage: BUFFER_USAGE.STORAGE | BUFFER_USAGE.COPY_SRC | BUFFER_USAGE.COPY_DST,
+    });
+    this.readbackBuffer = device.createBuffer({
+      size: byteLength,
+      usage: BUFFER_USAGE.MAP_READ | BUFFER_USAGE.COPY_DST,
+    });
+    this.paramsBuffer = device.createBuffer({
+      size: this.params.byteLength,
+      usage: BUFFER_USAGE.UNIFORM | BUFFER_USAGE.COPY_DST,
+    });
+    const module = device.createShaderModule({ code: SPRING_SHADER });
+    this.pipeline = device.createComputePipeline({
+      layout: 'auto',
+      compute: { module, entryPoint: 'step' },
+    });
+    this.bindGroup = device.createBindGroup({
+      layout: this.pipeline.getBindGroupLayout(0),
+      entries: [
+        { binding: 0, resource: { buffer: this.storageBuffer } },
+        { binding: 1, resource: { buffer: this.paramsBuffer } },
+      ],
+    });
+  }
+
+  ensureCapacity(required) {
+    if (required > this.capacity) throw new RangeError(`WebGPU spring capacity exceeded (${required} > ${this.capacity}).`);
+  }
+
+  copyInto(other, count) {
+    other.positions.set(this.positions.subarray(0, count));
+    other.velocities.set(this.velocities.subarray(0, count));
+    other.targets.set(this.targets.subarray(0, count));
+    other.omegas.set(this.omegas.subarray(0, count));
+    other.dampingRatios.set(this.dampingRatios.subarray(0, count));
+  }
+
+  step() {
+    throw new Error('WebGPUSpringBatch.step() is asynchronous; use stepAsync().');
+  }
+
+  #pack(count) {
+    for (let i = 0; i < count; i += 1) {
+      const offset = i * FLOATS_PER_SPRING;
+      this.packed[offset] = this.positions[i];
+      this.packed[offset + 1] = this.velocities[i];
+      this.packed[offset + 2] = this.targets[i];
+      this.packed[offset + 3] = this.omegas[i];
+      this.packed[offset + 4] = this.dampingRatios[i];
+      this.packed[offset + 5] = 0;
+      this.packed[offset + 6] = 0;
+      this.packed[offset + 7] = 0;
+    }
+  }
+
+  #unpack(count, mapped) {
+    this.packed.set(new Float32Array(mapped).subarray(0, count * FLOATS_PER_SPRING));
+    for (let i = 0; i < count; i += 1) {
+      const offset = i * FLOATS_PER_SPRING;
+      this.positions[i] = this.packed[offset];
+      this.velocities[i] = this.packed[offset + 1];
+    }
+  }
+
+  async #step(count, dtSeconds) {
+    if (this.disposed) return;
+    if (count <= 0 || dtSeconds <= 0) return;
+    this.ensureCapacity(count);
+    this.#pack(count);
+    this.paramsFloat[0] = dtSeconds / substepCount(dtSeconds);
+    this.params[1] = count;
+    this.device.queue.writeBuffer(this.storageBuffer, 0, this.packed, 0, count * FLOATS_PER_SPRING * Float32Array.BYTES_PER_ELEMENT);
+    this.device.queue.writeBuffer(this.paramsBuffer, 0, this.params);
+
+    const encoder = this.device.createCommandEncoder();
+    const pass = encoder.beginComputePass();
+    pass.setPipeline(this.pipeline);
+    pass.setBindGroup(0, this.bindGroup);
+    const steps = substepCount(dtSeconds);
+    for (let i = 0; i < steps; i += 1) pass.dispatchWorkgroups(Math.ceil(count / DEFAULT_WORKGROUP_SIZE));
+    pass.end();
+    const readbackBytes = count * FLOATS_PER_SPRING * Float32Array.BYTES_PER_ELEMENT;
+    encoder.copyBufferToBuffer(this.storageBuffer, 0, this.readbackBuffer, 0, readbackBytes);
+    this.device.queue.submit([encoder.finish()]);
+    await this.device.queue.onSubmittedWorkDone?.();
+    await this.readbackBuffer.mapAsync(MAP_MODE.READ);
+    const mapped = this.readbackBuffer.getMappedRange();
+    this.#unpack(count, mapped);
+    this.readbackBuffer.unmap();
+  }
+
+  stepAsync(count, dtSeconds) {
+    const run = () => this.#step(count, dtSeconds);
+    const result = this.stepChain.then(run, run);
+    this.stepChain = result.catch(() => {});
+    return result;
+  }
+
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.storageBuffer.destroy?.();
+    this.readbackBuffer.destroy?.();
+    this.paramsBuffer.destroy?.();
+  }
+}

package/dist/src/worker/index.d.ts

@@ -0,0 +1,17 @@
+export class SharedSpringWorkerBackend {
+  static isSupported(): boolean;
+  static create(capacity?: number): Promise<SharedSpringWorkerBackend>;
+  readonly kind: 'worker-wasm';
+  readonly capacity: number;
+  readonly variant: 'simd' | 'scalar';
+  readonly atomicCompletion: boolean;
+  readonly positions: Float32Array;
+  readonly velocities: Float32Array;
+  readonly targets: Float32Array;
+  readonly omegas: Float32Array;
+  readonly dampingRatios: Float32Array;
+  ensureCapacity(required: number): void;
+  step(count: number, dtSeconds: number): void;
+  stepAsync(count: number, dtSeconds: number): Promise<void>;
+  dispose(): void;
+}

package/dist/src/worker/index.js

@@ -0,0 +1 @@
+export { SharedSpringWorkerBackend } from './shared-spring-worker.js';

package/dist/src/worker/shared-spring-worker.js

@@ -0,0 +1,218 @@
+import { SharedWasmSpringBatch } from '../wasm/shared-wasm-spring-batch.js';
+
+function canUseSharedMemory() {
+  try {
+    if (typeof SharedArrayBuffer !== 'function' || typeof WebAssembly?.Memory !== 'function') return false;
+    const memory = new WebAssembly.Memory({ initial: 1, maximum: 1, shared: true });
+    return memory.buffer instanceof SharedArrayBuffer;
+  } catch {
+    return false;
+  }
+}
+
+async function createWorker(url) {
+  if (typeof globalThis.Worker === 'function') return new globalThis.Worker(url, { type: 'module' });
+  if (typeof process !== 'undefined' && process.versions?.node) {
+    const nodeWorkers = ['node', 'worker_threads'].join(':');
+    const { Worker } = await import(/* @vite-ignore */ nodeWorkers);
+    const execArgv = process.execArgv.filter((arg) => !arg.startsWith('--input-type'));
+    try {
+      return new Worker(url, { type: 'module', execArgv });
+    } catch (error) {
+      // Desktop shells and test runners can inject V8 flags that are valid in
+      // the parent process but rejected by worker_threads. Retrying without
+      // inherited flags keeps the shared backend available instead of
+      // silently forcing the slower main-thread solver.
+      if (error?.code !== 'ERR_WORKER_INVALID_EXEC_ARGV') throw error;
+      return new Worker(url, { type: 'module', execArgv: [] });
+    }
+  }
+  throw new Error('Module Worker is unavailable.');
+}
+
+function onWorkerMessage(worker, handler) {
+  if (typeof worker.addEventListener === 'function') {
+    const listener = (event) => handler(event.data);
+    worker.addEventListener('message', listener);
+    return () => worker.removeEventListener('message', listener);
+  }
+  worker.on('message', handler);
+  return () => worker.off?.('message', handler);
+}
+
+function onWorkerError(worker, handler) {
+  if (typeof worker.addEventListener === 'function') {
+    const listener = (event) => handler(event.error ?? new Error(event.message || 'Worker failed.'));
+    worker.addEventListener('error', listener);
+    return () => worker.removeEventListener('error', listener);
+  }
+  worker.on?.('error', handler);
+  return () => worker.off?.('error', handler);
+}
+
+export class SharedSpringWorkerBackend {
+  static isSupported() { return canUseSharedMemory(); }
+
+  static async create(capacity = 65536) {
+    if (!canUseSharedMemory()) throw new Error('Shared WebAssembly memory is unavailable in this environment.');
+    const batch = await SharedWasmSpringBatch.create(capacity);
+    const worker = await createWorker(new URL('./shared-worker.js', import.meta.url));
+    const controlBuffer = new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT * 8);
+    const backend = new SharedSpringWorkerBackend(batch, worker, controlBuffer);
+    try {
+      await backend.#initialize();
+      return backend;
+    } catch (error) {
+      backend.dispose();
+      throw error;
+    }
+  }
+
+  constructor(batch, worker, controlBuffer) {
+    this.kind = 'worker-wasm';
+    this.batch = batch;
+    this.worker = worker;
+    this.controlBuffer = controlBuffer;
+    this.control = new Int32Array(controlBuffer);
+    this.controlFloat = new Float32Array(controlBuffer);
+    this.pending = new Map();
+    this.sequence = 0;
+    this.atomicCompletion = typeof Atomics.waitAsync === 'function';
+    this.workerFailure = null;
+    this.stepChain = Promise.resolve();
+    this.ready = false;
+    this.disposed = false;
+    this.removeListener = onWorkerMessage(worker, (message) => this.#onMessage(message));
+    this.removeErrorListener = onWorkerError(worker, (error) => this.#onWorkerError(error));
+  }
+
+  get capacity() { return this.batch.capacity; }
+  get variant() { return this.batch.variant; }
+  get positions() { return this.batch.positions; }
+  get velocities() { return this.batch.velocities; }
+  get targets() { return this.batch.targets; }
+  get omegas() { return this.batch.omegas; }
+  get dampingRatios() { return this.batch.dampingRatios; }
+
+  ensureCapacity(required) { this.batch.ensureCapacity(required); }
+  copyInto(other, count) { this.batch.copyInto(other, count); }
+
+  async #initialize() {
+    const ready = new Promise((resolve, reject) => {
+      this.readyResolver = resolve;
+      this.readyRejecter = reject;
+    });
+    this.worker.postMessage({
+      type: 'init',
+      memory: this.batch.memory,
+      variant: this.batch.variant,
+      ptrs: this.batch.ptrs,
+      controlBuffer: this.controlBuffer,
+      atomicCompletion: this.atomicCompletion,
+    });
+    await ready;
+  }
+
+  #onWorkerError(error) {
+    this.workerFailure = error;
+    Atomics.store(this.control, 5, 3);
+    Atomics.store(this.control, 1, this.sequence);
+    Atomics.notify(this.control, 1);
+    if (!this.ready) this.readyRejecter?.(error);
+    for (const { reject } of this.pending.values()) reject(error);
+    this.pending.clear();
+  }
+
+  #onMessage(message) {
+    if (message?.type === 'ready') {
+      this.ready = true;
+      this.readyResolver?.(message);
+      this.readyResolver = null;
+      this.readyRejecter = null;
+      return;
+    }
+    if (message?.type === 'error') {
+      const error = new Error(message.message || 'Shared spring worker failed.');
+      this.workerFailure = error;
+      Atomics.store(this.control, 5, 3);
+      Atomics.store(this.control, 1, this.sequence);
+      Atomics.notify(this.control, 1);
+      if (!this.ready) this.readyRejecter?.(error);
+      for (const { reject } of this.pending.values()) reject(error);
+      this.pending.clear();
+      return;
+    }
+    if (message?.type === 'done') {
+      const pending = this.pending.get(message.sequence);
+      if (pending) {
+        this.pending.delete(message.sequence);
+        pending.resolve();
+      }
+    }
+  }
+
+  step(count, dtSeconds) {
+    // Synchronous/manual stepping keeps deterministic semantics and uses the
+    // shared WASM instance on the caller thread. Auto mode can use stepAsync().
+    this.batch.step(count, dtSeconds);
+  }
+
+  stepAsync(count, dtSeconds) {
+    if (this.disposed) return Promise.reject(new Error('Shared spring worker is disposed.'));
+    if (count === 0 || dtSeconds <= 0) return Promise.resolve();
+    const dispatch = () => this.#dispatchStep(count, dtSeconds);
+    const result = this.stepChain.then(dispatch, dispatch);
+    this.stepChain = result.catch(() => {});
+    return result;
+  }
+
+  #dispatchStep(count, dtSeconds) {
+    if (this.disposed) return Promise.reject(new Error('Shared spring worker is disposed.'));
+    const sequence = ++this.sequence;
+    Atomics.store(this.control, 2, count);
+    Atomics.store(this.control, 5, 0);
+    this.controlFloat[4] = dtSeconds;
+
+    let promise;
+    if (this.atomicCompletion) {
+      promise = this.#waitForSequence(sequence);
+    } else {
+      promise = new Promise((resolve, reject) => this.pending.set(sequence, { resolve, reject }));
+    }
+
+    Atomics.store(this.control, 0, sequence);
+    Atomics.notify(this.control, 0);
+    return promise;
+  }
+
+  async #waitForSequence(sequence) {
+    while (true) {
+      if (this.disposed) throw new Error('Shared spring worker is disposed.');
+      if (this.workerFailure) throw this.workerFailure;
+      const completed = Atomics.load(this.control, 1);
+      if (completed >= sequence) {
+        const errorCode = Atomics.load(this.control, 5);
+        if (errorCode !== 0) throw new Error(`Shared spring worker failed with code ${errorCode}.`);
+        return;
+      }
+      const waiter = Atomics.waitAsync(this.control, 1, completed);
+      if (waiter.async) await waiter.value;
+      else await Promise.resolve();
+    }
+  }
+
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    Atomics.store(this.control, 3, 1);
+    Atomics.store(this.control, 5, 2);
+    Atomics.store(this.control, 1, this.sequence);
+    Atomics.notify(this.control, 0);
+    Atomics.notify(this.control, 1);
+    for (const { reject } of this.pending.values()) reject(new Error('Shared spring worker disposed.'));
+    this.pending.clear();
+    this.removeListener?.();
+    this.removeErrorListener?.();
+    this.worker.terminate?.();
+  }
+}