@molcrafts/molrs 0.0.14 → 0.0.15

package/molrs.d.ts

@@ -370,6 +370,58 @@ export class Block {
      * ```
      */
     setColU32(key: string, data: Uint32Array): void;
+    /**
+     * Declare this block as N-dimensional with the given `shape`.
+     *
+     * `shape.iter().product()` must equal the block's current `nrows`
+     * when the block has columns. Pass an empty array to clear the
+     * shape and revert to plain row-table semantics.
+     *
+     * This does **not** reshape column storage — columns remain
+     * row-major 1D buffers of length `product(shape)`. `shape` is
+     * structural metadata; consumers (e.g. the volumetric renderer in
+     * MolVis) use it to unflatten the row index back into N-D
+     * coordinates.
+     *
+     * # Errors
+     *
+     * Throws if `shape.iter().product()` does not match the block's
+     * existing `nrows`, or if the block handle has been invalidated.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const grid = frame.createBlock("grid");
+     * grid.setColF("electron_density", values);  // values.length === 32*32*32
+     * grid.setShape(new Uint32Array([32, 32, 32]));
+     * ```
+     */
+    setShape(shape: Uint32Array): void;
+    /**
+     * Return the structural shape of the block as a `Uint32Array`.
+     *
+     * - Plain row tables (atoms, bonds): `[nrows]` — single-axis.
+     * - Volumetric grids: `[Nx, Ny, Nz]` — explicitly declared via
+     *   [`setShape`](Self::set_shape).
+     * - Empty blocks: `[]`.
+     *
+     * `block.shape()` is uniform across all block kinds — the rank of
+     * the returned array is what distinguishes a plain table from a
+     * volumetric grid. The product of the shape always equals
+     * `block.nrows()`.
+     *
+     * # Errors
+     *
+     * Throws if the block handle has been invalidated.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const atomsShape = atoms.shape();   // Uint32Array([1000])
+     * const gridShape  = grid.shape();    // Uint32Array([32, 32, 32])
+     * ```
+     */
+    shape(): Uint32Array;
     /**
      * Zero-copy JS float typed-array view into WASM linear memory.
      *
@@ -571,21 +623,25 @@ export class Box {
      */
     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.
+     * Return the box's 3×3 cell matrix `h` as a `WasmArray` with shape
+     * `[9]`, **column-major** (column j of `h` is the j-th lattice
+     * vector). Suitable for direct consumption by `marchingCubes` and
+     * other code that expects the cell as a flat 3×3 column-major
+     * `Float64Array`.
      *
      * # Returns
      *
-     * `WasmArray` containing `[lx, ly, lz]` in angstrom (A).
+     * `WasmArray` of length 9: `[h00, h10, h20, h01, h11, h21, h02, h12, h22]`,
+     * in angstrom (A).
      *
      * # Example (JavaScript)
      *
      * ```js
-     * const L = box.lengths().toCopy(); // Float32Array or Float64Array [10, 10, 10]
+     * const cell = box.hMatrix().toCopy(); // Float64Array, length 9
+     * // col0 = a-vector = cell[0..3]
      * ```
      */
+    hMatrix(): WasmArray;
     lengths(): WasmArray;
     /**
      * Create a new box from a 3x3 cell matrix and origin.
@@ -666,6 +722,36 @@ export class Box {
      * ```
      */
     static ortho(lengths: Float64Array, origin: Float64Array, pbc_x: boolean, pbc_y: boolean, pbc_z: boolean): Box;
+    /**
+     * 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 or Float64Array [10, 10, 10]
+     * ```
+     * Return the per-axis periodic boundary flags as a `Uint8Array`
+     * of length 3 (`[px, py, pz]`, 1 = periodic, 0 = open).
+     *
+     * Renderers that respect PBC (isosurface marching cubes,
+     * bond minimum-image, atom wrap-around) need this to decide
+     * whether to wrap coordinates across the cell.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const pbc = box.pbc(); // Uint8Array [1, 1, 1] for fully periodic
+     * const fullyPeriodic = pbc[0] === 1 && pbc[1] === 1 && pbc[2] === 1;
+     * ```
+     */
+    pbc(): Uint8Array;
     /**
      * Return the box tilt factors as a `WasmArray` with shape `[3]`.
      *
@@ -848,6 +934,130 @@ export class Box {
     wrapToBlock(coords: WasmArray, out_block: Block, out_key: string): void;
 }
 
+/**
+ * VASP CHGCAR / CHGDIF volumetric data reader.
+ *
+ * Reads VASP-format charge density files (extension-less canonical name
+ * `CHGCAR` or `CHGCAR_*`). Produces a [`Frame`] with:
+ * - `"atoms"` block: `element` (string), `x`/`y`/`z` (F, Cartesian Å).
+ * - `"grid"` block: structural shape `[nx, ny, nz]`, columns
+ *   `total` (always) and `diff` (when ISPIN=2).
+ * - `simbox`: triclinic POSCAR lattice in Å, fully periodic.
+ *
+ * CHGCAR is single-frame; only `step = 0` is valid.
+ *
+ * # Example (JavaScript)
+ *
+ * ```js
+ * const content = await file.text();
+ * const reader  = new CHGCARReader(content);
+ * const frame   = reader.read(0);
+ * const grid    = frame.getBlock("grid");
+ * const total   = grid.copyColF("total");
+ * ```
+ */
+export class CHGCARReader {
+    free(): void;
+    [Symbol.dispose](): void;
+    isEmpty(): boolean;
+    len(): number;
+    /**
+     * Create a new CHGCAR reader from the file's text content.
+     */
+    constructor(content: string);
+    /**
+     * Read the frame at `step`. CHGCAR is single-frame.
+     *
+     * # Errors
+     *
+     * Throws a `JsValue` string on parse errors.
+     */
+    read(step: number): Frame | undefined;
+}
+
+/**
+ * Crystallographic Information File (CIF / mmCIF) reader.
+ *
+ * Each `data_*` block in the file becomes one [`Frame`]. Most CIF files
+ * contain a single block (one structure), but multi-block files (e.g.
+ * polymorphs of the same compound) are also supported and are exposed
+ * as a multi-frame sequence. The unit cell parameters
+ * (`_cell_length_a`, `_b`, `_c`, `_cell_angle_alpha`, `_beta`,
+ * `_gamma`) are converted to a 3x3 h-matrix on the Rust side and
+ * surface on the JS side as `frame.simbox`.
+ *
+ * Produces a [`Frame`] with an `"atoms"` block containing
+ * `element` (string), `x`, `y`, `z` (F, angstrom in Cartesian
+ * coordinates) and (when present in the file) `label`, `occupancy`,
+ * `bfactor` columns.
+ *
+ * CIF parsing reads the entire file on each `read(step)` call --
+ * random access is therefore O(file_size), but typical CIF files are
+ * small (< 1 MB) and the molvis lazy trajectory caches frames at the
+ * JS level, so this is rarely a bottleneck.
+ *
+ * # Example (JavaScript)
+ *
+ * ```js
+ * const content = await file.text();
+ * const reader = new CIFReader(content);
+ * const frame  = reader.read(0);
+ * const atoms  = frame.getBlock("atoms");
+ * const box    = frame.simbox;        // populated from the unit cell
+ * ```
+ */
+export class CIFReader {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Check whether the file contains no valid blocks.
+     *
+     * # Errors
+     *
+     * Throws a `JsValue` string on parse errors.
+     */
+    isEmpty(): boolean;
+    /**
+     * Return the number of `data_*` blocks in the file.
+     *
+     * # Errors
+     *
+     * Throws a `JsValue` string on parse errors.
+     */
+    len(): number;
+    /**
+     * Create a new CIF reader from a string containing the file content.
+     *
+     * # Arguments
+     *
+     * * `content` - The full text content of a CIF file
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const reader = new CIFReader(cifString);
+     * ```
+     */
+    constructor(content: string);
+    /**
+     * Read the frame at the given block index.
+     *
+     * # Arguments
+     *
+     * * `step` - 0-based index of the `data_*` block to return
+     *
+     * # Returns
+     *
+     * A [`Frame`] for the requested block, or `undefined` when
+     * `step >= len()`.
+     *
+     * # Errors
+     *
+     * Throws a `JsValue` string on parse errors.
+     */
+    read(step: number): Frame | undefined;
+}
+
 /**
  * Mass-weighted cluster center calculator.
  */
@@ -1028,6 +1238,135 @@ export class ClusterResult {
     readonly numClusters: number;
 }
 
+/**
+ * Gaussian Cube file reader.
+ *
+ * Cube files describe a single voxel grid with embedded atom geometry.
+ * The reader produces a [`Frame`] with:
+ * - `"atoms"` block: `element` (string), `atomic_number` (i32),
+ *   `charge` (F), `x`/`y`/`z` (F, **always Å** — Bohr files are converted
+ *   on read).
+ * - `"grid"` block: structural shape `[nx, ny, nz]` and one f64 column
+ *   per scalar field — `density` for single-density files,
+ *   `mo_<idx>` for negative-natoms multi-orbital files.
+ * - `simbox`: voxel cell × dims in Å.
+ *
+ * Cube is inherently single-frame (only `step = 0` is valid).
+ *
+ * # Example (JavaScript)
+ *
+ * ```js
+ * const content = await file.text();
+ * const reader  = new CubeReader(content);
+ * const frame   = reader.read(0);
+ * const grid    = frame.getBlock("grid");   // shape [nx, ny, nz]
+ * const density = grid.copyColF("density"); // owned Float64Array
+ * ```
+ */
+export class CubeReader {
+    free(): void;
+    [Symbol.dispose](): void;
+    isEmpty(): boolean;
+    /**
+     * Return the number of frames (always 0 or 1).
+     */
+    len(): number;
+    /**
+     * Create a new Cube reader from the file's text content.
+     */
+    constructor(content: string);
+    /**
+     * Read the frame at `step`. Cube files are single-frame, so any
+     * `step != 0` returns `undefined`.
+     *
+     * # Errors
+     *
+     * Throws a `JsValue` string on parse errors.
+     */
+    read(step: number): Frame | undefined;
+}
+
+/**
+ * DCD trajectory file reader.
+ *
+ * DCD is a binary multi-frame trajectory format originally used by
+ * CHARMM and now widely produced by NAMD / OpenMM / GROMACS-via-VMD.
+ * This wrapper accepts the file as raw bytes (`Uint8Array`) since
+ * DCD is not text-encoded — passing a JS string would corrupt the
+ * fixed-width Fortran record markers.
+ *
+ * Each frame produces a [`Frame`] with an `"atoms"` block carrying
+ * `x`, `y`, `z` (F, angstrom). Box/cell information, when the DCD
+ * header declares it present, is attached as the frame's `simbox`.
+ *
+ * # Example (JavaScript)
+ *
+ * ```js
+ * const bytes = new Uint8Array(await blob.arrayBuffer());
+ * const reader = new DCDReader(bytes);
+ * console.log(reader.len()); // number of frames
+ *
+ * const frame = reader.read(0); // first frame
+ * const atoms = frame.getBlock("atoms");
+ * const x = atoms.copyColF("x");
+ * ```
+ */
+export class DCDReader {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Check whether the file contains no frames.
+     *
+     * # Errors
+     *
+     * Throws a `JsValue` string if the header cannot be parsed.
+     */
+    isEmpty(): boolean;
+    /**
+     * Return the number of frames in the DCD file.
+     *
+     * # Errors
+     *
+     * Throws a `JsValue` string if the header cannot be parsed.
+     */
+    len(): number;
+    /**
+     * Create a new DCD reader from the file's raw bytes.
+     *
+     * # Arguments
+     *
+     * * `bytes` - The full binary content of a DCD file. The reader
+     *   takes ownership of an internal copy, so the caller is free
+     *   to discard the buffer immediately after this returns.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const bytes = new Uint8Array(await file.arrayBuffer());
+     * const reader = new DCDReader(bytes);
+     * ```
+     */
+    constructor(bytes: Uint8Array);
+    /**
+     * 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 (truncated record,
+     * malformed header, byte-order mismatch).
+     */
+    read(step: number): Frame | undefined;
+}
+
 /**
  * Hierarchical data container mapping string keys to typed [`Block`]s.
  *
@@ -1055,6 +1394,21 @@ export class ClusterResult {
 export class Frame {
     free(): void;
     [Symbol.dispose](): void;
+    /**
+     * Return the names of all blocks attached to this frame.
+     *
+     * Iteration order matches the underlying `HashMap` and is therefore
+     * not stable across runs — callers that need a deterministic order
+     * must sort on the JS side. Returns an empty array if the frame
+     * has been dropped.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const names = frame.blockNames(); // e.g. ["atoms", "bonds"]
+     * ```
+     */
+    blockNames(): string[];
     /**
      * Remove all blocks from this frame (but keep the frame alive).
      *
@@ -1136,28 +1490,6 @@ export class Frame {
      * ```
      */
     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.
      *
@@ -1183,30 +1515,6 @@ export class Frame {
      * ```
      */
     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.
      *
@@ -1235,36 +1543,11 @@ export class Frame {
      */
     insertBlock(key: string, block: Block): void;
     /**
-     * Attach a grid to this frame under the given name.
+     * Return the names of all metadata keys on this frame.
      *
-     * 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.
+     * 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)
      *
@@ -1302,24 +1585,6 @@ 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`.
      *
@@ -1439,206 +1704,26 @@ export class Frame {
 }
 
 /**
- * A uniform spatial grid storing multiple named scalar arrays.
+ * One frame's location inside the source byte stream.
  *
- * 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());
- * ```
+ * `byteOffset` is the absolute byte position of the frame's first byte
+ * inside the source (round-tripped through `f64`; the spec caps source
+ * size at 1 TB which is well within `Number.MAX_SAFE_INTEGER`).
+ * `byteLen` is `u32` — per-frame size never exceeds the worker chunk
+ * size plus a small slack.
  */
-export class Grid {
+export class FrameIndexEntry {
+    private constructor();
     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]
-     * ```
+     * Size of this frame's encoded byte range, in bytes.
      */
-    pbc(): Uint8Array;
+    readonly byteLen: number;
     /**
-     * Total number of voxels: `nx * ny * nz`.
-     *
-     * # Example (JavaScript)
-     *
-     * ```js
-     * console.log(grid.total()); // 1000 for a 10×10×10 grid
-     * ```
+     * Absolute byte offset of this frame inside the source (in bytes).
      */
-    total(): number;
+    readonly byteOffset: number;
 }
 
 /**
@@ -2842,6 +2927,382 @@ export class WasmKMeans {
     constructor(k: number, max_iter: number, seed: number);
 }
 
+export class WasmLammpsDataStream {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Resize the reusable input buffer so it can hold at least
+     * `len` bytes, and return the WASM linear-memory pointer to
+     * its first byte.
+     *
+     * CALLER MUST RE-DERIVE THIS POINTER AFTER ANY OTHER WASM CALL —
+     * `wasm.memory.buffer` may have been detached by a `memory.grow`.
+     */
+    allocInputBuffer(len: number): number;
+    /**
+     * Number of blocks in the most recently parsed frame.
+     */
+    blockCount(): number;
+    /**
+     * Name of block `blockIdx`, or empty string if out of range.
+     */
+    blockName(block_idx: number): string;
+    /**
+     * Number of columns in block `blockIdx`.
+     */
+    columnCount(block_idx: number): number;
+    /**
+     * Column dtype string at `(blockIdx, colIdx)`. One of `"f64"`,
+     * `"u32"`, `"i32"`, `"string"` — or `"bool"` / `"u8"` if a
+     * future parser emits those (current streaming formats do not).
+     * Empty string if the index is out of range.
+     */
+    columnDtype(block_idx: number, col_idx: number): string;
+    /**
+     * Total flat element count of the column. For multi-dimensional
+     * columns (e.g. an Nx3 positions array) this is the product of
+     * all axes — i.e. the length of the slice the matching
+     * `columnPtr*` points at.
+     */
+    columnLen(block_idx: number, col_idx: number): number;
+    /**
+     * Column name at `(blockIdx, colIdx)`, or empty string if
+     * either index is out of range.
+     */
+    columnName(block_idx: number, col_idx: number): string;
+    /**
+     * Pointer to the contiguous `f64` slice backing this column,
+     * or 0 (null) if the column is missing or has the wrong
+     * dtype.
+     *
+     * **Lifetime**: valid only until the next non-trivial wasm
+     * call. See the module-level memory-grow contract.
+     */
+    columnPtrF64(block_idx: number, col_idx: number): number;
+    /**
+     * Pointer to the contiguous `i32` slice backing this column,
+     * or 0 (null) if the column is missing or has the wrong
+     * dtype.
+     *
+     * **Lifetime**: valid only until the next non-trivial wasm
+     * call. See the module-level memory-grow contract.
+     */
+    columnPtrI32(block_idx: number, col_idx: number): number;
+    /**
+     * Pointer to the contiguous `u32` slice backing this column,
+     * or 0 (null) if the column is missing or has the wrong
+     * dtype.
+     *
+     * **Lifetime**: valid only until the next non-trivial wasm
+     * call. See the module-level memory-grow contract.
+     */
+    columnPtrU32(block_idx: number, col_idx: number): number;
+    /**
+     * Copy a string column out by value. Returns an empty array
+     * if the column is missing or not a string column.
+     */
+    columnStrings(block_idx: number, col_idx: number): string[];
+    /**
+     * Feed the first `len` bytes of the input buffer into the
+     * indexer at absolute source offset `globalOffset`. Returns
+     * any frame entries that became finalized as a result.
+     *
+     * `globalOffset` is round-tripped through `f64`; per the
+     * streaming protocol the source size is capped at 1 TB
+     * (well within `Number.MAX_SAFE_INTEGER`).
+     */
+    feedIndexChunk(global_offset: number, len: number): FrameIndexEntry[];
+    /**
+     * Signal end-of-stream; return any trailing frame entry. The
+     * indexer is consumed and further `feedIndexChunk` calls
+     * throw.
+     */
+    finishIndex(): FrameIndexEntry[];
+    /**
+     * Number of named scalar arrays in grid `gridIdx`.
+     */
+    gridArrayCount(grid_idx: number): number;
+    /**
+     * Length (number of `f64` elements) of the grid scalar field.
+     */
+    gridArrayLen(grid_idx: number, array_idx: number): number;
+    /**
+     * Name of scalar array `(gridIdx, arrayIdx)`, or empty string
+     * if either index is out of range.
+     */
+    gridArrayName(grid_idx: number, array_idx: number): string;
+    /**
+     * Pointer to the contiguous `f64` slice backing the grid
+     * scalar field, or 0 (null) if either index is out of range.
+     *
+     * **Lifetime**: valid only until the next non-trivial wasm
+     * call. See the module-level memory-grow contract.
+     */
+    gridArrayPtrF64(grid_idx: number, array_idx: number): number;
+    /**
+     * Grid lattice cell as a length-9 `Float64Array` (column-major:
+     * `[col0_x, col0_y, col0_z, col1_x, col1_y, col1_z, col2_x, col2_y, col2_z]`).
+     */
+    gridCell(grid_idx: number): Float64Array;
+    /**
+     * Number of named grids attached to the current frame.
+     */
+    gridCount(): number;
+    /**
+     * Name of grid `gridIdx`, or empty string if out of range.
+     */
+    gridName(grid_idx: number): string;
+    /**
+     * Grid origin (Cartesian, Å) as a length-3 `Float64Array`.
+     */
+    gridOrigin(grid_idx: number): Float64Array;
+    /**
+     * Grid PBC flags as a length-3 `Uint8Array` (`1` = periodic,
+     * `0` = open).
+     */
+    gridPbc(grid_idx: number): Uint8Array;
+    /**
+     * Grid dimensions `[nx, ny, nz]` as a length-3 `Uint32Array`.
+     */
+    gridShape(grid_idx: number): Uint32Array;
+    /**
+     * Current capacity (in bytes) of the reusable input buffer.
+     */
+    inputCapacity(): number;
+    /**
+     * Create a new streaming reader. The reusable input buffer
+     * starts empty; call [`allocInputBuffer`] before feeding data.
+     */
+    constructor();
+    /**
+     * Decode the byte range `[offset, offset + len)` from the
+     * reusable input buffer as a single frame. Replaces any
+     * previously cached output; the caller must extract data
+     * before the next `parseRangeInInput` (the same buffer can
+     * be overwritten in between).
+     */
+    parseRangeInInput(offset: number, len: number): void;
+    /**
+     * Drop the cached output frame, releasing its memory and
+     * invalidating any outstanding `columnPtr*` / `gridArrayPtr*`
+     * pointers. Subsequent extraction calls return 0 / empty
+     * until the next `parseRangeInInput`.
+     */
+    releaseFrame(): void;
+    /**
+     * Box H-matrix as a length-9 `Float64Array` (column-major:
+     * `[col0_x, col0_y, col0_z, col1_x, col1_y, col1_z, col2_x, col2_y, col2_z]`),
+     * or `undefined` if the frame has no simbox.
+     *
+     * Returned by VALUE — the typed array is owned by JS and is
+     * stable across subsequent wasm calls.
+     */
+    simboxH(): Float64Array | undefined;
+    /**
+     * Box origin as a length-3 `Float64Array`, or `undefined` if
+     * the frame has no simbox.
+     */
+    simboxOrigin(): Float64Array | undefined;
+    /**
+     * Per-axis PBC flags as a length-3 `Uint8Array` (`1` = periodic,
+     * `0` = open), or `undefined` if the frame has no simbox.
+     *
+     * (wasm-bindgen does not support `[bool; 3]` returns natively,
+     * hence the `Uint8Array` wire format. The spec calls for
+     * `[boolean, boolean, boolean]`; the JS side is expected to
+     * `Boolean(arr[i])` each entry.)
+     */
+    simboxPbc(): Uint8Array | undefined;
+}
+
+export class WasmLammpsDumpStream {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Resize the reusable input buffer so it can hold at least
+     * `len` bytes, and return the WASM linear-memory pointer to
+     * its first byte.
+     *
+     * CALLER MUST RE-DERIVE THIS POINTER AFTER ANY OTHER WASM CALL —
+     * `wasm.memory.buffer` may have been detached by a `memory.grow`.
+     */
+    allocInputBuffer(len: number): number;
+    /**
+     * Number of blocks in the most recently parsed frame.
+     */
+    blockCount(): number;
+    /**
+     * Name of block `blockIdx`, or empty string if out of range.
+     */
+    blockName(block_idx: number): string;
+    /**
+     * Number of columns in block `blockIdx`.
+     */
+    columnCount(block_idx: number): number;
+    /**
+     * Column dtype string at `(blockIdx, colIdx)`. One of `"f64"`,
+     * `"u32"`, `"i32"`, `"string"` — or `"bool"` / `"u8"` if a
+     * future parser emits those (current streaming formats do not).
+     * Empty string if the index is out of range.
+     */
+    columnDtype(block_idx: number, col_idx: number): string;
+    /**
+     * Total flat element count of the column. For multi-dimensional
+     * columns (e.g. an Nx3 positions array) this is the product of
+     * all axes — i.e. the length of the slice the matching
+     * `columnPtr*` points at.
+     */
+    columnLen(block_idx: number, col_idx: number): number;
+    /**
+     * Column name at `(blockIdx, colIdx)`, or empty string if
+     * either index is out of range.
+     */
+    columnName(block_idx: number, col_idx: number): string;
+    /**
+     * Pointer to the contiguous `f64` slice backing this column,
+     * or 0 (null) if the column is missing or has the wrong
+     * dtype.
+     *
+     * **Lifetime**: valid only until the next non-trivial wasm
+     * call. See the module-level memory-grow contract.
+     */
+    columnPtrF64(block_idx: number, col_idx: number): number;
+    /**
+     * Pointer to the contiguous `i32` slice backing this column,
+     * or 0 (null) if the column is missing or has the wrong
+     * dtype.
+     *
+     * **Lifetime**: valid only until the next non-trivial wasm
+     * call. See the module-level memory-grow contract.
+     */
+    columnPtrI32(block_idx: number, col_idx: number): number;
+    /**
+     * Pointer to the contiguous `u32` slice backing this column,
+     * or 0 (null) if the column is missing or has the wrong
+     * dtype.
+     *
+     * **Lifetime**: valid only until the next non-trivial wasm
+     * call. See the module-level memory-grow contract.
+     */
+    columnPtrU32(block_idx: number, col_idx: number): number;
+    /**
+     * Copy a string column out by value. Returns an empty array
+     * if the column is missing or not a string column.
+     */
+    columnStrings(block_idx: number, col_idx: number): string[];
+    /**
+     * Feed the first `len` bytes of the input buffer into the
+     * indexer at absolute source offset `globalOffset`. Returns
+     * any frame entries that became finalized as a result.
+     *
+     * `globalOffset` is round-tripped through `f64`; per the
+     * streaming protocol the source size is capped at 1 TB
+     * (well within `Number.MAX_SAFE_INTEGER`).
+     */
+    feedIndexChunk(global_offset: number, len: number): FrameIndexEntry[];
+    /**
+     * Signal end-of-stream; return any trailing frame entry. The
+     * indexer is consumed and further `feedIndexChunk` calls
+     * throw.
+     */
+    finishIndex(): FrameIndexEntry[];
+    /**
+     * Number of named scalar arrays in grid `gridIdx`.
+     */
+    gridArrayCount(grid_idx: number): number;
+    /**
+     * Length (number of `f64` elements) of the grid scalar field.
+     */
+    gridArrayLen(grid_idx: number, array_idx: number): number;
+    /**
+     * Name of scalar array `(gridIdx, arrayIdx)`, or empty string
+     * if either index is out of range.
+     */
+    gridArrayName(grid_idx: number, array_idx: number): string;
+    /**
+     * Pointer to the contiguous `f64` slice backing the grid
+     * scalar field, or 0 (null) if either index is out of range.
+     *
+     * **Lifetime**: valid only until the next non-trivial wasm
+     * call. See the module-level memory-grow contract.
+     */
+    gridArrayPtrF64(grid_idx: number, array_idx: number): number;
+    /**
+     * Grid lattice cell as a length-9 `Float64Array` (column-major:
+     * `[col0_x, col0_y, col0_z, col1_x, col1_y, col1_z, col2_x, col2_y, col2_z]`).
+     */
+    gridCell(grid_idx: number): Float64Array;
+    /**
+     * Number of named grids attached to the current frame.
+     */
+    gridCount(): number;
+    /**
+     * Name of grid `gridIdx`, or empty string if out of range.
+     */
+    gridName(grid_idx: number): string;
+    /**
+     * Grid origin (Cartesian, Å) as a length-3 `Float64Array`.
+     */
+    gridOrigin(grid_idx: number): Float64Array;
+    /**
+     * Grid PBC flags as a length-3 `Uint8Array` (`1` = periodic,
+     * `0` = open).
+     */
+    gridPbc(grid_idx: number): Uint8Array;
+    /**
+     * Grid dimensions `[nx, ny, nz]` as a length-3 `Uint32Array`.
+     */
+    gridShape(grid_idx: number): Uint32Array;
+    /**
+     * Current capacity (in bytes) of the reusable input buffer.
+     */
+    inputCapacity(): number;
+    /**
+     * Create a new streaming reader. The reusable input buffer
+     * starts empty; call [`allocInputBuffer`] before feeding data.
+     */
+    constructor();
+    /**
+     * Decode the byte range `[offset, offset + len)` from the
+     * reusable input buffer as a single frame. Replaces any
+     * previously cached output; the caller must extract data
+     * before the next `parseRangeInInput` (the same buffer can
+     * be overwritten in between).
+     */
+    parseRangeInInput(offset: number, len: number): void;
+    /**
+     * Drop the cached output frame, releasing its memory and
+     * invalidating any outstanding `columnPtr*` / `gridArrayPtr*`
+     * pointers. Subsequent extraction calls return 0 / empty
+     * until the next `parseRangeInInput`.
+     */
+    releaseFrame(): void;
+    /**
+     * Box H-matrix as a length-9 `Float64Array` (column-major:
+     * `[col0_x, col0_y, col0_z, col1_x, col1_y, col1_z, col2_x, col2_y, col2_z]`),
+     * or `undefined` if the frame has no simbox.
+     *
+     * Returned by VALUE — the typed array is owned by JS and is
+     * stable across subsequent wasm calls.
+     */
+    simboxH(): Float64Array | undefined;
+    /**
+     * Box origin as a length-3 `Float64Array`, or `undefined` if
+     * the frame has no simbox.
+     */
+    simboxOrigin(): Float64Array | undefined;
+    /**
+     * Per-axis PBC flags as a length-3 `Uint8Array` (`1` = periodic,
+     * `0` = open), or `undefined` if the frame has no simbox.
+     *
+     * (wasm-bindgen does not support `[bool; 3]` returns natively,
+     * hence the `Uint8Array` wire format. The spec calls for
+     * `[boolean, boolean, boolean]`; the JS side is expected to
+     * `Boolean(arr[i])` each entry.)
+     */
+    simboxPbc(): Uint8Array | undefined;
+}
+
 /**
  * Stateless wrapper for [`molrs_compute::pca::Pca2`].
  *
@@ -2906,6 +3367,570 @@ export class WasmPcaResult {
     variance(): Float64Array;
 }
 
+export class WasmPdbStream {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Resize the reusable input buffer so it can hold at least
+     * `len` bytes, and return the WASM linear-memory pointer to
+     * its first byte.
+     *
+     * CALLER MUST RE-DERIVE THIS POINTER AFTER ANY OTHER WASM CALL —
+     * `wasm.memory.buffer` may have been detached by a `memory.grow`.
+     */
+    allocInputBuffer(len: number): number;
+    /**
+     * Number of blocks in the most recently parsed frame.
+     */
+    blockCount(): number;
+    /**
+     * Name of block `blockIdx`, or empty string if out of range.
+     */
+    blockName(block_idx: number): string;
+    /**
+     * Number of columns in block `blockIdx`.
+     */
+    columnCount(block_idx: number): number;
+    /**
+     * Column dtype string at `(blockIdx, colIdx)`. One of `"f64"`,
+     * `"u32"`, `"i32"`, `"string"` — or `"bool"` / `"u8"` if a
+     * future parser emits those (current streaming formats do not).
+     * Empty string if the index is out of range.
+     */
+    columnDtype(block_idx: number, col_idx: number): string;
+    /**
+     * Total flat element count of the column. For multi-dimensional
+     * columns (e.g. an Nx3 positions array) this is the product of
+     * all axes — i.e. the length of the slice the matching
+     * `columnPtr*` points at.
+     */
+    columnLen(block_idx: number, col_idx: number): number;
+    /**
+     * Column name at `(blockIdx, colIdx)`, or empty string if
+     * either index is out of range.
+     */
+    columnName(block_idx: number, col_idx: number): string;
+    /**
+     * Pointer to the contiguous `f64` slice backing this column,
+     * or 0 (null) if the column is missing or has the wrong
+     * dtype.
+     *
+     * **Lifetime**: valid only until the next non-trivial wasm
+     * call. See the module-level memory-grow contract.
+     */
+    columnPtrF64(block_idx: number, col_idx: number): number;
+    /**
+     * Pointer to the contiguous `i32` slice backing this column,
+     * or 0 (null) if the column is missing or has the wrong
+     * dtype.
+     *
+     * **Lifetime**: valid only until the next non-trivial wasm
+     * call. See the module-level memory-grow contract.
+     */
+    columnPtrI32(block_idx: number, col_idx: number): number;
+    /**
+     * Pointer to the contiguous `u32` slice backing this column,
+     * or 0 (null) if the column is missing or has the wrong
+     * dtype.
+     *
+     * **Lifetime**: valid only until the next non-trivial wasm
+     * call. See the module-level memory-grow contract.
+     */
+    columnPtrU32(block_idx: number, col_idx: number): number;
+    /**
+     * Copy a string column out by value. Returns an empty array
+     * if the column is missing or not a string column.
+     */
+    columnStrings(block_idx: number, col_idx: number): string[];
+    /**
+     * Feed the first `len` bytes of the input buffer into the
+     * indexer at absolute source offset `globalOffset`. Returns
+     * any frame entries that became finalized as a result.
+     *
+     * `globalOffset` is round-tripped through `f64`; per the
+     * streaming protocol the source size is capped at 1 TB
+     * (well within `Number.MAX_SAFE_INTEGER`).
+     */
+    feedIndexChunk(global_offset: number, len: number): FrameIndexEntry[];
+    /**
+     * Signal end-of-stream; return any trailing frame entry. The
+     * indexer is consumed and further `feedIndexChunk` calls
+     * throw.
+     */
+    finishIndex(): FrameIndexEntry[];
+    /**
+     * Number of named scalar arrays in grid `gridIdx`.
+     */
+    gridArrayCount(grid_idx: number): number;
+    /**
+     * Length (number of `f64` elements) of the grid scalar field.
+     */
+    gridArrayLen(grid_idx: number, array_idx: number): number;
+    /**
+     * Name of scalar array `(gridIdx, arrayIdx)`, or empty string
+     * if either index is out of range.
+     */
+    gridArrayName(grid_idx: number, array_idx: number): string;
+    /**
+     * Pointer to the contiguous `f64` slice backing the grid
+     * scalar field, or 0 (null) if either index is out of range.
+     *
+     * **Lifetime**: valid only until the next non-trivial wasm
+     * call. See the module-level memory-grow contract.
+     */
+    gridArrayPtrF64(grid_idx: number, array_idx: number): number;
+    /**
+     * Grid lattice cell as a length-9 `Float64Array` (column-major:
+     * `[col0_x, col0_y, col0_z, col1_x, col1_y, col1_z, col2_x, col2_y, col2_z]`).
+     */
+    gridCell(grid_idx: number): Float64Array;
+    /**
+     * Number of named grids attached to the current frame.
+     */
+    gridCount(): number;
+    /**
+     * Name of grid `gridIdx`, or empty string if out of range.
+     */
+    gridName(grid_idx: number): string;
+    /**
+     * Grid origin (Cartesian, Å) as a length-3 `Float64Array`.
+     */
+    gridOrigin(grid_idx: number): Float64Array;
+    /**
+     * Grid PBC flags as a length-3 `Uint8Array` (`1` = periodic,
+     * `0` = open).
+     */
+    gridPbc(grid_idx: number): Uint8Array;
+    /**
+     * Grid dimensions `[nx, ny, nz]` as a length-3 `Uint32Array`.
+     */
+    gridShape(grid_idx: number): Uint32Array;
+    /**
+     * Current capacity (in bytes) of the reusable input buffer.
+     */
+    inputCapacity(): number;
+    /**
+     * Create a new streaming reader. The reusable input buffer
+     * starts empty; call [`allocInputBuffer`] before feeding data.
+     */
+    constructor();
+    /**
+     * Decode the byte range `[offset, offset + len)` from the
+     * reusable input buffer as a single frame. Replaces any
+     * previously cached output; the caller must extract data
+     * before the next `parseRangeInInput` (the same buffer can
+     * be overwritten in between).
+     */
+    parseRangeInInput(offset: number, len: number): void;
+    /**
+     * Drop the cached output frame, releasing its memory and
+     * invalidating any outstanding `columnPtr*` / `gridArrayPtr*`
+     * pointers. Subsequent extraction calls return 0 / empty
+     * until the next `parseRangeInInput`.
+     */
+    releaseFrame(): void;
+    /**
+     * Box H-matrix as a length-9 `Float64Array` (column-major:
+     * `[col0_x, col0_y, col0_z, col1_x, col1_y, col1_z, col2_x, col2_y, col2_z]`),
+     * or `undefined` if the frame has no simbox.
+     *
+     * Returned by VALUE — the typed array is owned by JS and is
+     * stable across subsequent wasm calls.
+     */
+    simboxH(): Float64Array | undefined;
+    /**
+     * Box origin as a length-3 `Float64Array`, or `undefined` if
+     * the frame has no simbox.
+     */
+    simboxOrigin(): Float64Array | undefined;
+    /**
+     * Per-axis PBC flags as a length-3 `Uint8Array` (`1` = periodic,
+     * `0` = open), or `undefined` if the frame has no simbox.
+     *
+     * (wasm-bindgen does not support `[bool; 3]` returns natively,
+     * hence the `Uint8Array` wire format. The spec calls for
+     * `[boolean, boolean, boolean]`; the JS side is expected to
+     * `Boolean(arr[i])` each entry.)
+     */
+    simboxPbc(): Uint8Array | undefined;
+}
+
+export class WasmSdfStream {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Resize the reusable input buffer so it can hold at least
+     * `len` bytes, and return the WASM linear-memory pointer to
+     * its first byte.
+     *
+     * CALLER MUST RE-DERIVE THIS POINTER AFTER ANY OTHER WASM CALL —
+     * `wasm.memory.buffer` may have been detached by a `memory.grow`.
+     */
+    allocInputBuffer(len: number): number;
+    /**
+     * Number of blocks in the most recently parsed frame.
+     */
+    blockCount(): number;
+    /**
+     * Name of block `blockIdx`, or empty string if out of range.
+     */
+    blockName(block_idx: number): string;
+    /**
+     * Number of columns in block `blockIdx`.
+     */
+    columnCount(block_idx: number): number;
+    /**
+     * Column dtype string at `(blockIdx, colIdx)`. One of `"f64"`,
+     * `"u32"`, `"i32"`, `"string"` — or `"bool"` / `"u8"` if a
+     * future parser emits those (current streaming formats do not).
+     * Empty string if the index is out of range.
+     */
+    columnDtype(block_idx: number, col_idx: number): string;
+    /**
+     * Total flat element count of the column. For multi-dimensional
+     * columns (e.g. an Nx3 positions array) this is the product of
+     * all axes — i.e. the length of the slice the matching
+     * `columnPtr*` points at.
+     */
+    columnLen(block_idx: number, col_idx: number): number;
+    /**
+     * Column name at `(blockIdx, colIdx)`, or empty string if
+     * either index is out of range.
+     */
+    columnName(block_idx: number, col_idx: number): string;
+    /**
+     * Pointer to the contiguous `f64` slice backing this column,
+     * or 0 (null) if the column is missing or has the wrong
+     * dtype.
+     *
+     * **Lifetime**: valid only until the next non-trivial wasm
+     * call. See the module-level memory-grow contract.
+     */
+    columnPtrF64(block_idx: number, col_idx: number): number;
+    /**
+     * Pointer to the contiguous `i32` slice backing this column,
+     * or 0 (null) if the column is missing or has the wrong
+     * dtype.
+     *
+     * **Lifetime**: valid only until the next non-trivial wasm
+     * call. See the module-level memory-grow contract.
+     */
+    columnPtrI32(block_idx: number, col_idx: number): number;
+    /**
+     * Pointer to the contiguous `u32` slice backing this column,
+     * or 0 (null) if the column is missing or has the wrong
+     * dtype.
+     *
+     * **Lifetime**: valid only until the next non-trivial wasm
+     * call. See the module-level memory-grow contract.
+     */
+    columnPtrU32(block_idx: number, col_idx: number): number;
+    /**
+     * Copy a string column out by value. Returns an empty array
+     * if the column is missing or not a string column.
+     */
+    columnStrings(block_idx: number, col_idx: number): string[];
+    /**
+     * Feed the first `len` bytes of the input buffer into the
+     * indexer at absolute source offset `globalOffset`. Returns
+     * any frame entries that became finalized as a result.
+     *
+     * `globalOffset` is round-tripped through `f64`; per the
+     * streaming protocol the source size is capped at 1 TB
+     * (well within `Number.MAX_SAFE_INTEGER`).
+     */
+    feedIndexChunk(global_offset: number, len: number): FrameIndexEntry[];
+    /**
+     * Signal end-of-stream; return any trailing frame entry. The
+     * indexer is consumed and further `feedIndexChunk` calls
+     * throw.
+     */
+    finishIndex(): FrameIndexEntry[];
+    /**
+     * Number of named scalar arrays in grid `gridIdx`.
+     */
+    gridArrayCount(grid_idx: number): number;
+    /**
+     * Length (number of `f64` elements) of the grid scalar field.
+     */
+    gridArrayLen(grid_idx: number, array_idx: number): number;
+    /**
+     * Name of scalar array `(gridIdx, arrayIdx)`, or empty string
+     * if either index is out of range.
+     */
+    gridArrayName(grid_idx: number, array_idx: number): string;
+    /**
+     * Pointer to the contiguous `f64` slice backing the grid
+     * scalar field, or 0 (null) if either index is out of range.
+     *
+     * **Lifetime**: valid only until the next non-trivial wasm
+     * call. See the module-level memory-grow contract.
+     */
+    gridArrayPtrF64(grid_idx: number, array_idx: number): number;
+    /**
+     * Grid lattice cell as a length-9 `Float64Array` (column-major:
+     * `[col0_x, col0_y, col0_z, col1_x, col1_y, col1_z, col2_x, col2_y, col2_z]`).
+     */
+    gridCell(grid_idx: number): Float64Array;
+    /**
+     * Number of named grids attached to the current frame.
+     */
+    gridCount(): number;
+    /**
+     * Name of grid `gridIdx`, or empty string if out of range.
+     */
+    gridName(grid_idx: number): string;
+    /**
+     * Grid origin (Cartesian, Å) as a length-3 `Float64Array`.
+     */
+    gridOrigin(grid_idx: number): Float64Array;
+    /**
+     * Grid PBC flags as a length-3 `Uint8Array` (`1` = periodic,
+     * `0` = open).
+     */
+    gridPbc(grid_idx: number): Uint8Array;
+    /**
+     * Grid dimensions `[nx, ny, nz]` as a length-3 `Uint32Array`.
+     */
+    gridShape(grid_idx: number): Uint32Array;
+    /**
+     * Current capacity (in bytes) of the reusable input buffer.
+     */
+    inputCapacity(): number;
+    /**
+     * Create a new streaming reader. The reusable input buffer
+     * starts empty; call [`allocInputBuffer`] before feeding data.
+     */
+    constructor();
+    /**
+     * Decode the byte range `[offset, offset + len)` from the
+     * reusable input buffer as a single frame. Replaces any
+     * previously cached output; the caller must extract data
+     * before the next `parseRangeInInput` (the same buffer can
+     * be overwritten in between).
+     */
+    parseRangeInInput(offset: number, len: number): void;
+    /**
+     * Drop the cached output frame, releasing its memory and
+     * invalidating any outstanding `columnPtr*` / `gridArrayPtr*`
+     * pointers. Subsequent extraction calls return 0 / empty
+     * until the next `parseRangeInInput`.
+     */
+    releaseFrame(): void;
+    /**
+     * Box H-matrix as a length-9 `Float64Array` (column-major:
+     * `[col0_x, col0_y, col0_z, col1_x, col1_y, col1_z, col2_x, col2_y, col2_z]`),
+     * or `undefined` if the frame has no simbox.
+     *
+     * Returned by VALUE — the typed array is owned by JS and is
+     * stable across subsequent wasm calls.
+     */
+    simboxH(): Float64Array | undefined;
+    /**
+     * Box origin as a length-3 `Float64Array`, or `undefined` if
+     * the frame has no simbox.
+     */
+    simboxOrigin(): Float64Array | undefined;
+    /**
+     * Per-axis PBC flags as a length-3 `Uint8Array` (`1` = periodic,
+     * `0` = open), or `undefined` if the frame has no simbox.
+     *
+     * (wasm-bindgen does not support `[bool; 3]` returns natively,
+     * hence the `Uint8Array` wire format. The spec calls for
+     * `[boolean, boolean, boolean]`; the JS side is expected to
+     * `Boolean(arr[i])` each entry.)
+     */
+    simboxPbc(): Uint8Array | undefined;
+}
+
+export class WasmXyzStream {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Resize the reusable input buffer so it can hold at least
+     * `len` bytes, and return the WASM linear-memory pointer to
+     * its first byte.
+     *
+     * CALLER MUST RE-DERIVE THIS POINTER AFTER ANY OTHER WASM CALL —
+     * `wasm.memory.buffer` may have been detached by a `memory.grow`.
+     */
+    allocInputBuffer(len: number): number;
+    /**
+     * Number of blocks in the most recently parsed frame.
+     */
+    blockCount(): number;
+    /**
+     * Name of block `blockIdx`, or empty string if out of range.
+     */
+    blockName(block_idx: number): string;
+    /**
+     * Number of columns in block `blockIdx`.
+     */
+    columnCount(block_idx: number): number;
+    /**
+     * Column dtype string at `(blockIdx, colIdx)`. One of `"f64"`,
+     * `"u32"`, `"i32"`, `"string"` — or `"bool"` / `"u8"` if a
+     * future parser emits those (current streaming formats do not).
+     * Empty string if the index is out of range.
+     */
+    columnDtype(block_idx: number, col_idx: number): string;
+    /**
+     * Total flat element count of the column. For multi-dimensional
+     * columns (e.g. an Nx3 positions array) this is the product of
+     * all axes — i.e. the length of the slice the matching
+     * `columnPtr*` points at.
+     */
+    columnLen(block_idx: number, col_idx: number): number;
+    /**
+     * Column name at `(blockIdx, colIdx)`, or empty string if
+     * either index is out of range.
+     */
+    columnName(block_idx: number, col_idx: number): string;
+    /**
+     * Pointer to the contiguous `f64` slice backing this column,
+     * or 0 (null) if the column is missing or has the wrong
+     * dtype.
+     *
+     * **Lifetime**: valid only until the next non-trivial wasm
+     * call. See the module-level memory-grow contract.
+     */
+    columnPtrF64(block_idx: number, col_idx: number): number;
+    /**
+     * Pointer to the contiguous `i32` slice backing this column,
+     * or 0 (null) if the column is missing or has the wrong
+     * dtype.
+     *
+     * **Lifetime**: valid only until the next non-trivial wasm
+     * call. See the module-level memory-grow contract.
+     */
+    columnPtrI32(block_idx: number, col_idx: number): number;
+    /**
+     * Pointer to the contiguous `u32` slice backing this column,
+     * or 0 (null) if the column is missing or has the wrong
+     * dtype.
+     *
+     * **Lifetime**: valid only until the next non-trivial wasm
+     * call. See the module-level memory-grow contract.
+     */
+    columnPtrU32(block_idx: number, col_idx: number): number;
+    /**
+     * Copy a string column out by value. Returns an empty array
+     * if the column is missing or not a string column.
+     */
+    columnStrings(block_idx: number, col_idx: number): string[];
+    /**
+     * Feed the first `len` bytes of the input buffer into the
+     * indexer at absolute source offset `globalOffset`. Returns
+     * any frame entries that became finalized as a result.
+     *
+     * `globalOffset` is round-tripped through `f64`; per the
+     * streaming protocol the source size is capped at 1 TB
+     * (well within `Number.MAX_SAFE_INTEGER`).
+     */
+    feedIndexChunk(global_offset: number, len: number): FrameIndexEntry[];
+    /**
+     * Signal end-of-stream; return any trailing frame entry. The
+     * indexer is consumed and further `feedIndexChunk` calls
+     * throw.
+     */
+    finishIndex(): FrameIndexEntry[];
+    /**
+     * Number of named scalar arrays in grid `gridIdx`.
+     */
+    gridArrayCount(grid_idx: number): number;
+    /**
+     * Length (number of `f64` elements) of the grid scalar field.
+     */
+    gridArrayLen(grid_idx: number, array_idx: number): number;
+    /**
+     * Name of scalar array `(gridIdx, arrayIdx)`, or empty string
+     * if either index is out of range.
+     */
+    gridArrayName(grid_idx: number, array_idx: number): string;
+    /**
+     * Pointer to the contiguous `f64` slice backing the grid
+     * scalar field, or 0 (null) if either index is out of range.
+     *
+     * **Lifetime**: valid only until the next non-trivial wasm
+     * call. See the module-level memory-grow contract.
+     */
+    gridArrayPtrF64(grid_idx: number, array_idx: number): number;
+    /**
+     * Grid lattice cell as a length-9 `Float64Array` (column-major:
+     * `[col0_x, col0_y, col0_z, col1_x, col1_y, col1_z, col2_x, col2_y, col2_z]`).
+     */
+    gridCell(grid_idx: number): Float64Array;
+    /**
+     * Number of named grids attached to the current frame.
+     */
+    gridCount(): number;
+    /**
+     * Name of grid `gridIdx`, or empty string if out of range.
+     */
+    gridName(grid_idx: number): string;
+    /**
+     * Grid origin (Cartesian, Å) as a length-3 `Float64Array`.
+     */
+    gridOrigin(grid_idx: number): Float64Array;
+    /**
+     * Grid PBC flags as a length-3 `Uint8Array` (`1` = periodic,
+     * `0` = open).
+     */
+    gridPbc(grid_idx: number): Uint8Array;
+    /**
+     * Grid dimensions `[nx, ny, nz]` as a length-3 `Uint32Array`.
+     */
+    gridShape(grid_idx: number): Uint32Array;
+    /**
+     * Current capacity (in bytes) of the reusable input buffer.
+     */
+    inputCapacity(): number;
+    /**
+     * Create a new streaming reader. The reusable input buffer
+     * starts empty; call [`allocInputBuffer`] before feeding data.
+     */
+    constructor();
+    /**
+     * Decode the byte range `[offset, offset + len)` from the
+     * reusable input buffer as a single frame. Replaces any
+     * previously cached output; the caller must extract data
+     * before the next `parseRangeInInput` (the same buffer can
+     * be overwritten in between).
+     */
+    parseRangeInInput(offset: number, len: number): void;
+    /**
+     * Drop the cached output frame, releasing its memory and
+     * invalidating any outstanding `columnPtr*` / `gridArrayPtr*`
+     * pointers. Subsequent extraction calls return 0 / empty
+     * until the next `parseRangeInInput`.
+     */
+    releaseFrame(): void;
+    /**
+     * Box H-matrix as a length-9 `Float64Array` (column-major:
+     * `[col0_x, col0_y, col0_z, col1_x, col1_y, col1_z, col2_x, col2_y, col2_z]`),
+     * or `undefined` if the frame has no simbox.
+     *
+     * Returned by VALUE — the typed array is owned by JS and is
+     * stable across subsequent wasm calls.
+     */
+    simboxH(): Float64Array | undefined;
+    /**
+     * Box origin as a length-3 `Float64Array`, or `undefined` if
+     * the frame has no simbox.
+     */
+    simboxOrigin(): Float64Array | undefined;
+    /**
+     * Per-axis PBC flags as a length-3 `Uint8Array` (`1` = periodic,
+     * `0` = open), or `undefined` if the frame has no simbox.
+     *
+     * (wasm-bindgen does not support `[bool; 3]` returns natively,
+     * hence the `Uint8Array` wire format. The spec calls for
+     * `[boolean, boolean, boolean]`; the JS side is expected to
+     * `Boolean(arr[i])` each entry.)
+     */
+    simboxPbc(): Uint8Array | undefined;
+}
+
 /**
  * XYZ / Extended XYZ file reader.
  *