react-cheminfo 0.18.0 → 0.19.0

package/lib/molecule3d/ui/camera.js

@@ -1,8 +1,11 @@
 /**
- * The two camera moves the molecule viewer needs: frame whatever is on screen,
- * and the slow spin that makes a still picture of a 3D molecule readable.
+ * The camera moves the molecule viewer needs: frame whatever is on screen, the
+ * slow spin that makes a still picture of a 3D molecule readable, and the two
+ * directions between molstar's camera and the scene-relative camera a link
+ * carries.
  */
-import { Vec3 } from 'molstar/lib/mol-math/linear-algebra.js';
+import { Quat, Vec3 } from 'molstar/lib/mol-math/linear-algebra.js';
+import { normalizeMolecule3DCamera } from "../core/camera.js";
 /** Transition length used when the caller does not pick one, milliseconds. */
 export const DEFAULT_CAMERA_DURATION = 250;
 /** Turn rate used when the caller does not pick one, in molstar's spin unit. */
@@ -23,6 +26,19 @@ const MIN_FRAMING_RADIUS = 0.5;
 /** Screen up and viewing direction when the model is seen as its file lays it. */
 const FRONT_UP = Vec3.create(0, 1, 0);
 const FRONT_DIRECTION = Vec3.create(0, 0, -1);
+/** The camera's own axes, which the stored rotation turns into world ones. */
+const CAMERA_UP = Vec3.create(0, 1, 0);
+const CAMERA_BACK = Vec3.create(0, 0, 1);
+/**
+ * The radius a reset frames, which is the length every stored camera is
+ * measured against — so reading a camera and applying it are the same move in
+ * opposite directions.
+ * @param radius - Radius of the scene's visible bounding sphere.
+ * @returns The framed radius.
+ */
+function framedRadius(radius) {
+    return Math.max(radius * (1 + FRAMING_MARGIN), MIN_FRAMING_RADIUS);
+}
 /**
  * Frame everything currently in the scene.
  *
@@ -41,7 +57,7 @@ export function resetCamera(plugin, durationMilliseconds = DEFAULT_CAMERA_DURATI
         durationMs: durationMilliseconds,
         snapshot: (scene, camera) => {
             const { center, radius } = scene.boundingSphereVisible;
-            const framed = Math.max(radius * (1 + FRAMING_MARGIN), MIN_FRAMING_RADIUS);
+            const framed = framedRadius(radius);
             return fromFront
                 ? camera.getFocus(center, framed, FRONT_UP, FRONT_DIRECTION)
                 : camera.getFocus(center, framed);
@@ -63,4 +79,97 @@ export function setSpin(plugin, spinning, speed = DEFAULT_SPIN_SPEED) {
         },
     });
 }
+/**
+ * Where the camera stands, against the scene rather than its coordinates.
+ *
+ * An empty scene has no camera to read: a canvas showing nothing still has one,
+ * pointing at the origin from molstar's default distance, and measuring that
+ * against a sphere of no radius describes a view that means nothing — which
+ * would then be applied to the first molecule drawn.
+ * @param plugin - The molstar context.
+ * @returns The camera, or `null` when there is no canvas or nothing to measure
+ * it against.
+ */
+export function readCamera(plugin) {
+    const canvas = plugin.canvas3d;
+    if (canvas === undefined)
+        return null;
+    const { center, radius } = canvas.boundingSphereVisible;
+    if (!(radius > 0))
+        return null;
+    const framed = framedRadius(radius);
+    const camera = canvas.camera;
+    const { position, target, up } = camera.getSnapshot();
+    const back = Vec3.sub(Vec3.zero(), position, target);
+    const distance = Vec3.magnitude(back);
+    if (distance <= 0)
+        return null;
+    Vec3.scale(back, back, 1 / distance);
+    // The trackball keeps up and back close to square, never exactly so.
+    const trueUp = Vec3.scaleAndAdd(Vec3.zero(), up, back, -Vec3.dot(up, back));
+    if (Vec3.magnitude(trueUp) <= 0)
+        return null;
+    Vec3.normalize(trueUp, trueUp);
+    const right = Vec3.cross(Vec3.zero(), trueUp, back);
+    const rotation = Quat.fromBasis(Quat.identity(), right, trueUp, back);
+    const offset = Vec3.sub(Vec3.zero(), target, center);
+    Vec3.scale(offset, offset, 1 / framed);
+    return normalizeMolecule3DCamera({
+        rotation: [
+            rotation[0] ?? 0,
+            rotation[1] ?? 0,
+            rotation[2] ?? 0,
+            rotation[3] ?? 1,
+        ],
+        zoom: camera.getTargetDistance(framed) / distance,
+        offset: [offset[0] ?? 0, offset[1] ?? 0, offset[2] ?? 0],
+    });
+}
+/**
+ * Put the camera back where a link says it stood.
+ *
+ * Ordered through `requestCameraReset` for the same reason {@link resetCamera}
+ * is: the bounding sphere the camera is measured against is only refreshed when
+ * the canvas commits the scene, so the move is computed then rather than now.
+ * @param plugin - The molstar context.
+ * @param camera - Where to stand.
+ * @param durationMilliseconds - Transition length. Pass 0 for an instant jump.
+ */
+export function applyCamera(plugin, camera, durationMilliseconds = 0) {
+    const { rotation, zoom, offset } = normalizeMolecule3DCamera(camera);
+    const turn = Quat.create(rotation[0], rotation[1], rotation[2], rotation[3]);
+    plugin.canvas3d?.requestCameraReset({
+        durationMs: durationMilliseconds,
+        snapshot: (scene, current) => {
+            const { center, radius } = scene.boundingSphereVisible;
+            const framed = framedRadius(radius);
+            const up = Vec3.transformQuat(Vec3.zero(), CAMERA_UP, turn);
+            const back = Vec3.transformQuat(Vec3.zero(), CAMERA_BACK, turn);
+            const target = Vec3.create((center[0] ?? 0) + offset[0] * framed, (center[1] ?? 0) + offset[1] * framed, (center[2] ?? 0) + offset[2] * framed);
+            const distance = current.getTargetDistance(framed) / zoom;
+            const position = Vec3.scaleAndAdd(Vec3.zero(), target, back, distance);
+            return { target, position, up, radius: framed };
+        },
+    });
+}
+/**
+ * Follow the camera, however it moves — a drag, the reset button, the spin.
+ * @param plugin - The molstar context.
+ * @param listener - Called after every move, with the camera it left.
+ * @returns A function that stops calling the listener.
+ */
+export function watchCamera(plugin, listener) {
+    const camera = plugin.canvas3d?.camera;
+    if (camera === undefined)
+        return noop;
+    const subscription = camera.changed.subscribe(() => {
+        listener(readCamera(plugin));
+    });
+    return () => {
+        subscription.unsubscribe();
+    };
+}
+function noop() {
+    // Nothing was subscribed, so there is nothing to unsubscribe.
+}
 //# sourceMappingURL=camera.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"camera.js","sourceRoot":"","sources":["../../../src/molecule3d/ui/camera.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,wCAAwC,CAAC;AAG9D,8EAA8E;AAC9E,MAAM,CAAC,MAAM,uBAAuB,GAAG,GAAG,CAAC;AAE3C,gFAAgF;AAChF,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,GAAG,CAAC,CAAC;AAExC;;;;;;;GAOG;AACH,MAAM,cAAc,GAAG,IAAI,CAAC;AAE5B,sDAAsD;AACtD,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;AAEvC,+EAA+E;AAC/E,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAE/B,kFAAkF;AAClF,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;AACtC,MAAM,eAAe,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAE9C;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CACzB,MAAqB,EACrB,oBAAoB,GAAG,uBAAuB,EAC9C,SAAS,GAAG,KAAK;IAEjB,MAAM,CAAC,QAAQ,EAAE,kBAAkB,CAAC;QAClC,UAAU,EAAE,oBAAoB;QAChC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE;YAC1B,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC,qBAAqB,CAAC;YACvD,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CACrB,MAAM,GAAG,CAAC,CAAC,GAAG,cAAc,CAAC,EAC7B,kBAAkB,CACnB,CAAC;YACF,OAAO,SAAS;gBACd,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,CAAC;gBAC5D,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACtC,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,OAAO,CACrB,MAAqB,EACrB,QAAiB,EACjB,KAAK,GAAG,kBAAkB;IAE1B,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC;QACxB,SAAS,EAAE;YACT,OAAO,EAAE,QAAQ;gBACf,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE;gBACtD,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE;SAChC;KACF,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"camera.js","sourceRoot":"","sources":["../../../src/molecule3d/ui/camera.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,14 @@
+/**
+ * A picture of the scene, rendered off screen at a size of its own.
+ */
+import type { PluginContext } from 'molstar/lib/mol-plugin/context.js';
+import type { ImageSize } from '../core/exportImage.ts';
+/**
+ * Render the scene without its selection highlights or its axes.
+ * @param plugin - The molstar context.
+ * @param size - Pixel size of the picture.
+ * @returns The PNG as a data URI.
+ * @throws {Error} When the plugin has no screenshot helper.
+ */
+export declare function captureScene(plugin: PluginContext, size: ImageSize): Promise<string>;
+//# sourceMappingURL=captureScene.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"captureScene.d.ts","sourceRoot":"","sources":["../../../src/molecule3d/ui/captureScene.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAEvE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAExD;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,SAAS,GACd,OAAO,CAAC,MAAM,CAAC,CAYjB"}

package/lib/molecule3d/ui/captureScene.js

@@ -0,0 +1,24 @@
+/**
+ * A picture of the scene, rendered off screen at a size of its own.
+ */
+/**
+ * Render the scene without its selection highlights or its axes.
+ * @param plugin - The molstar context.
+ * @param size - Pixel size of the picture.
+ * @returns The PNG as a data URI.
+ * @throws {Error} When the plugin has no screenshot helper.
+ */
+export async function captureScene(plugin, size) {
+    const helper = plugin.helpers.viewportScreenshot;
+    if (helper === undefined) {
+        throw new Error('This viewer cannot take a picture of its scene.');
+    }
+    helper.behaviors.values.next({
+        ...helper.values,
+        resolution: { name: 'custom', params: size },
+        axes: { name: 'off', params: {} },
+        transparent: false,
+    });
+    return helper.getImageDataUri();
+}
+//# sourceMappingURL=captureScene.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"captureScene.js","sourceRoot":"","sources":["../../../src/molecule3d/ui/captureScene.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,MAAqB,EACrB,IAAe;IAEf,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,kBAAkB,CAAC;IACjD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;IACrE,CAAC;IACD,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC;QAC3B,GAAG,MAAM,CAAC,MAAM;QAChB,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE;QAC5C,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE;QACjC,WAAW,EAAE,KAAK;KACnB,CAAC,CAAC;IACH,OAAO,MAAM,CAAC,eAAe,EAAE,CAAC;AAClC,CAAC"}

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

@@ -0,0 +1,18 @@
+/**
+ * How a molecule viewer comes into being, and why it does so synchronously.
+ *
+ * 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`.
+ */
+import { Molecule3DViewer } from './viewer.ts';
+import type { Molecule3DViewerOptions } 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;
+//# sourceMappingURL=createViewer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"createViewer.d.ts","sourceRoot":"","sources":["../../../src/molecule3d/ui/createViewer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAEhE;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,WAAW,EACtB,OAAO,GAAE,uBAA4B,GACpC,gBAAgB,CAElB"}

package/lib/molecule3d/ui/createViewer.js

@@ -0,0 +1,19 @@
+/**
+ * How a molecule viewer comes into being, and why it does so synchronously.
+ *
+ * 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`.
+ */
+import { Molecule3DViewer } from "./viewer.js";
+/**
+ * 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 function createMolecule3DViewer(container, options = {}) {
+    return new Molecule3DViewer(container, options);
+}
+//# sourceMappingURL=createViewer.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"createViewer.js","sourceRoot":"","sources":["../../../src/molecule3d/ui/createViewer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG/C;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CACpC,SAAsB,EACtB,UAAmC,EAAE;IAErC,OAAO,IAAI,gBAAgB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;AAClD,CAAC"}

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

@@ -1,5 +1,6 @@
 import type { ReactNode } from 'react';
 import type { ViewerCapability } from '../../orbital/ui/capability.ts';
+import type { Molecule3DCamera } from '../core/camera.ts';
 import type { Measurement } from '../core/measurement.ts';
 import type { Molecule3DFile, Molecule3DSettings, Molecule3DTools } from '../core/settings.ts';
 /**
@@ -72,6 +73,26 @@ export interface MoleculeViewer3DProps {
      * @default undefined
      */
     onMeasurementsChange?: (measurements: readonly Measurement[]) => void;
+    /**
+     * Where the camera stands when the first molecule is framed — what a shared
+     * link carries. The camera belongs to whoever is dragging it afterwards, so
+     * this is read once and a later change is ignored; the viewer reports every
+     * move through `onCameraChange` instead.
+     * @default null — the molecule is framed as `frameNewMolecule` says
+     */
+    initialCamera?: Molecule3DCamera | null;
+    /**
+     * Called once the camera has come to rest, with where it stands. Not called
+     * while the model is spinning: a spinning camera has no orientation to keep.
+     * @default undefined
+     */
+    onCameraChange?: (camera: Molecule3DCamera) => void;
+    /**
+     * How long the camera must be still before `onCameraChange` is called,
+     * milliseconds, so one drag is one report rather than one per frame.
+     * @default 400
+     */
+    cameraSettleDelay?: number;
     /**
      * Name of an exported image, without its extension.
      * @default 'molecule'

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

@@ -1 +1 @@
-{"version":3,"file":"moleculeViewer3DProps.d.ts","sourceRoot":"","sources":["../../../src/molecule3d/ui/moleculeViewer3DProps.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EACV,cAAc,EACd,kBAAkB,EAClB,eAAe,EAChB,MAAM,qBAAqB,CAAC;AAE7B;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,qEAAqE;IACrE,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;IAC/B;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACpC;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IACjC;;;OAGG;IACH,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC9C;;;OAGG;IACH,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,kBAAkB,KAAK,IAAI,CAAC;IAC1D;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAC;IAC/C;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IACtC;;;OAGG;IACH,oBAAoB,CAAC,EAAE,CAAC,YAAY,EAAE,SAAS,WAAW,EAAE,KAAK,IAAI,CAAC;IACtE;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,CAAC,UAAU,EAAE,gBAAgB,KAAK,SAAS,CAAC;CACjE"}
+{"version":3,"file":"moleculeViewer3DProps.d.ts","sourceRoot":"","sources":["../../../src/molecule3d/ui/moleculeViewer3DProps.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EACV,cAAc,EACd,kBAAkB,EAClB,eAAe,EAChB,MAAM,qBAAqB,CAAC;AAE7B;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,qEAAqE;IACrE,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;IAC/B;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACpC;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IACjC;;;OAGG;IACH,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC9C;;;OAGG;IACH,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,kBAAkB,KAAK,IAAI,CAAC;IAC1D;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAC;IAC/C;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IACtC;;;OAGG;IACH,oBAAoB,CAAC,EAAE,CAAC,YAAY,EAAE,SAAS,WAAW,EAAE,KAAK,IAAI,CAAC;IACtE;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACxC;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,CAAC;IACpD;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,CAAC,UAAU,EAAE,gBAAgB,KAAK,SAAS,CAAC;CACjE"}

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

@@ -0,0 +1,47 @@
+/**
+ * Keeping one molstar canvas showing what the props describe: the model, its
+ * surface, its measurements, and where the camera stands over them.
+ *
+ * The draw is coalesced into one animation frame, so dragging a slider costs
+ * one rebuild rather than one per pixel, and the camera is framed only when the
+ * molecule is new — a restyle that snapped the view back would undo the
+ * reader's orientation.
+ */
+import type { RefObject } from 'react';
+import type { Measurement } from '../core/measurement.ts';
+import type { Molecule3DFile, Molecule3DSettings } from '../core/settings.ts';
+import type { MoleculeViewer3DProps } from './moleculeViewer3DProps.ts';
+import type { Molecule3DViewer } from './viewer.ts';
+/** What {@link useMoleculeScene} is given. */
+export interface MoleculeSceneOptions {
+    /** The element molstar draws in, or `null` before it exists. */
+    container: HTMLElement | null;
+    /** The viewer mounted in it. */
+    viewerRef: RefObject<Molecule3DViewer | null>;
+    /** What to draw, or `null` to empty the scene. */
+    molfile: Molecule3DFile | null;
+    /** How the camera meets a molecule it has not seen before. */
+    frameNewMolecule: 'front' | 'keep';
+    /** How the model is drawn. */
+    settings: Molecule3DSettings;
+    /** What is drawn over it. */
+    measurements: readonly Measurement[];
+    /** Whether the model is turning on its own. */
+    spinning: boolean;
+    /** Called with a drawing failure, and with `null` once a draw succeeds. */
+    onFailureChange: (message: string | null) => void;
+    /** Where the camera stands when the first molecule is framed, and who to tell. */
+    camera: Pick<MoleculeViewer3DProps, 'cameraSettleDelay' | 'initialCamera' | 'onCameraChange'>;
+}
+/** What {@link useMoleculeScene} answers. */
+export interface MoleculeScene {
+    /** Frame everything on screen again, as the toolbar's reset button does. */
+    resetView: () => void;
+}
+/**
+ * Draw the scene the options describe, and keep it drawn.
+ * @param options - See {@link MoleculeSceneOptions}.
+ * @returns See {@link MoleculeScene}.
+ */
+export declare function useMoleculeScene(options: MoleculeSceneOptions): MoleculeScene;
+//# sourceMappingURL=useMoleculeScene.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useMoleculeScene.d.ts","sourceRoot":"","sources":["../../../src/molecule3d/ui/useMoleculeScene.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAIvC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAG9E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAKxE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,8CAA8C;AAC9C,MAAM,WAAW,oBAAoB;IACnC,gEAAgE;IAChE,SAAS,EAAE,WAAW,GAAG,IAAI,CAAC;IAC9B,gCAAgC;IAChC,SAAS,EAAE,SAAS,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IAC9C,kDAAkD;IAClD,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;IAC/B,8DAA8D;IAC9D,gBAAgB,EAAE,OAAO,GAAG,MAAM,CAAC;IACnC,8BAA8B;IAC9B,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,6BAA6B;IAC7B,YAAY,EAAE,SAAS,WAAW,EAAE,CAAC;IACrC,+CAA+C;IAC/C,QAAQ,EAAE,OAAO,CAAC;IAClB,2EAA2E;IAC3E,eAAe,EAAE,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IAClD,kFAAkF;IAClF,MAAM,EAAE,IAAI,CACV,qBAAqB,EACrB,mBAAmB,GAAG,eAAe,GAAG,gBAAgB,CACzD,CAAC;CACH;AAED,6CAA6C;AAC7C,MAAM,WAAW,aAAa;IAC5B,4EAA4E;IAC5E,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CA+E7E"}

package/lib/molecule3d/ui/useMoleculeScene.js

@@ -0,0 +1,82 @@
+/**
+ * Keeping one molstar canvas showing what the props describe: the model, its
+ * surface, its measurements, and where the camera stands over them.
+ *
+ * The draw is coalesced into one animation frame, so dragging a slider costs
+ * one rebuild rather than one per pixel, and the camera is framed only when the
+ * molecule is new — a restyle that snapped the view back would undo the
+ * reader's orientation.
+ */
+import { useCallback, useEffect, useRef } from 'react';
+import { drawScene } from "./drawScene.js";
+import { DEFAULT_CAMERA_SETTLE_DELAY, useSharedCamera, } from "./useSharedCamera.js";
+/**
+ * Draw the scene the options describe, and keep it drawn.
+ * @param options - See {@link MoleculeSceneOptions}.
+ * @returns See {@link MoleculeScene}.
+ */
+export function useMoleculeScene(options) {
+    const { container, viewerRef, molfile, frameNewMolecule, settings, measurements, spinning, onFailureChange, camera: cameraProps, } = options;
+    const framedRef = useRef(null);
+    const reportFailure = useRef(onFailureChange);
+    useEffect(() => {
+        reportFailure.current = onFailureChange;
+    });
+    const camera = useSharedCamera({
+        container,
+        viewerRef,
+        spinning,
+        initialCamera: cameraProps.initialCamera ?? null,
+        onCameraChange: cameraProps.onCameraChange,
+        settleDelay: cameraProps.cameraSettleDelay ?? DEFAULT_CAMERA_SETTLE_DELAY,
+    });
+    useEffect(() => {
+        const viewer = viewerRef.current;
+        if (container === null || viewer === null)
+            return;
+        let cancelled = false;
+        const frame = requestAnimationFrame(() => {
+            const framed = framedRef.current;
+            const isNew = molfile !== null &&
+                (framed?.molfile !== molfile || framed.viewer !== viewer);
+            framedRef.current = molfile === null ? null : { molfile, viewer };
+            // The link's camera is spent on the first molecule framed; afterwards the
+            // camera is the reader's and a new molecule is framed as usual.
+            const linked = isNew
+                ? camera.takeLinkedCamera()
+                : null;
+            const frameCamera = isNew && linked === null ? frameNewMolecule : 'none';
+            void drawScene(viewer, molfile, settings, measurements, frameCamera)
+                .then(() => {
+                if (cancelled)
+                    return;
+                if (linked !== null)
+                    void viewer.setCamera(linked);
+                reportFailure.current(null);
+            })
+                .catch((error) => {
+                if (cancelled)
+                    return;
+                reportFailure.current(error instanceof Error ? error.message : String(error));
+            });
+        });
+        return () => {
+            cancelled = true;
+            cancelAnimationFrame(frame);
+        };
+    }, [
+        container,
+        viewerRef,
+        molfile,
+        frameNewMolecule,
+        settings,
+        measurements,
+        camera,
+    ]);
+    const resetView = useCallback(() => {
+        camera.noteMove();
+        void viewerRef.current?.resetCamera();
+    }, [camera, viewerRef]);
+    return { resetView };
+}
+//# sourceMappingURL=useMoleculeScene.js.map

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

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

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

@@ -0,0 +1,52 @@
+/**
+ * The camera of the canvas as something a site can keep: the one a link
+ * carried, applied to the first molecule framed, and every move the reader
+ * makes afterwards, reported once it has come to rest.
+ *
+ * The camera is never controlled. It belongs to whoever is dragging it, so the
+ * site is told where it went rather than asked where it should be — anything
+ * else fights the trackball.
+ */
+import type { RefObject } from 'react';
+import type { Molecule3DCamera } from '../core/camera.ts';
+import type { Molecule3DViewer } from './viewer.ts';
+/** How long the camera must be still before a move is reported, milliseconds. */
+export declare const DEFAULT_CAMERA_SETTLE_DELAY = 400;
+/** What {@link useSharedCamera} is given. */
+export interface SharedCameraOptions {
+    /** The element molstar draws in, or `null` before it exists. */
+    container: HTMLElement | null;
+    /** The viewer mounted in it. */
+    viewerRef: RefObject<Molecule3DViewer | null>;
+    /** Where the camera stands when the first molecule is framed. */
+    initialCamera: Molecule3DCamera | null;
+    /** Called once a move of the reader's has come to rest. */
+    onCameraChange?: (camera: Molecule3DCamera) => void;
+    /** Whether the model is turning, which suspends reporting. */
+    spinning: boolean;
+    /** How long the camera must be still before a move is reported. */
+    settleDelay: number;
+}
+/**
+ * What {@link useSharedCamera} answers. The same object on every render: the
+ * draw effect keys on it, and a fresh one would tear the scene down and build
+ * it again — which makes molstar frame the model afresh and loses the camera a
+ * link had just restored.
+ */
+export interface SharedCamera {
+    /**
+     * The camera a link carried, answered once and then never again — the next
+     * molecule is framed the way the viewer frames any other.
+     * @returns The camera to stand at, or `null` to frame the molecule.
+     */
+    takeLinkedCamera: () => Molecule3DCamera | null;
+    /** Note a move of the reader's, which is what starts reporting. */
+    noteMove: () => void;
+}
+/**
+ * Keep the camera of one canvas in step with the site that shows it.
+ * @param options - See {@link SharedCameraOptions}.
+ * @returns See {@link SharedCamera}.
+ */
+export declare function useSharedCamera(options: SharedCameraOptions): SharedCamera;
+//# sourceMappingURL=useSharedCamera.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useSharedCamera.d.ts","sourceRoot":"","sources":["../../../src/molecule3d/ui/useSharedCamera.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGvC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAG1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,iFAAiF;AACjF,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAE/C,6CAA6C;AAC7C,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,SAAS,EAAE,WAAW,GAAG,IAAI,CAAC;IAC9B,gCAAgC;IAChC,SAAS,EAAE,SAAS,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IAC9C,iEAAiE;IACjE,aAAa,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACvC,2DAA2D;IAC3D,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,CAAC;IACpD,8DAA8D;IAC9D,QAAQ,EAAE,OAAO,CAAC;IAClB,mEAAmE;IACnE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,gBAAgB,EAAE,MAAM,gBAAgB,GAAG,IAAI,CAAC;IAChD,mEAAmE;IACnE,QAAQ,EAAE,MAAM,IAAI,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CA6D1E"}

package/lib/molecule3d/ui/useSharedCamera.js

@@ -0,0 +1,82 @@
+/**
+ * The camera of the canvas as something a site can keep: the one a link
+ * carried, applied to the first molecule framed, and every move the reader
+ * makes afterwards, reported once it has come to rest.
+ *
+ * The camera is never controlled. It belongs to whoever is dragging it, so the
+ * site is told where it went rather than asked where it should be — anything
+ * else fights the trackball.
+ */
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+import { formatMolecule3DCamera } from "../core/camera.js";
+/** How long the camera must be still before a move is reported, milliseconds. */
+export const DEFAULT_CAMERA_SETTLE_DELAY = 400;
+/**
+ * Keep the camera of one canvas in step with the site that shows it.
+ * @param options - See {@link SharedCameraOptions}.
+ * @returns See {@link SharedCamera}.
+ */
+export function useSharedCamera(options) {
+    const { container, viewerRef, settleDelay } = options;
+    // Spent on the first molecule framed.
+    const linkedRef = useRef(false);
+    // What the last report said, so the settling of a move we ordered ourselves
+    // is not handed back to the site as a move the reader made.
+    const reportedRef = useRef(null);
+    // Whether the reader has touched the canvas, which is what starts reporting.
+    const movedRef = useRef(false);
+    const latest = useRef(options);
+    useEffect(() => {
+        latest.current = options;
+    });
+    const noteMove = useCallback(() => {
+        movedRef.current = true;
+    }, []);
+    const takeLinkedCamera = useCallback(() => {
+        if (linkedRef.current)
+            return null;
+        linkedRef.current = true;
+        const camera = latest.current.initialCamera;
+        if (camera !== null)
+            reportedRef.current = formatMolecule3DCamera(camera);
+        return camera;
+    }, []);
+    // Reporting waits for a first gesture. The camera also drifts on its own — a
+    // surface added after the model was framed grows the scene, and the same
+    // camera then reads as slightly closer — and a view nobody chose is not one
+    // to hand back to the site, let alone to put in a link.
+    useEffect(() => {
+        const viewer = viewerRef.current;
+        if (container === null || viewer === null)
+            return;
+        let timer = null;
+        container.addEventListener('pointerdown', noteMove);
+        container.addEventListener('wheel', noteMove, { passive: true });
+        const stopWatching = viewer.watchCamera((camera) => {
+            if (camera === null)
+                return;
+            if (timer !== null)
+                clearTimeout(timer);
+            timer = setTimeout(() => {
+                timer = null;
+                const current = latest.current;
+                if (current.spinning || !movedRef.current)
+                    return;
+                const text = formatMolecule3DCamera(camera);
+                if (text === reportedRef.current)
+                    return;
+                reportedRef.current = text;
+                current.onCameraChange?.(camera);
+            }, settleDelay);
+        });
+        return () => {
+            if (timer !== null)
+                clearTimeout(timer);
+            container.removeEventListener('pointerdown', noteMove);
+            container.removeEventListener('wheel', noteMove);
+            stopWatching();
+        };
+    }, [container, viewerRef, settleDelay, noteMove]);
+    return useMemo(() => ({ takeLinkedCamera, noteMove }), [takeLinkedCamera, noteMove]);
+}
+//# sourceMappingURL=useSharedCamera.js.map

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

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

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

@@ -1,25 +1,17 @@
 /**
- * Lifecycle of one molstar molecule viewer.
+ * Lifecycle of one molstar molecule viewer: `createMolecule3DViewer` builds
+ * one, and every operation a component performs on it is a method here.
  *
- * `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.
+ * The constructor returns before the canvas exists — see `createViewer.ts` —
+ * so every method queues its work behind `ready` and resolves to nothing once
+ * the viewer has been disposed. molstar's own UI is not mounted: every control
+ * is the component's.
  */
+import type { Molecule3DCamera } from '../core/camera.ts';
 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.
@@ -85,6 +77,20 @@ export declare class Molecule3DViewer {
      * @returns Nothing; resolves once the move has been ordered.
      */
     resetCamera(durationMilliseconds?: number, fromFront?: boolean): Promise<void>;
+    /**
+     * Put the camera where a link says it stood.
+     * @param camera - Where to stand.
+     * @param durationMilliseconds - Transition length; 0 jumps.
+     * @returns Nothing; resolves once the move has been ordered.
+     */
+    setCamera(camera: Molecule3DCamera, durationMilliseconds?: number): Promise<void>;
+    /**
+     * Follow the camera, however it moves.
+     * @param listener - Called after every move.
+     * @returns A function that stops calling the listener; safe to call before
+     * the canvas exists.
+     */
+    watchCamera(listener: (camera: Molecule3DCamera | null) => void): () => void;
     /**
      * Turn the automatic spin on or off.
      * @param spinning - Whether the scene should keep turning.