react-cheminfo 0.11.0 → 0.13.0

package/lib/molecule3d/ui/renderMolecule.js

@@ -0,0 +1,135 @@
+/**
+ * The 3D model of one molecule, built from an in-memory molfile.
+ *
+ * The whole molecule hangs off a single data node, and the drawn model hangs
+ * off the structure under it with a fixed ref of its own, so a surface can
+ * attach to the same atoms and loading another molecule deletes the subtree —
+ * surface included.
+ */
+import { createStructureRepresentationParams } from 'molstar/lib/mol-plugin-state/helpers/structure-representation-params.js';
+import { PluginStateObject } from 'molstar/lib/mol-plugin-state/objects.js';
+import { StructureFromModel } from 'molstar/lib/mol-plugin-state/transforms/model.js';
+import { StructureRepresentation3D } from 'molstar/lib/mol-plugin-state/transforms/representation.js';
+/** State-tree ref of the structure every representation hangs off. */
+export const MOLECULE_STRUCTURE_REF = 'molecule3d-structure';
+/** Root of the molecule subtree: deleting it removes model and surface. */
+const MOLECULE_DATA_REF = 'molecule3d-data';
+/** The drawn model, replaced in place whenever the style changes. */
+const MODEL_REPRESENTATION_REF = 'molecule3d-model';
+/**
+ * molstar's ball-and-stick radius factor that a size factor of 1 stands for:
+ * thin sticks and readable balls.
+ */
+const NATURAL_SIZE_FACTOR = 0.25;
+/** Bond radius as a fraction of the atom radius; molstar's own default. */
+const BALL_AND_STICK_ASPECT_RATIO = 2 / 3;
+/** Spacefill multiplies the van der Waals radius, whose honest value is 1. */
+const SPACEFILL_SCALE = 4;
+/** Sticks take the factor as a radius in ångström; 0.3 Å is licorice. */
+const STICK_SCALE = 1.2;
+/**
+ * Replace the displayed molecule. Everything already on screen goes first.
+ * @param plugin - The molstar context.
+ * @param molfile - Molfile text plus the format id.
+ * @param style - See {@link MoleculeStyle}.
+ * @returns Nothing; resolves once the model is on screen.
+ * @throws {Error} When the file parses to zero atoms. molstar's `mol` parser returns
+ * exactly that on a V3000 file, with no error, so without this check the viewer
+ * would show an empty scene and report nothing.
+ */
+export async function renderMolecule(plugin, molfile, style = {}) {
+    const { representation = 'ball-and-stick', sizeFactor = 1 } = style;
+    await clearMolecule(plugin);
+    const data = await plugin.builders.data.rawData({ data: molfile.data }, { ref: MOLECULE_DATA_REF, state: { isGhost: true } });
+    const trajectory = await plugin.builders.structure.parseTrajectory(data, molfile.format);
+    const model = await plugin.builders.structure.createModel(trajectory);
+    const atomCount = model.data?.atomicHierarchy.atoms._rowCount ?? 0;
+    if (atomCount === 0) {
+        await clearMolecule(plugin);
+        throw new Error(`molstar parsed 0 atoms from this ${molfile.format} file without reporting an error; a V3000 molfile must be parsed as "sdf".`);
+    }
+    await plugin
+        .build()
+        .to(model)
+        .apply(StructureFromModel, undefined, { ref: MOLECULE_STRUCTURE_REF })
+        .commit();
+    const structure = moleculeStructure(plugin);
+    if (structure === undefined) {
+        throw new Error('molstar built no structure from this molfile.');
+    }
+    await plugin
+        .build()
+        .to(MOLECULE_STRUCTURE_REF)
+        .applyOrUpdate(MODEL_REPRESENTATION_REF, StructureRepresentation3D, modelParams(plugin, structure, representation, sizeFactor * NATURAL_SIZE_FACTOR))
+        .commit();
+}
+/**
+ * Remove the molecule, and with it any surface drawn on the same atoms.
+ * @param plugin - The molstar context.
+ * @returns Nothing; resolves once the scene is empty.
+ */
+export async function clearMolecule(plugin) {
+    if (!plugin.state.data.cells.has(MOLECULE_DATA_REF))
+        return;
+    await plugin.build().delete(MOLECULE_DATA_REF).commit();
+}
+/**
+ * The atoms currently on screen, for anything that draws on top of them.
+ * @param plugin - The molstar context.
+ * @returns The loaded structure, or `undefined` when no molecule is displayed.
+ */
+export function moleculeStructure(plugin) {
+    const object = plugin.state.data.cells.get(MOLECULE_STRUCTURE_REF)?.obj;
+    if (!PluginStateObject.Molecule.Structure.is(object))
+        return undefined;
+    return object.data;
+}
+/**
+ * Translate one of the three representations into molstar's own. `stick` is a
+ * genuine licorice model: a uniform size theme and an aspect ratio of 1 give
+ * atoms and bonds one radius, so the joints are caps of the stick's thickness.
+ * @param plugin - The molstar context.
+ * @param structure - The atoms to draw.
+ * @param representation - Which representation.
+ * @param sizeFactor - molstar's own radius factor.
+ * @returns The parameters of the representation node.
+ */
+function modelParams(plugin, structure, representation, sizeFactor) {
+    const color = 'element-symbol';
+    const colorParams = {
+        carbonColor: { name: 'element-symbol', params: {} },
+    };
+    if (representation === 'spacefill') {
+        return createStructureRepresentationParams(plugin, structure, {
+            type: 'spacefill',
+            typeParams: { sizeFactor: sizeFactor * SPACEFILL_SCALE },
+            color,
+            colorParams,
+        });
+    }
+    if (representation === 'stick') {
+        return createStructureRepresentationParams(plugin, structure, {
+            type: 'ball-and-stick',
+            typeParams: {
+                sizeFactor: sizeFactor * STICK_SCALE,
+                sizeAspectRatio: 1,
+                aromaticBonds: false,
+            },
+            color,
+            colorParams,
+            size: 'uniform',
+            sizeParams: { value: 1 },
+        });
+    }
+    return createStructureRepresentationParams(plugin, structure, {
+        type: 'ball-and-stick',
+        typeParams: {
+            sizeFactor,
+            sizeAspectRatio: BALL_AND_STICK_ASPECT_RATIO,
+            aromaticBonds: false,
+        },
+        color,
+        colorParams,
+    });
+}
+//# sourceMappingURL=renderMolecule.js.map

package/lib/molecule3d/ui/renderMolecule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderMolecule.js","sourceRoot":"","sources":["../../../src/molecule3d/ui/renderMolecule.ts"],"names":[],"mappings":"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"}

package/lib/molecule3d/ui/renderSurface.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The translucent molecular surface drawn over the model. A second
+ * representation of the very structure the model is drawn from, with its own
+ * state-tree ref so it can be added, restyled and removed on its own.
+ */
+import type { PluginContext } from 'molstar/lib/mol-plugin/context.js';
+import type { SurfaceStyle } from './viewerTypes.ts';
+/**
+ * Add or restyle the molecular surface.
+ * @param plugin - The molstar context.
+ * @param style - See {@link SurfaceStyle}.
+ * @returns Nothing; resolves once the surface is on screen.
+ * @throws {Error} When no molecule is loaded — a surface needs atoms to wrap.
+ */
+export declare function renderSurface(plugin: PluginContext, style?: SurfaceStyle): Promise<void>;
+/**
+ * Remove the molecular surface, leaving the model in place.
+ * @param plugin - The molstar context.
+ * @returns Nothing; resolves once the surface is gone.
+ */
+export declare function clearSurface(plugin: PluginContext): Promise<void>;
+//# sourceMappingURL=renderSurface.d.ts.map

package/lib/molecule3d/ui/renderSurface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderSurface.d.ts","sourceRoot":"","sources":["../../../src/molecule3d/ui/renderSurface.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAavE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAKrD;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,aAAa,EACrB,KAAK,GAAE,YAAiB,GACvB,OAAO,CAAC,IAAI,CAAC,CA2Cf;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAGvE"}

package/lib/molecule3d/ui/renderSurface.js

@@ -0,0 +1,69 @@
+/**
+ * The translucent molecular surface drawn over the model. A second
+ * representation of the very structure the model is drawn from, with its own
+ * state-tree ref so it can be added, restyled and removed on its own.
+ */
+import { createStructureRepresentationParams } from 'molstar/lib/mol-plugin-state/helpers/structure-representation-params.js';
+import { StructureRepresentation3D } from 'molstar/lib/mol-plugin-state/transforms/representation.js';
+import { Color } from 'molstar/lib/mol-util/color/color.js';
+import { DEFAULT_MOLECULE_3D_SETTINGS } from "../core/settings.js";
+import { POLARITY_COLOR_THEME, registerPolarityTheme, } from "./polarityColorTheme.js";
+import { MOLECULE_STRUCTURE_REF, moleculeStructure } from "./renderMolecule.js";
+/** The surface node, replaced in place whenever the style changes. */
+const SURFACE_REF = 'molecule3d-surface';
+/**
+ * Add or restyle the molecular surface.
+ * @param plugin - The molstar context.
+ * @param style - See {@link SurfaceStyle}.
+ * @returns Nothing; resolves once the surface is on screen.
+ * @throws {Error} When no molecule is loaded — a surface needs atoms to wrap.
+ */
+export async function renderSurface(plugin, style = {}) {
+    const defaults = DEFAULT_MOLECULE_3D_SETTINGS;
+    const { probeRadius = defaults.probeRadius, alpha = defaults.surfaceAlpha, coloring = defaults.surfaceColoring, color = defaults.surfaceColor, } = style;
+    const structure = moleculeStructure(plugin);
+    if (structure === undefined) {
+        throw new Error('A molecular surface needs a molecule to wrap.');
+    }
+    const typeParams = { probeRadius, alpha };
+    let params;
+    if (coloring === 'element') {
+        params = createStructureRepresentationParams(plugin, structure, {
+            type: 'molecular-surface',
+            typeParams,
+            color: 'element-symbol',
+            colorParams: { carbonColor: { name: 'element-symbol', params: {} } },
+        });
+    }
+    else {
+        params = createStructureRepresentationParams(plugin, structure, {
+            type: 'molecular-surface',
+            typeParams,
+            color: 'uniform',
+            colorParams: { value: Color.fromHexStyle(color) },
+        });
+        if (coloring === 'polarity') {
+            registerPolarityTheme(plugin.representation.structure.themes.colorThemeRegistry);
+            params = {
+                ...params,
+                colorTheme: { name: POLARITY_COLOR_THEME, params: {} },
+            };
+        }
+    }
+    await plugin
+        .build()
+        .to(MOLECULE_STRUCTURE_REF)
+        .applyOrUpdate(SURFACE_REF, StructureRepresentation3D, params)
+        .commit();
+}
+/**
+ * Remove the molecular surface, leaving the model in place.
+ * @param plugin - The molstar context.
+ * @returns Nothing; resolves once the surface is gone.
+ */
+export async function clearSurface(plugin) {
+    if (!plugin.state.data.cells.has(SURFACE_REF))
+        return;
+    await plugin.build().delete(SURFACE_REF).commit();
+}
+//# sourceMappingURL=renderSurface.js.map

package/lib/molecule3d/ui/renderSurface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderSurface.js","sourceRoot":"","sources":["../../../src/molecule3d/ui/renderSurface.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,mCAAmC,EAAE,MAAM,yEAAyE,CAAC;AAC9H,OAAO,EAAE,yBAAyB,EAAE,MAAM,2DAA2D,CAAC;AAEtG,OAAO,EAAE,KAAK,EAAE,MAAM,qCAAqC,CAAC;AAE5D,OAAO,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AAEnE,OAAO,EACL,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAGhF,sEAAsE;AACtE,MAAM,WAAW,GAAG,oBAAoB,CAAC;AAEzC;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,MAAqB,EACrB,QAAsB,EAAE;IAExB,MAAM,QAAQ,GAAG,4BAA4B,CAAC;IAC9C,MAAM,EACJ,WAAW,GAAG,QAAQ,CAAC,WAAW,EAClC,KAAK,GAAG,QAAQ,CAAC,YAAY,EAC7B,QAAQ,GAAG,QAAQ,CAAC,eAAe,EACnC,KAAK,GAAG,QAAQ,CAAC,YAAY,GAC9B,GAAG,KAAK,CAAC;IACV,MAAM,SAAS,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAC5C,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;IACnE,CAAC;IACD,MAAM,UAAU,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;IAC1C,IAAI,MAA0D,CAAC;IAC/D,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,MAAM,GAAG,mCAAmC,CAAC,MAAM,EAAE,SAAS,EAAE;YAC9D,IAAI,EAAE,mBAAmB;YACzB,UAAU;YACV,KAAK,EAAE,gBAAgB;YACvB,WAAW,EAAE,EAAE,WAAW,EAAE,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE;SACrE,CAAC,CAAC;IACL,CAAC;SAAM,CAAC;QACN,MAAM,GAAG,mCAAmC,CAAC,MAAM,EAAE,SAAS,EAAE;YAC9D,IAAI,EAAE,mBAAmB;YACzB,UAAU;YACV,KAAK,EAAE,SAAS;YAChB,WAAW,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE;SAClD,CAAC,CAAC;QACH,IAAI,QAAQ,KAAK,UAAU,EAAE,CAAC;YAC5B,qBAAqB,CACnB,MAAM,CAAC,cAAc,CAAC,SAAS,CAAC,MAAM,CAAC,kBAAkB,CAC1D,CAAC;YACF,MAAM,GAAG;gBACP,GAAG,MAAM;gBACT,UAAU,EAAE,EAAE,IAAI,EAAE,oBAAoB,EAAE,MAAM,EAAE,EAAE,EAAE;aACvD,CAAC;QACJ,CAAC;IACH,CAAC;IACD,MAAM,MAAM;SACT,KAAK,EAAE;SACP,EAAE,CAAC,sBAAsB,CAAC;SAC1B,aAAa,CAAC,WAAW,EAAE,yBAAyB,EAAE,MAAM,CAAC;SAC7D,MAAM,EAAE,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,MAAqB;IACtD,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC;QAAE,OAAO;IACtD,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,MAAM,EAAE,CAAC;AACpD,CAAC"}

package/lib/molecule3d/ui/useControlledState.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A value a parent may own or leave to the component: when `value` is given
+ * it wins and changes are only reported; when it is not, the component keeps
+ * its own copy, starting from `initial`.
+ * @param value - The parent's value, or `undefined` to leave it uncontrolled.
+ * @param initial - Starting value of the component's own copy.
+ * @param onChange - Called with every change, controlled or not.
+ * @returns The current value and a setter.
+ */
+export declare function useControlledState<T>(value: T | undefined, initial: T | (() => T), onChange?: (value: T) => void): [T, (next: T) => void];
+//# sourceMappingURL=useControlledState.d.ts.map

package/lib/molecule3d/ui/useControlledState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useControlledState.d.ts","sourceRoot":"","sources":["../../../src/molecule3d/ui/useControlledState.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,KAAK,EAAE,CAAC,GAAG,SAAS,EACpB,OAAO,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,EACtB,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAC5B,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC,CAexB"}

package/lib/molecule3d/ui/useControlledState.js

@@ -0,0 +1,25 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+/**
+ * A value a parent may own or leave to the component: when `value` is given
+ * it wins and changes are only reported; when it is not, the component keeps
+ * its own copy, starting from `initial`.
+ * @param value - The parent's value, or `undefined` to leave it uncontrolled.
+ * @param initial - Starting value of the component's own copy.
+ * @param onChange - Called with every change, controlled or not.
+ * @returns The current value and a setter.
+ */
+export function useControlledState(value, initial, onChange) {
+    const [own, setOwn] = useState(initial);
+    const controlled = value !== undefined;
+    const onChangeRef = useRef(onChange);
+    useEffect(() => {
+        onChangeRef.current = onChange;
+    });
+    const set = useCallback((next) => {
+        if (!controlled)
+            setOwn(() => next);
+        onChangeRef.current?.(next);
+    }, [controlled]);
+    return [controlled ? value : own, set];
+}
+//# sourceMappingURL=useControlledState.js.map

package/lib/molecule3d/ui/useControlledState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useControlledState.js","sourceRoot":"","sources":["../../../src/molecule3d/ui/useControlledState.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEjE;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAAoB,EACpB,OAAsB,EACtB,QAA6B;IAE7B,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;IACxC,MAAM,UAAU,GAAG,KAAK,KAAK,SAAS,CAAC;IACvC,MAAM,WAAW,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;IACrC,SAAS,CAAC,GAAG,EAAE;QACb,WAAW,CAAC,OAAO,GAAG,QAAQ,CAAC;IACjC,CAAC,CAAC,CAAC;IACH,MAAM,GAAG,GAAG,WAAW,CACrB,CAAC,IAAO,EAAE,EAAE;QACV,IAAI,CAAC,UAAU;YAAE,MAAM,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;QACpC,WAAW,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC,EACD,CAAC,UAAU,CAAC,CACb,CAAC;IACF,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AACzC,CAAC"}

package/lib/molecule3d/ui/useImageExport.d.ts

@@ -0,0 +1,20 @@
+import type { RefObject } from 'react';
+import type { FigureFormat } from '../../download/core/downloadFigure.ts';
+import type { FigurePixels } from '../../download/core/figureScale.ts';
+import type { Molecule3DViewer } from './viewer.ts';
+/** What {@link useImageExport} hands the export panel. */
+export interface ImageExport {
+    /** Size of the canvas on screen, or `null` before it is laid out. */
+    canvasSize: () => FigurePixels | null;
+    /** Render the scene at `scale` and download it as `format`. */
+    exportImage: (format: FigureFormat, scale: number) => Promise<void>;
+}
+/**
+ * The two callbacks the export panel needs, bound to the canvas and its viewer.
+ * @param container - The element molstar draws into.
+ * @param viewerRef - The viewer, once created.
+ * @param fileName - File name without its extension.
+ * @returns See {@link ImageExport}.
+ */
+export declare function useImageExport(container: HTMLDivElement | null, viewerRef: RefObject<Molecule3DViewer | null>, fileName: string): ImageExport;
+//# sourceMappingURL=useImageExport.d.ts.map

package/lib/molecule3d/ui/useImageExport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useImageExport.d.ts","sourceRoot":"","sources":["../../../src/molecule3d/ui/useImageExport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGvC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AAC1E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAGvE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,0DAA0D;AAC1D,MAAM,WAAW,WAAW;IAC1B,qEAAqE;IACrE,UAAU,EAAE,MAAM,YAAY,GAAG,IAAI,CAAC;IACtC,+DAA+D;IAC/D,WAAW,EAAE,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACrE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,cAAc,GAAG,IAAI,EAChC,SAAS,EAAE,SAAS,CAAC,gBAAgB,GAAG,IAAI,CAAC,EAC7C,QAAQ,EAAE,MAAM,GACf,WAAW,CAqBb"}

package/lib/molecule3d/ui/useImageExport.js

@@ -0,0 +1,29 @@
+import { useCallback } from 'react';
+import { exportMoleculeImage } from "./exportMoleculeImage.js";
+/**
+ * The two callbacks the export panel needs, bound to the canvas and its viewer.
+ * @param container - The element molstar draws into.
+ * @param viewerRef - The viewer, once created.
+ * @param fileName - File name without its extension.
+ * @returns See {@link ImageExport}.
+ */
+export function useImageExport(container, viewerRef, fileName) {
+    const canvasSize = useCallback(() => {
+        if (container === null)
+            return null;
+        const box = container.getBoundingClientRect();
+        if (box.width <= 0 || box.height <= 0)
+            return null;
+        return { width: Math.round(box.width), height: Math.round(box.height) };
+    }, [container]);
+    const exportImage = useCallback(async (format, scale) => {
+        const viewer = viewerRef.current;
+        const size = canvasSize();
+        if (viewer === null || size === null) {
+            throw new Error('There is no picture to export yet.');
+        }
+        await exportMoleculeImage(viewer, { format, scale, size, fileName });
+    }, [canvasSize, viewerRef, fileName]);
+    return { canvasSize, exportImage };
+}
+//# sourceMappingURL=useImageExport.js.map

package/lib/molecule3d/ui/useImageExport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useImageExport.js","sourceRoot":"","sources":["../../../src/molecule3d/ui/useImageExport.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAKpC,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAW/D;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,SAAgC,EAChC,SAA6C,EAC7C,QAAgB;IAEhB,MAAM,UAAU,GAAG,WAAW,CAAC,GAAwB,EAAE;QACvD,IAAI,SAAS,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QACpC,MAAM,GAAG,GAAG,SAAS,CAAC,qBAAqB,EAAE,CAAC;QAC9C,IAAI,GAAG,CAAC,KAAK,IAAI,CAAC,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QACnD,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;IAC1E,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC;IAEhB,MAAM,WAAW,GAAG,WAAW,CAC7B,KAAK,EAAE,MAAoB,EAAE,KAAa,EAAE,EAAE;QAC5C,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC;QACjC,MAAM,IAAI,GAAG,UAAU,EAAE,CAAC;QAC1B,IAAI,MAAM,KAAK,IAAI,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YACrC,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;QACxD,CAAC;QACD,MAAM,mBAAmB,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;IACvE,CAAC,EACD,CAAC,UAAU,EAAE,SAAS,EAAE,QAAQ,CAAC,CAClC,CAAC;IAEF,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,CAAC;AACrC,CAAC"}

package/lib/molecule3d/ui/usePolarSurfaceArea.d.ts

@@ -0,0 +1,11 @@
+import type { Molecule3DFile } from '../core/settings.ts';
+/**
+ * Ertl's topological polar surface area of the molecule, from openchemlib,
+ * loaded only once a caller asks for it.
+ * @param molfile - The molecule, or `null`.
+ * @param enabled - Whether to compute it at all.
+ * @returns The area in Ų, or `null` while unknown, disabled, or when
+ * openchemlib is not installed or cannot read the molfile.
+ */
+export declare function usePolarSurfaceArea(molfile: Molecule3DFile | null, enabled: boolean): number | null;
+//# sourceMappingURL=usePolarSurfaceArea.d.ts.map

package/lib/molecule3d/ui/usePolarSurfaceArea.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePolarSurfaceArea.d.ts","sourceRoot":"","sources":["../../../src/molecule3d/ui/usePolarSurfaceArea.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,cAAc,GAAG,IAAI,EAC9B,OAAO,EAAE,OAAO,GACf,MAAM,GAAG,IAAI,CAmBf"}

package/lib/molecule3d/ui/usePolarSurfaceArea.js

@@ -0,0 +1,37 @@
+import { useEffect, useState } from 'react';
+/**
+ * Ertl's topological polar surface area of the molecule, from openchemlib,
+ * loaded only once a caller asks for it.
+ * @param molfile - The molecule, or `null`.
+ * @param enabled - Whether to compute it at all.
+ * @returns The area in Ų, or `null` while unknown, disabled, or when
+ * openchemlib is not installed or cannot read the molfile.
+ */
+export function usePolarSurfaceArea(molfile, enabled) {
+    const [result, setResult] = useState(null);
+    const data = enabled ? (molfile?.data ?? null) : null;
+    useEffect(() => {
+        if (data === null)
+            return;
+        let cancelled = false;
+        void computePolarSurfaceArea(data).then((area) => {
+            if (!cancelled)
+                setResult({ data, area });
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [data]);
+    return data !== null && result?.data === data ? result.area : null;
+}
+async function computePolarSurfaceArea(molfile) {
+    try {
+        const { Molecule, MoleculeProperties } = await import('openchemlib');
+        const molecule = Molecule.fromMolfile(molfile);
+        return new MoleculeProperties(molecule).polarSurfaceArea;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=usePolarSurfaceArea.js.map

package/lib/molecule3d/ui/usePolarSurfaceArea.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePolarSurfaceArea.js","sourceRoot":"","sources":["../../../src/molecule3d/ui/usePolarSurfaceArea.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAI5C;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAA8B,EAC9B,OAAgB;IAEhB,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,QAAQ,CAG1B,IAAI,CAAC,CAAC;IAChB,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAEtD,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO;QAC1B,IAAI,SAAS,GAAG,KAAK,CAAC;QACtB,KAAK,uBAAuB,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE;YAC/C,IAAI,CAAC,SAAS;gBAAE,SAAS,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5C,CAAC,CAAC,CAAC;QACH,OAAO,GAAG,EAAE;YACV,SAAS,GAAG,IAAI,CAAC;QACnB,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IAEX,OAAO,IAAI,KAAK,IAAI,IAAI,MAAM,EAAE,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AACrE,CAAC;AAED,KAAK,UAAU,uBAAuB,CACpC,OAAe;IAEf,IAAI,CAAC;QACH,MAAM,EAAE,QAAQ,EAAE,kBAAkB,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;QACrE,MAAM,QAAQ,GAAG,QAAQ,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QAC/C,OAAO,IAAI,kBAAkB,CAAC,QAAQ,CAAC,CAAC,gBAAgB,CAAC;IAC3D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/lib/molecule3d/ui/viewer.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Lifecycle of one molstar molecule viewer.
+ *
+ * `createMolecule3DViewer` is **synchronous** on purpose. React 19 runs an
+ * effect, its cleanup and the effect again on every mount in development, so an
+ * awaited constructor hands the cleanup nothing to dispose and leaks a WebGL
+ * context per mount. Returning the handle immediately means `dispose()` can
+ * always be called; the work is queued behind `ready`.
+ *
+ * molstar's own UI is not mounted: every control is the component's.
+ */
+import type { ImageSize } from '../core/exportImage.ts';
+import type { Measurement, MeasurementKind } from '../core/measurement.ts';
+import type { Molecule3DFile } from '../core/settings.ts';
+import type { Molecule3DViewerOptions, MoleculeStyle, SurfaceStyle } from './viewerTypes.ts';
+/**
+ * Create a viewer inside `container` and start initialising it.
+ * @param container - A positioned element; molstar inserts its canvas into it.
+ * @param options - See {@link Molecule3DViewerOptions}.
+ * @returns A handle that is safe to dispose immediately.
+ */
+export declare function createMolecule3DViewer(container: HTMLElement, options?: Molecule3DViewerOptions): Molecule3DViewer;
+/**
+ * One molstar canvas, and every operation the component performs on it. Every
+ * method resolves to nothing once `dispose` has been called.
+ */
+export declare class Molecule3DViewer {
+    #private;
+    /** Resolves once the canvas exists; every method awaits it internally. */
+    readonly ready: Promise<void>;
+    /**
+     * Mount the canvas and start initialising the plugin.
+     * @param container - A positioned element.
+     * @param options - See {@link Molecule3DViewerOptions}.
+     */
+    constructor(container: HTMLElement, options?: Molecule3DViewerOptions);
+    /**
+     * Replace the displayed molecule, clearing any surface and measurement.
+     * @param molfile - Molfile text plus format id.
+     * @param style - See {@link MoleculeStyle}.
+     * @returns Nothing; resolves once the model is on screen.
+     * @throws {Error} When the file parses to zero atoms.
+     */
+    showMolecule(molfile: Molecule3DFile, style?: MoleculeStyle): Promise<void>;
+    /**
+     * Empty the scene: the model, its surface and its measurements all go.
+     * @returns Nothing; resolves once the scene is empty.
+     */
+    hideMolecule(): Promise<void>;
+    /**
+     * Add or restyle the molecular surface over the current molecule.
+     * @param style - See {@link SurfaceStyle}.
+     * @returns Nothing; resolves once the surface is on screen.
+     */
+    showSurface(style?: SurfaceStyle): Promise<void>;
+    /**
+     * Remove the molecular surface, leaving the model in place.
+     * @returns Nothing; resolves once the surface is gone.
+     */
+    hideSurface(): Promise<void>;
+    /**
+     * Draw exactly these measurements over the current molecule.
+     * @param measurements - Replaces whatever is drawn.
+     * @returns Nothing; resolves once the labels are on screen.
+     */
+    showMeasurements(measurements: readonly Measurement[]): Promise<void>;
+    /**
+     * Make clicks on atoms build a measurement, or give them back to the camera.
+     * @param kind - The measurement to build, or `null`.
+     * @returns Nothing; resolves once the plugin has switched mode.
+     */
+    setMeasureKind(kind: MeasurementKind | null): Promise<void>;
+    /**
+     * Render the scene off screen at a given size, without the selection
+     * highlights or the axes.
+     * @param size - Pixel size of the picture.
+     * @returns The PNG as a data URI; `undefined` once the viewer is disposed.
+     * @throws {Error} When the plugin has no screenshot helper.
+     */
+    captureImage(size: ImageSize): Promise<string | undefined>;
+    /**
+     * Frame everything on screen.
+     * @param durationMilliseconds - Transition length; 0 jumps.
+     * @returns Nothing; resolves once the move has been ordered.
+     */
+    resetCamera(durationMilliseconds?: number): Promise<void>;
+    /**
+     * Turn the automatic spin on or off.
+     * @param spinning - Whether the scene should keep turning.
+     * @param speed - Turn rate, in molstar's own spin unit.
+     * @returns Nothing; resolves once the trackball has been reconfigured.
+     */
+    setSpin(spinning: boolean, speed?: number): Promise<void>;
+    /** Re-read the container's size. Call from a `ResizeObserver`. */
+    handleResize(): void;
+    /** Tear the viewer down and release its WebGL context. Idempotent. */
+    dispose(): void;
+}
+//# sourceMappingURL=viewer.d.ts.map

package/lib/molecule3d/ui/viewer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewer.d.ts","sourceRoot":"","sources":["../../../src/molecule3d/ui/viewer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC3E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAe1D,OAAO,KAAK,EACV,uBAAuB,EACvB,aAAa,EACb,YAAY,EACb,MAAM,kBAAkB,CAAC;AAE1B;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,WAAW,EACtB,OAAO,GAAE,uBAA4B,GACpC,gBAAgB,CAElB;AAED;;;GAGG;AACH,qBAAa,gBAAgB;;IAK3B,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9B;;;;OAIG;gBACS,SAAS,EAAE,WAAW,EAAE,OAAO,GAAE,uBAA4B;IAyBzE;;;;;;OAMG;IACH,YAAY,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAO3E;;;OAGG;IACH,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAO7B;;;;OAIG;IACH,WAAW,CAAC,KAAK,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhD;;;OAGG;IACH,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;;;OAIG;IACH,gBAAgB,CAAC,YAAY,EAAE,SAAS,WAAW,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrE;;;;OAIG;IACH,cAAc,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAM3D;;;;;;OAMG;IACH,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAgB1D;;;;OAIG;IACH,WAAW,CAAC,oBAAoB,SAA0B,GAAG,OAAO,CAAC,IAAI,CAAC;IAM1E;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,SAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IAMrE,kEAAkE;IAClE,YAAY,IAAI,IAAI;IAKpB,sEAAsE;IACtE,OAAO,IAAI,IAAI;CAwBhB"}