sim-lidar-rs 0.1.0

package/README.md

@@ -0,0 +1,55 @@
+# sim-lidar-rs
+
+High-performance simulated LiDAR sensor library built for the web.  
+Computes 100,000+ ray intersections per frame in Rust/WebAssembly, off the main thread.
+
+## Features
+
+- ⚡ **Fast** – Bounding Volume Hierarchy (BVH) accelerator built in Rust, compiled to Wasm
+- 🔒 **Non-blocking** – All computation runs inside a Web Worker
+- 🎯 **Realistic** – Configurable vertical channels, FOV, range limits, and Gaussian noise
+- 📦 **Zero-copy** – Hit-point buffers transferred directly from Wasm to JS
+- 🔷 **Strictly typed** – Full TypeScript API with sensor presets (VLP-16, Ouster OS1-32/64)
+
+## Quick Start
+
+```ts
+import { LidarClient, VLP16_CONFIG } from 'sim-lidar-rs';
+
+const vertices = new Float32Array([/* x,y,z ... */]);
+const indices  = new Uint32Array([/* i0,i1,i2 ... */]);
+
+const lidar = new LidarClient(vertices, indices, VLP16_CONFIG);
+await lidar.ready();
+
+const { hits, hitCount } = await lidar.scan({
+  position: { x: 0, y: 1.5, z: 0 },
+});
+console.log(`${hitCount} hits`); // hits is Float32Array [x,y,z, ...]
+
+lidar.dispose();
+```
+
+## Build
+
+```bash
+# Build Wasm module
+wasm-pack build --target web --out-dir ts/wasm
+
+# Build TypeScript library
+npm run build
+
+# Run Rust unit tests
+cargo test
+
+# Run TypeScript tests
+npm test
+```
+
+## Documentation
+
+See [ARCHITECTURE.md](./ARCHITECTURE.md) for the full architecture, core objectives, technical design, and sensor configuration reference.
+
+## License
+
+MIT

package/dist/__tests__/sim_lidar.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/simulator.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/three.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/types.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,95 @@
+/**
+ * sim-lidar-rs – Public TypeScript API
+ *
+ * Usage:
+ * ```ts
+ * import { LidarClient, VLP16_CONFIG } from 'sim-lidar-rs';
+ *
+ * const lidar = new LidarClient(vertices, indices, VLP16_CONFIG);
+ * await lidar.ready();
+ * const { hits, hitCount } = await lidar.scan({ position: { x: 0, y: 1, z: 0 } });
+ * ```
+ */
+export type { SensorConfig, Pose, ScanResult, Geometry, SimLidarEventHandlers } from "./types.js";
+export { VLP16_CONFIG, OUSTER_OS1_32_CONFIG, OUSTER_OS1_64_CONFIG, totalRays, SimLidarError, SimLidarNotInitializedError, SimLidarDisposedError, } from "./types.js";
+import type { SensorConfig, Pose, ScanResult, Geometry, SimLidarEventHandlers } from "./types.js";
+/**
+ * `LidarClient` wraps the Wasm LiDAR simulator running inside a Web Worker.
+ * All heavy computation runs off the main thread.
+ */
+export declare class LidarClient {
+    private worker;
+    private pending;
+    private readyPromise;
+    private _scanCounter;
+    private _disposed;
+    private readonly _handlers;
+    constructor(vertices: Float32Array, indices: Uint32Array, config: SensorConfig, 
+    /** Optional URL/path to the worker script. Defaults to the bundled worker. */
+    workerUrl?: string | URL, 
+    /** Optional observability callbacks. */
+    handlers?: SimLidarEventHandlers);
+    /** Resolves once the Wasm module has been initialised and the BVH built. */
+    ready(): Promise<void>;
+    /** Update the sensor configuration without rebuilding the BVH. */
+    setConfig(config: SensorConfig): void;
+    /** Run a full scan and return the resulting point cloud. */
+    scan(pose: Pose): Promise<ScanResult>;
+    /** Terminate the underlying Web Worker, rejecting any in-flight scan Promises. */
+    dispose(): void;
+    private _onMessage;
+}
+/**
+ * `SimLidar` is the primary TypeScript API for the sim-lidar-rs library.
+ *
+ * It abstracts the Web Worker communication using Promises and provides
+ * explicit lifecycle management to ensure Wasm instances are freed when
+ * the simulator is no longer needed.
+ *
+ * ```ts
+ * const lidar = new SimLidar(VLP16_CONFIG);
+ * await lidar.init();
+ * await lidar.updateEnvironment({ vertices, indices });
+ * const hits = await lidar.scan({ position: { x: 0, y: 1, z: 0 } });
+ * // hits is a Float32Array [x,y,z, x,y,z, …]
+ * lidar.destroy();
+ * ```
+ */
+export declare class SimLidar {
+    private worker;
+    private pending;
+    private _counter;
+    private readonly _config;
+    private _disposed;
+    private readonly _handlers;
+    constructor(config: SensorConfig, 
+    /** Optional URL/path to the worker script. Defaults to the bundled worker. */
+    workerUrl?: string | URL, 
+    /** Optional observability callbacks. */
+    handlers?: SimLidarEventHandlers);
+    /**
+     * Initialise the Wasm module inside the Web Worker.
+     * Must be called before {@link updateEnvironment} or {@link scan}.
+     */
+    init(): Promise<void>;
+    /**
+     * Load (or replace) the environment geometry and rebuild the BVH.
+     * Buffers are transferred to the worker to avoid copying.
+     */
+    updateEnvironment(geometry: Geometry): Promise<void>;
+    /**
+     * Run a full LiDAR scan from the given pose.
+     *
+     * @returns A `Promise` that resolves with a `Float32Array` of world-space
+     *   hit coordinates `[x,y,z, x,y,z, …]`.
+     */
+    scan(pose: Pose): Promise<Float32Array>;
+    /**
+     * Destroy the simulator: asks the worker to explicitly free the Wasm
+     * instance (releasing linear memory) and then terminates the worker thread.
+     *
+     * Any in-flight Promises are rejected with a {@link SimLidarDisposedError}.
+     */
+    destroy(): void;
+    private _onMessage;
+}

package/dist/sim-lidar-rs.js

@@ -0,0 +1,237 @@
+var g = Object.defineProperty;
+var y = (o, t, e) => t in o ? g(o, t, { enumerable: !0, configurable: !0, writable: !0, value: e }) : o[t] = e;
+var d = (o, t, e) => y(o, typeof t != "symbol" ? t + "" : t, e);
+const f = {
+  horizontalResolution: 1800,
+  verticalChannels: 16,
+  verticalFovUpper: 15,
+  verticalFovLower: -15,
+  minRange: 0.1,
+  maxRange: 100,
+  noiseStddev: 0
+}, w = {
+  horizontalResolution: 1024,
+  verticalChannels: 32,
+  verticalFovUpper: 22.5,
+  verticalFovLower: -22.5,
+  minRange: 0.1,
+  maxRange: 120,
+  noiseStddev: 0
+}, m = {
+  horizontalResolution: 2048,
+  verticalChannels: 64,
+  verticalFovUpper: 22.5,
+  verticalFovLower: -22.5,
+  minRange: 0.1,
+  maxRange: 120,
+  noiseStddev: 0
+};
+function v(o) {
+  return o.horizontalResolution * o.verticalChannels;
+}
+class h extends Error {
+  constructor(t) {
+    super(t), this.name = "SimLidarError", Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+class k extends h {
+  constructor() {
+    super("Simulator not initialised. Await init() / ready() before calling scan()."), this.name = "SimLidarNotInitializedError", Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+class p extends h {
+  constructor() {
+    super("This SimLidar instance has been destroyed and can no longer be used."), this.name = "SimLidarDisposedError", Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+class C {
+  constructor(t, e, i, r, a) {
+    d(this, "worker");
+    d(this, "pending", /* @__PURE__ */ new Map());
+    d(this, "readyPromise");
+    d(this, "_scanCounter", 0);
+    d(this, "_disposed", !1);
+    d(this, "_handlers");
+    this._handlers = a ?? {};
+    const c = r ?? new URL("./worker.js", import.meta.url);
+    this.worker = new Worker(c, { type: "module" }), this.worker.addEventListener("message", this._onMessage.bind(this)), this.readyPromise = new Promise((_, l) => {
+      this.pending.set("__ready__", {
+        resolve: _,
+        reject: l
+      });
+    });
+    const s = new Float32Array(t), n = new Uint32Array(e);
+    this.worker.postMessage(
+      { type: "init", vertices: s, indices: n, config: i },
+      [s.buffer, n.buffer]
+    );
+  }
+  /** Resolves once the Wasm module has been initialised and the BVH built. */
+  ready() {
+    return this.readyPromise;
+  }
+  /** Update the sensor configuration without rebuilding the BVH. */
+  setConfig(t) {
+    if (this._disposed) throw new p();
+    this.worker.postMessage({ type: "setConfig", config: t });
+  }
+  /** Run a full scan and return the resulting point cloud. */
+  scan(t) {
+    return this._disposed ? Promise.reject(new p()) : new Promise((e, i) => {
+      const r = `scan_${++this._scanCounter}`;
+      this.pending.set(r, {
+        resolve: e,
+        reject: i
+      }), this.worker.postMessage({ type: "scan", pose: t, __id: r });
+    });
+  }
+  /** Terminate the underlying Web Worker, rejecting any in-flight scan Promises. */
+  dispose() {
+    if (this._disposed) return;
+    this._disposed = !0;
+    const t = new p();
+    for (const e of this.pending.values())
+      e.reject(t);
+    this.pending.clear(), this.worker.terminate();
+  }
+  _onMessage(t) {
+    var i, r, a, c;
+    const e = t.data;
+    if (e.type === "ready") {
+      const s = this.pending.get("__ready__");
+      s && (this.pending.delete("__ready__"), s.resolve(void 0), (r = (i = this._handlers).onReady) == null || r.call(i));
+      return;
+    }
+    if (e.type === "scan") {
+      const s = e.__id, n = s ? this.pending.get(s) : void 0;
+      n && (this.pending.delete(s), n.resolve({ hits: e.hits, hitCount: e.hitCount }));
+      return;
+    }
+    if (e.type === "error") {
+      const s = new h(e.message);
+      (c = (a = this._handlers).onError) == null || c.call(a, s);
+      for (const n of this.pending.values())
+        n.reject(s);
+      this.pending.clear();
+    }
+  }
+}
+class L {
+  constructor(t, e, i) {
+    d(this, "worker");
+    d(this, "pending", /* @__PURE__ */ new Map());
+    d(this, "_counter", 0);
+    d(this, "_config");
+    d(this, "_disposed", !1);
+    d(this, "_handlers");
+    this._config = t, this._handlers = i ?? {};
+    const r = e ?? new URL("./worker.js", import.meta.url);
+    this.worker = new Worker(r, { type: "module" }), this.worker.addEventListener("message", this._onMessage.bind(this));
+  }
+  /**
+   * Initialise the Wasm module inside the Web Worker.
+   * Must be called before {@link updateEnvironment} or {@link scan}.
+   */
+  init() {
+    return this._disposed ? Promise.reject(new p()) : new Promise((t, e) => {
+      this.pending.set("__ready__", {
+        resolve: t,
+        reject: e
+      }), this.worker.postMessage({ type: "init", config: this._config });
+    });
+  }
+  /**
+   * Load (or replace) the environment geometry and rebuild the BVH.
+   * Buffers are transferred to the worker to avoid copying.
+   */
+  updateEnvironment(t) {
+    return this._disposed ? Promise.reject(new p()) : new Promise((e, i) => {
+      const r = `env_${++this._counter}`;
+      this.pending.set(r, {
+        resolve: e,
+        reject: i
+      });
+      const a = new Float32Array(t.vertices), c = new Uint32Array(t.indices);
+      this.worker.postMessage(
+        { type: "updateEnvironment", vertices: a, indices: c, __id: r },
+        [a.buffer, c.buffer]
+      );
+    });
+  }
+  /**
+   * Run a full LiDAR scan from the given pose.
+   *
+   * @returns A `Promise` that resolves with a `Float32Array` of world-space
+   *   hit coordinates `[x,y,z, x,y,z, …]`.
+   */
+  scan(t) {
+    return this._disposed ? Promise.reject(new p()) : new Promise((e, i) => {
+      const r = `scan_${++this._counter}`;
+      this.pending.set(r, {
+        resolve: e,
+        reject: i
+      }), this.worker.postMessage({ type: "scan", pose: t, __id: r });
+    });
+  }
+  /**
+   * Destroy the simulator: asks the worker to explicitly free the Wasm
+   * instance (releasing linear memory) and then terminates the worker thread.
+   *
+   * Any in-flight Promises are rejected with a {@link SimLidarDisposedError}.
+   */
+  destroy() {
+    if (this._disposed) return;
+    this._disposed = !0;
+    const t = new p();
+    for (const e of this.pending.values())
+      e.reject(t);
+    this.pending.clear(), this.worker.postMessage({ type: "destroy" });
+  }
+  _onMessage(t) {
+    var i, r, a, c;
+    const e = t.data;
+    if (e.type === "ready") {
+      const s = this.pending.get("__ready__");
+      s && (this.pending.delete("__ready__"), s.resolve(void 0), (r = (i = this._handlers).onReady) == null || r.call(i));
+      return;
+    }
+    if (e.type === "environmentUpdated") {
+      const s = e.__id;
+      if (s) {
+        const n = this.pending.get(s);
+        n && (this.pending.delete(s), n.resolve(void 0));
+      }
+      return;
+    }
+    if (e.type === "scan") {
+      const s = e.__id;
+      if (s) {
+        const n = this.pending.get(s);
+        n && (this.pending.delete(s), n.resolve(e.hits));
+      }
+      return;
+    }
+    if (e.type === "destroyed") {
+      this.worker.terminate();
+      return;
+    }
+    if (e.type === "error") {
+      const s = new h(e.message);
+      (c = (a = this._handlers).onError) == null || c.call(a, s);
+      for (const n of this.pending.values())
+        n.reject(s);
+      this.pending.clear();
+    }
+  }
+}
+export {
+  C as LidarClient,
+  w as OUSTER_OS1_32_CONFIG,
+  m as OUSTER_OS1_64_CONFIG,
+  L as SimLidar,
+  p as SimLidarDisposedError,
+  h as SimLidarError,
+  k as SimLidarNotInitializedError,
+  f as VLP16_CONFIG,
+  v as totalRays
+};

package/dist/three.d.ts

@@ -0,0 +1,116 @@
+/**
+ * sim-lidar-rs/three – Optional Three.js adapter
+ *
+ * This module does **not** import from the `three` package at runtime, so it
+ * carries zero extra bundle weight for projects that do not use Three.js.
+ * The exported helpers use structural typing to accept real Three.js objects.
+ *
+ * @example
+ * ```ts
+ * import * as THREE from 'three';
+ * import { extractGeometry, hitsToPoints } from 'sim-lidar-rs/three';
+ * import { SimLidar, VLP16_CONFIG } from 'sim-lidar-rs';
+ *
+ * // ── Build the LiDAR environment from your scene ──────────────────────────
+ * scene.updateMatrixWorld();
+ * const geometry = extractGeometry(scene);
+ *
+ * const lidar = new SimLidar(VLP16_CONFIG);
+ * await lidar.init();
+ * await lidar.updateEnvironment(geometry);
+ *
+ * // ── Visualise scan results in the same scene ──────────────────────────────
+ * const hits = await lidar.scan({ position: { x: 0, y: 1.5, z: 0 } });
+ * const points = hitsToPoints(hits, THREE);
+ * scene.add(points);
+ * ```
+ */
+import type { Geometry } from "./types.js";
+interface BufferAttribute {
+    /** Underlying flat typed array (e.g. Float32Array, Uint32Array). */
+    readonly array: ArrayLike<number>;
+    /** Number of elements (vertices / indices). */
+    readonly count: number;
+    /** Components per element (3 for position, 1 for scalar index). */
+    readonly itemSize: number;
+}
+interface BufferGeometry {
+    readonly attributes: Readonly<Record<string, BufferAttribute | undefined>>;
+    /** `null` for non-indexed geometries. */
+    readonly index: BufferAttribute | null;
+}
+interface Matrix4Like {
+    /** Column-major 16-element array, matching `THREE.Matrix4.elements`. */
+    readonly elements: ArrayLike<number>;
+}
+/** Structural type covering both `THREE.Scene` and `THREE.Mesh`. */
+interface Object3D {
+    /** `true` for `THREE.Mesh` instances. */
+    readonly isMesh?: boolean;
+    /** Present on mesh objects. */
+    readonly geometry?: BufferGeometry;
+    /** Child objects in the scene graph. */
+    readonly children: readonly Object3D[];
+    /**
+     * World-space transformation matrix.
+     * Call `scene.updateMatrixWorld()` before passing the scene to ensure
+     * matrices are current.
+     */
+    readonly matrixWorld?: Matrix4Like;
+}
+/**
+ * Recursively traverse a `THREE.Scene` or `THREE.Mesh` and merge every mesh's
+ * vertex positions and triangle indices into a single flat {@link Geometry}
+ * ready for {@link SimLidar.updateEnvironment} / {@link LidarClient}.
+ *
+ * - **Matrix transforms**: if a mesh exposes a `matrixWorld` property its
+ *   positions are converted to world space (column-major, Three.js convention).
+ *   Call `scene.updateMatrixWorld()` before calling this function.
+ * - **Non-indexed geometries**: auto-generated sequential indices are added.
+ * - Multiple meshes are merged into a single vertex/index buffer pair.
+ *
+ * @param object - A `THREE.Scene`, `THREE.Mesh`, or any object that structurally
+ *                 matches the {@link Object3D} interface.
+ * @returns Flat {@link Geometry} with `vertices` and `indices` buffers.
+ *
+ * @example
+ * ```ts
+ * scene.updateMatrixWorld();
+ * const { vertices, indices } = extractGeometry(scene);
+ * await lidar.updateEnvironment({ vertices, indices });
+ * ```
+ */
+export declare function extractGeometry(object: Object3D): Geometry;
+/**
+ * Convert a flat `Float32Array` of `[x,y,z, x,y,z, …]` hit coordinates (as
+ * returned by {@link SimLidar.scan} or {@link LidarClient.scan}) into a
+ * `THREE.Points` object for immediate browser visualisation.
+ *
+ * The Three.js namespace is accepted as the second argument so this helper
+ * does **not** carry a hard dependency on the `three` npm package.
+ * TypeScript will infer the return type as `THREE.Points` when you pass the
+ * full `THREE` namespace.
+ *
+ * @param hits - Flat `Float32Array` of hit coordinates `[x,y,z, …]`.
+ * @param three - An object exposing `BufferGeometry`, `Float32BufferAttribute`,
+ *                and `Points` constructors (pass `import * as THREE from 'three'`).
+ * @returns A `THREE.Points` instance ready to be added to a scene.
+ *
+ * @example
+ * ```ts
+ * import * as THREE from 'three';
+ * import { hitsToPoints } from 'sim-lidar-rs/three';
+ *
+ * const hits = await lidar.scan(pose);
+ * const points = hitsToPoints(hits, THREE);
+ * scene.add(points);
+ * ```
+ */
+export declare function hitsToPoints<TPoints = unknown>(hits: Float32Array, three: {
+    BufferGeometry: new () => {
+        setAttribute(name: string, attribute: unknown): void;
+    };
+    Float32BufferAttribute: new (array: ArrayLike<number>, itemSize: number) => unknown;
+    Points: new (geometry: unknown, material?: unknown) => TPoints;
+}): TPoints;
+export {};

package/dist/three.js

@@ -0,0 +1,42 @@
+function g(l) {
+  const n = [], s = [];
+  function d(o) {
+    var p;
+    if (o.isMesh && o.geometry) {
+      const r = o.geometry.attributes.position;
+      if (r) {
+        const A = n.length / 3, t = (p = o.matrixWorld) == null ? void 0 : p.elements, a = r.array;
+        for (let e = 0; e < r.count; e++) {
+          const c = e * r.itemSize;
+          let i = a[c], f = a[c + 1], u = a[c + 2];
+          if (t) {
+            const y = i, m = f, x = u;
+            i = t[0] * y + t[4] * m + t[8] * x + t[12], f = t[1] * y + t[5] * m + t[9] * x + t[13], u = t[2] * y + t[6] * m + t[10] * x + t[14];
+          }
+          n.push(i, f, u);
+        }
+        if (o.geometry.index) {
+          const e = o.geometry.index, c = e.array;
+          for (let i = 0; i < e.count; i++)
+            s.push(A + c[i]);
+        } else
+          for (let e = 0; e < r.count; e++)
+            s.push(A + e);
+      }
+    }
+    for (const r of o.children)
+      d(r);
+  }
+  return d(l), {
+    vertices: new Float32Array(n),
+    indices: new Uint32Array(s)
+  };
+}
+function h(l, n) {
+  const s = new n.BufferGeometry();
+  return s.setAttribute("position", new n.Float32BufferAttribute(l, 3)), new n.Points(s);
+}
+export {
+  g as extractGeometry,
+  h as hitsToPoints
+};

package/dist/types.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Sensor configuration mirroring real-world LiDARs (e.g. Velodyne VLP-16, Ouster).
+ */
+export interface SensorConfig {
+    /** Number of rays per full horizontal sweep (360°). */
+    horizontalResolution: number;
+    /** Number of vertical laser rings (e.g. 16, 32, 64). */
+    verticalChannels: number;
+    /** Upper vertical FOV limit in degrees (e.g. +15 for VLP-16). */
+    verticalFovUpper: number;
+    /** Lower vertical FOV limit in degrees (e.g. -15 for VLP-16). */
+    verticalFovLower: number;
+    /** Minimum valid range in metres. */
+    minRange: number;
+    /** Maximum valid range in metres. */
+    maxRange: number;
+    /** Standard deviation of Gaussian noise added to range measurements. 0 = disabled. */
+    noiseStddev: number;
+}
+/**
+ * Sensor pose: position + orientation.
+ */
+export interface Pose {
+    /** World-space sensor origin. */
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /**
+     * Sensor orientation as a unit quaternion.
+     * Defaults to identity `{ x:0, y:0, z:0, w:1 }` if omitted.
+     */
+    rotation?: {
+        x: number;
+        y: number;
+        z: number;
+        w: number;
+    };
+}
+/**
+ * Result of a single LiDAR scan.
+ */
+export interface ScanResult {
+    /**
+     * Flat `Float32Array` of hit world-space coordinates: `[x,y,z, x,y,z, …]`.
+     * Length is `hitCount * 3`.
+     */
+    hits: Float32Array;
+    /** Number of valid hits returned. */
+    hitCount: number;
+}
+/** VLP-16 preset. */
+export declare const VLP16_CONFIG: Readonly<SensorConfig>;
+/** Ouster OS1-32 preset. */
+export declare const OUSTER_OS1_32_CONFIG: Readonly<SensorConfig>;
+/** Ouster OS1-64 preset. */
+export declare const OUSTER_OS1_64_CONFIG: Readonly<SensorConfig>;
+/**
+ * Returns the total number of rays fired per scan for a given config.
+ */
+export declare function totalRays(config: SensorConfig): number;
+/**
+ * Environment geometry consumed by {@link SimLidar.updateEnvironment}.
+ */
+export interface Geometry {
+    /** Flat array of vertex positions `[x,y,z, …]`. */
+    vertices: Float32Array;
+    /** Flat array of triangle vertex indices. */
+    indices: Uint32Array;
+}
+/**
+ * Base error class for all sim-lidar-rs errors.
+ * Exported so consumers can use `err instanceof SimLidarError` to distinguish
+ * library errors from other runtime errors.
+ */
+export declare class SimLidarError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when a scan or environment update is requested before the simulator
+ * has been initialised (i.e. before `init()` or `ready()` has resolved).
+ */
+export declare class SimLidarNotInitializedError extends SimLidarError {
+    constructor();
+}
+/**
+ * Thrown when any method is called on a simulator instance that has already
+ * been disposed via `destroy()` or `dispose()`.
+ */
+export declare class SimLidarDisposedError extends SimLidarError {
+    constructor();
+}
+/**
+ * Optional event callbacks that can be passed to {@link SimLidar} and
+ * {@link LidarClient} constructors for observability and debugging.
+ */
+export interface SimLidarEventHandlers {
+    /**
+     * Called once the Wasm module has been loaded and the simulator is ready.
+     * Equivalent to awaiting `init()` / `ready()`.
+     */
+    onReady?: () => void;
+    /**
+     * Called whenever a worker-level error occurs (e.g. Wasm panic, unhandled
+     * exception inside the worker). Provides the error before it propagates to
+     * pending Promise rejections.
+     */
+    onError?: (err: SimLidarError) => void;
+}

package/dist/worker.d.ts

@@ -0,0 +1,18 @@
+/**
+ * worker.ts – Web Worker script that hosts the Wasm module.
+ *
+ * Messages sent TO the worker:
+ *   { type: 'init', config: SensorConfig, vertices?: Float32Array, indices?: Uint32Array }
+ *   { type: 'updateEnvironment', vertices: Float32Array, indices: Uint32Array, __id: string }
+ *   { type: 'scan', pose: Pose, __id: string }
+ *   { type: 'setConfig', config: SensorConfig }
+ *   { type: 'destroy' }
+ *
+ * Messages posted FROM the worker:
+ *   { type: 'ready' }
+ *   { type: 'environmentUpdated', __id: string }
+ *   { type: 'scan', hits: Float32Array, hitCount: number, __id: string }
+ *   { type: 'destroyed' }
+ *   { type: 'error', message: string }
+ */
+export {};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "sim-lidar-rs",
+  "version": "0.1.0",
+  "description": "High-performance simulated LiDAR sensor library for WebAssembly",
+  "type": "module",
+  "main": "./dist/sim-lidar-rs.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/sim-lidar-rs.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./three": {
+      "import": "./dist/three.js",
+      "types": "./dist/three.d.ts"
+    }
+  },
+  "scripts": {
+    "build:wasm": "wasm-pack build --target web --out-dir ts/wasm",
+    "build:types": "tsc --emitDeclarationOnly",
+    "build": "npm run build:wasm && vite build && npm run build:types",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit",
+    "docs": "typedoc",
+    "prepublishOnly": "npm run build && npm run lint && npm test",
+    "check-publish": "bash scripts/check-publish.sh",
+    "publish:npm": "bash scripts/check-publish.sh --publish"
+  },
+  "sideEffects": false,
+  "peerDependencies": {
+    "three": ">=0.150.0"
+  },
+  "peerDependenciesMeta": {
+    "three": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.35",
+    "@vitest/coverage-v8": "^1.0.0",
+    "typedoc": "^0.28.0",
+    "typescript": "^5.4.0",
+    "vite": "^5.2.0",
+    "vite-plugin-wasm": "^3.3.0",
+    "vitest": "^1.0.0"
+  },
+  "files": [
+    "dist",
+    "ts/wasm"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}