react-cheminfo 0.63.1 → 0.64.1

package/lib/molstar/core/index.js

@@ -1,6 +1,6 @@
 /**
  * The molstar layer under the 3D views: the plugin lifecycle, the camera, the
- * hover labels, the measurements and the picture of a scene.
+ * hover labels, the measurements, the highlights and the picture of a scene.
  *
  * Three of our sites mount a headless molstar canvas — the molecule viewer
  * here, lcao's orbitals and symmetry's crystals — and each of them had its own
@@ -16,6 +16,7 @@
  */
 export { cameraToPose, poseToCamera } from "./cameraPose.js";
 export { DEFAULT_CAMERA_DURATION, DEFAULT_SPIN_SPEED, FRAMING_MARGIN, MINIMUM_FRAMING_RADIUS, framedRadius, setSpin, } from "./camera.js";
+export { HighlightPainter, highlightOverpaint } from "./highlights.js";
 export { atomName, atomText, lociText, subscribeHover } from "./hover.js";
 export { MolstarPlugin } from "./plugin.js";
 export { captureScene } from "./captureScene.js";

package/lib/molstar/core/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/molstar/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EACL,uBAAuB,EACvB,kBAAkB,EAClB,cAAc,EACd,sBAAsB,EACtB,YAAY,EACZ,OAAO,GACR,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE1E,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/molstar/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EACL,uBAAuB,EACvB,kBAAkB,EAClB,cAAc,EACd,sBAAsB,EACtB,YAAY,EACZ,OAAO,GACR,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE1E,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,mBAAmB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-cheminfo",
-  "version": "0.63.1",
+  "version": "0.64.1",
   "license": "MIT",
   "description": "React components, hooks and framework-free helpers shared by the cheminfo sites: site chrome, citations, sharing, routing, pedagogy, charts, and the structure, orbital and 3D molecule viewers",
   "author": "Luc Patiny",

package/src/molecule3d/core/highlight.ts

@@ -0,0 +1,127 @@
+/**
+ * What a highlight on a 3D molecule is, without React and without molstar: a
+ * bonded path of atoms a site points at — the two atoms of a bond, the three of
+ * an angle, the four of a dihedral — for the model to emphasise.
+ *
+ * Atoms are named by position, as measurements name them, so a row of a table
+ * read off one conformer lands on the same atoms of every other conformer of
+ * the same molecule.
+ */
+
+import type { AtomReference } from './measurement.ts';
+import { sameAtoms } from './measurement.ts';
+
+/** One bonded path of atoms to emphasise on the model. */
+export interface Molecule3DHighlight {
+  /**
+   * The atoms in the order they are bonded: two for a bond, three for the two
+   * bonds of an angle, four for the three bonds of a dihedral. One atom
+   * emphasises that atom alone.
+   */
+  atoms: readonly AtomReference[];
+}
+
+/** Two consecutive atoms of a path: the bond a highlight emphasises. */
+export type HighlightedBond = readonly [AtomReference, AtomReference];
+
+/** Everything a list of highlights emphasises, each atom and bond once. */
+export interface HighlightedParts {
+  /** Every atom of every path, in the order the paths first name them. */
+  atoms: readonly AtomReference[];
+  /** Every pair of consecutive atoms, in the order the paths first name them. */
+  bonds: readonly HighlightedBond[];
+}
+
+/**
+ * The atoms and the bonds a list of highlights emphasises.
+ *
+ * A bond is a pair of consecutive atoms of one path, and nothing else: two
+ * atoms that are both highlighted, but by different paths or not next to each
+ * other in one, are not a bond of the highlight — so six C–H paths never
+ * emphasise the C–C bond between two of their carbons. An atom the structure
+ * lacks is left out, with the two pairs it stands in; the atoms on either side
+ * of it are not joined in its place.
+ * @param highlights - The paths, as a site passes them.
+ * @param hasAtom - Whether the structure on screen has an atom; asked only of
+ * references whose two numbers are whole and not negative.
+ * @default () => true
+ * @returns The atoms and the bonds, each once, in the order first named.
+ */
+export function highlightedParts(
+  highlights: readonly Molecule3DHighlight[],
+  hasAtom: (atom: AtomReference) => boolean = isAnyAtom,
+): HighlightedParts {
+  const atoms: AtomReference[] = [];
+  const bonds: HighlightedBond[] = [];
+  const atomKeys = new Set<string>();
+  const bondKeys = new Set<string>();
+  for (const highlight of highlights) {
+    let previous: AtomReference | undefined;
+    for (const atom of highlight.atoms) {
+      const present = isAtomReference(atom) && hasAtom(atom);
+      if (present && !atomKeys.has(atomKey(atom))) {
+        atomKeys.add(atomKey(atom));
+        atoms.push({ unit: atom.unit, element: atom.element });
+      }
+      if (present && previous !== undefined) {
+        const key = bondKey(previous, atom);
+        if (key !== null && !bondKeys.has(key)) {
+          bondKeys.add(key);
+          bonds.push([
+            { unit: previous.unit, element: previous.element },
+            { unit: atom.unit, element: atom.element },
+          ]);
+        }
+      }
+      previous = present ? atom : undefined;
+    }
+  }
+  return { atoms, bonds };
+}
+
+/**
+ * Whether two lists of highlights name the same atoms, in the same paths and
+ * the same order — what decides that the model needs no repainting.
+ * @param first - One list.
+ * @param second - The other.
+ * @returns True when every path of one is the path of the other at its place.
+ */
+export function sameHighlights(
+  first: readonly Molecule3DHighlight[],
+  second: readonly Molecule3DHighlight[],
+): boolean {
+  if (first === second) return true;
+  if (first.length !== second.length) return false;
+  for (let index = 0; index < first.length; index++) {
+    const one = first[index]?.atoms;
+    const other = second[index]?.atoms;
+    if (one === undefined || other === undefined) return false;
+    if (!sameAtoms(one, other)) return false;
+  }
+  return true;
+}
+
+function isAnyAtom(): boolean {
+  return true;
+}
+
+function isAtomReference(atom: AtomReference): boolean {
+  return (
+    Number.isInteger(atom.unit) &&
+    atom.unit >= 0 &&
+    Number.isInteger(atom.element) &&
+    atom.element >= 0
+  );
+}
+
+function atomKey(atom: AtomReference): string {
+  return `${atom.unit}:${atom.element}`;
+}
+
+// One key for a pair whichever way round, and none for an atom with itself.
+function bondKey(first: AtomReference, second: AtomReference): string | null {
+  const one = atomKey(first);
+  const other = atomKey(second);
+  if (one === other) return null;
+  return one < other ? `${one}-${other}` : `${other}-${one}`;
+}

package/src/molecule3d/core/index.ts

@@ -16,6 +16,12 @@ export type { ImageSize } from './exportImage.ts';
 export { dataUriBytes, rasterSvgMarkup } from './exportImage.ts';
 export type { Molecule3DGesture, Molecule3DGestureKey } from './gestures.ts';
 export { MOLECULE_3D_GESTURES } from './gestures.ts';
+export type {
+  HighlightedBond,
+  HighlightedParts,
+  Molecule3DHighlight,
+} from './highlight.ts';
+export { highlightedParts, sameHighlights } from './highlight.ts';
 export type {
   AtomReference,
   Measurement,
@@ -25,6 +31,7 @@ export {
   MEASUREMENT_ATOM_COUNTS,
   MEASUREMENT_KINDS,
   MEASUREMENT_LABELS,
+  sameMeasurements,
 } from './measurement.ts';
 export type {
   Molecule3DFile,

package/src/molecule3d/core/measurement.ts

@@ -41,3 +41,50 @@ export interface Measurement {
   kind: MeasurementKind;
   atoms: readonly AtomReference[];
 }
+
+/**
+ * Whether two lists name the same measurements, of the same kinds over the
+ * same atoms, in the same order — what decides that nothing needs drawing
+ * again.
+ * @param first - One list.
+ * @param second - The other.
+ * @returns True when every measurement of one is the measurement of the other
+ * at its place.
+ */
+export function sameMeasurements(
+  first: readonly Measurement[],
+  second: readonly Measurement[],
+): boolean {
+  if (first === second) return true;
+  if (first.length !== second.length) return false;
+  for (let index = 0; index < first.length; index++) {
+    const one = first[index];
+    const other = second[index];
+    if (one === undefined || other === undefined) return false;
+    if (one.kind !== other.kind || !sameAtoms(one.atoms, other.atoms)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Whether two lists name the same atoms in the same order.
+ * @param first - One list.
+ * @param second - The other.
+ * @returns True when every atom of one is the atom of the other at its place.
+ */
+export function sameAtoms(
+  first: readonly AtomReference[],
+  second: readonly AtomReference[],
+): boolean {
+  if (first.length !== second.length) return false;
+  for (let position = 0; position < first.length; position++) {
+    const atom = first[position];
+    const match = second[position];
+    if (atom?.unit !== match?.unit || atom?.element !== match?.element) {
+      return false;
+    }
+  }
+  return true;
+}

package/src/molecule3d/ui/MoleculeCanvas3D.tsx

@@ -10,6 +10,7 @@ import type { CSSProperties, ReactElement } from 'react';
 import { useEffect, useRef, useState } from 'react';
 
 import { DEFAULT_SPIN_SPEED } from '../../molstar/core/index.ts';
+import type { Molecule3DHighlight } from '../core/highlight.ts';
 import type { Measurement, MeasurementKind } from '../core/measurement.ts';
 import {
   normalizeMolecule3DSettings,
@@ -21,6 +22,7 @@ import { Molecule3DOptions } from './Molecule3DOptions.tsx';
 import { Molecule3DStage } from './Molecule3DStage.tsx';
 import { Molecule3DToolbar } from './Molecule3DToolbar.tsx';
 import { createMolecule3DViewer } from './createViewer.ts';
+import { highlightColorOf } from './highlightColor.ts';
 import type { MoleculeViewer3DProps } from './moleculeViewer3DProps.ts';
 import { useControlledState } from './useControlledState.ts';
 import { useImageExport } from './useImageExport.ts';
@@ -56,6 +58,7 @@ export function MoleculeCanvas3D(props: MoleculeCanvas3DProps): ReactElement {
     spinSpeed = DEFAULT_SPIN_SPEED,
     measurements: measurementsProp,
     onMeasurementsChange,
+    highlights = NO_HIGHLIGHTS,
     fileName = 'molecule',
     background,
     minHeight = 320,
@@ -133,6 +136,14 @@ export function MoleculeCanvas3D(props: MoleculeCanvas3DProps): ReactElement {
     void viewerRef.current?.setMeasureKind(measureKind);
   }, [container, measureKind]);
 
+  // Kept out of the scene: a new highlight repaints the model, never redraws it.
+  useEffect(() => {
+    void viewerRef.current?.setHighlights(
+      highlights,
+      highlightColorOf(container),
+    );
+  }, [container, highlights]);
+
   const { resetView } = useMoleculeScene({
     container,
     viewerRef,
@@ -204,6 +215,8 @@ export function MoleculeCanvas3D(props: MoleculeCanvas3DProps): ReactElement {
 
 const NO_MEASUREMENTS: readonly Measurement[] = [];
 
+const NO_HIGHLIGHTS: readonly Molecule3DHighlight[] = [];
+
 const STAGE_STYLE: CSSProperties = {
   position: 'relative',
   flex: '1 0 auto',

package/src/molecule3d/ui/drawScene.ts

@@ -4,8 +4,19 @@ import { normalizeMolecule3DSettings } from '../core/settings.ts';
 
 import type { Molecule3DViewer } from './viewer.ts';
 
+/** The operations of the viewer a scene is drawn with. */
+export type SceneViewer = Pick<
+  Molecule3DViewer,
+  | 'showMolecule'
+  | 'hideMolecule'
+  | 'showSurface'
+  | 'showMeasurements'
+  | 'resetCamera'
+  | 'setCamera'
+>;
+
 /**
- * Draw the scene. `showMolecule` empties it, so the surface and the
+ * Draw the whole scene. `showMolecule` empties it, so the surface and the
  * measurements are added after the model, and the camera is framed last.
  * @param viewer - The viewer holding the canvas.
  * @param molfile - What to draw, or `null` to empty the scene.
@@ -17,7 +28,7 @@ import type { Molecule3DViewer } from './viewer.ts';
  * @returns Nothing; resolves once the scene is complete.
  */
 export async function drawScene(
-  viewer: Molecule3DViewer,
+  viewer: SceneViewer,
   molfile: Molecule3DFile | null,
   settings: Molecule3DSettings,
   measurements: readonly Measurement[],

package/src/molecule3d/ui/highlightColor.ts

@@ -0,0 +1,34 @@
+/**
+ * The colour the 3D view emphasises in, read off the page it sits on.
+ *
+ * A WebGL colour cannot be a custom property, and the family's accent is the
+ * one colour a site owns, so it cannot be written into a shared library either:
+ * the view asks the browser what `--accent` resolved to where it is drawn, as
+ * the parallel coordinates do, and hands molstar the answer.
+ */
+
+import { normalizeColor } from '../../tokens/core/colors.ts';
+import { FAMILY_TOKEN_VALUES } from '../../tokens/core/familyTokens.ts';
+
+/**
+ * What `--accent` resolved to on an element of the view.
+ * @param element - An element of the view, once it is on the page, or `null`
+ * before it is.
+ * @returns The accent as `#rrggbb`. A site that declares none emphasises in its
+ * text colour, and a page that declares neither, or no page yet, in the
+ * family's.
+ */
+export function highlightColorOf(element: Element | null): string {
+  return (
+    tokenColor(element, '--accent') ??
+    tokenColor(element, '--text') ??
+    FAMILY_TOKEN_VALUES['--text']
+  );
+}
+
+function tokenColor(element: Element | null, name: string): string | undefined {
+  const resolve = globalThis.getComputedStyle;
+  if (element === null || typeof resolve !== 'function') return undefined;
+  const color = normalizeColor(resolve(element).getPropertyValue(name));
+  return color === null ? undefined : `#${color}`;
+}

package/src/molecule3d/ui/moleculeViewer3DProps.ts

@@ -2,6 +2,7 @@ import type { ReactNode } from 'react';
 
 import type { ViewerCapability } from '../../orbital/ui/capability.ts';
 import type { Molecule3DCamera } from '../core/camera.ts';
+import type { Molecule3DHighlight } from '../core/highlight.ts';
 import type { Measurement } from '../core/measurement.ts';
 import type {
   Molecule3DFile,
@@ -71,7 +72,9 @@ export interface MoleculeViewer3DProps {
   /**
    * The measurements drawn over the model, when the site owns them. They name
    * atoms by position, so they carry over to another conformer of the same
-   * molecule; a site showing an unrelated molecule should clear them.
+   * molecule; a site showing an unrelated molecule should clear them. Changing
+   * them redraws the measurements and nothing else: the model, its highlights
+   * and the camera are left as they are.
    * @default undefined
    */
   measurements?: readonly Measurement[];
@@ -80,6 +83,18 @@ export interface MoleculeViewer3DProps {
    * @default undefined
    */
   onMeasurementsChange?: (measurements: readonly Measurement[]) => void;
+  /**
+   * The parts of the model to emphasise in the site's accent colour, each a
+   * bonded path of atoms named as measurements name them: two atoms are that
+   * bond, three the two bonds of an angle, four the three bonds of a dihedral,
+   * and one atom is that atom alone. Only the bonds between consecutive atoms
+   * of one path are emphasised, never another bond between two highlighted
+   * atoms, and an atom the structure lacks is skipped. Changing them repaints
+   * the model and nothing else: the camera, the measurements and the hover are
+   * left as they are.
+   * @default [] — nothing is emphasised
+   */
+  highlights?: readonly Molecule3DHighlight[];
   /**
    * 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

package/src/molecule3d/ui/renderMolecule.ts

@@ -26,7 +26,7 @@ export const MOLECULE_STRUCTURE_REF = 'molecule3d-structure';
 const MOLECULE_DATA_REF = 'molecule3d-data';
 
 /** The drawn model, replaced in place whenever the style changes. */
-const MODEL_REPRESENTATION_REF = 'molecule3d-model';
+export const MODEL_REPRESENTATION_REF = 'molecule3d-model';
 
 /**
  * molstar's ball-and-stick radius factor that a size factor of 1 stands for:

package/src/molecule3d/ui/sceneDrawer.ts

@@ -0,0 +1,132 @@
+/**
+ * What one canvas shows, what it is asked to show next, and the least work
+ * between the two.
+ *
+ * The measurements are drawn over the model, not into it: a change of them
+ * alone replaces their own representations and leaves the model, its surface,
+ * its highlights and the camera as they are. Only another molecule, or another
+ * style for it, draws the scene again, and only another molecule frames the
+ * camera. Draws run one after another, so a measurement never lands on a model
+ * that is half built, and the last request asked is the one drawn.
+ */
+
+import type { Molecule3DCamera } from '../core/camera.ts';
+import type { Measurement } from '../core/measurement.ts';
+import { sameMeasurements } from '../core/measurement.ts';
+import type { Molecule3DFile, Molecule3DSettings } from '../core/settings.ts';
+import { sameMolecule3DSettings } from '../core/settings.ts';
+
+import type { SceneViewer } from './drawScene.ts';
+import { drawScene } from './drawScene.ts';
+
+/** What the canvas is asked to show. */
+export interface SceneRequest {
+  /** What to draw, or `null` to empty the scene. */
+  molfile: Molecule3DFile | null;
+  /** How the model is drawn. */
+  settings: Molecule3DSettings;
+  /** What is drawn over it. */
+  measurements: readonly Measurement[];
+  /** How the camera meets a molecule it has not shown before. */
+  frameNewMolecule: 'front' | 'keep';
+}
+
+/** Keeps one viewer showing the last scene it was asked for. */
+export class SceneDrawer {
+  /** The viewer drawn on. */
+  readonly viewer: SceneViewer;
+  readonly #takeLinkedCamera: () => Molecule3DCamera | null;
+  #asked: SceneRequest | null = null;
+  // The model on screen, or `null` when the next request must draw it again.
+  #drawn: Pick<SceneRequest, 'molfile' | 'settings'> | null = null;
+  // The measurements on screen, or `null` when the next request must draw them.
+  #measured: readonly Measurement[] | null = [];
+  // The molecule the camera was last framed on, so another one is told apart.
+  #framed: Molecule3DFile | null = null;
+  #queue: Promise<void> = Promise.resolve();
+
+  /**
+   * Start drawing on `viewer`, whose scene is empty.
+   * @param viewer - The viewer to draw on.
+   * @param takeLinkedCamera - Asked when a molecule is new: a camera to stand
+   * at instead of framing it, or `null`.
+   */
+  constructor(
+    viewer: SceneViewer,
+    takeLinkedCamera: () => Molecule3DCamera | null,
+  ) {
+    this.viewer = viewer;
+    this.#takeLinkedCamera = takeLinkedCamera;
+  }
+
+  /**
+   * Bring the canvas to `request`, once whatever was asked before is drawn.
+   * @param request - The scene to show; replaces any request still waiting.
+   * @returns Nothing; resolves once the canvas shows the last request asked,
+   * and rejects with what stopped it from being drawn.
+   */
+  draw(request: SceneRequest): Promise<void> {
+    this.#asked = request;
+    const drawn = this.#queue.then(() => this.#catchUp());
+    this.#queue = drawn.catch(ignore);
+    return drawn;
+  }
+
+  async #catchUp(): Promise<void> {
+    const request = this.#asked;
+    if (request === null) return;
+    const drawn = this.#drawn;
+    if (
+      drawn !== null &&
+      sameFile(drawn.molfile, request.molfile) &&
+      sameMolecule3DSettings(drawn.settings, request.settings)
+    ) {
+      await this.#measure(request);
+      return;
+    }
+    await this.#redraw(request);
+  }
+
+  // The model stays: only the measurements over it can have changed.
+  async #measure(request: SceneRequest): Promise<void> {
+    const { molfile, measurements } = request;
+    const measured = this.#measured;
+    if (measured !== null && sameMeasurements(measured, measurements)) return;
+    // As for the model: a list that fails partway is drawn again next time.
+    this.#measured = null;
+    // An empty scene has nothing to measure; the list waits for a molecule.
+    if (molfile !== null) await this.viewer.showMeasurements(measurements);
+    this.#measured = measurements;
+  }
+
+  async #redraw(request: SceneRequest): Promise<void> {
+    const { molfile, settings, measurements, frameNewMolecule } = request;
+    const isNew =
+      molfile !== null &&
+      (this.#framed === null || !sameFile(this.#framed, molfile));
+    this.#framed = molfile;
+    // A 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 ? this.#takeLinkedCamera() : null;
+    const frameCamera = isNew && linked === null ? frameNewMolecule : 'none';
+    // Kept only once drawn: a draw that fails is drawn again by the next
+    // request, whatever that one changes.
+    this.#drawn = null;
+    await drawScene(this.viewer, molfile, settings, measurements, frameCamera);
+    this.#drawn = { molfile, settings };
+    this.#measured = measurements;
+    if (linked !== null) await this.viewer.setCamera(linked);
+  }
+}
+
+function sameFile(
+  first: Molecule3DFile | null,
+  second: Molecule3DFile | null,
+): boolean {
+  if (first === null || second === null) return first === second;
+  return first.format === second.format && first.data === second.data;
+}
+
+function ignore(): void {
+  // A failure reached the caller of `draw`; the next draw still runs.
+}

package/src/molecule3d/ui/useMoleculeScene.ts

@@ -5,18 +5,18 @@
  * 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.
+ * reader's orientation. What each draw rebuilds is the scene drawer's call: a
+ * change of the measurements alone redraws them and nothing else.
  */
 
 import type { RefObject } from 'react';
 import { useCallback, useEffect, useRef } from 'react';
 
-import type { Molecule3DCamera } from '../core/camera.ts';
 import type { Measurement } from '../core/measurement.ts';
 import type { Molecule3DFile, Molecule3DSettings } from '../core/settings.ts';
 
-import { drawScene } from './drawScene.ts';
 import type { MoleculeViewer3DProps } from './moleculeViewer3DProps.ts';
+import { SceneDrawer } from './sceneDrawer.ts';
 import {
   DEFAULT_CAMERA_SETTLE_DELAY,
   useSharedCamera,
@@ -71,10 +71,7 @@ export function useMoleculeScene(options: MoleculeSceneOptions): MoleculeScene {
     onFailureChange,
     camera: cameraProps,
   } = options;
-  const framedRef = useRef<{
-    molfile: Molecule3DFile;
-    viewer: Molecule3DViewer;
-  } | null>(null);
+  const drawerRef = useRef<SceneDrawer | null>(null);
   const reportFailure = useRef(onFailureChange);
   useEffect(() => {
     reportFailure.current = onFailureChange;
@@ -92,31 +89,24 @@ export function useMoleculeScene(options: MoleculeSceneOptions): MoleculeScene {
   useEffect(() => {
     const viewer = viewerRef.current;
     if (container === null || viewer === null) return;
+    // A new viewer starts from an empty scene, so it gets a drawer of its own.
+    if (drawerRef.current?.viewer !== viewer) {
+      drawerRef.current = new SceneDrawer(viewer, camera.takeLinkedCamera);
+    }
+    const drawer = drawerRef.current;
     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: Molecule3DCamera | null = 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: unknown) => {
+      drawer.draw({ molfile, settings, measurements, frameNewMolecule }).then(
+        () => {
+          if (!cancelled) reportFailure.current(null);
+        },
+        (error: unknown) => {
           if (cancelled) return;
           reportFailure.current(
             error instanceof Error ? error.message : String(error),
           );
-        });
+        },
+      );
     });
     return () => {
       cancelled = true;

package/src/molecule3d/ui/useSharedCamera.ts

@@ -37,9 +37,7 @@ export interface SharedCameraOptions {
 
 /**
  * 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.
+ * draw effect keys on it, and a fresh one would run it again for nothing.
  */
 export interface SharedCamera {
   /**