@molcrafts/molrs 0.0.7 → 0.0.12

package/molrs.d.ts

@@ -5,14 +5,14 @@
  * Column-oriented data store with typed arrays.
  *
  * Each column is identified by a string key and has a fixed data type
- * (`f32`, `i32`, `u32`, `string`). All columns in a block must have
+ * (`F`, `i32`, `u32`, `string`). All columns in a block must have
  * the same number of rows.
  *
  * # Supported column types
  *
  * | JS type | Rust type | dtype string | Setter | Getter (copy) | Getter (view) |
  * |---------|-----------|-------------|--------|---------------|---------------|
- * | `Float32Array` | `f32` | `"f32"` | `setColF32` | `copyColF32` | `viewColF32` |
+ * | `Float32Array` / `Float64Array` | `F` | `"f32"` / `"f64"` | `setColF` | `copyColF` | `viewColF` |
  * | `Int32Array` | `i32` | `"i32"` | `setColI32` | `copyColI32` | `viewColI32` |
  * | `Uint32Array` | `u32` | `"u32"` | `setColU32` | `copyColU32` | `viewColU32` |
  * | `string[]` | `String` | `"string"` | `setColStr` | `copyColStr` | -- |
@@ -21,21 +21,21 @@
  *
  * ```js
  * const block = new Block();
- * block.setColF32("x", new Float32Array([1.0, 2.0, 3.0]));
- * block.setColF32("y", new Float32Array([0.0, 0.0, 0.0]));
+ * block.setColF("x", coordsX);
+ * block.setColF("y", coordsY);
  * console.log(block.nrows()); // 3
  * console.log(block.keys());  // ["x", "y"]
  *
- * const x = block.copyColF32("x"); // owned copy, safe to keep
+ * const x = block.copyColF("x"); // owned copy, safe to keep
  * ```
  */
 export class Block {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Owned `Float32Array` copy of a column.
+     * Owned JS float typed-array copy of a column.
      *
-     * Returns a new JS `Float32Array` that is an independent copy of
+     * Returns a new JS float typed array that is an independent copy of
      * the column data. Safe to store and use across allocations.
      *
      * # Arguments
@@ -44,20 +44,20 @@ export class Block {
      *
      * # Returns
      *
-     * An owned `Float32Array` copy of the column.
+     * An owned JS float typed-array copy of the column.
      *
      * # Errors
      *
-     * Throws if the column does not exist or is not of type `f32`.
+     * Throws if the column does not exist or is not of the active float type.
      *
      * # Example (JavaScript)
      *
      * ```js
-     * const x = block.copyColF32("x");
+     * const x = block.copyColF("x");
      * console.log(x[0]); // 1.0
      * ```
      */
-    copyColF32(key: string): Float32Array;
+    copyColF(key: string): Float64Array;
     /**
      * Owned `Int32Array` copy of a column.
      *
@@ -120,7 +120,8 @@ export class Block {
     /**
      * Return the data type string for a column.
      *
-     * Possible return values: `"f32"`, `"i32"`, `"u32"`, `"bool"`,
+     * Possible return values: `"f32"` or `"f64"` for float columns,
+     * plus `"i32"`, `"u32"`, `"bool"`,
      * `"string"`, `"u8"`. Returns `undefined` if the column does
      * not exist.
      *
@@ -135,7 +136,7 @@ export class Block {
      * # Example (JavaScript)
      *
      * ```js
-     * console.log(block.dtype("x"));      // "f32"
+     * console.log(block.dtype("x"));      // "f32" or "f64"
      * console.log(block.dtype("symbol")); // "string"
      * ```
      */
@@ -197,7 +198,7 @@ export class Block {
      *
      * ```js
      * const block = new Block();
-     * block.setColF32("values", new Float32Array([1, 2, 3]));
+     * block.setColF("values", values);
      * ```
      */
     constructor();
@@ -241,12 +242,12 @@ export class Block {
      */
     renameColumn(old_key: string, new_key: string): boolean;
     /**
-     * Set a float column from a `Float32Array`.
+     * Set a float column from a JS float typed array.
      *
      * # Arguments
      *
      * * `key` - Column name (e.g., `"x"`, `"mass"`, `"charge"`)
-     * * `data` - `Float32Array` with the column values
+     * * `data` - JS float typed array with the column values
      * * `shape` - Optional shape array for multi-dimensional data
      *   (e.g., `[N, 3]` for an Nx3 matrix stored flat). If omitted,
      *   the data is stored as a 1D column.
@@ -259,12 +260,12 @@ export class Block {
      * # Example (JavaScript)
      *
      * ```js
-     * block.setColF32("x", new Float32Array([1.0, 2.0, 3.0]));
+     * block.setColF("x", xCoords);
      * // Multi-dimensional: 2 rows x 3 columns
-     * block.setColF32("pos", new Float32Array([1,2,3, 4,5,6]), [2, 3]);
+     * block.setColF("pos", positions, [2, 3]);
      * ```
      */
-    setColF32(key: string, data: Float32Array, shape?: Uint32Array | null): void;
+    setColF(key: string, data: Float64Array, shape?: Uint32Array | null): void;
     /**
      * Set a signed integer column from an `Int32Array`.
      *
@@ -326,13 +327,13 @@ export class Block {
      */
     setColU32(key: string, data: Uint32Array): void;
     /**
-     * Zero-copy `Float32Array` view into WASM linear memory.
+     * Zero-copy JS float typed-array view into WASM linear memory.
      *
      * Returns a view backed directly by the block's storage in WASM
      * memory. This avoids copying but the view becomes **invalid**
      * if WASM linear memory grows (due to any allocation).
      *
-     * Use [`copyColF32`](Block::copy_col_f32) for a safe, long-lived copy.
+     * Use [`copyColF`](Block::copy_col_f) for a safe, long-lived copy.
      *
      * # Arguments
      *
@@ -340,20 +341,20 @@ export class Block {
      *
      * # Returns
      *
-     * A `Float32Array` view into WASM memory.
+     * A JS float typed-array view into WASM memory.
      *
      * # Errors
      *
-     * Throws if the column does not exist or is not of type `f32`.
+     * Throws if the column does not exist or is not of the active float type.
      *
      * # Example (JavaScript)
      *
      * ```js
-     * const view = block.viewColF32("x"); // zero-copy, use immediately
-     * const copy = block.copyColF32("x"); // safe to keep
+     * const view = block.viewColF("x"); // zero-copy, use immediately
+     * const copy = block.copyColF("x"); // safe to keep
      * ```
      */
-    viewColF32(key: string): Float32Array;
+    viewColF(key: string): Float64Array;
     /**
      * Zero-copy `Int32Array` view into WASM linear memory.
      *
@@ -411,8 +412,8 @@ export class Block {
  * # Example (JavaScript)
  *
  * ```js
- * const h = new Float32Array([10, 0, 0, 0, 10, 0, 0, 0, 10]);
- * const origin = new Float32Array([0, 0, 0]);
+ * const h = floatArrayH;
+ * const origin = floatArrayOrigin;
  * const box = new Box(h, origin, true, true, true);
  * console.log(box.volume()); // 1000.0
  * console.log(box.lengths().toCopy()); // [10, 10, 10]
@@ -427,7 +428,7 @@ export class Box {
      * # Arguments
      *
      * * `a` - Side length of the cube in angstrom (A)
-     * * `origin` - 3D origin vector as `Float32Array` with 3 elements
+     * * `origin` - 3D origin vector as a float typed array with 3 elements
      *   `[x, y, z]` in angstrom
      * * `pbc_x` - Enable periodic boundary in x direction
      * * `pbc_y` - Enable periodic boundary in y direction
@@ -444,12 +445,12 @@ export class Box {
      * # Example (JavaScript)
      *
      * ```js
-     * const origin = new Float32Array([0, 0, 0]);
+     * const origin = originVec;
      * const box = Box.cube(10.0, origin, true, true, true);
      * console.log(box.volume()); // 1000.0
      * ```
      */
-    static cube(a: number, origin: Float32Array, pbc_x: boolean, pbc_y: boolean, pbc_z: boolean): Box;
+    static cube(a: number, origin: Float64Array, pbc_x: boolean, pbc_y: boolean, pbc_z: boolean): Box;
     /**
      * Calculate displacement vectors between two sets of coordinates.
      *
@@ -478,8 +479,8 @@ export class Box {
      * # Example (JavaScript)
      *
      * ```js
-     * const a = WasmArray.from(new Float32Array([1,1,1]), [1,3]);
-     * const b = WasmArray.from(new Float32Array([9,9,9]), [1,3]);
+     * const a = WasmArray.from(aCoords, [1, 3]);
+     * const b = WasmArray.from(bCoords, [1, 3]);
      * const d = box.delta(a, b, true); // minimum-image displacement
      * ```
      */
@@ -496,7 +497,7 @@ export class Box {
      * * `b` - `WasmArray` with shape `[N, 3]` (target positions in A)
      * * `minimum_image` - If `true`, apply minimum image convention
      * * `out_block` - Target [`Block`] to write the result into
-     * * `out_key` - Column name for the result (f32, shape `[N, 3]`)
+     * * `out_key` - Column name for the result (float, shape `[N, 3]`)
      *
      * # Errors
      *
@@ -538,7 +539,7 @@ export class Box {
      * # Example (JavaScript)
      *
      * ```js
-     * const L = box.lengths().toCopy(); // Float32Array [10, 10, 10]
+     * const L = box.lengths().toCopy(); // Float32Array or Float64Array [10, 10, 10]
      * ```
      */
     lengths(): WasmArray;
@@ -547,10 +548,10 @@ export class Box {
      *
      * # Arguments
      *
-     * * `h` - 3x3 cell matrix as `Float32Array` with 9 elements in
+     * * `h` - 3x3 cell matrix as a float typed array with 9 elements in
      *   row-major order: `[h00, h01, h02, h10, h11, h12, h20, h21, h22]`.
      *   All values in angstrom (A).
-     * * `origin` - 3D origin vector as `Float32Array` with 3 elements
+     * * `origin` - 3D origin vector as a float typed array with 3 elements
      *   `[x, y, z]` in angstrom.
      * * `pbc_x` - Enable periodic boundary in x direction
      * * `pbc_y` - Enable periodic boundary in y direction
@@ -569,12 +570,12 @@ export class Box {
      *
      * ```js
      * // Triclinic box
-     * const h = new Float32Array([10, 2, 0, 0, 10, 0, 0, 0, 10]);
-     * const origin = new Float32Array([0, 0, 0]);
+     * const h = hMatrix;
+     * const origin = originVec;
      * const box = new Box(h, origin, true, true, true);
      * ```
      */
-    constructor(h: Float32Array, origin: Float32Array, pbc_x: boolean, pbc_y: boolean, pbc_z: boolean);
+    constructor(h: Float64Array, origin: Float64Array, pbc_x: boolean, pbc_y: boolean, pbc_z: boolean);
     /**
      * Return the box origin as a `WasmArray` with shape `[3]`.
      *
@@ -587,7 +588,7 @@ export class Box {
      * # Example (JavaScript)
      *
      * ```js
-     * const o = box.origin().toCopy(); // Float32Array [0, 0, 0]
+     * const o = box.origin().toCopy(); // Float32Array or Float64Array [0, 0, 0]
      * ```
      */
     origin(): WasmArray;
@@ -596,9 +597,9 @@ export class Box {
      *
      * # Arguments
      *
-     * * `lengths` - Box dimensions as `Float32Array` with 3 elements
+     * * `lengths` - Box dimensions as a float typed array with 3 elements
      *   `[lx, ly, lz]` in angstrom (A)
-     * * `origin` - 3D origin vector as `Float32Array` with 3 elements
+     * * `origin` - 3D origin vector as a float typed array with 3 elements
      *   `[x, y, z]` in angstrom
      * * `pbc_x` - Enable periodic boundary in x direction
      * * `pbc_y` - Enable periodic boundary in y direction
@@ -615,12 +616,12 @@ export class Box {
      * # Example (JavaScript)
      *
      * ```js
-     * const origin = new Float32Array([0, 0, 0]);
-     * const box = Box.ortho(new Float32Array([10, 20, 30]), origin, true, true, true);
+     * const origin = originVec;
+     * const box = Box.ortho(lengthsVec, origin, true, true, true);
      * console.log(box.volume()); // 6000.0
      * ```
      */
-    static ortho(lengths: Float32Array, origin: Float32Array, pbc_x: boolean, pbc_y: boolean, pbc_z: boolean): Box;
+    static ortho(lengths: Float64Array, origin: Float64Array, pbc_x: boolean, pbc_y: boolean, pbc_z: boolean): Box;
     /**
      * Return the box tilt factors as a `WasmArray` with shape `[3]`.
      *
@@ -636,7 +637,7 @@ export class Box {
      * # Example (JavaScript)
      *
      * ```js
-     * const t = box.tilts().toCopy(); // Float32Array [0, 0, 0]
+     * const t = box.tilts().toCopy(); // Float32Array or Float64Array [0, 0, 0]
      * ```
      */
     tilts(): WasmArray;
@@ -648,7 +649,7 @@ export class Box {
      *
      * * `coords` - `WasmArray` with shape `[N, 3]` (fractional, dimensionless)
      * * `out_block` - Target [`Block`]
-     * * `out_key` - Column name for the result (f32, shape `[N, 3]`)
+     * * `out_key` - Column name for the result (float, shape `[N, 3]`)
      *
      * # Errors
      *
@@ -669,7 +670,7 @@ export class Box {
      *
      * * `coords` - `WasmArray` with shape `[N, 3]` (Cartesian, A)
      * * `out_block` - Target [`Block`]
-     * * `out_key` - Column name for the result (f32, shape `[N, 3]`)
+     * * `out_key` - Column name for the result (float, shape `[N, 3]`)
      *
      * # Errors
      *
@@ -702,7 +703,7 @@ export class Box {
      * # Example (JavaScript)
      *
      * ```js
-     * const frac = WasmArray.from(new Float32Array([0.5, 0.5, 0.5]), [1, 3]);
+     * const frac = WasmArray.from(fracCoords, [1, 3]);
      * const cart = box.toCart(frac);
      * console.log(cart.toCopy()); // [5, 5, 5] for a 10x10x10 box
      * ```
@@ -731,7 +732,7 @@ export class Box {
      * # Example (JavaScript)
      *
      * ```js
-     * const cart = WasmArray.from(new Float32Array([5, 5, 5]), [1, 3]);
+     * const cart = WasmArray.from(coords, [1, 3]);
      * const frac = box.toFrac(cart);
      * console.log(frac.toCopy()); // [0.5, 0.5, 0.5] for a 10x10x10 box
      * ```
@@ -771,7 +772,7 @@ export class Box {
      * # Example (JavaScript)
      *
      * ```js
-     * const pos = WasmArray.from(new Float32Array([12, -1, 5]), [1, 3]);
+     * const pos = WasmArray.from(positions, [1, 3]);
      * const wrapped = box.wrap(pos); // wraps into [0, lx) x [0, ly) x [0, lz)
      * ```
      */
@@ -787,7 +788,7 @@ export class Box {
      * * `coords` - `WasmArray` with shape `[N, 3]` containing
      *   Cartesian coordinates in angstrom (A)
      * * `out_block` - Target [`Block`] to write the result into
-     * * `out_key` - Column name for the result (f32, shape `[N, 3]`)
+     * * `out_key` - Column name for the result (float, shape `[N, 3]`)
      *
      * # Errors
      *
@@ -816,9 +817,9 @@ export class CenterOfMass {
     /**
      * Create a center-of-mass calculator.
      *
-     * Pass `null` for uniform masses, or a `Float32Array` of per-particle masses.
+     * Pass `null` for uniform masses, or a float typed array of per-particle masses.
      */
-    constructor(masses?: Float32Array | null);
+    constructor(masses?: Float64Array | null);
 }
 
 /**
@@ -828,8 +829,8 @@ export class CenterOfMass {
  *
  * ```js
  * const com = new CenterOfMass().compute(frame, clusterResult);
- * com.centersOfMass();   // Float32Array [x0,y0,z0, ...]
- * com.clusterMasses();   // Float32Array
+ * com.centersOfMass();   // Float32Array or Float64Array [x0,y0,z0, ...]
+ * com.clusterMasses();   // Float32Array or Float64Array
  * ```
  */
 export class CenterOfMassResult {
@@ -837,13 +838,15 @@ export class CenterOfMassResult {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Mass-weighted centers, flat `[x0,y0,z0, x1,y1,z1, ...]`.
+     * Zero-copy `Float64Array` view of mass-weighted centers, flat
+     * `[x0,y0,z0, x1,y1,z1, ...]`. **Invalidated** on WASM memory growth.
      */
-    centersOfMass(): Float32Array;
+    centersOfMass(): Float64Array;
     /**
-     * Total mass per cluster.
+     * Zero-copy `Float64Array` view of total mass per cluster.
+     * **Invalidated** on WASM memory growth.
      */
-    clusterMasses(): Float32Array;
+    clusterMasses(): Float64Array;
     /**
      * Number of clusters.
      */
@@ -923,16 +926,16 @@ export class Cluster {
  *
  * ```js
  * const centers = new ClusterCenters().compute(frame, clusterResult);
- * // Float32Array [x0,y0,z0, x1,y1,z1, ...]
+ * // Float32Array or Float64Array [x0,y0,z0, x1,y1,z1, ...]
  * ```
  */
 export class ClusterCenters {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Compute geometric centers. Returns flat `Float32Array` `[x0,y0,z0, ...]`.
+     * Compute geometric centers. Returns a flat float typed array `[x0,y0,z0, ...]`.
      */
-    compute(frame: Frame, cluster_result: ClusterResult): Float32Array;
+    compute(frame: Frame, cluster_result: ClusterResult): Float64Array;
     constructor();
 }
 
@@ -991,10 +994,10 @@ export class ClusterResult {
  * # Conventions
  *
  * - The `"atoms"` block should contain per-atom properties: `symbol`
- *   (string), `x`/`y`/`z` (f32, coordinates in angstrom), and optionally
- *   `mass` (f32, atomic mass units) and `charge` (f32, elementary charges).
+ *   (string), `x`/`y`/`z` (F, coordinates in angstrom), and optionally
+ *   `mass` (F, atomic mass units) and `charge` (F, elementary charges).
  * - The `"bonds"` block should contain bond topology: `i`/`j` (u32,
- *   zero-based atom indices) and `order` (f32, bond order: 1.0 = single,
+ *   zero-based atom indices) and `order` (F, bond order: 1.0 = single,
  *   1.5 = aromatic, 2.0 = double, 3.0 = triple).
  *
  * # Example (JavaScript)
@@ -1002,7 +1005,7 @@ export class ClusterResult {
  * ```js
  * const frame = new Frame();
  * const atoms = frame.createBlock("atoms");
- * atoms.setColF32("x", new Float32Array([0.0, 1.54]));
+ * atoms.setColF("x", xCoords);
  * ```
  */
 export class Frame {
@@ -1044,7 +1047,7 @@ export class Frame {
      *
      * ```js
      * const atoms = frame.createBlock("atoms");
-     * atoms.setColF32("x", new Float32Array([1.0, 2.0]));
+     * atoms.setColF("x", xCoords);
      * ```
      */
     createBlock(key: string): Block;
@@ -1084,11 +1087,82 @@ export class Frame {
      * ```js
      * const atoms = frame.getBlock("atoms");
      * if (atoms) {
-     *   const x = atoms.copyColF32("x");
+     *   const x = atoms.copyColF("x");
      * }
      * ```
      */
     getBlock(key: string): Block | undefined;
+    /**
+     * Retrieve a named grid attached to this frame.
+     *
+     * Returns a cloned [`Grid`] wrapper, or `undefined` if the grid does
+     * not exist. The returned object is independent of the frame — mutations
+     * to it are not reflected in the frame without a subsequent
+     * [`insertGrid`](Frame::insert_grid) call.
+     *
+     * # Arguments
+     *
+     * * `name` — Grid name to retrieve.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const g = frame.getGrid("chgcar");
+     * if (g) {
+     *   const arr = g.getArray("rho");
+     * }
+     * ```
+     */
+    getGrid(name: string): Grid | undefined;
+    /**
+     * Read a per-frame metadata value as a numeric scalar.
+     *
+     * Returns `Some(v)` if the meta key exists AND its string value parses
+     * as an `f64`. Returns `None` if the key is missing or the value is
+     * non-numeric (e.g., `config="trans"`).
+     *
+     * `frame.meta` is a `HashMap<String, String>`; the ExtXYZ parser stores
+     * all comment-line values as strings. This accessor reads numeric ones
+     * via `str::parse::<f64>`.
+     *
+     * # Arguments
+     *
+     * * `name` — Meta key to look up (e.g., `"energy"`, `"temp"`).
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const energy = frame.getMetaScalar("energy");
+     * if (energy !== undefined) {
+     *   console.log("Energy:", energy);
+     * }
+     * ```
+     */
+    getMetaScalar(name: string): number | undefined;
+    /**
+     * Return the names of all grids attached to this frame.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const names = frame.gridNames(); // e.g. ["chgcar", "spin"]
+     * ```
+     */
+    gridNames(): Array<any>;
+    /**
+     * Returns `true` if a named grid is attached to this frame.
+     *
+     * # Arguments
+     *
+     * * `name` — Grid name to look up.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * frame.hasGrid("chgcar"); // true or false
+     * ```
+     */
+    hasGrid(name: string): boolean;
     /**
      * Insert a block by deep-copying its data into this frame's store.
      *
@@ -1116,6 +1190,45 @@ export class Frame {
      * ```
      */
     insertBlock(key: string, block: Block): void;
+    /**
+     * Attach a grid to this frame under the given name.
+     *
+     * If a grid with the same name already exists it is replaced. The grid
+     * data is moved into the frame; the JS `Grid` object becomes empty after
+     * this call and should not be reused.
+     *
+     * # Arguments
+     *
+     * * `name` — Name to store the grid under (e.g., `"chgcar"`).
+     * * `grid` — The [`Grid`] to attach.
+     *
+     * # Errors
+     *
+     * Throws a `JsValue` string if the frame has been dropped.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const grid = new Grid(10, 10, 10, origin, cell, true, true, true);
+     * grid.insertArray("rho", rhoData);
+     * frame.insertGrid("chgcar", grid);
+     * ```
+     */
+    insertGrid(name: string, grid: Grid): void;
+    /**
+     * Return the names of all metadata keys on this frame.
+     *
+     * Includes all keys regardless of whether their values are numeric
+     * or categorical. To filter to numeric keys, iterate and call
+     * [`getMetaScalar`](Self::get_meta_scalar) on each.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const names = frame.metaNames(); // e.g. ["energy", "config", "temp"]
+     * ```
+     */
+    metaNames(): string[];
     /**
      * Create a new, empty `Frame` with no blocks and no simulation box.
      *
@@ -1145,6 +1258,24 @@ export class Frame {
      * ```
      */
     removeBlock(key: string): void;
+    /**
+     * Remove a named grid from this frame.
+     *
+     * # Arguments
+     *
+     * * `name` — Grid name to remove.
+     *
+     * # Errors
+     *
+     * Throws a `JsValue` string if the frame has been dropped.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * frame.removeGrid("chgcar");
+     * ```
+     */
+    removeGrid(name: string): void;
     /**
      * Rename a block from `old_key` to `new_key`.
      *
@@ -1194,6 +1325,33 @@ export class Frame {
      * ```
      */
     renameColumn(block_key: string, old_col: string, new_col: string): boolean;
+    /**
+     * Set a per-frame metadata value.
+     *
+     * Stores `value` as the string backing for `name` on `frame.meta`.
+     * Numeric values are read back via
+     * [`getMetaScalar`](Self::get_meta_scalar) by parsing the string
+     * form. `frame.meta` is the single source of truth for per-frame
+     * scalars — no separate aggregation layer is needed on the JS side.
+     *
+     * # Arguments
+     *
+     * * `name` — Meta key (e.g., `"energy"`, `"temp"`).
+     * * `value` — String value. For numeric labels, the caller is
+     *   responsible for converting (e.g., `num.toString()`).
+     *
+     * # Errors
+     *
+     * Throws a `JsValue` string if the frame has been dropped.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * frame.setMeta("energy", "-3.14");
+     * frame.setMeta("note", "run-42");
+     * ```
+     */
+    setMeta(name: string, value: string): void;
     /**
      * Get the simulation box attached to this frame (if any).
      *
@@ -1229,13 +1387,216 @@ export class Frame {
      * # Example (JavaScript)
      *
      * ```js
-     * const origin = new Float32Array([0, 0, 0]);
+     * const origin = originVec;
      * frame.simbox = Box.cube(10.0, origin, true, true, true);
      * ```
      */
     set simbox(value: Box | null | undefined);
 }
 
+/**
+ * A uniform spatial grid storing multiple named scalar arrays.
+ *
+ * All arrays in a `Grid` share the same spatial definition: dimensions
+ * (`[nx, ny, nz]`), Cartesian origin, cell matrix (columns are lattice
+ * vectors, matching VASP/molrs convention), and periodic boundary flags.
+ *
+ * # Example (JavaScript)
+ *
+ * ```js
+ * // Create a 10×10×10 cubic grid
+ * const origin = new Float32Array([0, 0, 0]);
+ * const cell = new Float32Array([
+ *   10, 0, 0,   // first column (a vector)
+ *    0,10, 0,   // second column (b vector)
+ *    0, 0,10,   // third column (c vector)
+ * ]);
+ * const grid = new Grid(10, 10, 10, origin, cell, true, true, true);
+ *
+ * // Insert a density array (must have length = 10*10*10 = 1000)
+ * const rho = new Float32Array(1000).fill(1.0);
+ * grid.insertArray("rho", rho);
+ *
+ * // Retrieve it
+ * const arr = grid.getArray("rho");
+ * console.log(arr.toCopy());
+ * ```
+ */
+export class Grid {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Names of all scalar arrays stored in this grid.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const names = grid.arrayNames(); // e.g. ["rho", "spin"]
+     * ```
+     */
+    arrayNames(): Array<any>;
+    /**
+     * Cell matrix in Ångström as a flat array of length 9 in column-major
+     * order (columns are lattice vectors, matching VASP/molrs convention).
+     *
+     * Layout: `[col0_x, col0_y, col0_z, col1_x, col1_y, col1_z, col2_x, col2_y, col2_z]`
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const c = grid.cell();
+     * const flat = c.toCopy(); // Float32Array of length 9
+     * ```
+     */
+    cell(): WasmArray;
+    /**
+     * Grid dimensions `[nx, ny, nz]`.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * console.log(grid.dim()); // [10, 10, 10]
+     * ```
+     */
+    dim(): Uint32Array;
+    /**
+     * Retrieve a named scalar array as a zero-copy `Float64Array` view
+     * over the underlying WASM memory. Flat row-major order, length
+     * `nx * ny * nz`. Use [`Grid::dim`] for shape.
+     *
+     * **Warning**: the view is invalidated on any WASM memory growth.
+     * Copy it in JS (`new Float64Array(view)`) if it needs to outlive
+     * subsequent allocations.
+     *
+     * Returns `undefined` if the named array does not exist.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const view = grid.getArray("rho");          // zero-copy
+     * const copy = new Float64Array(view);        // owned copy if needed
+     * ```
+     */
+    getArray(name: string): Float64Array | undefined;
+    /**
+     * Returns `true` if a named array is present in this grid.
+     *
+     * # Arguments
+     *
+     * * `name` — Array name to look up.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * grid.hasArray("rho"); // true or false
+     * ```
+     */
+    hasArray(name: string): boolean;
+    /**
+     * Insert (or replace) a named scalar array.
+     *
+     * The provided `data` must have exactly `nx * ny * nz` elements in
+     * row-major `(ix, iy, iz)` order.
+     *
+     * # Arguments
+     *
+     * * `name` — Array name.
+     * * `data` — Float32Array with length equal to `grid.total()`.
+     *
+     * # Errors
+     *
+     * Throws if `data.length != nx * ny * nz`.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const rho = new Float32Array(grid.total()).fill(0.5);
+     * grid.insertArray("rho", rho);
+     * ```
+     */
+    insertArray(name: string, data: Float64Array): void;
+    /**
+     * Returns `true` if no arrays are stored.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * console.log(grid.isEmpty()); // true for a freshly created grid
+     * ```
+     */
+    isEmpty(): boolean;
+    /**
+     * Number of named arrays stored in this grid.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * console.log(grid.len()); // e.g. 2
+     * ```
+     */
+    len(): number;
+    /**
+     * Create a new empty grid with the given spatial definition.
+     *
+     * # Arguments
+     *
+     * * `dim_x`, `dim_y`, `dim_z` — Number of grid points along each axis.
+     * * `origin` — Float32Array of length 3: Cartesian origin in Ångström.
+     * * `cell` — Float32Array of length 9: cell matrix in column-major order.
+     *   `cell[0..3]` is the first lattice vector (a), `cell[3..6]` is b,
+     *   `cell[6..9]` is c (matching VASP/molrs convention where columns are
+     *   lattice vectors).
+     * * `pbc_x`, `pbc_y`, `pbc_z` — Periodic boundary flags for each axis.
+     *
+     * # Errors
+     *
+     * Throws if `origin` does not have length 3, or `cell` does not have
+     * length 9.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const origin = new Float32Array([0, 0, 0]);
+     * const cell = new Float32Array([10,0,0, 0,10,0, 0,0,10]);
+     * const grid = new Grid(10, 10, 10, origin, cell, true, true, true);
+     * ```
+     */
+    constructor(dim_x: number, dim_y: number, dim_z: number, origin: Float64Array, cell: Float64Array, pbc_x: boolean, pbc_y: boolean, pbc_z: boolean);
+    /**
+     * Cartesian origin in Ångström as a 1-D array of length 3.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const o = grid.origin();
+     * const arr = o.toCopy(); // Float32Array [ox, oy, oz]
+     * ```
+     */
+    origin(): WasmArray;
+    /**
+     * Periodic boundary flags as a `Uint8Array`-compatible slice.
+     *
+     * Each element is `1` (periodic) or `0` (not periodic).
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * console.log(grid.pbc()); // [1, 1, 1]
+     * ```
+     */
+    pbc(): Uint8Array;
+    /**
+     * Total number of voxels: `nx * ny * nz`.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * console.log(grid.total()); // 1000 for a 10×10×10 grid
+     * ```
+     */
+    total(): number;
+}
+
 /**
  * Gyration tensor per cluster.
  *
@@ -1245,9 +1606,13 @@ export class GyrationTensor {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Compute gyration tensors. Returns flat `Float32Array` (9 values per cluster).
+     * Compute gyration tensors. Returns a flat float typed array (9 values per cluster).
+     *
+     * Internally computes the cluster geometric centers (via
+     * [`RsClusterCenters`]) since the new compute trait exposes them as a
+     * required upstream — the old single-frame wasm API hides this detail.
      */
-    compute(frame: Frame, cluster_result: ClusterResult): Float32Array;
+    compute(frame: Frame, cluster_result: ClusterResult): Float64Array;
     constructor();
 }
 
@@ -1258,10 +1623,14 @@ export class InertiaTensor {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Compute inertia tensors. Returns flat `Float32Array` (9 values per cluster).
+     * Compute inertia tensors. Returns a flat float typed array (9 values per cluster).
+     *
+     * Internally computes the cluster centers of mass (via
+     * [`RsCenterOfMass`]) since the new compute trait consumes them as a
+     * required upstream — the old single-frame wasm API hides this detail.
      */
-    compute(frame: Frame, cluster_result: ClusterResult): Float32Array;
-    constructor(masses?: Float32Array | null);
+    compute(frame: Frame, cluster_result: ClusterResult): Float64Array;
+    constructor(masses?: Float64Array | null);
 }
 
 /**
@@ -1308,8 +1677,8 @@ export class LAMMPSDumpReader {
  * Reads LAMMPS data files (the format written by `write_data`). The
  * reader produces a [`Frame`] containing:
  *
- * - `"atoms"` block: `type` (i32), `x`, `y`, `z` (f32, angstrom),
- *   and optionally `charge` (f32)
+ * - `"atoms"` block: `type` (i32), `x`, `y`, `z` (F, angstrom),
+ *   and optionally `charge` (F)
  * - `"bonds"` block (if present): `i`, `j` (u32), `type` (i32)
  * - Simulation box (`simbox`) with PBC
  *
@@ -1413,7 +1782,7 @@ export class LinkedCell {
      * Finds all unique pairs `(i < j)` of atoms within the cutoff
      * distance using the cell-list algorithm.
      *
-     * The frame must have an `"atoms"` block with `x`, `y`, `z` (f32) columns.
+     * The frame must have an `"atoms"` block with `x`, `y`, `z` (F) columns.
      * If the frame has a `simbox`, periodic boundary conditions are used.
      * Otherwise, a free-boundary bounding box is auto-generated.
      *
@@ -1434,7 +1803,7 @@ export class LinkedCell {
      * ```js
      * const lc = new LinkedCell(3.0);
      * const nlist = lc.build(frame);
-     * const dists = nlist.distances(); // Float32Array
+     * const dists = nlist.distances(); // Float32Array or Float64Array
      * ```
      */
     build(frame: Frame): NeighborList;
@@ -1512,25 +1881,23 @@ export class MSD {
     /**
      * Feed a frame into the MSD analysis.
      *
-     * The first frame sets the reference configuration.
-     * Subsequent frames compute MSD relative to that reference.
+     * Internally clones the frame's core data so subsequent mutations on
+     * the JS side (e.g. trajectory playback overwriting buffers) do not
+     * race against pending [`results`](Self::results) calls. The first
+     * frame sets the reference configuration.
      *
      * # Arguments
      *
      * * `frame` - Frame with `"atoms"` block containing
-     *   `x`, `y`, `z` (f32) columns
-     *
-     * # Errors
-     *
-     * Throws if the frame is missing required columns or has a
-     * different number of atoms than the reference.
+     *   `x`, `y`, `z` (F) columns
      *
      * # Example (JavaScript)
      *
      * ```js
      * const msd = new MSD();
      * msd.feed(frame0);  // sets reference
-     * msd.feed(frame1);  // computes MSD vs frame0
+     * msd.feed(frame1);  // added to trajectory
+     * const series = msd.results();
      * ```
      */
     feed(frame: Frame): void;
@@ -1548,14 +1915,14 @@ export class MSD {
      */
     constructor();
     /**
-     * Reset the analysis, clearing reference and all results.
+     * Reset the analysis, clearing the trajectory buffer.
      */
     reset(): void;
     /**
-     * Return all accumulated MSD results as an array.
+     * Run the stateless [`molrs_compute::MSD`] over every fed frame and
+     * return the per-frame time series.
      *
-     * Returns one [`MSDResult`] per frame fed (including the
-     * reference frame, which has MSD = 0).
+     * The first frame is always the reference, so `results()[0].mean ≈ 0`.
      *
      * # Example (JavaScript)
      *
@@ -1579,7 +1946,7 @@ export class MSD {
  * ```js
  * const result = msd.compute(frame);
  * console.log(result.mean);              // number (A^2)
- * console.log(result.perParticle());     // Float32Array (A^2)
+ * console.log(result.perParticle());     // Float32Array or Float64Array (A^2)
  * ```
  */
 export class MSDResult {
@@ -1587,12 +1954,11 @@ export class MSDResult {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Per-particle squared displacements as `Float32Array` in A^2.
-     *
-     * `perParticle()[i]` is `|r_i(t) - r_i(0)|^2` for particle `i`.
-     * Length equals the number of atoms.
+     * Zero-copy `Float64Array` view of per-particle squared displacements
+     * in A². `perParticle()[i]` is `|r_i(t) - r_i(0)|²` for particle `i`.
+     * **Invalidated** on WASM memory growth; copy in JS if needed.
      */
-    perParticle(): Float32Array;
+    perParticle(): Float64Array;
     /**
      * System-average mean squared displacement in A^2.
      *
@@ -1602,6 +1968,19 @@ export class MSDResult {
     readonly mean: number;
 }
 
+/**
+ * Reader for MolRec Zarr v3 archives.
+ */
+export class MolRecReader {
+    free(): void;
+    [Symbol.dispose](): void;
+    countAtoms(): number;
+    countFrames(): number;
+    free(): void;
+    constructor(files: Map<any, any>);
+    readFrame(t: number): Frame | undefined;
+}
+
 /**
  * Result of a neighbor search: all atom pairs within a distance cutoff.
  *
@@ -1626,7 +2005,7 @@ export class MSDResult {
  *
  * const i = nlist.queryPointIndices(); // Uint32Array
  * const j = nlist.pointIndices();      // Uint32Array
- * const d = nlist.distances();         // Float32Array (in A)
+ * const d = nlist.distances();         // Float32Array or Float64Array (in A)
  * ```
  */
 export class NeighborList {
@@ -1634,28 +2013,26 @@ export class NeighborList {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Squared pairwise distances in A^2, as a `Float32Array`.
-     *
-     * More efficient than `distances()` when you only need to
-     * compare or threshold distances.
+     * Zero-copy `Float64Array` view of squared pairwise distances in A^2.
+     * Same invalidation caveat as [`queryPointIndices`](Self::query_point_indices).
      */
-    distSq(): Float32Array;
+    distSq(): Float64Array;
     /**
-     * Pairwise distances in angstrom (A), as a `Float32Array`.
+     * Pairwise distances in angstrom (A). Computed lazily from `distSq`.
      *
-     * `distances()[k]` is the distance between query point
-     * `queryPointIndices()[k]` and reference point `pointIndices()[k]`.
+     * Returns an owned copy because distances are derived on the fly
+     * (`sqrt` per pair) rather than stored.
      */
-    distances(): Float32Array;
+    distances(): Float64Array;
     /**
-     * Reference point indices (`j`) for each pair, as a `Uint32Array`.
+     * Zero-copy `Uint32Array` view of reference point indices (`j`).
+     * Same invalidation caveat as [`queryPointIndices`](Self::query_point_indices).
      */
     pointIndices(): Uint32Array;
     /**
-     * Query point indices (`i`) for each pair, as a `Uint32Array`.
-     *
-     * The `k`-th pair connects query point `queryPointIndices()[k]`
-     * to reference point `pointIndices()[k]`.
+     * Zero-copy `Uint32Array` view of query point indices (`i`) over
+     * WASM memory. **Invalidated** on any WASM memory growth — copy
+     * in JS (`new Uint32Array(view)`) if it needs to outlive later calls.
      */
     queryPointIndices(): Uint32Array;
     /**
@@ -1685,8 +2062,8 @@ export class NeighborList {
  *
  * PDB files contain a single molecular structure. The reader produces
  * a [`Frame`] with an `"atoms"` block containing columns such as
- * `name` (string), `resname` (string), `x`, `y`, `z` (f32, angstrom),
- * and optionally `occupancy` and `bfactor` (f32).
+ * `name` (string), `resname` (string), `x`, `y`, `z` (F, angstrom),
+ * and optionally `occupancy` and `bfactor` (F).
  *
  * # Example (JavaScript)
  *
@@ -1695,7 +2072,7 @@ export class NeighborList {
  * const frame = reader.read(0);
  * const atoms = frame.getBlock("atoms");
  * const names = atoms.copyColStr("name"); // ["CA", "CB", ...]
- * const x = atoms.copyColF32("x");
+ * const x = atoms.copyColF("x");
  * ```
  */
 export class PDBReader {
@@ -1761,15 +2138,16 @@ export class PDBReader {
 /**
  * Radial distribution function g(r) analysis.
  *
- * Computes the pair correlation function by binning neighbor-pair
- * distances into a histogram and normalizing by the ideal-gas
- * density (spherical shell volume normalization).
+ * Bins neighbor-pair distances in `[rMin, rMax]` and normalizes by the
+ * ideal-gas pair density. Defaults follow freud (`rMin = 0`). Periodic
+ * systems take their normalization volume from `frame.simbox`; non-periodic
+ * systems must supply it explicitly via [`computeWithVolume`].
  *
  * # Algorithm
  *
  * g(r) = n(r) / (rho * V_shell(r) * N_ref)
  *
- * where `n(r)` is the pair count in bin `r`, `rho` is the number
+ * where `n(r)` is the pair count in bin `r`, `rho = N/V` is the number
  * density, and `V_shell(r)` is the shell volume for that bin.
  *
  * # Example (JavaScript)
@@ -1778,60 +2156,73 @@ export class PDBReader {
  * const lc = new LinkedCell(5.0);
  * const nlist = lc.build(frame);
  *
- * const rdf = new RDF(100, 5.0);
+ * const rdf = new RDF(100, 5.0);          // rMin defaults to 0
  * const result = rdf.compute(frame, nlist);
  *
- * const r  = result.binCenters();  // Float32Array, bin centers in A
- * const gr = result.rdf();         // Float32Array, g(r) values
+ * // Non-periodic frame: supply the normalization volume.
+ * const resultFree = rdf.computeWithVolume(nlist, volumeA3);
+ *
+ * const r  = result.binCenters();
+ * const gr = result.rdf();
  * ```
  */
 export class RDF {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Compute the RDF from a pre-built neighbor list.
-     *
-     * The frame is needed to read the simulation box volume for
-     * normalization.
+     * Compute g(r) using the simulation-box volume from `frame.simbox`.
      *
      * # Arguments
      *
-     * * `frame` - Frame with a `simbox` set (for volume normalization)
+     * * `frame` - Frame with a `simbox` set (used only for volume)
      * * `neighbors` - Pre-built [`NeighborList`] from [`LinkedCell`]
      *
-     * # Returns
+     * # Errors
+     *
+     * Throws if the frame has no `simbox` — use
+     * [`computeWithVolume`](Self::compute_with_volume) for non-periodic frames.
+     */
+    compute(frame: Frame, neighbors: NeighborList): RDFResult;
+    /**
+     * Compute g(r) using an explicit normalization volume (A^3).
      *
-     * An [`RDFResult`] containing bin centers, g(r) values, and raw
-     * pair counts.
+     * Use this for non-periodic systems or to override the box volume.
+     * Internally wraps the supplied volume as a cubic SimBox since the
+     * underlying [`molrs_compute::RDF`] pulls its normalization volume from
+     * `frame.simbox`.
      *
-     * # Errors
+     * # Arguments
      *
-     * Throws if the frame cannot be cloned or the computation fails.
+     * * `neighbors` - Pre-built [`NeighborList`]
+     * * `volume` - Normalization volume in A^3 (must be finite and > 0)
      *
      * # Example (JavaScript)
      *
      * ```js
-     * const result = rdf.compute(frame, nlist);
-     * const gr = result.rdf(); // Float32Array
+     * const result = rdf.computeWithVolume(nlist, 1000.0);
      * ```
      */
-    compute(frame: Frame, neighbors: NeighborList): RDFResult;
+    computeWithVolume(neighbors: NeighborList, volume: number): RDFResult;
     /**
-     * Create a new RDF analysis with specified binning.
+     * Create a new RDF analysis.
      *
      * # Arguments
      *
      * * `n_bins` - Number of histogram bins
-     * * `r_max` - Maximum radial distance in angstrom (A). Should
-     *   match or be less than the neighbor-search cutoff.
+     * * `r_max` - Upper radial cutoff in angstrom (A). Should be ≤ the
+     *   neighbor-search cutoff.
+     * * `r_min` - Lower radial cutoff in angstrom (A). Optional, defaults
+     *   to 0 (freud convention). Pairs with `d < rMin` or `d == 0` are
+     *   excluded from the histogram.
      *
      * # Example (JavaScript)
      *
      * ```js
-     * const rdf = new RDF(100, 5.0); // 100 bins up to 5 A
+     * const rdf = new RDF(100, 5.0);       // rMin = 0
+     * const rdf2 = new RDF(100, 5.0, 0.5); // exclude d < 0.5 A
      * ```
      */
-    constructor(n_bins: number, r_max: number);
+    constructor(n_bins: number, r_max: number, r_min?: number | null);
 }
 
 /**
@@ -1844,9 +2235,9 @@ export class RDF {
  *
  * ```js
  * const result = rdf.compute(frame, nlist);
- * const r  = result.binCenters();  // Float32Array [0.025, 0.075, ...]
- * const gr = result.rdf();         // Float32Array, normalized g(r)
- * const nr = result.pairCounts();  // Float32Array, raw counts
+ * const r  = result.binCenters();  // Float32Array or Float64Array [0.025, 0.075, ...]
+ * const gr = result.rdf();         // Float32Array or Float64Array, normalized g(r)
+ * const nr = result.pairCounts();  // Float32Array or Float64Array, raw counts
  * console.log("Volume:", result.volume, "A^3");
  * console.log("N_ref:", result.numPoints);
  * ```
@@ -1856,34 +2247,36 @@ export class RDFResult {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Bin center positions as `Float32Array` in angstrom (A).
-     *
-     * Length equals `n_bins` (the value passed to the `RDF` constructor).
+     * Zero-copy `Float64Array` view of bin center positions in A.
+     * Length equals `n_bins`. **Invalidated** on WASM memory growth;
+     * copy in JS if it needs to outlive later calls.
      */
-    binCenters(): Float32Array;
+    binCenters(): Float64Array;
     /**
-     * Bin edge positions as `Float32Array` in angstrom (A).
-     *
-     * Length is `n_bins + 1` (one more than bin centers).
+     * Zero-copy `Float64Array` view of bin edge positions in A.
+     * Length is `n_bins + 1`. Same invalidation caveat.
      */
-    binEdges(): Float32Array;
+    binEdges(): Float64Array;
     /**
-     * Raw (un-normalized) pair counts per bin as `Float32Array`.
+     * Zero-copy `Float64Array` view of raw (un-normalized) pair counts
+     * per bin. Same invalidation caveat.
      */
-    pairCounts(): Float32Array;
+    pairCounts(): Float64Array;
     /**
-     * Normalized g(r) values as `Float32Array` (dimensionless).
-     *
-     * A uniform ideal gas has g(r) = 1.0 everywhere. Peaks indicate
-     * preferred interatomic distances (coordination shells).
+     * Zero-copy `Float64Array` view of normalized g(r). Same invalidation
+     * caveat.
      */
-    rdf(): Float32Array;
+    rdf(): Float64Array;
     /**
      * Number of reference points used in the normalization.
      */
     readonly numPoints: number;
     /**
-     * Simulation box volume used in the normalization, in A^3.
+     * Inner cutoff in A (lower edge of bin 0).
+     */
+    readonly rMin: number;
+    /**
+     * Normalization volume in A^3 (from the SimBox or the explicit caller value).
      */
     readonly volume: number;
 }
@@ -1895,119 +2288,61 @@ export class RadiusOfGyration {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Compute radii of gyration. Returns `Float32Array` of length `numClusters`.
+     * Compute radii of gyration. Returns a float typed array of length `numClusters`.
+     *
+     * Internally computes the cluster centers of mass so the single-frame
+     * wasm signature `(frame, cluster)` stays stable despite the new
+     * compute trait needing explicit COM upstream.
      */
-    compute(frame: Frame, cluster_result: ClusterResult): Float32Array;
-    constructor(masses?: Float32Array | null);
+    compute(frame: Frame, cluster_result: ClusterResult): Float64Array;
+    constructor(masses?: Float64Array | null);
 }
 
 /**
- * Reader for Zarr V3 simulation archives.
+ * MDL molfile / SDF (V2000 CTAB) reader.
+ *
+ * Parses the connection table found in `.mol` files and the record
+ * blocks of `.sdf` files. Coordinates come directly from the file —
+ * no 3D generation is performed. Only V2000 is supported; V3000
+ * records throw on read.
  *
- * Wraps [`SimulationStore`] from `molrs-core` for reading trajectory
- * frames and system metadata from an in-memory Zarr store. The store
- * is populated from a `Map<string, Uint8Array>` of file paths to
- * binary content.
+ * Produces a [`Frame`] with:
+ * - `"atoms"` block: `element` (string), `id` (u32, 1-based),
+ *   `x`, `y`, `z` (F, angstrom)
+ * - `"bonds"` block (if present): `atomi`, `atomj` (u32, 0-based),
+ *   `order` (u32)
+ *
+ * Multi-record SDF files expose each record as a separate frame via
+ * `read(step)`.
  *
  * # Example (JavaScript)
  *
  * ```js
- * const files = new Map();
- * files.set("zarr.json", new Uint8Array([...]));
- * files.set("system/.zarray", new Uint8Array([...]));
- * // ... etc.
- *
- * const reader = new SimulationReader(files);
- * const frame = reader.readFrame(0);
+ * const reader = new SDFReader(sdfContent);
+ * const frame = reader.read(0);
+ * const atoms = frame.getBlock("atoms");
+ * const x = atoms.copyColF("x");
  * ```
  */
-export class SimulationReader {
+export class SDFReader {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Return the number of atoms in the system topology.
-     *
-     * # Example (JavaScript)
-     *
-     * ```js
-     * console.log(reader.countAtoms()); // e.g., 256
-     * ```
+     * Check whether the file contains no records.
      */
-    countAtoms(): number;
+    isEmpty(): boolean;
     /**
-     * Return the number of trajectory frames in the archive.
-     *
-     * Returns `0` if no trajectory data is present.
-     *
-     * # Errors
-     *
-     * Throws a `JsValue` string on I/O errors.
-     *
-     * # Example (JavaScript)
-     *
-     * ```js
-     * console.log(reader.countFrames()); // e.g., 1000
-     * ```
+     * Return the total number of records in the SDF file.
      */
-    countFrames(): number;
+    len(): number;
     /**
-     * Create a reader from a map of file paths to binary content.
-     *
-     * The map keys are relative paths within the Zarr archive
-     * (e.g., `"zarr.json"`, `"system/.zarray"`). Values are the
-     * raw bytes of each file as `Uint8Array`.
-     *
-     * # Arguments
-     *
-     * * `files` - `Map<string, Uint8Array>` mapping archive paths
-     *   to their binary content
-     *
-     * # Returns
-     *
-     * A new `SimulationReader` ready to read frames.
-     *
-     * # Errors
-     *
-     * Throws a `JsValue` string if the archive cannot be opened
-     * (e.g., missing required metadata files).
-     *
-     * # Example (JavaScript)
-     *
-     * ```js
-     * const reader = new SimulationReader(filesMap);
-     * ```
+     * Create a new SDF reader from a string containing the file content.
      */
-    constructor(files: Map<any, any>);
+    constructor(content: string);
     /**
-     * Read a trajectory frame at the given time index.
-     *
-     * The returned [`Frame`] merges the static system topology
-     * (atoms, bonds) with the per-frame trajectory data (positions,
-     * velocities, etc.) at time step `t`.
-     *
-     * # Arguments
-     *
-     * * `t` - Zero-based time step index
-     *
-     * # Returns
-     *
-     * A [`Frame`] with merged system + trajectory data, or `undefined`
-     * if no trajectory is present.
-     *
-     * # Errors
-     *
-     * Throws a `JsValue` string on I/O or deserialization errors.
-     *
-     * # Example (JavaScript)
-     *
-     * ```js
-     * const frame = reader.readFrame(0);
-     * if (frame) {
-     *   const x = frame.getBlock("atoms").copyColF32("x");
-     * }
-     * ```
+     * Read the frame (SDF record) at the given step index.
      */
-    readFrame(t: number): Frame | undefined;
+    read(step: number): Frame | undefined;
 }
 
 /**
@@ -2028,7 +2363,7 @@ export class SimulationReader {
  *
  * const frame = ir.toFrame();
  * const atoms = frame.getBlock("atoms");
- * console.log(atoms.copyColStr("symbol")); // ["C", "C", "O", "H", ...]
+ * console.log(atoms.copyColStr("element")); // ["C", "C", "O", "H", ...]
  * ```
  */
 export class SmilesIR {
@@ -2044,7 +2379,7 @@ export class SmilesIR {
      *   are added. No 3D coordinates are present -- use
      *   [`generate3D`](crate::generate_3d_wasm) to embed coordinates.
      * - `"bonds"` block: `i`, `j` (u32, zero-based atom indices),
-     *   `order` (f32, bond order: 1.0 = single, 1.5 = aromatic,
+     *   `order` (F, bond order: 1.0 = single, 1.5 = aromatic,
      *   2.0 = double, 3.0 = triple).
      *
      * # Returns
@@ -2061,7 +2396,7 @@ export class SmilesIR {
      * ```js
      * const frame = ir.toFrame();
      * const bonds = frame.getBlock("bonds");
-     * const order = bonds.copyColF32("order");
+     * const order = bonds.copyColF("order");
      * ```
      */
     toFrame(): Frame;
@@ -2239,26 +2574,26 @@ export class TopologyRingInfo {
 }
 
 /**
- * Owned f32 array with ndarray-compatible shape metadata.
+ * Owned float array with ndarray-compatible shape metadata.
  *
- * Stores a flat `Vec<f32>` together with a shape descriptor (e.g.,
+ * Stores a flat `Vec<F>` together with a shape descriptor (e.g.,
  * `[N, 3]` for an Nx3 coordinate matrix). Used for passing
  * multi-dimensional numeric data across the WASM boundary.
  *
  * # Memory layout
  *
  * Data is stored in row-major (C) order, matching ndarray's default
- * and JavaScript's `Float32Array` convention.
+ * and JavaScript's float typed-array convention.
  *
  * # Example (JavaScript)
  *
  * ```js
  * // Create a 2x3 zero array
  * const arr = new WasmArray([2, 3]);
- * arr.writeFrom(new Float32Array([1,2,3, 4,5,6]));
+ * arr.writeFrom(floatArray);
  *
  * // Or from existing data
- * const arr2 = WasmArray.from(new Float32Array([1,2,3]), [1, 3]);
+ * const arr2 = WasmArray.from(floatArray, [1, 3]);
  *
  * // Get data back
  * const copy = arr.toCopy();       // safe owned copy
@@ -2269,15 +2604,15 @@ export class WasmArray {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Return the data type string. Always `"float"` for `WasmArray`.
+     * Return the concrete float dtype string for this build.
      */
     dtype(): string;
     /**
-     * Create a `WasmArray` from an existing JS `Float32Array`.
+     * Create a `WasmArray` from an existing JS float typed array.
      *
      * # Arguments
      *
-     * * `data` - Source `Float32Array`
+     * * `data` - Source float typed array (`Float32Array` or `Float64Array`)
      * * `shape` - Optional shape. If omitted, defaults to `[data.length]` (1D).
      *
      * # Returns
@@ -2291,11 +2626,11 @@ export class WasmArray {
      * # Example (JavaScript)
      *
      * ```js
-     * const arr = WasmArray.from(new Float32Array([1,2,3,4,5,6]), [2, 3]);
+     * const arr = WasmArray.from(floatArray, [2, 3]);
      * console.log(arr.shape()); // [2, 3]
      * ```
      */
-    static from(data: Float32Array, shape?: Uint32Array | null): WasmArray;
+    static from(data: Float64Array, shape?: Uint32Array | null): WasmArray;
     /**
      * Check whether the array contains no elements.
      */
@@ -2355,13 +2690,13 @@ export class WasmArray {
      * # Example (JavaScript)
      *
      * ```js
-     * const arr = WasmArray.from(new Float32Array([1, 2, 3]));
+     * const arr = WasmArray.from(floatArray);
      * console.log(arr.sum()); // 6.0
      * ```
      */
     sum(): number;
     /**
-     * Create an owned JS `Float32Array` copy of the data.
+     * Create an owned JS float typed-array copy of the data.
      *
      * The returned array is an independent copy that is safe to store
      * and use regardless of subsequent WASM memory operations.
@@ -2372,9 +2707,9 @@ export class WasmArray {
      * const copy = arr.toCopy(); // safe to keep indefinitely
      * ```
      */
-    toCopy(): Float32Array;
+    toCopy(): Float64Array;
     /**
-     * Zero-copy `Float32Array` view over this array's backing storage.
+     * Zero-copy float typed-array view over this array's backing storage.
      *
      * **Warning**: The returned view becomes **invalid** if WASM linear
      * memory grows (due to any allocation). Use [`toCopy`](WasmArray::to_copy)
@@ -2382,7 +2717,8 @@ export class WasmArray {
      *
      * # Safety (internal)
      *
-     * Uses `Float32Array::view` which creates an unowned view into
+     * Uses the corresponding JS float typed-array `view` constructor,
+     * which creates an unowned view into
      * WASM memory. The view must not outlive the `WasmArray` and must
      * not be used after any allocation that could trigger memory growth.
      *
@@ -2393,16 +2729,16 @@ export class WasmArray {
      * // Do NOT allocate between view creation and use
      * ```
      */
-    toTypedArray(): Float32Array;
+    toTypedArray(): Float64Array;
     /**
-     * Overwrite the array contents from a JS `Float32Array`.
+     * Overwrite the array contents from a JS float typed array.
      *
      * The source array must have exactly the same number of elements
      * as this `WasmArray` (i.e., the shape is preserved).
      *
      * # Arguments
      *
-     * * `arr` - Source `Float32Array` with matching length
+     * * `arr` - Source float typed array with matching length
      *
      * # Errors
      *
@@ -2412,10 +2748,118 @@ export class WasmArray {
      *
      * ```js
      * const wa = new WasmArray([3]);
-     * wa.writeFrom(new Float32Array([1.0, 2.0, 3.0]));
+     * wa.writeFrom(floatArray);
      * ```
      */
-    write_from(arr: Float32Array): void;
+    write_from(arr: Float64Array): void;
+}
+
+/**
+ * Wrapper for [`molrs_compute::kmeans::KMeans`].
+ *
+ * # Example (JavaScript)
+ *
+ * ```js
+ * const km = new WasmKMeans(3, 100, 42);
+ * const labels = km.fit(coords, nRows, 2);   // Int32Array
+ * ```
+ */
+export class WasmKMeans {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Cluster a row-major `n_rows × n_dims` coordinate matrix.
+     *
+     * # Returns
+     *
+     * Cluster labels in `0..k` as an owned `Int32Array`, one per row.
+     *
+     * # Errors
+     *
+     * Throws if `k > n_rows`, `n_dims == 0`, the length does not match
+     * `n_rows * n_dims`, or any element is non-finite.
+     */
+    fit(coords: Float64Array, n_rows: number, n_dims: number): Int32Array;
+    /**
+     * Create a new k-means configuration.
+     *
+     * # Arguments
+     *
+     * * `k` — number of clusters (>= 1).
+     * * `max_iter` — maximum Lloyd iterations (>= 1).
+     * * `seed` — RNG seed for k-means++ initialization. Cast to `u64`
+     *   internally (JS numbers are `f64`; integers up to 2^53 pass
+     *   through losslessly).
+     *
+     * # Errors
+     *
+     * Throws if `k == 0` or `max_iter == 0`.
+     */
+    constructor(k: number, max_iter: number, seed: number);
+}
+
+/**
+ * Stateless wrapper for [`molrs_compute::pca::Pca2`].
+ *
+ * All configuration lives on [`fitTransform`](Self::fit_transform).
+ *
+ * # Example (JavaScript)
+ *
+ * ```js
+ * const pca = new WasmPca2();
+ * const result = pca.fitTransform(matrix, nRows, nCols);
+ * const coords   = result.coords();    // Float64Array, length 2 * nRows
+ * const variance = result.variance();  // Float64Array, length 2
+ * ```
+ */
+export class WasmPca2 {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Fit 2-component PCA on a row-major observation matrix and return the
+     * projected coordinates + per-component variance.
+     *
+     * # Arguments
+     *
+     * * `matrix` — row-major `n_rows × n_cols` observation matrix.
+     * * `n_rows` — number of observations.
+     * * `n_cols` — number of features.
+     *
+     * # Errors
+     *
+     * Throws if `n_rows < 3`, `n_cols < 2`, the length does not match
+     * `n_rows * n_cols`, any element is non-finite, or any column has
+     * zero variance.
+     */
+    fitTransform(matrix: Float64Array, n_rows: number, n_cols: number): WasmPcaResult;
+    /**
+     * Create a new PCA calculator. The struct carries no state — all
+     * parameters are supplied on [`fitTransform`](Self::fit_transform).
+     */
+    constructor();
+}
+
+/**
+ * Result of a [`WasmPca2::fit_transform`] call.
+ *
+ * Each accessor returns an **owned** `Float64Array` (copy of the underlying
+ * `Vec`) so JS is free to let this wrapper be GC'd without dangling views.
+ */
+export class WasmPcaResult {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Projected 2D coordinates as a row-major `Float64Array` of length
+     * `2 * n_rows`. `coords[2 * i + 0]` is the PC1 score for row `i`,
+     * `coords[2 * i + 1]` is PC2.
+     */
+    coords(): Float64Array;
+    /**
+     * Explained variance per component as `Float64Array` of length 2.
+     * `variance[0] >= variance[1]` by construction.
+     */
+    variance(): Float64Array;
 }
 
 /**
@@ -2423,7 +2867,7 @@ export class WasmArray {
  *
  * Supports multi-frame trajectory files. Each frame produces a
  * [`Frame`] with an `"atoms"` block containing `element` (string)
- * and `x`, `y`, `z` (f32, coordinates in angstrom) columns.
+ * and `x`, `y`, `z` (F, coordinates in angstrom) columns.
  *
  * # Example (JavaScript)
  *
@@ -2434,7 +2878,7 @@ export class WasmArray {
  *
  * const frame = reader.read(0); // first frame
  * const atoms = frame.getBlock("atoms");
- * const x = atoms.copyColF32("x");
+ * const x = atoms.copyColF("x");
  * ```
  */
 export class XYZReader {
@@ -2511,13 +2955,13 @@ export class XYZReader {
 /**
  * Generate 3D coordinates for a molecular [`Frame`].
  *
- * The input frame must have an `"atoms"` block with a `"symbol"`
+ * The input frame must have an `"atoms"` block with a `"element"`
  * string column (element symbols like `"C"`, `"N"`, `"O"`). A
- * `"bonds"` block with `i`, `j` (u32) and `order` (f32) columns
+ * `"bonds"` block with `i`, `j` (u32) and `order` (F) columns
  * is required for correct geometry.
  *
  * Returns a **new** [`Frame`] with 3D coordinates added as `x`, `y`,
- * `z` (f32, angstrom) columns in the `"atoms"` block.
+ * `z` (F, angstrom) columns in the `"atoms"` block.
  *
  * # Arguments
  *
@@ -2550,9 +2994,9 @@ export class XYZReader {
  * const frame3d = generate3D(frame2d, "fast", 42);
  *
  * const atoms = frame3d.getBlock("atoms");
- * const x = atoms.copyColF32("x"); // Float32Array with 3D x-coords
- * const y = atoms.copyColF32("y");
- * const z = atoms.copyColF32("z");
+ * const x = atoms.copyColF("x"); // Float32Array or Float64Array with 3D x-coords
+ * const y = atoms.copyColF("y");
+ * const z = atoms.copyColF("z");
  * ```
  */
 export function generate3D(frame: Frame, speed?: string | null, seed?: number | null): Frame;
@@ -2604,7 +3048,7 @@ export function start(): void;
  *
  * ```js
  * const mem = wasmMemory();
- * const buf = new Float32Array(mem.buffer, ptr, len);
+ * const buf = new Float64Array(mem.buffer, ptr, len); // or Float32Array in default builds
  * ```
  */
 export function wasmMemory(): WebAssembly.Memory;