@kent-tokyo/chematic 1.0.12 → 1.0.14

package/README.md

@@ -4,6 +4,10 @@ WebAssembly bindings for [chematic](https://github.com/kent-tokyo/chematic), a p
 
 Published to npm as [`@kent-tokyo/chematic`](https://www.npmjs.com/package/@kent-tokyo/chematic).
 
+The current workspace line is 1.0.14. The binding keeps bounded parsing,
+typed failures, and opt-in `embed_pipeline_v2_json`; 3D/MMFF94 behavior remains
+Experimental and is not a claim of full RDKit parity.
+
 ## Installation
 
 ```sh
@@ -29,7 +33,8 @@ npm install @kent-tokyo/chematic
   deterministic input indices and partial/complete status; bounded malformed
   XYZ frames are grouped inline as rejected records when a later count-line
   boundary is recoverable (core file-backed readers remain fail-stop)
-- Bounded topology parsing for CML, ChemicalJSON (`mol_from_cjson`), MolJSON,
+- Bounded topology parsing for CML (`mol_from_cml_strict` provides the opt-in
+  non-empty, balanced, single-root boundary), ChemicalJSON (`mol_from_cjson`), MolJSON,
   CDXML, MOL2, and PDB/mmCIF
 - PDBx/mmCIF, PQR, QCSchema JSON, ORCA input/output, Gaussian Cube, OpenDX,
   and LAMMPS data/dump I/O (JSON-based bindings; see `format_io.rs`)
@@ -99,6 +104,11 @@ console.log(mol.labute_asa());                   // Labute approx. surface area
 const charges = JSON.parse(gasteiger_charges_json(mol));
 console.log(charges); // [-0.08, 0.12, -0.43, ...]
 
+// Explicit RDKit-compatibility descriptor profile (kept separate from the
+// historical native get_descriptors_json() profile)
+const rdkitDescriptors = JSON.parse(get_rdkit_descriptors_json(mol));
+console.log(rdkitDescriptors.aromatic_ring_count);
+
 // VSA descriptor bins
 const slogpVsa = JSON.parse(slogp_vsa_json(mol));
 const smrVsa   = JSON.parse(smr_vsa_json(mol));
@@ -167,12 +177,65 @@ portable across native and `wasm32-unknown-unknown`
 precision across every JS engine, only that the value is finite, non-negative,
 and enforced correctly on all of them.
 
+`nearest_neighbors_json` keeps its historical chematic-native ECFP4 profile.
+For the separately named RDKit-compatible Morgan profile, use
+`rdkit_nearest_neighbors_json(querySmiles, dbSmilesJson, k)`. It returns the
+same `{index, tanimoto}` shape and reports preprocessing failures without
+silently falling back to native ECFP4.
+
+For repeated queries, construct `new RdkitSearchIndex(dbSmilesJson)` once and
+call `index.search_json(querySmiles, k)`. The prepared index is intended for
+chunked libraries up to the WASM batch limit and applies the same fail-closed
+RDKit-compatible profile without rebuilding database fingerprints per query.
+
+## V3000 SGROUP syntax view
+
+`v3000_sgroups_json(block)` exposes bounded, typed SGROUP syntax without
+expanding polymer or Markush semantics. It preserves source order for unknown
+attributes and returns `kindToken` for unknown group kinds. Group IDs, parent
+references, atom references, and grouped-field counts are validated before
+JSON is returned.
+
+```js
+const groups = JSON.parse(v3000_sgroups_json(v3000Block));
+// [{ id, kind, parentId, atomIds, attributes, kindToken? }]
+```
+
+This is a syntax-level API; it does not claim polymer expansion, Markush
+interpretation, or cross-engine semantic compatibility.
+
 ## Bundle Size
 
-The optimized v1.0.10 candidate artifact was measured at **3.73 MB raw / 1.36 MB gzip**. Bundle size depends on features and toolchain; see [`benchmarks/2026-09-09-wasm-size-v1.0.10.md`](../../benchmarks/2026-09-09-wasm-size-v1.0.10.md) for exact tools, digest, and reproduction steps.
+The optimized v1.0.12 artifact was measured at **3.93 MB raw / 1.43 MB gzip**. Bundle size depends on features and toolchain; see [`benchmarks/2026-09-11-official-rdkit-js-v1.0.12.md`](../../benchmarks/2026-09-11-official-rdkit-js-v1.0.12.md) for exact tools, digest, and reproduction steps.
 
 PNG rasterization (`tiny_skia`) is excluded from the WASM build — use SVG output instead. All SVG depiction APIs remain fully available.
 
+## Versioned document binding boundary
+
+The `*_v1` document APIs provide a stable JSON boundary for downstream editors:
+
+```js
+const parsed = JSON.parse(reaction_document_json_v1(JSON.stringify(document)));
+const edited = JSON.parse(edit_reaction_document_json_v1(
+  JSON.stringify(parsed),
+  JSON.stringify({ kind: "set_step_condition", step_id: "step-1", key: "temperature", value: "25 C" }),
+));
+
+const cdxmlEnvelope = JSON.parse(cdxml_document_json_v1(cdxml));
+const cdxmlAgain = cdxml_document_from_json_v1(JSON.stringify(cdxmlEnvelope));
+```
+
+`cdxml_document_json_v1` retains the exact `source` string and returns a
+structural `document` summary with opaque objects and `diagnostics`. Use
+`edit_cdxml_document_json_v1` for bounded page/object edits; it reparses the
+result before returning. Errors are JSON-shaped with stable `code`, `path`, and
+`message` fields (`malformed_input`, `resource_limit`,
+`unsupported_construct`, `lossy_conversion`, or `serialization_error`).
+`reaction_document_to_rxn_v1` and `cdxml_document_projection_json_v1` reject
+lossy legacy projections with `lossy_conversion` diagnostics. These APIs do not claim
+mechanism correctness, product prediction, complete stoichiometry, or full
+ChemDraw/RXN compatibility.
+
 ## Building from source
 
 ```sh

package/chematic_wasm.d.ts

@@ -409,6 +409,10 @@ export class MolHandle {
      * Most basic pKa in the molecule, or NaN if no basic site.
      */
     pka_base_value(): number;
+    /**
+     * Atom indices of potential tetrahedral stereocenters.
+     */
+    potential_stereocenter_indices(): Uint32Array;
     /**
      * Quantitative Estimate of Drug-likeness (QED); range [0, 1].
      */
@@ -462,6 +466,47 @@ export class MolHandle {
     zagreb_index_m1(): number;
 }
 
+/**
+ * Reusable prepared index for the RDKit-compatible Morgan profile.
+ *
+ * Build one index per input chunk (the WASM batch limit is 1,024 molecules),
+ * then call [`RdkitSearchIndex::search_json`] for multiple queries without
+ * reparsing or refingerprinting the database.
+ */
+export class RdkitSearchIndex {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Whether the prepared index contains no molecules.
+     */
+    is_empty(): boolean;
+    /**
+     * Number of molecules in this chunk.
+     */
+    len(): number;
+    /**
+     * Build an index from a JSON array of SMILES strings.
+     */
+    constructor(db_smiles_json: string);
+    /**
+     * Search the prepared index with a query SMILES.
+     */
+    search_json(query_smiles: string, k: number): string;
+    /**
+     * Search without the historical six-decimal JSON score truncation.
+     *
+     * This opt-in endpoint is for exact parity measurements. Callers that
+     * need the stable historical wire format should continue using
+     * RdkitSearchIndex::search_json.
+     */
+    search_json_precise(query_smiles: string, k: number): string;
+    /**
+     * Search with an inclusive Tanimoto threshold and precise JSON scores.
+     * A threshold of `0.0` includes zero-score candidates.
+     */
+    search_json_threshold_precise(query_smiles: string, threshold: number, k: number): string;
+}
+
 /**
  * Return a copy of the molecule with all implicit hydrogens converted to explicit H atoms.
  */
@@ -593,6 +638,11 @@ export function canonical_tautomer_with_blocked_atoms_json(mol: MolHandle, block
  */
 export function canonicalize_smiles_batch_json(smiles_batch: string, delimiter: string): string;
 
+/**
+ * Validate a versioned CDXML JSON envelope and serialize its exact source.
+ */
+export function cdxml_document_from_json_v1(document_json: string): string;
+
 /**
  * Parse a CDXML document while preserving page and presentation objects.
  * The returned JSON contains an opaque `raw_xml` for each object so unknown
@@ -600,6 +650,22 @@ export function canonicalize_smiles_batch_json(smiles_batch: string, delimiter:
  */
 export function cdxml_document_json(cdxml: string): string;
 
+/**
+ * Return a loss-preserving, versioned JSON envelope for a CDXML document.
+ *
+ * `source` is retained for exact re-serialization; `document` is the stable
+ * structural summary used by editors. Unknown objects remain in the summary
+ * and are listed under `document.diagnostics`.
+ */
+export function cdxml_document_json_v1(cdxml: string): string;
+
+/**
+ * Project a CDXML document to its first molecular fragment only when no
+ * presentation data would be lost. Unknown/presentation objects are reported
+ * as an explicit lossy conversion instead of being silently dropped.
+ */
+export function cdxml_document_projection_json_v1(cdxml: string): string;
+
 /**
  * Parse all molecular fragments from a CDXML string.
  *
@@ -872,6 +938,18 @@ export function ecfp_bitvec_custom(mol: MolHandle, radius: number, nbits: number
  */
 export function edit_cdxml_document_json(cdxml: string, edit_json: string): string;
 
+/**
+ * Apply a bounded CDXML edit to a versioned JSON envelope and return the
+ * updated envelope. The source is reparsed after editing, so paths and
+ * diagnostics cannot drift from the returned document summary.
+ */
+export function edit_cdxml_document_json_v1(document_json: string, edit_json: string): string;
+
+/**
+ * Apply a bounded, stable-ID reaction-document edit and return canonical JSON.
+ */
+export function edit_reaction_document_json_v1(document_json: string, edit_json: string): string;
+
 /**
  * Run `embed_ensemble_v2` on `mol`'s own atom order (never canonicalizes/
  * reparses, same convention as `embed_pipeline_v2_json`). See the module doc
@@ -1157,6 +1235,17 @@ export function get_descriptors_json(mol: MolHandle): string;
  */
 export function get_dihedral_json(smiles: string, a: number, b: number, c: number, d: number): any;
 
+/**
+ * RDKit-compatibility descriptor profile as JSON.
+ *
+ * This is deliberately separate from [`get_descriptors_json`]: the latter is
+ * the historical native profile, while this profile uses the opt-in RDKit
+ * molecular-weight, HBA, and aromatic-ring implementations.  Keeping the
+ * boundary explicit prevents a compatibility correction from silently
+ * changing the browser's native descriptor contract.
+ */
+export function get_rdkit_descriptors_json(mol: MolHandle): string;
+
 /**
  * Compute GETAWAY descriptors (GEometry, Topology and Atom-Weights AssemblY) from 3D coords.
  *
@@ -1456,7 +1545,7 @@ export function minimize_mmff94_lbfgs_json(mol: MolHandle, max_iter: number): st
  * `coords_json` — JSON array of `[x,y,z]` arrays (Å), one per atom.
  * `max_iter` — maximum iterations (0 = default 500).
  *
- * Returns JSON: `{"coords":[[x,y,z],...], "energy":float, "iterations":int, "converged":bool, "sound":bool, "worst_bond_length":float}`
+ * Returns JSON: `{"coords":[[x,y,z],...], "energy":float, "iterations":int, "converged":bool, "sound":bool, "worst_bond_length":float, "rejected_unsound_step":bool}`
  * or `{"error":"<msg>"}` on failure. `sound` is all-finite coordinates and
  * no bond stretched past a sane covalent-bond length — independent of
  * `converged`, since steepest descent often reports `converged:false` on
@@ -1619,6 +1708,14 @@ export function mol_from_cjson(json: string): MolHandle;
  */
 export function mol_from_cml(cml: string): MolHandle;
 
+/**
+ * Parse a structurally valid, non-empty CML string into a `MolHandle`.
+ *
+ * This opt-in strict boundary rejects missing/empty molecules and malformed
+ * XML while `mol_from_cml` retains its historical lenient behavior.
+ */
+export function mol_from_cml_strict(cml: string): MolHandle;
+
 /**
  * Parse a Gaussian Cube file and return a `MolHandle` (topology only --
  * element list, no bonds; Cube carries no bond table). Use
@@ -2145,6 +2242,17 @@ export function rdkit_ecfp_config_chiral_detail_json(mol: MolHandle, radius: num
  */
 export function rdkit_ecfp_config_detail_json(mol: MolHandle, radius: number, nbits: number): string;
 
+/**
+ * Find the k nearest neighbours using the RDKit-compatible Morgan/ECFP4
+ * profile. This is intentionally separate from [`nearest_neighbors_json`],
+ * whose historical contract uses chematic's native ECFP4 profile.
+ *
+ * Returns JSON with the original database indices and six-decimal Tanimoto
+ * scores. Any RDKit-profile preprocessing failure is returned as an error;
+ * this API never falls back to the native profile.
+ */
+export function rdkit_nearest_neighbors_json(query_smiles: string, db_smiles_json: string, k: number): string;
+
 /**
  * Compute the RDKit-compatible Daylight-like path fingerprint as a bit-packed
  * byte vector (256 bytes = 2048 bits). This is the WASM counterpart of the
@@ -2167,6 +2275,21 @@ export function rdkit_rdk_bitvec(mol: MolHandle): Uint8Array;
  */
 export function rdkit_torsion_bitvec(mol: MolHandle): Uint8Array;
 
+/**
+ * Validate and deterministically serialize a rich reaction document JSON.
+ *
+ * This is the versioned JSON boundary for WASM consumers. It preserves IDs,
+ * metadata, and provenance, and rejects malformed documents before returning
+ * JSON. Use [`edit_reaction_document_json_v1`] for bounded ID-addressed edits.
+ */
+export function reaction_document_json_v1(document_json: string): string;
+
+/**
+ * Convert a rich reaction document to legacy RXN V2000 with structured loss
+ * reporting. A lossy projection is never returned as if it were complete.
+ */
+export function reaction_document_to_rxn_v1(document_json: string): string;
+
 /**
  * Check whether a reaction SMILES matches a reaction SMARTS query.
  *
@@ -2238,13 +2361,13 @@ export function rgroup_decompose_json(smiles_json: string, core_smarts: string):
 export function ring_families_json(mol: MolHandle): string;
 
 /**
- * Parse and serialize a V3000 block while preserving opaque V3000 metadata.
+ * Parse and serialize a V3000 block while preserving V3000 metadata.
  *
  * Unlike the topology-only [`mol_from_v3000_block`] + [`to_mol_v3000_block`]
  * pair, this explicit round-trip API retains `SGROUP` logical lines and
- * `COLLECTION` stereo groups. SGROUP semantics remain opaque until the core
- * molecule model grows a typed representation; the API therefore preserves
- * bytes at the logical-line level without claiming polymer/query semantics.
+ * `COLLECTION` stereo groups. SGROUP polymer/query expansion is still out of
+ * scope, but the typed syntax view is available through
+ * [`v3000_sgroups_json`].
  */
 export function roundtrip_mol_v3000_block(block: string): string;
 
@@ -2655,6 +2778,8 @@ export function topo_path_bitvec(mol: MolHandle): Uint8Array;
  */
 export function torsion_bitvec(mol: MolHandle): Uint8Array;
 
+export function v3000_sgroups_json(block: string): string;
+
 /**
  * Validate a vendor-neutral NMR spectrum JSON document without parsing a
  * vendor-specific raw file or predicting peaks.
@@ -2792,6 +2917,7 @@ export interface InitOutput {
     readonly __wbg_depictoptions_free: (a: number, b: number) => void;
     readonly __wbg_mhfplshhandle_free: (a: number, b: number) => void;
     readonly __wbg_molhandle_free: (a: number, b: number) => void;
+    readonly __wbg_rdkitsearchindex_free: (a: number, b: number) => void;
     readonly add_hydrogens: (a: number) => number;
     readonly admet_profile_json: (a: number, b: number) => [number, number];
     readonly atom_pair_bitvec: (a: number) => [number, number];
@@ -2806,7 +2932,10 @@ export interface InitOutput {
     readonly canonical_tautomer: (a: number) => number;
     readonly canonical_tautomer_with_blocked_atoms_json: (a: number, b: number, c: number) => [number, number];
     readonly canonicalize_smiles_batch_json: (a: number, b: number, c: number, d: number) => [number, number, number, number];
+    readonly cdxml_document_from_json_v1: (a: number, b: number) => [number, number, number, number];
     readonly cdxml_document_json: (a: number, b: number) => [number, number, number, number];
+    readonly cdxml_document_json_v1: (a: number, b: number) => [number, number, number, number];
+    readonly cdxml_document_projection_json_v1: (a: number, b: number) => [number, number, number, number];
     readonly cdxml_to_smiles_json: (a: number, b: number) => [number, number, number, number];
     readonly charge_parent_json: (a: number) => [number, number];
     readonly chematic_version: () => [number, number];
@@ -2859,6 +2988,8 @@ export interface InitOutput {
     readonly ecfp6_bitvec_with_chirality: (a: number, b: number) => [number, number];
     readonly ecfp_bitvec_custom: (a: number, b: number, c: number, d: number) => [number, number];
     readonly edit_cdxml_document_json: (a: number, b: number, c: number, d: number) => [number, number, number, number];
+    readonly edit_cdxml_document_json_v1: (a: number, b: number, c: number, d: number) => [number, number, number, number];
+    readonly edit_reaction_document_json_v1: (a: number, b: number, c: number, d: number) => [number, number, number, number];
     readonly embed_ensemble_v2_json: (a: number, b: number, c: number) => [number, number];
     readonly embed_pipeline_v2_json: (a: number, b: number, c: number) => [number, number];
     readonly enumerate_library_2way: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number, number];
@@ -2888,6 +3019,7 @@ export interface InitOutput {
     readonly get_bond_length_json: (a: number, b: number, c: number, d: number) => number;
     readonly get_descriptors_json: (a: number) => [number, number];
     readonly get_dihedral_json: (a: number, b: number, c: number, d: number, e: number, f: number) => any;
+    readonly get_rdkit_descriptors_json: (a: number) => [number, number];
     readonly getaway_descriptors_json: (a: number) => [number, number];
     readonly hdf_json: (a: number, b: number, c: number, d: bigint) => [number, number];
     readonly identify_functional_groups: (a: number) => [number, number];
@@ -2936,6 +3068,7 @@ export interface InitOutput {
     readonly mol_from_cdxml: (a: number, b: number) => [number, number, number];
     readonly mol_from_cjson: (a: number, b: number) => [number, number, number];
     readonly mol_from_cml: (a: number, b: number) => [number, number, number];
+    readonly mol_from_cml_strict: (a: number, b: number) => [number, number, number];
     readonly mol_from_cube: (a: number, b: number) => [number, number, number];
     readonly mol_from_extxyz: (a: number, b: number) => [number, number, number];
     readonly mol_from_mmcif: (a: number, b: number) => [number, number, number];
@@ -3018,6 +3151,7 @@ export interface InitOutput {
     readonly molhandle_pains_passes: (a: number) => number;
     readonly molhandle_pka_acid_value: (a: number) => number;
     readonly molhandle_pka_base_value: (a: number) => number;
+    readonly molhandle_potential_stereocenter_indices: (a: number) => [number, number];
     readonly molhandle_qed: (a: number) => number;
     readonly molhandle_randic_index: (a: number) => number;
     readonly molhandle_reos_passes: (a: number) => number;
@@ -3069,9 +3203,18 @@ export interface InitOutput {
     readonly rdkit_ecfp_config_chiral_bitvec: (a: number, b: number, c: number) => [number, number, number, number];
     readonly rdkit_ecfp_config_chiral_detail_json: (a: number, b: number, c: number) => [number, number, number, number];
     readonly rdkit_ecfp_config_detail_json: (a: number, b: number, c: number) => [number, number, number, number];
+    readonly rdkit_nearest_neighbors_json: (a: number, b: number, c: number, d: number, e: number) => [number, number];
     readonly rdkit_path_bitvec: (a: number) => [number, number];
     readonly rdkit_rdk_bitvec: (a: number) => [number, number];
     readonly rdkit_torsion_bitvec: (a: number) => [number, number];
+    readonly rdkitsearchindex_is_empty: (a: number) => number;
+    readonly rdkitsearchindex_len: (a: number) => number;
+    readonly rdkitsearchindex_new: (a: number, b: number) => [number, number, number];
+    readonly rdkitsearchindex_search_json: (a: number, b: number, c: number, d: number) => [number, number];
+    readonly rdkitsearchindex_search_json_precise: (a: number, b: number, c: number, d: number) => [number, number];
+    readonly rdkitsearchindex_search_json_threshold_precise: (a: number, b: number, c: number, d: number, e: number) => [number, number];
+    readonly reaction_document_json_v1: (a: number, b: number) => [number, number, number, number];
+    readonly reaction_document_to_rxn_v1: (a: number, b: number) => [number, number, number, number];
     readonly reaction_smarts_match: (a: number, b: number, c: number, d: number) => [number, number, number];
     readonly remove_hydrogens: (a: number) => number;
     readonly retro_disconnect_json: (a: number, b: number, c: number, d: number) => [number, number, number, number];
@@ -3129,6 +3272,7 @@ export interface InitOutput {
     readonly to_xyz: (a: number) => [number, number];
     readonly topo_path_bitvec: (a: number) => [number, number];
     readonly torsion_bitvec: (a: number) => [number, number];
+    readonly v3000_sgroups_json: (a: number, b: number) => [number, number, number, number];
     readonly validate_nmr_spectrum_json: (a: number, b: number) => [number, number];
     readonly virtual_screen_ecfp4_json: (a: number, b: number, c: number, d: number, e: number) => [number, number];
     readonly whim_descriptors_json: (a: number) => [number, number];

package/chematic_wasm.js

@@ -961,6 +961,16 @@ export class MolHandle {
         const ret = wasm.molhandle_pka_base_value(this.__wbg_ptr);
         return ret;
     }
+    /**
+     * Atom indices of potential tetrahedral stereocenters.
+     * @returns {Uint32Array}
+     */
+    potential_stereocenter_indices() {
+        const ret = wasm.molhandle_potential_stereocenter_indices(this.__wbg_ptr);
+        var v1 = getArrayU32FromWasm0(ret[0], ret[1]).slice();
+        wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
+        return v1;
+    }
     /**
      * Quantitative Estimate of Drug-likeness (QED); range [0, 1].
      * @returns {number}
@@ -1079,6 +1089,124 @@ export class MolHandle {
 }
 if (Symbol.dispose) MolHandle.prototype[Symbol.dispose] = MolHandle.prototype.free;
 
+/**
+ * Reusable prepared index for the RDKit-compatible Morgan profile.
+ *
+ * Build one index per input chunk (the WASM batch limit is 1,024 molecules),
+ * then call [`RdkitSearchIndex::search_json`] for multiple queries without
+ * reparsing or refingerprinting the database.
+ */
+export class RdkitSearchIndex {
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        RdkitSearchIndexFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_rdkitsearchindex_free(ptr, 0);
+    }
+    /**
+     * Whether the prepared index contains no molecules.
+     * @returns {boolean}
+     */
+    is_empty() {
+        const ret = wasm.rdkitsearchindex_is_empty(this.__wbg_ptr);
+        return ret !== 0;
+    }
+    /**
+     * Number of molecules in this chunk.
+     * @returns {number}
+     */
+    len() {
+        const ret = wasm.rdkitsearchindex_len(this.__wbg_ptr);
+        return ret >>> 0;
+    }
+    /**
+     * Build an index from a JSON array of SMILES strings.
+     * @param {string} db_smiles_json
+     */
+    constructor(db_smiles_json) {
+        const ptr0 = passStringToWasm0(db_smiles_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.rdkitsearchindex_new(ptr0, len0);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        this.__wbg_ptr = ret[0];
+        RdkitSearchIndexFinalization.register(this, this.__wbg_ptr, this);
+        return this;
+    }
+    /**
+     * Search the prepared index with a query SMILES.
+     * @param {string} query_smiles
+     * @param {number} k
+     * @returns {string}
+     */
+    search_json(query_smiles, k) {
+        let deferred2_0;
+        let deferred2_1;
+        try {
+            const ptr0 = passStringToWasm0(query_smiles, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+            const len0 = WASM_VECTOR_LEN;
+            const ret = wasm.rdkitsearchindex_search_json(this.__wbg_ptr, ptr0, len0, k);
+            deferred2_0 = ret[0];
+            deferred2_1 = ret[1];
+            return getStringFromWasm0(ret[0], ret[1]);
+        } finally {
+            wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
+        }
+    }
+    /**
+     * Search without the historical six-decimal JSON score truncation.
+     *
+     * This opt-in endpoint is for exact parity measurements. Callers that
+     * need the stable historical wire format should continue using
+     * RdkitSearchIndex::search_json.
+     * @param {string} query_smiles
+     * @param {number} k
+     * @returns {string}
+     */
+    search_json_precise(query_smiles, k) {
+        let deferred2_0;
+        let deferred2_1;
+        try {
+            const ptr0 = passStringToWasm0(query_smiles, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+            const len0 = WASM_VECTOR_LEN;
+            const ret = wasm.rdkitsearchindex_search_json_precise(this.__wbg_ptr, ptr0, len0, k);
+            deferred2_0 = ret[0];
+            deferred2_1 = ret[1];
+            return getStringFromWasm0(ret[0], ret[1]);
+        } finally {
+            wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
+        }
+    }
+    /**
+     * Search with an inclusive Tanimoto threshold and precise JSON scores.
+     * A threshold of `0.0` includes zero-score candidates.
+     * @param {string} query_smiles
+     * @param {number} threshold
+     * @param {number} k
+     * @returns {string}
+     */
+    search_json_threshold_precise(query_smiles, threshold, k) {
+        let deferred2_0;
+        let deferred2_1;
+        try {
+            const ptr0 = passStringToWasm0(query_smiles, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+            const len0 = WASM_VECTOR_LEN;
+            const ret = wasm.rdkitsearchindex_search_json_threshold_precise(this.__wbg_ptr, ptr0, len0, threshold, k);
+            deferred2_0 = ret[0];
+            deferred2_1 = ret[1];
+            return getStringFromWasm0(ret[0], ret[1]);
+        } finally {
+            wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
+        }
+    }
+}
+if (Symbol.dispose) RdkitSearchIndex.prototype[Symbol.dispose] = RdkitSearchIndex.prototype.free;
+
 /**
  * Return a copy of the molecule with all implicit hydrogens converted to explicit H atoms.
  * @param {MolHandle} mol
@@ -1401,6 +1529,32 @@ export function canonicalize_smiles_batch_json(smiles_batch, delimiter) {
     }
 }
 
+/**
+ * Validate a versioned CDXML JSON envelope and serialize its exact source.
+ * @param {string} document_json
+ * @returns {string}
+ */
+export function cdxml_document_from_json_v1(document_json) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const ptr0 = passStringToWasm0(document_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.cdxml_document_from_json_v1(ptr0, len0);
+        var ptr2 = ret[0];
+        var len2 = ret[1];
+        if (ret[3]) {
+            ptr2 = 0; len2 = 0;
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        deferred3_0 = ptr2;
+        deferred3_1 = len2;
+        return getStringFromWasm0(ptr2, len2);
+    } finally {
+        wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+    }
+}
+
 /**
  * Parse a CDXML document while preserving page and presentation objects.
  * The returned JSON contains an opaque `raw_xml` for each object so unknown
@@ -1429,6 +1583,64 @@ export function cdxml_document_json(cdxml) {
     }
 }
 
+/**
+ * Return a loss-preserving, versioned JSON envelope for a CDXML document.
+ *
+ * `source` is retained for exact re-serialization; `document` is the stable
+ * structural summary used by editors. Unknown objects remain in the summary
+ * and are listed under `document.diagnostics`.
+ * @param {string} cdxml
+ * @returns {string}
+ */
+export function cdxml_document_json_v1(cdxml) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const ptr0 = passStringToWasm0(cdxml, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.cdxml_document_json_v1(ptr0, len0);
+        var ptr2 = ret[0];
+        var len2 = ret[1];
+        if (ret[3]) {
+            ptr2 = 0; len2 = 0;
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        deferred3_0 = ptr2;
+        deferred3_1 = len2;
+        return getStringFromWasm0(ptr2, len2);
+    } finally {
+        wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+    }
+}
+
+/**
+ * Project a CDXML document to its first molecular fragment only when no
+ * presentation data would be lost. Unknown/presentation objects are reported
+ * as an explicit lossy conversion instead of being silently dropped.
+ * @param {string} cdxml
+ * @returns {string}
+ */
+export function cdxml_document_projection_json_v1(cdxml) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const ptr0 = passStringToWasm0(cdxml, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.cdxml_document_projection_json_v1(ptr0, len0);
+        var ptr2 = ret[0];
+        var len2 = ret[1];
+        if (ret[3]) {
+            ptr2 = 0; len2 = 0;
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        deferred3_0 = ptr2;
+        deferred3_1 = len2;
+        return getStringFromWasm0(ptr2, len2);
+    } finally {
+        wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+    }
+}
+
 /**
  * Parse all molecular fragments from a CDXML string.
  *
@@ -2131,6 +2343,66 @@ export function edit_cdxml_document_json(cdxml, edit_json) {
     }
 }
 
+/**
+ * Apply a bounded CDXML edit to a versioned JSON envelope and return the
+ * updated envelope. The source is reparsed after editing, so paths and
+ * diagnostics cannot drift from the returned document summary.
+ * @param {string} document_json
+ * @param {string} edit_json
+ * @returns {string}
+ */
+export function edit_cdxml_document_json_v1(document_json, edit_json) {
+    let deferred4_0;
+    let deferred4_1;
+    try {
+        const ptr0 = passStringToWasm0(document_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(edit_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ret = wasm.edit_cdxml_document_json_v1(ptr0, len0, ptr1, len1);
+        var ptr3 = ret[0];
+        var len3 = ret[1];
+        if (ret[3]) {
+            ptr3 = 0; len3 = 0;
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        deferred4_0 = ptr3;
+        deferred4_1 = len3;
+        return getStringFromWasm0(ptr3, len3);
+    } finally {
+        wasm.__wbindgen_free(deferred4_0, deferred4_1, 1);
+    }
+}
+
+/**
+ * Apply a bounded, stable-ID reaction-document edit and return canonical JSON.
+ * @param {string} document_json
+ * @param {string} edit_json
+ * @returns {string}
+ */
+export function edit_reaction_document_json_v1(document_json, edit_json) {
+    let deferred4_0;
+    let deferred4_1;
+    try {
+        const ptr0 = passStringToWasm0(document_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(edit_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ret = wasm.edit_reaction_document_json_v1(ptr0, len0, ptr1, len1);
+        var ptr3 = ret[0];
+        var len3 = ret[1];
+        if (ret[3]) {
+            ptr3 = 0; len3 = 0;
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        deferred4_0 = ptr3;
+        deferred4_1 = len3;
+        return getStringFromWasm0(ptr3, len3);
+    } finally {
+        wasm.__wbindgen_free(deferred4_0, deferred4_1, 1);
+    }
+}
+
 /**
  * Run `embed_ensemble_v2` on `mol`'s own atom order (never canonicalizes/
  * reparses, same convention as `embed_pipeline_v2_json`). See the module doc
@@ -2854,6 +3126,31 @@ export function get_dihedral_json(smiles, a, b, c, d) {
     return ret;
 }
 
+/**
+ * RDKit-compatibility descriptor profile as JSON.
+ *
+ * This is deliberately separate from [`get_descriptors_json`]: the latter is
+ * the historical native profile, while this profile uses the opt-in RDKit
+ * molecular-weight, HBA, and aromatic-ring implementations.  Keeping the
+ * boundary explicit prevents a compatibility correction from silently
+ * changing the browser's native descriptor contract.
+ * @param {MolHandle} mol
+ * @returns {string}
+ */
+export function get_rdkit_descriptors_json(mol) {
+    let deferred1_0;
+    let deferred1_1;
+    try {
+        _assertClass(mol, MolHandle);
+        const ret = wasm.get_rdkit_descriptors_json(mol.__wbg_ptr);
+        deferred1_0 = ret[0];
+        deferred1_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+    }
+}
+
 /**
  * Compute GETAWAY descriptors (GEometry, Topology and Atom-Weights AssemblY) from 3D coords.
  *
@@ -3580,7 +3877,7 @@ export function minimize_mmff94_lbfgs_json(mol, max_iter) {
  * `coords_json` — JSON array of `[x,y,z]` arrays (Å), one per atom.
  * `max_iter` — maximum iterations (0 = default 500).
  *
- * Returns JSON: `{"coords":[[x,y,z],...], "energy":float, "iterations":int, "converged":bool, "sound":bool, "worst_bond_length":float}`
+ * Returns JSON: `{"coords":[[x,y,z],...], "energy":float, "iterations":int, "converged":bool, "sound":bool, "worst_bond_length":float, "rejected_unsound_step":bool}`
  * or `{"error":"<msg>"}` on failure. `sound` is all-finite coordinates and
  * no bond stretched past a sane covalent-bond length — independent of
  * `converged`, since steepest descent often reports `converged:false` on
@@ -4006,6 +4303,24 @@ export function mol_from_cml(cml) {
     return MolHandle.__wrap(ret[0]);
 }
 
+/**
+ * Parse a structurally valid, non-empty CML string into a `MolHandle`.
+ *
+ * This opt-in strict boundary rejects missing/empty molecules and malformed
+ * XML while `mol_from_cml` retains its historical lenient behavior.
+ * @param {string} cml
+ * @returns {MolHandle}
+ */
+export function mol_from_cml_strict(cml) {
+    const ptr0 = passStringToWasm0(cml, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.mol_from_cml_strict(ptr0, len0);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return MolHandle.__wrap(ret[0]);
+}
+
 /**
  * Parse a Gaussian Cube file and return a `MolHandle` (topology only --
  * element list, no bonds; Cube carries no bond table). Use
@@ -5432,6 +5747,36 @@ export function rdkit_ecfp_config_detail_json(mol, radius, nbits) {
     }
 }
 
+/**
+ * Find the k nearest neighbours using the RDKit-compatible Morgan/ECFP4
+ * profile. This is intentionally separate from [`nearest_neighbors_json`],
+ * whose historical contract uses chematic's native ECFP4 profile.
+ *
+ * Returns JSON with the original database indices and six-decimal Tanimoto
+ * scores. Any RDKit-profile preprocessing failure is returned as an error;
+ * this API never falls back to the native profile.
+ * @param {string} query_smiles
+ * @param {string} db_smiles_json
+ * @param {number} k
+ * @returns {string}
+ */
+export function rdkit_nearest_neighbors_json(query_smiles, db_smiles_json, k) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const ptr0 = passStringToWasm0(query_smiles, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(db_smiles_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ret = wasm.rdkit_nearest_neighbors_json(ptr0, len0, ptr1, len1, k);
+        deferred3_0 = ret[0];
+        deferred3_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+    }
+}
+
 /**
  * Compute the RDKit-compatible Daylight-like path fingerprint as a bit-packed
  * byte vector (256 bytes = 2048 bits). This is the WASM counterpart of the
@@ -5478,6 +5823,63 @@ export function rdkit_torsion_bitvec(mol) {
     return v1;
 }
 
+/**
+ * Validate and deterministically serialize a rich reaction document JSON.
+ *
+ * This is the versioned JSON boundary for WASM consumers. It preserves IDs,
+ * metadata, and provenance, and rejects malformed documents before returning
+ * JSON. Use [`edit_reaction_document_json_v1`] for bounded ID-addressed edits.
+ * @param {string} document_json
+ * @returns {string}
+ */
+export function reaction_document_json_v1(document_json) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const ptr0 = passStringToWasm0(document_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.reaction_document_json_v1(ptr0, len0);
+        var ptr2 = ret[0];
+        var len2 = ret[1];
+        if (ret[3]) {
+            ptr2 = 0; len2 = 0;
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        deferred3_0 = ptr2;
+        deferred3_1 = len2;
+        return getStringFromWasm0(ptr2, len2);
+    } finally {
+        wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+    }
+}
+
+/**
+ * Convert a rich reaction document to legacy RXN V2000 with structured loss
+ * reporting. A lossy projection is never returned as if it were complete.
+ * @param {string} document_json
+ * @returns {string}
+ */
+export function reaction_document_to_rxn_v1(document_json) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const ptr0 = passStringToWasm0(document_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.reaction_document_to_rxn_v1(ptr0, len0);
+        var ptr2 = ret[0];
+        var len2 = ret[1];
+        if (ret[3]) {
+            ptr2 = 0; len2 = 0;
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        deferred3_0 = ptr2;
+        deferred3_1 = len2;
+        return getStringFromWasm0(ptr2, len2);
+    } finally {
+        wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+    }
+}
+
 /**
  * Check whether a reaction SMILES matches a reaction SMARTS query.
  *
@@ -5636,13 +6038,13 @@ export function ring_families_json(mol) {
 }
 
 /**
- * Parse and serialize a V3000 block while preserving opaque V3000 metadata.
+ * Parse and serialize a V3000 block while preserving V3000 metadata.
  *
  * Unlike the topology-only [`mol_from_v3000_block`] + [`to_mol_v3000_block`]
  * pair, this explicit round-trip API retains `SGROUP` logical lines and
- * `COLLECTION` stereo groups. SGROUP semantics remain opaque until the core
- * molecule model grows a typed representation; the API therefore preserves
- * bytes at the logical-line level without claiming polymer/query semantics.
+ * `COLLECTION` stereo groups. SGROUP polymer/query expansion is still out of
+ * scope, but the typed syntax view is available through
+ * [`v3000_sgroups_json`].
  * @param {string} block
  * @returns {string}
  */
@@ -6919,6 +7321,31 @@ export function torsion_bitvec(mol) {
     return v1;
 }
 
+/**
+ * @param {string} block
+ * @returns {string}
+ */
+export function v3000_sgroups_json(block) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const ptr0 = passStringToWasm0(block, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.v3000_sgroups_json(ptr0, len0);
+        var ptr2 = ret[0];
+        var len2 = ret[1];
+        if (ret[3]) {
+            ptr2 = 0; len2 = 0;
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        deferred3_0 = ptr2;
+        deferred3_1 = len2;
+        return getStringFromWasm0(ptr2, len2);
+    } finally {
+        wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+    }
+}
+
 /**
  * Validate a vendor-neutral NMR spectrum JSON document without parsing a
  * vendor-specific raw file or predicting peaks.
@@ -7463,6 +7890,9 @@ const MhfpLshHandleFinalization = (typeof FinalizationRegistry === 'undefined')
 const MolHandleFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(ptr => wasm.__wbg_molhandle_free(ptr, 1));
+const RdkitSearchIndexFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_rdkitsearchindex_free(ptr, 1));
 
 function addToExternrefTable0(obj) {
     const idx = wasm.__externref_table_alloc();

package/package.json

@@ -5,7 +5,7 @@
     "Kentaro Tanabe (kent-tokyo) <kent-tokyo@users.noreply.github.com>"
   ],
   "description": "WebAssembly bindings for chematic — use chematic from JavaScript/TypeScript",
-  "version": "1.0.12",
+  "version": "1.0.14",
   "license": "MIT OR Apache-2.0",
   "repository": {
     "type": "git",