react-cheminfo 0.66.0 → 0.67.0

package/src/locales/de.json

@@ -34,7 +34,7 @@
   "site.nmrium.tagline": "NMR-Spektren im Browser verarbeiten und zuordnen.",
   "site.metabo.tagline": "Eine Reihe von NMR-Spektren in eine Karte Ihrer Proben verwandeln.",
   "site.derepflow.tagline": "Die Bestandteile eines Gemischs aus seinem ¹³C-Spektrum bestimmen.",
-  "site.surge.tagline": "Alle Konstitutionsisomere einer Summenformel.",
+  "site.isomers.tagline": "Alle Konstitutionsisomere einer Summenformel.",
   "site.tex.tagline": "LaTeX-Formeln, aus einer URL als SVG oder PNG gerendert.",
   "site.lcao.tagline": "Atomorbitale zu Molekülorbitalen kombinieren.",
   "site.regexp.tagline": "Reguläre Ausdrücke in einer interaktiven Spielwiese lernen.",
@@ -493,6 +493,10 @@
   "structure.tool.reactionOnly": "Nur beim Zeichnen einer Reaktion.",
   "structure.tool.unavailable": "In diesem Editor nicht verfügbar.",
   "structure.loadingEditor": "Der Editor wird geladen…",
+  "structure.import.open": "Eine Strukturdatei öffnen",
+  "structure.import.drop": "Ablegen, um die Struktur zu laden",
+  "structure.import.unreadableFile": "{name} enthält weder Molfile noch SMILES noch idCode, die Zeichnung bleibt erhalten.",
+  "structure.import.unreadableText": "Dieser Text ist weder ein Molfile noch ein SMILES noch ein idCode, die Zeichnung bleibt erhalten.",
   "structure.export.open": "Struktur exportieren",
   "structure.export.glyph": "Struktur kopieren oder speichern: SMILES, Molfile",
   "structure.export.title": "Struktur exportieren",
@@ -522,6 +526,10 @@
   "molecule3d.molecularSurface": "Moleküloberfläche",
   "molecule3d.displayOptions": "Anzeigeoptionen",
   "molecule3d.exportImage": "Bild exportieren",
+  "molecule3d.frames": "Bilder",
+  "molecule3d.framesHelp": "Ein animiertes PNG enthält alle Bilder und spielt sie in einer Schleife ab. Browser spielen es ab; ein Programm, das es nicht kann, zeigt das erste Bild.",
+  "molecule3d.frames.one": "Dieses",
+  "molecule3d.frames.all": "Alle {count}, animiert",
   "molecule3d.fullScreen": "Vollbild",
   "molecule3d.measure": "Messen",
   "molecule3d.clearMeasurements": "Alle Messungen entfernen",

package/src/locales/en.json

@@ -34,7 +34,7 @@
   "site.nmrium.tagline": "Process and assign NMR spectra in the browser.",
   "site.metabo.tagline": "Turn a batch of NMR spectra into a map of your samples.",
   "site.derepflow.tagline": "Identify the constituents of a mixture from its ¹³C spectrum.",
-  "site.surge.tagline": "Every constitutional isomer of a molecular formula.",
+  "site.isomers.tagline": "Every constitutional isomer of a molecular formula.",
   "site.tex.tagline": "LaTeX formulas rendered to SVG or PNG from a URL.",
   "site.lcao.tagline": "Combine atomic orbitals into molecular ones.",
   "site.regexp.tagline": "Learn regular expressions in a live playground.",
@@ -437,6 +437,10 @@
   "structure.tool.reactionOnly": "Only when drawing a reaction.",
   "structure.tool.unavailable": "Not available in this editor.",
   "structure.loadingEditor": "Loading the editor…",
+  "structure.import.open": "Open a structure file",
+  "structure.import.drop": "Drop to load the structure",
+  "structure.import.unreadableFile": "{name} holds no molfile, SMILES or idCode, so the drawing was kept.",
+  "structure.import.unreadableText": "That text is not a molfile, a SMILES or an idCode, so the drawing was kept.",
   "structure.export.open": "Export the structure",
   "structure.export.glyph": "Copy or save the structure: SMILES, molfile",
   "structure.export.title": "Export the structure",
@@ -498,6 +502,10 @@
   "molecule3d.molecularSurface": "Molecular surface",
   "molecule3d.displayOptions": "Display options",
   "molecule3d.exportImage": "Export image",
+  "molecule3d.frames": "Frames",
+  "molecule3d.framesHelp": "An animated PNG holds every frame and plays them in a loop. Browsers play it; a program that cannot shows its first frame.",
+  "molecule3d.frames.one": "This one",
+  "molecule3d.frames.all": "All {count}, animated",
   "molecule3d.fullScreen": "Full screen",
   "molecule3d.measure": "Measure",
   "molecule3d.clearMeasurements": "Remove all measurements",

package/src/locales/es.json

@@ -34,7 +34,7 @@
   "site.nmrium.tagline": "Procesar y asignar espectros de RMN en el navegador.",
   "site.metabo.tagline": "Convertir un lote de espectros de RMN en un mapa de sus muestras.",
   "site.derepflow.tagline": "Identificar los constituyentes de una mezcla a partir de su espectro de ¹³C.",
-  "site.surge.tagline": "Todos los isómeros constitucionales de una fórmula molecular.",
+  "site.isomers.tagline": "Todos los isómeros constitucionales de una fórmula molecular.",
   "site.tex.tagline": "Fórmulas LaTeX representadas en SVG o PNG desde una URL.",
   "site.lcao.tagline": "Combinar orbitales atómicos en orbitales moleculares.",
   "site.regexp.tagline": "Aprender expresiones regulares en un entorno interactivo.",
@@ -493,6 +493,10 @@
   "structure.tool.reactionOnly": "Solo al dibujar una reacción.",
   "structure.tool.unavailable": "No disponible en este editor.",
   "structure.loadingEditor": "Cargando el editor…",
+  "structure.import.open": "Abrir un archivo de estructura",
+  "structure.import.drop": "Suelta para cargar la estructura",
+  "structure.import.unreadableFile": "{name} no contiene ningún molfile, SMILES ni idCode, así que se conserva el dibujo.",
+  "structure.import.unreadableText": "Ese texto no es un molfile, un SMILES ni un idCode, así que se conserva el dibujo.",
   "structure.export.open": "Exportar la estructura",
   "structure.export.glyph": "Copiar o guardar la estructura: SMILES, molfile",
   "structure.export.title": "Exportar la estructura",
@@ -522,6 +526,10 @@
   "molecule3d.molecularSurface": "Superficie molecular",
   "molecule3d.displayOptions": "Opciones de presentación",
   "molecule3d.exportImage": "Exportar la imagen",
+  "molecule3d.frames": "Fotogramas",
+  "molecule3d.framesHelp": "Un PNG animado contiene todos los fotogramas y los reproduce en bucle. Los navegadores lo reproducen; un programa que no puede muestra el primer fotograma.",
+  "molecule3d.frames.one": "Este",
+  "molecule3d.frames.all": "Los {count}, animados",
   "molecule3d.fullScreen": "Pantalla completa",
   "molecule3d.measure": "Medir",
   "molecule3d.clearMeasurements": "Quitar todas las medidas",

package/src/locales/fr.json

@@ -34,7 +34,7 @@
   "site.nmrium.tagline": "Traiter et attribuer des spectres RMN dans le navigateur.",
   "site.metabo.tagline": "Transformer un lot de spectres RMN en une carte de vos échantillons.",
   "site.derepflow.tagline": "Identifier les constituants d'un mélange à partir de son spectre ¹³C.",
-  "site.surge.tagline": "Tous les isomères de constitution d'une formule moléculaire.",
+  "site.isomers.tagline": "Tous les isomères de constitution d'une formule moléculaire.",
   "site.tex.tagline": "Des formules LaTeX rendues en SVG ou PNG depuis une URL.",
   "site.lcao.tagline": "Combiner des orbitales atomiques en orbitales moléculaires.",
   "site.regexp.tagline": "Apprendre les expressions régulières dans un bac à sable interactif.",
@@ -493,6 +493,10 @@
   "structure.tool.reactionOnly": "Seulement lors du dessin d'une réaction.",
   "structure.tool.unavailable": "Indisponible dans cet éditeur.",
   "structure.loadingEditor": "Chargement de l'éditeur…",
+  "structure.import.open": "Ouvrir un fichier de structure",
+  "structure.import.drop": "Déposer pour charger la structure",
+  "structure.import.unreadableFile": "{name} ne contient ni molfile, ni SMILES, ni idCode : le dessin est conservé.",
+  "structure.import.unreadableText": "Ce texte n'est ni un molfile, ni un SMILES, ni un idCode : le dessin est conservé.",
   "structure.export.open": "Exporter la structure",
   "structure.export.glyph": "Copier ou enregistrer la structure : SMILES, molfile",
   "structure.export.title": "Exporter la structure",
@@ -522,6 +526,10 @@
   "molecule3d.molecularSurface": "Surface moléculaire",
   "molecule3d.displayOptions": "Options d'affichage",
   "molecule3d.exportImage": "Exporter l'image",
+  "molecule3d.frames": "Images",
+  "molecule3d.framesHelp": "Un PNG animé contient toutes les images et les joue en boucle. Les navigateurs le jouent ; un programme qui ne le peut pas montre la première image.",
+  "molecule3d.frames.one": "Celle-ci",
+  "molecule3d.frames.all": "Les {count}, animées",
   "molecule3d.fullScreen": "Plein écran",
   "molecule3d.measure": "Mesurer",
   "molecule3d.clearMeasurements": "Retirer toutes les mesures",

package/src/locales/it.json

@@ -34,7 +34,7 @@
   "site.nmrium.tagline": "Elaborare e assegnare spettri NMR nel browser.",
   "site.metabo.tagline": "Trasformare una serie di spettri NMR in una mappa dei propri campioni.",
   "site.derepflow.tagline": "Identificare i costituenti di una miscela dal suo spettro ¹³C.",
-  "site.surge.tagline": "Tutti gli isomeri costituzionali di una formula molecolare.",
+  "site.isomers.tagline": "Tutti gli isomeri costituzionali di una formula molecolare.",
   "site.tex.tagline": "Formule LaTeX rese in SVG o PNG a partire da un URL.",
   "site.lcao.tagline": "Combinare orbitali atomici in orbitali molecolari.",
   "site.regexp.tagline": "Imparare le espressioni regolari in un ambiente interattivo.",
@@ -437,6 +437,10 @@
   "structure.tool.reactionOnly": "Solo quando si disegna una reazione.",
   "structure.tool.unavailable": "Non disponibile in questo editor.",
   "structure.loadingEditor": "Caricamento dell'editor…",
+  "structure.import.open": "Apri un file di struttura",
+  "structure.import.drop": "Rilascia per caricare la struttura",
+  "structure.import.unreadableFile": "{name} non contiene né molfile, né SMILES, né idCode, quindi il disegno resta com'era.",
+  "structure.import.unreadableText": "Questo testo non è né un molfile, né uno SMILES, né un idCode, quindi il disegno resta com'era.",
   "structure.export.open": "Esporta la struttura",
   "structure.export.glyph": "Copia o salva la struttura: SMILES, molfile",
   "structure.export.title": "Esporta la struttura",
@@ -498,6 +502,10 @@
   "molecule3d.molecularSurface": "Superficie molecolare",
   "molecule3d.displayOptions": "Opzioni di visualizzazione",
   "molecule3d.exportImage": "Esporta l'immagine",
+  "molecule3d.frames": "Fotogrammi",
+  "molecule3d.framesHelp": "Un PNG animato contiene tutti i fotogrammi e li riproduce in ciclo. I browser lo riproducono; un programma che non può mostra il primo fotogramma.",
+  "molecule3d.frames.one": "Questo",
+  "molecule3d.frames.all": "Tutti i {count}, animati",
   "molecule3d.fullScreen": "Schermo intero",
   "molecule3d.measure": "Misura",
   "molecule3d.clearMeasurements": "Togli tutte le misure",

package/src/molecule3d/core/animatedPng.ts

@@ -0,0 +1,79 @@
+/**
+ * Frames of a scene as one animated PNG, which loops forever.
+ *
+ * An APNG is a PNG whose frames every browser plays, and whose first frame
+ * any program that does not play them still shows. It keeps every colour of a
+ * shaded molecule, which a GIF's 256 cannot.
+ */
+
+import type * as Upng from '@pdf-lib/upng';
+
+/** How many frames a second are played, and saved, when nobody says. */
+export const DEFAULT_FRAMES_PER_SECOND = 25;
+
+/** One frame: its pixels as RGBA bytes, row by row from the top. */
+export interface RgbaFrame {
+  width: number;
+  height: number;
+  data: Uint8ClampedArray | Uint8Array;
+}
+
+/**
+ * Encode frames as one animated PNG, every frame shown for the same time, the
+ * whole looping forever. The encoder is loaded on first use.
+ * @param frames - The frames, in order, all the same size.
+ * @param framesPerSecond - How many are shown per second.
+ * @returns The PNG file.
+ * @throws {Error} When there is no frame, or the frames differ in size.
+ */
+export async function encodeAnimatedPng(
+  frames: readonly RgbaFrame[],
+  framesPerSecond: number,
+): Promise<Uint8Array<ArrayBuffer>> {
+  const first = frames[0];
+  if (first === undefined) throw new Error('There is no frame to encode.');
+  const { width, height } = first;
+  const buffers: ArrayBuffer[] = [];
+  const delays: number[] = [];
+  const delay = Math.max(1, Math.round(1000 / framesPerSecond));
+  for (const frame of frames) {
+    if (frame.width !== width || frame.height !== height) {
+      throw new Error('Every frame of an animated PNG must be the same size.');
+    }
+    buffers.push(rgbaBuffer(frame));
+    delays.push(delay);
+  }
+  const upng = await loadEncoder();
+  // 0 colours: lossless.
+  return new Uint8Array(upng.encode(buffers, width, height, 0, delays));
+}
+
+/**
+ * The bytes of a frame in an ArrayBuffer of their own size, which the encoder
+ * reads whole.
+ * @param frame - The frame.
+ * @returns Its RGBA bytes.
+ */
+function rgbaBuffer(frame: RgbaFrame): ArrayBuffer {
+  const { data } = frame;
+  const { buffer, byteOffset, byteLength } = data;
+  if (
+    buffer instanceof ArrayBuffer &&
+    byteOffset === 0 &&
+    byteLength === buffer.byteLength
+  ) {
+    return buffer;
+  }
+  return new Uint8Array(data).buffer;
+}
+
+type Encoder = Pick<typeof Upng, 'encode'>;
+
+async function loadEncoder(): Promise<Encoder> {
+  const { default: loaded } = (await import('@pdf-lib/upng')) as {
+    default: Encoder | { default: Encoder };
+  };
+  // A bundler hands the ES build's one default object; Node's own import hands
+  // the exports of the CommonJS build, whose default is that object.
+  return 'encode' in loaded ? loaded : loaded.default;
+}

package/src/molecule3d/core/file.ts

@@ -0,0 +1,23 @@
+/**
+ * A molfile for the viewer, with the parser molstar has to read it with.
+ *
+ * A file of several models — an SDF of several records, an XYZ of several
+ * frames — is a series of frames of one molecule, which the viewer can play
+ * and export as an animated PNG.
+ */
+export interface Molecule3DFile {
+  /**
+   * molstar's format id: `mol` reads V2000, `sdf` reads V2000 and V3000, `xyz`
+   * reads bare coordinates and infers the bonds from the distances.
+   */
+  format: 'mol' | 'sdf' | 'xyz';
+  /** The file text. It must carry 3D coordinates. */
+  data: string;
+  /**
+   * Names the molecule the file draws, when several files draw one — one per
+   * normal mode, say. Replacing a file by another of the same name keeps the
+   * camera where the reader left it, instead of framing a new molecule.
+   * @default undefined — every other file is another molecule
+   */
+  moleculeId?: string;
+}

package/src/molecule3d/core/index.ts

@@ -1,3 +1,5 @@
+export type { RgbaFrame } from './animatedPng.ts';
+export { DEFAULT_FRAMES_PER_SECOND, encodeAnimatedPng } from './animatedPng.ts';
 export type {
   Molecule3DCamera,
   Molecule3DRotation,
@@ -33,8 +35,8 @@ export {
   MEASUREMENT_LABELS,
   sameMeasurements,
 } from './measurement.ts';
+export type { Molecule3DFile } from './file.ts';
 export type {
-  Molecule3DFile,
   Molecule3DSettings,
   Molecule3DTools,
   RepresentationId,

package/src/molecule3d/core/settings.ts

@@ -3,14 +3,6 @@
  * free of React and molstar so a site can persist and validate them.
  */
 
-/** A molfile for the viewer, with the parser molstar has to read it with. */
-export interface Molecule3DFile {
-  /** molstar's format id: `mol` reads V2000, `sdf` reads V2000 and V3000. */
-  format: 'mol' | 'sdf';
-  /** The molfile text. It must carry 3D coordinates. */
-  data: string;
-}
-
 /** Ways the model can be drawn, in the order the picker offers them. */
 export const REPRESENTATIONS = [
   'ball-and-stick',

package/src/molecule3d/ui/Molecule3DExport.tsx

@@ -16,15 +16,28 @@ import {
 import { FigureDownloadPanel } from '../../download/ui/FigureDownloadPanel.tsx';
 import { useFigureTask } from '../../download/ui/useFigureTask.ts';
 import { useChromeT } from '../../i18n/ui/useT.ts';
+import { OverlaySegmented } from '../../overlay/ui/OverlaySegmented.tsx';
 
 /** Props of {@link Molecule3DExport}. */
 export interface Molecule3DExportProps {
   /** Reads the size of the canvas on screen, when the popover opens. */
   getSize: () => FigurePixels | null;
-  /** Writes the file. */
-  onExport: (format: FigureFormat, scale: number) => Promise<void>;
+  /**
+   * Writes the file: every frame, as an animated PNG, when `animated` is set.
+   */
+  onExport: (
+    format: FigureFormat,
+    scale: number,
+    animated: boolean,
+  ) => Promise<void>;
   /** Puts a PNG at that scale on the clipboard, and says what came of it. */
   onCopy: (scale: number) => Promise<FigureNotice>;
+  /**
+   * How many frames the scene holds. Above one, a PNG may hold them all, as an
+   * animation.
+   * @default 1
+   */
+  frameCount?: number;
 }
 
 /**
@@ -33,11 +46,14 @@ export interface Molecule3DExportProps {
  * @returns The panel.
  */
 export function Molecule3DExport(props: Molecule3DExportProps): ReactElement {
-  const { getSize, onExport, onCopy } = props;
+  const { getSize, onExport, onCopy, frameCount = 1 } = props;
   const t = useChromeT();
   const [size] = useState(getSize);
   const [format, setFormat] = useState<FigureFormat>('png');
   const [scale, setScale] = useState(DEFAULT_FIGURE_SCALE);
+  const [frames, setFrames] = useState<FrameChoice>('all');
+  const offerFrames = frameCount > 1 && format === 'png';
+  const animated = offerFrames && frames === 'all';
   const { run, busy, failure, notice, clear } = useFigureTask();
 
   // What the last copy came to only describes the choices it was made with.
@@ -61,8 +77,30 @@ export function Molecule3DExport(props: Molecule3DExportProps): ReactElement {
       rasterSvg
       onFormatChange={changed(setFormat)}
       onScaleChange={changed(setScale)}
-      onSave={() => run(onExport(format, scale).then(() => null))}
+      onSave={() => run(onExport(format, scale, animated).then(() => null))}
       onCopy={() => run(onCopy(scale))}
-    />
+    >
+      {offerFrames && (
+        <OverlaySegmented<FrameChoice>
+          label={t('molecule3d.frames')}
+          help={{
+            title: t('molecule3d.frames'),
+            body: t('molecule3d.framesHelp'),
+          }}
+          value={frames}
+          options={[
+            { value: 'one', label: t('molecule3d.frames.one') },
+            {
+              value: 'all',
+              label: t('molecule3d.frames.all', { count: frameCount }),
+            },
+          ]}
+          onChange={changed(setFrames)}
+        />
+      )}
+    </FigureDownloadPanel>
   );
 }
+
+/** The frame on screen, or every frame as an animated PNG. */
+type FrameChoice = 'one' | 'all';

package/src/molecule3d/ui/Molecule3DToolbar.tsx

@@ -225,11 +225,18 @@ export function Molecule3DToolbar(props: Molecule3DToolbarProps): ReactElement {
 
 const TOOLTIP_PROPS = { placement: 'right' } as const;
 
+// A canvas too short for both cards puts the second one beside the first,
+// rather than cutting it off; the column itself lets clicks through to the
+// canvas between and below the cards.
 const COLUMN_STYLE: CSSProperties = {
   display: 'flex',
   flexDirection: 'column',
+  flexWrap: 'wrap',
+  alignContent: 'flex-start',
+  alignItems: 'flex-start',
   gap: 6,
-  pointerEvents: 'auto',
+  height: '100%',
+  pointerEvents: 'none',
 };
 
-const CARD_STYLE: CSSProperties = { padding: 0 };
+const CARD_STYLE: CSSProperties = { padding: 0, pointerEvents: 'auto' };

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 { DEFAULT_FRAMES_PER_SECOND } from '../core/animatedPng.ts';
 import type { Molecule3DHighlight } from '../core/highlight.ts';
 import type { Measurement, MeasurementKind } from '../core/measurement.ts';
 import {
@@ -21,14 +22,13 @@ import { Molecule3DExport } from './Molecule3DExport.tsx';
 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';
 import { useMoleculeScene } from './useMoleculeScene.ts';
+import { useMoleculeViewer } from './useMoleculeViewer.ts';
 import { usePolarSurfaceArea } from './usePolarSurfaceArea.ts';
-import type { Molecule3DViewer } from './viewer.ts';
 
 /** Props of {@link MoleculeCanvas3D}. */
 export interface MoleculeCanvas3DProps extends Omit<
@@ -56,6 +56,8 @@ export function MoleculeCanvas3D(props: MoleculeCanvas3DProps): ReactElement {
     defaultSpinning = false,
     onSpinningChange,
     spinSpeed = DEFAULT_SPIN_SPEED,
+    playing = false,
+    framesPerSecond = DEFAULT_FRAMES_PER_SECOND,
     measurements: measurementsProp,
     onMeasurementsChange,
     highlights = NO_HIGHLIGHTS,
@@ -82,6 +84,7 @@ export function MoleculeCanvas3D(props: MoleculeCanvas3DProps): ReactElement {
     readonly Measurement[]
   >(measurementsProp, NO_MEASUREMENTS, onMeasurementsChange);
   const [measureKind, setMeasureKind] = useState<MeasurementKind | null>(null);
+  const [frameCount, setFrameCount] = useState(0);
   const polarSurfaceArea = usePolarSurfaceArea(
     molfile,
     settings.surfaceColoring === 'polarity',
@@ -90,51 +93,31 @@ export function MoleculeCanvas3D(props: MoleculeCanvas3DProps): ReactElement {
   // A callback ref: the element arriving is what creates the viewer, and every
   // effect keyed on it runs again, in order, after the viewer exists.
   const [container, setContainer] = useState<HTMLDivElement | null>(null);
-  const viewerRef = useRef<Molecule3DViewer | null>(null);
   // The viewer is created once, so what its callbacks read is kept fresh here.
-  const latest = useRef({
-    measurements,
-    setMeasurements,
-    onFailureChange,
-    background,
-  });
+  const latest = useRef({ measurements, setMeasurements });
   useEffect(() => {
-    latest.current = {
-      measurements,
-      setMeasurements,
-      onFailureChange,
-      background,
-    };
+    latest.current = { measurements, setMeasurements };
+  });
+  const viewerRef = useMoleculeViewer(container, {
+    background,
+    onMeasure: (measurement) => {
+      const current = latest.current;
+      current.setMeasurements([...current.measurements, measurement]);
+    },
+    onFrameCountChange: setFrameCount,
   });
 
   useEffect(() => {
-    if (container === null) return;
-    const viewer = createMolecule3DViewer(container, {
-      background: latest.current.background,
-      onMeasure: (measurement) => {
-        const current = latest.current;
-        current.setMeasurements([...current.measurements, measurement]);
-      },
-    });
-    viewerRef.current = viewer;
-    const observer = new ResizeObserver(() => {
-      viewer.handleResize();
-    });
-    observer.observe(container);
-    return () => {
-      observer.disconnect();
-      viewerRef.current = null;
-      viewer.dispose();
-    };
-  }, [container]);
+    void viewerRef.current?.setSpin(spinning, spinSpeed);
+  }, [container, viewerRef, spinning, spinSpeed]);
 
   useEffect(() => {
-    void viewerRef.current?.setSpin(spinning, spinSpeed);
-  }, [container, spinning, spinSpeed]);
+    void viewerRef.current?.frames.play(playing, framesPerSecond);
+  }, [container, viewerRef, playing, framesPerSecond]);
 
   useEffect(() => {
     void viewerRef.current?.setMeasureKind(measureKind);
-  }, [container, measureKind]);
+  }, [container, viewerRef, measureKind]);
 
   // Kept out of the scene: a new highlight repaints the model, never redraws it.
   useEffect(() => {
@@ -142,7 +125,7 @@ export function MoleculeCanvas3D(props: MoleculeCanvas3DProps): ReactElement {
       highlights,
       highlightColorOf(container),
     );
-  }, [container, highlights]);
+  }, [container, viewerRef, highlights]);
 
   const { resetView } = useMoleculeScene({
     container,
@@ -160,6 +143,7 @@ export function MoleculeCanvas3D(props: MoleculeCanvas3DProps): ReactElement {
     container,
     viewerRef,
     fileName,
+    framesPerSecond,
   );
 
   return (
@@ -202,6 +186,7 @@ export function MoleculeCanvas3D(props: MoleculeCanvas3DProps): ReactElement {
                     getSize={canvasSize}
                     onExport={exportImage}
                     onCopy={copyImage}
+                    frameCount={frameCount}
                   />
                 }
               />
@@ -231,6 +216,7 @@ const CANVAS_STYLE: CSSProperties = { position: 'absolute', inset: 0 };
 const OVERLAY_STYLE: CSSProperties = {
   position: 'absolute',
   top: 8,
+  bottom: 8,
   left: 8,
   zIndex: 2,
   display: 'flex',

package/src/molecule3d/ui/drawScene.ts

@@ -1,5 +1,6 @@
+import type { Molecule3DFile } from '../core/file.ts';
 import type { Measurement } from '../core/measurement.ts';
-import type { Molecule3DFile, Molecule3DSettings } from '../core/settings.ts';
+import type { Molecule3DSettings } from '../core/settings.ts';
 import { normalizeMolecule3DSettings } from '../core/settings.ts';
 
 import type { Molecule3DViewer } from './viewer.ts';

package/src/molecule3d/ui/exportMoleculeImage.ts

@@ -4,13 +4,22 @@ import { FIGURE_PNG_TYPE } from '../../download/core/figurePng.ts';
 import { figurePixels } from '../../download/core/figureScale.ts';
 import { FIGURE_SVG_TYPE } from '../../download/core/figureSvg.ts';
 import { sanitizeFileName } from '../../download/core/sanitizeFileName.ts';
+import { encodeAnimatedPng } from '../core/animatedPng.ts';
 import type { ImageSize } from '../core/exportImage.ts';
 import { dataUriBytes, rasterSvgMarkup } from '../core/exportImage.ts';
 
-/** The one thing an export asks of a viewer: a picture of its scene. */
+/** What an export asks of a viewer: a picture of its scene. */
 export interface SceneCapture {
   /** Render the scene at that pixel size, as a `data:` URI. */
   captureImage: (size: ImageSize) => Promise<string | undefined>;
+  /**
+   * The frames of the scene, each rendered at that pixel size, for an animated
+   * PNG.
+   * @default undefined — the viewer has a single frame to give
+   */
+  frames?: {
+    capture: (size: ImageSize) => Promise<ImageData[] | undefined>;
+  };
 }
 
 /** What {@link exportMoleculeImage} writes. */
@@ -22,6 +31,12 @@ export interface MoleculeImageRequest {
   size: ImageSize;
   /** File name without its extension. */
   fileName: string;
+  /**
+   * Every frame of the scene as one animated PNG, played at this many frames a
+   * second, rather than the frame on screen. Ignored for an SVG.
+   * @default undefined — the frame on screen
+   */
+  framesPerSecond?: number;
 }
 
 /**
@@ -54,11 +69,21 @@ export async function exportMoleculeImage(
   viewer: SceneCapture,
   request: MoleculeImageRequest,
 ): Promise<void> {
-  const { format, scale, size, fileName } = request;
+  const { format, scale, size, fileName, framesPerSecond } = request;
   const pixels = figurePixels(size, scale);
+  const base = sanitizeFileName(fileName, 'molecule');
+  if (format === 'png' && framesPerSecond !== undefined) {
+    if (viewer.frames === undefined) {
+      throw new Error('This viewer has no frames to animate.');
+    }
+    const frames = await viewer.frames.capture(pixels);
+    if (frames === undefined) return;
+    const bytes = await encodeAnimatedPng(frames, framesPerSecond);
+    downloadBlob(new Blob([bytes], { type: FIGURE_PNG_TYPE }), `${base}.png`);
+    return;
+  }
   const dataUri = await viewer.captureImage(pixels);
   if (dataUri === undefined) return;
-  const base = sanitizeFileName(fileName, 'molecule');
   if (format === 'png') {
     downloadBlob(
       new Blob([dataUriBytes(dataUri)], { type: FIGURE_PNG_TYPE }),