@kent-tokyo/chematic 0.8.0 → 0.9.0

package/README.md

@@ -30,6 +30,10 @@ npm install @kent-tokyo/chematic
 - SVG grid layout for multiple molecules
 - Reaction SMILES/SMIRKS parsing and transform
 - Add/remove explicit hydrogens
+- `embed_pipeline_v2_json`: torsion-knowledge-aware 3D embedding + stereo
+  verification/repair + policy-gated force field, mirroring the Python
+  `Mol.embed_pipeline_v2()` binding — opt-in, not a default 3D API
+  ([usage](#3d-embedding-embed_pipeline_v2_json))
 
 ## Usage
 
@@ -96,6 +100,43 @@ const ifg = JSON.parse(identify_functional_groups(mol));
 console.log(ifg); // [{"atoms":[1,2,3],"types":"OC=O"}, ...]
 ```
 
+### 3D embedding (`embed_pipeline_v2_json`)
+
+Opt-in — does not change behavior of any existing 3D API (`generate_coords`,
+`generate_and_minimize_*`, etc.), which remain the defaults.
+
+```js
+const response = JSON.parse(embed_pipeline_v2_json(mol, JSON.stringify({
+  embedSeed: 7,
+  maxAttempts: 8,
+  embedTimeoutMs: null,
+  useExpTorsions: false,
+  useSmallRingTorsions: false,
+  useMacrocycleTorsions: false,
+  useMacrocycle14Bounds: false,
+  includeLegacyTorsionHeuristic: false,
+  stereoPolicy: "ignore",
+  failOnUnevaluableStereo: false,
+  forceFieldPolicy: "none",
+  forceFieldMaxIterations: 200,
+  gateMmff94TorsionOop: false,
+  ringTorsionPolicy: "fail_closed",
+  totalTimeoutMs: null,
+})));
+// response.ok, response.result / response.error — same shape as
+// Mol.embed_pipeline_v2() in the Python binding.
+```
+
+Verified working end-to-end under real WASM (both `wasm-pack --target nodejs`
+and `--target web`, the latter being what this package's npm build actually
+uses) — success, typed-failure, and typed-timeout paths all return real
+results. `embedTimeoutMs`/`totalTimeoutMs` use a monotonic clock that's
+portable across native and `wasm32-unknown-unknown`
+([`web-time`](https://crates.io/crates/web-time), backed by
+`Performance.now()` in the browser); this does not claim identical wall-clock
+precision across every JS engine, only that the value is finite, non-negative,
+and enforced correctly on all of them.
+
 ## Version History
 
 **v0.1.94** (2026-06-12):

package/chematic_wasm.d.ts

@@ -790,6 +790,25 @@ export function ecfp6_bitvec_with_chirality(mol: MolHandle, use_chirality: boole
  */
 export function ecfp_bitvec_custom(mol: MolHandle, radius: number, nbits: number, use_chirality: boolean): Uint8Array;
 
+/**
+ * Run the opt-in v2 embedding pipeline, applied directly to `mol`'s own atom
+ * order (never canonicalizes/reparses -- see the module doc).
+ *
+ * `config_json` must be an object with exactly the 15 fields `PipelineV2Config`
+ * requires (camelCase keys: `embedSeed`, `maxAttempts`, `embedTimeoutMs`,
+ * `useExpTorsions`, `useSmallRingTorsions`, `useMacrocycleTorsions`,
+ * `useMacrocycle14Bounds`, `includeLegacyTorsionHeuristic`, `stereoPolicy`,
+ * `failOnUnevaluableStereo`, `forceFieldPolicy`, `forceFieldMaxIterations`,
+ * `gateMmff94TorsionOop`, `ringTorsionPolicy`, `totalTimeoutMs`) -- an unknown
+ * field, a missing field, an unknown `stereoPolicy`/`ringTorsionPolicy`/
+ * `forceFieldPolicy` string, or a wrong-typed/out-of-range integer all fail
+ * closed rather than silently defaulting.
+ *
+ * Never throws. Always returns a JSON string tagged with `schemaVersion: 1` and
+ * `ok: true`/`false` -- see the module doc for both shapes.
+ */
+export function embed_pipeline_v2_json(mol: MolHandle, config_json: string): string;
+
 /**
  * Enumerate a combinatorial library from a SMIRKS template and two fragment sets.
  *
@@ -1612,6 +1631,32 @@ export function rdkit_ecfp_config_detail_json(mol: MolHandle, radius: number, nb
  */
 export function remove_hydrogens(mol: MolHandle): MolHandle;
 
+/**
+ * Single-step retrosynthetic disconnection (issue #91).
+ *
+ * Thin wrapper around [`chematic_rxn::retro::retro_disconnect`] -- applies
+ * the same built-in 60-template SMIRKS library and returns identical
+ * disconnections (same templates, same precursor sets, same ordering:
+ * fewest precursors first) as the Rust and Python (`Mol.retro_disconnect()`)
+ * APIs. This function changes nothing about the underlying algorithm; it
+ * only serializes the result to JSON.
+ *
+ * `max_results` -- cap on returned disconnections (0 = unlimited).
+ *
+ * `reaction_class` -- filter to a single reaction class, or `""` for all
+ * classes. Valid values: `"AmideBond"`, `"Ester"`, `"Ether"`, `"CNBond"`,
+ * `"CCBond"`, `"CSBond"`, `"Other"`. An unrecognized non-empty value is a
+ * JS error (not silently ignored).
+ *
+ * JSON schema: array of
+ * `{"template":str,"reaction_class":str,"precursors":[str,...],"sa_scores":[number,...],"max_sa_score":number}`
+ * -- same field names as the Python binding's dict output. Returns `[]`
+ * when no template matches the molecule (e.g. it has no disconnectable
+ * bond the template library recognizes) -- a valid, non-error result,
+ * distinct from the `reaction_class` validation error above.
+ */
+export function retro_disconnect_json(mol: MolHandle, max_results: number, reaction_class: string): string;
+
 /**
  * Decompose a set of molecules against a core SMARTS, returning R-group SMILES.
  *
@@ -2047,6 +2092,7 @@ export interface InitOutput {
     readonly ecfp6_bitvec: (a: number) => [number, number];
     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 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];
     readonly enumerate_stereo_isomers_json: (a: number) => [number, number, number, number];
     readonly enumerate_tautomers_json: (a: number) => [number, number];
@@ -2217,6 +2263,7 @@ export interface InitOutput {
     readonly rdkit_ecfp_config_bitvec: (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 remove_hydrogens: (a: number) => number;
+    readonly retro_disconnect_json: (a: number, b: number, c: number, d: number) => [number, number, number, number];
     readonly rgroup_decompose_json: (a: number, b: number, c: number, d: number) => [number, number, number, number];
     readonly ring_families_json: (a: number) => [number, number, number, number];
     readonly run_reactants: (a: number, b: number, c: number, d: number) => [number, number, number, number];
@@ -2265,6 +2312,7 @@ export interface InitOutput {
     readonly start: () => void;
     readonly __wbindgen_malloc: (a: number, b: number) => number;
     readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+    readonly __externref_table_alloc: () => number;
     readonly __wbindgen_externrefs: WebAssembly.Table;
     readonly __wbindgen_free: (a: number, b: number, c: number) => void;
     readonly __externref_table_dealloc: (a: number) => void;

package/chematic_wasm.js

@@ -1886,6 +1886,42 @@ export function ecfp_bitvec_custom(mol, radius, nbits, use_chirality) {
     return v1;
 }
 
+/**
+ * Run the opt-in v2 embedding pipeline, applied directly to `mol`'s own atom
+ * order (never canonicalizes/reparses -- see the module doc).
+ *
+ * `config_json` must be an object with exactly the 15 fields `PipelineV2Config`
+ * requires (camelCase keys: `embedSeed`, `maxAttempts`, `embedTimeoutMs`,
+ * `useExpTorsions`, `useSmallRingTorsions`, `useMacrocycleTorsions`,
+ * `useMacrocycle14Bounds`, `includeLegacyTorsionHeuristic`, `stereoPolicy`,
+ * `failOnUnevaluableStereo`, `forceFieldPolicy`, `forceFieldMaxIterations`,
+ * `gateMmff94TorsionOop`, `ringTorsionPolicy`, `totalTimeoutMs`) -- an unknown
+ * field, a missing field, an unknown `stereoPolicy`/`ringTorsionPolicy`/
+ * `forceFieldPolicy` string, or a wrong-typed/out-of-range integer all fail
+ * closed rather than silently defaulting.
+ *
+ * Never throws. Always returns a JSON string tagged with `schemaVersion: 1` and
+ * `ok: true`/`false` -- see the module doc for both shapes.
+ * @param {MolHandle} mol
+ * @param {string} config_json
+ * @returns {string}
+ */
+export function embed_pipeline_v2_json(mol, config_json) {
+    let deferred2_0;
+    let deferred2_1;
+    try {
+        _assertClass(mol, MolHandle);
+        const ptr0 = passStringToWasm0(config_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.embed_pipeline_v2_json(mol.__wbg_ptr, ptr0, len0);
+        deferred2_0 = ret[0];
+        deferred2_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
+    }
+}
+
 /**
  * Enumerate a combinatorial library from a SMIRKS template and two fragment sets.
  *
@@ -4058,6 +4094,56 @@ export function remove_hydrogens(mol) {
     return MolHandle.__wrap(ret);
 }
 
+/**
+ * Single-step retrosynthetic disconnection (issue #91).
+ *
+ * Thin wrapper around [`chematic_rxn::retro::retro_disconnect`] -- applies
+ * the same built-in 60-template SMIRKS library and returns identical
+ * disconnections (same templates, same precursor sets, same ordering:
+ * fewest precursors first) as the Rust and Python (`Mol.retro_disconnect()`)
+ * APIs. This function changes nothing about the underlying algorithm; it
+ * only serializes the result to JSON.
+ *
+ * `max_results` -- cap on returned disconnections (0 = unlimited).
+ *
+ * `reaction_class` -- filter to a single reaction class, or `""` for all
+ * classes. Valid values: `"AmideBond"`, `"Ester"`, `"Ether"`, `"CNBond"`,
+ * `"CCBond"`, `"CSBond"`, `"Other"`. An unrecognized non-empty value is a
+ * JS error (not silently ignored).
+ *
+ * JSON schema: array of
+ * `{"template":str,"reaction_class":str,"precursors":[str,...],"sa_scores":[number,...],"max_sa_score":number}`
+ * -- same field names as the Python binding's dict output. Returns `[]`
+ * when no template matches the molecule (e.g. it has no disconnectable
+ * bond the template library recognizes) -- a valid, non-error result,
+ * distinct from the `reaction_class` validation error above.
+ * @param {MolHandle} mol
+ * @param {number} max_results
+ * @param {string} reaction_class
+ * @returns {string}
+ */
+export function retro_disconnect_json(mol, max_results, reaction_class) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        _assertClass(mol, MolHandle);
+        const ptr0 = passStringToWasm0(reaction_class, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.retro_disconnect_json(mol.__wbg_ptr, max_results, 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);
+    }
+}
+
 /**
  * Decompose a set of molecules against a core SMARTS, returning R-group SMILES.
  *
@@ -5108,6 +5194,10 @@ export function xlogp3_per_atom_json(mol) {
 function __wbg_get_imports() {
     const import0 = {
         __proto__: null,
+        __wbg___wbindgen_is_undefined_c05833b95a3cf397: function(arg0) {
+            const ret = arg0 === undefined;
+            return ret;
+        },
         __wbg___wbindgen_string_get_b0ca35b86a603356: function(arg0, arg1) {
             const obj = arg1;
             const ret = typeof(obj) === 'string' ? obj : undefined;
@@ -5122,6 +5212,30 @@ function __wbg_get_imports() {
         __wbg_error_744744ff0c9861e6: function(arg0) {
             console.error(arg0);
         },
+        __wbg_now_e7c6795a7f81e10f: function(arg0) {
+            const ret = arg0.now();
+            return ret;
+        },
+        __wbg_performance_3fcf6e32a7e1ed0a: function(arg0) {
+            const ret = arg0.performance;
+            return ret;
+        },
+        __wbg_static_accessor_GLOBAL_4ef717fb391d88b7: function() {
+            const ret = typeof global === 'undefined' ? null : global;
+            return isLikeNone(ret) ? 0 : addToExternrefTable0(ret);
+        },
+        __wbg_static_accessor_GLOBAL_THIS_8d1badc68b5a74f4: function() {
+            const ret = typeof globalThis === 'undefined' ? null : globalThis;
+            return isLikeNone(ret) ? 0 : addToExternrefTable0(ret);
+        },
+        __wbg_static_accessor_SELF_146583524fe1469b: function() {
+            const ret = typeof self === 'undefined' ? null : self;
+            return isLikeNone(ret) ? 0 : addToExternrefTable0(ret);
+        },
+        __wbg_static_accessor_WINDOW_f2829a2234d7819e: function() {
+            const ret = typeof window === 'undefined' ? null : window;
+            return isLikeNone(ret) ? 0 : addToExternrefTable0(ret);
+        },
         __wbindgen_cast_0000000000000001: function(arg0) {
             // Cast intrinsic for `F64 -> Externref`.
             const ret = arg0;
@@ -5161,6 +5275,12 @@ const MolHandleFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(ptr => wasm.__wbg_molhandle_free(ptr, 1));
 
+function addToExternrefTable0(obj) {
+    const idx = wasm.__externref_table_alloc();
+    wasm.__wbindgen_externrefs.set(idx, obj);
+    return idx;
+}
+
 function _assertClass(instance, klass) {
     if (!(instance instanceof klass)) {
         throw new Error(`expected instance of ${klass.name}`);

package/package.json

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