@cosmol-studio/cosmolkit 0.0.0-stage → 0.5.0-rc.13

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 COSMolKit Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,195 @@
-# Temporary Holding Version
+# COSMolKit WASM
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@cosmol-studio/cosmolkit` is the WebAssembly projection of the Rust `cosmolkit` facade. The
+package uses the `wasm-bindgen` `web` target and exposes an opaque
+`Molecule` value. Parsing and chemistry errors are thrown as JavaScript
+exceptions; successful methods return strings, numbers, typed arrays, or new
+`Molecule` values.
+
+## Install
+
+```bash
+npm install @cosmol-studio/cosmolkit
+```
+
+The package is browser/bundler-oriented. It can be used from Vite, webpack,
+Rollup, and other tools that support the web `WebAssembly` target.
+
+## Native JavaScript
+
+Initialize the module once before using `Molecule`:
+
+```js
+import init, { Molecule } from "@cosmol-studio/cosmolkit";
+
+await init();
+
+const molecule = Molecule.fromSmiles("CCO");
+console.log(molecule.toSmiles());
+console.log(molecule.numAtoms());
+molecule.free();
+```
+
+The published npm package is scoped as `@cosmol-studio/cosmolkit`. The Rust
+binding crate remains `cosmolkit-wasm` internally.
+
+## Native JavaScript From A CDN
+
+For a browser page that does not use a bundler, import the generated web
+module from jsDelivr. Pin the package version in production and keep the
+background `.wasm` file on the same CDN host:
+
+```html
+<div id="molecule"></div>
+<script type="module">
+  import init, { Molecule } from
+    "https://cdn.jsdelivr.net/npm/@cosmol-studio/cosmolkit@0.3.0/wasm_wasm.js";
+
+  await init(
+    "https://cdn.jsdelivr.net/npm/@cosmol-studio/cosmolkit@0.3.0/wasm_wasm_bg.wasm",
+  );
+  const molecule = Molecule.fromSmiles("c1ccccc1O");
+  document.querySelector("#molecule").textContent = molecule.toSmiles();
+  molecule.free();
+</script>
+```
+
+The generated wasm-bindgen module is currently named `wasm_wasm.js` because
+Alef derives the generated Cargo package from the `wasm/` source directory.
+The package export remains `Molecule`; the generated filename is an artifact
+of the binding build and should be updated here if that output layout changes.
+
+More focused examples are in [`examples/vanilla`](./examples/vanilla/):
+
+- [`basic.js`](./examples/vanilla/basic.js): parse, write, and render SVG.
+- [`cdn.html`](./examples/vanilla/cdn.html): run the web module directly from
+  jsDelivr without a bundler.
+- [`descriptors.js`](./examples/vanilla/descriptors.js): descriptors and typed
+  coordinate arrays.
+- [`fingerprints.js`](./examples/vanilla/fingerprints.js): typed fingerprint
+  bit vectors.
+- [`binary.js`](./examples/vanilla/binary.js): binary serialization roundtrip.
+- [`substructure.js`](./examples/vanilla/substructure.js): SMARTS matching and
+  disconnected fragments.
+- [`stereo.js`](./examples/vanilla/stereo.js): stereochemistry and conformers.
+
+## React
+
+The React example keeps initialization and molecule ownership in component
+state. It does not call the Rust API during render:
+
+```jsx
+import { useEffect, useState } from "react";
+import init, { Molecule } from "@cosmol-studio/cosmolkit";
+
+export function MoleculePanel({ smiles }) {
+  const [ready, setReady] = useState(false);
+  const [molecule, setMolecule] = useState(null);
+  const [error, setError] = useState(null);
+
+  useEffect(() => {
+    let active = true;
+    init()
+      .then(() => {
+        if (active) setReady(true);
+      })
+      .catch((value) => {
+        if (active) setError(String(value));
+      });
+    return () => {
+      active = false;
+    };
+  }, []);
+
+  useEffect(() => {
+    if (!ready) return;
+    try {
+      const next = Molecule.fromSmiles(smiles);
+      setMolecule(next);
+      setError(null);
+    } catch (value) {
+      setError(String(value));
+    }
+  }, [ready, smiles]);
+
+  useEffect(() => () => molecule?.free(), [molecule]);
+
+  if (error) return <pre>{error}</pre>;
+  if (!molecule) return <p>Loading COSMolKit...</p>;
+  return <output>{molecule.toSmiles()} ({molecule.numAtoms()} atoms)</output>;
+}
+```
+
+The complete copyable component is
+[`examples/react/MoleculePanel.jsx`](./examples/react/MoleculePanel.jsx).
+
+## Vue
+
+Vue applications should initialize in `onMounted` and replace the previous
+opaque value when the input changes:
+
+```vue
+<script setup>
+import { onBeforeUnmount, onMounted, ref, watch } from "vue";
+import init, { Molecule } from "@cosmol-studio/cosmolkit";
+
+const props = defineProps({ smiles: { type: String, default: "CCO" } });
+const molecule = ref(null);
+const error = ref("");
+
+async function update() {
+  try {
+    const next = Molecule.fromSmiles(props.smiles);
+    molecule.value?.free();
+    molecule.value = next;
+    error.value = "";
+  } catch (value) {
+    error.value = String(value);
+  }
+}
+
+onMounted(async () => {
+  try {
+    await init();
+    await update();
+  } catch (value) {
+    error.value = String(value);
+  }
+});
+watch(() => props.smiles, update);
+onBeforeUnmount(() => molecule.value?.free());
+</script>
+
+<template>
+  <pre v-if="error">{{ error }}</pre>
+  <output v-else-if="molecule">{{ molecule.toSmiles() }}</output>
+  <p v-else>Loading COSMolKit...</p>
+</template>
+```
+
+The complete component is [`examples/vue/MoleculePanel.vue`](./examples/vue/MoleculePanel.vue).
+
+## Ownership And Errors
+
+`Molecule` values own Rust allocations. Keep a value while it is in use and
+call `.free()` when a long-lived UI state or worker no longer needs it. Methods
+such as `withHydrogens()`, `with2dCoordinates()`, and
+`with3dConformer()` return new values and leave the source value unchanged.
+
+Fingerprint methods return `Uint32Array` set-bit lists. Coordinate methods
+return flattened `Float64Array` values. Binary serialization returns a
+`Uint8Array`, which can be stored or transferred through a worker.
+
+## Examples
+
+The examples are intentionally small and use only the published package:
+
+- [`examples/vanilla/basic.js`](./examples/vanilla/basic.js)
+- [`examples/vanilla/cdn.html`](./examples/vanilla/cdn.html)
+- [`examples/vanilla/descriptors.js`](./examples/vanilla/descriptors.js)
+- [`examples/vanilla/fingerprints.js`](./examples/vanilla/fingerprints.js)
+- [`examples/vanilla/binary.js`](./examples/vanilla/binary.js)
+- [`examples/vanilla/substructure.js`](./examples/vanilla/substructure.js)
+- [`examples/vanilla/stereo.js`](./examples/vanilla/stereo.js)
+- [`examples/react/MoleculePanel.jsx`](./examples/react/MoleculePanel.jsx)
+- [`examples/vue/MoleculePanel.vue`](./examples/vue/MoleculePanel.vue)

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "@cosmol-studio/cosmolkit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.5.0-rc.13",
+  "description": "WebAssembly bindings for COSMolKit",
+  "type": "module",
+  "main": "wasm_wasm.js",
+  "module": "wasm_wasm.js",
+  "types": "wasm_wasm.d.ts",
+  "exports": {
+    ".": {
+      "types": "./wasm_wasm.d.ts",
+      "default": "./wasm_wasm.js"
+    },
+    "./*": "./*"
+  },
+  "files": [
+    "*.js",
+    "*.d.ts",
+    "*.wasm",
+    "snippets",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cosmol-studio/COSMolKit"
+  }
+}

package/snippets/wasm-wasm-2e23ff5c4614b73b/inline0.js

@@ -0,0 +1 @@
+export function visitSdfReadParams(v,f){try{f(v);}catch(cause){throw new TypeError('invalid SdfReadParams',{cause});}}

package/snippets/wasm-wasm-2e23ff5c4614b73b/inline1.js

@@ -0,0 +1 @@
+export function visitScalarMorganparams(v,f){try{f(v);}catch(cause){throw new TypeError("invalid MorganParams",{cause});}} export function visitScalarMorganatom(v,f){try{f(v);}catch(cause){throw new TypeError("invalid MorganAtomInvariantsGenerator",{cause});}} export function visitScalarMorganbond(v,f){try{f(v);}catch(cause){throw new TypeError("invalid MorganBondInvariantsGenerator",{cause});}} export function visitScalarMorgancall(v,f){try{f(v);}catch(cause){throw new TypeError("invalid MorganCallParams",{cause});}} export function visitScalarMorganMolecule(v,f){try{f(v);}catch(cause){throw new TypeError("invalid Molecule",{cause});}}

package/snippets/wasm-wasm-2e23ff5c4614b73b/inline10.js

@@ -0,0 +1 @@
+export function visitMorganParams(v,f){try{f(v);}catch(cause){throw new TypeError('invalid MorganParams',{cause});}} export function visitMorganInvariants(v,f){try{f(v);}catch(cause){throw new TypeError('invalid MorganInvariants',{cause});}} export function visitMorganQuery(v,f){try{f(v);}catch(cause){throw new TypeError('invalid QueryGraph',{cause});}} export function visitMorganAtom(v,f){try{f(v);}catch(cause){throw new TypeError('invalid MorganAtomInvariantsGenerator',{cause});}} export function visitMorganBond(v,f){try{f(v);}catch(cause){throw new TypeError('invalid MorganBondInvariantsGenerator',{cause});}}

package/snippets/wasm-wasm-2e23ff5c4614b73b/inline11.js

@@ -0,0 +1 @@
+export function visitMol2Params(v,f){try{f(v);}catch(cause){throw new TypeError('invalid Mol2ReadParams',{cause});}} export function visitXyzParams(v,f){try{f(v);}catch(cause){throw new TypeError('invalid XyzWriteParams',{cause});}}

package/snippets/wasm-wasm-2e23ff5c4614b73b/inline12.js

@@ -0,0 +1 @@
+export function visitFingerprintAdditionalOutput(value,visit){try{visit(value);}catch(cause){throw new TypeError('invalid FingerprintAdditionalOutput',{cause});}}

package/snippets/wasm-wasm-2e23ff5c4614b73b/inline13.js

@@ -0,0 +1 @@
+export function visit_sanitize_operations(value, visit) { try { visit(value); } catch (cause) { throw new TypeError('invalid SanitizeOperations', { cause }); } }

package/snippets/wasm-wasm-2e23ff5c4614b73b/inline14.js

@@ -0,0 +1 @@
+export function visitBioMoleculeParams(v,f){try{f(v);}catch(cause){throw new TypeError('invalid BioMoleculeParams',{cause});}}

package/snippets/wasm-wasm-2e23ff5c4614b73b/inline15.js

@@ -0,0 +1 @@
+export function visit_batch_records(records, visit) { for (const record of records) visit(record); }

package/snippets/wasm-wasm-2e23ff5c4614b73b/inline16.js

@@ -0,0 +1 @@
+export function visitDistanceMatrix3dParams(v,f){try{f(v);}catch(cause){throw new TypeError('invalid DistanceMatrix3dParams',{cause});}}

package/snippets/wasm-wasm-2e23ff5c4614b73b/inline17.js

@@ -0,0 +1 @@
+export function visitDistanceMatrixParams(v,f){try{f(v);}catch(cause){throw new TypeError('invalid DistanceMatrixParams',{cause});}}

package/snippets/wasm-wasm-2e23ff5c4614b73b/inline18.js

@@ -0,0 +1 @@
+export function visitMolSelection(v,f){try{f(v);}catch(cause){throw new TypeError('invalid MolCoordinateSelection',{cause});}} export function visitMolWriteParams(v,f){try{f(v);}catch(cause){throw new TypeError('invalid MolBlockWriteParams',{cause});}} export function visitMolQuery(v,f){try{f(v);}catch(cause){throw new TypeError('invalid QueryGraph',{cause});}} export function visitMolProperties(v,f){try{f(v);}catch(cause){throw new TypeError('invalid MoleculeProperties',{cause});}}

package/snippets/wasm-wasm-2e23ff5c4614b73b/inline19.js

@@ -0,0 +1 @@
+export function visitLayeredMask(value,visit){try{visit(value);}catch(cause){throw new TypeError('invalid Fingerprint',{cause});}}

package/snippets/wasm-wasm-2e23ff5c4614b73b/inline2.js

@@ -0,0 +1 @@
+export function attachProteinIterator(v) { Object.defineProperty(v, Symbol.iterator, {value: function() { return this; }}); return v; }

package/snippets/wasm-wasm-2e23ff5c4614b73b/inline20.js

@@ -0,0 +1 @@
+export function visitBioAltloc(v,f){try{f(v);}catch(cause){throw new TypeError('invalid AltLocLabel',{cause});}} export function visitBioElement(v,f){try{f(v);}catch(cause){throw new TypeError('invalid Element',{cause});}}

package/snippets/wasm-wasm-2e23ff5c4614b73b/inline21.js

@@ -0,0 +1 @@
+export function visitSupplierParams(v,f){try{f(v);}catch(cause){throw new TypeError('invalid SdfReadParams',{cause});}} export function attachSdfIterator(v){Object.defineProperty(v,Symbol.iterator,{value:function(){return this;}});return v;}

package/snippets/wasm-wasm-2e23ff5c4614b73b/inline22.js

@@ -0,0 +1 @@
+export function visitSearchCompiledQuery(v,f){try{f(v);}catch(cause){throw new TypeError('invalid CompiledQuery',{cause});}}

package/snippets/wasm-wasm-2e23ff5c4614b73b/inline23.js

@@ -0,0 +1 @@
+export function visitSearchSmartsWriteParams(v,f){try{f(v);}catch(cause){throw new TypeError('invalid SmartsWriteParams',{cause});}}

package/snippets/wasm-wasm-2e23ff5c4614b73b/inline24.js

@@ -0,0 +1 @@
+export function visitSearchSubstructMatchParams(v,f){try{f(v);}catch(cause){throw new TypeError('invalid SubstructMatchParams',{cause});}}

package/snippets/wasm-wasm-2e23ff5c4614b73b/inline25.js

@@ -0,0 +1 @@
+export function visitSearchQueryGraph(v,f){try{f(v);}catch(cause){throw new TypeError('invalid QueryGraph',{cause});}}

package/snippets/wasm-wasm-2e23ff5c4614b73b/inline26.js

@@ -0,0 +1 @@
+export function visitReactionQuery(v,f){try{f(v);}catch(cause){throw new TypeError('invalid QueryGraph',{cause});}}

package/snippets/wasm-wasm-2e23ff5c4614b73b/inline27.js

@@ -0,0 +1 @@
+export function visitReactionMolecule(v,f){try{f(v);}catch(cause){throw new TypeError('invalid Molecule',{cause});}}

package/snippets/wasm-wasm-2e23ff5c4614b73b/inline28.js

@@ -0,0 +1 @@
+export function visitTorsionParams(value,visit){try { visit(value); } catch(cause) { throw new TypeError('invalid AtomPair parameter', {cause}); }} export function visitTorsionInvariants(value,visit){try { visit(value); } catch(cause) { throw new TypeError('invalid AtomPair parameter', {cause}); }}

package/snippets/wasm-wasm-2e23ff5c4614b73b/inline29.js

@@ -0,0 +1 @@
+export function visitHydrogenAddParams(v,f){try{f(v);}catch(cause){throw new TypeError('invalid AddHsParams',{cause});}} export function visitHydrogenRemoveParams(v,f){try{f(v);}catch(cause){throw new TypeError('invalid RemoveHsParams',{cause});}}

package/snippets/wasm-wasm-2e23ff5c4614b73b/inline3.js

@@ -0,0 +1 @@
+export function visitSanitizeParams(v,f){try{f(v);}catch(cause){throw new TypeError('invalid SanitizeParams',{cause});}}

package/snippets/wasm-wasm-2e23ff5c4614b73b/inline30.js

@@ -0,0 +1 @@
+export function visitScalarTopologicalTorsionparams(v,f){try{f(v);}catch(cause){throw new TypeError("invalid TopologicalTorsionParams",{cause});}} export function visitScalarTopologicalTorsionatom(v,f){try{f(v);}catch(cause){throw new TypeError("invalid AtomPairAtomInvariantsGenerator",{cause});}} export function visitScalarTopologicalTorsioncall(v,f){try{f(v);}catch(cause){throw new TypeError("invalid TopologicalTorsionCallParams",{cause});}} export function visitScalarTopologicalTorsionMolecule(v,f){try{f(v);}catch(cause){throw new TypeError("invalid Molecule",{cause});}}

package/snippets/wasm-wasm-2e23ff5c4614b73b/inline31.js

@@ -0,0 +1 @@
+export function visitGroupId(v,f){try{f(v);}catch(cause){throw new TypeError('invalid SubstanceGroupId',{cause});}} export function visitGroupKind(v,f){try{f(v);}catch(cause){throw new TypeError('invalid SubstanceGroupKind',{cause});}}

package/snippets/wasm-wasm-2e23ff5c4614b73b/inline32.js

@@ -0,0 +1 @@
+export function visit_execution(value, visit) { try { visit(value); } catch (cause) { throw new TypeError('invalid BatchParams', { cause }); } }

package/snippets/wasm-wasm-2e23ff5c4614b73b/inline4.js

@@ -0,0 +1 @@
+export function visitReactionCxSmilesFields(v,f){try{f(v);}catch(cause){throw new TypeError('invalid CxSmilesFields',{cause});}}

package/snippets/wasm-wasm-2e23ff5c4614b73b/inline5.js

@@ -0,0 +1 @@
+export function visitReactionCoordinateSelection(v,f){try{f(v);}catch(cause){throw new TypeError('invalid ReactionCoordinateSelection',{cause});}}

package/snippets/wasm-wasm-2e23ff5c4614b73b/inline6.js

@@ -0,0 +1 @@
+export function visitRingSearchParams(v,f){try{f(v);}catch(cause){throw new TypeError('invalid RingSearchParams',{cause});}}

package/snippets/wasm-wasm-2e23ff5c4614b73b/inline7.js

@@ -0,0 +1 @@
+export function visitAtomPairParams(value,visit){try { visit(value); } catch(cause) { throw new TypeError('invalid AtomPair parameter', {cause}); }} export function visitAtomPairInvariants(value,visit){try { visit(value); } catch(cause) { throw new TypeError('invalid AtomPair parameter', {cause}); }}

package/snippets/wasm-wasm-2e23ff5c4614b73b/inline8.js

@@ -0,0 +1 @@
+export function visitSdfBatchRead(v,f){try{f(v);}catch(cause){throw new TypeError('invalid SdfReadParams',{cause});}} export function visitSdfBatchExport(v,f){try{f(v);}catch(cause){throw new TypeError('invalid BatchExportParams',{cause});}} export function visitSdfDataset(v,f){try{f(v);}catch(cause){throw new TypeError('invalid SdfDataset',{cause});}} export function attachSdfBatchIterator(v){Object.defineProperty(v,Symbol.iterator,{value:function(){return this;}});return v;}

package/snippets/wasm-wasm-2e23ff5c4614b73b/inline9.js

@@ -0,0 +1 @@
+export function visitKekulizeParams(v,f){try{f(v);}catch(cause){throw new TypeError('invalid KekulizeParams',{cause});}}