@cosmol-studio/cosmolkit-core-3d 0.5.1-rc.3 → 0.6.0-dev.1

package/README.md

@@ -1,245 +1,25 @@
-# COSMolKit WASM
+# COSMolKit for JavaScript and TypeScript
 
-`@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
+WebAssembly bindings to the public Rust API, with generated TypeScript declarations.
 
 ```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";
+```typescript
+import init, { molFromSmiles } 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>
+const mol = molFromSmiles("CCO");
+console.log(mol.toSmiles());
+console.log(mol.numAtoms);
+mol.free();
 ```
 
-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.
-
-In-place molecule operations retain the trailing `_` in JavaScript, such as
-`addHydrogens_()` and `add2dCoordinates_()`. Their configured forms also retain
-it: `add2dCoordinatesWithParams_(params)`. Use `with2dCoordinates()` or
-`with2dCoordinatesWithParams(params)` when a new molecule is required.
-
-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:
+Use the full package above or select a smaller
+[feature package](https://kit.cosmol.org/javascript/).
+Native objects retain Rust ownership and copy-on-write behavior.
+Params accept typed options or parameter instances; invalid inputs throw typed errors.
 
-- [`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)
+[API and examples](https://kit.cosmol.org/javascript/api) ·
+[Build and development](https://github.com/cosmol-studio/COSMolKit/blob/main/wasm/dev.md) · [Binding contract](https://github.com/cosmol-studio/COSMolKit/blob/main/wasm/BINDING_CONTRACT.md)