@molcrafts/molrs 0.0.1 → 0.0.5

package/molrs.d.ts

@@ -2,554 +2,2346 @@
 /* eslint-disable */
 
 /**
- * A block containing columnar data.
+ * 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
+ * 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` |
+ * | `Int32Array` | `i32` | `"i32"` | `setColI32` | `copyColI32` | `viewColI32` |
+ * | `Uint32Array` | `u32` | `"u32"` | `setColU32` | `copyColU32` | `viewColU32` |
+ * | `string[]` | `String` | `"string"` | `setColStr` | `copyColStr` | -- |
+ *
+ * # Example (JavaScript)
+ *
+ * ```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]));
+ * console.log(block.nrows()); // 3
+ * console.log(block.keys());  // ["x", "y"]
+ *
+ * const x = block.copyColF32("x"); // owned copy, safe to keep
+ * ```
  */
 export class Block {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Gets an f32 column as Float32Array.
+     * Owned `Float32Array` copy of a column.
+     *
+     * Returns a new JS `Float32Array` that is an independent copy of
+     * the column data. Safe to store and use across allocations.
+     *
+     * # Arguments
+     *
+     * * `key` - Column name
+     *
+     * # Returns
+     *
+     * An owned `Float32Array` copy of the column.
+     *
+     * # Errors
+     *
+     * Throws if the column does not exist or is not of type `f32`.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const x = block.copyColF32("x");
+     * console.log(x[0]); // 1.0
+     * ```
      */
-    getColumnF32(key: string): Float32Array;
+    copyColF32(key: string): Float32Array;
     /**
-     * Gets an f32 column with shape (for compatibility).
+     * Owned `Int32Array` copy of a column.
+     *
+     * # Arguments
+     *
+     * * `key` - Column name
+     *
+     * # Errors
+     *
+     * Throws if the column does not exist or is not of type `i32`.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const types = block.copyColI32("type_id");
+     * ```
      */
-    getColumnF32WithShape(key: string): any;
+    copyColI32(key: string): Int32Array;
     /**
-     * Gets an i64 column.
+     * Owned `string[]` copy of a string column.
+     *
+     * # Arguments
+     *
+     * * `key` - Column name
+     *
+     * # Returns
+     *
+     * A JS `Array` of strings.
+     *
+     * # Errors
+     *
+     * Throws if the column does not exist or is not of type `string`.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const symbols = block.copyColStr("symbol"); // ["C", "C", "O"]
+     * ```
      */
-    getColumnI64(key: string): BigInt64Array;
+    copyColStr(key: string): Array<any>;
     /**
-     * Gets a string column.
+     * Owned `Uint32Array` copy of a column.
+     *
+     * # Arguments
+     *
+     * * `key` - Column name
+     *
+     * # Errors
+     *
+     * Throws if the column does not exist or is not of type `u32`.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const bondI = block.copyColU32("i");
+     * const bondJ = block.copyColU32("j");
+     * ```
      */
-    getColumnStrings(key: string): Array<any> | undefined;
+    copyColU32(key: string): Uint32Array;
     /**
-     * Gets a u32 column.
+     * Return the data type string for a column.
+     *
+     * Possible return values: `"f32"`, `"i32"`, `"u32"`, `"bool"`,
+     * `"string"`, `"u8"`. Returns `undefined` if the column does
+     * not exist.
+     *
+     * # Arguments
+     *
+     * * `key` - Column name
+     *
+     * # Returns
+     *
+     * The dtype string, or `undefined` if the column is not found.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * console.log(block.dtype("x"));      // "f32"
+     * console.log(block.dtype("symbol")); // "string"
+     * ```
      */
-    getColumnU32(key: string): Uint32Array;
+    dtype(key: string): string | undefined;
     /**
-     * Gets a u8 column.
+     * Check whether this block has zero columns.
+     *
+     * # Errors
+     *
+     * Throws if the block handle has been invalidated.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * if (block.isEmpty()) { // no columns yet }
+     * ```
      */
-    getColumnU8(key: string): Uint8Array | undefined;
+    isEmpty(): boolean;
     /**
-     * Gets column keys.
+     * Return all column names as a JS `string[]`.
+     *
+     * # Errors
+     *
+     * Throws if the block handle has been invalidated.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const names = block.keys(); // ["x", "y", "z", "symbol"]
+     * ```
      */
     keys(): Array<any>;
     /**
-     * Gets the number of columns.
+     * Return the number of columns in this block.
+     *
+     * # Errors
+     *
+     * Throws if the block handle has been invalidated.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * console.log(block.len()); // e.g., 3
+     * ```
      */
     len(): number;
     /**
-     * Creates a new empty Block.
+     * Create a new, standalone empty `Block`.
+     *
+     * The block is backed by its own temporary store. Prefer
+     * [`Frame.createBlock()`](crate::Frame::create_block) to create
+     * blocks that are immediately attached to a frame.
+     *
+     * # Errors
+     *
+     * Throws a `JsValue` string if the internal store allocation fails.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const block = new Block();
+     * block.setColF32("values", new Float32Array([1, 2, 3]));
+     * ```
      */
     constructor();
     /**
-     * Gets the number of rows.
+     * Return the number of rows (shared across all columns).
+     *
+     * Returns `0` if the block has no columns.
+     *
+     * # Errors
+     *
+     * Throws if the block handle has been invalidated.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * console.log(block.nrows()); // e.g., 100
+     * ```
      */
     nrows(): number;
     /**
-     * Renames a column.
+     * Rename a column from `old_key` to `new_key`.
+     *
+     * # Arguments
+     *
+     * * `old_key` - Current column name
+     * * `new_key` - New column name
+     *
+     * # Returns
+     *
+     * `true` if the column was found and renamed, `false` otherwise.
+     *
+     * # Errors
+     *
+     * Throws if the block handle has been invalidated.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * block.renameColumn("element", "symbol"); // true
+     * ```
      */
     renameColumn(old_key: string, new_key: string): boolean;
     /**
-     * Sets an f32 column.
+     * Set a float column from a `Float32Array`.
+     *
+     * # Arguments
+     *
+     * * `key` - Column name (e.g., `"x"`, `"mass"`, `"charge"`)
+     * * `data` - `Float32Array` 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.
+     *
+     * # Errors
+     *
+     * Throws if `shape` product does not match `data.length`, or if
+     * the resulting row count is inconsistent with existing columns.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * block.setColF32("x", new Float32Array([1.0, 2.0, 3.0]));
+     * // Multi-dimensional: 2 rows x 3 columns
+     * block.setColF32("pos", new Float32Array([1,2,3, 4,5,6]), [2, 3]);
+     * ```
+     */
+    setColF32(key: string, data: Float32Array, shape?: Uint32Array | null): void;
+    /**
+     * Set a signed integer column from an `Int32Array`.
+     *
+     * # Arguments
+     *
+     * * `key` - Column name
+     * * `data` - `Int32Array` with the column values
+     *
+     * # Errors
+     *
+     * Throws if the row count is inconsistent with existing columns.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * block.setColI32("charge_sign", new Int32Array([1, -1, 0]));
+     * ```
+     */
+    setColI32(key: string, data: Int32Array): void;
+    /**
+     * Set a string column from a JS `string[]`.
+     *
+     * # Arguments
+     *
+     * * `key` - Column name (e.g., `"symbol"`, `"name"`)
+     * * `data` - JS `Array` where every element must be a string
+     *
+     * # Errors
+     *
+     * Throws if any element is not a string, or if the row count is
+     * inconsistent with existing columns.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * atoms.setColStr("symbol", ["C", "C", "O"]);
+     * ```
      */
-    setColumnF32(key: string, data: Float32Array, shape?: Uint32Array | null): void;
+    setColStr(key: string, data: Array<any>): void;
     /**
-     * Sets an i64 column.
+     * Set an unsigned integer column from a `Uint32Array`.
+     *
+     * # Arguments
+     *
+     * * `key` - Column name (e.g., `"i"`, `"j"` for bond indices)
+     * * `data` - `Uint32Array` with the column values
+     *
+     * # Errors
+     *
+     * Throws if the row count is inconsistent with existing columns.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * // Bond topology: atom indices
+     * bonds.setColU32("i", new Uint32Array([0, 1]));
+     * bonds.setColU32("j", new Uint32Array([1, 2]));
+     * ```
      */
-    setColumnI64(key: string, data: BigInt64Array, _shape?: Uint32Array | null): void;
+    setColU32(key: string, data: Uint32Array): void;
     /**
-     * Sets a string column.
+     * Zero-copy `Float32Array` 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.
+     *
+     * # Arguments
+     *
+     * * `key` - Column name
+     *
+     * # Returns
+     *
+     * A `Float32Array` view into WASM memory.
+     *
+     * # Errors
+     *
+     * Throws if the column does not exist or is not of type `f32`.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const view = block.viewColF32("x"); // zero-copy, use immediately
+     * const copy = block.copyColF32("x"); // safe to keep
+     * ```
      */
-    setColumnStrings(key: string, data: Array<any>, _shape?: Uint32Array | null): void;
+    viewColF32(key: string): Float32Array;
     /**
-     * Sets a u32 column.
+     * Zero-copy `Int32Array` view into WASM linear memory.
+     *
+     * **Warning**: invalidated if WASM linear memory grows.
+     * Use [`copyColI32`](Block::copy_col_i32) for a safe copy.
+     *
+     * # Arguments
+     *
+     * * `key` - Column name
+     *
+     * # Errors
+     *
+     * Throws if the column does not exist or is not of type `i32`.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const view = block.viewColI32("type_id");
+     * ```
      */
-    setColumnU32(key: string, data: Uint32Array, _shape?: Uint32Array | null): void;
+    viewColI32(key: string): Int32Array;
     /**
-     * Sets a u8 column.
+     * Zero-copy `Uint32Array` view into WASM linear memory.
+     *
+     * **Warning**: invalidated if WASM linear memory grows.
+     * Use [`copyColU32`](Block::copy_col_u32) for a safe copy.
+     *
+     * # Arguments
+     *
+     * * `key` - Column name
+     *
+     * # Errors
+     *
+     * Throws if the column does not exist or is not of type `u32`.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const view = block.viewColU32("i");
+     * ```
      */
-    setColumnU8(key: string, data: Uint8Array, _shape?: Uint32Array | null): void;
+    viewColU32(key: string): Uint32Array;
 }
 
 /**
- * Simulation box defining the periodic boundary conditions and coordinate transformations.
+ * Simulation box defining periodic boundary conditions and coordinate
+ * transformations.
+ *
+ * Represents a parallelepiped defined by a 3x3 matrix `h` and an
+ * origin point. Supports periodic boundary conditions (PBC)
+ * independently in x, y, z directions.
+ *
+ * Exported as `Box` in JavaScript.
+ *
+ * # Example (JavaScript)
  *
- * Represents a parallelepiped defined by a 3x3 matrix `h` and an origin.
- * Supports periodic boundary conditions (PBC) independently in x, y, z directions.
+ * ```js
+ * const h = new Float32Array([10, 0, 0, 0, 10, 0, 0, 0, 10]);
+ * const origin = new Float32Array([0, 0, 0]);
+ * const box = new Box(h, origin, true, true, true);
+ * console.log(box.volume()); // 1000.0
+ * console.log(box.lengths().toCopy()); // [10, 10, 10]
+ * ```
  */
 export class Box {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Create a cubic box.
+     * Create a cubic box with equal side lengths.
      *
      * # Arguments
-     * * `a` - Side length of the cube
-     * * `origin` - 3D origin vector as Float32Array with 3 elements
-     * * `pbc_x`, `pbc_y`, `pbc_z` - Periodic boundary conditions for each axis
+     *
+     * * `a` - Side length of the cube in angstrom (A)
+     * * `origin` - 3D origin vector as `Float32Array` with 3 elements
+     *   `[x, y, z]` in angstrom
+     * * `pbc_x` - Enable periodic boundary in x direction
+     * * `pbc_y` - Enable periodic boundary in y direction
+     * * `pbc_z` - Enable periodic boundary in z direction
+     *
+     * # Returns
+     *
+     * A new cubic `Box` with side length `a`.
+     *
+     * # Errors
+     *
+     * Throws if `origin` does not have 3 elements.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const origin = new Float32Array([0, 0, 0]);
+     * 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;
     /**
      * Calculate displacement vectors between two sets of coordinates.
      *
+     * Computes `delta = b - a` for each pair of points. When
+     * `minimum_image` is `true`, the minimum-image convention is
+     * applied so that the displacement uses the shortest vector
+     * under periodic boundary conditions.
+     *
+     * # Arguments
+     *
+     * * `a` - `WasmArray` with shape `[N, 3]` (reference positions in A)
+     * * `b` - `WasmArray` with shape `[N, 3]` (target positions in A)
+     * * `minimum_image` - If `true`, apply minimum image convention
+     *   for PBC-enabled axes
+     *
+     * # Returns
+     *
+     * `WasmArray` with shape `[N, 3]` containing displacement vectors
+     * `(b - a)` in angstrom (A).
+     *
+     * # Errors
+     *
+     * Throws if `a` or `b` does not have shape `[N, 3]`, or if the
+     * two arrays have different numbers of rows.
+     *
+     * # 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 d = box.delta(a, b, true); // minimum-image displacement
+     * ```
+     */
+    delta(a: WasmArray, b: WasmArray, minimum_image: boolean): WasmArray;
+    /**
+     * Calculate displacement vectors and write the result directly into
+     * a [`Block`] column.
+     *
+     * This is an allocation-efficient alternative to [`delta`](Box::delta).
+     *
+     * # Arguments
+     *
+     * * `a` - `WasmArray` with shape `[N, 3]` (reference positions in A)
+     * * `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]`)
+     *
+     * # Errors
+     *
+     * Throws if shapes are invalid or if the block write fails.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * box.deltaToBlock(a, b, true, outBlock, "displacements");
+     * ```
+     */
+    deltaToBlock(a: WasmArray, b: WasmArray, minimum_image: boolean, out_block: Block, out_key: string): void;
+    /**
+     * Return the 8 corner vertices of the parallelepiped.
+     *
+     * # Returns
+     *
+     * `WasmArray` with shape `[8, 3]` containing the corner
+     * coordinates in angstrom (A). The flat array has 24 elements.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const corners = box.getCorners();
+     * console.log(corners.len()); // 24 (8 corners x 3 coords)
+     * ```
+     */
+    get_corners(): WasmArray;
+    /**
+     * Return the box edge lengths as a `WasmArray` with shape `[3]`.
+     *
+     * For orthorhombic boxes these are `[lx, ly, lz]`. For triclinic
+     * boxes these are the lengths of the three cell vectors.
+     *
+     * # Returns
+     *
+     * `WasmArray` containing `[lx, ly, lz]` in angstrom (A).
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const L = box.lengths().toCopy(); // Float32Array [10, 10, 10]
+     * ```
+     */
+    lengths(): WasmArray;
+    /**
+     * Create a new box from a 3x3 cell matrix and origin.
+     *
      * # Arguments
-     * * `a` - F32View with Nx3 coordinates
-     * * `b` - F32View with Nx3 coordinates
-     * * `minimum_image` - If true, apply minimum image convention
+     *
+     * * `h` - 3x3 cell matrix as `Float32Array` 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
+     *   `[x, y, z]` in angstrom.
+     * * `pbc_x` - Enable periodic boundary in x direction
+     * * `pbc_y` - Enable periodic boundary in y direction
+     * * `pbc_z` - Enable periodic boundary in z direction
      *
      * # Returns
-     * F32View with Nx3 displacement vectors (b - a)
+     *
+     * A new `Box` instance.
+     *
+     * # Errors
+     *
+     * Throws if `h` does not have 9 elements or `origin` does not have
+     * 3 elements, or if the matrix is singular.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * // Triclinic box
+     * const h = new Float32Array([10, 2, 0, 0, 10, 0, 0, 0, 10]);
+     * const origin = new Float32Array([0, 0, 0]);
+     * const box = new Box(h, origin, true, true, true);
+     * ```
      */
-    delta(a: F32View, b: F32View, minimum_image: boolean): F32View;
-    get_corners(): F32View;
+    constructor(h: Float32Array, origin: Float32Array, pbc_x: boolean, pbc_y: boolean, pbc_z: boolean);
     /**
-     * Get the box edge lengths as F32View [lx, ly, lz].
+     * Return the box origin as a `WasmArray` with shape `[3]`.
+     *
+     * The origin is the lower-left corner of the box in angstrom (A).
+     *
+     * # Returns
+     *
+     * `WasmArray` containing `[ox, oy, oz]` in angstrom.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const o = box.origin().toCopy(); // Float32Array [0, 0, 0]
+     * ```
      */
-    lengths(): F32View;
+    origin(): WasmArray;
+    /**
+     * Create an orthorhombic (rectangular) box with axis-aligned edges.
+     *
+     * # Arguments
+     *
+     * * `lengths` - Box dimensions as `Float32Array` with 3 elements
+     *   `[lx, ly, lz]` in angstrom (A)
+     * * `origin` - 3D origin vector as `Float32Array` with 3 elements
+     *   `[x, y, z]` in angstrom
+     * * `pbc_x` - Enable periodic boundary in x direction
+     * * `pbc_y` - Enable periodic boundary in y direction
+     * * `pbc_z` - Enable periodic boundary in z direction
+     *
+     * # Returns
+     *
+     * A new orthorhombic `Box`.
+     *
+     * # Errors
+     *
+     * Throws if `lengths` or `origin` does not have 3 elements.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const origin = new Float32Array([0, 0, 0]);
+     * const box = Box.ortho(new Float32Array([10, 20, 30]), 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;
+    /**
+     * Return the box tilt factors as a `WasmArray` with shape `[3]`.
+     *
+     * Tilt factors `[xy, xz, yz]` define the off-diagonal elements
+     * of the cell matrix (LAMMPS convention). For orthorhombic boxes
+     * all tilts are zero.
+     *
+     * # Returns
+     *
+     * `WasmArray` containing `[xy, xz, yz]` (dimensionless ratios
+     * multiplied by the corresponding box length, so effectively in A).
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const t = box.tilts().toCopy(); // Float32Array [0, 0, 0]
+     * ```
+     */
+    tilts(): WasmArray;
+    /**
+     * Convert fractional to Cartesian coordinates and write the result
+     * directly into a [`Block`] column.
+     *
+     * # Arguments
+     *
+     * * `coords` - `WasmArray` with shape `[N, 3]` (fractional, dimensionless)
+     * * `out_block` - Target [`Block`]
+     * * `out_key` - Column name for the result (f32, shape `[N, 3]`)
+     *
+     * # Errors
+     *
+     * Throws if `coords` does not have shape `[N, 3]`.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * box.toCartToBlock(fracCoords, outBlock, "cart_coords");
+     * ```
+     */
+    toCartToBlock(coords: WasmArray, out_block: Block, out_key: string): void;
+    /**
+     * Convert Cartesian to fractional coordinates and write the result
+     * directly into a [`Block`] column.
+     *
+     * # Arguments
+     *
+     * * `coords` - `WasmArray` with shape `[N, 3]` (Cartesian, A)
+     * * `out_block` - Target [`Block`]
+     * * `out_key` - Column name for the result (f32, shape `[N, 3]`)
+     *
+     * # Errors
+     *
+     * Throws if `coords` does not have shape `[N, 3]`.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * box.toFracToBlock(cartCoords, outBlock, "frac_coords");
+     * ```
+     */
+    toFracToBlock(coords: WasmArray, out_block: Block, out_key: string): void;
+    /**
+     * Convert fractional coordinates to Cartesian coordinates.
+     *
+     * # Arguments
+     *
+     * * `coords` - `WasmArray` with shape `[N, 3]` containing
+     *   fractional coordinates (dimensionless)
+     *
+     * # Returns
+     *
+     * `WasmArray` with shape `[N, 3]` containing Cartesian coordinates
+     * in angstrom (A).
+     *
+     * # Errors
+     *
+     * Throws if `coords` does not have shape `[N, 3]`.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const frac = WasmArray.from(new Float32Array([0.5, 0.5, 0.5]), [1, 3]);
+     * const cart = box.toCart(frac);
+     * console.log(cart.toCopy()); // [5, 5, 5] for a 10x10x10 box
+     * ```
+     */
+    to_cart(coords: WasmArray): WasmArray;
+    /**
+     * Convert Cartesian coordinates to fractional coordinates.
+     *
+     * Fractional coordinates are in the range [0, 1) for atoms
+     * inside the primary image of the box.
+     *
+     * # Arguments
+     *
+     * * `coords` - `WasmArray` with shape `[N, 3]` containing
+     *   Cartesian coordinates in angstrom (A)
+     *
+     * # Returns
+     *
+     * `WasmArray` with shape `[N, 3]` containing fractional coordinates
+     * (dimensionless).
+     *
+     * # Errors
+     *
+     * Throws if `coords` does not have shape `[N, 3]`.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const cart = WasmArray.from(new Float32Array([5, 5, 5]), [1, 3]);
+     * const frac = box.toFrac(cart);
+     * console.log(frac.toCopy()); // [0.5, 0.5, 0.5] for a 10x10x10 box
+     * ```
+     */
+    to_frac(coords: WasmArray): WasmArray;
+    /**
+     * Return the box volume in cubic angstrom (A^3).
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * console.log(box.volume()); // e.g., 1000.0
+     * ```
+     */
+    volume(): number;
+    /**
+     * Wrap Cartesian coordinates into the primary image of the box.
+     *
+     * Atoms outside the box are translated back into the primary image
+     * using the periodic boundary conditions. Only axes with PBC
+     * enabled are wrapped.
+     *
+     * # Arguments
+     *
+     * * `coords` - `WasmArray` with shape `[N, 3]` containing
+     *   Cartesian coordinates in angstrom (A)
+     *
+     * # Returns
+     *
+     * `WasmArray` with shape `[N, 3]` containing wrapped coordinates
+     * in angstrom (A).
+     *
+     * # Errors
+     *
+     * Throws if `coords` does not have shape `[N, 3]`.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const pos = WasmArray.from(new Float32Array([12, -1, 5]), [1, 3]);
+     * const wrapped = box.wrap(pos); // wraps into [0, lx) x [0, ly) x [0, lz)
+     * ```
+     */
+    wrap(coords: WasmArray): WasmArray;
+    /**
+     * Wrap coordinates and write the result directly into a [`Block`] column.
+     *
+     * This is an allocation-efficient alternative to [`wrap`](Box::wrap)
+     * that avoids creating an intermediate `WasmArray`.
+     *
+     * # Arguments
+     *
+     * * `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]`)
+     *
+     * # Errors
+     *
+     * Throws if `coords` does not have shape `[N, 3]` or if the
+     * block write fails.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * box.wrapToBlock(coords, outBlock, "wrapped_pos");
+     * ```
+     */
+    wrapToBlock(coords: WasmArray, out_block: Block, out_key: string): void;
+}
+
+/**
+ * Distance-based cluster analysis using BFS on the neighbor graph.
+ *
+ * Particles that are connected (directly or transitively) through
+ * neighbor-list pairs are grouped into clusters. Clusters smaller
+ * than `minClusterSize` are filtered out (their particles get
+ * cluster ID = -1).
+ *
+ * # Example (JavaScript)
+ *
+ * ```js
+ * const lc = new LinkedCell(2.0);
+ * const nlist = lc.build(frame);
+ *
+ * const cluster = new Cluster(5); // min 5 particles per cluster
+ * const result = cluster.compute(frame, nlist);
+ *
+ * console.log(result.numClusters);     // number of valid clusters
+ * console.log(result.clusterIdx());    // Int32Array, per-particle IDs
+ * console.log(result.clusterSizes());  // Uint32Array, size of each cluster
+ * ```
+ */
+export class Cluster {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Run cluster analysis on a frame with pre-built neighbor pairs.
+     *
+     * # Arguments
+     *
+     * * `frame` - Frame with atom positions
+     * * `neighbors` - Pre-built [`NeighborList`] defining connectivity
+     *
+     * # Returns
+     *
+     * A [`ClusterResult`] with per-particle cluster IDs and cluster sizes.
+     *
+     * # Errors
+     *
+     * Throws if the frame cannot be cloned or the analysis fails.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const result = cluster.compute(frame, nlist);
+     * ```
+     */
+    compute(frame: Frame, neighbors: NeighborList): ClusterResult;
+    /**
+     * Create a cluster analysis with a minimum cluster size filter.
+     *
+     * # Arguments
+     *
+     * * `min_cluster_size` - Minimum number of particles for a cluster
+     *   to be considered valid. Clusters with fewer particles are
+     *   discarded (their particles get cluster ID = -1).
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const cluster = new Cluster(5); // ignore clusters < 5 particles
+     * ```
+     */
+    constructor(min_cluster_size: number);
+}
+
+/**
+ * Result of a distance-based cluster analysis.
+ *
+ * # Example (JavaScript)
+ *
+ * ```js
+ * const result = cluster.compute(frame, nlist);
+ * console.log(result.numClusters);       // number
+ *
+ * const ids   = result.clusterIdx();     // Int32Array (per-particle)
+ * const sizes = result.clusterSizes();   // Uint32Array (per-cluster)
+ *
+ * // Particles in filtered-out clusters have id = -1
+ * for (let i = 0; i < ids.length; i++) {
+ *   if (ids[i] === -1) console.log(`Particle ${i} not in any valid cluster`);
+ * }
+ * ```
+ */
+export class ClusterResult {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Per-particle cluster ID assignment as `Int32Array`.
+     *
+     * `clusterIdx()[i]` is the cluster ID for particle `i`.
+     * Particles in clusters smaller than `minClusterSize` are
+     * assigned ID = -1 (filtered out).
+     *
+     * Cluster IDs are zero-based and contiguous: `0, 1, ..., numClusters-1`.
+     */
+    clusterIdx(): Int32Array;
+    /**
+     * Size (particle count) of each valid cluster as `Uint32Array`.
+     *
+     * `clusterSizes()[c]` is the number of particles in cluster `c`.
+     * Length equals `numClusters`.
+     */
+    clusterSizes(): Uint32Array;
+    /**
+     * Number of valid clusters found (after min-size filtering).
+     */
+    readonly numClusters: number;
+}
+
+/**
+ * Hierarchical data container mapping string keys to typed [`Block`]s.
+ *
+ * A `Frame` owns a set of named blocks (column stores) and an optional
+ * simulation box ([`Box`](super::region::simbox::Box)). This is the
+ * primary interchange type for molecular data in the WASM API.
+ *
+ * # 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).
+ * - The `"bonds"` block should contain bond topology: `i`/`j` (u32,
+ *   zero-based atom indices) and `order` (f32, bond order: 1.0 = single,
+ *   1.5 = aromatic, 2.0 = double, 3.0 = triple).
+ *
+ * # Example (JavaScript)
+ *
+ * ```js
+ * const frame = new Frame();
+ * const atoms = frame.createBlock("atoms");
+ * atoms.setColF32("x", new Float32Array([0.0, 1.54]));
+ * ```
+ */
+export class Frame {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Remove all blocks from this frame (but keep the frame alive).
+     *
+     * # Errors
+     *
+     * Throws a `JsValue` string if the frame has already been dropped.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * frame.clear();
+     * ```
+     */
+    clear(): void;
+    /**
+     * Create a new empty [`Block`] and register it under `key`.
+     *
+     * If a block with the same key already exists it is replaced.
+     *
+     * # Arguments
+     *
+     * * `key` - Block name (e.g., `"atoms"`, `"bonds"`)
+     *
+     * # Returns
+     *
+     * A mutable [`Block`] handle that can be used to add columns.
+     *
+     * # Errors
+     *
+     * Throws a `JsValue` string if the underlying store operation fails
+     * (e.g., the frame has been dropped).
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const atoms = frame.createBlock("atoms");
+     * atoms.setColF32("x", new Float32Array([1.0, 2.0]));
+     * ```
+     */
+    createBlock(key: string): Block;
+    /**
+     * Explicitly release this frame and all its blocks from the store.
+     *
+     * After calling `drop()`, any subsequent operations on this frame
+     * or its blocks will throw. This is optional -- the frame will also
+     * be released when garbage-collected by the JS engine.
+     *
+     * # Errors
+     *
+     * Throws a `JsValue` string if the frame was already dropped.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * frame.drop();
+     * // frame.clear() would now throw
+     * ```
+     */
+    drop(): void;
+    /**
+     * Retrieve an existing [`Block`] by name.
+     *
+     * # Arguments
+     *
+     * * `key` - Block name to look up
+     *
+     * # Returns
+     *
+     * The [`Block`] if found, or `undefined` if no block with that key
+     * exists in this frame.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const atoms = frame.getBlock("atoms");
+     * if (atoms) {
+     *   const x = atoms.copyColF32("x");
+     * }
+     * ```
+     */
+    getBlock(key: string): Block | undefined;
+    /**
+     * Insert a block by deep-copying its data into this frame's store.
+     *
+     * This is useful for transferring a block from one frame to another.
+     * The source block's data is cloned; subsequent modifications to the
+     * source will not affect this frame.
+     *
+     * # Arguments
+     *
+     * * `key` - Name under which to store the block
+     * * `block` - The source [`Block`] whose data will be copied
+     *
+     * # Errors
+     *
+     * Throws a `JsValue` string if either the source block or the
+     * destination frame handle is invalid.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const otherFrame = new Frame();
+     * const atoms = otherFrame.createBlock("atoms");
+     * // ... populate atoms ...
+     * frame.insertBlock("atoms", atoms);
+     * ```
+     */
+    insertBlock(key: string, block: Block): void;
+    /**
+     * Create a new, empty `Frame` with no blocks and no simulation box.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const frame = new Frame();
+     * ```
+     */
+    constructor();
+    /**
+     * Remove a block by name.
+     *
+     * # Arguments
+     *
+     * * `key` - Block name to remove
+     *
+     * # Errors
+     *
+     * Throws a `JsValue` string if the frame has been dropped or the
+     * key does not exist.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * frame.removeBlock("bonds");
+     * ```
+     */
+    removeBlock(key: string): void;
+    /**
+     * Rename a block from `old_key` to `new_key`.
+     *
+     * # Arguments
+     *
+     * * `old_key` - Current block name
+     * * `new_key` - New block name
+     *
+     * # Returns
+     *
+     * `true` if the block was found and renamed, `false` if `old_key`
+     * did not exist.
+     *
+     * # Errors
+     *
+     * Throws a `JsValue` string if the frame has been dropped.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * frame.renameBlock("atoms", "particles");
+     * ```
+     */
+    renameBlock(old_key: string, new_key: string): boolean;
+    /**
+     * Rename a column within a specific block.
+     *
+     * # Arguments
+     *
+     * * `block_key` - Name of the block containing the column
+     * * `old_col` - Current column name
+     * * `new_col` - New column name
+     *
+     * # Returns
+     *
+     * `true` if the column was found and renamed, `false` if
+     * `old_col` did not exist in the block.
+     *
+     * # Errors
+     *
+     * Throws a `JsValue` string if the frame or block does not exist.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * frame.renameColumn("atoms", "element", "symbol");
+     * ```
+     */
+    renameColumn(block_key: string, old_col: string, new_col: string): boolean;
+    /**
+     * Get the simulation box attached to this frame (if any).
+     *
+     * # Returns
+     *
+     * The [`Box`](super::region::simbox::Box) if one has been set,
+     * or `undefined` otherwise.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const box = frame.simbox;
+     * if (box) {
+     *   console.log("Volume:", box.volume());
+     * }
+     * ```
+     */
+    get simbox(): Box | undefined;
+    /**
+     * Attach or detach a simulation box.
+     *
+     * Pass a [`Box`](super::region::simbox::Box) to attach, or
+     * `undefined`/`null` to detach.
+     *
+     * # Arguments
+     *
+     * * `simbox` - The simulation box, or `undefined`/`null` to remove it
+     *
+     * # Errors
+     *
+     * Throws a `JsValue` string if the frame has been dropped.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const origin = new Float32Array([0, 0, 0]);
+     * frame.simbox = Box.cube(10.0, origin, true, true, true);
+     * ```
+     */
+    set simbox(value: Box | null | undefined);
+}
+
+/**
+ * LAMMPS data file reader.
+ *
+ * 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)
+ * - `"bonds"` block (if present): `i`, `j` (u32), `type` (i32)
+ * - Simulation box (`simbox`) with PBC
+ *
+ * Only a single frame is supported (`step = 0`).
+ *
+ * # Example (JavaScript)
+ *
+ * ```js
+ * const reader = new LAMMPSReader(dataFileContent);
+ * const frame = reader.read(0);
+ * const atoms = frame.getBlock("atoms");
+ * const bonds = frame.getBlock("bonds");
+ * const box   = frame.simbox;
+ * ```
+ */
+export class LAMMPSReader {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Check whether the file contains no valid frames.
+     *
+     * # Errors
+     *
+     * Throws a `JsValue` string on parse errors.
+     */
+    isEmpty(): boolean;
+    /**
+     * Return the number of frames (always 0 or 1 for LAMMPS data files).
+     *
+     * # Errors
+     *
+     * Throws a `JsValue` string on parse errors.
+     */
+    len(): number;
+    /**
+     * Create a new LAMMPS data file reader from string content.
+     *
+     * # Arguments
+     *
+     * * `content` - The full text content of a LAMMPS data file
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const reader = new LAMMPSReader(dataFileString);
+     * ```
+     */
+    constructor(content: string);
+    /**
+     * Read the frame at the given step index.
+     *
+     * LAMMPS data files contain a single configuration, so only
+     * `step = 0` is valid. Passing any other step returns `undefined`.
+     *
+     * # Arguments
+     *
+     * * `step` - Frame index (must be `0`)
+     *
+     * # Returns
+     *
+     * A [`Frame`] with atoms, optional bonds, and simbox, or `undefined`.
+     *
+     * # Errors
+     *
+     * Throws a `JsValue` string on parse errors.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const frame = reader.read(0);
+     * ```
+     */
+    read(step: number): Frame | undefined;
+}
+
+/**
+ * Cell-list (linked-cell) based neighbor search.
+ *
+ * Creates a spatial index from a [`Frame`]'s atom positions and
+ * simulation box, then finds all neighbor pairs within the cutoff
+ * distance.
+ *
+ * All distances are in angstrom (A).
+ *
+ * # Example (JavaScript)
+ *
+ * ```js
+ * const lc = new LinkedCell(3.0);       // cutoff = 3.0 A
+ * const nlist = lc.build(frame);         // self-query (unique pairs i < j)
+ * const cross = lc.query(ref, other);    // cross-query
+ *
+ * console.log(nlist.numPairs);
+ * ```
+ */
+export class LinkedCell {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Build a neighbor list from a [`Frame`] (self-query).
+     *
+     * 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.
+     * If the frame has a `simbox`, periodic boundary conditions are used.
+     * Otherwise, a free-boundary bounding box is auto-generated.
+     *
+     * # Arguments
+     *
+     * * `frame` - Frame with atom positions
+     *
+     * # Returns
+     *
+     * A [`NeighborList`] containing all unique pairs within the cutoff.
+     *
+     * # Errors
+     *
+     * Throws if the frame is missing required data.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const lc = new LinkedCell(3.0);
+     * const nlist = lc.build(frame);
+     * const dists = nlist.distances(); // Float32Array
+     * ```
+     */
+    build(frame: Frame): NeighborList;
+    /**
+     * Create a linked-cell neighbor search with the given distance cutoff.
+     *
+     * # Arguments
+     *
+     * * `cutoff` - Maximum neighbor distance in angstrom (A)
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const lc = new LinkedCell(5.0);
+     * ```
+     */
+    constructor(cutoff: number);
+    /**
+     * Cross-query: find all pairs where `i` indexes query points and
+     * `j` indexes the reference points.
+     *
+     * # Arguments
+     *
+     * * `ref_frame` - Frame with reference atom positions
+     * * `query_frame` - Frame with query atom positions (must have
+     *   `"atoms"` block with `x`, `y`, `z` columns)
+     *
+     * # Returns
+     *
+     * A [`NeighborList`] containing all `(i, j, distance)` pairs
+     * within the cutoff.
+     *
+     * # Errors
+     *
+     * Throws if either frame is missing required columns.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const lc = new LinkedCell(3.0);
+     * const crossPairs = lc.query(refFrame, otherFrame);
+     * console.log(crossPairs.numPairs);
+     * ```
+     */
+    query(ref_frame: Frame, query_frame: Frame): NeighborList;
+}
+
+/**
+ * Mean squared displacement (MSD) analysis.
+ *
+ * Computes MSD = |r(t) - r(0)|^2 for each particle and the system
+ * average. The first frame fed is automatically used as the reference.
+ * Useful for measuring diffusion coefficients via D = MSD / (6t).
+ *
+ * All distances are in angstrom (A), so MSD is in A^2.
+ *
+ * # Example (JavaScript)
+ *
+ * ```js
+ * const msd = new MSD();
+ * for (const frame of trajectory) {
+ *   msd.feed(frame);         // first frame = reference
+ * }
+ * const results = msd.results();  // MSDResult[] per frame
+ * console.log(results[10].mean);  // MSD at frame 10 in A^2
+ * ```
+ *
+ * # References
+ *
+ * - Einstein, A. (1905). *Annalen der Physik*, 322(8), 549-560.
+ */
+export class MSD {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Feed a frame into the MSD analysis.
+     *
+     * The first frame sets the reference configuration.
+     * Subsequent frames compute MSD relative to that reference.
+     *
+     * # 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.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const msd = new MSD();
+     * msd.feed(frame0);  // sets reference
+     * msd.feed(frame1);  // computes MSD vs frame0
+     * ```
+     */
+    feed(frame: Frame): void;
+    /**
+     * Create an empty MSD analysis.
+     *
+     * The first frame passed to [`feed`] becomes the reference
+     * configuration (t=0).
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const msd = new MSD();
+     * ```
+     */
+    constructor();
+    /**
+     * Reset the analysis, clearing reference and all results.
+     */
+    reset(): void;
+    /**
+     * Return all accumulated MSD results as an array.
+     *
+     * Returns one [`MSDResult`] per frame fed (including the
+     * reference frame, which has MSD = 0).
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const results = msd.results();
+     * results.forEach((r, t) => console.log(`t=${t}: MSD=${r.mean}`));
+     * ```
+     */
+    results(): MSDResult[];
+    /**
+     * Number of frames accumulated.
+     */
+    readonly count: number;
+}
+
+/**
+ * Result of a mean squared displacement computation.
+ *
+ * # Example (JavaScript)
+ *
+ * ```js
+ * const result = msd.compute(frame);
+ * console.log(result.mean);              // number (A^2)
+ * console.log(result.perParticle());     // Float32Array (A^2)
+ * ```
+ */
+export class MSDResult {
+    private constructor();
+    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.
+     */
+    perParticle(): Float32Array;
+    /**
+     * System-average mean squared displacement in A^2.
+     *
+     * This is the arithmetic mean of all per-particle squared
+     * displacements: `mean = sum(|r_i(t) - r_i(0)|^2) / N`.
+     */
+    readonly mean: number;
+}
+
+/**
+ * Result of a neighbor search: all atom pairs within a distance cutoff.
+ *
+ * Contains pair indices, distances, and squared distances for every
+ * neighbor pair found. This object is produced by [`LinkedCell`]
+ * and consumed by analysis classes like [`RDF`] and [`Cluster`].
+ *
+ * # Properties
+ *
+ * | Property | Type | Description |
+ * |----------|------|-------------|
+ * | `numPairs` | `number` | Total number of neighbor pairs |
+ * | `numPoints` | `number` | Number of reference points |
+ * | `numQueryPoints` | `number` | Number of query points |
+ * | `isSelfQuery` | `boolean` | Whether this is a self-query result |
+ *
+ * # Example (JavaScript)
+ *
+ * ```js
+ * const nlist = lc.build(frame);
+ * console.log(nlist.numPairs);
+ *
+ * const i = nlist.queryPointIndices(); // Uint32Array
+ * const j = nlist.pointIndices();      // Uint32Array
+ * const d = nlist.distances();         // Float32Array (in A)
+ * ```
+ */
+export class NeighborList {
+    private constructor();
+    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.
+     */
+    distSq(): Float32Array;
+    /**
+     * Pairwise distances in angstrom (A), as a `Float32Array`.
+     *
+     * `distances()[k]` is the distance between query point
+     * `queryPointIndices()[k]` and reference point `pointIndices()[k]`.
+     */
+    distances(): Float32Array;
+    /**
+     * Reference point indices (`j`) for each pair, as a `Uint32Array`.
+     */
+    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]`.
+     */
+    queryPointIndices(): Uint32Array;
+    /**
+     * Whether this result came from a self-query (`build()`).
+     *
+     * In self-queries, only unique pairs `(i < j)` are reported.
+     */
+    readonly isSelfQuery: boolean;
+    /**
+     * Total number of neighbor pairs found.
+     */
+    readonly numPairs: number;
+    /**
+     * Number of reference (target) points in the search.
+     */
+    readonly numPoints: number;
+    /**
+     * Number of query points in the search.
+     *
+     * For self-queries, this equals `numPoints`.
+     */
+    readonly numQueryPoints: number;
+}
+
+/**
+ * Protein Data Bank (PDB) file reader.
+ *
+ * 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).
+ *
+ * # Example (JavaScript)
+ *
+ * ```js
+ * const reader = new PDBReader(pdbContent);
+ * const frame = reader.read(0);
+ * const atoms = frame.getBlock("atoms");
+ * const names = atoms.copyColStr("name"); // ["CA", "CB", ...]
+ * const x = atoms.copyColF32("x");
+ * ```
+ */
+export class PDBReader {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Check whether the file contains no valid frames.
+     *
+     * # Errors
+     *
+     * Throws a `JsValue` string on parse errors.
+     */
+    isEmpty(): boolean;
+    /**
+     * Return the number of frames (always 0 or 1 for PDB files).
+     *
+     * # Errors
+     *
+     * Throws a `JsValue` string on parse errors.
+     */
+    len(): number;
+    /**
+     * Create a new PDB reader from a string containing the file content.
+     *
+     * # Arguments
+     *
+     * * `content` - The full text content of a PDB file
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const reader = new PDBReader(pdbString);
+     * ```
+     */
+    constructor(content: string);
+    /**
+     * Read the frame at the given step index.
+     *
+     * PDB files contain a single structure, so only `step = 0` is
+     * valid. Passing any other step returns `undefined`.
+     *
+     * # Arguments
+     *
+     * * `step` - Frame index (must be `0` for PDB files)
+     *
+     * # Returns
+     *
+     * A [`Frame`] if `step == 0` and the file is valid, or `undefined`.
+     *
+     * # Errors
+     *
+     * Throws a `JsValue` string on parse errors.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const frame = reader.read(0);
+     * ```
+     */
+    read(step: number): Frame | undefined;
+}
+
+/**
+ * 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).
+ *
+ * # 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
+ * density, and `V_shell(r)` is the shell volume for that bin.
+ *
+ * # Example (JavaScript)
+ *
+ * ```js
+ * const lc = new LinkedCell(5.0);
+ * const nlist = lc.build(frame);
+ *
+ * const rdf = new RDF(100, 5.0);
+ * const result = rdf.compute(frame, nlist);
+ *
+ * const r  = result.binCenters();  // Float32Array, bin centers in A
+ * const gr = result.rdf();         // Float32Array, g(r) values
+ * ```
+ */
+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.
+     *
+     * # Arguments
+     *
+     * * `frame` - Frame with a `simbox` set (for volume normalization)
+     * * `neighbors` - Pre-built [`NeighborList`] from [`LinkedCell`]
+     *
+     * # Returns
+     *
+     * An [`RDFResult`] containing bin centers, g(r) values, and raw
+     * pair counts.
+     *
+     * # Errors
+     *
+     * Throws if the frame cannot be cloned or the computation fails.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const result = rdf.compute(frame, nlist);
+     * const gr = result.rdf(); // Float32Array
+     * ```
+     */
+    compute(frame: Frame, neighbors: NeighborList): RDFResult;
+    /**
+     * Create a new RDF analysis with specified binning.
+     *
+     * # 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.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const rdf = new RDF(100, 5.0); // 100 bins up to 5 A
+     * ```
+     */
+    constructor(n_bins: number, r_max: number);
+}
+
+/**
+ * Result of a radial distribution function computation.
+ *
+ * Contains the binned g(r) values, bin geometry, raw pair counts,
+ * and normalization metadata.
+ *
+ * # Example (JavaScript)
+ *
+ * ```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
+ * console.log("Volume:", result.volume, "A^3");
+ * console.log("N_ref:", result.numPoints);
+ * ```
+ */
+export class RDFResult {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
     /**
-     * Create a new box from a 3x3 matrix and origin.
+     * Bin center positions as `Float32Array` in angstrom (A).
      *
-     * # Arguments
-     * * `h` - 3x3 matrix as Float32Array with 9 elements (row-major: [h00, h01, h02, h10, ...])
-     * * `origin` - 3D origin vector as Float32Array with 3 elements [x, y, z]
-     * * `pbc_x`, `pbc_y`, `pbc_z` - Periodic boundary conditions for each axis
-     */
-    constructor(h: Float32Array, origin: Float32Array, pbc_x: boolean, pbc_y: boolean, pbc_z: boolean);
-    /**
-     * Get the box origin as F32View [x, y, z].
+     * Length equals `n_bins` (the value passed to the `RDF` constructor).
      */
-    origin(): F32View;
+    binCenters(): Float32Array;
     /**
-     * Create an orthorhombic box (rectangular box with axis-aligned edges).
+     * Bin edge positions as `Float32Array` in angstrom (A).
      *
-     * # Arguments
-     * * `lengths` - Box dimensions as Float32Array with 3 elements [lx, ly, lz]
-     * * `origin` - 3D origin vector as Float32Array with 3 elements
-     * * `pbc_x`, `pbc_y`, `pbc_z` - Periodic boundary conditions for each axis
-     */
-    static ortho(lengths: Float32Array, origin: Float32Array, pbc_x: boolean, pbc_y: boolean, pbc_z: boolean): Box;
-    /**
-     * Get the box tilt factors as F32View [xy, xz, yz].
+     * Length is `n_bins + 1` (one more than bin centers).
      */
-    tilts(): F32View;
+    binEdges(): Float32Array;
     /**
-     * Convert fractional coordinates to Cartesian coordinates.
-     *
-     * # Arguments
-     * * `coords` - F32View with Nx3 coordinates
-     *
-     * # Returns
-     * F32View with Nx3 Cartesian coordinates
+     * Raw (un-normalized) pair counts per bin as `Float32Array`.
      */
-    to_cart(coords: F32View): F32View;
+    pairCounts(): Float32Array;
     /**
-     * Convert Cartesian coordinates to fractional coordinates.
-     *
-     * # Arguments
-     * * `coords` - F32View with Nx3 coordinates
+     * Normalized g(r) values as `Float32Array` (dimensionless).
      *
-     * # Returns
-     * F32View with Nx3 fractional coordinates
+     * A uniform ideal gas has g(r) = 1.0 everywhere. Peaks indicate
+     * preferred interatomic distances (coordination shells).
      */
-    to_frac(coords: F32View): F32View;
+    rdf(): Float32Array;
     /**
-     * Get the volume of the box.
+     * Number of reference points used in the normalization.
      */
-    volume(): number;
+    readonly numPoints: number;
     /**
-     * Wrap coordinates into the primary simulation box.
-     *
-     * # Arguments
-     * * `coords` - F32View with Nx3 coordinates
-     *
-     * # Returns
-     * F32View with Nx3 wrapped coordinates
+     * Simulation box volume used in the normalization, in A^3.
      */
-    wrap(coords: F32View): F32View;
+    readonly volume: number;
 }
 
 /**
- * Zero-copy view over f32 array data shared between JavaScript and Rust.
- *
- * `F32View` provides a safe wrapper around f32 arrays that can be accessed from both
- * JavaScript and Rust without copying data. The data lives in WASM linear memory,
- * and JavaScript can create typed array views over this memory using `ptr()` and `len()`.
- *
- * # Memory Model
+ * Reader for Zarr V3 simulation archives.
  *
- * - Data is stored in `Vec<f32>` in WASM linear memory (Rust heap)
- * - JavaScript creates `Float32Array` views using `ptr()` and `len()`
- * - No copying occurs when JavaScript reads/writes via these views
- * - **Important**: Pointers are only valid until WASM memory grows
+ * 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.
  *
- * # Safety Considerations
- *
- * - Views should be short-lived (don't store across async boundaries)
- * - JavaScript must not modify the underlying array while Rust holds a reference
- * - WASM memory can grow/relocate, invalidating pointers
- *
- * # Example
- *
- * ```javascript
- * // Create a view for 1000 atoms with 3D coordinates
- * const view = new F32View([1000, 3]);
- *
- * // Access the data from JavaScript without copying
- * const mem = new Float32Array(wasmMemory.buffer, view.ptr(), view.len());
- * mem.set([1.0, 2.0, 3.0, ...]); // Write data
+ * # Example (JavaScript)
  *
- * // Pass to Rust for zero-copy processing
- * const wrapped = box.wrap(view);
+ * ```js
+ * const files = new Map();
+ * files.set("zarr.json", new Uint8Array([...]));
+ * files.set("system/.zarray", new Uint8Array([...]));
+ * // ... etc.
  *
- * // Read results without copying
- * const result = new Float32Array(wasmMemory.buffer, wrapped.ptr(), wrapped.len());
+ * const reader = new SimulationReader(files);
+ * const frame = reader.readFrame(0);
  * ```
  */
-export class F32View {
+export class SimulationReader {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Get the total number of elements in the view.
+     * Return the number of atoms in the system topology.
      *
-     * Returns the product of all shape dimensions.
+     * # Example (JavaScript)
+     *
+     * ```js
+     * console.log(reader.countAtoms()); // e.g., 256
+     * ```
      */
-    len(): number;
+    countAtoms(): number;
     /**
-     * Create a new F32View with the given shape.
+     * Return the number of trajectory frames in the archive.
      *
-     * Allocates a buffer in WASM linear memory with size = product of shape dimensions.
+     * Returns `0` if no trajectory data is present.
      *
-     * # Arguments
+     * # Errors
      *
-     * * `shape` - Dimensions of the array (e.g., `[1000, 3]` for Nx3 coordinates)
+     * Throws a `JsValue` string on I/O errors.
      *
-     * # Example
+     * # Example (JavaScript)
      *
-     * ```javascript
-     * const view = new F32View([100, 3]); // 100 atoms, 3D coordinates
-     * console.log(view.len()); // 300
+     * ```js
+     * console.log(reader.countFrames()); // e.g., 1000
      * ```
      */
-    constructor(shape: Uint32Array);
+    countFrames(): number;
     /**
-     * Get a pointer to the underlying data for zero-copy access from JavaScript.
+     * 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 raw pointer to the first element of the data buffer.
+     * A new `SimulationReader` ready to read frames.
      *
-     * # Safety
+     * # Errors
      *
-     * The pointer is only valid until the next WASM memory allocation.
-     * JavaScript should create typed array views immediately and not store the pointer.
+     * Throws a `JsValue` string if the archive cannot be opened
+     * (e.g., missing required metadata files).
      *
-     * # Example
+     * # Example (JavaScript)
      *
-     * ```javascript
-     * const view = new F32View([10, 3]);
-     * const ptr = view.ptr();
-     * const arr = new Float32Array(wasmMemory.buffer, ptr, view.len());
+     * ```js
+     * const reader = new SimulationReader(filesMap);
      * ```
      */
-    ptr(): number;
-    /**
-     * Get the shape of the array (cloned for JS boundary).
-     */
-    shape(): Uint32Array;
+    constructor(files: Map<any, any>);
     /**
-     * Compute the sum of all elements (for testing).
+     * Read a trajectory frame at the given time index.
      *
-     * # Returns
+     * The returned [`Frame`] merges the static system topology
+     * (atoms, bonds) with the per-frame trajectory data (positions,
+     * velocities, etc.) at time step `t`.
      *
-     * Sum of all elements in the view.
-     */
-    sum(): number;
-    /**
-     * Export the view data as a JavaScript Float32Array.
+     * # Arguments
      *
-     * Creates a new JavaScript array and copies the data.
-     * Use this for compatibility or when you need an owned JavaScript array.
+     * * `t` - Zero-based time step index
      *
      * # Returns
      *
-     * A new Float32Array containing a copy of the data.
+     * 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
+     * # Example (JavaScript)
      *
-     * ```javascript
-     * const view = new F32View([2, 3]);
-     * // ... populate view ...
-     * const arr = view.to_js_array(); // Copies data
+     * ```js
+     * const frame = reader.readFrame(0);
+     * if (frame) {
+     *   const x = frame.getBlock("atoms").copyColF32("x");
+     * }
      * ```
      */
-    to_js_array(): Float32Array;
+    readFrame(t: number): Frame | undefined;
+}
+
+/**
+ * Intermediate representation of a parsed SMILES string.
+ *
+ * Holds the molecular graph(s) parsed from a SMILES string. A single
+ * SMILES string can encode multiple disconnected molecules separated
+ * by `.` (e.g., `"[Na+].[Cl-]"`).
+ *
+ * Call [`toFrame()`](WasmSmilesIR::to_frame) to convert to a [`Frame`]
+ * with `"atoms"` and `"bonds"` blocks.
+ *
+ * # Example (JavaScript)
+ *
+ * ```js
+ * const ir = parseSMILES("CCO");
+ * console.log(ir.nComponents); // 1
+ *
+ * const frame = ir.toFrame();
+ * const atoms = frame.getBlock("atoms");
+ * console.log(atoms.copyColStr("symbol")); // ["C", "C", "O", "H", ...]
+ * ```
+ */
+export class SmilesIR {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
     /**
-     * Write data from a JavaScript Float32Array into this view.
+     * Convert the intermediate representation to a [`Frame`].
      *
-     * Copies data from the JavaScript array into WASM memory once.
-     * The array length must match the view's total size.
+     * The resulting frame contains:
      *
-     * # Arguments
+     * - `"atoms"` block: `symbol` (string), and implicit hydrogens
+     *   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,
+     *   2.0 = double, 3.0 = triple).
      *
-     * * `arr` - JavaScript Float32Array to copy from
+     * # Returns
+     *
+     * A new [`Frame`] with atoms and bonds.
      *
      * # Errors
      *
-     * Returns an error if the array length doesn't match the view size.
+     * Throws a `JsValue` string if the conversion fails (e.g.,
+     * invalid valence).
      *
-     * # Example
+     * # Example (JavaScript)
      *
-     * ```javascript
-     * const view = new F32View([2, 3]);
-     * const data = new Float32Array([1, 2, 3, 4, 5, 6]);
-     * view.write_from(data);
+     * ```js
+     * const frame = ir.toFrame();
+     * const bonds = frame.getBlock("bonds");
+     * const order = bonds.copyColF32("order");
      * ```
      */
-    write_from(arr: Float32Array): void;
+    toFrame(): Frame;
+    /**
+     * Return the number of disconnected components in the SMILES.
+     *
+     * Components are separated by `.` in the SMILES string. For
+     * example, `"[Na+].[Cl-]"` has 2 components.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const ir = parseSMILES("[Na+].[Cl-]");
+     * console.log(ir.nComponents); // 2
+     * ```
+     */
+    readonly nComponents: number;
 }
 
 /**
- * A frame that contains blocks of data.
+ * Owned f32 array with ndarray-compatible shape metadata.
+ *
+ * Stores a flat `Vec<f32>` 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.
+ *
+ * # Example (JavaScript)
+ *
+ * ```js
+ * // Create a 2x3 zero array
+ * const arr = new WasmArray([2, 3]);
+ * arr.writeFrom(new Float32Array([1,2,3, 4,5,6]));
+ *
+ * // Or from existing data
+ * const arr2 = WasmArray.from(new Float32Array([1,2,3]), [1, 3]);
+ *
+ * // Get data back
+ * const copy = arr.toCopy();       // safe owned copy
+ * const view = arr.toTypedArray(); // zero-copy (invalidated on alloc)
+ * ```
  */
-export class Frame {
+export class WasmArray {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Clears all blocks from the frame.
+     * Return the data type string. Always `"float"` for `WasmArray`.
      */
-    clear(): void;
+    dtype(): string;
     /**
-     * Creates a new block in this frame.
+     * Create a `WasmArray` from an existing JS `Float32Array`.
+     *
+     * # Arguments
+     *
+     * * `data` - Source `Float32Array`
+     * * `shape` - Optional shape. If omitted, defaults to `[data.length]` (1D).
+     *
+     * # Returns
+     *
+     * A new `WasmArray` owning a copy of the data.
+     *
+     * # Errors
+     *
+     * Throws if `shape` product does not equal `data.length`.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const arr = WasmArray.from(new Float32Array([1,2,3,4,5,6]), [2, 3]);
+     * console.log(arr.shape()); // [2, 3]
+     * ```
      */
-    createBlock(key: string): Block;
+    static from(data: Float32Array, shape?: Uint32Array | null): WasmArray;
     /**
-     * Drops this frame from the store.
+     * Check whether the array contains no elements.
      */
-    drop(): void;
+    is_empty(): boolean;
     /**
-     * Gets an existing block by key.
+     * Return the total number of elements (product of all shape dimensions).
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const arr = new WasmArray([10, 3]);
+     * console.log(arr.len()); // 30
+     * ```
      */
-    getBlock(key: string): Block | undefined;
+    len(): number;
     /**
-     * Inserts a block into the frame (takes ownership).
+     * Create a zero-initialized array with the given shape.
+     *
+     * The total number of elements is the product of all dimensions.
+     *
+     * # Arguments
+     *
+     * * `shape` - Array of dimension sizes (e.g., `[10, 3]` for 10 rows x 3 columns)
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const coords = new WasmArray([100, 3]); // 100 atoms, 3D
+     * console.log(coords.len()); // 300
+     * ```
      */
-    insertBlock(key: string, block: Block): void;
+    constructor(shape: Uint32Array);
     /**
-     * Creates a new Frame.
+     * Return a raw pointer to the underlying data buffer.
+     *
+     * This is intended for advanced interop with other WASM modules
+     * that need direct memory access. The pointer is only valid as
+     * long as this `WasmArray` is alive and no WASM memory growth
+     * has occurred.
      */
-    constructor();
+    ptr(): number;
     /**
-     * Removes a block from the frame.
+     * Return a copy of the shape metadata as a JS array.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const s = arr.shape(); // e.g., [10, 3]
+     * ```
      */
-    removeBlock(key: string): void;
+    shape(): Uint32Array;
     /**
-     * Renames a block in the frame.
+     * Compute the sum of all elements.
+     *
+     * Primarily useful for quick sanity checks and testing.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const arr = WasmArray.from(new Float32Array([1, 2, 3]));
+     * console.log(arr.sum()); // 6.0
+     * ```
      */
-    renameBlock(old_key: string, new_key: string): boolean;
+    sum(): number;
     /**
-     * Renames a column in the specified block.
+     * Create an owned JS `Float32Array` copy of the data.
+     *
+     * The returned array is an independent copy that is safe to store
+     * and use regardless of subsequent WASM memory operations.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const copy = arr.toCopy(); // safe to keep indefinitely
+     * ```
      */
-    renameColumn(block_key: string, old_col_key: string, new_col_key: string): boolean;
+    toCopy(): Float32Array;
     /**
-     * Gets the simulation box (if any).
+     * Zero-copy `Float32Array` 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)
+     * if you need to keep the data.
+     *
+     * # Safety (internal)
+     *
+     * Uses `Float32Array::view` 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.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const view = arr.toTypedArray(); // use immediately
+     * // Do NOT allocate between view creation and use
+     * ```
      */
-    get simbox(): Box | undefined;
+    toTypedArray(): Float32Array;
     /**
-     * Sets the simulation box.
+     * Overwrite the array contents from a JS `Float32Array`.
+     *
+     * 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
+     *
+     * # Errors
+     *
+     * Throws if `arr.length` does not match this array's element count.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const wa = new WasmArray([3]);
+     * wa.writeFrom(new Float32Array([1.0, 2.0, 3.0]));
+     * ```
      */
-    set simbox(value: Box | null | undefined);
+    write_from(arr: Float32Array): void;
 }
 
 /**
- * LAMMPS data file reader for WASM
+ * XYZ / Extended XYZ file reader.
+ *
+ * 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.
  *
  * # Example (JavaScript)
+ *
  * ```js
- * const reader = new LammpsReader(fileContent);
- * const frame = reader.read(0);
+ * const content = await file.text(); // read file in browser
+ * const reader = new XYZReader(content);
+ * console.log(reader.len()); // number of frames
+ *
+ * const frame = reader.read(0); // first frame
+ * const atoms = frame.getBlock("atoms");
+ * const x = atoms.copyColF32("x");
  * ```
  */
-export class LammpsReader {
+export class XYZReader {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Returns the number of frames (always 1 for LAMMPS).
-     * @returns {number}
+     * Check whether the file contains no frames.
+     *
+     * # Errors
+     *
+     * Throws a `JsValue` string if the file cannot be scanned.
      */
-    len(): number;
-    constructor(content: string);
+    isEmpty(): boolean;
     /**
-     * Reads a frame at the given step.
-     * @param {number} step - Frame index (LAMMPS only supports single frame, so only step=0 is valid)
-     * @returns {Frame | undefined}
+     * Return the number of frames in the file.
+     *
+     * # Returns
+     *
+     * The total frame count.
+     *
+     * # Errors
+     *
+     * Throws a `JsValue` string if the file cannot be scanned.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * console.log(reader.len()); // e.g., 100
+     * ```
      */
-    read(step: number): Frame | undefined;
-}
-
-/**
- * PDB file reader for WASM
- *
- * # Example (JavaScript)
- * ```js
- * const reader = new PdbReader(fileContent);
- * const frame = reader.read(0);
- * ```
- */
-export class PdbReader {
-    free(): void;
-    [Symbol.dispose](): void;
+    len(): number;
     /**
-     * Returns the number of frames (always 1 for PDB).
-     * @returns {number}
+     * Create a new XYZ reader from a string containing the file content.
+     *
+     * # Arguments
+     *
+     * * `content` - The full text content of an XYZ or Extended XYZ file
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const reader = new XYZReader(fileContent);
+     * ```
      */
-    len(): number;
     constructor(content: string);
     /**
-     * Reads a frame at the given step.
-     * @param {number} step - Frame index (PDB only supports single frame, so only step=0 is valid)
-     * @returns {Frame | undefined}
+     * Read a frame at the given step index.
+     *
+     * # Arguments
+     *
+     * * `step` - Zero-based frame index
+     *
+     * # Returns
+     *
+     * A [`Frame`] if the step exists, or `undefined` if `step` is
+     * out of range.
+     *
+     * # Errors
+     *
+     * Throws a `JsValue` string on parse errors.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const frame = reader.read(0);
+     * if (frame) {
+     *   const atoms = frame.getBlock("atoms");
+     * }
+     * ```
      */
     read(step: number): Frame | undefined;
 }
 
 /**
- * XYZ/ExtXYZ file reader for WASM
+ * Generate 3D coordinates for a molecular [`Frame`].
+ *
+ * The input frame must have an `"atoms"` block with a `"symbol"`
+ * string column (element symbols like `"C"`, `"N"`, `"O"`). A
+ * `"bonds"` block with `i`, `j` (u32) and `order` (f32) 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.
+ *
+ * # Arguments
+ *
+ * * `frame` - Input molecular frame with atoms and bonds (from
+ *   [`parseSMILES`](crate::parse_smiles) or file readers)
+ * * `speed` - Quality/speed preset:
+ *   - `"fast"` -- minimal refinement, suitable for visualization
+ *   - `"medium"` (default) -- balanced quality/speed
+ *   - `"better"` -- thorough conformer search, best geometry
+ * * `seed` - Optional RNG seed (`u32`) for reproducibility. If
+ *   omitted, a random seed is used.
+ *
+ * # Returns
+ *
+ * A new [`Frame`] with 3D coordinates. The original frame is
+ * not modified.
+ *
+ * # Errors
+ *
+ * Throws a `JsValue` string if:
+ * - The frame has no `"atoms"` block or is missing required columns
+ * - The molecular graph has invalid valences or topology
+ * - The 3D embedding fails to converge
  *
  * # Example (JavaScript)
+ *
  * ```js
- * const reader = new XyzReader(fileContent);
- * const frame = reader.read(0);
+ * const ir = parseSMILES("c1ccccc1"); // benzene
+ * const frame2d = ir.toFrame();
+ * 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");
  * ```
  */
-export class XyzReader {
-    free(): void;
-    [Symbol.dispose](): void;
-    /**
-     * Returns the number of frames in the file.
-     * @returns {number}
-     */
-    len(): number;
-    constructor(content: string);
-    /**
-     * Reads a frame at the given step.
-     * @param {number} step - Frame index
-     * @returns {Frame | undefined}
-     */
-    read(step: number): Frame | undefined;
-}
+export function generate3D(frame: Frame, speed?: string | null, seed?: number | null): Frame;
 
 /**
- * Writes a frame to a string in the specified format.
+ * Parse a SMILES notation string into an intermediate representation.
+ *
+ * Supports standard SMILES features including ring closures,
+ * branching, stereochemistry markers, and aromatic atoms.
+ *
+ * # Arguments
+ *
+ * * `smiles` - SMILES notation string (e.g., `"CCO"` for ethanol,
+ *   `"c1ccccc1"` for benzene, `"[Na+].[Cl-]"` for NaCl)
+ *
+ * # Returns
+ *
+ * A [`SmilesIR`](WasmSmilesIR) object. Call `.toFrame()` to convert
+ * to a [`Frame`] with atoms and bonds blocks.
+ *
+ * # Errors
+ *
+ * Throws a `JsValue` string if the SMILES string is malformed
+ * (e.g., unmatched ring closure digits, invalid atom symbols).
  *
  * # Example (JavaScript)
+ *
  * ```js
- * const output = writeFrame(frame, "xyz");
- * console.log(output); // XYZ format string
+ * const ir = parseSMILES("CCO");
+ * const frame = ir.toFrame();
+ * const mol3d = generate3D(frame, "fast");
  * ```
- *
- * @param {Frame} frame - Frame to write
- * @param {string} format - Output format ("xyz" or "pdb")
- * @returns {string} Formatted output
  */
-export function writeFrame(frame: Frame, format: string): string;
-
-export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+export function parseSMILES(smiles: string): SmilesIR;
 
-export interface InitOutput {
-    readonly memory: WebAssembly.Memory;
-    readonly __wbg_block_free: (a: number, b: number) => void;
-    readonly __wbg_frame_free: (a: number, b: number) => void;
-    readonly block_getColumnF32: (a: number, b: number, c: number) => [number, number, number];
-    readonly block_getColumnF32WithShape: (a: number, b: number, c: number) => [number, number, number];
-    readonly block_getColumnI64: (a: number, b: number, c: number) => [number, number, number];
-    readonly block_getColumnStrings: (a: number, b: number, c: number) => any;
-    readonly block_getColumnU32: (a: number, b: number, c: number) => [number, number, number];
-    readonly block_getColumnU8: (a: number, b: number, c: number) => any;
-    readonly block_keys: (a: number) => [number, number, number];
-    readonly block_len: (a: number) => [number, number, number];
-    readonly block_new: () => number;
-    readonly block_nrows: (a: number) => [number, number, number];
-    readonly block_renameColumn: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
-    readonly block_setColumnF32: (a: number, b: number, c: number, d: any, e: number) => [number, number];
-    readonly block_setColumnI64: (a: number, b: number, c: number, d: any, e: number) => [number, number];
-    readonly block_setColumnStrings: (a: number, b: number, c: number, d: any, e: number) => [number, number];
-    readonly block_setColumnU32: (a: number, b: number, c: number, d: any, e: number) => [number, number];
-    readonly block_setColumnU8: (a: number, b: number, c: number, d: any, e: number) => [number, number];
-    readonly frame_clear: (a: number) => [number, number];
-    readonly frame_createBlock: (a: number, b: number, c: number) => [number, number, number];
-    readonly frame_drop: (a: number) => [number, number];
-    readonly frame_getBlock: (a: number, b: number, c: number) => number;
-    readonly frame_insertBlock: (a: number, b: number, c: number, d: number) => [number, number];
-    readonly frame_new: () => number;
-    readonly frame_removeBlock: (a: number, b: number, c: number) => [number, number];
-    readonly frame_renameBlock: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
-    readonly frame_renameColumn: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number, number];
-    readonly frame_set_simbox: (a: number, b: number) => void;
-    readonly frame_simbox: (a: number) => number;
-    readonly __wbg_f32view_free: (a: number, b: number) => void;
-    readonly f32view_len: (a: number) => number;
-    readonly f32view_new: (a: number, b: number) => number;
-    readonly f32view_ptr: (a: number) => number;
-    readonly f32view_shape: (a: number) => [number, number];
-    readonly f32view_sum: (a: number) => number;
-    readonly f32view_to_js_array: (a: number) => any;
-    readonly f32view_write_from: (a: number, b: any) => [number, number];
-    readonly __wbg_lammpsreader_free: (a: number, b: number) => void;
-    readonly __wbg_pdbreader_free: (a: number, b: number) => void;
-    readonly __wbg_xyzreader_free: (a: number, b: number) => void;
-    readonly lammpsreader_len: (a: number) => [number, number, number];
-    readonly lammpsreader_new: (a: number, b: number) => number;
-    readonly lammpsreader_read: (a: number, b: number) => [number, number, number];
-    readonly pdbreader_len: (a: number) => [number, number, number];
-    readonly pdbreader_new: (a: number, b: number) => number;
-    readonly pdbreader_read: (a: number, b: number) => [number, number, number];
-    readonly xyzreader_len: (a: number) => [number, number, number];
-    readonly xyzreader_new: (a: number, b: number) => number;
-    readonly xyzreader_read: (a: number, b: number) => [number, number, number];
-    readonly __wbg_box_free: (a: number, b: number) => void;
-    readonly box_cube: (a: number, b: any, c: number, d: number, e: number) => [number, number, number];
-    readonly box_delta: (a: number, b: number, c: number, d: number) => [number, number, number];
-    readonly box_get_corners: (a: number) => number;
-    readonly box_lengths: (a: number) => number;
-    readonly box_new: (a: any, b: any, c: number, d: number, e: number) => [number, number, number];
-    readonly box_origin: (a: number) => number;
-    readonly box_ortho: (a: any, b: any, c: number, d: number, e: number) => [number, number, number];
-    readonly box_tilts: (a: number) => number;
-    readonly box_to_cart: (a: number, b: number) => [number, number, number];
-    readonly box_to_frac: (a: number, b: number) => [number, number, number];
-    readonly box_volume: (a: number) => number;
-    readonly box_wrap: (a: number, b: number) => [number, number, number];
-    readonly writeFrame: (a: number, b: number, c: number) => [number, number, number, number];
-    readonly __wbindgen_malloc: (a: number, b: number) => number;
-    readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
-    readonly __wbindgen_exn_store: (a: number) => void;
-    readonly __externref_table_alloc: () => number;
-    readonly __wbindgen_externrefs: WebAssembly.Table;
-    readonly __externref_table_dealloc: (a: number) => void;
-    readonly __wbindgen_free: (a: number, b: number, c: number) => void;
-    readonly __wbindgen_start: () => void;
-}
-
-export type SyncInitInput = BufferSource | WebAssembly.Module;
+/**
+ * WASM module entry point. Installs the panic hook so that Rust panics
+ * are forwarded to the browser console as readable stack traces.
+ */
+export function start(): void;
 
 /**
- * Instantiates the given `module`, which can either be bytes or
- * a precompiled `WebAssembly.Module`.
+ * Return a handle to the WASM linear memory.
  *
- * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ * Useful for advanced interop where JS code needs direct access to the
+ * WASM memory buffer (e.g., for zero-copy typed-array views).
  *
- * @returns {InitOutput}
+ * # Example (JavaScript)
+ *
+ * ```js
+ * const mem = wasmMemory();
+ * const buf = new Float32Array(mem.buffer, ptr, len);
+ * ```
  */
-export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+export function wasmMemory(): WebAssembly.Memory;
 
 /**
- * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
- * for everything else, calls `WebAssembly.instantiate` directly.
+ * Serialize a [`Frame`] to a string in the specified format.
+ *
+ * The frame must have an `"atoms"` block with at least an element/name
+ * string column and `x`, `y`, `z` float columns (coordinates in
+ * angstrom).
+ *
+ * # Arguments
+ *
+ * * `frame` - The [`Frame`] to write
+ * * `format` - Output format string: `"xyz"` or `"pdb"`
+ *   (case-insensitive)
+ *
+ * # Returns
  *
- * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ * The formatted file content as a string.
  *
- * @returns {Promise<InitOutput>}
+ * # Errors
+ *
+ * Throws a `JsValue` string if:
+ * - The format is not recognized
+ * - The frame is missing required columns
+ * - The writer encounters an error
+ *
+ * # Example (JavaScript)
+ *
+ * ```js
+ * const xyzStr = writeFrame(frame, "xyz");
+ * console.log(xyzStr);
+ * // 2
+ * //
+ * // H  0.000000  0.000000  0.000000
+ * // O  1.000000  0.000000  0.500000
+ *
+ * const pdbStr = writeFrame(frame, "pdb");
+ * // download or display the PDB string
+ * ```
  */
-export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;
+export function writeFrame(frame: Frame, format: string): string;