@cosmol-studio/cosmolkit-core-3d 0.0.0-stage → 0.5.0-rc.19

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,240 @@
-# 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 default package is **full**. Each smaller distribution has its own package
+name, so upgrading it cannot select a different feature combination:
+
+| Package name (under `@cosmol-studio/`) | Included public features |
+|---|---|
+| `cosmolkit-core` | `core`, including molecular IO and batch processing |
+| `cosmolkit-core-search` | `core + search` |
+| `cosmolkit-core-fingerprints` | `core + fingerprints` |
+| `cosmolkit-core-analysis` | `core + search + fingerprints + descriptors` |
+| `cosmolkit-core-reaction` | `core + reaction` (including search) |
+| `cosmolkit-core-depict` | `core + depict` |
+| `cosmolkit-core-3d` | `core + conformer` (including forcefields and alignment) |
+| `cosmolkit-core-bio` | `core + bio` |
+| `cosmolkit-core-inchi` | `core + inchi` |
+| `cosmolkit` | `full` |
+
+For example: `npm install @cosmol-studio/cosmolkit-core-bio`, then import from
+`"@cosmol-studio/cosmolkit-core-bio"`. Omitted domains are absent from both exports and TypeScript
+declarations; they are not runtime placeholders.
+
+WASM uses the Rust facade's feature tree, generated from its Cargo manifest.
+The platform exception is binary archives: `toBinary`/`fromBinary` and the
+binary-only encoding dependencies are not compiled, even in `full`.
+Query IO needs `search`; automatic 2D coordinate generation needs `depict`.
+Without these capabilities, shared IO entrypoints report an explicit error.
+
+All packages use the Rust release version, without a feature suffix. Stable
+releases update `latest`; RC releases update `rc`, not `latest`. To install an
+RC, use e.g. `npm install @cosmol-studio/cosmolkit-core-bio@rc`. Tags identify
+release channels, never feature combinations. Pin a version or use a lockfile
+for reproducible installs.
+
+Existing installations using feature dist-tags such as `cosmolkit@core-bio`
+must switch once to the corresponding package name. New releases do not update
+those old feature tags.
+
+InChI is available in `core-inchi` and the default full package:
+
+```js
+const molecule = Molecule.fromSmiles("CCO");
+console.log(molecule.toInchi());
+console.log(molecule.toInchiKey());
+const restored = Molecule.fromInchi(molecule.toInchi());
+restored.free();
+molecule.free();
+```
+
+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.5.0/wasm_wasm.js";
+
+  await init(
+    "https://cdn.jsdelivr.net/npm/@cosmol-studio/cosmolkit@0.5.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.
+- [`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. Native binary archives are intentionally
+not part of the WASM API.
+
+## 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/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,35 @@
 {
   "name": "@cosmol-studio/cosmolkit-core-3d",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.5.0-rc.19",
+  "cosmolkitPreset": "core-3d",
+  "cosmolkitVersion": "0.5.0-rc.19",
+  "publishConfig": {
+    "access": "public",
+    "tag": "rc"
+  },
+  "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-caf920d9aee5a9bb/inline0.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-caf920d9aee5a9bb/inline1.js

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

package/snippets/wasm-wasm-caf920d9aee5a9bb/inline10.js

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

package/snippets/wasm-wasm-caf920d9aee5a9bb/inline11.js

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

package/snippets/wasm-wasm-caf920d9aee5a9bb/inline12.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-caf920d9aee5a9bb/inline13.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-caf920d9aee5a9bb/inline2.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-caf920d9aee5a9bb/inline3.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-caf920d9aee5a9bb/inline4.js

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

package/snippets/wasm-wasm-caf920d9aee5a9bb/inline5.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-caf920d9aee5a9bb/inline6.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-caf920d9aee5a9bb/inline7.js

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

package/snippets/wasm-wasm-caf920d9aee5a9bb/inline8.js

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

package/snippets/wasm-wasm-caf920d9aee5a9bb/inline9.js

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